@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

package/scripts/build/copy-tenant-assets.mjs

@@ -16,12 +16,20 @@
  * Idempotent: it wipes+rewrites the destination on every run. `TENANT_ASSETS_DEST`
  * overrides the destination (used by tests / spikes).
  *
- * VERSIONED TENANTS (decision `assets-r2-versioned`): a tenant whose assets are
+ * VERSIONED TENANTS: a tenant whose assets are
  * served version-scoped from R2 (src/pages/tenants/[id]/[...path].ts) must NOT be
  * baked here — otherwise the static file would shadow the R2 route. Opt a tenant
  * out by adding a `tenants/<id>/.tot/assets-versioned` marker file, or by listing
  * its id in the `TENANT_ASSETS_VERSIONED` env (comma-separated). Non-versioned
- * tenants keep the baked path unchanged (back-compat).
+ * tenants are baked here.
+ *
+ * TENANT_ASSETS_BAKE_VERSIONED=1 overrides ALL of the above and bakes every
+ * tenant's public/ regardless of versioned-ness. Set by the STATIC-plane bundle
+ * build (scripts/publish/materialize-tenant.mjs): the S3/CloudFront static site
+ * has no R2 asset route — a bundle is self-contained by definition — so
+ * skipping a versioned tenant's assets there just produces a bundle whose pages
+ * reference files that don't exist. The Worker-plane build never sets this, so
+ * R2 shadowing semantics are unchanged there.
  */
 import { cp, mkdir, readdir, rm } from "node:fs/promises";
 import { existsSync } from "node:fs";
@@ -44,9 +52,11 @@ const versionedEnv = new Set(
     .map((s) => s.trim())
     .filter(Boolean),
 );
+const bakeVersioned = process.env.TENANT_ASSETS_BAKE_VERSIONED === "1";
 const isVersioned = (id) =>
-  versionedEnv.has(id) ||
-  existsSync(join(src, id, ".tot", "assets-versioned"));
+  !bakeVersioned &&
+  (versionedEnv.has(id) ||
+    existsSync(join(src, id, ".tot", "assets-versioned")));
 
 let copied = 0;
 let skipped = 0;

package/scripts/dev/ai-edit.mjs

@@ -15,7 +15,7 @@
  * `tot` CLI, so `~/.tot/credentials.json` is directly readable. No token
  * plumbing needed between the CLI and the dev server.
  *
- * Scope (decision `d2-resolved-inline-ai-scope`): content + theme.json ONLY.
+ * Scope: content + theme.json ONLY.
  * The MCP tool enforces this server-side; nothing here widens it.
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from "node:fs";

package/scripts/dev/checkout-watch.mjs

@@ -35,8 +35,8 @@ export function resync(sourceRoot, targetRoot, rel) {
  * RELIABILITY-FIRST: defaults to an mtime POLL, not native `fs.watch`. Native watch
  * is event-driven but LOSSY on macOS — editors that save via write-temp-then-rename
  * (VS Code, vim, JetBrains, …) routinely deliver NO change event on the original
- * path, so the save silently fails to hot-reload (the 2026-07-14 "didn't reload"
- * report). The poll stat()s the tree on a short interval and never misses an edit.
+ * path, so the save silently fails to hot-reload. The poll stat()s the tree on a
+ * short interval and never misses an edit.
  *
  * Opt into event-driven native watch with TOT_DEV_NATIVE_WATCH=1 (it still falls
  * back to polling where recursive watch is unavailable, e.g. Linux). Dependency-free

package/scripts/dev/file-browser.mjs

@@ -5,13 +5,11 @@
  *
  * Follows the scripts/dev delegation pattern (see ai-edit.mjs): all logic lives
  * here, dependency-free and testable under `node --test`; a thin dev-only Vite
- * plugin (dev-plugins/dev-file-browser.mjs — added when C0/C1 integrate) maps
+ * plugin (dev-plugins/dev-file-browser.mjs) maps
  * req/res onto `handleTree` / `handleFile`. Every path is routed through
  * safe-path.mjs; the source root comes from tenant-source-root.mjs (never SSR).
  *
- * Git-status badges (C3 acceptance) layer on when C4's git-status.mjs lands —
- * the tree here carries structure only, so this module owns no git surface and
- * doesn't collide with C4.
+ * The tree here carries structure only, so this module owns no git surface.
  */
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join, extname, sep } from "node:path";
@@ -111,8 +109,8 @@ export function readFile(sourceRoot, relPath) {
   }
 
   const norm = relPath.split(sep).join("/");
-  // The viewer needs the on-disk version (C6 baseVersion) + whether the file is in
-  // the write allowlist (C5 editable vs read-only) — surfaced on every ok read.
+  // The viewer needs the on-disk version (baseVersion) + whether the file is in
+  // the write allowlist (editable vs read-only) — surfaced on every ok read.
   const mtimeMs = st.mtimeMs;
   const writable = matchesWriteAllowlist(norm);
   if (BINARY_EXT.has(extname(norm).toLowerCase())) {

package/scripts/dev/file-writer.mjs

@@ -15,7 +15,7 @@
  * lands on disk (and C1's Monitor timestamps the save→reload) — this module never
  * sends its own reload.
  *
- * Stale-write guard (C6): writeSourceFile/handleWrite accept an optional
+ * Stale-write guard: writeSourceFile/handleWrite accept an optional
  * baseVersion — the mtimeMs the client captured when it opened or last saved the
  * file. If the file on disk has since changed (someone edited it via $EDITOR, git,
  * or the AI ask box while autosave was armed), the write is refused with
@@ -74,7 +74,7 @@ export function writeSourceFile(sourceRoot, relPath, content, opts = {}) {
   } catch {
     /* leaf doesn't exist yet — a new file, which is fine */
   }
-  // Stale-write guard (C6): if the client supplied the version it last saw and the
+  // Stale-write guard: if the client supplied the version it last saw and the
   // file has since changed on disk (or now exists when it expected none), refuse
   // rather than clobber. Omit baseVersion to force-save.
   const baseVersion = opts && opts.baseVersion;
@@ -123,7 +123,7 @@ export function handleWrite(env = process.env, body = {}) {
     return { status: 400, json: { ok: false, status: "no_path", message: "path is required" } };
   }
 
-  const result = writeSourceFile(root.sourceRoot, relPath, body.content, {
+  const result = writeSourceFile(root.sourceRoot, relPath, /** @type {string} */ (body.content), {
     baseVersion: body ? body.baseVersion : undefined,
   });
   const status = result.ok

package/scripts/dev/git-status.mjs

@@ -118,10 +118,10 @@ export function computeDiff(gitCwd, sourceRoot, relPath) {
   } catch {
     workingExists = false;
   }
-  if (workingExists && st.isDirectory()) {
+  if (st && st.isDirectory()) {
     return { ok: false, status: "is_dir", message: `${relPath} is a directory` };
   }
-  if (workingExists) {
+  if (workingExists && st) {
     if (BINARY_EXT.has(extname(posix).toLowerCase())) {
       return { ok: true, path: posix, status: fileStatus(gitCwd, relPath), shown: false, reason: "binary" };
     }

package/scripts/dev/integration-guardrails.mjs

@@ -0,0 +1,498 @@
+/**
+ * integration-guardrails.mjs — make the epic's integration discipline routine and
+ * VISIBLE before a unit branch is folded into the umbrella. One command answers
+ * the four questions the lead integrator otherwise asks (and hand-writes a note
+ * about) for every unit:
+ *
+ *   1. Ownership   — does this branch only touch files inside its declared area,
+ *                    or did it wander into files another in-flight unit owns?
+ *   2. Base drift  — has the umbrella moved far enough ahead of this branch's
+ *                    merge-base that a refresh/rebase is due before folding?
+ *   3. Sibling     — do any files this branch touches ALSO appear on a concurrent
+ *      overlap        issue/ fix/ wip/ impl/ branch (a hot-file collision, e.g.
+ *                     the admin Publish module the whole epic keeps colliding on)?
+ *   4. Focused     — do the scoped lint/typecheck/test commands for the touched
+ *      checks         files actually PASS (not just "did you run something")?
+ *
+ * It then prints a structured **integrator handoff note** (files touched grouped
+ * by area, drift status, overlaps, check results) that the lead can paste straight
+ * into an integration commit/PR instead of composing by hand.
+ *
+ * Design mirrors scripts/preview/*-doctor.sh: findings are ordered so the FIRST
+ * ✗ (blocker) or ⚠ (warning) is the thing to deal with, each carries its remedy,
+ * and the exit code is non-zero when a blocker (a failed focused check) is present
+ * so it is safe to drop into a pre-fold gate.
+ *
+ * The git/exec-driven parts live in `main()`; everything checkable — glob→area
+ * matching, drift classification, sibling-overlap join, check derivation, note
+ * formatting — is a pure exported function with no I/O so it unit-tests under
+ * `node --test` (the scripts/dev convention), with no build step and no deps
+ * beyond node: builtins + the `git` CLI.
+ *
+ * Ownership convention: a branch's area is a list of path globs, declared either
+ *   • inline:  --area 'scripts/dev/**' --area 'docs/dev/**'   (repeatable), or
+ *   • in a manifest `.tot-ownership.json` at the repo root, keyed by branch name:
+ *       { "areas": { "issue/integration-conflict-guardrails": ["scripts/dev/**"] } }
+ * With no area declared the ownership check is SKIPPED (reported as such) — it
+ * never fabricates a verdict it can't back.
+ *
+ * Usage:
+ *   node scripts/dev/integration-guardrails.mjs [--umbrella <ref>] [--area <glob>]...
+ *       [--manifest <path>] [--no-siblings] [--no-checks] [--json]
+ *   # defaults: --umbrella feature/8500-storefront-integration, manifest .tot-ownership.json
+ */
+import { execFileSync } from "node:child_process";
+
+/** Umbrella branch this epic folds into. */
+export const DEFAULT_UMBRELLA = "feature/8500-storefront-integration";
+
+/** Branch-name prefixes that denote a concurrent, in-flight unit. */
+export const UNIT_BRANCH_PREFIXES = ["issue/", "fix/", "wip/", "impl/"];
+
+/**
+ * Compile a path glob to a RegExp. Supports `**` (any chars incl. `/`), `*`
+ * (any chars except `/`), and a trailing `/` as shorthand for a directory prefix
+ * (`scripts/dev/` ≡ `scripts/dev/**`). All other regex metacharacters are escaped.
+ * @param {string} glob
+ * @returns {RegExp}
+ */
+export function globToRegExp(glob) {
+  let g = String(glob).replace(/^\.\//, "");
+  if (g.endsWith("/")) g += "**";
+  let re = "";
+  for (let i = 0; i < g.length; i++) {
+    const c = g[i];
+    if (c === "*") {
+      if (g[i + 1] === "*") {
+        re += ".*";
+        i++;
+      } else {
+        re += "[^/]*";
+      }
+    } else if ("\\^$.|?+()[]{}".includes(c)) {
+      re += "\\" + c;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp("^" + re + "$");
+}
+
+/**
+ * True iff `file` (a posix repo-relative path) matches any of `globs`.
+ * @param {string} file
+ * @param {string[]} globs
+ * @returns {boolean}
+ */
+export function matchesAny(file, globs) {
+  const norm = String(file).replace(/^\.\//, "");
+  return (globs || []).some((g) => globToRegExp(g).test(norm));
+}
+
+/**
+ * Partition touched files into those inside the declared ownership area and those
+ * outside it (cross-area edits that warrant integrator review).
+ * @param {string[]} files
+ * @param {string[]} areaGlobs
+ * @returns {{ declared: boolean, inArea: string[], crossArea: string[] }}
+ */
+export function classifyOwnership(files, areaGlobs) {
+  const declared = Array.isArray(areaGlobs) && areaGlobs.length > 0;
+  if (!declared) return { declared: false, inArea: [...(files || [])], crossArea: [] };
+  const inArea = [];
+  const crossArea = [];
+  for (const f of files || []) {
+    if (matchesAny(f, areaGlobs)) inArea.push(f);
+    else crossArea.push(f);
+  }
+  return { declared: true, inArea, crossArea };
+}
+
+/**
+ * Classify how stale a branch's base is from the count of umbrella commits landed
+ * since the branch's merge-base. `warn` recommends a refresh; `stale` strongly
+ * recommends one before folding.
+ * @param {number} behind  umbrella commits ahead of the merge-base
+ * @param {{ warnAt?: number, staleAt?: number }} [opts]
+ * @returns {{ level: "fresh"|"warn"|"stale", behind: number, recommend: string }}
+ */
+export function classifyBaseDrift(behind, opts = {}) {
+  const warnAt = opts.warnAt ?? 10;
+  const staleAt = opts.staleAt ?? 30;
+  const n = Number.isFinite(behind) ? behind : 0;
+  if (n >= staleAt) {
+    return {
+      level: "stale",
+      behind: n,
+      recommend: `umbrella is ${n} commits ahead of this branch's base — refresh before folding (git merge ${DEFAULT_UMBRELLA}, or rebase) so conflicts surface here, not in the integrator's fold`,
+    };
+  }
+  if (n >= warnAt) {
+    return {
+      level: "warn",
+      behind: n,
+      recommend: `umbrella is ${n} commits ahead — a refresh (git merge ${DEFAULT_UMBRELLA}) is recommended before folding`,
+    };
+  }
+  return { level: "fresh", behind: n, recommend: "base is fresh — no refresh needed" };
+}
+
+/**
+ * Join this branch's touched files against each sibling branch's touched files,
+ * returning the files that appear on at least one sibling (hot-file collisions).
+ * @param {string[]} ourFiles
+ * @param {Record<string, string[]>} siblingFilesByBranch
+ * @returns {Array<{ file: string, branches: string[] }>}
+ */
+export function computeSiblingOverlaps(ourFiles, siblingFilesByBranch) {
+  const ours = new Set(ourFiles || []);
+  /** @type {Map<string, string[]>} */
+  const hits = new Map();
+  for (const [branch, files] of Object.entries(siblingFilesByBranch || {})) {
+    for (const f of files || []) {
+      if (!ours.has(f)) continue;
+      const list = hits.get(f) || [];
+      if (!list.includes(branch)) list.push(branch);
+      hits.set(f, list);
+    }
+  }
+  return [...hits.entries()]
+    .map(([file, branches]) => ({ file, branches: branches.sort() }))
+    .sort((a, b) => a.file.localeCompare(b.file));
+}
+
+/**
+ * Derive the focused check commands implied by a set of touched files — scoped to
+ * what changed rather than the whole `pnpm run check`. Pure/deterministic so the
+ * mapping is unit-tested; the runner in `main()` executes each returned command.
+ *
+ *  • touched `scripts/**` (or storefront dev-plugins/integrations) `*.test.mjs`,
+ *    plus the `.test.mjs` sibling of any touched non-test `.mjs`, → one `node --test`
+ *    over exactly those files.
+ *  • touched `scripts/**` `.mjs`/`.js` → `typecheck:scripts` (checkJs over scripts/).
+ *  • touched `apps/storefront/src/**` `.ts`/`.astro`/`.tsx` → the storefront package typecheck.
+ *
+ * @param {string[]} files
+ * @param {(p: string) => boolean} [existsFn]  whether a repo-relative path exists (for the .test.mjs sibling probe); defaults to always-true
+ * @returns {Array<{ name: string, command: string, args: string[] }>}
+ */
+export function deriveChecks(files, existsFn) {
+  const has = typeof existsFn === "function" ? existsFn : () => true;
+  const list = files || [];
+  const isScript = (f) => /^scripts\//.test(f) || /^apps\/storefront\/(dev-plugins|integrations)\//.test(f);
+
+  /** @type {Set<string>} */
+  const testFiles = new Set();
+  for (const f of list) {
+    if (!isScript(f)) continue;
+    if (f.endsWith(".test.mjs")) {
+      testFiles.add(f);
+    } else if (f.endsWith(".mjs") || f.endsWith(".js")) {
+      const sibling = f.replace(/\.(mjs|js)$/, ".test.mjs");
+      if (has(sibling)) testFiles.add(sibling);
+    }
+  }
+
+  /** @type {Array<{ name: string, command: string, args: string[] }>} */
+  const checks = [];
+  if (testFiles.size > 0) {
+    checks.push({ name: "dev-script tests", command: "node", args: ["--test", ...[...testFiles].sort()] });
+  }
+  if (list.some((f) => /^scripts\/.*\.(mjs|js)$/.test(f))) {
+    checks.push({ name: "scripts typecheck", command: "pnpm", args: ["run", "typecheck:scripts"] });
+  }
+  if (list.some((f) => /^apps\/storefront\/src\/.*\.(ts|tsx|astro)$/.test(f))) {
+    checks.push({ name: "storefront typecheck", command: "pnpm", args: ["--filter", "@tot/storefront", "typecheck"] });
+  }
+  return checks;
+}
+
+/**
+ * @typedef {Object} GuardrailResult
+ * @property {string} branch
+ * @property {string} umbrella
+ * @property {string} mergeBase
+ * @property {string[]} files
+ * @property {{ level: "fresh"|"warn"|"stale", behind: number, recommend: string }} drift
+ * @property {{ declared: boolean, inArea: string[], crossArea: string[] }} ownership
+ * @property {Array<{ file: string, branches: string[] }>} overlaps
+ * @property {Array<{ name: string, ok: boolean, skipped?: boolean, detail?: string }>} checks
+ */
+
+/**
+ * Render the integrator handoff note (markdown) from a result. This is the note
+ * the lead otherwise writes by hand when folding a unit.
+ * @param {GuardrailResult} r
+ * @returns {string}
+ */
+export function formatHandoffNote(r) {
+  const lines = [];
+  lines.push(`### Integration handoff — ${r.branch}`);
+  lines.push("");
+  lines.push(`- **Umbrella:** ${r.umbrella} (merge-base ${short(r.mergeBase)})`);
+  lines.push(`- **Base drift:** ${r.drift.level} (${r.drift.behind} commit(s) behind umbrella)`);
+
+  const own = r.ownership;
+  if (!own.declared) {
+    lines.push(`- **Ownership:** not declared — ${r.files.length} file(s) touched, area unverified`);
+  } else {
+    lines.push(
+      `- **Ownership:** ${own.inArea.length} in-area, ${own.crossArea.length} cross-area` +
+        (own.crossArea.length ? ` ⚠ (${own.crossArea.join(", ")})` : ""),
+    );
+  }
+
+  if (r.overlaps.length) {
+    lines.push(`- **Hot-file overlap:** ${r.overlaps.length} file(s) also on sibling branches ⚠`);
+    for (const o of r.overlaps) lines.push(`    - \`${o.file}\` ↔ ${o.branches.join(", ")}`);
+  } else {
+    lines.push(`- **Hot-file overlap:** none`);
+  }
+
+  if (r.checks.length) {
+    const parts = r.checks.map((c) => `${c.skipped ? "skipped" : c.ok ? "✓" : "✗"} ${c.name}`);
+    lines.push(`- **Focused checks:** ${parts.join(", ")}`);
+  } else {
+    lines.push(`- **Focused checks:** none derived (no checkable files touched)`);
+  }
+
+  lines.push("");
+  lines.push(`**Files touched (${r.files.length}):**`);
+  for (const f of r.files) {
+    const tag = own.declared && own.crossArea.includes(f) ? " ⚠ cross-area" : "";
+    lines.push(`- \`${f}\`${tag}`);
+  }
+  return lines.join("\n");
+}
+
+/** @param {string} sha */
+function short(sha) {
+  return String(sha || "").slice(0, 9);
+}
+
+// ─── git-driven CLI (not covered by unit tests — the pure logic above is) ─────
+
+/** Run git in the repo; returns trimmed stdout, or "" on failure. @param {string[]} args */
+function git(args) {
+  try {
+    return execFileSync("git", args, { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Resolve the umbrella ref to fold against. A worktree's LOCAL umbrella branch is
+ * routinely behind what was last fetched, so prefer `origin/<ref>` when it exists
+ * and is not behind the local ref. If `ref` already names a remote/explicit rev,
+ * it is used as-is.
+ * @param {string} ref
+ * @returns {string}
+ */
+function resolveUmbrella(ref) {
+  if (ref.includes("/") && git(["rev-parse", "--verify", "--quiet", ref])) {
+    // already a remote-tracking or fully-qualified ref the caller chose
+    if (ref.startsWith("origin/") || ref.startsWith("refs/")) return ref;
+  }
+  const remote = `origin/${ref}`;
+  const remoteSha = git(["rev-parse", "--verify", "--quiet", remote]);
+  const localSha = git(["rev-parse", "--verify", "--quiet", ref]);
+  if (!remoteSha) return ref; // no remote-tracking ref — use whatever we were given
+  if (!localSha) return remote;
+  // Use the remote unless the local ref is strictly ahead of it (local has commits
+  // origin lacks — e.g. an integrator working locally ahead of a push).
+  const localAhead = Number(git(["rev-list", "--count", `${remote}..${localSha}`]) || "0");
+  return localAhead > 0 ? ref : remote;
+}
+
+/**
+ * Union of the files this unit changes: commits since the umbrella merge-base,
+ * plus working-tree changes vs HEAD (staged + unstaged), plus untracked files.
+ * Uses prefix-free plumbing (`diff --name-only`, `ls-files --others`) rather than
+ * `status --porcelain` so there is no status-column slicing to get wrong.
+ * @param {string} base
+ * @returns {string[]}
+ */
+function touchedFiles(base) {
+  const set = new Set();
+  const add = (out) => {
+    for (const l of out.split("\n")) if (l.trim()) set.add(l.trim());
+  };
+  if (base) add(git(["diff", "--name-only", `${base}..HEAD`]));
+  add(git(["diff", "--name-only", "HEAD"])); // staged + unstaged vs HEAD
+  add(git(["ls-files", "--others", "--exclude-standard"])); // untracked
+  return [...set].sort();
+}
+
+/** @param {string} branch @param {string} umbrella */
+function branchTouchedFiles(branch, umbrella) {
+  const base = git(["merge-base", branch, umbrella]);
+  if (!base) return [];
+  const out = git(["diff", "--name-only", `${base}..${branch}`]);
+  return out ? out.split("\n").filter(Boolean) : [];
+}
+
+/** @param {string[]} argv */
+function parseArgs(argv) {
+  const opts = {
+    umbrella: DEFAULT_UMBRELLA,
+    areas: /** @type {string[]} */ ([]),
+    manifest: ".tot-ownership.json",
+    siblings: true,
+    checks: true,
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--umbrella") opts.umbrella = argv[++i];
+    else if (a === "--area") opts.areas.push(argv[++i]);
+    else if (a === "--manifest") opts.manifest = argv[++i];
+    else if (a === "--no-siblings") opts.siblings = false;
+    else if (a === "--no-checks") opts.checks = false;
+    else if (a === "--json") opts.json = true;
+    else if (a === "-h" || a === "--help") opts.help = true;
+    else throw new Error(`unknown argument: ${a}`);
+  }
+  return opts;
+}
+
+async function main() {
+  const { readFileSync, existsSync } = await import("node:fs");
+  let opts;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (e) {
+    process.stderr.write(`${e.message}\n`);
+    process.exit(2);
+    return;
+  }
+  if (opts.help) {
+    process.stdout.write(
+      "usage: node scripts/dev/integration-guardrails.mjs [--umbrella <ref>] [--area <glob>]... " +
+        "[--manifest <path>] [--no-siblings] [--no-checks] [--json]\n",
+    );
+    return;
+  }
+
+  const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]) || "HEAD";
+  // Fold against the SHARED umbrella tip, not a possibly-stale local ref: prefer
+  // origin/<umbrella> when it exists AND is at least as advanced as the local ref
+  // (a local umbrella branch in a worktree is routinely behind what was fetched).
+  const umbrella = resolveUmbrella(opts.umbrella);
+  const mergeBase = git(["merge-base", "HEAD", umbrella]);
+  if (!mergeBase) {
+    process.stderr.write(`✗ no merge-base between HEAD and ${umbrella} — is the umbrella fetched?\n`);
+    process.exit(1);
+    return;
+  }
+  const behind = Number(git(["rev-list", "--count", `${mergeBase}..${umbrella}`]) || "0");
+  const files = touchedFiles(mergeBase);
+
+  // Ownership area: explicit --area wins; else manifest keyed by branch name.
+  let areas = opts.areas;
+  if (areas.length === 0 && existsSync(opts.manifest)) {
+    try {
+      const manifest = JSON.parse(readFileSync(opts.manifest, "utf8"));
+      const declared = manifest && manifest.areas && manifest.areas[branch];
+      if (Array.isArray(declared)) areas = declared;
+    } catch {
+      /* a malformed manifest just means "no declared area" */
+    }
+  }
+
+  const drift = classifyBaseDrift(behind);
+  const ownership = classifyOwnership(files, areas);
+
+  /** @type {Record<string, string[]>} */
+  const siblingFiles = {};
+  if (opts.siblings) {
+    const raw = git(["for-each-ref", "--format=%(refname:short)", "refs/heads"]);
+    for (const b of raw.split("\n").filter(Boolean)) {
+      if (b === branch) continue;
+      if (!UNIT_BRANCH_PREFIXES.some((p) => b.startsWith(p))) continue;
+      const bf = branchTouchedFiles(b, umbrella);
+      if (bf.length) siblingFiles[b] = bf;
+    }
+  }
+  const overlaps = computeSiblingOverlaps(files, siblingFiles);
+
+  /** @type {Array<{ name: string, ok: boolean, skipped?: boolean, detail?: string }>} */
+  const checkResults = [];
+  const derived = deriveChecks(files, (p) => existsSync(p));
+  if (!opts.checks) {
+    for (const c of derived) checkResults.push({ name: c.name, ok: true, skipped: true });
+  } else {
+    for (const c of derived) {
+      try {
+        execFileSync(c.command, c.args, { stdio: "pipe", encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
+        checkResults.push({ name: c.name, ok: true });
+      } catch (e) {
+        const tail = String((e && (e.stdout || "")) + (e && (e.stderr || ""))).trim().split("\n").slice(-6).join("\n");
+        checkResults.push({ name: c.name, ok: false, detail: tail });
+      }
+    }
+  }
+
+  /** @type {GuardrailResult} */
+  const result = { branch, umbrella, mergeBase, files, drift, ownership, overlaps, checks: checkResults };
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  } else {
+    renderReport(result);
+    process.stdout.write("\n" + formatHandoffNote(result) + "\n");
+  }
+
+  const blocker = checkResults.some((c) => !c.ok && !c.skipped);
+  process.exit(blocker ? 1 : 0);
+}
+
+/** @param {GuardrailResult} r */
+function renderReport(r) {
+  const ok = (s) => process.stdout.write(`  ✓ ${s}\n`);
+  const bad = (s) => process.stdout.write(`  ✗ ${s}\n`);
+  const warn = (s) => process.stdout.write(`  ⚠ ${s}\n`);
+  const note = (s) => process.stdout.write(`    → ${s}\n`);
+
+  process.stdout.write(`\n== integration guardrails: ${r.branch} → ${r.umbrella} ==\n`);
+
+  // 1. base drift
+  if (r.drift.level === "fresh") ok(`base fresh (${r.drift.behind} behind umbrella)`);
+  else warn(`base drift: ${r.drift.behind} behind umbrella`), note(r.drift.recommend);
+
+  // 2. ownership
+  if (!r.ownership.declared) {
+    warn(`ownership area not declared for ${r.branch}`);
+    note("declare it in .tot-ownership.json (areas[<branch>]) or pass --area <glob> to enable the check");
+  } else if (r.ownership.crossArea.length === 0) {
+    ok(`ownership clean — all ${r.ownership.inArea.length} touched file(s) inside declared area`);
+  } else {
+    warn(`${r.ownership.crossArea.length} cross-area edit(s) outside declared area`);
+    for (const f of r.ownership.crossArea) note(f);
+    note("confirm these are intended, or move them to their owner's branch before folding");
+  }
+
+  // 3. sibling overlap
+  if (r.overlaps.length === 0) ok("no hot-file overlap with sibling unit branches");
+  else {
+    warn(`${r.overlaps.length} file(s) also touched by concurrent unit branch(es)`);
+    for (const o of r.overlaps) note(`${o.file}  ↔  ${o.branches.join(", ")}`);
+    note("coordinate fold order with the integrator; expect a conflict on these — refresh base first");
+  }
+
+  // 4. focused checks
+  if (r.checks.length === 0) ok("no focused checks derived (no checkable files touched)");
+  for (const c of r.checks) {
+    if (c.skipped) note(`check skipped (--no-checks): ${c.name}`);
+    else if (c.ok) ok(`focused check passed: ${c.name}`);
+    else {
+      bad(`focused check FAILED: ${c.name}`);
+      if (c.detail) for (const l of c.detail.split("\n")) note(l);
+    }
+  }
+}
+
+// Run only when invoked directly (not when imported by the test).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}

package/scripts/dev/locate-handler.mjs

@@ -3,12 +3,12 @@
  *   POST /__tot/locate          {domPath, path} → {ok, path, line, col} | {status}
  *   POST /__tot/open-in-editor   {path, line, col} → {ok} | {status}
  *
- * Keeps locate.mjs a PURE parse5 walk (already integrated + tested 5/5); this module
+ * Keeps locate.mjs a PURE parse5 walk; this module
  * adds the env/path-resolution/refusal concerns and is itself unit-testable under
  * `node --test` with no running dev server (the scripts/dev delegation pattern — see
  * file-browser.mjs). The thin dev-plugins/dev-locate.mjs wrapper maps req/res onto it.
  *
- * HONORS decision `click-to-source-anchors-at-content-region`: the served page wraps
+ * The served page wraps
  * the raw content region (<main>, the whole of content/home.html) in the storefront's
  * own chrome (skip-link, header, nav, footer) that is NOT in the tenant source. So we
  * resolve the clicked URL to its raw content source and walk THAT from <body>:
@@ -90,7 +90,7 @@ export function handleLocate(env = process.env, body = {}) {
 
   const html = readFileSync(abs, "utf8");
   const found = locate(html, body.domPath);
-  if (typeof found.line === "number") {
+  if ("line" in found && typeof found.line === "number") {
     return { status: 200, json: { ok: true, path: rel, line: found.line, col: found.col } };
   }
   // The walk missed: the element is outside the raw content region — i.e. the storefront

package/scripts/dev/port-check.mjs

@@ -8,9 +8,9 @@ import net from "node:net";
  * predicts astro's own bind on either IP family.
  *
  * WHY THIS EXISTS: Vite's `strictPort` defaults OFF, so when the requested port is
- * taken astro SILENTLY moves to the next free port. On 2026-07-14 that stranded the
- * CLI's liveness poll on the ORIGINAL port (answered by a stale foreign server) →
- * a false "✨ You're live" pointing at the wrong server. Pre-flighting the port and
+ * taken astro SILENTLY moves to the next free port — stranding the CLI's liveness
+ * poll on the ORIGINAL port (answered by a stale foreign server) → a false
+ * "✨ You're live" pointing at the wrong server. Pre-flighting the port and
  * failing clearly removes that whole class of silent failure.
  *
  * Dependency-free (node:net only) so it copies into the standalone runner and is