npm - @jay-framework/jay-stack-cli - Versions diffs - 0.15.5 → 0.16.0 - Mend

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

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 (39) hide show

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

@@ -0,0 +1,175 @@
+# Directory-Based Routing
+## Route Structure
+Pages live under `src/pages/`. Directory names become URL segments.
+```
+src/pages/
+├── page.jay-html                    → /
+├── about/
+│   └── page.jay-html                → /about
+├── products/
+│   ├── page.jay-html                → /products
+│   └── [slug]/
+│       └── page.jay-html            → /products/:slug
+├── blog/
+│   ├── page.jay-html                → /blog
+│   └── [[slug]]/
+│       └── page.jay-html            → /blog/:slug  (optional)
+└── files/
+    └── [...path]/
+        └── page.jay-html            → /files/*  (catch-all)
+```
+## Dynamic Routes
+| Syntax       | Meaning            | Example                                 |
+| ------------ | ------------------ | --------------------------------------- |
+| `[param]`    | Required parameter | `[slug]` → `/products/:slug`            |
+| `[[param]]`  | Optional parameter | `[[slug]]` → `/blog` or `/blog/my-post` |
+| `[...param]` | Catch-all          | `[...path]` → matches any sub-path      |
+## Route Priority
+Static routes match before dynamic routes (most specific first):
+1. **Static segments** (exact match) — highest priority
+2. **`[param]`** — required dynamic param
+3. **`[[param]]`** — optional param
+4. **`[...param]`** — catch-all — lowest priority
+## Static Route Overrides
+A static route can override a dynamic route for a specific URL — giving one particular page a custom layout while the dynamic route handles everything else:
+```
+src/pages/products/
+├── [slug]/page.jay-html              # dynamic: /products/:slug
+└── ceramic-flower-vase/page.jay-html # static override for this specific product
+```
+The static `ceramic-flower-vase/` route takes priority over `[slug]/` for that URL, but all other product URLs still use the dynamic route.
+### Static Override Params (`jay-params`)
+Static override routes often use the same contract as the dynamic route they override. Since the static route has no dynamic directory segment, the params must be declared explicitly using `<script type="application/jay-params">`:
+```html
+<!-- src/pages/products/ceramic-flower-vase/page.jay-html -->
+<html>
+  <head>
+    <script type="application/jay-params">
+      slug: ceramic-flower-vase
+    </script>
+    <script
+      type="application/jay-headless"
+      plugin="wix-stores"
+      contract="product-page"
+      key="product"
+    ></script>
+  </head>
+  <body>
+    <h1>{product.productName}</h1>
+  </body>
+</html>
+```
+The script body is YAML. The declared params are passed to the component as if extracted from a dynamic URL segment. Without this, the component would receive no param values.
+## Page Files
+Each page directory can contain:
+| File                | Purpose                             |
+| ------------------- | ----------------------------------- |
+| `page.jay-html`     | Template (required for rendering)   |
+| `page.jay-contract` | Page-level data contract (optional) |
+### page.jay-contract
+Defines the page's own ViewState — data that the page's server-side code provides:
+```yaml
+name: Page
+tags:
+  - tag: title
+    type: data
+    dataType: string
+    phase: slow
+  - tag: items
+    type: sub-contract
+    repeated: true
+    trackBy: id
+    tags:
+      - tag: id
+        type: data
+        dataType: string
+      - tag: name
+        type: data
+        dataType: string
+```
+## Dynamic Routes and Contract Params
+When a component on the page — whether the page contract, a headless component, or a headfull full-stack component — declares `params`, the page should be placed in a dynamic route directory that provides those params.
+For example, if a headless component's contract declares:
+```yaml
+name: product-page
+params:
+  slug: string
+tags:
+  - ...
+```
+Then the page using this component should live at a route that provides a `slug` param:
+```
+src/pages/products/[slug]/page.jay-html
+```
+Multiple components on the same page can each declare params. The route directory must provide all required params across all components. For example, if the page contract requires `lang` and a headless component requires `slug`, the page should live at `src/pages/[lang]/products/[slug]/page.jay-html`.
+### Discovering Param Values
+For SSG with dynamic routes, the plugin component provides a `loadParams` generator that yields all valid param combinations. Use it to discover what routes will be generated:
+```bash
+jay-stack params wix-stores/product-page
+# Output: [{"slug": "blue-shirt"}, {"slug": "red-hat"}, ...]
+```
+Params are always strings (URL params).
+## Query Parameters
+URL query parameters (`?page=2&sort=price`) are available in the **fast render phase only** via `props.query`:
+```typescript
+.withFastRender(async (props, carryForward, dbService) => {
+    const page = parseInt(props.query.page || '1');
+    const sort = props.query.sort || 'name';
+    const products = await dbService.getProducts({ page, sort });
+    return phaseOutput({ products, currentPage: page }, {});
+})
+```
+- `props.query` is `Record<string, string>` — empty `{}` when no query string
+- Not available in the slow phase (compile error) — slow results are cached by path params only
+- In the interactive phase, use `new URLSearchParams(window.location.search)` directly
+## Plugin Routes
+Plugins can provide their own pages via `routes` in `plugin.yaml`. These are backoffice tools, admin dashboards, or editors with boxed designs that don't need per-site customization.
+Plugin routes appear alongside project routes. If your project defines the same route path in `src/pages/`, your page takes precedence — the plugin's page is skipped.
+To override a plugin route, simply create a page at the same path:
+```
+# Plugin provides /admin/products
+# To customize, create:
+src/pages/admin/products/page.jay-html
+```

package/agent-kit-template/developer/seo-guide.md ADDED Viewed

@@ -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/INSTRUCTIONS.md ADDED Viewed

@@ -0,0 +1,43 @@
+# Jay Plugin Development — Agent Kit
+This folder contains guides for creating jay-stack plugins: contracts, headless components, server actions, services, and plugin-provided routes.
+## What is a Jay Plugin?
+A plugin provides headless components (data + interactions, no UI) that project designers use via contracts. Plugins can also provide complete pages (backoffice tools, admin dashboards) via routes. Plugins can be standalone npm packages or inline within a project (see `examples/jay-stack/fake-shop`).
+## Workflow
+1. **Define contracts first** — the contract is the source of truth
+2. **Implement components** matching the contracts
+3. **Define actions** with `.jay-action` metadata
+4. **Optionally add routes** — pages for admin tools and dashboards
+5. **Set up `plugin.yaml`** — list contracts, actions, services, contexts, routes
+6. **Validate** with `jay-stack validate-plugin`
+## Guides
+| File                                             | Topic                                                                   |
+| ------------------------------------------------ | ----------------------------------------------------------------------- |
+| [contracts-guide.md](contracts-guide.md)         | Contract format: tags, types, phases, props, params, sub-contracts      |
+| [plugin-structure.md](plugin-structure.md)       | plugin.yaml, package layout, exports                                    |
+| [component-structure.md](component-structure.md) | makeJayStackComponent, builder API, three-phase rendering               |
+| [component-state.md](component-state.md)         | createSignal, createMemo, createEffect, createDerivedArray, createEvent |
+| [component-refs.md](component-refs.md)           | Refs, collection refs, element types                                    |
+| [component-data.md](component-data.md)           | Immutable data, JSON Patch, createPatchableSignal                       |
+| [component-context.md](component-context.md)     | Context hooks: provide, reactive, global                                |
+| [render-results.md](render-results.md)           | phaseOutput, RenderPipeline, errors, redirects                          |
+| [actions-guide.md](actions-guide.md)             | makeJayAction, makeJayQuery, .jay-action files                          |
+| [services-guide.md](services-guide.md)           | createJayService, makeJayInit                                           |
+| [plugin-routes.md](plugin-routes.md)             | Plugin-provided pages: routes, jay-html templates, page components      |
+| [seo-guide.md](seo-guide.md)                     | SEO head tags: title, meta, OG, canonical via phaseOutput               |
+| [validation.md](validation.md)                   | jay-stack validate-plugin usage                                         |
+| [dev-server-service.md](dev-server-service.md)   | Dev server service API: routes, params, freeze management               |
+| `../references/<plugin>/`                        | Plugin reference data                                                   |
+## Key Principles
+- **Contract is the source of truth** — define it before implementing the component
+- **Data is immutable** — never mutate ViewState directly, use JSON Patch
+- **Phase-aware** — choose the right rendering phase for each piece of data
+- **Props for configuration, params for URLs** — props are passed by parent components, params come from route segments

package/agent-kit-template/plugin/actions-guide.md ADDED Viewed

@@ -0,0 +1,184 @@
+# Server Actions
+Actions provide RPC-style server endpoints for client-to-server communication.
+## makeJayAction — Mutations (POST)
+```typescript
+import { makeJayAction } from '@jay-framework/fullstack-component';
+export const addToCart = makeJayAction('cart.addToCart')
+  .withServices(CART_SERVICE)
+  .withHandler(async (input: { productId: string; quantity: number }, cartService) => {
+    const cart = await cartService.addItem(input.productId, input.quantity);
+    return { cartItemCount: cart.items.length };
+  });
+```
+## makeJayQuery — Reads (GET)
+Queries use GET and support caching:
+```typescript
+import { makeJayQuery } from '@jay-framework/fullstack-component';
+export const searchProducts = makeJayQuery('products.search')
+  .withServices(PRODUCTS_SERVICE)
+  .withCaching({ maxAge: 60 })
+  .withHandler(async (input: { query: string; page?: number }, productsDb) => {
+    const results = await productsDb.search(input.query, input.page);
+    return { products: results.items, totalCount: results.total };
+  });
+```
+## Builder API
+```typescript
+makeJayAction('name')
+  .withServices(SERVICE1, SERVICE2) // Inject services
+  .withMethod('PUT') // Override HTTP method (default: POST for actions)
+  .withCaching({ maxAge: 60 }) // Enable caching (queries only)
+  .withHandler(async (input, svc1, svc2) => {
+    // Define handler
+    return result;
+  });
+```
+## ActionError
+Throw typed errors from action handlers:
+```typescript
+import { ActionError } from '@jay-framework/fullstack-component';
+throw new ActionError('OUT_OF_STOCK', 'Only 2 units available');
+throw new ActionError('INVALID_INPUT', 'Product ID is required');
+```
+## Calling Actions from Client
+Actions are callable functions on the client:
+```typescript
+.withInteractive(function MyComp(props, refs) {
+    refs.addToCart.onClick(async () => {
+        const result = await addToCart({
+            productId: props.productId,
+            quantity: 1,
+        });
+        // result.cartItemCount
+    });
+})
+```
+## Calling Actions from Server
+When called from server-side code (e.g., within a render phase), services are automatically injected — no network call is made.
+## .jay-action Metadata Files
+Each action should have a `.jay-action` file describing its input/output schemas for agent discovery:
+```yaml
+name: searchProducts
+description: Search products with text, filters, sorting, and 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 for Schemas
+| Notation                  | Meaning                   |
+| ------------------------- | ------------------------- |
+| `prop: string`            | Required string           |
+| `prop?: number`           | Optional number           |
+| `prop: boolean`           | Required boolean          |
+| `prop: enum(a \| b \| c)` | Required enum             |
+| `prop:` + nested block    | Nested object             |
+| `prop:` + `- child: type` | Array of objects          |
+| `prop: record(T)`         | Record with typed values  |
+| `prop: importedName`      | Type from `import:` block |
+## makeJayStream — Streaming (POST, NDJSON)
+Streaming actions return an async generator that yields chunks:
+```typescript
+import { makeJayStream } from '@jay-framework/fullstack-component';
+export const discoverParams = makeJayStream('routes.discoverParams')
+  .withServices(PRODUCTS_SERVICE)
+  .withHandler(async function* (input: { route: string }, productsService) {
+    let page = 1;
+    while (true) {
+      const products = await productsService.list({ page, pageSize: 100 });
+      yield products.map((p) => ({ slug: p.slug }));
+      if (!products.hasMore) break;
+      page++;
+    }
+  });
+```
+### Consuming on the client
+```typescript
+for await (const batch of discoverParams({ route: '/products/[slug]' })) {
+  console.log(batch); // [{ slug: 'item-a' }, { slug: 'item-b' }]
+}
+```
+### Wire format
+The server responds with NDJSON (newline-delimited JSON). Each line is a complete JSON object:
+```
+{"chunk":[{"slug":"item-a"},{"slug":"item-b"}]}
+{"chunk":[{"slug":"item-c"}]}
+{"done":true}
+```
+### .jay-action for streaming
+Add `streaming: true` to the metadata file:
+```yaml
+name: discoverParams
+description: Discover URL params by querying the product catalog
+streaming: true
+inputSchema:
+  route: string
+outputSchema:
+  - slug: string
+```
+## Type Helpers
+```typescript
+import {
+  ActionInput,
+  ActionOutput,
+  isJayAction,
+  StreamChunk,
+  isJayStreamAction,
+} from '@jay-framework/fullstack-component';
+type SearchInput = ActionInput<typeof searchProducts>;
+type SearchOutput = ActionOutput<typeof searchProducts>;
+type ParamBatch = StreamChunk<typeof discoverParams>;
+```

package/agent-kit-template/plugin/component-context.md ADDED Viewed

@@ -0,0 +1,103 @@
+# Component Context
+Context provides a way to share state between components without passing props through every level.
+## Context Markers
+Create a typed marker to identify a context:
+```typescript
+import { createContextMarker } from '@jay-framework/component';
+interface CartContext {
+  itemCount: () => number;
+  addItem: (productId: string) => void;
+}
+const CART_CONTEXT = createContextMarker<CartContext>('CartContext');
+```
+## provideContext
+Provide a non-reactive context value to child components:
+```typescript
+import { provideContext } from '@jay-framework/component';
+provideContext(CART_CONTEXT, {
+  itemCount: () => items().length,
+  addItem: (id) => addToCartAction({ productId: id }),
+});
+```
+## provideReactiveContext
+Provide a reactive context — the factory function has access to hooks:
+```typescript
+import { provideReactiveContext, createSignal } from '@jay-framework/component';
+const cartCtx = provideReactiveContext(CART_CONTEXT, () => {
+  const [items, setItems] = createSignal<CartItem[]>([]);
+  return {
+    itemCount: () => items().length,
+    addItem: (id) => setItems((prev) => [...prev, { productId: id }]),
+  };
+});
+```
+The returned value is the context instance, usable in the same component.
+## registerReactiveGlobalContext
+Register a context globally during client initialization (in `makeJayInit`):
+```typescript
+import { registerReactiveGlobalContext, createSignal } from '@jay-framework/component';
+export const init = makeJayInit().withClient(() => {
+  registerReactiveGlobalContext(CART_CONTEXT, () => {
+    const [items, setItems] = createSignal<CartItem[]>([]);
+    return {
+      itemCount: () => items().length,
+      addItem: (id) => setItems((prev) => [...prev, { productId: id }]),
+    };
+  });
+});
+```
+Global contexts are available to all components without explicit providing.
+## Consuming Context
+Components consume contexts via `.withContexts()` on the builder:
+```typescript
+makeJayStackComponent<MyContract>()
+  .withContexts(CART_CONTEXT)
+  .withInteractive(function MyComp(props, refs, cartCtx) {
+    refs.addToCart.onClick(() => {
+      cartCtx.addItem(props.productId);
+    });
+    return {
+      render: () => ({
+        cartCount: cartCtx.itemCount(),
+      }),
+    };
+  });
+```
+## Listing in plugin.yaml
+If your plugin provides contexts for other plugins to consume, list them in `plugin.yaml`:
+```yaml
+contexts:
+  - name: cart
+    marker: CART_CONTEXT
+    description: Client-side cart state (item count, add/remove items, totals)
+    doc: ./docs/cart-context.md # optional — markdown documentation
+```
+This makes the context discoverable in `plugins-index.yaml`. If `doc` is provided, the file must exist and be exported from the package.