@tokenoftrust/cli 2.2.13 → 2.2.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.2.13",
+  "version": "2.2.15",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/declared-config.mjs

@@ -0,0 +1,78 @@
+/**
+ * The `.tot/config.json` keys the platform reads, and the refusal of everything
+ * else. Shared by `tot validate` (src/validate.mjs) and the monorepo/dev-loop
+ * validator (scripts/tenant/validate.mjs), so both refuse the same keys.
+ *
+ * Mirrors packages/public-runtime/src/declared-tenant-config.mjs (this package ships
+ * to npm on its own); test/declared-config-parity.test.mjs pins the two together, so
+ * a field the platform honors can never be refused here, and a key no surface reads
+ * can never pass. Dependency-free: the storefront runner copies this file as-is.
+ */
+
+export const TOT_CONFIG_KEYS = [
+  "$schema", "tenant", "scope", "mappings", "hostPlatform", "sample", "seed",
+  "siteType", "compliance", "capabilities", "features",
+];
+// Keys other tooling has written that the platform does NOT read, with the key it does.
+const RENAMED_CONFIG_KEYS = { appDomain: "scope", tenantId: "tenant" };
+export const COMPLIANCE_KEYS = [
+  "ruleProfile", "minAge", "nicotineWarning", "shippingRestriction", "pactAct",
+  "adultSignature", "prop65", "purchaseLimit", "stateEligibility", "exciseTax",
+];
+export const FEATURE_KEYS = [
+  "catalog", "productSearch", "savedItems", "quickView", "newsletter", "commerceSitemap", "productJsonLd", "ageGate",
+];
+export const SITE_TYPES = ["commerce", "marketing"];
+
+const ERROR = "error";
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** @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 };
+}
+
+/**
+ * Refuse what the platform would silently ignore: an unknown top-level key, an
+ * unknown `compliance`/`features` key, or a declared field of the wrong shape. Each
+ * one passes JSON parsing and renders nothing — on a regulated store that is a
+ * mandated notice that never appears.
+ * @param {Record<string, any>} config parsed `.tot/config.json` (an object)
+ * @param {string} [file]
+ * @returns {Finding[]}
+ */
+export function validateDeclaredConfig(config, file = ".tot/config.json") {
+  const out = [];
+  for (const key of Object.keys(config)) {
+    if (!TOT_CONFIG_KEYS.includes(key)) {
+      const renamed = RENAMED_CONFIG_KEYS[/** @type {keyof typeof RENAMED_CONFIG_KEYS} */ (key)];
+      out.push(mk(ERROR, "config-unknown-key", file,
+        `\`${key}\` is not a .tot/config.json key — the platform never reads it`,
+        renamed ? `use \`${renamed}\`` : `known keys: ${TOT_CONFIG_KEYS.join(", ")}`));
+    }
+  }
+  if (config.siteType !== undefined && !SITE_TYPES.includes(config.siteType)) {
+    out.push(mk(ERROR, "config-site-type", file, `\`siteType\` is "${config.siteType}" — must be one of ${SITE_TYPES.join(", ")}`));
+  }
+  /** @type {Array<[string, string[]]>} */
+  const objectFields = [["compliance", COMPLIANCE_KEYS], ["features", FEATURE_KEYS]];
+  for (const [field, known] of objectFields) {
+    const value = config[field];
+    if (value === undefined) continue;
+    if (!isObject(value)) {
+      out.push(mk(ERROR, `config-${field}`, file, `\`${field}\` must be an object`));
+      continue;
+    }
+    for (const key of Object.keys(value)) {
+      if (!known.includes(key)) {
+        out.push(mk(ERROR, `config-${field}-unknown-key`, `${file} ${field}`,
+          `\`${field}.${key}\` is not a ${field} key — nothing renders from it`,
+          `known keys: ${known.join(", ")}`));
+      }
+    }
+  }
+  if (config.capabilities !== undefined && !isObject(config.capabilities)) {
+    out.push(mk(ERROR, "config-capabilities", file, "`capabilities` must be an object"));
+  }
+  return out;
+}

package/src/tot-repo-mappings.mjs

@@ -0,0 +1,153 @@
+/**
+ * `.tot/config.json` mapping resolution — the ONE reading of a store repo's
+ * declared layout, shared by every consumer: the hosted reconcile (preview,
+ * candidate, aggregate, publication), `tot dev`'s checkout graft, `tot validate`,
+ * the platform's materialize / asset-repair scripts, and this kit's
+ * `repair-tenant-config.mjs`. The platform imports this file from the kit.
+ *
+ * A mapping is `{ workspace, repo, kind }`:
+ *   - `workspace` — where the files physically live in the store repo. It is the
+ *     only source of truth for location; nothing assumes a `tenants/<id>/` layout
+ *     inside the store's own repo.
+ *   - `repo` — the storefront artifact target, `tenants/<segment>/<rel>`. Only
+ *     `<rel>` (the tenant-relative path: `theme.json`, `content/`, `public/`, …)
+ *     is read from it. The tenant namespace always comes from the CANONICAL
+ *     tenant id — the store's registered id hosted, the config's `tenant` locally
+ *     — never from `<segment>`, so a config whose segment disagrees with its
+ *     tenant id resolves identically on every surface.
+ *
+ * Pure and dependency-free so kit tools, platform `.mjs` scripts and TypeScript
+ * consumers (types in the adjacent `.d.mts`) all import it. The published CLI
+ * installs without the kit, so it ships a byte-identical copy that its own test
+ * suite holds equal to this file.
+ */
+
+/** Platform test tenants nest one level deeper: `tenants/e2e/<id>.e2e.test/`. */
+const TARGET_RE = /^tenants\/(?:e2e\/([^/]+\.e2e\.test)|([^/]+))(?:\/(.*))?$/;
+
+/**
+ * Split a declared mapping target into the tenant segment it names and the
+ * tenant-relative path it addresses. Null when the target is not under
+ * `tenants/<segment>/`, or when its relative part is not a clean path (empty,
+ * `.` or `..` segments) — such a target could address outside the tenant.
+ * A trailing `/` (tree target) is preserved on `rel`; the tenant root is `""`.
+ * @param {unknown} repo
+ * @returns {{ segment: string, rel: string } | null}
+ */
+export function parseMappingTarget(repo) {
+  if (typeof repo !== "string") return null;
+  const m = TARGET_RE.exec(repo);
+  if (!m) return null;
+  const segment = m[1] ?? m[2];
+  const rel = m[3] ?? "";
+  const parts = rel.replace(/\/$/, "").split("/");
+  if (rel && parts.some((p) => !p || p === "." || p === "..")) return null;
+  return { segment, rel };
+}
+
+/** The canonical artifact root for a tenant: `tenants/<tenantId>/`. */
+export function tenantArtifactRoot(tenantId) {
+  return `tenants/${tenantId}/`;
+}
+
+function asDir(path) {
+  return path === "" || path.endsWith("/") ? path : `${path}/`;
+}
+
+function mappingsOf(config) {
+  return Array.isArray(config?.mappings) ? config.mappings : [];
+}
+
+/**
+ * Map a tenant-repo path to its tenant-relative path (e.g. `content/home.json`).
+ * First match wins; a `file` mapping matches exactly, a `tree` mapping by prefix.
+ * Null when no mapping covers the path or the covering mapping's target is not
+ * a valid tenant target.
+ * @param {{ mappings?: unknown }} config
+ * @param {string} workspacePath
+ * @returns {string | null}
+ */
+export function mapWorkspaceToTenantRelative(config, workspacePath) {
+  for (const m of mappingsOf(config)) {
+    if (!m || typeof m !== "object" || typeof m.workspace !== "string") continue;
+    if (m.kind === "file") {
+      if (workspacePath !== m.workspace) continue;
+      const target = parseMappingTarget(m.repo);
+      return target ? target.rel : null;
+    }
+    if (m.kind === "tree") {
+      const ws = asDir(m.workspace);
+      if (!workspacePath.startsWith(ws)) continue;
+      const target = parseMappingTarget(m.repo);
+      return target ? asDir(target.rel) + workspacePath.slice(ws.length) : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Map a tenant-repo path to its storefront artifact path under the CANONICAL
+ * tenant root (`tenants/<tenantId>/<rel>`). Null when unmapped.
+ * @param {{ mappings?: unknown }} config
+ * @param {string} tenantId
+ * @param {string} workspacePath
+ * @returns {string | null}
+ */
+export function mapWorkspaceToArtifact(config, tenantId, workspacePath) {
+  const rel = mapWorkspaceToTenantRelative(config, workspacePath);
+  return rel === null ? null : tenantArtifactRoot(tenantId) + rel;
+}
+
+/**
+ * The inverse: where a tenant-relative path (`theme.json`, `content`, `public`,
+ * `content/home.json`) lives in the tenant repo, per the declared mappings.
+ * Unmapped paths resolve to themselves — the flat checkout layout — so a
+ * consumer still finds files the mappings do not cover (and the config-coverage
+ * check reports the gap).
+ * @param {{ mappings?: unknown }} config
+ * @param {string} relPath tenant-relative, no leading `/`
+ * @returns {string}
+ */
+export function workspacePathForTenantRelative(config, relPath) {
+  const bare = relPath.replace(/\/$/, "");
+  for (const m of mappingsOf(config)) {
+    if (!m || typeof m !== "object" || typeof m.workspace !== "string") continue;
+    const target = parseMappingTarget(m.repo);
+    if (!target) continue;
+    const targetRel = target.rel.replace(/\/$/, "");
+    const ws = m.workspace.replace(/\/$/, "");
+    if (m.kind === "file") {
+      if (targetRel === bare) return ws;
+      continue;
+    }
+    if (m.kind !== "tree") continue;
+    if (targetRel === bare) return ws;
+    const prefix = asDir(targetRel);
+    if (bare.startsWith(prefix)) {
+      const rest = bare.slice(prefix.length);
+      return ws ? `${ws}/${rest}` : rest;
+    }
+  }
+  return bare;
+}
+
+/**
+ * Mappings whose declared target names a tenant segment other than the
+ * canonical tenant id. They still resolve correctly (the segment is never
+ * read); this exists so validators can tell the author the config disagrees
+ * with itself.
+ * @param {{ mappings?: unknown }} config
+ * @param {string} tenantId
+ * @returns {{ workspace: string, repo: string, segment: string }[]}
+ */
+export function foreignTenantSegments(config, tenantId) {
+  const out = [];
+  for (const m of mappingsOf(config)) {
+    if (!m || typeof m !== "object") continue;
+    const target = parseMappingTarget(m.repo);
+    if (target && target.segment !== tenantId) {
+      out.push({ workspace: String(m.workspace ?? ""), repo: m.repo, segment: target.segment });
+    }
+  }
+  return out;
+}

package/src/validate.mjs

@@ -5,7 +5,7 @@
  *
  * Design principle — "valid locally ≡ will reconcile in storefront": these checks
  * mirror the reconcile pipeline's own gate (@tot/private-controlplane
- * customization-reconcile.ts `mapToArtifact` / `validateRawHtml`). Kept in step
+ * customization-reconcile.ts `validateMappingShape` / `validateRawHtml`, and the shared mapping resolver `tot-repo-mappings.mjs`). Kept in step
  * with the in-repo source of truth `scripts/tenant/validate.mjs` (which the CI
  * regression test imports) — including its platform-route awareness (commerce
  * tenants own /collections, /products/<handle>, /search, /saved, /account, /cart,
@@ -17,6 +17,20 @@
  */
 import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
+import { validateDeclaredConfig } from "./declared-config.mjs";
+import {
+  foreignTenantSegments,
+  parseMappingTarget,
+  workspacePathForTenantRelative,
+} from "./tot-repo-mappings.mjs";
+
+export {
+  TOT_CONFIG_KEYS,
+  COMPLIANCE_KEYS,
+  FEATURE_KEYS,
+  SITE_TYPES,
+  validateDeclaredConfig,
+} from "./declared-config.mjs";
 
 const NUL = String.fromCharCode(0);
 export const ERROR = "error";
@@ -63,74 +77,10 @@ const hasScanExt = (p) => CONFLICT_SCAN_EXT.has((p.match(/\.[^./\\]+$/) || [""])
 const KNOWN_KINDS = new Set(["file", "tree"]);
 const REQUIRED_WORKSPACES = ["content/", "public/", "theme.json"];
 
-// The keys the platform reads in `.tot/config.json`. Mirrors
-// packages/public-runtime/src/declared-tenant-config.mjs (this package ships to npm
-// on its own); test/declared-config-parity.test.mjs pins the two together, so a
-// field the platform honors can never be refused here, and a key no surface reads
-// can never pass.
-export const TOT_CONFIG_KEYS = [
-  "$schema", "tenant", "scope", "mappings", "hostPlatform", "sample", "seed",
-  "siteType", "compliance", "capabilities", "features",
-];
-// Keys other tooling has written that the platform does NOT read, with the key it does.
-const RENAMED_CONFIG_KEYS = { appDomain: "scope", tenantId: "tenant" };
-export const COMPLIANCE_KEYS = [
-  "ruleProfile", "minAge", "nicotineWarning", "shippingRestriction", "pactAct",
-  "adultSignature", "prop65", "purchaseLimit", "stateEligibility", "exciseTax",
-];
-export const FEATURE_KEYS = [
-  "catalog", "productSearch", "savedItems", "quickView", "newsletter", "commerceSitemap", "productJsonLd", "ageGate",
-];
-export const SITE_TYPES = ["commerce", "marketing"];
-
-const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
-
-/**
- * Refuse what the platform would silently ignore: an unknown top-level key, an
- * unknown `compliance`/`features` key, or a declared field of the wrong shape. Each
- * one passes JSON parsing and renders nothing — on a regulated store that is a
- * mandated notice that never appears.
- * @returns {Finding[]}
- */
-export function validateDeclaredConfig(config, file = ".tot/config.json") {
-  const out = [];
-  for (const key of Object.keys(config)) {
-    if (!TOT_CONFIG_KEYS.includes(key)) {
-      const renamed = RENAMED_CONFIG_KEYS[key];
-      out.push(mk(ERROR, "config-unknown-key", file,
-        `\`${key}\` is not a .tot/config.json key — the platform never reads it`,
-        renamed ? `use \`${renamed}\`` : `known keys: ${TOT_CONFIG_KEYS.join(", ")}`));
-    }
-  }
-  if (config.siteType !== undefined && !SITE_TYPES.includes(config.siteType)) {
-    out.push(mk(ERROR, "config-site-type", file, `\`siteType\` is "${config.siteType}" — must be one of ${SITE_TYPES.join(", ")}`));
-  }
-  /** @type {Array<[string, string[]]>} */
-  const objectFields = [["compliance", COMPLIANCE_KEYS], ["features", FEATURE_KEYS]];
-  for (const [field, known] of objectFields) {
-    const value = config[field];
-    if (value === undefined) continue;
-    if (!isObject(value)) {
-      out.push(mk(ERROR, `config-${field}`, file, `\`${field}\` must be an object`));
-      continue;
-    }
-    for (const key of Object.keys(value)) {
-      if (!known.includes(key)) {
-        out.push(mk(ERROR, `config-${field}-unknown-key`, `${file} ${field}`,
-          `\`${field}.${key}\` is not a ${field} key — nothing renders from it`,
-          `known keys: ${known.join(", ")}`));
-      }
-    }
-  }
-  if (config.capabilities !== undefined && !isObject(config.capabilities)) {
-    out.push(mk(ERROR, "config-capabilities", file, "`capabilities` must be an object"));
-  }
-  return out;
-}
 
 /**
  * Validate a parsed `.tot/config.json` against the shape the reconcile pipeline
- * (`mapToArtifact`) requires. Pure — no I/O.
+ * (`validateMappingShape`) requires. Pure — no I/O.
  * @returns {Finding[]}
  */
 export function validateConfigShape(config, file = ".tot/config.json") {
@@ -155,18 +105,29 @@ export function validateConfigShape(config, file = ".tot/config.json") {
     }
     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.
+    // THE regression guard: reconcile reads the tenant-relative target out of
+    // m.repo and only knows "file" vs tree — a missing/unparseable repo or
+    // kind:"dir" is refused there, so refuse it here first.
     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)`,
+          `mapping for "${m.workspace ?? "?"}" is missing a string \`repo\` (the reconcile refuses it)`,
           `add "repo": "tenants/${config.tenant ?? "<id>"}/${(m.workspace ?? "").replace(/\/+$/, "")}${m.kind === "file" ? "" : "/"}"`),
       );
+    } else {
+      const target = parseMappingTarget(m.repo);
+      if (!target) {
+        out.push(
+          mk(ERROR, "mapping-repo", at,
+            `mapping for "${m.workspace ?? "?"}" targets "${m.repo}" — \`repo\` must be a clean path under tenants/<id>/ (the reconcile refuses it)`,
+            `e.g. "repo": "tenants/${config.tenant ?? "<id>"}/content/"`),
+        );
+      } else {
+        // Coverage is about WHAT is mapped (the target), not where it lives.
+        seen.add(target.rel.replace(/\/+$/, "") + (m.kind === "tree" ? "/" : ""));
+        seen.add(target.rel);
+      }
     }
     if (!KNOWN_KINDS.has(m.kind)) {
       out.push(
@@ -1091,16 +1052,9 @@ 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)
+  // 1. .tot/config.json — shape (flow-back readiness). Read first: its mappings
+  // say where theme.json / content/ / public/ live in this tree.
   const configPath = join(tenantDir, ".tot", "config.json");
   let config = null;
   if (existsSync(configPath)) {
@@ -1111,14 +1065,46 @@ export function validateTenant(tenantDir, opts = {}) {
       config = value;
       findings.push(...validateConfigShape(value, ".tot/config.json"));
     }
-  } else {
+  }
+  const located = (tenantRel) => join(tenantDir, workspacePathForTenantRelative(config, tenantRel));
+  const contentDir = located("content");
+  const publicDir = located("public");
+  const pagesDir = join(contentDir, "pages-html");
+
+  // 0. basic layout
+  if (!existsSync(contentDir)) {
+    findings.push(mk(ERROR, "layout", rel(contentDir) + "/", `no ${rel(contentDir)}/ directory`));
+  }
+
+  if (!existsSync(configPath)) {
     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)"),
     );
   }
   const scope = opts.scope || config?.scope;
-  const activeTenantId = opts.tenantId || scope || config?.tenant;
+  // The canonical tenant id: the one the asset rule binds to and the one the
+  // mappings' targets resolve under — never a directory name.
+  const activeTenantId = opts.tenantId || config?.tenant || scope;
+  if (config && activeTenantId) {
+    for (const f of foreignTenantSegments(config, activeTenantId)) {
+      findings.push(
+        mk(WARN, "mapping-tenant-segment", ".tot/config.json",
+          `mapping for "${f.workspace}" targets "${f.repo}", naming tenant "${f.segment}" — this store is "${activeTenantId}". ` +
+            `It still resolves under tenants/${activeTenantId}/ (the segment is not read), and its assets are served at /tenants/${activeTenantId}/...`,
+          `write "repo": "tenants/${activeTenantId}/${parseMappingTarget(f.repo)?.rel ?? ""}" so the config agrees with itself ` +
+            `(the agency kit's tools/repair-tenant-config.mjs rewrites the whole config)`),
+      );
+    }
+  }
+  // Publication refuses a config whose `scope` is not the store's id.
+  if (config && typeof config.tenant === "string" && config.scope !== config.tenant) {
+    findings.push(
+      mk(WARN, "config-scope-mismatch", ".tot/config.json",
+        `"scope" is ${JSON.stringify(config.scope ?? null)} but "tenant" is "${config.tenant}" — publication refuses a config whose scope is not the store's id`,
+        `set "scope" to "${config.tenant}" (the agency kit's tools/repair-tenant-config.mjs rewrites the whole config)`),
+    );
+  }
   // 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";
@@ -1128,18 +1114,18 @@ export function validateTenant(tenantDir, opts = {}) {
   }
 
   // 2. theme.json — parse (a malformed one is a WHOLE-APP BUILD FAILURE)
-  const themePath = join(tenantDir, "theme.json");
+  const themePath = located("theme.json");
   if (existsSync(themePath)) {
     const { error } = readJsonSafe(themePath);
     if (error) {
       findings.push(
-        mk(ERROR, "theme-parse", "theme.json",
+        mk(ERROR, "theme-parse", rel(themePath),
           `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");
+  const capabilitiesPath = located("capabilities.json");
   if (existsSync(capabilitiesPath)) {
     const { value, error } = readJsonSafe(capabilitiesPath);
     if (error) {
@@ -1149,7 +1135,7 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
-  const scriptsPath = join(tenantDir, "scripts.json");
+  const scriptsPath = located("scripts.json");
   if (existsSync(scriptsPath)) {
     const { value, error } = readJsonSafe(scriptsPath);
     if (error) {
@@ -1159,7 +1145,7 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
-  const embedsPath = join(tenantDir, "embeds.json");
+  const embedsPath = located("embeds.json");
   if (existsSync(embedsPath)) {
     const { value, error } = readJsonSafe(embedsPath);
     if (error) {
@@ -1259,9 +1245,7 @@ export function validateTenant(tenantDir, opts = {}) {
   // 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)),
+    ...[themePath, capabilitiesPath, scriptsPath, configPath].filter((p) => existsSync(p)),
   ];
   for (const p of conflictScanFiles) {
     const lines = detectConflictMarkers(readFileSync(p, "utf8"));
@@ -1280,9 +1264,8 @@ export function validateTenant(tenantDir, opts = {}) {
   // origin, is blocking; advisory (info) when there's no embeds.json to compare.
   {
     let declaredEmbeds = null;
-    const embedsFile = join(tenantDir, "embeds.json");
-    if (existsSync(embedsFile)) {
-      const { value } = readJsonSafe(embedsFile);
+    if (existsSync(embedsPath)) {
+      const { value } = readJsonSafe(embedsPath);
       if (Array.isArray(value)) declaredEmbeds = new Set(value.filter((s) => typeof s === "string"));
     }
     for (const file of walk(contentDir, (p) => p.endsWith(".html"))) {