@jay-framework/jay-stack-cli 0.15.5 → 0.16.0

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

@@ -0,0 +1,193 @@
+# Contract Authoring Guide
+
+Contracts (`.jay-contract` files) are the source of truth for a component's data shape. Define the contract before implementing the component.
+
+## Basic Structure
+
+```yaml
+name: ProductCard
+description: Displays a single product with price and add-to-cart. Use for product grids and featured sections.
+props:
+  - name: productId
+    type: string
+    required: true
+    description: The product to display
+params:
+  slug: string
+tags:
+  - tag: name
+    type: data
+    dataType: string
+    phase: slow
+```
+
+## Tag Types
+
+### `data` — Read-only values
+
+```yaml
+- tag: productName
+  type: data
+  dataType: string # string (default), number, boolean, date
+  required: true # optional, defaults to false
+  phase: slow # slow, fast, or fast+interactive
+  description: Display name
+```
+
+### `variant` — Enum/boolean for conditionals
+
+```yaml
+- tag: status
+  type: variant
+  dataType: enum (AVAILABLE | OUT_OF_STOCK | PREORDER)
+  phase: fast+interactive
+```
+
+### `interactive` — Element refs for user interaction
+
+```yaml
+- tag: addToCart
+  type: interactive
+  elementType: HTMLButtonElement # HTMLAnchorElement, HTMLInputElement, HTMLSelectElement, etc.
+```
+
+Interactive tags are always `fast+interactive` — do not specify a phase.
+
+A tag can be both data and interactive:
+
+```yaml
+- tag: quantityInput
+  type: [data, interactive]
+  dataType: number
+  elementType: HTMLInputElement
+```
+
+### `sub-contract` — Nested objects
+
+Inline:
+
+```yaml
+- tag: pricing
+  type: sub-contract
+  tags:
+    - tag: amount
+      type: data
+      dataType: number
+    - tag: currency
+      type: data
+      dataType: string
+```
+
+Linked (reference another contract file):
+
+```yaml
+- tag: author
+  type: sub-contract
+  link: ./author.jay-contract
+```
+
+### `sub-contract` with `repeated: true` — Arrays
+
+```yaml
+- tag: items
+  type: sub-contract
+  repeated: true
+  trackBy: id # Required: identifies each item
+  phase: fast
+  tags:
+    - tag: id
+      type: data
+      dataType: string
+    - tag: name
+      type: data
+      dataType: string
+```
+
+`trackBy` must reference a `data` tag with `string` or `number` type within the same sub-contract.
+
+## Async Data
+
+Wrap any tag in `Promise<T>` with `async: true`:
+
+```yaml
+- tag: reviews
+  type: data
+  async: true
+  dataType: string # Compiles to Promise<string>
+
+- tag: relatedProducts
+  type: sub-contract
+  repeated: true
+  trackBy: id
+  async: true # Compiles to Promise<Array<...>>
+  tags:
+    - tag: id
+      type: data
+      dataType: string
+```
+
+## Rendering Phases
+
+Each tag has a phase that determines when its data is available:
+
+| Phase              | When               | Use For                                 |
+| ------------------ | ------------------ | --------------------------------------- |
+| `slow`             | Build time (SSG)   | Static content, SEO data, product names |
+| `fast`             | Request time (SSR) | Per-request data, live pricing, stock   |
+| `fast+interactive` | Request + client   | Data that also updates on the client    |
+
+**How to choose:**
+
+- Can the data be known at build time? Use `slow`
+- Does it change per request (user, time, session)? Use `fast`
+- Does it also update on the client after interaction? Use `fast+interactive`
+- Interactive tags (refs) are always `fast+interactive`
+
+**Phase rules for arrays:** Child phases must be >= parent phase. If the array is `fast`, all children must be `fast` or later.
+
+## Props vs Params
+
+### Props — Component configuration
+
+Props are passed by the parent component or jay-html template. Use for component inputs like IDs, configuration flags, display options.
+
+```yaml
+props:
+  - name: productId
+    type: string
+    required: true
+    description: The product to display
+  - name: showPricing
+    type: boolean
+    default: 'true'
+```
+
+### Params — URL route segments
+
+Params come from dynamic route segments (`[slug]`, `[[lang]]`, `[...path]`). Use for page-level routing data.
+
+```yaml
+params:
+  slug: string # required — from [slug]
+  lang: string? # optional — from [[lang]]
+  path: string[] # catch-all — from [...path]
+```
+
+## Description Field
+
+Always include a `description` at the contract level explaining when to use this contract:
+
+```yaml
+name: product-search
+description: Product listing with filters, sorting, and pagination. Use for search results and category pages.
+```
+
+## Validation Rules
+
+- Tag names must be unique at each level
+- `repeated: true` requires `trackBy`
+- `trackBy` must reference a `data` tag with `string` or `number` type
+- Interactive tags cannot have an explicit `phase`
+- Sub-contracts must have either `tags` (inline) or `link` (external), not both
+- Array children must have phase >= parent phase
+- Prop names must be unique

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

@@ -0,0 +1,210 @@
+# Plugin Structure
+
+A plugin provides headless components, contracts, and actions. It can be a standalone npm package or inline within a project.
+
+## plugin.yaml
+
+The plugin manifest declares all contracts, actions, services, contexts, and configuration:
+
+```yaml
+name: my-plugin
+contracts:
+  - name: product-page
+    contract: product-page.jay-contract
+    component: productPage
+    description: Complete product detail page with SSR
+
+  - name: product-search
+    contract: product-search.jay-contract
+    component: productSearch
+    description: Product listing with filters and pagination
+
+actions:
+  - name: searchProducts
+    action: search-products.jay-action
+  - name: addToCart
+    action: add-to-cart.jay-action
+
+services:
+  - name: my-store
+    marker: MY_STORE_SERVICE_MARKER
+    description: Provides product catalog API (query, filter, sort)
+
+contexts:
+  - name: my-cart
+    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
+  configTemplate:
+    - source: templates/config.yaml
+      target: my-plugin.yaml
+```
+
+### Contract Entry Fields
+
+- `name` — Contract name (used in `contract="..."` in jay-html)
+- `contract` — Path to `.jay-contract` file (relative to plugin root)
+- `component` — Export name of the component (e.g., `productPage`)
+- `description` — What this component does and when to use it
+
+### Action Entry Fields
+
+- `name` — Action name (used with `jay-stack action <plugin>/<action>`)
+- `action` — Path to `.jay-action` metadata file
+
+### Service Entry Fields
+
+- `name` — Service name (for identification in plugins-index)
+- `marker` — Exported service marker constant (e.g., `MY_STORE_SERVICE_MARKER`)
+- `description` — What APIs this service provides
+- `doc` — (optional) Path to a markdown file documenting the service API
+
+Services are server-side APIs created with `createJayService`. Other plugins and page components consume them via `.withServices(MARKER)`.
+
+### Context Entry Fields
+
+- `name` — Context name (for identification in plugins-index)
+- `marker` — Exported context marker constant (e.g., `MY_CART_CONTEXT`)
+- `description` — What reactive state this context provides
+- `doc` — (optional) Path to a markdown file documenting the context API
+
+Contexts are client-side reactive state. Other plugins and page components consume them via `.withContexts(MARKER)`.
+
+### Documentation Files
+
+When `doc` is specified, the markdown file must exist and (for NPM packages) be exported in `package.json`:
+
+```yaml
+services:
+  - name: my-store
+    marker: MY_STORE_SERVICE_MARKER
+    description: Product catalog API
+    doc: ./docs/my-store-service.md
+```
+
+```json
+{
+  "exports": {
+    "./docs/my-store-service.md": "./docs/my-store-service.md"
+  }
+}
+```
+
+### 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)
+- `references` — Reference generator for `jay-stack agent-kit` (generates discovery data)
+- `configTemplate` — Config file templates to copy during setup
+
+## Package Layout
+
+### Standalone NPM Package
+
+```
+my-plugin/
+├── plugin.yaml
+├── package.json
+├── lib/
+│   ├── contracts/
+│   │   ├── product-page.jay-contract
+│   │   └── product-search.jay-contract
+│   ├── actions/
+│   │   ├── search-products.jay-action
+│   │   └── add-to-cart.jay-action
+│   ├── components/
+│   │   ├── product-page.ts
+│   │   └── product-search.ts
+│   ├── services/
+│   │   └── products-db.ts
+│   └── init.ts
+├── agent-kit/                    # Optional: plugin-contributed guides
+│   ├── designer/
+│   │   └── my-plugin-usage.md
+│   └── developer/
+│       └── my-plugin-config.md
+└── dist/
+```
+
+### Inline Plugin (within a project)
+
+```
+my-project/
+├── src/
+│   ├── pages/
+│   │   └── ...
+│   └── plugins/
+│       └── my-plugin/
+│           ├── plugin.yaml
+│           ├── product-page.jay-contract
+│           ├── product-page.ts
+│           └── init.ts
+```
+
+See `examples/jay-stack/fake-shop` for a working example.
+
+## package.json Exports
+
+For NPM packages, declare exports so the framework can resolve the plugin:
+
+```json
+{
+  "name": "@my-org/my-plugin",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./plugin.yaml": "./plugin.yaml"
+  },
+  "files": ["dist", "plugin.yaml", "lib/contracts", "lib/actions"]
+}
+```
+
+## Plugin-Contributed Agent-Kit Guides
+
+A plugin can include guides that are merged into the project's agent-kit during `jay-stack agent-kit`. Create an `agent-kit/` folder with subfolders for each role:
+
+```
+my-plugin/
+└── agent-kit/
+    ├── designer/
+    │   └── my-plugin-usage.md    # How to use contracts in jay-html
+    ├── developer/
+    │   └── my-plugin-config.md   # How to configure the plugin
+    └── plugin/
+        └── my-plugin-extending.md  # How to extend the plugin
+```
+
+## Reference Declarations
+
+Plugins can declare reference data generated by `jay-stack agent-kit`:
+
+```yaml
+# In plugin.yaml
+references:
+  - name: product-catalog
+    description: All products with IDs, slugs, names, and prices
+    file: product-catalog.json
+  - name: collection-schemas
+    description: Collection field schemas for filtering
+    file: collection-schemas.json
+```
+
+The `agent-kit` command generates `references/<plugin>/INDEX.md` from these declarations.