@jay-framework/jay-stack-cli 0.15.6 → 0.16.1

package/agent-kit-template/developer/dev-server-service.md

@@ -0,0 +1,126 @@
+# Dev Server Service API
+
+The dev server exposes a `DevServerService` for design board applications, CLI tools, and plugins. It provides route listing, param discovery, and freeze management.
+
+## Service Marker
+
+Registered as `DEV_SERVER_SERVICE` — injectable in actions and components:
+
+```typescript
+import { DEV_SERVER_SERVICE } from '@jay-framework/dev-server';
+
+export const listAllRoutes = makeJayAction('admin.listRoutes')
+  .withServices(DEV_SERVER_SERVICE)
+  .withHandler(async (_input, devServer) => {
+    return devServer.listRoutes();
+  });
+```
+
+## Direct Access
+
+Also returned from `mkDevServer()` for CLI usage:
+
+```typescript
+const { service } = await mkDevServer(options);
+```
+
+## Routes
+
+### listRoutes()
+
+Returns all page routes in the project:
+
+```typescript
+const routes = service.listRoutes();
+// [{ path: '/products/kitan/[[category]]', jayHtmlPath: '...', compPath: '...' }]
+```
+
+### loadRouteParams(route, onBatch)
+
+Async generator that yields param batches from the route's `loadParams`:
+
+```typescript
+for await (const batch of service.loadRouteParams('/products/kitan/[[category]]')) {
+  console.log(batch); // [{ category: 'shirts' }, { category: 'pants' }]
+}
+```
+
+Returns empty if the route has no `page.ts` or no `loadParams`. Throws if the route doesn't exist.
+
+## Freeze Management
+
+### FreezeStore
+
+Accessible via `service.freezeStore`:
+
+```typescript
+const store = service.freezeStore;
+
+// Save a ViewState snapshot
+const entry = await store.save('/products/kitan', viewState);
+
+// List freezes for a route
+const freezes = await store.list('/products/kitan');
+
+// Get a specific freeze
+const freeze = await store.get('abc123');
+
+// Rename
+await store.rename('abc123', 'in-stock state');
+
+// Delete
+await store.delete('abc123');
+```
+
+## Editor Protocol
+
+These APIs are also exposed via the editor protocol (Socket.IO) for design board applications:
+
+| Protocol Message  | Service Method                            |
+| ----------------- | ----------------------------------------- |
+| `listRoutes`      | `service.listRoutes()`                    |
+| `listFreezes`     | `service.freezeStore.list(route)`         |
+| `renameFreeze`    | `service.freezeStore.rename(id, name)`    |
+| `deleteFreeze`    | `service.freezeStore.delete(id)`          |
+| `loadRouteParams` | `service.loadRouteParams(route, onBatch)` |
+
+### Streaming Events
+
+`loadRouteParams` streams batches via `routeParamsBatch` socket events:
+
+```typescript
+// Client sends: { type: 'loadRouteParams', route: '/products/[slug]' }
+// Server responds: { type: 'loadRouteParams', success: true }
+// Server emits:   { type: 'routeParamsBatch', route: '...', params: [...], hasMore: true }
+// Server emits:   { type: 'routeParamsBatch', route: '...', params: [...], hasMore: true }
+// Server emits:   { type: 'routeParamsBatch', route: '...', params: [], hasMore: false }
+```
+
+### Freeze Changed Event
+
+The `freezeChanged` socket event is emitted when jay-html or CSS files change. Design board applications should listen for this to refresh their frozen views:
+
+```typescript
+socket.on('freezeChanged', () => {
+  // Re-fetch frozen page fragments
+});
+```
+
+## Iframe / Embed Mode
+
+When a page is loaded inside an iframe with `?_jay_embed=true` (e.g., by the AIditor), the Alt+S shortcut is disabled (parent owns it). Freeze is triggered via `postMessage`:
+
+```typescript
+// Parent → iframe: request freeze
+iframe.contentWindow.postMessage({ type: 'jay:requestFreeze' }, '*');
+
+// Iframe → parent: freeze done
+// { type: 'jay:freeze', id: string, route: string }
+```
+
+The parent constructs the frozen page URL:
+
+```
+route + '?_jay_freeze=' + id                        // full page
+route + '?_jay_freeze=' + id + '&format=fragment'   // shadow DOM fragment
+```

package/agent-kit-template/developer/page-components.md

@@ -81,6 +81,37 @@ export const page = makeJayStackComponent<ProductPageContract>()
   });
 ```
 
+## Calling File Upload Actions
+
+Actions created with `.withFiles()` accept browser `File` objects directly. Use `oninput` events on file inputs to drive signals, then pass them to the action:
+
+```typescript
+import { createSignal } from '@jay-framework/component';
+import { uploadPhoto } from '../actions/upload.actions';
+
+.withInteractive(function UploadPage(props, refs, fastViewState) {
+    const [result, setResult] = createSignal('');
+    const [selectedFile, setSelectedFile] = createSignal<File | undefined>(undefined);
+
+    refs.fileInput.oninput(({ event }) => {
+        setSelectedFile((event.target as HTMLInputElement).files?.[0]);
+    });
+
+    refs.uploadBtn.onclick(async () => {
+        const file = selectedFile();
+        if (!file) return;
+        const res = await uploadPhoto({ caption: 'My photo', photo: file });
+        setResult(res.message);
+    });
+
+    return {
+        render: () => ({ result: result() }),
+    };
+})
+```
+
+No casting needed — browser `File` is assignable to `JayFile`.
+
 ## Combining with Headless Plugins
 
 A page component handles page-level data. Plugin headless components handle their own data independently. Both render into the same page:

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

@@ -159,3 +159,17 @@ URL query parameters (`?page=2&sort=price`) are available in the **fast render p
 - `props.query` is `Record<string, string>` — empty `{}` when no query string
 - 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
+
+## 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.
+
+Plugin routes appear alongside project routes. If your project defines the same route path in `src/pages/`, your page takes precedence — the plugin's page is skipped.
+
+To override a plugin route, simply create a page at the same path:
+
+```
+# Plugin provides /admin/products
+# To customize, create:
+src/pages/admin/products/page.jay-html
+```

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

@@ -1,18 +1,19 @@
 # Jay Plugin Development — Agent Kit
 
-This folder contains guides for creating jay-stack plugins: contracts, headless components, server actions, and services.
+This folder contains guides for creating jay-stack plugins: contracts, headless components, server actions, services, and plugin-provided routes.
 
 ## What is a Jay Plugin?
 
-A plugin provides headless components (data + interactions, no UI) that project designers use via contracts. Plugins can be standalone npm packages or inline within a project (see `examples/jay-stack/fake-shop`).
+A plugin provides headless components (data + interactions, no UI) that project designers use via contracts. Plugins can also provide complete pages (backoffice tools, admin dashboards) via routes. Plugins can be standalone npm packages or inline within a project (see `examples/jay-stack/fake-shop`).
 
 ## Workflow
 
 1. **Define contracts first** — the contract is the source of truth
 2. **Implement components** matching the contracts
 3. **Define actions** with `.jay-action` metadata
-4. **Set up `plugin.yaml`**
-5. **Validate** with `jay-stack validate-plugin`
+4. **Optionally add routes** — pages for admin tools and dashboards
+5. **Set up `plugin.yaml`** — list contracts, actions, services, contexts, routes
+6. **Validate** with `jay-stack validate-plugin`
 
 ## Guides
 
@@ -28,8 +29,10 @@ A plugin provides headless components (data + interactions, no UI) that project
 | [render-results.md](render-results.md)           | phaseOutput, RenderPipeline, errors, redirects                          |
 | [actions-guide.md](actions-guide.md)             | makeJayAction, makeJayQuery, .jay-action files                          |
 | [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               |
 | [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                                                   |
 
 ## Key Principles

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

@@ -38,12 +38,99 @@ 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)
   .withHandler(async (input, svc1, svc2) => {
     // Define handler
     return result;
   });
 ```
 
+## .withFiles() — File Uploads
+
+Actions can receive binary files (images, documents, etc.) via multipart/form-data.
+Add `.withFiles()` to the builder chain to enable file uploads.
+
+```typescript
+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)
+  .withHandler(async (input: { caption: string; photo: JayFile }) => {
+    // JayFile provides: name, type, size, path (temp file on disk)
+    const data = fs.readFileSync(input.photo.path);
+    // Process file...
+    return { fileName: input.photo.name, size: input.photo.size };
+    // Temp file is automatically cleaned up after handler returns
+  });
+```
+
+### JayFile type
+
+```typescript
+interface JayFile {
+  name: string; // Original filename
+  type: string; // MIME type (e.g., 'image/png')
+  size: number; // File size in bytes
+  path: string; // Absolute path to temp file on disk
+}
+```
+
+### Multiple files
+
+Use an array type for the field — files with the same field name are grouped:
+
+```typescript
+.withHandler(async (input: { images: JayFile[] }) => {
+    for (const img of input.images) {
+      // Process each file
+    }
+});
+```
+
+**File fields must be top-level properties** — not nested inside objects. Dynamic file fields via index signatures are supported:
+
+```typescript
+{ notes: string; screenshot: JayFile; extras: JayFile[] }           // OK
+{ notes: string; [key: string]: string | JayFile | undefined }      // OK
+{ meta: { photo: JayFile } }                                        // NOT supported
+```
+
+### Streaming with files
+
+`makeJayStream` also supports `.withFiles()`:
+
+```typescript
+export const processImages = makeJayStream('images.process')
+  .withFiles()
+  .withHandler(async function* (input: { images: JayFile[] }) {
+    for (const img of input.images) {
+      yield { step: 'processing', fileName: img.name };
+    }
+    yield { step: 'done' };
+  });
+```
+
+### Client-side usage
+
+The client automatically sends `FormData` when `File` or `Blob` objects are present:
+
+```typescript
+refs.uploadBtn.onClick(async () => {
+  const fileInput = refs.fileInput.element as HTMLInputElement;
+  const file = fileInput.files?.[0];
+  const result = await uploadPhoto({ caption: 'My photo', photo: file });
+});
+```
+
+### 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:
@@ -109,17 +196,106 @@ outputSchema:
 | `prop: string`            | Required string           |
 | `prop?: number`           | Optional number           |
 | `prop: boolean`           | Required boolean          |
+| `prop: file`              | File upload (`JayFile`)   |
+| `prop: file[]`            | Multiple file uploads     |
 | `prop: enum(a \| b \| c)` | Required enum             |
 | `prop:` + nested block    | Nested object             |
 | `prop:` + `- child: type` | Array of objects          |
 | `prop: record(T)`         | Record with typed values  |
 | `prop: importedName`      | Type from `import:` block |
 
+## makeJayStream — Streaming (POST, NDJSON)
+
+Streaming actions return an async generator that yields chunks:
+
+```typescript
+import { makeJayStream } from '@jay-framework/fullstack-component';
+
+export const discoverParams = makeJayStream('routes.discoverParams')
+  .withServices(PRODUCTS_SERVICE)
+  .withHandler(async function* (input: { route: string }, productsService) {
+    let page = 1;
+    while (true) {
+      const products = await productsService.list({ page, pageSize: 100 });
+      yield products.map((p) => ({ slug: p.slug }));
+      if (!products.hasMore) break;
+      page++;
+    }
+  });
+```
+
+### Consuming on the client
+
+```typescript
+for await (const batch of discoverParams({ route: '/products/[slug]' })) {
+  console.log(batch); // [{ slug: 'item-a' }, { slug: 'item-b' }]
+}
+```
+
+### Wire format
+
+The server responds with NDJSON (newline-delimited JSON). Each line is a complete JSON object:
+
+```
+{"chunk":[{"slug":"item-a"},{"slug":"item-b"}]}
+{"chunk":[{"slug":"item-c"}]}
+{"done":true}
+```
+
+### .jay-action for streaming
+
+Add `streaming: true` to the metadata file:
+
+```yaml
+name: discoverParams
+description: Discover URL params by querying the product catalog
+streaming: true
+inputSchema:
+  route: string
+outputSchema:
+  - slug: string
+```
+
+### .jay-action for file uploads
+
+Use `file` type for upload fields. The generated TypeScript uses `JayFile`:
+
+```yaml
+name: uploadPhoto
+description: Upload a product photo with caption
+inputSchema:
+  caption: string
+  photo: file
+  attachments?: file[]
+outputSchema:
+  fileId: string
+  message: string
+```
+
+For dynamic file fields, use `record(file)`:
+
+```yaml
+name: submitTask
+description: Submit task with named file attachments
+inputSchema:
+  notes: string
+  files: record(file)
+```
+
+This generates `files: Record<string, JayFile>`.
+
 ## Type Helpers
 
 ```typescript
-import { ActionInput, ActionOutput, isJayAction } from '@jay-framework/fullstack-component';
+import {
+  ActionInput,
+  ActionOutput,
+  isJayAction,
+  StreamChunk,
+  isJayStreamAction,
+} from '@jay-framework/fullstack-component';
 
 type SearchInput = ActionInput<typeof searchProducts>;
 type SearchOutput = ActionOutput<typeof searchProducts>;
+type ParamBatch = StreamChunk<typeof discoverParams>;
 ```

package/agent-kit-template/plugin/dev-server-service.md

@@ -0,0 +1,137 @@
+# Dev Server Service API
+
+The dev server exposes a `DevServerService` for plugins, design board applications, and CLI tools. It provides route listing, param discovery, and freeze management.
+
+## Service Marker
+
+Registered as `DEV_SERVER_SERVICE` — inject in actions and components:
+
+```typescript
+import { DEV_SERVER_SERVICE } from '@jay-framework/dev-server';
+
+export const listAllRoutes = makeJayAction('admin.listRoutes')
+  .withServices(DEV_SERVER_SERVICE)
+  .withHandler(async (_input, devServer) => {
+    return devServer.listRoutes();
+  });
+```
+
+Or in a component:
+
+```typescript
+makeJayStackComponent()
+  .withServices(DEV_SERVER_SERVICE)
+  .withFastRender(async (_props, devServer) => {
+    const routes = devServer.listRoutes();
+    return phaseOutput({ routes, routeCount: routes.length }, {});
+  });
+```
+
+## Direct Access
+
+Also returned from `mkDevServer()` for CLI usage:
+
+```typescript
+const { service } = await mkDevServer(options);
+```
+
+## Routes
+
+### listRoutes()
+
+Returns all page routes in the project (including plugin-provided routes):
+
+```typescript
+const routes = service.listRoutes();
+// [{ path: '/products/kitan/[[category]]', jayHtmlPath: '...', compPath: '...' }]
+```
+
+### loadRouteParams(route)
+
+Async generator that yields param batches from the route's `loadParams`:
+
+```typescript
+for await (const batch of service.loadRouteParams('/products/kitan/[[category]]')) {
+  console.log(batch); // [{ category: 'shirts' }, { category: 'pants' }]
+}
+```
+
+Returns empty if the route has no `page.ts` or no `loadParams`. Throws if the route doesn't exist.
+
+## Freeze Management
+
+### FreezeStore
+
+Accessible via `service.freezeStore`:
+
+```typescript
+const store = service.freezeStore;
+
+// Save a ViewState snapshot
+const entry = await store.save('/products/kitan', viewState);
+
+// List freezes for a route
+const freezes = await store.list('/products/kitan');
+
+// Get a specific freeze
+const freeze = await store.get('abc123');
+
+// Rename
+await store.rename('abc123', 'in-stock state');
+
+// Delete
+await store.delete('abc123');
+```
+
+## Editor Protocol
+
+These APIs are also exposed via the editor protocol (Socket.IO) for design board applications:
+
+| Protocol Message  | Service Method                            |
+| ----------------- | ----------------------------------------- |
+| `listRoutes`      | `service.listRoutes()`                    |
+| `listFreezes`     | `service.freezeStore.list(route)`         |
+| `renameFreeze`    | `service.freezeStore.rename(id, name)`    |
+| `deleteFreeze`    | `service.freezeStore.delete(id)`          |
+| `loadRouteParams` | `service.loadRouteParams(route, onBatch)` |
+
+### Streaming Events
+
+`loadRouteParams` streams batches via `routeParamsBatch` socket events:
+
+```typescript
+// Client sends: { type: 'loadRouteParams', route: '/products/[slug]' }
+// Server responds: { type: 'loadRouteParams', success: true }
+// Server emits:   { type: 'routeParamsBatch', route: '...', params: [...], hasMore: true }
+// Server emits:   { type: 'routeParamsBatch', route: '...', params: [...], hasMore: true }
+// Server emits:   { type: 'routeParamsBatch', route: '...', params: [], hasMore: false }
+```
+
+### Freeze Changed Event
+
+The `freezeChanged` socket event is emitted when jay-html or CSS files change. Design board applications should listen for this to refresh their frozen views:
+
+```typescript
+socket.on('freezeChanged', () => {
+  // Re-fetch frozen page fragments
+});
+```
+
+## Iframe / Embed Mode
+
+When a page is loaded inside an iframe with `?_jay_embed=true` (e.g., by the AIditor), the Alt+S shortcut is disabled (parent owns it). Freeze is triggered via `postMessage`:
+
+```typescript
+// Parent → iframe: request freeze
+iframe.contentWindow.postMessage({ type: 'jay:requestFreeze' }, '*');
+
+// Iframe → parent: freeze done
+// { type: 'jay:freeze', id: string, route: string }
+```
+
+The parent constructs the frozen page URL:
+
+```
+route + '?_jay_freeze=' + id                        // full page
+route + '?_jay_freeze=' + id + '&format=fragment'   // shadow DOM fragment
+```

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

@@ -0,0 +1,146 @@
+# Plugin Routes
+
+Plugins can provide complete pages served by the dev server. This is designed for backoffice tools, admin dashboards, and editors — pages with a boxed design that doesn't need per-site visual customization.
+
+## When to Use Plugin Routes
+
+- **Admin dashboards** — product management, analytics, settings
+- **Editor tools** — visual page editors, contract browsers
+- **Developer tools** — debugging panels, state inspectors
+
+Plugin routes are NOT for end-user pages that need visual customization per site. For those, provide headless components and let the project create its own pages.
+
+## Creating a Plugin Route
+
+A plugin route is a **headless component + jay-html template + route path**. It uses the same rendering pipeline as project pages.
+
+### 1. Create the jay-html template
+
+```html
+<!-- pages/admin/page.jay-html -->
+<html>
+  <head>
+    <script type="application/jay-data">
+      data:
+          title: string
+          items:
+              - name: string
+                count: number
+    </script>
+    <style>
+      .admin {
+        max-width: 800px;
+        margin: 0 auto;
+        padding: 20px;
+        font-family: system-ui;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="admin">
+      <h1>{title}</h1>
+      <div forEach="items" trackBy="name"><span>{name}</span>: <strong>{count}</strong></div>
+    </div>
+  </body>
+</html>
+```
+
+### 2. Create the page component
+
+```typescript
+// pages/admin/page.ts
+import { makeJayStackComponent, phaseOutput } from '@jay-framework/fullstack-component';
+import { MY_SERVICE, MyService } from '../../services';
+
+export const page = makeJayStackComponent()
+  .withProps<{}>()
+  .withServices(MY_SERVICE)
+  .withFastRender(async (_props, myService: MyService) => {
+    const data = await myService.getDashboardData();
+    return phaseOutput({ title: 'Admin Dashboard', items: data.items }, {});
+  });
+```
+
+The page component follows the same pattern as any `makeJayStackComponent` — supports `withSlowlyRender`, `withFastRender`, `withInteractive`, `withLoadParams`, and `withServices`.
+
+### 3. Declare the route in plugin.yaml
+
+```yaml
+name: my-plugin
+routes:
+  - path: /admin/dashboard
+    jayHtml: ./pages/admin/page.jay-html
+    component: ./pages/admin/page.ts
+    description: Admin dashboard showing key metrics
+```
+
+For local plugins, `jayHtml` and `component` are relative paths. For NPM packages, use `package.json` export subpaths.
+
+### 4. For NPM packages — export the page files
+
+```json
+{
+  "exports": {
+    "./admin-dashboard.jay-html": "./dist/pages/admin/page.jay-html",
+    "./admin-dashboard.css": "./dist/pages/admin/page.css"
+  }
+}
+```
+
+Then reference the export subpath in plugin.yaml:
+
+```yaml
+routes:
+  - path: /admin/dashboard
+    jayHtml: admin-dashboard.jay-html
+    css: admin-dashboard.css
+    component: adminDashboard
+```
+
+## Route Parameters
+
+Plugin routes support the same parameter patterns as project routes:
+
+```yaml
+routes:
+  - path: /admin/products/[id]
+    jayHtml: ./pages/product-detail/page.jay-html
+    component: ./pages/product-detail/page.ts
+```
+
+The page component can use `withLoadParams` for SSG parameter discovery:
+
+```typescript
+export const page = makeJayStackComponent()
+  .withProps<{}>()
+  .withServices(PRODUCTS_SERVICE)
+  .withLoadParams<{ id: string }>(async function* (productsService) {
+    const products = await productsService.listAll();
+    yield products.map((p) => ({ id: p.id }));
+  })
+  .withSlowlyRender(async (props: { id: string }, productsService) => {
+    const product = await productsService.getById(props.id);
+    return phaseOutput({ name: product.name, price: product.price }, {});
+  });
+```
+
+## Route Priority
+
+Project routes always take precedence. If the project creates a page at the same path, the plugin's route is skipped:
+
+```
+src/pages/admin/dashboard/page.jay-html   ← project wins
+plugin provides /admin/dashboard          ← skipped
+```
+
+This lets projects override any plugin page without modifying the plugin.
+
+## Prefix Convention
+
+Each plugin should choose a recognizable route prefix to avoid collisions:
+
+- `/admin/...` — admin tools
+- `/aiditor/...` — AIditor editor
+- `/cms/...` — content management
+
+There is no enforced convention — just pick a prefix that's unique and descriptive.

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

@@ -35,6 +35,12 @@ contexts:
     marker: MY_CART_CONTEXT
     description: Client-side cart state (add/remove items, totals)
 
+routes:
+  - path: /admin/dashboard
+    jayHtml: ./pages/admin/page.jay-html
+    component: ./pages/admin/page.ts
+    description: Admin dashboard with product stats
+
 setup:
   handler: setup-handler
   references: references-handler
@@ -93,6 +99,16 @@ services:
 }
 ```
 
+### Route Entry Fields
+
+- `path` — Route path (e.g., `/admin/products`, `/dashboard/[section]`)
+- `jayHtml` — Path to the page's jay-html template (relative to plugin root, or export subpath for NPM)
+- `css` — (optional) Path to the page's CSS file
+- `component` — Path to the page component (relative to plugin root, or exported member name for NPM)
+- `description` — What this page does
+
+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.
+
 ### Setup Fields
 
 - `handler` — Setup handler for `jay-stack setup` (handles config, credentials)

package/dist/index.js

@@ -2441,7 +2441,7 @@ async function startDevServer(options = {}) {
   editorServer.onGetProjectInfo(handlers.onGetProjectInfo);
   editorServer.onExport(handlers.onExport);
   editorServer.onImport(handlers.onImport);
-  const { server, viteServer, routes } = await mkDevServer({
+  const { server, viteServer, routes, service } = await mkDevServer({
     pagesRootFolder: path.resolve(resolvedConfig.devServer.pagesBase),
     projectRootFolder: process.cwd(),
     publicBaseUrlPath: "/",
@@ -2450,6 +2450,73 @@ async function startDevServer(options = {}) {
     httpServer
   });
   app.use(server);
+  const { freezeStore } = service;
+  editorServer.onListRoutes(async () => ({
+    type: "listRoutes",
+    success: true,
+    routes: service.listRoutes()
+  }));
+  if (freezeStore) {
+    editorServer.onListFreezes(async (params) => ({
+      type: "listFreezes",
+      success: true,
+      freezes: (await freezeStore.list(params.route)).map(
+        ({ id, name, route, routePattern, createdAt }) => ({
+          id,
+          name,
+          route,
+          routePattern,
+          createdAt
+        })
+      )
+    }));
+    editorServer.onRenameFreeze(async (params) => ({
+      type: "renameFreeze",
+      success: await freezeStore.rename(params.id, params.name)
+    }));
+    editorServer.onDeleteFreeze(async (params) => ({
+      type: "deleteFreeze",
+      success: await freezeStore.delete(params.id)
+    }));
+    viteServer.watcher.on("change", (changedPath) => {
+      if (changedPath.endsWith(".jay-html") || changedPath.endsWith(".css")) {
+        editorServer.emitFreezeChanged();
+      }
+    });
+  }
+  editorServer.onLoadRouteParams(async (params) => {
+    const routePath = params.route;
+    try {
+      (async () => {
+        try {
+          for await (const batch of service.loadRouteParams(routePath)) {
+            editorServer.emitRouteParamsBatch({
+              type: "routeParamsBatch",
+              route: routePath,
+              params: batch,
+              hasMore: true
+            });
+          }
+          editorServer.emitRouteParamsBatch({
+            type: "routeParamsBatch",
+            route: routePath,
+            params: [],
+            hasMore: false
+          });
+        } catch (err) {
+          editorServer.emitRouteParamsBatch({
+            type: "routeParamsBatch",
+            route: routePath,
+            params: [],
+            hasMore: false
+          });
+        }
+      })();
+      return { type: "loadRouteParams", success: true };
+    } catch (err) {
+      return { type: "loadRouteParams", success: false, error: err.message };
+    }
+  });
   const publicPath = path.resolve(resolvedConfig.devServer.publicFolder);
   if (fs.existsSync(publicPath)) {
     app.use(express.static(publicPath));
@@ -3067,6 +3134,52 @@ async function validateSchema(context, result) {
       });
     }
   }
+  if (manifest.routes) {
+    if (!Array.isArray(manifest.routes)) {
+      result.errors.push({
+        type: "schema",
+        message: 'Field "routes" must be an array',
+        location: "plugin.yaml"
+      });
+    } else {
+      manifest.routes.forEach((route, index) => {
+        if (!route.path) {
+          result.errors.push({
+            type: "schema",
+            message: `Route at index ${index} is missing "path" field`,
+            location: "plugin.yaml"
+          });
+        }
+        if (!route.jayHtml) {
+          result.errors.push({
+            type: "schema",
+            message: `Route "${route.path || index}" is missing "jayHtml" field`,
+            location: "plugin.yaml",
+            suggestion: "Specify the export subpath for the jay-html file"
+          });
+        }
+        if (!route.component) {
+          result.errors.push({
+            type: "schema",
+            message: `Route "${route.path || index}" is missing "component" field`,
+            location: "plugin.yaml",
+            suggestion: "Specify the exported member name for the page component"
+          });
+        }
+        if (route.jayHtml) {
+          validateDocFile(
+            route.jayHtml,
+            `route "${route.path}" jayHtml`,
+            context,
+            result
+          );
+        }
+        if (route.css) {
+          validateDocFile(route.css, `route "${route.path}" css`, context, result);
+        }
+      });
+    }
+  }
 }
 function resolveContractFile(contractSpec, context) {
   if (context.isNpmPackage) {
@@ -4239,15 +4352,29 @@ async function runAction(actionRef, options, projectRoot, initializeServices) {
 async function runParams(contractRef, options, projectRoot, initializeServices) {
   let viteServer;
   try {
-    const slashIndex = contractRef.indexOf("/");
-    if (slashIndex === -1) {
-      getLogger().error(
-        chalk.red("❌ Invalid contract reference. Use format: <plugin>/<contract>")
-      );
-      process.exit(1);
+    let pluginName;
+    let contractName;
+    if (contractRef.startsWith("@")) {
+      const secondSlash = contractRef.indexOf("/", contractRef.indexOf("/") + 1);
+      if (secondSlash === -1) {
+        getLogger().error(
+          chalk.red("❌ Invalid contract reference. Use format: @scope/plugin/contract")
+        );
+        process.exit(1);
+      }
+      pluginName = contractRef.substring(0, secondSlash);
+      contractName = contractRef.substring(secondSlash + 1);
+    } else {
+      const slashIndex = contractRef.indexOf("/");
+      if (slashIndex === -1) {
+        getLogger().error(
+          chalk.red("❌ Invalid contract reference. Use format: <plugin>/<contract>")
+        );
+        process.exit(1);
+      }
+      pluginName = contractRef.substring(0, slashIndex);
+      contractName = contractRef.substring(slashIndex + 1);
     }
-    const pluginName = contractRef.substring(0, slashIndex);
-    const contractName = contractRef.substring(slashIndex + 1);
     if (options.verbose) {
       getLogger().info("Starting Vite for TypeScript support...");
     }
@@ -4282,21 +4409,21 @@ async function runParams(contractRef, options, projectRoot, initializeServices)
     }
     const { resolveServices } = await import("@jay-framework/stack-server-runtime");
     const resolvedServices = resolveServices(component.services || []);
-    const allParams = [];
     const paramsGenerator = component.loadParams(resolvedServices);
+    let total = 0;
     for await (const batch of paramsGenerator) {
-      allParams.push(...batch);
-    }
-    if (options.yaml) {
-      getLogger().important(YAML.stringify(allParams));
-    } else {
-      getLogger().important(JSON.stringify(allParams, null, 2));
+      for (const params of batch) {
+        if (options.yaml) {
+          getLogger().important(YAML.stringify([params]).trimEnd());
+        } else {
+          getLogger().important(JSON.stringify(params));
+        }
+        total++;
+      }
     }
     if (!options.yaml) {
-      getLogger().important(
-        chalk.green(`
-✅ Found ${allParams.length} param combination(s)`)
-      );
+      getLogger().important(chalk.green(`
+✅ Found ${total} param combination(s)`));
     }
   } catch (error) {
     getLogger().error(chalk.red("❌ Failed to discover params:") + " " + error.message);
@@ -4671,8 +4798,8 @@ program.command("action <plugin/action>").description(
   await runAction(actionRef, options, process.cwd(), initializeServicesForCli);
 });
 program.command("params <plugin/contract>").description(
-  "Discover load param values for a contract (e.g., jay-stack params wix-stores/product-page)"
-).option("--yaml", "Output result as YAML instead of JSON").option("-v, --verbose", "Show detailed output").action(async (contractRef, options) => {
+  "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) => {
   await runParams(contractRef, options, process.cwd(), initializeServicesForCli);
 });
 program.parse(process.argv);

package/package.json

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