@jay-framework/jay-stack-cli 0.17.3 → 0.18.0

package/dist/index.js

@@ -7,18 +7,18 @@ import getPort from "get-port";
 import path from "path";
 import fs, { promises } from "fs";
 import YAML from "yaml";
-import { getLogger, createDevLogger, setDevLogger } from "@jay-framework/logger";
+import { getLogger, setDevLogger, createDevLogger } from "@jay-framework/logger";
 import { parseJayFile, JAY_IMPORT_RESOLVER, generateElementDefinitionFile, ContractTagType, parseContract, generateElementFile, generateServerElementFile, htmlElementTagNameMap } from "@jay-framework/compiler-jay-html";
 import { JAY_CONTRACT_EXTENSION, JAY_EXTENSION, resolvePluginManifest, LOCAL_PLUGIN_PATH, JayAtomicType, JayEnumType, loadPluginManifest, RuntimeMode, GenerateTarget } from "@jay-framework/compiler-shared";
-import { scanPlugins as scanPlugins$1, listContracts, materializeContracts } from "@jay-framework/stack-server-runtime";
+import { listContracts, materializeContracts, scanPlugins as scanPlugins$1 } from "@jay-framework/stack-server-runtime";
 import { listContracts as listContracts2, materializeContracts as materializeContracts2 } from "@jay-framework/stack-server-runtime";
 import { Command } from "commander";
 import chalk from "chalk";
+import path$1 from "node:path";
+import fs$1 from "node:fs/promises";
 import { createRequire } from "module";
 import { glob } from "glob";
 import { parse } from "node-html-parser";
-import path$1 from "node:path";
-import fs$1 from "node:fs/promises";
 import fsSync from "node:fs";
 import { fileURLToPath } from "node:url";
 const DEFAULT_CONFIG = {
@@ -2530,6 +2530,11 @@ async function startDevServer(options = {}) {
   routes.forEach((route) => {
     app.get(route.path, route.handler);
   });
+  service.attachRouteRegistrar((added) => {
+    added.forEach((route) => {
+      app.get(route.path, route.handler);
+    });
+  });
   generatePageDefinitionFiles(routes, jayOptions.tsConfigFilePath, process.cwd());
   httpServer.listen(devServerPort, () => {
     log.important(`🚀 Jay Stack dev server started successfully!`);
@@ -2583,6 +2588,175 @@ async function startDevServer(options = {}) {
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
 }
+async function initializeServicesForCli(projectRoot, viteServer) {
+  const path2 = await import("node:path");
+  const fs2 = await import("node:fs");
+  const {
+    runInitCallbacks,
+    getServiceRegistry,
+    discoverPluginsWithInit,
+    sortPluginsByDependencies,
+    executePluginServerInits
+  } = await import("@jay-framework/stack-server-runtime");
+  let initErrors = /* @__PURE__ */ new Map();
+  try {
+    const discoveredPlugins = await discoverPluginsWithInit({
+      projectRoot,
+      verbose: false
+    });
+    const pluginsWithInit = sortPluginsByDependencies(discoveredPlugins);
+    try {
+      initErrors = await executePluginServerInits(pluginsWithInit, viteServer, false);
+    } catch (error) {
+      getLogger().warn(chalk.yellow(`⚠️  Plugin initialization skipped: ${error.message}`));
+    }
+    const initPathTs = path2.join(projectRoot, "src", "init.ts");
+    const initPathJs = path2.join(projectRoot, "src", "init.js");
+    let initModule;
+    if (fs2.existsSync(initPathTs) && viteServer) {
+      initModule = await viteServer.ssrLoadModule(initPathTs);
+    } else if (fs2.existsSync(initPathJs)) {
+      initModule = await import(initPathJs);
+    }
+    if (initModule?.init?._serverInit) {
+      await initModule.init._serverInit();
+    }
+    await runInitCallbacks();
+  } catch (error) {
+    getLogger().warn(chalk.yellow(`⚠️  Service initialization failed: ${error.message}`));
+    getLogger().warn(chalk.gray("   Static contracts will still be listed."));
+  }
+  return { services: getServiceRegistry(), initErrors };
+}
+async function runDev(projectPath, options) {
+  const logLevel = options.quiet ? "silent" : options.verbose ? "verbose" : "info";
+  setDevLogger(createDevLogger(logLevel));
+  const testMode = options.testMode || options.timeout !== void 0;
+  await startDevServer({
+    projectPath: projectPath || process.cwd(),
+    testMode,
+    timeout: options.timeout,
+    logLevel
+  });
+}
+async function resolveProductionContext(projectPath, versionOverride) {
+  const resolvedPath = path$1.resolve(projectPath || process.cwd());
+  const jayConfigPath = path$1.join(resolvedPath, ".jay");
+  let pagesBase = "./src/pages";
+  try {
+    const jayConfig = YAML.parse(await fs$1.readFile(jayConfigPath, "utf-8"));
+    pagesBase = jayConfig?.devServer?.pagesBase || pagesBase;
+  } catch {
+  }
+  const version = versionOverride || await resolveVersionFromPackageJson(resolvedPath);
+  return {
+    resolvedPath,
+    pagesRoot: path$1.resolve(resolvedPath, pagesBase),
+    buildRoot: path$1.join(resolvedPath, "build"),
+    version,
+    tsConfigFilePath: path$1.join(resolvedPath, "tsconfig.json")
+  };
+}
+async function resolveVersionFromPackageJson(projectRoot) {
+  try {
+    const pkgJson = JSON.parse(
+      await fs$1.readFile(path$1.join(projectRoot, "package.json"), "utf-8")
+    );
+    if (pkgJson.version) {
+      return pkgJson.version;
+    }
+  } catch {
+  }
+  return "1";
+}
+function initLogger(verbose) {
+  const logLevel = verbose ? "verbose" : "info";
+  setDevLogger(createDevLogger(logLevel));
+}
+async function runBuild(projectPath, options) {
+  initLogger(options.verbose);
+  const ctx = await resolveProductionContext(projectPath, options.version);
+  const { buildVersion } = await import("@jay-framework/production-server");
+  await buildVersion({
+    version: ctx.version,
+    projectRoot: ctx.resolvedPath,
+    pagesRoot: ctx.pagesRoot,
+    buildRoot: ctx.buildRoot,
+    concurrency: 4,
+    tsConfigFilePath: ctx.tsConfigFilePath,
+    minify: options.minify
+  });
+}
+async function runServe(projectPath, options) {
+  initLogger(options.verbose);
+  const ctx = await resolveProductionContext(projectPath, options.version);
+  if (options.role === "renderer") {
+    const { startRendererServer } = await import("@jay-framework/production-server");
+    await startRendererServer({
+      buildRoot: ctx.buildRoot,
+      version: ctx.version,
+      port: parseInt(options.port, 10),
+      projectRoot: ctx.resolvedPath,
+      pagesRoot: ctx.pagesRoot,
+      tsConfigFilePath: ctx.tsConfigFilePath
+    });
+  } else {
+    const { startMainServer } = await import("@jay-framework/production-server");
+    await startMainServer({
+      buildRoot: ctx.buildRoot,
+      version: ctx.version,
+      port: parseInt(options.port, 10),
+      testMode: options.testMode,
+      publicBasePath: options.staticBaseUrl,
+      serveStatic: options.serveStatic
+    });
+  }
+}
+async function runRebuild(projectPath, options) {
+  initLogger(options.verbose);
+  const ctx = await resolveProductionContext(projectPath, options.version);
+  let params;
+  if (options.params) {
+    params = JSON.parse(options.params);
+  }
+  const { rebuild } = await import("@jay-framework/production-server");
+  let target;
+  if (options.contract) {
+    target = { mode: "contract", contractName: options.contract, params };
+  } else if (options.route) {
+    target = { mode: "route", routePattern: options.route, params };
+  } else if (options.url) {
+    target = { mode: "url", url: options.url };
+  } else {
+    getLogger().error(chalk.red("One of --contract, --route, or --url is required"));
+    process.exit(1);
+  }
+  const result = await rebuild({
+    projectRoot: ctx.resolvedPath,
+    pagesRoot: ctx.pagesRoot,
+    buildRoot: ctx.buildRoot,
+    version: ctx.version,
+    target,
+    tsConfigFilePath: ctx.tsConfigFilePath
+  });
+  if (result.errors.length > 0) {
+    for (const err of result.errors) {
+      getLogger().error(
+        chalk.red(`  Error: ${err.route} ${JSON.stringify(err.params)}: ${err.error}`)
+      );
+    }
+    process.exit(1);
+  }
+}
+const runProduction = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  initLogger,
+  resolveProductionContext,
+  resolveVersionFromPackageJson,
+  runBuild,
+  runRebuild,
+  runServe
+}, Symbol.toStringTag, { value: "Module" }));
 const s = createRequire(import.meta.url), e = s("typescript"), u = e;
 new Proxy(e, {
   get(t, r) {
@@ -3605,9 +3779,6 @@ const SKIP_ATTRS = /* @__PURE__ */ new Set([
   "if",
   "ref",
   "trackBy",
-  "slowForEach",
-  "jayIndex",
-  "jayTrackBy",
   "when-resolved",
   "when-loading",
   "when-rejected",
@@ -4260,95 +4431,369 @@ function printJayValidationResult(result, options) {
     }
   }
 }
-async function initializeServicesForCli(projectRoot, viteServer) {
-  const path2 = await import("node:path");
-  const fs2 = await import("node:fs");
-  const {
-    runInitCallbacks,
-    getServiceRegistry,
-    discoverPluginsWithInit,
-    sortPluginsByDependencies,
-    executePluginServerInits
-  } = await import("@jay-framework/stack-server-runtime");
-  let initErrors = /* @__PURE__ */ new Map();
-  try {
-    const discoveredPlugins = await discoverPluginsWithInit({
-      projectRoot,
-      verbose: false
-    });
-    const pluginsWithInit = sortPluginsByDependencies(discoveredPlugins);
-    try {
-      initErrors = await executePluginServerInits(pluginsWithInit, viteServer, false);
-    } catch (error) {
-      getLogger().warn(chalk.yellow(`⚠️  Plugin initialization skipped: ${error.message}`));
+async function runValidate(scanPath, options) {
+  const result = await validateJayFiles({
+    path: scanPath,
+    verbose: options.verbose,
+    json: options.json
+  });
+  printJayValidationResult(result, options);
+  if (!result.valid) {
+    process.exit(1);
+  }
+}
+async function runValidatePlugin(pluginPath, options) {
+  const result = await validatePlugin({
+    pluginPath: pluginPath || process.cwd(),
+    local: options.local,
+    verbose: options.verbose,
+    strict: options.strict,
+    generateTypes: options.generateTypes
+  });
+  printValidationResult(result, options.verbose ?? false);
+  if (!result.valid || options.strict && result.warnings.length > 0) {
+    process.exit(1);
+  }
+}
+function printValidationResult(result, verbose) {
+  const logger = getLogger();
+  if (result.valid && result.warnings.length === 0) {
+    logger.important(chalk.green("Plugin validation successful!\n"));
+    if (verbose) {
+      logger.important("Plugin: " + result.pluginName);
+      logger.important("  plugin.yaml valid");
+      logger.important(`  ${result.contractsChecked} contracts validated`);
+      if (result.typesGenerated) {
+        logger.important(`  ${result.typesGenerated} type definitions generated`);
+      }
+      logger.important(`  ${result.componentsChecked} components validated`);
+      if (result.packageJsonChecked) {
+        logger.important("  package.json valid");
+      }
+      logger.important("\nNo errors found.");
     }
-    const initPathTs = path2.join(projectRoot, "src", "init.ts");
-    const initPathJs = path2.join(projectRoot, "src", "init.js");
-    let initModule;
-    if (fs2.existsSync(initPathTs) && viteServer) {
-      initModule = await viteServer.ssrLoadModule(initPathTs);
-    } else if (fs2.existsSync(initPathJs)) {
-      initModule = await import(initPathJs);
+  } else if (result.valid && result.warnings.length > 0) {
+    logger.important(chalk.yellow("Plugin validation passed with warnings\n"));
+    logger.important("Warnings:");
+    result.warnings.forEach((warning) => {
+      logger.important(chalk.yellow(`  ${warning.message}`));
+      if (warning.location) {
+        logger.important(chalk.gray(`      Location: ${warning.location}`));
+      }
+      if (warning.suggestion) {
+        logger.important(chalk.gray(`      ${warning.suggestion}`));
+      }
+      logger.important("");
+    });
+    logger.important(chalk.gray("Use --strict to treat warnings as errors."));
+  } else {
+    logger.important(chalk.red("Plugin validation failed\n"));
+    logger.important("Errors:");
+    result.errors.forEach((error) => {
+      logger.important(chalk.red(`  ${error.message}`));
+      if (error.location) {
+        logger.important(chalk.gray(`      Location: ${error.location}`));
+      }
+      if (error.suggestion) {
+        logger.important(chalk.gray(`      ${error.suggestion}`));
+      }
+      logger.important("");
+    });
+    logger.important(chalk.red(`${result.errors.length} errors found.`));
+  }
+}
+const ALL_ROLES = ["designer", "developer", "plugin", "devops"];
+async function runAgentKit(options) {
+  const projectRoot = process.cwd();
+  const { initErrors, viteServer } = await runMaterialize(
+    projectRoot,
+    options,
+    "agent-kit/materialized-contracts",
+    true
+  );
+  try {
+    if (!options.list) {
+      await ensureAgentKitDocs(projectRoot, options.force, options.mode);
+      await mergePluginAgentKitGuides(projectRoot, options.mode);
+      if (options.references !== false) {
+        await generatePluginReferences(projectRoot, options, initErrors, viteServer);
+      }
     }
-    if (initModule?.init?._serverInit) {
-      await initModule.init._serverInit();
+  } finally {
+    if (viteServer) {
+      await viteServer.close();
     }
-    await runInitCallbacks();
-  } catch (error) {
-    getLogger().warn(chalk.yellow(`⚠️  Service initialization failed: ${error.message}`));
-    getLogger().warn(chalk.gray("   Static contracts will still be listed."));
   }
-  return { services: getServiceRegistry(), initErrors };
 }
-async function runAction(actionRef, options, projectRoot, initializeServices) {
+async function runMaterialize(projectRoot, options, defaultOutputRelative, keepViteAlive = false) {
+  const outputDir = options.output ?? path$1.join(projectRoot, defaultOutputRelative);
   let viteServer;
+  let initErrors = /* @__PURE__ */ new Map();
   try {
-    const slashIndex = actionRef.indexOf("/");
-    if (slashIndex === -1) {
-      getLogger().error(
-        chalk.red("❌ Invalid action reference. Use format: <plugin>/<action>")
-      );
-      process.exit(1);
+    if (options.list) {
+      const index = await listContracts({
+        projectRoot,
+        dynamicOnly: options.dynamicOnly,
+        pluginFilter: options.plugin
+      });
+      if (options.yaml) {
+        getLogger().important(YAML.stringify(index));
+      } else {
+        printContractList(index);
+      }
+      return { initErrors };
     }
-    const actionExport = actionRef.substring(slashIndex + 1);
-    const input = options.input ? JSON.parse(options.input) : {};
     if (options.verbose) {
       getLogger().info("Starting Vite for TypeScript support...");
     }
     viteServer = await createViteForCli({ projectRoot });
-    await initializeServices(projectRoot, viteServer);
-    const { discoverAndRegisterActions, discoverAllPluginActions, ActionRegistry } = await import("@jay-framework/stack-server-runtime");
-    const registry = new ActionRegistry();
-    await discoverAndRegisterActions({
-      projectRoot,
-      registry,
-      verbose: options.verbose,
-      viteServer
-    });
-    await discoverAllPluginActions({
+    const { services, initErrors: errors } = await initializeServicesForCli(
       projectRoot,
-      registry,
-      verbose: options.verbose,
       viteServer
-    });
-    const allNames = registry.getNames();
-    const matchedName = allNames.find((name) => name === actionExport) || allNames.find((name) => name.endsWith("." + actionExport)) || allNames.find((name) => name === actionRef);
-    if (!matchedName) {
-      getLogger().error(chalk.red(`❌ Action "${actionExport}" not found.`));
-      if (allNames.length > 0) {
-        getLogger().error(`   Available actions: ${allNames.join(", ")}`);
-      } else {
-        getLogger().error("   No actions registered. Does the plugin have actions?");
-      }
-      process.exit(1);
+    );
+    initErrors = errors;
+    const result = await materializeContracts(
+      {
+        projectRoot,
+        outputDir,
+        force: options.force,
+        dynamicOnly: options.dynamicOnly,
+        pluginFilter: options.plugin,
+        verbose: options.verbose,
+        viteServer
+      },
+      services
+    );
+    if (options.yaml) {
+      getLogger().important(YAML.stringify(result.pluginsIndex));
+    } else {
+      const totalContracts = result.pluginsIndex.plugins.reduce(
+        (sum, p) => sum + p.contracts.length,
+        0
+      );
+      getLogger().important(chalk.green(`
+Materialized ${totalContracts} contracts`));
+      getLogger().important(`   Static: ${result.staticCount}`);
+      getLogger().important(`   Dynamic: ${result.dynamicCount}`);
+      getLogger().important(`   Output: ${result.outputDir}`);
     }
+    return { initErrors, viteServer: keepViteAlive ? viteServer : void 0 };
+  } catch (error) {
+    getLogger().error(chalk.red("Failed to materialize contracts:") + " " + error.message);
     if (options.verbose) {
-      getLogger().info(`Executing action: ${matchedName}`);
-      getLogger().info(`Input: ${JSON.stringify(input)}`);
+      getLogger().error(error.stack);
     }
-    const result = await registry.execute(matchedName, input);
-    if (result.success) {
-      if (options.yaml) {
+    process.exit(1);
+  } finally {
+    if (viteServer && !keepViteAlive) {
+      await viteServer.close();
+    }
+  }
+  return { initErrors };
+}
+async function ensureAgentKitDocs(projectRoot, _force, mode) {
+  const agentKitDir = path$1.join(projectRoot, "agent-kit");
+  const thisDir = path$1.dirname(fileURLToPath(import.meta.url));
+  const templateDir = path$1.resolve(thisDir, "..", "agent-kit-template");
+  const roles = mode && ALL_ROLES.includes(mode) ? [mode] : ALL_ROLES;
+  for (const role of roles) {
+    const roleTemplateDir = path$1.join(templateDir, role);
+    const roleOutputDir = path$1.join(agentKitDir, role);
+    let files;
+    try {
+      files = (await fs$1.readdir(roleTemplateDir)).filter((f) => f.endsWith(".md"));
+    } catch {
+      continue;
+    }
+    await fs$1.mkdir(roleOutputDir, { recursive: true });
+    for (const filename of files) {
+      await fs$1.copyFile(
+        path$1.join(roleTemplateDir, filename),
+        path$1.join(roleOutputDir, filename)
+      );
+      getLogger().info(chalk.gray(`   Created agent-kit/${role}/${filename}`));
+    }
+  }
+}
+async function mergePluginAgentKitGuides(projectRoot, mode) {
+  const plugins = await scanPlugins$1({ projectRoot });
+  const agentKitDir = path$1.join(projectRoot, "agent-kit");
+  const roles = mode && ALL_ROLES.includes(mode) ? [mode] : ALL_ROLES;
+  const copiedPerRole = /* @__PURE__ */ new Map();
+  for (const [, plugin] of plugins) {
+    const pluginAgentKitDir = path$1.join(plugin.pluginPath, "agent-kit");
+    if (!fsSync.existsSync(pluginAgentKitDir))
+      continue;
+    for (const role of roles) {
+      const roleSourceDir = path$1.join(pluginAgentKitDir, role);
+      let files;
+      try {
+        files = (await fs$1.readdir(roleSourceDir)).filter(
+          (f) => f.endsWith(".md") && f !== "INSTRUCTIONS.md"
+        );
+      } catch {
+        continue;
+      }
+      if (files.length === 0)
+        continue;
+      const roleOutputDir = path$1.join(agentKitDir, role);
+      await fs$1.mkdir(roleOutputDir, { recursive: true });
+      for (const filename of files) {
+        const sourcePath = path$1.join(roleSourceDir, filename);
+        await fs$1.copyFile(sourcePath, path$1.join(roleOutputDir, filename));
+        let description = "";
+        try {
+          const content = await fs$1.readFile(sourcePath, "utf-8");
+          const lines = content.split("\n");
+          let pastHeading = false;
+          for (const line of lines) {
+            if (line.startsWith("# ")) {
+              pastHeading = true;
+              continue;
+            }
+            if (pastHeading && line.trim()) {
+              description = line.trim();
+              break;
+            }
+          }
+        } catch {
+        }
+        if (!copiedPerRole.has(role))
+          copiedPerRole.set(role, []);
+        copiedPerRole.get(role).push({ filename, pluginName: plugin.name, description });
+        getLogger().info(
+          chalk.gray(
+            `   Copied agent-kit/${role}/${filename} from plugin "${plugin.name}"`
+          )
+        );
+      }
+    }
+  }
+  for (const [role, entries] of copiedPerRole) {
+    const instructionsPath = path$1.join(agentKitDir, role, "INSTRUCTIONS.md");
+    if (!fsSync.existsSync(instructionsPath))
+      continue;
+    const lines = [
+      "",
+      "## Plugin-Contributed Guides",
+      "",
+      "| File | Plugin | Description |",
+      "| --- | --- | --- |"
+    ];
+    for (const { filename, pluginName, description } of entries) {
+      lines.push(`| [${filename}](${filename}) | ${pluginName} | ${description} |`);
+    }
+    lines.push("");
+    await fs$1.appendFile(instructionsPath, lines.join("\n"));
+  }
+}
+async function generatePluginReferences(projectRoot, options, initErrors, viteServer) {
+  const { discoverPluginsWithReferences, executePluginReferences } = await import("@jay-framework/stack-server-runtime");
+  const plugins = await discoverPluginsWithReferences({
+    projectRoot,
+    verbose: options.verbose,
+    pluginFilter: options.plugin
+  });
+  if (plugins.length === 0)
+    return;
+  const logger = getLogger();
+  logger.important("");
+  logger.important(chalk.bold("Generating plugin references..."));
+  for (const plugin of plugins) {
+    const pluginInitError = initErrors.get(plugin.name);
+    if (pluginInitError) {
+      logger.warn(
+        chalk.yellow(
+          `   ${plugin.name}: references skipped — init failed: ${pluginInitError.message}`
+        )
+      );
+      continue;
+    }
+    try {
+      const result = await executePluginReferences(plugin, {
+        projectRoot,
+        force: options.force ?? false,
+        viteServer,
+        verbose: options.verbose
+      });
+      if (result.referencesCreated.length > 0) {
+        logger.important(chalk.green(`   ${plugin.name}:`));
+        for (const ref of result.referencesCreated) {
+          logger.important(chalk.gray(`      ${ref}`));
+        }
+        if (result.message) {
+          logger.important(chalk.gray(`      ${result.message}`));
+        }
+      }
+    } catch (error) {
+      logger.warn(chalk.yellow(`   ${plugin.name}: references skipped — ${error.message}`));
+    }
+  }
+}
+function printContractList(index) {
+  const logger = getLogger();
+  logger.important("\nAvailable Contracts:\n");
+  for (const plugin of index.plugins) {
+    logger.important(chalk.bold(plugin.name));
+    for (const contract of plugin.contracts) {
+      const typeIcon = contract.type === "static" ? "static" : "dynamic";
+      logger.important(`   [${typeIcon}] ${contract.name}`);
+    }
+    logger.important("");
+  }
+  if (index.plugins.length === 0) {
+    logger.important(chalk.gray("No contracts found."));
+  }
+}
+async function runAction(actionRef, options, projectRoot, initializeServices) {
+  let viteServer;
+  try {
+    const slashIndex = actionRef.indexOf("/");
+    if (slashIndex === -1) {
+      getLogger().error(
+        chalk.red("❌ Invalid action reference. Use format: <plugin>/<action>")
+      );
+      process.exit(1);
+    }
+    const actionExport = actionRef.substring(slashIndex + 1);
+    const input = options.input ? JSON.parse(options.input) : {};
+    if (options.verbose) {
+      getLogger().info("Starting Vite for TypeScript support...");
+    }
+    viteServer = await createViteForCli({ projectRoot });
+    await initializeServices(projectRoot, viteServer);
+    const { discoverAndRegisterActions, discoverAllPluginActions, ActionRegistry } = await import("@jay-framework/stack-server-runtime");
+    const registry = new ActionRegistry();
+    await discoverAndRegisterActions({
+      projectRoot,
+      registry,
+      verbose: options.verbose,
+      viteServer
+    });
+    await discoverAllPluginActions({
+      projectRoot,
+      registry,
+      verbose: options.verbose,
+      viteServer
+    });
+    const allNames = registry.getNames();
+    const matchedName = allNames.find((name) => name === actionExport) || allNames.find((name) => name.endsWith("." + actionExport)) || allNames.find((name) => name === actionRef);
+    if (!matchedName) {
+      getLogger().error(chalk.red(`❌ Action "${actionExport}" not found.`));
+      if (allNames.length > 0) {
+        getLogger().error(`   Available actions: ${allNames.join(", ")}`);
+      } else {
+        getLogger().error("   No actions registered. Does the plugin have actions?");
+      }
+      process.exit(1);
+    }
+    if (options.verbose) {
+      getLogger().info(`Executing action: ${matchedName}`);
+      getLogger().info(`Input: ${JSON.stringify(input)}`);
+    }
+    const result = await registry.execute(matchedName, input);
+    if (result.success) {
+      if (options.yaml) {
         getLogger().important(YAML.stringify(result.data));
       } else {
         getLogger().important(JSON.stringify(result.data, null, 2));
@@ -4584,65 +5029,184 @@ async function runSetup(pluginFilter, options, projectRoot, initializeServices)
     }
   }
 }
-const program = new Command();
-program.name("jay-stack").description("Jay Stack CLI - Development server and plugin validation").version("0.9.0");
-program.command("dev [path]").description("Start the Jay Stack development server").option("-v, --verbose", "Enable verbose logging output").option("-q, --quiet", "Suppress all non-error output").option("--test-mode", "Enable test endpoints (/_jay/health, /_jay/shutdown)").option("--timeout <seconds>", "Auto-shutdown after N seconds (implies --test-mode)", parseInt).action(async (path2, options) => {
+async function runCommand(commandRef, rawArgs, options, projectRoot, initializeServices) {
+  let viteServer;
   try {
-    const logLevel = options.quiet ? "silent" : options.verbose ? "verbose" : "info";
-    setDevLogger(createDevLogger(logLevel));
-    const testMode = options.testMode || options.timeout !== void 0;
-    await startDevServer({
-      projectPath: path2 || process.cwd(),
-      testMode,
-      timeout: options.timeout,
-      logLevel
+    const {
+      discoverPluginCommands,
+      commandSchemaToFlags,
+      parseInputFromFlags,
+      executePluginCommand
+    } = await import("@jay-framework/stack-server-runtime");
+    const commands = await discoverPluginCommands({
+      projectRoot,
+      verbose: options.verbose
     });
-  } catch (error) {
-    getLogger().error(chalk.red("Error starting dev server:") + " " + error.message);
-    process.exit(1);
-  }
-});
-program.command("build [path]").description("Build production artifacts").option("--version <n>", "Build version number", "1").option("--no-minify", "Disable minification (useful for debugging)").option("-v, --verbose", "Enable verbose logging output").action(async (projectPath, options) => {
-  try {
-    const logLevel = options.verbose ? "verbose" : "info";
-    setDevLogger(createDevLogger(logLevel));
-    const resolvedPath = path$1.resolve(projectPath || process.cwd());
-    const jayConfigPath = path$1.join(resolvedPath, ".jay");
-    let pagesBase = "./src/pages";
-    try {
-      const jayConfig = YAML.parse(await fs$1.readFile(jayConfigPath, "utf-8"));
-      pagesBase = jayConfig?.devServer?.pagesBase || pagesBase;
-    } catch {
+    if (options.list || !commandRef) {
+      printCommandList(commands);
+      return;
+    }
+    const slashIndex = commandRef.indexOf("/");
+    if (slashIndex === -1) {
+      getLogger().error(
+        chalk.red("Invalid command reference. Use format: <plugin>/<command>")
+      );
+      getLogger().error(chalk.gray("Example: jay-stack run media/upload-public"));
+      process.exit(1);
+    }
+    const pluginName = commandRef.substring(0, slashIndex);
+    const commandName = commandRef.substring(slashIndex + 1);
+    const command = commands.find(
+      (c) => (c.pluginName === pluginName || c.packageName === pluginName) && c.commandName === commandName
+    );
+    if (!command) {
+      getLogger().error(chalk.red(`Command "${commandRef}" not found.`));
+      const pluginCommands = commands.filter(
+        (c) => c.pluginName === pluginName || c.packageName === pluginName
+      );
+      if (pluginCommands.length > 0) {
+        getLogger().error(`Available commands for ${pluginName}:`);
+        for (const c of pluginCommands) {
+          getLogger().error(
+            `   ${c.commandName}${c.metadata?.description ? "    " + c.metadata.description : ""}`
+          );
+        }
+      } else if (commands.length > 0) {
+        getLogger().error("Available plugins with commands:");
+        const plugins = [...new Set(commands.map((c) => c.pluginName))];
+        for (const p of plugins) {
+          getLogger().error(`   ${p}`);
+        }
+      } else {
+        getLogger().error("No plugins with CLI commands found.");
+      }
+      process.exit(1);
+    }
+    let input = {};
+    if (command.metadata?.inputSchema) {
+      const flagDefs = commandSchemaToFlags(command.metadata.inputSchema);
+      const rawOptions = parseRawFlags(rawArgs, flagDefs);
+      input = parseInputFromFlags(rawOptions, command.metadata.inputSchema);
     }
-    const { buildVersion } = await import("@jay-framework/production-server");
-    await buildVersion({
-      version: parseInt(options.version, 10),
-      projectRoot: resolvedPath,
-      pagesRoot: path$1.resolve(resolvedPath, pagesBase),
-      buildRoot: path$1.join(resolvedPath, "build"),
-      publicBasePath: "/",
-      concurrency: 4,
-      tsConfigFilePath: path$1.join(resolvedPath, "tsconfig.json"),
-      minify: options.minify
+    if (options.verbose) {
+      getLogger().info("Starting Vite for TypeScript support...");
+    }
+    viteServer = await createViteForCli({ projectRoot });
+    await initializeServices(projectRoot, viteServer);
+    const { registerService } = await import("@jay-framework/stack-server-runtime");
+    const { CONSOLE_CONTEXT } = await import("@jay-framework/fullstack-component");
+    const jayConfig = loadConfig();
+    const publicFolder = path$1.resolve(
+      projectRoot,
+      jayConfig.devServer?.publicFolder || "public"
+    );
+    const version = await resolveVersionFromPackageJson(projectRoot);
+    const buildRoot = path$1.resolve(projectRoot, `build/v${version}`);
+    registerService(CONSOLE_CONTEXT, {
+      projectRoot,
+      publicFolder,
+      build: {
+        frontend: path$1.join(buildRoot, "frontend"),
+        backend: path$1.join(buildRoot, "backend")
+      },
+      verbose: options.verbose ?? false,
+      log: (msg) => getLogger().important(msg),
+      warn: (msg) => getLogger().warn(chalk.yellow(msg)),
+      error: (msg) => getLogger().error(chalk.red(msg))
     });
+    if (options.verbose) {
+      getLogger().info(`Executing ${command.pluginName}/${command.commandName}...`);
+    }
+    const result = await executePluginCommand(command, input, viteServer);
+    if (!result.success) {
+      process.exit(1);
+    }
   } catch (error) {
-    getLogger().error(chalk.red("Build failed:") + " " + error.message);
-    if (error.stack)
+    getLogger().error(chalk.red("Command failed:") + " " + error.message);
+    if (options.verbose) {
       getLogger().error(error.stack);
+    }
     process.exit(1);
+  } finally {
+    if (viteServer) {
+      await viteServer.close();
+    }
   }
-});
-program.command("serve [path]").description("Start production server").option("--version <n>", "Build version to serve", "1").option("--port <n>", "Port number", "3000").action(async (projectPath, options) => {
-  try {
-    setDevLogger(createDevLogger("info"));
-    const resolvedPath = path$1.resolve(projectPath || process.cwd());
-    const { startMainServer } = await import("@jay-framework/production-server");
-    await startMainServer({
-      buildRoot: path$1.join(resolvedPath, "build"),
-      version: parseInt(options.version, 10),
-      port: parseInt(options.port, 10),
-      publicBasePath: "/"
-    });
+}
+function printCommandList(commands) {
+  const logger = getLogger();
+  if (commands.length === 0) {
+    logger.important(chalk.gray("No plugins with CLI commands found."));
+    return;
+  }
+  logger.important("\nAvailable plugin commands:\n");
+  const byPlugin = /* @__PURE__ */ new Map();
+  for (const cmd of commands) {
+    if (!byPlugin.has(cmd.pluginName))
+      byPlugin.set(cmd.pluginName, []);
+    byPlugin.get(cmd.pluginName).push(cmd);
+  }
+  for (const [pluginName, cmds] of byPlugin) {
+    logger.important(chalk.bold(`  ${pluginName}`));
+    for (const cmd of cmds) {
+      const desc = cmd.metadata?.description ? `    ${cmd.metadata.description}` : "";
+      logger.important(`    ${cmd.commandName}${desc}`);
+    }
+    logger.important("");
+  }
+}
+function parseRawFlags(args, flagDefs) {
+  const result = {};
+  const booleanFlags = new Set(
+    flagDefs.filter((f) => f.type === "boolean").map((f) => {
+      const match = f.flag.match(/^--(\S+)/);
+      return match ? match[1] : "";
+    })
+  );
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const name = arg.slice(2);
+      if (booleanFlags.has(name)) {
+        result[name] = true;
+        i++;
+      } else if (i + 1 < args.length && !args[i + 1].startsWith("--")) {
+        result[name] = args[i + 1];
+        i += 2;
+      } else {
+        result[name] = true;
+        i++;
+      }
+    } else {
+      i++;
+    }
+  }
+  return result;
+}
+const program = new Command();
+program.name("jay-stack").description("Jay Stack CLI - Development server and plugin validation").version("0.9.0");
+program.command("dev").description("Start the Jay Stack development server").option("-p, --path <path>", "Project root (default: cwd)").option("-v, --verbose", "Enable verbose logging output").option("-q, --quiet", "Suppress all non-error output").option("--test-mode", "Enable test endpoints (/_jay/health, /_jay/shutdown)").option("--timeout <seconds>", "Auto-shutdown after N seconds (implies --test-mode)", parseInt).action(async (options) => {
+  try {
+    await runDev(options.path, options);
+  } catch (error) {
+    getLogger().error(chalk.red("Error starting dev server:") + " " + error.message);
+    process.exit(1);
+  }
+});
+program.command("build").description("Build production artifacts").option("-p, --path <path>", "Project root (default: cwd)").option("--version <n>", "Build version number (default: from package.json)").option("--no-minify", "Disable minification (useful for debugging)").option("-v, --verbose", "Enable verbose logging output").action(async (options) => {
+  try {
+    await runBuild(options.path, options);
+  } catch (error) {
+    getLogger().error(chalk.red("Build failed:") + " " + error.message);
+    if (error.stack)
+      getLogger().error(error.stack);
+    process.exit(1);
+  }
+});
+program.command("serve").description("Start production server").option("-p, --path <path>", "Project root (default: cwd)").option("--version <n>", "Build version to serve (default: from package.json)").option("--port <n>", "Port number", "3000").option("--role <role>", "Server role: main (default) or renderer", "main").option("--static-base-url <url>", "Base URL for browser-facing assets (default: /)").option("--no-serve-static", "Disable serving static files from frontend/").option("--test-mode", "Enable test endpoints (/_jay/health, /_jay/shutdown)").option("-v, --verbose", "Enable verbose logging output").action(async (options) => {
+  try {
+    await runServe(options.path, options);
   } catch (error) {
     getLogger().error(chalk.red("Server failed:") + " " + error.message);
     if (error.stack)
@@ -4650,17 +5214,31 @@ program.command("serve [path]").description("Start production server").option("-
     process.exit(1);
   }
 });
-program.command("validate [path]").description("Validate all .jay-html and .jay-contract files in the project").option("-v, --verbose", "Show per-file validation status").option("--json", "Output results as JSON").action(async (scanPath, options) => {
+program.command("rebuild").description("Rebuild instances by contract, route, or URL").option("--contract <name>", "Rebuild by contract name (e.g., product-page)").option("--route <pattern>", "Rebuild by route pattern (e.g., /products/[slug])").option("--url <url>", "Rebuild by URL (e.g., /products/blue-widget)").option("--params <json>", `JSON params to rebuild specific instance (e.g., '{"slug":"x"}')`).option("--version <n>", "Build version (default: from package.json)").option("-p, --path <path>", "Project root (default: cwd)").option("-v, --verbose", "Enable verbose logging output").action(async (options) => {
   try {
-    const result = await validateJayFiles({
-      path: scanPath,
-      verbose: options.verbose,
-      json: options.json
-    });
-    printJayValidationResult(result, options);
-    if (!result.valid) {
-      process.exit(1);
-    }
+    await runRebuild(options.path, options);
+  } catch (error) {
+    getLogger().error(chalk.red("Rebuild failed:") + " " + error.message);
+    if (error.stack)
+      getLogger().error(error.stack);
+    process.exit(1);
+  }
+});
+program.command("cleanup").description("Delete orphaned files from previous rebuilds").option("--version <n>", "Build version (default: from package.json)").option("-p, --path <path>", "Project root (default: cwd)").action(async (options) => {
+  try {
+    const { initLogger: initLogger2, resolveProductionContext: resolveProductionContext2 } = await Promise.resolve().then(() => runProduction);
+    initLogger2();
+    const ctx = await resolveProductionContext2(options.path, options.version);
+    const { cleanupOrphanedFiles } = await import("@jay-framework/production-server");
+    await cleanupOrphanedFiles(ctx.buildRoot, ctx.version);
+  } catch (error) {
+    getLogger().error(chalk.red("Cleanup failed:") + " " + error.message);
+    process.exit(1);
+  }
+});
+program.command("validate").description("Validate all .jay-html and .jay-contract files").option("-p, --path <path>", "Scan root (default: cwd)").option("-v, --verbose", "Show per-file validation status").option("--json", "Output results as JSON").action(async (options) => {
+  try {
+    await runValidate(options.path, options);
   } catch (error) {
     if (options.json) {
       getLogger().important(
@@ -4672,342 +5250,40 @@ program.command("validate [path]").description("Validate all .jay-html and .jay-
     process.exit(1);
   }
 });
-program.command("validate-plugin [path]").description("Validate a Jay Stack plugin package").option("--local", "Validate local plugins in src/plugins/").option("-v, --verbose", "Show detailed validation output").option("--strict", "Treat warnings as errors (for CI)").option("--generate-types", "Generate .d.ts files for contracts").action(async (pluginPath, options) => {
+program.command("validate-plugin").description("Validate a Jay Stack plugin package").option("-p, --path <path>", "Plugin root (default: cwd)").option("--local", "Validate local plugins in src/plugins/").option("-v, --verbose", "Show detailed validation output").option("--strict", "Treat warnings as errors (for CI)").option("--generate-types", "Generate .d.ts files for contracts").action(async (options) => {
   try {
-    const result = await validatePlugin({
-      pluginPath: pluginPath || process.cwd(),
-      local: options.local,
-      verbose: options.verbose,
-      strict: options.strict,
-      generateTypes: options.generateTypes
-    });
-    printValidationResult(result, options.verbose);
-    if (!result.valid || options.strict && result.warnings.length > 0) {
-      process.exit(1);
-    }
+    await runValidatePlugin(options.path, options);
   } catch (error) {
     getLogger().error(chalk.red("Validation error:") + " " + error.message);
     process.exit(1);
   }
 });
-const ALL_ROLES = ["designer", "developer", "plugin"];
-async function ensureAgentKitDocs(projectRoot, _force, mode) {
-  const agentKitDir = path$1.join(projectRoot, "agent-kit");
-  const thisDir = path$1.dirname(fileURLToPath(import.meta.url));
-  const templateDir = path$1.resolve(thisDir, "..", "agent-kit-template");
-  const roles = mode && ALL_ROLES.includes(mode) ? [mode] : ALL_ROLES;
-  for (const role of roles) {
-    const roleTemplateDir = path$1.join(templateDir, role);
-    const roleOutputDir = path$1.join(agentKitDir, role);
-    let files;
-    try {
-      files = (await fs$1.readdir(roleTemplateDir)).filter((f) => f.endsWith(".md"));
-    } catch {
-      continue;
-    }
-    await fs$1.mkdir(roleOutputDir, { recursive: true });
-    for (const filename of files) {
-      await fs$1.copyFile(
-        path$1.join(roleTemplateDir, filename),
-        path$1.join(roleOutputDir, filename)
-      );
-      getLogger().info(chalk.gray(`   Created agent-kit/${role}/${filename}`));
-    }
-  }
-}
-async function mergePluginAgentKitGuides(projectRoot, mode) {
-  const plugins = await scanPlugins$1({ projectRoot });
-  const agentKitDir = path$1.join(projectRoot, "agent-kit");
-  const roles = mode && ALL_ROLES.includes(mode) ? [mode] : ALL_ROLES;
-  const copiedPerRole = /* @__PURE__ */ new Map();
-  for (const [, plugin] of plugins) {
-    const pluginAgentKitDir = path$1.join(plugin.pluginPath, "agent-kit");
-    if (!fsSync.existsSync(pluginAgentKitDir))
-      continue;
-    for (const role of roles) {
-      const roleSourceDir = path$1.join(pluginAgentKitDir, role);
-      let files;
-      try {
-        files = (await fs$1.readdir(roleSourceDir)).filter(
-          (f) => f.endsWith(".md") && f !== "INSTRUCTIONS.md"
-        );
-      } catch {
-        continue;
-      }
-      if (files.length === 0)
-        continue;
-      const roleOutputDir = path$1.join(agentKitDir, role);
-      await fs$1.mkdir(roleOutputDir, { recursive: true });
-      for (const filename of files) {
-        const sourcePath = path$1.join(roleSourceDir, filename);
-        await fs$1.copyFile(sourcePath, path$1.join(roleOutputDir, filename));
-        let description = "";
-        try {
-          const content = await fs$1.readFile(sourcePath, "utf-8");
-          const lines = content.split("\n");
-          let pastHeading = false;
-          for (const line of lines) {
-            if (line.startsWith("# ")) {
-              pastHeading = true;
-              continue;
-            }
-            if (pastHeading && line.trim()) {
-              description = line.trim();
-              break;
-            }
-          }
-        } catch {
-        }
-        if (!copiedPerRole.has(role))
-          copiedPerRole.set(role, []);
-        copiedPerRole.get(role).push({ filename, pluginName: plugin.name, description });
-        getLogger().info(
-          chalk.gray(
-            `   Copied agent-kit/${role}/${filename} from plugin "${plugin.name}"`
-          )
-        );
-      }
-    }
-  }
-  for (const [role, entries] of copiedPerRole) {
-    const instructionsPath = path$1.join(agentKitDir, role, "INSTRUCTIONS.md");
-    if (!fsSync.existsSync(instructionsPath))
-      continue;
-    const lines = [
-      "",
-      "## Plugin-Contributed Guides",
-      "",
-      "| File | Plugin | Description |",
-      "| --- | --- | --- |"
-    ];
-    for (const { filename, pluginName, description } of entries) {
-      lines.push(`| [${filename}](${filename}) | ${pluginName} | ${description} |`);
-    }
-    lines.push("");
-    await fs$1.appendFile(instructionsPath, lines.join("\n"));
-  }
-}
-async function generatePluginReferences(projectRoot, options, initErrors, viteServer) {
-  const { discoverPluginsWithReferences, executePluginReferences } = await import("@jay-framework/stack-server-runtime");
-  const plugins = await discoverPluginsWithReferences({
-    projectRoot,
-    verbose: options.verbose,
-    pluginFilter: options.plugin
-  });
-  if (plugins.length === 0)
-    return;
-  const logger = getLogger();
-  logger.important("");
-  logger.important(chalk.bold("📚 Generating plugin references..."));
-  for (const plugin of plugins) {
-    const pluginInitError = initErrors.get(plugin.name);
-    if (pluginInitError) {
-      logger.warn(
-        chalk.yellow(
-          `   ⚠️  ${plugin.name}: references skipped — init failed: ${pluginInitError.message}`
-        )
-      );
-      continue;
-    }
-    try {
-      const result = await executePluginReferences(plugin, {
-        projectRoot,
-        force: options.force ?? false,
-        viteServer,
-        verbose: options.verbose
-      });
-      if (result.referencesCreated.length > 0) {
-        logger.important(chalk.green(`   ✅ ${plugin.name}:`));
-        for (const ref of result.referencesCreated) {
-          logger.important(chalk.gray(`      ${ref}`));
-        }
-        if (result.message) {
-          logger.important(chalk.gray(`      ${result.message}`));
-        }
-      }
-    } catch (error) {
-      logger.warn(
-        chalk.yellow(`   ⚠️  ${plugin.name}: references skipped — ${error.message}`)
-      );
-    }
-  }
-}
-async function runMaterialize(projectRoot, options, defaultOutputRelative, keepViteAlive = false) {
-  const path2 = await import("node:path");
-  const outputDir = options.output ?? path2.join(projectRoot, defaultOutputRelative);
-  let viteServer;
-  let initErrors = /* @__PURE__ */ new Map();
-  try {
-    if (options.list) {
-      const index = await listContracts({
-        projectRoot,
-        dynamicOnly: options.dynamicOnly,
-        pluginFilter: options.plugin
-      });
-      if (options.yaml) {
-        getLogger().important(YAML.stringify(index));
-      } else {
-        printContractList(index);
-      }
-      return { initErrors };
-    }
-    if (options.verbose) {
-      getLogger().info("Starting Vite for TypeScript support...");
-    }
-    viteServer = await createViteForCli({ projectRoot });
-    const { services, initErrors: errors } = await initializeServicesForCli(
-      projectRoot,
-      viteServer
-    );
-    initErrors = errors;
-    const result = await materializeContracts(
-      {
-        projectRoot,
-        outputDir,
-        force: options.force,
-        dynamicOnly: options.dynamicOnly,
-        pluginFilter: options.plugin,
-        verbose: options.verbose,
-        viteServer
-      },
-      services
-    );
-    if (options.yaml) {
-      getLogger().important(YAML.stringify(result.pluginsIndex));
-    } else {
-      const totalContracts = result.pluginsIndex.plugins.reduce(
-        (sum, p) => sum + p.contracts.length,
-        0
-      );
-      getLogger().important(chalk.green(`
-✅ Materialized ${totalContracts} contracts`));
-      getLogger().important(`   Static: ${result.staticCount}`);
-      getLogger().important(`   Dynamic: ${result.dynamicCount}`);
-      getLogger().important(`   Output: ${result.outputDir}`);
-    }
-    return { initErrors, viteServer: keepViteAlive ? viteServer : void 0 };
-  } catch (error) {
-    getLogger().error(chalk.red("❌ Failed to materialize contracts:") + " " + error.message);
-    if (options.verbose) {
-      getLogger().error(error.stack);
-    }
-    process.exit(1);
-  } finally {
-    if (viteServer && !keepViteAlive) {
-      await viteServer.close();
-    }
-  }
-  return { initErrors };
-}
-program.command("setup [plugin]").description(
-  "Run plugin setup: create config templates, validate credentials, generate reference data"
-).option("--force", "Force re-run (overwrite config templates and regenerate references)").option("-v, --verbose", "Show detailed output").action(async (plugin, options) => {
+program.command("setup [plugin]").description("Run plugin setup: config templates, credential validation, reference data").option("--force", "Force re-run (overwrite config templates and regenerate references)").option("-v, --verbose", "Show detailed output").action(async (plugin, options) => {
   await runSetup(plugin, options, process.cwd(), initializeServicesForCli);
 });
-program.command("agent-kit").description(
-  "Prepare the agent kit: materialize contracts, generate references, and write docs to agent-kit/"
-).option("-o, --output <dir>", "Output directory (default: agent-kit/materialized-contracts)").option("--yaml", "Output contract index as YAML to stdout").option("--list", "List contracts without writing files").option("--plugin <name>", "Filter to specific plugin").option("--dynamic-only", "Only process dynamic contracts").option("--force", "Force re-materialization").option("--no-references", "Skip reference data generation").option(
+program.command("agent-kit").description("Prepare agent kit: materialize contracts, generate references, write docs").option("-o, --output <dir>", "Output directory (default: agent-kit/materialized-contracts)").option("--yaml", "Output contract index as YAML to stdout").option("--list", "List contracts without writing files").option("--plugin <name>", "Filter to specific plugin").option("--dynamic-only", "Only process dynamic contracts").option("--force", "Force re-materialization").option("--no-references", "Skip reference data generation").option(
   "-m, --mode <role>",
   "Generate guides for a specific role: designer, developer, or plugin (default: all)"
 ).option("-v, --verbose", "Show detailed output").action(async (options) => {
-  const projectRoot = process.cwd();
-  const { initErrors, viteServer } = await runMaterialize(
-    projectRoot,
-    options,
-    "agent-kit/materialized-contracts",
-    /* keepViteAlive */
-    true
-  );
-  try {
-    if (!options.list) {
-      await ensureAgentKitDocs(projectRoot, options.force, options.mode);
-      await mergePluginAgentKitGuides(projectRoot, options.mode);
-      if (options.references !== false) {
-        await generatePluginReferences(projectRoot, options, initErrors, viteServer);
-      }
-    }
-  } finally {
-    if (viteServer) {
-      await viteServer.close();
-    }
-  }
+  await runAgentKit(options);
 });
-program.command("action <plugin/action>").description(
-  `Run a plugin action (e.g., jay-stack action wix-stores/searchProducts --input '{"query":""}')`
-).option("--input <json>", "JSON input for the action (default: {})").option("--yaml", "Output result as YAML instead of JSON").option("-v, --verbose", "Show detailed output").action(async (actionRef, options) => {
+program.command("action <plugin/action>").description("Run a plugin action (e.g., jay-stack action wix-stores/searchProducts)").option("--input <json>", "JSON input for the action (default: {})").option("--yaml", "Output result as YAML instead of JSON").option("-v, --verbose", "Show detailed output").action(async (actionRef, options) => {
   await runAction(actionRef, options, process.cwd(), initializeServicesForCli);
 });
-program.command("params <plugin/contract>").description(
-  "Discover load param values for a contract. Streams results as NDJSON (one JSON object per line) or YAML."
-).option("--yaml", "Output as YAML instead of NDJSON").option("-v, --verbose", "Show detailed output").action(async (contractRef, options) => {
+program.command("run [plugin/command]").description("Run a plugin CLI command (e.g., jay-stack run media/upload-public)").option("--list", "List all available plugin commands").option("-v, --verbose", "Show detailed output").allowUnknownOption().allowExcessArguments().action(async (commandRef, options, command) => {
+  const rawArgs = command.parent?.rawArgs.slice(3) ?? [];
+  const extraArgs = rawArgs.filter(
+    (a) => a !== commandRef && a !== "-v" && a !== "--verbose" && a !== "--list"
+  );
+  await runCommand(commandRef, extraArgs, options, process.cwd(), initializeServicesForCli);
+});
+program.command("params <plugin/contract>").description("Discover load param values for a contract (NDJSON or YAML)").option("--yaml", "Output as YAML instead of NDJSON").option("-v, --verbose", "Show detailed output").action(async (contractRef, options) => {
   await runParams(contractRef, options, process.cwd(), initializeServicesForCli);
 });
 program.parse(process.argv);
 if (!process.argv.slice(2).length) {
   program.outputHelp();
 }
-function printValidationResult(result, verbose) {
-  const logger = getLogger();
-  if (result.valid && result.warnings.length === 0) {
-    logger.important(chalk.green("✅ Plugin validation successful!\n"));
-    if (verbose) {
-      logger.important("Plugin: " + result.pluginName);
-      logger.important("  ✅ plugin.yaml valid");
-      logger.important(`  ✅ ${result.contractsChecked} contracts validated`);
-      if (result.typesGenerated) {
-        logger.important(`  ✅ ${result.typesGenerated} type definitions generated`);
-      }
-      logger.important(`  ✅ ${result.componentsChecked} components validated`);
-      if (result.packageJsonChecked) {
-        logger.important("  ✅ package.json valid");
-      }
-      logger.important("\nNo errors found.");
-    }
-  } else if (result.valid && result.warnings.length > 0) {
-    logger.important(chalk.yellow("⚠️  Plugin validation passed with warnings\n"));
-    logger.important("Warnings:");
-    result.warnings.forEach((warning) => {
-      logger.important(chalk.yellow(`  ⚠️  ${warning.message}`));
-      if (warning.location) {
-        logger.important(chalk.gray(`      Location: ${warning.location}`));
-      }
-      if (warning.suggestion) {
-        logger.important(chalk.gray(`      → ${warning.suggestion}`));
-      }
-      logger.important("");
-    });
-    logger.important(chalk.gray("Use --strict to treat warnings as errors."));
-  } else {
-    logger.important(chalk.red("❌ Plugin validation failed\n"));
-    logger.important("Errors:");
-    result.errors.forEach((error) => {
-      logger.important(chalk.red(`  ❌ ${error.message}`));
-      if (error.location) {
-        logger.important(chalk.gray(`      Location: ${error.location}`));
-      }
-      if (error.suggestion) {
-        logger.important(chalk.gray(`      → ${error.suggestion}`));
-      }
-      logger.important("");
-    });
-    logger.important(chalk.red(`${result.errors.length} errors found.`));
-  }
-}
-function printContractList(index) {
-  const logger = getLogger();
-  logger.important("\nAvailable Contracts:\n");
-  for (const plugin of index.plugins) {
-    logger.important(chalk.bold(`📦 ${plugin.name}`));
-    for (const contract of plugin.contracts) {
-      const typeIcon = contract.type === "static" ? "📄" : "⚡";
-      logger.important(`   ${typeIcon} ${contract.name}`);
-    }
-    logger.important("");
-  }
-  if (index.plugins.length === 0) {
-    logger.important(chalk.gray("No contracts found."));
-  }
-}
 export {
   createEditorHandlers,
   getConfigWithDefaults,