@tokenoftrust/storefront-runner 1.3.2

package/scripts/tot-dev.mjs

@@ -0,0 +1,376 @@
+#!/usr/bin/env node
+/**
+ * `tot dev` — the developer's on-save local preview loop (the magic).
+ *
+ * Boots the storefront's `astro dev` (which already gives Vite HMR / live-reload
+ * on save) and points the browser at the developer's tenant via the DNS-free
+ * path-prefix route (`/<appDomain>/`). Edit a file under `content/<tenant>/`
+ * (home.html, pages, chrome) or the tenant theme → save → the browser reloads.
+ * Private, on-save, NO publish: product data renders from local fixtures; nothing
+ * is written to KV or shared. ("Publish" — to test/live — stays a separate,
+ * deliberate, compliance-gated step.)
+ *
+ * TWO MODES
+ *   1. MONOREPO (default): `node scripts/tot-dev.mjs <tenant>` — runs astro dev
+ *      over the in-tree colocated `tenants/<tenant>/` layout (content/, public/,
+ *      theme.json).
+ *   2. STANDALONE: `node scripts/tot-dev.mjs --workspace <checkout-path>` — the
+ *      developer has cloned their tenant's Gitea repo (a FLAT, tenant-centric
+ *      layout: `content/`, `public/`, `theme.json`, `.tot/config.json`). This mode
+ *      reads the checkout's `.tot/config.json` `mappings` and grafts each workspace
+ *      prefix into the storefront paths the app globs, then boots the same astro dev.
+ *      Edits in the CHECKOUT hot-reload via Vite. On exit the graft (and any
+ *      backed-up in-tree tenant content) is restored — the tree is left clean.
+ *      Phase-0 bridge: the platform still comes from THIS storefront checkout; the
+ *      containerized "platform baked in, tenant clone mounted" version is deferred.
+ *
+ *      WHY COPY+WATCH, NOT SYMLINK: a symlink from the in-tree path to the checkout
+ *      resolves (in Vite) to the checkout's REAL path, which is OUTSIDE the app root,
+ *      so Vite's `server.fs.allow` denies the `?raw`/glob import ("Denied ID …"). So
+ *      we COPY the checkout's files into the in-tree paths (inside the app root, which
+ *      Vite trusts) and run a recursive `fs.watch` on the checkout that re-syncs each
+ *      changed file back into the in-tree copy on save — which is what fires Vite HMR.
+ *
+ * Two things learned the hard way (see the two-liners below):
+ *   - Tenant is selected by the URL path-prefix (`/<appDomain>/`), NOT by
+ *     DEFAULT_TENANT_ID — the @astrojs/cloudflare dev runtime (workerd) reads env
+ *     from .dev.vars/bindings, so a spawned process.env var never reaches it, and
+ *     a bare `/` falls back to the first static tenant (pilot).
+ *   - `--host` is passed so the server binds all interfaces (0.0.0.0 + ::).
+ *     Without it astro/vite may bind IPv6 `::1` only, and browsers that resolve
+ *     `localhost` to IPv4 `127.0.0.1` get "unable to connect".
+ *
+ * Usage:
+ *   node scripts/tot-dev.mjs <tenant> [--port 4321]
+ *   node scripts/tot-dev.mjs sample-store.example
+ *   node scripts/tot-dev.mjs --workspace ~/tot/site [--port 4321]   (standalone)
+ *   (from a workspace dir with .tot/config.json)  node <repo>/scripts/tot-dev.mjs
+ *
+ * Ctrl-C stops the server. Exit 1 = can't resolve tenant/domain/workspace; 2 = bad usage.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import {
+  readFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  renameSync,
+  rmSync,
+  cpSync,
+} from "node:fs";
+import { dirname, resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveDevSourceRoot } from "./dev/tenant-source-root.mjs";
+import { firstFreePort } from "./dev/port-check.mjs";
+import { resync, startWatch } from "./dev/checkout-watch.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, ".."); // scripts/ -> repo root
+
+const argv = process.argv.slice(2);
+const flag = (name, def) => {
+  const i = argv.indexOf(`--${name}`);
+  return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : def;
+};
+
+// `--version` / `-v` / `version` → print the runner's PUBLISHED version and exit.
+// Reads the emitted root package.json (build-runner.mjs stamps RUNNER_VERSION in
+// PUBLISH mode). This is the version the 2026-07-14 cache-staleness bug hid — the
+// runner kept being served from a stale public-0.1.0 dir with no way to see it —
+// so making it directly checkable (npm bin `storefront-runner`) is part of the fix.
+if (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "version") {
+  let v = "0.0.0";
+  try {
+    v = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8")).version || v;
+  } catch {
+    /* fall back to 0.0.0 */
+  }
+  console.log(v);
+  process.exit(0);
+}
+
+// --- workspace (standalone) mode? --------------------------------------------
+// `--workspace <path>` points at a developer's cloned tenant repo (flat layout +
+// .tot/config.json). Absent → classic monorepo mode.
+const workspacePath = flag("workspace", null);
+
+// --- resolve the tenant + its appDomain --------------------------------------
+// In monorepo mode the workspace config (if any) is read from CWD, as before.
+// In standalone mode it comes from the checkout's .tot/config.json.
+const cfgPath = workspacePath
+  ? join(resolve(workspacePath), ".tot", "config.json")
+  : join(process.cwd(), ".tot", "config.json");
+let cfg = null;
+if (existsSync(cfgPath)) {
+  try {
+    cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+  } catch {
+    /* ignore */
+  }
+}
+
+if (workspacePath && !cfg) {
+  console.error(
+    `✗ standalone mode: no readable .tot/config.json under ${resolve(workspacePath)}\n` +
+      `  Is this a materialized tenant checkout (content/, public/, theme.json, .tot/config.json)?`,
+  );
+  process.exit(1);
+}
+
+let tenant = argv[0] && !argv[0].startsWith("--") ? argv[0] : null;
+tenant = tenant ?? cfg?.tenant ?? null;
+
+if (!tenant) {
+  console.error(
+    "usage: node scripts/tot-dev.mjs <tenant> [--port 4321]\n" +
+      "       node scripts/tot-dev.mjs --workspace <checkout-path> [--port 4321]\n" +
+      "  (or run from a workspace dir containing .tot/config.json)",
+  );
+  process.exit(2);
+}
+
+/** The path-prefix segment that selects this tenant: its registered appDomain. */
+function resolveDomain(id) {
+  // A workspace marker's `scope` carries the appDomain — but only trust it when
+  // it looks like a hostname (has a dot), since the path-prefix route only
+  // matches a domain that strictly claims the tenant (see tenantRouting.ts).
+  if (cfg?.scope && cfg.scope.includes(".")) return cfg.scope;
+  try {
+    const src = readFileSync(
+      resolve(repoRoot, "apps/storefront/src/config/tenants.ts"),
+      "utf8",
+    );
+    // Each tenant block declares tenant_id then appDomain; pair them up.
+    const re = /tenant_id:\s*"([^"]+)"[\s\S]*?appDomain:\s*"([^"]+)"/g;
+    for (let m; (m = re.exec(src)); ) if (m[1] === id) return m[2];
+  } catch {
+    /* ignore */
+  }
+  return null;
+}
+
+const domain = resolveDomain(tenant);
+if (!domain) {
+  console.error(
+    `✗ couldn't resolve a domain for "${tenant}" — is it registered in ` +
+      `apps/storefront/src/config/tenants.ts (or set as a hostname in .tot/config.json scope)?`,
+  );
+  process.exit(1);
+}
+
+// --- standalone: graft the checkout into the storefront's globbed paths -------
+// COPY the checkout's files into the in-tree paths (so Vite's fs.allow trusts them)
+// + fs.watch the checkout to re-sync each save into the in-tree copy (fires HMR).
+// Records let us undo everything on exit (leave the tree exactly as found).
+/** @type {{ target: string, backup: string|null }[]} */
+const grafts = [];
+/** @type {import("node:fs").FSWatcher[]} */
+const watchers = [];
+let cleanedUp = false;
+
+function isSymlink(p) {
+  try {
+    return lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Move `from` → `to`, with a cross-device fallback. In the container the baked-in
+ * `tenants/<id>/` lives in a read-only overlay layer, and overlayfs can't rename a
+ * directory across the layer boundary — `renameSync` throws EXDEV. Fall back to a
+ * recursive copy + remove so the graft's move-aside/restore still works there. On
+ * macOS (same-fs) the fast rename is taken.
+ */
+function movePath(from, to) {
+  try {
+    renameSync(from, to);
+  } catch (e) {
+    if (e?.code !== "EXDEV") throw e;
+    cpSync(from, to, { recursive: true });
+    rmSync(from, { recursive: true, force: true });
+  }
+}
+
+function cleanupGrafts() {
+  if (cleanedUp) return;
+  cleanedUp = true;
+  for (const w of watchers) {
+    try {
+      w.close();
+    } catch {
+      /* best effort */
+    }
+  }
+  // Undo in reverse: remove our copied-in files, then restore any backed-up content.
+  for (const { target, backup } of grafts.reverse()) {
+    try {
+      if (existsSync(target) || isSymlink(target)) rmSync(target, { recursive: true, force: true });
+    } catch {
+      /* best effort */
+    }
+    if (backup) {
+      try {
+        movePath(backup, target);
+      } catch {
+        /* best effort */
+      }
+    }
+  }
+}
+
+// resync() + startWatch() moved to scripts/dev/checkout-watch.mjs (testable +
+// ships in the runner via copyMjsFlat). startWatch now polls by default for
+// reliable save detection — native fs.watch dropped editor atomic-saves on macOS.
+
+if (workspacePath) {
+  const wsRoot = resolve(workspacePath);
+  const mappings = Array.isArray(cfg.mappings) ? cfg.mappings : [];
+  if (mappings.length === 0) {
+    console.error(`✗ .tot/config.json has no "mappings" — cannot graft the checkout.`);
+    process.exit(1);
+  }
+
+  console.log(`\n  tot dev — standalone (${tenant})`);
+  console.log(`  checkout: ${wsRoot}`);
+
+  for (const map of mappings) {
+    // `workspace` is the checkout-relative prefix (e.g. "content/", "theme.json").
+    // COLOCATION: a tenant IS the repo-root dir `tenants/<id>/`, and the checkout
+    // (a `git subtree split --prefix=tenants/<id>` of that dir) has the SAME layout
+    // at its root — so the graft is an identity map: content/ -> tenants/<id>/content/,
+    // public/ -> tenants/<id>/public/, theme.json -> tenants/<id>/theme.json. We map
+    // structurally (ignoring any legacy `repo` field in the checkout's .tot/config.json).
+    const wsRel = String(map.workspace ?? "").replace(/\/+$/, "");
+    if (!wsRel) continue;
+    const repoRel = join("tenants", tenant, wsRel);
+
+    const source = resolve(wsRoot, wsRel); // real files in the checkout
+    const target = resolve(repoRoot, repoRel); // where the app globs them
+    const isDir = map.kind !== "file";
+
+    if (!existsSync(source)) {
+      console.warn(`  ⚠ checkout has no ${wsRel} — skipping (${map.kind ?? "?"})`);
+      continue;
+    }
+
+    // Ensure the destination's parent exists (e.g. content/ or themes/tenants/).
+    mkdirSync(dirname(target), { recursive: true });
+
+    // If real in-tree content already occupies the destination, move it aside so
+    // we can restore it verbatim on exit (never destroy tracked tenant content).
+    let backup = null;
+    if (existsSync(target) || isSymlink(target)) {
+      backup = `${target}.__totdev_bak_${process.pid}`;
+      movePath(target, backup);
+    }
+
+    // COPY the checkout's files into the in-tree path (inside Vite's trusted root).
+    cpSync(source, target, { recursive: true });
+    grafts.push({ target, backup });
+
+    // WATCH the checkout for saves → re-sync into the in-tree copy → Vite HMR.
+    // `startWatch` polls by default (reliable — native fs.watch dropped editor
+    // atomic-saves on macOS); TOT_DEV_NATIVE_WATCH=1 opts into event-driven watch.
+    try {
+      const w = startWatch(source, isDir, (rel) => resync(source, target, rel));
+      watchers.push(w);
+    } catch (e) {
+      console.warn(`  ⚠ could not watch ${wsRel} (edits won't hot-reload): ${e?.message}`);
+    }
+
+    console.log(`  ↪ ${repoRel} ⇐ ${wsRel}${backup ? " (in-tree content backed up)" : ""}`);
+  }
+
+  if (grafts.length === 0) {
+    console.error(`✗ nothing to graft — the checkout had none of the mapped prefixes.`);
+    cleanupGrafts();
+    process.exit(1);
+  }
+} else if (!existsSync(resolve(repoRoot, "tenants", tenant, "content"))) {
+  console.warn(`⚠ no tenants/${tenant}/content/ found — the tenant may not be registered yet.`);
+}
+
+// Resolve the port BEFORE printing a URL or booting astro. Vite's `strictPort`
+// defaults off, so a taken port makes astro SILENTLY drift to the next free one —
+// which then mismatches the URL we (and the CLI's liveness poll) advertise, and a
+// stale server on the original port produced a false "You're live" (2026-07-14).
+// Instead we pick the first free port ourselves and PRINT it, so a busy default
+// port "just works" (better UX than failing). See port-check.mjs.
+const requestedPort = Number(flag("port", "4321"));
+const resolvedPort = await firstFreePort(requestedPort);
+const port = String(resolvedPort);
+if (resolvedPort !== requestedPort) {
+  console.log(`  ⚠ port ${requestedPort} was busy — starting on ${resolvedPort} instead.`);
+}
+
+// Land the developer on their store ROOT (plain save→reload HMR against their own
+// site) — not the /dev cockpit, which is a hosted-only surface excluded from the
+// local runner build (see build-runner.mjs DROP + stripCockpitPlugins).
+const url = `http://localhost:${port}/${domain}/`;
+
+console.log(`\n  tot dev — ${tenant}`);
+console.log(`  → ${url}`);
+if (workspacePath) {
+  console.log(`  Edit files in your CHECKOUT (content/*.html, theme.json, public/…) + save → the browser reloads.`);
+} else {
+  console.log(`  Edit tenants/${tenant}/content/*.html (or the theme) + save → the browser reloads.`);
+}
+console.log(`  Private local preview — nothing is published. Server binds all interfaces (LAN-visible). Ctrl-C to stop.\n`);
+
+// --- mirror colocated tenant public/ assets into the storefront public/ dir ----
+// astro dev is exec'd directly below (bypassing the `predev` npm lifecycle), so
+// run the copy here: tenants/<id>/public/** -> apps/storefront/public/tenants/<id>/.
+// Must run AFTER any standalone graft (so a grafted checkout's public/ is mirrored).
+{
+  const r = spawnSync(
+    "node",
+    [resolve(repoRoot, "scripts/build/copy-tenant-assets.mjs")],
+    { cwd: repoRoot, stdio: "inherit" },
+  );
+  if (r.status !== 0) {
+    console.warn("  ⚠ copy-tenant-assets failed — static tenant assets may 404.");
+  }
+}
+
+// --- boot astro dev (Vite HMR); --host so IPv4 `localhost`/127.0.0.1 both work -
+// In standalone mode we MUST keep astro in the FOREGROUND, attached to this
+// process: Astro 7 auto-detects an agent-run terminal and forks the dev server to
+// a detached daemon (`astro dev stop/status`), which would make THIS process exit
+// immediately — firing our cleanup and tearing down the graft symlinks while the
+// daemon keeps serving the (restored) in-tree content. Setting ASTRO_DEV_BACKGROUND
+// tells Astro "you are already the managed child → run foreground" (see astro's
+// cli/dev/{index,background}.js), so our SIGINT/exit lifecycle and symlink cleanup
+// stay correct. Monorepo mode is left untouched (current behavior).
+// TOT_DEV_TENANT tells the inline-AI edit loop (WS5 G1 — astro.config.mjs's
+// inlineAiEditPlugin, scripts/dev/ai-edit.mjs) which tenant's content/theme to
+// read+write: one `tot dev <tenant>` run always serves exactly one tenant, so
+// there's no per-request domain lookup to do.
+// TOT_DEV_SOURCE_ROOT tells the /dev file tools (C3 tree/viewer, C4 diff, C5
+// writer — scripts/dev/tenant-source-root.mjs) WHERE the developer's editable
+// source lives. STANDALONE: the developer's REAL checkout (wsRoot) — the tools
+// MUST read+write it, NOT the in-tree graft, or browser edits are silently lost
+// on the next resync. MONOREPO: the in-tree tenants/<id>/ dir.
+const devSourceRoot = resolveDevSourceRoot(workspacePath, repoRoot, tenant);
+const spawnEnv = workspacePath
+  ? { ...process.env, ASTRO_DEV_BACKGROUND: "1", TOT_DEV_TENANT: tenant, TOT_DEV_SOURCE_ROOT: devSourceRoot }
+  : { ...process.env, TOT_DEV_TENANT: tenant, TOT_DEV_SOURCE_ROOT: devSourceRoot };
+const child = spawn(
+  "pnpm",
+  ["--filter", "@tot/storefront-runner", "exec", "astro", "dev", "--port", port, "--host"],
+  { cwd: repoRoot, stdio: "inherit", env: spawnEnv },
+);
+
+// Clean up grafts on every exit path so we never leave symlinks in the tree.
+function shutdown(signal) {
+  child.kill(signal);
+}
+child.on("exit", (code) => {
+  cleanupGrafts();
+  process.exit(code ?? 0);
+});
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+// Belt-and-suspenders: if the parent dies without the child exit firing.
+process.on("exit", cleanupGrafts);

package/tenants/README.md

@@ -0,0 +1,14 @@
+# tenants/
+
+This directory is the **runtime graft target** for the local dev loop — it ships
+**empty** on purpose.
+
+The storefront runner is a moat-free LOCAL dev harness. It bundles **no** tenant
+content. When you run `tot dev`, your OWN tenant checkout (content, theme, public
+assets) is grafted into `tenants/<your-id>/` here, and the renderer's
+checkout-glob resolver discovers and serves it at `/<your-domain>/`. On exit the
+graft is removed and this directory is left empty again.
+
+Do not commit real merchant content here — the runner's build-time clean-guard
+(`scripts/build/check-runner-clean.mjs`) fails the build if anything but this
+README appears under `tenants/`.

package/tenants/home/content/chrome.json

@@ -0,0 +1,7 @@
+{
+  "nav": [],
+  "footer": {
+    "columns": [],
+    "social": []
+  }
+}

package/tenants/home/content/home.html

@@ -0,0 +1,58 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Storefront runner — local dev</title>
+<meta name="description" content="You're running the Token of Trust storefront runner locally.">
+<meta name="robots" content="noindex,nofollow">
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; margin: 0; }
+  body {
+    font-family: system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    line-height: 1.6; color: #16243d; background: #f5f7fa;
+    min-height: 100vh; display: grid; place-items: center; padding: 2rem;
+  }
+  .card {
+    max-width: 640px; width: 100%; background: #fff; border: 1px solid #e3e8ef;
+    border-radius: 16px; padding: 2.5rem; box-shadow: 0 6px 24px rgba(15,33,56,.08);
+  }
+  .badge {
+    display: inline-block; font-size: .78rem; font-weight: 600; letter-spacing: .04em;
+    text-transform: uppercase; color: #1b3b64; background: #eaeef4;
+    padding: .3rem .7rem; border-radius: 999px; margin-bottom: 1.1rem;
+  }
+  h1 { font-size: 1.7rem; line-height: 1.2; margin-bottom: .6rem; color: #0f2138; }
+  p { color: #5b6a82; margin-bottom: 1rem; }
+  code {
+    font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace; font-size: .92em;
+    background: #f5f7fa; border: 1px solid #e3e8ef; border-radius: 6px; padding: .1rem .4rem;
+  }
+  ul { margin: 0 0 1rem 1.2rem; color: #5b6a82; }
+  li { margin-bottom: .4rem; }
+  .muted { font-size: .88rem; color: #8a95a8; margin-bottom: 0; }
+  @media (prefers-color-scheme: dark) {
+    body { color: #e6ebf3; background: #0f1622; }
+    .card { background: #16202e; border-color: #26313f; box-shadow: none; }
+    h1 { color: #f2f5f9; }
+    p, ul { color: #9aa6b8; }
+    .badge { color: #cdd8e6; background: #22303f; }
+    code { background: #0f1622; border-color: #26313f; }
+  }
+</style>
+</head>
+<body>
+<main class="card">
+  <span class="badge">Local dev</span>
+  <h1>You're running the Token of Trust storefront runner locally.</h1>
+  <p>This is the default home page. To make it yours, edit
+    <code>tenants/home/content/home.html</code> and save — this page reloads automatically.</p>
+  <ul>
+    <li>Your real store renders here once you check one out with the Token of Trust CLI.</li>
+    <li>Visit <code>/sample-store.example/</code> to see the bundled sample store, including the 21+ age-gate and nicotine-warning compliance affordances.</li>
+  </ul>
+  <p class="muted">Serving from the storefront runner. No account or network required.</p>
+</main>
+</body>
+</html>

package/tenants/home/content/home.json

@@ -0,0 +1,11 @@
+{
+  "seoTitle": "Storefront runner — local dev",
+  "seoDescription": "You're running the Token of Trust storefront runner locally.",
+  "blocks": [
+    {
+      "component": "hero",
+      "headline": "Running locally",
+      "subhead": "You're running the Token of Trust storefront runner. Edit tenants/home/content/home.html and save to change this page."
+    }
+  ]
+}