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

package/dist/index.d.ts

@@ -1,6 +1,15 @@
 import { LogLevel } from '@jay-framework/logger';
 export { MaterializeContractsOptions, MaterializeResult, PluginContractEntry, PluginsIndex, PluginsIndexEntry, listContracts, materializeContracts } from '@jay-framework/stack-server-build';
 
+/**
+ * `express.static` `setHeaders` callback that mirrors production for agent-readiness resources
+ * (DL#217): everything under `/.well-known/` is served CORS-open, with `SKILL.md` as
+ * `text/markdown` and skill archives (`.gz`) as `application/gzip`. Exported so the dev-serving
+ * test guards the real behavior rather than a copy.
+ */
+declare function setWellKnownHeaders(res: {
+    setHeader(name: string, value: string): void;
+}, filePath: string): void;
 interface StartDevServerOptions {
     projectPath?: string;
     testMode?: boolean;
@@ -19,10 +28,34 @@ interface JayConfig {
     };
     site?: {
         baseUrl?: string;
+        /** Site/organization name — drives Organization + WebSite JSON-LD (DL#213). */
+        name?: string;
+        /** Logo URL (absolute or baseUrl-relative) for the Organization JSON-LD (DL#213). */
+        logo?: string;
+        /** Short site description for the Organization JSON-LD (DL#213). */
+        description?: string;
+        /** Social/profile URLs for the Organization `sameAs` (DL#213). */
+        sameAs?: string[];
+    };
+    /** Project-wide validation suppressions for project-level concerns (DL#214). */
+    validations?: {
+        /**
+         * Suppress the `/.well-known/ard.json` absence nudge — for sites with no agent-callable
+         * resources/APIs to advertise. Lives in `.jay` (not a page's `application/jay-validations`
+         * script) because it governs a single project-level file, not any page's markup.
+         */
+        'allow-no-ard'?: boolean;
+        /**
+         * Suppress the minimum-error-pages nudge — for sites that intentionally ship no branded
+         * `404`/`5xx` pages and accept the plain-text fallback. Lives in `.jay` (not a page's
+         * `application/jay-validations` script) because it governs the project's `pages/` tree as a
+         * whole, not any single page's markup (DL#218).
+         */
+        'allow-no-error-pages'?: boolean;
     };
 }
 declare function loadConfig(projectRoot?: string): JayConfig;
 declare function getConfigWithDefaults(config: JayConfig): Required<Pick<JayConfig, 'devServer'>> & Pick<JayConfig, 'site'>;
 declare function updateConfig(updates: Partial<JayConfig>): void;
 
-export { type JayConfig, type StartDevServerOptions, getConfigWithDefaults, loadConfig, startDevServer, updateConfig };
+export { type JayConfig, type StartDevServerOptions, getConfigWithDefaults, loadConfig, setWellKnownHeaders, startDevServer, updateConfig };

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}`);
@@ -199,6 +200,13 @@ const generateContractDefinitionFiles$1 = /* @__PURE__ */ Object.freeze(/* @__PU
   __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 +222,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 +240,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 +308,7 @@ async function startDevServer(options = {}) {
       }, options.timeout * 1e3);
     }
   }
+  app.use(errorPageHandler(404));
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
 }
@@ -3004,6 +3015,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 +3139,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 +3994,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 +4870,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 = [];
   }
@@ -5005,6 +5086,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 +5332,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 +5649,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 +6587,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 +6659,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 +6779,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 +6909,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 +6942,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 +7141,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 +7160,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 +7407,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) {
@@ -7117,10 +7514,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 +7529,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) {
@@ -7158,7 +7558,7 @@ async function runBuild(projectPath, options) {
   }
   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,7 +7567,8 @@ 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) {
@@ -7234,7 +7635,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 +8688,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 +8759,7 @@ export {
   listContracts,
   loadConfig,
   materializeContracts,
+  setWellKnownHeaders,
   startDevServer,
   updateConfig
 };