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/plugin/render-results.md ADDED Viewed

@@ -0,0 +1,112 @@
+# Render Results
+Each rendering phase (slow, fast) returns a render result indicating success, error, or redirect.
+## phaseOutput — Success
+Returns ViewState data and optional carry-forward data for the next phase:
+```typescript
+import { phaseOutput } from '@jay-framework/fullstack-component';
+return phaseOutput(
+  { title: 'My Product', price: 29.99 }, // ViewState — sent to template
+  { productId: 'abc123' }, // CarryForward — passed to next phase only
+);
+```
+CarryForward is available in the next phase via `props.carryForward` but is not part of the ViewState.
+## Error Results
+Return errors to stop rendering and show an error page:
+```typescript
+import {
+  notFound,
+  badRequest,
+  unauthorized,
+  forbidden,
+  serverError5xx,
+  clientError4xx,
+} from '@jay-framework/fullstack-component';
+// 404
+if (!product) return notFound('Product not found');
+// 400
+if (!input.query) return badRequest('Query is required');
+// 401
+if (!session) return unauthorized('Please log in');
+// 403
+if (!canAccess) return forbidden('Access denied');
+// Custom 4xx
+return clientError4xx(429, 'Rate limit exceeded');
+// 5xx
+return serverError5xx(500, 'Database connection failed');
+```
+## Redirects
+```typescript
+import { redirect3xx } from '@jay-framework/fullstack-component';
+return redirect3xx(301, '/new-location');
+return redirect3xx(302, `/products/${product.slug}`);
+```
+## RenderPipeline — Composable Rendering
+For complex render logic, `RenderPipeline` chains operations with automatic error propagation:
+```typescript
+import { RenderPipeline } from '@jay-framework/fullstack-component';
+const Pipeline = RenderPipeline.for<SlowViewState, CarryForward>();
+return Pipeline.try(() => db.getProduct(props.slug))
+  .map((product) => product ?? Pipeline.notFound('Product not found'))
+  .map(async (product) => ({
+    ...product,
+    reviews: await db.getReviews(product.id),
+  }))
+  .toPhaseOutput((product) => ({
+    viewState: { title: product.name, price: product.price },
+    carryForward: { productId: product.id },
+  }));
+```
+### Pipeline Factory Methods
+```typescript
+const P = RenderPipeline.for<VS, CF>();
+P.ok(value); // Wrap a value
+P.try(() => fetchData()); // Wrap a function (catches errors)
+P.from(previousPhaseResult); // Continue from a prior phase result
+P.notFound('message'); // Error pipeline
+P.badRequest('message'); // Error pipeline
+P.unauthorized('message'); // Error pipeline
+P.forbidden('message'); // Error pipeline
+P.serverError(500, 'message'); // Error pipeline
+P.redirect(301, '/path'); // Redirect pipeline
+```
+### Pipeline Chain Methods
+```typescript
+pipeline
+    .map(value => transform(value))           // Transform the value
+    .map(async value => await asyncOp(value)) // Async transform
+    .recover(error => P.ok(fallbackValue))    // Recover from errors
+    .toPhaseOutput(value => ({                // Convert to PhaseOutput
+        viewState: { ... },
+        carryForward: { ... },
+    }));
+```
+Errors short-circuit — if any step returns an error pipeline, subsequent `.map()` calls are skipped.

package/agent-kit-template/plugin/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/services-guide.md ADDED Viewed

@@ -0,0 +1,116 @@
+# Services and Initialization
+Services provide dependency injection for server-side resources (databases, APIs, etc.).
+## createJayService
+Create a typed service marker:
+```typescript
+import { createJayService } from '@jay-framework/fullstack-component';
+export interface ProductsDatabase {
+  getProduct(slug: string): Promise<Product | null>;
+  search(query: string): Promise<Product[]>;
+}
+export const PRODUCTS_DB = createJayService<ProductsDatabase>('ProductsDatabase');
+```
+The marker is a Symbol-based key — it provides type safety without coupling to a specific implementation.
+## makeJayInit
+Initialize services and client-side state during app startup:
+### Server-only init
+```typescript
+import { makeJayInit, registerService } from '@jay-framework/fullstack-component';
+export const init = makeJayInit().withServer(async () => {
+  const db = await connectToDatabase();
+  registerService(PRODUCTS_DB, db);
+});
+```
+### Server + Client init
+The server can pass data to the client via the return value:
+```typescript
+export const init = makeJayInit()
+  .withServer(async () => {
+    registerService(PRODUCTS_DB, await connectDb());
+    return { currency: 'USD', storeId: 'store-123' };
+  })
+  .withClient((data) => {
+    // data is typed: { currency: string; storeId: string }
+    registerReactiveGlobalContext(STORE_CONFIG, () => ({
+      currency: data.currency,
+      storeId: data.storeId,
+    }));
+  });
+```
+### Client-only init
+```typescript
+export const init = makeJayInit().withClient(() => {
+  initAnalytics();
+});
+```
+## Using Services
+### In Components
+```typescript
+makeJayStackComponent<MyContract>()
+  .withServices(PRODUCTS_DB)
+  .withSlowlyRender(async (props, db) => {
+    const product = await db.getProduct(props.slug);
+    return phaseOutput({ title: product.name }, {});
+  });
+```
+### In Actions
+```typescript
+makeJayAction('products.search')
+  .withServices(PRODUCTS_DB)
+  .withHandler(async (input, db) => {
+    return db.search(input.query);
+  });
+```
+### In loadParams
+```typescript
+.withServices(PRODUCTS_DB)
+.withLoadParams(async function* (db) {
+    const products = await db.getAll();
+    yield products.map(p => ({ slug: p.slug }));
+})
+```
+## Listing in plugin.yaml
+If your plugin provides services for other plugins to consume, list them in `plugin.yaml`:
+```yaml
+services:
+  - name: products-db
+    marker: PRODUCTS_DB
+    description: Product catalog database API (query, search, get by slug)
+    doc: ./docs/products-db-service.md # optional — markdown documentation
+```
+This makes the service discoverable in `plugins-index.yaml`. If `doc` is provided, the file must exist and be exported from the package.
+## Service Lifecycle
+- Services are registered during `makeJayInit().withServer()` callbacks
+- Registration order follows plugin dependency order
+- Services are available to all components and actions after init
+- Services are server-side only — they are not sent to the client

package/agent-kit-template/plugin/validation.md ADDED Viewed

@@ -0,0 +1,101 @@
+# Plugin Validation
+Run `jay-stack validate-plugin` to check your plugin for errors.
+## Usage
+```bash
+# Validate the current plugin
+jay-stack validate-plugin
+# Validate a specific plugin path
+jay-stack validate-plugin --path ./src/plugins/my-plugin
+# Verbose output
+jay-stack validate-plugin -v
+```
+## What It Checks
+### Contract Validation
+- YAML structure is valid
+- All required fields are present (`name`, `tags`)
+- Tag types are valid (`data`, `variant`, `interactive`, `sub-contract`)
+- `dataType` is valid for the tag type
+- `trackBy` references an existing data tag with string/number type
+- `repeated` sub-contracts have `trackBy`
+- Phase constraints are satisfied (children >= parent for arrays)
+- No duplicate tag names at the same level
+- Props have valid types and unique names
+### Plugin Structure
+- `plugin.yaml` exists and is valid YAML
+- Contract files referenced in `plugin.yaml` exist
+- Component export names are valid strings (not file paths)
+- Action metadata files (`.jay-action`) exist
+### Type Generation
+- Contracts compile to valid TypeScript types
+- Generated ViewState, Refs, Props, and Params interfaces are correct
+## Common Errors
+### "trackBy references non-existent tag"
+The `trackBy` field must reference a `data` tag within the same sub-contract:
+```yaml
+# Wrong — trackBy references a tag that doesn't exist
+- tag: items
+  type: sub-contract
+  repeated: true
+  trackBy: itemId # No tag named "itemId"
+  tags:
+    - tag: id # Should be "itemId" or trackBy should be "id"
+      type: data
+      dataType: string
+```
+### "Child phase earlier than parent"
+Array children must have phase >= parent:
+```yaml
+# Wrong
+- tag: items
+  type: sub-contract
+  repeated: true
+  trackBy: id
+  phase: fast
+  tags:
+    - tag: name
+      type: data
+      phase: slow # Error: slow < fast
+```
+### "Interactive tag cannot have explicit phase"
+Interactive tags are always `fast+interactive`:
+```yaml
+# Wrong
+- tag: button
+  type: interactive
+  elementType: HTMLButtonElement
+  phase: slow # Error: remove this line
+```
+### "Component looks like a path"
+The `component` field in `plugin.yaml` should be an export name, not a file path:
+```yaml
+# Wrong
+component: ./lib/components/product-page.ts
+# Right
+component: productPage
+```