@tokenoftrust/storefront-runner 4.3.1 → 4.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "4.3.1",
+  "version": "4.3.2",
   "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/scripts/dev/catalog-preview-refresh.mjs

@@ -0,0 +1,530 @@
+#!/usr/bin/env node
+// Child commands, each a fixed argv and never a shell: git, lsof, /usr/bin/python3, node, pnpm, wrangler.
+/** Pinned-ref refresh for the local Wrangler preview. Not the Astro dev server. */
+import { execFileSync, spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, cpSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { nonceFindings, tenantAssetRefs } from "../diag/check-preview-serving-core.mjs";
+import { runCatalogSmoke } from "../diag/catalog-local-smoke.mjs";
+import { isMainModule } from "../lib/is-main-module.mjs";
+import { isPortFree } from "./port-check.mjs";
+
+export const CATALOG_PORT = 5176;
+export const PREVIEW_PORT = 8787;
+const ASTRO_DEV_PORT = 4321;
+const SHA = /^[a-f0-9]{40}$/;
+const PIN_REL = "apps/storefront/src/lib/catalog/catalog-setup/contract/pin.json";
+function e2eCatalogFixtures(preview) {
+  const root = join(preview, "tenants/e2e");
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name.endsWith(".e2e.test"))
+    .map((entry) => `tenants/e2e/${entry.name}/content/catalog`);
+}
+const STOREFRONT_BRANCH = "origin/feature/8500-storefront-integration";
+const CATALOG_BRANCH = "origin/feature/1154-product-catalog";
+const PROCESS_READER = [
+  "import ctypes, json, os, struct, sys",
+  "from ctypes import c_int, c_uint32, c_uint64, c_char, c_size_t, c_void_p",
+  "mode, pid_text = sys.argv[1], sys.argv[2]",
+  "pid = int(pid_text)",
+  "libc = ctypes.CDLL('/usr/lib/libSystem.B.dylib', use_errno=True)",
+  "def argv_of(target):",
+  "    mib = (c_int * 3)(1, 49, target)",
+  "    size = c_size_t()",
+  "    if libc.sysctl(mib, 3, None, ctypes.byref(size), None, 0):",
+  "        raise SystemExit('process_gone')",
+  "    buf = ctypes.create_string_buffer(size.value)",
+  "    if libc.sysctl(mib, 3, buf, ctypes.byref(size), None, 0):",
+  "        raise SystemExit('process_gone')",
+  "    raw = buf.raw[:size.value]",
+  "    if len(raw) < 4:",
+  "        raise SystemExit('process_gone')",
+  "    argc = struct.unpack_from('i', raw)[0]",
+  "    if argc < 1 or argc > 4096:",
+  "        raise SystemExit('process_gone')",
+  "    start = raw.index(b'\\0', 4) + 1",
+  "    while start < len(raw) and raw[start] == 0:",
+  "        start += 1",
+  "    parts = [os.fsdecode(part) for part in raw[start:].split(b'\\0')[:argc]]",
+  "    if len(parts) != argc:",
+  "        raise SystemExit('process_gone')",
+  "    return parts",
+  "if mode == 'children':",
+  "    libc.proc_listchildpids.argtypes = [c_int, c_void_p, c_int]",
+  "    libc.proc_listchildpids.restype = c_int",
+  "    cap = 4096",
+  "    buf = (c_int * cap)()",
+  "    count = libc.proc_listchildpids(pid, ctypes.byref(buf), ctypes.sizeof(buf))",
+  "    if count < 0 or count >= cap:",
+  "        raise SystemExit('process_children_unbounded')",
+  "    print(json.dumps([int(buf[index]) for index in range(count)]))",
+  "elif mode == 'identity':",
+  "    class ProcBsdInfo(ctypes.Structure):",
+  "        _fields_ = [('pbi_flags', c_uint32), ('pbi_status', c_uint32), ('pbi_xstatus', c_uint32), ('pbi_pid', c_uint32), ('pbi_ppid', c_uint32), ('pbi_uid', c_uint32), ('pbi_gid', c_uint32), ('pbi_ruid', c_uint32), ('pbi_rgid', c_uint32), ('pbi_svuid', c_uint32), ('pbi_svgid', c_uint32), ('reserved', c_uint32), ('pbi_comm', c_char * 16), ('pbi_name', c_char * 32), ('pbi_nfiles', c_uint32), ('pbi_pgid', c_uint32), ('pbi_pjobc', c_uint32), ('e_tdev', c_uint32), ('e_tpgid', c_uint32), ('pbi_nice', c_int), ('pbi_start_tvsec', c_uint64), ('pbi_start_tvusec', c_uint64)]",
+  "    info = ProcBsdInfo()",
+  "    libc.proc_pidinfo.argtypes = [c_int, c_int, c_uint64, c_void_p, c_int]",
+  "    libc.proc_pidinfo.restype = c_int",
+  "    size = libc.proc_pidinfo(pid, 3, 0, ctypes.byref(info), ctypes.sizeof(info))",
+  "    if size != ctypes.sizeof(info) or int(info.pbi_pid) != pid:",
+  "        raise SystemExit('process_gone')",
+  "    print(json.dumps({'uid': int(info.pbi_uid), 'start': '%d.%d' % (int(info.pbi_start_tvsec), int(info.pbi_start_tvusec)), 'argv': argv_of(pid)}))",
+  "else:",
+  "    raise SystemExit('process_reader_mode')",
+].join("\n");
+
+const delay = (ms) => new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+const fixedError = (code) => new Error(code);
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const git = (root, ...args) => execFileSync("git", ["-C", root, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 30000 }).trim();
+const gitBytes = (root, ref) => execFileSync("git", ["-C", root, "show", ref], { stdio: ["ignore", "pipe", "pipe"], timeout: 30000, maxBuffer: 8 * 1024 * 1024 });
+
+export function assertServicePorts(ports = { catalog: CATALOG_PORT, preview: PREVIEW_PORT }) {
+  if (ports.catalog === ASTRO_DEV_PORT || ports.preview === ASTRO_DEV_PORT) throw fixedError("refresh_astro_port_refused");
+  if (ports.catalog !== 5176 || ports.preview !== 8787) throw fixedError("refresh_port_mismatch");
+}
+export function catalogBase() {
+  assertServicePorts();
+  return `http://127.0.0.1:${CATALOG_PORT}`;
+}
+export function previewBase() {
+  assertServicePorts();
+  return `http://127.0.0.1:${PREVIEW_PORT}`;
+}
+
+export function validateRequest(options) {
+  assertServicePorts();
+  if (!SHA.test(options.storefrontSha ?? "") || !SHA.test(options.catalogSha ?? "")) throw fixedError("refresh_full_refs_required");
+  for (const key of ["preview", "catalogRepo", "sentinelPath", "sentinelMarker"]) if (!options[key]) throw fixedError("refresh_configuration_missing");
+  if (!/^\/(?!\/)[a-zA-Z0-9/._-]*$/.test(options.sentinelPath) || options.sentinelPath.split("/").includes("..")
+    || options.sentinelMarker.length > 160 || /[\x00-\x1f]/.test(options.sentinelMarker)) throw fixedError("refresh_sentinel_invalid");
+}
+
+/** The effect order is explicit so failures before admission cannot stop the old process. */
+export async function refreshPreview(options, effects = realEffects) {
+  validateRequest(options);
+  const prior = await effects.inspect(options);
+  await effects.prove(prior, options, prior.storefrontSha);
+  const prepared = await effects.prepare(options, prior);
+  try {
+    await effects.prove(prior, options, prior.storefrontSha);
+  } catch (error) {
+    await effects.discard(prepared);
+    throw error;
+  }
+  if (prior.storefrontSha === options.storefrontSha) {
+    await effects.discard(prepared);
+    return { status: "unchanged", storefrontSha: options.storefrontSha, catalogSha: options.catalogSha, restarts: 0, identities: prior.identities };
+  }
+  let stopped = false;
+  let started;
+  try {
+    await effects.assertUnchanged(prior);
+    stopped = true;
+    await effects.stop(prior.process);
+    started = await effects.start(prepared, prior, options);
+    await effects.prove({ ...prior, process: started }, options, options.storefrontSha);
+    await effects.assertPrivateState(prior);
+    await effects.record(prior, prepared, started, options);
+    return { status: "refreshed", storefrontSha: options.storefrontSha, catalogSha: options.catalogSha, restarts: 1, identities: prior.identities };
+  } catch {
+    if (!stopped) {
+      await effects.discard(prepared);
+      throw fixedError("refresh_failed_before_stop");
+    }
+    try {
+      if (started) await effects.stop(started);
+      const recovered = await effects.start({ checkout: prior.checkout }, prior, options);
+      await effects.prove({ ...prior, process: recovered }, options, prior.storefrontSha);
+      await effects.assertPrivateState(prior);
+      await effects.record(prior, { checkout: prior.checkout }, recovered, { ...options, storefrontSha: prior.storefrontSha });
+      await effects.discard(prepared);
+    } catch {
+      throw fixedError("refresh_failed_recovery_failed");
+    }
+    throw fixedError("refresh_failed_prior_restored");
+  }
+}
+
+function pythonJson(mode, pid) {
+  try {
+    return JSON.parse(execFileSync("/usr/bin/python3", ["-c", PROCESS_READER, mode, String(pid)], {
+      encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 3000,
+    }));
+  } catch (error) {
+    const detail = `${error.stderr ?? ""}${error.message ?? ""}`;
+    if (detail.includes("process_children_unbounded")) throw fixedError("refresh_process_children_unbounded");
+    if (detail.includes("process_gone")) return null;
+    throw error;
+  }
+}
+
+function linuxIdentity(pid) {
+  let argv;
+  let status;
+  let stat;
+  try {
+    argv = readFileSync(`/proc/${pid}/cmdline`).toString("utf8").split("\0").filter(Boolean);
+    status = readFileSync(`/proc/${pid}/status`, "utf8");
+    stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+    return null;
+  }
+  const uid = Number(/^Uid:\s+(\d+)/m.exec(status)?.[1]);
+  const after = stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/);
+  if (!argv.length || !Number.isInteger(uid) || !after[19]) return null;
+  return { uid, start: after[19], argv };
+}
+
+function childPids(pid) {
+  if (process.platform === "darwin") {
+    const listed = pythonJson("children", pid);
+    if (!Array.isArray(listed) || listed.some((child) => !Number.isInteger(child))) throw fixedError("refresh_process_children_unbounded");
+    return listed;
+  }
+  const children = [];
+  for (const name of readdirSync("/proc")) {
+    if (!/^\d+$/.test(name)) continue;
+    let stat;
+    try { stat = readFileSync(`/proc/${name}/stat`, "utf8"); } catch { continue; }
+    const parent = Number(stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/)[1]);
+    if (parent === pid) children.push(Number(name));
+  }
+  return children;
+}
+
+export function processIdentity(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 2) throw fixedError("refresh_process_identity_invalid");
+  const info = process.platform === "darwin" ? pythonJson("identity", pid) : linuxIdentity(pid);
+  if (!info || !Array.isArray(info.argv) || info.argv.some((part) => typeof part !== "string")) throw fixedError("refresh_process_identity_invalid");
+  if (info.uid !== process.getuid?.()) throw fixedError("refresh_process_owner_mismatch");
+  let cwd;
+  if (process.platform === "darwin") {
+    const listing = execFileSync("/usr/sbin/lsof", ["-a", "-p", String(pid), "-d", "cwd", "-Fn"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 3000 });
+    cwd = listing.split("\n").find((line) => line.startsWith("n"))?.slice(1);
+  } else cwd = realpathSync(`/proc/${pid}/cwd`);
+  if (!cwd) throw fixedError("refresh_process_identity_invalid");
+  return { pid, uid: info.uid, start: String(info.start), command: info.argv.join("\0"), argv: info.argv, cwd: realpathSync(cwd) };
+}
+
+function sameProcess(current, identity) {
+  return current.pid === identity.pid && current.uid === identity.uid && current.start === identity.start
+    && current.command === identity.command && current.cwd === identity.cwd
+    && JSON.stringify(current.argv) === JSON.stringify(identity.argv);
+}
+
+/** Re-read pid, cwd, command, and process start time. A swapped pid does not match. */
+export function recheckIdentity(identity, read = processIdentity) {
+  const current = read(identity.pid);
+  if (!current || !sameProcess(current, identity)) throw fixedError("refresh_process_changed");
+  return current;
+}
+
+export function assertIdentity(identity) {
+  recheckIdentity(identity);
+}
+
+/**
+ * Signal only after a fresh read. `beforeSignal` exists so a test can swap the pid
+ * after the first check; the re-read immediately before the signal must refuse it.
+ */
+export function signalOwned(identity, options = {}) {
+  const read = options.read ?? processIdentity;
+  recheckIdentity(identity, read);
+  options.beforeSignal?.(identity);
+  recheckIdentity(identity, read);
+  process.kill(identity.pid, "SIGTERM");
+}
+
+export function privateIdentity(path, file = false) {
+  const info = statSync(path);
+  if (info.uid !== process.getuid?.()) throw fixedError("refresh_private_owner_mismatch");
+  if (file && (info.mode & 0o077)) throw fixedError("refresh_environment_permissions");
+  return { path: realpathSync(path), dev: info.dev, ino: info.ino, uid: info.uid, mode: info.mode & 0o777, ...(file ? { digest: digest(readFileSync(path)) } : {}) };
+}
+
+export function headersForOrigin(target, configuredOrigin, capability) {
+  const headers = { accept: "application/json" };
+  if (target.origin === configuredOrigin.origin && capability) headers.authorization = `Bearer ${capability}`;
+  return headers;
+}
+
+export async function fetchLocal(path, base, options = {}) {
+  const origin = new URL(base);
+  const target = new URL(path, origin);
+  if (origin.protocol !== "http:" || origin.hostname !== "127.0.0.1" || origin.username || origin.password
+    || target.origin !== origin.origin || target.username || target.password) throw fixedError("refresh_local_origin_refused");
+  const headers = headersForOrigin(target, origin, options.capability);
+  if (target.host !== origin.host && (headers.authorization || headers["x-tot-capability"])) throw fixedError("refresh_capability_off_origin");
+  const response = await (options.fetchImpl ?? fetch)(target, { redirect: "manual", headers, signal: AbortSignal.timeout(3000) });
+  if (response.redirected || (response.status >= 300 && response.status < 400) || !response.ok) {
+    await response.body?.cancel();
+    throw fixedError("refresh_http_failure");
+  }
+  return response;
+}
+
+function assertFixtureTree(path) {
+  const info = lstatSync(path);
+  if (info.isSymbolicLink() || (!info.isDirectory() && !info.isFile())) throw fixedError("refresh_fixture_link_refused");
+  if (info.isDirectory()) for (const name of readdirSync(path)) assertFixtureTree(join(path, name));
+}
+
+function embedsSha(path, sha) {
+  for (const entry of readdirSync(path, { withFileTypes: true })) {
+    const file = join(path, entry.name);
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory() && embedsSha(file, sha)) return true;
+    if (entry.isFile() && /\.(?:mjs|js|json)$/.test(entry.name) && readFileSync(file, "utf8").includes(sha)) return true;
+  }
+  return false;
+}
+
+function scratch(root, sha) {
+  const checkout = join(tmpdir(), `catalog-preview-${randomUUID()}`);
+  git(root, "worktree", "add", "--detach", checkout, sha);
+  return checkout;
+}
+
+export function assertLocalWrangler(owned, app, volumePath) {
+  const argv = owned.argv;
+  if (!Array.isArray(argv) || !argv.every((value) => typeof value === "string") || owned.cwd !== app) throw fixedError("refresh_not_owned_local_wrangler");
+  const dev = argv.findIndex((value, index) => /(?:^|\/)wrangler(?:\.js)?$/.test(value) && argv[index + 1] === "dev");
+  if (dev < 0) throw fixedError("refresh_not_owned_local_wrangler");
+  const args = argv.slice(dev + 2);
+  const values = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (!argument.startsWith("--")) throw fixedError("refresh_not_owned_local_wrangler");
+    const equal = argument.indexOf("=");
+    const key = equal < 0 ? argument : argument.slice(0, equal);
+    if (Object.hasOwn(values, key)) throw fixedError("refresh_not_owned_local_wrangler");
+    const value = equal >= 0 ? argument.slice(equal + 1) : key === "--local" ? true : args[index += 1];
+    if (value === undefined || (typeof value === "string" && value.startsWith("--"))) throw fixedError("refresh_not_owned_local_wrangler");
+    values[key] = value;
+  }
+  if (values["--local"] !== true || Object.hasOwn(values, "--remote") || values["--port"] !== String(PREVIEW_PORT) || values["--ip"] !== "127.0.0.1"
+    || typeof values["--persist-to"] !== "string") throw fixedError("refresh_not_owned_local_wrangler");
+  let persisted;
+  try { persisted = realpathSync(resolve(app, values["--persist-to"])); } catch { throw fixedError("refresh_not_owned_local_wrangler"); }
+  if (persisted !== volumePath) throw fixedError("refresh_not_owned_local_wrangler");
+}
+
+function descendantsOf(pid) {
+  const out = [];
+  const visit = (parent) => {
+    for (const child of childPids(parent)) {
+      visit(child);
+      try {
+        out.push(processIdentity(child));
+      } catch (error) {
+        if (error?.message !== "refresh_process_identity_invalid") throw error;
+      }
+    }
+  };
+  visit(pid);
+  return out;
+}
+
+export const realEffects = {
+  async inspect(options) {
+    assertServicePorts();
+    const preview = realpathSync(options.preview);
+    const receiptPath = join(preview, "apps/storefront/.wrangler/catalog-preview-refresh.json");
+    const receipt = existsSync(receiptPath) ? JSON.parse(readFileSync(receiptPath, "utf8")) : null;
+    const checkout = receipt?.checkout ?? preview;
+    const storefrontSha = git(checkout, "rev-parse", "HEAD");
+    if (git(checkout, "status", "--porcelain", "--untracked-files=no")) throw fixedError("refresh_preview_tracked_dirty");
+    const pid = Number(receipt?.pid ?? options.pid);
+    const owned = processIdentity(pid);
+    const app = realpathSync(join(checkout, "apps/storefront"));
+    const volume = privateIdentity(join(preview, "local-state"));
+    const environment = privateIdentity(join(preview, "apps/storefront/.dev.vars"), true);
+    assertLocalWrangler(owned, app, volume.path);
+    if (checkout !== preview && realpathSync(join(checkout, "apps/storefront/.dev.vars")) !== environment.path) throw fixedError("refresh_serving_environment_mismatch");
+    if (receipt?.process && JSON.stringify(owned) !== JSON.stringify(receipt.process)) throw fixedError("refresh_saved_process_mismatch");
+    return {
+      checkout, storefrontSha, process: owned, preview, receiptPath, volume, environment,
+      identities: {
+        volume: { dev: volume.dev, ino: volume.ino, uid: volume.uid },
+        environment: { dev: environment.dev, ino: environment.ino, uid: environment.uid, mode: environment.mode },
+      },
+    };
+  },
+  async prepare(options, prior) {
+    const catalog = realpathSync(options.catalogRepo);
+    if (git(catalog, "status", "--porcelain", "--untracked-files=no")) throw fixedError("refresh_catalog_tracked_dirty");
+    for (const [root, sha, branch] of [[prior.preview, options.storefrontSha, STOREFRONT_BRANCH], [catalog, options.catalogSha, CATALOG_BRANCH]]) {
+      if (git(root, "rev-parse", `${sha}^{commit}`) !== sha) throw fixedError("refresh_ref_missing");
+      try { git(root, "merge-base", "--is-ancestor", sha, branch); } catch { throw fixedError("refresh_ref_not_integrated"); }
+    }
+    if (!gitBytes(prior.preview, `${options.storefrontSha}:pnpm-lock.yaml`).equals(gitBytes(prior.checkout, "HEAD:pnpm-lock.yaml"))
+      || !gitBytes(catalog, `${options.catalogSha}:package-lock.json`).equals(gitBytes(catalog, "HEAD:package-lock.json"))) throw fixedError("refresh_lock_changed");
+    const pin = JSON.parse(git(prior.preview, "show", `${options.storefrontSha}:${PIN_REL}`));
+    if (pin.repo !== "tokenoftrust/product-catalog" || pin.commit !== options.catalogSha) throw fixedError("refresh_consumer_pin_mismatch");
+    for (const [path, hash] of Object.entries(pin.files)) {
+      if (digest(execFileSync("git", ["-C", catalog, "show", `${options.catalogSha}:${path}`], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: 8 * 1024 * 1024 })) !== hash) throw fixedError("refresh_contract_hash_mismatch");
+    }
+    if (prior.storefrontSha === options.storefrontSha) return {};
+    for (const rel of e2eCatalogFixtures(prior.preview)) {
+      if (existsSync(join(prior.preview, rel)) && git(prior.preview, "ls-tree", "-r", "--name-only", options.storefrontSha, "--", rel)) throw fixedError("refresh_fixture_tracked_collision");
+    }
+    let checkout;
+    let catalogCheckout;
+    try {
+      checkout = scratch(prior.preview, options.storefrontSha);
+      catalogCheckout = scratch(catalog, options.catalogSha);
+      for (const rel of e2eCatalogFixtures(prior.preview)) if (existsSync(join(prior.preview, rel))) {
+        if (git(checkout, "ls-files", "--", rel)) throw fixedError("refresh_fixture_tracked_collision");
+        assertFixtureTree(join(prior.preview, rel));
+        cpSync(join(prior.preview, rel), join(checkout, rel), { recursive: true, dereference: false, errorOnExist: true, force: false });
+      }
+      const dependencies = ["node_modules"];
+      for (const workspaceRoot of ["apps", "packages", "agency-kit"]) {
+        const sourceRoot = join(prior.checkout, workspaceRoot);
+        if (!existsSync(sourceRoot)) continue;
+        if (existsSync(join(sourceRoot, "node_modules"))) dependencies.push(`${workspaceRoot}/node_modules`);
+        for (const entry of readdirSync(sourceRoot, { withFileTypes: true })) {
+          if (entry.isDirectory() && entry.name !== "node_modules" && existsSync(join(sourceRoot, entry.name, "node_modules"))) dependencies.push(`${workspaceRoot}/${entry.name}/node_modules`);
+        }
+      }
+      for (const rel of dependencies) {
+        if (!existsSync(join(prior.checkout, rel))) throw fixedError("refresh_dependencies_missing");
+        cpSync(join(prior.checkout, rel), join(checkout, rel), { recursive: true, dereference: false, preserveTimestamps: true });
+      }
+      symlinkSync(prior.environment.path, join(checkout, "apps/storefront/.dev.vars"));
+      runCatalogSmoke(checkout);
+      execFileSync(process.execPath, ["scripts/build/copy-tenant-assets.mjs"], { cwd: checkout, stdio: ["ignore", "pipe", "pipe"], timeout: 45000 });
+      execFileSync("pnpm", ["--config.verify-deps-before-run=false", "--filter", "@tot/storefront", "run", "build"], {
+        cwd: checkout, env: { ...process.env, CLOUDFLARE_ENV: "preview" }, stdio: ["ignore", "pipe", "pipe"], timeout: 180000, maxBuffer: 4 * 1024 * 1024,
+      });
+      if (git(checkout, "rev-parse", "HEAD") !== options.storefrontSha || git(checkout, "status", "--porcelain", "--untracked-files=no")) throw fixedError("refresh_build_source_changed");
+      const config = JSON.parse(readFileSync(join(checkout, "apps/storefront/dist/server/wrangler.json"), "utf8"));
+      if (!embedsSha(join(checkout, "apps/storefront/dist/server"), options.storefrontSha)) throw fixedError("refresh_build_ref_missing");
+      if (config.no_bundle !== true) throw fixedError("refresh_build_config_invalid");
+      const priorConfig = JSON.parse(readFileSync(join(prior.checkout, "apps/storefront/dist/server/wrangler.json"), "utf8"));
+      for (const key of ["d1_databases", "kv_namespaces", "r2_buckets", "durable_objects", "migrations"]) {
+        if (JSON.stringify(config[key] ?? null) !== JSON.stringify(priorConfig[key] ?? null)) throw fixedError("refresh_state_bindings_changed");
+      }
+      git(catalog, "worktree", "remove", catalogCheckout);
+      catalogCheckout = undefined;
+      return { checkout, storefrontRoot: prior.preview };
+    } catch (error) {
+      for (const [root, worktree] of [[prior.preview, checkout], [catalog, catalogCheckout]]) {
+        if (worktree) try { git(root, "worktree", "remove", worktree); } catch { /* Keep unclean scratch evidence. Never force. */ }
+      }
+      if (String(error?.message ?? "").startsWith("refresh_")) throw error;
+      throw fixedError("refresh_prepare_failed");
+    }
+  },
+  async prove(prior, options, storefrontSha) {
+    assertIdentity(prior.process);
+    const storefront = await (await fetchLocal("/health", previewBase())).json();
+    const catalog = await (await fetchLocal("/health", catalogBase())).json();
+    if (storefront.sha !== storefrontSha || catalog.sourceCommit !== options.catalogSha) throw fixedError("refresh_served_ref_mismatch");
+    const response = await fetchLocal(options.sentinelPath, previewBase());
+    const sentinel = await response.text();
+    if (nonceFindings({ csp: response.headers.get("content-security-policy"), html: sentinel }).length) throw fixedError("refresh_sentinel_nonce_mismatch");
+    const assets = tenantAssetRefs(sentinel);
+    if (assets.length > 32) throw fixedError("refresh_sentinel_asset_limit");
+    for (const asset of assets) {
+      const fetched = await fetchLocal(asset, previewBase());
+      await fetched.body?.cancel();
+    }
+    if (!sentinel.includes(options.sentinelMarker)) throw fixedError("refresh_sentinel_mismatch");
+  },
+  async assertUnchanged(prior) {
+    assertIdentity(prior.process);
+    if (git(prior.checkout, "rev-parse", "HEAD") !== prior.storefrontSha || git(prior.checkout, "status", "--porcelain", "--untracked-files=no")) throw fixedError("refresh_preview_changed");
+    await this.assertPrivateState(prior);
+  },
+  async assertPrivateState(prior) {
+    const volume = privateIdentity(prior.volume.path);
+    const environment = privateIdentity(prior.environment.path, true);
+    if (volume.dev !== prior.volume.dev || volume.ino !== prior.volume.ino || volume.uid !== prior.volume.uid
+      || environment.dev !== prior.environment.dev || environment.ino !== prior.environment.ino || environment.uid !== prior.environment.uid
+      || environment.mode !== prior.environment.mode || environment.digest !== prior.environment.digest) throw fixedError("refresh_private_state_changed");
+  },
+  async stop(owned) {
+    const descendants = descendantsOf(owned.pid);
+    for (const identity of [...descendants, owned]) signalOwned(identity);
+    for (let attempt = 0; attempt < 50; attempt += 1) {
+      let live = false;
+      for (const identity of [...descendants, owned]) {
+        try {
+          recheckIdentity(identity);
+          live = true;
+        } catch { /* Gone or changed: never signal the replacement. */ }
+      }
+      if (!live) return;
+      await delay(100);
+    }
+    throw fixedError("refresh_owned_stop_timeout");
+  },
+  async start(prepared, prior, _options) {
+    if (!(await isPortFree(PREVIEW_PORT))) throw fixedError("refresh_preview_port_not_free");
+    const app = join(prepared.checkout, "apps/storefront");
+    const logDir = join(prior.preview, "apps/storefront/.wrangler/catalog-refresh-logs");
+    mkdirSync(logDir, { recursive: true, mode: 0o700 });
+    const log = openSync(join(logDir, `${randomUUID()}.log`), "wx", 0o600);
+    let child;
+    try {
+      child = spawn(process.execPath, [
+        join(app, "node_modules/wrangler/bin/wrangler.js"), "dev", "--config", "dist/server/wrangler.json",
+        "--local", "--ip", "127.0.0.1", "--port", String(PREVIEW_PORT), "--persist-to", prior.volume.path, "--log-level", "error",
+      ], { cwd: app, env: { ...process.env }, detached: true, stdio: ["ignore", log, log] });
+    } finally { closeSync(log); }
+    let failed = false;
+    child.once("error", () => { failed = true; });
+    child.once("exit", () => { failed = true; });
+    child.unref();
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+      if (failed) {
+        try { if (child.pid) await this.stop(processIdentity(child.pid)); } catch { /* An exited root cannot be signalled. */ }
+        throw fixedError("refresh_start_failed");
+      }
+      try {
+        const identity = processIdentity(child.pid);
+        await fetchLocal("/health", previewBase());
+        return identity;
+      } catch { await delay(200); }
+    }
+    if (child.pid) {
+      try { await this.stop(processIdentity(child.pid)); } catch { throw fixedError("refresh_start_cleanup_failed"); }
+    }
+    throw fixedError("refresh_start_timeout");
+  },
+  async record(prior, prepared, processInfo, options) {
+    mkdirSync(join(prior.receiptPath, ".."), { recursive: true, mode: 0o700 });
+    writeFileSync(prior.receiptPath, `${JSON.stringify({ checkout: prepared.checkout, pid: processInfo.pid, process: processInfo, storefrontSha: options.storefrontSha, catalogSha: options.catalogSha })}\n`, { mode: 0o600 });
+  },
+  async discard(prepared) {
+    if (prepared?.checkout && prepared.storefrontRoot) {
+      try { git(prepared.storefrontRoot, "worktree", "remove", prepared.checkout); } catch { /* Keep private scratch evidence when removal is not clean. */ }
+    }
+  },
+};
+
+if (isMainModule(import.meta.url)) {
+  if (process.argv.includes("--help")) {
+    console.log("Usage: node scripts/dev/catalog-preview-refresh.mjs --preview=<preserved-checkout> --catalog-repo=<catalog-checkout> --storefront-sha=<integrated-full-sha> --catalog-sha=<integrated-full-sha> --pid=<owned-Wrangler-pid-on-first-run> --sentinel-path=/<local-fixture> --sentinel-marker=<stable-fixture-label>\nCatalog must already serve the requested ref on 5176. Preview stays on 8787. Private state is never reset.");
+  } else {
+    const options = {};
+    const keys = { preview: "preview", "catalog-repo": "catalogRepo", "storefront-sha": "storefrontSha", "catalog-sha": "catalogSha", pid: "pid", "sentinel-path": "sentinelPath", "sentinel-marker": "sentinelMarker" };
+    try {
+      for (const arg of process.argv.slice(2)) {
+        const match = /^--([a-z-]+)=(.*)$/.exec(arg);
+        if (!match || !keys[match[1]] || Object.hasOwn(options, keys[match[1]])) throw fixedError("refresh_arguments_invalid");
+        options[keys[match[1]]] = match[2];
+      }
+      console.log(JSON.stringify(await refreshPreview(options)));
+    } catch (error) {
+      console.error(/^refresh_[a-z0-9_]+$/.test(error.message) ? error.message : "catalog_preview_refresh_failed");
+      process.exitCode = 1;
+    }
+  }
+}