@jay-framework/jay-stack-cli 0.21.0 → 0.22.0

package/dist/index.js

@@ -18,7 +18,6 @@ import path$1 from "node:path";
 import fs$1 from "node:fs/promises";
 import { createRequire } from "module";
 import { glob } from "glob";
-import { parse } from "node-html-parser";
 import fsSync from "node:fs";
 import { fileURLToPath } from "node:url";
 const DEFAULT_CONFIG = {
@@ -3022,6 +3021,769 @@ function checkParamsConsistency(paramsTypeNames, localInterfaces, contractImport
     }
   }
 }
+const REJECTED_ITEM_FIELDS = ["kind", "parameters", "component", "allowedScopes"];
+const HTML_SOFT_LIMIT_BYTES = 8 * 1024;
+const HTML_HARD_LIMIT_BYTES = 32 * 1024;
+const FOLDER_PATH_MAX_SEGMENTS = 32;
+const BLOCKED_TAGS = /<\s*(script|iframe|object|embed)\b[^>]*>[\s\S]*?<\/\s*\1\s*>|<\s*(script|iframe|object|embed)\b[^>]*\/?>/gi;
+const EVENT_HANDLER_ATTR = /\s+on[a-z]+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi;
+const JAVASCRIPT_URL = /\b(href|src|xlink:href)\s*=\s*("|')\s*javascript:/gi;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function byteLengthUtf8(value) {
+  return new TextEncoder().encode(value).length;
+}
+function detectUnsafeAddMenuHtmlFragment(html) {
+  if (BLOCKED_TAGS.test(html)) {
+    BLOCKED_TAGS.lastIndex = 0;
+    return {
+      code: "html-fragment-unsafe-markup",
+      message: "html-fragment must not include script, iframe, object, or embed"
+    };
+  }
+  BLOCKED_TAGS.lastIndex = 0;
+  if (EVENT_HANDLER_ATTR.test(html)) {
+    EVENT_HANDLER_ATTR.lastIndex = 0;
+    return {
+      code: "html-fragment-unsafe-markup",
+      message: "html-fragment must not include inline event handler attributes"
+    };
+  }
+  EVENT_HANDLER_ATTR.lastIndex = 0;
+  if (JAVASCRIPT_URL.test(html)) {
+    JAVASCRIPT_URL.lastIndex = 0;
+    return {
+      code: "html-fragment-unsafe-markup",
+      message: "html-fragment must not include javascript: URLs"
+    };
+  }
+  JAVASCRIPT_URL.lastIndex = 0;
+  return null;
+}
+function sanitizeAddMenuHtmlFragment(html) {
+  let result = html;
+  result = result.replace(BLOCKED_TAGS, "");
+  BLOCKED_TAGS.lastIndex = 0;
+  result = result.replace(EVENT_HANDLER_ATTR, "");
+  EVENT_HANDLER_ATTR.lastIndex = 0;
+  result = result.replace(JAVASCRIPT_URL, "");
+  JAVASCRIPT_URL.lastIndex = 0;
+  return result.trim();
+}
+function catalogWarning(code, message, itemId, sourcePath) {
+  return { code, message, ...itemId ? { itemId } : {}, ...sourcePath ? { sourcePath } : {} };
+}
+function requiredString(obj, field, itemPath, errors, code) {
+  const value = obj[field];
+  if (typeof value !== "string" || value.trim().length === 0) {
+    errors.push({
+      path: `${itemPath}.${field}`,
+      message: "required non-empty string",
+      ...code ? { code } : {}
+    });
+    return null;
+  }
+  return value.trim();
+}
+function optionalString(obj, field) {
+  const value = obj[field];
+  if (value === void 0)
+    return void 0;
+  if (typeof value !== "string")
+    return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function validateInteraction(raw, itemPath, errors) {
+  if (raw === void 0)
+    return void 0;
+  if (!isRecord(raw)) {
+    errors.push({
+      path: itemPath,
+      message: "interaction must be an object",
+      code: "interaction-not-object"
+    });
+    return void 0;
+  }
+  const mode = raw.mode;
+  if (mode !== "reference" && mode !== "stage-place") {
+    errors.push({
+      path: `${itemPath}.mode`,
+      message: 'interaction.mode must be "reference" or "stage-place"',
+      code: "interaction-invalid-mode"
+    });
+    return void 0;
+  }
+  return {
+    mode,
+    stagePromptTemplate: optionalString(raw, "stagePromptTemplate")
+  };
+}
+function validatePresentation(raw, itemPath, errors) {
+  if (raw === void 0)
+    return void 0;
+  if (!isRecord(raw)) {
+    errors.push({
+      path: itemPath,
+      message: "presentation must be an object",
+      code: "presentation-not-object"
+    });
+    return void 0;
+  }
+  const type = raw.type;
+  if (type !== "image" && type !== "gif" && type !== "html-fragment") {
+    errors.push({
+      path: `${itemPath}.type`,
+      message: 'presentation.type must be "image", "gif", or "html-fragment"',
+      code: "presentation-unknown-type"
+    });
+    return void 0;
+  }
+  if (type === "image") {
+    const src = requiredString(raw, "src", itemPath, errors, "presentation-missing-src");
+    if (!src)
+      return void 0;
+    return { type: "image", src };
+  }
+  if (type === "gif") {
+    const src = requiredString(raw, "src", itemPath, errors, "presentation-missing-src");
+    if (!src)
+      return void 0;
+    return {
+      type: "gif",
+      src,
+      poster: optionalString(raw, "poster")
+    };
+  }
+  if ("src" in raw) {
+    errors.push({
+      path: `${itemPath}.src`,
+      message: "html-fragment must use presentation.html, not presentation.src",
+      code: "html-fragment-src-not-allowed"
+    });
+  }
+  const htmlValue = raw.html;
+  if (typeof htmlValue !== "string" || htmlValue.trim().length === 0) {
+    errors.push({
+      path: `${itemPath}.html`,
+      message: "html-fragment requires non-empty presentation.html",
+      code: "html-fragment-missing-html"
+    });
+    return void 0;
+  }
+  const unsafe = detectUnsafeAddMenuHtmlFragment(htmlValue);
+  if (unsafe) {
+    errors.push({
+      path: `${itemPath}.html`,
+      message: unsafe.message,
+      code: unsafe.code
+    });
+    return void 0;
+  }
+  const sanitized = sanitizeAddMenuHtmlFragment(htmlValue);
+  if (byteLengthUtf8(sanitized) > HTML_HARD_LIMIT_BYTES) {
+    errors.push({
+      path: `${itemPath}.html`,
+      message: `html-fragment exceeds ${HTML_HARD_LIMIT_BYTES} bytes after sanitize`,
+      code: "html-fragment-oversize-hard"
+    });
+    return void 0;
+  }
+  return { type: "html-fragment", html: htmlValue };
+}
+const BROWSE_SIZES = /* @__PURE__ */ new Set(["large", "medium", "small"]);
+function validateBrowse(raw, itemPath, errors) {
+  if (raw === void 0)
+    return void 0;
+  if (!isRecord(raw)) {
+    errors.push({
+      path: itemPath,
+      message: "browse must be an object",
+      code: "browse-not-object"
+    });
+    return void 0;
+  }
+  const sizeRaw = raw.size;
+  if (sizeRaw === void 0) {
+    return {};
+  }
+  if (typeof sizeRaw !== "string" || !BROWSE_SIZES.has(sizeRaw)) {
+    errors.push({
+      path: `${itemPath}.size`,
+      message: 'browse.size must be "large", "medium", or "small"',
+      code: "browse-unknown-size"
+    });
+    return void 0;
+  }
+  return { size: sizeRaw };
+}
+function validateFolderPath(raw, itemPath, errors) {
+  if (raw === void 0)
+    return void 0;
+  if (!Array.isArray(raw)) {
+    errors.push({
+      path: `${itemPath}.folderPath`,
+      message: "folderPath must be an array of strings",
+      code: "folder-path-not-array"
+    });
+    return void 0;
+  }
+  const segments = [];
+  for (let index = 0; index < raw.length; index++) {
+    const value = raw[index];
+    if (typeof value !== "string") {
+      errors.push({
+        path: `${itemPath}.folderPath[${index}]`,
+        message: "folderPath segments must be strings",
+        code: "folder-path-segment-type"
+      });
+      return void 0;
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+      errors.push({
+        path: `${itemPath}.folderPath[${index}]`,
+        message: "folderPath segments must be non-empty",
+        code: "folder-path-empty-segment"
+      });
+      return void 0;
+    }
+    if (trimmed === ".." || trimmed.includes("/") || trimmed.includes("\\")) {
+      errors.push({
+        path: `${itemPath}.folderPath[${index}]`,
+        message: 'folderPath segments must not contain ".." or path separators',
+        code: "folder-path-invalid-segment"
+      });
+      return void 0;
+    }
+    if (segments.at(-1) === trimmed) {
+      errors.push({
+        path: `${itemPath}.folderPath[${index}]`,
+        message: "folderPath must not contain duplicate adjacent segments",
+        code: "folder-path-adjacent-duplicate"
+      });
+      return void 0;
+    }
+    segments.push(trimmed);
+  }
+  if (segments.length > FOLDER_PATH_MAX_SEGMENTS) {
+    errors.push({
+      path: `${itemPath}.folderPath`,
+      message: `folderPath exceeds ${FOLDER_PATH_MAX_SEGMENTS} segments`,
+      code: "folder-path-too-deep"
+    });
+    return void 0;
+  }
+  return segments.length > 0 ? segments : void 0;
+}
+function validateAddMenuItem(raw, itemPath) {
+  const errors = [];
+  if (!isRecord(raw)) {
+    return {
+      item: null,
+      errors: [
+        { path: itemPath, message: "item must be an object", code: "item-not-object" }
+      ]
+    };
+  }
+  for (const field of REJECTED_ITEM_FIELDS) {
+    if (field in raw) {
+      errors.push({
+        path: `${itemPath}.${field}`,
+        message: `field "${field}" is not allowed in Add Menu catalog items`,
+        code: `rejected-field-${field}`
+      });
+    }
+  }
+  const id = requiredString(raw, "id", itemPath, errors, "missing-id");
+  const title = requiredString(raw, "title", itemPath, errors, "missing-title");
+  const category = requiredString(raw, "category", itemPath, errors, "missing-category");
+  const prompt = requiredString(raw, "prompt", itemPath, errors, "missing-prompt");
+  if (errors.length > 0 || !id || !title || !category || !prompt) {
+    return { item: null, errors };
+  }
+  const interaction = validateInteraction(raw.interaction, `${itemPath}.interaction`, errors);
+  const presentation = validatePresentation(raw.presentation, `${itemPath}.presentation`, errors);
+  const browse = validateBrowse(raw.browse, `${itemPath}.browse`, errors);
+  const folderPath = validateFolderPath(raw.folderPath, itemPath, errors);
+  if (errors.length > 0) {
+    return { item: null, errors };
+  }
+  return {
+    item: {
+      id,
+      title,
+      category,
+      prompt,
+      pluginName: optionalString(raw, "pluginName"),
+      packageName: optionalString(raw, "packageName"),
+      subCategory: optionalString(raw, "subCategory"),
+      ...folderPath ? { folderPath } : {},
+      thumbnail: optionalString(raw, "thumbnail"),
+      ...presentation ? { presentation } : {},
+      ...browse ? { browse } : {},
+      ...interaction ? { interaction } : {}
+    },
+    errors
+  };
+}
+function validateAddMenuCatalogFile(raw, sourcePath) {
+  const errors = [];
+  if (!isRecord(raw)) {
+    return {
+      file: null,
+      errors: [
+        {
+          path: sourcePath,
+          message: "catalog file must be an object",
+          code: "catalog-not-object"
+        }
+      ]
+    };
+  }
+  if (!Array.isArray(raw.items)) {
+    return {
+      file: null,
+      errors: [
+        {
+          path: `${sourcePath}.items`,
+          message: "items must be an array",
+          code: "catalog-items-not-array"
+        }
+      ]
+    };
+  }
+  const items = [];
+  raw.items.forEach((entry, index) => {
+    const result = validateAddMenuItem(entry, `${sourcePath}.items[${index}]`);
+    errors.push(...result.errors);
+    if (result.item)
+      items.push(result.item);
+  });
+  if (items.length === 0 && errors.length > 0) {
+    return { file: null, errors };
+  }
+  return { file: { items }, errors };
+}
+function normalizeAddMenuPresentation(item) {
+  if (item.presentation)
+    return item.presentation;
+  const thumbnail = item.thumbnail?.trim();
+  if (!thumbnail)
+    return void 0;
+  if (/\.gif$/i.test(thumbnail)) {
+    return { type: "gif", src: thumbnail };
+  }
+  return { type: "image", src: thumbnail };
+}
+function normalizeAddMenuBrowseSize(item) {
+  return item.browse?.size ?? "medium";
+}
+function hasSingleRootDiv(html) {
+  const trimmed = html.trim();
+  if (!trimmed.startsWith("<div"))
+    return false;
+  const openMatch = trimmed.match(/^<div\b[^>]*>/i);
+  if (!openMatch)
+    return false;
+  const afterOpen = trimmed.slice(openMatch[0].length);
+  const closeIdx = afterOpen.lastIndexOf("</div>");
+  if (closeIdx < 0)
+    return false;
+  const tail = afterOpen.slice(closeIdx + "</div>".length).trim();
+  return tail.length === 0;
+}
+function hasAtScopeStyle(html) {
+  return /<style\b[^>]*>[\s\S]*@scope\b/i.test(html);
+}
+function lintHtmlFragment(item, sourcePath) {
+  const errors = [];
+  const warnings = [];
+  const presentation = item.presentation;
+  if (!presentation || presentation.type !== "html-fragment") {
+    return { errors, warnings };
+  }
+  const rawHtml = presentation.html?.trim() ?? "";
+  if (!rawHtml) {
+    errors.push(
+      catalogWarning(
+        "html-fragment-missing-html",
+        "html-fragment requires non-empty presentation.html",
+        item.id,
+        sourcePath
+      )
+    );
+    return { errors, warnings };
+  }
+  const unsafe = detectUnsafeAddMenuHtmlFragment(rawHtml);
+  if (unsafe) {
+    errors.push(catalogWarning(unsafe.code, unsafe.message, item.id, sourcePath));
+    return { errors, warnings };
+  }
+  const sanitized = sanitizeAddMenuHtmlFragment(rawHtml);
+  const bytes = byteLengthUtf8(sanitized);
+  if (bytes > HTML_HARD_LIMIT_BYTES) {
+    errors.push(
+      catalogWarning(
+        "html-fragment-oversize-hard",
+        `html-fragment exceeds ${HTML_HARD_LIMIT_BYTES} bytes after sanitize (${bytes})`,
+        item.id,
+        sourcePath
+      )
+    );
+  } else if (bytes > HTML_SOFT_LIMIT_BYTES) {
+    warnings.push(
+      catalogWarning(
+        "html-fragment-oversize-soft",
+        `html-fragment exceeds ${HTML_SOFT_LIMIT_BYTES} bytes after sanitize (${bytes}) — consider trimming`,
+        item.id,
+        sourcePath
+      )
+    );
+  }
+  if (!hasSingleRootDiv(sanitized)) {
+    warnings.push(
+      catalogWarning(
+        "html-fragment-missing-root-div",
+        "html-fragment should use a single root <div>",
+        item.id,
+        sourcePath
+      )
+    );
+  }
+  if (!hasAtScopeStyle(sanitized)) {
+    warnings.push(
+      catalogWarning(
+        "html-fragment-missing-at-scope",
+        "html-fragment should include <style> with @scope for preview isolation",
+        item.id,
+        sourcePath
+      )
+    );
+  }
+  return { errors, warnings };
+}
+function lintGifPoster(item, sourcePath) {
+  const presentation = normalizeAddMenuPresentation(item);
+  if (presentation?.type !== "gif" || presentation.poster?.trim())
+    return [];
+  return [
+    catalogWarning(
+      "gif-missing-poster",
+      `gif item "${item.id}" has no poster — add poster for prefers-reduced-motion accessibility`,
+      item.id,
+      sourcePath
+    )
+  ];
+}
+function lintBrowseLargeWithoutPresentation(item, sourcePath) {
+  if (normalizeAddMenuBrowseSize(item) !== "large")
+    return [];
+  if (normalizeAddMenuPresentation(item))
+    return [];
+  return [
+    catalogWarning(
+      "browse-large-without-presentation",
+      `large browse item "${item.id}" has no presentation or thumbnail — add a preview`,
+      item.id,
+      sourcePath
+    )
+  ];
+}
+function lintAddMenuCatalog(items, sourcePath) {
+  const errors = [];
+  const warnings = [];
+  for (const item of items) {
+    warnings.push(...lintGifPoster(item, sourcePath));
+    warnings.push(...lintBrowseLargeWithoutPresentation(item, sourcePath));
+    const htmlLint = lintHtmlFragment(item, sourcePath);
+    errors.push(...htmlLint.errors);
+    warnings.push(...htmlLint.warnings);
+  }
+  return { errors, warnings };
+}
+const ADD_MENU_VALIDATION_SUGGESTIONS = {
+  "gif-missing-poster": "Add presentation.poster with a static image for prefers-reduced-motion accessibility",
+  "html-fragment-missing-root-div": 'Wrap preview markup in a single root <div class="am-preview"> — see agent-kit/plugin/aiditor-add-menu.md',
+  "html-fragment-missing-at-scope": "Add <style> with @scope (.am-preview) inside the root div — see agent-kit/plugin/aiditor-add-menu.md",
+  "html-fragment-missing-html": "Set presentation.html with inline markup — external preview files are not supported",
+  "html-fragment-src-not-allowed": "Remove presentation.src; use presentation.html for html-fragment previews",
+  "html-fragment-unsafe-markup": "Remove scripts, event handlers, and javascript: URLs from presentation.html",
+  "html-fragment-oversize-soft": "Trim inline html or use a gif preview for rich motion",
+  "html-fragment-oversize-hard": "Reduce presentation.html below 32 KB after sanitize",
+  "browse-large-without-presentation": "Add presentation or thumbnail — large browse tiles need a visual preview",
+  "browse-unknown-size": "Set browse.size to large, medium, or small",
+  "presentation-unknown-type": "Set presentation.type to image, gif, or html-fragment",
+  "interaction-invalid-mode": "Set interaction.mode to reference (default) or stage-place",
+  "folder-path-not-array": "folderPath must be a yaml array of folder name strings",
+  "folder-path-segment-type": "Each folderPath entry must be a non-empty string",
+  "folder-path-empty-segment": "Remove empty folderPath segments",
+  "folder-path-invalid-segment": 'Use separate array elements per folder level — no "/" or "\\" in segment names',
+  "folder-path-adjacent-duplicate": "Remove duplicate consecutive folderPath segments",
+  "folder-path-too-deep": `Shorten folderPath to at most ${FOLDER_PATH_MAX_SEGMENTS} segments`,
+  "rejected-field-kind": "Remove kind — express item intent in prompt text",
+  "rejected-field-parameters": "Remove parameters — materialize values into prompt",
+  "rejected-field-component": "Remove component — use prompt plus contract paths in agent-kit",
+  "rejected-field-allowedScopes": "Remove allowedScopes — attachment scope is chosen in the AIditor UI",
+  "add-menu-missing-agentkit-handler": "Declare agentkit in plugin.yaml pointing at an agent-kit handler export; run jay-stack agent-kit (project yarn agent-kit) to materialize catalogs — not jay-stack setup",
+  "add-menu-legacy-setup-handler": "Move add-menu catalog writes from the setup handler to agentkit. Setup is for config/credentials only; run jay-stack agent-kit to generate agent-kit/aiditor/add-menu/*.yaml",
+  "deprecated-nested-setup-keys": "Replace nested setup.handler / setup.references with flat keys: setup: <handler> and agentkit: <handler>"
+};
+const ADD_MENU_CATALOG_REL_PATHS = [
+  "agent-kit/aiditor/add-menu.template.yaml",
+  "agent-kit/aiditor/add-menu.yaml"
+];
+const CONTRIBUTOR_GUIDE = "agent-kit/plugin/aiditor-add-menu.md";
+const ADD_MENU_WRITE_MARKERS = [
+  "agent-kit/aiditor/add-menu",
+  "aiditor-add-menu-thumbnails",
+  "writeAddMenuCatalog",
+  "copyAiditorAddMenuThumbnails"
+];
+function isRelativeHandlerRef(value) {
+  return value.startsWith("./") || value.startsWith("../");
+}
+function resolveModulePath$1(basePath) {
+  for (const ext of ["", ".ts", ".js", "/index.ts", "/index.js"]) {
+    const candidate = basePath + ext;
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+function collectTypeScriptFiles(dir, depth = 0) {
+  if (depth > 4)
+    return [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory() && entry.name !== "node_modules" && entry.name !== "test") {
+      files.push(...collectTypeScriptFiles(fullPath, depth + 1));
+    } else if (entry.isFile() && (entry.name.endsWith(".ts") || entry.name.endsWith(".js"))) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+function resolveHandlerSourceFile(pluginPath, handlerRef, isNpmPackage) {
+  if (isRelativeHandlerRef(handlerRef)) {
+    return resolveModulePath$1(path.join(pluginPath, handlerRef)) ?? null;
+  }
+  const searchRoots = isNpmPackage ? [path.join(pluginPath, "lib"), path.join(pluginPath, "dist")] : [pluginPath];
+  for (const root of searchRoots) {
+    if (!fs.existsSync(root))
+      continue;
+    for (const file of collectTypeScriptFiles(root)) {
+      const content = fs.readFileSync(file, "utf-8");
+      const definesHandler = new RegExp(
+        `export\\s+(?:async\\s+)?function\\s+${handlerRef}\\b`
+      ).test(content);
+      const definesDefaultNamed = new RegExp(
+        `export\\s+default\\s+async\\s+function\\s+${handlerRef}\\b`
+      ).test(content);
+      if (definesHandler || definesDefaultNamed) {
+        return file;
+      }
+      const reExportMatch = content.match(
+        new RegExp(
+          `export\\s*\\{[^}]*\\b${handlerRef}\\b[^}]*\\}\\s*from\\s*['"]([^'"]+)['"]`
+        )
+      );
+      if (reExportMatch) {
+        const importSpec = reExportMatch[1].replace(/\.js$/, "");
+        const resolved = resolveModulePath$1(path.resolve(path.dirname(file), importSpec));
+        if (resolved)
+          return resolved;
+      }
+    }
+  }
+  return null;
+}
+function extractBalancedBlock(source, openBraceIndex) {
+  let depth = 0;
+  for (let index = openBraceIndex; index < source.length; index++) {
+    const char = source[index];
+    if (char === "{")
+      depth++;
+    else if (char === "}") {
+      depth--;
+      if (depth === 0) {
+        return source.slice(openBraceIndex, index + 1);
+      }
+    }
+  }
+  return null;
+}
+function findFunctionBodyOpenBrace(source, searchFrom) {
+  const arrowMatch = /=>\s*\{/.exec(source.slice(searchFrom));
+  const parenMatch = /\)\s*(?::[^{]+)?\{/.exec(source.slice(searchFrom));
+  const candidates = [];
+  if (arrowMatch?.index !== void 0) {
+    candidates.push(searchFrom + arrowMatch.index + arrowMatch[0].length - 1);
+  }
+  if (parenMatch?.index !== void 0) {
+    candidates.push(searchFrom + parenMatch.index + parenMatch[0].length - 1);
+  }
+  if (candidates.length === 0)
+    return -1;
+  return Math.min(...candidates);
+}
+function extractFunctionBody(source, functionName) {
+  const patterns = [
+    new RegExp(`export\\s+async\\s+function\\s+${functionName}\\b`),
+    new RegExp(`export\\s+function\\s+${functionName}\\b`),
+    new RegExp(`export\\s+default\\s+async\\s+function\\s+${functionName}\\b`),
+    new RegExp(
+      `export\\s+const\\s+${functionName}\\s*=\\s*async\\s*\\([^)]*\\)\\s*(?::[^{]+)?=>\\s*\\{`
+    ),
+    new RegExp(
+      `export\\s+const\\s+${functionName}\\s*=\\s*\\([^)]*\\)\\s*(?::[^{]+)?=>\\s*\\{`
+    )
+  ];
+  for (const pattern of patterns) {
+    const match = pattern.exec(source);
+    if (!match)
+      continue;
+    const braceIndex = findFunctionBodyOpenBrace(source, match.index);
+    if (braceIndex === -1)
+      continue;
+    return extractBalancedBlock(source, braceIndex);
+  }
+  return null;
+}
+function extractDefaultExportFunctionBody(source) {
+  const patterns = [
+    /export\s+default\s+async\s+function\s+\w+\b/,
+    /export\s+default\s+async\s+function\s*\(/,
+    /export\s+default\s+async\s*\([^)]*\)\s*(?::[^{]+)?=>\s*\{/
+  ];
+  for (const pattern of patterns) {
+    const match = pattern.exec(source);
+    if (!match)
+      continue;
+    const braceIndex = findFunctionBodyOpenBrace(source, match.index);
+    if (braceIndex === -1)
+      continue;
+    return extractBalancedBlock(source, braceIndex);
+  }
+  return null;
+}
+function handlerBodyWritesAddMenuCatalog(body) {
+  return ADD_MENU_WRITE_MARKERS.some((marker) => body.includes(marker));
+}
+function resolveSetupHandlerFunctionBody(pluginPath, handlerRef, isNpmPackage) {
+  const sourceFile = resolveHandlerSourceFile(pluginPath, handlerRef, isNpmPackage);
+  if (!sourceFile)
+    return null;
+  const source = fs.readFileSync(sourceFile, "utf-8");
+  if (isRelativeHandlerRef(handlerRef)) {
+    return extractDefaultExportFunctionBody(source) ?? extractFunctionBody(source, "setup") ?? extractFunctionBody(source, handlerRef);
+  }
+  return extractFunctionBody(source, handlerRef);
+}
+function suggestionForCode(code) {
+  if (!code)
+    return `See ${CONTRIBUTOR_GUIDE} for schema and validation rules`;
+  return ADD_MENU_VALIDATION_SUGGESTIONS[code] ?? `See ${CONTRIBUTOR_GUIDE} for schema and validation rules`;
+}
+function mapSchemaError(error, catalogPath) {
+  const code = error.code ?? "catalog-validation-error";
+  return {
+    type: "add-menu-catalog",
+    code,
+    message: `[${code}] ${error.message}`,
+    location: error.path || catalogPath,
+    suggestion: suggestionForCode(code)
+  };
+}
+function mapLintFinding(finding, catalogPath, severity) {
+  return {
+    type: "add-menu-catalog",
+    code: finding.code,
+    message: `[${finding.code}] ${finding.message}`,
+    location: finding.sourcePath ?? catalogPath,
+    itemId: finding.itemId,
+    suggestion: suggestionForCode(finding.code),
+    ...severity === "warning" ? {} : {}
+  };
+}
+function pluginShipsAddMenuCatalog(context) {
+  return ADD_MENU_CATALOG_REL_PATHS.some(
+    (relPath) => fs.existsSync(path.join(context.pluginPath, relPath))
+  );
+}
+function validateAddMenuAgentKitHandler(context, result) {
+  if (!pluginShipsAddMenuCatalog(context))
+    return;
+  const agentKitHandler = context.manifest.agentkit;
+  if (!agentKitHandler) {
+    result.warnings.push({
+      type: "add-menu-catalog",
+      code: "add-menu-missing-agentkit-handler",
+      message: "[add-menu-missing-agentkit-handler] Plugin ships add-menu catalog yaml but plugin.yaml has no agentkit handler — catalogs must be generated during jay-stack agent-kit (yarn agent-kit), not jay-stack setup",
+      location: "plugin.yaml",
+      suggestion: suggestionForCode("add-menu-missing-agentkit-handler")
+    });
+  }
+  const setupHandler = typeof context.manifest.setup === "string" ? context.manifest.setup : void 0;
+  if (!setupHandler)
+    return;
+  const setupBody = resolveSetupHandlerFunctionBody(
+    context.pluginPath,
+    setupHandler,
+    context.isNpmPackage
+  );
+  if (!setupBody || !handlerBodyWritesAddMenuCatalog(setupBody))
+    return;
+  result.warnings.push({
+    type: "add-menu-catalog",
+    code: "add-menu-legacy-setup-handler",
+    message: "[add-menu-legacy-setup-handler] setup handler writes add-menu catalogs — move catalog materialization to agentkit and run jay-stack agent-kit (yarn agent-kit); keep setup for config and credentials only",
+    location: `plugin.yaml setup (${setupHandler})`,
+    suggestion: suggestionForCode("add-menu-legacy-setup-handler")
+  });
+}
+async function validateAddMenuCatalogFileAtPath(catalogPath, relPath, result) {
+  let parsed;
+  try {
+    const content = await fs.promises.readFile(catalogPath, "utf-8");
+    parsed = YAML.parse(content);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    result.errors.push({
+      type: "add-menu-catalog",
+      code: "catalog-yaml-parse-error",
+      message: `Invalid add-menu catalog YAML: ${message}`,
+      location: relPath,
+      suggestion: `Check YAML syntax in the add-menu catalog file. See ${CONTRIBUTOR_GUIDE}`
+    });
+    return;
+  }
+  const validated = validateAddMenuCatalogFile(parsed, relPath);
+  result.errors.push(...validated.errors.map((error) => mapSchemaError(error, relPath)));
+  if (!validated.file?.items.length) {
+    return;
+  }
+  const linted = lintAddMenuCatalog(validated.file.items, relPath);
+  result.errors.push(
+    ...linted.errors.map((finding) => mapLintFinding(finding, relPath, "error"))
+  );
+  result.warnings.push(
+    ...linted.warnings.map((finding) => mapLintFinding(finding, relPath, "warning"))
+  );
+}
+async function validateAddMenuCatalog(context, result) {
+  validateAddMenuAgentKitHandler(context, result);
+  for (const relPath of ADD_MENU_CATALOG_REL_PATHS) {
+    const catalogPath = path.join(context.pluginPath, relPath);
+    if (!fs.existsSync(catalogPath))
+      continue;
+    await validateAddMenuCatalogFileAtPath(catalogPath, relPath, result);
+  }
+}
 async function validatePlugin(options = {}) {
   const pluginPath = options.pluginPath || process.cwd();
   if (options.local) {
@@ -3088,6 +3850,7 @@ async function validatePluginPackage(pluginPath, options) {
   if (pluginManifest.dynamic_contracts) {
     await validateDynamicContracts(context, result);
   }
+  await validateAddMenuCatalog(context, result);
   result.valid = result.errors.length === 0;
   return result;
 }
@@ -3437,25 +4200,32 @@ async function validateSchema(context, result) {
     }
   }
   if (manifest.setup) {
-    if (manifest.setup.handler) {
+    if (typeof manifest.setup !== "string") {
+      result.errors.push({
+        type: "schema",
+        message: "Deprecated nested setup keys (setup.handler / setup.references) — use flat setup: and agentkit: in plugin.yaml",
+        location: "plugin.yaml setup",
+        suggestion: "Replace setup.handler with top-level setup: and setup.references with top-level agentkit:"
+      });
+    } else {
       validateHandlerRef(
-        manifest.setup.handler,
+        manifest.setup,
         "Setup handler",
-        "plugin.yaml setup.handler",
-        context,
-        result
-      );
-    }
-    if (manifest.setup.references) {
-      validateHandlerRef(
-        manifest.setup.references,
-        "References handler",
-        "plugin.yaml setup.references",
+        "plugin.yaml setup",
         context,
         result
       );
     }
   }
+  if (manifest.agentkit) {
+    validateHandlerRef(
+      manifest.agentkit,
+      "Agent-kit handler",
+      "plugin.yaml agentkit",
+      context,
+      result
+    );
+  }
 }
 function checkExportExists(exportName, context) {
   const packageJsonPath = path.join(context.pluginPath, "package.json");
@@ -3842,6 +4612,18 @@ async function validatePackageJson(context, result) {
         suggestion: 'Add "./plugin.yaml": "./plugin.yaml" to exports field'
       });
     }
+    const agentKitDir = path.join(context.pluginPath, "agent-kit");
+    if (fs.existsSync(agentKitDir) && fs.statSync(agentKitDir).isDirectory()) {
+      const filesArray = packageJson.files;
+      if (!filesArray || !filesArray.includes("agent-kit")) {
+        result.warnings.push({
+          type: "export-mismatch",
+          message: 'agent-kit directory exists but is not listed in package.json "files"',
+          location: packageJsonPath,
+          suggestion: 'Add "agent-kit" to the "files" array so agent-kit files are shipped with the package'
+        });
+      }
+    }
   } catch (error) {
     result.errors.push({
       type: "schema",
@@ -4233,38 +5015,18 @@ function extractRouteParams(filePath, pagesBase) {
   }
   return params;
 }
-function dedentYaml(text) {
-  const lines = text.split("\n").filter((l) => l.trim().length > 0);
-  if (lines.length === 0)
-    return "";
-  const minIndent = Math.min(...lines.map((l) => l.match(/^\s*/)?.[0].length ?? 0));
-  return lines.map((l) => l.slice(minIndent)).join("\n");
-}
-function extractJayParams(content) {
-  const root = parse(content, {
-    comment: true,
-    blockTextElements: { script: true, style: true }
-  });
-  const head = root.querySelector("head");
-  if (!head)
-    return /* @__PURE__ */ new Set();
-  const paramScripts = head.querySelectorAll('script[type="application/jay-params"]');
-  if (paramScripts.length !== 1)
-    return /* @__PURE__ */ new Set();
-  const body = dedentYaml(paramScripts[0].textContent ?? "");
-  if (!body)
-    return /* @__PURE__ */ new Set();
-  try {
-    const parsed = YAML.parse(body);
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      return new Set(Object.keys(parsed));
+function extractHeadlessPropsParamNames(parsedFile) {
+  const names = /* @__PURE__ */ new Set();
+  for (const imp of parsedFile.headlessImports) {
+    if (imp.headlessProps) {
+      for (const key of Object.keys(imp.headlessProps)) {
+        names.add(key);
+      }
     }
-    return /* @__PURE__ */ new Set();
-  } catch {
-    return /* @__PURE__ */ new Set();
   }
+  return names;
 }
-function checkRouteParams(parsedFile, filePath, pagesBase, jayHtmlContent) {
+function checkRouteParams(parsedFile, filePath, pagesBase) {
   const requiredParams = /* @__PURE__ */ new Set();
   function collectParams(params) {
     for (const p of params) {
@@ -4284,13 +5046,13 @@ function checkRouteParams(parsedFile, filePath, pagesBase, jayHtmlContent) {
   if (requiredParams.size === 0)
     return [];
   const routeParams = extractRouteParams(filePath, pagesBase);
-  const jayParams = extractJayParams(jayHtmlContent);
-  const availableParams = /* @__PURE__ */ new Set([...routeParams, ...jayParams]);
+  const headlessProps = extractHeadlessPropsParamNames(parsedFile);
+  const availableParams = /* @__PURE__ */ new Set([...routeParams, ...headlessProps]);
   const warnings = [];
   for (const param of requiredParams) {
     if (!availableParams.has(param)) {
       warnings.push(
-        `Contract requires param "${param}" but the route does not provide it. Add a dynamic segment [${param}] to the route path or declare it in <script type="application/jay-params">.`
+        `Contract requires param "${param}" but the route does not provide it. Add a dynamic segment [${param}] to the route path or provide it in the headless component's YAML body.`
       );
     }
   }
@@ -4514,6 +5276,7 @@ async function runPluginValidators(projectRoot, parsedFiles, errors, warnings) {
         const ctx = {
           filePath: relativePath,
           body: parsed.body,
+          css: parsed.css,
           head: parsed.headMeta,
           contract: resolvedPageContract ? {
             name: resolvedPageContract.name,
@@ -4660,7 +5423,13 @@ async function validateJayFiles(options = {}) {
         continue;
       }
       parsedFiles.push({ relativePath, parsed: parsedFile.val });
-      const routeParamWarnings = checkRouteParams(parsedFile.val, jayFile, scanDir, content);
+      if (content.includes("application/jay-params")) {
+        warnings.push({
+          file: relativePath,
+          message: '<script type="application/jay-params"> is deprecated. Move the values into the YAML body of the headless component that uses them. See agent-kit/developer/routing.md for details.'
+        });
+      }
+      const routeParamWarnings = checkRouteParams(parsedFile.val, jayFile, scanDir);
       for (const msg of routeParamWarnings) {
         warnings.push({ file: relativePath, message: msg });
       }
@@ -4784,11 +5553,25 @@ function printJayValidationResult(result, options) {
         logger.important(chalk.blue(`      Suggestion: ${error.suggestion}`));
       }
     }
+    const fileGroups = /* @__PURE__ */ new Map();
     for (const warning of warns) {
-      logger.important(chalk.yellow(`   ⚠ ${warning.file}`));
-      logger.important(chalk.gray(`      ${warning.message}`));
-      if (warning.suggestion) {
-        logger.important(chalk.blue(`      Suggestion: ${warning.suggestion}`));
+      const group = fileGroups.get(warning.file) || [];
+      group.push(warning);
+      fileGroups.set(warning.file, group);
+    }
+    for (const [file, groupWarns] of fileGroups) {
+      logger.important(chalk.yellow(`   ⚠ ${file}`));
+      for (const warning of groupWarns) {
+        if (warning.message) {
+          logger.important(chalk.gray(`      ${warning.message}`));
+        }
+      }
+      const suggestions = [...new Set(groupWarns.map((w) => w.suggestion).filter(Boolean))];
+      if (suggestions.length > 0) {
+        logger.important(chalk.blue(`      Suggestions:`));
+        for (const s2 of suggestions) {
+          logger.important(chalk.blue(`        ${s2}`));
+        }
       }
     }
   }
@@ -4909,7 +5692,7 @@ async function runAgentKit(options) {
       await ensureAgentKitDocs(projectRoot, options.force, options.mode);
       await mergePluginAgentKitGuides(projectRoot, options.mode);
       if (options.references !== false) {
-        await generatePluginReferences(projectRoot, options, initErrors, viteServer);
+        await generatePluginAgentKit(projectRoot, options, initErrors, viteServer);
       }
     }
   } finally {
@@ -5106,9 +5889,9 @@ async function mergePluginAgentKitGuides(projectRoot, mode) {
     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({
+async function generatePluginAgentKit(projectRoot, options, initErrors, viteServer) {
+  const { discoverPluginsWithAgentKit, executePluginAgentKit } = await import("@jay-framework/stack-server-runtime");
+  const plugins = await discoverPluginsWithAgentKit({
     projectRoot,
     verbose: options.verbose,
     pluginFilter: options.plugin
@@ -5117,35 +5900,35 @@ async function generatePluginReferences(projectRoot, options, initErrors, viteSe
     return;
   const logger = getLogger();
   logger.important("");
-  logger.important(chalk.bold("Generating plugin references..."));
+  logger.important(chalk.bold("Generating plugin agent-kit data..."));
   for (const plugin of plugins) {
     const pluginInitError = initErrors.get(plugin.name);
     if (pluginInitError) {
       logger.warn(
         chalk.yellow(
-          `   ${plugin.name}: references skipped — init failed: ${pluginInitError.message}`
+          `   ${plugin.name}: agent-kit skipped — init failed: ${pluginInitError.message}`
         )
       );
       continue;
     }
     try {
-      const result = await executePluginReferences(plugin, {
+      const result = await executePluginAgentKit(plugin, {
         projectRoot,
         force: options.force ?? false,
         viteServer,
         verbose: options.verbose
       });
-      if (result.referencesCreated.length > 0) {
+      if (result.agentKitCreated.length > 0) {
         logger.important(chalk.green(`   ${plugin.name}:`));
-        for (const ref of result.referencesCreated) {
-          logger.important(chalk.gray(`      ${ref}`));
+        for (const created of result.agentKitCreated) {
+          logger.important(chalk.gray(`      ${created}`));
         }
         if (result.message) {
           logger.important(chalk.gray(`      ${result.message}`));
         }
       }
     } catch (error) {
-      logger.warn(chalk.yellow(`   ${plugin.name}: references skipped — ${error.message}`));
+      logger.warn(chalk.yellow(`   ${plugin.name}: agent-kit skipped — ${error.message}`));
     }
   }
 }