@jay-framework/jay-stack-cli 0.25.1 → 0.25.3

package/dist/index.js

@@ -50,7 +50,8 @@ function loadConfig(projectRoot) {
         ...DEFAULT_CONFIG.devServer,
         ...userConfig.devServer
       },
-      site: userConfig.site
+      site: userConfig.site,
+      validations: userConfig.validations
     };
   } catch (error) {
     getLogger().warn(`Failed to parse .jay YAML config file, using defaults: ${error}`);
@@ -134,10 +135,6 @@ async function generatePageDefinitionFiles(jayHtmlPaths, tsConfigPath, projectRo
     }
   }
 }
-const generatePageDefinitionFiles$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
-  __proto__: null,
-  generatePageDefinitionFiles
-}, Symbol.toStringTag, { value: "Module" }));
 const IGNORED_DIRS = /* @__PURE__ */ new Set(["node_modules", "build", "dist", ".git", ".cache"]);
 async function generateContractDefinitionFiles(root) {
   const contractFiles = await collectContractFiles(root);
@@ -195,10 +192,13 @@ async function collectContractFiles(root) {
   await walk(root);
   return results;
 }
-const generateContractDefinitionFiles$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
-  __proto__: null,
-  generateContractDefinitionFiles
-}, Symbol.toStringTag, { value: "Module" }));
+function setWellKnownHeaders(res, filePath) {
+  if (filePath.includes(`${path$1.sep}.well-known${path$1.sep}`)) {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    if (filePath.endsWith(".md")) res.setHeader("Content-Type", "text/markdown; charset=utf-8");
+    if (filePath.endsWith(".gz")) res.setHeader("Content-Type", "application/gzip");
+  }
+}
 async function startDevServer(options = {}) {
   const projectPath = options.projectPath || process.cwd();
   if (projectPath !== process.cwd()) {
@@ -214,7 +214,7 @@ async function startDevServer(options = {}) {
   const httpServer = http.createServer(app);
   const devServerPort = await getPort({ port: resolvedConfig.devServer.portRange });
   const log = getLogger();
-  const { server, viteServer, routes, service } = await mkDevServer({
+  const { server, viteServer, routes, service, errorPageHandler } = await mkDevServer({
     pagesRootFolder: path$1.resolve(resolvedConfig.devServer.pagesBase),
     projectRootFolder: process.cwd(),
     publicBaseUrlPath: "/",
@@ -232,18 +232,20 @@ async function startDevServer(options = {}) {
     });
   }
   if (fs$1.existsSync(publicPath)) {
-    app.use(express.static(publicPath));
+    app.use(express.static(publicPath, { dotfiles: "allow", setHeaders: setWellKnownHeaders }));
   } else {
     log.important(`⚠️  Public folder not found: ${resolvedConfig.devServer.publicFolder}`);
   }
+  const pageRouter = express.Router();
   routes.forEach((route) => {
-    app.get(route.path, route.handler);
+    pageRouter.get(route.path, route.handler);
   });
   service.attachRouteRegistrar((added) => {
     added.forEach((route) => {
-      app.get(route.path, route.handler);
+      pageRouter.get(route.path, route.handler);
     });
   });
+  app.use(pageRouter);
   void (async () => {
     await generatePageDefinitionFiles(
       routes.map((route) => route.fsRoute.jayHtmlPath),
@@ -298,6 +300,7 @@ async function startDevServer(options = {}) {
       }, options.timeout * 1e3);
     }
   }
+  app.use(errorPageHandler(404));
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
 }
@@ -3004,6 +3007,61 @@ async function validateAiditorSettings(context, result) {
     });
   }
 }
+async function compileValidateRouteJayHtml(absoluteJayHtmlPath, pluginRoot) {
+  const content = fs$1.readFileSync(absoluteJayHtmlPath, "utf-8");
+  const dirname = path$1.dirname(absoluteJayHtmlPath);
+  const filename = path$1.basename(absoluteJayHtmlPath, JAY_EXTENSION$1);
+  const errors = [];
+  try {
+    const parsedFile = await parseJayFile(
+      content,
+      filename,
+      dirname,
+      {},
+      JAY_IMPORT_RESOLVER,
+      pluginRoot
+    );
+    for (const validation of parsedFile.validations) {
+      errors.push(validation);
+    }
+    if (!parsedFile.val || parsedFile.validations.length > 0) {
+      return errors;
+    }
+    const generatedFile = generateElementFile(parsedFile.val, RuntimeMode$1.MainTrusted);
+    for (const validation of generatedFile.validations) {
+      errors.push(validation);
+    }
+    const serverElementFile = generateServerElementFile(parsedFile.val);
+    for (const validation of serverElementFile.validations) {
+      errors.push(`[SSR] ${validation}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    errors.push(message);
+  }
+  return errors;
+}
+async function validateRouteJayHtmlTemplates(context, result) {
+  const routes = context.manifest.routes;
+  if (!routes || !Array.isArray(routes)) return;
+  for (const route of routes) {
+    if (!route.jayHtml) continue;
+    const absolutePath = path$1.resolve(context.pluginPath, route.jayHtml);
+    if (!fs$1.existsSync(absolutePath)) {
+      continue;
+    }
+    const compileErrors = await compileValidateRouteJayHtml(absolutePath, context.pluginPath);
+    const relPath = path$1.relative(context.pluginPath, absolutePath);
+    for (const message of compileErrors) {
+      result.errors.push({
+        type: "jay-html-compile",
+        message: `Route "${route.path}" jayHtml failed to compile: ${message}`,
+        location: relPath,
+        suggestion: "Fix the template syntax or run `jay-stack validate -p <dir>` on the source page during development. See agent-kit/designer/jay-html-template-syntax.md"
+      });
+    }
+  }
+}
 async function validatePlugin(options = {}) {
   const pluginPath = options.pluginPath || process.cwd();
   if (options.local) {
@@ -3073,6 +3131,7 @@ async function validatePluginPackage(pluginPath, options) {
   await validateAddMenuCatalog(context, result);
   await validateAiditorSettings(context, result);
   validateNoCompilerLeak(context, result);
+  await validateRouteJayHtmlTemplates(context, result);
   result.valid = result.errors.length === 0;
   return result;
 }
@@ -3927,6 +3986,20 @@ async function validatePackageJson(context, result) {
         suggestion: 'Add "./plugin.yaml": "./plugin.yaml" to exports field'
       });
     }
+    if (context.manifest.commands) {
+      for (const cmd of context.manifest.commands) {
+        if (!cmd.command) continue;
+        const exportKey = `./${cmd.command}`;
+        if (!packageJson.exports || !packageJson.exports[exportKey]) {
+          result.errors.push({
+            type: "export-mismatch",
+            message: `command metadata file "${cmd.command}" not exported in package.json (required for plugin resolution)`,
+            location: packageJsonPath,
+            suggestion: `Add "${exportKey}": "${exportKey}" to exports field`
+          });
+        }
+      }
+    }
     const agentKitDir = path$1.join(context.pluginPath, "agent-kit");
     if (fs$1.existsSync(agentKitDir) && fs$1.statSync(agentKitDir).isDirectory()) {
       const filesArray = packageJson.files;
@@ -4789,10 +4862,10 @@ function routeToRegex(route) {
 async function buildRouteOracle(pagesBase) {
   let routes = [];
   try {
-    routes = await scanRoutes(pagesBase, {
+    ({ routes } = await scanRoutes(pagesBase, {
       jayHtmlFilename: "page.jay-html",
       compFilename: "page.ts"
-    });
+    }));
   } catch {
     routes = [];
   }
@@ -4832,6 +4905,10 @@ async function collectPublicAssets(publicFolder) {
   await walk(publicFolder, "");
   return assets;
 }
+function openingTag(el) {
+  const attrs = el.rawAttrs?.replace(/\s+jay-[\w-]+(="[^"]*"|='[^']*')?/g, "").replace(/\s+/g, " ").trim();
+  return attrs ? `<${el.rawTagName} ${attrs}>` : `<${el.rawTagName}>`;
+}
 function originOf(baseUrl) {
   try {
     return new URL(baseUrl).origin;
@@ -4871,10 +4948,11 @@ function checkInternalLinks(options) {
       if (raw === void 0 || raw === null) continue;
       const verdict = classifyHref(raw, baseUrl);
       if (verdict.kind === "skip") continue;
+      const tag = openingTag(anchor);
       if (verdict.kind === "degenerate") {
         findings.push({
           file: relativePath,
-          message: `Anchor has a placeholder href "${raw}" — it links nowhere and ships as a dead link.`,
+          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;
@@ -4883,7 +4961,7 @@ function checkInternalLinks(options) {
       if (ownUrl !== void 0 && target === ownUrl) {
         findings.push({
           file: relativePath,
-          message: `Link points to the page's own route "${target}" — a self-link goes nowhere.`,
+          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.`
         });
         continue;
@@ -4893,7 +4971,7 @@ function checkInternalLinks(options) {
       if (oracle.dynamicMatchers.some((re) => re.test(target))) continue;
       findings.push({
         file: relativePath,
-        message: `Broken internal link "${raw}" — no page or public asset produces the URL "${target}".`,
+        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}.`
       });
     }
@@ -5005,6 +5083,89 @@ async function loadSlowViewState(cacheAbsPath) {
     return {};
   }
 }
+async function loadCarryForward(cacheAbsPath) {
+  try {
+    const cache = JSON.parse(await promises.readFile(cacheAbsPath, "utf8"));
+    return cache.carryForward ?? {};
+  } catch {
+    return {};
+  }
+}
+function jsonLdBodyError(body) {
+  const text = body?.trim();
+  if (!text) return "Empty JSON-LD block — add structured data or remove the tag.";
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (e2) {
+    return `Invalid JSON: ${e2.message}`;
+  }
+  const objs = Array.isArray(parsed) ? parsed : [parsed];
+  for (const obj of objs) {
+    if (!obj || typeof obj !== "object") {
+      return "JSON-LD must be an object (or array of objects) with @context and @type.";
+    }
+    if (!("@context" in obj) || !("@type" in obj)) {
+      return "JSON-LD is missing @context or @type.";
+    }
+  }
+  return null;
+}
+function isLdJsonHeadTag(tag) {
+  return tag?.tag?.toLowerCase?.() === "script" && tag?.attrs?.type === "application/ld+json";
+}
+function checkBuildJsonLd(manifest) {
+  const findings = [];
+  for (const tag of manifest.siteHeadTags ?? []) {
+    if (!isLdJsonHeadTag(tag)) continue;
+    const err = jsonLdBodyError(tag.children);
+    if (err) {
+      findings.push({
+        file: ".jay (site.*)",
+        message: `Site JSON-LD: ${err}`,
+        severity: "error",
+        source: "build-output"
+      });
+    }
+  }
+  for (const route of manifest.routes) {
+    for (const script of route.scripts ?? []) {
+      if (script.attributes?.type !== "application/ld+json") continue;
+      const err = jsonLdBodyError(script.inline);
+      if (err) {
+        findings.push({
+          file: route.pattern,
+          message: `Template JSON-LD: ${err}`,
+          severity: "error",
+          source: "build-output"
+        });
+      }
+    }
+  }
+  return findings;
+}
+function checkInstanceJsonLd(args) {
+  const { instanceUrl, carryForward } = args;
+  const findings = [];
+  const slowHeadTags = carryForward?.__slowHeadTags;
+  if (!Array.isArray(slowHeadTags)) return findings;
+  for (const source of slowHeadTags) {
+    if (!Array.isArray(source)) continue;
+    for (const tag of source) {
+      if (!isLdJsonHeadTag(tag)) continue;
+      const err = jsonLdBodyError(tag?.children);
+      if (err) {
+        findings.push({
+          file: instanceUrl,
+          message: `Component JSON-LD: ${err}`,
+          severity: "error",
+          source: "build-output"
+        });
+      }
+    }
+  }
+  return findings;
+}
 function checkTemplateLinksAgainstBuild(args) {
   const { parsedFiles, buildUrls, assetUrls, dynamicMatchers, baseUrl } = args;
   const findings = [];
@@ -5168,6 +5329,122 @@ 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}`);
 }
@@ -5369,6 +5646,17 @@ function resolveContractTag(contract, tagPath) {
   }
   return void 0;
 }
+function checkJsonLdScripts(jayHtml) {
+  const errors = [];
+  for (const script of jayHtml.scripts ?? []) {
+    if (script.attributes?.type !== "application/ld+json") continue;
+    const err = jsonLdBodyError(script.inline);
+    if (err) {
+      errors.push(`<script type="application/ld+json">: ${err} See designer/seo-guide.md.`);
+    }
+  }
+  return errors;
+}
 function checkRefElementTypes(jayHtml, file) {
   const imports = jayHtml.headlessImports;
   const keyMap = /* @__PURE__ */ new Map();
@@ -6296,14 +6584,12 @@ async function validateJayFiles(options = {}) {
   const reuseByTemplate = /* @__PURE__ */ new Map();
   const cataloguedContractFiles = /* @__PURE__ */ new Set();
   const pageJayHtmlFiles = await findJayFiles(scanDir);
-  const componentJayHtmlFiles = await findJayFiles(componentsDir).catch(() => []);
+  const componentJayHtmlFiles = options.compileOnly ? [] : await findJayFiles(componentsDir).catch(() => []);
   const jayHtmlFiles = [...pageJayHtmlFiles, ...componentJayHtmlFiles];
   const componentJayHtmlFileSet = new Set(componentJayHtmlFiles);
-  const componentContractFiles = await findContractFiles(componentsDir).catch(
-    () => []
-  );
+  const componentContractFiles = options.compileOnly ? [] : await findContractFiles(componentsDir).catch(() => []);
   for (const cf of componentContractFiles) cataloguedContractFiles.add(cf);
-  const contractFiles = [...await findContractFiles(scanDir), ...componentContractFiles];
+  const contractFiles = options.compileOnly ? [] : [...await findContractFiles(scanDir), ...componentContractFiles];
   const contractNameByFile = /* @__PURE__ */ new Map();
   if (options.verbose) {
     getLogger().info(chalk.gray(`Scanning directory: ${scanDir}`));
@@ -6370,6 +6656,35 @@ async function validateJayFiles(options = {}) {
         continue;
       }
       parsedFiles.push({ relativePath, parsed: parsedFile.val });
+      if (options.compileOnly) {
+        const generatedFile2 = generateElementFile(
+          parsedFile.val,
+          RuntimeMode$1.MainTrusted,
+          GenerateTarget.jay
+        );
+        for (const validation of generatedFile2.validations) {
+          errors.push({
+            file: relativePath,
+            message: validation,
+            stage: "generate"
+          });
+        }
+        const serverElementFile2 = generateServerElementFile(parsedFile.val);
+        for (const validation of serverElementFile2.validations) {
+          errors.push({
+            file: relativePath,
+            message: `[SSR] ${validation}`,
+            stage: "generate"
+          });
+        }
+        if (options.verbose) {
+          const failed = generatedFile2.validations.length > 0 || serverElementFile2.validations.length > 0;
+          getLogger().info(
+            failed ? chalk.red(`❌ ${relativePath}`) : chalk.green(`✓ ${relativePath}`)
+          );
+        }
+        continue;
+      }
       if (content.includes("application/jay-params")) {
         errors.push({
           file: relativePath,
@@ -6461,6 +6776,9 @@ async function validateJayFiles(options = {}) {
           suggestion: finding.suggestion
         });
       }
+      for (const message of checkJsonLdScripts(parsedFile.val)) {
+        errors.push({ file: relativePath, message, stage: "generate" });
+      }
       regionsSeen += collectRegionElements(parsedFile.val.body).length;
       templateImportsSeen += parsedFile.val.headlessImports.filter(
         (imp) => imp.template
@@ -6588,6 +6906,24 @@ async function validateJayFiles(options = {}) {
       }
     }
   }
+  if (options.compileOnly) {
+    return {
+      valid: errors.length === 0,
+      jayHtmlFilesScanned: jayHtmlFiles.length,
+      contractFilesScanned: contractFiles.length,
+      errors,
+      warnings,
+      coverage,
+      pluginValidators: [],
+      designSystemCoverage,
+      designSystemReuse: {
+        perTemplate: {},
+        catalogued: 0,
+        reusedMoreThanOnce: 0,
+        reusedOfCatalogued: 0
+      }
+    };
+  }
   const robotsTxtPath = path$1.resolve(projectRoot, "public/robots.txt");
   if (!fs$1.existsSync(robotsTxtPath)) {
     warnings.push({
@@ -6603,6 +6939,60 @@ async function validateJayFiles(options = {}) {
       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, {
+      jayHtmlFilename: "page.jay-html",
+      compFilename: "page.ts"
+    });
+    const errorPages = scanResult.errorPages ?? [];
+    const tokens = new Set(errorPages.map((ep) => ep.token));
+    const missing = [];
+    if (!tokens.has("404") && !tokens.has("4xx")) missing.push("404");
+    if (!tokens.has("5xx")) missing.push("5xx");
+    if (missing.length > 0) {
+      warnings.push({
+        file: "src/pages",
+        message: `No branded error page for ${missing.join(" and ")} — these responses fall back to plain text instead of your site's layout.`,
+        suggestion: "Add pages/404/page.jay-html and pages/5xx/page.jay-html importing the `error` headless contract, or suppress with `validations: { allow-no-error-pages: true }` in .jay. See designer/error-pages-guide.md."
+      });
+    }
+  }
   const allowNoTemplate = /* @__PURE__ */ new Set();
   let allowNoDesignSystem = false;
   for (const { parsed } of parsedFiles) {
@@ -6748,6 +7138,7 @@ async function runBuildOutputValidation(args) {
       baseUrl
     })
   );
+  findings.push(...checkBuildJsonLd(loaded.manifest));
   for (const instance of oracle.instances) {
     const slowViewState = await loadSlowViewState(instance.cacheAbsPath);
     findings.push(
@@ -6766,6 +7157,8 @@ async function runBuildOutputValidation(args) {
         slowViewState
       })
     );
+    const carryForward = await loadCarryForward(instance.cacheAbsPath);
+    findings.push(...checkInstanceJsonLd({ instanceUrl: instance.url, carryForward }));
   }
   for (const finding of findings) {
     if (finding.severity === "error") {
@@ -7011,7 +7404,8 @@ async function runValidate(scanPath, options) {
     verbose: options.verbose,
     json: options.json,
     tier2: options.tier2,
-    buildDir: options.buildDir
+    buildDir: options.buildDir,
+    compileOnly: options.compileOnly
   });
   printJayValidationResult(result, options);
   if (!result.valid) {
@@ -7092,12 +7486,6 @@ function printPluginValidationResult(result, verbose) {
     logger.important(chalk.red(`${result.errors.length} errors found.`));
   }
 }
-const runValidate$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
-  __proto__: null,
-  runValidate,
-  runValidatePlugin,
-  surfaceValidationIssues
-}, Symbol.toStringTag, { value: "Module" }));
 async function runDev(projectPath, options) {
   const logLevel = options.quiet ? "silent" : options.verbose ? "verbose" : "info";
   setDevLogger(createDevLogger(logLevel));
@@ -7117,10 +7505,12 @@ async function resolveProductionContext(projectPath, versionOverride) {
   const jayConfigPath = path__default.join(resolvedPath, ".jay");
   let pagesBase = "./src/pages";
   let siteBaseUrl;
+  let site;
   try {
     const jayConfig = YAML.parse(await fs$2.readFile(jayConfigPath, "utf-8"));
     pagesBase = jayConfig?.devServer?.pagesBase || pagesBase;
     siteBaseUrl = jayConfig?.site?.baseUrl;
+    site = jayConfig?.site;
   } catch {
   }
   const version = versionOverride || await resolveVersionFromPackageJson(resolvedPath);
@@ -7130,7 +7520,8 @@ async function resolveProductionContext(projectPath, versionOverride) {
     buildRoot: path__default.join(resolvedPath, "build"),
     version,
     tsConfigFilePath: path__default.join(resolvedPath, "tsconfig.json"),
-    siteBaseUrl
+    siteBaseUrl,
+    site
   };
 }
 async function resolveVersionFromPackageJson(projectRoot) {
@@ -7151,14 +7542,13 @@ function initLogger(verbose) {
 }
 async function runBuild(projectPath, options) {
   initLogger(options.verbose);
-  const { surfaceValidationIssues: surfaceValidationIssues2 } = await Promise.resolve().then(() => runValidate$1);
-  const valid = await surfaceValidationIssues2(projectPath, { verbose: options.verbose });
+  const valid = await surfaceValidationIssues(projectPath, { verbose: options.verbose });
   if (!valid) {
     process.exit(1);
   }
   const ctx = await resolveProductionContext(projectPath, options.version);
   await generateDefinitionFiles(ctx);
-  const { buildVersion } = await import("./index-BQbkAEhi.js");
+  const { buildVersion } = await import("./index-B5oavmfA.js");
   await buildVersion({
     version: ctx.version,
     projectRoot: ctx.resolvedPath,
@@ -7167,20 +7557,19 @@ async function runBuild(projectPath, options) {
     concurrency: 4,
     tsConfigFilePath: ctx.tsConfigFilePath,
     minify: options.minify,
-    siteBaseUrl: ctx.siteBaseUrl
+    siteBaseUrl: ctx.siteBaseUrl,
+    site: ctx.site
   });
 }
 async function generateDefinitionFiles(ctx) {
   const { glob: glob2 } = await import("glob");
-  const { generatePageDefinitionFiles: generatePageDefinitionFiles2 } = await Promise.resolve().then(() => generatePageDefinitionFiles$1);
-  const { generateContractDefinitionFiles: generateContractDefinitionFiles2 } = await Promise.resolve().then(() => generateContractDefinitionFiles$1);
   const jayHtmlPaths = await glob2("**/page.jay-html", {
     cwd: ctx.pagesRoot,
     absolute: true,
     ignore: ["**/node_modules/**", "**/build/**", "**/dist/**"]
   });
-  await generatePageDefinitionFiles2(jayHtmlPaths, ctx.tsConfigFilePath, ctx.resolvedPath);
-  await generateContractDefinitionFiles2(path__default.resolve(ctx.resolvedPath, "src"));
+  await generatePageDefinitionFiles(jayHtmlPaths, ctx.tsConfigFilePath, ctx.resolvedPath);
+  await generateContractDefinitionFiles(path__default.resolve(ctx.resolvedPath, "src"));
 }
 async function runServe(projectPath, options) {
   initLogger(options.verbose);
@@ -7234,7 +7623,8 @@ async function runRebuild(projectPath, options) {
     version: ctx.version,
     target,
     tsConfigFilePath: ctx.tsConfigFilePath,
-    siteBaseUrl: ctx.siteBaseUrl
+    siteBaseUrl: ctx.siteBaseUrl,
+    site: ctx.site
   });
   if (result.errors.length > 0) {
     for (const err of result.errors) {
@@ -8286,9 +8676,16 @@ program.command("validate").description("Validate all .jay-html and .jay-contrac
 ).addOption(new Option("--t2", "Alias for --tier-2").hideHelp()).option(
   "--build-dir <dir>",
   "Build backend dir or build root for Tier 2 (default: highest build/v*)"
+).option(
+  "--compile-only",
+  "Parse and compile .jay-html only (no project rules — for plugin route source checks)"
 ).action(async (options) => {
   try {
-    await runValidate(options.path, { ...options, tier2: options.tier2 || options.t2 });
+    await runValidate(options.path, {
+      ...options,
+      tier2: options.tier2 || options.t2,
+      compileOnly: options.compileOnly
+    });
   } catch (error) {
     if (options.json) {
       getLogger().important(
@@ -8350,6 +8747,7 @@ export {
   listContracts,
   loadConfig,
   materializeContracts,
+  setWellKnownHeaders,
   startDevServer,
   updateConfig
 };