@jay-framework/jay-stack-cli 0.16.3 → 0.16.5

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/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>`)
@@ -271,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],
@@ -4167,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,
@@ -4630,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({
@@ -4790,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.3",
+  "version": "0.16.5",
   "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.3",
-    "@jay-framework/compiler-shared": "^0.16.3",
-    "@jay-framework/dev-server": "^0.16.3",
-    "@jay-framework/editor-server": "^0.16.3",
-    "@jay-framework/fullstack-component": "^0.16.3",
-    "@jay-framework/logger": "^0.16.3",
-    "@jay-framework/plugin-validator": "^0.16.3",
-    "@jay-framework/stack-server-runtime": "^0.16.3",
+    "@jay-framework/compiler-jay-html": "^0.16.5",
+    "@jay-framework/compiler-shared": "^0.16.5",
+    "@jay-framework/dev-server": "^0.16.5",
+    "@jay-framework/editor-server": "^0.16.5",
+    "@jay-framework/fullstack-component": "^0.16.5",
+    "@jay-framework/logger": "^0.16.5",
+    "@jay-framework/plugin-validator": "^0.16.5",
+    "@jay-framework/stack-server-runtime": "^0.16.5",
     "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.3",
+    "@jay-framework/dev-environment": "^0.16.5",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",