feat: enhance plugin scaffolding

Author: vobu

EXAMPLES.md

@@ -908,6 +908,8 @@ c8 upgrade plugin my-custom-plugin 1.2.3
 
 Plugins must be regular Node.js modules with a `c8ctl-plugin.js` or `c8ctl-plugin.ts` file in the root directory. The plugin file must export a `commands` object. The `c8ctl` runtime object provides environment information:
 
+When bootstrapping with `c8 init plugin <name>`, the generated project also includes an `AGENTS.md` file with an implementation workflow and runtime API reference for coding agents.
+
 ```typescript
 // c8ctl-plugin.ts
 import { c8ctl } from 'c8ctl/runtime';

PLUGIN-HELP.md

@@ -273,6 +273,19 @@ See [tests/unit/plugin-loader.test.ts](tests/unit/plugin-loader.test.ts) for uni
 - Help text includes plugin commands
 - Metadata is properly parsed
 
+## AGENTS.md in Scaffolded Plugins
+
+When you bootstrap a plugin with `c8ctl init plugin <name>`, the generated project includes an `AGENTS.md` file.
+
+Treat this file as the default implementation contract for coding agents and contributors. It captures:
+
+- plugin contract expectations (`commands`, optional `metadata`, keywords)
+- available runtime APIs on global `c8ctl`
+- a fast local development loop (`install` → `build` → `load` → `help` → `run`)
+- minimal quality checks before considering work complete
+
+Keeping `AGENTS.md` aligned with your plugin design helps autonomous contributors make correct, minimal, and testable changes.
+
 ## Example Plugin Development Flow
 
 1. Create plugin with commands:

README.md

@@ -394,7 +394,7 @@ c8ctl help
 
 **Plugin Development:**
 - Use `c8ctl init plugin <name>` to scaffold a new plugin with TypeScript template
-- Generated scaffold includes all necessary files and build configuration
+- Generated scaffold includes all necessary files, build configuration, and an `AGENTS.md` guide for autonomous plugin implementation
 - Plugins have access to the c8ctl runtime via `globalThis.c8ctl`
 - Plugins can create SDK clients via `globalThis.c8ctl.createClient(profile?, sdkConfig?)`
 - Plugins can resolve tenant IDs via `globalThis.c8ctl.resolveTenantId(profile?)`

package.json

@@ -19,9 +19,10 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "npm run clean && tsc && npm run copy-plugins",
+    "build": "npm run clean && tsc && npm run copy-plugins && npm run copy-templates",
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "copy-plugins": "node -e \"const fs=require('fs');const path=require('path');const src='default-plugins';const dest='dist/default-plugins';if(fs.existsSync(src)){fs.cpSync(src,dest,{recursive:true})}\"",
+    "copy-templates": "node -e \"const fs=require('fs');const src='src/templates';const dest='dist/templates';if(fs.existsSync(src)){fs.cpSync(src,dest,{recursive:true})}\"",
     "prepublishOnly": "npm run build",
     "test": "node --test tests/unit/setup.test.ts tests/unit/*.test.ts tests/integration/*.test.ts",
     "test:unit": "node --test tests/unit/setup.test.ts tests/unit/*.test.ts",

src/commands/plugins.ts

@@ -5,18 +5,34 @@
 import { getLogger } from '../logger.ts';
 import { execSync } from 'node:child_process';
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { clearLoadedPlugins } from '../plugin-loader.ts';
 import { ensurePluginsDir } from '../config.ts';
 import {
   addPluginToRegistry,
   removePluginFromRegistry,
   getRegisteredPlugins,
   isPluginRegistered,
-  getPluginEntry,
-  type PluginEntry,
+  getPluginEntry
 } from '../plugin-registry.ts';
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function getTemplate(templateFileName: string): string {
+  const templatePath = join(__dirname, '..', 'templates', templateFileName);
+  return readFileSync(templatePath, 'utf-8');
+}
+
+function renderTemplate(templateFileName: string, replacements: Record<string, string> = {}): string {
+  let content = getTemplate(templateFileName);
+  for (const [key, value] of Object.entries(replacements)) {
+    content = content.replaceAll(`{{${key}}}`, value);
+  }
+  return content;
+}
+
 /**
  * Load a plugin (npm install wrapper)
  * Supports either package name or --from flag with URL
@@ -625,191 +641,51 @@ export async function initPlugin(pluginName?: string): Promise<void> {
 
   try {
     logger.info(`Creating plugin: ${dirName}...`);
+
+    const templateVars = { PLUGIN_NAME: dirName };
 
     // Create plugin directory
     mkdirSync(pluginDir, { recursive: true });
 
     // Create package.json
-    const packageJson = {
-      name: dirName,
-      version: '1.0.0',
-      type: 'module',
-      description: `A c8ctl plugin`,
-      keywords: ['c8ctl', 'c8ctl-plugin'],
-      main: 'c8ctl-plugin.js',
-      scripts: {
-        build: 'tsc',
-        watch: 'tsc --watch',
-      },
-      devDependencies: {
-        typescript: '^5.0.0',
-        '@types/node': '^22.0.0',
-      },
-    };
-    
-    writeFileSync(
-      join(pluginDir, 'package.json'),
-      JSON.stringify(packageJson, null, 2)
-    );
-    
+    writeFileSync(join(pluginDir, 'package.json'), renderTemplate('package.json', templateVars));
+
     // Create tsconfig.json
-    const tsConfig = {
-      compilerOptions: {
-        target: 'ES2022',
-        module: 'ES2022',
-        moduleResolution: 'node',
-        outDir: '.',
-        rootDir: './src',
-        strict: true,
-        esModuleInterop: true,
-        skipLibCheck: true,
-        forceConsistentCasingInFileNames: true,
-      },
-      include: ['src/**/*'],
-      exclude: ['node_modules'],
-    };
-    
-    writeFileSync(
-      join(pluginDir, 'tsconfig.json'),
-      JSON.stringify(tsConfig, null, 2)
-    );
+    writeFileSync(join(pluginDir, 'tsconfig.json'), getTemplate('tsconfig.json'));
 
     // Create src directory
     mkdirSync(join(pluginDir, 'src'), { recursive: true });
-    
-    // Create c8ctl-plugin.ts
-    const pluginTemplate = `/**
- * ${dirName} - A c8ctl plugin
- */
 
-// The c8ctl runtime is available globally
-declare const c8ctl: {
-  version: string;
-  nodeVersion: string;
-  platform: string;
-  arch: string;
-  cwd: string;
-  outputMode: 'text' | 'json';
-  activeProfile?: string;
-  activeTenant?: string;
-};
-
-// Optional metadata for help text
-export const metadata = {
-  name: '${dirName}',
-  description: 'A c8ctl plugin',
-  commands: {
-    hello: {
-      description: 'Say hello from the plugin',
-    },
-  },
-};
-
-// Required commands export
-export const commands = {
-  hello: async (args: string[]) => {
-    console.log('Hello from ${dirName}!');
-    console.log('c8ctl version:', c8ctl.version);
-    console.log('Node version:', c8ctl.nodeVersion);
-    
-    if (args.length > 0) {
-      console.log('Arguments:', args.join(', '));
-    }
+    // Create root c8ctl-plugin.js entry point
+    writeFileSync(join(pluginDir, 'c8ctl-plugin.js'), getTemplate('c8ctl-plugin.js'));
 
-    // Example: Access c8ctl runtime
-    console.log('Current directory:', c8ctl.cwd);
-    console.log('Output mode:', c8ctl.outputMode);
+    // Create c8ctl-plugin.ts
+    writeFileSync(join(pluginDir, 'src', 'c8ctl-plugin.ts'), renderTemplate('c8ctl-plugin.ts', templateVars));
 
-    if (c8ctl.activeProfile) {
-      console.log('Active profile:', c8ctl.activeProfile);
-    }
-  },
-};
-`;
+    // Create README.md
+    const readme = renderTemplate('README.md', templateVars);
 
     writeFileSync(
-      join(pluginDir, 'src', 'c8ctl-plugin.ts'),
-      pluginTemplate
+      join(pluginDir, 'README.md'),
+      readme
     );
-    
-    // Create README.md
-    const readme = `# ${dirName}
-
-A c8ctl plugin.
-
-## Development
-
-1. Install dependencies:
-\`\`\`bash
-npm install
-\`\`\`
-
-2. Build the plugin:
-\`\`\`bash
-npm run build
-\`\`\`
-
-3. Load the plugin for testing:
-\`\`\`bash
-c8ctl load plugin --from file://\${PWD}
-\`\`\`
-
-4. Test the plugin command:
-\`\`\`bash
-c8ctl hello
-\`\`\`
-
-## Plugin Structure
-
-- \`src/c8ctl-plugin.ts\` - Plugin source code (TypeScript)
-- \`c8ctl-plugin.js\` - Compiled plugin file (JavaScript)
-- \`package.json\` - Package metadata with c8ctl keywords
 
-## Publishing
+    // Create AGENTS.md
+    const agents = getTemplate('AGENTS.md');
 
-Before publishing, ensure:
-- The plugin is built (\`npm run build\`)
-- The package.json has correct metadata
-- Keywords include 'c8ctl' or 'c8ctl-plugin'
-
-Then publish to npm:
-\`\`\`bash
-npm publish
-\`\`\`
-
-Users can install your plugin with:
-\`\`\`bash
-c8ctl load plugin ${dirName}
-\`\`\`
-`;
-    
     writeFileSync(
-      join(pluginDir, 'README.md'),
-      readme
+      join(pluginDir, 'AGENTS.md'),
+      agents
     );
 
     // Create .gitignore
-    const gitignore = `node_modules/
-*.js
-*.js.map
-!c8ctl-plugin.js
-`;
-    
-    writeFileSync(
-      join(pluginDir, '.gitignore'),
-      gitignore
-    );
+    writeFileSync(join(pluginDir, '.gitignore'), getTemplate('.gitignore'));
 
     logger.success('Plugin scaffolding created successfully!');
-    logger.info('');
-    logger.info(`Next steps:`);
-    logger.info(`  1. cd ${dirName}`);
-    logger.info(`  2. npm install`);
-    logger.info(`  3. npm run build`);
-    logger.info(`  4. c8ctl load plugin --from file://\${PWD}`);
-    logger.info(`  5. c8ctl hello`);
-    logger.info('');
-    logger.info(`Edit src/c8ctl-plugin.ts to add your plugin logic.`);
+    const nextSteps = renderTemplate('init-plugin-next-steps.txt', templateVars);
+    for (const line of nextSteps.split('\n')) {
+      logger.info(line);
+    }
   } catch (error) {
     logger.error('Failed to create plugin', error as Error);
     process.exit(1);

src/templates/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+*.js
+*.js.map
+!c8ctl-plugin.js

src/templates/AGENTS.md

@@ -0,0 +1,77 @@
+# AGENTS.md
+
+This file describes how to efficiently implement and iterate on this c8ctl plugin as an autonomous coding agent.
+
+## Goal
+
+Build and maintain a plugin that exposes useful commands through `export const commands` in `src/c8ctl-plugin.ts`.
+
+## Plugin Contract
+
+- Plugin entry point: `c8ctl-plugin.js` (root re-export to `dist/c8ctl-plugin.js`)
+- Source file: `src/c8ctl-plugin.ts`
+- Build output: `dist/c8ctl-plugin.js`
+- Required export: `commands` object mapping command name -> async handler
+- Optional export: `metadata` object for help descriptions
+- Package keywords must include `c8ctl` or `c8ctl-plugin`
+
+## Runtime API (available as global `c8ctl`)
+
+Runtime environment object:
+
+- `c8ctl.env.version`
+- `c8ctl.env.nodeVersion`
+- `c8ctl.env.platform`
+- `c8ctl.env.arch`
+- `c8ctl.env.cwd`
+- `c8ctl.env.rootDir`
+
+Direct compatibility fields:
+
+- `c8ctl.version`
+- `c8ctl.nodeVersion`
+- `c8ctl.platform`
+- `c8ctl.arch`
+- `c8ctl.cwd`
+- `c8ctl.outputMode`
+- `c8ctl.activeProfile`
+- `c8ctl.activeTenant`
+
+Methods:
+
+- `c8ctl.createClient(profileFlag?, sdkConfig?)`
+- `c8ctl.resolveTenantId(profileFlag?)`
+- `c8ctl.getLogger(mode?)`
+
+## Development Loop
+
+1. Install dependencies: `npm install`
+2. Build plugin: `npm run build`
+3. Load from local folder: `c8ctl load plugin --from file://${PWD}`
+4. Verify command is available: `c8ctl <plugin>`
+5. Execute plugin command: `c8ctl <plugin> <commands>`
+
+## Implementation Guidance
+
+- Keep command handlers focused and composable.
+- Use `c8ctl.getLogger()` for output-mode-aware logs.
+- Use `c8ctl.createClient()` for Camunda API interactions.
+- Use `c8ctl.resolveTenantId()` instead of duplicating tenant fallback logic.
+- Prefer clear, actionable error messages.
+- Avoid command names that conflict with built-in c8ctl commands.
+- For any non-trivial implementation or behavior change, always cross-check against upstream `c8ctl` repository: <https://github.com/camunda/c8ctl> before finalizing
+
+## Quality Checks
+
+Before considering a change complete:
+
+1. Build succeeds: `npm run build`
+2. Plugin loads: `c8ctl load plugin --from file://${PWD}`
+3. Command appears in help: `c8ctl help`
+4. Command executes with expected output
+
+## Minimal Change Policy
+
+- Make the smallest change required for each task.
+- Do not add unrelated commands or refactors.
+- Keep `metadata.commands` descriptions concise and user-facing.