@tokenoftrust/storefront-runner 1.3.2

package/scripts/dev/checkout-watch.mjs

@@ -0,0 +1,116 @@
+// @ts-check
+import { watch, readdirSync, statSync, existsSync, cpSync, rmSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+// Standalone (`tot dev --workspace`) re-sync: the developer's checkout is COPIED
+// into the storefront's in-tree tenants/<id>/ (Vite's server.fs.allow refuses files
+// outside its root), and each save is mirrored back so Vite's own watcher fires the
+// browser reload. This module owns detecting the save + doing the copy.
+
+/** Re-sync one changed checkout path into its in-tree copy (copy on save, remove on delete). */
+export function resync(sourceRoot, targetRoot, rel) {
+  const from = rel ? join(sourceRoot, rel) : sourceRoot;
+  const to = rel ? join(targetRoot, rel) : targetRoot;
+  try {
+    if (existsSync(from)) {
+      mkdirSync(dirname(to), { recursive: true });
+      cpSync(from, to, { recursive: true });
+    } else if (existsSync(to)) {
+      rmSync(to, { recursive: true, force: true });
+    }
+  } catch (e) {
+    console.warn(`  ⚠ re-sync failed for ${rel || "(root)"}: ${e?.message}`);
+  }
+}
+
+/**
+ * Watch a checkout path (dir or single file) and invoke `onChange(rel)` on every
+ * add/change/delete, where `rel` is the source-relative path ("" for a file source).
+ *
+ * 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.
+ *
+ * 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
+ * on purpose (matches the rest of the tenant tooling); returns `{ close() }`.
+ * @param {string} source @param {boolean} isDir @param {(rel: string) => void} onChange
+ */
+export function startWatch(source, isDir, onChange) {
+  const useNative = /^(1|true|yes|on)$/i.test(process.env.TOT_DEV_NATIVE_WATCH || "");
+  if (useNative) {
+    try {
+      return watch(source, { recursive: isDir }, (_event, filename) =>
+        onChange(isDir ? (filename ? String(filename) : "") : ""),
+      );
+    } catch (e) {
+      // Linux: recursive fs.watch is ERR_FEATURE_UNAVAILABLE_ON_PLATFORM → poll.
+      console.warn(`  ⚠ native watch unavailable (${e?.code || e?.message}); falling back to polling.`);
+    }
+  }
+  // Poll frequently for a snappy save→reload (responsiveness > CPU here). Tune with
+  // CHOKIDAR_INTERVAL (ms) for very large trees or constrained hosts.
+  const interval = Number(process.env.CHOKIDAR_INTERVAL) || 150;
+  const seenMtimes = new Map(); // relPath -> mtimeMs
+  let primed = false;
+  const scan = () => {
+    const present = new Set();
+    const visit = (absDir, relDir) => {
+      let entries;
+      try {
+        entries = readdirSync(absDir, { withFileTypes: true });
+      } catch {
+        return; // dir vanished mid-scan — a later scan reconciles it
+      }
+      for (const e of entries) {
+        const rel = relDir ? join(relDir, e.name) : e.name;
+        const abs = join(absDir, e.name);
+        if (e.isDirectory()) {
+          visit(abs, rel);
+          continue;
+        }
+        present.add(rel);
+        let m;
+        try {
+          m = statSync(abs).mtimeMs;
+        } catch {
+          continue;
+        }
+        const prev = seenMtimes.get(rel);
+        if (prev === undefined || prev !== m) {
+          seenMtimes.set(rel, m);
+          if (primed) onChange(rel);
+        }
+      }
+    };
+    if (isDir) {
+      visit(source, "");
+    } else {
+      present.add("");
+      let m;
+      try {
+        m = statSync(source).mtimeMs;
+      } catch {
+        m = undefined;
+      }
+      const prev = seenMtimes.get("");
+      if (m !== undefined && prev !== m) {
+        seenMtimes.set("", m);
+        if (primed) onChange("");
+      }
+    }
+    for (const rel of [...seenMtimes.keys()]) {
+      if (!present.has(rel)) {
+        seenMtimes.delete(rel);
+        if (primed) onChange(rel);
+      }
+    }
+    primed = true;
+  };
+  scan(); // prime the snapshot without emitting spurious initial events
+  const id = setInterval(scan, interval);
+  if (typeof id.unref === "function") id.unref();
+  return { close: () => clearInterval(id) };
+}

package/scripts/dev/file-browser.mjs

@@ -0,0 +1,159 @@
+/**
+ * file-browser.mjs — server-side logic for the C3 Files tab: a nested source
+ * tree (`GET /__tot/tree`) and a single-file read for the read-only viewer
+ * (`GET /__tot/file?path=`).
+ *
+ * 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
+ * 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.
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, extname, sep } from "node:path";
+import { resolveSafePath, matchesWriteAllowlist } from "./safe-path.mjs";
+import { resolveTenantSourceRoot } from "./tenant-source-root.mjs";
+
+/** Above this, the viewer degrades to "not shown" rather than shipping a huge string. */
+const MAX_FILE_BYTES = 512 * 1024;
+
+/** Extension → CodeMirror language name (null = plain text, still viewable). */
+const LANG_BY_EXT = {
+  ".html": "html",
+  ".htm": "html",
+  ".svg": "html",
+  ".json": "json",
+  ".css": "css",
+  ".js": "javascript",
+  ".mjs": "javascript",
+  ".cjs": "javascript",
+  ".ts": "javascript",
+  ".md": "markdown",
+  ".txt": "text",
+};
+
+/** Extensions we never try to render as text (binary assets under public/). */
+const BINARY_EXT = new Set([
+  ".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".ico", ".bmp",
+  ".woff", ".woff2", ".ttf", ".otf", ".eot",
+  ".pdf", ".zip", ".gz", ".mp4", ".webm", ".mov", ".mp3", ".wav",
+]);
+
+/** Dirs never worth showing in the tenant source tree. */
+const IGNORE_NAMES = new Set([".git", "node_modules", ".DS_Store"]);
+
+/** @returns CodeMirror language name for a path, or null for plain text. */
+export function languageForPath(relPath) {
+  return LANG_BY_EXT[extname(relPath).toLowerCase()] ?? null;
+}
+
+/**
+ * Build a nested tree of the tenant source root:
+ *   { name, path, type:"dir", children:[…] } | { name, path, type:"file", language }
+ * `path` is always root-relative with forward slashes. Dirs sort before files,
+ * each alphabetically. Unreadable dirs degrade to empty children (never throw).
+ */
+export function buildTree(sourceRoot, { ignore = IGNORE_NAMES } = {}) {
+  const walk = (absDir, relDir) => {
+    let entries;
+    try {
+      entries = readdirSync(absDir, { withFileTypes: true });
+    } catch {
+      return []; // vanished / unreadable mid-walk — reconcile on next fetch
+    }
+    const nodes = [];
+    for (const e of entries) {
+      if (ignore.has(e.name)) continue;
+      const rel = relDir ? `${relDir}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        nodes.push({ name: e.name, path: rel, type: "dir", children: walk(join(absDir, e.name), rel) });
+      } else if (e.isFile()) {
+        nodes.push({ name: e.name, path: rel, type: "file", language: languageForPath(rel) });
+      }
+    }
+    nodes.sort((a, b) =>
+      a.type === b.type ? a.name.localeCompare(b.name) : a.type === "dir" ? -1 : 1,
+    );
+    return nodes;
+  };
+  return walk(sourceRoot, "");
+}
+
+/**
+ * Read a single file for the viewer. Traversal-guarded via safe-path. Binary and
+ * oversized files degrade to `{content:null}` with a flag rather than shipping
+ * bytes the viewer can't render.
+ */
+export function readFile(sourceRoot, relPath) {
+  let abs;
+  try {
+    abs = resolveSafePath(sourceRoot, relPath);
+  } catch (e) {
+    return { ok: false, status: "bad_path", message: e.message };
+  }
+
+  let st;
+  try {
+    st = statSync(abs);
+  } catch {
+    return { ok: false, status: "not_found", message: `No such file: ${relPath}` };
+  }
+  if (st.isDirectory()) {
+    return { ok: false, status: "is_dir", message: `${relPath} is a directory` };
+  }
+
+  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.
+  const mtimeMs = st.mtimeMs;
+  const writable = matchesWriteAllowlist(norm);
+  if (BINARY_EXT.has(extname(norm).toLowerCase())) {
+    return { ok: true, status: "ok", path: norm, binary: true, size: st.size, language: null, content: null, mtimeMs, writable };
+  }
+  if (st.size > MAX_FILE_BYTES) {
+    return { ok: true, status: "ok", path: norm, tooBig: true, size: st.size, language: languageForPath(norm), content: null, mtimeMs, writable };
+  }
+
+  const buf = readFileSync(abs);
+  if (buf.includes(0)) {
+    // NUL byte → treat as binary even without a known extension.
+    return { ok: true, status: "ok", path: norm, binary: true, size: st.size, language: null, content: null, mtimeMs, writable };
+  }
+  return { ok: true, status: "ok", path: norm, size: st.size, language: languageForPath(norm), content: buf.toString("utf8"), mtimeMs, writable };
+}
+
+// --- request-level handlers (env → {status, json}) -------------------------
+// The deferred dev-plugins/dev-file-browser.mjs wrapper maps HTTP req/res onto
+// these; keeping them here means the whole endpoint contract is unit-testable
+// without a running dev server.
+
+/** GET /__tot/tree */
+export function handleTree(env = process.env) {
+  const root = resolveTenantSourceRoot(env);
+  if (!root.ok) return { status: root.status === "no_tenant" ? 403 : 500, json: root };
+  return {
+    status: 200,
+    json: { ok: true, tenantId: root.tenantId, root: root.sourceRoot, tree: buildTree(root.sourceRoot) },
+  };
+}
+
+/** GET /__tot/file?path= */
+export function handleFile(env = process.env, relPath) {
+  const root = resolveTenantSourceRoot(env);
+  if (!root.ok) return { status: root.status === "no_tenant" ? 403 : 500, json: root };
+  if (!relPath) return { status: 400, json: { ok: false, status: "no_path", message: "path query param is required" } };
+
+  const result = readFile(root.sourceRoot, relPath);
+  const status = result.ok
+    ? 200
+    : result.status === "bad_path"
+      ? 400
+      : result.status === "not_found"
+        ? 404
+        : 400;
+  return { status, json: result };
+}

package/scripts/dev/file-writer.mjs

@@ -0,0 +1,141 @@
+/**
+ * file-writer.mjs — server-side logic for C5's in-browser edit: write a single
+ * tenant source file (`POST /__tot/write {path, content}`).
+ *
+ * Mirrors the file-browser.mjs pattern (see also ai-edit.mjs): all logic lives
+ * here, dependency-free and testable under `node --test`; a thin dev-only Vite
+ * plugin (dev-plugins/dev-write.mjs — added when C0/C1 integrate) maps req/res
+ * onto `handleWrite`. Every write is double-guarded — the strict WRITE allowlist
+ * (matchesWriteAllowlist) AND the traversal/symlink guard (resolveSafePath) — and
+ * the target is resolved from tenant-source-root.mjs, which points at the
+ * developer's REAL CHECKOUT in standalone mode (never the in-tree graft, or the
+ * edit is silently discarded on the next resync).
+ *
+ * The existing tenant-hot-reload watcher carries the browser reload once the file
+ * 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
+ * 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
+ * `{status:"conflict", current}` (HTTP 409) carrying the current mtimeMs instead
+ * of silently clobbering. Omit baseVersion to force-save (the UI's explicit
+ * override). A brand-new file with a baseVersion is likewise a conflict — someone
+ * else created it first.
+ */
+import { mkdirSync, writeFileSync, statSync } from "node:fs";
+import { dirname, sep } from "node:path";
+import { resolveSafePath, matchesWriteAllowlist } from "./safe-path.mjs";
+import { resolveTenantSourceRoot } from "./tenant-source-root.mjs";
+
+/** Reject absurd payloads outright (the editable surface is small HTML/JSON). */
+const MAX_WRITE_BYTES = 2 * 1024 * 1024;
+
+/**
+ * Write `content` to `relPath` under `sourceRoot`, double-guarded. Creates parent
+ * dirs for a new file (e.g. content/pages-html/<new>.html). Never throws — every
+ * failure is a `{ok:false, status, message}` result.
+ * @param {string} sourceRoot
+ * @param {string} relPath
+ * @param {string} content
+ * @param {{baseVersion?:number}} [opts] baseVersion = mtimeMs the client last saw;
+ *   a mismatch (or a file that now exists when the client expected none) → conflict.
+ * @returns {{ok:true,status:"ok",path:string,bytes:number,mtimeMs:number}
+ *          | {ok:false,status:"conflict",current:number|null,message:string}
+ *          | {ok:false,status:string,message:string}}
+ */
+export function writeSourceFile(sourceRoot, relPath, content, opts = {}) {
+  if (typeof content !== "string") {
+    return { ok: false, status: "bad_content", message: "content must be a string" };
+  }
+  if (Buffer.byteLength(content, "utf8") > MAX_WRITE_BYTES) {
+    return { ok: false, status: "too_large", message: "content exceeds the write size limit" };
+  }
+  // Allowlist first (only the raw-HTML content surface + theme.json are writable),
+  // then the traversal/symlink guard — defence in depth.
+  if (!matchesWriteAllowlist(relPath)) {
+    return { ok: false, status: "not_writable", message: `not in the write allowlist: ${relPath}` };
+  }
+  let abs;
+  try {
+    abs = resolveSafePath(sourceRoot, relPath);
+  } catch (e) {
+    return { ok: false, status: "bad_path", message: e.message };
+  }
+  // Current on-disk state (mtime + dir check) in one stat.
+  let current = null;
+  try {
+    const cur = statSync(abs);
+    if (cur.isDirectory()) {
+      return { ok: false, status: "is_dir", message: `${relPath} is a directory` };
+    }
+    current = cur.mtimeMs;
+  } 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
+  // 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;
+  if (typeof baseVersion === "number" && current !== baseVersion) {
+    return {
+      ok: false,
+      status: "conflict",
+      current,
+      message: current === null
+        ? `${relPath} was deleted since you opened it`
+        : `${relPath} changed on disk since you opened it`,
+    };
+  }
+  try {
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content, "utf8");
+  } catch (e) {
+    return { ok: false, status: "write_failed", message: e.message };
+  }
+  const st = statSync(abs);
+  return {
+    ok: true,
+    status: "ok",
+    path: relPath.split(sep).join("/"),
+    bytes: Buffer.byteLength(content, "utf8"),
+    mtimeMs: st.mtimeMs,
+  };
+}
+
+// --- request-level handler (env + body → {status, json}) -------------------
+// The deferred dev-plugins/dev-write.mjs wrapper maps the HTTP req/res + JSON
+// body onto this; keeping it here makes the whole endpoint contract unit-testable
+// without a running dev server.
+
+/**
+ * POST /__tot/write — body {path, content, baseVersion?}.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {{path?:string, content?:unknown, baseVersion?:number}} [body]
+ */
+export function handleWrite(env = process.env, body = {}) {
+  const root = resolveTenantSourceRoot(env);
+  if (!root.ok) return { status: root.status === "no_tenant" ? 403 : 500, json: root };
+
+  const relPath = body && body.path;
+  if (!relPath) {
+    return { status: 400, json: { ok: false, status: "no_path", message: "path is required" } };
+  }
+
+  const result = writeSourceFile(root.sourceRoot, relPath, body.content, {
+    baseVersion: body ? body.baseVersion : undefined,
+  });
+  const status = result.ok
+    ? 200
+    : result.status === "conflict"
+      ? 409
+      : result.status === "not_writable"
+        ? 403
+        : result.status === "too_large"
+          ? 413
+          : result.status === "write_failed"
+            ? 500
+            : 400; // bad_content | bad_path | is_dir
+  return { status, json: result };
+}

package/scripts/dev/git-status.mjs

@@ -0,0 +1,171 @@
+/**
+ * git-status.mjs — working-tree status + HEAD diff for C4's /__tot/diff endpoint
+ * (and reusable by C3's tree git-status badges).
+ *
+ * Two jobs, both dependency-free (node: builtins + the `git` CLI) so they copy
+ * into the standalone `tot dev` runner and test under `node --test`:
+ *
+ *  1. parseStatus / fileStatus — classify a path from `git status --porcelain`
+ *     (untracked / modified / added / unchanged), the authoritative "is this file
+ *     new?" check the handoff calls out (a new file shows NOTHING under a plain
+ *     `git diff`, so porcelain is what distinguishes all-added from a real diff).
+ *
+ *  2. computeDiff / handleDiff — return {before, after} strings for the client's
+ *     @codemirror/merge view (which diffs the two strings itself — no jsdiff dep).
+ *     `before` = the file's content at HEAD via `git show HEAD:./<path>` ("" for a
+ *     new/untracked file → renders as all-added); `after` = the working file.
+ *     Binary and oversized files degrade to `{shown:false}` rather than shipping
+ *     bytes the merge view can't render.
+ *
+ * Git is run with cwd = gitCwd (from tenant-source-root.mjs) and the pathspec as
+ * `HEAD:./<relPath>` — the `./` makes it relative to gitCwd, correct in BOTH the
+ * standalone mode (gitCwd is its own repo root) and monorepo mode (gitCwd is a
+ * subdir of the monorepo tree).
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { extname, sep } from "node:path";
+import { resolveSafePath } from "./safe-path.mjs";
+import { resolveTenantSourceRoot } from "./tenant-source-root.mjs";
+
+/** Above this the diff degrades to "not shown" rather than shipping a huge string. */
+const MAX_DIFF_BYTES = 512 * 1024;
+
+const BINARY_EXT = new Set([
+  ".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".ico", ".bmp",
+  ".woff", ".woff2", ".ttf", ".otf", ".eot",
+  ".pdf", ".zip", ".gz", ".mp4", ".webm", ".mov", ".mp3", ".wav",
+]);
+
+/** Run a git command in `cwd`; return {ok, stdout} — never throws. */
+function git(cwd, args) {
+  try {
+    const stdout = execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: 8 * 1024 * 1024 });
+    return { ok: true, stdout };
+  } catch (e) {
+    return { ok: false, stdout: "", code: e && e.status, stderr: e && e.stderr };
+  }
+}
+
+/**
+ * Parse `git status --porcelain` output into a Map of posix-relative-path →
+ * two-char XY status code (e.g. " M", "??", "A "). Handles the rename form
+ * "R  old -> new" by keying the new path.
+ */
+export function parseStatus(porcelain) {
+  const map = new Map();
+  for (const line of porcelain.split("\n")) {
+    if (line.length < 4) continue;
+    const xy = line.slice(0, 2);
+    let path = line.slice(3);
+    const arrow = path.indexOf(" -> ");
+    if (arrow >= 0) path = path.slice(arrow + 4);
+    // porcelain quotes paths with special chars; strip surrounding quotes.
+    if (path.startsWith('"') && path.endsWith('"')) path = path.slice(1, -1);
+    map.set(path, xy);
+  }
+  return map;
+}
+
+/** Classify one path from a parsed status map → "untracked"|"modified"|"added"|"unchanged". */
+export function classify(statusMap, relPathPosix) {
+  const xy = statusMap.get(relPathPosix);
+  if (!xy) return "unchanged";
+  if (xy === "??") return "untracked";
+  if (xy.includes("A")) return "added";
+  return "modified";
+}
+
+/**
+ * fileStatus(gitCwd, relPath) → status string (single-file porcelain query).
+ * We filter with `-- <path>`, so any returned line pertains to THIS file — read
+ * its XY code directly rather than matching the path key. This is essential in
+ * monorepo mode: porcelain output paths are repo-root-relative while the query is
+ * cwd-relative, so a key lookup would always miss and report "unchanged".
+ */
+export function fileStatus(gitCwd, relPath) {
+  const posix = relPath.split(sep).join("/");
+  const res = git(gitCwd, ["status", "--porcelain", "--", posix]);
+  if (!res.ok) return "unknown";
+  const line = res.stdout.split("\n").find((l) => l.length >= 2);
+  if (!line) return "unchanged";
+  const xy = line.slice(0, 2);
+  if (xy === "??") return "untracked";
+  if (xy.includes("A")) return "added";
+  return "modified";
+}
+
+/**
+ * Build the before/after diff payload for one file.
+ * @returns {{ok:true, path, status, shown:boolean, before?:string, after?:string, reason?:string}
+ *          | {ok:false, status:string, message:string}}
+ */
+export function computeDiff(gitCwd, sourceRoot, relPath) {
+  let abs;
+  try {
+    abs = resolveSafePath(sourceRoot, relPath);
+  } catch (e) {
+    return { ok: false, status: "bad_path", message: e.message };
+  }
+  const posix = relPath.split(sep).join("/");
+
+  // Working ("after") side — may be absent (a deleted file).
+  let after = null;
+  let workingExists = true;
+  let st;
+  try {
+    st = statSync(abs);
+  } catch {
+    workingExists = false;
+  }
+  if (workingExists && st.isDirectory()) {
+    return { ok: false, status: "is_dir", message: `${relPath} is a directory` };
+  }
+  if (workingExists) {
+    if (BINARY_EXT.has(extname(posix).toLowerCase())) {
+      return { ok: true, path: posix, status: fileStatus(gitCwd, relPath), shown: false, reason: "binary" };
+    }
+    if (st.size > MAX_DIFF_BYTES) {
+      return { ok: true, path: posix, status: fileStatus(gitCwd, relPath), shown: false, reason: "too_big" };
+    }
+    const buf = readFileSync(abs);
+    if (buf.includes(0)) {
+      return { ok: true, path: posix, status: fileStatus(gitCwd, relPath), shown: false, reason: "binary" };
+    }
+    after = buf.toString("utf8");
+  }
+
+  const status = fileStatus(gitCwd, relPath);
+
+  // HEAD ("before") side — "" when the file isn't in HEAD (new/untracked →
+  // all-added in the merge view). git show fails for a path not in HEAD.
+  let before = "";
+  if (status !== "untracked" && status !== "added") {
+    const shown = git(gitCwd, ["show", `HEAD:./${posix}`]);
+    if (shown.ok) before = shown.stdout;
+  }
+
+  return {
+    ok: true,
+    path: posix,
+    status: workingExists ? status : "deleted",
+    shown: true,
+    before,
+    after: after ?? "",
+  };
+}
+
+// --- request-level handler (env → {status, json}) --------------------------
+// The deferred dev-plugins wrapper maps GET /__tot/diff?path= onto this; keeping
+// it here makes the endpoint contract unit-testable without a running dev server.
+
+/** GET /__tot/diff?path= */
+export function handleDiff(env = process.env, relPath) {
+  const root = resolveTenantSourceRoot(env);
+  if (!root.ok) return { status: root.status === "no_tenant" ? 403 : 500, json: root };
+  if (!relPath) return { status: 400, json: { ok: false, status: "no_path", message: "path query param is required" } };
+
+  const result = computeDiff(root.gitCwd, root.sourceRoot, relPath);
+  const status = result.ok ? 200 : result.status === "bad_path" ? 400 : 400;
+  return { status, json: result };
+}