@jay-framework/plugin-validator 0.20.0 → 0.22.0

package/dist/index.d.ts

@@ -18,16 +18,22 @@ interface ValidationResult {
     typesGenerated?: number;
 }
 interface ValidationError {
-    type: 'schema' | 'file-missing' | 'export-mismatch' | 'contract-invalid' | 'component-contract-mismatch' | 'type-generation-failed';
+    type: 'schema' | 'file-missing' | 'export-mismatch' | 'contract-invalid' | 'component-contract-mismatch' | 'type-generation-failed' | 'add-menu-catalog';
     message: string;
     location?: string;
     suggestion?: string;
+    /** Add Menu lint / schema code (Design Log #30) */
+    code?: string;
+    itemId?: string;
 }
 interface ValidationWarning {
     type: string;
     message: string;
     location?: string;
     suggestion?: string;
+    /** Add Menu lint code (Design Log #30) */
+    code?: string;
+    itemId?: string;
 }
 interface PluginContext {
     manifest: PluginManifest;
@@ -79,4 +85,72 @@ interface CheckResult {
  */
 declare function checkComponentPropsAndParams(sourceCode: string, contract: ContractPropsAndParams, contractName: string, contractPath: string, sourcePath: string): CheckResult;
 
-export { type PluginContext, type ValidatePluginOptions, type ValidationError, type ValidationResult, type ValidationWarning, checkComponentPropsAndParams, validatePlugin };
+/**
+ * Add Menu catalog schema validation and lint.
+ *
+ * Source of truth for plugin authors (`jay-stack validate-plugin`) and for
+ * AIditor runtime catalog loading. When changing Add Menu schema or lint rules,
+ * update this module and `agent-kit/plugin/aiditor-add-menu.md` in the same change.
+ */
+type AddMenuBrowseSize = 'large' | 'medium' | 'small';
+type AddMenuPresentation = {
+    type: 'image';
+    src: string;
+} | {
+    type: 'gif';
+    src: string;
+    poster?: string;
+} | {
+    type: 'html-fragment';
+    html: string;
+};
+type AddMenuInteraction = {
+    mode: 'reference' | 'stage-place';
+    stagePromptTemplate?: string;
+};
+type AddMenuCatalogLintWarning = {
+    code: string;
+    message: string;
+    itemId?: string;
+    sourcePath?: string;
+};
+type AddMenuValidationError = {
+    path: string;
+    message: string;
+    code?: string;
+};
+type AddMenuItem = {
+    id: string;
+    title: string;
+    category: string;
+    prompt: string;
+    pluginName?: string;
+    packageName?: string;
+    subCategory?: string;
+    folderPath?: string[];
+    thumbnail?: string;
+    presentation?: AddMenuPresentation;
+    browse?: {
+        size?: AddMenuBrowseSize;
+    };
+    interaction?: AddMenuInteraction;
+};
+type AddMenuCatalogFile = {
+    items: AddMenuItem[];
+};
+declare function validateAddMenuItem(raw: unknown, itemPath: string): {
+    item: AddMenuItem | null;
+    errors: AddMenuValidationError[];
+};
+declare function validateAddMenuCatalogFile(raw: unknown, sourcePath: string): {
+    file: AddMenuCatalogFile | null;
+    errors: AddMenuValidationError[];
+};
+declare function lintAddMenuCatalog(items: AddMenuItem[], sourcePath: string): {
+    errors: AddMenuCatalogLintWarning[];
+    warnings: AddMenuCatalogLintWarning[];
+};
+/** Human-readable fix hints for validate-plugin output. */
+declare const ADD_MENU_VALIDATION_SUGGESTIONS: Record<string, string>;
+
+export { ADD_MENU_VALIDATION_SUGGESTIONS, type AddMenuBrowseSize, type AddMenuCatalogFile, type AddMenuCatalogLintWarning, type AddMenuInteraction, type AddMenuItem, type AddMenuPresentation, type AddMenuValidationError, type PluginContext, type ValidatePluginOptions, type ValidationError, type ValidationResult, type ValidationWarning, checkComponentPropsAndParams, lintAddMenuCatalog, validateAddMenuCatalogFile, validateAddMenuItem, validatePlugin };

package/dist/index.js

@@ -272,6 +272,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) {
@@ -338,6 +1101,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;
 }
@@ -451,6 +1215,14 @@ async function validateSchema(context, result) {
             location: "plugin.yaml",
             suggestion: 'Specify the exported member name from the module (e.g., "moodTracker")'
           });
+        } else {
+          validateHandlerRef(
+            contract.component,
+            `Contract "${contract.name}" component`,
+            `plugin.yaml contracts[${index}]`,
+            context,
+            result
+          );
         }
       });
     }
@@ -483,6 +1255,24 @@ async function validateSchema(context, result) {
           suggestion: 'Specify prefix for dynamic contract names (e.g., "cms")'
         });
       }
+      if (config.component) {
+        validateHandlerRef(
+          config.component,
+          `dynamic_contracts[${prefix}] component`,
+          `plugin.yaml dynamic_contracts`,
+          context,
+          result
+        );
+      }
+      if (config.generator) {
+        validateHandlerRef(
+          config.generator,
+          `dynamic_contracts[${prefix}] generator`,
+          `plugin.yaml dynamic_contracts`,
+          context,
+          result
+        );
+      }
     }
   }
   if (!manifest.contracts && !manifest.dynamic_contracts) {
@@ -553,6 +1343,23 @@ async function validateSchema(context, result) {
       });
     }
   }
+  if (manifest.actions) {
+    for (const entry of manifest.actions) {
+      const exportName = typeof entry === "string" ? entry : entry.name;
+      if (exportName) {
+        validateHandlerRef(
+          exportName,
+          `Action "${exportName}"`,
+          "plugin.yaml actions",
+          context,
+          result
+        );
+      }
+    }
+  }
+  if (manifest.init) {
+    validateHandlerRef(manifest.init, "Init handler", "plugin.yaml init", context, result);
+  }
   if (manifest.routes) {
     if (!Array.isArray(manifest.routes)) {
       result.errors.push({
@@ -584,6 +1391,14 @@ async function validateSchema(context, result) {
             location: "plugin.yaml",
             suggestion: "Specify the exported member name for the page component"
           });
+        } else {
+          validateHandlerRef(
+            route.component,
+            `Route "${route.path}" component`,
+            `plugin.yaml routes`,
+            context,
+            result
+          );
         }
         if (route.jayHtml) {
           validateDocFile(
@@ -623,22 +1438,112 @@ async function validateSchema(context, result) {
             suggestion: "Specify the relative path to the validator handler module"
           });
         }
-        if (validator.handler && !context.isNpmPackage) {
-          const handlerPath = path.join(context.pluginPath, validator.handler);
-          const extensions = ["", ".ts", ".js", "/index.ts", "/index.js"];
-          const found = extensions.some((ext) => fs.existsSync(handlerPath + ext));
-          if (!found) {
-            result.errors.push({
-              type: "file-missing",
-              message: `Validator "${validator.name}" handler not found: ${validator.handler}`,
-              location: "plugin.yaml validators",
-              suggestion: `Create the validator handler at ${handlerPath}.ts`
-            });
-          }
+        if (validator.handler) {
+          validateHandlerRef(
+            validator.handler,
+            `Validator "${validator.name}" handler`,
+            "plugin.yaml validators",
+            context,
+            result
+          );
         }
       });
     }
   }
+  if (manifest.setup) {
+    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,
+        "Setup handler",
+        "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");
+  if (!fs.existsSync(packageJsonPath))
+    return true;
+  let mainPath;
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+    if (packageJson.exports?.["."]) {
+      const entry = packageJson.exports["."];
+      const entryPath = typeof entry === "string" ? entry : entry.default || entry.import;
+      if (entryPath)
+        mainPath = path.join(context.pluginPath, entryPath);
+    }
+    if (!mainPath && packageJson.main) {
+      mainPath = path.join(context.pluginPath, packageJson.main);
+    }
+  } catch {
+    return true;
+  }
+  if (!mainPath || !fs.existsSync(mainPath))
+    return true;
+  try {
+    const content = fs.readFileSync(mainPath, "utf-8");
+    const patterns = [
+      new RegExp(`export\\s*\\{[^}]*\\b${exportName}\\b[^}]*\\}`, "m"),
+      new RegExp(`export\\s+(?:async\\s+)?function\\s+${exportName}\\b`),
+      new RegExp(`export\\s+(?:const|let|var)\\s+${exportName}\\b`)
+    ];
+    return patterns.some((p) => p.test(content));
+  } catch {
+    return true;
+  }
+}
+function isRelativePath(value) {
+  return value.startsWith("./") || value.startsWith("../");
+}
+function validateHandlerRef(value, label, location, context, result) {
+  if (context.isNpmPackage) {
+    if (isRelativePath(value)) {
+      result.errors.push({
+        type: "export-mismatch",
+        message: `${label} "${value}" is a relative path, but NPM plugins must use an export name`,
+        location,
+        suggestion: `Export the function from the package entry point and use the export name instead of a path`
+      });
+    } else if (!checkExportExists(value, context)) {
+      result.errors.push({
+        type: "export-mismatch",
+        message: `${label} "${value}" is not exported from the package`,
+        location,
+        suggestion: `Add "export { ${value} } from '...'" to the package entry point`
+      });
+    }
+  } else if (isRelativePath(value)) {
+    const handlerPath = path.join(context.pluginPath, value);
+    const extensions = ["", ".ts", ".js", "/index.ts", "/index.js"];
+    const found = extensions.some((ext) => fs.existsSync(handlerPath + ext));
+    if (!found) {
+      result.errors.push({
+        type: "file-missing",
+        message: `${label} not found: ${value}`,
+        location,
+        suggestion: `Create the handler at ${handlerPath}.ts`
+      });
+    }
+  }
 }
 function resolveContractFile(contractSpec, context) {
   if (context.isNpmPackage) {
@@ -958,6 +1863,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",
@@ -1020,6 +1937,10 @@ async function validateDynamicContracts(context, result) {
   }
 }
 export {
+  ADD_MENU_VALIDATION_SUGGESTIONS,
   checkComponentPropsAndParams,
+  lintAddMenuCatalog,
+  validateAddMenuCatalogFile,
+  validateAddMenuItem,
   validatePlugin
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/plugin-validator",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Validation tool for Jay Stack plugins",
@@ -21,19 +21,19 @@
     "build:check-types": "tsc",
     "clean": "rimraf dist",
     "confirm": "npm run clean && npm run build && npm run build:check-types && npm run test",
-    "test": ":",
-    "test:watch": ":"
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-html": "^0.20.0",
-    "@jay-framework/compiler-shared": "^0.20.0",
-    "@jay-framework/editor-protocol": "^0.20.0",
-    "@jay-framework/typescript-bridge": "^0.20.0",
+    "@jay-framework/compiler-jay-html": "^0.22.0",
+    "@jay-framework/compiler-shared": "^0.22.0",
+    "@jay-framework/editor-protocol": "^0.22.0",
+    "@jay-framework/typescript-bridge": "^0.22.0",
     "chalk": "^4.1.2",
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.20.0",
+    "@jay-framework/dev-environment": "^0.22.0",
     "@types/node": "^22.15.21",
     "rimraf": "^5.0.5",
     "tsup": "^8.0.1",