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

package/dist/index.js

@@ -12,7 +12,7 @@ import { checkValidationErrors, JAY_CONTRACT_EXTENSION as JAY_CONTRACT_EXTENSION
 import fs$2 from "node:fs/promises";
 import * as path from "node:path";
 import path__default from "node:path";
-import { scanPlugins, sortPluginsByDependencies, getServiceRegistry, actionRegistry, resolveServices, ActionRegistry, discoverPluginsWithInit, executePluginServerInits, runInitCallbacks, registerService } from "@jay-framework/stack-server-runtime";
+import { scanPlugins, sortPluginsByDependencies, getServiceRegistry, actionRegistry, resolveServices, headMetaToHeadTags, ActionRegistry, discoverPluginsWithInit, executePluginServerInits, runInitCallbacks, registerService } from "@jay-framework/stack-server-runtime";
 import { createRequire } from "module";
 import jsBeautify from "js-beautify";
 import "node:crypto";
@@ -21,10 +21,11 @@ import fs__default from "node:fs";
 import { createRequire as createRequire$1 } from "node:module";
 import { isJayAction, isJayStreamAction, isJayCliCommand, CONSOLE_CONTEXT } from "@jay-framework/fullstack-component";
 import { parse, NodeType, HTMLElement } from "node-html-parser";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import chalk from "chalk";
 import { glob } from "glob";
 import postcss from "postcss";
+import { scanRoutes, JayRouteParamType } from "@jay-framework/stack-route-scanner";
 import { fileURLToPath } from "node:url";
 import { select, confirm, input } from "@inquirer/prompts";
 const DEFAULT_CONFIG = {
@@ -4253,11 +4254,10 @@ function firstColon(decl) {
 }
 function diffBodies(sourceParent, regionParent) {
   const out = [];
-  const ignoreClass = isRegionTag(regionParent) ? readAttr(regionParent, "ref") : void 0;
-  diffChildren([], sourceParent, regionParent, ignoreClass, out);
+  diffChildren([], sourceParent, regionParent, out);
   return out;
 }
-function diffChildren(parentPath, sParent, rParent, ignoreClass, out) {
+function diffChildren(parentPath, sParent, rParent, out) {
   const rSup = isElement(rParent) ? parseOverride(rParent) : NO_SUPPRESSION;
   const sSup = isElement(sParent) ? parseContent(sParent) : NO_SUPPRESSION;
   const sup = unionSuppression(rSup, sSup);
@@ -4280,24 +4280,23 @@ function diffChildren(parentPath, sParent, rParent, ignoreClass, out) {
     if (rc.nodeType !== NodeType.ELEMENT_NODE) continue;
     const re = rc;
     if (isRegionTag(re)) continue;
-    const childIgnoreClass = parentPath.length === 0 ? ignoreClass : void 0;
-    diffElement([...parentPath, i], s2[i], re, childIgnoreClass, out);
+    diffElement([...parentPath, i], s2[i], re, out);
   }
 }
-function diffElement(path2, se, re, ignoreClass, out) {
+function diffElement(path2, se, re, out) {
   const sup = unionSuppression(parseOverride(re), parseContent(se));
   if (sup.all) return;
-  compareAttributes(path2, se, re, sup, ignoreClass, out);
+  compareAttributes(path2, se, re, sup, out);
   compareStyle(path2, se, re, sup, out);
-  diffChildren(path2, se, re, void 0, out);
+  diffChildren(path2, se, re, out);
 }
-function compareAttributes(path2, se, re, sup, ignoreClass, out) {
+function compareAttributes(path2, se, re, sup, out) {
   const sm = attrMap(se);
   const rm = attrMap(re);
   const names = [.../* @__PURE__ */ new Set([...sm.keys(), ...rm.keys()])].sort();
   for (const name of names) {
-    const sv = name === "class" ? stripClassToken(sm.get(name), ignoreClass) : sm.get(name);
-    const rv = name === "class" ? stripClassToken(rm.get(name), ignoreClass) : rm.get(name);
+    const sv = sm.get(name);
+    const rv = rm.get(name);
     const change = scalarChange(sv, rv, (a, b) => normalizeExpr(a) === normalizeExpr(b));
     if (!change) continue;
     const facet = { kind: "attribute", path: path2, element: tagOf(re), name };
@@ -4319,11 +4318,6 @@ function compareStyle(path2, se, re, sup, out) {
       out.push({ facet, change, sourceValue: sv, regionValue: rv });
   }
 }
-function stripClassToken(value, token) {
-  if (value === void 0 || !token) return value;
-  const kept = value.split(/\s+/).filter((t) => t && t !== token);
-  return kept.length ? kept.join(" ") : void 0;
-}
 function scalarChange(sv, rv, equal) {
   if (sv === void 0 && rv === void 0) return void 0;
   if (sv === void 0) return "added";
@@ -4541,7 +4535,7 @@ function coalesceCss(contributions) {
     (g) => g.selectors.length > 0 ? scopeWrap(g.css, g.selectors.join(", "), g.to) : g.css
   ).join("\n\n");
 }
-function fillRegions(container, stack, opts, errors, cssBlocks, parentScoped = false) {
+function fillRegions(container, stack, opts, errors, cssBlocks) {
   for (const region of directRegions(container)) {
     const name = contractName(region);
     const templatePath = opts.resolveTemplate(name);
@@ -4559,15 +4553,11 @@ function fillRegions(container, stack, opts, errors, cssBlocks, parentScoped = f
       );
       continue;
     }
-    const existing = region.innerHTML;
-    const filled = opts.preserveOverrides ? mergeOverrides(template.body, existing) : template.body;
+    const filled = opts.preserveOverrides ? mergeOverrides(template.body, region.innerHTML) : template.body;
     region.set_content(filled);
-    const ref = readAttr(region, "ref");
-    let scoped = false;
     if (template.css) {
       const selector = (opts.scopeSelector ?? defaultScopeSelector)(region);
       if (selector) {
-        scoped = true;
         const to = [
           ...new Set(
             directRegions(region).filter((c) => opts.resolveTemplate(contractName(c)) !== null).map((c) => readAttr(c, "ref")).filter((r) => !!r).map((r) => `.${r}`)
@@ -4576,15 +4566,14 @@ function fillRegions(container, stack, opts, errors, cssBlocks, parentScoped = f
         cssBlocks.push({
           key: `${templatePath}\0${[...to].sort().join(",")}`,
           selector,
-          css: scopeReadyCss(template.body, template.css),
+          css: template.css,
           to
         });
       } else {
         cssBlocks.push({ key: templatePath, selector: null, css: template.css });
       }
     }
-    if (ref && (scoped || parentScoped)) stampScopeAnchor(region, ref);
-    fillRegions(region, [...stack, templatePath], opts, errors, cssBlocks, scoped);
+    fillRegions(region, [...stack, templatePath], opts, errors, cssBlocks);
   }
 }
 function directRegions(container) {
@@ -4612,39 +4601,6 @@ function scopeWrap(css, selector, to) {
 ${css}
 }`;
 }
-function rootClassesOf(templateBody) {
-  const classes = /* @__PURE__ */ new Set();
-  for (const child of parse(templateBody).childNodes) {
-    if (child instanceof HTMLElement) {
-      for (const c of child.classList.values()) classes.add(c);
-    }
-  }
-  return classes;
-}
-function scopeReadyCss(templateBody, css) {
-  const rootClasses = rootClassesOf(templateBody);
-  if (rootClasses.size === 0) return css;
-  try {
-    const root = postcss.parse(css);
-    root.walkRules((rule) => {
-      rule.selectors = rule.selectors.map((sel) => rewriteRootSelector(sel, rootClasses));
-    });
-    return root.toString();
-  } catch {
-    return css;
-  }
-}
-function rewriteRootSelector(selector, rootClasses) {
-  return selector.replace(
-    /\.([A-Za-z0-9_-]+)/g,
-    (match, name) => rootClasses.has(name) ? ":scope" : match
-  );
-}
-function stampScopeAnchor(region, className) {
-  for (const child of region.childNodes) {
-    if (child instanceof HTMLElement) child.classList.add(className);
-  }
-}
 function mergeOverrides(templateBody, existingBody) {
   const tRoot = parse(templateBody);
   const eRoot = parse(existingBody);
@@ -4790,6 +4746,428 @@ function scopeInnerBody(block) {
 function normalizeCssBody(body) {
   return body.replace(/\s+/g, " ").replace(/\s*([{}:;,])\s*/g, "$1").replace(/;}/g, "}").trim();
 }
+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';
+function normalizePath(p) {
+  let s2 = p.split("#")[0].split("?")[0];
+  s2 = s2.replace(/\/{2,}/g, "/");
+  if (s2.length > 1) s2 = s2.replace(/\/+$/, "");
+  return s2 === "" ? "/" : s2;
+}
+function escapeRegExp(s2) {
+  return s2.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function routeToConcreteUrl(route) {
+  const parts = [];
+  for (const seg of route.segments) {
+    if (typeof seg === "string") {
+      parts.push(seg);
+    } else {
+      const v = route.inferredParams?.[seg.name];
+      if (v === void 0) return null;
+      parts.push(v);
+    }
+  }
+  return normalizePath("/" + parts.join("/"));
+}
+function routeToRegex(route) {
+  let pattern = "";
+  for (const seg of route.segments) {
+    if (typeof seg === "string") {
+      pattern += "/" + escapeRegExp(seg);
+    } else if (seg.type === JayRouteParamType.optional) {
+      pattern += "(?:/[^/]+)?";
+    } else if (seg.type === JayRouteParamType.catchAll) {
+      pattern += "(?:/[^/]+)+";
+    } else {
+      pattern += "/[^/]+";
+    }
+  }
+  if (pattern === "") pattern = "/";
+  return new RegExp("^" + pattern + "$");
+}
+async function buildRouteOracle(pagesBase) {
+  let routes = [];
+  try {
+    routes = await scanRoutes(pagesBase, {
+      jayHtmlFilename: "page.jay-html",
+      compFilename: "page.ts"
+    });
+  } catch {
+    routes = [];
+  }
+  const staticUrls = /* @__PURE__ */ new Set();
+  const dynamicMatchers = [];
+  const selfUrlByPath = /* @__PURE__ */ new Map();
+  for (const route of routes) {
+    const concrete = routeToConcreteUrl(route);
+    if (concrete !== null) {
+      staticUrls.add(concrete);
+      if (route.jayHtmlPath) selfUrlByPath.set(path$1.resolve(route.jayHtmlPath), concrete);
+    }
+    if (route.segments.some((s2) => typeof s2 !== "string")) {
+      dynamicMatchers.push(routeToRegex(route));
+    }
+  }
+  return { staticUrls, dynamicMatchers, selfUrlByPath };
+}
+async function collectPublicAssets(publicFolder) {
+  const assets = /* @__PURE__ */ new Set();
+  async function walk(dir, prefix) {
+    let entries;
+    try {
+      entries = await promises.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        await walk(path$1.join(dir, entry.name), rel);
+      } else {
+        assets.add("/" + rel);
+      }
+    }
+  }
+  await walk(publicFolder, "");
+  return assets;
+}
+function originOf(baseUrl) {
+  try {
+    return new URL(baseUrl).origin;
+  } catch {
+    return void 0;
+  }
+}
+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 (/^(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) };
+      } catch {
+      }
+    }
+    return { kind: "skip" };
+  }
+  if (t.startsWith("/")) return { kind: "check", targetPath: normalizePath(t) };
+  return { kind: "skip" };
+}
+function checkInternalLinks(options) {
+  const { parsedFiles, oracle, assetUrls, baseUrl, projectRoot } = options;
+  const findings = [];
+  for (const { relativePath, parsed } of parsedFiles) {
+    if (parsed.validationOverrides?.["jay-stack"]?.[SUPPRESS_KEY] === true) continue;
+    const ownUrl = oracle.selfUrlByPath.get(path$1.resolve(projectRoot ?? ".", relativePath));
+    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;
+      if (verdict.kind === "degenerate") {
+        findings.push({
+          file: relativePath,
+          message: `Anchor 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) {
+        findings.push({
+          file: relativePath,
+          message: `Link 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;
+      }
+      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 "${raw}" — no page or public asset produces the URL "${target}".`,
+        suggestion: `Create a placeholder page/route for "${target}", or remove the link. Otherwise ${SUPPRESS_HINT}.`
+      });
+    }
+  }
+  return findings;
+}
+const META_SUPPRESS_HINT = 'suppress with jay-stack:\n  allow-meta-issues: true\nin the page <script type="application/jay-validations"> block';
+const LINK_SUPPRESS_HINT = 'suppress with jay-stack:\n  allow-broken-links: true\nin the page <script type="application/jay-validations"> block';
+const UNRESOLVED_BINDING = /\{[A-Za-z_$][\w$]*(?:\.[\w$]+)*\}/;
+const TITLE_MAX = 60;
+const DESCRIPTION_MAX = 160;
+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(/\/$/, "") || "/";
+}
+function routeInstanceUrl(route, instance) {
+  return normalizePath(buildUrlFromManifest(route.pattern, instance.params));
+}
+async function discoverBuildBackendDir(projectRoot, explicit) {
+  if (explicit) {
+    const abs = path$1.resolve(projectRoot, explicit);
+    if (await fileExists(path$1.join(abs, "route-manifest.json"))) return abs;
+    const nested = path$1.join(abs, "backend");
+    if (await fileExists(path$1.join(nested, "route-manifest.json"))) return nested;
+    const fromRoot = await highestVersionBackend(abs);
+    if (fromRoot) return fromRoot;
+    return null;
+  }
+  return highestVersionBackend(path$1.join(projectRoot, "build"));
+}
+async function highestVersionBackend(buildRoot) {
+  let entries;
+  try {
+    entries = (await promises.readdir(buildRoot, { withFileTypes: true })).filter((e2) => e2.isDirectory() && /^v/.test(e2.name)).map((e2) => e2.name);
+  } catch {
+    return null;
+  }
+  if (entries.length === 0) return null;
+  entries.sort(compareVersionDesc);
+  for (const name of entries) {
+    const backend = path$1.join(buildRoot, name, "backend");
+    if (await fileExists(path$1.join(backend, "route-manifest.json"))) return backend;
+  }
+  return null;
+}
+function compareVersionDesc(a, b) {
+  const pa = a.replace(/^v/, "").split(".").map(Number);
+  const pb = b.replace(/^v/, "").split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const da = pa[i] || 0;
+    const db = pb[i] || 0;
+    if (da !== db) return db - da;
+  }
+  return 0;
+}
+async function fileExists(p) {
+  try {
+    await promises.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function loadBuildManifest(backendDir) {
+  let manifest;
+  try {
+    manifest = JSON.parse(
+      await promises.readFile(path$1.join(backendDir, "route-manifest.json"), "utf8")
+    );
+  } catch {
+    return null;
+  }
+  let metadata = null;
+  try {
+    metadata = JSON.parse(
+      await promises.readFile(path$1.join(backendDir, "build-metadata.json"), "utf8")
+    );
+  } catch {
+    metadata = null;
+  }
+  return { manifest, metadata };
+}
+function buildBuildOracle(manifest, 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) {
+      const url = routeInstanceUrl(route, instance);
+      urls.add(url);
+      instances.push({
+        url,
+        cacheAbsPath: path$1.resolve(backendDir, instance.cachePath),
+        pattern: route.pattern,
+        headMeta: route.headMeta
+      });
+    }
+  }
+  return { urls, instances };
+}
+async function loadSlowViewState(cacheAbsPath) {
+  try {
+    const cache = JSON.parse(await promises.readFile(cacheAbsPath, "utf8"));
+    return cache.slowViewState ?? {};
+  } catch {
+    return {};
+  }
+}
+function checkTemplateLinksAgainstBuild(args) {
+  const { parsedFiles, buildUrls, assetUrls, dynamicMatchers, baseUrl } = args;
+  const findings = [];
+  for (const { relativePath, parsed } of parsedFiles) {
+    if (parsed.validationOverrides?.["jay-stack"]?.["allow-broken-links"] === true) continue;
+    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 !== "check") continue;
+      const target = verdict.targetPath;
+      if (buildUrls.has(target) || assetUrls.has(target)) continue;
+      if (!dynamicMatchers.some((re) => re.test(target))) continue;
+      findings.push({
+        file: relativePath,
+        message: `Broken link "${raw}" — matches a dynamic route but "${target}" is not among the URLs this build produces.`,
+        suggestion: `Create the slug/page, fix the path, or remove the link. Otherwise ${LINK_SUPPRESS_HINT}.`,
+        severity: "error",
+        source: "build-output"
+      });
+    }
+  }
+  return findings;
+}
+function resolveContentHref(raw, instanceUrl, baseUrl) {
+  const t = raw.trim();
+  if (t === "" || t === "#" || t.startsWith("#")) return { kind: "skip" };
+  if (t.includes("{")) return { kind: "skip" };
+  if (t.startsWith("/") || t.startsWith("//") || /^[a-z][a-z0-9+.-]*:/i.test(t)) {
+    const v = classifyHref(t, baseUrl);
+    return v.kind === "check" ? v : { kind: "skip" };
+  }
+  try {
+    const u2 = new URL(t, "https://_local_" + (instanceUrl === "/" ? "/" : instanceUrl));
+    return { kind: "check", targetPath: normalizePath(u2.pathname) };
+  } catch {
+    return { kind: "skip" };
+  }
+}
+function collectContentHrefs(viewState) {
+  const hrefs = [];
+  const seen = /* @__PURE__ */ new Set();
+  const walk = (node) => {
+    if (node == null) return;
+    if (typeof node === "string") {
+      if (node.includes("<a ")) {
+        const root = parse(node);
+        for (const a of root.querySelectorAll("a[href]")) {
+          const h = a.getAttribute("href");
+          if (h) hrefs.push(h);
+        }
+      }
+      return;
+    }
+    if (typeof node !== "object") return;
+    if (seen.has(node)) return;
+    seen.add(node);
+    if (Array.isArray(node)) {
+      for (const item of node) walk(item);
+    } else {
+      for (const v of Object.values(node)) walk(v);
+    }
+  };
+  walk(viewState);
+  return hrefs;
+}
+function checkContentLinks(args) {
+  const { instanceUrl, slowViewState, buildUrls, assetUrls, baseUrl } = args;
+  const findings = [];
+  const reported = /* @__PURE__ */ new Set();
+  for (const raw of collectContentHrefs(slowViewState)) {
+    const verdict = resolveContentHref(raw, instanceUrl, baseUrl);
+    if (verdict.kind !== "check") continue;
+    const target = verdict.targetPath;
+    if (buildUrls.has(target) || assetUrls.has(target)) continue;
+    if (reported.has(target)) continue;
+    reported.add(target);
+    findings.push({
+      file: instanceUrl,
+      message: `Broken link "${raw}" in rendered content of ${instanceUrl} — resolves to "${target}", which this build does not produce.`,
+      // Content links come from authored markdown/CMS data that often doubles as repo docs (where a
+      // repo-relative "../pkg/foo.ts" is correct), so this is a warning, not a build-failing error —
+      // unlike hand-authored template links (Check 1), which are site-only and stay errors.
+      suggestion: `Fix the link in the source content, point it at an absolute URL, or ${LINK_SUPPRESS_HINT}.`,
+      severity: "warning",
+      source: "build-output"
+    });
+  }
+  return findings;
+}
+function checkInstanceMeta(args) {
+  const { instanceUrl, headMeta, slowViewState } = args;
+  if (!headMeta) return [];
+  const findings = [];
+  const tags = headMetaToHeadTags(headMeta, slowViewState);
+  const addLeftover = (what, value) => findings.push({
+    file: instanceUrl,
+    message: `<${what}> for ${instanceUrl} resolves to "${value}" — an unresolved binding was not produced by slow render.`,
+    suggestion: `Ensure the field is produced by the slow phase, or make the ${what} static.`,
+    severity: "error",
+    source: "build-output"
+  });
+  const addWarn = (message) => findings.push({
+    file: instanceUrl,
+    message,
+    suggestion: `Fix the content or ${META_SUPPRESS_HINT}.`,
+    severity: "warning",
+    source: "build-output"
+  });
+  for (const tag of tags) {
+    if (tag.tag === "title") {
+      const value = tag.children ?? "";
+      if (UNRESOLVED_BINDING.test(value)) addLeftover("title", value);
+      else if (value.trim() === "") addWarn(`<title> for ${instanceUrl} is empty.`);
+      else if (value.length > TITLE_MAX)
+        addWarn(
+          `<title> for ${instanceUrl} is ${value.length} chars (recommend ≤ ${TITLE_MAX}).`
+        );
+    } else if (tag.tag === "meta" && tag.attrs?.name === "description") {
+      const value = tag.attrs.content ?? "";
+      if (UNRESOLVED_BINDING.test(value)) addLeftover('meta name="description"', value);
+      else if (value.trim() === "")
+        addWarn(`<meta name="description"> for ${instanceUrl} is empty.`);
+      else if (value.length > DESCRIPTION_MAX)
+        addWarn(
+          `<meta name="description"> for ${instanceUrl} is ${value.length} chars (recommend ≤ ${DESCRIPTION_MAX}).`
+        );
+    }
+  }
+  return findings;
+}
+function isBuildStale(metadata, newestSourceMtimeMs) {
+  if (!metadata?.buildTimestamp) return false;
+  const built = Date.parse(metadata.buildTimestamp);
+  if (Number.isNaN(built)) return false;
+  return newestSourceMtimeMs > built;
+}
+async function newestSourceMtime(dirs) {
+  let newest = 0;
+  const walk = async (dir) => {
+    let entries;
+    try {
+      entries = await promises.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      const full = path$1.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+      } else {
+        try {
+          const st = await promises.stat(full);
+          if (st.mtimeMs > newest) newest = st.mtimeMs;
+        } catch {
+        }
+      }
+    }
+  };
+  for (const dir of dirs) await walk(dir);
+  return newest;
+}
 async function findJayFiles(dir) {
   return await glob(`${dir}/**/*${JAY_EXTENSION$1}`);
 }
@@ -5369,8 +5747,7 @@ function checkRegionCssDrift(jayHtml, loadTemplate) {
       if (content === void 0) {
         templateCss = null;
       } else {
-        const body = parse(content).querySelector("body");
-        templateCss = scopeReadyCss(body ? body.innerHTML : "", extractStyleCss(content));
+        templateCss = extractStyleCss(content);
       }
       templateCssCache.set(imp.template, templateCss);
     }
@@ -5462,6 +5839,33 @@ function checkNestedRegionRefs(jayHtml, loadTemplate) {
   }
   return warnings;
 }
+function checkRegionCssNoRef(jayHtml, loadTemplate) {
+  const importsWithTemplate = jayHtml.headlessImports.filter((imp) => imp.template);
+  if (importsWithTemplate.length === 0) return [];
+  const findings = [];
+  const shipsCssCache = /* @__PURE__ */ new Map();
+  const templateShipsCss = (rel) => {
+    let v = shipsCssCache.get(rel);
+    if (v === void 0) {
+      const content = loadTemplate(rel);
+      v = content !== void 0 && extractStyleCss(content).trim() !== "";
+      shipsCssCache.set(rel, v);
+    }
+    return v;
+  };
+  for (const region of collectRegionElements(jayHtml.body)) {
+    const contractName2 = (region.rawTagName ?? "").toLowerCase().substring(4);
+    const imp = importsWithTemplate.find((i) => i.contractName === contractName2);
+    if (!imp?.template) continue;
+    if (region.getAttribute("ref")) continue;
+    if (!templateShipsCss(imp.template)) continue;
+    findings.push({
+      message: `<jay:${contractName2}> flattens template="${imp.template}" which ships CSS, but the region has no ref= — so its CSS cannot be scoped and \`jay-stack sync\` will silently drop it.`,
+      suggestion: `Add a ref= to the <jay:${contractName2}> so sync can scope its CSS as an @scope (.<ref>) block and preserve it.`
+    });
+  }
+  return findings;
+}
 const CONTENT_TAGS = /* @__PURE__ */ new Set([
   // inline text semantics
   "span",
@@ -5888,6 +6292,9 @@ async function validateJayFiles(options = {}) {
   const parsedFiles = [];
   let regionsSeen = 0;
   let templateImportsSeen = 0;
+  const designSystemCoverage = [];
+  const reuseByTemplate = /* @__PURE__ */ new Map();
+  const cataloguedContractFiles = /* @__PURE__ */ new Set();
   const pageJayHtmlFiles = await findJayFiles(scanDir);
   const componentJayHtmlFiles = await findJayFiles(componentsDir).catch(() => []);
   const jayHtmlFiles = [...pageJayHtmlFiles, ...componentJayHtmlFiles];
@@ -5895,6 +6302,7 @@ async function validateJayFiles(options = {}) {
   const componentContractFiles = await findContractFiles(componentsDir).catch(
     () => []
   );
+  for (const cf of componentContractFiles) cataloguedContractFiles.add(cf);
   const contractFiles = [...await findContractFiles(scanDir), ...componentContractFiles];
   const contractNameByFile = /* @__PURE__ */ new Map();
   if (options.verbose) {
@@ -6044,10 +6452,45 @@ async function validateJayFiles(options = {}) {
           suggestion: finding.suggestion
         });
       }
+      const cssNoRefErrors = checkRegionCssNoRef(parsedFile.val, readTemplateRel);
+      for (const finding of cssNoRefErrors) {
+        errors.push({
+          file: relativePath,
+          message: finding.message,
+          stage: "generate",
+          suggestion: finding.suggestion
+        });
+      }
       regionsSeen += collectRegionElements(parsedFile.val.body).length;
       templateImportsSeen += parsedFile.val.headlessImports.filter(
         (imp) => imp.template
       ).length;
+      if (!componentJayHtmlFileSet.has(jayFile)) {
+        const body = parsedFile.val.body;
+        const total = body.querySelectorAll("*").length;
+        const coveredNodes = /* @__PURE__ */ new Set();
+        for (const region of directChildRegions(body)) {
+          const contractName2 = regionContractName(region);
+          const imp = parsedFile.val.headlessImports.find(
+            (i) => i.contractName === contractName2
+          );
+          if (!imp?.template) continue;
+          coveredNodes.add(region);
+          for (const descendant of region.querySelectorAll("*")) {
+            coveredNodes.add(descendant);
+          }
+          const templateAbs = path$1.resolve(dirname, imp.template);
+          reuseByTemplate.set(templateAbs, (reuseByTemplate.get(templateAbs) ?? 0) + 1);
+          if (imp.contractPath) cataloguedContractFiles.add(imp.contractPath);
+        }
+        const covered = coveredNodes.size;
+        designSystemCoverage.push({
+          file: relativePath,
+          coveragePct: total ? covered / total : 0,
+          covered,
+          total
+        });
+      }
       const notLinkedWarnings = componentJayHtmlFileSet.has(jayFile) ? [] : checkRegionNotLinked(
         parsedFile.val,
         (imp) => listTemplatesForContractFile(imp.contractPath).map((t) => ({
@@ -6198,6 +6641,55 @@ async function validateJayFiles(options = {}) {
       suggestion: noDesignSystem.suggestion
     });
   }
+  const cataloguedTemplatePaths = /* @__PURE__ */ new Set();
+  for (const contractFile of cataloguedContractFiles) {
+    for (const t of listTemplatesForContractFile(contractFile)) {
+      cataloguedTemplatePaths.add(path$1.resolve(t.path));
+    }
+  }
+  const rel = (p) => "./" + path$1.relative(projectRoot, p).replace(/\\/g, "/");
+  const perTemplate = {};
+  for (const [abs, count] of reuseByTemplate) perTemplate[rel(abs)] = count;
+  const designSystemReuse = {
+    perTemplate,
+    catalogued: cataloguedTemplatePaths.size,
+    reusedMoreThanOnce: [...reuseByTemplate.values()].filter((n) => n >= 2).length,
+    reusedOfCatalogued: [...cataloguedTemplatePaths].filter(
+      (p) => (reuseByTemplate.get(p) ?? 0) >= 2
+    ).length
+  };
+  const linkOracle = await buildRouteOracle(scanDir);
+  const assetUrls = await collectPublicAssets(
+    path$1.resolve(projectRoot, resolvedConfig.devServer.publicFolder)
+  );
+  const linkFindings = checkInternalLinks({
+    parsedFiles,
+    oracle: linkOracle,
+    assetUrls,
+    baseUrl: config.site?.baseUrl,
+    projectRoot
+  });
+  for (const finding of linkFindings) {
+    errors.push({
+      file: finding.file,
+      message: finding.message,
+      stage: "generate",
+      source: "internal-links",
+      suggestion: finding.suggestion
+    });
+  }
+  if (options.tier2) {
+    await runBuildOutputValidation({
+      projectRoot,
+      buildDir: options.buildDir,
+      parsedFiles,
+      linkOracle,
+      assetUrls,
+      baseUrl: config.site?.baseUrl,
+      errors,
+      warnings
+    });
+  }
   const pluginValidators = await runPluginValidators(projectRoot, parsedFiles, errors, warnings);
   return {
     valid: errors.length === 0,
@@ -6206,9 +6698,94 @@ async function validateJayFiles(options = {}) {
     errors,
     warnings,
     coverage,
-    pluginValidators
+    pluginValidators,
+    designSystemCoverage,
+    designSystemReuse
   };
 }
+async function runBuildOutputValidation(args) {
+  const { projectRoot, buildDir, parsedFiles, linkOracle, assetUrls, baseUrl, errors, warnings } = args;
+  const backendDir = await discoverBuildBackendDir(projectRoot, buildDir);
+  if (!backendDir) {
+    errors.push({
+      file: "build",
+      message: "Tier 2: no build found. Run `jay-stack build` first, or point --build-dir at a build.",
+      stage: "generate",
+      source: "build-output"
+    });
+    return;
+  }
+  const loaded = await loadBuildManifest(backendDir);
+  if (!loaded) {
+    errors.push({
+      file: backendDir,
+      message: `Tier 2: could not read route-manifest.json in ${backendDir}.`,
+      stage: "generate",
+      source: "build-output"
+    });
+    return;
+  }
+  const newest = await newestSourceMtime([
+    path$1.join(projectRoot, "src"),
+    path$1.join(projectRoot, "content")
+  ]);
+  if (isBuildStale(loaded.metadata, newest)) {
+    warnings.push({
+      file: "build",
+      message: `Tier 2: validated against a build from ${loaded.metadata?.buildTimestamp}; source has changed since.`,
+      source: "build-output",
+      suggestion: "Re-run `jay-stack build` for accurate results."
+    });
+  }
+  const oracle = buildBuildOracle(loaded.manifest, backendDir);
+  const findings = [];
+  findings.push(
+    ...checkTemplateLinksAgainstBuild({
+      parsedFiles,
+      buildUrls: oracle.urls,
+      assetUrls,
+      dynamicMatchers: linkOracle.dynamicMatchers,
+      baseUrl
+    })
+  );
+  for (const instance of oracle.instances) {
+    const slowViewState = await loadSlowViewState(instance.cacheAbsPath);
+    findings.push(
+      ...checkContentLinks({
+        instanceUrl: instance.url,
+        slowViewState,
+        buildUrls: oracle.urls,
+        assetUrls,
+        baseUrl
+      })
+    );
+    findings.push(
+      ...checkInstanceMeta({
+        instanceUrl: instance.url,
+        headMeta: instance.headMeta,
+        slowViewState
+      })
+    );
+  }
+  for (const finding of findings) {
+    if (finding.severity === "error") {
+      errors.push({
+        file: finding.file,
+        message: finding.message,
+        stage: "generate",
+        source: "build-output",
+        suggestion: finding.suggestion
+      });
+    } else {
+      warnings.push({
+        file: finding.file,
+        message: finding.message,
+        source: "build-output",
+        suggestion: finding.suggestion
+      });
+    }
+  }
+}
 function printJayValidationResult(result, options) {
   const logger = getLogger();
   if (options.json) {
@@ -6216,9 +6793,11 @@ function printJayValidationResult(result, options) {
     return;
   }
   logger.important("");
-  const coreErrors = result.errors.filter((e2) => e2.stage !== "plugin");
+  const coreErrors = result.errors.filter(
+    (e2) => e2.stage !== "plugin" && e2.source !== "build-output"
+  );
   const coreWarnings = result.warnings.filter((w) => !w.source);
-  logger.important(chalk.bold("📦 jay-stack (core)"));
+  logger.important(chalk.bold("📦 Tier 1 — jay-stack (core)"));
   if (coreErrors.length === 0) {
     logger.important(
       chalk.green(
@@ -6241,6 +6820,40 @@ function printJayValidationResult(result, options) {
       logger.important(chalk.blue(`     Suggestion: ${warning.suggestion}`));
     }
   }
+  const buildErrors = result.errors.filter((e2) => e2.source === "build-output");
+  const buildWarnings = result.warnings.filter((w) => w.source === "build-output");
+  if (buildErrors.length > 0 || buildWarnings.length > 0) {
+    logger.important("");
+    logger.important(chalk.bold("📦 Tier 2 — build-output validation (--tier-2)"));
+    for (const error of buildErrors) {
+      logger.important(chalk.red(`   ❌ ${error.file}`));
+      logger.important(chalk.gray(`      ${error.message}`));
+      if (error.suggestion) {
+        logger.important(chalk.blue(`      Suggestion: ${error.suggestion}`));
+      }
+    }
+    const buildWarnGroups = /* @__PURE__ */ new Map();
+    for (const warning of buildWarnings) {
+      const group = buildWarnGroups.get(warning.file) || [];
+      group.push(warning);
+      buildWarnGroups.set(warning.file, group);
+    }
+    for (const [file, groupWarns] of buildWarnGroups) {
+      logger.important(chalk.yellow(`   ⚠ ${file}`));
+      for (const warning of groupWarns) {
+        if (warning.message) {
+          logger.important(chalk.gray(`      ${warning.message}`));
+        }
+      }
+      const suggestions = [...new Set(groupWarns.map((w) => w.suggestion).filter(Boolean))];
+      if (suggestions.length > 0) {
+        logger.important(chalk.blue(`      Suggestions:`));
+        for (const s2 of suggestions) {
+          logger.important(chalk.blue(`        ${s2}`));
+        }
+      }
+    }
+  }
   const pluginErrors = result.errors.filter((e2) => e2.stage === "plugin");
   const pluginWarnings = result.warnings.filter((w) => !!w.source);
   for (const validatorName of result.pluginValidators) {
@@ -6280,23 +6893,84 @@ function printJayValidationResult(result, options) {
       }
     }
   }
-  if (options.verbose && result.coverage.length > 0) {
-    logger.important("");
-    logger.important(chalk.bold("📦 Tag Coverage"));
-    for (const fileCov of result.coverage) {
-      logger.important(`   ${fileCov.file}`);
-      for (const contract of fileCov.contracts) {
-        const label = contract.key ? `${contract.key} (${contract.contractName})` : contract.contractName;
-        logger.important(
-          `     ${label}: ${contract.usedTags}/${contract.totalTags} tags used`
-        );
-        if (contract.unusedTags.length > 0) {
+  const { designSystemCoverage, designSystemReuse } = result;
+  const reuseTemplates = Object.keys(designSystemReuse.perTemplate);
+  const hasTagCoverage = result.coverage.length > 0;
+  const hasScorecard = designSystemCoverage.length > 0 || reuseTemplates.length > 0;
+  let totalUsedTags = 0;
+  let totalTags = 0;
+  for (const fileCov of result.coverage) {
+    for (const contract of fileCov.contracts) {
+      totalUsedTags += contract.usedTags;
+      totalTags += contract.totalTags;
+    }
+  }
+  let totalCovered = 0;
+  let totalElements = 0;
+  for (const cov of designSystemCoverage) {
+    totalCovered += cov.covered;
+    totalElements += cov.total;
+  }
+  if (options.verbose) {
+    if (hasTagCoverage) {
+      logger.important("");
+      logger.important(chalk.bold("📦 Tag Coverage"));
+      for (const fileCov of result.coverage) {
+        logger.important(`   ${fileCov.file}`);
+        for (const contract of fileCov.contracts) {
+          const label = contract.key ? `${contract.key} (${contract.contractName})` : contract.contractName;
           logger.important(
-            chalk.gray(`       Unused: ${contract.unusedTags.join(", ")}`)
+            `     ${label}: ${contract.usedTags}/${contract.totalTags} tags used`
           );
+          if (contract.unusedTags.length > 0) {
+            logger.important(
+              chalk.gray(`       Unused: ${contract.unusedTags.join(", ")}`)
+            );
+          }
         }
       }
     }
+    if (hasScorecard) {
+      logger.important("");
+      logger.important(chalk.bold("📊 Design-system scorecard"));
+      for (const cov of designSystemCoverage) {
+        const pct = Math.round(cov.coveragePct * 100);
+        const lowFlag = pct < 50 ? chalk.yellow("  ⚠ low") : "";
+        logger.important(
+          chalk.gray(
+            `   Coverage: ${cov.file}  ${pct}%  (${cov.covered}/${cov.total} elements)`
+          ) + lowFlag
+        );
+      }
+      if (reuseTemplates.length > 0) {
+        const parts = reuseTemplates.map((t) => {
+          const n = designSystemReuse.perTemplate[t];
+          return n < 2 ? `${t} ×${n}${chalk.yellow(" ⚠ single-use")}` : `${t} ×${n}`;
+        });
+        logger.important(chalk.gray(`   Reuse: ${parts.join("   ")}`));
+      }
+      logger.important(
+        chalk.gray(
+          `   ${designSystemReuse.reusedOfCatalogued} of ${designSystemReuse.catalogued} catalogued templates reused > 1`
+        )
+      );
+    }
+  } else if (hasTagCoverage || hasScorecard) {
+    logger.important("");
+    if (hasTagCoverage) {
+      const pct = totalTags ? Math.round(totalUsedTags / totalTags * 100) : 0;
+      logger.important(
+        chalk.bold("📦 Tag coverage: ") + `${pct}% (${totalUsedTags}/${totalTags} tags used across ${result.coverage.length} page(s))`
+      );
+    }
+    if (hasScorecard) {
+      const pct = totalElements ? Math.round(totalCovered / totalElements * 100) : 0;
+      const lowFlag = pct < 50 ? chalk.yellow("  ⚠ low") : "";
+      logger.important(
+        chalk.bold("📊 Design-system scorecard: ") + `${pct}% element coverage (${totalCovered}/${totalElements}), ${designSystemReuse.reusedOfCatalogued} of ${designSystemReuse.catalogued} catalogued templates reused > 1` + lowFlag
+      );
+    }
+    logger.important(chalk.gray("   Run validate -v for per-page details."));
   }
   logger.important("");
   if (result.valid && result.warnings.length === 0) {
@@ -6322,12 +6996,22 @@ function printJayValidationResult(result, options) {
       )
     );
   }
+  if (!options.tier2) {
+    logger.important("");
+    logger.important(
+      chalk.gray(
+        "ℹ This was Tier 1 (template) validation. Tier 2 runs deeper checks against an existing build\n  (dynamic-slug links, rendered-content links, per-instance meta):\n    jay-stack validate --tier-2\n  See: agent-kit/designer/validation-tier-2-guide.md"
+      )
+    );
+  }
 }
 async function runValidate(scanPath, options) {
   const result = await validateJayFiles({
     path: scanPath,
     verbose: options.verbose,
-    json: options.json
+    json: options.json,
+    tier2: options.tier2,
+    buildDir: options.buildDir
   });
   printJayValidationResult(result, options);
   if (!result.valid) {
@@ -6474,7 +7158,7 @@ async function runBuild(projectPath, options) {
   }
   const ctx = await resolveProductionContext(projectPath, options.version);
   await generateDefinitionFiles(ctx);
-  const { buildVersion } = await import("./index-l6QVpvnY.js");
+  const { buildVersion } = await import("./index-BQbkAEhi.js");
   await buildVersion({
     version: ctx.version,
     projectRoot: ctx.resolvedPath,
@@ -7594,9 +8278,17 @@ program.command("cleanup").description("Delete orphaned files from previous rebu
     process.exit(1);
   }
 });
-program.command("validate").description("Validate all .jay-html and .jay-contract files").option("-p, --path <path>", "Scan root (default: cwd)").option("-v, --verbose", "Show per-file validation status").option("--json", "Output results as JSON").action(async (options) => {
+program.command("validate").description("Validate all .jay-html and .jay-contract files").option("-p, --path <path>", "Scan root (default: cwd)").option("-v, --verbose", "Show per-file validation status").option("--json", "Output results as JSON").addOption(
+  new Option(
+    "--tier-2",
+    "Run Tier 2: deep validation against an existing build (dynamic-slug links, rendered content, per-instance meta)"
+  )
+).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*)"
+).action(async (options) => {
   try {
-    await runValidate(options.path, options);
+    await runValidate(options.path, { ...options, tier2: options.tier2 || options.t2 });
   } catch (error) {
     if (options.json) {
       getLogger().important(