@tokenoftrust/storefront-runner 2.2.96 → 2.2.98

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.2.96",
+  "version": "2.2.98",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/cli/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/packages/cli/src/visual-parity.mjs

@@ -1,11 +1,13 @@
 /**
  * Read-only closure checks for the optional visual-parity migration module.
- * The tenant checkout remains portable: this reads only content/, public/, and
- * .tot/visual-parity.json, never a preview host or a delivery provider.
+ * The tenant checkout remains portable: this reads only content/, public/ and theme.json (where
+ * `.tot/config.json` maps them) and .tot/visual-parity.json, never a preview host or a delivery
+ * provider.
  */
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { extname, join, relative } from "node:path";
+import { workspacePathForTenantRelative } from "./tot-repo-mappings.mjs";
 
 const ERROR = "error";
 // Public routes implemented by the renderer. Authentication and cart URLs are
@@ -59,10 +61,10 @@ function parseConfig(tenantDir) {
   }
 }
 
-function tenantFromConfig(tenantDir) {
+/** The checkout's `.tot/config.json`, or null when absent or unreadable. */
+function readTotConfig(tenantDir) {
   try {
-    const value = JSON.parse(readFileSync(join(tenantDir, ".tot", "config.json"), "utf8"));
-    return typeof value?.tenant === "string" ? value.tenant : null;
+    return JSON.parse(readFileSync(join(tenantDir, ".tot", "config.json"), "utf8"));
   } catch { return null; }
 }
 
@@ -278,7 +280,11 @@ export function validateVisualParityClosure(tenantDir, options = {}) {
   const findings = [];
   const { value: config, findings: configFindings } = parseConfig(tenantDir);
   findings.push(...configFindings);
-  const pagesDir = join(tenantDir, "content", "pages");
+  // Files are found where the checkout's `.tot/config.json` mappings declare them, as `tot validate`
+  // and the hosted reconcile find them.
+  const totConfig = readTotConfig(tenantDir);
+  const located = (rel) => join(tenantDir, workspacePathForTenantRelative(totConfig, rel));
+  const pagesDir = located("content/pages");
   const files = walk(pagesDir).filter((file) => file.endsWith(".json")).sort();
   if (files.length === 0) findings.push(finding("parity-pages-missing", "content/pages/", "no page JSON files define the visual-parity route scope", "add the paired authored page records under content/pages/ before closing parity"));
   const pages = [];
@@ -297,17 +303,17 @@ export function validateVisualParityClosure(tenantDir, options = {}) {
   const routes = new Set(["/"]);
   for (const page of pages) routes.add(normalizeRoute(page.value.slug));
   /** @type {{findings:ParityFinding[], tenantId:string|null, publicDir:string, routes:Set<string>, allowlist:string[], decodeAssets:DecodeAsset[]}} */
-  const context = { findings, tenantId: tenantId ?? tenantFromConfig(tenantDir), publicDir: join(tenantDir, "public"), routes, allowlist: Array.isArray(config.externalNavigationAllowlist) ? config.externalNavigationAllowlist : [], decodeAssets: [] };
+  const context = { findings, tenantId: tenantId ?? (typeof totConfig?.tenant === "string" ? totConfig.tenant : null), publicDir: located("public"), routes, allowlist: Array.isArray(config.externalNavigationAllowlist) ? config.externalNavigationAllowlist : [], decodeAssets: [] };
   if (!context.tenantId) findings.push(finding("parity-tenant-id", ".tot/config.json", "tenant id is required to verify /tenants/<tenant>/ assets", "set tenant in .tot/config.json or pass a resolved tenant id"));
   for (const page of pages) inspectValue(page.value, page.file, [], context);
   for (const name of ["home.json", "chrome.json"]) {
-    const path = join(tenantDir, "content", name);
+    const path = located(`content/${name}`);
     if (existsSync(path)) {
       const value = readStructured(path, `content/${name}`, findings);
       if (value != null) inspectValue(value, `content/${name}`, [], context);
     }
   }
-  const themePath = join(tenantDir, "theme.json");
+  const themePath = located("theme.json");
   if (existsSync(themePath)) {
     const value = readStructured(themePath, "theme.json", findings);
     if (value != null) inspectValue(value, "theme.json", [], context);

package/packages/public-runtime/src/static-bundle.ts

@@ -44,6 +44,7 @@ import { assetContentType } from "./tenant-assets.js";
 import { formatHtmlCacheControl } from "./html-cache-policy.js";
 import { NATIVE_GA4_SANDBOX_ASSET_PATH } from "./integration/native-ga4-sandbox-asset.mjs";
 import { CONTENT_NAMED_ASSET_PREFIXES } from "./content-named-asset-prefixes.mjs";
+import { resolveRedirect } from "./publication-redirects.mjs";
 
 // ---------------------------------------------------------------------------
 // R2 seam — same structural subset tenant-assets.ts uses (no workers-types dep)
@@ -189,41 +190,15 @@ function isManifestRedirectRule(value: string): boolean {
 }
 
 /**
- * Where a rule sends a request whose path continues `capture` past the rule's directory; null
- * unless the result is a same-origin path. Same semantics as `ruleLocation` in
- * `publication-redirects.mjs` and the CloudFront function — the three are held together by
- * `tests/fixtures/redirect-match-cases.json`.
- */
-function ruleLocation(to: string, capture: string): string | null {
-  const location = to.endsWith("/*") ? `${to.slice(0, -1)}${capture}` : to;
-  return location.startsWith("/") && !location.startsWith("//") && !location.includes("\\")
-    ? location
-    : null;
-}
-
-/**
- * The redirect the manifest declares for `pathname`, as a location, or null. An exact entry wins
- * outright; otherwise the rule with the longest directory that the trailing-slash form of the path
- * starts with decides — and when its location is unusable there is no redirect.
+ * The redirect the manifest declares for `pathname`, as a location, or null — the redirect
+ * contract's own matcher (`publication-redirects.mjs`), so this plane cannot answer differently.
  */
 function staticBundleRedirectLocation(
   redirects: StaticBundleManifest["redirects"],
   pathname: string,
 ): string | null {
   if (!redirects?.length) return null;
-  const path = pathname === "/" || pathname.split("/").pop()?.includes(".")
-    ? pathname
-    : pathname.endsWith("/") ? pathname : `${pathname}/`;
-  let rule: { from: string; to: string } | null = null;
-  for (const redirect of redirects) {
-    if (redirect.from.endsWith("/*")) {
-      const dir = redirect.from.slice(0, -1);
-      if (path.startsWith(dir) && (rule === null || dir.length > rule.from.length - 1)) rule = redirect;
-    } else if (redirect.from === pathname || redirect.from === path) {
-      return redirect.to;
-    }
-  }
-  return rule === null ? null : ruleLocation(rule.to, path.slice(rule.from.length - 1));
+  return resolveRedirect(redirects, pathname)?.location ?? null;
 }
 
 function isManifestRedirectDestination(value: string): boolean {

package/scripts/tenant/validate.mjs

@@ -1386,21 +1386,24 @@ if (isMain) {
     })()
     : baseline;
   const { ok, findings } = result;
+  // exitCode, never exit(): a report written to a pipe is flushed asynchronously, and exit() cuts a
+  // large one off mid-JSON for whoever parses it.
   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${profile ? ` --profile ${profile}` : ""} — ${tenantId ?? dir}\n`);
-  // Named, grouped callouts FIRST — see printLoudAdvisories above.
-  printLoudAdvisories(findings, { log: (s) => console.log(s) });
-  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);
+    process.exitCode = ok ? 0 : 1;
+  } else {
+    const errors = findings.filter((f) => f.level === ERROR);
+    const warns = findings.filter((f) => f.level === WARN);
+    console.log(`\ntot validate${profile ? ` --profile ${profile}` : ""} — ${tenantId ?? dir}\n`);
+    // Named, grouped callouts FIRST — see printLoudAdvisories above.
+    printLoudAdvisories(findings, { log: (s) => console.log(s) });
+    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.exitCode = errors.length === 0 ? 0 : 1;
+  }
 }