@objectstack/cli 3.0.6 → 3.0.8

package/src/commands/plugin/add.ts

@@ -0,0 +1,112 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { Args, Command, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+import { resolveConfigPath } from '../../utils/config.js';
+import { printHeader, printSuccess, printError } from '../../utils/format.js';
+
+/**
+ * Add a plugin import and entry to objectstack.config.ts.
+ *
+ * This performs a simple text-based transformation:
+ * 1. Adds an import statement for the package at the top of the file.
+ * 2. Inserts the imported identifier into the `plugins` array, creating one if absent.
+ */
+function addPluginToConfig(configPath: string, packageName: string): void {
+  let content = fs.readFileSync(configPath, 'utf-8');
+
+  // Derive a variable name from the package name
+  // e.g. "@objectstack/plugin-auth" → "authPlugin"
+  const shortName = packageName
+    .replace(/^@[^/]+\//, '')        // strip scope
+    .replace(/^plugin-/, '')          // strip "plugin-" prefix
+    .replace(/-+/g, '-')             // collapse consecutive hyphens
+    .replace(/^-|-$/g, '');          // trim leading/trailing hyphens
+  const varName = shortName.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase()) + 'Plugin';
+
+  // 1. Add import
+  const importLine = `import ${varName} from '${packageName}';\n`;
+
+  if (content.includes(packageName)) {
+    throw new Error(`Plugin '${packageName}' is already referenced in the config`);
+  }
+
+  // Insert import after the last existing import
+  const importRegex = /^import .+$/gm;
+  let lastImportEnd = 0;
+  let match: RegExpExecArray | null;
+  while ((match = importRegex.exec(content)) !== null) {
+    lastImportEnd = match.index + match[0].length;
+  }
+
+  if (lastImportEnd > 0) {
+    content = content.slice(0, lastImportEnd) + '\n' + importLine + content.slice(lastImportEnd);
+  } else {
+    content = importLine + '\n' + content;
+  }
+
+  // 2. Add to plugins array (target only the first plugins: [ within defineStack)
+  if (/plugins\s*:\s*\[/.test(content)) {
+    // plugins array exists — append to it (first occurrence only)
+    let replaced = false;
+    content = content.replace(
+      /(plugins\s*:\s*\[)/,
+      (match) => {
+        if (replaced) return match;
+        replaced = true;
+        return `${match}\n    ${varName},`;
+      }
+    );
+  } else {
+    // No plugins array — add one before the closing of defineStack({...})
+    // Look for the last property before the closing `})` or `})`
+    content = content.replace(
+      /(defineStack\(\{[\s\S]*?)(}\s*\))/,
+      `$1  plugins: [\n    ${varName},\n  ],\n$2`
+    );
+  }
+
+  fs.writeFileSync(configPath, content);
+}
+
+export { addPluginToConfig };
+
+export default class PluginAdd extends Command {
+  static override description = 'Add a plugin to objectstack.config.ts';
+
+  static override args = {
+    package: Args.string({ description: 'Plugin package name (e.g. @objectstack/plugin-auth)', required: true }),
+  };
+
+  static override flags = {
+    dev: Flags.boolean({ char: 'd', description: 'Add as a dev-only plugin' }),
+    config: Flags.string({ char: 'c', description: 'Configuration file path' }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(PluginAdd);
+
+    try {
+      const configPath = resolveConfigPath(flags.config);
+
+      printHeader('Add Plugin');
+      console.log(`  ${chalk.dim('Package:')} ${chalk.white(args.package)}`);
+      console.log(`  ${chalk.dim('Config:')}  ${chalk.white(path.relative(process.cwd(), configPath))}`);
+      console.log('');
+
+      addPluginToConfig(configPath, args.package);
+      printSuccess(`Added ${chalk.cyan(args.package)} to config`);
+
+      console.log('');
+      console.log(chalk.dim('  Next steps:'));
+      console.log(chalk.dim(`  1. Install the package: pnpm add ${args.package}`));
+      console.log(chalk.dim('  2. Run: os validate'));
+      console.log('');
+    } catch (error: any) {
+      printError(error.message || String(error));
+      this.exit(1);
+    }
+  }
+}

package/src/commands/plugin/info.ts

@@ -0,0 +1,79 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { Args, Command } from '@oclif/core';
+import chalk from 'chalk';
+import { loadConfig } from '../../utils/config.js';
+import { printHeader, printError, printInfo, printKV } from '../../utils/format.js';
+import { resolvePluginName, resolvePluginVersion, resolvePluginType } from '../../utils/plugin-helpers.js';
+
+export default class PluginInfo extends Command {
+  static override description = 'Show detailed information about a plugin';
+
+  static override args = {
+    name: Args.string({ description: 'Plugin name or package name', required: true }),
+    config: Args.string({ description: 'Configuration file path', required: false }),
+  };
+
+  async run(): Promise<void> {
+    const { args } = await this.parse(PluginInfo);
+
+    try {
+      const { config } = await loadConfig(args.config);
+      const allPlugins: unknown[] = [
+        ...(config.plugins || []),
+        ...(config.devPlugins || []),
+      ];
+
+      const found = allPlugins.find((p) => {
+        const pName = resolvePluginName(p);
+        return pName === args.name || pName.includes(args.name);
+      });
+
+      if (!found) {
+        printError(`Plugin '${args.name}' not found in configuration`);
+        console.log('');
+        console.log(chalk.dim('  Available plugins:'));
+        for (const p of allPlugins) {
+          console.log(chalk.dim(`    - ${resolvePluginName(p)}`));
+        }
+        console.log('');
+        this.exit(1);
+      }
+
+      printHeader(`Plugin: ${resolvePluginName(found)}`);
+
+      printKV('Name', resolvePluginName(found));
+      printKV('Version', resolvePluginVersion(found));
+      printKV('Type', resolvePluginType(found));
+
+      const isDev = (config.devPlugins || []).includes(found);
+      printKV('Environment', isDev ? 'development' : 'production');
+
+      if (found && typeof found === 'object') {
+        const p = found as Record<string, unknown>;
+
+        if (typeof p.description === 'string') {
+          printKV('Description', p.description);
+        }
+
+        if (Array.isArray(p.dependencies) && p.dependencies.length > 0) {
+          printKV('Dependencies', p.dependencies.join(', '));
+        }
+
+        // Show services if it's a loaded plugin instance
+        if (typeof p.init === 'function') {
+          printInfo('This is a runtime plugin instance (has init function)');
+        }
+      }
+
+      if (typeof found === 'string') {
+        printInfo('This is a string reference (will be imported at runtime)');
+      }
+
+      console.log('');
+    } catch (error: any) {
+      printError(error.message || String(error));
+      this.exit(1);
+    }
+  }
+}

package/src/commands/plugin/list.ts

@@ -0,0 +1,93 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { Args, Command, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import { loadConfig } from '../../utils/config.js';
+import { printHeader, printInfo, printError } from '../../utils/format.js';
+import { resolvePluginName, resolvePluginVersion, resolvePluginType } from '../../utils/plugin-helpers.js';
+
+export default class PluginList extends Command {
+  static override description = 'List plugins defined in the configuration';
+
+  static override aliases = ['plugin ls'];
+
+  static override args = {
+    config: Args.string({ description: 'Configuration file path', required: false }),
+  };
+
+  static override flags = {
+    json: Flags.boolean({ description: 'Output as JSON' }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(PluginList);
+
+    try {
+      const { config } = await loadConfig(args.config);
+      const plugins: unknown[] = config.plugins || [];
+      const devPlugins: unknown[] = config.devPlugins || [];
+
+      if (flags.json) {
+        const data = {
+          plugins: plugins.map(p => ({
+            name: resolvePluginName(p),
+            version: resolvePluginVersion(p),
+            type: resolvePluginType(p),
+            dev: false,
+          })),
+          devPlugins: devPlugins.map(p => ({
+            name: resolvePluginName(p),
+            version: resolvePluginVersion(p),
+            type: resolvePluginType(p),
+            dev: true,
+          })),
+        };
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+
+      printHeader('Plugins');
+
+      if (plugins.length === 0 && devPlugins.length === 0) {
+        printInfo('No plugins configured');
+        console.log('');
+        console.log(chalk.dim('  Hint: Add plugins to your objectstack.config.ts'));
+        console.log(chalk.dim('  Or run: os plugin add <package-name>'));
+        console.log('');
+        return;
+      }
+
+      if (plugins.length > 0) {
+        console.log(chalk.bold(`\n  Plugins (${plugins.length}):`));
+        for (const plugin of plugins) {
+          const name = resolvePluginName(plugin);
+          const version = resolvePluginVersion(plugin);
+          const type = resolvePluginType(plugin);
+          console.log(
+            `    ${chalk.cyan('●')} ${chalk.white(name)}` +
+            (version !== '-' ? chalk.dim(` v${version}`) : '') +
+            (type !== 'standard' ? chalk.dim(` [${type}]`) : '')
+          );
+        }
+      }
+
+      if (devPlugins.length > 0) {
+        console.log(chalk.bold(`\n  Dev Plugins (${devPlugins.length}):`));
+        for (const plugin of devPlugins) {
+          const name = resolvePluginName(plugin);
+          const version = resolvePluginVersion(plugin);
+          console.log(
+            `    ${chalk.yellow('●')} ${chalk.white(name)}` +
+            (version !== '-' ? chalk.dim(` v${version}`) : '') +
+            chalk.dim(' [dev]')
+          );
+        }
+      }
+
+      console.log('');
+    } catch (error: any) {
+      printError(error.message || String(error));
+      this.exit(1);
+    }
+  }
+}

package/src/commands/plugin/remove.ts

@@ -0,0 +1,97 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { Args, Command, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+import { resolveConfigPath } from '../../utils/config.js';
+import { printHeader, printSuccess, printError } from '../../utils/format.js';
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Remove a plugin reference from objectstack.config.ts.
+ *
+ * Removes matching import line and the entry from the plugins array.
+ */
+function removePluginFromConfig(configPath: string, pluginName: string): void {
+  let content = fs.readFileSync(configPath, 'utf-8');
+
+  // Remove the import line that references this plugin (exact package name match)
+  const importRegex = new RegExp(`^import .+['"]${escapeRegex(pluginName)}['"]\\s*;?\\s*$\\n?`, 'gm');
+  const hadImport = importRegex.test(content);
+  // Reset regex lastIndex after test()
+  importRegex.lastIndex = 0;
+  content = content.replace(importRegex, '');
+
+  // Also try to remove by a derived variable name
+  const shortName = pluginName
+    .replace(/^@[^/]+\//, '')
+    .replace(/^plugin-/, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+  const varName = shortName.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase()) + 'Plugin';
+
+  // Remove import by variable name if it wasn't caught above
+  if (!hadImport) {
+    const varImportRegex = new RegExp(`^import .* ${escapeRegex(varName)} .+$\\n?`, 'gm');
+    content = content.replace(varImportRegex, '');
+  }
+
+  // Remove the entry from the plugins array
+  // Match: varName, or 'package-name', or "package-name"
+  const entryPatterns = [
+    new RegExp(`\\s*${escapeRegex(varName)},?\\n?`, 'g'),
+    new RegExp(`\\s*['"]${escapeRegex(pluginName)}['"],?\\n?`, 'g'),
+  ];
+
+  for (const pattern of entryPatterns) {
+    content = content.replace(pattern, '\n');
+  }
+
+  // Clean up empty plugins array: plugins: [\n  ],
+  content = content.replace(/plugins\s*:\s*\[\s*\],?\n?/g, '');
+
+  fs.writeFileSync(configPath, content);
+}
+
+export { removePluginFromConfig };
+
+export default class PluginRemove extends Command {
+  static override description = 'Remove a plugin from objectstack.config.ts';
+
+  static override aliases = ['plugin rm'];
+
+  static override args = {
+    name: Args.string({ description: 'Plugin name or package name to remove', required: true }),
+  };
+
+  static override flags = {
+    config: Flags.string({ char: 'c', description: 'Configuration file path' }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(PluginRemove);
+
+    try {
+      const configPath = resolveConfigPath(flags.config);
+
+      printHeader('Remove Plugin');
+      console.log(`  ${chalk.dim('Plugin:')} ${chalk.white(args.name)}`);
+      console.log(`  ${chalk.dim('Config:')} ${chalk.white(path.relative(process.cwd(), configPath))}`);
+      console.log('');
+
+      removePluginFromConfig(configPath, args.name);
+      printSuccess(`Removed ${chalk.cyan(args.name)} from config`);
+
+      console.log('');
+      console.log(chalk.dim('  Tip: Run `pnpm remove ' + args.name + '` to uninstall the package'));
+      console.log('');
+    } catch (error: any) {
+      printError(error.message || String(error));
+      this.exit(1);
+    }
+  }
+}

package/src/commands/serve.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 path from 'path';
 import fs from 'fs';
 import net from 'net';
@@ -48,15 +48,24 @@ const getAvailablePort = async (startPort: number): Promise<number> => {
   return port;
 };
 
-export const serveCommand = new Command('serve')
-  .description('Start ObjectStack server with plugins from configuration')
-  .argument('[config]', 'Configuration file path', 'objectstack.config.ts')
-  .option('-p, --port <port>', 'Server port', '3000')
-  .option('--dev', 'Run in development mode (load devPlugins)')
-  .option('--ui', 'Enable Studio UI at /_studio/ (default: true in dev mode)')
-  .option('--no-server', 'Skip starting HTTP server plugin')
-  .action(async (configPath, options) => {
-    let port = parseInt(options.port);
+export default class Serve extends Command {
+  static override description = 'Start ObjectStack server with plugins from configuration';
+
+  static override args = {
+    config: Args.string({ description: 'Configuration file path', required: false, default: 'objectstack.config.ts' }),
+  };
+
+  static override flags = {
+    port: Flags.string({ char: 'p', description: 'Server port', default: '3000' }),
+    dev: Flags.boolean({ description: 'Run in development mode (load devPlugins)' }),
+    ui: Flags.boolean({ description: 'Enable Studio UI at /_studio/ (default: true in dev mode)' }),
+    server: Flags.boolean({ description: 'Start HTTP server plugin', default: true, allowNo: true }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(Serve);
+
+    let port = parseInt(flags.port);
     try {
       const availablePort = await getAvailablePort(port);
       if (availablePort !== port) {
@@ -66,15 +75,15 @@ export const serveCommand = new Command('serve')
       // Ignore error and try with original port
     }
 
-    const isDev = options.dev || process.env.NODE_ENV === 'development';
+    const isDev = flags.dev || process.env.NODE_ENV === 'development';
 
-    const absolutePath = path.resolve(process.cwd(), configPath);
+    const absolutePath = path.resolve(process.cwd(), args.config!);
     const relativeConfig = path.relative(process.cwd(), absolutePath);
     
     if (!fs.existsSync(absolutePath)) {
       printError(`Configuration file not found: ${absolutePath}`);
       console.log(chalk.dim('  Hint: Run `objectstack init` to create a new project'));
-      process.exit(1);
+      this.exit(1);
     }
 
     // Quiet loading — only show a single spinner line
@@ -106,7 +115,7 @@ export const serveCommand = new Command('serve')
       console.debug = originalConsoleDebug;
     };
 
-    const portShifted = parseInt(options.port) !== port;
+    const portShifted = parseInt(flags.port) !== port;
 
     try {
       // ── Suppress ALL runtime noise during boot ────────────────────
@@ -131,7 +140,7 @@ export const serveCommand = new Command('serve')
       const config = mod.default || mod;
 
       if (!config) {
-        throw new Error(`No default export found in ${configPath}`);
+        throw new Error(`No default export found in ${args.config}`);
       }
 
       // Import ObjectStack runtime
@@ -151,7 +160,7 @@ export const serveCommand = new Command('serve')
       let plugins = config.plugins || [];
 
       // Merge devPlugins if in dev mode
-      if (options.dev && config.devPlugins) {
+      if (flags.dev && config.devPlugins) {
         plugins = [...plugins, ...config.devPlugins];
       }
 
@@ -228,7 +237,7 @@ export const serveCommand = new Command('serve')
       }
 
       // Add HTTP server plugin if not disabled
-      if (options.server !== false) {
+      if (flags.server) {
         try {
           const { HonoServerPlugin } = await import('@objectstack/plugin-hono-server');
           const serverPlugin = new HonoServerPlugin({ port });
@@ -260,7 +269,7 @@ export const serveCommand = new Command('serve')
       // ── Studio UI ─────────────────────────────────────────────────
       // In dev mode, Studio UI is enabled by default (use --no-ui to disable).
       // Always serves the pre-built dist/ — no Vite dev server, no extra port.
-      const enableUI = options.ui ?? isDev;
+      const enableUI = flags.ui || isDev;
 
       if (enableUI) {
         const studioPath = resolveStudioPath();
@@ -306,6 +315,7 @@ export const serveCommand = new Command('serve')
       console.log('');
       printError(error.message || String(error));
       if (process.env.DEBUG) console.error(chalk.dim(error.stack));
-      process.exit(1);
+      this.exit(1);
     }
-  });
+  }
+}

package/src/commands/studio.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 { spawn } from 'child_process';
 import { printHeader, printKV, printStep } from '../utils/format.js';
@@ -12,11 +12,20 @@ import { printHeader, printKV, printStep } from '../utils/format.js';
  * Starts the ObjectStack server in development mode with the Studio
  * UI available at http://localhost:<port>/_studio/
  */
-export const studioCommand = new Command('studio')
-  .description('Launch Studio UI with development server')
-  .argument('[config]', 'Configuration file path', 'objectstack.config.ts')
-  .option('-p, --port <port>', 'Server port', '3000')
-  .action(async (configPath, options) => {
+export default class Studio extends Command {
+  static override description = 'Launch Studio UI with development server';
+
+  static override args = {
+    config: Args.string({ description: 'Configuration file path', required: false, default: 'objectstack.config.ts' }),
+  };
+
+  static override flags = {
+    port: Flags.string({ char: 'p', description: 'Server port', default: '3000' }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(Studio);
+
     printHeader('Studio');
     printKV('Mode', 'dev + ui', '🎨');
     printStep('Delegating to serve --dev --ui …');
@@ -24,19 +33,20 @@ export const studioCommand = new Command('studio')
 
     // Delegate to the serve command with --dev --ui flags
     const binPath = process.argv[1];
-    const args = [
+    const spawnArgs = [
       binPath,
       'serve',
-      configPath,
+      args.config!,
       '--dev',
       '--ui',
-      '--port', options.port,
+      '--port', flags.port,
     ];
 
-    const child = spawn(process.execPath, args, {
+    const child = spawn(process.execPath, spawnArgs, {
       stdio: 'inherit',
       env: { ...process.env, NODE_ENV: 'development' },
     });
 
     child.on('exit', (code) => process.exit(code ?? 0));
-  });
+  }
+}

package/src/commands/test.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 path from 'path';
 import fs from 'fs';
@@ -52,18 +52,28 @@ function resolveGlob(pattern: string): string[] {
     .filter(fullPath => fs.statSync(fullPath).isFile());
 }
 
-export const testCommand = new Command('test')
-  .description('Run Quality Protocol test scenarios against a running server')
-  .argument('[files]', 'Glob pattern for test files (e.g. "qa/*.test.json")', 'qa/*.test.json')
-  .option('--url <url>', 'Target base URL', 'http://localhost:3000')
-  .option('--token <token>', 'Authentication token')
-  .action(async (filesPattern, options) => {
+export default class Test extends Command {
+  static override description = 'Run Quality Protocol test scenarios against a running server';
+
+  static override args = {
+    files: Args.string({ description: 'Glob pattern for test files (e.g. "qa/*.test.json")', required: false, default: 'qa/*.test.json' }),
+  };
+
+  static override flags = {
+    url: Flags.string({ description: 'Target base URL', default: 'http://localhost:3000' }),
+    token: Flags.string({ description: 'Authentication token' }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(Test);
+    const filesPattern = args.files;
+
     console.log(chalk.bold(`\n🧪 ObjectStack Quality Protocol Runner`));
     console.log(chalk.dim(`-------------------------------------`));
-    console.log(`Target: ${chalk.blue(options.url)}`);
+    console.log(`Target: ${chalk.blue(flags.url)}`);
     
     // 1. Setup Runner
-    const adapter = new CoreQA.HttpTestAdapter(options.url, options.token);
+    const adapter = new CoreQA.HttpTestAdapter(flags.url, flags.token);
     const runner = new CoreQA.TestRunner(adapter);
 
     // 2. Find test files using glob-style pattern matching
@@ -121,4 +131,5 @@ export const testCommand = new Command('test')
         console.log(chalk.green(`SUCCESS: All ${totalPassed} scenarios passed.`));
         process.exit(0);
     }
-  });
+  }
+}