@jay-framework/jay-stack-cli 0.16.2 → 0.16.4

package/agent-kit-template/developer/page-components.md

@@ -125,6 +125,16 @@ src/pages/products/[slug]/
 
 The jay-html template uses unprefixed bindings for page data and key-prefixed bindings for plugin data.
 
+## Note on `.withClientDefaults()`
+
+`withClientDefaults` is only needed when a headless component is used **inside a `forEach`** and new items can be added on the client (e.g., "Add Item" button). It provides initial ViewState for instances that don't exist during SSR.
+
+You do NOT need it for:
+
+- Components outside forEach — `withFastRender` provides SSR initial state
+- Components inside a conditional (`if=`) — server data is computed for all discovered instances regardless of the condition's SSR value
+- Static forEach where all items come from the server
+
 ## Builder API Reference
 
 See the plugin [component-structure.md](../plugin/component-structure.md) for the full builder API: `.withProps()`, `.withServices()`, `.withContexts()`, phase rendering, and render results.

package/agent-kit-template/plugin/INSTRUCTIONS.md

@@ -13,7 +13,8 @@ A plugin provides headless components (data + interactions, no UI) that project
 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`
+6. **Configure build** — dual entry points (server + client), vite.config.ts, package.json exports
+7. **Validate** with `jay-stack validate-plugin`
 
 ## Guides
 

package/agent-kit-template/plugin/component-structure.md

@@ -96,17 +96,20 @@ Runs on each request. Receives props (including `query` for query parameters) an
 })
 ```
 
-### `.withClientDefaults(fn)` — Default client ViewState
+### `.withClientDefaults(fn)` — Defaults for dynamically created forEach items
 
-Provides default values for client-side ViewState before hydration:
+Required only when the component is used inside a `forEach` where new items can be added on the client. When a user adds a new item to a forEach array, the new instance has no server data — `withClientDefaults` provides the initial ViewState.
 
 ```typescript
-.withClientDefaults(() => ({
-    quantity: 1,
-    selectedVariant: 'default',
+.withClientDefaults((props) => ({
+    viewState: { label: `Item ${props.itemId}`, value: 0 },
+    carryForward: {},
 }))
 ```
 
+**When to use:** Component inside `forEach` + items can be added client-side.
+**When NOT to use:** Components outside forEach, or forEach with server-only items. Use `withFastRender` instead for SSR initial state.
+
 ### `.withInteractive(ComponentConstructor)` — Client-side logic
 
 The interactive phase runs in the browser. Use hooks here (see component-state.md):

package/agent-kit-template/plugin/contracts-guide.md

@@ -83,7 +83,15 @@ Linked (reference another contract file):
 ```yaml
 - tag: author
   type: sub-contract
-  link: ./author.jay-contract
+  link: ./author.jay-contract # relative path (same package)
+```
+
+For dynamic/materialized contracts linking to static contracts in a plugin package, use the package path:
+
+```yaml
+- tag: gallery
+  type: sub-contract
+  link: '@my-org/my-plugin/media-gallery' # package path (cross-directory)
 ```
 
 ### `sub-contract` with `repeated: true` — Arrays

package/agent-kit-template/plugin/plugin-structure.md

@@ -19,6 +19,16 @@ contracts:
     component: productSearch
     description: Product listing with filters and pagination
 
+dynamic_contracts:
+  # Single contract: prefix used as the contract name directly
+  - prefix: product-page
+    component: productPage
+    generator: productPageContractGenerator
+  # Multiple contracts: prefix/name format (e.g., list/recipes, list/articles)
+  - prefix: list
+    component: dynamicList
+    generator: listContractGenerator
+
 actions:
   - name: searchProducts
     action: search-products.jay-action
@@ -56,6 +66,49 @@ setup:
 - `component` — Export name of the component (e.g., `productPage`)
 - `description` — What this component does and when to use it
 
+### Dynamic Contract Entry Fields
+
+Dynamic contracts are generated at setup time from site-specific data (e.g., CMS collection schemas, extended product fields).
+
+- `prefix` — Identifier for this dynamic contract group. Used as the contract name for single contracts, or as `prefix/name` for multiple.
+- `component` — Export name of the headless component that serves these contracts
+- `generator` — Export name of the generator function that produces contract YAML
+
+**Single contract** — generator returns one `{ yaml }` without a name:
+
+```yaml
+dynamic_contracts:
+  - prefix: product-page
+    component: productPage
+    generator: productPageContractGenerator
+```
+
+Referenced as `contract="product-page"` in jay-html.
+
+**Multiple contracts** — generator yields `{ name, yaml }` for each:
+
+```yaml
+dynamic_contracts:
+  - prefix: list
+    component: dynamicList
+    generator: listContractGenerator
+```
+
+Referenced as `contract="list/recipes"`, `contract="list/articles"` etc.
+
+Contracts are materialized by `jay-stack agent-kit` or `jay-stack setup` and stored in `agent-kit/materialized-contracts/`.
+
+**Linking to static contracts from generated YAML** — materialized contracts live in a different directory than the plugin source. Use the plugin's package path (not relative paths) for `link:` references to static contracts:
+
+```yaml
+# In the generated contract YAML:
+tags:
+  - tag: gallery
+    type: sub-contract
+    link: '@my-org/my-plugin/media-gallery' # package path — works from any directory
+    # NOT: link: ./media-gallery            # relative path — breaks in materialized location
+```
+
 ### Action Entry Fields
 
 - `name` — Action name (used with `jay-stack action <plugin>/<action>`)
@@ -161,22 +214,101 @@ my-project/
 
 See `examples/jay-stack/fake-shop` for a working example.
 
+## Dual Entry Points
+
+Jay plugins are fullstack — they run on both server and client. The build produces two bundles:
+
+- **Server** (`dist/index.js`) — actions, services, SSR rendering, `init()`. Built with `vite build --ssr`.
+- **Client** (`dist/index.client.js`) — components for hydration, context tokens, `init()`. Built with `vite build`.
+
+Create two entry files:
+
+| File                  | Exports                                                    |
+| --------------------- | ---------------------------------------------------------- |
+| `lib/index.ts`        | Actions, services, components (SSR), init, service markers |
+| `lib/index.client.ts` | Components (hydration), context markers, init              |
+
+Actions and service providers are server-only. Components appear in **both** entries.
+
+## Build Scripts
+
+```json
+{
+  "scripts": {
+    "build": "npm run clean && npm run definitions && npm run build:client && npm run build:server && npm run build:copy-assets && npm run build:types && npm run validate",
+    "definitions": "jay-cli definitions lib",
+    "build:client": "vite build",
+    "build:server": "vite build --ssr",
+    "build:copy-assets": "cp lib/*.jay-contract* dist/",
+    "build:types": "tsup lib/index.ts lib/index.client.ts --dts-only --format esm",
+    "validate": "jay-stack-cli validate-plugin",
+    "clean": "rimraf dist"
+  }
+}
+```
+
+The `vite.config.ts` uses `isSsrBuild` to switch entry points:
+
+```typescript
+import { resolve } from 'path';
+import { defineConfig } from 'vite';
+import { jayStackCompiler } from '@jay-framework/compiler-jay-stack';
+
+const jayOptions = { tsConfigFilePath: resolve(__dirname, 'tsconfig.json'), outputDir: 'build' };
+
+export default defineConfig(({ isSsrBuild }) => ({
+  plugins: [...jayStackCompiler(jayOptions)],
+  build: {
+    minify: false,
+    ssr: isSsrBuild,
+    emptyOutDir: false,
+    lib: {
+      entry: isSsrBuild
+        ? { index: resolve(__dirname, 'lib/index.ts') }
+        : { 'index.client': resolve(__dirname, 'lib/index.client.ts') },
+      formats: ['es'],
+    },
+    rollupOptions: {
+      external: [
+        '@jay-framework/component',
+        '@jay-framework/fullstack-component',
+        '@jay-framework/stack-client-runtime',
+        '@jay-framework/stack-server-runtime',
+        '@jay-framework/reactive',
+        '@jay-framework/runtime',
+      ],
+    },
+  },
+}));
+```
+
 ## package.json Exports
 
-For NPM packages, declare exports so the framework can resolve the plugin:
+For NPM packages, declare exports for both server and client entry points:
 
 ```json
 {
   "name": "@my-org/my-plugin",
   "type": "module",
+  "main": "dist/index.js",
   "exports": {
-    ".": "./dist/index.js",
-    "./plugin.yaml": "./plugin.yaml"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/index.client.d.ts",
+      "default": "./dist/index.client.js"
+    },
+    "./plugin.yaml": "./plugin.yaml",
+    "./my-contract.jay-contract": "./dist/my-contract.jay-contract"
   },
-  "files": ["dist", "plugin.yaml", "lib/contracts", "lib/actions"]
+  "files": ["dist", "plugin.yaml"]
 }
 ```
 
+The `./client` export is required — the framework uses it for browser-side hydration code. The `.` export handles server-side rendering and action execution.
+
 ## Plugin-Contributed Agent-Kit Guides
 
 A plugin can include guides that are merged into the project's agent-kit during `jay-stack agent-kit`. Create an `agent-kit/` folder with subfolders for each role:
@@ -192,6 +324,34 @@ my-plugin/
         └── my-plugin-extending.md  # How to extend the plugin
 ```
 
+For NPM packages, include `agent-kit` in the `files` array:
+
+```json
+{
+  "files": ["dist", "plugin.yaml", "agent-kit"]
+}
+```
+
+No `plugin.yaml` declaration needed — the CLI discovers guides by scanning the `agent-kit/` directory. Files are copied as-is into the project's `agent-kit/{role}/`.
+
+**File format convention:** The first line after the `#` heading is used as the description in the INSTRUCTIONS.md index table. Write it as a short sentence explaining when to use this guide:
+
+```markdown
+# Scroll Carousel
+
+Horizontal slider with prev/next buttons and edge detection. Headless component — requires import.
+
+## Import
+
+...
+```
+
+The INSTRUCTIONS.md table will show:
+
+```
+| scroll-carousel.md | my-plugin | Horizontal slider with prev/next buttons and edge detection. Headless component — requires import. |
+```
+
 ## Reference Declarations
 
 Plugins can declare reference data generated by `jay-stack agent-kit`:

package/dist/index.js

@@ -8,15 +8,19 @@ import path from "path";
 import fs, { promises } from "fs";
 import YAML from "yaml";
 import { getLogger, createDevLogger, setDevLogger } from "@jay-framework/logger";
-import { parseJayFile, JAY_IMPORT_RESOLVER, generateElementDefinitionFile, ContractTagType, parseContract, generateElementFile, htmlElementTagNameMap } from "@jay-framework/compiler-jay-html";
+import { parseJayFile, JAY_IMPORT_RESOLVER, generateElementDefinitionFile, ContractTagType, parseContract, generateElementFile, generateServerElementFile, htmlElementTagNameMap } from "@jay-framework/compiler-jay-html";
 import { JAY_CONTRACT_EXTENSION, JAY_EXTENSION, resolvePluginManifest, LOCAL_PLUGIN_PATH, JayAtomicType, JayEnumType, loadPluginManifest, RuntimeMode, GenerateTarget } from "@jay-framework/compiler-shared";
-import { listContracts, materializeContracts } from "@jay-framework/stack-server-runtime";
+import { scanPlugins as scanPlugins$1, listContracts, materializeContracts } from "@jay-framework/stack-server-runtime";
 import { listContracts as listContracts2, materializeContracts as materializeContracts2 } from "@jay-framework/stack-server-runtime";
 import { Command } from "commander";
 import chalk from "chalk";
 import { createRequire } from "module";
 import { glob } from "glob";
 import { parse } from "node-html-parser";
+import path$1 from "node:path";
+import fs$1 from "node:fs/promises";
+import fsSync from "node:fs";
+import { fileURLToPath } from "node:url";
 const DEFAULT_CONFIG = {
   devServer: {
     portRange: [3e3, 3100],
@@ -3452,6 +3456,14 @@ async function validatePackageJson(context, result) {
           suggestion: 'Add "." export for the main module entry'
         });
       }
+      if (!packageJson.exports["./client"]) {
+        result.warnings.push({
+          type: "export-mismatch",
+          message: 'package.json exports missing "./client" entry point',
+          location: packageJsonPath,
+          suggestion: 'Add "./client": "./dist/index.client.js" to exports. The client bundle provides components for hydration and client-side contexts. Build with: vite build (client) + vite build --ssr (server)'
+        });
+      }
       if (context.manifest.contracts) {
         for (const contract of context.manifest.contracts) {
           const contractExport = "./" + contract.contract;
@@ -4159,6 +4171,16 @@ async function validateJayFiles(options = {}) {
       } else if (options.verbose) {
         getLogger().info(chalk.green(`✓ ${relativePath}`));
       }
+      const serverElementFile = generateServerElementFile(parsedFile.val);
+      if (serverElementFile.validations.length > 0) {
+        for (const validation of serverElementFile.validations) {
+          errors.push({
+            file: relativePath,
+            message: `[SSR] ${validation}`,
+            stage: "generate"
+          });
+        }
+      }
     } catch (error) {
       errors.push({
         file: relativePath,
@@ -4622,32 +4644,101 @@ program.command("validate-plugin [path]").description("Validate a Jay Stack plug
 });
 const ALL_ROLES = ["designer", "developer", "plugin"];
 async function ensureAgentKitDocs(projectRoot, _force, mode) {
-  const path2 = await import("node:path");
-  const fs2 = await import("node:fs/promises");
-  const { fileURLToPath } = await import("node:url");
-  const agentKitDir = path2.join(projectRoot, "agent-kit");
-  const thisDir = path2.dirname(fileURLToPath(import.meta.url));
-  const templateDir = path2.resolve(thisDir, "..", "agent-kit-template");
+  const agentKitDir = path$1.join(projectRoot, "agent-kit");
+  const thisDir = path$1.dirname(fileURLToPath(import.meta.url));
+  const templateDir = path$1.resolve(thisDir, "..", "agent-kit-template");
   const roles = mode && ALL_ROLES.includes(mode) ? [mode] : ALL_ROLES;
   for (const role of roles) {
-    const roleTemplateDir = path2.join(templateDir, role);
-    const roleOutputDir = path2.join(agentKitDir, role);
+    const roleTemplateDir = path$1.join(templateDir, role);
+    const roleOutputDir = path$1.join(agentKitDir, role);
     let files;
     try {
-      files = (await fs2.readdir(roleTemplateDir)).filter((f) => f.endsWith(".md"));
+      files = (await fs$1.readdir(roleTemplateDir)).filter((f) => f.endsWith(".md"));
     } catch {
       continue;
     }
-    await fs2.mkdir(roleOutputDir, { recursive: true });
+    await fs$1.mkdir(roleOutputDir, { recursive: true });
     for (const filename of files) {
-      await fs2.copyFile(
-        path2.join(roleTemplateDir, filename),
-        path2.join(roleOutputDir, filename)
+      await fs$1.copyFile(
+        path$1.join(roleTemplateDir, filename),
+        path$1.join(roleOutputDir, filename)
       );
       getLogger().info(chalk.gray(`   Created agent-kit/${role}/${filename}`));
     }
   }
 }
+async function mergePluginAgentKitGuides(projectRoot, mode) {
+  const plugins = await scanPlugins$1({ projectRoot });
+  const agentKitDir = path$1.join(projectRoot, "agent-kit");
+  const roles = mode && ALL_ROLES.includes(mode) ? [mode] : ALL_ROLES;
+  const copiedPerRole = /* @__PURE__ */ new Map();
+  for (const [, plugin] of plugins) {
+    const pluginAgentKitDir = path$1.join(plugin.pluginPath, "agent-kit");
+    if (!fsSync.existsSync(pluginAgentKitDir))
+      continue;
+    for (const role of roles) {
+      const roleSourceDir = path$1.join(pluginAgentKitDir, role);
+      let files;
+      try {
+        files = (await fs$1.readdir(roleSourceDir)).filter(
+          (f) => f.endsWith(".md") && f !== "INSTRUCTIONS.md"
+        );
+      } catch {
+        continue;
+      }
+      if (files.length === 0)
+        continue;
+      const roleOutputDir = path$1.join(agentKitDir, role);
+      await fs$1.mkdir(roleOutputDir, { recursive: true });
+      for (const filename of files) {
+        const sourcePath = path$1.join(roleSourceDir, filename);
+        await fs$1.copyFile(sourcePath, path$1.join(roleOutputDir, filename));
+        let description = "";
+        try {
+          const content = await fs$1.readFile(sourcePath, "utf-8");
+          const lines = content.split("\n");
+          let pastHeading = false;
+          for (const line of lines) {
+            if (line.startsWith("# ")) {
+              pastHeading = true;
+              continue;
+            }
+            if (pastHeading && line.trim()) {
+              description = line.trim();
+              break;
+            }
+          }
+        } catch {
+        }
+        if (!copiedPerRole.has(role))
+          copiedPerRole.set(role, []);
+        copiedPerRole.get(role).push({ filename, pluginName: plugin.name, description });
+        getLogger().info(
+          chalk.gray(
+            `   Copied agent-kit/${role}/${filename} from plugin "${plugin.name}"`
+          )
+        );
+      }
+    }
+  }
+  for (const [role, entries] of copiedPerRole) {
+    const instructionsPath = path$1.join(agentKitDir, role, "INSTRUCTIONS.md");
+    if (!fsSync.existsSync(instructionsPath))
+      continue;
+    const lines = [
+      "",
+      "## Plugin-Contributed Guides",
+      "",
+      "| File | Plugin | Description |",
+      "| --- | --- | --- |"
+    ];
+    for (const { filename, pluginName, description } of entries) {
+      lines.push(`| [${filename}](${filename}) | ${pluginName} | ${description} |`);
+    }
+    lines.push("");
+    await fs$1.appendFile(instructionsPath, lines.join("\n"));
+  }
+}
 async function generatePluginReferences(projectRoot, options, initErrors, viteServer) {
   const { discoverPluginsWithReferences, executePluginReferences } = await import("@jay-framework/stack-server-runtime");
   const plugins = await discoverPluginsWithReferences({
@@ -4782,6 +4873,7 @@ program.command("agent-kit").description(
   try {
     if (!options.list) {
       await ensureAgentKitDocs(projectRoot, options.force, options.mode);
+      await mergePluginAgentKitGuides(projectRoot, options.mode);
       if (options.references !== false) {
         await generatePluginReferences(projectRoot, options, initErrors, viteServer);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/jay-stack-cli",
-  "version": "0.16.2",
+  "version": "0.16.4",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -24,14 +24,14 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-html": "^0.16.2",
-    "@jay-framework/compiler-shared": "^0.16.2",
-    "@jay-framework/dev-server": "^0.16.2",
-    "@jay-framework/editor-server": "^0.16.2",
-    "@jay-framework/fullstack-component": "^0.16.2",
-    "@jay-framework/logger": "^0.16.2",
-    "@jay-framework/plugin-validator": "^0.16.2",
-    "@jay-framework/stack-server-runtime": "^0.16.2",
+    "@jay-framework/compiler-jay-html": "^0.16.4",
+    "@jay-framework/compiler-shared": "^0.16.4",
+    "@jay-framework/dev-server": "^0.16.4",
+    "@jay-framework/editor-server": "^0.16.4",
+    "@jay-framework/fullstack-component": "^0.16.4",
+    "@jay-framework/logger": "^0.16.4",
+    "@jay-framework/plugin-validator": "^0.16.4",
+    "@jay-framework/stack-server-runtime": "^0.16.4",
     "chalk": "^4.1.2",
     "commander": "^14.0.0",
     "express": "^5.0.1",
@@ -42,7 +42,7 @@
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.16.2",
+    "@jay-framework/dev-environment": "^0.16.4",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",