npm - @tokenoftrust/storefront-runner - Versions diffs - 1.3.2 - Mend

@tokenoftrust/storefront-runner 1.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (310) hide show

package/scripts/dev/locate-handler.mjs ADDED Viewed

@@ -0,0 +1,163 @@
+/**
+ * locate-handler.mjs — request-level logic for C7/C8 click-to-source:
+ *   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
+ * 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 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>:
+ *   · a content-region click resolves to the exact source line;
+ *   · a click on a page with no raw source (templated/commerce) → {status:"not_raw_html"};
+ *   · a click on the chrome of a raw page (header/footer/etc — absent from the source,
+ *     so the walk misses) → an EXPLICIT {status:"not_in_content"} refusal, never a
+ *     silent/coincidental miss and never a wrong location.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { resolveSafePath, matchesWriteAllowlist } from "./safe-path.mjs";
+import { resolveTenantSourceRoot } from "./tenant-source-root.mjs";
+import { locate } from "./locate.mjs";
+/**
+ * Map a served page pathname to its raw-HTML content source, root-relative.
+ * `/` or `/<tenant>/` → content/home.html; `/<tenant>/<slug…>` → content/pages-html/<slug…>.html.
+ * The tenant path-prefix (appDomain, present under `tot dev`'s localhost routing) is
+ * stripped when it leads. Returns null if the result isn't a raw-HTML content path.
+ * @returns {string|null}
+ */
+export function resolvePageSource(pathname, tenantId) {
+  if (typeof pathname !== "string") return null;
+  let clean;
+  try {
+    clean = decodeURIComponent(pathname.split("?")[0].split("#")[0]);
+  } catch {
+    return null; // malformed %-encoding
+  }
+  const segments = clean.split("/").filter(Boolean);
+  if (segments.length && tenantId && segments[0] === tenantId) segments.shift();
+  // No `..` games — resolveSafePath is the real guard, but reject early so a slug can't
+  // even be shaped into a traversal.
+  if (segments.some((s) => s === "..")) return null;
+  const rel = segments.length === 0 ? "content/home.html" : `content/pages-html/${segments.join("/")}.html`;
+  return matchesWriteAllowlist(rel) ? rel : null;
+}
+/** True iff `domPath` is a non-empty array of {tag, index} steps. */
+function isDomPath(domPath) {
+  return (
+    Array.isArray(domPath) &&
+    domPath.length > 0 &&
+    domPath.every((s) => s && typeof s.tag === "string" && Number.isFinite(Number(s.index)))
+  );
+}
+/**
+ * POST /__tot/locate — {domPath, path} → source line:col.
+ * @returns {{status:number, json:any}}
+ */
+export function handleLocate(env = process.env, body = {}) {
+  const root = resolveTenantSourceRoot(env);
+  if (!root.ok) return { status: root.status === "no_tenant" ? 403 : 500, json: root };
+  if (!isDomPath(body.domPath)) {
+    return { status: 400, json: { ok: false, status: "bad_dom_path", message: "domPath must be a non-empty array of {tag,index}" } };
+  }
+  const rel = resolvePageSource(body.path, root.tenantId);
+  // No raw-HTML content file backs this URL → click-to-source doesn't apply here.
+  if (!rel) {
+    return { status: 200, json: { ok: false, status: "not_raw_html", message: "This page isn’t a raw-HTML content page — click-to-source is for content/*.html tenants." } };
+  }
+  let abs;
+  try {
+    abs = resolveSafePath(root.sourceRoot, rel);
+  } catch (e) {
+    return { status: 400, json: { ok: false, status: "bad_path", message: e.message } };
+  }
+  if (!existsSync(abs)) {
+    // The URL shape is a raw content page, but no such source file exists (e.g. a
+    // templated route that merely looks like one) — refuse cleanly, never guess.
+    return { status: 200, json: { ok: false, status: "not_raw_html", message: "No raw-HTML source backs this page." } };
+  }
+  const html = readFileSync(abs, "utf8");
+  const found = locate(html, body.domPath);
+  if (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
+  // chrome (header, nav, footer) that wraps <main> and isn’t in the source. Explicit
+  // refusal per the content-region decision, not a bare not_found.
+  return {
+    status: 200,
+    json: {
+      ok: false,
+      status: "not_in_content",
+      message: "That element is part of the storefront frame (header, nav, or footer), not your content source. Click something inside your page content.",
+    },
+  };
+}
+/** Clamp a 1-based line/col to a safe positive integer (defaults to 1). */
+function toPos(n) {
+  const v = Math.floor(Number(n));
+  return Number.isFinite(v) && v > 0 ? v : 1;
+}
+/**
+ * POST /__tot/open-in-editor — best-effort open {path} at {line, col} in the developer's
+ * $EDITOR. Degrades gracefully (never throws to the client) when no editor is configured.
+ * @returns {{status:number, json:any}}
+ */
+export function handleOpenInEditor(env = process.env, body = {}, spawnFn = spawn) {
+  const root = resolveTenantSourceRoot(env);
+  if (!root.ok) return { status: root.status === "no_tenant" ? 403 : 500, json: root };
+  const rel = typeof body.path === "string" ? body.path : "";
+  if (!matchesWriteAllowlist(rel)) {
+    return { status: 400, json: { ok: false, status: "bad_path", message: "path must be a tenant content file" } };
+  }
+  let abs;
+  try {
+    abs = resolveSafePath(root.sourceRoot, rel);
+  } catch (e) {
+    return { status: 400, json: { ok: false, status: "bad_path", message: e.message } };
+  }
+  const editorCmd = env.TOT_DEV_EDITOR || env.VISUAL || env.EDITOR || "";
+  if (!editorCmd.trim()) {
+    return { status: 200, json: { ok: false, status: "no_editor", message: "Set $EDITOR or TOT_DEV_EDITOR to open files from here." } };
+  }
+  const line = toPos(body.line);
+  const col = toPos(body.col);
+  // Shell-free: split the editor command into a binary + preset flags, then append the
+  // file target in the binary's expected form. No user string ever reaches a shell.
+  const tokens = editorCmd.trim().split(/\s+/);
+  const bin = tokens[0];
+  const preArgs = tokens.slice(1);
+  let target;
+  if (/(^|\/)(code|codium|cursor|vscode)$/i.test(bin) || preArgs.includes("-g")) {
+    target = preArgs.includes("-g") ? [`${abs}:${line}:${col}`] : ["-g", `${abs}:${line}:${col}`];
+  } else if (/(^|\/)(vi|vim|nvim|nano|emacs|emacsclient)$/i.test(bin)) {
+    target = [`+${line}`, abs];
+  } else {
+    target = [abs]; // unknown editor — just open the file
+  }
+  try {
+    const child = spawnFn(bin, [...preArgs, ...target], { detached: true, stdio: "ignore" });
+    if (child && typeof child.unref === "function") child.unref();
+  } catch (e) {
+    return { status: 200, json: { ok: false, status: "editor_failed", message: `Couldn’t launch ${bin}: ${e.message}` } };
+  }
+  return { status: 200, json: { ok: true, path: rel, line, col } };
+}

package/scripts/dev/locate.mjs ADDED Viewed

@@ -0,0 +1,112 @@
+// locate.mjs — map a clicked element back to its source line:col in a raw-HTML
+// tenant file (content/home.html, content/pages-html/**). Pure logic: given the
+// file's HTML text + a DOM path captured in the browser, walk the parse5 tree the
+// SAME way the browser walked its live DOM and read the target node's source
+// location. Dependency-free except parse5 (server-side only), so it's unit-testable
+// with node:test and carries no framework/build coupling.
+//
+// THE WALK (must stay byte-identical in intent to captureDomPath() in
+// apps/storefront/src/lib/dev/ai-widget-client.js):
+//   A DOM path is an array of { tag, index } steps, ordered from the <body>'s
+//   direct child DOWN to the target. Each step names a lowercased tag and the
+//   0-based position of that element among its same-tag ELEMENT siblings (text and
+//   comment nodes ignored) — i.e. an nth-of-type index. The walk is anchored at
+//   <body> because both the browser and parse5 run the HTML tree-construction spec
+//   (injecting html/head/body around a fragment identically), so body's element
+//   subtree corresponds one-to-one between the two. `locate.test.mjs` proves the
+//   round-trip element → domPath → locate === the element's own source location.
+import { parse } from "parse5";
+/** Element children only (parse5 tags elements with `.tagName`; skip #text/#comment). */
+function elementChildren(node) {
+  return (node.childNodes ?? []).filter((c) => typeof c.tagName === "string");
+}
+/** Find the <body> element in a parsed parse5 document, or null. */
+export function findBody(document) {
+  const html = elementChildren(document).find((n) => n.tagName === "html");
+  const scope = html ?? document;
+  return elementChildren(scope).find((n) => n.tagName === "body") ?? null;
+}
+/**
+ * Walk a DOM path from <body> to the target node in a parse5 tree.
+ * Returns the parse5 node, or null if any step doesn't resolve.
+ */
+export function walk(bodyNode, domPath) {
+  let node = bodyNode;
+  for (const step of domPath) {
+    const tag = String(step.tag).toLowerCase();
+    const index = Number(step.index) || 0;
+    let seen = -1;
+    let next = null;
+    for (const child of elementChildren(node)) {
+      if (child.tagName.toLowerCase() === tag) {
+        seen += 1;
+        if (seen === index) {
+          next = child;
+          break;
+        }
+      }
+    }
+    if (!next) return null;
+    node = next;
+  }
+  return node;
+}
+/**
+ * Reference implementation of the BROWSER-side capture (captureDomPath in
+ * ai-widget-client.js), operating on a parse5 node + its ancestry map. Exported so
+ * the test can assert the client walk and the server walk are mutually inverse over
+ * the same tree — the guarantee the card demands ("must EXACTLY match the client
+ * walk"). Not used by the request path.
+ */
+export function domPathOf(target, parentOf) {
+  const path = [];
+  let node = target;
+  while (node) {
+    const parent = parentOf.get(node);
+    if (!parent || parent.tagName === "body") {
+      if (parent && parent.tagName === "body") {
+        path.unshift(stepFor(node, parent));
+      }
+      break;
+    }
+    path.unshift(stepFor(node, parent));
+    node = parent;
+  }
+  return path;
+}
+function stepFor(node, parent) {
+  const tag = node.tagName.toLowerCase();
+  let index = 0;
+  for (const sib of elementChildren(parent)) {
+    if (sib === node) break;
+    if (sib.tagName.toLowerCase() === tag) index += 1;
+  }
+  return { tag, index };
+}
+/**
+ * Resolve a DOM path to a source location within `html`.
+ * @param {string} html  raw source of the tenant file
+ * @param {Array<{tag:string,index:number}>} domPath  from the browser capture
+ * @returns {{line:number,col:number}|{status:string}}
+ *   { line, col } (1-based, from parse5 startLine/startCol) on success, or a
+ *   { status } discriminant: "empty_path" | "no_body" | "not_found" | "no_location".
+ */
+export function locate(html, domPath) {
+  if (!Array.isArray(domPath) || domPath.length === 0) return { status: "empty_path" };
+  const document = parse(html, { sourceCodeLocationInfo: true });
+  const body = findBody(document);
+  if (!body) return { status: "no_body" };
+  const node = walk(body, domPath);
+  if (!node) return { status: "not_found" };
+  const loc = node.sourceCodeLocation;
+  // Synthesized/adjusted nodes (rare in raw HTML) carry no location — degrade
+  // rather than point at the wrong place.
+  if (!loc || typeof loc.startLine !== "number") return { status: "no_location" };
+  return { line: loc.startLine, col: loc.startCol };
+}

package/scripts/dev/port-check.mjs ADDED Viewed

@@ -0,0 +1,48 @@
+// @ts-check
+import net from "node:net";
+/**
+ * Is `port` free to bind right now? Resolves false if anything already holds it
+ * (EADDRINUSE, or any bind error) — we listen with the host OMITTED so Node binds
+ * dual-stack (::/0.0.0.0), matching how `astro dev --host` grabs the port, so this
+ * 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
+ * failing clearly removes that whole class of silent failure.
+ *
+ * Dependency-free (node:net only) so it copies into the standalone runner and is
+ * testable under `node --test`.
+ * @param {number} port
+ * @returns {Promise<boolean>}
+ */
+export function isPortFree(port) {
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.once("error", () => resolve(false));
+    srv.once("listening", () => srv.close(() => resolve(true)));
+    try {
+      srv.listen(port);
+    } catch {
+      resolve(false);
+    }
+  });
+}
+/**
+ * The first free port at or after `preferred` (scanning upward). Lets `tot dev`
+ * boot on a busy default port by moving to the next open one and printing it —
+ * a better first-run experience than failing. Falls back to `preferred` after
+ * `maxTries` so the caller still gets a definite bind attempt (and a real error).
+ * @param {number} preferred
+ * @param {number} [maxTries]
+ * @returns {Promise<number>}
+ */
+export async function firstFreePort(preferred, maxTries = 64) {
+  for (let p = preferred; p < preferred + maxTries; p++) {
+    if (await isPortFree(p)) return p;
+  }
+  return preferred;
+}

package/scripts/dev/safe-path.mjs ADDED Viewed

@@ -0,0 +1,109 @@
+/**
+ * safe-path.mjs — the shared path-traversal guard for every `/__tot/*` dev
+ * endpoint (C3 tree/file, C4 diff, C5 write, C7/C8 locate).
+ *
+ * `tot dev` binds `--host` (LAN-visible) and the later chunks add file WRITE +
+ * `$EDITOR` spawn, so an unguarded `?path=` is a real directory-traversal /
+ * symlink-escape surface. This module is the ONE guard they all route through:
+ * resolve the caller-supplied relative path against an absolute root, collapse
+ * `..`, and prove the result stays inside the root both LEXICALLY and after
+ * realpath (so a symlink inside the root can't point out of it).
+ *
+ * Dependency-free (node: builtins only) so it copies cleanly into the standalone
+ * `tot dev` runner (see scripts/build/build-runner.mjs) and is testable under
+ * `node --test` with no build step (the scripts/dev convention).
+ */
+import { realpathSync } from "node:fs";
+import { resolve, sep, isAbsolute, relative } from "node:path";
+export class SafePathError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "SafePathError";
+    this.code = code;
+  }
+}
+/**
+ * realpath the deepest EXISTING ancestor of `p`, then re-append the missing
+ * tail. Lets us symlink-check a path whose leaf doesn't exist yet (the C5 write
+ * case: writing a brand-new file), without following a non-existent leaf.
+ */
+function realpathOfNearest(p) {
+  let cur = p;
+  const tail = []; // deepest-first
+  for (;;) {
+    try {
+      const real = realpathSync(cur);
+      return tail.length ? resolve(real, ...tail.reverse()) : real;
+    } catch (e) {
+      if (e.code !== "ENOENT") throw e;
+      const parent = resolve(cur, "..");
+      if (parent === cur) return cur; // reached the filesystem root
+      tail.push(relative(parent, cur));
+      cur = parent;
+    }
+  }
+}
+/**
+ * Resolve a caller-supplied relative path against an absolute `root`,
+ * guaranteeing the result stays inside `root`. Returns the absolute path.
+ * Throws SafePathError (with a `.code`) on any escape / bad input.
+ */
+export function resolveSafePath(root, relPath) {
+  if (typeof relPath !== "string" || relPath.length === 0) {
+    throw new SafePathError("path is required", "empty");
+  }
+  if (relPath.includes("\0")) {
+    throw new SafePathError("path contains a NUL byte", "nul");
+  }
+  if (isAbsolute(relPath)) {
+    throw new SafePathError(`absolute paths are not allowed: ${relPath}`, "absolute");
+  }
+  const realRoot = realpathSync(root); // root always exists
+  const candidate = resolve(realRoot, relPath); // resolve() collapses ..
+  // Lexical containment — covers `../../etc/passwd` and also non-existent leaves.
+  if (candidate !== realRoot && !candidate.startsWith(realRoot + sep)) {
+    throw new SafePathError(`path escapes the root: ${relPath}`, "escape");
+  }
+  // Symlink containment — a symlink inside root pointing outside it.
+  const realResolved = realpathOfNearest(candidate);
+  if (realResolved !== realRoot && !realResolved.startsWith(realRoot + sep)) {
+    throw new SafePathError(`path escapes the root via a symlink: ${relPath}`, "escape");
+  }
+  return candidate;
+}
+/** Boolean convenience — true iff `relPath` resolves safely inside `root`. */
+export function isSafePath(root, relPath) {
+  try {
+    resolveSafePath(root, relPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+/**
+ * Strict WRITE allowlist for C5's `POST /__tot/write` — only the raw-HTML
+ * content surface is writable. Read/tree endpoints (C3) do NOT use this; they
+ * rely on `resolveSafePath` containment alone so the tree can show everything.
+ * Kept here so the write path reuses the one guard rather than reinventing it.
+ */
+const WRITE_ALLOWLIST = [
+  /^content\/home\.html$/,
+  /^content\/pages-html\/[^\0]+\.html$/,
+  /^theme\.json$/,
+];
+/** True iff `relPath` (root-relative, any separator) is writable per the allowlist. */
+export function matchesWriteAllowlist(relPath) {
+  if (typeof relPath !== "string" || !relPath) return false;
+  const norm = relPath.split(sep).join("/").replace(/^\.\//, "");
+  return WRITE_ALLOWLIST.some((re) => re.test(norm));
+}

package/scripts/dev/shot.mjs ADDED Viewed

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// shot.mjs — headless screenshot of a URL to a file, in ONE command. Replaces the
+// multi-step MCP navigate→screenshot→read loop and gives timeout control for heavy
+// pages (e.g. a live Shopify site that stalls the browser MCP). Then just Read the
+// output file. Uses the repo's playwright-core + a system Chrome (same resolution
+// as scripts/site-migration/validate-page-browser.mjs).
+//
+// Usage:
+//   node scripts/dev/shot.mjs <url> [outfile=/tmp/shot.jpeg] [--full] [--wait 4000] [--width 1200] [--scroll 900]
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+const repoRequire = createRequire(new URL("../../packages/migration/package.json", import.meta.url));
+const { chromium } = repoRequire("playwright-core");
+const CHROME_PATHS = [
+  process.env.CHROME_PATH,
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "/Applications/Chromium.app/Contents/MacOS/Chromium",
+  "/usr/bin/google-chrome",
+  "/usr/bin/chromium-browser",
+  "/usr/bin/chromium",
+].filter(Boolean);
+const executablePath = CHROME_PATHS.find((p) => existsSync(p));
+const args = process.argv.slice(2);
+const url = args[0];
+if (!url) { console.error("usage: shot.mjs <url> [out] [--full] [--wait ms] [--width px] [--scroll y]"); process.exit(2); }
+const out = args[1] && !args[1].startsWith("--") ? args[1] : "/tmp/shot.jpeg";
+const opt = (k, d) => { const i = args.indexOf(k); return i >= 0 ? args[i + 1] : d; };
+const full = args.includes("--full");
+const wait = parseInt(opt("--wait", "3500"), 10);
+const width = parseInt(opt("--width", "1200"), 10);
+const scrollY = opt("--scroll", null);
+const browser = await chromium.launch(executablePath ? { executablePath } : {});
+try {
+  const page = await browser.newPage({ viewport: { width, height: 900 } });
+  try { await page.goto(url, { waitUntil: "domcontentloaded", timeout: 30000 }); }
+  catch (e) { console.error(`nav warning: ${e.message}`); } // heavy page — screenshot what loaded
+  await page.waitForTimeout(wait);
+  if (scrollY != null) { await page.evaluate((y) => window.scrollTo(0, y), Number(scrollY)); await page.waitForTimeout(600); }
+  await page.screenshot({ path: out, type: "jpeg", quality: 88, fullPage: full && scrollY == null });
+  console.log(`shot: ${out} (${url})`);
+} finally {
+  await browser.close();
+}

package/scripts/dev/tenant-source-root.mjs ADDED Viewed

@@ -0,0 +1,76 @@
+/**
+ * tenant-source-root.mjs — resolve WHERE the developer's editable tenant source
+ * lives, as threaded by `tot dev` (scripts/tot-dev.mjs) via env.
+ *
+ * CRITICAL (standalone write-through): in `--workspace` mode `tot dev` COPIES the
+ * developer's checkout into an in-tree graft and re-syncs on save. The file tree,
+ * viewer, diff and (C5) writer must operate on the developer's REAL CHECKOUT —
+ * NOT the in-tree graft — or edits made in the browser are silently discarded on
+ * the next resync. `tot dev` therefore sets TOT_DEV_SOURCE_ROOT to the checkout
+ * in standalone mode and to `tenants/<id>/` in monorepo mode; this module is the
+ * single reader of that contract.
+ *
+ * Env-only, never SSR: the storefront's SSR frontmatter runs in workerd (even
+ * under `astro dev`) and can't see TOT_DEV_* — so the panel derives tenant +
+ * root from these endpoints, never from an SSR prop.
+ *
+ * Dependency-free (node: builtins) — copies into the standalone runner, testable
+ * under `node --test`.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+/**
+ * @returns {{ok:true, tenantId:string, sourceRoot:string, gitCwd:string}
+ *          | {ok:false, status:string, message:string}}
+ * `gitCwd` is the working dir for C4's `git show HEAD:<pathspec>` — the source
+ * root is its own git working tree in standalone mode, and lies within the
+ * monorepo's tree in monorepo mode, so the source root serves as gitCwd in both.
+ */
+export function resolveTenantSourceRoot(env = process.env) {
+  const tenantId = env.TOT_DEV_TENANT || null;
+  const sourceRoot = env.TOT_DEV_SOURCE_ROOT || null;
+  if (!tenantId) {
+    return {
+      ok: false,
+      status: "no_tenant",
+      message: "TOT_DEV_TENANT is not set — the /dev file tools run only under `tot dev`.",
+    };
+  }
+  if (!sourceRoot) {
+    return {
+      ok: false,
+      status: "no_source_root",
+      message:
+        "TOT_DEV_SOURCE_ROOT is not set — update `tot dev` (scripts/tot-dev.mjs) to thread it onto the astro dev child.",
+    };
+  }
+  const abs = resolve(sourceRoot);
+  if (!existsSync(abs)) {
+    return { ok: false, status: "missing_source_root", message: `TOT_DEV_SOURCE_ROOT does not exist: ${abs}` };
+  }
+  return { ok: true, tenantId, sourceRoot: abs, gitCwd: abs };
+}
+/**
+ * The WRITER side of the same contract: decide the absolute TOT_DEV_SOURCE_ROOT
+ * `tot dev` (scripts/tot-dev.mjs) threads onto the astro dev child.
+ *
+ * STANDALONE (`--workspace <path>`): the developer's REAL checkout — the /dev
+ * file tools MUST read+write it, NOT the in-tree graft, or browser edits are
+ * silently discarded on the next resync (see the module header). MONOREPO (no
+ * workspace): the in-tree `tenants/<id>/` dir the app globs from.
+ *
+ * @param {string|null|undefined} workspacePath the `--workspace` checkout path, if any
+ * @param {string} repoRoot the storefront repo root
+ * @param {string} tenant the tenant id
+ * @returns {string} absolute source root
+ */
+export function resolveDevSourceRoot(workspacePath, repoRoot, tenant) {
+  return workspacePath
+    ? resolve(workspacePath)
+    : resolve(repoRoot, "tenants", tenant);
+}

package/scripts/dev/unified-diff.mjs ADDED Viewed

@@ -0,0 +1,81 @@
+/**
+ * Minimal unified-diff applier for the inline-AI edit loop (WS5 G1).
+ *
+ * The MCP `content_edit` tool returns a per-file unified diff (`--- a/<path>` /
+ * `+++ b/<path>` header, `@@ -l,c +l,c @@` hunks) rather than a full-file
+ * rewrite — this is what turns that diff back into the file's new content, so
+ * `tot dev` can apply it, hot-reload, and undo it cleanly. Dependency-free
+ * (matches the rest of the tenant tooling — see packages/cli/src/mcp.mjs).
+ *
+ * Deliberately narrow: standard unified-diff hunks only (context/added/removed
+ * lines prefixed ` `/`+`/`-`), no fuzzy matching, no rename/binary support —
+ * that's exactly the shape content_edit's system prompt asks the model for.
+ */
+/** One `@@ -l,c +l,c @@` hunk: the old/new starting line + its body lines. */
+function parseHunks(diff) {
+  const lines = diff.split(/\r?\n/);
+  const hunks = [];
+  let current = null;
+  const hunkHeader = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+  for (const line of lines) {
+    const m = hunkHeader.exec(line);
+    if (m) {
+      current = { oldStart: Number(m[1]), body: [] };
+      hunks.push(current);
+      continue;
+    }
+    if (!current) continue; // header lines (---/+++) or preamble — skip
+    if (line.startsWith(" ") || line.startsWith("+") || line.startsWith("-")) {
+      current.body.push(line);
+    }
+    // A line with no +/-/space prefix inside a hunk (e.g. "\ No newline at
+    // end of file") is ignored — we don't model trailing-newline markers.
+  }
+  return hunks;
+}
+/**
+ * Apply a unified diff to `content`, returning the new content.
+ * Throws with a descriptive message if a hunk's context/removed lines don't
+ * match the given content at the expected position (the diff is stale or the
+ * file changed underneath it) — callers should surface this, never guess.
+ */
+export function applyUnifiedDiff(content, diff) {
+  const original = content.split(/\r?\n/);
+  const hunks = parseHunks(diff);
+  if (hunks.length === 0) return content; // no-op diff
+  const result = [];
+  let cursor = 0; // 0-indexed position in `original` we've copied through
+  for (const hunk of hunks) {
+    const start = hunk.oldStart - 1; // hunk headers are 1-indexed
+    if (start < cursor) {
+      throw new Error(`overlapping or out-of-order hunk at line ${hunk.oldStart}`);
+    }
+    // Copy untouched context up to the hunk.
+    result.push(...original.slice(cursor, start));
+    let pos = start;
+    for (const line of hunk.body) {
+      const tag = line[0];
+      const text = line.slice(1);
+      if (tag === " " || tag === "-") {
+        if (original[pos] !== text) {
+          throw new Error(
+            `diff does not match file content at line ${pos + 1}: `
+            + `expected ${JSON.stringify(text)}, found ${JSON.stringify(original[pos])}`,
+          );
+        }
+        if (tag === " ") result.push(text);
+        pos += 1;
+      } else if (tag === "+") {
+        result.push(text);
+      }
+    }
+    cursor = pos;
+  }
+  result.push(...original.slice(cursor));
+  return result.join("\n");
+}