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

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

@@ -0,0 +1,34 @@
+# Jay Stack Developer — Agent Kit
+
+This folder contains guides for building jay-stack projects: project configuration, routing, page components, and wiring plugins together.
+
+## What Does the Developer Role Do?
+
+The developer sets up the project, configures plugins, creates page-level components (`page.ts`), defines page contracts (`page.jay-contract`), and wires everything together. This is distinct from the designer role (creates jay-html UI) and the plugin role (creates reusable headless components).
+
+## Workflow
+
+1. **Set up the project** — `jay-stack setup` to configure plugins
+2. **Define routes** — create page directories under `src/pages/`
+3. **Create page contracts** — `page.jay-contract` for page-level data
+4. **Create page components** — `page.ts` with `makeJayStackComponent`
+5. **Configure services** — `src/init.ts` for project-level services
+6. **Validate** — `jay-stack validate`
+7. **Test** — `jay-stack dev --test-mode`
+
+## Guides
+
+| File                                         | Topic                                                      |
+| -------------------------------------------- | ---------------------------------------------------------- |
+| [project-structure.md](project-structure.md) | Directory layout, configuration files                      |
+| [routing.md](routing.md)                     | Directory-based routing, dynamic routes                    |
+| [configuration.md](configuration.md)         | .jay file, plugin config, init.ts                          |
+| [page-contracts.md](page-contracts.md)       | Page-level contracts (page.jay-contract)                   |
+| [page-components.md](page-components.md)     | page.ts: makeJayStackComponent for pages                   |
+| [component-state.md](component-state.md)     | createSignal, createMemo, createEffect, createDerivedArray |
+| [component-refs.md](component-refs.md)       | Refs, collection refs, element types                       |
+| [component-data.md](component-data.md)       | Immutable data, JSON Patch, patching                       |
+| [render-results.md](render-results.md)       | phaseOutput, RenderPipeline, errors, redirects             |
+| [seo-guide.md](seo-guide.md)                 | SEO head tags: title, meta, OG, canonical via phaseOutput  |
+| [cli-commands.md](cli-commands.md)           | CLI commands: setup, validate, dev, agent-kit              |
+| `../references/<plugin>/`                    | Plugin reference data                                      |

package/agent-kit-template/developer/cli-commands.md

@@ -0,0 +1,228 @@
+# CLI Commands Reference
+
+## jay-stack setup
+
+Run plugin setup. Plugins can create configuration files, generate reference data, and validate their prerequisites.
+
+```bash
+# Run setup for all installed plugins
+jay-stack setup
+
+# Run setup for a specific plugin
+jay-stack setup wix-stores
+
+# Re-run setup (e.g., after config change)
+jay-stack setup wix-data --force
+```
+
+Plugins declare their setup handler in `plugin.yaml`. Setup does two things:
+
+1. **Config templates**: Creates `config/<plugin>.yaml` with placeholder credentials if missing
+2. **Credential validation**: Attempts to initialize services, reports success or failure
+
+Reference data (product catalogs, collection schemas) is generated by `jay-stack agent-kit`, not by setup.
+
+Run this after installing new plugins, before `jay-stack agent-kit`.
+
+## jay-stack agent-kit
+
+Materialize contracts, generate discovery indexes, and produce plugin reference data. Run this after setup.
+
+```bash
+# Default: writes to agent-kit/
+jay-stack agent-kit
+
+# Custom output directory for contracts
+jay-stack agent-kit --output my-output/
+
+# List contracts without writing files
+jay-stack agent-kit --list
+
+# Filter to specific plugin
+jay-stack agent-kit --plugin wix-stores
+
+# Force re-materialization
+jay-stack agent-kit --force
+
+# Skip reference data generation
+jay-stack agent-kit --no-references
+```
+
+Outputs:
+
+- `plugins-index.yaml`
+- `materialized-contracts/<plugin>/*.jay-contract` (dynamic contracts)
+- `references/<plugin>/` — plugin reference data (product catalogs, collection schemas, etc.)
+- Documentation files (INSTRUCTIONS.md and reference docs)
+
+## jay-stack validate
+
+Validate all `.jay-html` and `.jay-contract` files.
+
+```bash
+# Validate entire project
+jay-stack validate
+
+# Validate a specific path
+jay-stack validate src/pages/products/
+
+# Verbose (per-file status)
+jay-stack validate -v
+
+# JSON output
+jay-stack validate --json
+```
+
+Example output:
+
+```
+✅ Jay Stack validation successful!
+Scanned 5 .jay-html files, 3 .jay-contract files
+No errors found.
+```
+
+On failure:
+
+```
+❌ Jay Stack validation failed
+
+Errors:
+  ❌ src/pages/products/page.jay-html
+     Unknown ref "nonExistentRef" - not found in contract
+
+1 error(s) found, 7 file(s) valid.
+```
+
+Always run validate after creating or editing jay-html and contract files.
+
+## jay-stack params
+
+Discover load param values for SSG route generation.
+
+```bash
+# Discover slug values for product pages
+jay-stack params wix-stores/product-page
+
+# YAML output
+jay-stack params wix-stores/product-page --yaml
+
+# Verbose
+jay-stack params wix-stores/product-page -v
+```
+
+Format: `<plugin-name>/<contract-name>`
+
+Example output:
+
+```json
+[
+  { "slug": "ceramic-flower-vase" },
+  { "slug": "blue-running-shoes" },
+  { "slug": "organic-cotton-tshirt" }
+]
+
+✅ Found 3 param combination(s)
+```
+
+Use this to discover what param values exist for dynamic routes like `[slug]`. Only works on contracts whose component has `loadParams`.
+
+## jay-stack action
+
+Run a plugin action from the CLI. Use to discover data for populating pages.
+
+```bash
+# Run with default input
+jay-stack action wix-stores/searchProducts
+
+# Run with input
+jay-stack action wix-stores/searchProducts --input '{"query": "shoes", "limit": 5}'
+
+# YAML output
+jay-stack action wix-stores/getCategories --yaml
+
+# Verbose
+jay-stack action wix-stores/getProductBySlug --input '{"slug": "blue-shirt"}' -v
+```
+
+Format: `<plugin-name>/<action-name>`
+
+Action names are listed in `plugins-index.yaml` under each plugin's `actions:` array. Each action entry includes a `description` and a `path` to the `.jay-action` file. Read the `.jay-action` file to see the full input/output schemas before calling an action.
+
+Example output:
+
+```json
+{
+  "items": [
+    { "_id": "prod-1", "name": "Blue Shirt", "slug": "blue-shirt", "price": 29.99 },
+    { "_id": "prod-2", "name": "Red Hat", "slug": "red-hat", "price": 19.99 }
+  ],
+  "totalCount": 2
+}
+```
+
+If not found, lists available actions:
+
+```
+❌ Action "badName" not found.
+   Available actions: searchProducts, getProductBySlug, getCategories
+```
+
+## jay-stack dev
+
+Start the development server.
+
+```bash
+# Normal dev mode
+jay-stack dev
+
+# Test mode (enables health/shutdown endpoints)
+jay-stack dev --test-mode
+
+# Auto-timeout (implies test mode)
+jay-stack dev --timeout 60
+```
+
+### Test mode endpoints
+
+| Endpoint         | Method | Response                                                        |
+| ---------------- | ------ | --------------------------------------------------------------- |
+| `/_jay/health`   | GET    | `{"status":"ready","port":3300,"editorPort":3301,"uptime":5.2}` |
+| `/_jay/shutdown` | POST   | `{"status":"shutting_down"}`                                    |
+
+### Wait for server ready
+
+Poll the health endpoint:
+
+```bash
+# Bash
+for i in {1..30}; do
+  curl -s http://localhost:3300/_jay/health | grep -q "ready" && break
+  sleep 1
+done
+```
+
+```typescript
+// TypeScript
+async function waitForServer(timeout = 30000): Promise<string> {
+  const start = Date.now();
+  while (Date.now() - start < timeout) {
+    try {
+      const res = await fetch('http://localhost:3300/_jay/health');
+      if (res.ok) {
+        const { port } = await res.json();
+        return `http://localhost:${port}`;
+      }
+    } catch {
+      /* not ready */
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  throw new Error('Server not ready');
+}
+```
+
+### Shutdown
+
+```bash
+curl -X POST http://localhost:3300/_jay/shutdown
+```

package/agent-kit-template/developer/component-data.md

@@ -0,0 +1,109 @@
+# Immutable Data and Patching
+
+In Jay, ViewState data is immutable. Never mutate objects directly — use signals and JSON Patch for updates.
+
+## Immutable Data Model
+
+ViewState objects passed to the render function are immutable snapshots. The framework compares old and new snapshots to determine what changed in the DOM.
+
+```typescript
+// WRONG — never mutate directly
+viewState.items.push(newItem);
+viewState.count = 5;
+
+// RIGHT — return new values from signals
+const [count, setCount] = createSignal(0);
+setCount(5);
+
+return { render: () => ({ count: count() }) };
+```
+
+## JSON Patch for Complex Updates
+
+For objects with many fields, use `createPatchableSignal` with JSON Patch operations instead of replacing the entire object:
+
+```typescript
+import { createPatchableSignal } from '@jay-framework/component';
+import { REPLACE, ADD, REMOVE } from '@jay-framework/json-patch';
+
+const [state, setState, patchState] = createPatchableSignal({
+  title: 'Product',
+  price: 29.99,
+  tags: ['sale', 'featured'],
+  details: { color: 'red', size: 'M' },
+});
+```
+
+### Patch Operations
+
+**REPLACE** — Update an existing value:
+
+```typescript
+patchState({ op: REPLACE, path: ['price'], value: 19.99 });
+patchState({ op: REPLACE, path: ['details', 'color'], value: 'blue' });
+```
+
+**ADD** — Add a new field or array item:
+
+```typescript
+patchState({ op: ADD, path: ['tags', 1], value: 'new-tag' }); // Insert at index 1
+patchState({ op: ADD, path: ['details', 'weight'], value: '500g' });
+```
+
+**REMOVE** — Remove a field or array item:
+
+```typescript
+patchState({ op: REMOVE, path: ['tags', 0] }); // Remove first tag
+patchState({ op: REMOVE, path: ['details', 'size'] });
+```
+
+**MOVE** — Move a value from one path to another:
+
+```typescript
+import { MOVE } from '@jay-framework/json-patch';
+
+patchState({ op: MOVE, from: ['tags', 0], path: ['tags', 2] }); // Reorder array item
+patchState({ op: MOVE, from: ['details', 'color'], path: ['primaryColor'] }); // Relocate field
+```
+
+### Multiple Patches
+
+Apply multiple patches at once — the framework batches them into a single update:
+
+```typescript
+patchState(
+  { op: REPLACE, path: ['price'], value: 19.99 },
+  { op: REPLACE, path: ['details', 'color'], value: 'blue' },
+);
+```
+
+### When to Use Patch vs Set
+
+- **Simple values** (number, string, boolean): use `setSignal(newValue)`
+- **Objects with few fields**: use `setSignal({ ...old, field: newValue })`
+- **Complex nested objects**: use `patchState` for surgical updates
+- **Arrays with identity tracking**: use `patchState` with ADD/REMOVE
+
+## createDerivedArray (Map Hook)
+
+Transform an array reactively with smart caching. Only remaps items that actually changed:
+
+```typescript
+import { createDerivedArray } from '@jay-framework/component';
+
+const displayProducts = createDerivedArray(
+  () => products(),
+  (item, index, length) => ({
+    label: `${item().name} - ${formatPrice(item().price)}`,
+    position: `${index() + 1} of ${length()}`,
+  }),
+);
+```
+
+Key behavior:
+
+- If an item's object identity hasn't changed, the cached mapped result is reused
+- `index()` and `length()` are tracked — if you don't call them, changes to index/length won't trigger a remap
+- Returns a `Getter<U[]>` — read with `displayProducts()`
+
+See [component-state.md](component-state.md) for the full hook reference.

package/agent-kit-template/developer/component-refs.md

@@ -0,0 +1,117 @@
+# Component Refs
+
+Refs provide access to DOM elements declared as `interactive` in the contract. They are the second parameter of the interactive constructor.
+
+## Single Refs
+
+A ref maps to one DOM element:
+
+```yaml
+# Contract
+- tag: addToCart
+  type: interactive
+  elementType: HTMLButtonElement
+```
+
+```typescript
+// Component
+.withInteractive(function MyComp(props, refs) {
+    refs.addToCart.onClick(() => {
+        // handle click
+    });
+})
+```
+
+### Ref Methods
+
+Refs provide type-safe access to the DOM element:
+
+```typescript
+refs.submitButton.onClick(() => {
+  /* ... */
+});
+
+// exec$ gives direct access to the element and current ViewState
+refs.submitButton.exec$((element, viewState) => {
+  element.disabled = viewState.isSubmitting;
+});
+```
+
+## Collection Refs
+
+When an interactive tag is inside a `repeated` sub-contract, the ref becomes a collection. In jay-html, collection refs use the `$` suffix:
+
+```html
+<div forEach="items" trackBy="id">
+  <button ref="itemButton$">Click</button>
+</div>
+```
+
+The `$` is stripped from the name in the contract and component code:
+
+```yaml
+# Contract
+- tag: items
+  type: sub-contract
+  repeated: true
+  trackBy: id
+  tags:
+    - tag: id
+      type: data
+      dataType: string
+    - tag: itemButton
+      type: interactive
+      elementType: HTMLButtonElement
+```
+
+### Collection Ref Methods
+
+```typescript
+// Map over all items in the collection
+const labels = refs.itemButton.map((proxy, viewState, coordinate) => {
+  return viewState.name;
+});
+
+// Find a specific item
+const target = refs.itemButton.find((viewState) => viewState.id === 'target-id');
+
+// Find by coordinate
+const target = refs.itemButton.find((viewState, coordinate) =>
+  sameCoordinate(coordinate, ['item-2', 'itemButton']),
+);
+```
+
+## Element Types
+
+Common element types for interactive tags:
+
+| Element Type          | Use For               |
+| --------------------- | --------------------- |
+| `HTMLButtonElement`   | Buttons, clickable    |
+| `HTMLAnchorElement`   | Links                 |
+| `HTMLInputElement`    | Text inputs, checkbox |
+| `HTMLSelectElement`   | Dropdowns             |
+| `HTMLTextAreaElement` | Multi-line text       |
+| `HTMLFormElement`     | Forms                 |
+| `HTMLDivElement`      | Generic containers    |
+
+Multiple element types (when the same ref may bind to different elements):
+
+```yaml
+- tag: trigger
+  type: interactive
+  elementType: HTMLButtonElement | HTMLAnchorElement
+```
+
+## Data + Interactive
+
+A tag can be both data and interactive:
+
+```yaml
+- tag: quantityInput
+  type: [data, interactive]
+  dataType: number
+  elementType: HTMLInputElement
+```
+
+This generates both a ViewState field and a ref.

package/agent-kit-template/developer/component-state.md

@@ -0,0 +1,140 @@
+# Component State Hooks
+
+All hooks are used inside the interactive phase (the `withInteractive` constructor function). They provide reactive state management for client-side behavior.
+
+## createSignal
+
+Creates a reactive getter/setter pair:
+
+```typescript
+import { createSignal } from '@jay-framework/component';
+
+const [count, setCount] = createSignal(0);
+
+// Read
+count(); // 0
+
+// Write
+setCount(5); // set to 5
+setCount((n) => n + 1); // increment
+```
+
+Can initialize from a getter (reactive dependency):
+
+```typescript
+const [label, setLabel] = createSignal(() => 'Hello ' + props.name());
+```
+
+## createPatchableSignal
+
+Creates a signal with JSON Patch support for fine-grained updates to complex objects:
+
+```typescript
+import { createPatchableSignal } from '@jay-framework/component';
+import { REPLACE } from '@jay-framework/json-patch';
+
+const [data, setData, patchData] = createPatchableSignal({
+  label: 'Hello',
+  count: 0,
+  nested: { value: 42 },
+});
+
+// Patch a specific field
+patchData({ op: REPLACE, path: ['label'], value: 'Updated' });
+
+// Patch nested field
+patchData({ op: REPLACE, path: ['nested', 'value'], value: 99 });
+```
+
+See [component-data.md](component-data.md) for more on immutable data and patching.
+
+## createMemo
+
+Creates a memoized computed value that recalculates only when dependencies change:
+
+```typescript
+import { createMemo } from '@jay-framework/component';
+
+const fullName = createMemo(() => `${firstName()} ${lastName()}`);
+
+// Read
+fullName(); // recomputes only when firstName() or lastName() change
+```
+
+With initial value:
+
+```typescript
+const total = createMemo((prev) => prev + latestValue(), 0);
+```
+
+## createEffect
+
+Registers a side effect that runs on mount and when dependencies change. Optional cleanup function:
+
+```typescript
+import { createEffect } from '@jay-framework/component';
+
+createEffect(() => {
+  const handler = () => setWindowWidth(window.innerWidth);
+  window.addEventListener('resize', handler);
+  return () => window.removeEventListener('resize', handler); // cleanup
+});
+```
+
+Effects track reactive dependencies automatically:
+
+```typescript
+createEffect(() => {
+  document.title = `${count()} items`; // reruns when count() changes
+});
+```
+
+## createDerivedArray
+
+Efficiently maps an array with smart caching. Only remaps items that actually changed:
+
+```typescript
+import { createDerivedArray } from '@jay-framework/component';
+
+const displayItems = createDerivedArray(
+  () => products(),
+  (item, index, length) => ({
+    name: item().name,
+    displayPrice: formatPrice(item().price),
+    isLast: index() === length() - 1,
+  }),
+);
+
+// Read the mapped array
+displayItems();
+```
+
+Key optimizations:
+
+- Reuses mapped items when the source item hasn't changed
+- Only tracks `index()` and `length()` if you actually call them
+- Uses object identity (not deep equality) for cache hits
+
+## createEvent
+
+Creates an event emitter for component-to-parent communication:
+
+```typescript
+import { createEvent } from '@jay-framework/component';
+
+const onChange = createEvent<{ value: number }>((emitter) => {
+  emitter.emit({ value: count() });
+});
+```
+
+## useReactive
+
+Gets the current reactive context for advanced use cases:
+
+```typescript
+import { useReactive } from '@jay-framework/component';
+
+const reactive = useReactive();
+```
+
+Most components won't need this — prefer the higher-level hooks above.

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

@@ -0,0 +1,76 @@
+# Configuration
+
+## .jay File
+
+Optional YAML file at project root configuring the dev server:
+
+```yaml
+devServer:
+  portRange:
+    - 3000
+    - 3100
+  pagesBase: ./src/pages
+  componentsBase: ./src/components
+  publicFolder: ./public
+editorServer:
+  portRange:
+    - 3101
+    - 3200
+```
+
+### Key Fields
+
+- `devServer.pagesBase` — Root directory for pages (default: `./src/pages`)
+- `devServer.componentsBase` — Root directory for components
+- `devServer.publicFolder` — Static assets directory
+- `devServer.portRange` — Port range for the dev server
+
+## Plugin Configuration (config/)
+
+The `config/` folder holds plugin configuration files generated by `jay-stack setup`:
+
+```
+config/
+├── project.conf.yaml       # Project name and metadata
+└── wix-data.yaml           # Plugin-specific config (auto-generated)
+```
+
+Plugins create their config files here during setup. The location is configured via `configBase` in the `.jay` file (defaults to `./config`).
+
+## Project Init (src/init.ts)
+
+The project can have an `init.ts` for project-level initialization:
+
+```typescript
+import { makeJayInit, registerService } from '@jay-framework/fullstack-component';
+
+export const init = makeJayInit()
+  .withServer(async () => {
+    // Register project-level services
+    registerService(MY_SERVICE, createMyService());
+
+    // Return data for client
+    return { locale: 'en-US' };
+  })
+  .withClient((data) => {
+    // Client-side init
+    console.log('Locale:', data.locale);
+  });
+```
+
+Init runs after all plugin inits, in dependency order.
+
+## package.json Scripts
+
+```json
+{
+  "scripts": {
+    "dev": "jay-stack-cli dev",
+    "validate": "jay-stack-cli validate",
+    "definitions": "jay-cli definitions src",
+    "build": "npm run definitions",
+    "setup": "jay-stack-cli setup",
+    "agent-kit": "jay-stack-cli agent-kit"
+  }
+}
+```