@objectstack/cli 3.0.5 → 3.0.7

package/src/commands/compile.ts

@@ -1,11 +1,11 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import { Command } from 'commander';
+import { Args, Command, Flags } from '@oclif/core';
 import path from 'path';
 import fs from 'fs';
 import chalk from 'chalk';
 import { ZodError } from 'zod';
-import { ObjectStackDefinitionSchema } from '@objectstack/spec';
+import { ObjectStackDefinitionSchema, normalizeStackInput } from '@objectstack/spec';
 import { loadConfig } from '../utils/config.js';
 import {
   printHeader,
@@ -19,46 +19,55 @@ import {
   printMetadataStats,
 } from '../utils/format.js';
 
-export const compileCommand = new Command('compile')
-  .description('Compile ObjectStack configuration to JSON artifact')
-  .argument('[config]', 'Source configuration file')
-  .option('-o, --output <path>', 'Output JSON file', 'dist/objectstack.json')
-  .option('--json', 'Output compile result as JSON (for CI)')
-  .action(async (configPath, options) => {
+export default class Compile extends Command {
+  static override description = 'Compile ObjectStack configuration to JSON artifact';
+
+  static override args = {
+    config: Args.string({ description: 'Source configuration file', required: false }),
+  };
+
+  static override flags = {
+    output: Flags.string({ char: 'o', description: 'Output JSON file', default: 'dist/objectstack.json' }),
+    json: Flags.boolean({ description: 'Output compile result as JSON (for CI)' }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(Compile);
     const timer = createTimer();
 
-    if (!options.json) {
+    if (!flags.json) {
       printHeader('Compile');
     }
 
     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', path.relative(process.cwd(), absolutePath));
         printKV('Load time', `${duration}ms`);
       }
 
-      // 2. Validate against Protocol
-      if (!options.json) printStep('Validating protocol compliance...');
-      const result = ObjectStackDefinitionSchema.safeParse(config);
+      // 2. Normalize map-formatted stack definition and validate against Protocol
+      if (!flags.json) printStep('Validating protocol compliance...');
+      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({ success: false, errors: (result.error as unknown as ZodError).issues }));
-          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. Generate Artifact
-      if (!options.json) printStep('Writing artifact...');
-      const output = options.output;
+      if (!flags.json) printStep('Writing artifact...');
+      const output = flags.output!;
       const artifactPath = path.resolve(process.cwd(), output);
       const artifactDir = path.dirname(artifactPath);
 
@@ -72,7 +81,7 @@ export const compileCommand = new Command('compile')
       const sizeKB = (jsonContent.length / 1024).toFixed(1);
       const stats = collectMetadataStats(config);
 
-      if (options.json) {
+      if (flags.json) {
         console.log(JSON.stringify({
           success: true,
           output: artifactPath,
@@ -93,12 +102,13 @@ export const compileCommand = new Command('compile')
       console.log('');
 
     } catch (error: any) {
-      if (options.json) {
+      if (flags.json) {
         console.log(JSON.stringify({ success: false, error: error.message }));
-        process.exit(1);
+        this.exit(1);
       }
       console.log('');
       printError(error.message || String(error));
-      process.exit(1);
+      this.error(error.message || String(error));
     }
-  });
+  }
+}

package/src/commands/create.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 fs from 'fs';
 import path from 'path';
@@ -182,37 +182,46 @@ function toCamelCase(str: string): string {
   return str.replace(/-([a-z])/g, (g) => g[1].toUpperCase());
 }
 
-export const createCommand = new Command('create')
-  .description('Create a new package, plugin, or example from template')
-  .argument('<type>', 'Type of project to create (plugin, example)')
-  .argument('[name]', 'Name of the project')
-  .option('-d, --dir <directory>', 'Target directory')
-  .action(async (type: string, name?: string, options?: { dir?: string }) => {
+export default class Create extends Command {
+  static override description = 'Create a new package, plugin, or example from template';
+
+  static override args = {
+    type: Args.string({ description: 'Type of project to create (plugin, example)', required: true }),
+    name: Args.string({ description: 'Name of the project', required: false }),
+  };
+
+  static override flags = {
+    dir: Flags.string({ char: 'd', description: 'Target directory' }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(Create);
+
     console.log(chalk.bold(`\n📦 ObjectStack Project Creator`));
     console.log(chalk.dim(`-------------------------------`));
     
-    if (!templates[type as keyof typeof templates]) {
-      console.error(chalk.red(`\n❌ Unknown type: ${type}`));
+    if (!templates[args.type as keyof typeof templates]) {
+      console.error(chalk.red(`\n❌ Unknown type: ${args.type}`));
       console.log(chalk.dim('Available types: plugin, example'));
       process.exit(1);
     }
     
-    if (!name) {
+    if (!args.name) {
       console.error(chalk.red('\n❌ Project name is required'));
-      console.log(chalk.dim(`Usage: objectstack create ${type} <name>`));
+      console.log(chalk.dim(`Usage: objectstack create ${args.type} <name>`));
       process.exit(1);
     }
     
-    const template = templates[type as keyof typeof templates];
+    const template = templates[args.type as keyof typeof templates];
     const cwd = process.cwd();
     
     // Determine target directory
     let targetDir: string;
-    if (options?.dir) {
-      targetDir = path.resolve(cwd, options.dir);
+    if (flags.dir) {
+      targetDir = path.resolve(cwd, flags.dir);
     } else {
-      const baseDir = type === 'plugin' ? 'packages/plugins' : 'examples';
-      const projectName = type === 'plugin' ? `plugin-${name}` : name;
+      const baseDir = args.type === 'plugin' ? 'packages/plugins' : 'examples';
+      const projectName = args.type === 'plugin' ? `plugin-${args.name}` : args.name;
       targetDir = path.join(cwd, baseDir, projectName);
     }
     
@@ -222,7 +231,7 @@ export const createCommand = new Command('create')
       process.exit(1);
     }
     
-    console.log(`📁 Creating ${type}: ${chalk.blue(name)}`);
+    console.log(`📁 Creating ${args.type}: ${chalk.blue(args.name)}`);
     console.log(`📂 Location: ${chalk.dim(targetDir)}`);
     console.log('');
     
@@ -239,7 +248,7 @@ export const createCommand = new Command('create')
           fs.mkdirSync(dir, { recursive: true });
         }
         
-        const content = contentFn(name);
+        const content = contentFn(args.name);
         const fileContent = typeof content === 'string' 
           ? content 
           : JSON.stringify(content, null, 2);
@@ -268,4 +277,5 @@ export const createCommand = new Command('create')
       
       process.exit(1);
     }
-  });
+  }
+}

package/src/commands/dev.ts

@@ -1,19 +1,29 @@
 // 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 { execSync, spawn } from 'child_process';
 import fs from 'fs';
 import path from 'path';
 import { printHeader, printKV, printStep, printError } from '../utils/format.js';
 
-export const devCommand = new Command('dev')
-  .description('Start development mode with hot-reload')
-  .argument('[package]', 'Package name or filter pattern', 'all')
-  .option('-w, --watch', 'Enable watch mode (default)', true)
-  .option('--ui', 'Enable Studio UI at /_studio/')
-  .option('-v, --verbose', 'Verbose output')
-  .action(async (packageName, options) => {
+export default class Dev extends Command {
+  static override description = 'Start development mode with hot-reload';
+
+  static override args = {
+    package: Args.string({ description: 'Package name or filter pattern', default: 'all', required: false }),
+  };
+
+  static override flags = {
+    watch: Flags.boolean({ char: 'w', description: 'Enable watch mode (default)', default: true }),
+    ui: Flags.boolean({ description: 'Enable Studio UI at /_studio/' }),
+    verbose: Flags.boolean({ char: 'v', description: 'Verbose output' }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(Dev);
+    const packageName = args.package;
+
     printHeader('Development Mode');
     
     // Check if we are running inside a package (Single Package Mode)
@@ -28,7 +38,7 @@ export const devCommand = new Command('dev')
        // usage: objectstack serve --dev
        const binPath = process.argv[1]; // path to objectstack bin
        
-       const child = spawn(process.execPath, [binPath, 'serve', '--dev', ...(options.ui ? ['--ui'] : []), ...(options.verbose ? ['--verbose'] : [])], {
+       const child = spawn(process.execPath, [binPath, 'serve', '--dev', ...(flags.ui ? ['--ui'] : []), ...(flags.verbose ? ['--verbose'] : [])], {
          stdio: 'inherit',
          env: { ...process.env, NODE_ENV: 'development' }
        });
@@ -69,4 +79,5 @@ export const devCommand = new Command('dev')
       printError(`Development mode failed: ${error.message || error}`);
       process.exit(1);
     }
-  });
+  }
+}

package/src/commands/diff.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 { loadConfig } from '../utils/config.js';
 import {
@@ -153,19 +153,27 @@ function diffNamedArrays(
 
 // ─── Command ────────────────────────────────────────────────────────
 
-export const diffCommand = new Command('diff')
-  .description('Compare two ObjectStack configurations and detect breaking changes')
-  .argument('[before]', 'Path to the "before" config file')
-  .argument('[after]', 'Path to the "after" config file')
-  .option('--before <path>', 'Path to the "before" config (alternative)')
-  .option('--after <path>', 'Path to the "after" config (alternative)')
-  .option('--json', 'Output as JSON')
-  .option('--breaking-only', 'Show only breaking changes')
-  .action(async (beforeArg, afterArg, options) => {
+export default class Diff extends Command {
+  static override description = 'Compare two ObjectStack configurations and detect breaking changes';
+
+  static override args = {
+    before: Args.string({ description: 'Path to the "before" config file', required: false }),
+    after: Args.string({ description: 'Path to the "after" config file', required: false }),
+  };
+
+  static override flags = {
+    before: Flags.string({ description: 'Path to the "before" config (alternative)' }),
+    after: Flags.string({ description: 'Path to the "after" config (alternative)' }),
+    json: Flags.boolean({ description: 'Output as JSON' }),
+    'breaking-only': Flags.boolean({ description: 'Show only breaking changes' }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(Diff);
     const timer = createTimer();
 
-    const beforePath: string | undefined = beforeArg || options.before;
-    const afterPath: string | undefined = afterArg || options.after;
+    const beforePath: string | undefined = args.before || flags.before;
+    const afterPath: string | undefined = args.after || flags.after;
 
     if (!beforePath || !afterPath) {
       printError('Two config file paths are required.');
@@ -175,7 +183,7 @@ export const diffCommand = new Command('diff')
       process.exit(1);
     }
 
-    if (!options.json) {
+    if (!flags.json) {
       printHeader('Diff');
       printStep('Loading configurations...');
     }
@@ -184,7 +192,7 @@ export const diffCommand = new Command('diff')
       const { config: beforeConfig } = await loadConfig(beforePath);
       const { config: afterConfig } = await loadConfig(afterPath);
 
-      if (!options.json) {
+      if (!flags.json) {
         printInfo(`Before: ${chalk.white(beforePath)}`);
         printInfo(`After:  ${chalk.white(afterPath)}`);
       }
@@ -215,14 +223,14 @@ export const diffCommand = new Command('diff')
       }
 
       // ── Filter ──
-      const diffs = options.breakingOnly
+      const diffs = flags['breaking-only']
         ? allDiffs.filter((d) => d.breaking)
         : allDiffs;
 
       const breakingCount = allDiffs.filter((d) => d.breaking).length;
 
       // ── Output ──
-      if (options.json) {
+      if (flags.json) {
         console.log(JSON.stringify({
           before: beforePath,
           after: afterPath,
@@ -237,7 +245,7 @@ export const diffCommand = new Command('diff')
       console.log('');
 
       if (diffs.length === 0) {
-        printSuccess(options.breakingOnly
+        printSuccess(flags['breaking-only']
           ? 'No breaking changes detected.'
           : 'No changes detected.');
         console.log('');
@@ -274,7 +282,7 @@ export const diffCommand = new Command('diff')
       console.log('');
 
     } catch (error: any) {
-      if (options.json) {
+      if (flags.json) {
         console.log(JSON.stringify({ error: error.message }));
         process.exit(1);
       }
@@ -282,4 +290,5 @@ export const diffCommand = new Command('diff')
       printError(error.message || String(error));
       process.exit(1);
     }
-  });
+  }
+}

package/src/commands/doctor.ts

@@ -1,10 +1,11 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import { Command } from 'commander';
+import { Command, Flags } from '@oclif/core';
 import chalk from 'chalk';
 import { execSync } from 'child_process';
 import fs from 'fs';
 import path from 'path';
+import { normalizeStackInput } from '@objectstack/spec';
 import { printHeader, printSuccess, printWarning, printError, printStep, printInfo } from '../utils/format.js';
 import { loadConfig, configExists } from '../utils/config.js';
 
@@ -298,11 +299,17 @@ function scanDeprecatedPatterns(dir: string): Array<{ file: string; line: number
 
 // ─── Command ────────────────────────────────────────────────────────
 
-export const doctorCommand = new Command('doctor')
-  .description('Check development environment and configuration health')
-  .option('-v, --verbose', 'Show detailed information')
-  .option('--scan-deprecations', 'Scan for deprecated ObjectStack patterns')
-  .action(async (options) => {
+export default class Doctor extends Command {
+  static override description = 'Check development environment and configuration health';
+
+  static override flags = {
+    verbose: Flags.boolean({ char: 'v', description: 'Show detailed information' }),
+    'scan-deprecations': Flags.boolean({ description: 'Scan for deprecated ObjectStack patterns' }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(Doctor);
+
     printHeader('Environment Health Check');
     
     const results: HealthCheckResult[] = [];
@@ -438,7 +445,7 @@ export const doctorCommand = new Command('doctor')
         printError(`${padded} ${result.message}`);
       }
       
-      if (result.fix && (options.verbose || result.status === 'error')) {
+      if (result.fix && (flags.verbose || result.status === 'error')) {
         console.log(chalk.dim(`      → ${result.fix}`));
       }
       
@@ -476,7 +483,8 @@ export const doctorCommand = new Command('doctor')
     if (configExists()) {
       printStep('Loading configuration for analysis...');
       try {
-        const { config } = await loadConfig();
+        const { config: rawConfig } = await loadConfig();
+        const config: any = normalizeStackInput(rawConfig as Record<string, unknown>);
 
         // Circular dependency detection
         if (Array.isArray(config.objects) && config.objects.length > 0) {
@@ -524,7 +532,7 @@ export const doctorCommand = new Command('doctor')
     }
 
     // ── Deprecation Pattern Scan ─────────────────────────────────────
-    if (options.scanDeprecations) {
+    if (flags['scan-deprecations']) {
       printStep('Scanning for deprecated ObjectStack patterns...');
       const scanDir = path.join(cwd, 'src');
       const deprecations = scanDeprecatedPatterns(scanDir);
@@ -532,7 +540,7 @@ export const doctorCommand = new Command('doctor')
         hasWarnings = true;
         for (const dep of deprecations) {
           printWarning(`${dep.file}:${dep.line} — ${dep.description}`);
-          if (options.verbose) {
+          if (flags.verbose) {
             console.log(chalk.dim(`      → ${dep.replacement}`));
           }
         }
@@ -560,4 +568,5 @@ export const doctorCommand = new Command('doctor')
     }
     
     console.log('');
-  });
+  }
+}

package/src/commands/explain.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 {
   printHeader,
@@ -314,15 +314,24 @@ const SCHEMAS: Record<string, SchemaInfo> = {
 
 // ─── Command ────────────────────────────────────────────────────────
 
-export const explainCommand = new Command('explain')
-  .description('Display human-readable explanation of an ObjectStack schema')
-  .argument('[schema]', 'Schema name (e.g., object, field, view, flow, agent, app)')
-  .option('--json', 'Output as JSON')
-  .action(async (schemaName, options) => {
+export default class Explain extends Command {
+  static override description = 'Display human-readable explanation of an ObjectStack schema';
+
+  static override args = {
+    schema: Args.string({ description: 'Schema name (e.g., object, field, view, flow, agent, app)', required: false }),
+  };
+
+  static override flags = {
+    json: Flags.boolean({ description: 'Output as JSON' }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(Explain);
+    const schemaName = args.schema;
 
     // ── No argument: list all schemas ──
     if (!schemaName) {
-      if (options.json) {
+      if (flags.json) {
         console.log(JSON.stringify({
           schemas: Object.entries(SCHEMAS).map(([key, s]) => ({
             name: key,
@@ -347,7 +356,7 @@ export const explainCommand = new Command('explain')
     // ── Lookup schema ──
     const schema = SCHEMAS[schemaName.toLowerCase()];
     if (!schema) {
-      if (options.json) {
+      if (flags.json) {
         console.log(JSON.stringify({ error: `Unknown schema: ${schemaName}` }));
         process.exit(1);
       }
@@ -359,7 +368,7 @@ export const explainCommand = new Command('explain')
     }
 
     // ── JSON output ──
-    if (options.json) {
+    if (flags.json) {
       console.log(JSON.stringify(schema, null, 2));
       return;
     }
@@ -399,4 +408,5 @@ export const explainCommand = new Command('explain')
     // Documentation link
     printKV('  Docs', `https://objectstack.dev/docs/${schema.docsPath}`);
     console.log('');
-  });
+  }
+}