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

package/agent-kit-template/developer/render-results.md

@@ -17,6 +17,43 @@ return phaseOutput(
 
 CarryForward is available in the next phase via `props.carryForward` but is not part of the ViewState.
 
+### Response Headers (fast phase only)
+
+The third parameter accepts `responseHeaders` to set HTTP headers on the page response:
+
+```typescript
+return phaseOutput(
+  { memberName: member.name },
+  {},
+  { responseHeaders: { 'Cache-Control': 'no-store' } },
+);
+```
+
+Use this when the page renders per-user data that must not be cached by CDN or browser. Can be combined with `headTags` in the same options object.
+
+### Cookies (fast phase only)
+
+The fast phase receives `props.cookies` — a `Record<string, string>` parsed from the HTTP `Cookie` header:
+
+```typescript
+.withFastRender(async (props, memberService) => {
+    const token = props.cookies['session-token'];
+    if (!token) return redirect3xx(302, '/login');
+
+    const member = await memberService.validate(token);
+    if (!member) return redirect3xx(302, '/login');
+
+    return phaseOutput(
+        { memberName: member.name },
+        {},
+        { responseHeaders: { 'Cache-Control': 'no-store' } },
+    );
+})
+```
+
+- `props.cookies` is `Record<string, string>` — empty `{}` when no cookies
+- Not available in the slow phase (compile error) — same as `props.query`
+
 ## Error Results
 
 Return errors to stop rendering and show an error page:

package/agent-kit-template/developer/routing.md

@@ -160,6 +160,31 @@ URL query parameters (`?page=2&sort=price`) are available in the **fast render p
 - Not available in the slow phase (compile error) — slow results are cached by path params only
 - In the interactive phase, use `new URLSearchParams(window.location.search)` directly
 
+## Cookies
+
+HTTP cookies are available in the **fast render phase only** via `props.cookies`:
+
+```typescript
+.withFastRender(async (props, carryForward, memberService) => {
+    const token = props.cookies['session-token'];
+    if (!token) return redirect3xx(302, '/login');
+
+    const member = await memberService.validate(token);
+    if (!member) return redirect3xx(302, '/login');
+
+    return phaseOutput(
+        { memberName: member.name },
+        {},
+        { responseHeaders: { 'Cache-Control': 'no-store' } },
+    );
+})
+```
+
+- `props.cookies` is `Record<string, string>` — empty `{}` when no cookies
+- Not available in the slow phase (compile error) — same as query params
+- In the interactive phase, use `document.cookie` directly
+- To set response headers (e.g. `Cache-Control: no-store`), use `responseHeaders` in `phaseOutput()` options
+
 ## Plugin Routes
 
 Plugins can provide their own pages via `routes` in `plugin.yaml`. These are backoffice tools, admin dashboards, or editors with boxed designs that don't need per-site customization.

package/agent-kit-template/devops/INSTRUCTIONS.md

@@ -9,15 +9,16 @@ The devops role handles the production lifecycle: building artifacts, configurin
 ## Workflow
 
 1. **Build** — `jay-stack build` to compile all pages into production artifacts
-2. **Deploy** — upload `frontend/` to CDN, deploy `backend/` to server container
+2. **Deploy** — upload `frontend/` to CDN, deploy `backend/` to server container. Plugins can provide deploy commands via `jay-stack run <plugin>/deploy`
 3. **Serve** — start the production server with environment-appropriate flags
 4. **Invalidate** — rebuild specific pages when data changes
+5. **Admin** — run plugin CLI commands via `jay-stack run <plugin>/<command>` (media upload, data sync, cache purge)
 
 ## Guides
 
-| File                                       | Topic                                                    |
-| ------------------------------------------ | -------------------------------------------------------- |
-| [production-build.md](production-build.md) | Build pipeline, output structure, frontend/backend split |
-| [serving-modes.md](serving-modes.md)       | Self-hosted, CDN, BaaS (fetch handler), CLI flags        |
-| [fetch-handler.md](fetch-handler.md)       | @jay-framework/jay-fetch-handler for BaaS integration    |
-| [invalidation.md](invalidation.md)         | Rebuild, renderer server, cleanup                        |
+| File                                       | Topic                                                      |
+| ------------------------------------------ | ---------------------------------------------------------- |
+| [production-build.md](production-build.md) | Build pipeline, output structure, frontend/backend split   |
+| [serving-modes.md](serving-modes.md)       | Self-hosted, CDN, BaaS (fetch handler), CLI flags          |
+| [fetch-handler.md](fetch-handler.md)       | Fetch handler, ArtifactStore interface, BaaS custom stores |
+| [invalidation.md](invalidation.md)         | Rebuild, renderer server, cleanup                          |

package/agent-kit-template/devops/fetch-handler.md

@@ -23,23 +23,45 @@ const handler = createJayFetchHandler(options);
 
 ```typescript
 interface JayFetchHandlerOptions {
-  backendDir: string; // Path to build/v{n}/backend/
+  // Artifact source (one required)
+  backendDir?: string; // Path to build/v{n}/backend/ (creates FilesystemArtifactStore)
+  artifactStore?: ArtifactStore; // Custom store for non-filesystem backends (DL#143)
+
   staticBaseUrl?: string; // Base URL for browser assets (default: '/')
   frontendDir?: string; // When set, serves static files from this directory
+
+  // Pre-imported modules — for bundled entry.mjs (DL#143)
+  plugins?: PreImportedPlugin[];
+  actionModules?: Array<{ module: Record<string, unknown>; name: string }>;
 }
 ```
 
 | Option          | Required | Description                                                                                                                          |
 | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `backendDir`    | Yes      | Path to the backend build directory containing manifest, server modules, and pre-rendered files                                      |
+| `backendDir`    | \*       | Path to the backend build directory. Creates a `FilesystemArtifactStore` internally                                                  |
+| `artifactStore` | \*       | Custom `ArtifactStore` implementation (e.g., cloud storage). Use instead of `backendDir`                                             |
 | `staticBaseUrl` | No       | URL prefix for import maps, CSS links, and client bundles. Set to your CDN URL for external hosting. Default: `/`                    |
 | `frontendDir`   | No       | When provided, the handler serves static files from this directory. Omit for CDN deployments where static files are hosted elsewhere |
+| `plugins`       | No       | Pre-imported plugin init modules. Bypasses filesystem discovery — use for bundled deployments                                        |
+| `actionModules` | No       | Pre-imported action modules. Bypasses filesystem discovery — use for bundled deployments                                             |
 
-## Usage — Wix BaaS
+\* One of `backendDir` or `artifactStore` is required.
+
+## Usage — Self-Hosted
 
 ```typescript
 import { createJayFetchHandler } from '@jay-framework/jay-fetch-handler';
 
+const handler = createJayFetchHandler({
+  backendDir: './build/v1/backend',
+  staticBaseUrl: '/',
+  frontendDir: './build/v1/frontend',
+});
+```
+
+## Usage — CDN Mode
+
+```typescript
 const handler = createJayFetchHandler({
   backendDir: './build/v1/backend',
   staticBaseUrl: 'https://static.parastorage.com/services/my-app/1.0.0/',
@@ -50,6 +72,47 @@ export default { fetch: handler };
 
 The BaaS runtime calls `handler(request)` for each incoming HTTP request.
 
+## Usage — BaaS with Custom Artifact Store
+
+For deployments where backend files are not on the local filesystem (e.g., stored in a cloud database), provide a custom `ArtifactStore` and pre-imported modules:
+
+```typescript
+import { createJayFetchHandler } from '@jay-framework/jay-fetch-handler';
+import { WixDataArtifactStore } from '@jay-framework/wix-baas-adapter';
+import { init as wixStoresInit } from '@jay-framework/wix-stores';
+import * as wixStoresModule from '@jay-framework/wix-stores';
+
+const handler = createJayFetchHandler({
+  artifactStore: new WixDataArtifactStore({
+    collectionId: 'jay-backend-files',
+    cacheDir: '/tmp/jay-backend',
+  }),
+  staticBaseUrl: 'https://static.parastorage.com/services/my-app/1.0.0/',
+  plugins: [{ name: 'wix-stores', init: wixStoresInit }],
+  actionModules: [{ module: wixStoresModule, name: 'wix-stores' }],
+});
+
+export default { fetch: handler };
+```
+
+The `ArtifactStore` interface:
+
+```typescript
+interface ArtifactStore {
+  readManifest(): Promise<RouteManifest>;
+  readCacheData(relativePath: string): Promise<CacheEntry>;
+  readPagePartsConfig(relativePath: string): Promise<any>;
+  loadServerElement(relativePath: string): Promise<ServerElementModule>;
+  loadModule(modulePath: string, local?: boolean): Promise<any>;
+  getAssetPath(relativePath: string): string;
+  getBuildDir(): string;
+}
+```
+
+`loadModule` handles all module loading — server elements, page components, headless components. The `local` flag indicates whether the path is relative to the build directory (`true`) or an npm package (`false`). For filesystem deployments, local modules resolve from `basePath` and npm modules use bare `import()`. BaaS implementations resolve all modules from their pre-bundled registry, ignoring the `local` flag.
+
+For serve-only imports (no build-time dependencies), use `@jay-framework/production-server/serve`.
+
 ## Usage — Cloudflare Workers
 
 ```typescript

package/agent-kit-template/devops/serving-modes.md

@@ -43,6 +43,33 @@ jay-stack serve --port 4000 \
 
 The server generates import maps, CSS links, and client bundle URLs prefixed with `--static-base-url`. It does not serve static files itself.
 
+## BaaS Mode (Custom Artifact Store)
+
+For platforms where backend files are not on the local filesystem (e.g., stored in a cloud database), use `createJayFetchHandler` with a custom `ArtifactStore` and pre-imported modules:
+
+```typescript
+import { createJayFetchHandler } from '@jay-framework/jay-fetch-handler';
+
+const handler = createJayFetchHandler({
+  artifactStore: customStore, // Custom ArtifactStore implementation
+  staticBaseUrl: 'https://cdn.example.com/app/1.0.0/',
+  plugins: [
+    // Pre-imported plugin init modules
+    { name: 'my-plugin', init: myPluginInit },
+  ],
+  actionModules: [
+    // Pre-imported action modules
+    { module: myPluginModule, name: 'my-plugin' },
+  ],
+});
+
+export default { fetch: handler };
+```
+
+Pre-imported modules bypass filesystem discovery — the entry file bundles everything with esbuild. See [fetch-handler.md](fetch-handler.md) for the `ArtifactStore` interface and full BaaS example.
+
+For serve-only imports without build-time dependencies, use `@jay-framework/production-server/serve`.
+
 ## CLI Flags
 
 ### jay-stack serve

package/agent-kit-template/plugin/INSTRUCTIONS.md

@@ -33,6 +33,7 @@ A plugin provides headless components (data + interactions, no UI) that project
 | [services-guide.md](services-guide.md)           | createJayService, makeJayInit                                           |
 | [plugin-routes.md](plugin-routes.md)             | Plugin-provided pages: routes, jay-html templates, page components      |
 | [seo-guide.md](seo-guide.md)                     | SEO head tags: title, meta, OG, canonical via phaseOutput               |
+| [commands-guide.md](commands-guide.md)           | makeCliCommand, .jay-command files, CONSOLE_CONTEXT, jay-stack run      |
 | [validation.md](validation.md)                   | jay-stack validate-plugin usage                                         |
 | [dev-server-service.md](dev-server-service.md)   | Dev server service API: routes, params, freeze management               |
 | `../references/<plugin>/`                        | Plugin reference data                                                   |

package/agent-kit-template/plugin/actions-guide.md

@@ -38,7 +38,7 @@ makeJayAction('name')
   .withServices(SERVICE1, SERVICE2) // Inject services
   .withMethod('PUT') // Override HTTP method (default: POST for actions)
   .withCaching({ maxAge: 60 }) // Enable caching (queries only)
-  .withFiles({ maxFileSize: 5_000_000 }) // Accept file uploads (multipart/form-data)
+  .withFiles() // Accept file uploads (multipart/form-data)
   .withHandler(async (input, svc1, svc2) => {
     // Define handler
     return result;
@@ -55,7 +55,7 @@ import { makeJayAction, type JayFile } from '@jay-framework/fullstack-component'
 import fs from 'fs';
 
 export const uploadPhoto = makeJayAction('photos.upload')
-  .withFiles({ maxFileSize: 5 * 1024 * 1024 }) // 5MB limit, 10 files max (default)
+  .withFiles()
   .withHandler(async (input: { caption: string; photo: JayFile }) => {
     // JayFile provides: name, type, size, path (temp file on disk)
     const data = fs.readFileSync(input.photo.path);
@@ -123,14 +123,6 @@ refs.uploadBtn.onClick(async () => {
 });
 ```
 
-### FileUploadOptions
-
-```typescript
-.withFiles()                                       // Defaults: 10MB per file, 10 files max
-.withFiles({ maxFileSize: 2 * 1024 * 1024 })       // 2MB limit
-.withFiles({ maxFileSize: 20_000_000, maxFiles: 5 }) // 20MB, 5 files
-```
-
 ## ActionError
 
 Throw typed errors from action handlers:

package/agent-kit-template/plugin/commands-guide.md

@@ -0,0 +1,121 @@
+# CLI Commands
+
+Plugins can expose CLI commands for admin and batch operations. Run via `jay-stack run <plugin>/<command>`.
+
+## When to Use
+
+- Media upload (public folder → cloud storage)
+- Data sync (external CMS → local references)
+- Deployment (build artifacts → cloud provider)
+- Cache management (CDN purge, rebuild triggers)
+
+For request-response operations, use [actions](actions-guide.md) instead.
+
+## Creating a Command
+
+### 1. Build the handler
+
+```typescript
+import { makeCliCommand, CONSOLE_CONTEXT } from '@jay-framework/fullstack-component';
+import { MEDIA_SERVICE } from './services';
+
+export const uploadPublic = makeCliCommand('upload-public')
+  .withServices(MEDIA_SERVICE, CONSOLE_CONTEXT)
+  .withHandler(async (input: { folder?: string; dryRun?: boolean }, mediaService, console) => {
+    const path = await import('node:path');
+    const fs = await import('node:fs/promises');
+
+    const dir = path.resolve(console.publicFolder, input.folder || '');
+    const files = await fs.readdir(dir, { recursive: true });
+
+    for (const file of files) {
+      const filePath = path.join(dir, String(file));
+      const stat = await fs.stat(filePath);
+      if (!stat.isFile()) continue;
+
+      if (input.dryRun) {
+        console.log(`[dry-run] Would upload ${file}`);
+        continue;
+      }
+
+      const url = await mediaService.upload(filePath);
+      console.log(`Uploaded ${file} → ${url}`);
+    }
+
+    return { success: true };
+  });
+```
+
+### 2. Create the metadata file
+
+Place `.jay-command` files in a `commands/` folder (alongside `contracts/` and `actions/`):
+
+```yaml
+# commands/upload-public.jay-command
+name: upload-public
+description: Upload public folder files to cloud storage
+
+inputSchema:
+  folder?: string
+  dryRun?: boolean
+```
+
+The `inputSchema` auto-generates CLI flags:
+
+- `folder?: string` → `--folder <value>` (optional)
+- `dryRun?: boolean` → `--dry-run` (optional flag)
+
+Required fields (no `?`) are validated before the handler runs.
+
+### 3. Declare in plugin.yaml
+
+```yaml
+commands:
+  - name: upload-public
+    command: commands/upload-public.jay-command
+```
+
+## `CONSOLE_CONTEXT` Service
+
+A framework-provided service with project info and a logger:
+
+```typescript
+interface ConsoleContext {
+  projectRoot: string;
+  publicFolder: string;
+  build: {
+    frontend: string; // Build output: JS, CSS, public assets
+    backend: string; // Build output: server modules, pre-rendered HTML
+  };
+  verbose: boolean;
+  log: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+}
+```
+
+Request it via `.withServices(CONSOLE_CONTEXT)`. Commands that don't need it simply don't request it.
+
+## Running Commands
+
+```bash
+# Run a command
+jay-stack run media/upload-public --folder images --dry-run
+
+# List all available commands
+jay-stack run --list
+
+# Verbose output
+jay-stack run media/upload-public -v
+```
+
+## Input Type Mapping
+
+| Schema type       | CLI flag                            | Example            |
+| ----------------- | ----------------------------------- | ------------------ |
+| `field: string`   | `--field <value>` (required)        | `--env production` |
+| `field?: string`  | `--field <value>` (optional)        | `--folder images`  |
+| `field?: boolean` | `--field` (optional flag)           | `--dry-run`        |
+| `field: number`   | `--field <value>` (required number) | `--concurrency 4`  |
+
+camelCase names become kebab-case flags: `dryRun` → `--dry-run`.

package/agent-kit-template/plugin/component-structure.md

@@ -87,7 +87,7 @@ CarryForward data is passed to the fast phase but not included in the ViewState.
 
 ### `.withFastRender(fn)` — Request-time rendering
 
-Runs on each request. Receives props (including `query` for query parameters) and carry-forward from slow phase.
+Runs on each request. Receives props (including `query` for query parameters and `cookies` for HTTP cookies) and carry-forward from slow phase. Can set HTTP response headers via `phaseOutput()` options.
 
 ```typescript
 .withFastRender(async (props, db) => {
@@ -96,6 +96,30 @@ Runs on each request. Receives props (including `query` for query parameters) an
 })
 ```
 
+#### Cookies
+
+`props.cookies` is a `Record<string, string>` parsed from the HTTP `Cookie` header. Use for auth checks:
+
+```typescript
+.withFastRender(async (props, memberService) => {
+    const token = props.cookies['session-token'];
+    if (!token) return redirect3xx(302, '/login');
+
+    const member = await memberService.validate(token);
+    if (!member) return redirect3xx(302, '/login');
+
+    return phaseOutput(
+        { isLoggedIn: true, memberName: member.name },
+        {},
+        { responseHeaders: { 'Cache-Control': 'no-store' } },
+    );
+})
+```
+
+- Empty `{}` when no cookies are present
+- Not available in the slow phase (compile error)
+- `responseHeaders` in `phaseOutput()` options sets HTTP headers on the response (e.g. `Cache-Control: no-store` for per-user pages)
+
 ### `.withClientDefaults(fn)` — Defaults for dynamically created forEach items
 
 Required only when the component is used inside a `forEach` where new items can be added on the client. When a user adds a new item to a forEach array, the new instance has no server data — `withClientDefaults` provides the initial ViewState.
@@ -134,7 +158,7 @@ The interactive phase runs in the browser. Use hooks here (see component-state.m
 
 Each phase can return:
 
-- `phaseOutput(viewState, carryForward)` — success
+- `phaseOutput(viewState, carryForward, options?)` — success (options: `{ headTags?, responseHeaders? }`)
 - `notFound()`, `badRequest()`, `unauthorized()`, `forbidden()` — client errors
 - `serverError5xx(status, message)` — server errors
 - `redirect3xx(status, location)` — redirects

package/agent-kit-template/plugin/plugin-structure.md

@@ -55,6 +55,12 @@ routes:
     component: ./pages/admin/page.ts
     description: Admin dashboard with product stats
 
+commands:
+  - name: upload-public
+    command: commands/upload-public.jay-command
+  - name: sync-catalog
+    command: commands/sync-catalog.jay-command
+
 setup:
   handler: setup-handler
   references: references-handler
@@ -172,6 +178,13 @@ services:
 
 Plugin routes are served by the dev server alongside project routes. If a project defines the same route path, the project's page takes precedence.
 
+### Command Entry Fields
+
+- `name` — Command name (used with `jay-stack run <plugin>/<command>`)
+- `command` — (optional) Path to `.jay-command` metadata file (declares description and input schema)
+
+Commands are CLI operations run via `jay-stack run`. Use `makeCliCommand()` to create handlers with service injection. See [commands-guide.md](commands-guide.md).
+
 ### Setup Fields
 
 - `handler` — Setup handler for `jay-stack setup` (handles config, credentials)
@@ -193,6 +206,8 @@ my-plugin/
 │   ├── actions/
 │   │   ├── search-products.jay-action
 │   │   └── add-to-cart.jay-action
+│   ├── commands/
+│   │   └── upload-public.jay-command
 │   ├── webhooks/
 │   │   └── on-product-change.ts
 │   ├── components/

package/agent-kit-template/plugin/render-results.md

@@ -17,6 +17,43 @@ return phaseOutput(
 
 CarryForward is available in the next phase via `props.carryForward` but is not part of the ViewState.
 
+### Response Headers (fast phase only)
+
+The third parameter accepts `responseHeaders` to set HTTP headers on the page response:
+
+```typescript
+return phaseOutput(
+  { memberName: member.name },
+  {},
+  { responseHeaders: { 'Cache-Control': 'no-store' } },
+);
+```
+
+Use this when the component renders per-user data that must not be cached by CDN or browser. Can be combined with `headTags` in the same options object.
+
+### Cookies (fast phase only)
+
+The fast phase receives `props.cookies` — a `Record<string, string>` parsed from the HTTP `Cookie` header:
+
+```typescript
+.withFastRender(async (props, memberService) => {
+    const token = props.cookies['session-token'];
+    if (!token) return redirect3xx(302, '/login');
+
+    const member = await memberService.validate(token);
+    if (!member) return redirect3xx(302, '/login');
+
+    return phaseOutput(
+        { isLoggedIn: true, memberName: member.name },
+        {},
+        { responseHeaders: { 'Cache-Control': 'no-store' } },
+    );
+})
+```
+
+- `props.cookies` is `Record<string, string>` — empty `{}` when no cookies
+- Not available in the slow phase (compile error) — same as `props.query`
+
 ## Error Results
 
 Return errors to stop rendering and show an error page:

package/dist/index.js

@@ -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!`);
@@ -2643,7 +2648,7 @@ async function resolveProductionContext(projectPath, versionOverride) {
     pagesBase = jayConfig?.devServer?.pagesBase || pagesBase;
   } catch {
   }
-  const version = versionOverride ? parseInt(versionOverride, 10) : await resolveVersionFromPackageJson(resolvedPath);
+  const version = versionOverride || await resolveVersionFromPackageJson(resolvedPath);
   return {
     resolvedPath,
     pagesRoot: path$1.resolve(resolvedPath, pagesBase),
@@ -2658,14 +2663,11 @@ async function resolveVersionFromPackageJson(projectRoot) {
       await fs$1.readFile(path$1.join(projectRoot, "package.json"), "utf-8")
     );
     if (pkgJson.version) {
-      const major = parseInt(pkgJson.version.split(".")[0], 10);
-      const minor = parseInt(pkgJson.version.split(".")[1] || "0", 10);
-      const patch = parseInt(pkgJson.version.split(".")[2] || "0", 10);
-      return major * 1e4 + minor * 100 + patch;
+      return pkgJson.version;
     }
   } catch {
   }
-  return 1;
+  return "1";
 }
 function initLogger(verbose) {
   const logLevel = verbose ? "verbose" : "info";
@@ -2750,6 +2752,7 @@ const runProduction = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defin
   __proto__: null,
   initLogger,
   resolveProductionContext,
+  resolveVersionFromPackageJson,
   runBuild,
   runRebuild,
   runServe
@@ -3776,9 +3779,6 @@ const SKIP_ATTRS = /* @__PURE__ */ new Set([
   "if",
   "ref",
   "trackBy",
-  "slowForEach",
-  "jayIndex",
-  "jayTrackBy",
   "when-resolved",
   "when-loading",
   "when-rejected",
@@ -4502,7 +4502,7 @@ function printValidationResult(result, verbose) {
     logger.important(chalk.red(`${result.errors.length} errors found.`));
   }
 }
-const ALL_ROLES = ["designer", "developer", "plugin"];
+const ALL_ROLES = ["designer", "developer", "plugin", "devops"];
 async function runAgentKit(options) {
   const projectRoot = process.cwd();
   const { initErrors, viteServer } = await runMaterialize(
@@ -5029,6 +5029,161 @@ async function runSetup(pluginFilter, options, projectRoot, initializeServices)
     }
   }
 }
+async function runCommand(commandRef, rawArgs, options, projectRoot, initializeServices) {
+  let viteServer;
+  try {
+    const {
+      discoverPluginCommands,
+      commandSchemaToFlags,
+      parseInputFromFlags,
+      executePluginCommand
+    } = await import("@jay-framework/stack-server-runtime");
+    const commands = await discoverPluginCommands({
+      projectRoot,
+      verbose: options.verbose
+    });
+    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);
+    }
+    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("Command failed:") + " " + error.message);
+    if (options.verbose) {
+      getLogger().error(error.stack);
+    }
+    process.exit(1);
+  } finally {
+    if (viteServer) {
+      await viteServer.close();
+    }
+  }
+}
+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) => {
@@ -5115,6 +5270,13 @@ program.command("agent-kit").description("Prepare agent kit: materialize contrac
 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("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);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/jay-stack-cli",
-  "version": "0.17.4",
+  "version": "0.18.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -24,15 +24,15 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-html": "^0.17.4",
-    "@jay-framework/compiler-shared": "^0.17.4",
-    "@jay-framework/dev-server": "^0.17.4",
-    "@jay-framework/editor-server": "^0.17.4",
-    "@jay-framework/fullstack-component": "^0.17.4",
-    "@jay-framework/logger": "^0.17.4",
-    "@jay-framework/plugin-validator": "^0.17.4",
-    "@jay-framework/production-server": "^0.17.4",
-    "@jay-framework/stack-server-runtime": "^0.17.4",
+    "@jay-framework/compiler-jay-html": "^0.18.0",
+    "@jay-framework/compiler-shared": "^0.18.0",
+    "@jay-framework/dev-server": "^0.18.0",
+    "@jay-framework/editor-server": "^0.18.0",
+    "@jay-framework/fullstack-component": "^0.18.0",
+    "@jay-framework/logger": "^0.18.0",
+    "@jay-framework/plugin-validator": "^0.18.0",
+    "@jay-framework/production-server": "^0.18.0",
+    "@jay-framework/stack-server-runtime": "^0.18.0",
     "chalk": "^4.1.2",
     "commander": "^14.0.0",
     "express": "^5.0.1",
@@ -43,7 +43,7 @@
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.17.4",
+    "@jay-framework/dev-environment": "^0.18.0",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",