@tokenoftrust/storefront-runner 2.2.89 → 2.2.90

package/packages/public-runtime/src/catalog-files.ts

@@ -0,0 +1,51 @@
+/**
+ * A store's own catalog files — the cold content artifact of ADR 0033 — typed for the platform.
+ *
+ * The layout, the validator and the parser live once, in the agency kit's pure catalog module
+ * (`agency-kit/tools/lib/catalog-model/files.mjs`), which the kit's own tools, the renderer, the
+ * reconcile validator and the migration engine all import. This module only narrows its records
+ * to the canonical types in `./product.ts`; the kit's model is pinned to those types field for
+ * field by `scripts/lib/agency-kit-catalog-drift.test.mjs`.
+ */
+import {
+  readCatalogFile as readKitCatalogFile,
+  readCatalogFiles as readKitCatalogFiles,
+  type CatalogStore,
+} from "../../../agency-kit/tools/lib/catalog-model/files.mjs";
+import type { CatalogCollection, CatalogProduct } from "./product.js";
+
+export {
+  CATALOG_ARTIFACT_PREFIX,
+  CATALOG_COLLECTIONS_PREFIX,
+  CATALOG_CONTENT_DIRS,
+  CATALOG_HANDLE_RE,
+  CATALOG_PRODUCTS_PREFIX,
+  CatalogFileError,
+  catalogFileIssues,
+  classifyCatalogPath,
+  declaredAvailability,
+  planCatalogFiles,
+  type CatalogFileKind,
+  type CatalogStore,
+  type InventoryProvider,
+} from "../../../agency-kit/tools/lib/catalog-model/files.mjs";
+
+export type CatalogFileRecord =
+  | { kind: "product"; record: CatalogProduct }
+  | { kind: "collection"; record: CatalogCollection };
+
+/** One validated catalog file as its canonical record. Throws `CatalogFileError`. */
+export function readCatalogFile(relative: string, raw: string, store: CatalogStore): CatalogFileRecord {
+  return readKitCatalogFile(relative, raw, store) as unknown as CatalogFileRecord;
+}
+
+/** A whole validated catalog. Throws `CatalogFileError` naming every failing file. */
+export function readCatalogFiles(
+  entries: Iterable<{ path: string; raw: string | null }>,
+  store: CatalogStore,
+): { products: CatalogProduct[]; collections: CatalogCollection[] } {
+  return readKitCatalogFiles(entries, store) as unknown as {
+    products: CatalogProduct[];
+    collections: CatalogCollection[];
+  };
+}

package/packages/public-runtime/src/tenant.ts

@@ -622,6 +622,25 @@ export interface TenantConfig {
      */
     htmlCachePolicy?: HtmlCachePolicy;
   };
+  /**
+   * Catalog serving (ADR 0033). The store's own `content/catalog/` files are the
+   * system of record; this declares which artifact serves reads.
+   *
+   * `"files"` (the default): the store's catalog files, then the platform's
+   * grandfathered in-repo snapshot for the same data scope, then an empty catalog.
+   * `"d1"`: the derived D1 serving projection, read on the control plane only.
+   * Never inferred from a tenant id.
+   */
+  catalog?: {
+    serving?: "files" | "d1";
+  };
+  /**
+   * Availability (hot) provider (ADR 0033). Availability is never read from catalog
+   * content files. Absent ⇒ `"mirror"`, the only implemented provider.
+   */
+  inventory?: {
+    provider: "mirror" | "live-hydrate" | "tot-authoritative";
+  };
   /**
    * Storefront product/subscription state — the paywall the platform gates GO-LIVE
    * on. This is the storefront's

package/scripts/dev/standalone-graft-plan.mjs

@@ -1,24 +1,46 @@
 // @ts-check
 /**
  * Pure planning for `tot dev --workspace` grafts: which checkout-relative paths
- * get copied into the in-tree `tenants/<id>/` layout the app globs, and whether
- * each is a file or a directory tree. Decision-only — scripts/tot-dev.mjs does
- * the actual fs copy/backup/watch effects per planned entry.
+ * get copied where in the in-tree `tenants/<id>/` layout the app globs, and
+ * whether each is a file or a directory tree. Decision-only — scripts/tot-dev.mjs
+ * does the actual fs copy/backup/watch effects per planned entry.
+ *
+ * A mapping's `workspace` is where the files live in the checkout; its `repo`
+ * names what they are, tenant-relative (`theme.json`, `content/`, …). They land
+ * under THIS tenant's directory — the same resolution the hosted reconcile uses
+ * (agency-kit/tools/lib/tot-repo-mappings.mjs), whatever tenant segment `repo`
+ * spells — so the dev server serves them at the same `/tenants/<tenant>/…` the
+ * hosted preview does.
  */
+import { tenantDirRelative } from "../lib/tenant-dirs.mjs";
+import { parseMappingTarget } from "../../agency-kit/tools/lib/tot-repo-mappings.mjs";
+
+const TOT_CONFIG = ".tot/config.json";
 
 /**
- * @param {Array<{workspace?: unknown, kind?: unknown}>} mappings the checkout's
- *   own `.tot/config.json` `mappings` array (content/, public/, theme.json, …)
- * @returns {{ workspace: string, isDir: boolean }[]}
+ * @param {string} tenant canonical tenant id (the checkout config's `tenant`)
+ * @param {unknown} mappings the checkout's own `.tot/config.json` `mappings` array
+ *   (content/, public/, theme.json, …)
+ * @returns {{ workspace: string, target: string | null, isDir: boolean }[]} checkout-relative
+ *   `workspace` and repo-relative `target` (POSIX); `target` is null for a mapping whose `repo` is
+ *   not a valid `tenants/<id>/<path>` target, which the caller skips
  */
-export function standaloneGraftPlan(mappings) {
+export function standaloneGraftPlan(tenant, mappings) {
+  const root = tenantDirRelative(tenant);
   const plan = [];
   const seen = new Set();
   for (const map of Array.isArray(mappings) ? mappings : []) {
     const workspace = String(map?.workspace ?? "").replace(/\/+$/, "");
     if (!workspace || seen.has(workspace)) continue;
     seen.add(workspace);
-    plan.push({ workspace, isDir: map?.kind !== "file" });
+    if (workspace === TOT_CONFIG) {
+      plan.push({ workspace, target: `${root}/${TOT_CONFIG}`, isDir: false });
+      continue;
+    }
+    const declared = parseMappingTarget(map?.repo);
+    const rel = declared ? declared.rel.replace(/\/+$/, "") : null;
+    const target = rel === null ? null : rel ? `${root}/${rel}` : root;
+    plan.push({ workspace, target, isDir: map?.kind !== "file" });
   }
   // `.tot/config.json` is never itself one of the declared `mappings` (those map
   // content/public/theme.json) but IS the tenant's own declared platform config
@@ -28,8 +50,8 @@ export function standaloneGraftPlan(mappings) {
   // scripts/tenant/materialize-tenant-content.mjs copies for a Gitea-sourced
   // tenant. Graft it unconditionally so a regulated store's mandated notices
   // resolve from the SAME declared config locally as they would once published.
-  if (!seen.has(".tot/config.json")) {
-    plan.push({ workspace: ".tot/config.json", isDir: false });
+  if (!seen.has(TOT_CONFIG)) {
+    plan.push({ workspace: TOT_CONFIG, target: `${root}/${TOT_CONFIG}`, isDir: false });
   }
   return plan;
 }

package/scripts/tenant/materialize-tenant-content.mjs

@@ -71,6 +71,7 @@ import { tmpdir } from "node:os";
 import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { tenantDirRelative } from "../lib/tenant-dirs.mjs";
+import { parseMappingTarget } from "../../agency-kit/tools/lib/tot-repo-mappings.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(here, "..", "..");
@@ -153,7 +154,13 @@ function canonicalMappings(tenant) {
  */
 export function copyMapping({ checkoutDir, root, tenant, mapping, log = (/** @type {string} */ _m) => {} }) {
   const src = join(checkoutDir, mapping.workspace.replace(/\/+$/, ""));
-  const target = resolveTargetPath(root, tenant, mapping.repo.replace(/\/+$/, ""));
+  // The mapping names WHAT the files are (its tenant-relative target); the
+  // tenant being materialized names WHOSE — never the target's tenant segment.
+  const declared = parseMappingTarget(mapping.repo);
+  if (!declared) {
+    throw new Error(`mapping target "${mapping.repo}" escapes tenants/${tenant}/ — refusing`);
+  }
+  const target = resolveTargetPath(root, tenant, `tenants/${tenant}/${declared.rel}`.replace(/\/+$/, ""));
   if (target === resolve(root, tenantDirRelative(tenant))) {
     throw new Error("mapping target cannot replace the tenant root");
   }

package/scripts/tenant/validate.mjs

@@ -5,7 +5,7 @@
  * 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)
+ *     / missing-`repo` mapping makes the flow-back reconcile refuse it)
  *   · 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
@@ -15,7 +15,7 @@
  *
  * 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.
+ * customization-reconcile.ts `validateMappingShape` / `validateRawHtml`, and the shared mapping resolver `tot-repo-mappings.mjs`). Keep them in step.
  *
  * Dependency-free. Two modes (mirrors scripts/tot-dev.mjs):
  *   node scripts/tenant/validate.mjs <tenant>                # monorepo: tenants/<tenant>/
@@ -38,6 +38,11 @@ import {
   isSafeRehostedAssetPathForTenant,
   isSafeStorefrontHref,
 } from "../../packages/public-runtime/src/extension-contract-values.mjs";
+import {
+  foreignTenantSegments,
+  parseMappingTarget,
+  workspacePathForTenantRelative,
+} from "../../agency-kit/tools/lib/tot-repo-mappings.mjs";
 import { validateVisualParityClosure } from "../../packages/cli/src/visual-parity.mjs";
 
 /** Catalogued embed slugs a tenant may opt into (mirror of EMBED_PROVIDERS). */
@@ -97,7 +102,7 @@ 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.
+ * (`validateMappingShape`) 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[]}
@@ -123,18 +128,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(
@@ -998,16 +1014,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)) {
@@ -1018,7 +1027,18 @@ 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)",
@@ -1031,7 +1051,28 @@ export function validateTenant(tenantDir, opts = {}) {
     );
   }
   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";
@@ -1041,18 +1082,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) {
@@ -1062,7 +1103,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) {
@@ -1072,7 +1113,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) {
@@ -1177,9 +1218,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"));
@@ -1200,9 +1239,8 @@ export function validateTenant(tenantDir, opts = {}) {
   // 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 (existsSync(embedsPath)) {
+      const { value } = readJsonSafe(embedsPath);
       if (Array.isArray(value)) declaredEmbeds = value.filter((s) => typeof s === "string");
     }
     for (const f of lintTenantEmbeds({ dir: contentDir, declared: declaredEmbeds }).findings) {

package/scripts/tot-dev.mjs

@@ -62,7 +62,7 @@ import {
 import { dirname, resolve, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveDevSourceRoot } from "./dev/tenant-source-root.mjs";
-import { tenantDirRelative, tenantDirSegments } from "./lib/tenant-dirs.mjs";
+import { tenantDirSegments } from "./lib/tenant-dirs.mjs";
 import { firstFreePort, isPortFree } from "./dev/port-check.mjs";
 import { busyPortMessage, classifyBusyPort, lockPort, unlockPort } from "./dev/port-lock.mjs";
 import { resync, startWatch } from "./dev/checkout-watch.mjs";
@@ -276,12 +276,12 @@ if (workspacePath) {
   console.log(`  checkout: ${wsRoot}`);
 
   /**
-   * Graft one checkout path (`wsRel`, checkout-relative) into the in-tree
-   * `tenants/<tenant>/` layout the app globs, with the same move-aside/restore +
-   * watch-and-resync machinery every mapping gets. Returns true if grafted.
+   * Graft one checkout path (`wsRel`, checkout-relative) to `repoRel` in the
+   * in-tree `tenants/<tenant>/` layout the app globs, with the same
+   * move-aside/restore + watch-and-resync machinery every mapping gets. Returns
+   * true if grafted.
    */
-  function graftOne(wsRel, isDir) {
-    const repoRel = join(tenantDirRelative(tenant), wsRel);
+  function graftOne(wsRel, repoRel, isDir) {
 
     const source = resolve(wsRoot, wsRel); // real files in the checkout
     const target = resolve(repoRoot, repoRel); // where the app globs them
@@ -320,19 +320,19 @@ if (workspacePath) {
     return true;
   }
 
-  // `workspace` is the checkout-relative prefix (e.g. "content/", "theme.json").
-  // COLOCATION: a tenant IS the repo-root dir `tenants/<id>/`, and the checkout
-  // (a `git subtree split --prefix=tenants/<id>` of that dir) has the SAME layout
-  // at its root — so the graft is an identity map: content/ -> tenants/<id>/content/,
-  // public/ -> tenants/<id>/public/, theme.json -> tenants/<id>/theme.json. We map
-  // structurally (ignoring any legacy `repo` field in the checkout's .tot/config.json).
-  // standaloneGraftPlan ALSO appends `.tot/config.json` unconditionally — see its
-  // own doc comment. Its success does NOT count toward "did we graft a usable
-  // site" below: a checkout with config but no content/public/theme is still
-  // nothing to serve.
+  // Each mapping's checkout files land where its `repo` says, under THIS tenant's
+  // directory (see scripts/dev/standalone-graft-plan.mjs) — resolved exactly as
+  // the hosted reconcile resolves them. standaloneGraftPlan ALSO appends
+  // `.tot/config.json` unconditionally — see its own doc comment. Its success does
+  // NOT count toward "did we graft a usable site" below: a checkout with config but
+  // no content/public/theme is still nothing to serve.
   let mappedCount = 0;
-  for (const { workspace, isDir } of standaloneGraftPlan(mappings)) {
-    const grafted = graftOne(workspace, isDir);
+  for (const { workspace, target, isDir } of standaloneGraftPlan(tenant, mappings)) {
+    if (!target) {
+      console.warn(`  ⚠ mapping for "${workspace}" has no valid "repo" under tenants/<id>/ — skipping (run tot validate)`);
+      continue;
+    }
+    const grafted = graftOne(workspace, target, isDir);
     if (workspace === ".tot/config.json") {
       if (!grafted) console.warn(`  ⚠ checkout has no .tot/config.json — compliance/capabilities/siteType resolve undeclared.`);
       continue;