Merge pull request kubernetes-sigs#4368 from illume/agentplug

headlamp-plugin: Add AGENTS.md to created plugins and bundle examples

Author: illume

plugins/headlamp-plugin/.gitignore

@@ -2,3 +2,6 @@ node_modules
 kinvolk-headlamp-plugin-*.tgz
 kinvolk-headlamp-plugin-*.tar.gz
 lib
+examples
+official-plugins
+.temp-official-plugins

plugins/headlamp-plugin/bin/headlamp-plugin.js

@@ -952,6 +952,7 @@ function upgrade(packageFolder, skipPackageUpdates, headlampPluginVersion) {
       path.join('.vscode', 'settings.json'),
       path.join('.vscode', 'tasks.json'),
       'tsconfig.json',
+      'AGENTS.md',
     ];
     const templateFolder = path.resolve(__dirname, '..', 'template');
 
@@ -967,9 +968,14 @@ function upgrade(packageFolder, skipPackageUpdates, headlampPluginVersion) {
         fs.copyFileSync(from, to);
       }
       // Add file if it is different
-      if (fs.readFileSync(from, 'utf8') !== fs.readFileSync(to, 'utf8')) {
-        console.log(`Updating file: "${to}"`);
-        fs.copyFileSync(from, to);
+      if (fs.existsSync(to)) {
+        const fromContent = fs.readFileSync(from, 'utf8');
+        const toContent = fs.readFileSync(to, 'utf8');
+
+        if (fromContent !== toContent) {
+          console.log(`Updating file: "${to}"`);
+          fs.writeFileSync(to, fromContent);
+        }
       }
     });
   }

plugins/headlamp-plugin/package.json

@@ -7,7 +7,10 @@
   "bin": "bin/headlamp-plugin.js",
   "scripts": {
     "prepack": "(node -e \"if (! require('fs').existsSync('./lib/components')) {process.exit(1)} \" || (echo 'lib dir is empty. Remember to run `npm run build` before packing' && exit 1))",
-    "build": "npx shx rm -rf lib types lib/assets lib/components lib/helpers lib/i18n lib/lib lib/plugin lib/redux lib/resources && npx shx cp -r ../../frontend/src/assets ../../frontend/src/components ../../frontend/src/helpers ../../frontend/src/stateless ../../frontend/src/i18n ../../frontend/src/lib ../../frontend/src/plugin ../../frontend/src/redux ../../frontend/src/resources src/ && tsc --build ./tsconfig.json && npx shx cp -r src/additional.d.ts lib/ && npx shx cp -r ../../frontend/src/assets lib/ && npx shx cp -r ../../frontend/src/resources lib/ && npx shx cp -r ../../frontend/src/i18n/locales lib/i18n && node scripts/copy-static-assets.js",
+    "build": "npm run prepare-bundle && npx shx rm -rf lib types lib/assets lib/components lib/helpers lib/i18n lib/lib lib/plugin lib/redux lib/resources && npx shx cp -r ../../frontend/src/assets ../../frontend/src/components ../../frontend/src/helpers ../../frontend/src/stateless ../../frontend/src/i18n ../../frontend/src/lib ../../frontend/src/plugin ../../frontend/src/redux ../../frontend/src/resources src/ && tsc --build ./tsconfig.json && npx shx cp -r src/additional.d.ts lib/ && npx shx cp -r ../../frontend/src/assets lib/ && npx shx cp -r ../../frontend/src/resources lib/ && npx shx cp -r ../../frontend/src/i18n/locales lib/i18n && node scripts/copy-static-assets.js",
+    "bundle-examples": "node scripts/bundle-examples.js",
+    "fetch-official-plugins": "node scripts/fetch-official-plugins.js",
+    "prepare-bundle": "npm run bundle-examples && npm run fetch-official-plugins",
     "update-dependencies": "node dependencies-sync.js update && npm install && node scripts/copy-package-lock.js",
     "check-dependencies": "node dependencies-sync.js check",
     "copy-package-lock": "node scripts/copy-package-lock.js"
@@ -132,6 +135,8 @@
     "lib",
     "types",
     ".storybook",
+    "examples",
+    "official-plugins",
     "plugin-management/plugin-management.js",
     "plugin-management/multi-plugin-management.js"
   ],

plugins/headlamp-plugin/scripts/bundle-examples.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+/*
+ * Copyright 2025 The Kubernetes Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * This script copies example plugins from plugins/examples into
+ * examples/ directory for bundling with headlamp-plugin package.
+ * These plugins are referenced in AGENTS.md and help agents write good plugins.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const { getLocalGitHash, storeHash, shouldSkipBasedOnHash } = require('./git-hash-utils');
+
+const scriptDir = __dirname;
+const pluginDir = path.resolve(scriptDir, '..');
+const examplesSourceDir = path.resolve(pluginDir, '..', 'examples');
+const examplesDestDir = path.resolve(pluginDir, 'examples');
+const hashFile = path.resolve(examplesDestDir, '.git-hash');
+
+console.log('Bundling example plugins...');
+console.log(`Source: ${examplesSourceDir}`);
+console.log(`Destination: ${examplesDestDir}`);
+
+// Get the current git hash
+const currentHash = getLocalGitHash('plugins/examples', path.resolve(pluginDir, '..', '..'));
+
+// Check if we can skip bundling
+if (shouldSkipBasedOnHash(examplesDestDir, hashFile, currentHash)) {
+  console.log('Example plugins are already up to date (git hash matches)');
+  console.log('Skipping bundle...');
+  process.exit(0);
+}
+
+// Remove existing examples directory if it exists
+if (fs.existsSync(examplesDestDir)) {
+  console.log('Removing existing examples directory...');
+  fs.rmSync(examplesDestDir, { recursive: true });
+}
+
+// Create examples directory
+fs.mkdirSync(examplesDestDir, { recursive: true });
+
+// Get list of example plugins
+const examplePlugins = fs
+  .readdirSync(examplesSourceDir, { withFileTypes: true })
+  .filter(dirent => dirent.isDirectory())
+  .map(dirent => dirent.name);
+
+console.log(`Found ${examplePlugins.length} example plugins to bundle`);
+
+// Copy each example plugin
+examplePlugins.forEach(pluginName => {
+  const sourcePath = path.join(examplesSourceDir, pluginName);
+  const destPath = path.join(examplesDestDir, pluginName);
+
+  console.log(`Copying ${pluginName}...`);
+
+  // Copy the plugin directory
+  fs.copySync(sourcePath, destPath, {
+    filter: src => {
+      // Skip node_modules, dist, and other build artifacts
+      const relativePath = path.relative(sourcePath, src);
+      if (relativePath.includes('node_modules')) return false;
+      if (relativePath.includes('dist')) return false;
+      if (relativePath.includes('.eslintcache')) return false;
+      if (relativePath.includes('storybook-static')) return false;
+      if (relativePath.includes('package-lock.json')) return false;
+      return true;
+    },
+  });
+});
+
+// Store the git hash if available
+if (currentHash) {
+  storeHash(hashFile, currentHash);
+  console.log(`Successfully bundled ${examplePlugins.length} example plugins to examples/`);
+  console.log(`Git hash: ${currentHash}`);
+} else {
+  console.log(`Successfully bundled ${examplePlugins.length} example plugins to examples/`);
+}

plugins/headlamp-plugin/scripts/fetch-official-plugins.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+/*
+ * Copyright 2025 The Kubernetes Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * This script fetches official plugins from https://github.com/headlamp-k8s/plugins/
+ * and bundles them into official-plugins/ directory for inclusion with headlamp-plugin package.
+ * These plugins are referenced in AGENTS.md and help agents write good plugins.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const { execSync } = require('child_process');
+const { getRemoteGitHash, storeHash, shouldSkipBasedOnHash } = require('./git-hash-utils');
+
+const scriptDir = __dirname;
+const pluginDir = path.resolve(scriptDir, '..');
+const officialPluginsDir = path.resolve(pluginDir, 'official-plugins');
+const hashFile = path.resolve(officialPluginsDir, '.git-hash');
+const officialPluginsRepo = 'https://github.com/headlamp-k8s/plugins.git';
+
+console.log('Fetching official plugins...');
+
+// Get the current remote hash
+const remoteHash = getRemoteGitHash(officialPluginsRepo);
+
+// Check if we can skip fetching
+if (shouldSkipBasedOnHash(officialPluginsDir, hashFile, remoteHash)) {
+  console.log('Official plugins are already up to date (git hash matches)');
+  console.log('Skipping fetch...');
+  process.exit(0);
+}
+
+console.log('Fetching latest official plugins from GitHub...');
+
+// Remove existing directory if it exists
+if (fs.existsSync(officialPluginsDir)) {
+  console.log('Removing existing official-plugins directory...');
+  fs.rmSync(officialPluginsDir, { recursive: true });
+}
+
+// Create official-plugins directory
+fs.mkdirSync(officialPluginsDir, { recursive: true });
+
+// Clone the repository into a temporary directory
+const tempDir = path.resolve(pluginDir, '.temp-official-plugins');
+if (fs.existsSync(tempDir)) {
+  fs.rmSync(tempDir, { recursive: true });
+}
+
+try {
+  console.log('Cloning official plugins repository...');
+  execSync(`git clone --depth 1 ${officialPluginsRepo} ${tempDir}`, {
+    stdio: 'inherit',
+  });
+
+  // Get the current commit hash
+  const currentHash = execSync('git rev-parse HEAD', {
+    cwd: tempDir,
+    encoding: 'utf8',
+  }).trim();
+
+  // Get list of plugin directories (skip .git and README.md)
+  const pluginDirs = fs
+    .readdirSync(tempDir, { withFileTypes: true })
+    .filter(
+      dirent =>
+        dirent.isDirectory() && dirent.name !== '.git' && !dirent.name.startsWith('.')
+    )
+    .map(dirent => dirent.name);
+
+  console.log(`Found ${pluginDirs.length} official plugins`);
+
+  // Copy each plugin directory
+  pluginDirs.forEach(pluginName => {
+    const sourcePath = path.join(tempDir, pluginName);
+    const destPath = path.join(officialPluginsDir, pluginName);
+
+    console.log(`Copying ${pluginName}...`);
+
+    // Copy the plugin directory
+    fs.copySync(sourcePath, destPath, {
+      filter: src => {
+        // Skip node_modules, dist, and other build artifacts
+        const relativePath = path.relative(sourcePath, src);
+        if (relativePath.includes('node_modules')) return false;
+        if (relativePath.includes('dist')) return false;
+        if (relativePath.includes('.git')) return false;
+        if (relativePath.includes('.eslintcache')) return false;
+        if (relativePath.includes('storybook-static')) return false;
+        if (relativePath.includes('package-lock.json')) return false;
+        return true;
+      },
+    });
+  });
+
+  // Store the git hash
+  storeHash(hashFile, currentHash);
+
+  console.log(
+    `Successfully fetched ${pluginDirs.length} official plugins to official-plugins/`
+  );
+  console.log(`Git hash: ${currentHash}`);
+} catch (error) {
+  console.error('Failed to fetch official plugins:', error.message);
+  process.exit(1);
+} finally {
+  // Clean up temporary directory
+  if (fs.existsSync(tempDir)) {
+    console.log('Cleaning up temporary directory...');
+    fs.rmSync(tempDir, { recursive: true });
+  }
+}

plugins/headlamp-plugin/scripts/git-hash-utils.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+/*
+ * Copyright 2025 The Kubernetes Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Shared utilities for git hash tracking used by bundling scripts.
+ * These hashing functions make development faster by meaning the plugins
+ * are not copied again and again if they don't change.
+ */
+
+const fs = require('fs-extra');
+const { execSync } = require('child_process');
+
+/**
+ * Get the stored hash from a hash file
+ * @param {string} hashFile - Path to the hash file
+ * @returns {string|null} - The stored hash or null if file doesn't exist
+ */
+function getStoredHash(hashFile) {
+  if (fs.existsSync(hashFile)) {
+    return fs.readFileSync(hashFile, 'utf8').trim();
+  }
+  return null;
+}
+
+/**
+ * Store a hash to a hash file
+ * @param {string} hashFile - Path to the hash file
+ * @param {string} hash - The hash to store
+ */
+function storeHash(hashFile, hash) {
+  fs.writeFileSync(hashFile, hash);
+}
+
+/**
+ * Get the git hash of a local directory path
+ * @param {string} dirPath - The directory path relative to git root (e.g., 'plugins/examples')
+ * @param {string} cwd - The working directory to run git command from
+ * @returns {string|null} - The git hash or null if git is not available
+ */
+function getLocalGitHash(dirPath, cwd) {
+  try {
+    const output = execSync(`git log -1 --format=%H -- ${dirPath}`, {
+      cwd: cwd,
+      encoding: 'utf8',
+    });
+    return output.trim();
+  } catch (error) {
+    console.log('Git not available or not in a git repository');
+    return null;
+  }
+}
+
+/**
+ * Get the remote git hash from a repository
+ * @param {string} repoUrl - The repository URL
+ * @returns {string|null} - The remote hash or null if failed
+ */
+function getRemoteGitHash(repoUrl) {
+  try {
+    const output = execSync(`git ls-remote ${repoUrl} HEAD`, {
+      encoding: 'utf8',
+    });
+    return output.split('\t')[0].trim();
+  } catch (error) {
+    console.error('Failed to get remote hash:', error.message);
+    return null;
+  }
+}
+
+/**
+ * Check if a directory should be skipped based on hash comparison
+ * @param {string} targetDir - The target directory to check
+ * @param {string} hashFile - Path to the hash file
+ * @param {string} currentHash - The current hash to compare against
+ * @returns {boolean} - True if should skip, false otherwise
+ */
+function shouldSkipBasedOnHash(targetDir, hashFile, currentHash) {
+  // Check if directory exists and has content
+  if (!fs.existsSync(targetDir)) {
+    return false;
+  }
+
+  const entries = fs.readdirSync(targetDir).filter(e => e !== '.git-hash');
+  if (entries.length === 0) {
+    return false;
+  }
+
+  // Check if hashes match
+  const storedHash = getStoredHash(hashFile);
+
+  if (!currentHash || !storedHash) {
+    return false;
+  }
+
+  return currentHash === storedHash;
+}
+
+module.exports = {
+  getStoredHash,
+  storeHash,
+  getLocalGitHash,
+  getRemoteGitHash,
+  shouldSkipBasedOnHash,
+};