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

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/plugin-structure.md

@@ -0,0 +1,194 @@
+# 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)
+
+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"
+  }
+}
+```
+
+### 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.

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

@@ -0,0 +1,116 @@
+# Services and Initialization
+
+Services provide dependency injection for server-side resources (databases, APIs, etc.).
+
+## createJayService
+
+Create a typed service marker:
+
+```typescript
+import { createJayService } from '@jay-framework/fullstack-component';
+
+export interface ProductsDatabase {
+  getProduct(slug: string): Promise<Product | null>;
+  search(query: string): Promise<Product[]>;
+}
+
+export const PRODUCTS_DB = createJayService<ProductsDatabase>('ProductsDatabase');
+```
+
+The marker is a Symbol-based key — it provides type safety without coupling to a specific implementation.
+
+## makeJayInit
+
+Initialize services and client-side state during app startup:
+
+### Server-only init
+
+```typescript
+import { makeJayInit, registerService } from '@jay-framework/fullstack-component';
+
+export const init = makeJayInit().withServer(async () => {
+  const db = await connectToDatabase();
+  registerService(PRODUCTS_DB, db);
+});
+```
+
+### Server + Client init
+
+The server can pass data to the client via the return value:
+
+```typescript
+export const init = makeJayInit()
+  .withServer(async () => {
+    registerService(PRODUCTS_DB, await connectDb());
+    return { currency: 'USD', storeId: 'store-123' };
+  })
+  .withClient((data) => {
+    // data is typed: { currency: string; storeId: string }
+    registerReactiveGlobalContext(STORE_CONFIG, () => ({
+      currency: data.currency,
+      storeId: data.storeId,
+    }));
+  });
+```
+
+### Client-only init
+
+```typescript
+export const init = makeJayInit().withClient(() => {
+  initAnalytics();
+});
+```
+
+## Using Services
+
+### In Components
+
+```typescript
+makeJayStackComponent<MyContract>()
+  .withServices(PRODUCTS_DB)
+  .withSlowlyRender(async (props, db) => {
+    const product = await db.getProduct(props.slug);
+    return phaseOutput({ title: product.name }, {});
+  });
+```
+
+### In Actions
+
+```typescript
+makeJayAction('products.search')
+  .withServices(PRODUCTS_DB)
+  .withHandler(async (input, db) => {
+    return db.search(input.query);
+  });
+```
+
+### In loadParams
+
+```typescript
+.withServices(PRODUCTS_DB)
+.withLoadParams(async function* (db) {
+    const products = await db.getAll();
+    yield products.map(p => ({ slug: p.slug }));
+})
+```
+
+## Listing in plugin.yaml
+
+If your plugin provides services for other plugins to consume, list them in `plugin.yaml`:
+
+```yaml
+services:
+  - name: products-db
+    marker: PRODUCTS_DB
+    description: Product catalog database API (query, search, get by slug)
+    doc: ./docs/products-db-service.md # optional — markdown documentation
+```
+
+This makes the service discoverable in `plugins-index.yaml`. If `doc` is provided, the file must exist and be exported from the package.
+
+## Service Lifecycle
+
+- Services are registered during `makeJayInit().withServer()` callbacks
+- Registration order follows plugin dependency order
+- Services are available to all components and actions after init
+- Services are server-side only — they are not sent to the client