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

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-refs.md

@@ -31,9 +31,13 @@ refs.submitButton.onClick(() => {
   /* ... */
 });
 
-// exec$ gives direct access to the element and current ViewState
-refs.submitButton.exec$((element, viewState) => {
-  element.disabled = viewState.isSubmitting;
+// exec$ gives direct access to the element and current ViewState.
+// Only use exec$ inside event handlers — never at top-level component
+// creation or in effects, because elements don't exist yet at that point.
+refs.submitButton.onclick(() => {
+  refs.submitButton.exec$((element, viewState) => {
+    element.disabled = viewState.isSubmitting;
+  });
 });
 ```
 

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

@@ -35,6 +35,10 @@ actions:
   - name: addToCart
     action: add-to-cart.jay-action
 
+webhooks:
+  - name: onProductChange
+  - name: onInventoryUpdate
+
 services:
   - name: my-store
     marker: MY_STORE_SERVICE_MARKER
@@ -51,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
@@ -114,6 +124,12 @@ tags:
 - `name` — Action name (used with `jay-stack action <plugin>/<action>`)
 - `action` — Path to `.jay-action` metadata file
 
+### Webhook Entry Fields
+
+- `name` — Export name of the `makeWebhook()` constant (e.g., `onProductChange`)
+
+Webhooks are exposed at `POST /_jay/webhooks/{webhookName}` on the renderer server. The `webhookName` comes from the `makeWebhook('plugin.event-name')` call, not from the export name. The export name in plugin.yaml tells the framework which export to load from the plugin module.
+
 ### Service Entry Fields
 
 - `name` — Service name (for identification in plugins-index)
@@ -162,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)
@@ -183,6 +206,10 @@ my-plugin/
 │   ├── actions/
 │   │   ├── search-products.jay-action
 │   │   └── add-to-cart.jay-action
+│   ├── commands/
+│   │   └── upload-public.jay-command
+│   ├── webhooks/
+│   │   └── on-product-change.ts
 │   ├── components/
 │   │   ├── product-page.ts
 │   │   └── product-search.ts

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/agent-kit-template/plugin/webhooks-guide.md

@@ -0,0 +1,124 @@
+# Webhooks & Data Change Invalidation
+
+Webhooks let external systems (CMS, database, etc.) notify the renderer server when data changes, triggering targeted rebuilds of affected pages.
+
+## makeWebhook
+
+```typescript
+import { makeWebhook } from '@jay-framework/fullstack-component';
+
+export const onProductChange = makeWebhook('wix-stores.product-change')
+  .withServices(PRODUCTS_SERVICE)
+  .withHandler(async (event, invalidate, productsService) => {
+    const slug = await productsService.resolveSlug(event.payload.itemId);
+    await invalidate('product-page', { slug });
+  });
+```
+
+## Builder API
+
+```typescript
+makeWebhook('plugin-name.event-name')
+  .withServices(SERVICE1, SERVICE2) // Inject services
+  .withHandler(async (event, invalidate, svc1, svc2) => {
+    // event.type — webhook name
+    // event.payload — parsed JSON body from the HTTP request
+    // event.headers — HTTP headers
+    // invalidate(contractName, params?) — trigger rebuild
+  });
+```
+
+## The invalidate Function
+
+The `invalidate` callback resolves contract names to routes and rebuilds affected instances:
+
+```typescript
+// Rebuild a specific instance — finds routes using 'product-page' contract,
+// rebuilds the instance matching { slug: 'blue-widget' }
+await invalidate('product-page', { slug: 'blue-widget' });
+
+// Rebuild ALL instances of routes using 'search-results' contract
+await invalidate('search-results');
+```
+
+**Contract-based, not route-based.** A plugin knows its own contract names but not the project's route structure. The framework resolves which routes use each contract via the `contracts` field in the route manifest.
+
+## Declaring in plugin.yaml
+
+```yaml
+webhooks:
+  - name: onProductChange
+  - name: onInventoryUpdate
+```
+
+The `name` field is the **export name** from the plugin module. The webhook URL is derived from the `makeWebhook()` name argument, not the export name.
+
+## URL Mapping
+
+Webhooks are exposed on the renderer server at:
+
+```
+POST /_jay/webhooks/{webhookName}
+```
+
+Where `{webhookName}` is the first argument to `makeWebhook()`. Example:
+
+```
+makeWebhook('wix-stores.product-change')
+  → POST /_jay/webhooks/wix-stores.product-change
+```
+
+## Optimistic Skip
+
+After re-running the slow render, the framework compares the new pre-rendered jay-html with the existing one. If the template structure is unchanged (e.g., a price change updates ViewState but doesn't toggle a slow conditional), the server element compilation and Vite client build are skipped.
+
+## Project Webhooks
+
+Projects can define webhooks in `src/webhooks/`:
+
+```typescript
+// src/webhooks/on-content-update.ts
+import { makeWebhook } from '@jay-framework/fullstack-component';
+
+export const onContentUpdate = makeWebhook('cms.content-update').withHandler(
+  async (event, invalidate) => {
+    const { pageSlug } = event.payload as { pageSlug: string };
+    await invalidate('content-page', { slug: pageSlug });
+  },
+);
+```
+
+Project webhooks don't need plugin.yaml — they are discovered by scanning compiled files in `server/webhooks/`.
+
+## CLI Rebuild
+
+For manual or CI-triggered rebuilds without a webhook:
+
+```bash
+# By contract — rebuild all routes using this contract
+jay-stack rebuild --contract product-page
+
+# By contract + params — rebuild specific instance
+jay-stack rebuild --contract product-page --params '{"slug":"blue-widget"}'
+
+# By route — rebuild all instances of a route (useful for pages with page.ts, no contract)
+jay-stack rebuild --route /products/[slug]
+
+# By route + params — rebuild specific instance
+jay-stack rebuild --route /products/[slug] --params '{"slug":"blue-widget"}'
+
+# By URL — resolve URL to route+params, rebuild that instance
+jay-stack rebuild --url /products/blue-widget
+```
+
+## Renderer Server
+
+The renderer server (`jay-stack serve --role=renderer`) hosts webhook endpoints and a rebuild API:
+
+```
+POST /_jay/webhooks/:name    — Webhook handler (plugin-defined)
+POST /_jay/rebuild           — Programmatic rebuild { contract, route, url, params }
+GET  /_jay/status            — Health check + build info
+```
+
+The `POST /_jay/rebuild` endpoint accepts one of `contract`, `route`, or `url` in the JSON body.