@tokenoftrust/storefront-runner 2.4.26 → 2.4.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.4.26",
+  "version": "2.4.27",
   "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/packages/cli/src/publication-spaces.mjs

@@ -0,0 +1,223 @@
+/**
+ * A tenant's publication topology as a developer's workspace sees it: one ROOT repository serving
+ * `/`, plus any MOUNTED spaces — each its own repository serving one mount (`/blog`, `/docs`).
+ *
+ * The platform declares the topology; the workspace only records what it was told, in
+ * `.tot/publication-spaces.json` (written by `tot clone`, never committed — the root repo's git
+ * excludes it, and the `spaces/` folder each mounted space is cloned into). Every command that needs
+ * to know which repository owns a URL or a file reads it through this module, so `tot validate`,
+ * `tot dev`, `tot clone` and the change router answer the same way.
+ *
+ * Mount matching mirrors packages/public-runtime/src/publication-space.ts
+ * (`publicationMountMatchesPath`): a mount owns itself and everything below it, segment-wise and
+ * case-sensitively; the longest matching mount wins and `/` owns what nothing else claims.
+ * apps/storefront/src/config/publicationSpaceOwnership.test.ts pins the two together.
+ *
+ * Dependency-free: the published CLI ships it as-is.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Where `tot clone` puts each mounted space, relative to the root checkout: `spaces/<spaceId>/`. */
+export const SPACES_DIR = "spaces";
+/** The workspace's record of the declared topology, relative to the root checkout. */
+export const TOPOLOGY_FILE = ".tot/publication-spaces.json";
+export const TOPOLOGY_VERSION = 1;
+
+const SPACE_ID = /^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$/;
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/**
+ * @typedef {{ forge: string, repo: string, defaultBranch: string }} SpaceSource
+ * @typedef {{ id: string, mount: string, visibility: "public"|"internal", source: SpaceSource,
+ *   aliases?: string[], collections?: Record<string, string> }} TopologySpace
+ * @typedef {{ version: 1, tenant: string, spaces: TopologySpace[] }} Topology
+ */
+
+/** A mount in canonical form: leading `/`, no trailing `/` except the root itself. Null when not a mount. */
+export function normalizeMount(value) {
+  if (typeof value !== "string" || !value.startsWith("/") || /[?#\\]/.test(value)) return null;
+  const trimmed = value.replace(/\/+$/, "");
+  if (!trimmed) return "/";
+  if (trimmed.split("/").slice(1).some((seg) => !seg || seg === "." || seg === "..")) return null;
+  return trimmed;
+}
+
+/** A request path reduced to what routing reads: no origin, query or fragment; NFC; single slashes. */
+export function normalizeRequestPath(value) {
+  let path = String(value ?? "").trim();
+  try {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path)) path = new URL(path).pathname;
+  } catch {
+    return null;
+  }
+  path = path.replace(/[?#].*$/, "");
+  if (!path.startsWith("/")) path = `/${path}`;
+  try {
+    path = decodeURIComponent(path);
+  } catch {
+    return null;
+  }
+  path = path.normalize("NFC").replace(/\/{2,}/g, "/");
+  return path;
+}
+
+/** Does `mount` own `path` (both normalized)? A mount owns itself and every path below it. */
+export function mountMatchesPath(mount, path) {
+  if (mount === "/") return true;
+  return path === mount || path === `${mount}/` || path.startsWith(`${mount}/`);
+}
+
+/**
+ * Parse a recorded topology. Throws with the reason on anything malformed — a half-read topology
+ * would route a change to the wrong repository.
+ * @param {unknown} input
+ * @returns {Topology}
+ */
+export function parseTopology(input) {
+  const raw = /** @type {any} */ (input);
+  if (!isObject(raw) || raw.version !== TOPOLOGY_VERSION || typeof raw.tenant !== "string" || !raw.tenant ||
+    !Array.isArray(raw.spaces)) {
+    throw new Error(`${TOPOLOGY_FILE} is not a version-${TOPOLOGY_VERSION} topology`);
+  }
+  const ids = new Set();
+  const mounts = new Set();
+  const spaces = raw.spaces.map((space, index) => {
+    const at = `${TOPOLOGY_FILE} spaces[${index}]`;
+    if (!isObject(space) || typeof space.id !== "string" || !SPACE_ID.test(space.id)) throw new Error(`${at}: invalid id`);
+    const mount = normalizeMount(space.mount);
+    if (!mount) throw new Error(`${at}: invalid mount`);
+    if (space.visibility !== "public" && space.visibility !== "internal") throw new Error(`${at}: invalid visibility`);
+    const source = space.source;
+    if (!isObject(source) || typeof source.forge !== "string" || typeof source.repo !== "string" || !source.repo ||
+      typeof source.defaultBranch !== "string" || !source.defaultBranch) throw new Error(`${at}: invalid source`);
+    if (ids.has(space.id)) throw new Error(`${at}: duplicate id ${space.id}`);
+    if (mounts.has(mount)) throw new Error(`${at}: duplicate mount ${mount}`);
+    ids.add(space.id);
+    mounts.add(mount);
+    const aliases = Array.isArray(space.aliases) ? space.aliases.map(normalizeMount).filter(Boolean) : [];
+    return {
+      id: space.id,
+      mount,
+      visibility: space.visibility,
+      source: { forge: source.forge, repo: source.repo, defaultBranch: source.defaultBranch },
+      ...(aliases.length ? { aliases } : {}),
+      ...(isObject(space.collections) ? { collections: { ...space.collections } } : {}),
+    };
+  });
+  if (spaces.filter((space) => space.mount === "/").length !== 1) {
+    throw new Error(`${TOPOLOGY_FILE}: exactly one space must own "/"`);
+  }
+  return { version: TOPOLOGY_VERSION, tenant: raw.tenant, spaces };
+}
+
+/**
+ * Build a topology from the platform's declared-space list (`GET /api/publication-spaces`, whose
+ * rows carry `id`, `visibility`, `canonicalMount`, `source` and `routes`).
+ * @param {string} tenant
+ * @param {unknown} rows
+ * @returns {Topology}
+ */
+export function topologyFromDeclaredSpaces(tenant, rows) {
+  if (!Array.isArray(rows)) throw new Error("the platform returned no publication-space list");
+  return parseTopology({
+    version: TOPOLOGY_VERSION,
+    tenant,
+    spaces: rows.map((row) => ({
+      id: row?.id,
+      mount: row?.routes?.canonicalMount ?? row?.canonicalMount,
+      visibility: row?.visibility,
+      source: row?.source,
+      aliases: Array.isArray(row?.routes?.aliases) ? row.routes.aliases.map((alias) => alias?.from) : undefined,
+      collections: row?.routes?.collections,
+    })),
+  });
+}
+
+/** The root space (owns `/`; `parseTopology` guarantees exactly one). @param {Topology} topology */
+export function rootSpace(topology) {
+  return /** @type {TopologySpace} */ (topology.spaces.find((space) => space.mount === "/"));
+}
+
+/** The mounted spaces, longest mount first. @param {Topology} topology */
+export function mountedSpaces(topology) {
+  return topology.spaces.filter((space) => space.mount !== "/").sort((a, b) => b.mount.length - a.mount.length);
+}
+
+/**
+ * Which space owns a URL path: the longest canonical mount (or alias) that owns it, else the root.
+ * Returns null for a path that cannot be read as a URL path.
+ * @param {Topology} topology
+ * @param {string} urlPath
+ * @returns {{ space: TopologySpace, via: "mount"|"alias"|"root" } | null}
+ */
+export function owningSpace(topology, urlPath) {
+  const path = normalizeRequestPath(urlPath);
+  if (path === null) return null;
+  /** @type {{ space: TopologySpace, via: "mount"|"alias", mount: string } | null} */
+  let best = null;
+  for (const space of topology.spaces) {
+    if (space.mount === "/") continue;
+    /** @type {Array<[string, "mount"|"alias"]>} */
+    const claims = [[space.mount, "mount"], ...(space.aliases ?? []).map((alias) => /** @type {[string, "alias"]} */ ([alias, "alias"]))];
+    for (const [mount, via] of claims) {
+      if (mountMatchesPath(mount, path) && (!best || mount.length > best.mount.length)) best = { space, via, mount };
+    }
+  }
+  if (best) return { space: best.space, via: best.via };
+  return { space: rootSpace(topology), via: "root" };
+}
+
+/** A mounted space's working tree, relative to the root checkout. @param {TopologySpace} space */
+export function spaceDir(space) {
+  return space.mount === "/" ? "" : `${SPACES_DIR}/${space.id}`;
+}
+
+/**
+ * Which space a workspace file belongs to, from its path relative to the root checkout:
+ * `spaces/<id>/...` is that space's, everything else is the root's. A file under `spaces/` naming
+ * no declared space belongs to none (null) — it must not be routed anywhere.
+ * @param {Topology} topology
+ * @param {string} relPath
+ * @returns {{ space: TopologySpace, path: string } | null}
+ */
+export function spaceForWorkspaceFile(topology, relPath) {
+  const rel = String(relPath).replace(/\\/g, "/").replace(/^\.\//, "");
+  if (rel === SPACES_DIR || rel.startsWith(`${SPACES_DIR}/`)) {
+    const [, id, ...rest] = rel.split("/");
+    const space = topology.spaces.find((candidate) => candidate.mount !== "/" && candidate.id === id);
+    return space ? { space, path: rest.join("/") } : null;
+  }
+  return { space: rootSpace(topology), path: rel };
+}
+
+/** Read a workspace's recorded topology, or null when the workspace records none. Throws when malformed. */
+export function readWorkspaceTopology(workspace) {
+  const file = join(workspace, TOPOLOGY_FILE);
+  if (!existsSync(file)) return null;
+  return parseTopology(JSON.parse(readFileSync(file, "utf8")));
+}
+
+/**
+ * Record a topology in a root checkout, and keep it — and the cloned spaces — out of the root
+ * repository: both are listed in the checkout's own `.git/info/exclude`, never in a committed file.
+ */
+export function writeWorkspaceTopology(workspace, topology) {
+  const file = join(workspace, TOPOLOGY_FILE);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(parseTopology(topology), null, 2)}\n`);
+  excludeFromRootRepo(workspace, [`/${TOPOLOGY_FILE}`, `/${SPACES_DIR}/`]);
+}
+
+/** Append patterns to `<workspace>/.git/info/exclude`, once each. No-op outside a git checkout. */
+export function excludeFromRootRepo(workspace, patterns) {
+  const gitDir = join(workspace, ".git");
+  if (!existsSync(gitDir)) return;
+  const file = join(gitDir, "info", "exclude");
+  mkdirSync(dirname(file), { recursive: true });
+  const current = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const lines = new Set(current.split("\n").map((line) => line.trim()));
+  const missing = patterns.filter((pattern) => !lines.has(pattern));
+  if (!missing.length) return;
+  appendFileSync(file, `${current && !current.endsWith("\n") ? "\n" : ""}${missing.join("\n")}\n`);
+}

package/scripts/dev/publication-spaces-loop.mjs

@@ -0,0 +1,122 @@
+/**
+ * `tot dev`'s mounted publication spaces: run `publication-spaces-dev.ts` (compose the tenant's
+ * declared spaces from their local working trees through the publish-path composition, then seed
+ * the dev server's local state) alongside the dev server, and again whenever a space's working tree
+ * changes — so `/docs`, `/blog`, ... render locally from the same route plan visitors get, and a
+ * save in a space shows on the next reload.
+ *
+ * The composition is the private control plane, so it runs only where the platform tree is present
+ * (the storefront monorepo). The public runner ships without it; there a checkout that has cloned
+ * spaces is told which paths will not render, instead of silently serving 404s under each mount.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { startWatch } from "./checkout-watch.mjs";
+
+export const SEEDER = "scripts/dev/publication-spaces-dev.ts";
+
+/** Can this tree compose publication spaces? (The public runner cannot: no control plane.) */
+export function publicationSpacesComposable(repoRoot) {
+  return existsSync(join(repoRoot, SEEDER)) &&
+    existsSync(join(repoRoot, "packages", "private-controlplane")) &&
+    existsSync(join(repoRoot, "apps", "storefront", "node_modules", ".bin", "tsx"));
+}
+
+/** The seeder argv for a tenant (and the developer's checkout, in workspace mode). Pure. */
+export function seederArgs(repoRoot, tenant, workspace) {
+  return [join(repoRoot, SEEDER), "--tenant", tenant, ...(workspace ? ["--workspace", workspace] : [])];
+}
+
+/** Read the seeder's one-line JSON verdict from its stdout; null when it printed none. Pure. */
+export function parseSeederVerdict(stdout) {
+  const line = String(stdout).trim().split("\n").filter(Boolean).pop();
+  if (!line) return null;
+  try {
+    const parsed = JSON.parse(line);
+    return parsed && typeof parsed.status === "string" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The developer-facing line for a verdict. Pure. */
+export function describeVerdict(verdict, { first }) {
+  if (!verdict) return "  ⚠ mounted publication spaces could not be composed — their paths will 404 locally.";
+  switch (verdict.status) {
+    case "seeded": {
+      const mounts = verdict.spaces.map((space) => `${space.mount}/ (${space.spaceId})`).join(", ");
+      return first ? `  ✓ mounted spaces render locally: ${mounts}` : `  ↻ re-composed mounted spaces: ${mounts} — reload to see it`;
+    }
+    case "incomplete":
+      return `  ⚠ mounted spaces not composed — ${verdict.missing.join("; ")}. Their paths 404 locally until cloned (tot clone).`;
+    case "refused":
+      return `  ✗ the publish-path composition refused ${verdict.spaceId ?? "this topology"}: ${verdict.code} — a publish would refuse it too.`;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Compose + seed once now, then again on every change under `watchDirs()`. Runs are serialized: a
+ * save during a run schedules exactly one more. Returns `{ close }`.
+ * @param {{ repoRoot: string, tenant: string, workspace: string|null, log?: (line: string) => void,
+ *   spawnImpl?: typeof spawn, watch?: typeof startWatch, watchDirs?: (verdict: any) => string[] }} input
+ */
+export function startPublicationSpacesLoop({
+  repoRoot, tenant, workspace, log = console.log, spawnImpl = spawn, watch = startWatch,
+  watchDirs = (verdict) => verdict?.watch ?? [],
+}) {
+  const appDir = join(repoRoot, "apps", "storefront");
+  const tsx = join(appDir, "node_modules", ".bin", "tsx");
+  const watchers = [];
+  let running = false;
+  let again = false;
+  let closed = false;
+  let first = true;
+  let watching = false;
+
+  const run = () => {
+    if (closed) return;
+    if (running) { again = true; return; }
+    running = true;
+    let stdout = "";
+    let stderr = "";
+    const child = spawnImpl(tsx, seederArgs(repoRoot, tenant, workspace), { cwd: appDir, stdio: ["ignore", "pipe", "pipe"] });
+    child.stdout?.on("data", (chunk) => { stdout += chunk; });
+    child.stderr?.on("data", (chunk) => { stderr += chunk; });
+    child.on("close", () => {
+      running = false;
+      const verdict = parseSeederVerdict(stdout);
+      if (!verdict && stderr.trim()) log(`  ⚠ ${stderr.trim().split("\n").pop()}`);
+      const line = describeVerdict(verdict, { first });
+      if (line && !(verdict?.status === "none")) log(line);
+      first = false;
+      if (!watching && verdict && verdict.status !== "none") {
+        watching = true;
+        for (const dir of watchDirs(verdict)) {
+          try {
+            watchers.push(watch(dir, true, () => run()));
+          } catch {
+            log(`  ⚠ could not watch ${dir} — re-run tot dev to pick up its changes.`);
+          }
+        }
+      }
+      if (again) { again = false; run(); }
+    });
+    child.on("error", (error) => {
+      running = false;
+      log(`  ⚠ mounted publication spaces could not be composed: ${error.message}`);
+    });
+  };
+
+  run();
+  return {
+    close() {
+      closed = true;
+      for (const watcher of watchers) {
+        try { watcher.close(); } catch { /* best effort */ }
+      }
+    },
+  };
+}

package/scripts/tot-dev.mjs

@@ -68,6 +68,8 @@ import { busyPortMessage, classifyBusyPort, lockPort, unlockPort } from "./dev/p
 import { resync, startWatch } from "./dev/checkout-watch.mjs";
 import { standaloneGraftPlan } from "./dev/standalone-graft-plan.mjs";
 import { findMissingCtaIds } from "./tenant/validate.mjs";
+import { publicationSpacesComposable, startPublicationSpacesLoop } from "./dev/publication-spaces-loop.mjs";
+import { SPACES_DIR } from "../packages/cli/src/publication-spaces.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(here, ".."); // scripts/ -> repo root
@@ -415,14 +417,13 @@ console.log(`  Private local preview — nothing is published. Server binds all
 }
 
 // --- 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).
+// astro MUST stay 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
+// (tearing down the graft, stopping the publication-space loop) while the daemon
+// keeps serving. 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 stays correct in both modes.
 // TOT_DEV_TENANT tells the inline-AI edit loop (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
@@ -433,9 +434,7 @@ console.log(`  Private local preview — nothing is published. Server binds all
 // 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 spawnEnv = { ...process.env, ASTRO_DEV_BACKGROUND: "1", TOT_DEV_TENANT: tenant, TOT_DEV_SOURCE_ROOT: devSourceRoot };
 // LAUNCHER-AGNOSTIC astro spawn: the published runner tree may have been
 // installed by pnpm OR npm (npm ships with every Node — the runner must not
 // require pnpm at RUNTIME), so resolve astro's real entry through Node's own
@@ -453,12 +452,31 @@ const child = spawn(
   { cwd: appDir, stdio: "inherit", env: spawnEnv },
 );
 
+// --- mounted publication spaces (/docs, /blog, ...) -----------------------------
+// Composed from their local working trees through the publish-path composition and seeded into
+// the dev server's local state while astro boots, then again on every save in a space (see
+// scripts/dev/publication-spaces-loop.mjs). The public runner has no composition, so there a
+// checkout with cloned spaces is told its mounted paths will not render rather than left to 404.
+let spacesLoop = null;
+if (publicationSpacesComposable(repoRoot)) {
+  spacesLoop = startPublicationSpacesLoop({
+    repoRoot,
+    tenant,
+    workspace: workspacePath ? resolve(workspacePath) : null,
+  });
+} else if (workspacePath && existsSync(join(resolve(workspacePath), SPACES_DIR))) {
+  console.warn(
+    `  ⚠ this checkout has mounted publication spaces (${SPACES_DIR}/) — the public preview engine renders the root only, so their paths 404 here.`,
+  );
+}
+
 // Clean up grafts + the port lock on every exit path so we never leave
 // symlinks in the tree, or a lock a LATER run would misread as still live.
 function shutdown(signal) {
   child.kill(signal);
 }
 function cleanupAll() {
+  spacesLoop?.close();
   cleanupGrafts();
   unlockPort(resolvedPort);
 }