@tokenoftrust/cli 2.4.1 → 2.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.4.1",
+  "version": "2.4.3",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/commands/submit.mjs

@@ -28,11 +28,12 @@
  * needed. `--watch` just raises the budget (longer waitMs, more attempts) so an
  * attached dev can stay and watch reconcile+compliance resolve live.
  *
- * Watching through to accept (E1b): `--watch` also sets untilShipped, so once
- * reconcile resolves cleanly the loop keeps going (preview_status reuses the
- * SAME waitMs budget server-side to long-poll for a ship decision too — one
- * poll axis, not two) until change_accept ships it or the attempts budget
- * runs out. A failed reconcile never waits for ship — it can't have shipped.
+ * Watching through to live (E1b): `--watch` also sets untilShipped, so once
+ * reconcile resolves cleanly the loop keeps going until the pipeline verdict
+ * (`preview_status.verdict`) shows this commit live — on Cloudflare once the
+ * pointer flip is proven, on CloudFront once the CI publish is confirmed — or the
+ * attempts budget runs out. A failed reconcile never waits for ship — it can't
+ * have shipped.
  * Detached devs get the E1 email instead; this is the attached half.
  *
  * Dependency-free (global fetch + `git`).
@@ -1798,7 +1799,7 @@ export async function run(argv, ctx, {
     let status;
     operation = "preview_status";
     if (args.noWait) {
-      status = normalizePreviewStatus(await scoped.callTool("preview_status", { commit: statusSha }));
+      status = normalizePreviewStatus(await scoped.callTool("preview_status", { commit: statusSha }), statusSha);
     } else {
       // One in-place status line (TTY: a spinner with an elapsed-seconds counter;
       // non-TTY: a ~10s heartbeat) instead of a newline per poll — the wait reads
@@ -1880,10 +1881,10 @@ export async function run(argv, ctx, {
 /**
  * Normalize a `preview_status` tool response to the contract shape the CLI reports
  * on: { status, reconcile:{ok,errors}, compliance:{verdict,detail}, previewUrl,
- * shipped, delivery, dispatched }. A live tool always returns status
+ * shipped, delivery, dispatched, verdict }. A live tool always returns status
  * pending|reconciled|failed; anything else (an older MCP without the tool's flat
  * fields) normalizes to "unknown" so the CLI degrades visibly instead of pretending
- * it reconciled. `shipped` (E1b) is null until change_accept ships this exact commit.
+ * it reconciled. `shipped` (E1b) is derived from the verdict: null until this commit is live.
  *
  * `delivery` is the MCP's reconcile-observability triad for the Gitea webhook that
  * fired on this commit ({ target, actual, evidence, drift? }) — or null when NO
@@ -1893,7 +1894,11 @@ export async function run(argv, ctx, {
  * read under a different tenant scope than it was pushed to), which is a permanent
  * dead-end the CLI must not report as "still reconciling". Pure — unit-tested.
  */
-export function normalizePreviewStatus(r) {
+/**
+ * @param {any} r  the `preview_status` response
+ * @param {string|null} [commit]  the sha the status was asked for (what `shipped` is decided against)
+ */
+export function normalizePreviewStatus(r, commit = null) {
   const status = r?.status;
   const known = status === "pending" || status === "reconciled" || status === "failed";
   const delivery = r?.delivery ?? null;
@@ -1902,7 +1907,7 @@ export function normalizePreviewStatus(r) {
     reconcile: r?.reconcile ?? null,
     compliance: r?.compliance ?? null,
     previewUrl: r?.previewUrl ?? null,
-    shipped: r?.shipped ?? null,
+    shipped: shippedFromVerdict(r?.verdict ?? null, commit),
     delivery,
     dispatched: delivery != null,
     // The ONE pipeline-status read every surface (console, `preview_status`, `tot
@@ -1913,6 +1918,26 @@ export function normalizePreviewStatus(r) {
   };
 }
 
+/**
+ * Whether the pipeline verdict shows `commit` live, and where: the live release IS this commit, or
+ * the live release is the next release this commit's change was merged into (its membership names
+ * the commit as a change head). Per provider, the verdict's live release is recorded only once
+ * delivery is proven — the Cloudflare pointer flip read back, or the CloudFront CI publish
+ * confirmed. Null when not live (or no verdict). Pure — unit-tested.
+ * @param {any} verdict  @param {string|null} commit
+ * @returns {{ sha: string, receiptId: string|null, provider: string|null, provedAt: string|null }|null}
+ */
+export function shippedFromVerdict(verdict, commit) {
+  if (!commit || verdict?.kind !== "idle" || !verdict.live?.sha) return null;
+  const live = verdict.live;
+  const merged =
+    verdict.preview?.sha === live.sha &&
+    Array.isArray(verdict.preview?.membership) &&
+    verdict.preview.membership.some((m) => m?.headSha === commit);
+  if (live.sha !== commit && !merged) return null;
+  return { sha: live.sha, receiptId: live.receiptId ?? null, provider: live.provider ?? null, provedAt: live.provedAt ?? null };
+}
+
 /** A submit succeeds only when reconcile has neither failed nor failed to start. */
 export function previewSubmitSucceeded(status) {
   const knownSuccessState = status?.status === "pending" || status?.status === "reconciled";
@@ -1971,7 +1996,7 @@ export async function pollPreviewStatus(
   for (let i = 0; i < attempts; i++) {
     const startedAt = now();
     const args = waitMs ? { commit, waitMs } : { commit };
-    last = normalizePreviewStatus(await scoped.callTool("preview_status", args));
+    last = normalizePreviewStatus(await scoped.callTool("preview_status", args), commit);
     if (last.dispatched) everDispatched = true;
     last.everDispatched = everDispatched;
     if (onTick) onTick(last, i);
@@ -2194,6 +2219,25 @@ export function formatVerdictBlock(verdict, supportBundleText = null) {
  * --json — automation doesn't want a browser popping up). `commit`/`ref`/`verb`
  * feed the honest never-dispatched block.
  */
+/**
+ * The ship line after a watched submit: where this commit is live (per provider) once the verdict
+ * shows it, or that a reviewer still has to accept it. Null when reconcile has not settled. Pure.
+ * @param {{ status?: string, shipped?: { sha: string, receiptId: string|null, provider: string|null, provedAt: string|null }|null }} s
+ */
+export function formatShipLine(s) {
+  if (s?.shipped) {
+    const where =
+      s.shipped.provider === "s3-overwrite" ? "CloudFront" : s.shipped.provider === "worker-r2-pointer" ? "Cloudflare" : "your live site";
+    return (
+      `\n  ✓ shipped — live at ${s.shipped.sha.slice(0, 9)} on ${where}` +
+      (s.shipped.receiptId ? ` (receipt ${s.shipped.receiptId})` : "") +
+      (s.shipped.provedAt ? `, proven ${s.shipped.provedAt}` : "")
+    );
+  }
+  if (s?.status === "reconciled") return `\n  ~ not yet shipped — a reviewer still needs to run change_accept.`;
+  return null;
+}
+
 /**
  * @param {any} s @param {string} tenant
  * @param {{ open?: boolean, quiet?: boolean, commit?: string|null, ref?: string|null, verb?: string, noChanges?: boolean }} [opts]
@@ -2249,11 +2293,8 @@ function reportStatus(s, tenant, { open = true, quiet = false, commit = null, re
       console.log(`  compliance: ${s.compliance.verdict}${s.compliance.detail ? ` — ${s.compliance.detail}` : ""}`);
       for (const c of s.compliance.checks ?? []) reportComplianceCheck(c);
     }
-    if (s.shipped) {
-      console.log(`\n  ✓ shipped — change ${s.shipped.changeId} accepted at ${s.shipped.shippedAt}`);
-    } else if (s.status === "reconciled") {
-      console.log(`\n  ~ not yet shipped — a reviewer still needs to run change_accept.`);
-    }
+    const shipLine = formatShipLine(s);
+    if (shipLine) console.log(shipLine);
     for (const line of formatShareableUrlBlock(s, tenant)) console.log(line);
   }
   if (s.previewUrl && open && s.status === "reconciled" && openBrowser(s.previewUrl)) {

package/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`);
+}