@jay-framework/jay-stack-cli 0.19.6 → 0.19.7

package/agent-kit-template/INSTRUCTIONS.md

@@ -0,0 +1,37 @@
+# Jay Stack Agent Kit
+
+This agent kit provides role-specific guides for building a Jay Stack application. Each role covers a different aspect of the project.
+
+## Roles
+
+### Designer (`designer/`)
+
+Creates `.jay-html` pages and templates. Binds to contract data using template syntax — data bindings, conditions, loops, and refs. Styles pages with CSS.
+
+**Use when:** building or modifying the visual UI of pages and components.
+
+### Developer (`developer/`)
+
+Creates page components (`page.ts`) using `makeJayStackComponent`, defines page contracts (`page.jay-contract`), configures routing, and sets up project services. Also creates headfull components for shared UI sections (headers, footers).
+
+**Use when:** adding page logic, defining data shapes, configuring the project, or creating shared components.
+
+### Plugin (`plugin/`)
+
+Creates reusable headless components packaged as plugins. Defines contracts, actions, services, and CLI commands that other projects consume.
+
+**Use when:** building a reusable plugin that will be installed by other projects.
+
+### DevOps (`devops/`)
+
+Handles production builds, deployment configuration, serving modes, and cache invalidation.
+
+**Use when:** deploying the application or configuring production infrastructure.
+
+## Shared Guides
+
+### Contracts (`contracts/`)
+
+Contract authoring guide shared across all roles. Covers syntax, page contracts, component contracts, linked contracts, and graduated examples.
+
+**Start here:** [contracts/GUIDE.md](contracts/GUIDE.md) — decision tree for what kind of contract to write.

package/agent-kit-template/contracts/GUIDE.md

@@ -0,0 +1,70 @@
+# Contract Authoring Guide
+
+Contracts (`.jay-contract` files) define the data shape, interaction points, and rendering phases for a component. They are the source of truth shared between the component implementation and the template.
+
+## What Kind of Contract Do I Need?
+
+### Page contract
+
+A page has its own data that isn't fully provided by plugins.
+
+- Place as `page.jay-contract` next to `page.jay-html` and `page.ts`
+- Use `params` for dynamic route segments (`slug`, `category`)
+- Can coexist with plugin headless contracts on the same page
+- See [page-contracts.md](page-contracts.md)
+
+### Headfull component contract
+
+A shared UI section (header, footer, sidebar) that appears across multiple pages.
+
+- Place in `src/components/<name>/` alongside the `.ts` and `.jay-html` files
+- Use `props` for configuration passed by the parent page
+- No `params` (components don't own routes)
+- See [component-contracts.md](component-contracts.md)
+
+### Plugin contract
+
+A headless component provided by a plugin for others to consume.
+
+- Place in the plugin's `lib/contracts/` directory
+- Declared in `plugin.yaml`
+- Can be static (file) or dynamic (generated at build time)
+- See the plugin role guide for plugin-specific concerns
+
+### Shared sub-contract
+
+A reusable piece extracted from a larger contract and linked via `link:` syntax.
+
+- Place alongside the contracts that reference it
+- No `props` or `params` (data flows from the parent)
+- See [linked-contracts.md](linked-contracts.md)
+
+## Decision Checklist
+
+| Question                                            | If yes                                                                                   |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Does the component own a URL route?                 | Add `params` — see [page-contracts.md](page-contracts.md)                                |
+| Is it configured by a parent?                       | Add `props` — see [component-contracts.md](component-contracts.md)                       |
+| Does it have nested repeated data?                  | Use `sub-contract` with `repeated: true` and `trackBy`                                   |
+| Is a sub-contract reused across multiple contracts? | Extract to a separate file, use `link:` — see [linked-contracts.md](linked-contracts.md) |
+| Does data change per request?                       | Use `fast` or `fast+interactive` phase                                                   |
+| Does data update on the client after interaction?   | Use `fast+interactive` phase                                                             |
+| Is the data static / known at build time?           | Use `slow` phase                                                                         |
+| Does the user click, type, or select something?     | Add `interactive` tag with the right `elementType`                                       |
+
+## Contract Syntax Reference
+
+See [syntax.md](syntax.md) for the full YAML format: tag types, phases, data types, props, params, async data, and validation rules.
+
+## Examples
+
+Start with the simplest example that matches your use case, then add complexity as needed:
+
+| Example                                                | Complexity     | Key patterns                                                |
+| ------------------------------------------------------ | -------------- | ----------------------------------------------------------- |
+| [mini-cart](examples/mini-cart.md)                     | Trivial        | Variant + interactive refs                                  |
+| [cart-indicator](examples/cart-indicator.md)           | Simple         | Flat data, variants, phase choices                          |
+| [category-list](examples/category-list.md)             | Medium         | Props, repeated sub-contracts                               |
+| [product-card](examples/product-card.md)               | Medium-complex | Linked sub-contracts, variants, multiple ref types          |
+| [product-page](examples/product-page.md)               | Complex        | Params, nested repeated sub-contracts, linked sub-contracts |
+| [composing-contracts](examples/composing-contracts.md) | Pattern        | How contracts link together into a hierarchy                |

package/agent-kit-template/contracts/component-contracts.md

@@ -0,0 +1,82 @@
+# Headfull Component Contracts
+
+Headfull components in Jay Stack are full-stack and must have a contract. The contract defines the data the component provides to its template.
+
+## When to Use
+
+Use a headfull component contract for shared UI sections that appear across multiple pages: headers, footers, sidebars, navigation menus.
+
+## File Structure
+
+Each headfull component lives in its own subdirectory under `src/components/`:
+
+```
+src/components/site-header/
+  site-header.ts             # makeJayStackComponent logic
+  site-header.jay-html       # template
+  site-header.jay-contract   # contract (required)
+```
+
+## Contract with Props
+
+Headfull components use `props` (not `params`) for configuration passed by the parent page:
+
+```yaml
+name: site-header
+description: Site-wide header with navigation and cart indicator.
+props:
+  - name: logoUrl
+    type: string
+    description: URL for the site logo
+  - name: showSearch
+    type: boolean
+    default: 'true'
+    description: Whether to show the search bar
+tags:
+  - tag: siteName
+    type: data
+    dataType: string
+    phase: slow
+  - tag: navLinks
+    type: sub-contract
+    repeated: true
+    trackBy: _id
+    tags:
+      - tag: _id
+        type: data
+        dataType: string
+      - tag: label
+        type: data
+        dataType: string
+      - tag: navLink
+        type: interactive
+        elementType: HTMLAnchorElement
+```
+
+## Importing in jay-html
+
+The import must include the `contract` attribute:
+
+```html
+<script
+  type="application/jay-headfull"
+  src="../components/site-header/site-header"
+  names="SiteHeader"
+  contract="../components/site-header/site-header.jay-contract"
+></script>
+```
+
+Usage in the page body:
+
+```html
+<jay:SiteHeader logoUrl="/logo.png" />
+```
+
+## Component Contract vs Page Contract
+
+|              | Page contract                          | Component contract                                                   |
+| ------------ | -------------------------------------- | -------------------------------------------------------------------- |
+| **Location** | `src/pages/.../page.jay-contract`      | `src/components/<name>/<name>.jay-contract`                          |
+| **Params**   | Yes (from route segments)              | No (components don't own routes)                                     |
+| **Props**    | Rarely                                 | Yes (configured by parent)                                           |
+| **Import**   | `<script type="application/jay-data">` | `<script type="application/jay-headfull">` with `contract` attribute |

package/agent-kit-template/contracts/examples/cart-indicator.md

@@ -0,0 +1,60 @@
+# Example: Cart Indicator
+
+A simple flat contract for a header widget. Shows phase choices and the difference between data, variant, and interactive tags.
+
+```yaml
+name: cart-indicator
+description: Cart indicator showing item count, typically used in site header.
+
+tags:
+  - tag: itemCount
+    type: data
+    dataType: number
+    phase: fast+interactive
+    description: Total number of items in cart
+
+  - tag: hasItems
+    type: variant
+    dataType: boolean
+    phase: fast+interactive
+    description: Whether cart has any items
+
+  - tag: cartButton
+    type: interactive
+    elementType: HTMLButtonElement
+    description: Button to open cart
+
+  - tag: cartLink
+    type: interactive
+    elementType: HTMLAnchorElement
+    description: Link to cart page
+
+  - tag: isLoading
+    type: variant
+    dataType: boolean
+    phase: fast+interactive
+    description: Whether cart data is loading
+
+  - tag: justAdded
+    type: variant
+    dataType: boolean
+    phase: fast+interactive
+    description: Briefly true after an item is added (for animation)
+```
+
+## Why these choices
+
+- **Everything is `fast+interactive`** — cart data is per-session (not build-time), and updates live when items are added.
+- **`hasItems` is a variant, not computed from `itemCount`** — the template can use `if="hasItems"` directly without comparing numbers.
+- **`justAdded` is a transient variant** — the component briefly sets it to true for CSS animation, then resets it.
+- **Both `cartButton` and `cartLink`** — gives the designer flexibility to use either a button (opens mini-cart) or a link (navigates to cart page).
+
+## Jay-HTML usage
+
+```html
+<div class="cart-indicator">
+  <a ref="cartLink" class="cart-icon">
+    <span if="hasItems" class="badge">{itemCount}</span>
+  </a>
+</div>
+```

package/agent-kit-template/contracts/examples/category-list.md

@@ -0,0 +1,77 @@
+# Example: Category List
+
+A medium-complexity contract with props and a repeated sub-contract. Shows how to configure a component at design time.
+
+```yaml
+name: category-list
+description: Displays store categories. Use for category navigation grids and menus.
+props:
+  - name: parentCategory
+    type: string
+    description: Parent category slug. Only direct children of this category are shown.
+tags:
+  - tag: categories
+    type: sub-contract
+    repeated: true
+    trackBy: _id
+    description: List of visible store categories
+    tags:
+      - tag: _id
+        type: data
+        dataType: string
+
+      - tag: name
+        type: data
+        dataType: string
+        required: true
+
+      - tag: slug
+        type: data
+        dataType: string
+
+      - tag: description
+        type: data
+        dataType: string
+
+      - tag: productCount
+        type: data
+        dataType: number
+
+      - tag: imageUrl
+        type: data
+        dataType: string
+        meta: { mediaType: wix-image }
+
+      - tag: categoryLink
+        type: interactive
+        elementType: HTMLAnchorElement
+
+  - tag: hasCategories
+    type: variant
+    dataType: boolean
+    description: Whether there are any categories
+```
+
+## Why these choices
+
+- **`props` instead of `params`** — this is a widget placed on a page, not a page itself. The parent decides which categories to show.
+- **No explicit phases** — category data is static and available at all phases.
+- **`trackBy: _id`** — each category has a stable GUID for efficient list diffing.
+- **`hasCategories` variant** — lets the template show an empty state without checking array length.
+- **`meta: { mediaType: wix-image }`** — tells validators this string is a Wix media URL.
+
+## Jay-HTML usage
+
+```html
+<jay:category-list parentCategory="shop">
+  <div if="hasCategories" class="category-grid">
+    <div forEach="categories" trackBy="_id">
+      <a ref="categoryLink" class="category-card">
+        <img src="{imageUrl}" alt="{name}" />
+        <span>{name}</span>
+        <span class="count">({productCount})</span>
+      </a>
+    </div>
+  </div>
+</jay:category-list>
+```

package/agent-kit-template/contracts/examples/composing-contracts.md

@@ -0,0 +1,100 @@
+# Example: Composing Contracts
+
+How contracts link together into a reusable hierarchy. This example shows the wix-stores composition pattern.
+
+## The Hierarchy
+
+```
+media.jay-contract                  ← Trivial: url + mediaType
+  ↑
+media-gallery.jay-contract          ← Links to media, adds thumbnail navigation
+  ↑
+product-page.jay-contract           ← Links to media-gallery, adds options, pricing
+
+product-options.jay-contract        ← Reusable option/choice structure
+  ↑
+product-card.jay-contract           ← Links to product-options for quick-add
+  ↑
+product-search.jay-contract         ← Links to product-card for search results
+```
+
+## Level 1: Leaf contract
+
+The simplest building block. No sub-contracts, no links.
+
+```yaml
+# media.jay-contract
+name: media
+description: Single media item.
+tags:
+  - { tag: url, type: data, dataType: string, meta: { mediaType: wix-image } }
+  - { tag: mediaType, type: variant, dataType: 'enum (IMAGE | VIDEO)' }
+```
+
+## Level 2: Composing leaves
+
+Links to a leaf contract and adds its own structure.
+
+```yaml
+# media-gallery.jay-contract
+name: mediaGallery
+description: Image/video gallery with thumbnail navigation.
+tags:
+  - tag: selectedMedia
+    type: sub-contract
+    link: ./media
+
+  - tag: availableMedia
+    type: sub-contract
+    repeated: true
+    trackBy: mediaId
+    tags:
+      - { tag: mediaId, type: data }
+      - { tag: media, type: sub-contract, link: ./media }
+      - tag: selected
+        type: [variant, interactive]
+        dataType: enum(selected | notSelected)
+        elementType: HTMLImageElement | HTMLDivElement
+```
+
+## Level 3: Page contract composing everything
+
+The product page links to the gallery (which links to media) and adds its own options, pricing, and actions.
+
+```yaml
+# product-page.jay-contract (abbreviated)
+name: product-page
+params:
+  slug: string
+tags:
+  - { tag: productName, type: data, dataType: string }
+  - { tag: mediaGallery, type: sub-contract, phase: fast+interactive, link: ./media-gallery }
+  - { tag: price, type: data, dataType: string, phase: fast+interactive }
+  # ... options, actions, etc.
+```
+
+## Parallel composition
+
+The same `product-options.jay-contract` is linked by both the product page (inline options) and the product card (quick-add):
+
+```yaml
+# In product-card.jay-contract
+- { tag: quickOption, type: sub-contract, link: ./product-options }
+# In product-page.jay-contract — options are defined inline because they have
+# page-specific additions (text choice dropdown, modifier support)
+```
+
+## When to extract vs inline
+
+| Extract into a linked file                                 | Keep inline                             |
+| ---------------------------------------------------------- | --------------------------------------- |
+| Used by 2+ contracts                                       | Used by only one contract               |
+| Complex enough to be its own concept (media, product-card) | Simple nested object (pricing, summary) |
+| Has its own identity that designers/developers reference   | Just a grouping of related fields       |
+
+## Benefits of composition
+
+- **Single source of truth** — change `media.jay-contract` once, all galleries update
+- **Readability** — each file stays focused on one concept
+- **Reusability** — `product-card` is used in search, related products, and category pages
+- **Independent testing** — each contract level can be validated independently

package/agent-kit-template/contracts/examples/mini-cart.md

@@ -0,0 +1,43 @@
+# Example: Mini Cart
+
+A trivial contract with one variant and two interactive refs. Good starting point for understanding the basics.
+
+```yaml
+name: mini-cart
+description: Drawer that auto-opens when a product is added to cart.
+
+tags:
+  - tag: isOpen
+    type: variant
+    dataType: boolean
+    phase: fast+interactive
+    description: Whether the mini-cart drawer is currently open
+
+  - tag: openButton
+    type: interactive
+    elementType: HTMLButtonElement
+    description: Button to manually open the mini-cart drawer
+
+  - tag: closeButton
+    type: interactive
+    elementType: HTMLButtonElement
+    description: Button to close the mini-cart drawer
+```
+
+## Why these choices
+
+- **`isOpen` is `fast+interactive`** — the drawer state starts on the server (closed) and toggles on the client.
+- **Interactive tags have no explicit phase** — they're always `fast+interactive`.
+- **No props or params** — the mini-cart doesn't need configuration and doesn't own a route.
+
+## Jay-HTML usage
+
+```html
+<div class="mini-cart-overlay" if="isOpen">
+  <div class="mini-cart-drawer">
+    <button ref="closeButton">Close</button>
+    <!-- cart content here -->
+  </div>
+</div>
+<button ref="openButton">Cart</button>
+```

package/agent-kit-template/contracts/examples/product-card.md

@@ -0,0 +1,70 @@
+# Example: Product Card
+
+A medium-complex contract designed as a reusable sub-contract. Shows linked sub-contracts, variants for conditional rendering, and multiple interactive element types.
+
+```yaml
+name: product-card
+description: Single product card with image, price, and quick-add. Used in product grids and search results.
+tags:
+  - { tag: _id, type: data, dataType: string }
+  - { tag: name, type: data, dataType: string, required: true }
+  - { tag: slug, type: data, dataType: string }
+  - { tag: productUrl, type: data, dataType: string }
+  - { tag: productLink, type: interactive, elementType: HTMLAnchorElement }
+
+  # Media — inline sub-contract for the card thumbnail
+  - tag: thumbnail
+    type: sub-contract
+    tags:
+      - { tag: url, type: data, dataType: string, meta: { mediaType: wix-image } }
+      - { tag: altText, type: data, dataType: string }
+      - { tag: width, type: data, dataType: number }
+      - { tag: height, type: data, dataType: number }
+
+  # Pricing — fast+interactive because it changes with variant selection
+  - { tag: price, type: data, dataType: string, phase: fast+interactive }
+  - { tag: strikethroughPrice, type: data, dataType: string, phase: fast+interactive }
+  - { tag: hasDiscount, type: variant, dataType: boolean }
+
+  # Inventory — inline sub-contract with enum variant
+  - tag: inventory
+    type: sub-contract
+    tags:
+      - tag: availabilityStatus
+        type: variant
+        dataType: enum (IN_STOCK | OUT_OF_STOCK | PARTIALLY_OUT_OF_STOCK)
+
+  # Quick-add — linked sub-contracts for option selection
+  - tag: quickAddType
+    type: variant
+    dataType: enum (SIMPLE | SINGLE_OPTION | COLOR_AND_TEXT_OPTIONS | NEEDS_CONFIGURATION)
+
+  - { tag: quickOption, type: sub-contract, link: ./product-options }
+  - { tag: secondQuickOption, type: sub-contract, link: ./product-options }
+
+  - { tag: addToCartButton, type: interactive, elementType: HTMLButtonElement }
+  - { tag: isAddingToCart, type: variant, dataType: boolean, phase: fast+interactive }
+  - { tag: cardContainer, type: interactive, elementType: HTMLElement }
+```
+
+## Why these choices
+
+- **No props or params** — this is a sub-contract, not a standalone component. Data flows from the parent (search results, related products).
+- **`link: ./product-options`** — the option/choice structure is shared with the product page, so it's extracted into its own file.
+- **`quickAddType` enum** — drives which quick-add UI to show. The designer uses `if="quickAddType===SIMPLE"` etc.
+- **`cardContainer` is `HTMLElement`** — not a button or link, just a generic element for mouseenter preloading.
+- **Inline `thumbnail` sub-contract** — only used here, so no need to extract.
+
+## Jay-HTML usage
+
+```html
+<a ref="productLink" class="product-card" ref="cardContainer">
+  <img src="{thumbnail.url}" alt="{thumbnail.altText}" />
+  <h3>{name}</h3>
+  <div class="price">
+    <span if="hasDiscount" class="original">{strikethroughPrice}</span>
+    <span>{price}</span>
+  </div>
+  <button if="quickAddType===SIMPLE" ref="addToCartButton">Add to Cart</button>
+</a>
+```

package/agent-kit-template/contracts/examples/product-page.md

@@ -0,0 +1,125 @@
+# Example: Product Page
+
+A complex page contract with params, nested repeated sub-contracts, linked sub-contracts, and multiple rendering phases.
+
+```yaml
+name: product-page
+description: Full product detail page with variants, options, media gallery, and add-to-cart.
+params:
+  slug: string
+  prefix: string?
+  category: string?
+tags:
+  - { tag: _id, type: data, dataType: string }
+  - { tag: productName, type: data, dataType: string, required: true }
+  - { tag: description, type: data, dataType: html-string }
+  - { tag: brand, type: data, dataType: string }
+  - { tag: ribbon, type: data, dataType: string }
+  - { tag: productType, type: variant, dataType: 'enum (PHYSICAL | DIGITAL)' }
+
+  # Linked sub-contract for the media gallery
+  - tag: mediaGallery
+    type: sub-contract
+    phase: fast+interactive
+    link: ./media-gallery
+
+  # Pricing — per-variant, changes on client
+  - { tag: sku, type: data, dataType: string, phase: fast+interactive }
+  - { tag: price, type: data, dataType: string, phase: fast+interactive }
+  - { tag: strikethroughPrice, type: data, dataType: string, phase: fast+interactive }
+  - {
+      tag: stockStatus,
+      type: variant,
+      dataType: 'enum (OUT_OF_STOCK | IN_STOCK)',
+      phase: fast+interactive,
+    }
+
+  # Quantity controls — dual-type tag (data + interactive)
+  - tag: quantity
+    type: sub-contract
+    tags:
+      - { tag: decrementButton, type: interactive, elementType: HTMLButtonElement }
+      - { tag: incrementButton, type: interactive, elementType: HTMLButtonElement }
+      - {
+          tag: quantity,
+          type: [data, interactive],
+          dataType: number,
+          elementType: HTMLInputElement,
+        }
+
+  # Call to action
+  - { tag: addToCartButton, type: interactive, elementType: HTMLButtonElement, required: true }
+  - { tag: buyNowButton, type: interactive, elementType: HTMLButtonElement, required: true }
+  - { tag: actionsEnabled, type: variant, dataType: boolean, phase: fast+interactive }
+
+  # Options — nested repeated sub-contracts (options → choices)
+  - tag: options
+    type: sub-contract
+    repeated: true
+    trackBy: _id
+    tags:
+      - { tag: _id, type: data, dataType: string }
+      - { tag: name, type: data, dataType: string }
+      - {
+          tag: optionRenderType,
+          type: variant,
+          dataType: 'enum (TEXT_CHOICES | COLOR_SWATCH_CHOICES)',
+        }
+      - { tag: textChoice, type: interactive, elementType: HTMLSelectElement }
+
+      - tag: choices
+        type: sub-contract
+        repeated: true
+        trackBy: choiceId
+        tags:
+          - { tag: choiceId, type: data, dataType: string }
+          - { tag: name, type: data, dataType: string }
+          - { tag: colorCode, type: data, dataType: string }
+          - { tag: inStock, type: data, dataType: boolean }
+          - { tag: isSelected, type: variant, dataType: boolean, phase: fast+interactive }
+          - { tag: choiceButton, type: interactive, elementType: HTMLButtonElement }
+
+  # Info sections — repeated content blocks
+  - tag: infoSections
+    type: sub-contract
+    repeated: true
+    trackBy: _id
+    tags:
+      - { tag: _id, type: data, dataType: string }
+      - { tag: title, type: data, dataType: string }
+      - { tag: plainDescription, type: data, dataType: html-string }
+```
+
+## Why these choices
+
+- **`params`** — this is a page contract with dynamic route segments (`/products/[slug]`).
+- **`link: ./media-gallery`** — the gallery is complex enough to warrant its own file and is reusable.
+- **Options are inline** — despite being complex, they're specific to the product page and not reused elsewhere.
+- **`html-string` for description** — the product description contains HTML formatting from the CMS.
+- **`[data, interactive]` for quantity** — the input both displays the current value and accepts user input.
+- **No phase on product name** — available at all phases (SSG, SSR, and client).
+- **`fast+interactive` on pricing** — prices change when a variant is selected on the client.
+- **Nested `repeated`** — options contain choices, both with their own `trackBy` for efficient diffing.
+
+## Jay-HTML usage
+
+```html
+<h1>{productName}</h1>
+<div class="price">
+  <span>{price}</span>
+  <span if="stockStatus===OUT_OF_STOCK" class="out-of-stock">Out of Stock</span>
+</div>
+
+<div forEach="options" trackBy="_id">
+  <h3>{name}</h3>
+  <div if="optionRenderType===COLOR_SWATCH_CHOICES">
+    <div forEach="choices" trackBy="choiceId">
+      <button ref="choiceButton" style="background: {colorCode}" class="swatch" if="isSelected">
+        selected
+      </button>
+    </div>
+  </div>
+</div>
+
+<button ref="addToCartButton">Add to Cart</button>
+```