@jay-framework/jay-stack-cli 0.25.4 → 0.26.0

package/dist/index.js

@@ -9,7 +9,7 @@ import YAML from "yaml";
 import { getLogger, setDevLogger, createDevLogger } from "@jay-framework/logger";
 import { parseJayFile, JAY_IMPORT_RESOLVER, generateElementDefinitionFile, parseContract, compileContract, parseAction, generateElementFile, generateServerElementFile, htmlElementTagNameMap, loadLinkedContract, getLinkedContractDir } from "@jay-framework/compiler-jay-html";
 import { checkValidationErrors, JAY_CONTRACT_EXTENSION as JAY_CONTRACT_EXTENSION$1, loadPluginManifest as loadPluginManifest$1, normalizeActionEntry as normalizeActionEntry$1, JAY_EXTENSION as JAY_EXTENSION$1, RuntimeMode as RuntimeMode$1, GenerateTarget, findDynamicContract, isEnumType as isEnumType$1, equalJayTypes, prettifyHtml } from "@jay-framework/compiler-shared";
-import fs$2 from "node:fs/promises";
+import fs$1$1 from "node:fs/promises";
 import * as path from "node:path";
 import path__default from "node:path";
 import { scanPlugins, sortPluginsByDependencies, getServiceRegistry, actionRegistry, resolveServices, headMetaToHeadTags, ActionRegistry, discoverPluginsWithInit, executePluginServerInits, runInitCallbacks, registerService } from "@jay-framework/stack-server-runtime";
@@ -26,6 +26,7 @@ import chalk from "chalk";
 import { glob } from "glob";
 import postcss from "postcss";
 import { scanRoutes, JayRouteParamType } from "@jay-framework/stack-route-scanner";
+import { FilesystemArtifactStore } from "@jay-framework/production-server";
 import { fileURLToPath } from "node:url";
 import { select, confirm, input } from "@inquirer/prompts";
 const DEFAULT_CONFIG = {
@@ -65,7 +66,11 @@ function getConfigWithDefaults(config) {
       pagesBase: config.devServer?.pagesBase || DEFAULT_CONFIG.devServer.pagesBase,
       componentsBase: config.devServer?.componentsBase || DEFAULT_CONFIG.devServer.componentsBase,
       publicFolder: config.devServer?.publicFolder || DEFAULT_CONFIG.devServer.publicFolder,
-      configBase: config.devServer?.configBase || DEFAULT_CONFIG.devServer.configBase
+      configBase: config.devServer?.configBase || DEFAULT_CONFIG.devServer.configBase,
+      // No default — absent means Vite's localhost-only host check (DL#220).
+      allowedHosts: config.devServer?.allowedHosts,
+      // Default off — source-editing markers (DL#219) only for opt-in sessions.
+      sourceEditing: config.devServer?.sourceEditing
     },
     site: config.site
   };
@@ -220,7 +225,9 @@ async function startDevServer(options = {}) {
     publicBaseUrlPath: "/",
     jayRollupConfig: jayOptions,
     logLevel: options.logLevel,
-    httpServer
+    httpServer,
+    allowedHosts: resolvedConfig.devServer.allowedHosts,
+    sourceEditing: resolvedConfig.devServer.sourceEditing
   });
   app.use(server);
   const publicPath = path$1.resolve(resolvedConfig.devServer.publicFolder);
@@ -3306,7 +3313,7 @@ async function validateSchema(context, result) {
     }
   }
   const hasCapability = Boolean(
-    manifest.contracts || manifest.dynamic_contracts || manifest.actions || manifest.validators || manifest.routes || manifest.services || manifest.contexts || manifest.init || manifest.setup || manifest.agentkit || manifest.commands
+    manifest.contracts || manifest.dynamic_contracts || manifest.actions || manifest.validators || manifest.projectValidators || manifest.routes || manifest.services || manifest.contexts || manifest.init || manifest.setup || manifest.agentkit || manifest.commands
   );
   if (!hasCapability) {
     if (manifest.global === true) {
@@ -3322,7 +3329,7 @@ async function validateSchema(context, result) {
     } else {
       result.warnings.push({
         type: "schema",
-        message: "Plugin declares no capabilities (contracts, dynamic_contracts, actions, validators, routes, services, contexts, init, setup, agentkit, commands)",
+        message: "Plugin declares no capabilities (contracts, dynamic_contracts, actions, validators, projectValidators, routes, services, contexts, init, setup, agentkit, commands)",
         location: "plugin.yaml",
         suggestion: "Declare at least one capability. See agent-kit/plugin/plugin-structure.md"
       });
@@ -3512,6 +3519,43 @@ async function validateSchema(context, result) {
       });
     }
   }
+  if (manifest.projectValidators) {
+    if (!Array.isArray(manifest.projectValidators)) {
+      result.errors.push({
+        type: "schema",
+        message: 'Field "projectValidators" must be an array',
+        location: "plugin.yaml"
+      });
+    } else {
+      manifest.projectValidators.forEach((validator, index) => {
+        if (!validator.name) {
+          result.errors.push({
+            type: "schema",
+            message: `Project validator at index ${index} is missing "name" field`,
+            location: "plugin.yaml"
+          });
+        }
+        if (!validator.handler) {
+          result.errors.push({
+            type: "schema",
+            message: `Project validator "${validator.name || index}" is missing "handler" field`,
+            location: "plugin.yaml",
+            suggestion: "Specify the relative path to the project validator handler module"
+          });
+        }
+        if (validator.handler) {
+          validateHandlerRef(
+            validator.handler,
+            `Project validator "${validator.name}" handler`,
+            "plugin.yaml projectValidators",
+            context,
+            result,
+            "./tools"
+          );
+        }
+      });
+    }
+  }
   if (manifest.setup) {
     if (typeof manifest.setup !== "string") {
       result.errors.push({
@@ -3593,7 +3637,7 @@ function hasComponentCapability(context) {
   return Boolean(m.contracts || m.dynamic_contracts || m.routes);
 }
 function needsToolsEntry(manifest) {
-  if (manifest.validators || manifest.commands || manifest.agentkit || manifest.setup) {
+  if (manifest.validators || manifest.projectValidators || manifest.commands || manifest.agentkit || manifest.setup) {
     return true;
   }
   if (manifest.actions) {
@@ -3695,6 +3739,25 @@ function resolveContractFile(contractSpec, context) {
 }
 async function validateContract(contract, index, context, generateTypes, result) {
   result.contractsChecked = (result.contractsChecked || 0) + 1;
+  const hasEditingGuide = typeof contract.editingGuide === "string" && contract.editingGuide.length > 0;
+  const isReadonly = contract.readonly === true;
+  if (!hasEditingGuide && !isReadonly) {
+    result.warnings.push({
+      type: "source-editing-coverage",
+      message: `Contract "${contract.name}" declares no source-editing story. Add "editingGuide: <path.md>" (how to edit its bound data) or "readonly: true" (not editable in place).`,
+      location: `plugin.yaml contracts[${index}]`,
+      suggestion: "See the plugin source-editing guide (DL#219)."
+    });
+  } else if (hasEditingGuide) {
+    const guideFullPath = path$1.resolve(context.pluginPath, contract.editingGuide);
+    if (!fs$1.existsSync(guideFullPath)) {
+      result.warnings.push({
+        type: "source-editing-coverage",
+        message: `Contract "${contract.name}" editingGuide file not found: ${contract.editingGuide}`,
+        location: `plugin.yaml contracts[${index}]`
+      });
+    }
+  }
   const contractPath = resolveContractFile(contract.contract, context);
   if (!contractPath) {
     result.errors.push({
@@ -4198,7 +4261,7 @@ function facetLabel(f) {
   }
 }
 const CONTENT_MARKER = "jay-content";
-const META_ATTRS = /* @__PURE__ */ new Set(["jc", "override", "page-scope", CONTENT_MARKER]);
+const META_ATTRS = /* @__PURE__ */ new Set(["jc", "override", "page-scope", CONTENT_MARKER, "jay-policy"]);
 function isMetaAttr(name) {
   return META_ATTRS.has(name.toLowerCase());
 }
@@ -4821,6 +4884,8 @@ function normalizeCssBody(body) {
 }
 const SUPPRESS_KEY = "allow-broken-links";
 const SUPPRESS_HINT = 'suppress with jay-stack:\n  allow-broken-links: true\nin a <script type="application/jay-validations"> block';
+const SELF_LINK_ALLOW_ATTR = "jay-allow-self-link";
+const TODO_SCHEME = /^todo:/i;
 function normalizePath(p) {
   let s2 = p.split("#")[0].split("?")[0];
   s2 = s2.replace(/\/{2,}/g, "/");
@@ -4916,64 +4981,137 @@ function originOf(baseUrl) {
     return void 0;
   }
 }
+function fragmentOf(raw) {
+  const hash = raw.indexOf("#");
+  return hash === -1 ? "" : raw.slice(hash + 1);
+}
 function classifyHref(raw, baseUrl) {
   if (raw.includes("{")) return { kind: "skip" };
   const t = raw.trim();
   if (t === "" || t === "#") return { kind: "degenerate" };
-  if (t.startsWith("#")) return { kind: "skip" };
+  if (TODO_SCHEME.test(t)) return { kind: "todo", note: t.replace(TODO_SCHEME, "").trim() };
+  if (t.startsWith("#")) return { kind: "localFragment", fragment: t.slice(1) };
   if (/^(mailto:|tel:|javascript:|data:|sms:|ftp:)/i.test(t)) return { kind: "skip" };
   if (/^[a-z][a-z0-9+.-]*:\/\//i.test(t) || t.startsWith("//")) {
     const sameOrigin = baseUrl ? originOf(baseUrl) : void 0;
     if (sameOrigin) {
       try {
         const u2 = new URL(t.startsWith("//") ? "https:" + t : t);
-        if (u2.origin === sameOrigin)
-          return { kind: "check", targetPath: normalizePath(u2.pathname) };
+        if (u2.origin === sameOrigin) {
+          const frag = u2.hash.slice(1);
+          return frag ? { kind: "check", targetPath: normalizePath(u2.pathname), fragment: frag } : { kind: "check", targetPath: normalizePath(u2.pathname) };
+        }
       } catch {
       }
     }
     return { kind: "skip" };
   }
-  if (t.startsWith("/")) return { kind: "check", targetPath: normalizePath(t) };
+  if (t.startsWith("/")) {
+    const frag = fragmentOf(t);
+    return frag ? { kind: "check", targetPath: normalizePath(t), fragment: frag } : { kind: "check", targetPath: normalizePath(t) };
+  }
   return { kind: "skip" };
 }
+function fragmentNeedsAnchor(fragment) {
+  const f = fragment.trim();
+  return f !== "" && f.toLowerCase() !== "top";
+}
+function collectAnchorIds(body) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const el of body.querySelectorAll("[id]")) {
+    const id = el.getAttribute("id");
+    if (id) ids.add(id);
+  }
+  for (const a of body.querySelectorAll("a[name]")) {
+    const name = a.getAttribute("name");
+    if (name) ids.add(name);
+  }
+  return ids;
+}
 function checkInternalLinks(options) {
   const { parsedFiles, oracle, assetUrls, baseUrl, projectRoot } = options;
   const findings = [];
+  const idsByUrl = /* @__PURE__ */ new Map();
   for (const { relativePath, parsed } of parsedFiles) {
-    if (parsed.validationOverrides?.["jay-stack"]?.[SUPPRESS_KEY] === true) continue;
+    const url = oracle.selfUrlByPath.get(path$1.resolve(projectRoot ?? ".", relativePath));
+    if (url !== void 0) idsByUrl.set(url, collectAnchorIds(parsed.body));
+  }
+  for (const { relativePath, parsed } of parsedFiles) {
+    const allowBroken = parsed.validationOverrides?.["jay-stack"]?.[SUPPRESS_KEY] === true;
     const ownUrl = oracle.selfUrlByPath.get(path$1.resolve(projectRoot ?? ".", relativePath));
+    const ownIds = ownUrl !== void 0 ? idsByUrl.get(ownUrl) : void 0;
     for (const anchor of parsed.body.querySelectorAll("a[href]")) {
       const raw = anchor.getAttribute("href");
       if (raw === void 0 || raw === null) continue;
       const verdict = classifyHref(raw, baseUrl);
       if (verdict.kind === "skip") continue;
       const tag = openingTag(anchor);
+      if (verdict.kind === "todo") {
+        const note = verdict.note ? ` — intended target "${verdict.note}" is not wired up yet` : "";
+        findings.push({
+          file: relativePath,
+          severity: "warning",
+          message: `TODO link ${tag}${note}. This reminder cannot be suppressed — resolve it before release.`,
+          suggestion: `Replace the "todo:" href with the real destination once the page/route exists.`
+        });
+        continue;
+      }
+      if (verdict.kind === "localFragment") {
+        if (!fragmentNeedsAnchor(verdict.fragment)) continue;
+        if (ownIds && !ownIds.has(verdict.fragment)) {
+          findings.push({
+            file: relativePath,
+            severity: "error",
+            message: `Broken fragment link ${tag} — this page has no element with id "${verdict.fragment}".`,
+            suggestion: `Add id="${verdict.fragment}" to the target element, or fix the fragment.`
+          });
+        }
+        continue;
+      }
       if (verdict.kind === "degenerate") {
+        if (allowBroken) continue;
         findings.push({
           file: relativePath,
+          severity: "error",
           message: `Anchor ${tag} has a placeholder href "${raw}" — it links nowhere and ships as a dead link.`,
           suggestion: `Point the link at a real page, use <button> for a JS-driven action, or ${SUPPRESS_HINT}.`
         });
         continue;
       }
       const target = verdict.targetPath;
-      if (ownUrl !== void 0 && target === ownUrl) {
+      const fragment = verdict.fragment ?? "";
+      if (ownUrl !== void 0 && target === ownUrl && !fragmentNeedsAnchor(fragment)) {
+        if (anchor.hasAttribute(SELF_LINK_ALLOW_ATTR)) continue;
         findings.push({
           file: relativePath,
+          severity: "warning",
           message: `Anchor ${tag} points to the page's own route "${target}" — a self-link goes nowhere.`,
-          suggestion: `Remove the link, use "#" within-page navigation, or point it at a different page.`
+          suggestion: `Remove the link, use an in-page "#" fragment, or add ${SELF_LINK_ALLOW_ATTR} to the anchor if intentional.`
         });
         continue;
       }
-      if (oracle.staticUrls.has(target)) continue;
-      if (assetUrls.has(target)) continue;
-      if (oracle.dynamicMatchers.some((re) => re.test(target))) continue;
-      findings.push({
-        file: relativePath,
-        message: `Broken internal link in anchor ${tag} — no page or public asset produces the URL "${target}".`,
-        suggestion: `Create a placeholder page/route for "${target}", or remove the link. Otherwise ${SUPPRESS_HINT}.`
-      });
+      const resolves = oracle.staticUrls.has(target) || assetUrls.has(target) || oracle.dynamicMatchers.some((re) => re.test(target));
+      if (!resolves) {
+        if (allowBroken) continue;
+        findings.push({
+          file: relativePath,
+          severity: "error",
+          message: `Broken internal link in anchor ${tag} — no page or public asset produces the URL "${target}".`,
+          suggestion: `Create a placeholder page/route for "${target}", or remove the link. Otherwise ${SUPPRESS_HINT}.`
+        });
+        continue;
+      }
+      if (fragmentNeedsAnchor(fragment)) {
+        const targetIds = target === ownUrl ? ownIds : idsByUrl.get(target);
+        if (targetIds && !targetIds.has(fragment)) {
+          findings.push({
+            file: relativePath,
+            severity: "error",
+            message: `Broken fragment link ${tag} — page "${target}" has no element with id "${fragment}".`,
+            suggestion: `Add id="${fragment}" to the target element on "${target}", or fix the fragment.`
+          });
+        }
+      }
     }
   }
   return findings;
@@ -4983,6 +5121,47 @@ const LINK_SUPPRESS_HINT = 'suppress with jay-stack:\n  allow-broken-links: true
 const UNRESOLVED_BINDING = /\{[A-Za-z_$][\w$]*(?:\.[\w$]+)*\}/;
 const TITLE_MAX = 60;
 const DESCRIPTION_MAX = 160;
+const PAGE_CACHE_SOFT_BYTES = 300 * 1024;
+const PAGE_CACHE_HARD_BYTES = 512 * 1024;
+async function checkPageCacheFileSizes(args) {
+  const { cacheAbsPath, routePattern } = args;
+  const findings = [];
+  const rel = path$1.basename(path$1.dirname(cacheAbsPath)) + "/" + path$1.basename(cacheAbsPath);
+  let bytes;
+  try {
+    bytes = (await promises.stat(cacheAbsPath)).size;
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    findings.push({
+      file: routePattern,
+      message: `${rel} is listed in the build manifest but could not be read (${detail}).`,
+      suggestion: "Rebuild the project or fix the missing pre-rendered cache file.",
+      severity: "error",
+      source: "build-output"
+    });
+    return findings;
+  }
+  if (bytes >= PAGE_CACHE_HARD_BYTES) {
+    const hardKiB = PAGE_CACHE_HARD_BYTES / 1024;
+    findings.push({
+      file: routePattern,
+      message: `${rel} is ${bytes} bytes (≥ ${PAGE_CACHE_HARD_BYTES} bytes / ${hardKiB} KiB hard limit). Shrink slow-phase carry before deploy.`,
+      suggestion: "Reduce slow-phase carryForward in this cache file before deploy (smaller payloads, defer non-first-paint data). See agent-kit developer/query-param-pages.md — cache size thresholds.",
+      severity: "error",
+      source: "build-output"
+    });
+  } else if (bytes >= PAGE_CACHE_SOFT_BYTES) {
+    const softKiB = PAGE_CACHE_SOFT_BYTES / 1024;
+    findings.push({
+      file: routePattern,
+      message: `${rel} is ${bytes} bytes (≥ ${PAGE_CACHE_SOFT_BYTES} bytes / ${softKiB} KiB soft budget). Consider deferring non-critical carry data.`,
+      suggestion: "Review carryForward size: keep only what the default view needs for first paint; defer the rest (per-request fetch or post-hydration load). Oversize caches often need product decisions about what loads when — see agent-kit developer/query-param-pages.md.",
+      severity: "warning",
+      source: "build-output"
+    });
+  }
+  return findings;
+}
 function buildUrlFromManifest(pattern, params) {
   return pattern.replace(/\[\[(\w+)\]\]/g, (_, name) => params[name] || "").replace(/\[\.\.\.(\w+)\]/g, (_, name) => params[name] || "").replace(/\[(\w+)\]/g, (_, name) => params[name] || "").replace(/\/\/+/g, "/").replace(/\/$/, "") || "/";
 }
@@ -5053,16 +5232,15 @@ async function loadBuildManifest(backendDir) {
   }
   return { manifest, metadata };
 }
-function buildBuildOracle(manifest, backendDir) {
+async function buildBuildOracle(manifest, backendDir) {
+  const store = new FilesystemArtifactStore(backendDir);
   const urls = /* @__PURE__ */ new Set();
   const instances = [];
   for (const route of manifest.routes) {
     const hasDynamic = route.segments.some((s2) => s2.type !== "static");
-    if (route.instances.length === 0) {
-      if (!hasDynamic) urls.add(normalizePath(route.pattern));
-      continue;
-    }
-    for (const instance of route.instances) {
+    let count = 0;
+    for await (const instance of store.listInstances(route, { fresh: true })) {
+      count++;
       const url = routeInstanceUrl(route, instance);
       urls.add(url);
       instances.push({
@@ -5072,6 +5250,7 @@ function buildBuildOracle(manifest, backendDir) {
         headMeta: route.headMeta
       });
     }
+    if (count === 0 && !hasDynamic) urls.add(normalizePath(route.pattern));
   }
   return { urls, instances };
 }
@@ -5329,122 +5508,6 @@ async function newestSourceMtime(dirs) {
   for (const dir of dirs) await walk(dir);
   return newest;
 }
-const URN_PATTERN = /^urn:air:[^:\s]+:[^:\s]+:[^:\s]+$/;
-const MEDIA_TYPE_PATTERN = /^[a-z]+\/[A-Za-z0-9.+-]+$/;
-const ARD_SUGGEST = "See developer/seo-guide.md (ARD v0.91) for the schema and a worked example.";
-function validateArdDocument(doc) {
-  const findings = [];
-  if (!doc || typeof doc !== "object") {
-    return [
-      {
-        message: "ard.json must be a JSON object with an `entries` array.",
-        severity: "error",
-        suggestion: ARD_SUGGEST
-      }
-    ];
-  }
-  const entries = doc.entries;
-  if (!Array.isArray(entries)) {
-    return [
-      {
-        message: "ard.json is missing the required `entries` array.",
-        severity: "error",
-        suggestion: ARD_SUGGEST
-      }
-    ];
-  }
-  entries.forEach((entry, i) => {
-    const at = `ard.json entries[${i}]`;
-    if (!entry || typeof entry !== "object") {
-      findings.push({ message: `${at} must be an object.`, severity: "error" });
-      return;
-    }
-    if (typeof entry.identifier !== "string" || !URN_PATTERN.test(entry.identifier)) {
-      findings.push({
-        message: `${at}.identifier must match urn:air:<publisher>:<namespace>:<name>.`,
-        severity: "error",
-        suggestion: ARD_SUGGEST
-      });
-    }
-    if (typeof entry.displayName !== "string" || entry.displayName.trim() === "") {
-      findings.push({
-        message: `${at}.displayName is required.`,
-        severity: "error"
-      });
-    }
-    if (typeof entry.type !== "string" || !MEDIA_TYPE_PATTERN.test(entry.type)) {
-      findings.push({
-        message: `${at}.type must be an IANA media type (e.g. application/mcp-server-card+json).`,
-        severity: "error"
-      });
-    }
-    const hasUrl = entry.url !== void 0;
-    const hasData = entry.data !== void 0;
-    if (hasUrl === hasData) {
-      findings.push({
-        message: `${at} must have exactly one of \`url\` or \`data\`.`,
-        severity: "error"
-      });
-    }
-    const rq = entry.representativeQueries;
-    if (rq === void 0) {
-      findings.push({
-        message: `${at} is missing representativeQueries (2–5 recommended) — agents may not surface this resource.`,
-        severity: "warning",
-        suggestion: ARD_SUGGEST
-      });
-    } else if (!Array.isArray(rq) || rq.length < 2 || rq.length > 5) {
-      findings.push({
-        message: `${at}.representativeQueries should list 2–5 example queries.`,
-        severity: "warning"
-      });
-    }
-  });
-  return findings;
-}
-async function checkArdFiles(projectRoot) {
-  const wellKnown = path$1.resolve(projectRoot, "public/.well-known");
-  const ardPath = path$1.join(wellKnown, "ard.json");
-  const aliasPath = path$1.join(wellKnown, "ai-catalog.json");
-  const ardRaw = await readIfExists(ardPath);
-  const aliasRaw = await readIfExists(aliasPath);
-  if (ardRaw === null && aliasRaw === null) {
-    return { findings: [], absent: true };
-  }
-  const findings = [];
-  if (ardRaw === null && aliasRaw !== null) {
-    findings.push({
-      message: "Only public/.well-known/ai-catalog.json found — ARD renamed this to ard.json. Add ard.json (keep ai-catalog.json as a copy for older clients).",
-      severity: "warning",
-      suggestion: ARD_SUGGEST
-    });
-  } else if (ardRaw !== null && aliasRaw !== null && ardRaw.trim() !== aliasRaw.trim()) {
-    findings.push({
-      message: "public/.well-known/ard.json and ai-catalog.json differ — the alias should be a copy of ard.json.",
-      severity: "warning"
-    });
-  }
-  const canonicalRaw = ardRaw ?? aliasRaw;
-  let parsed;
-  try {
-    parsed = JSON.parse(canonicalRaw);
-  } catch (e2) {
-    findings.push({
-      message: `${ardRaw !== null ? "ard.json" : "ai-catalog.json"} is not valid JSON: ${e2.message}`,
-      severity: "error"
-    });
-    return { findings, absent: false };
-  }
-  findings.push(...validateArdDocument(parsed));
-  return { findings, absent: false };
-}
-async function readIfExists(p) {
-  try {
-    return await promises.readFile(p, "utf8");
-  } catch {
-    return null;
-  }
-}
 async function findJayFiles(dir) {
   return await glob(`${dir}/**/*${JAY_EXTENSION$1}`);
 }
@@ -6448,6 +6511,37 @@ function resolveContractLinks(contract, contractPath) {
   const contractDir = path$1.dirname(contractPath);
   return { ...contract, tags: resolveLinkedTags(contract.tags, contractDir) };
 }
+async function loadPluginToolsHandler(plugin, handlerRef, capabilityLabel, name, source, errors) {
+  try {
+    let handlerModule;
+    if (plugin.isLocal) {
+      const handlerPath = path$1.resolve(plugin.pluginPath, handlerRef);
+      handlerModule = await import(handlerPath);
+    } else {
+      handlerModule = await import(`${plugin.packageName}/tools`);
+    }
+    const fn = plugin.isLocal ? handlerModule.validate ?? handlerModule.default : handlerModule[handlerRef];
+    if (typeof fn !== "function") {
+      const expected = plugin.isLocal ? "validate" : handlerRef;
+      errors.push({
+        file: `plugin:${plugin.name}`,
+        message: `${capabilityLabel} "${name}" handler does not export a "${expected}" function`,
+        stage: "plugin",
+        source
+      });
+      return void 0;
+    }
+    return fn;
+  } catch (loadErr) {
+    errors.push({
+      file: `plugin:${plugin.name}`,
+      message: `Failed to load ${capabilityLabel.toLowerCase()} "${name}": ${loadErr.message}`,
+      stage: "plugin",
+      source
+    });
+    return void 0;
+  }
+}
 async function runPluginValidators(projectRoot, parsedFiles, errors, warnings) {
   const scannedPlugins = await scanPlugins({ projectRoot, includeDevDeps: true });
   const loadedValidators = [];
@@ -6455,37 +6549,16 @@ async function runPluginValidators(projectRoot, parsedFiles, errors, warnings) {
     if (!plugin.manifest.validators) continue;
     for (const validatorDef of plugin.manifest.validators) {
       const source = `${plugin.name}/${validatorDef.name}`;
-      let validatorFn;
-      try {
-        let handlerModule;
-        if (plugin.isLocal) {
-          const handlerPath = path$1.resolve(plugin.pluginPath, validatorDef.handler);
-          handlerModule = await import(handlerPath);
-        } else {
-          handlerModule = await import(`${plugin.packageName}/tools`);
-        }
-        validatorFn = plugin.isLocal ? handlerModule.validate ?? handlerModule.default : handlerModule[validatorDef.handler];
-        if (typeof validatorFn !== "function") {
-          errors.push({
-            file: `plugin:${plugin.name}`,
-            message: `Validator "${validatorDef.name}" handler does not export a "validate" function`,
-            stage: "plugin",
-            source
-          });
-          loadedValidators.push(source);
-          continue;
-        }
-      } catch (loadErr) {
-        errors.push({
-          file: `plugin:${plugin.name}`,
-          message: `Failed to load validator "${validatorDef.name}": ${loadErr.message}`,
-          stage: "plugin",
-          source
-        });
-        loadedValidators.push(source);
-        continue;
-      }
+      const validatorFn = await loadPluginToolsHandler(
+        plugin,
+        validatorDef.handler,
+        "Validator",
+        validatorDef.name,
+        source,
+        errors
+      );
       loadedValidators.push(source);
+      if (!validatorFn) continue;
       for (const { relativePath, parsed } of parsedFiles) {
         const pageContractPath = parsed.contractRef ? path$1.resolve(
           path$1.dirname(path$1.resolve(projectRoot, relativePath)),
@@ -6568,6 +6641,56 @@ async function runPluginValidators(projectRoot, parsedFiles, errors, warnings) {
   }
   return loadedValidators;
 }
+async function runProjectValidators(projectRoot, errors, warnings) {
+  const scannedPlugins = await scanPlugins({ projectRoot, includeDevDeps: true });
+  const loadedValidators = [];
+  for (const [, plugin] of scannedPlugins) {
+    if (!plugin.manifest.projectValidators) continue;
+    for (const validatorDef of plugin.manifest.projectValidators) {
+      const source = `${plugin.name}/${validatorDef.name}`;
+      const validatorFn = await loadPluginToolsHandler(
+        plugin,
+        validatorDef.handler,
+        "Project validator",
+        validatorDef.name,
+        source,
+        errors
+      );
+      loadedValidators.push(source);
+      if (!validatorFn) continue;
+      const ctx = { projectRoot };
+      try {
+        const findings = await validatorFn(ctx);
+        for (const finding of findings) {
+          if (finding.severity === "error") {
+            errors.push({
+              file: finding.file,
+              message: finding.message,
+              stage: "plugin",
+              source,
+              suggestion: finding.suggestion
+            });
+          } else {
+            warnings.push({
+              file: finding.file,
+              message: finding.message,
+              source,
+              suggestion: finding.suggestion
+            });
+          }
+        }
+      } catch (runErr) {
+        errors.push({
+          file: ".jay",
+          message: `Project validator "${source}" threw: ${runErr.message}`,
+          stage: "plugin",
+          source
+        });
+      }
+    }
+  }
+  return loadedValidators;
+}
 async function validateJayFiles(options = {}) {
   const projectRoot = options.projectRoot ?? process.cwd();
   const config = loadConfig(projectRoot);
@@ -6924,56 +7047,6 @@ async function validateJayFiles(options = {}) {
       }
     };
   }
-  const robotsTxtPath = path$1.resolve(projectRoot, "public/robots.txt");
-  if (!fs$1.existsSync(robotsTxtPath)) {
-    warnings.push({
-      file: "public/robots.txt",
-      message: "public/robots.txt not found — search engines may crawl pages you don't intend to expose.",
-      suggestion: "Create public/robots.txt with: User-agent: *\nAllow: /\nSitemap: https://your-domain.com/sitemap.xml"
-    });
-  }
-  if (!config.site?.baseUrl) {
-    warnings.push({
-      file: ".jay",
-      message: "site.baseUrl not configured — sitemap.xml will not be generated in production.",
-      suggestion: "Add to .jay config:\n  site:\n    baseUrl: https://your-domain.com"
-    });
-  }
-  if (!config.site?.name) {
-    warnings.push({
-      file: ".jay",
-      message: "site.name not configured — Organization/WebSite JSON-LD and llms.txt will not be emitted, reducing how well search engines and agents understand the site.",
-      suggestion: "Add to .jay config:\n  site:\n    name: Your Site Name\n    logo: /logo.png\n    description: What your site is about"
-    });
-  }
-  const allowNoArd = config.validations?.["allow-no-ard"] === true;
-  const ardResult = await checkArdFiles(projectRoot);
-  if (ardResult.absent) {
-    if (!allowNoArd) {
-      warnings.push({
-        file: "public/.well-known/ard.json",
-        message: "public/.well-known/ard.json not found — agents cannot discover this site’s resources/APIs via Agentic Resource Discovery.",
-        suggestion: "Author public/.well-known/ard.json (ARD v0.91), or suppress with `validations: { allow-no-ard: true }` in .jay if the site has no agent resources to advertise. See developer/seo-guide.md."
-      });
-    }
-  } else {
-    for (const finding of ardResult.findings) {
-      if (finding.severity === "error") {
-        errors.push({
-          file: "public/.well-known/ard.json",
-          message: finding.message,
-          stage: "generate",
-          suggestion: finding.suggestion
-        });
-      } else {
-        warnings.push({
-          file: "public/.well-known/ard.json",
-          message: finding.message,
-          suggestion: finding.suggestion
-        });
-      }
-    }
-  }
   const allowNoErrorPages = config.validations?.["allow-no-error-pages"] === true;
   if (!allowNoErrorPages) {
     const scanResult = await scanRoutes(scanDir, {
@@ -7060,13 +7133,22 @@ async function validateJayFiles(options = {}) {
     projectRoot
   });
   for (const finding of linkFindings) {
-    errors.push({
-      file: finding.file,
-      message: finding.message,
-      stage: "generate",
-      source: "internal-links",
-      suggestion: finding.suggestion
-    });
+    if (finding.severity === "warning") {
+      warnings.push({
+        file: finding.file,
+        message: finding.message,
+        source: "internal-links",
+        suggestion: finding.suggestion
+      });
+    } else {
+      errors.push({
+        file: finding.file,
+        message: finding.message,
+        stage: "generate",
+        source: "internal-links",
+        suggestion: finding.suggestion
+      });
+    }
   }
   if (options.tier2) {
     await runBuildOutputValidation({
@@ -7081,6 +7163,7 @@ async function validateJayFiles(options = {}) {
     });
   }
   const pluginValidators = await runPluginValidators(projectRoot, parsedFiles, errors, warnings);
+  const projectValidators = await runProjectValidators(projectRoot, errors, warnings);
   return {
     valid: errors.length === 0,
     jayHtmlFilesScanned: jayHtmlFiles.length,
@@ -7088,7 +7171,7 @@ async function validateJayFiles(options = {}) {
     errors,
     warnings,
     coverage,
-    pluginValidators,
+    pluginValidators: [...pluginValidators, ...projectValidators],
     designSystemCoverage,
     designSystemReuse
   };
@@ -7127,7 +7210,7 @@ async function runBuildOutputValidation(args) {
       suggestion: "Re-run `jay-stack build` for accurate results."
     });
   }
-  const oracle = buildBuildOracle(loaded.manifest, backendDir);
+  const oracle = await buildBuildOracle(loaded.manifest, backendDir);
   const findings = [];
   findings.push(
     ...checkTemplateLinksAgainstBuild({
@@ -7139,6 +7222,14 @@ async function runBuildOutputValidation(args) {
     })
   );
   findings.push(...checkBuildJsonLd(loaded.manifest));
+  for (const inst of oracle.instances) {
+    findings.push(
+      ...await checkPageCacheFileSizes({
+        cacheAbsPath: inst.cacheAbsPath,
+        routePattern: inst.pattern
+      })
+    );
+  }
   for (const instance of oracle.instances) {
     const slowViewState = await loadSlowViewState(instance.cacheAbsPath);
     findings.push(
@@ -7507,7 +7598,7 @@ async function resolveProductionContext(projectPath, versionOverride) {
   let siteBaseUrl;
   let site;
   try {
-    const jayConfig = YAML.parse(await fs$2.readFile(jayConfigPath, "utf-8"));
+    const jayConfig = YAML.parse(await fs$1$1.readFile(jayConfigPath, "utf-8"));
     pagesBase = jayConfig?.devServer?.pagesBase || pagesBase;
     siteBaseUrl = jayConfig?.site?.baseUrl;
     site = jayConfig?.site;
@@ -7527,7 +7618,7 @@ async function resolveProductionContext(projectPath, versionOverride) {
 async function resolveVersionFromPackageJson(projectRoot) {
   try {
     const pkgJson = JSON.parse(
-      await fs$2.readFile(path__default.join(projectRoot, "package.json"), "utf-8")
+      await fs$1$1.readFile(path__default.join(projectRoot, "package.json"), "utf-8")
     );
     if (pkgJson.version) {
       return pkgJson.version;
@@ -7548,7 +7639,7 @@ async function runBuild(projectPath, options) {
   }
   const ctx = await resolveProductionContext(projectPath, options.version);
   await generateDefinitionFiles(ctx);
-  const { buildVersion } = await import("./index-B5oavmfA.js");
+  const { buildVersion } = await import("@jay-framework/production-build");
   await buildVersion({
     version: ctx.version,
     projectRoot: ctx.resolvedPath,
@@ -7914,22 +8005,22 @@ async function ensureAgentKitDocs(projectRoot, _force, mode) {
     const roleOutputDir = path__default.join(agentKitDir, role);
     let files;
     try {
-      files = (await fs$2.readdir(roleTemplateDir)).filter((f) => f.endsWith(".md"));
+      files = (await fs$1$1.readdir(roleTemplateDir)).filter((f) => f.endsWith(".md"));
     } catch {
       continue;
     }
-    await fs$2.mkdir(roleOutputDir, { recursive: true });
+    await fs$1$1.mkdir(roleOutputDir, { recursive: true });
     for (const filename of files) {
-      await fs$2.copyFile(
+      await fs$1$1.copyFile(
         path__default.join(roleTemplateDir, filename),
         path__default.join(roleOutputDir, filename)
       );
       getLogger().info(chalk.gray(`   Created agent-kit/${role}/${filename}`));
     }
   }
-  const topLevelFiles = (await fs$2.readdir(templateDir)).filter((f) => f.endsWith(".md"));
+  const topLevelFiles = (await fs$1$1.readdir(templateDir)).filter((f) => f.endsWith(".md"));
   for (const filename of topLevelFiles) {
-    await fs$2.copyFile(path__default.join(templateDir, filename), path__default.join(agentKitDir, filename));
+    await fs$1$1.copyFile(path__default.join(templateDir, filename), path__default.join(agentKitDir, filename));
     getLogger().info(chalk.gray(`   Created agent-kit/${filename}`));
   }
   const sharedDirs = ["contracts"];
@@ -7941,15 +8032,15 @@ async function ensureAgentKitDocs(projectRoot, _force, mode) {
   }
 }
 async function copyDirRecursive(src, dest) {
-  await fs$2.mkdir(dest, { recursive: true });
-  const entries = await fs$2.readdir(src, { withFileTypes: true });
+  await fs$1$1.mkdir(dest, { recursive: true });
+  const entries = await fs$1$1.readdir(src, { withFileTypes: true });
   for (const entry of entries) {
     const srcPath = path__default.join(src, entry.name);
     const destPath = path__default.join(dest, entry.name);
     if (entry.isDirectory()) {
       await copyDirRecursive(srcPath, destPath);
     } else if (entry.name.endsWith(".md")) {
-      await fs$2.copyFile(srcPath, destPath);
+      await fs$1$1.copyFile(srcPath, destPath);
     }
   }
 }
@@ -7965,7 +8056,7 @@ async function mergePluginAgentKitGuides(projectRoot, mode) {
       const roleSourceDir = path__default.join(pluginAgentKitDir, role);
       let files;
       try {
-        files = (await fs$2.readdir(roleSourceDir)).filter(
+        files = (await fs$1$1.readdir(roleSourceDir)).filter(
           (f) => f.endsWith(".md") && f !== "INSTRUCTIONS.md"
         );
       } catch {
@@ -7973,13 +8064,13 @@ async function mergePluginAgentKitGuides(projectRoot, mode) {
       }
       if (files.length === 0) continue;
       const roleOutputDir = path__default.join(agentKitDir, role);
-      await fs$2.mkdir(roleOutputDir, { recursive: true });
+      await fs$1$1.mkdir(roleOutputDir, { recursive: true });
       for (const filename of files) {
         const sourcePath = path__default.join(roleSourceDir, filename);
-        await fs$2.copyFile(sourcePath, path__default.join(roleOutputDir, filename));
+        await fs$1$1.copyFile(sourcePath, path__default.join(roleOutputDir, filename));
         let description = "";
         try {
-          const content = await fs$2.readFile(sourcePath, "utf-8");
+          const content = await fs$1$1.readFile(sourcePath, "utf-8");
           const lines = content.split("\n");
           let pastHeading = false;
           for (const line of lines) {
@@ -8018,7 +8109,7 @@ async function mergePluginAgentKitGuides(projectRoot, mode) {
       lines.push(`| [${filename}](${filename}) | ${pluginName} | ${description} |`);
     }
     lines.push("");
-    await fs$2.appendFile(instructionsPath, lines.join("\n"));
+    await fs$1$1.appendFile(instructionsPath, lines.join("\n"));
   }
 }
 async function generatePluginAgentKit(projectRoot, options, initErrors, viteServer) {