@tokenoftrust/storefront-runner 2.0.2 → 2.0.4

package/scripts/tenant/validate.mjs

@@ -0,0 +1,837 @@
+#!/usr/bin/env node
+/**
+ * `tot validate <tenant>` — static tenant-contract linter.
+ *
+ * Catches, BEFORE a commit reaches the hosted storefront, the classes of tenant
+ * defect that otherwise fail silently or as a cryptic runtime/reconcile error:
+ *   · `.tot/config.json` mapping-shape drift  (the #24/#25 regression — a `kind:"dir"`
+ *     / missing-`repo` mapping makes the flow-back reconcile `mapToArtifact` throw)
+ *   · malformed `theme.json` / `home.json` / `chrome.json`  (an eager Vite glob turns
+ *     these into a WHOLE-APP BUILD FAILURE)
+ *   · raw HTML that isn't a servable document, or drops CSS under the CSP nonce
+ *   · non-portable internal links (`https://<self-domain>/…`, `http://localhost…`) — the
+ *     class that "leaves localhost" when served locally or on a custom domain
+ *   · dangling internal links / missing referenced public assets
+ *
+ * Design principle — "valid locally ≡ will reconcile in storefront": the checks below
+ * mirror the reconcile pipeline's own gate (`@tot/private-controlplane`
+ * customization-reconcile.ts `mapToArtifact` / `validateRawHtml`). Keep them in step.
+ *
+ * Dependency-free. Two modes (mirrors scripts/tot-dev.mjs):
+ *   node scripts/tenant/validate.mjs <tenant>                # monorepo: tenants/<tenant>/
+ *   node scripts/tenant/validate.mjs --workspace <checkout>  # a standalone tenant checkout
+ *
+ * Exit 0 = no errors (warnings allowed); 1 = one or more errors; 2 = usage error.
+ * `--json` prints machine-readable findings. Importable: `validateTenant`,
+ * `validateConfigShape`, `discoverTenantIds` are exported for the CI regression test.
+ */
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { dirname, resolve, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { KNOWN_EMBEDS, lintTenantEmbeds } from "./lint-embeds.mjs";
+import { listTenantDirIds, tenantDirSegments } from "../lib/tenant-dirs.mjs";
+
+/** Catalogued embed slugs a tenant may opt into (mirror of EMBED_PROVIDERS). */
+const KNOWN_EMBED_SLUGS = new Set(KNOWN_EMBEDS.map((p) => p.slug));
+
+const here = dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = resolve(here, "../..");
+const TENANTS_DIR = join(REPO_ROOT, "tenants");
+const tenantDir = (id) => join(REPO_ROOT, ...tenantDirSegments(id));
+const NUL = String.fromCharCode(0);
+
+// --- findings model ----------------------------------------------------------
+const ERROR = "error";
+const WARN = "warn";
+/** @typedef {{level:string, rule:string, file:string, message:string, fix?:string}} Finding */
+
+function mk(level, rule, file, message, fix) {
+  return { level, rule, file, message, fix };
+}
+
+// --- git conflict markers ----------------------------------------------------
+// A half-resolved merge/rebase can commit literal conflict markers into content.
+// These are the default and diff3 marker lines, anchored
+// at line start and exactly 7 chars with a trailing boundary — precise enough that
+// real content never matches. `=======` / `|||||||` ALONE are NOT flagged (a lone
+// `=======` is a common markdown/prose horizontal rule); only the START (`<<<<<<<`)
+// and END (`>>>>>>>`) markers trigger — either one is a near-certain conflict, so
+// we err false-negative-averse and flag on either.
+const CONFLICT_START = /^<{7}(?=[ \t]|$)/;
+const CONFLICT_END = /^>{7}(?=[ \t]|$)/;
+
+/**
+ * Line numbers (1-based) of git conflict markers in `content`. Empty ⇒ none.
+ * Pure — exported for focused testing.
+ * @param {string} content
+ * @returns {number[]}
+ */
+export function detectConflictMarkers(content) {
+  if (typeof content !== "string" || (!content.includes("<<<<<<<") && !content.includes(">>>>>>>"))) return [];
+  const lines = content.split(/\r?\n/);
+  const hits = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (CONFLICT_START.test(lines[i]) || CONFLICT_END.test(lines[i])) hits.push(i + 1);
+  }
+  return hits;
+}
+
+// Text artifacts a conflict marker can hide in (images/fonts live in public/, not scanned).
+const CONFLICT_SCAN_EXT = new Set([".html", ".htm", ".json", ".md", ".txt", ".css", ".js", ".mjs", ".svg", ".xml"]);
+const hasScanExt = (p) => CONFLICT_SCAN_EXT.has((p.match(/\.[^./\\]+$/) || [""])[0].toLowerCase());
+
+// --- canonical `.tot/config.json` shape (the #24/#25 regression guard) --------
+const KNOWN_KINDS = new Set(["file", "tree"]);
+const REQUIRED_WORKSPACES = ["content/", "public/", "theme.json"];
+
+/**
+ * Validate a parsed `.tot/config.json` against the shape the reconcile pipeline
+ * (`mapToArtifact`) requires. Pure — no I/O — so the CI regression test can call it.
+ * @param {any} config parsed JSON
+ * @param {string} file path for messages
+ * @returns {Finding[]}
+ */
+export function validateConfigShape(config, file = ".tot/config.json") {
+  const out = [];
+  if (config == null || typeof config !== "object") {
+    return [mk(ERROR, "config-parse", file, "config is not a JSON object")];
+  }
+  if (typeof config.tenant !== "string" || !config.tenant) {
+    out.push(mk(ERROR, "config-tenant", file, "`tenant` must be a non-empty string"));
+  }
+  if (!Array.isArray(config.mappings)) {
+    out.push(mk(ERROR, "config-mappings", file, "`mappings` must be an array", "seed shape: [{workspace,repo,kind}]"));
+    return out; // nothing more to check without the array
+  }
+  const seen = new Set();
+  for (const [i, m] of config.mappings.entries()) {
+    const at = `${file} mappings[${i}]`;
+    if (m == null || typeof m !== "object") {
+      out.push(mk(ERROR, "mapping-shape", at, "mapping must be an object"));
+      continue;
+    }
+    if (typeof m.workspace !== "string" || !m.workspace) {
+      out.push(mk(ERROR, "mapping-workspace", at, "`workspace` must be a non-empty string"));
+    } else {
+      seen.add(m.workspace.replace(/\/+$/, "") + (m.kind === "tree" ? "/" : ""));
+      seen.add(m.workspace);
+    }
+    // THE regression guard: reconcile's mapToArtifact dereferences m.repo and only
+    // knows "file" vs tree — a missing repo or kind:"dir" makes it throw at runtime.
+    if (typeof m.repo !== "string" || !m.repo) {
+      out.push(
+        mk(ERROR, "mapping-repo", at,
+          `mapping for "${m.workspace ?? "?"}" is missing a string \`repo\` (reconcile mapToArtifact throws on undefined.repo)`,
+          `add "repo": "tenants/${config.tenant ?? "<id>"}/${(m.workspace ?? "").replace(/\/+$/, "")}${m.kind === "file" ? "" : "/"}"`),
+      );
+    }
+    if (!KNOWN_KINDS.has(m.kind)) {
+      out.push(
+        mk(ERROR, "mapping-kind", at,
+          `\`kind\` is "${m.kind}" — must be "file" or "tree" (legacy "dir" is the #24/#25 bug)`,
+          m.kind === "dir" ? 'change "dir" → "tree"' : 'set "file" for a single file, "tree" for a directory'),
+      );
+    }
+  }
+  // must cover content/ + public/ + theme.json so nothing a dev edits is silently unmapped
+  for (const req of REQUIRED_WORKSPACES) {
+    const bare = req.replace(/\/+$/, "");
+    if (!seen.has(req) && !seen.has(bare)) {
+      out.push(mk(WARN, "config-coverage", file, `mappings do not cover "${req}" — edits there won't flow back`));
+    }
+  }
+  return out;
+}
+
+// --- tiny HTML checks (mirror customization-reconcile.ts validateRawHtml) ------
+function isFullDocument(html) {
+  const head = html.slice(0, 512).toLowerCase();
+  return head.includes("<!doctype") || head.includes("<html");
+}
+function validateRawHtmlBody(html) {
+  if (typeof html !== "string" || html.length === 0) return "empty document";
+  if (html.includes(NUL)) return "contains NUL byte (not text/HTML)";
+  if (!html.includes("<")) return "no markup tags found";
+  return null;
+}
+// Compact structural mirror of @tot/public-runtime chrome.ts's `ChromeConfig`
+// shape — the consolidated header/footer schema (retired both the old lean
+// `SiteChrome` and the `sharedChrome: true`-gated `TenantChrome`). This is
+// NOT a full validateChromeConfig() pass — deep per-item errors are the
+// write-path's job (packages/private-controlplane/src/customization-chrome.ts,
+// which does call the real validateChromeConfig()); this only decides whether
+// the tenant's chrome.json looks enough like a ChromeConfig to opt the tenant
+// into shared chrome for the html-fragment check below. This script runs as
+// plain Node (no TS loader), so it can't import the TS-source
+// `@tot/public-runtime` package at runtime — this is a copy. Parity test:
+// packages/public-runtime/tests/chrome-config-shape-parity.test.ts. Kept in
+// step with packages/cli/src/validate.mjs's identical copy.
+const CHROME_HEADER_VARIANTS = new Set(["primary", "minimal"]);
+const CHROME_FOOTER_VARIANTS = new Set(["default"]);
+export function looksLikeChromeConfig(value) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) return false;
+  const header = value.header;
+  if (header == null || typeof header !== "object" || Array.isArray(header)) return false;
+  if (!CHROME_HEADER_VARIANTS.has(header.variant)) return false;
+  const brand = header.brand;
+  if (brand == null || typeof brand !== "object" || typeof brand.label !== "string" || brand.label.trim() === "") return false;
+  if (!Array.isArray(header.nav)) return false;
+  const footer = value.footer;
+  if (footer == null || typeof footer !== "object" || Array.isArray(footer)) return false;
+  if (!CHROME_FOOTER_VARIANTS.has(footer.variant)) return false;
+  if (!Array.isArray(footer.columns)) return false;
+  return true;
+}
+
+/**
+ * Does the tenant provide chrome to wrap body-only fragments? True when it
+ * ships EITHER a hand-authored `content/chrome.html`, OR a `content/chrome.json`
+ * that looks like a consolidated `ChromeConfig` (see {@link looksLikeChromeConfig}).
+ * Mirrors the serve-time resolution in apps/storefront getChromeHtml() →
+ * parseChromeConfig(): a config that parses is rendered into the wrapper
+ * (renderRawChrome), so a fragment is NOT served naked.
+ */
+function providesChrome(contentDir) {
+  if (existsSync(join(contentDir, "chrome.html"))) return true;
+  const configPath = join(contentDir, "chrome.json");
+  if (!existsSync(configPath)) return false;
+  const { value } = readJsonSafe(configPath);
+  return looksLikeChromeConfig(value);
+}
+
+const CAPABILITY_KEYS = new Set(["cartCheckout", "ageVerification", "exciseTax"]);
+
+function complianceObligations(config) {
+  const compliance = config?.compliance || {};
+  return {
+    ageVerification: !!compliance.minAge,
+    exciseTax: !!compliance.nicotineWarning,
+  };
+}
+
+function rawHtmlAllowed(config) {
+  const obligations = complianceObligations(config);
+  const regulated = obligations.ageVerification || obligations.exciseTax;
+  return !regulated;
+}
+
+function validateCapabilitiesDoc(doc, file, config) {
+  const out = [];
+  if (doc == null || typeof doc !== "object" || Array.isArray(doc)) {
+    return [mk(ERROR, "capabilities-root", file, "capabilities must be a JSON object")];
+  }
+  for (const [key, value] of Object.entries(doc)) {
+    if (!CAPABILITY_KEYS.has(key)) {
+      out.push(mk(ERROR, "capability-unknown", file, `unknown capability "${key}"`));
+      continue;
+    }
+    if (value == null || typeof value !== "object" || typeof value.enabled !== "boolean") {
+      out.push(mk(ERROR, "capability-shape", file, `${key} must be an object with boolean "enabled"`));
+    }
+  }
+  const obligations = complianceObligations(config);
+  if (obligations.ageVerification && doc.ageVerification?.enabled === false) {
+    out.push(mk(ERROR, "capability-compliance-floor", file, "ageVerification cannot be disabled for a tenant with compliance.minAge"));
+  }
+  if (obligations.exciseTax && doc.exciseTax?.enabled === false) {
+    out.push(mk(ERROR, "capability-compliance-floor", file, "exciseTax cannot be disabled for a tenant with compliance.nicotineWarning"));
+  }
+  return out;
+}
+
+function validateEmbedsDoc(doc, file) {
+  // embeds.json is the tenant's self-serve third-party embed opt-in: a JSON
+  // array of catalogued provider slugs (e.g. ["pipedrive"]). An unknown slug is
+  // a WARNING, not an error — resolveEffectiveEmbeds drops it (fail-safe: the
+  // embed stays CSP-blocked), so a typo is inert rather than dangerous, but the
+  // tenant still needs to know it won't take effect.
+  if (!Array.isArray(doc)) {
+    return [mk(ERROR, "embeds-root", file, "embeds.json must be a JSON array of provider slugs, e.g. [\"pipedrive\"]")];
+  }
+  const out = [];
+  for (const slug of doc) {
+    if (typeof slug !== "string") {
+      out.push(mk(ERROR, "embeds-shape", file, `every entry must be a string slug; got ${typeof slug}`));
+    } else if (!KNOWN_EMBED_SLUGS.has(slug)) {
+      out.push(mk(WARN, "embed-unknown", file, `"${slug}" is not a known embed provider — it will be ignored (the CSP will still block that embed). Known: ${[...KNOWN_EMBED_SLUGS].join(", ")}.`));
+    }
+  }
+  return out;
+}
+
+function validateScriptsDoc(doc, file, config) {
+  const out = [];
+  if (doc == null || typeof doc !== "object" || !Array.isArray(doc.scripts)) {
+    return [mk(ERROR, "scripts-root", file, 'scripts.json must have a "scripts" array')];
+  }
+  const regulated = !rawHtmlAllowed(config);
+  for (const [i, entry] of doc.scripts.entries()) {
+    const at = `${file} scripts[${i}]`;
+    if (entry == null || typeof entry !== "object") {
+      out.push(mk(ERROR, "script-entry", at, "script entry must be an object"));
+      continue;
+    }
+    if (entry.isolation === "inline") {
+      out.push(
+        regulated
+          ? mk(ERROR, "script-inline-regulated", at, 'inline scripts are not allowed for regulated tenants; use isolation:"sandbox"')
+          : mk(WARN, "script-inline", at, 'inline scripts run same-origin; prefer isolation:"sandbox"'),
+      );
+    }
+  }
+  return out;
+}
+
+const SUPPORTED_BLOCK_CONTRACTS = new Set(["block-palette@1", "block-palette@2", "block-palette@3"]);
+const KNOWN_BLOCKS = new Set([
+  "hero",
+  "promo_tiles",
+  "featured_collections",
+  "featured_products",
+  "membership_band",
+  "editorial",
+  "newsletter",
+  "marketing_hero",
+  "trust_bar",
+  "split_compare",
+  "steps",
+  "card_grid",
+  "integrations",
+  "proof_strip",
+  "testimonials",
+  "faq",
+  "cta_band",
+]);
+const REQUIRED_BLOCK_PROPS = {
+  hero: ["headline"],
+  promo_tiles: ["tiles"],
+  featured_collections: ["handles"],
+  membership_band: ["tiers"],
+  editorial: ["title"],
+  newsletter: ["title"],
+  marketing_hero: ["headline"],
+  trust_bar: ["items"],
+  split_compare: ["title", "before", "after"],
+  steps: ["title", "steps"],
+  card_grid: ["title", "cards"],
+  integrations: ["title", "platforms"],
+  proof_strip: ["title"],
+  testimonials: ["quotes"],
+  faq: ["title", "items"],
+  cta_band: ["title"],
+};
+const PRODUCT_SOURCE_KEYS = new Set([
+  "collection",
+  "tag",
+  "featured",
+  "newest",
+  "bestSelling",
+  "onSale",
+  "handles",
+  "related",
+  "recentlyViewed",
+]);
+const PRODUCT_SOURCE_SHORTCUTS = new Set(["featured", "newest", "bestSelling", "onSale"]);
+
+function validateProductSource(value, file, at) {
+  const out = [];
+  if (typeof value === "string") {
+    if (!PRODUCT_SOURCE_SHORTCUTS.has(value)) {
+      out.push(mk(ERROR, "product-source", file, `${at}.source must be one of featured, newest, bestSelling, onSale or a source object`));
+    }
+    return out;
+  }
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    out.push(mk(ERROR, "product-source", file, `${at}.source must be a source string or object`));
+    return out;
+  }
+  const keys = Object.keys(value).filter((k) => value[k] !== undefined);
+  const recognized = keys.filter((k) => PRODUCT_SOURCE_KEYS.has(k));
+  if (keys.length !== 1 || recognized.length !== 1) {
+    out.push(mk(ERROR, "product-source", file, `${at}.source must declare exactly one recognized source key`));
+    return out;
+  }
+  const key = recognized[0];
+  const got = value[key];
+  if (key === "handles") {
+    if (!Array.isArray(got) || !got.every((v) => typeof v === "string")) {
+      out.push(mk(ERROR, "product-source", file, `${at}.source.handles must be a string array`));
+    }
+  } else if (key === "collection" || key === "tag" || key === "related") {
+    if (typeof got !== "string") {
+      out.push(mk(ERROR, "product-source", file, `${at}.source.${key} must be a string`));
+    }
+  } else if (got !== true) {
+    out.push(mk(ERROR, "product-source", file, `${at}.source.${key} must be true`));
+  }
+  return out;
+}
+
+function validateHomeDoc(doc, file) {
+  const out = [];
+  if (doc == null || typeof doc !== "object" || Array.isArray(doc)) {
+    return [mk(ERROR, "home-root", file, "home.json must be a JSON object")];
+  }
+  if (doc.contract !== undefined && (typeof doc.contract !== "string" || !SUPPORTED_BLOCK_CONTRACTS.has(doc.contract))) {
+    out.push(mk(ERROR, "home-contract", file, `unsupported block contract "${String(doc.contract)}"`));
+  }
+  if (!Array.isArray(doc.blocks)) {
+    out.push(mk(ERROR, "home-blocks", file, "`blocks` must be an array"));
+    return out;
+  }
+  doc.blocks.forEach((block, i) => {
+    const at = `blocks[${i}]`;
+    if (block == null || typeof block !== "object" || Array.isArray(block)) {
+      out.push(mk(ERROR, "block-shape", file, `${at} must be an object`));
+      return;
+    }
+    const component = block.component;
+    if (typeof component !== "string") {
+      out.push(mk(ERROR, "block-component", file, `${at}.component is required`));
+      return;
+    }
+    if (!KNOWN_BLOCKS.has(component)) {
+      out.push(mk(ERROR, "block-unknown", file, `${at}.component "${component}" is not in the supported block palette`));
+      return;
+    }
+    for (const prop of REQUIRED_BLOCK_PROPS[component] || []) {
+      if (block[prop] === undefined) out.push(mk(ERROR, "block-required", file, `${at} (${component}) is missing "${prop}"`));
+    }
+    if (component === "featured_products") {
+      if (block.source !== undefined) out.push(...validateProductSource(block.source, file, at));
+      if (block.handles !== undefined && (!Array.isArray(block.handles) || !block.handles.every((v) => typeof v === "string"))) {
+        out.push(mk(ERROR, "block-prop", file, `${at}.handles must be a string array`));
+      }
+      if (block.limit !== undefined && typeof block.limit !== "number") {
+        out.push(mk(ERROR, "block-prop", file, `${at}.limit must be a number`));
+      }
+    }
+  });
+  return out;
+}
+
+// --- filesystem helpers ------------------------------------------------------
+function readJsonSafe(path) {
+  try {
+    return { value: JSON.parse(readFileSync(path, "utf8")), error: null };
+  } catch (e) {
+    return { value: null, error: /** @type {Error} */ (e).message };
+  }
+}
+function walk(dir, pred) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    const st = statSync(p);
+    if (st.isDirectory()) out.push(...walk(p, pred));
+    else if (pred(p)) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Every tenant id with a directory on disk — real tenants under `tenants/`, and
+ * platform test tenants under `tenants/e2e/`.
+ *
+ * DELIBERATELY UNFILTERED, unlike the generalized listings: this drives the
+ * `.tot/config.json` shape guard, and a test tenant reconciles through the very
+ * same pipeline a real one does. Excluding the fixtures here would silently stop
+ * validating exactly the configs the e2e suites depend on.
+ */
+export function discoverTenantIds() {
+  if (!existsSync(TENANTS_DIR)) return [];
+  return listTenantDirIds(TENANTS_DIR, readdirSync, (p) => statSync(p).isDirectory(), join);
+}
+
+// --- link / asset extraction -------------------------------------------------
+const HREF_RE = /\bhref\s*=\s*"([^"]*)"/gi;
+const SRC_RE = /\b(?:src|srcset)\s*=\s*"([^"]*)"/gi;
+const STYLE_OPEN_WITH_ATTRS_RE = /<style\s+[^>]*>/i;
+/** An in-page skip link: an anchor to a #main-ish target, or one carrying a skip class. */
+const SKIP_LINK_RE = /<a\b[^>]*(?:class="[^"]*\bskip[-\w]*\b[^"]*"|href="#(?:main|content|main-content)\b")/i;
+
+// --- platform-owned routes (framework surfaces, NOT tenant pages) ------------
+/**
+ * In MONOREPO mode the tenant is served BY this storefront platform, which itself
+ * owns a set of framework routes — catalog (`/collections`, `/collections/<handle>`,
+ * `/products/<handle>`), `/search`, `/saved`, the auth/account route (`/account`),
+ * and `/cart` when cart/checkout is on. A COMMERCE tenant that links into those is
+ * linking to a live platform surface, so such links must NOT be flagged
+ * `link-dangling` — only genuinely-missing tenant pages/assets should warn.
+ *
+ * MARKETING tenants get none of these (their commerce affordances are off), so they
+ * stay strict. A standalone tenant-checkout (`--workspace`) also stays conservative —
+ * it can't assume the eventual host is this platform — UNLESS the config resolves the
+ * host (`"hostPlatform": "tot-storefront"`).
+ *
+ * The route→feature mapping mirrors `resolveTenantFeatures` in
+ * `@tot/public-runtime` tenant.ts (catalog / productSearch / savedItems) — keep in step.
+ */
+const COMMERCE_ROUTE_FEATURES = { catalog: true, productSearch: true, savedItems: true };
+
+/**
+ * @param {any} config parsed `.tot/config.json` (or null)
+ * @param {boolean} hostIsPlatform is the serving host this ToT storefront platform?
+ * @returns {{active:boolean, owns:(path:string)=>boolean}}
+ */
+function resolvePlatformRouteOwnership(config, hostIsPlatform) {
+  const inert = { active: false, owns: () => false };
+  if (!hostIsPlatform) return inert; // standalone / unresolved host → conservative
+  const siteType = config?.siteType ?? "commerce"; // unset == commerce (platform default)
+  if (siteType === "marketing") return inert; // marketing owns no commerce routes
+  // commerce feature defaults, with any explicit per-flag overrides layered on
+  const features = { ...COMMERCE_ROUTE_FEATURES };
+  const overrides = config?.features;
+  if (overrides && typeof overrides === "object") {
+    for (const [k, v] of Object.entries(overrides)) if (v !== undefined && k in features) features[k] = v;
+  }
+  const cartEnabled = config?.capabilities?.cartCheckout?.enabled ?? true; // commerce default: on
+
+  const exact = new Set(["/account"]); // the auth/account route the platform currently serves
+  const prefixes = ["/account/"];
+  if (features.catalog) {
+    exact.add("/collections");
+    prefixes.push("/collections/", "/products/");
+  }
+  if (features.productSearch) exact.add("/search");
+  if (features.savedItems) exact.add("/saved");
+  if (cartEnabled) {
+    exact.add("/cart");
+    prefixes.push("/cart/");
+  }
+  return {
+    active: true,
+    owns(path) {
+      const norm = path.replace(/\/+$/, "") || "/";
+      if (exact.has(norm)) return true;
+      return prefixes.some((p) => path.startsWith(p));
+    },
+  };
+}
+
+/**
+ * Full static validation of a tenant directory.
+ * @param {string} tenantDir absolute path to the tenant dir (content/ public/ theme.json [.tot/])
+ * @param {{tenantId?:string, scope?:string, mode?:"monorepo"|"workspace"}} [opts]
+ *   `mode` — "monorepo" (default): served by this platform, so commerce tenants own
+ *   the framework routes. "workspace": a standalone checkout, conservative about
+ *   platform-route ownership unless the config resolves the host.
+ * @returns {{ok:boolean, findings:Finding[]}}
+ */
+export function validateTenant(tenantDir, opts = {}) {
+  /** @type {Finding[]} */
+  const findings = [];
+  const rel = (p) => relative(tenantDir, p) || p;
+  const contentDir = join(tenantDir, "content");
+  const publicDir = join(tenantDir, "public");
+  const pagesDir = join(contentDir, "pages-html");
+
+  // 0. basic layout
+  if (!existsSync(contentDir)) {
+    findings.push(mk(ERROR, "layout", "content/", "no content/ directory"));
+  }
+
+  // 1. .tot/config.json — shape (flow-back readiness)
+  const configPath = join(tenantDir, ".tot", "config.json");
+  let config = null;
+  if (existsSync(configPath)) {
+    const { value, error } = readJsonSafe(configPath);
+    if (error) {
+      findings.push(mk(ERROR, "config-parse", ".tot/config.json", `invalid JSON: ${error}`));
+    } else {
+      config = value;
+      findings.push(...validateConfigShape(value, ".tot/config.json"));
+    }
+  } else {
+    findings.push(
+      mk(WARN, "config-absent", ".tot/config.json",
+        "no .tot/config.json — tenant can serve but is NOT flow-back-ready (reconcile has nothing to map)",
+        // The host tenant tree fully supports a colocated .tot/config.json: the resolver
+        // globs tenants/*/.tot/config.json (config/resolver.ts), copy-tenant-assets bakes
+        // ONLY public/ so the .tot dir never ships to served output, and this validator
+        // recognizes it above. So this is a real flow-back-readiness gap, NOT an
+        // unsupported-layout ask — add the file to close it.
+        "add tenants/<id>/.tot/config.json mapping theme.json + content/ + public/ (host-tree layout is supported — .tot/ is never served); see tenants/tokenoftrust.com/.tot/config.json"),
+    );
+  }
+  const scope = opts.scope || config?.scope;
+  // platform-route awareness: which framework routes the host platform owns for this tenant
+  const mode = opts.mode === "workspace" ? "workspace" : "monorepo";
+  const hostIsPlatform = mode === "monorepo" || config?.hostPlatform === "tot-storefront";
+  const platformRoutes = resolvePlatformRouteOwnership(config, hostIsPlatform);
+  if (config?.capabilities) {
+    findings.push(...validateCapabilitiesDoc(config.capabilities, ".tot/config.json capabilities", config));
+  }
+
+  // 2. theme.json — parse (a malformed one is a WHOLE-APP BUILD FAILURE)
+  const themePath = join(tenantDir, "theme.json");
+  if (existsSync(themePath)) {
+    const { error } = readJsonSafe(themePath);
+    if (error) {
+      findings.push(
+        mk(ERROR, "theme-parse", "theme.json",
+          `invalid JSON: ${error}`, "theme.json is loaded by an eager Vite glob — a parse error fails the entire storefront build"),
+      );
+    }
+  }
+
+  const capabilitiesPath = join(tenantDir, "capabilities.json");
+  if (existsSync(capabilitiesPath)) {
+    const { value, error } = readJsonSafe(capabilitiesPath);
+    if (error) {
+      findings.push(mk(ERROR, "capabilities-parse", "capabilities.json", `invalid JSON: ${error}`));
+    } else {
+      findings.push(...validateCapabilitiesDoc(value, "capabilities.json", config));
+    }
+  }
+
+  const scriptsPath = join(tenantDir, "scripts.json");
+  if (existsSync(scriptsPath)) {
+    const { value, error } = readJsonSafe(scriptsPath);
+    if (error) {
+      findings.push(mk(ERROR, "scripts-parse", "scripts.json", `invalid JSON: ${error}`));
+    } else {
+      findings.push(...validateScriptsDoc(value, "scripts.json", config));
+    }
+  }
+
+  const embedsPath = join(tenantDir, "embeds.json");
+  if (existsSync(embedsPath)) {
+    const { value, error } = readJsonSafe(embedsPath);
+    if (error) {
+      findings.push(mk(ERROR, "embeds-parse", "embeds.json", `invalid JSON: ${error}`));
+    } else {
+      findings.push(...validateEmbedsDoc(value, "embeds.json"));
+    }
+  }
+
+  // 3. content JSON — parse + blocks shape
+  for (const name of ["home.json", "chrome.json"]) {
+    const p = join(contentDir, name);
+    if (existsSync(p)) {
+      const { value, error } = readJsonSafe(p);
+      if (error) {
+        findings.push(mk(ERROR, "content-json-parse", `content/${name}`, `invalid JSON: ${error} (fails the build)`));
+      } else if (name === "home.json") {
+        findings.push(...validateHomeDoc(value, "content/home.json"));
+      }
+    }
+  }
+
+  // 4. raw HTML documents — validate + portability + resolution
+  const hasChrome = providesChrome(contentDir);
+  const htmlFiles = walk(contentDir, (p) => p.endsWith(".html"));
+  // build the set of resolvable internal page paths (root-absolute → page file)
+  const pageTargets = buildPageTargetSet(contentDir, pagesDir);
+
+  for (const p of htmlFiles) {
+    const r = rel(p);
+    const html = readFileSync(p, "utf8");
+    const base = r === "content/chrome.html";
+
+    const bad = validateRawHtmlBody(html);
+    if (bad) {
+      findings.push(mk(ERROR, "html-invalid", r, `not a servable document: ${bad}`));
+      continue;
+    }
+    if (config && !rawHtmlAllowed(config)) {
+      findings.push(
+        mk(ERROR, "raw-html-compliance-bypass", r,
+          "raw HTML bypasses platform Layout compliance; regulated commerce tenants must use block composition or an extracted runtime"),
+      );
+    }
+    if (!base && !isFullDocument(html) && !hasChrome) {
+      findings.push(
+        mk(ERROR, "html-fragment", r,
+          "is an HTML fragment but the tenant ships no chrome to wrap it — it will serve unwrapped/naked",
+          "make it a full <!doctype html> document, add a content/chrome.json with header.variant/header.brand.label/header.nav and footer.variant/footer.columns, or add content/chrome.html with <!--PAGE_BODY-->"),
+      );
+    }
+    // A body-only fragment is spliced INTO the tenant's chrome, and that chrome
+    // already supplies the skip link. A fragment that kept its own ships two — an
+    // a11y defect no browser reports and reconcile cannot see, so it survives every
+    // gate and lands in the assembled page.
+    if (!base && !isFullDocument(html) && hasChrome && SKIP_LINK_RE.test(html)) {
+      findings.push(
+        mk(WARN, "duplicate-skip-link", r,
+          "keeps its own skip link, but the tenant's chrome already supplies one — the assembled page will have two",
+          "delete the page-level skip link; the chrome's skipLink is the one that renders"),
+      );
+    }
+    // CSP: the nonce injector only rewrites a bare `<style>`; `<style type=…>` is skipped → its CSS is dropped.
+    if (STYLE_OPEN_WITH_ATTRS_RE.test(html)) {
+      findings.push(
+        mk(WARN, "style-attrs", r,
+          "has an inline <style …> with attributes — the CSP nonce injector only matches a bare <style>, so this CSS is dropped when served",
+          "use a bare <style> tag"),
+      );
+    }
+
+    // link portability + resolution
+    for (const m of html.matchAll(HREF_RE)) {
+      const href = m[1].trim();
+      findings.push(...checkLink(href, r, scope, pageTargets, platformRoutes.owns));
+    }
+    // asset existence (src=/tenants/<id>/… or root-absolute /… under public)
+    for (const m of html.matchAll(SRC_RE)) {
+      const f = checkAsset(m[1].trim(), r, publicDir, opts.tenantId || config?.tenant);
+      if (f) findings.push(f);
+    }
+  }
+
+  // 5. git conflict markers — advisory (never blocks), but LOUD: a half-resolved
+  // merge/rebase must not slip past as "validated". Scans text artifacts under
+  // content/ plus the root config files.
+  const conflictScanFiles = [
+    ...walk(contentDir, hasScanExt),
+    ...["theme.json", "capabilities.json", "scripts.json", join(".tot", "config.json")]
+      .map((f) => join(tenantDir, f))
+      .filter((p) => existsSync(p)),
+  ];
+  for (const p of conflictScanFiles) {
+    const lines = detectConflictMarkers(readFileSync(p, "utf8"));
+    if (lines.length) {
+      findings.push(
+        mk(WARN, "git-conflict-markers", rel(p),
+          `git conflict markers at line(s) ${lines.join(", ")} — looks like an unfinished merge/rebase (the page would still build/serve broken)`,
+          "resolve the conflict and remove the <<<<<<< / ======= / >>>>>>> lines before submitting"),
+      );
+    }
+  }
+
+  // Embed CSP shift-left: scan the tenant's HTML for third-party embeds and
+  // check them against the embeds.json opt-in. A known provider not opted in,
+  // or an unknown external <script>/<iframe> origin, will be silently blocked by
+  // the strict CSP — surface it here (in the dev loop) instead of as a blank
+  // spot a human has to notice. Advisory (info) when there's no embeds.json to
+  // compare against, since the opt-in may be the platform build-time default.
+  if (existsSync(contentDir)) {
+    let declaredEmbeds = null;
+    const embedsFile = join(tenantDir, "embeds.json");
+    if (existsSync(embedsFile)) {
+      const { value } = readJsonSafe(embedsFile);
+      if (Array.isArray(value)) declaredEmbeds = value.filter((s) => typeof s === "string");
+    }
+    for (const f of lintTenantEmbeds({ dir: contentDir, declared: declaredEmbeds }).findings) {
+      findings.push(mk(f.level, "embed-csp", rel(f.file), f.message));
+    }
+  }
+
+  const ok = !findings.some((f) => f.level === ERROR);
+  return { ok, findings };
+}
+
+function buildPageTargetSet(contentDir, pagesDir) {
+  const set = new Set(["/", ""]);
+  if (existsSync(join(contentDir, "home.html"))) set.add("/");
+  for (const p of walk(pagesDir, (x) => x.endsWith(".html"))) {
+    // pages-html/foo/bar.html → /foo/bar/  and  /foo/bar
+    const relPath = relative(pagesDir, p).replace(/\.html$/, "");
+    const slug = relPath === "index" ? "" : relPath;
+    set.add(`/${slug}/`.replace(/\/+/g, "/"));
+    set.add(`/${slug}`.replace(/\/+$/, "") || "/");
+  }
+  return set;
+}
+
+function checkLink(href, file, scope, pageTargets, ownsPlatformRoute = (/** @type {string} */ _p) => false) {
+  const out = [];
+  if (!href || href.startsWith("#") || href.startsWith("mailto:") || href.startsWith("tel:")) return out;
+  // localhost never belongs in committed content
+  if (/^https?:\/\/localhost(?::\d+)?/i.test(href)) {
+    out.push(mk(ERROR, "link-localhost", file, `links to a localhost URL: ${href}`, "use a root-absolute path (/foo/)"));
+    return out;
+  }
+  // absolute link back to the tenant's own scope → non-portable (leaves localhost/preview)
+  if (scope && new RegExp(`^https?://(www\\.)?${escapeRe(scope)}(/|$)`, "i").test(href)) {
+    const path = href.replace(/^https?:\/\/(www\.)?[^/]+/i, "") || "/";
+    out.push(
+      mk(ERROR, "link-nonportable", file,
+        `internal CTA is hardcoded to https://${scope}${path} — it leaves localhost/preview when served`,
+        `use the root-absolute form: ${path}`),
+    );
+    return out;
+  }
+  // other absolute / protocol-relative / mail: external, leave alone
+  if (/^([a-z]+:)?\/\//i.test(href)) return out;
+  // root-absolute internal link → must resolve to a known page
+  if (href.startsWith("/")) {
+    if (href.startsWith("/tenants/")) return out; // asset path, not a page
+    const path = href.split(/[?#]/)[0];
+    const norm = path.replace(/\/+$/, "") || "/";
+    if (pageTargets.has(path) || pageTargets.has(norm) || pageTargets.has(norm + "/")) return out;
+    // a framework route the host platform owns (e.g. /collections, /account) is not a dangling tenant page
+    if (ownsPlatformRoute(path)) return out;
+    out.push(mk(WARN, "link-dangling", file, `internal link ${path} does not resolve to a known page (would 404)`));
+    return out;
+  }
+  // relative internal link — discouraged (breaks under path-prefix serving)
+  out.push(mk(WARN, "link-relative", file, `relative link "${href}" — internal links should be root-absolute (/foo/)`));
+  return out;
+}
+
+function checkAsset(src, file, publicDir, tenantId) {
+  if (!src || /^([a-z]+:)?\/\//i.test(src) || src.startsWith("data:")) return null;
+  let relPath = null;
+  if (tenantId && src.startsWith(`/tenants/${tenantId}/`)) {
+    relPath = src.slice(`/tenants/${tenantId}/`.length).split(/[?#]/)[0];
+  } else if (src.startsWith("/")) {
+    return null; // some other root-absolute asset (served from build public root) — out of scope
+  } else {
+    relPath = src.split(/[?#]/)[0];
+  }
+  if (!relPath) return null;
+  if (!existsSync(join(publicDir, relPath))) {
+    return mk(WARN, "asset-missing", file, `references public asset "${src}" which is not present under public/`);
+  }
+  return null;
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+// --- CLI ---------------------------------------------------------------------
+function resolveTenantDir(argv) {
+  const wsIdx = argv.indexOf("--workspace");
+  if (wsIdx !== -1) {
+    const dir = argv[wsIdx + 1];
+    if (!dir) return { error: "--workspace requires a path" };
+    return { dir: resolve(dir), tenantId: null };
+  }
+  const id = argv.find((a) => !a.startsWith("--"));
+  if (!id) return { error: "usage: node scripts/tenant/validate.mjs <tenant> | --workspace <dir> [--json]" };
+  return { dir: tenantDir(id), tenantId: id };
+}
+
+const isMain = resolve(process.argv[1] || "") === resolve(fileURLToPath(import.meta.url));
+if (isMain) {
+  const argv = process.argv.slice(2);
+  const asJson = argv.includes("--json");
+  const { dir, tenantId, error } = resolveTenantDir(argv);
+  if (error) {
+    console.error(error);
+    process.exit(2);
+  }
+  if (!dir) process.exit(2);
+  if (!existsSync(dir)) {
+    console.error(`✗ no tenant directory at ${dir}`);
+    process.exit(2);
+  }
+  const mode = argv.includes("--workspace") ? "workspace" : "monorepo";
+  const { ok, findings } = validateTenant(dir, { tenantId: tenantId ?? undefined, mode });
+  if (asJson) {
+    console.log(JSON.stringify({ ok, findings }, null, 2));
+    process.exit(ok ? 0 : 1);
+  }
+  const errors = findings.filter((f) => f.level === ERROR);
+  const warns = findings.filter((f) => f.level === WARN);
+  console.log(`\ntot validate — ${tenantId ?? dir}\n`);
+  for (const f of findings) {
+    const tag = f.level === ERROR ? "✗" : "⚠";
+    console.log(`  ${tag} [${f.rule}] ${f.file}\n      ${f.message}${f.fix ? `\n      → ${f.fix}` : ""}`);
+  }
+  console.log(
+    `\n${errors.length === 0 ? "✔" : "✖"} ${errors.length} error(s), ${warns.length} warning(s).\n`,
+  );
+  process.exit(errors.length === 0 ? 0 : 1);
+}