@jay-framework/stack-server-runtime 0.17.4 → 0.18.0

package/dist/index.d.ts

@@ -129,15 +129,6 @@ interface InstanceSlowRenderResult {
  * Shared between preRenderJayHtml (pre-render path) and handleDirectRequest (direct path).
  */
 declare function slowRenderInstances(discovered: DiscoveredHeadlessInstance[], headlessInstanceComponents: HeadlessInstanceComponent[]): Promise<InstanceSlowRenderResult | undefined>;
-/**
- * Validate that forEach headless instances do not have a slow phase.
- *
- * Components with slowlyRender cannot be used inside forEach because
- * forEach items are only known at request time, after slow rendering completes.
- *
- * @returns Array of validation error messages (empty if all valid)
- */
-declare function validateForEachInstances(forEachInstances: ForEachHeadlessInstance[], headlessInstanceComponents: HeadlessInstanceComponent[]): string[];
 
 declare function renderFastChangingData(pageParams: object, pageProps: PageProps, carryForward: object, parts: Array<DevServerPagePart>, instancePhaseData?: InstancePhaseData, forEachInstances?: ForEachHeadlessInstance[], headlessInstanceComponents?: HeadlessInstanceComponent[], mergedSlowViewState?: object, query?: Record<string, string>, cookies?: Record<string, string>): Promise<AnyFastRenderResult>;
 
@@ -992,6 +983,11 @@ interface RouteIndexEntry {
     path: string;
     description?: string;
 }
+/** CLI command entry in plugins-index.yaml (DL#142) */
+interface CommandIndexEntry {
+    name: string;
+    description?: string;
+}
 /** Entry for plugins-index.yaml (Design Log #85) */
 interface PluginsIndexEntry {
     name: string;
@@ -1005,6 +1001,8 @@ interface PluginsIndexEntry {
     contexts?: ContextIndexEntry[];
     /** Plugin-provided routes (DL#130) */
     routes?: RouteIndexEntry[];
+    /** CLI commands (DL#142) */
+    commands?: CommandIndexEntry[];
 }
 interface PluginsIndex {
     plugins: PluginsIndexEntry[];
@@ -1267,4 +1265,45 @@ declare function serializeHeadTags(tags: HeadTag[]): string;
  */
 declare function parseCookies(cookieHeader: string | null | undefined): Record<string, string>;
 
-export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionErrorResponse, type ActionExecutionResult, type ActionIndexEntry, type ActionMetadata, ActionRegistry, type ActionSchema, type ContextIndexEntry, type DevServerPagePart, DevSlowlyChangingPhase, type GenerateClientScriptOptions, type HeadlessInstanceComponent, type InstancePhaseData, type InstanceSlowRenderResult, type LoadedPageParts, type MaterializeContractsOptions, type MaterializeResult, type PluginActionDiscoveryOptions, type PluginClientInitInfo, type PluginContractEntry, type PluginInitDiscoveryOptions, type PluginReferencesContext, type PluginReferencesHandler, type PluginReferencesResult, type PluginScanOptions, type PluginSetupContext, type PluginSetupHandler, type PluginSetupResult, type PluginWithInit, type PluginWithReferences, type PluginWithSetup, type PluginsIndex, type PluginsIndexEntry, type ProjectClientInitInfo, type RegisteredAction, type RegisteredActionBase, type RegisteredActionEntry, type RegisteredStreamAction, type RouteIndexEntry, type ScannedPlugin, type ScriptFragments, type ServiceIndexEntry, SlowRenderCache, type SlowRenderCacheEntry, type SlowlyChangingPhase, type ViteSSRLoader, actionRegistry, buildAutomationWrap, buildScriptFragments, clearActionRegistry, clearClientInitData, clearLifecycleCallbacks, clearServerElementCache, clearServiceRegistry, discoverAllPluginActions, discoverAndRegisterActions, discoverPluginActions, discoverPluginsWithInit, discoverPluginsWithReferences, discoverPluginsWithSetup, executeAction, executePluginReferences, executePluginServerInits, executePluginSetup, generateClientScript, generateFrozenPageHtml, generatePromiseReconstruction, generateSSRPageHtml, getActionCacheHeaders, getClientInitData, getClientInitDataForKey, getRegisteredAction, getRegisteredActionNames, getService, getServiceRegistry, hasAction, hasService, invalidateServerElementCache, listContracts, loadActionMetadata, loadPageParts, materializeContracts, mergeHeadTags, onInit, onShutdown, parseActionMetadata, parseCookies, preparePluginClientInits, registerAction, registerService, renderFastChangingData, resolveActionMetadataPath, resolveServices, resolveViewStatePromises, runInitCallbacks, runLoadParams, runShutdownCallbacks, scanPlugins, serializeHeadTags, setClientInitData, slowRenderInstances, sortPluginsByDependencies, tagIdentityKey, validateForEachInstances };
+/**
+ * Plugin CLI Commands (Design Log #142)
+ *
+ * Plugins expose CLI commands via `commands` in plugin.yaml.
+ * Each command has a `makeCliCommand` handler and an optional `.jay-command` metadata file.
+ * Run via `jay-stack run <plugin>/<command>`.
+ */
+
+interface CommandMetadata {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, string>;
+}
+interface DiscoveredCommand {
+    pluginName: string;
+    pluginPath: string;
+    packageName: string;
+    isLocal: boolean;
+    commandName: string;
+    handlerExport: string;
+    pluginModule?: string;
+    metadata?: CommandMetadata;
+    metadataPath?: string;
+}
+interface CommandFlag {
+    flag: string;
+    description: string;
+    required: boolean;
+    type: 'string' | 'boolean' | 'number';
+}
+declare function discoverPluginCommands(options: {
+    projectRoot: string;
+    verbose?: boolean;
+    pluginFilter?: string;
+}): Promise<DiscoveredCommand[]>;
+declare function commandSchemaToFlags(inputSchema: Record<string, string>): CommandFlag[];
+declare function parseInputFromFlags(rawOptions: Record<string, any>, schema: Record<string, string>): Record<string, any>;
+declare function executePluginCommand(command: DiscoveredCommand, input: Record<string, any>, viteServer?: ViteSSRLoader): Promise<{
+    success: boolean;
+}>;
+
+export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionErrorResponse, type ActionExecutionResult, type ActionIndexEntry, type ActionMetadata, ActionRegistry, type ActionSchema, type CommandFlag, type CommandIndexEntry, type CommandMetadata, type ContextIndexEntry, type DevServerPagePart, DevSlowlyChangingPhase, type DiscoveredCommand, type GenerateClientScriptOptions, type HeadlessInstanceComponent, type InstancePhaseData, type InstanceSlowRenderResult, type LoadedPageParts, type MaterializeContractsOptions, type MaterializeResult, type PluginActionDiscoveryOptions, type PluginClientInitInfo, type PluginContractEntry, type PluginInitDiscoveryOptions, type PluginReferencesContext, type PluginReferencesHandler, type PluginReferencesResult, type PluginScanOptions, type PluginSetupContext, type PluginSetupHandler, type PluginSetupResult, type PluginWithInit, type PluginWithReferences, type PluginWithSetup, type PluginsIndex, type PluginsIndexEntry, type ProjectClientInitInfo, type RegisteredAction, type RegisteredActionBase, type RegisteredActionEntry, type RegisteredStreamAction, type RouteIndexEntry, type ScannedPlugin, type ScriptFragments, type ServiceIndexEntry, SlowRenderCache, type SlowRenderCacheEntry, type SlowlyChangingPhase, type ViteSSRLoader, actionRegistry, buildAutomationWrap, buildScriptFragments, clearActionRegistry, clearClientInitData, clearLifecycleCallbacks, clearServerElementCache, clearServiceRegistry, commandSchemaToFlags, discoverAllPluginActions, discoverAndRegisterActions, discoverPluginActions, discoverPluginCommands, discoverPluginsWithInit, discoverPluginsWithReferences, discoverPluginsWithSetup, executeAction, executePluginCommand, executePluginReferences, executePluginServerInits, executePluginSetup, generateClientScript, generateFrozenPageHtml, generatePromiseReconstruction, generateSSRPageHtml, getActionCacheHeaders, getClientInitData, getClientInitDataForKey, getRegisteredAction, getRegisteredActionNames, getService, getServiceRegistry, hasAction, hasService, invalidateServerElementCache, listContracts, loadActionMetadata, loadPageParts, materializeContracts, mergeHeadTags, onInit, onShutdown, parseActionMetadata, parseCookies, parseInputFromFlags, preparePluginClientInits, registerAction, registerService, renderFastChangingData, resolveActionMetadataPath, resolveServices, resolveViewStatePromises, runInitCallbacks, runLoadParams, runShutdownCallbacks, scanPlugins, serializeHeadTags, setClientInitData, slowRenderInstances, sortPluginsByDependencies, tagIdentityKey };

package/dist/index.js

@@ -4,7 +4,7 @@ var __publicField = (obj, key, value) => {
   __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
-import { phaseOutput, isJayAction, isJayStreamAction } from "@jay-framework/fullstack-component";
+import { phaseOutput, isJayAction, isJayStreamAction, isJayCliCommand } from "@jay-framework/fullstack-component";
 import "prettier";
 import "js-beautify";
 import fs$1 from "fs";
@@ -1293,22 +1293,6 @@ async function slowRenderInstances(discovered, headlessInstanceComponents) {
     instancePhaseData: { discovered: discoveredForFast, carryForwards, slowViewStates }
   };
 }
-function validateForEachInstances(forEachInstances, headlessInstanceComponents) {
-  const componentByContractName = /* @__PURE__ */ new Map();
-  for (const comp of headlessInstanceComponents) {
-    componentByContractName.set(comp.contractName, comp);
-  }
-  const validations = [];
-  for (const instance of forEachInstances) {
-    const comp = componentByContractName.get(instance.contractName);
-    if (comp?.compDefinition.slowlyRender) {
-      validations.push(
-        `<jay:${instance.contractName}> inside forEach has a slow rendering phase. Headless components with slow phases cannot be used inside forEach because forEach items are only known at request time, after slow rendering completes. Use slowForEach instead, or remove the slow phase from the component.`
-      );
-    }
-  }
-  return validations;
-}
 class ActionRegistry {
   constructor() {
     __publicField(this, "actions", /* @__PURE__ */ new Map());
@@ -1325,7 +1309,9 @@ class ActionRegistry {
       cacheOptions: action.cacheOptions,
       services: action.services,
       handler: action.handler,
-      ...action.acceptsFiles && { acceptsFiles: true }
+      ...action.acceptsFiles && {
+        acceptsFiles: true
+      }
     };
     this.actions.set(action.actionName, entry);
   }
@@ -1483,7 +1469,9 @@ class ActionRegistry {
       isStreaming: true,
       services: action.services,
       handler: action.handler,
-      ...action.acceptsFiles && { acceptsFiles: true }
+      ...action.acceptsFiles && {
+        acceptsFiles: true
+      }
     };
     this.actions.set(action.actionName, entry);
   }
@@ -2583,6 +2571,24 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
           ...r.description && { description: r.description }
         }));
       }
+      if (manifest.commands?.length) {
+        entry.commands = manifest.commands.map((c) => {
+          let description;
+          if (c.command) {
+            try {
+              const cmdPath = path.resolve(plugin.pluginPath, c.command);
+              const cmdContent = fs.readFileSync(cmdPath, "utf-8");
+              const parsed = YAML.parse(cmdContent);
+              description = parsed?.description;
+            } catch {
+            }
+          }
+          return {
+            name: c.name,
+            ...description && { description }
+          };
+        });
+      }
       pluginsIndexMap.set(plugin.name, entry);
     }
     if (!dynamicOnly && manifest.contracts) {
@@ -2718,7 +2724,8 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
       ...data.actions && data.actions.length > 0 && { actions: data.actions },
       ...data.services?.length && { services: data.services },
       ...data.contexts?.length && { contexts: data.contexts },
-      ...data.routes?.length && { routes: data.routes }
+      ...data.routes?.length && { routes: data.routes },
+      ...data.commands?.length && { commands: data.commands }
     }))
   };
   fs.mkdirSync(outputDir, { recursive: true });
@@ -2781,6 +2788,24 @@ async function listContracts(options) {
           ...r.description && { description: r.description }
         }));
       }
+      if (manifest.commands?.length) {
+        entry.commands = manifest.commands.map((c) => {
+          let description;
+          if (c.command) {
+            try {
+              const cmdPath = path.resolve(plugin.pluginPath, c.command);
+              const cmdContent = fs.readFileSync(cmdPath, "utf-8");
+              const parsed = YAML.parse(cmdContent);
+              description = parsed?.description;
+            } catch {
+            }
+          }
+          return {
+            name: c.name,
+            ...description && { description }
+          };
+        });
+      }
       pluginsMap.set(plugin.name, entry);
     }
     if (!dynamicOnly && manifest.contracts) {
@@ -2828,7 +2853,8 @@ async function listContracts(options) {
       contracts: data.contracts,
       ...data.services?.length && { services: data.services },
       ...data.contexts?.length && { contexts: data.contexts },
-      ...data.routes?.length && { routes: data.routes }
+      ...data.routes?.length && { routes: data.routes },
+      ...data.commands?.length && { commands: data.commands }
     }))
   };
 }
@@ -2970,6 +2996,135 @@ function parseCookies(cookieHeader) {
   }
   return cookies;
 }
+async function discoverPluginCommands(options) {
+  const { projectRoot, verbose, pluginFilter } = options;
+  const allPlugins = await scanPlugins({
+    projectRoot,
+    verbose,
+    discoverTransitive: true
+  });
+  const commands = [];
+  for (const [packageName, plugin] of allPlugins) {
+    if (!plugin.manifest.commands || plugin.manifest.commands.length === 0)
+      continue;
+    if (pluginFilter && plugin.name !== pluginFilter && packageName !== pluginFilter) {
+      continue;
+    }
+    for (const cmd of plugin.manifest.commands) {
+      let metadata;
+      let metadataPath;
+      if (cmd.command) {
+        metadataPath = path.resolve(plugin.pluginPath, cmd.command);
+        metadata = loadCommandMetadata(metadataPath);
+      }
+      commands.push({
+        pluginName: plugin.name,
+        pluginPath: plugin.pluginPath,
+        packageName: plugin.packageName,
+        isLocal: plugin.isLocal,
+        commandName: cmd.name,
+        handlerExport: cmd.name,
+        pluginModule: plugin.manifest.module,
+        metadata,
+        metadataPath
+      });
+      if (verbose) {
+        getLogger().info(`[Commands] Found ${plugin.name}/${cmd.name}`);
+      }
+    }
+  }
+  return commands;
+}
+function loadCommandMetadata(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    return YAML.parse(content);
+  } catch {
+    return void 0;
+  }
+}
+function commandSchemaToFlags(inputSchema) {
+  const flags = [];
+  for (const [field, type] of Object.entries(inputSchema)) {
+    const isOptional = field.endsWith("?");
+    const cleanName = isOptional ? field.slice(0, -1) : field;
+    const kebabName = camelToKebab(cleanName);
+    const cleanType = type.toLowerCase().trim();
+    const isBoolean = cleanType === "boolean";
+    flags.push({
+      flag: isBoolean ? `--${kebabName}` : `--${kebabName} <value>`,
+      description: "",
+      required: !isOptional,
+      type: cleanType === "number" ? "number" : isBoolean ? "boolean" : "string"
+    });
+  }
+  return flags;
+}
+function camelToKebab(str) {
+  return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+function parseInputFromFlags(rawOptions, schema) {
+  const input = {};
+  for (const [field, type] of Object.entries(schema)) {
+    const isOptional = field.endsWith("?");
+    const cleanName = isOptional ? field.slice(0, -1) : field;
+    const kebabName = camelToKebab(cleanName);
+    const value = rawOptions[kebabName];
+    if (value === void 0) {
+      if (!isOptional) {
+        throw new Error(`Missing required flag: --${kebabName}`);
+      }
+      continue;
+    }
+    const cleanType = type.toLowerCase().trim();
+    if (cleanType === "number") {
+      const parsed = Number(value);
+      if (isNaN(parsed))
+        throw new Error(`Flag --${kebabName} must be a number`);
+      input[cleanName] = parsed;
+    } else if (cleanType === "boolean") {
+      input[cleanName] = value === true || value === "true";
+    } else {
+      input[cleanName] = String(value);
+    }
+  }
+  return input;
+}
+async function executePluginCommand(command, input, viteServer) {
+  const cliCommand = await loadCommandHandler(command, viteServer);
+  const services = resolveServices(cliCommand.services);
+  return cliCommand.handler(input, ...services);
+}
+async function loadCommandHandler(command, viteServer) {
+  let module;
+  if (command.isLocal) {
+    const moduleFile = command.pluginModule || "index";
+    const modulePath = path.resolve(command.pluginPath, moduleFile);
+    if (viteServer) {
+      module = await viteServer.ssrLoadModule(modulePath);
+    } else {
+      module = await import(modulePath);
+    }
+  } else {
+    if (viteServer) {
+      module = await viteServer.ssrLoadModule(command.packageName);
+    } else {
+      module = await import(command.packageName);
+    }
+  }
+  for (const [, exported] of Object.entries(module)) {
+    if (isJayCliCommand(exported) && exported.commandName === command.commandName) {
+      return exported;
+    }
+  }
+  const byName = module[command.handlerExport];
+  if (byName && isJayCliCommand(byName)) {
+    return byName;
+  }
+  throw new Error(
+    `CLI command "${command.commandName}" not found as export in "${command.isLocal ? command.pluginPath : command.packageName}". Available exports: ${Object.keys(module).join(", ")}`
+  );
+}
 export {
   ActionRegistry,
   DevSlowlyChangingPhase,
@@ -2982,13 +3137,16 @@ export {
   clearLifecycleCallbacks,
   clearServerElementCache,
   clearServiceRegistry,
+  commandSchemaToFlags,
   discoverAllPluginActions,
   discoverAndRegisterActions,
   discoverPluginActions,
+  discoverPluginCommands,
   discoverPluginsWithInit,
   discoverPluginsWithReferences,
   discoverPluginsWithSetup,
   executeAction,
+  executePluginCommand,
   executePluginReferences,
   executePluginServerInits,
   executePluginSetup,
@@ -3015,6 +3173,7 @@ export {
   onShutdown,
   parseActionMetadata,
   parseCookies,
+  parseInputFromFlags,
   preparePluginClientInits,
   registerAction,
   registerService,
@@ -3030,6 +3189,5 @@ export {
   setClientInitData,
   slowRenderInstances,
   sortPluginsByDependencies,
-  tagIdentityKey,
-  validateForEachInstances
+  tagIdentityKey
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/stack-server-runtime",
-  "version": "0.17.4",
+  "version": "0.18.0",
   "license": "Apache-2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.mts",
@@ -26,21 +26,21 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-html": "^0.17.4",
-    "@jay-framework/compiler-shared": "^0.17.4",
-    "@jay-framework/component": "^0.17.4",
-    "@jay-framework/fullstack-component": "^0.17.4",
-    "@jay-framework/logger": "^0.17.4",
-    "@jay-framework/runtime": "^0.17.4",
-    "@jay-framework/ssr-runtime": "^0.17.4",
-    "@jay-framework/stack-route-scanner": "^0.17.4",
-    "@jay-framework/view-state-merge": "^0.17.4",
+    "@jay-framework/compiler-jay-html": "^0.18.0",
+    "@jay-framework/compiler-shared": "^0.18.0",
+    "@jay-framework/component": "^0.18.0",
+    "@jay-framework/fullstack-component": "^0.18.0",
+    "@jay-framework/logger": "^0.18.0",
+    "@jay-framework/runtime": "^0.18.0",
+    "@jay-framework/ssr-runtime": "^0.18.0",
+    "@jay-framework/stack-route-scanner": "^0.18.0",
+    "@jay-framework/view-state-merge": "^0.18.0",
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.17.4",
-    "@jay-framework/jay-cli": "^0.17.4",
-    "@jay-framework/stack-client-runtime": "^0.17.4",
+    "@jay-framework/dev-environment": "^0.18.0",
+    "@jay-framework/jay-cli": "^0.18.0",
+    "@jay-framework/stack-client-runtime": "^0.18.0",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",