@jay-framework/jay-stack-cli 0.13.0 → 0.14.0

package/agent-kit-template/INSTRUCTIONS.md

@@ -26,7 +26,7 @@ There is no standalone "interactive" phase. Any tag with `type: interactive` (re
 ## Workflow
 
 1. **Read this file** for overview and workflow
-2. **Discover plugins** — read `materialized-contracts/plugins-index.yaml` to see available plugins, contracts, and actions. Read `materialized-contracts/contracts-index.yaml` for the full contract list.
+2. **Discover plugins** — read `plugins-index.yaml` to see available plugins, contracts, and actions.
 3. **Read contracts** — read the `.jay-contract` files (paths from plugins-index) to understand data shapes, tag types, phases, and props.
 4. **Read actions** — read `.jay-action` files (paths from plugins-index) to see action descriptions, input schemas, and output schemas. This tells you what data each action accepts and returns.
 5. **Read references** — check `references/<plugin>/` for pre-generated discovery data (product catalogs, collection schemas, etc.). These are generated by `jay-stack agent-kit` and contain real data from the site.
@@ -50,7 +50,7 @@ There is no standalone "interactive" phase. Any tag with `type: interactive` (re
 
 ### 1. Discover plugins and contracts
 
-Read `materialized-contracts/plugins-index.yaml`:
+Read `plugins-index.yaml`:
 
 ```yaml
 plugins:

package/agent-kit-template/cli-commands.md

@@ -50,8 +50,7 @@ jay-stack agent-kit --no-references
 
 Outputs:
 
-- `materialized-contracts/contracts-index.yaml`
-- `materialized-contracts/plugins-index.yaml`
+- `plugins-index.yaml`
 - `materialized-contracts/<plugin>/*.jay-contract` (dynamic contracts)
 - `references/<plugin>/` — plugin reference data (product catalogs, collection schemas, etc.)
 - Documentation files (INSTRUCTIONS.md and reference docs)

package/agent-kit-template/contracts-and-plugins.md

@@ -2,10 +2,9 @@
 
 ## Discovery: Plugins Index
 
-After running `jay-stack agent-kit`, read `materialized-contracts/plugins-index.yaml`:
+After running `jay-stack agent-kit`, read `plugins-index.yaml`:
 
 ```yaml
-materialized_at: '2026-02-09T...'
 jay_stack_version: '1.0.0'
 plugins:
   - name: wix-stores
@@ -37,18 +36,6 @@ Fields:
 - `actions[].description` — short description of what the action does
 - `actions[].path` — path to the `.jay-action` file with full input/output schemas
 
-## Discovery: Contracts Index
-
-`materialized-contracts/contracts-index.yaml` lists all contracts across all plugins:
-
-```yaml
-contracts:
-  - plugin: wix-stores
-    name: product-page
-    type: static
-    path: ./node_modules/@wix/stores/lib/contracts/product-page.jay-contract
-```
-
 ## Reading plugin.yaml
 
 Each plugin has a `plugin.yaml` at its root (the `path` from plugins-index):
@@ -249,16 +236,16 @@ outputSchema:
 
 Schemas use a compact type notation:
 
-| Notation | Meaning |
-| --- | --- |
-| `propName: string` | Required string property |
-| `propName?: number` | Optional number property |
-| `propName: boolean` | Required boolean |
-| `propName: enum(a \| b \| c)` | Required enum |
-| `propName:` + nested block | Nested object |
-| `propName:` + `- childProp: type` | Array of objects (YAML list) |
-| `propName: importedName` | Type from `import:` block (references a `.jay-contract`) |
-| `- importedName` | Array of imported type |
+| Notation                          | Meaning                                                  |
+| --------------------------------- | -------------------------------------------------------- |
+| `propName: string`                | Required string property                                 |
+| `propName?: number`               | Optional number property                                 |
+| `propName: boolean`               | Required boolean                                         |
+| `propName: enum(a \| b \| c)`     | Required enum                                            |
+| `propName:` + nested block        | Nested object                                            |
+| `propName:` + `- childProp: type` | Array of objects (YAML list)                             |
+| `propName: importedName`          | Type from `import:` block (references a `.jay-contract`) |
+| `- importedName`                  | Array of imported type                                   |
 
 ### Using Action Metadata
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { LogLevel } from '@jay-framework/logger';
 import { PublishMessage, PublishResponse, SaveImageMessage, SaveImageResponse, HasImageMessage, HasImageResponse, GetProjectInfoMessage, GetProjectInfoResponse, ExportMessage, ExportResponse, ImportMessage, ImportResponse, ProjectPage, Plugin } from '@jay-framework/editor-protocol';
-export { ContractIndexEntry, ContractsIndex, MaterializeContractsOptions, MaterializeResult, listContracts, materializeContracts } from '@jay-framework/stack-server-runtime';
+export { MaterializeContractsOptions, MaterializeResult, PluginContractEntry, PluginsIndex, PluginsIndexEntry, listContracts, materializeContracts } from '@jay-framework/stack-server-runtime';
 
 interface StartDevServerOptions {
     projectPath?: string;

package/dist/index.js

@@ -2402,7 +2402,7 @@ async function startDevServer(options = {}) {
   const resolvedConfig = getConfigWithDefaults(config);
   const jayOptions = {
     tsConfigFilePath: "./tsconfig.json",
-    outputDir: "build/jay-runtime"
+    outputDir: "build"
   };
   const app = express();
   const devServerPort = await getPort({ port: resolvedConfig.devServer.portRange });
@@ -2441,7 +2441,6 @@ async function startDevServer(options = {}) {
     pagesRootFolder: path.resolve(resolvedConfig.devServer.pagesBase),
     projectRootFolder: process.cwd(),
     publicBaseUrlPath: "/",
-    dontCacheSlowly: false,
     jayRollupConfig: jayOptions,
     logLevel: options.logLevel
   });
@@ -2934,13 +2933,206 @@ async function findJayFiles(dir) {
 async function findContractFiles(dir) {
   return await glob(`${dir}/**/*${JAY_CONTRACT_EXTENSION}`);
 }
+function flattenContractTags(tags, prefix) {
+  const result = [];
+  for (const tag of tags) {
+    const tagPath = prefix ? `${prefix}.${tag.tag}` : tag.tag;
+    result.push({ path: tagPath, required: tag.required === true });
+    if (tag.tags) {
+      result.push(...flattenContractTags(tag.tags, tagPath));
+    }
+  }
+  return result;
+}
+function extractExpressions(text) {
+  const results = [];
+  const regex = /\{([^}]+)\}/g;
+  let match;
+  while ((match = regex.exec(text)) !== null) {
+    results.push(match[1].trim());
+  }
+  return results;
+}
+function extractTagPath(expr) {
+  let cleaned = expr.replace(/^!/, "").trim();
+  cleaned = cleaned.split(/\s*[!=]==?\s*/)[0].trim();
+  if (cleaned === "." || cleaned === "")
+    return null;
+  if (/^[a-zA-Z_$][a-zA-Z0-9_$]*(\.[a-zA-Z_$][a-zA-Z0-9_$]*)*$/.test(cleaned)) {
+    return cleaned;
+  }
+  return null;
+}
+const SKIP_ATTRS = /* @__PURE__ */ new Set([
+  "forEach",
+  "if",
+  "ref",
+  "trackBy",
+  "slowForEach",
+  "jayIndex",
+  "jayTrackBy",
+  "when-resolved",
+  "when-loading",
+  "when-rejected",
+  "accessor"
+]);
+function collectUsedTags(jayHtml) {
+  const imports = jayHtml.headlessImports;
+  const usedTags = /* @__PURE__ */ new Map();
+  const keyMap = /* @__PURE__ */ new Map();
+  for (let i = 0; i < imports.length; i++) {
+    if (imports[i].contract) {
+      usedTags.set(i, /* @__PURE__ */ new Set());
+      if (imports[i].key) {
+        keyMap.set(imports[i].key, i);
+      }
+    }
+  }
+  function markUsed(importIndex, tagPath) {
+    usedTags.get(importIndex)?.add(tagPath);
+  }
+  function resolvePath(path2, scopes) {
+    const dot = path2.indexOf(".");
+    if (dot !== -1) {
+      const key = path2.substring(0, dot);
+      const idx = keyMap.get(key);
+      if (idx !== void 0) {
+        markUsed(idx, path2.substring(dot + 1));
+        return;
+      }
+    }
+    if (scopes.length > 0) {
+      const scope = scopes[scopes.length - 1];
+      const full = scope.prefix ? `${scope.prefix}.${path2}` : path2;
+      markUsed(scope.importIndex, full);
+    }
+  }
+  function walkElement(element, scopes) {
+    const tagName = element.rawTagName?.toLowerCase();
+    let childScopes = scopes;
+    if (tagName?.startsWith("jay:")) {
+      const contractName = tagName.substring(4);
+      const idx = imports.findIndex(
+        (imp) => imp.contractName === contractName && imp.contract
+      );
+      if (idx !== -1) {
+        childScopes = [...scopes, { importIndex: idx, prefix: "" }];
+      }
+    }
+    const forEachVal = element.getAttribute?.("forEach");
+    if (forEachVal) {
+      const fePath = extractTagPath(forEachVal);
+      if (fePath) {
+        resolvePath(fePath, childScopes);
+        const dot = fePath.indexOf(".");
+        if (dot !== -1) {
+          const key = fePath.substring(0, dot);
+          const idx = keyMap.get(key);
+          if (idx !== void 0) {
+            childScopes = [
+              ...childScopes,
+              { importIndex: idx, prefix: fePath.substring(dot + 1) }
+            ];
+          }
+        } else if (childScopes.length > 0) {
+          const scope = childScopes[childScopes.length - 1];
+          const newPrefix = scope.prefix ? `${scope.prefix}.${fePath}` : fePath;
+          childScopes = [
+            ...childScopes,
+            { importIndex: scope.importIndex, prefix: newPrefix }
+          ];
+        }
+      }
+    }
+    if (tagName === "with-data") {
+      const accessor = element.getAttribute?.("accessor");
+      if (accessor && accessor !== "." && childScopes.length > 0) {
+        resolvePath(accessor, childScopes);
+        const scope = childScopes[childScopes.length - 1];
+        const newPrefix = scope.prefix ? `${scope.prefix}.${accessor}` : accessor;
+        childScopes = [
+          ...childScopes,
+          { importIndex: scope.importIndex, prefix: newPrefix }
+        ];
+      }
+    }
+    const ifVal = element.getAttribute?.("if");
+    if (ifVal) {
+      const ifPath = extractTagPath(ifVal);
+      if (ifPath)
+        resolvePath(ifPath, scopes);
+    }
+    const refVal = element.getAttribute?.("ref");
+    if (refVal) {
+      resolvePath(refVal, scopes);
+    }
+    const attrs = element.attributes ?? {};
+    for (const [name, value] of Object.entries(attrs)) {
+      if (SKIP_ATTRS.has(name))
+        continue;
+      for (const expr of extractExpressions(value)) {
+        const p = extractTagPath(expr);
+        if (p)
+          resolvePath(p, scopes);
+      }
+    }
+    for (const child of element.childNodes ?? []) {
+      if (child.nodeType === 3) {
+        const text = child.rawText ?? child.text ?? "";
+        for (const expr of extractExpressions(text)) {
+          const p = extractTagPath(expr);
+          if (p)
+            resolvePath(p, childScopes);
+        }
+      } else if (child.nodeType === 1) {
+        walkElement(child, childScopes);
+      }
+    }
+  }
+  walkElement(jayHtml.body, []);
+  return usedTags;
+}
+function analyzeTagCoverage(jayHtml, file) {
+  const imports = jayHtml.headlessImports;
+  const withContracts = imports.filter((imp) => imp.contract);
+  if (withContracts.length === 0)
+    return null;
+  const usedTagsMap = collectUsedTags(jayHtml);
+  const contracts = [];
+  for (let i = 0; i < imports.length; i++) {
+    const imp = imports[i];
+    if (!imp.contract)
+      continue;
+    const allTags = flattenContractTags(imp.contract.tags);
+    const usedSet = usedTagsMap.get(i) ?? /* @__PURE__ */ new Set();
+    const expanded = new Set(usedSet);
+    for (const usedPath of usedSet) {
+      const segments = usedPath.split(".");
+      for (let j = 1; j < segments.length; j++) {
+        expanded.add(segments.slice(0, j).join("."));
+      }
+    }
+    const unused = allTags.filter((t) => !expanded.has(t.path));
+    const requiredUnused = unused.filter((t) => t.required);
+    contracts.push({
+      key: imp.key,
+      contractName: imp.contractName,
+      totalTags: allTags.length,
+      usedTags: allTags.length - unused.length,
+      unusedTags: unused.map((t) => t.path),
+      requiredUnusedTags: requiredUnused.map((t) => t.path)
+    });
+  }
+  return { file, contracts };
+}
 async function validateJayFiles(options = {}) {
   const config = loadConfig();
   const resolvedConfig = getConfigWithDefaults(config);
-  const projectRoot = process.cwd();
+  const projectRoot = options.projectRoot ?? process.cwd();
   const scanDir = options.path ? path.resolve(options.path) : path.resolve(resolvedConfig.devServer.pagesBase);
   const errors = [];
   const warnings = [];
+  const coverage = [];
   const jayHtmlFiles = await findJayFiles(scanDir);
   const contractFiles = await findContractFiles(scanDir);
   if (options.verbose) {
@@ -3006,6 +3198,10 @@ async function validateJayFiles(options = {}) {
         }
         continue;
       }
+      const fileCoverage = analyzeTagCoverage(parsedFile.val, relativePath);
+      if (fileCoverage) {
+        coverage.push(fileCoverage);
+      }
       const generatedFile = generateElementFile(
         parsedFile.val,
         RuntimeMode.MainTrusted,
@@ -3041,7 +3237,8 @@ async function validateJayFiles(options = {}) {
     jayHtmlFilesScanned: jayHtmlFiles.length,
     contractFilesScanned: contractFiles.length,
     errors,
-    warnings
+    warnings,
+    coverage
   };
 }
 function printJayValidationResult(result, options) {
@@ -3070,6 +3267,29 @@ function printJayValidationResult(result, options) {
       chalk.red(`${result.errors.length} error(s) found, ${validFiles} file(s) valid.`)
     );
   }
+  if (result.coverage.length > 0) {
+    logger.important("");
+    logger.important("Tag Coverage:");
+    for (const fileCov of result.coverage) {
+      logger.important(`  ${fileCov.file}`);
+      for (const contract of fileCov.contracts) {
+        const label = contract.key ? `${contract.key} (${contract.contractName})` : contract.contractName;
+        logger.important(
+          `    ${label}: ${contract.usedTags}/${contract.totalTags} tags used`
+        );
+        if (contract.unusedTags.length > 0) {
+          logger.important(chalk.gray(`      Unused: ${contract.unusedTags.join(", ")}`));
+        }
+        if (contract.requiredUnusedTags.length > 0) {
+          logger.important(
+            chalk.yellow(
+              `      ⚠ Required unused: ${contract.requiredUnusedTags.join(", ")}`
+            )
+          );
+        }
+      }
+    }
+  }
 }
 async function initializeServicesForCli(projectRoot, viteServer) {
   const path2 = await import("node:path");
@@ -3553,12 +3773,14 @@ async function runMaterialize(projectRoot, options, defaultOutputRelative, keepV
       services
     );
     if (options.yaml) {
-      getLogger().important(YAML.stringify(result.index));
+      getLogger().important(YAML.stringify(result.pluginsIndex));
     } else {
-      getLogger().important(
-        chalk.green(`
-✅ Materialized ${result.index.contracts.length} contracts`)
+      const totalContracts = result.pluginsIndex.plugins.reduce(
+        (sum, p) => sum + p.contracts.length,
+        0
       );
+      getLogger().important(chalk.green(`
+✅ Materialized ${totalContracts} contracts`));
       getLogger().important(`   Static: ${result.staticCount}`);
       getLogger().important(`   Dynamic: ${result.dynamicCount}`);
       getLogger().important(`   Output: ${result.outputDir}`);
@@ -3670,21 +3892,15 @@ function printValidationResult(result, verbose) {
 function printContractList(index) {
   const logger = getLogger();
   logger.important("\nAvailable Contracts:\n");
-  const byPlugin = /* @__PURE__ */ new Map();
-  for (const contract of index.contracts) {
-    const existing = byPlugin.get(contract.plugin) || [];
-    existing.push(contract);
-    byPlugin.set(contract.plugin, existing);
-  }
-  for (const [plugin, contracts] of byPlugin) {
-    logger.important(chalk.bold(`📦 ${plugin}`));
-    for (const contract of contracts) {
+  for (const plugin of index.plugins) {
+    logger.important(chalk.bold(`📦 ${plugin.name}`));
+    for (const contract of plugin.contracts) {
       const typeIcon = contract.type === "static" ? "📄" : "⚡";
       logger.important(`   ${typeIcon} ${contract.name}`);
     }
     logger.important("");
   }
-  if (index.contracts.length === 0) {
+  if (index.plugins.length === 0) {
     logger.important(chalk.gray("No contracts found."));
   }
 }

package/package.json

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