@tokenoftrust/storefront-runner 2.2.85 → 2.2.87

package/packages/public-runtime/src/publication-redirects.mjs

@@ -1,379 +1,5 @@
 // @ts-check
-// The pure core that turns a tenant's DECLARED redirects into a substrate-neutral redirect set
-// the publish pipeline can emit.
-//
-// A tenant's public site is served CDN -> static object (ADR 0013), so a redirect cannot be a
-// request-time decision in the Worker: it must exist in the published artifact. Both substrates
-// express it the same way — a precomputed map consulted by the single permitted edge function —
-// so the set below is substrate-neutral and the adapters only serialize it.
-//
-// Redirects are DECLARED, never derived from a tenant id. Three declaration sources normalize into
-// the one `redirect-308` contract `PublicationSpaceAliasV1` already defines:
-//   - publication-space `routes.aliases` entries whose behavior is `redirect-308`;
-//   - a content collection's `redirects.json` (old slug -> new slug), which becomes
-//     `/<collection>/<old>/` -> `/<collection>/<new>/`;
-//   - the tenant-wide `content/redirects.json` (relative path -> relative path or an explicit
-//     HTTPS destination), for legacy URLs that belong to no single collection.
-// Adding a tenant is a declaration, not a code change.
-//
-// 308 rather than 301 throughout: both pass ranking signal, and 308 additionally preserves the
-// request method, so a redirected non-GET is not silently rewritten. The declared alias contract
-// already specifies 308; collection renames join it rather than introducing a second status.
-//
-// Fails closed. An ambiguous declaration (one `from`, two targets), a cycle, or a set that exceeds
-// the substrate's ceiling REFUSES rather than emitting a partial map — a redirect that silently
-// does not exist is the failure this mechanism exists to prevent.
-
-/** The status every materialized redirect carries. */
-export const REDIRECT_STATUS = 308;
-
-/**
- * CloudFront Functions cap total code size at 10 KB, and the map is baked into the one
- * viewer-request function the public path already carries. The emitter refuses above the budget
- * left for it rather than shipping a function that cannot publish.
- */
-export const EDGE_FUNCTION_CODE_LIMIT_BYTES = 10240;
-/** Bump only when the meaning of a whole-site delivery manifest changes without changing its values. */
-export const WHOLE_SITE_DELIVERY_CONTRACT = "whole-site-delivery-v1";
-/** Reserved for the function's own logic, so the map gets the rest. */
-export const EDGE_FUNCTION_RESERVED_BYTES = 2048;
-/** Bytes available to the serialized map. */
-export const REDIRECT_MAP_BUDGET_BYTES =
-  EDGE_FUNCTION_CODE_LIMIT_BYTES - EDGE_FUNCTION_RESERVED_BYTES;
-
-/** JSON is not quite JS: these are legal in a JSON string but terminate a line to a JS parser. */
-const LINE_SEPARATOR = "
";
-const PARAGRAPH_SEPARATOR = "
";
-
-/**
- * @typedef {Object} DeclaredRedirect
- * @property {string} from    root-absolute request path
- * @property {string} to      root-absolute destination path
- * @property {string} source  which declaration produced it, for the report
- */
-
-/**
- * @typedef {Object} RedirectSet
- * @property {boolean} ok
- * @property {{from: string, to: string}[]} redirects  normalized, deduped, chain-collapsed
- * @property {string[]} violations  why it refused; empty when ok
- * @property {number} bytes         serialized size of the map
- * @property {number} budget        bytes available to the map
- */
-
-/**
- * Normalize a declared path to the form the edge function compares against: root-absolute, no
- * query or fragment, with a trailing slash unless the last segment names a file.
- * Returns null when the value cannot be a same-origin request path.
- * @param {string} raw
- * @returns {string | null}
- */
-export function normalizeRedirectPath(raw) {
-  if (typeof raw !== "string") return null;
-  const trimmed = raw.trim();
-  if (!trimmed.startsWith("/")) return null;
-  // Protocol-relative (`//host/...`) would leave the origin.
-  if (trimmed.startsWith("//")) return null;
-  const withoutSuffix = trimmed.split("?")[0].split("#")[0];
-  if (withoutSuffix.includes("..")) return null;
-  const collapsed = withoutSuffix.replace(/\/{2,}/g, "/");
-  if (collapsed === "/") return "/";
-  // The last NON-EMPTY segment: a trailing slash otherwise hides the filename from this test.
-  const segments = collapsed.split("/").filter(Boolean);
-  const last = segments[segments.length - 1] ?? "";
-  const namesFile = last.includes(".");
-  if (namesFile) return collapsed.replace(/\/$/, "");
-  return collapsed.endsWith("/") ? collapsed : `${collapsed}/`;
-}
-
-/**
- * Turn a content collection's `redirects.json` (old slug -> new slug) into declared redirects
- * under that collection's route prefix.
- * @param {string} collection  e.g. "blog"
- * @param {Record<string, unknown>} rows
- * @returns {DeclaredRedirect[]}
- */
-export function redirectsFromCollection(collection, rows) {
-  if (!rows || typeof rows !== "object") return [];
-  /** @type {DeclaredRedirect[]} */
-  const out = [];
-  for (const [oldSlug, newSlug] of Object.entries(rows)) {
-    if (typeof newSlug !== "string" || !oldSlug || !newSlug) continue;
-    out.push({
-      from: `/${collection}/${oldSlug}/`,
-      to: `/${collection}/${newSlug}/`,
-      source: `content/${collection}/redirects.json`,
-    });
-  }
-  return out;
-}
-
-/**
- * Turn the tenant-wide `content/redirects.json` map into root-relative declarations.
- * Its keys and same-origin values are repository paths without a leading slash; an
- * explicit HTTPS destination remains absolute and is validated by `buildRedirectSet`.
- * @param {Record<string, unknown>} rows
- * @returns {DeclaredRedirect[]}
- */
-export function redirectsFromSiteMap(rows) {
-  if (!rows || typeof rows !== "object" || Array.isArray(rows)) {
-    throw new TypeError(
-      "content/redirects.json must be an object mapping relative paths to destinations",
-    );
-  }
-  /** @type {DeclaredRedirect[]} */
-  const out = [];
-  for (const [from, rawTo] of Object.entries(rows)) {
-    if (
-      !from || from.startsWith("/") || typeof rawTo !== "string" || !rawTo || rawTo.startsWith("/")
-    ) {
-      throw new TypeError(
-        "content/redirects.json keys and same-origin destinations must be non-empty paths without a leading slash",
-      );
-    }
-    const rootedFrom = `/${from}`;
-    const isExternal = /^[A-Za-z][A-Za-z0-9+.-]*:/.test(rawTo);
-    const rootedTo = isExternal ? rawTo : `/${rawTo}`;
-    out.push({
-      from: normalizeRedirectPath(rootedFrom) ?? rootedFrom,
-      to: isExternal ? rawTo : normalizeRedirectPath(rootedTo) ?? rootedTo,
-      source: SITE_REDIRECTS_PATH,
-    });
-  }
-  return out;
-}
-
-/**
- * A content collection's redirect declaration, as it appears in a composed bundle's file list.
- * `content/blog/redirects.json` declares redirects for the `blog` collection.
- */
-export const COLLECTION_REDIRECTS_PATH = /^content\/([A-Za-z0-9][A-Za-z0-9_-]*)\/redirects\.json$/;
-
-/** The tenant-wide redirect declaration, for legacy URLs that belong to no single collection. */
-export const SITE_REDIRECTS_PATH = "content/redirects.json";
-
-/**
- * Does this composed file declare redirects the composition lifts into `routes.aliases`?
- * @param {string} path
- * @returns {boolean}
- */
-export function isRedirectDeclarationPath(path) {
-  return path === SITE_REDIRECTS_PATH || COLLECTION_REDIRECTS_PATH.test(path ?? "");
-}
-
-/**
- * Declared redirects for every content collection present in a composed revision.
- *
- * Reads the COMPOSED files rather than a working tree, so the redirects are bound to the same
- * revision as the pages they point at — a rename and its redirect can never publish apart.
- *
- * @param {{path: string, json: unknown}[]} entries  composed files, already parsed
- * @returns {DeclaredRedirect[]}
- */
-export function declaredRedirectsFromContent(entries) {
-  /** @type {DeclaredRedirect[]} */
-  const out = [];
-  for (const entry of entries ?? []) {
-    if (entry?.path === SITE_REDIRECTS_PATH) {
-      out.push(...redirectsFromSiteMap(/** @type {Record<string, unknown>} */ (entry.json)));
-      continue;
-    }
-    const match = COLLECTION_REDIRECTS_PATH.exec(entry?.path ?? "");
-    if (!match) continue;
-    out.push(
-      ...redirectsFromCollection(
-        /** @type {string} */ (match[1]),
-        /** @type {Record<string, unknown>} */ (entry.json),
-      ),
-    );
-  }
-  return out;
-}
-
-/**
- * Normalize a same-origin path or a deliberately external HTTPS destination.
- *
- * A source is always same-origin; a TARGET may leave the origin, but only when the declaration
- * says so in full: `https:` only, no credentials, no query, no fragment. Anything else — including
- * every shape that merely looks absolute — is not a usable destination and refuses.
- * @param {string} raw
- * @returns {string | null}
- */
-function normalizeRedirectDestination(/** @type {string} */ raw) {
-  const sameOrigin = normalizeRedirectPath(raw);
-  if (sameOrigin !== null) return sameOrigin;
-  try {
-    const url = new URL(raw);
-    if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
-      return null;
-    }
-    return url.toString().replace(/\/$/, url.pathname === "/" ? "/" : "");
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Turn publication-space aliases into declared redirects. Only `redirect-308` aliases produce a
- * redirect; a `render` alias is served, not redirected.
- * @param {{from?: string, behavior?: string, to?: string}[]} aliases
- * @param {string} [source]
- * @returns {DeclaredRedirect[]}
- */
-export function redirectsFromAliases(aliases, source = "publication-space routes.aliases") {
-  if (!Array.isArray(aliases)) return [];
-  /** @type {DeclaredRedirect[]} */
-  const out = [];
-  for (const alias of aliases) {
-    if (!alias || alias.behavior !== "redirect-308") continue;
-    if (typeof alias.from !== "string" || typeof alias.to !== "string") continue;
-    out.push({ from: alias.from, to: alias.to, source });
-  }
-  return out;
-}
-
-/**
- * Follow `from -> to` through the declared map so a rename chain (a -> b, b -> c) resolves to a
- * single hop (a -> c). A chain costs an extra round trip on every visit and dilutes the signal the
- * redirect exists to preserve. A cycle is unresolvable and refuses.
- * @param {Map<string, string>} direct
- * @param {string} from
- * @returns {{to: string} | {cycle: string[]}}
- */
-function collapseChain(direct, from) {
-  const seen = [from];
-  let to = /** @type {string} */ (direct.get(from));
-  while (direct.has(to)) {
-    if (seen.includes(to)) return { cycle: [...seen, to] };
-    seen.push(to);
-    to = /** @type {string} */ (direct.get(to));
-  }
-  return { to };
-}
-
-/**
- * Build the substrate-neutral redirect set from every declared source.
- * @param {DeclaredRedirect[]} declared
- * @param {number} [budget]
- * @returns {RedirectSet}
- */
-export function buildRedirectSet(declared, budget = REDIRECT_MAP_BUDGET_BYTES) {
-  /** @type {string[]} */
-  const violations = [];
-  /** @type {Map<string, string>} */
-  const direct = new Map();
-  /** @type {Map<string, string>} */
-  const origin = new Map();
-
-  for (const entry of declared) {
-    const from = normalizeRedirectPath(entry.from);
-    const to = normalizeRedirectDestination(entry.to);
-    if (from === null) {
-      violations.push(`${entry.source}: redirect source is not a usable request path`);
-      continue;
-    }
-    if (to === null) {
-      violations.push(`${entry.source}: redirect target is not a usable destination path`);
-      continue;
-    }
-    if (from === to) {
-      violations.push(`${entry.source}: "${from}" redirects to itself`);
-      continue;
-    }
-    const existing = direct.get(from);
-    if (existing !== undefined && existing !== to) {
-      violations.push(
-        `"${from}" is declared twice with different targets ("${existing}" in ${origin.get(from)}, "${to}" in ${entry.source})`,
-      );
-      continue;
-    }
-    direct.set(from, to);
-    origin.set(from, entry.source);
-  }
-
-  /** @type {{from: string, to: string}[]} */
-  const redirects = [];
-  for (const from of [...direct.keys()].sort()) {
-    const resolved = collapseChain(direct, from);
-    if ("cycle" in resolved) {
-      violations.push(`redirect cycle: ${resolved.cycle.join(" -> ")}`);
-      continue;
-    }
-    redirects.push({ from, to: resolved.to });
-  }
-
-  const bytes = serializeRedirectMap(redirects).length;
-  if (bytes > budget) {
-    violations.push(
-      `redirect map is ${bytes} bytes, over the ${budget}-byte edge budget (${redirects.length} redirects) — move the map to a key-value store before declaring more`,
-    );
-  }
-
-  return { ok: violations.length === 0, redirects, violations, bytes, budget };
-}
-
-/**
- * The map exactly as an edge function embeds it: compact JSON, keys sorted, so the same declared
- * input always produces byte-identical output and the published artifact stays deterministic.
- *
- * The output is embedded as a JS literal in generated edge-function source, and its keys and values
- * are tenant-declared strings. `JSON.stringify` escapes quotes and backslashes, which closes the
- * obvious break-out; the escapes below close the rest of the JSON-is-not-quite-JS gap — the two
- * separator code points are legal in JSON strings but are line terminators to a JS parser, and `<`
- * is neutralized so the same bytes stay inert if the map is ever inlined into markup.
- * @param {{from: string, to: string}[]} redirects
- * @returns {string}
- */
-export function serializeRedirectMap(redirects) {
-  /** @type {Record<string, string>} */
-  const map = {};
-  for (const { from, to } of [...redirects].sort((a, b) => a.from.localeCompare(b.from))) {
-    map[from] = to;
-  }
-  return JSON.stringify(map)
-    .split(LINE_SEPARATOR)
-    .join("\\u2028")
-    .split(PARAGRAPH_SEPARATOR)
-    .join("\\u2029")
-    .split("<")
-    .join("\\u003c");
-}
-
-/**
- * The declared set as publication-space aliases — the shape `routes.aliases` already carries and
- * `publicationRedirects()` (scripts/publish/lib/publication-space-release.mjs) already consumes on
- * its way into the live pointer. Emitting this rather than a parallel structure is what keeps
- * redirects ONE contract: the edge function, the pointer value, and the declaration all agree
- * because there is only one of them.
- *
- * Returns an empty array when the set refused, so a caller that ignores `ok` cannot publish a
- * half-built topology.
- * @param {RedirectSet} set
- * @returns {{from: string, behavior: "redirect-308", to: string}[]}
- */
-export function aliasesFromRedirectSet(set) {
-  if (!set.ok) return [];
-  return set.redirects.map(({ from, to }) => ({
-    from,
-    behavior: /** @type {"redirect-308"} */ ("redirect-308"),
-    to,
-  }));
-}
-
-/**
- * @param {RedirectSet} set
- * @returns {string}
- */
-export function formatRedirectSetReport(set) {
-  const lines = [];
-  lines.push(
-    `== Redirect materialization == ${set.redirects.length} redirect(s), ${set.bytes}/${set.budget} bytes`,
-  );
-  for (const violation of set.violations) lines.push(`  REFUSE: ${violation}`);
-  lines.push(
-    set.ok
-      ? `OK — every declared redirect materializes at ${REDIRECT_STATUS}.`
-      : `REFUSED — ${set.violations.length} violation(s); nothing emitted.`,
-  );
-  return lines.join("\n");
-}
+// The redirect contract — declaration format, edge budget, reference matcher — is the agency kit's
+// pure module, so a store developer validates a map with the kit alone and a publish applies the
+// same code. This subpath is how the platform imports it.
+export * from "../../../agency-kit/tools/lib/redirect-declaration.mjs";

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

@@ -169,7 +169,10 @@ export interface StaticBundleManifest {
   htmlCacheControl?: string;
   /** T6 classification: relPath -> {hash, kind}. Absent on a pre-T6 manifest — every lookup then falls back to the old versions/<digest>/<rel> key (see `resolveStaticBundleObjectKey`). */
   files?: Record<string, StaticBundleFileEntry>;
-  /** Exact, version-bound whole-site redirects materialized from content/redirects.json. */
+  /**
+   * Version-bound whole-site redirects materialized from content/redirects.json: exact paths and
+   * `/<dir>/*` rules (see `publication-redirects.mjs` for the declaration contract).
+   */
   redirects?: Array<{ from: string; to: string }>;
 }
 
@@ -179,6 +182,50 @@ function isManifestRedirectPath(value: string): boolean {
     !value.split("/").includes("..");
 }
 
+/** A `/<dir>/*` rule (or rule target): `*` only as the whole last segment. */
+function isManifestRedirectRule(value: string): boolean {
+  return value.endsWith("/*") && value.indexOf("*") === value.length - 1 &&
+    isManifestRedirectPath(value.slice(0, -1));
+}
+
+/**
+ * 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.
+ */
+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));
+}
+
 function isManifestRedirectDestination(value: string): boolean {
   if (isManifestRedirectPath(value)) return true;
   try {
@@ -219,9 +266,13 @@ function parseManifest(raw: string): StaticBundleManifest | null {
       redirects = [];
       for (const value of m.redirects) {
         const redirect = value as { from?: unknown; to?: unknown };
-        if (!redirect || typeof redirect.from !== "string" || typeof redirect.to !== "string" ||
-            !isManifestRedirectPath(redirect.from) ||
-            !isManifestRedirectDestination(redirect.to)) return null;
+        if (!redirect || typeof redirect.from !== "string" || typeof redirect.to !== "string") return null;
+        const valid = isManifestRedirectRule(redirect.from)
+          ? redirect.from !== "/*" && (isManifestRedirectRule(redirect.to) ||
+            (!redirect.to.includes("*") && isManifestRedirectPath(redirect.to)))
+          : !redirect.from.includes("*") && isManifestRedirectPath(redirect.from) &&
+            !redirect.to.includes("*") && isManifestRedirectDestination(redirect.to);
+        if (!valid) return null;
         redirects.push({ from: redirect.from, to: redirect.to });
       }
     }
@@ -426,15 +477,12 @@ export async function serveStaticBundle(
     return failClosed(deps, `missing/unreadable manifest for digest ${digest}`);
   }
 
-  const redirectPath = pathname === "/" || pathname.split("/").pop()?.includes(".")
-    ? pathname
-    : pathname.endsWith("/") ? pathname : `${pathname}/`;
-  const redirect = manifest.redirects?.find(({ from }) => from === pathname || from === redirectPath);
-  if (redirect) {
-    const query = redirect.to.startsWith("/") ? search : "";
+  const redirectTo = staticBundleRedirectLocation(manifest.redirects, pathname);
+  if (redirectTo !== null) {
+    const query = redirectTo.startsWith("/") ? search : "";
     return new Response(null, {
       status: 308,
-      headers: { location: `${redirect.to}${query}`, "cache-control": "public, max-age=300" },
+      headers: { location: `${redirectTo}${query}`, "cache-control": "public, max-age=300" },
     });
   }
 

package/packages/public-runtime/tests/fixtures/redirect-match-cases.json

@@ -0,0 +1,34 @@
+{
+  "description": "One redirect set and the location every edge must answer for each request path. Run against the reference matcher (publication-redirects.mjs resolveRedirect), the Cloudflare static plane (static-bundle.ts serveStaticBundle) and the CloudFront viewer function (live-pointer-rewrite.mjs). null means no redirect.",
+  "redirects": [
+    { "from": "/blogs/*", "to": "/blog/" },
+    { "from": "/blogs/news/*", "to": "/blog/*" },
+    { "from": "/blogs/news/special/", "to": "/blog/featured/" },
+    { "from": "/collections/*", "to": "/shop/" },
+    { "from": "/my-account/", "to": "https://app.example.com/signin" },
+    { "from": "/pages/*", "to": "/*" },
+    { "from": "/sitemap_index.xml", "to": "/sitemap.xml" }
+  ],
+  "cases": [
+    { "path": "/blogs/news/hello", "location": "/blog/hello/" },
+    { "path": "/blogs/news/hello/", "location": "/blog/hello/" },
+    { "path": "/blogs/news/", "location": "/blog/" },
+    { "path": "/blogs/news", "location": "/blog/" },
+    { "path": "/blogs/news/feed.atom", "location": "/blog/feed.atom" },
+    { "path": "/blogs/news/special/", "location": "/blog/featured/" },
+    { "path": "/blogs/news/special", "location": "/blog/featured/" },
+    { "path": "/blogs/other/post/", "location": "/blog/" },
+    { "path": "/blogs/", "location": "/blog/" },
+    { "path": "/pages/about", "location": "/about/" },
+    { "path": "/pages/policies/terms/", "location": "/policies/terms/" },
+    { "path": "/pages//evil.example/", "location": null },
+    { "path": "/collections/vapes/", "location": "/shop/" },
+    { "path": "/collections/vapes/products/x", "location": "/shop/" },
+    { "path": "/sitemap_index.xml", "location": "/sitemap.xml" },
+    { "path": "/my-account", "location": "https://app.example.com/signin" },
+    { "path": "/blog/hello/", "location": null },
+    { "path": "/blogsx/", "location": null },
+    { "path": "/pages.html", "location": null },
+    { "path": "/", "location": null }
+  ]
+}

package/scripts/dev/port-lock.mjs

@@ -0,0 +1,109 @@
+// @ts-check
+/**
+ * Records which pid `tot dev` last bound a given port under, so a later
+ * invocation that finds the port busy can tell a STALE occupant (our own
+ * earlier `tot dev` process, no longer running — the socket just hasn't been
+ * released yet, or the process crashed without a clean shutdown) from a
+ * genuinely live one (a different, healthy server — ours or someone else's).
+ *
+ * Without this, `firstFreePort` silently drifts to the next port either way —
+ * fine for "someone else's server is using 4321", actively misleading after a
+ * crash: the developer's browser is still pointed at the old port, and nothing
+ * tells them the server they expect there isn't the one that just started
+ * (fb-1791304494289-ussj8l). Dependency-free (node:fs/os/path only) so it
+ * copies into the standalone runner like port-check.mjs.
+ */
+import { mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const PORT_LOCK_DIR = join(homedir(), ".tot", "run", "dev-ports");
+
+/** Record that `pid` (default: this process) is bound to `port`. Best-effort. */
+export function lockPort(port, { pid = process.pid, dir = PORT_LOCK_DIR } = {}) {
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, String(port)), String(pid));
+  } catch {
+    /* best-effort — a failed lock must never block `tot dev` from starting */
+  }
+}
+
+/** Release a port lock (best-effort; safe to call more than once). */
+export function unlockPort(port, { dir = PORT_LOCK_DIR } = {}) {
+  try {
+    rmSync(join(dir, String(port)), { force: true });
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** The pid last recorded as bound to `port`, or null when no lock is on file / unreadable. */
+export function readPortLock(port, { dir = PORT_LOCK_DIR } = {}) {
+  try {
+    const pid = Number(readFileSync(join(dir, String(port)), "utf8").trim());
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Is a pid a live process? (signal 0 probe; EPERM = alive but not ours.) */
+export function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return /** @type {NodeJS.ErrnoException} */ (e)?.code === "EPERM";
+  }
+}
+
+/**
+ * Why is `requestedPort` unavailable?
+ *  - `{ kind: "ours", pid }` — an EARLIER `tot dev` session still holds it and is
+ *    still running. It may be wedged (a renderer crash leaves the server process
+ *    alive and bound), so the developer must be told which process to stop.
+ *  - `{ kind: "stale", pid }` — our own recorded occupant is gone; the socket is
+ *    lingering past a crash/kill.
+ *  - `{ kind: "other" }` — busy with no lock of ours: someone else's server.
+ *  - `null` — the port isn't busy right now.
+ * @param {number} requestedPort
+ * @param {{ isFree: (port:number)=>Promise<boolean>, pidAlive?: (pid:number)=>boolean, dir?: string }} deps
+ * @returns {Promise<{kind:"ours"|"stale", pid:number}|{kind:"other"}|null>}
+ */
+export async function classifyBusyPort(requestedPort, { isFree, pidAlive = processAlive, dir = PORT_LOCK_DIR }) {
+  if (await isFree(requestedPort)) return null;
+  const pid = readPortLock(requestedPort, { dir });
+  if (pid == null) return { kind: "other" };
+  return { kind: pidAlive(pid) ? "ours" : "stale", pid };
+}
+
+/**
+ * The line `tot dev` prints when it starts on `resolvedPort` because
+ * `requestedPort` was busy. Every case involving an earlier `tot dev` session
+ * says so and names the process, so a browser tab left on the old port is never
+ * silently a different server.
+ * @param {number} requestedPort
+ * @param {number} resolvedPort
+ * @param {{kind:"ours"|"stale", pid:number}|{kind:"other"}|null} busy
+ */
+export function busyPortMessage(requestedPort, resolvedPort, busy) {
+  const tab = `    A browser tab on :${requestedPort} is NOT this session — use the URL below.`;
+  if (busy?.kind === "ours") {
+    return (
+      `  ⚠ port ${requestedPort} is held by an earlier \`tot dev\` session that is still running ` +
+      `(pid ${busy.pid}) — starting on ${resolvedPort} instead.\n` +
+      `    If that session crashed or stopped reloading, stop it (\`kill ${busy.pid}\`) and restart to get ${requestedPort} back.\n` +
+      tab
+    );
+  }
+  if (busy?.kind === "stale") {
+    return (
+      `  ⚠ port ${requestedPort} is still held after an earlier \`tot dev\` session (pid ${busy.pid}) exited ` +
+      `— starting on ${resolvedPort} instead.\n` +
+      `    Find the holder with \`lsof -nP -iTCP:${requestedPort} -sTCP:LISTEN\` and stop it to get ${requestedPort} back.\n` +
+      tab
+    );
+  }
+  return `  ⚠ port ${requestedPort} was busy — starting on ${resolvedPort} instead.`;
+}

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

@@ -0,0 +1,35 @@
+// @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.
+ */
+
+/**
+ * @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 }[]}
+ */
+export function standaloneGraftPlan(mappings) {
+  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" });
+  }
+  // `.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
+  // — siteType/compliance/capabilities/features (see
+  // apps/storefront/src/config/devTenantSeed.ts TOT_CONFIG_TENANT_FIELDS and
+  // resolver.ts declaredConfigs()) — the same file
+  // 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 });
+  }
+  return plan;
+}