@objectstack/cli 2.0.6 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/cli",
-  "version": "2.0.6",
+  "version": "3.0.0",
   "description": "Command Line Interface for ObjectStack Protocol",
   "main": "dist/index.js",
   "bin": {
@@ -22,16 +22,16 @@
     "commander": "^14.0.3",
     "tsx": "^4.7.1",
     "zod": "^4.3.6",
-    "@objectstack/core": "2.0.6",
-    "@objectstack/driver-memory": "^2.0.6",
-    "@objectstack/objectql": "^2.0.6",
-    "@objectstack/plugin-hono-server": "2.0.6",
-    "@objectstack/rest": "2.0.6",
-    "@objectstack/runtime": "^2.0.6",
-    "@objectstack/spec": "2.0.6"
+    "@objectstack/core": "3.0.0",
+    "@objectstack/driver-memory": "^3.0.0",
+    "@objectstack/objectql": "^3.0.0",
+    "@objectstack/plugin-hono-server": "3.0.0",
+    "@objectstack/rest": "3.0.0",
+    "@objectstack/runtime": "^3.0.0",
+    "@objectstack/spec": "3.0.0"
   },
   "peerDependencies": {
-    "@objectstack/core": "2.0.6"
+    "@objectstack/core": "3.0.0"
   },
   "devDependencies": {
     "@types/node": "^25.2.2",

package/src/bin.ts

@@ -16,6 +16,8 @@ import { validateCommand } from './commands/validate.js';
 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');
@@ -46,6 +48,7 @@ ${chalk.bold.cyan('◆ ObjectStack CLI')} ${chalk.dim(`v${pkg.version}`)}
 ${chalk.bold('Workflow:')}
   ${chalk.dim('$')} os init                      ${chalk.dim('# Create a new project')}
   ${chalk.dim('$')} os generate object task       ${chalk.dim('# Add metadata')}
+  ${chalk.dim('$')} os plugin add <package>       ${chalk.dim('# Add a plugin')}
   ${chalk.dim('$')} os validate                   ${chalk.dim('# Check configuration')}
   ${chalk.dim('$')} os dev                        ${chalk.dim('# Start dev server')}
   ${chalk.dim('$')} os studio                     ${chalk.dim('# Dev server + Studio UI')}
@@ -70,8 +73,22 @@ program.addCommand(infoCommand);
 program.addCommand(generateCommand);
 program.addCommand(createCommand);
 
+// ── Plugin Management ──
+program.addCommand(pluginCommand);
+
 // ── Quality ──
 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);
+});

package/src/commands/generate.ts

@@ -204,11 +204,110 @@ function toSnakeCase(str: string): string {
   return str.replace(/[-]/g, '_').replace(/[A-Z]/g, c => `_${c.toLowerCase()}`).replace(/^_/, '');
 }
 
+// ─── Field Type Mapping ─────────────────────────────────────────────
+
+const FIELD_TYPE_MAP: Record<string, string> = {
+  text: 'string',
+  textarea: 'string',
+  richtext: 'string',
+  html: 'string',
+  markdown: 'string',
+  number: 'number',
+  integer: 'number',
+  currency: 'number',
+  percent: 'number',
+  boolean: 'boolean',
+  date: 'string',
+  datetime: 'string',
+  time: 'string',
+  email: 'string',
+  phone: 'string',
+  url: 'string',
+  select: 'string',
+  multiselect: 'string[]',
+  lookup: 'string',
+  master_detail: 'string',
+  formula: 'unknown',
+  autonumber: 'string',
+  json: 'Record<string, unknown>',
+  file: 'string',
+  image: 'string',
+  password: 'string',
+  slug: 'string',
+  uuid: 'string',
+  ip_address: 'string',
+  color: 'string',
+  rating: 'number',
+  geo_point: '{ lat: number; lng: number }',
+  vector: 'number[]',
+  encrypted: 'string',
+};
+
+function fieldTypeToTs(fieldType: string, multiple?: boolean): string {
+  const base = FIELD_TYPE_MAP[fieldType] || 'unknown';
+  return multiple ? `${base}[]` : base;
+}
+
+function generateTypesFromConfig(config: Record<string, unknown>): string {
+  const lines: string[] = [
+    '// Auto-generated by ObjectStack CLI — do not edit manually',
+    `// Generated at ${new Date().toISOString()}`,
+    '',
+    "import type { Data } from '@objectstack/spec';",
+    '',
+  ];
+
+  // Extract objects from config (supports both top-level and nested)
+  const objects: Record<string, unknown>[] = [];
+  const rawObjects = (config as any).objects ?? (config as any).data?.objects ?? {};
+
+  if (Array.isArray(rawObjects)) {
+    objects.push(...rawObjects);
+  } else if (typeof rawObjects === 'object') {
+    for (const val of Object.values(rawObjects)) {
+      if (val && typeof val === 'object') objects.push(val as Record<string, unknown>);
+    }
+  }
+
+  if (objects.length === 0) {
+    lines.push('// No objects found in configuration');
+    return lines.join('\n') + '\n';
+  }
+
+  for (const obj of objects) {
+    const name = String(obj.name || 'unknown');
+    const typeName = name
+      .split('_')
+      .map((w: string) => w.charAt(0).toUpperCase() + w.slice(1))
+      .join('');
+    const fields = (obj.fields ?? {}) as Record<string, Record<string, unknown>>;
+
+    lines.push(`/** ${String(obj.label || typeName)} record type */`);
+    lines.push(`export interface ${typeName}Record {`);
+    lines.push('  id: string;');
+
+    for (const [fieldName, fieldDef] of Object.entries(fields)) {
+      const fType = String(fieldDef.type || 'text');
+      const tsType = fieldTypeToTs(fType, !!fieldDef.multiple);
+      const required = fieldDef.required ? '' : '?';
+      if (fieldDef.label) {
+        lines.push(`  /** ${fieldDef.label} */`);
+      }
+      lines.push(`  ${fieldName}${required}: ${tsType};`);
+    }
+
+    lines.push('}');
+    lines.push('');
+  }
+
+  return lines.join('\n') + '\n';
+}
+
 // ─── Command ────────────────────────────────────────────────────────
 
-export const generateCommand = new Command('generate')
-  .alias('g')
-  .description('Generate metadata files (object, view, action, flow, agent, dashboard, app)')
+const generateMetadataCommand = new Command('metadata')
+  .alias('m')
+  .description('Generate metadata scaffold (object, view, action, flow, agent, dashboard, app)')
   .argument('<type>', 'Metadata type to generate')
   .argument('<name>', 'Name for the metadata (use kebab-case)')
   .option('-d, --dir <directory>', 'Target directory (overrides default)')
@@ -297,3 +396,82 @@ export const generateCommand = new Command('generate')
       process.exit(1);
     }
   });
+
+const generateTypesCommand = new Command('types')
+  .description('Generate TypeScript type definitions from ObjectStack configuration')
+  .argument('[config]', 'Configuration file path')
+  .option('-o, --output <file>', 'Output file path', 'src/types/objectstack.d.ts')
+  .option('--dry-run', 'Show what would be generated without writing files')
+  .action(async (configPath, options) => {
+    printHeader('Generate Types');
+
+    try {
+      const { loadConfig } = await import('../utils/config.js');
+      printInfo('Loading configuration...');
+      const { config, absolutePath } = await loadConfig(configPath);
+
+      console.log(`  ${chalk.dim('Config:')} ${chalk.white(absolutePath)}`);
+      console.log(`  ${chalk.dim('Output:')} ${chalk.white(options.output)}`);
+      console.log('');
+
+      const content = generateTypesFromConfig(config as Record<string, unknown>);
+
+      if (options.dryRun) {
+        printInfo('Dry run — no files written');
+        console.log('');
+        for (const line of content.split('\n')) {
+          console.log(chalk.dim(`  ${line}`));
+        }
+        console.log('');
+        return;
+      }
+
+      const outPath = path.resolve(process.cwd(), options.output);
+      const outDir = path.dirname(outPath);
+      if (!fs.existsSync(outDir)) {
+        fs.mkdirSync(outDir, { recursive: true });
+      }
+      fs.writeFileSync(outPath, content);
+      printSuccess(`Generated types at ${options.output}`);
+      console.log('');
+
+    } catch (error: any) {
+      printError(error.message || String(error));
+      process.exit(1);
+    }
+  });
+
+export const generateCommand = new Command('generate')
+  .alias('g')
+  .description('Generate metadata files or TypeScript types')
+  .argument('[type]', 'Metadata type to generate (object, view, action, flow, agent, dashboard, app)')
+  .argument('[name]', 'Name for the metadata (use kebab-case)')
+  .option('-d, --dir <directory>', 'Target directory (overrides default)')
+  .option('--dry-run', 'Show what would be created without writing files')
+  .addCommand(generateTypesCommand)
+  .action(async (type: string | undefined, name: string | undefined, options) => {
+    if (!type) {
+      printHeader('Generate');
+      console.log(chalk.bold('  Sub-commands:'));
+      console.log(`    ${chalk.cyan('types'.padEnd(12))} Generate TypeScript type definitions from config`);
+      console.log('');
+      console.log(chalk.bold('  Metadata types:'));
+      for (const [key, gen] of Object.entries(GENERATORS)) {
+        console.log(`    ${chalk.cyan(key.padEnd(12))} ${chalk.dim(gen.description)}`);
+      }
+      console.log('');
+      console.log(chalk.dim('  Usage: objectstack generate <type> <name>'));
+      console.log(chalk.dim('  Usage: objectstack generate types [config]'));
+      return;
+    }
+
+    // Delegate to metadata command action
+    if (!name) {
+      printError('Missing required argument: <name>');
+      console.log(chalk.dim('  Usage: objectstack generate <type> <name>'));
+      process.exit(1);
+    }
+
+    // Execute metadata generation inline
+    await generateMetadataCommand.parseAsync([type, name, ...process.argv.slice(4)], { from: 'user' });
+  });

package/src/commands/plugin.ts

@@ -0,0 +1,372 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+import { loadConfig, resolveConfigPath } from '../utils/config.js';
+import { printHeader, printSuccess, printError, printInfo, printWarning, printKV } from '../utils/format.js';
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+/**
+ * Resolve plugin display name from a plugin entry.
+ * Plugins can be string package names, objects with `.name`, or class instances.
+ */
+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.
+ */
+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.
+ */
+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';
+}
+
+/**
+ * Read the raw text of the config file.
+ */
+function readConfigText(configPath: string): string {
+  return fs.readFileSync(configPath, 'utf-8');
+}
+
+/**
+ * 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 = readConfigText(configPath);
+
+  // 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);
+}
+
+/**
+ * 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 = readConfigText(configPath);
+
+  // 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);
+}
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// ─── Subcommands ────────────────────────────────────────────────────
+
+const listCommand = new Command('list')
+  .alias('ls')
+  .description('List plugins defined in the configuration')
+  .argument('[config]', 'Configuration file path')
+  .option('--json', 'Output as JSON')
+  .action(async (configSource?: string, options?: { json?: boolean }) => {
+    try {
+      const { config } = await loadConfig(configSource);
+      const plugins: unknown[] = config.plugins || [];
+      const devPlugins: unknown[] = config.devPlugins || [];
+
+      if (options?.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));
+      process.exit(1);
+    }
+  });
+
+const infoSubCommand = new Command('info')
+  .description('Show detailed information about a plugin')
+  .argument('<name>', 'Plugin name or package name')
+  .argument('[config]', 'Configuration file path')
+  .action(async (name: string, configSource?: string) => {
+    try {
+      const { config } = await loadConfig(configSource);
+      const allPlugins: unknown[] = [
+        ...(config.plugins || []),
+        ...(config.devPlugins || []),
+      ];
+
+      const found = allPlugins.find((p) => {
+        const pName = resolvePluginName(p);
+        return pName === name || pName.includes(name);
+      });
+
+      if (!found) {
+        printError(`Plugin '${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('');
+        process.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));
+      process.exit(1);
+    }
+  });
+
+const addCommand = new Command('add')
+  .description('Add a plugin to objectstack.config.ts')
+  .argument('<package>', 'Plugin package name (e.g. @objectstack/plugin-auth)')
+  .option('-d, --dev', 'Add as a dev-only plugin')
+  .option('-c, --config <path>', 'Configuration file path')
+  .action(async (packageName: string, options?: { dev?: boolean; config?: string }) => {
+    try {
+      const configPath = resolveConfigPath(options?.config);
+
+      printHeader('Add Plugin');
+      console.log(`  ${chalk.dim('Package:')} ${chalk.white(packageName)}`);
+      console.log(`  ${chalk.dim('Config:')}  ${chalk.white(path.relative(process.cwd(), configPath))}`);
+      console.log('');
+
+      addPluginToConfig(configPath, packageName);
+      printSuccess(`Added ${chalk.cyan(packageName)} to config`);
+
+      console.log('');
+      console.log(chalk.dim('  Next steps:'));
+      console.log(chalk.dim(`  1. Install the package: pnpm add ${packageName}`));
+      console.log(chalk.dim('  2. Run: os validate'));
+      console.log('');
+    } catch (error: any) {
+      printError(error.message || String(error));
+      process.exit(1);
+    }
+  });
+
+const removeCommand = new Command('remove')
+  .alias('rm')
+  .description('Remove a plugin from objectstack.config.ts')
+  .argument('<name>', 'Plugin name or package name to remove')
+  .option('-c, --config <path>', 'Configuration file path')
+  .action(async (pluginName: string, options?: { config?: string }) => {
+    try {
+      const configPath = resolveConfigPath(options?.config);
+
+      printHeader('Remove Plugin');
+      console.log(`  ${chalk.dim('Plugin:')} ${chalk.white(pluginName)}`);
+      console.log(`  ${chalk.dim('Config:')} ${chalk.white(path.relative(process.cwd(), configPath))}`);
+      console.log('');
+
+      removePluginFromConfig(configPath, pluginName);
+      printSuccess(`Removed ${chalk.cyan(pluginName)} from config`);
+
+      console.log('');
+      console.log(chalk.dim('  Tip: Run `pnpm remove ' + pluginName + '` to uninstall the package'));
+      console.log('');
+    } catch (error: any) {
+      printError(error.message || String(error));
+      process.exit(1);
+    }
+  });
+
+// ─── Main Plugin Command ────────────────────────────────────────────
+
+export const pluginCommand = new Command('plugin')
+  .description('Manage plugins (list, info, add, remove)')
+  .addCommand(listCommand)
+  .addCommand(infoSubCommand)
+  .addCommand(addCommand)
+  .addCommand(removeCommand);

package/src/index.ts

@@ -6,7 +6,9 @@ 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';