@objectstack/cli 3.0.6 → 3.0.8

package/src/commands/validate.ts

@@ -1,6 +1,6 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import { Command } from 'commander';
+import { Args, Command, Flags } from '@oclif/core';
 import chalk from 'chalk';
 import { ZodError } from 'zod';
 import { ObjectStackDefinitionSchema, normalizeStackInput } from '@objectstack/spec';
@@ -17,53 +17,62 @@ import {
   printMetadataStats,
 } from '../utils/format.js';
 
-export const validateCommand = new Command('validate')
-  .description('Validate ObjectStack configuration against the protocol schema')
-  .argument('[config]', 'Configuration file path')
-  .option('--strict', 'Treat warnings as errors')
-  .option('--json', 'Output results as JSON')
-  .action(async (configPath, options) => {
+export default class Validate extends Command {
+  static override description = 'Validate ObjectStack configuration against the protocol schema';
+
+  static override args = {
+    config: Args.string({ description: 'Configuration file path', required: false }),
+  };
+
+  static override flags = {
+    strict: Flags.boolean({ description: 'Treat warnings as errors' }),
+    json: Flags.boolean({ description: 'Output results as JSON' }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(Validate);
+
     const timer = createTimer();
     
-    if (!options.json) {
+    if (!flags.json) {
       printHeader('Validate');
     }
 
     try {
       // 1. Load configuration
-      if (!options.json) printStep('Loading configuration...');
-      const { config, absolutePath, duration } = await loadConfig(configPath);
+      if (!flags.json) printStep('Loading configuration...');
+      const { config, absolutePath, duration } = await loadConfig(args.config);
       
-      if (!options.json) {
+      if (!flags.json) {
         printKV('Config', absolutePath);
         printKV('Load time', `${duration}ms`);
       }
 
       // 2. Normalize map-formatted stack definition and validate against schema
-      if (!options.json) printStep('Validating against ObjectStack Protocol...');
+      if (!flags.json) printStep('Validating against ObjectStack Protocol...');
       const normalized = normalizeStackInput(config as Record<string, unknown>);
       const result = ObjectStackDefinitionSchema.safeParse(normalized);
 
       if (!result.success) {
-        if (options.json) {
+        if (flags.json) {
           console.log(JSON.stringify({
             valid: false,
             errors: (result.error as unknown as ZodError).issues,
             duration: timer.elapsed(),
           }, null, 2));
-          process.exit(1);
+          this.exit(1);
         }
 
         console.log('');
         printError('Validation failed');
         formatZodErrors(result.error as unknown as ZodError);
-        process.exit(1);
+        this.exit(1);
       }
 
       // 3. Collect and display stats
       const stats = collectMetadataStats(config);
 
-      if (options.json) {
+      if (flags.json) {
         console.log(JSON.stringify({
           valid: true,
           manifest: config.manifest,
@@ -109,25 +118,26 @@ export const validateCommand = new Command('validate')
         for (const w of warnings) {
           console.log(chalk.yellow(`  ⚠ ${w}`));
         }
-        if (options.strict) {
+        if (flags.strict) {
           console.log('');
           printError('Strict mode: warnings treated as errors');
-          process.exit(1);
+          this.exit(1);
         }
       }
 
       console.log('');
     } catch (error: any) {
-      if (options.json) {
+      if (flags.json) {
         console.log(JSON.stringify({
           valid: false,
           error: error.message,
           duration: timer.elapsed(),
         }, null, 2));
-        process.exit(1);
+        this.exit(1);
       }
       console.log('');
       printError(error.message || String(error));
-      process.exit(1);
+      this.exit(1);
     }
-  });
+  }
+}

package/src/index.ts

@@ -1,14 +1,22 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-export * from './commands/compile.js';
-export * from './commands/validate.js';
-export * from './commands/info.js';
-export * from './commands/init.js';
-export * from './commands/generate.js';
-export * from './commands/create.js';
-export * from './commands/plugin.js';
-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';
+// ─── oclif Command Classes ──────────────────────────────────────────
+// Each command is auto-discovered by oclif from `src/commands/`.
+// These re-exports provide programmatic access for testing and integration.
+
+export { default as CompileCommand } from './commands/compile.js';
+export { default as ValidateCommand } from './commands/validate.js';
+export { default as InfoCommand } from './commands/info.js';
+export { default as InitCommand } from './commands/init.js';
+export { default as GenerateCommand } from './commands/generate.js';
+export { default as CreateCommand } from './commands/create.js';
+export { default as DevCommand } from './commands/dev.js';
+export { default as ServeCommand } from './commands/serve.js';
+export { default as TestCommand } from './commands/test.js';
+export { default as DoctorCommand } from './commands/doctor.js';
+
+// ─── Plugin topic subcommands ───────────────────────────────────────
+export { default as PluginListCommand } from './commands/plugin/list.js';
+export { default as PluginInfoCommand } from './commands/plugin/info.js';
+export { default as PluginAddCommand } from './commands/plugin/add.js';
+export { default as PluginRemoveCommand } from './commands/plugin/remove.js';

package/src/utils/plugin-helpers.ts

@@ -0,0 +1,37 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Resolve plugin display name from a plugin entry.
+ * Plugins can be string package names, objects with `.name`, or class instances.
+ */
+export function resolvePluginName(plugin: unknown): string {
+  if (typeof plugin === 'string') return plugin;
+  if (plugin && typeof plugin === 'object') {
+    const p = plugin as Record<string, unknown>;
+    if (typeof p.name === 'string') return p.name;
+    if (p.constructor && p.constructor.name !== 'Object') return p.constructor.name;
+  }
+  return 'unknown';
+}
+
+/**
+ * Resolve plugin version from a plugin entry.
+ */
+export function resolvePluginVersion(plugin: unknown): string {
+  if (plugin && typeof plugin === 'object') {
+    const p = plugin as Record<string, unknown>;
+    if (typeof p.version === 'string') return p.version;
+  }
+  return '-';
+}
+
+/**
+ * Resolve plugin type from a plugin entry.
+ */
+export function resolvePluginType(plugin: unknown): string {
+  if (plugin && typeof plugin === 'object') {
+    const p = plugin as Record<string, unknown>;
+    if (typeof p.type === 'string') return p.type;
+  }
+  return 'standard';
+}

package/src/utils/studio.ts

@@ -236,7 +236,6 @@ export function createStudioProxyPlugin(vitePort: number) {
             method: c.req.method,
             headers,
             body: isBodyAllowed ? c.req.raw.body : undefined,
-            // @ts-expect-error — duplex required for streaming request body
             duplex: isBodyAllowed ? 'half' : undefined,
           });
 

package/test/commands.test.ts

@@ -1,70 +1,109 @@
 import { describe, it, expect } from 'vitest';
-import { compileCommand } from '../src/commands/compile';
-import { serveCommand } from '../src/commands/serve';
-import { devCommand } from '../src/commands/dev';
-import { doctorCommand } from '../src/commands/doctor';
-import { createCommand } from '../src/commands/create';
-import { testCommand } from '../src/commands/test';
-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', () => {
+import Compile from '../src/commands/compile';
+import Serve from '../src/commands/serve';
+import Dev from '../src/commands/dev';
+import Doctor from '../src/commands/doctor';
+import Create from '../src/commands/create';
+import Test from '../src/commands/test';
+import Validate from '../src/commands/validate';
+import Init from '../src/commands/init';
+import Info from '../src/commands/info';
+import Generate from '../src/commands/generate';
+import Lint from '../src/commands/lint';
+import Diff from '../src/commands/diff';
+import Explain from '../src/commands/explain';
+import Studio from '../src/commands/studio';
+import PluginList from '../src/commands/plugin/list';
+import PluginInfo from '../src/commands/plugin/info';
+import PluginAdd from '../src/commands/plugin/add';
+import PluginRemove from '../src/commands/plugin/remove';
+import V2ToV3 from '../src/commands/codemod/v2-to-v3';
+
+describe('CLI Commands (oclif)', () => {
   it('should have compile command', () => {
-    expect(compileCommand.name()).toBe('compile');
-    expect(compileCommand.description()).toContain('Compile');
+    expect(Compile.description).toContain('Compile');
   });
 
   it('should have serve command', () => {
-    expect(serveCommand.name()).toBe('serve');
-    expect(serveCommand.description()).toContain('server');
+    expect(Serve.description).toContain('server');
   });
 
   it('should have dev command', () => {
-    expect(devCommand.name()).toBe('dev');
-    expect(devCommand.description()).toContain('development mode');
+    expect(Dev.description).toContain('development mode');
   });
 
   it('should have doctor command', () => {
-    expect(doctorCommand.name()).toBe('doctor');
-    expect(doctorCommand.description()).toContain('health');
+    expect(Doctor.description).toContain('health');
   });
 
   it('should have create command', () => {
-    expect(createCommand.name()).toBe('create');
-    expect(createCommand.description()).toContain('Create');
+    expect(Create.description).toContain('Create');
   });
 
   it('should have test command', () => {
-    expect(testCommand.name()).toBe('test');
-    expect(testCommand.description()).toContain('Quality Protocol');
+    expect(Test.description).toContain('Quality Protocol');
   });
 
   it('should have validate command', () => {
-    expect(validateCommand.name()).toBe('validate');
-    expect(validateCommand.description()).toContain('Validate');
+    expect(Validate.description).toContain('Validate');
   });
 
   it('should have init command', () => {
-    expect(initCommand.name()).toBe('init');
-    expect(initCommand.description()).toContain('Initialize');
+    expect(Init.description).toContain('Initialize');
   });
 
   it('should have info command', () => {
-    expect(infoCommand.name()).toBe('info');
-    expect(infoCommand.description()).toContain('summary');
+    expect(Info.description).toContain('summary');
   });
 
   it('should have generate command with alias', () => {
-    expect(generateCommand.name()).toBe('generate');
-    expect(generateCommand.alias()).toBe('g');
-    expect(generateCommand.description()).toContain('Generate');
+    expect(Generate.aliases).toContain('g');
+    expect(Generate.description).toContain('Generate');
+  });
+
+  it('should have lint command', () => {
+    expect(Lint.description).toContain('style');
+  });
+
+  it('should have diff command', () => {
+    expect(Diff.description).toContain('Compare');
+  });
+
+  it('should have explain command', () => {
+    expect(Explain.description).toContain('explanation');
+  });
+
+  it('should have studio command', () => {
+    expect(Studio.description).toContain('Studio');
+  });
+
+  it('should have codemod v2-to-v3 command', () => {
+    expect(V2ToV3.description).toContain('v2');
   });
 
-  it('should have plugin command with subcommands', () => {
-    expect(pluginCommand.name()).toBe('plugin');
-    expect(pluginCommand.description()).toContain('plugin');
+  describe('Plugin subcommands', () => {
+    it('should have plugin list command', () => {
+      expect(PluginList.description).toContain('List');
+    });
+
+    it('should have plugin info command', () => {
+      expect(PluginInfo.description).toContain('information');
+    });
+
+    it('should have plugin add command', () => {
+      expect(PluginAdd.description).toContain('Add');
+    });
+
+    it('should have plugin remove command', () => {
+      expect(PluginRemove.description).toContain('Remove');
+    });
+
+    it('should have plugin remove alias', () => {
+      expect(PluginRemove.aliases).toContain('plugin rm');
+    });
+
+    it('should have plugin list alias', () => {
+      expect(PluginList.aliases).toContain('plugin ls');
+    });
   });
 });

package/test/plugin-commands.test.ts

@@ -1,162 +1,44 @@
-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);
+import { describe, it, expect } from 'vitest';
+
+/**
+ * The custom loadPluginCommands mechanism has been removed.
+ * Plugin command extension is now handled by oclif's built-in plugin system.
+ *
+ * Plugins extend the CLI by:
+ * 1. Including `oclif` config in their package.json
+ * 2. Exporting oclif Command classes from `src/commands/`
+ * 3. Being installed via `os plugins install <package>`
+ *
+ * The objectstack.config.ts no longer determines CLI command availability.
+ */
+
+describe('oclif Plugin System', () => {
+  it('should have oclif plugins configured in package.json', async () => {
+    const { createRequire } = await import('module');
+    const require = createRequire(import.meta.url);
+    const pkg = require('../package.json');
+
+    expect(pkg.oclif).toBeDefined();
+    expect(pkg.oclif.plugins).toContain('@oclif/plugin-help');
+    expect(pkg.oclif.plugins).toContain('@oclif/plugin-plugins');
+  });
+
+  it('should have oclif command discovery configured', async () => {
+    const { createRequire } = await import('module');
+    const require = createRequire(import.meta.url);
+    const pkg = require('../package.json');
+
+    expect(pkg.oclif.commands).toBeDefined();
+    expect(pkg.oclif.commands.strategy).toBe('pattern');
+    expect(pkg.oclif.commands.target).toBe('./dist/commands');
+  });
+
+  it('should have bin entries pointing to oclif runner', async () => {
+    const { createRequire } = await import('module');
+    const require = createRequire(import.meta.url);
+    const pkg = require('../package.json');
+
+    expect(pkg.bin.os).toBe('./bin/run.js');
+    expect(pkg.bin.objectstack).toBe('./bin/run.js');
   });
 });

package/test/plugin.test.ts

@@ -1,39 +1,35 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { pluginCommand } from '../src/commands/plugin';
+import PluginList from '../src/commands/plugin/list';
+import PluginInfo from '../src/commands/plugin/info';
+import PluginAdd from '../src/commands/plugin/add';
+import PluginRemove from '../src/commands/plugin/remove';
 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');
+describe('Plugin Commands (oclif)', () => {
+  it('should have plugin list command', () => {
+    expect(PluginList.description).toContain('List');
   });
 
-  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 plugin list alias', () => {
+    expect(PluginList.aliases).toContain('plugin ls');
   });
 
-  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 plugin info command', () => {
+    expect(PluginInfo.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 plugin add command', () => {
+    expect(PluginAdd.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');
+  it('should have plugin remove command', () => {
+    expect(PluginRemove.description).toContain('Remove');
+  });
+
+  it('should have plugin remove alias', () => {
+    expect(PluginRemove.aliases).toContain('plugin rm');
   });
 });
 

package/tsconfig.build.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src"]
+}

package/bin/objectstack.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import '../dist/bin.js';