@tokenoftrust/cli 2.4.4 → 2.4.5

package/bin/tot.mjs

@@ -62,7 +62,7 @@ const COMMANDS = [
   { invocation: "dev", blurb: "run your store locally with save→reload" },
   { invocation: "preview", blurb: "push your store to a reviewable preview" },
   { invocation: "status", blurb: "the pipeline verdict for your active tenant — progressing / stuck / idle, and why" },
-  { invocation: "ship", blurb: "publish the tenant's current green aggregate live (plan → confirm → ship)" },
+  { invocation: "ship", blurb: "publish the store live — its green aggregate and approved mounted spaces as one release (plan → confirm → ship)" },
   { invocation: "accept / tot merge", blurb: "queue a PR into the preview aggregate — operator verb, no go-live (plan → confirm → integrate)" },
   { invocation: "sync", blurb: "fetch `preview` and merge it into your local branch (accept-conflict recovery)" },
   { invocation: "rollback [<version>]", blurb: "instant re-point to a prior live version (list → confirm → rollback)" },
@@ -81,6 +81,16 @@ const COMMANDS = [
   { invocation: "--version", blurb: "print the CLI version" },
 ];
 
+/** Store-root verbs that never run inside a mounted publication space's checkout. */
+const SPACE_REFUSED_COMMANDS = new Set(["preview", "submit", "deploy", "sync", "accept", "merge", "hotfix", "revert"]);
+
+/** @param {string} cmd @param {string} spaceId */
+function spaceCheckoutRefusal(cmd, spaceId) {
+  return `✗ this is the "${spaceId}" publication space's own repository — \`tot ${cmd}\` acts on the store's root repository.\n` +
+    "  → commit and `git push` here (tot mints this space's credential on push); once its version is built and\n" +
+    "    approved on the store's admin Publish tab, `tot ship` takes it live with the rest of the store.\n";
+}
+
 function usage() {
   const col = Math.max(...COMMANDS.map((c) => `tot ${c.invocation}`.length)) + 2;
   const lines = COMMANDS.map((c) => `  ${`tot ${c.invocation}`.padEnd(col)}${c.blurb}`).join("\n");
@@ -115,6 +125,18 @@ async function dispatch(cmd, rest, ctx) {
     return 2;
   }
 
+  // A mounted publication space's checkout (spaces/<id>/, recorded by `tot clone`) is its own
+  // repository: the store-root verbs below would push it with the ROOT's credential or merge the
+  // root's preview branch into it. Refuse them there, naming the space's own path.
+  if (SPACE_REFUSED_COMMANDS.has(cmd)) {
+    const { recordedCheckout } = await import("../src/commands/git-credential.mjs");
+    const space = recordedCheckout(ctx.cwd);
+    if (space?.kind === "publication-space") {
+      process.stderr.write(spaceCheckoutRefusal(cmd, space.spaceId));
+      return 2;
+    }
+  }
+
   if (cmd === "start") {
     const { run } = await import("../src/commands/start.mjs");
     return run(rest, ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.4.4",
+  "version": "2.4.5",
   "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/pr.mjs

@@ -17,6 +17,12 @@
  * `candidate_status` / `candidate_close` tools. Dependency-free (global fetch +
  * `git`).
  *
+ * A STORE SPLIT ACROSS REPOSITORIES. In a checkout that records mounted publication spaces
+ * (`tot clone`), `tot pr list` also routes every changed file — the root's and each
+ * `spaces/<id>/` checkout's — to the repository that ships it, lists each space repository's
+ * open candidates, and names any root change whose URL a mounted space serves (it would never
+ * reach a visitor).
+ *
  * OPERATOR MODE. `tot pr list --tenant <t>` lists a tenant's OPEN
  * candidate queue WITHOUT a checkout — the read-only companion to `tot ship --pr <N>
  * --tenant <t>`. It reuses that command's exact transport: the SAME `GET /api/changes`
@@ -24,6 +30,9 @@
  * `normalizeChangesQueue` from ship.mjs). `view`/`close` stay developer-only.
  */
 import { execFileSync } from "node:child_process";
+import {
+  readWorkspaceTopology, routeWorkspaceChanges, spaceDir, workspaceChangedFiles,
+} from "../publication-spaces.mjs";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { fail } from "../errors.mjs";
@@ -294,6 +303,56 @@ export async function runPrListOperator({ tenant, secret, storefrontUrl = null }
   return 0;
 }
 
+/**
+ * The per-repository view of a split store: each repository's changed files (not yet submitted)
+ * and, for a mounted space, its open candidates. Silent for a checkout that records no spaces.
+ * @param {string} workspace
+ * @param {{ scoped: { callTool: (name: string, args?: any) => Promise<any> }, storefrontUrl: string,
+ *   tenant: string, git?: (dir: string, args: string[]) => string }} deps
+ */
+export async function printChangesByRepository(workspace, {
+  scoped, storefrontUrl, tenant,
+  git = (dir, cargs) => {
+    try {
+      return execFileSync("git", ["-C", dir, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+    } catch {
+      return "";
+    }
+  },
+}) {
+  let topology;
+  try {
+    topology = readWorkspaceTopology(workspace);
+  } catch (e) {
+    console.log(`\n  ⚠ ${String(/** @type {any} */ (e)?.message || e)} — re-run \`tot clone --spaces\` to record it again.`);
+    return;
+  }
+  if (!topology || topology.spaces.length < 2) return;
+  const routed = routeWorkspaceChanges(topology, workspaceChangedFiles(workspace, topology, git));
+  console.log("\nChanges by owning repository:");
+  for (const { space, files } of routed.groups) {
+    const where = space.mount === "/" ? "this checkout" : `${spaceDir(space)}/, mount ${space.mount}`;
+    console.log(`  ${space.id} — ${space.source.forge}:${space.source.repo} (${where}): ` +
+      `${files.length ? `${files.length} changed file(s) not yet submitted` : "no local changes"}`);
+    for (const file of files) console.log(`      ${file}`);
+    if (space.mount === "/") continue;
+    try {
+      const open = extractCandidates(await scoped.callTool("candidate_status", { repo: space.source.repo }));
+      for (const c of open) {
+        console.log(`  ${formatCandidateLine({ ...c, previewUrl: c.previewUrl ?? buildPreviewUrl(storefrontUrl, tenant, c.prNumber) })}`);
+      }
+    } catch (e) {
+      console.log(`      (couldn't read this repository's candidates: ${String(/** @type {any} */ (e)?.message || e)})`);
+    }
+  }
+  for (const { file, owner } of routed.misrouted) {
+    console.log(`  ⚠ ${file}: its URL is served by the "${owner.id}" space (mount ${owner.mount}), so this root change never reaches a visitor — move it to ${spaceDir(owner)}/`);
+  }
+  for (const file of routed.unowned) {
+    console.log(`  ⚠ ${file}: no declared space owns this folder — it ships nowhere`);
+  }
+}
+
 /** @param {string[]} argv @param {any} ctx */
 export async function run(argv, ctx) {
   const env = process.env;
@@ -376,14 +435,15 @@ export async function run(argv, ctx) {
     if (args.sub === "list") {
       if (!candidates.length) {
         console.log(`No open candidate PRs for ${repo}. Run \`tot submit\` to open one.`);
-        return 0;
-      }
-      const active = readActiveChangeId(statePath, scope);
-      console.log(`Open candidate PRs for ${repo}:`);
-      for (const c of candidates) {
-        const previewUrl = c.previewUrl ?? buildPreviewUrl(storefrontUrl, tenant, c.prNumber);
-        console.log(formatCandidateLine({ ...c, previewUrl }, { active: !!active && c.changeId === active }));
+      } else {
+        const active = readActiveChangeId(statePath, scope);
+        console.log(`Open candidate PRs for ${repo}:`);
+        for (const c of candidates) {
+          const previewUrl = c.previewUrl ?? buildPreviewUrl(storefrontUrl, tenant, c.prNumber);
+          console.log(formatCandidateLine({ ...c, previewUrl }, { active: !!active && c.changeId === active }));
+        }
       }
+      await printChangesByRepository(workspace, { scoped, storefrontUrl, tenant });
       return 0;
     }
 

package/src/commands/ship.mjs

@@ -36,10 +36,20 @@
  *      `promote_failed` / `record_failed` (a partial failure, recoverable by
  *      re-running `tot ship`, never a false live claim).
  *
+ * A STORE SPLIT ACROSS REPOSITORIES ships as ONE release. Each mounted publication space (a
+ * `/blog` or `/docs` served from its own repository) publishes through its own reviewed path, so
+ * the plan also reads the tenant's declared spaces (`GET /api/publication-spaces`) and lists, per
+ * repository, what this release takes live: every space whose candidate is APPROVED and is not
+ * what live already serves is activated (`POST /api/publication-spaces/<id>/activate`, the same
+ * reviewed transition the admin Publish tab performs) under the same single confirm; a candidate
+ * still awaiting review is named as not in this release. The space list comes from the platform,
+ * never from the checkout.
+ *
  * TRANSPORT: operators/CI may use a Bearer operator secret. A signed-in owner or
  * developer instead mints a storefront viewer session from their OWN `tot login`
  * identity; the server still enforces the live owner / `ship-on-behalf` grant.
  */
+import { createHash } from "node:crypto";
 import { fail } from "../errors.mjs";
 import { planForAction, printPlanAndConfirm } from "../plan.mjs";
 import { startProgress } from "../progress.mjs";
@@ -81,6 +91,10 @@ const USAGE = `tot ship — publish the tenant's CURRENT GREEN AGGREGATE to live
   VERIFIED live truth — never a false "shipped" — surfacing a refusal or a
   recoverable partial failure honestly if it isn't.
 
+  A store split across repositories (a root plus mounted spaces such as /blog)
+  ships as ONE release: the plan lists each repository, and every space whose
+  candidate is approved is taken live under the same confirm.
+
   The candidate-level merge is the separate \`tot accept\` / \`tot merge\` verb —
   \`tot ship\` never merges.`;
 
@@ -294,6 +308,102 @@ export function refusalNextStep(reason) {
   }
 }
 
+// ─── Mounted publication spaces in the release ──────────────────────────────────
+
+/**
+ * Split the tenant's declared spaces (`GET /api/publication-spaces` rows) into what this release
+ * takes live and what it leaves out. A space is READY when its candidate is approved and live
+ * does not already serve it; a candidate awaiting review (or with changes requested) is WAITING.
+ * A space with no candidate, or whose candidate is already live, has nothing to release. Pure.
+ * @param {any} rows
+ * @returns {{ ready: Array<{ spaceId: string, mount: string, versionId: string, sourceSha: string,
+ *   liveVersionId: string|null, activate: { targetVersionId: string, expectedSourceSha: string,
+ *   expectedArtifactDigest: string, expectedRevision: number } }>,
+ *   waiting: Array<{ spaceId: string, mount: string, versionId: string, why: string }> }}
+ */
+export function spaceReleasePlan(rows) {
+  const ready = [];
+  const waiting = [];
+  for (const row of Array.isArray(rows) ? rows : []) {
+    const candidate = row?.candidate;
+    if (!candidate || typeof row.id !== "string") continue;
+    const mount = row.routes?.canonicalMount ?? row.canonicalMount ?? "?";
+    if (candidate.live?.state === "current") continue;
+    const decision = candidate.review?.decision;
+    const activate = candidate.actions?.activate;
+    if (decision === "approved" && activate && typeof activate.targetVersionId === "string") {
+      ready.push({
+        spaceId: row.id, mount, versionId: candidate.versionId, sourceSha: String(candidate.sourceSha ?? ""),
+        liveVersionId: candidate.live?.versionId ?? null, activate,
+      });
+    } else {
+      waiting.push({
+        spaceId: row.id, mount, versionId: candidate.versionId,
+        why: decision === "changes-requested" ? "changes requested in review" : "awaiting review",
+      });
+    }
+  }
+  return { ready, waiting };
+}
+
+/** The plan lines naming each repository's part of the release. Pure. */
+export function spaceReleaseLines(release) {
+  const lines = [];
+  if (release.ready.length) {
+    lines.push("  publication spaces going live in this release:");
+    for (const space of release.ready) {
+      lines.push(`    ${space.mount} (${space.spaceId}): ${space.versionId} @ ${space.sourceSha.slice(0, 8)}` +
+        `${space.liveVersionId ? ` — replaces live ${space.liveVersionId}` : " — first live version"}`);
+    }
+  }
+  if (release.waiting.length) {
+    lines.push("  not in this release:");
+    for (const space of release.waiting) {
+      lines.push(`    ${space.mount} (${space.spaceId}): ${space.versionId} — ${space.why} (review it on the store's admin Publish tab)`);
+    }
+  }
+  return lines;
+}
+
+/** A deterministic transition id, so a retried ship of the same release is idempotent. Pure. */
+export function spaceTransitionId(space) {
+  const digest = createHash("sha256")
+    .update(`${space.spaceId}\0${space.activate.targetVersionId}\0${space.activate.expectedRevision}`)
+    .digest("hex").slice(0, 24);
+  return `cli-ship.${digest}`;
+}
+
+/** Read the tenant's declared spaces for the release; null when the store reports none. Never throws. */
+async function readSpaceRelease({ base, authHeaders, fetchImpl }) {
+  try {
+    const res = await fetchImpl(`${base}/api/publication-spaces`, { method: "GET", headers: authHeaders });
+    const body = await readJsonSafe(res);
+    if (!res.ok || body?.ok !== true) return null;
+    return spaceReleasePlan(body.spaces);
+  } catch {
+    return null;
+  }
+}
+
+/** Activate one approved space candidate; returns a one-line honest outcome. Never throws. */
+async function activateSpace({ base, authHeaders, fetchImpl, space }) {
+  try {
+    const res = await fetchImpl(`${base}/api/publication-spaces/${encodeURIComponent(space.spaceId)}/activate`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...authHeaders },
+      body: JSON.stringify({ transitionId: spaceTransitionId(space), ...space.activate }),
+    });
+    const body = await readJsonSafe(res);
+    if (res.ok && body?.ok === true) return { ok: true, line: `  ✓ ${space.mount} (${space.spaceId}) is live: ${space.versionId}` };
+    if (body?.committed === true) {
+      return { ok: false, line: `  ⏳ ${space.mount} (${space.spaceId}): selected ${space.versionId}; delivery is still confirming — re-run \`tot ship\` to confirm` };
+    }
+    return { ok: false, line: `  ✗ ${space.mount} (${space.spaceId}) did not go live: ${body?.error || `HTTP ${res.status}`}` };
+  } catch (e) {
+    return { ok: false, line: `  ✗ ${space.mount} (${space.spaceId}) did not go live: ${String(/** @type {any} */ (e)?.message || e)}` };
+  }
+}
+
 /** Read a fetch Response body as JSON, tolerating a non-JSON/empty body. */
 async function readJsonSafe(res) {
   try {
@@ -386,7 +496,9 @@ export async function runShip(
     return 1;
   }
   const plan = normalizeShipPlan(planData);
-  if (!plan.ok) {
+  // The tenant's mounted publication spaces ride the same release (see the file header).
+  const spaces = (await readSpaceRelease({ base, authHeaders, fetchImpl })) ?? { ready: [], waiting: [] };
+  if (!plan.ok && !spaces.ready.length) {
     console.error(fail(plan.message, refusalNextStep(plan.reason)));
     // A not-green / no-passed-run refusal is exactly what the doctor diagnoses —
     // name the changes keeping the aggregate red right here.
@@ -397,23 +509,28 @@ export async function runShip(
   // 2. Print the EXACT plan via the shared affordance, then require ONE
   //    explicit confirm (`--yes` non-interactive; a non-TTY without it refuses).
   const liveUrl = liveUrlFor(tenant);
-  const planLines = planForAction({
-    action: "ship",
-    tenant,
-    pinnedSha: plan.pinnedSha,
-    artifactDigest: plan.artifactDigest,
-    includedPrs: plan.includedPrs,
-    rollbackTarget: plan.rollbackTarget,
-    paywall: plan.paywall,
-    targets: { live: liveUrl },
-  });
+  const planLines = plan.ok
+    ? planForAction({
+      action: "ship",
+      tenant,
+      pinnedSha: plan.pinnedSha,
+      artifactDigest: plan.artifactDigest,
+      includedPrs: plan.includedPrs,
+      rollbackTarget: plan.rollbackTarget,
+      paywall: plan.paywall,
+      targets: { live: liveUrl },
+    })
+    : [`  whole-site aggregate: not in this release — ${plan.message}`];
+  planLines.push(...spaceReleaseLines(spaces));
   if (acceptQualityReason) {
     planLines.push("  quality findings: accept this exact revision and continue");
     planLines.push(`  acceptance reason: ${acceptQualityReason.trim() || "(missing)"}`);
   }
   const { confirmed, reason } = await confirmPlan(planLines, {
     yes,
-    question: `Ship ${tenant}'s current green aggregate live?`,
+    question: spaces.ready.length
+      ? `Ship this release of ${tenant} live (${[...(plan.ok ? ["the green aggregate"] : []), ...spaces.ready.map((s) => s.mount)].join(", ")})?`
+      : `Ship ${tenant}'s current green aggregate live?`,
   });
   if (!confirmed) {
     if (reason === "non-tty") {
@@ -459,6 +576,21 @@ export async function runShip(
     console.log("  ✓ quality findings accepted for this revision; continuing the publish.");
   }
 
+  // Each approved space goes live through its own reviewed transition, under the confirm above.
+  const releaseSpaces = async () => {
+    let allLive = true;
+    for (const space of spaces.ready) {
+      const outcome = await activateSpace({ base, authHeaders, fetchImpl, space });
+      if (!outcome.ok) allLive = false;
+      (outcome.ok ? console.log : console.error)(outcome.line);
+    }
+    return allLive;
+  };
+  if (!plan.ok) {
+    console.log(`\n  Shipping ${tenant}'s publication spaces (the whole-site aggregate is not in this release):`);
+    return (await releaseSpaces()) ? 0 : 1;
+  }
+
   // 3. SHIP — the human go-live gate (confirmGoLive) plus the reviewed pin, so a
   //    STALE plan (the aggregate moved / the artifact changed since GET) is
   //    refused rather than shipping something nobody reviewed.
@@ -504,7 +636,8 @@ export async function runShip(
 
   const code = reportShipResult(shipResult, { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
   if (code !== 0) await surfaceDoctor();
-  return code;
+  const spacesLive = spaces.ready.length ? await releaseSpaces() : true;
+  return code !== 0 ? code : spacesLive ? 0 : 1;
 }
 
 /**

package/src/publication-spaces.mjs

@@ -305,3 +305,75 @@ export function describeOwner(topology, urlPath) {
     dir: spaceDir(space) || ".",
   };
 }
+
+/**
+ * Route changed workspace files to the repository that ships them. Paths are relative to the
+ * root checkout (a space's files as `spaces/<id>/...`). Each file lands in its owning space's
+ * group; a root file whose URL a mounted space owns is ALSO named as misrouted (it ships with the
+ * root and still never reaches a visitor); a file under `spaces/` naming no declared space is
+ * unowned. Pure.
+ * @param {Topology} topology
+ * @param {string[]} files
+ * @returns {{ groups: Array<{ space: TopologySpace, files: string[] }>,
+ *   misrouted: Array<{ file: string, owner: TopologySpace }>, unowned: string[] }}
+ */
+export function routeWorkspaceChanges(topology, files) {
+  const root = rootSpace(topology);
+  /** @type {Map<string, string[]>} */
+  const byId = new Map(topology.spaces.map((space) => [space.id, []]));
+  const misrouted = [];
+  const unowned = [];
+  for (const file of files) {
+    const owner = spaceForWorkspaceFile(topology, file);
+    if (!owner) { unowned.push(file); continue; }
+    /** @type {string[]} */ (byId.get(owner.space.id)).push(file);
+    if (owner.space.mount === "/") {
+      const urlPath = rootFileUrlPath(root, file);
+      const served = urlPath ? owningSpace(topology, urlPath) : null;
+      if (served?.space && served.space.mount !== "/") misrouted.push({ file, owner: served.space });
+    }
+  }
+  return {
+    groups: topology.spaces.map((space) => ({ space, files: /** @type {string[]} */ (byId.get(space.id)) })),
+    misrouted,
+    unowned,
+  };
+}
+
+/**
+ * Parse `git status --porcelain=v1 -z` into changed paths (a rename yields its new path). Pure.
+ * @param {string} out
+ * @returns {string[]}
+ */
+export function parsePorcelainZ(out) {
+  const parts = String(out).split("\0");
+  const paths = [];
+  for (let i = 0; i < parts.length; i++) {
+    const entry = parts[i];
+    if (!entry || entry.length < 4) continue;
+    const status = entry.slice(0, 2);
+    paths.push(entry.slice(3));
+    if (status[0] === "R" || status[0] === "C") i++; // the next field is the rename's source
+  }
+  return paths;
+}
+
+/**
+ * Every changed file in a workspace, relative to the root checkout: the root repository's own
+ * changes plus each cloned space's (`spaces/<id>/...`). `git(dir, args)` runs git in `dir`.
+ * @param {string} workspace
+ * @param {Topology} topology
+ * @param {(dir: string, args: string[]) => string} git
+ * @returns {string[]}
+ */
+export function workspaceChangedFiles(workspace, topology, git) {
+  const files = parsePorcelainZ(git(workspace, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]));
+  for (const space of mountedSpaces(topology)) {
+    const dir = join(workspace, spaceDir(space));
+    if (!existsSync(join(dir, ".git"))) continue;
+    for (const file of parsePorcelainZ(git(dir, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]))) {
+      files.push(`${spaceDir(space)}/${file}`);
+    }
+  }
+  return files;
+}