@jay-framework/stack-server-build 0.24.5 → 0.24.7

package/dist/index.d.ts

@@ -6,7 +6,7 @@ import { Contract, HeadlessContractInfo, DiscoveredHeadlessInstance, ForEachHead
 import { AnyJayStackComponentDefinition, HeadTag } from '@jay-framework/fullstack-component';
 import { JayRollupConfig } from '@jay-framework/rollup-plugin';
 import { TrackByMap } from '@jay-framework/view-state-merge';
-import { PluginClientInitInfo, ActionRegistry, ViteSSRLoader as ViteSSRLoader$1, PluginAgentKitResult, PluginSetupPrompt, PluginSetupResult } from '@jay-framework/stack-server-runtime';
+import { PluginClientInitInfo, ActionRegistry, ViteSSRLoader as ViteSSRLoader$1, ScannedPlugin, PluginAgentKitResult, PluginSetupPrompt, PluginSetupResult } from '@jay-framework/stack-server-runtime';
 export * from '@jay-framework/stack-server-runtime';
 export { PluginAgentKitContext, PluginAgentKitHandler, PluginAgentKitResult, PluginSetupContext, PluginSetupHandler, PluginSetupPrompt, PluginSetupResult } from '@jay-framework/stack-server-runtime';
 
@@ -408,6 +408,8 @@ interface PluginsIndexEntry {
 }
 interface PluginsIndex {
     plugins: PluginsIndexEntry[];
+    /** DL#204 — pointer to the sibling design-system index (region/template catalog). */
+    designSystemIndex?: string;
 }
 interface MaterializeContractsOptions {
     projectRoot: string;
@@ -437,6 +439,77 @@ declare function materializeContracts(options: MaterializeContractsOptions, serv
  */
 declare function listContracts(options: MaterializeContractsOptions): Promise<PluginsIndex>;
 
+/**
+ * Design-System Index (DL#204)
+ *
+ * Catalogs every headless component an agent could flatten as a `<jay:X>` region: its contract and
+ * the `.jay-html` template variants it ships. Two discovery sources, merged into one catalog:
+ *   1. Local components under `componentsBase` (default `./src/components`).
+ *   2. Plugin components (static `manifest.contracts`).
+ *
+ * Template↔contract association is by the template's *declared* contract reference
+ * (`<script type="application/jay-data" contract="…">`), not by a filename convention: a `.jay-html`
+ * is a variant of contract `X` iff its resolved `contract=` points at `X.jay-contract`. This handles
+ * a directory holding several contracts correctly and needs no new naming rule.
+ *
+ * @see Design Log #204 — A design-system (region/template) index in the agent-kit
+ */
+
+/** One `.jay-html` template that renders a given contract. */
+interface TemplateVariant {
+    /** Path to the `.jay-html` (absolute from the lookup helpers; project-relative in the emitted index). */
+    path: string;
+    /** Stable label: `''` for `<contract-basename>.jay-html`, else the filename stem (e.g. `card.feature`). */
+    variant: string;
+    /** From the template's `<title>` static text; omitted when empty or interpolation-only. */
+    title?: string;
+}
+/** One component (contract) and every template that renders it. */
+interface DesignSystemComponentEntry {
+    /** Contract name. */
+    name: string;
+    /** Path to the `.jay-contract` (project-relative in the emitted index). */
+    contractPath: string;
+    /** From the `.jay-contract` — a component-level property, read once (not per template). */
+    description?: string;
+    source: 'local' | 'plugin';
+    /** Plugin name when `source === 'plugin'`. */
+    plugin?: string;
+    /** Every `.jay-html` whose `contractRef` resolves to this contract. */
+    templates: TemplateVariant[];
+}
+interface DesignSystemIndex {
+    components: DesignSystemComponentEntry[];
+}
+/**
+ * DL#204 — every template variant for the contract at `contractFile`. A template counts when its
+ * resolved `contractRef` equals `contractFile` (reference match, not filename). Generalizes DL#200's
+ * boolean `hasTemplateForContractFile`.
+ */
+declare function listTemplatesForContractFile(contractFile: string | undefined): TemplateVariant[];
+/** DL#200/204 — does any `.jay-html` render this contract? Thin wrapper over the enumeration. */
+declare function hasTemplateForContractFile(contractFile: string | undefined): boolean;
+interface BuildDesignSystemIndexOptions {
+    projectRoot: string;
+    /** Local component root; default `./src/components` (same base `validate`/`sync` use). */
+    componentsBase?: string;
+    /** Scanned plugins (reuse the same scan plugins-index did). */
+    plugins: Map<string, ScannedPlugin>;
+    /** Resolves a plugin contract spec to an absolute `.jay-contract` path (shared with the materializer). */
+    resolvePluginContractPath: (plugin: ScannedPlugin, contractSpec: string) => string;
+}
+/**
+ * DL#204 — build the catalog from the two discovery sources. Dynamic (generated) plugin contracts are
+ * not included: they are materialized into agent-kit and have no co-located `.jay-html` to flatten.
+ */
+declare function buildDesignSystemIndex(options: BuildDesignSystemIndexOptions): DesignSystemIndex;
+/**
+ * DL#204 — render the human/agent "add-menu": the `<title>` catalog of components and their template
+ * variants, each with a paste-ready `template=` import + `<jay:X>` region. Generated from the same
+ * `DesignSystemIndex` object, so it can never drift from the YAML.
+ */
+declare function renderAddMenu(index: DesignSystemIndex): string;
+
 /**
  * Plugin CLI Commands (Design Log #142)
  *
@@ -680,4 +753,4 @@ declare class SlowRenderCache {
     private scanAndDeleteCacheFiles;
 }
 
-export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionIndexEntry, type ActionMetadata, type ActionSchema, type CommandFlag, type CommandIndexEntry, type CommandMetadata, type ContextIndexEntry, type DevServerPagePart, type DiscoveredCommand, type GenerateClientScriptOptions, type HeadlessInstanceComponent, type LoadPagePartsOptions, type LoadedPageParts, type MaterializeContractsOptions, type MaterializeResult, type PluginActionDiscoveryOptions, type PluginContractEntry, type PluginWithAgentKit, type PluginWithSetup, type PluginsIndex, type PluginsIndexEntry, type ProjectClientInitInfo, type RouteIndexEntry, type ScriptFragments, type ServiceIndexEntry, SetupNeedsAnswerError, SlowRenderCache, type SlowRenderCacheEntry, type ViteSSRLoader, buildAutomationWrap, buildPageReloadHmrScript, buildScriptFragments, clearServerElementCache, commandSchemaToFlags, discoverAllPluginActions, discoverAndRegisterActions, discoverPluginActions, discoverPluginCommands, discoverPluginsWithAgentKit, discoverPluginsWithSetup, executePluginAgentKit, executePluginCommand, executePluginSetup, generateClientScript, generateFrozenPageHtml, generatePromiseReconstruction, generateSSRPageHtml, headMetaToHeadTags, invalidateServerElementCache, listContracts, loadActionMetadata, loadPageParts, materializeContracts, parseActionMetadata, parseInputFromFlags, resolveActionMetadataPath, resolveClientImportPath, resolveViewStatePromises };
+export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionIndexEntry, type ActionMetadata, type ActionSchema, type BuildDesignSystemIndexOptions, type CommandFlag, type CommandIndexEntry, type CommandMetadata, type ContextIndexEntry, type DesignSystemComponentEntry, type DesignSystemIndex, type DevServerPagePart, type DiscoveredCommand, type GenerateClientScriptOptions, type HeadlessInstanceComponent, type LoadPagePartsOptions, type LoadedPageParts, type MaterializeContractsOptions, type MaterializeResult, type PluginActionDiscoveryOptions, type PluginContractEntry, type PluginWithAgentKit, type PluginWithSetup, type PluginsIndex, type PluginsIndexEntry, type ProjectClientInitInfo, type RouteIndexEntry, type ScriptFragments, type ServiceIndexEntry, SetupNeedsAnswerError, SlowRenderCache, type SlowRenderCacheEntry, type TemplateVariant, type ViteSSRLoader, buildAutomationWrap, buildDesignSystemIndex, buildPageReloadHmrScript, buildScriptFragments, clearServerElementCache, commandSchemaToFlags, discoverAllPluginActions, discoverAndRegisterActions, discoverPluginActions, discoverPluginCommands, discoverPluginsWithAgentKit, discoverPluginsWithSetup, executePluginAgentKit, executePluginCommand, executePluginSetup, generateClientScript, generateFrozenPageHtml, generatePromiseReconstruction, generateSSRPageHtml, hasTemplateForContractFile, headMetaToHeadTags, invalidateServerElementCache, listContracts, listTemplatesForContractFile, loadActionMetadata, loadPageParts, materializeContracts, parseActionMetadata, parseInputFromFlags, renderAddMenu, resolveActionMetadataPath, resolveClientImportPath, resolveViewStatePromises };

package/dist/index.js

@@ -4,19 +4,20 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 import fs$1 from "node:fs/promises";
 import * as path from "node:path";
 import path__default from "node:path";
-import { parseJayFile, JAY_IMPORT_RESOLVER, injectHeadfullFSTemplates, discoverHeadlessInstances, assignCoordinatesToJayHtml, generateServerElementFile, parseAction } from "@jay-framework/compiler-jay-html";
+import { parseJayFile, JAY_IMPORT_RESOLVER, discoverHeadlessInstances, assignCoordinatesToJayHtml, generateServerElementFile, parseAction } from "@jay-framework/compiler-jay-html";
+import { makePassthroughInstanceComponent, serializeHeadTags, mergeHeadTags, actionRegistry, scanPlugins, resolveServices, sortPluginsByDependencies, getServiceRegistry } from "@jay-framework/stack-server-runtime";
+export * from "@jay-framework/stack-server-runtime";
 import { createRequire } from "module";
 import jsBeautify from "js-beautify";
 import fs$2 from "fs";
 import path$1 from "path";
 import YAML from "yaml";
-import { serializeHeadTags, mergeHeadTags, actionRegistry, scanPlugins, resolveServices, sortPluginsByDependencies, getServiceRegistry } from "@jay-framework/stack-server-runtime";
-export * from "@jay-framework/stack-server-runtime";
 import crypto from "node:crypto";
 import { getLogger } from "@jay-framework/logger";
 import * as fs from "node:fs";
 import { createRequire as createRequire$1 } from "node:module";
 import { isJayAction, isJayStreamAction, isJayCliCommand } from "@jay-framework/fullstack-component";
+import { parse } from "node-html-parser";
 const require$3 = createRequire(import.meta.url);
 function resolveClientImportPath(route) {
   if (route.clientCompPath) return route.clientCompPath;
@@ -69,7 +70,14 @@ async function loadPageParts(vite, route, pagesBase, projectBase, jayRollupConfi
       let clientModuleImport;
       let isNpmPackage;
       if (headlessImport.structural) {
-        continue;
+        compDefinition = makePassthroughInstanceComponent(
+          (headlessImport.contract?.tags ?? []).map((t) => ({
+            name: t.tag,
+            phase: t.phase
+          }))
+        );
+        isNpmPackage = false;
+        clientModuleImport = "";
       } else {
         const modulePath = isLocalModule ? path__default.resolve(dirName, module) : require$3.resolve(module, { paths: require$3.resolve.paths(dirName) });
         compDefinition = (await vite.ssrLoadModule(modulePath))[name];
@@ -110,11 +118,7 @@ async function loadPageParts(vite, route, pagesBase, projectBase, jayRollupConfi
       contract: hi.contract,
       contractPath: hi.contractPath
     }));
-    const jayHtmlForDiscovery = injectHeadfullFSTemplates(
-      jayHtmlSource,
-      dirName,
-      JAY_IMPORT_RESOLVER
-    );
+    const jayHtmlForDiscovery = jayHtmlSource;
     let discoveryResult;
     if (headlessInstanceComponents.length > 0) {
       const firstDiscovery = discoverHeadlessInstances(jayHtmlForDiscovery);
@@ -151,6 +155,8 @@ async function loadPageParts(vite, route, pagesBase, projectBase, jayRollupConfi
 var __defProp2 = Object.defineProperty;
 var __defNormalProp2 = (obj, key, value) => key in obj ? __defProp2(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField2 = (obj, key, value) => __defNormalProp2(obj, key + "", value);
+const JAY_EXTENSION = ".jay-html";
+const JAY_CONTRACT_EXTENSION = ".jay-contract";
 class JayAtomicType {
   constructor(name) {
     __publicField2(this, "kind", 0);
@@ -1334,6 +1340,172 @@ async function discoverPluginActions(pluginPath, projectRoot, registry = actionR
   }
   return registeredActions;
 }
+function readTemplateMeta(jayHtmlPath) {
+  let content;
+  try {
+    content = fs.readFileSync(jayHtmlPath, "utf-8");
+  } catch {
+    return {};
+  }
+  const root = parse(content);
+  const ref = root.querySelector('script[type="application/jay-data"]')?.getAttribute("contract");
+  const contractRef = ref ? path.resolve(path.dirname(jayHtmlPath), ref) : void 0;
+  const rawTitle = root.querySelector("title")?.text?.trim();
+  const staticTitle = rawTitle ? rawTitle.replace(/\{[^}]*\}/g, "").trim() : "";
+  return { contractRef, title: staticTitle.length > 0 ? staticTitle : void 0 };
+}
+function listTemplatesForContractFile(contractFile) {
+  if (!contractFile) return [];
+  const dir = path.dirname(contractFile);
+  const target = path.resolve(contractFile);
+  const contractBasename = path.basename(contractFile, JAY_CONTRACT_EXTENSION);
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const variants = [];
+  for (const f of names) {
+    if (!f.endsWith(JAY_EXTENSION)) continue;
+    const jayHtmlPath = path.join(dir, f);
+    const meta = readTemplateMeta(jayHtmlPath);
+    if (meta.contractRef !== target) continue;
+    const stem = path.basename(f, JAY_EXTENSION);
+    variants.push({
+      path: jayHtmlPath,
+      variant: stem === contractBasename ? "" : stem,
+      ...meta.title && { title: meta.title }
+    });
+  }
+  return variants.sort((a, b) => a.variant.localeCompare(b.variant));
+}
+function hasTemplateForContractFile(contractFile) {
+  return listTemplatesForContractFile(contractFile).length > 0;
+}
+function readContractField(contractFile, field) {
+  try {
+    const parsed = YAML.parse(fs.readFileSync(contractFile, "utf-8"));
+    const value = parsed?.[field];
+    return typeof value === "string" ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function findContractFilesSync(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...findContractFilesSync(full));
+    else if (entry.name.endsWith(JAY_CONTRACT_EXTENSION)) out.push(full);
+  }
+  return out.sort();
+}
+function buildDesignSystemIndex(options) {
+  const { projectRoot, plugins, resolvePluginContractPath } = options;
+  const componentsBase = options.componentsBase ? path.resolve(projectRoot, options.componentsBase) : path.join(projectRoot, "src", "components");
+  const rel = (p) => "./" + path.relative(projectRoot, p).replace(/\\/g, "/");
+  const makeEntry = (contractFile, source, pluginName, nameOverride) => {
+    const name = nameOverride ?? readContractField(contractFile, "name") ?? path.basename(contractFile, JAY_CONTRACT_EXTENSION);
+    const description = readContractField(contractFile, "description");
+    const templates = listTemplatesForContractFile(contractFile).map((t) => ({
+      ...t,
+      path: rel(t.path)
+    }));
+    return {
+      name,
+      contractPath: rel(contractFile),
+      ...description && { description },
+      source,
+      ...pluginName && { plugin: pluginName },
+      templates
+    };
+  };
+  const components = [];
+  for (const contractFile of findContractFilesSync(componentsBase)) {
+    components.push(makeEntry(contractFile, "local", void 0));
+  }
+  for (const [, plugin] of plugins) {
+    const contracts = plugin.manifest.contracts;
+    if (!Array.isArray(contracts)) continue;
+    for (const contract of contracts) {
+      const spec = contract.contract;
+      if (!spec) continue;
+      const contractFile = resolvePluginContractPath(plugin, spec);
+      components.push(makeEntry(contractFile, "plugin", plugin.name, contract.name));
+    }
+  }
+  return { components };
+}
+function toKebabCase$1(str) {
+  return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase().replace(/[\s_]+/g, "-").replace(/^-/, "");
+}
+function renderAddMenu(index) {
+  const lines = [];
+  lines.push("# Design-system elements you can add");
+  lines.push("");
+  lines.push(
+    "Generated by `jay-stack agent-kit`. Each component ships a contract and one or more"
+  );
+  lines.push(
+    "`.jay-html` templates you can flatten into a page as a `<jay:X>` region. Pick a variant,"
+  );
+  lines.push("paste its import + region, then run `jay-stack sync` to flatten the markup. See");
+  lines.push("`designer/design-system-guide.md`.");
+  lines.push("");
+  if (index.components.length === 0) {
+    lines.push("_No design-system components found._");
+    lines.push("");
+    return lines.join("\n");
+  }
+  for (const component of index.components) {
+    lines.push(
+      component.description ? `## ${component.name} — ${component.description}` : `## ${component.name}`
+    );
+    lines.push("");
+    if (component.templates.length === 0) {
+      lines.push(
+        "_No template yet (COMPONENT-NO-TEMPLATE) — this component can't be flattened until it ships a `.jay-html`._"
+      );
+      lines.push("");
+      continue;
+    }
+    lines.push("| Variant | Title | Template |");
+    lines.push("| --- | --- | --- |");
+    for (const template of component.templates) {
+      const variant = template.variant === "" ? "(default)" : template.variant;
+      lines.push(`| ${variant} | ${template.title ?? ""} | ${template.path} |`);
+    }
+    lines.push("");
+    const first = component.templates[0];
+    const regionTag = toKebabCase$1(component.name);
+    const contractAttr = component.source === "plugin" ? component.name : component.contractPath;
+    lines.push("```html");
+    lines.push("<script");
+    lines.push('  type="application/jay-headless"');
+    if (component.source === "plugin" && component.plugin) {
+      lines.push(`  plugin="${component.plugin}"`);
+    }
+    lines.push(`  contract="${contractAttr}"`);
+    lines.push(`  template="${first.path}"`);
+    lines.push("><\/script>");
+    lines.push("");
+    lines.push(
+      `<jay:${regionTag} ref="${regionTag}"><!-- flattened copy; edit freely --></jay:${regionTag}>`
+    );
+    lines.push("```");
+    lines.push("");
+    lines.push("Then run `jay-stack sync` to flatten it.");
+    lines.push("");
+  }
+  return lines.join("\n");
+}
 const require$1 = createRequire(import.meta.url);
 async function executeDynamicGenerator(plugin, config, projectRoot, services, verbose, viteServer) {
   const { pluginPath, name: pluginName, isLocal, packageName } = plugin;
@@ -1463,6 +1635,15 @@ function resolveActionFilePath(actionPath, packageName, pluginPath, isLocal, pro
 function toKebabCase(str) {
   return str.replace(/([A-Z])/g, "-$1").toLowerCase().replace(/^-/, "");
 }
+function readComponentsBase(projectRoot) {
+  try {
+    const parsed = YAML.parse(fs.readFileSync(path.join(projectRoot, ".jay"), "utf-8"));
+    const base = parsed?.devServer?.componentsBase;
+    if (typeof base === "string" && base.length > 0) return base;
+  } catch {
+  }
+  return "./src/components";
+}
 async function materializeContracts(options, services = /* @__PURE__ */ new Map()) {
   const {
     projectRoot,
@@ -1682,13 +1863,26 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
       ...data.commands?.length && { commands: data.commands }
     }))
   };
+  const designSystem = buildDesignSystemIndex({
+    projectRoot,
+    componentsBase: readComponentsBase(projectRoot),
+    plugins,
+    resolvePluginContractPath: (plugin, spec) => resolveStaticContractPath(plugin, spec, projectRoot)
+  });
+  pluginsIndex.designSystemIndex = "./design-system-index.yaml";
   fs.mkdirSync(outputDir, { recursive: true });
   const agentKitDir = path.dirname(outputDir);
   const pluginsIndexPath = path.join(agentKitDir, "plugins-index.yaml");
   fs.writeFileSync(pluginsIndexPath, YAML.stringify(pluginsIndex), "utf-8");
+  const designSystemIndexPath = path.join(agentKitDir, "design-system-index.yaml");
+  fs.writeFileSync(designSystemIndexPath, YAML.stringify(designSystem), "utf-8");
+  const addMenuPath = path.join(agentKitDir, "design-system.md");
+  fs.writeFileSync(addMenuPath, renderAddMenu(designSystem), "utf-8");
   if (verbose) {
     getLogger().info(`
 ✅ Plugins index written to: ${pluginsIndexPath}`);
+    getLogger().info(`✅ Design-system index written to: ${designSystemIndexPath}`);
+    getLogger().info(`✅ Design-system add-menu written to: ${addMenuPath}`);
   }
   return {
     pluginsIndex,
@@ -2308,6 +2502,7 @@ export {
   SetupNeedsAnswerError,
   SlowRenderCache,
   buildAutomationWrap,
+  buildDesignSystemIndex,
   buildPageReloadHmrScript,
   buildScriptFragments,
   clearServerElementCache,
@@ -2325,14 +2520,17 @@ export {
   generateFrozenPageHtml,
   generatePromiseReconstruction,
   generateSSRPageHtml,
+  hasTemplateForContractFile,
   headMetaToHeadTags,
   invalidateServerElementCache,
   listContracts,
+  listTemplatesForContractFile,
   loadActionMetadata,
   loadPageParts,
   materializeContracts,
   parseActionMetadata,
   parseInputFromFlags,
+  renderAddMenu,
   resolveActionMetadataPath,
   resolveClientImportPath,
   resolveViewStatePromises

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/stack-server-build",
-  "version": "0.24.5",
+  "version": "0.24.7",
   "license": "Apache-2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.mts",
@@ -24,21 +24,22 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-html": "^0.24.5",
-    "@jay-framework/compiler-shared": "^0.24.5",
-    "@jay-framework/component": "^0.24.5",
-    "@jay-framework/fullstack-component": "^0.24.5",
-    "@jay-framework/logger": "^0.24.5",
-    "@jay-framework/runtime": "^0.24.5",
-    "@jay-framework/ssr-runtime": "^0.24.5",
-    "@jay-framework/stack-route-scanner": "^0.24.5",
-    "@jay-framework/stack-server-runtime": "^0.24.5",
-    "@jay-framework/view-state-merge": "^0.24.5",
+    "@jay-framework/compiler-jay-html": "^0.24.7",
+    "@jay-framework/compiler-shared": "^0.24.7",
+    "@jay-framework/component": "^0.24.7",
+    "@jay-framework/fullstack-component": "^0.24.7",
+    "@jay-framework/logger": "^0.24.7",
+    "@jay-framework/runtime": "^0.24.7",
+    "@jay-framework/ssr-runtime": "^0.24.7",
+    "@jay-framework/stack-route-scanner": "^0.24.7",
+    "@jay-framework/stack-server-runtime": "^0.24.7",
+    "@jay-framework/view-state-merge": "^0.24.7",
+    "node-html-parser": "^6.1.12",
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.24.5",
-    "@jay-framework/rollup-plugin": "^0.24.5",
+    "@jay-framework/dev-environment": "^0.24.7",
+    "@jay-framework/rollup-plugin": "^0.24.7",
     "@types/node": "^22.15.21",
     "rimraf": "^5.0.5",
     "tsup": "^8.0.1",