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

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

@@ -0,0 +1,112 @@
+# Render Results
+
+Each rendering phase (slow, fast) returns a render result indicating success, error, or redirect.
+
+## phaseOutput — Success
+
+Returns ViewState data and optional carry-forward data for the next phase:
+
+```typescript
+import { phaseOutput } from '@jay-framework/fullstack-component';
+
+return phaseOutput(
+  { title: 'My Product', price: 29.99 }, // ViewState — sent to template
+  { productId: 'abc123' }, // CarryForward — passed to next phase only
+);
+```
+
+CarryForward is available in the next phase via `props.carryForward` but is not part of the ViewState.
+
+## Error Results
+
+Return errors to stop rendering and show an error page:
+
+```typescript
+import {
+  notFound,
+  badRequest,
+  unauthorized,
+  forbidden,
+  serverError5xx,
+  clientError4xx,
+} from '@jay-framework/fullstack-component';
+
+// 404
+if (!product) return notFound('Product not found');
+
+// 400
+if (!input.query) return badRequest('Query is required');
+
+// 401
+if (!session) return unauthorized('Please log in');
+
+// 403
+if (!canAccess) return forbidden('Access denied');
+
+// Custom 4xx
+return clientError4xx(429, 'Rate limit exceeded');
+
+// 5xx
+return serverError5xx(500, 'Database connection failed');
+```
+
+## Redirects
+
+```typescript
+import { redirect3xx } from '@jay-framework/fullstack-component';
+
+return redirect3xx(301, '/new-location');
+return redirect3xx(302, `/products/${product.slug}`);
+```
+
+## RenderPipeline — Composable Rendering
+
+For complex render logic, `RenderPipeline` chains operations with automatic error propagation:
+
+```typescript
+import { RenderPipeline } from '@jay-framework/fullstack-component';
+
+const Pipeline = RenderPipeline.for<SlowViewState, CarryForward>();
+
+return Pipeline.try(() => db.getProduct(props.slug))
+  .map((product) => product ?? Pipeline.notFound('Product not found'))
+  .map(async (product) => ({
+    ...product,
+    reviews: await db.getReviews(product.id),
+  }))
+  .toPhaseOutput((product) => ({
+    viewState: { title: product.name, price: product.price },
+    carryForward: { productId: product.id },
+  }));
+```
+
+### Pipeline Factory Methods
+
+```typescript
+const P = RenderPipeline.for<VS, CF>();
+
+P.ok(value); // Wrap a value
+P.try(() => fetchData()); // Wrap a function (catches errors)
+P.from(previousPhaseResult); // Continue from a prior phase result
+P.notFound('message'); // Error pipeline
+P.badRequest('message'); // Error pipeline
+P.unauthorized('message'); // Error pipeline
+P.forbidden('message'); // Error pipeline
+P.serverError(500, 'message'); // Error pipeline
+P.redirect(301, '/path'); // Redirect pipeline
+```
+
+### Pipeline Chain Methods
+
+```typescript
+pipeline
+    .map(value => transform(value))           // Transform the value
+    .map(async value => await asyncOp(value)) // Async transform
+    .recover(error => P.ok(fallbackValue))    // Recover from errors
+    .toPhaseOutput(value => ({                // Convert to PhaseOutput
+        viewState: { ... },
+        carryForward: { ... },
+    }));
+```
+
+Errors short-circuit — if any step returns an error pipeline, subsequent `.map()` calls are skipped.

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

@@ -0,0 +1,161 @@
+# Directory-Based Routing
+
+## Route Structure
+
+Pages live under `src/pages/`. Directory names become URL segments.
+
+```
+src/pages/
+├── page.jay-html                    → /
+├── about/
+│   └── page.jay-html                → /about
+├── products/
+│   ├── page.jay-html                → /products
+│   └── [slug]/
+│       └── page.jay-html            → /products/:slug
+├── blog/
+│   ├── page.jay-html                → /blog
+│   └── [[slug]]/
+│       └── page.jay-html            → /blog/:slug  (optional)
+└── files/
+    └── [...path]/
+        └── page.jay-html            → /files/*  (catch-all)
+```
+
+## Dynamic Routes
+
+| Syntax       | Meaning            | Example                                 |
+| ------------ | ------------------ | --------------------------------------- |
+| `[param]`    | Required parameter | `[slug]` → `/products/:slug`            |
+| `[[param]]`  | Optional parameter | `[[slug]]` → `/blog` or `/blog/my-post` |
+| `[...param]` | Catch-all          | `[...path]` → matches any sub-path      |
+
+## Route Priority
+
+Static routes match before dynamic routes (most specific first):
+
+1. **Static segments** (exact match) — highest priority
+2. **`[param]`** — required dynamic param
+3. **`[[param]]`** — optional param
+4. **`[...param]`** — catch-all — lowest priority
+
+## Static Route Overrides
+
+A static route can override a dynamic route for a specific URL — giving one particular page a custom layout while the dynamic route handles everything else:
+
+```
+src/pages/products/
+├── [slug]/page.jay-html              # dynamic: /products/:slug
+└── ceramic-flower-vase/page.jay-html # static override for this specific product
+```
+
+The static `ceramic-flower-vase/` route takes priority over `[slug]/` for that URL, but all other product URLs still use the dynamic route.
+
+### Static Override Params (`jay-params`)
+
+Static override routes often use the same contract as the dynamic route they override. Since the static route has no dynamic directory segment, the params must be declared explicitly using `<script type="application/jay-params">`:
+
+```html
+<!-- src/pages/products/ceramic-flower-vase/page.jay-html -->
+<html>
+  <head>
+    <script type="application/jay-params">
+      slug: ceramic-flower-vase
+    </script>
+    <script
+      type="application/jay-headless"
+      plugin="wix-stores"
+      contract="product-page"
+      key="product"
+    ></script>
+  </head>
+  <body>
+    <h1>{product.productName}</h1>
+  </body>
+</html>
+```
+
+The script body is YAML. The declared params are passed to the component as if extracted from a dynamic URL segment. Without this, the component would receive no param values.
+
+## Page Files
+
+Each page directory can contain:
+
+| File                | Purpose                             |
+| ------------------- | ----------------------------------- |
+| `page.jay-html`     | Template (required for rendering)   |
+| `page.jay-contract` | Page-level data contract (optional) |
+
+### page.jay-contract
+
+Defines the page's own ViewState — data that the page's server-side code provides:
+
+```yaml
+name: Page
+tags:
+  - tag: title
+    type: data
+    dataType: string
+    phase: slow
+  - tag: items
+    type: sub-contract
+    repeated: true
+    trackBy: id
+    tags:
+      - tag: id
+        type: data
+        dataType: string
+      - tag: name
+        type: data
+        dataType: string
+```
+
+## Dynamic Routes and Contract Params
+
+When a component on the page — whether the page contract, a headless component, or a headfull full-stack component — declares `params`, the page should be placed in a dynamic route directory that provides those params.
+
+For example, if a headless component's contract declares:
+
+```yaml
+name: product-page
+params:
+  slug: string
+tags:
+  - ...
+```
+
+Then the page using this component should live at a route that provides a `slug` param:
+
+```
+src/pages/products/[slug]/page.jay-html
+```
+
+Multiple components on the same page can each declare params. The route directory must provide all required params across all components. For example, if the page contract requires `lang` and a headless component requires `slug`, the page should live at `src/pages/[lang]/products/[slug]/page.jay-html`.
+
+### Discovering Param Values
+
+For SSG with dynamic routes, the plugin component provides a `loadParams` generator that yields all valid param combinations. Use it to discover what routes will be generated:
+
+```bash
+jay-stack params wix-stores/product-page
+# Output: [{"slug": "blue-shirt"}, {"slug": "red-hat"}, ...]
+```
+
+Params are always strings (URL params).
+
+## Query Parameters
+
+URL query parameters (`?page=2&sort=price`) are available in the **fast render phase only** via `props.query`:
+
+```typescript
+.withFastRender(async (props, carryForward, dbService) => {
+    const page = parseInt(props.query.page || '1');
+    const sort = props.query.sort || 'name';
+    const products = await dbService.getProducts({ page, sort });
+    return phaseOutput({ products, currentPage: page }, {});
+})
+```
+
+- `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

package/agent-kit-template/developer/seo-guide.md

@@ -0,0 +1,93 @@
+# SEO Head Tags
+
+Components inject `<title>`, `<meta>`, `<link>` tags into the HTML `<head>` during SSR by returning `headTags` from `phaseOutput()`.
+
+## Basic Usage
+
+```typescript
+return phaseOutput(
+  { title: product.name, price: product.price },
+  { productId: product.id },
+  {
+    headTags: [
+      { tag: 'title', children: `${product.name} | My Store` },
+      { tag: 'meta', attrs: { name: 'description', content: product.description } },
+      { tag: 'meta', attrs: { property: 'og:title', content: product.name } },
+      { tag: 'meta', attrs: { property: 'og:description', content: product.description } },
+      { tag: 'meta', attrs: { property: 'og:image', content: product.imageUrl } },
+      { tag: 'link', attrs: { rel: 'canonical', href: canonicalUrl } },
+    ],
+  },
+);
+```
+
+## HeadTag Type
+
+```typescript
+interface HeadTag {
+  tag: string; // 'title', 'meta', 'link', etc.
+  attrs?: Record<string, string>; // HTML attributes
+  children?: string; // Text content (for <title>, <script>, etc.)
+}
+```
+
+## Common SEO Tags
+
+```typescript
+// Page title
+{ tag: 'title', children: 'Product Name | Store' }
+
+// Meta description
+{ tag: 'meta', attrs: { name: 'description', content: 'Product description here' } }
+
+// Open Graph
+{ tag: 'meta', attrs: { property: 'og:title', content: 'Product Name' } }
+{ tag: 'meta', attrs: { property: 'og:description', content: 'Description' } }
+{ tag: 'meta', attrs: { property: 'og:image', content: 'https://...' } }
+{ tag: 'meta', attrs: { property: 'og:type', content: 'product' } }
+
+// Twitter Card
+{ tag: 'meta', attrs: { name: 'twitter:card', content: 'summary_large_image' } }
+{ tag: 'meta', attrs: { name: 'twitter:title', content: 'Product Name' } }
+
+// Canonical URL
+{ tag: 'link', attrs: { rel: 'canonical', href: 'https://example.com/products/slug' } }
+
+// JSON-LD structured data
+{ tag: 'script', attrs: { type: 'application/ld+json' }, children: JSON.stringify(structuredData) }
+```
+
+## Mapping Generic SEO Data
+
+If the data source provides a generic structure (array of tags with type/props/children), map it:
+
+```typescript
+const headTags = seoData.tags.map((tag) => ({
+  tag: tag.type,
+  attrs: Object.fromEntries(tag.props.map((p) => [p.key, p.value])),
+  children: tag.children,
+}));
+
+return phaseOutput(viewState, carryForward, { headTags });
+```
+
+## Phase Rules
+
+- Return headTags from **slow** phase for build-time SEO data (product name, description)
+- Return headTags from **fast** phase for per-request data (pricing, availability)
+- Fast phase headTags **replace** slow phase entirely (no merge)
+- No interactive phase — head tags are SSR-only
+
+## Collision Rules
+
+- `<title>` — singleton, last-write-wins
+- `<meta name="X">` — keyed by `name`, last-write-wins
+- `<meta property="X">` — keyed by `property`, last-write-wins
+- `<link rel="canonical">` — singleton, last-write-wins
+- Other tags — always included (no dedup)
+- A warning is logged on collision between different components
+
+## Restrictions
+
+- Head tags from components inside `forEach` are ignored
+- The framework handles HTML escaping automatically

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

@@ -0,0 +1,40 @@
+# Jay Plugin Development — Agent Kit
+
+This folder contains guides for creating jay-stack plugins: contracts, headless components, server actions, and services.
+
+## 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`).
+
+## 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`
+
+## Guides
+
+| File                                             | Topic                                                                   |
+| ------------------------------------------------ | ----------------------------------------------------------------------- |
+| [contracts-guide.md](contracts-guide.md)         | Contract format: tags, types, phases, props, params, sub-contracts      |
+| [plugin-structure.md](plugin-structure.md)       | plugin.yaml, package layout, exports                                    |
+| [component-structure.md](component-structure.md) | makeJayStackComponent, builder API, three-phase rendering               |
+| [component-state.md](component-state.md)         | createSignal, createMemo, createEffect, createDerivedArray, createEvent |
+| [component-refs.md](component-refs.md)           | Refs, collection refs, element types                                    |
+| [component-data.md](component-data.md)           | Immutable data, JSON Patch, createPatchableSignal                       |
+| [component-context.md](component-context.md)     | Context hooks: provide, reactive, global                                |
+| [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                                           |
+| [seo-guide.md](seo-guide.md)                     | SEO head tags: title, meta, OG, canonical via phaseOutput               |
+| [validation.md](validation.md)                   | jay-stack validate-plugin usage                                         |
+| `../references/<plugin>/`                        | Plugin reference data                                                   |
+
+## Key Principles
+
+- **Contract is the source of truth** — define it before implementing the component
+- **Data is immutable** — never mutate ViewState directly, use JSON Patch
+- **Phase-aware** — choose the right rendering phase for each piece of data
+- **Props for configuration, params for URLs** — props are passed by parent components, params come from route segments

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

@@ -0,0 +1,125 @@
+# Server Actions
+
+Actions provide RPC-style server endpoints for client-to-server communication.
+
+## makeJayAction — Mutations (POST)
+
+```typescript
+import { makeJayAction } from '@jay-framework/fullstack-component';
+
+export const addToCart = makeJayAction('cart.addToCart')
+  .withServices(CART_SERVICE)
+  .withHandler(async (input: { productId: string; quantity: number }, cartService) => {
+    const cart = await cartService.addItem(input.productId, input.quantity);
+    return { cartItemCount: cart.items.length };
+  });
+```
+
+## makeJayQuery — Reads (GET)
+
+Queries use GET and support caching:
+
+```typescript
+import { makeJayQuery } from '@jay-framework/fullstack-component';
+
+export const searchProducts = makeJayQuery('products.search')
+  .withServices(PRODUCTS_SERVICE)
+  .withCaching({ maxAge: 60 })
+  .withHandler(async (input: { query: string; page?: number }, productsDb) => {
+    const results = await productsDb.search(input.query, input.page);
+    return { products: results.items, totalCount: results.total };
+  });
+```
+
+## Builder API
+
+```typescript
+makeJayAction('name')
+  .withServices(SERVICE1, SERVICE2) // Inject services
+  .withMethod('PUT') // Override HTTP method (default: POST for actions)
+  .withCaching({ maxAge: 60 }) // Enable caching (queries only)
+  .withHandler(async (input, svc1, svc2) => {
+    // Define handler
+    return result;
+  });
+```
+
+## ActionError
+
+Throw typed errors from action handlers:
+
+```typescript
+import { ActionError } from '@jay-framework/fullstack-component';
+
+throw new ActionError('OUT_OF_STOCK', 'Only 2 units available');
+throw new ActionError('INVALID_INPUT', 'Product ID is required');
+```
+
+## Calling Actions from Client
+
+Actions are callable functions on the client:
+
+```typescript
+.withInteractive(function MyComp(props, refs) {
+    refs.addToCart.onClick(async () => {
+        const result = await addToCart({
+            productId: props.productId,
+            quantity: 1,
+        });
+        // result.cartItemCount
+    });
+})
+```
+
+## Calling Actions from Server
+
+When called from server-side code (e.g., within a render phase), services are automatically injected — no network call is made.
+
+## .jay-action Metadata Files
+
+Each action should have a `.jay-action` file describing its input/output schemas for agent discovery:
+
+```yaml
+name: searchProducts
+description: Search products with text, filters, sorting, and pagination
+
+import:
+  productCard: product-card.jay-contract
+
+inputSchema:
+  query: string
+  filters?:
+    inStockOnly?: boolean
+    minPrice?: number
+    maxPrice?: number
+  sortBy?: enum(relevance | price_asc | price_desc)
+  pageSize?: number
+
+outputSchema:
+  products:
+    - productCard
+  totalCount: number
+  hasMore: boolean
+```
+
+### Jay-Type Notation for Schemas
+
+| Notation                  | Meaning                   |
+| ------------------------- | ------------------------- |
+| `prop: string`            | Required string           |
+| `prop?: number`           | Optional number           |
+| `prop: boolean`           | Required boolean          |
+| `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 |
+
+## Type Helpers
+
+```typescript
+import { ActionInput, ActionOutput, isJayAction } from '@jay-framework/fullstack-component';
+
+type SearchInput = ActionInput<typeof searchProducts>;
+type SearchOutput = ActionOutput<typeof searchProducts>;
+```

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

@@ -0,0 +1,103 @@
+# Component Context
+
+Context provides a way to share state between components without passing props through every level.
+
+## Context Markers
+
+Create a typed marker to identify a context:
+
+```typescript
+import { createContextMarker } from '@jay-framework/component';
+
+interface CartContext {
+  itemCount: () => number;
+  addItem: (productId: string) => void;
+}
+
+const CART_CONTEXT = createContextMarker<CartContext>('CartContext');
+```
+
+## provideContext
+
+Provide a non-reactive context value to child components:
+
+```typescript
+import { provideContext } from '@jay-framework/component';
+
+provideContext(CART_CONTEXT, {
+  itemCount: () => items().length,
+  addItem: (id) => addToCartAction({ productId: id }),
+});
+```
+
+## provideReactiveContext
+
+Provide a reactive context — the factory function has access to hooks:
+
+```typescript
+import { provideReactiveContext, createSignal } from '@jay-framework/component';
+
+const cartCtx = provideReactiveContext(CART_CONTEXT, () => {
+  const [items, setItems] = createSignal<CartItem[]>([]);
+  return {
+    itemCount: () => items().length,
+    addItem: (id) => setItems((prev) => [...prev, { productId: id }]),
+  };
+});
+```
+
+The returned value is the context instance, usable in the same component.
+
+## registerReactiveGlobalContext
+
+Register a context globally during client initialization (in `makeJayInit`):
+
+```typescript
+import { registerReactiveGlobalContext, createSignal } from '@jay-framework/component';
+
+export const init = makeJayInit().withClient(() => {
+  registerReactiveGlobalContext(CART_CONTEXT, () => {
+    const [items, setItems] = createSignal<CartItem[]>([]);
+    return {
+      itemCount: () => items().length,
+      addItem: (id) => setItems((prev) => [...prev, { productId: id }]),
+    };
+  });
+});
+```
+
+Global contexts are available to all components without explicit providing.
+
+## Consuming Context
+
+Components consume contexts via `.withContexts()` on the builder:
+
+```typescript
+makeJayStackComponent<MyContract>()
+  .withContexts(CART_CONTEXT)
+  .withInteractive(function MyComp(props, refs, cartCtx) {
+    refs.addToCart.onClick(() => {
+      cartCtx.addItem(props.productId);
+    });
+
+    return {
+      render: () => ({
+        cartCount: cartCtx.itemCount(),
+      }),
+    };
+  });
+```
+
+## Listing in plugin.yaml
+
+If your plugin provides contexts for other plugins to consume, list them in `plugin.yaml`:
+
+```yaml
+contexts:
+  - name: cart
+    marker: CART_CONTEXT
+    description: Client-side cart state (item count, add/remove items, totals)
+    doc: ./docs/cart-context.md # optional — markdown documentation
+```
+
+This makes the context discoverable in `plugins-index.yaml`. If `doc` is provided, the file must exist and be exported from the package.