@objectstack/cli 2.0.6 → 3.0.0

package/src/utils/plugin-commands.ts

@@ -0,0 +1,163 @@
+// 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: Record<string, unknown>;
+
+  try {
+    const loaded = await loadConfig();
+    config = loaded.config;
+  } catch {
+    // No config file found — nothing to load
+    return;
+  }
+
+  const plugins: unknown[] = [
+    ...((config.plugins as unknown[] | undefined) || []),
+    ...((config.devPlugins as unknown[] | undefined) || []),
+  ];
+
+  // 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: unknown) {
+      // Log warning but don't crash — plugin commands are optional
+      if (process.env.DEBUG) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(
+          chalk.yellow(`  ⚠ Failed to load CLI command '${contribution.name}' from plugin '${contribution.pluginName}': ${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 {
+  if (value === null || typeof value !== 'object') return false;
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj.name === 'function' &&
+    typeof obj.description === 'function' &&
+    typeof obj.action === 'function' &&
+    typeof obj.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';
+}

package/test/commands.test.ts

@@ -9,6 +9,7 @@ import { validateCommand } from '../src/commands/validate';
 import { initCommand } from '../src/commands/init';
 import { infoCommand } from '../src/commands/info';
 import { generateCommand } from '../src/commands/generate';
+import { pluginCommand } from '../src/commands/plugin';
 
 describe('CLI Commands', () => {
   it('should have compile command', () => {
@@ -61,4 +62,9 @@ describe('CLI Commands', () => {
     expect(generateCommand.alias()).toBe('g');
     expect(generateCommand.description()).toContain('Generate');
   });
+
+  it('should have plugin command with subcommands', () => {
+    expect(pluginCommand.name()).toBe('plugin');
+    expect(pluginCommand.description()).toContain('plugin');
+  });
 });

package/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);
+  });
+});

package/test/plugin.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { pluginCommand } from '../src/commands/plugin';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+describe('Plugin Command', () => {
+  it('should have plugin command with subcommands', () => {
+    expect(pluginCommand.name()).toBe('plugin');
+    expect(pluginCommand.description()).toContain('plugin');
+  });
+
+  it('should have list subcommand with alias', () => {
+    const list = pluginCommand.commands.find(c => c.name() === 'list');
+    expect(list).toBeDefined();
+    expect(list!.alias()).toBe('ls');
+    expect(list!.description()).toContain('List');
+  });
+
+  it('should have info subcommand', () => {
+    const info = pluginCommand.commands.find(c => c.name() === 'info');
+    expect(info).toBeDefined();
+    expect(info!.description()).toContain('information');
+  });
+
+  it('should have add subcommand', () => {
+    const add = pluginCommand.commands.find(c => c.name() === 'add');
+    expect(add).toBeDefined();
+    expect(add!.description()).toContain('Add');
+  });
+
+  it('should have remove subcommand with alias', () => {
+    const remove = pluginCommand.commands.find(c => c.name() === 'remove');
+    expect(remove).toBeDefined();
+    expect(remove!.alias()).toBe('rm');
+    expect(remove!.description()).toContain('Remove');
+  });
+});
+
+describe('Plugin Config Manipulation', () => {
+  let tmpDir: string;
+  let configPath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'os-plugin-test-'));
+    configPath = path.join(tmpDir, 'objectstack.config.ts');
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('addPluginToConfig (via file manipulation)', () => {
+    it('should add plugin import and entry to config with existing plugins array', () => {
+      fs.writeFileSync(configPath, `import { defineStack } from '@objectstack/spec';
+
+export default defineStack({
+  manifest: {
+    name: 'test-app',
+    version: '1.0.0',
+  },
+  plugins: [
+  ],
+});
+`);
+
+      // Simulate what the add command does
+      let content = fs.readFileSync(configPath, 'utf-8');
+      const packageName = '@objectstack/plugin-auth';
+      const varName = 'authPlugin';
+      const importLine = `import ${varName} from '${packageName}';\n`;
+      
+      // Add import after last import
+      const importRegex = /^import .+$/gm;
+      let lastImportEnd = 0;
+      let match: RegExpExecArray | null;
+      while ((match = importRegex.exec(content)) !== null) {
+        lastImportEnd = match.index + match[0].length;
+      }
+      content = content.slice(0, lastImportEnd) + '\n' + importLine + content.slice(lastImportEnd);
+      
+      // Add to plugins array
+      content = content.replace(
+        /(plugins\s*:\s*\[)/,
+        `$1\n    ${varName},`
+      );
+
+      fs.writeFileSync(configPath, content);
+      
+      const result = fs.readFileSync(configPath, 'utf-8');
+      expect(result).toContain("import authPlugin from '@objectstack/plugin-auth'");
+      expect(result).toContain('authPlugin,');
+    });
+
+    it('should add plugin to config without existing plugins array', () => {
+      fs.writeFileSync(configPath, `import { defineStack } from '@objectstack/spec';
+
+export default defineStack({
+  manifest: {
+    name: 'test-app',
+    version: '1.0.0',
+  },
+});
+`);
+
+      let content = fs.readFileSync(configPath, 'utf-8');
+      const packageName = '@objectstack/plugin-security';
+      const varName = 'securityPlugin';
+      const importLine = `import ${varName} from '${packageName}';\n`;
+
+      // Add import
+      const importRegex = /^import .+$/gm;
+      let lastImportEnd = 0;
+      let match: RegExpExecArray | null;
+      while ((match = importRegex.exec(content)) !== null) {
+        lastImportEnd = match.index + match[0].length;
+      }
+      content = content.slice(0, lastImportEnd) + '\n' + importLine + content.slice(lastImportEnd);
+
+      // Add plugins array
+      if (!/plugins\s*:\s*\[/.test(content)) {
+        content = content.replace(
+          /(defineStack\(\{[\s\S]*?)(}\s*\))/,
+          `$1  plugins: [\n    ${varName},\n  ],\n$2`
+        );
+      }
+
+      fs.writeFileSync(configPath, content);
+
+      const result = fs.readFileSync(configPath, 'utf-8');
+      expect(result).toContain("import securityPlugin from '@objectstack/plugin-security'");
+      expect(result).toContain('plugins: [');
+      expect(result).toContain('securityPlugin,');
+    });
+  });
+
+  describe('removePluginFromConfig (via file manipulation)', () => {
+    it('should remove plugin import and entry from config', () => {
+      fs.writeFileSync(configPath, `import { defineStack } from '@objectstack/spec';
+import authPlugin from '@objectstack/plugin-auth';
+
+export default defineStack({
+  manifest: {
+    name: 'test-app',
+    version: '1.0.0',
+  },
+  plugins: [
+    authPlugin,
+  ],
+});
+`);
+
+      let content = fs.readFileSync(configPath, 'utf-8');
+      const packageName = '@objectstack/plugin-auth';
+      
+      // Remove import
+      const importRegex = new RegExp(`^import .+['"]${packageName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"].*$\\n?`, 'gm');
+      content = content.replace(importRegex, '');
+
+      // Remove from plugins array
+      content = content.replace(/\s*authPlugin,?\n?/g, '\n');
+
+      fs.writeFileSync(configPath, content);
+
+      const result = fs.readFileSync(configPath, 'utf-8');
+      expect(result).not.toContain('@objectstack/plugin-auth');
+      expect(result).not.toContain('authPlugin');
+      // The rest of the config should remain intact
+      expect(result).toContain("import { defineStack } from '@objectstack/spec'");
+      expect(result).toContain('manifest');
+    });
+  });
+});