@objectstack/cli 2.0.6 → 2.0.7

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/cli@2.0.6 build /home/runner/work/spec/spec/packages/cli
+> @objectstack/cli@2.0.7 build /home/runner/work/spec/spec/packages/cli
 > tsup
 
 CLI Building entry: src/bin.ts
@@ -15,10 +15,10 @@
 ESM Build start
 CLI Cleaning output folder
 ESM Build start
-ESM dist/index.js 58.94 KB
-ESM ⚡️ Build success in 158ms
-ESM dist/bin.js 61.55 KB
-ESM ⚡️ Build success in 186ms
+ESM dist/index.js 71.41 KB
+ESM ⚡️ Build success in 166ms
+ESM dist/bin.js 74.36 KB
+ESM ⚡️ Build success in 178ms
 DTS Build start
-DTS ⚡️ Build success in 7538ms
-DTS dist/index.d.ts 2.93 KB
+DTS ⚡️ Build success in 9654ms
+DTS dist/index.d.ts 3.42 KB

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @objectstack/cli
 
+## 2.0.7
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectstack/spec@2.0.7
+  - @objectstack/core@2.0.7
+  - @objectstack/objectql@2.0.7
+  - @objectstack/driver-memory@2.0.7
+  - @objectstack/plugin-hono-server@2.0.7
+  - @objectstack/rest@2.0.7
+  - @objectstack/runtime@2.0.7
+
 ## 2.0.6
 
 ### Patch Changes

package/README.md

@@ -58,6 +58,15 @@ os compile
 
 Available generate types: `object`, `view`, `action`, `flow`, `agent`, `dashboard`, `app`
 
+### Plugin Management
+
+| Command | Description |
+|---------|-------------|
+| `os plugin list [config]` | List plugins defined in configuration (alias: `os plugin ls`) |
+| `os plugin info <name> [config]` | Show detailed plugin information |
+| `os plugin add <package>` | Add a plugin import and entry to config |
+| `os plugin remove <name>` | Remove a plugin from config (alias: `os plugin rm`) |
+
 ### Quality
 
 | Command | Description |
@@ -118,6 +127,81 @@ export default defineStack({
 - `-d, --dir <directory>` — Override target directory
 - `--dry-run` — Preview without writing files
 
+### `os plugin list`
+
+- `--json` — Output as JSON
+
+### `os plugin add`
+
+- `-d, --dev` — Add as a dev-only plugin
+- `-c, --config <path>` — Configuration file path
+
+### `os plugin remove`
+
+- `-c, --config <path>` — Configuration file path
+
+## Plugin CLI Extensions
+
+Plugins can extend the CLI with custom commands via the `contributes.commands` manifest field. The CLI automatically discovers and loads these commands at startup.
+
+### How to Create a CLI Plugin
+
+**1. Declare commands in the plugin manifest:**
+
+```typescript
+export default defineStack({
+  manifest: {
+    id: 'com.acme.marketplace',
+    version: '1.0.0',
+    type: 'plugin',
+    name: 'Marketplace Plugin',
+    contributes: {
+      commands: [
+        {
+          name: 'marketplace',
+          description: 'Manage marketplace applications',
+          module: './dist/cli.js',
+        },
+      ],
+    },
+  },
+});
+```
+
+**2. Export Commander.js commands from the module:**
+
+```typescript
+// src/cli.ts
+import { Command } from 'commander';
+
+const marketplaceCommand = new Command('marketplace')
+  .description('Manage marketplace applications')
+  .addCommand(
+    new Command('search')
+      .argument('<query>')
+      .action(async (query) => { /* ... */ })
+  )
+  .addCommand(
+    new Command('install')
+      .argument('<app>')
+      .action(async (app) => { /* ... */ })
+  );
+
+// Named export (recommended)
+export const commands = [marketplaceCommand];
+// Also supports: export default Command | Command[]
+```
+
+**3. Register the plugin in the host project and use:**
+
+```bash
+os plugin add @acme/plugin-marketplace
+os marketplace search "crm"
+os marketplace install com.acme.crm
+```
+
+For a complete guide, see the [Plugin CLI Extensions](/docs/guides/plugins#cli-command-extensions) section in the Plugins guide.
+
 ### `os info`
 
 - `--json` — Output as JSON
@@ -133,9 +217,10 @@ os init                          # 1. Create project
 os generate object customer      # 2. Add a Customer object
 os generate object order         # 3. Add an Order object  
 os generate view customer        # 4. Add a list view
-os validate                      # 5. Validate everything
-os dev                           # 6. Start dev server
-os compile                       # 7. Build for production
+os plugin add @objectstack/plugin-auth  # 5. Add auth plugin
+os validate                      # 6. Validate everything
+os dev                           # 7. Start dev server
+os compile                       # 8. Build for production
 ```
 
 ## License

package/dist/bin.js

@@ -2,8 +2,8 @@
 
 // src/bin.ts
 import { createRequire as createRequire2 } from "module";
-import { Command as Command12 } from "commander";
-import chalk13 from "chalk";
+import { Command as Command13 } from "commander";
+import chalk15 from "chalk";
 
 // src/commands/compile.ts
 import { Command } from "commander";
@@ -69,10 +69,10 @@ function formatZodErrors(error) {
     console.log(chalk.bold.red(`
   ${section}:`));
     for (const issue of sectionIssues) {
-      const path11 = issue.path?.join(".") || "";
+      const path12 = issue.path?.join(".") || "";
       const code = issue.code || "";
       const msg = issue.message || "";
-      console.log(chalk.red(`    \u2717 ${path11}`));
+      console.log(chalk.red(`    \u2717 ${path12}`));
       console.log(chalk.dim(`      ${code}: ${msg}`));
       if (issue.expected) {
         console.log(chalk.dim(`      expected: ${chalk.green(issue.expected)}`));
@@ -1874,33 +1874,366 @@ var generateCommand = new Command11("generate").alias("g").description("Generate
   }
 });
 
+// src/commands/plugin.ts
+import { Command as Command12 } from "commander";
+import chalk13 from "chalk";
+import fs11 from "fs";
+import path11 from "path";
+function resolvePluginName(plugin) {
+  if (typeof plugin === "string") return plugin;
+  if (plugin && typeof plugin === "object") {
+    const p = plugin;
+    if (typeof p.name === "string") return p.name;
+    if (p.constructor && p.constructor.name !== "Object") return p.constructor.name;
+  }
+  return "unknown";
+}
+function resolvePluginVersion(plugin) {
+  if (plugin && typeof plugin === "object") {
+    const p = plugin;
+    if (typeof p.version === "string") return p.version;
+  }
+  return "-";
+}
+function resolvePluginType(plugin) {
+  if (plugin && typeof plugin === "object") {
+    const p = plugin;
+    if (typeof p.type === "string") return p.type;
+  }
+  return "standard";
+}
+function readConfigText(configPath) {
+  return fs11.readFileSync(configPath, "utf-8");
+}
+function addPluginToConfig(configPath, packageName) {
+  let content = readConfigText(configPath);
+  const shortName = packageName.replace(/^@[^/]+\//, "").replace(/^plugin-/, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  const varName = shortName.replace(/-([a-z])/g, (_, c) => c.toUpperCase()) + "Plugin";
+  const importLine = `import ${varName} from '${packageName}';
+`;
+  if (content.includes(packageName)) {
+    throw new Error(`Plugin '${packageName}' is already referenced in the config`);
+  }
+  const importRegex = /^import .+$/gm;
+  let lastImportEnd = 0;
+  let match;
+  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;
+  }
+  if (/plugins\s*:\s*\[/.test(content)) {
+    let replaced = false;
+    content = content.replace(
+      /(plugins\s*:\s*\[)/,
+      (match2) => {
+        if (replaced) return match2;
+        replaced = true;
+        return `${match2}
+    ${varName},`;
+      }
+    );
+  } else {
+    content = content.replace(
+      /(defineStack\(\{[\s\S]*?)(}\s*\))/,
+      `$1  plugins: [
+    ${varName},
+  ],
+$2`
+    );
+  }
+  fs11.writeFileSync(configPath, content);
+}
+function removePluginFromConfig(configPath, pluginName) {
+  let content = readConfigText(configPath);
+  const importRegex = new RegExp(`^import .+['"]${escapeRegex(pluginName)}['"]\\s*;?\\s*$\\n?`, "gm");
+  const hadImport = importRegex.test(content);
+  importRegex.lastIndex = 0;
+  content = content.replace(importRegex, "");
+  const shortName = pluginName.replace(/^@[^/]+\//, "").replace(/^plugin-/, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  const varName = shortName.replace(/-([a-z])/g, (_, c) => c.toUpperCase()) + "Plugin";
+  if (!hadImport) {
+    const varImportRegex = new RegExp(`^import .* ${escapeRegex(varName)} .+$\\n?`, "gm");
+    content = content.replace(varImportRegex, "");
+  }
+  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");
+  }
+  content = content.replace(/plugins\s*:\s*\[\s*\],?\n?/g, "");
+  fs11.writeFileSync(configPath, content);
+}
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+var listCommand = new Command12("list").alias("ls").description("List plugins defined in the configuration").argument("[config]", "Configuration file path").option("--json", "Output as JSON").action(async (configSource, options) => {
+  try {
+    const { config } = await loadConfig(configSource);
+    const plugins = config.plugins || [];
+    const devPlugins = 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(chalk13.dim("  Hint: Add plugins to your objectstack.config.ts"));
+      console.log(chalk13.dim("  Or run: os plugin add <package-name>"));
+      console.log("");
+      return;
+    }
+    if (plugins.length > 0) {
+      console.log(chalk13.bold(`
+  Plugins (${plugins.length}):`));
+      for (const plugin of plugins) {
+        const name = resolvePluginName(plugin);
+        const version = resolvePluginVersion(plugin);
+        const type = resolvePluginType(plugin);
+        console.log(
+          `    ${chalk13.cyan("\u25CF")} ${chalk13.white(name)}` + (version !== "-" ? chalk13.dim(` v${version}`) : "") + (type !== "standard" ? chalk13.dim(` [${type}]`) : "")
+        );
+      }
+    }
+    if (devPlugins.length > 0) {
+      console.log(chalk13.bold(`
+  Dev Plugins (${devPlugins.length}):`));
+      for (const plugin of devPlugins) {
+        const name = resolvePluginName(plugin);
+        const version = resolvePluginVersion(plugin);
+        console.log(
+          `    ${chalk13.yellow("\u25CF")} ${chalk13.white(name)}` + (version !== "-" ? chalk13.dim(` v${version}`) : "") + chalk13.dim(" [dev]")
+        );
+      }
+    }
+    console.log("");
+  } catch (error) {
+    printError(error.message || String(error));
+    process.exit(1);
+  }
+});
+var infoSubCommand = new Command12("info").description("Show detailed information about a plugin").argument("<name>", "Plugin name or package name").argument("[config]", "Configuration file path").action(async (name, configSource) => {
+  try {
+    const { config } = await loadConfig(configSource);
+    const allPlugins = [
+      ...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(chalk13.dim("  Available plugins:"));
+      for (const p of allPlugins) {
+        console.log(chalk13.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;
+      if (typeof p.description === "string") {
+        printKV("Description", p.description);
+      }
+      if (Array.isArray(p.dependencies) && p.dependencies.length > 0) {
+        printKV("Dependencies", p.dependencies.join(", "));
+      }
+      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) {
+    printError(error.message || String(error));
+    process.exit(1);
+  }
+});
+var addCommand = new Command12("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, options) => {
+  try {
+    const configPath = resolveConfigPath(options?.config);
+    printHeader("Add Plugin");
+    console.log(`  ${chalk13.dim("Package:")} ${chalk13.white(packageName)}`);
+    console.log(`  ${chalk13.dim("Config:")}  ${chalk13.white(path11.relative(process.cwd(), configPath))}`);
+    console.log("");
+    addPluginToConfig(configPath, packageName);
+    printSuccess(`Added ${chalk13.cyan(packageName)} to config`);
+    console.log("");
+    console.log(chalk13.dim("  Next steps:"));
+    console.log(chalk13.dim(`  1. Install the package: pnpm add ${packageName}`));
+    console.log(chalk13.dim("  2. Run: os validate"));
+    console.log("");
+  } catch (error) {
+    printError(error.message || String(error));
+    process.exit(1);
+  }
+});
+var removeCommand = new Command12("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, options) => {
+  try {
+    const configPath = resolveConfigPath(options?.config);
+    printHeader("Remove Plugin");
+    console.log(`  ${chalk13.dim("Plugin:")} ${chalk13.white(pluginName)}`);
+    console.log(`  ${chalk13.dim("Config:")} ${chalk13.white(path11.relative(process.cwd(), configPath))}`);
+    console.log("");
+    removePluginFromConfig(configPath, pluginName);
+    printSuccess(`Removed ${chalk13.cyan(pluginName)} from config`);
+    console.log("");
+    console.log(chalk13.dim("  Tip: Run `pnpm remove " + pluginName + "` to uninstall the package"));
+    console.log("");
+  } catch (error) {
+    printError(error.message || String(error));
+    process.exit(1);
+  }
+});
+var pluginCommand = new Command12("plugin").description("Manage plugins (list, info, add, remove)").addCommand(listCommand).addCommand(infoSubCommand).addCommand(addCommand).addCommand(removeCommand);
+
+// src/utils/plugin-commands.ts
+import chalk14 from "chalk";
+async function loadPluginCommands(program2) {
+  let config;
+  try {
+    const loaded = await loadConfig();
+    config = loaded.config;
+  } catch {
+    return;
+  }
+  const plugins = [
+    ...config.plugins || [],
+    ...config.devPlugins || []
+  ];
+  const contributions = [];
+  for (const plugin of plugins) {
+    if (!plugin || typeof plugin !== "object") continue;
+    const p = plugin;
+    const manifest = p.manifest;
+    const contributes = manifest?.contributes ?? p.contributes;
+    if (!contributes) continue;
+    const commands = contributes.commands;
+    if (!Array.isArray(commands)) continue;
+    const pluginName = resolvePluginName2(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 : void 0,
+        module: typeof cmd.module === "string" ? cmd.module : void 0,
+        pluginName
+      });
+    }
+  }
+  if (contributions.length === 0) return;
+  for (const contribution of contributions) {
+    try {
+      const commands = await importPluginCommands(contribution);
+      for (const cmd of commands) {
+        program2.addCommand(cmd);
+      }
+    } catch (error) {
+      if (process.env.DEBUG) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(
+          chalk14.yellow(`  \u26A0 Failed to load CLI command '${contribution.name}' from plugin '${contribution.pluginName}': ${message}`)
+        );
+      }
+    }
+  }
+}
+async function importPluginCommands(contribution) {
+  const moduleId = contribution.module ? `${contribution.pluginName}/${contribution.module.replace(/^\.\//, "")}` : contribution.pluginName;
+  const mod = await import(moduleId);
+  if (Array.isArray(mod.commands)) {
+    return mod.commands.filter(isCommandInstance);
+  }
+  const defaultExport = mod.default;
+  if (defaultExport) {
+    if (Array.isArray(defaultExport)) {
+      return defaultExport.filter(isCommandInstance);
+    }
+    if (isCommandInstance(defaultExport)) {
+      return [defaultExport];
+    }
+  }
+  const commands = [];
+  for (const key of Object.keys(mod)) {
+    if (isCommandInstance(mod[key])) {
+      commands.push(mod[key]);
+    }
+  }
+  return commands;
+}
+function isCommandInstance(value) {
+  if (value === null || typeof value !== "object") return false;
+  const obj = value;
+  return typeof obj.name === "function" && typeof obj.description === "function" && typeof obj.action === "function" && typeof obj.parse === "function";
+}
+function resolvePluginName2(plugin) {
+  if (typeof plugin.name === "string") return plugin.name;
+  const manifest = plugin.manifest;
+  if (manifest && typeof manifest.name === "string") return manifest.name;
+  if (plugin.constructor && plugin.constructor.name !== "Object") return plugin.constructor.name;
+  return "unknown";
+}
+
 // src/bin.ts
 var require2 = createRequire2(import.meta.url);
 var pkg = require2("../package.json");
 process.on("unhandledRejection", (err) => {
-  console.error(chalk13.red(`
+  console.error(chalk15.red(`
   \u2717 Unhandled error: ${err?.message || err}`));
   if (err?.stack && process.env.DEBUG) {
-    console.error(chalk13.dim(err.stack));
+    console.error(chalk15.dim(err.stack));
   }
   process.exit(1);
 });
-var program = new Command12();
+var program = new Command13();
 program.name("objectstack").description("ObjectStack CLI \u2014 Build metadata-driven apps with the ObjectStack Protocol").version(pkg.version, "-v, --version").configureHelp({
   sortSubcommands: false
 }).addHelpText("before", `
-${chalk13.bold.cyan("\u25C6 ObjectStack CLI")} ${chalk13.dim(`v${pkg.version}`)}
+${chalk15.bold.cyan("\u25C6 ObjectStack CLI")} ${chalk15.dim(`v${pkg.version}`)}
 `).addHelpText("after", `
-${chalk13.bold("Workflow:")}
-  ${chalk13.dim("$")} os init                      ${chalk13.dim("# Create a new project")}
-  ${chalk13.dim("$")} os generate object task       ${chalk13.dim("# Add metadata")}
-  ${chalk13.dim("$")} os validate                   ${chalk13.dim("# Check configuration")}
-  ${chalk13.dim("$")} os dev                        ${chalk13.dim("# Start dev server")}
-  ${chalk13.dim("$")} os studio                     ${chalk13.dim("# Dev server + Studio UI")}
-  ${chalk13.dim("$")} os compile                    ${chalk13.dim("# Build for production")}
-
-${chalk13.dim("Aliases: objectstack | os")}
-${chalk13.dim("Docs: https://objectstack.dev")}
+${chalk15.bold("Workflow:")}
+  ${chalk15.dim("$")} os init                      ${chalk15.dim("# Create a new project")}
+  ${chalk15.dim("$")} os generate object task       ${chalk15.dim("# Add metadata")}
+  ${chalk15.dim("$")} os plugin add <package>       ${chalk15.dim("# Add a plugin")}
+  ${chalk15.dim("$")} os validate                   ${chalk15.dim("# Check configuration")}
+  ${chalk15.dim("$")} os dev                        ${chalk15.dim("# Start dev server")}
+  ${chalk15.dim("$")} os studio                     ${chalk15.dim("# Dev server + Studio UI")}
+  ${chalk15.dim("$")} os compile                    ${chalk15.dim("# Build for production")}
+
+${chalk15.dim("Aliases: objectstack | os")}
+${chalk15.dim("Docs: https://objectstack.dev")}
 `);
 program.addCommand(initCommand);
 program.addCommand(devCommand);
@@ -1911,6 +2244,15 @@ program.addCommand(validateCommand);
 program.addCommand(infoCommand);
 program.addCommand(generateCommand);
 program.addCommand(createCommand);
+program.addCommand(pluginCommand);
 program.addCommand(testCommand);
 program.addCommand(doctorCommand);
-program.parse(process.argv);
+loadPluginCommands(program).then(() => {
+  program.parse(process.argv);
+}).catch((err) => {
+  if (process.env.DEBUG) {
+    console.error(chalk15.yellow(`
+  \u26A0 Plugin command loading failed: ${err?.message || err}`));
+  }
+  program.parse(process.argv);
+});

package/dist/index.d.ts

@@ -90,6 +90,8 @@ declare const templates: {
 };
 declare const createCommand: Command;
 
+declare const pluginCommand: Command;
+
 declare const devCommand: Command;
 
 declare const serveCommand: Command;
@@ -98,4 +100,15 @@ declare const testCommand: Command;
 
 declare const doctorCommand: Command;
 
-export { compileCommand, createCommand, devCommand, doctorCommand, generateCommand, infoCommand, initCommand, serveCommand, templates, testCommand, validateCommand };
+/**
+ * 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
+ */
+declare function loadPluginCommands(program: Command): Promise<void>;
+
+export { compileCommand, createCommand, devCommand, doctorCommand, generateCommand, infoCommand, initCommand, loadPluginCommands, pluginCommand, serveCommand, templates, testCommand, validateCommand };