npm - @jay-framework/jay-stack-cli - Versions diffs - 0.15.4 → 0.15.6 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (36) hide show

package/agent-kit-template/designer/jay-html-template-syntax.md ADDED Viewed

@@ -0,0 +1,203 @@
+# Jay-HTML Template Syntax
+## File Structure
+A `.jay-html` file is standard HTML with jay-specific extensions.
+```html
+<html>
+  <head>
+    <!-- Page contract (optional — defines page-level data) -->
+    <script type="application/jay-data" contract="./page.jay-contract"></script>
+    <!-- Explicit route params (for static override routes) -->
+    <script type="application/jay-params">
+      slug: ceramic-flower-vase
+    </script>
+    <!-- Headless component imports -->
+    <script type="application/jay-headless" plugin="..." contract="..." key="..."></script>
+    <!-- Headfull component imports -->
+    <script type="application/jay-headfull" src="..." names="..." contract="..."></script>
+    <!-- Styles -->
+    <style>
+      /* inline CSS */
+    </style>
+    <link rel="stylesheet" href="../../styles/theme.css" />
+  </head>
+  <body>
+    <!-- Template with data bindings -->
+    <h1>{title}</h1>
+  </body>
+</html>
+```
+## Data Binding
+Use `{expression}` to bind contract data:
+```html
+<h1>{productName}</h1>
+<!-- simple -->
+<span>{product.price}</span>
+<!-- nested via key -->
+<div style="color: {textColor}">{msg}</div>
+<!-- in attributes -->
+<a href="/products/{slug}">{name}</a>
+<!-- interpolated in attr values -->
+```
+## Boolean Attributes
+HTML boolean attributes (`disabled`, `checked`, `hidden`, `readonly`) can be bound to contract data:
+```html
+<button disabled="isSubmitting">Submit</button>
+<!-- disabled when isSubmitting is true -->
+<button disabled="!inStock">Add to Cart</button>
+<!-- disabled when inStock is false -->
+<input type="checkbox" checked="isSelected" />
+<!-- checked when isSelected is true -->
+<div hidden="!isVisible">Content</div>
+<!-- hidden when isVisible is false -->
+```
+- Set the attribute value to a **boolean tag name** — the attribute is present when true, absent when false
+- Use `!` prefix to negate: `disabled="!enabled"` means disabled when enabled is false
+- Without a value (`disabled` alone), the attribute is always present (standard HTML behavior)
+## Conditional Rendering
+Use the `if` attribute to conditionally show elements.
+### Boolean
+```html
+<span if="inStock">In Stock</span> <span if="!inStock">Out of Stock</span>
+```
+### Enum Variant
+No quotes around the value:
+```html
+<div if="type===physical">Ships to your door</div>
+<div if="type!==physical">Not a physical product</div>
+<div if="status===active">Active</div>
+```
+### Numeric Comparisons
+Compare against numbers or other fields:
+```html
+<span if="count > 0">You have {count} items</span>
+<span if="count <= 0">No items</span>
+<button if="currentPage <= 1" disabled>Previous</button>
+<span if="price <= budget">Affordable</span>
+<span if="available >= required">In stock</span>
+```
+Operators: `>`, `<`, `>=`, `<=`, `==`, `!=`
+### Logical AND / OR
+Combine conditions with `&&` and `||`:
+```html
+<div if="inStock && hasDiscount">Great deal!</div>
+<span if="isPromoted || hasDiscount">Has offer</span>
+```
+Use parentheses for complex expressions:
+```html
+<div if="(inStock && hasDiscount) || isPromoted">Buyable</div>
+<div if="inStock && price > 0">Purchasable</div>
+<button if="count <= 0 || isLoading" disabled>Checkout</button>
+```
+### Rules Summary
+- Boolean: `if="flag"` / `if="!flag"`
+- Enum: `if="tag===value"` / `if="tag!==value"` (no quotes around value)
+- Numeric: `if="count > 0"`, `if="price <= budget"`
+- Field comparison: `if="available >= required"`
+- Logical: `if="a && b"`, `if="a || b"`, `if="(a || b) && c"`
+- Negation: `!` prefix on booleans
+## Loops (forEach / trackBy)
+Iterate over repeated sub-contracts:
+```html
+<li forEach="products" trackBy="id">
+  <a href="/products/{slug}">
+    <div>{name}</div>
+    <div>{price}</div>
+  </a>
+</li>
+```
+- `forEach` — the repeated tag name from the contract
+- `trackBy` — stable unique key for each item (must match contract's trackBy)
+- Inside the loop, bindings resolve to the **current item's** tags
+**Nested loops:**
+```html
+<div forEach="options" trackBy="_id">
+  <h3>{name}</h3>
+  <div forEach="choices" trackBy="choiceId">
+    <button ref="choiceButton">{name}</button>
+  </div>
+</div>
+```
+## Refs (Interactions)
+Map elements to contract `interactive` tags using `ref`:
+```html
+<button ref="addToCart">Add to Cart</button>
+<input value="{quantity}" ref="quantityInput" />
+<a ref="productLink" href="/products/{slug}">{name}</a>
+<select ref="sizeSelector">
+  ...
+</select>
+```
+Match the element type to the contract's `elementType`:
+- `HTMLButtonElement` → `<button>`
+- `HTMLInputElement` → `<input>`
+- `HTMLAnchorElement` → `<a>`
+- `HTMLSelectElement` → `<select>`
+**Key-based headless refs** — prefix with the key:
+```html
+<button ref="rating.submitButton">Submit</button> <button ref="mt.happy">+1 Happy</button>
+```
+**Refs inside forEach** — use the tag path from the contract:
+```html
+<div forEach="options" trackBy="_id">
+  <div forEach="choices" trackBy="choiceId">
+    <button ref="choiceButton">{name}</button>
+  </div>
+</div>
+```
+## Page-Level Contract
+A page can define its own data contract:
+```html
+<script type="application/jay-data" contract="./page.jay-contract"></script>
+```
+Tags from the page contract are bound directly (no key prefix).

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

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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.