@tokenoftrust/cli 2.4.2 → 2.4.4

package/package.json

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

@@ -11,6 +11,18 @@
  *   tot clone <tenant> <dir>     clone into <dir>
  *   tot clone <tenant> --remote-only   just mint + print the remote, don't materialize
  *   tot clone agency-kit [dir]   READ-ONLY clone of the Agency Kit (ADR 0037)
+ *   tot clone --spaces           (inside a checkout) record the store's publication spaces and
+ *                                clone any mounted space not yet under spaces/
+ *
+ * MOUNTED PUBLICATION SPACES. A store whose site is split across repositories (a root plus
+ * mounted spaces such as `/blog`) is cloned whole: after the root, `tot clone` reads the
+ * platform's declared split (`GET /api/publication-spaces`, over the developer's own viewer
+ * session), records it in `.tot/publication-spaces.json`, and clones each mounted space it can
+ * get a credential for into `spaces/<spaceId>/`. Space credentials come only from the MCP
+ * `publication_checkout` tool; like the root's, the token rides a one-shot header, is never
+ * written to `.git/config`, and is never printed. Each space checkout records its kind so
+ * `tot git-credential` re-mints its credential through `publication_checkout` on every fetch and
+ * push, never as the root store's.
  *
  * AGENCY KIT. `agency-kit` is an alias, not a tenant: it mints through
  * `repo_read_credential` (see READ_ONLY_ALIASES / kitReadCredentialInput) and skips
@@ -53,6 +65,8 @@
  * Dependency-free (global fetch + `git` via child_process).
  */
 import { execFile, execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { promisify } from "node:util";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
@@ -63,7 +77,12 @@ import { writeNvmrc } from "../sample.mjs";
 import { emitObstacle } from "../obstacle.mjs";
 import {
   splitAuthedRemote, basicAuthExtraHeader, installForgeCredentialHelper, recordReadOnlyKitCheckout,
+  recordPublicationSpaceCheckout,
 } from "../git-credential.mjs";
+import { resolveViewerTransport } from "../viewer-session.mjs";
+import {
+  mountedSpaces, spaceDir, topologyFromDeclaredSpaces, writeWorkspaceTopology, TOPOLOGY_FILE,
+} from "../publication-spaces.mjs";
 import { recordDiagnostic } from "../diagnostics.mjs";
 
 const execFileP = promisify(execFile);
@@ -71,7 +90,7 @@ const execFileP = promisify(execFile);
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
 function parseArgs(argv) {
-  /** @type {{ tenant: string|null, dir: string|null, tag: string, pr: string|null, remoteOnly: boolean, mcp: string|null, printRemote: boolean, help: boolean }} */
+  /** @type {{ tenant: string|null, dir: string|null, tag: string, pr: string|null, remoteOnly: boolean, mcp: string|null, url: string|null, printRemote: boolean, spaces: boolean, help: boolean }} */
   const a = {
     tenant: null,
     dir: null,
@@ -79,7 +98,9 @@ function parseArgs(argv) {
     pr: null,
     remoteOnly: false,
     mcp: null,
+    url: null,
     printRemote: false,
+    spaces: false,
     help: false,
   };
   for (let i = 0; i < argv.length; i++) {
@@ -89,6 +110,8 @@ function parseArgs(argv) {
     else if (t === "--remote-only") a.remoteOnly = true;
     else if (t === "--mcp") a.mcp = argv[++i];
     else if (t === "--print-remote") a.printRemote = true;
+    else if (t === "--spaces") a.spaces = true;
+    else if (t === "--url") a.url = argv[++i];
     else if (t === "--help" || t === "-h") a.help = true;
     // Positional, git-clone style: `tot clone <tenant> [<dir>]`.
     else if (!t.startsWith("--")) {
@@ -126,6 +149,13 @@ const USAGE = `tot clone — clone a tenant store you can build on (mirrors \`gi
                                 <tenant>-pr<N>)
   tot clone agency-kit [dir]   clone the Agency Kit, READ-ONLY, into ./agency-kit
                                 (needs agency access — ask Token of Trust)
+  tot clone --spaces           (inside a checkout) record the store's publication
+                                spaces and clone any mounted space not yet under
+                                spaces/<id>/
+
+A store split across repositories (a root plus mounted spaces like /blog) clones
+whole: the root, then each mounted space you can edit into spaces/<id>/.
+\`tot validate --owner <path>\` names the repository that owns a URL.
 
 Options:
   --tag <tag>       deprecated compatibility input; tenant repos use the bare domain.
@@ -134,6 +164,8 @@ Options:
   --remote-only     don't clone; just mint + print the clone URL for <tenant>.
   --mcp <url>       MCP base URL. Default: env MCP_BASE_URL / TOT_MCP_URL, else
                     ${DEFAULT_MCP_URL}.
+  --url <origin>    storefront origin the publication spaces are read from.
+                    Default: env TOT_STOREFRONT_URL, else the shared storefront.
   --print-remote    with --remote-only, also print the authenticated remote
                     (contains a live token!).`;
 
@@ -154,7 +186,7 @@ function makeRedactor(env) {
 export async function run(argv, ctx, deps = {}) {
   const {
     env = process.env, createClient = createMcpClient, establish = establishSession,
-    signIn = offerSignIn, cloneDeps = {},
+    signIn = offerSignIn, cloneDeps = {}, readTopology = fetchDeclaredTopology,
   } = deps;
   const args = parseArgs(argv);
   if (args.help) {
@@ -172,6 +204,24 @@ export async function run(argv, ctx, deps = {}) {
     args.tenant = ctx.tenant;
   }
 
+  if (args.spaces) {
+    if (ctx.mode !== "checkout" || !ctx.workspacePath || !args.tenant) {
+      console.error(fail("`tot clone --spaces` runs inside a store checkout", "tot clone <tenant>   (clones the root and its spaces)"));
+      return 2;
+    }
+    const redact = makeRedactor(env);
+    const client = createClient(args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL);
+    try {
+      await signInOrOffer(client, { env, establish, signIn });
+      await clonePublicationSpacesInto(client, {
+        tenant: args.tenant, dir: ctx.workspacePath, env, storefrontUrl: args.url, redact, readTopology, cloneDeps,
+      });
+      return 0;
+    } catch (e) {
+      return reportFailure(e, redact);
+    }
+  }
+
   let pr;
   try {
     pr = parsePrNumber(args.pr);
@@ -246,11 +296,14 @@ export async function run(argv, ctx, deps = {}) {
       tag: args.tag,
       cloneDir,
       redact,
-    });
+    }, cloneDeps);
     console.log(`\n+ ready. repo: ${res.cloneUrl || res.publicUrl}`);
 
     if (res.cloned) {
       console.log(`+ cloned. HEAD: ${res.head}`);
+      await clonePublicationSpacesInto(client, {
+        tenant: args.tenant, dir: /** @type {string} */ (res.dir), env, storefrontUrl: args.url, redact, readTopology, cloneDeps,
+      });
       console.log(`\nYour local working clone is at ${res.dir}.`);
       console.log(`  cd ${res.dir} && tot dev            # run it locally with save→reload`);
       console.log(`  (origin has no token — \`tot\` mints one fresh at fetch/push time)`);
@@ -374,7 +427,7 @@ export function checkoutPointsAtEntitlement(checkout) {
  * @returns {Promise<{ gitRemote: string, cloneUrl: string|null, publicUrl: string,
  *   cloned: boolean, dir: string|null, head: string|null }>}
  */
-export async function checkoutTenant(client, { tenant, tag = "main", cloneDir = null, redact = (s) => s }) {
+export async function checkoutTenant(client, { tenant, tag = "main", cloneDir = null, redact = (s) => s }, cloneDeps = {}) {
   // tenant_checkout is the SOLE AUTHORITATIVE checkout decision, and it names the tenant
   // (scopeToTenant injects it), so the server checks out that held tenant directly — or
   // answers for a staff-preview authorization, or refuses naming the tenants the session
@@ -419,7 +472,7 @@ export async function checkoutTenant(client, { tenant, tag = "main", cloneDir =
   if (!cloneDir) {
     return { gitRemote, cloneUrl, publicUrl, cloned: false, dir: null, head: null };
   }
-  const { dir, head } = await cloneRepo(gitRemote, cloneDir, redact);
+  const { dir, head } = await cloneRepo(gitRemote, cloneDir, redact, cloneDeps);
   return { gitRemote, cloneUrl, publicUrl, cloned: true, dir, head };
 }
 
@@ -515,6 +568,137 @@ async function cloneRepo(gitRemote, dir, redact, {
   return { dir, head };
 }
 
+// ─── mounted publication spaces ────────────────────────────────────────────────
+
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+/**
+ * Read a store's declared publication topology from the platform: `GET /api/publication-spaces`
+ * over the developer's own viewer session, which returns only the spaces the platform lets this
+ * developer see. Never throws.
+ * @param {{ tenant: string, env?: NodeJS.ProcessEnv, storefrontUrl?: string|null,
+ *   fetchImpl?: typeof fetch, resolveTransport?: typeof resolveViewerTransport }} input
+ * @returns {Promise<{ ok: true, topology: import("../publication-spaces.mjs").Topology } | { ok: false, reason: string }>}
+ */
+export async function fetchDeclaredTopology({
+  tenant, env = process.env, storefrontUrl = null, fetchImpl = fetch, resolveTransport = resolveViewerTransport,
+}) {
+  const origin = storefrontUrl || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+  const transport = await resolveTransport({ tenant, env, fetchImpl, storefrontUrl: origin });
+  if (!transport.ok) return { ok: false, reason: transport.message };
+  let res;
+  try {
+    res = await fetchImpl(`${transport.base}/api/publication-spaces`, { headers: transport.authHeaders });
+  } catch (e) {
+    return { ok: false, reason: `couldn't reach ${transport.base}: ${/** @type {any} */ (e)?.message || e}` };
+  }
+  /** @type {any} */
+  let body = null;
+  try { body = await res.json(); } catch { /* not JSON */ }
+  if (!res.ok || !body?.ok) return { ok: false, reason: body?.error || `HTTP ${res.status}` };
+  try {
+    return { ok: true, topology: topologyFromDeclaredSpaces(tenant, body.spaces) };
+  } catch (e) {
+    return { ok: false, reason: String(/** @type {any} */ (e)?.message || e) };
+  }
+}
+
+/**
+ * Mint a write credential for one mounted space through `publication_checkout`, refusing a
+ * result for any other space or repository. The credential is returned, never printed.
+ * @param {{ callTool: (name: string, args?: Record<string, unknown>) => Promise<any> }} scoped
+ * @param {import("../publication-spaces.mjs").TopologySpace} space
+ * @param {(s: string) => string} redact
+ * @returns {Promise<{ gitRemote: string }>}
+ */
+export async function mintPublicationSpace(scoped, space, redact = (s) => s) {
+  const next = `ask the store owner for edit access to the "${space.id}" space, then run \`tot clone --spaces\` in your checkout`;
+  /** @type {any} */
+  let res;
+  try {
+    res = await scoped.callTool("publication_checkout", {});
+  } catch (e) {
+    const reason = serverReason(e);
+    throw new CliError(`no write credential for the "${space.id}" space${reason ? `: ${redact(reason)}` : ""}`, { next, cause: e });
+  }
+  if (!res || res.status !== "checked-out" || typeof res.gitRemote !== "string" || !res.gitRemote) {
+    const reason = serverReason(res);
+    throw new CliError(`no write credential for the "${space.id}" space${reason ? `: ${redact(reason)}` : ""}`, { next });
+  }
+  if (res.binding?.spaceId !== space.id || res.repo !== space.source.repo || res.binding?.source?.repo !== space.source.repo) {
+    throw new CliError(`Token of Trust has no write credential for the "${space.id}" space (it offered "${res.binding?.spaceId ?? "another space"}")`, { next });
+  }
+  return { gitRemote: res.gitRemote };
+}
+
+/**
+ * Clone each mounted space of `topology` that is not yet under `<dir>/spaces/` — a space this
+ * developer has no credential for is reported and skipped, never fatal to the root clone.
+ * @param {ReturnType<import("../mcp.mjs").createMcpClient>} client
+ * @param {{ tenant: string, dir: string, topology: import("../publication-spaces.mjs").Topology,
+ *   redact?: (s: string) => string }} input
+ * @param {Parameters<typeof cloneRepo>[3]} [deps]
+ * @returns {Promise<Array<{ spaceId: string, mount: string, dir: string, status: "cloned"|"present"|"skipped",
+ *   head?: string, reason?: string, next?: string }>>}
+ */
+export async function clonePublicationSpaces(client, { tenant, dir, topology, redact = (s) => s }, deps = {}) {
+  const spaces = mountedSpaces(topology);
+  if (!spaces.length) return [];
+  const scoped = await scopeToTenant(client, tenant, { redact });
+  const results = [];
+  for (const space of spaces) {
+    const rel = spaceDir(space);
+    const target = join(dir, rel);
+    if (existsSync(target)) {
+      results.push({ spaceId: space.id, mount: space.mount, dir: rel, status: /** @type {const} */ ("present") });
+      continue;
+    }
+    console.error(`~ publication_checkout (tenant=${tenant}, space=${space.id}) — MCP mints a fresh space credential`);
+    try {
+      const { gitRemote } = await mintPublicationSpace(scoped, space, redact);
+      const cred = splitAuthedRemote(gitRemote);
+      const scrub = (/** @type {string} */ s) => (cred ? redact(s).split(cred.token).join("***") : redact(s));
+      const { head } = await cloneRepo(gitRemote, target, scrub, {
+        ...deps,
+        store: false,
+        record: (gitSync) => recordPublicationSpaceCheckout(gitSync, { tenant, spaceId: space.id, repo: space.source.repo }),
+      });
+      results.push({ spaceId: space.id, mount: space.mount, dir: rel, status: /** @type {const} */ ("cloned"), head });
+    } catch (e) {
+      const err = /** @type {any} */ (e);
+      results.push({
+        spaceId: space.id, mount: space.mount, dir: rel, status: /** @type {const} */ ("skipped"),
+        reason: err instanceof CliError ? err.message : redact(String(err?.message || err)),
+        ...(err?.next ? { next: err.next } : {}),
+      });
+    }
+  }
+  return results;
+}
+
+/**
+ * After a root clone (or `tot clone --spaces` in a checkout): record the declared topology and
+ * clone the mounted spaces, reporting each in one line. A topology the platform will not give is
+ * reported and the root stays usable on its own.
+ */
+async function clonePublicationSpacesInto(client, { tenant, dir, env, storefrontUrl, redact, readTopology, cloneDeps }) {
+  const read = await readTopology({ tenant, env, storefrontUrl });
+  if (!read.ok) {
+    console.log(`~ publication spaces: couldn't read this store's split (${redact(read.reason)}) — the root is cloned on its own.`);
+    console.log(`  Run \`tot clone --spaces\` in ${dir} to retry.`);
+    return;
+  }
+  writeWorkspaceTopology(dir, read.topology);
+  const mounted = mountedSpaces(read.topology);
+  if (!mounted.length) return;
+  console.log(`+ publication spaces recorded in ${TOPOLOGY_FILE}: ${mounted.map((s) => `${s.mount} (${s.id})`).join(", ")}`);
+  for (const result of await clonePublicationSpaces(client, { tenant, dir, topology: read.topology, redact }, cloneDeps)) {
+    if (result.status === "cloned") console.log(`+ space ${result.spaceId} (${result.mount}) cloned into ${result.dir}/. HEAD: ${result.head}`);
+    else if (result.status === "present") console.log(`  space ${result.spaceId} (${result.mount}) already at ${result.dir}/`);
+    else console.log(`~ space ${result.spaceId} (${result.mount}) not cloned: ${result.reason}${result.next ? `\n  next: ${result.next}` : ""}`);
+  }
+}
+
 // ─── read-only aliases: `tot clone agency-kit` ─────────────────────────────────
 
 /**

package/src/commands/git-credential.mjs

@@ -17,10 +17,12 @@
  * sends when the forge rejected the credential, drops that cache so the next
  * `get` re-mints; `store` is a no-op.
  *
- * Two checkout kinds: a tenant store (its `.tot/config.json`) mints a push
+ * Three checkout kinds: a tenant store (its `.tot/config.json`) mints a push
  * credential through `tenant_checkout`; a read-only kit clone (recorded in local
  * git config by `tot clone agency-kit`) mints through `repo_read_credential`,
- * cached under a key a store's can never take.
+ * cached under a key a store's can never take; a mounted publication space (recorded
+ * by `tot clone` under `spaces/<id>/`) mints through `publication_checkout`, never
+ * cached, because each mint rotates the editor's older tokens.
  *
  * FAILS SILENT ON STDOUT, NEVER LOUD THERE: `get` prints NOTHING on stdout and
  * exits non-zero on any problem (not signed in, MCP unreachable, cwd isn't a
@@ -49,14 +51,15 @@ import { readFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession } from "../auth.mjs";
-import { checkoutTenant, mintReadOnlyAlias, resolveReadOnlyAlias } from "./clone.mjs";
+import { checkoutTenant, mintPublicationSpace, mintReadOnlyAlias, resolveReadOnlyAlias } from "./clone.mjs";
+import { scopeToTenant } from "../tenant-scope.mjs";
 import { detectContext } from "../context.mjs";
 import { repoNameFromRemote, tagFromRepoName } from "./submit.mjs";
 import { CliError, formatError } from "../errors.mjs";
 import {
   parseCredentialInput, formatCredentialOutput, splitAuthedRemote,
   readCachedCredential, writeCachedCredential,
-  kitCredentialCachePath, dropCachedCredential, readCheckoutKind, READ_ONLY_KIT_KIND,
+  kitCredentialCachePath, dropCachedCredential, readCheckoutKind, READ_ONLY_KIT_KIND, PUBLICATION_SPACE_KIND,
 } from "../git-credential.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -115,14 +118,39 @@ export function readStdin() {
  *   establish?: typeof establishSession,
  *   checkout?: typeof checkoutTenant,
  *   mintReadOnly?: typeof mintReadOnlyAlias,
+ *   mintSpace?: typeof mintPublicationSpace,
  * }} [opts]
  * @returns {Promise<{username:string,password:string}|null>}
  */
 export async function mintOrCacheCredential({
   env = process.env, cwd = process.cwd(), expectedHost = null,
   createClient = createMcpClient, establish = establishSession, checkout = checkoutTenant,
-  mintReadOnly = mintReadOnlyAlias,
+  mintReadOnly = mintReadOnlyAlias, mintSpace = mintPublicationSpace,
 } = {}) {
+  const recorded = recordedCheckout(cwd);
+  if (recorded?.kind === "invalid") return null; // a half-recorded space mints nothing, never the store's
+  if (recorded?.kind === PUBLICATION_SPACE_KIND) {
+    if (expectedHost && !hostMatches(recorded.originUrl, expectedHost)) return null;
+    const baseUrl = env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+    const client = createClient(baseUrl);
+    try {
+      await establish(client, { env });
+    } catch {
+      return null;
+    }
+    try {
+      const scoped = await scopeToTenant(client, recorded.tenant);
+      const res = await mintSpace(scoped, {
+        id: recorded.spaceId, mount: "", visibility: "public",
+        source: { forge: "", repo: recorded.repo, defaultBranch: "" },
+      });
+      const cred = splitAuthedRemote(res.gitRemote || "");
+      return cred ? { username: cred.username, password: cred.token } : null;
+    } catch (e) {
+      if (e instanceof CliError) console.error(formatError(e));
+      return null;
+    }
+  }
   const kit = kitCheckout(cwd);
   if (kit) {
     if (expectedHost && !hostMatches(kit.originUrl, expectedHost)) return null;
@@ -219,6 +247,25 @@ export async function mintOrCacheCredential({
   }
 }
 
+/**
+ * The publication-space checkout `cwd` is in (or a half-recorded one: `{ kind: "invalid" }`),
+ * from the kind `tot clone` recorded; null for anything else. Never throws.
+ * @param {string} cwd
+ * @returns {{ kind: "publication-space", tenant: string, spaceId: string, repo: string, originUrl: string|null }
+ *   | { kind: "invalid" } | null}
+ */
+export function recordedCheckout(cwd) {
+  const git = (cargs) =>
+    execFileSync("git", ["-C", cwd, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+  let kind;
+  try { kind = readCheckoutKind(git); } catch { return null; }
+  if (kind.kind === "invalid") return { kind: "invalid" };
+  if (kind.kind !== PUBLICATION_SPACE_KIND) return null;
+  let originUrl = null;
+  try { originUrl = git(["remote", "get-url", "origin"]).trim(); } catch { /* host check fails closed */ }
+  return { ...kind, originUrl };
+}
+
 /**
  * The read-only kit checkout `cwd` is in, from the kind `tot clone` recorded, or null when
  * it is not one (a store, a loose dir, not a repo). Never throws.

package/src/commands/validate.mjs

@@ -10,26 +10,34 @@
  *   tot validate <tenant>        (inside the monorepo) lint tenants/<tenant>/
  *   tot validate --workspace DIR lint a specific checkout directory
  *   tot validate --json          machine-readable findings
+ *   tot validate --owner <path>  name the repository that owns a URL path
+ *
+ * A checkout whose tenant has mounted publication spaces (its `.tot/publication-spaces.json`, which
+ * `tot clone` records) also reports root files whose URL a mounted space owns.
  *
  * Exit 0 = no errors (warnings allowed); 1 = one or more errors; 2 = usage / no target.
  */
-import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
 import { validateTenant, ERROR, WARN, printLoudAdvisories } from "../validate.mjs";
 import { validateVisualParityClosure } from "../visual-parity.mjs";
 import { fail } from "../errors.mjs";
 import { tenantDirSegments } from "../tenant-dirs.mjs";
+import {
+  describeOwner, readWorkspaceTopology, rootFilesOwnedByMounts, TOPOLOGY_FILE,
+} from "../publication-spaces.mjs";
 
 const mergeFindings = (...groups) => [...new Map(groups.flat().map((item) => [JSON.stringify(item), item])).values()]
   .sort((a, b) => `${a.file}\0${a.rule}\0${a.message}`.localeCompare(`${b.file}\0${b.rule}\0${b.message}`));
 
 function parseArgs(argv) {
-  const a = { tenant: null, workspace: null, json: false, help: false, profile: null, profileSpecified: false };
+  const a = { tenant: null, workspace: null, json: false, help: false, profile: null, profileSpecified: false, owner: null };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--workspace") a.workspace = argv[++i];
     else if (t === "--profile") { a.profileSpecified = true; a.profile = argv[++i] ?? null; }
     else if (t === "--json") a.json = true;
+    else if (t === "--owner") a.owner = argv[++i] ?? "";
     else if (t === "--help" || t === "-h") a.help = true;
     else if (!t.startsWith("--") && !a.tenant) a.tenant = t;
   }
@@ -42,7 +50,70 @@ const USAGE = `tot validate — lint your store before you submit
   tot validate <tenant>         (inside the monorepo) lint tenants/<tenant>/
   tot validate --workspace <dir>  lint a specific checkout directory
   tot validate --profile visual-parity  close portable page/asset/link migration scope
-  tot validate --json           machine-readable findings`;
+  tot validate --json           machine-readable findings
+  tot validate --owner <path>   which repository owns a URL path (the root, or a mounted space)`;
+
+/** Every file under `<dir>/content/`, relative to `dir`. */
+function contentFiles(dir) {
+  const out = [];
+  const walk = (abs) => {
+    let entries;
+    try { entries = readdirSync(abs, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const full = join(abs, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) out.push(relative(dir, full).split(sep).join("/"));
+    }
+  };
+  walk(join(dir, "content"));
+  return out.sort();
+}
+
+/**
+ * The workspace's recorded topology, or an error string when it is unreadable.
+ * @returns {{ topology: import("../publication-spaces.mjs").Topology | null } | { error: string }}
+ */
+function topologyFor(dir) {
+  try {
+    return { topology: readWorkspaceTopology(dir) };
+  } catch (e) {
+    return { error: String(/** @type {any} */ (e)?.message || e) };
+  }
+}
+
+/** `tot validate --owner <path>`: name the repository that owns a URL path. */
+function runOwner(args, dir) {
+  const read = topologyFor(dir);
+  if ("error" in read) {
+    console.error(fail(read.error, "re-run `tot clone <tenant>` to record the topology again"));
+    return 2;
+  }
+  if (!read.topology) {
+    console.error(fail(
+      `this checkout records no publication topology (${TOPOLOGY_FILE})`,
+      "`tot clone <tenant>` records it — until then every path is the root repository's",
+    ));
+    return 2;
+  }
+  const owner = describeOwner(read.topology, /** @type {string} */ (args.owner));
+  if (!owner) {
+    console.error(fail(`"${args.owner}" is not a URL path`, "tot validate --owner /blog/my-post"));
+    return 2;
+  }
+  if (args.json) {
+    console.log(JSON.stringify(owner, null, 2));
+    return 0;
+  }
+  if (!owner.spaceId) {
+    console.log(`${owner.path} is a platform path — no repository serves it.`);
+    return 0;
+  }
+  const kind = owner.mount === "/" ? "the root space" : `the mounted space "${owner.spaceId}" (mount ${owner.mount}${owner.via === "alias" ? ", via an alias" : ""})`;
+  console.log(`${owner.path} is owned by ${kind}`);
+  console.log(`  repository: ${owner.repo}`);
+  console.log(`  edit it in: ${owner.dir === "." ? "this checkout" : `${owner.dir}/`}`);
+  return 0;
+}
 
 /**
  * Resolve the tenant directory + id + scope to validate, from args + context.
@@ -84,6 +155,8 @@ export function run(argv, ctx) {
     return 2;
   }
 
+  if (args.owner !== null) return runOwner(args, dir);
+
   if (args.profileSpecified && args.profile !== "visual-parity") {
     console.error(fail(`unknown validation profile: ${args.profile}`, "use --profile visual-parity"));
     return 2;
@@ -96,13 +169,21 @@ export function run(argv, ctx) {
     // arbitrary --workspace <dir> stays conservative (unless its config resolves the host).
     mode: args.workspace ? "workspace" : "monorepo",
   });
+  const topology = topologyFor(dir);
+  const spaceFindings = "error" in topology
+    ? [{ level: ERROR, rule: "publication-topology", file: TOPOLOGY_FILE, message: topology.error,
+      fix: "re-run `tot clone <tenant>` to record the topology again" }]
+    : topology.topology ? rootFilesOwnedByMounts(topology.topology, contentFiles(dir)) : [];
+  const withSpaces = spaceFindings.length
+    ? { ok: baseline.ok && !spaceFindings.some((item) => item.level === ERROR), findings: mergeFindings(baseline.findings, spaceFindings) }
+    : baseline;
   const result = args.profile === "visual-parity"
     ? (() => {
       const parity = validateVisualParityClosure(dir, { tenantId: target.tenantId ?? undefined });
-      const findings = mergeFindings(baseline.findings, parity.findings);
+      const findings = mergeFindings(withSpaces.findings, parity.findings);
       return { ok: !findings.some((item) => item.level === ERROR), findings };
     })()
-    : baseline;
+    : withSpaces;
   const { ok, findings } = result;
 
   if (args.json) {

package/src/git-credential.mjs

@@ -151,11 +151,17 @@ export function dropCachedCredential(filePath) {
 }
 
 /** The checkout kinds `tot` records in a checkout's local git config. A tenant store
- *  carries none (it is recognized by its `.tot/config.json`); a read-only kit clone is
- *  recorded explicitly, because nothing else in it says what to mint. */
+ *  carries none (it is recognized by its `.tot/config.json`); a read-only kit clone and a
+ *  mounted publication space are recorded explicitly, because nothing else in them says what
+ *  to mint — a space repository carries a `.tot/config.json` naming its tenant, which would
+ *  otherwise mint the ROOT repository's credential for it. */
 export const CHECKOUT_KIND_KEY = "tot.checkoutKind";
 export const READ_TARGET_KEY = "tot.readTarget";
 export const READ_ONLY_KIT_KIND = "read-only-kit";
+export const PUBLICATION_SPACE_KIND = "publication-space";
+export const SPACE_TENANT_KEY = "tot.spaceTenant";
+export const SPACE_ID_KEY = "tot.spaceId";
+export const SPACE_REPO_KEY = "tot.spaceRepo";
 
 /**
  * Record in a freshly cloned checkout that it is a read-only kit clone of `target`, so
@@ -169,18 +175,43 @@ export function recordReadOnlyKitCheckout(git, target) {
   git(["config", "--local", READ_TARGET_KEY, target]);
 }
 
+/**
+ * Record in a freshly cloned checkout that it is the mounted publication space `spaceId` of
+ * `tenant`, whose repository is `repo`, so `tot git-credential` mints its credential through
+ * `publication_checkout` and never as the tenant's root store. Throws on a git failure.
+ * @param {(cargs: string[]) => unknown} git  a `git -C <checkout>` runner
+ * @param {{ tenant: string, spaceId: string, repo: string }} space
+ */
+export function recordPublicationSpaceCheckout(git, { tenant, spaceId, repo }) {
+  git(["config", "--local", CHECKOUT_KIND_KEY, PUBLICATION_SPACE_KIND]);
+  git(["config", "--local", SPACE_TENANT_KEY, tenant]);
+  git(["config", "--local", SPACE_ID_KEY, spaceId]);
+  git(["config", "--local", SPACE_REPO_KEY, repo]);
+}
+
 /**
  * Read which kind of checkout `git` runs in: `{ kind: "read-only-kit", target }` for a
- * recorded kit clone, else `{ kind: "store" }` (the default; the store path then applies
- * its own checks). An unrecorded or unreadable config is a store, never a kit.
+ * recorded kit clone, `{ kind: "publication-space", tenant, spaceId, repo }` for a recorded
+ * space, else `{ kind: "store" }` (the default; the store path then applies its own checks).
+ * An unrecorded config is a store. A space record missing a field is `{ kind: "invalid" }`:
+ * it must mint nothing, never fall back to the store's credential.
  * @param {(cargs: string[]) => string} git
- * @returns {{ kind: "read-only-kit", target: string } | { kind: "store" }}
+ * @returns {{ kind: "read-only-kit", target: string } |
+ *   { kind: "publication-space", tenant: string, spaceId: string, repo: string } |
+ *   { kind: "invalid" } | { kind: "store" }}
  */
 export function readCheckoutKind(git) {
   const get = (key) => {
     try { return String(git(["config", "--local", "--get", key])).trim(); } catch { return ""; }
   };
-  if (get(CHECKOUT_KIND_KEY) !== READ_ONLY_KIT_KIND) return { kind: "store" };
+  const kind = get(CHECKOUT_KIND_KEY);
+  if (kind === PUBLICATION_SPACE_KIND) {
+    const tenant = get(SPACE_TENANT_KEY);
+    const spaceId = get(SPACE_ID_KEY);
+    const repo = get(SPACE_REPO_KEY);
+    return tenant && spaceId && repo ? { kind: PUBLICATION_SPACE_KIND, tenant, spaceId, repo } : { kind: "invalid" };
+  }
+  if (kind !== READ_ONLY_KIT_KIND) return { kind: "store" };
   const target = get(READ_TARGET_KEY);
   return target ? { kind: READ_ONLY_KIT_KIND, target } : { kind: "store" };
 }

package/src/publication-spaces.mjs

@@ -0,0 +1,307 @@
+/**
+ * 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;
+
+/**
+ * Platform-owned paths no space serves (packages/public-runtime PUBLICATION_SPACE_RESERVED_MOUNTS;
+ * the ownership parity test holds the two equal).
+ */
+export const PLATFORM_PATHS = Object.freeze([
+  "/.well-known", "/__evidence", "/__preview", "/_a", "/_astro", "/_style-guide", "/admin", "/api",
+  "/apps", "/assets", "/auth", "/brand", "/capabilities", "/cockpit", "/dashboard", "/dev",
+  "/favicon.svg", "/health", "/js", "/feed.json", "/llms.txt", "/publication-discovery",
+  "/search-index.json", "/sitemap.xml", "/platform", "/preview", "/products", "/collections",
+  "/search", "/saved", "/robots.txt", "/shared", "/style-guide", "/tenants",
+]);
+
+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: none for a platform path (`/api`, `/admin`, ...), else the longest
+ * canonical mount (or alias) that owns it, else the root. Null for a path that cannot be read as one.
+ * @param {Topology} topology
+ * @param {string} urlPath
+ * @returns {{ space: TopologySpace, via: "mount"|"alias"|"root" } | { space: null, via: "platform" } | null}
+ */
+export function owningSpace(topology, urlPath) {
+  const path = normalizeRequestPath(urlPath);
+  if (path === null) return null;
+  const folded = path.toLowerCase();
+  if (PLATFORM_PATHS.some((reserved) => mountMatchesPath(reserved, folded))) return { space: null, via: "platform" };
+  /** @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`);
+}
+
+/** The post collections a space can carry; each is served under its base path (default: its name). */
+export const COLLECTIONS = ["blog", "the-build"];
+
+/**
+ * The URL path a ROOT checkout file renders at, for the files whose URL the layout fixes:
+ * `content/pages-html/<slug>.html` and `content/pages/<slug>.json` at `/<slug>`, a collection's
+ * files under its base path. Null for files with no URL of their own (theme, chrome, assets).
+ * @param {TopologySpace} root
+ * @param {string} relPath  path relative to the root checkout
+ */
+export function rootFileUrlPath(root, relPath) {
+  const rel = String(relPath).replace(/\\/g, "/");
+  let m = /^content\/pages-html\/(.+)\.html$/.exec(rel) ?? /^content\/pages\/(.+)\.json$/.exec(rel);
+  if (m) return `/${m[1]}`;
+  m = /^content\/([^/]+)\//.exec(rel);
+  if (m && COLLECTIONS.includes(m[1])) {
+    const base = root.collections?.[m[1]] ?? m[1];
+    return base ? `/${base.replace(/^\/+|\/+$/g, "")}` : null;
+  }
+  return null;
+}
+
+/**
+ * Root files whose URL a mounted space owns. Visitors get the space's page at that URL, never the
+ * root's, so the file is dead weight in the root and a change to it ships nowhere.
+ * @param {Topology} topology
+ * @param {string[]} rootFiles  paths relative to the root checkout
+ * @returns {Array<{ level: "warn", rule: string, file: string, message: string, fix: string }>}
+ */
+export function rootFilesOwnedByMounts(topology, rootFiles) {
+  const root = rootSpace(topology);
+  const findings = [];
+  for (const file of rootFiles) {
+    const urlPath = rootFileUrlPath(root, file);
+    if (!urlPath) continue;
+    const owner = owningSpace(topology, urlPath);
+    if (!owner || !owner.space || owner.space.mount === "/") continue;
+    findings.push({
+      level: /** @type {"warn"} */ ("warn"),
+      rule: "publication-space-owns-url",
+      file,
+      message: `${urlPath} is served by the mounted space "${owner.space.id}" (${owner.space.source.forge}:${owner.space.source.repo}, mount ${owner.space.mount}), so this root file never reaches a visitor.`,
+      fix: `move it into ${spaceDir(owner.space)}/ (the "${owner.space.id}" repository), or delete it from the root`,
+    });
+  }
+  return findings;
+}
+
+/**
+ * Who owns a URL path. `spaceId` is null for a platform path, which no repository serves.
+ * @param {Topology} topology @param {string} urlPath
+ * @returns {{ path: string, spaceId: string|null, mount: string|null, via: string, repo: string|null, dir: string|null } | null}
+ */
+export function describeOwner(topology, urlPath) {
+  const owner = owningSpace(topology, urlPath);
+  if (!owner) return null;
+  const { space, via } = owner;
+  if (!space) {
+    return { path: /** @type {string} */ (normalizeRequestPath(urlPath)), spaceId: null, mount: null, via, repo: null, dir: null };
+  }
+  return {
+    path: /** @type {string} */ (normalizeRequestPath(urlPath)),
+    spaceId: space.id,
+    mount: space.mount,
+    via,
+    repo: `${space.source.forge}:${space.source.repo}`,
+    dir: spaceDir(space) || ".",
+  };
+}

package/src/tenant-scope.mjs

@@ -26,7 +26,8 @@ import { CliError } from "./errors.mjs";
  * Tools whose `tenant` argument is the tenant the call acts on. Action-harness tools get the
  * argument from `registerActionTool` (tot-mcp `src/modules/mcp/tools/action-tool.ts`), which
  * resolves it through `resolveCallTenant` and echoes the tenant it acted on in every success
- * result; `tenant_checkout` declares the same argument itself and echoes it too.
+ * result; `tenant_checkout` and `publication_checkout` declare the same argument themselves and
+ * echo the tenant too.
  */
 export const TENANT_SCOPED_TOOLS = Object.freeze(new Set([
   "candidate_open",
@@ -35,6 +36,7 @@ export const TENANT_SCOPED_TOOLS = Object.freeze(new Set([
   "preview_status",
   "promotion_rollback",
   "promotion_status",
+  "publication_checkout",
   "tenant_checkout",
 ]));