@jay-framework/jay-stack-cli 0.11.0 → 0.13.0

package/agent-kit-template/contracts-and-plugins.md

@@ -0,0 +1,293 @@
+# Contracts and Plugins
+
+## Discovery: Plugins Index
+
+After running `jay-stack agent-kit`, read `materialized-contracts/plugins-index.yaml`:
+
+```yaml
+materialized_at: '2026-02-09T...'
+jay_stack_version: '1.0.0'
+plugins:
+  - name: wix-stores
+    path: ./node_modules/@wix/stores
+    contracts:
+      - name: product-page
+        type: static
+        path: ./node_modules/@wix/stores/lib/contracts/product-page.jay-contract
+      - name: product-search
+        type: static
+        path: ./node_modules/@wix/stores/lib/contracts/product-search.jay-contract
+    actions:
+      - name: searchProducts
+        description: Search products with text/filter/sort/pagination
+        path: ./node_modules/@wix/stores/lib/actions/search-products.jay-action
+      - name: getProductBySlug
+        description: Get a single product by URL slug
+        path: ./node_modules/@wix/stores/lib/actions/get-product-by-slug.jay-action
+```
+
+Fields:
+
+- `name` — plugin name (use in `plugin="..."` attributes in jay-html)
+- `path` — path to plugin root (relative to project root)
+- `contracts[].name` — contract name (use in `contract="..."` attributes)
+- `contracts[].type` — `static` (defined in source) or `dynamic` (generated at runtime)
+- `contracts[].path` — path to the `.jay-contract` file you can read
+- `actions[].name` — action name (use with `jay-stack action <plugin>/<action>`)
+- `actions[].description` — short description of what the action does
+- `actions[].path` — path to the `.jay-action` file with full input/output schemas
+
+## Discovery: Contracts Index
+
+`materialized-contracts/contracts-index.yaml` lists all contracts across all plugins:
+
+```yaml
+contracts:
+  - plugin: wix-stores
+    name: product-page
+    type: static
+    path: ./node_modules/@wix/stores/lib/contracts/product-page.jay-contract
+```
+
+## Reading plugin.yaml
+
+Each plugin has a `plugin.yaml` at its root (the `path` from plugins-index):
+
+```yaml
+name: wix-stores
+contracts:
+  - name: product-page
+    contract: product-page.jay-contract
+    component: productPage
+    description: Complete headless product page with server-side rendering
+  - name: product-search
+    contract: product-search.jay-contract
+    component: productSearch
+    description: Headless product search page
+actions:
+  - name: searchProducts
+    action: search-products.jay-action
+  - name: getProductBySlug
+    action: get-product-by-slug.jay-action
+  - name: getCategories
+    action: get-categories.jay-action
+```
+
+Key fields:
+
+- `contracts[].name` — use in `contract="..."` in jay-html
+- `contracts[].description` — what the component does (helps you decide which to use)
+- `actions[].name` — action name (use with `jay-stack action <plugin>/<action>`)
+- `actions[].action` — path to `.jay-action` file with full metadata (description, input/output schemas)
+
+## Reading .jay-contract Files
+
+Contracts define the data shape (ViewState), interaction points (Refs), and rendering phases.
+
+### Tag Types
+
+| Type                              | Purpose                          | Jay-HTML Usage                    |
+| --------------------------------- | -------------------------------- | --------------------------------- |
+| `data`                            | Read-only data value             | `{tagName}` binding               |
+| `variant`                         | Enum or boolean for conditions   | `if="tagName===value"`            |
+| `interactive`                     | Element ref for user interaction | `ref="tagName"`                   |
+| `[data, interactive]`             | Both data and interactive        | `{tagName}` + `ref="tagName"`     |
+| `sub-contract`                    | Nested object                    | `{parent.child}`                  |
+| `sub-contract` + `repeated: true` | Array for loops                  | `forEach="tagName" trackBy="..."` |
+
+### Phases
+
+| Phase              | When                     | Example                                   |
+| ------------------ | ------------------------ | ----------------------------------------- |
+| `slow`             | Build time (SSG)         | Product name, description, static content |
+| `fast`             | Request time (SSR)       | Live pricing, stock status                |
+| `fast+interactive` | Request + client updates | Price that updates on variant selection   |
+| _(no phase)_       | All phases               | Available everywhere                      |
+
+### Props
+
+Components that accept props:
+
+```yaml
+props:
+  - name: productId
+    type: string
+    required: true
+    description: The ID of the product to display
+```
+
+Use in jay-html: `<jay:contract-name productId="value">`.
+
+### Params
+
+Page components with dynamic routes:
+
+```yaml
+params:
+  slug: string
+```
+
+Params are always strings. Discover values with `jay-stack params`.
+
+### Linked Sub-Contracts
+
+A sub-contract can reference another contract file:
+
+```yaml
+- tag: mediaGallery
+  type: sub-contract
+  phase: fast+interactive
+  link: ./media-gallery # refers to media-gallery.jay-contract in same directory
+```
+
+Read the linked file to see the nested tags.
+
+## Contract Examples
+
+**Simple component with props:**
+
+```yaml
+name: ProductWidget
+props:
+  - name: productId
+    type: string
+    required: true
+tags:
+  - tag: name
+    type: data
+    dataType: string
+    phase: slow
+  - tag: price
+    type: data
+    dataType: number
+    phase: slow
+  - tag: inStock
+    type: variant
+    dataType: boolean
+    phase: fast+interactive
+  - tag: addToCart
+    type: interactive
+    elementType: HTMLButtonElement
+```
+
+**Page with nested loops:**
+
+```yaml
+name: product-page
+tags:
+  - tag: productName
+    type: data
+    dataType: string
+  - tag: price
+    type: data
+    dataType: string
+    phase: fast+interactive
+  - tag: addToCartButton
+    type: interactive
+    elementType: HTMLButtonElement
+  - tag: options
+    type: sub-contract
+    repeated: true
+    trackBy: _id
+    tags:
+      - tag: _id
+        type: data
+        dataType: string
+      - tag: name
+        type: data
+        dataType: string
+      - tag: choices
+        type: sub-contract
+        repeated: true
+        trackBy: choiceId
+        tags:
+          - tag: choiceId
+            type: data
+            dataType: string
+          - tag: name
+            type: data
+            dataType: string
+          - tag: isSelected
+            type: variant
+            dataType: boolean
+            phase: fast+interactive
+          - tag: choiceButton
+            type: interactive
+            elementType: HTMLButtonElement
+```
+
+## Reading .jay-action Files
+
+Actions with `.jay-action` files have rich metadata: name, description, and typed input/output schemas. Read the file at the `path` from `plugins-index.yaml` (or from `plugin.yaml`'s `actions[].action` field).
+
+### .jay-action Format
+
+```yaml
+name: searchProducts
+description: Search products with text/filter/sort/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
+
+Schemas use a compact type notation:
+
+| Notation | Meaning |
+| --- | --- |
+| `propName: string` | Required string property |
+| `propName?: number` | Optional number property |
+| `propName: boolean` | Required boolean |
+| `propName: enum(a \| b \| c)` | Required enum |
+| `propName:` + nested block | Nested object |
+| `propName:` + `- childProp: type` | Array of objects (YAML list) |
+| `propName: importedName` | Type from `import:` block (references a `.jay-contract`) |
+| `- importedName` | Array of imported type |
+
+### Using Action Metadata
+
+1. **Discovery** — read `plugins-index.yaml` for action names and descriptions
+2. **Details** — read the `.jay-action` file at the path for full input/output schemas
+3. **Run** — use `jay-stack action <plugin>/<action> --input '{...}'` with a JSON body matching the inputSchema
+
+## From Contract to Jay-HTML
+
+### Step by step
+
+1. **Read the contract** — identify tags, their types, and phases
+2. **Map `data` tags** → `{tagName}` bindings
+3. **Map `variant` tags** → `if="tagName===value"` conditions
+4. **Map `interactive` tags** → `ref="tagName"` on appropriate element types
+5. **Map `sub-contract` + `repeated: true`** → `forEach="tagName" trackBy="..."` loops
+6. **Map nested `sub-contract`** → dotted paths or nested context inside forEach
+7. **Respect phases** — don't assume fast-only data is available at build time
+
+### Quick mapping
+
+| Contract Tag                                                     | Jay-HTML                                      |
+| ---------------------------------------------------------------- | --------------------------------------------- |
+| `{tag: title, type: data}`                                       | `<h1>{title}</h1>`                            |
+| `{tag: active, type: variant, dataType: boolean}`                | `<span if="active">Active</span>`             |
+| `{tag: status, type: variant, dataType: "enum (A \| B)"}`        | `<div if="status===A">...</div>`              |
+| `{tag: btn, type: interactive, elementType: HTMLButtonElement}`  | `<button ref="btn">Click</button>`            |
+| `{tag: link, type: interactive, elementType: HTMLAnchorElement}` | `<a ref="link">Go</a>`                        |
+| `{tag: input, type: interactive, elementType: HTMLInputElement}` | `<input ref="input" value="{val}" />`         |
+| `{tag: sel, type: interactive, elementType: HTMLSelectElement}`  | `<select ref="sel">...</select>`              |
+| `{tag: items, type: sub-contract, repeated: true, trackBy: id}`  | `<div forEach="items" trackBy="id">...</div>` |
+| `{tag: detail, type: sub-contract}`                              | `{detail.fieldName}`                          |

package/agent-kit-template/jay-html-syntax.md

@@ -0,0 +1,312 @@
+# Jay-HTML Syntax Reference
+
+## 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>
+
+    <!-- Headless component imports -->
+    <script type="application/jay-headless" plugin="..." contract="..." key="..."></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 -->
+```
+
+## Conditional Rendering
+
+Use the `if` attribute:
+
+```html
+<span if="inStock">In Stock</span>
+<span if="!inStock">Out of Stock</span>
+<div if="type===physical">Ships to your door</div>
+<div if="type===virtual">Instant download</div>
+```
+
+Rules:
+
+- Boolean: `if="tagName"` / `if="!tagName"`
+- Enum variant: `if="tagName===value"` / `if="tagName!==value"` (no quotes around value)
+- Negation: `!` prefix
+
+## 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>
+```
+
+## Headless Components
+
+### Pattern 1: Key-Based Import
+
+Data merged into parent ViewState under a key. Use when you have **one instance** of a component per page.
+
+Declare in `<head>` with a `key` attribute:
+
+```html
+<head>
+  <script
+    type="application/jay-headless"
+    plugin="wix-stores"
+    contract="product-page"
+    key="productPage"
+  ></script>
+</head>
+```
+
+Access data and refs with the key prefix:
+
+```html
+<h1>{productPage.productName}</h1>
+<span>{productPage.price}</span>
+<button ref="productPage.addToCartButton">Add to Cart</button>
+
+<!-- Nested repeated sub-contracts -->
+<div forEach="productPage.options" trackBy="_id">
+  <h3>{name}</h3>
+  <div forEach="choices" trackBy="choiceId">
+    <button ref="choiceButton">{name}</button>
+  </div>
+</div>
+```
+
+### Pattern 2: Instance-Based (jay: prefix)
+
+Multiple instances with props and inline templates. Use when you need **multiple instances** or need to pass **props**.
+
+Declare in `<head>` **without** a `key`:
+
+```html
+<head>
+  <script
+    type="application/jay-headless"
+    plugin="product-widget"
+    contract="product-widget"
+  ></script>
+</head>
+```
+
+Use `<jay:contract-name>` tags with props:
+
+```html
+<!-- Static props — each instance renders independently -->
+<jay:product-widget productId="prod-1">
+  <h3>{name}</h3>
+  <div>${price}</div>
+  <button ref="addToCart">Add</button>
+</jay:product-widget>
+
+<jay:product-widget productId="prod-2">
+  <h3>{name}</h3>
+  <button ref="addToCart">Add</button>
+</jay:product-widget>
+```
+
+**With forEach** (dynamic props from parent data):
+
+```html
+<div forEach="featuredProducts" trackBy="_id">
+  <jay:product-widget productId="{_id}">
+    <h3>{name}</h3>
+    <div>${price}</div>
+    <button ref="addToCart">Add</button>
+  </jay:product-widget>
+</div>
+```
+
+Inside `<jay:...>`, bindings resolve to **that instance's** contract tags (not the parent).
+
+## 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).
+
+## Styling
+
+**Inline `<style>`:**
+
+```html
+<head>
+  <style>
+    .product-card {
+      border: 1px solid #ccc;
+      padding: 16px;
+    }
+    .price {
+      font-weight: bold;
+      color: #2d7d2d;
+    }
+  </style>
+</head>
+```
+
+**External stylesheets:**
+
+```html
+<link rel="stylesheet" href="../../styles/theme.css" />
+```
+
+**Dynamic style bindings:**
+
+```html
+<div style="color: {textColor}; width: {width}px">styled</div>
+```
+
+## Complete Example
+
+A homepage with key-based and instance-based headless components:
+
+```html
+<html>
+  <head>
+    <script
+      type="application/jay-headless"
+      plugin="mood-tracker"
+      contract="mood-tracker"
+      key="mt"
+    ></script>
+    <script
+      type="application/jay-headless"
+      plugin="product-widget"
+      contract="product-widget"
+    ></script>
+    <script type="application/jay-data" contract="./page.jay-contract"></script>
+    <style>
+      .section {
+        margin: 20px 0;
+        padding: 10px;
+      }
+      .product-card {
+        border: 1px solid #ccc;
+        padding: 10px;
+        display: inline-block;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>Homepage</h1>
+
+    <!-- Key-based: mood tracker -->
+    <div class="section">
+      <div>Happy: {mt.happy} <button ref="mt.happy">more</button></div>
+      <span if="mt.currentMood === happy">:)</span>
+      <span if="mt.currentMood === sad">:(</span>
+    </div>
+
+    <!-- Instance-based: static product widgets -->
+    <div class="section">
+      <jay:product-widget productId="1">
+        <h3>{name}</h3>
+        <div>${price}</div>
+        <span if="inStock">In Stock</span>
+        <button ref="addToCart">Add</button>
+      </jay:product-widget>
+    </div>
+
+    <!-- Instance-based: dynamic from forEach -->
+    <div class="section">
+      <div forEach="featuredProducts" trackBy="_id">
+        <div class="product-card">
+          <jay:product-widget productId="{_id}">
+            <h3>{name}</h3>
+            <div>${price}</div>
+            <button ref="addToCart">Add</button>
+          </jay:product-widget>
+        </div>
+      </div>
+    </div>
+  </body>
+</html>
+```