feat: add CLI command extension support for plugins

Plugins can now extend the ObjectStack CLI with custom commands by declaring
`contributes.commands` in their manifest. The CLI dynamically discovers and
loads plugin-contributed Commander.js commands at startup.

Changes:
- spec: Add `commands` contribution point to ManifestSchema.contributes
- spec: Add CLICommandContributionSchema and CLIExtensionExportSchema
- cli: Add plugin command discovery and loading (plugin-commands.ts)
- cli: Update bin.ts to load plugin commands before parsing
- tests: Add tests for new schemas and plugin command loading

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/cli/src/bin.ts

@@ -17,6 +17,7 @@ import { initCommand } from './commands/init.js';
 import { infoCommand } from './commands/info.js';
 import { generateCommand } from './commands/generate.js';
 import { pluginCommand } from './commands/plugin.js';
+import { loadPluginCommands } from './utils/plugin-commands.js';
 
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
@@ -79,4 +80,15 @@ program.addCommand(pluginCommand);
 program.addCommand(testCommand);
 program.addCommand(doctorCommand);
 
-program.parse(process.argv);
+// ── Plugin-Contributed Commands ──
+// Load commands from installed plugins that declare `contributes.commands` in their manifest.
+// This must complete before `program.parse()` so that plugin commands are available.
+loadPluginCommands(program).then(() => {
+  program.parse(process.argv);
+}).catch((err) => {
+  // If plugin command loading fails, still parse with built-in commands
+  if (process.env.DEBUG) {
+    console.error(chalk.yellow(`\n  ⚠ Plugin command loading failed: ${err?.message || err}`));
+  }
+  program.parse(process.argv);
+});

packages/cli/src/index.ts

@@ -11,3 +11,4 @@ export * from './commands/dev.js';
 export * from './commands/serve.js';
 export * from './commands/test.js';
 export * from './commands/doctor.js';
+export * from './utils/plugin-commands.js';

packages/cli/src/utils/plugin-commands.ts

@@ -0,0 +1,162 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { loadConfig } from './config.js';
+
+/**
+ * CLI Command Contribution resolved from a plugin manifest.
+ */
+interface ResolvedCommandContribution {
+  /** CLI command name */
+  name: string;
+  /** Brief description */
+  description?: string;
+  /** Module path to import */
+  module?: string;
+  /** Source plugin package name */
+  pluginName: string;
+}
+
+/**
+ * Discover CLI command contributions from installed plugins.
+ * 
+ * Scans the project's `objectstack.config.ts` for plugins that declare
+ * `contributes.commands` in their manifest, then dynamically imports
+ * those plugin modules to register Commander.js commands.
+ * 
+ * @param program - The root Commander.js program to register commands on
+ */
+export async function loadPluginCommands(program: Command): Promise<void> {
+  let config: any;
+
+  try {
+    const loaded = await loadConfig();
+    config = loaded.config;
+  } catch {
+    // No config file found — nothing to load
+    return;
+  }
+
+  const plugins: unknown[] = [
+    ...(config.plugins || []),
+    ...(config.devPlugins || []),
+  ];
+
+  // Collect command contributions from plugin manifests
+  const contributions: ResolvedCommandContribution[] = [];
+
+  for (const plugin of plugins) {
+    if (!plugin || typeof plugin !== 'object') continue;
+    const p = plugin as Record<string, unknown>;
+
+    const manifest = p.manifest as Record<string, unknown> | undefined;
+    const contributes = (manifest?.contributes ?? p.contributes) as Record<string, unknown> | undefined;
+    if (!contributes) continue;
+
+    const commands = contributes.commands as Array<Record<string, unknown>> | undefined;
+    if (!Array.isArray(commands)) continue;
+
+    const pluginName = resolvePluginName(p);
+
+    for (const cmd of commands) {
+      if (!cmd || typeof cmd.name !== 'string') continue;
+      contributions.push({
+        name: cmd.name,
+        description: typeof cmd.description === 'string' ? cmd.description : undefined,
+        module: typeof cmd.module === 'string' ? cmd.module : undefined,
+        pluginName,
+      });
+    }
+  }
+
+  if (contributions.length === 0) return;
+
+  // Load and register each contributed command
+  for (const contribution of contributions) {
+    try {
+      const commands = await importPluginCommands(contribution);
+      for (const cmd of commands) {
+        program.addCommand(cmd);
+      }
+    } catch (error: any) {
+      // Log warning but don't crash — plugin commands are optional
+      if (process.env.DEBUG) {
+        console.error(
+          chalk.yellow(`  ⚠ Failed to load CLI command '${contribution.name}' from plugin '${contribution.pluginName}': ${error.message}`)
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Import Commander.js commands from a plugin module.
+ * 
+ * The module must export commands in one of these forms:
+ * - `export const commands: Command[]`
+ * - `export default Command`
+ * - `export default Command[]`
+ */
+async function importPluginCommands(
+  contribution: ResolvedCommandContribution
+): Promise<Command[]> {
+  // Resolve the module specifier
+  const moduleId = contribution.module
+    ? `${contribution.pluginName}/${contribution.module.replace(/^\.\//, '')}`
+    : contribution.pluginName;
+
+  const mod = await import(moduleId);
+
+  // Form 1: Named export `commands`
+  if (Array.isArray(mod.commands)) {
+    return mod.commands.filter(isCommandInstance);
+  }
+
+  // Form 2: Default export (single or array)
+  const defaultExport = mod.default;
+  if (defaultExport) {
+    if (Array.isArray(defaultExport)) {
+      return defaultExport.filter(isCommandInstance);
+    }
+    if (isCommandInstance(defaultExport)) {
+      return [defaultExport];
+    }
+  }
+
+  // Fallback: search for any Command instances in module exports
+  const commands: Command[] = [];
+  for (const key of Object.keys(mod)) {
+    if (isCommandInstance(mod[key])) {
+      commands.push(mod[key]);
+    }
+  }
+
+  return commands;
+}
+
+/**
+ * Check if a value is a Commander.js Command instance.
+ * Uses duck-typing to avoid import dependency issues.
+ */
+function isCommandInstance(value: unknown): value is Command {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    typeof (value as any).name === 'function' &&
+    typeof (value as any).description === 'function' &&
+    typeof (value as any).action === 'function' &&
+    typeof (value as any).parse === 'function'
+  );
+}
+
+/**
+ * Resolve a human-readable name from a plugin object.
+ */
+function resolvePluginName(plugin: Record<string, unknown>): string {
+  if (typeof plugin.name === 'string') return plugin.name;
+  const manifest = plugin.manifest as Record<string, unknown> | undefined;
+  if (manifest && typeof manifest.name === 'string') return manifest.name;
+  if (plugin.constructor && plugin.constructor.name !== 'Object') return plugin.constructor.name;
+  return 'unknown';
+}

packages/cli/test/plugin-commands.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { Command } from 'commander';
+import { loadPluginCommands } from '../src/utils/plugin-commands';
+
+// Mock the config loader
+vi.mock('../src/utils/config.js', () => ({
+  loadConfig: vi.fn(),
+}));
+
+import { loadConfig } from '../src/utils/config';
+
+const mockedLoadConfig = vi.mocked(loadConfig);
+
+describe('loadPluginCommands', () => {
+  let program: Command;
+
+  beforeEach(() => {
+    program = new Command();
+    program.name('objectstack');
+    vi.clearAllMocks();
+  });
+
+  it('should do nothing when no config file exists', async () => {
+    mockedLoadConfig.mockRejectedValue(new Error('No config found'));
+
+    await loadPluginCommands(program);
+    expect(program.commands).toHaveLength(0);
+  });
+
+  it('should do nothing when no plugins have command contributions', async () => {
+    mockedLoadConfig.mockResolvedValue({
+      config: {
+        plugins: [
+          { name: 'simple-plugin' },
+        ],
+      },
+      absolutePath: '/test/objectstack.config.ts',
+      duration: 10,
+    });
+
+    await loadPluginCommands(program);
+    expect(program.commands).toHaveLength(0);
+  });
+
+  it('should do nothing when plugins array is empty', async () => {
+    mockedLoadConfig.mockResolvedValue({
+      config: {
+        plugins: [],
+      },
+      absolutePath: '/test/objectstack.config.ts',
+      duration: 10,
+    });
+
+    await loadPluginCommands(program);
+    expect(program.commands).toHaveLength(0);
+  });
+
+  it('should do nothing when config has no plugins key', async () => {
+    mockedLoadConfig.mockResolvedValue({
+      config: {},
+      absolutePath: '/test/objectstack.config.ts',
+      duration: 10,
+    });
+
+    await loadPluginCommands(program);
+    expect(program.commands).toHaveLength(0);
+  });
+
+  it('should detect command contributions from plugin manifest', async () => {
+    // This test verifies that the contribution detection logic works,
+    // even though the dynamic import will fail (no real module to load)
+    mockedLoadConfig.mockResolvedValue({
+      config: {
+        plugins: [
+          {
+            name: '@acme/plugin-marketplace',
+            manifest: {
+              contributes: {
+                commands: [
+                  {
+                    name: 'marketplace',
+                    description: 'Manage marketplace apps',
+                    module: './cli',
+                  },
+                ],
+              },
+            },
+          },
+        ],
+      },
+      absolutePath: '/test/objectstack.config.ts',
+      duration: 10,
+    });
+
+    // loadPluginCommands will try to import the module and fail silently
+    // (since no real module exists), but it should not throw
+    await loadPluginCommands(program);
+  });
+
+  it('should detect contributions from top-level contributes field', async () => {
+    mockedLoadConfig.mockResolvedValue({
+      config: {
+        plugins: [
+          {
+            name: '@acme/plugin-deploy',
+            contributes: {
+              commands: [
+                {
+                  name: 'deploy',
+                  description: 'Deploy to cloud',
+                },
+              ],
+            },
+          },
+        ],
+      },
+      absolutePath: '/test/objectstack.config.ts',
+      duration: 10,
+    });
+
+    // Should not throw even if import fails
+    await loadPluginCommands(program);
+  });
+
+  it('should skip non-object plugins', async () => {
+    mockedLoadConfig.mockResolvedValue({
+      config: {
+        plugins: [
+          'some-string-plugin',
+          null,
+          undefined,
+          42,
+        ],
+      },
+      absolutePath: '/test/objectstack.config.ts',
+      duration: 10,
+    });
+
+    await loadPluginCommands(program);
+    expect(program.commands).toHaveLength(0);
+  });
+
+  it('should handle plugins with non-array commands gracefully', async () => {
+    mockedLoadConfig.mockResolvedValue({
+      config: {
+        plugins: [
+          {
+            name: '@acme/bad-plugin',
+            contributes: {
+              commands: 'not-an-array',
+            },
+          },
+        ],
+      },
+      absolutePath: '/test/objectstack.config.ts',
+      duration: 10,
+    });
+
+    await loadPluginCommands(program);
+    expect(program.commands).toHaveLength(0);
+  });
+});