@tokenoftrust/cli 1.4.0 → 1.4.1

package/src/commands/clone.mjs

@@ -23,6 +23,27 @@
  * resolved via src/auth.mjs). When there's no session yet and we're on a TTY, we
  * offer to sign in right here and retry — no "run tot login, then re-run".
  *
+ * OPERATOR CROSS-TENANT PR CLONE (unit u6). `tot clone <tenant> --pr <N> [dir]`
+ * materializes a PARTICULAR pull request's head — including on a tenant the
+ * operator does NOT own/isn't a member of (e.g. inspecting someone else's PR
+ * #7). This does NOT go through `tenant_checkout` — that tool mints a PUSH
+ * credential for your own active tenant only, its `tag` param is deprecated +
+ * ignored (repo-name cutover, 8425), and it flatly refuses a foreign tenant
+ * (over-scoped). Instead it mints a SHORT-lived, READ-ONLY credential via
+ * `repo_read_credential({ tenant })` — the read counterpart to tenant_checkout,
+ * server-authorized by tot20's `decideContentRead` (deny-by-default: org-wide
+ * read authority, ownership of the target, or a per-tenant operator grant). The
+ * SAME call also covers your OWN tenant (its exact-tenant path needs no grant),
+ * so `--pr` always takes this path regardless of membership — there is no
+ * PR-ref parameter on tenant_checkout to make the own-tenant case worth
+ * special-casing. Once cloned, the PR's head is fetched by NUMBER via Gitea's
+ * standard `refs/pull/<N>/head` ref — no separate PR-metadata lookup is needed
+ * (and `repo_pr_read`/`repo_pr_list` are app-session-only tools today, per their
+ * `guardCommon`/`boundApp` gate in tot-mcp — unreachable from this CLI's single
+ * developer-OAuth auth plane for a genuine cross-tenant human operator, so this
+ * command does not depend on them). The CLI never reimplements or bypasses the
+ * server's authorization decision — only requests it and relays the result.
+ *
  * Dependency-free (global fetch + `git` via child_process).
  */
 import { execFile } from "node:child_process";
@@ -33,6 +54,7 @@ import { offerSignIn } from "./login.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 import { writeNvmrc } from "../sample.mjs";
 import { emitObstacle } from "../obstacle.mjs";
+import { CREDENTIAL_HELPER, splitAuthedRemote, basicAuthExtraHeader } from "../git-credential.mjs";
 
 const execFileP = promisify(execFile);
 
@@ -43,6 +65,7 @@ function parseArgs(argv) {
     tenant: null,
     dir: null,
     tag: "main",
+    pr: null,
     remoteOnly: false,
     mcp: null,
     printRemote: false,
@@ -51,6 +74,7 @@ function parseArgs(argv) {
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--tag") a.tag = argv[++i];
+    else if (t === "--pr") a.pr = argv[++i];
     else if (t === "--remote-only") a.remoteOnly = true;
     else if (t === "--mcp") a.mcp = argv[++i];
     else if (t === "--print-remote") a.printRemote = true;
@@ -64,14 +88,36 @@ function parseArgs(argv) {
   return a;
 }
 
+/**
+ * Parse + validate the `--pr` value into a positive integer, or null when
+ * absent. Throws a CliError (never a raw NaN downstream) on garbage input.
+ * Pure. @param {unknown} raw @returns {number|null}
+ */
+export function parsePrNumber(raw) {
+  if (raw == null) return null;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1) {
+    throw new CliError(`invalid --pr value "${raw}" — must be a positive PR number`, {
+      next: "tot clone <tenant> --pr <N> [dir]",
+    });
+  }
+  return n;
+}
+
 const USAGE = `tot clone — clone a tenant store you can build on (mirrors \`git clone\`)
 
   tot clone                    list the stores you can build on
   tot clone <tenant>           clone into ./<tenant> (authenticated remote configured)
   tot clone <tenant> <dir>     clone into <dir>
+  tot clone <tenant> --pr <N> [dir]   OPERATOR: clone PR #<N>'s head, READ-ONLY
+                                (works even on a tenant you don't own/aren't a
+                                member of, when authorized; dir defaults to
+                                <tenant>-pr<N>)
 
 Options:
   --tag <tag>       which repo (repo = "<tenant>-<tag>"). Default: main.
+  --pr <N>          clone PR #<N>'s head instead of the default branch — a
+                    READ-ONLY cross-tenant credential, not a push checkout.
   --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}.
@@ -105,10 +151,19 @@ export async function run(argv, ctx) {
     args.tenant = ctx.tenant;
   }
 
+  let pr;
+  try {
+    pr = parsePrNumber(args.pr);
+  } catch (e) {
+    console.error(formatError(e));
+    return e.exitCode ?? 1;
+  }
+
   // git-clone semantics: unless you explicitly asked for --remote-only, cloning
   // is the default, and the target dir defaults to the tenant name (like
-  // `git clone <url>` deriving the dir from the repo basename).
-  const cloneDir = args.remoteOnly ? null : args.dir || args.tenant;
+  // `git clone <url>` deriving the dir from the repo basename) — or, with
+  // --pr, to "<tenant>-pr<N>" so a PR clone never collides with a plain one.
+  const cloneDir = args.remoteOnly ? null : args.dir || (pr ? `${args.tenant}-pr${pr}` : args.tenant);
 
   const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const redact = makeRedactor(env);
@@ -134,11 +189,48 @@ export async function run(argv, ctx) {
 
     // No tenant → list the stores this identity can build on and stop.
     if (!args.tenant) {
+      if (pr) {
+        console.error(fail("`tot clone --pr` needs a tenant", "tot clone <tenant> --pr <N> [dir]"));
+        return 2;
+      }
       const list = await client.callTool("client_list", {});
       printClientList(list);
       return 0;
     }
 
+    // --pr ALWAYS takes the cross-tenant read-credential path, even for your own
+    // tenant — tenant_checkout has no PR-ref parameter to select, so there is no
+    // membership-based fork here (see the file header comment).
+    if (pr) {
+      console.error(
+        `~ repo_read_credential (tenant=${args.tenant}) — MCP mints a read-only credential`,
+      );
+      const res = await cloneCrossTenantPr(client, {
+        tenant: args.tenant,
+        pr,
+        cloneDir,
+        redact,
+      });
+      console.log(`\n+ ready (read-only). repo: ${res.publicUrl}`);
+
+      if (res.cloned) {
+        console.log(`+ cloned PR #${pr}. HEAD: ${res.head}`);
+        console.log(`\nYour local read-only clone of PR #${pr} is at ${res.dir}.`);
+        console.log(`  (this credential can only pull, never push — for your own tenant's`);
+        console.log(`   push checkout, run \`tot clone ${args.tenant}\` without --pr)`);
+        return 0;
+      }
+
+      console.log(`\nPublic clone URL (no credential): ${res.publicUrl}`);
+      console.log(`Drop --remote-only to clone PR #${pr} with the read-only remote configured.`);
+      if (args.printRemote) {
+        console.log(
+          `\nREAD-ONLY remote (contains a live token — handle carefully):\n${res.gitRemote}`,
+        );
+      }
+      return 0;
+    }
+
     console.error(`~ client_switch → ${args.tenant}`);
     console.error(
       `~ tenant_checkout (tag=${args.tag}) — MCP mints a fresh repo-scoped credential`,
@@ -153,9 +245,9 @@ export async function run(argv, ctx) {
 
     if (res.cloned) {
       console.log(`+ cloned. HEAD: ${res.head}`);
-      console.log(`\nYour local working clone is at ${res.dir} with an authenticated remote.`);
+      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(`  (the minted token lives in .git/config; a later clone rotates it)`);
+      console.log(`  (origin has no token — \`tot\` mints one fresh at fetch/push time)`);
       return 0;
     }
 
@@ -194,6 +286,22 @@ export async function run(argv, ctx) {
  */
 export async function checkoutTenant(client, { tenant, tag = "main", cloneDir = null, redact = (s) => s }) {
   await client.callTool("client_switch", { tenant });
+  // vc-app-binding safety-net (08-18, §5): ensure THIS developer is bound to the
+  // storefront version-control app BEFORE checkout, so tenant_checkout can resolve
+  // `appForCaller` for them instead of 403-ing "No version-control app is bound." The
+  // human's OWN session self-triggers it (no subject_token — the subject is the
+  // caller's already-verified identity); the MCP entitlement-gates + authors the bind.
+  // Best-effort + FAIL-OPEN: a missing tool / cold MCP / any fault must never block a
+  // checkout that would otherwise succeed, and if the developer is still unbound the
+  // tenant_checkout error below (via checkoutError) is the honest backstop. Binding is
+  // also ensured at the authority seams (native OAuth sign-in) + backfill; this line
+  // self-heals a legacy session that predates them.
+  try {
+    // Wire name is `identity_bind` (tot-mcp taxonomy: <subject>_<action>).
+    await client.callTool("identity_bind", {});
+  } catch {
+    /* fail-open — see above */
+  }
   const checkout = await client.callTool("tenant_checkout", { tenant, tag });
 
   // A non-checkout result (not provisioned / not entitled / failed) must surface
@@ -216,17 +324,38 @@ export async function checkoutTenant(client, { tenant, tag = "main", cloneDir =
 }
 
 /**
- * git clone the authenticated remote into `dir`. Throws CliError on failure.
- * Runs git as a NON-BLOCKING child process (promisified execFile) so the clone
- * doesn't stall the Node event loop — `tot start` runs this inside a
- * `Promise.all([...])` alongside the renderer prefetch, and a synchronous clone
- * would serialize what's meant to overlap.
+ * git clone the authenticated remote into `dir` — WITHOUT ever writing the
+ * live token to `.git/config` (unit u10). The MCP mints `gitRemote` as a
+ * basic-auth URL (`user:token@host`); rather than passing that straight to
+ * `git clone` (which records exactly the URL it was given as `origin`, token
+ * and all — the pre-u10 shape this fixes), the token is handed to git
+ * EPHEMERALLY via a one-shot `http.extraheader` (same mechanism
+ * pushPreviewRef in submit.mjs uses for a push) while the clone SOURCE is
+ * already the tokenless public URL — so `origin` comes out tokenless from
+ * the very first commit. The new checkout's `credential.helper` is then
+ * configured to `tot git-credential`, so every later fetch/push mints a
+ * fresh token through the CLI's own login session instead of ever needing
+ * one persisted on disk (a later clone no longer needs to "rotate" anything
+ * — the old flow's `.git/config` token is simply never written).
+ *
+ * Runs git as a NON-BLOCKING child process (promisified execFile) so the
+ * clone doesn't stall the Node event loop — `tot start` runs this inside a
+ * `Promise.all([...])` alongside the renderer prefetch, and a synchronous
+ * clone would serialize what's meant to overlap. Throws CliError on failure.
  */
 async function cloneRepo(gitRemote, dir, redact) {
   const git = async (cargs) => (await execFileP("git", cargs)).stdout.toString();
   console.log(`+ git clone → ${dir}`);
+  const cred = splitAuthedRemote(gitRemote);
+  const cloneArgs = cred
+    ? [
+        "-c", `http.extraheader=${basicAuthExtraHeader(cred.username, cred.token)}`,
+        "-c", "credential.helper=",
+        "clone", cred.publicUrl, dir,
+      ]
+    : ["clone", gitRemote, dir]; // no embedded token (e.g. already public) — clone as given
   try {
-    await git(["clone", gitRemote, dir]);
+    await git(cloneArgs);
   } catch (e) {
     // Beacon the cockpit before we surface the error — covers this path for both
     // `tot clone` and `tot start` (which clones through here). Awaited so the
@@ -236,11 +365,145 @@ async function cloneRepo(gitRemote, dir, redact) {
       next: `check the target dir is empty and you can reach the remote, then re-run`,
     });
   }
+  try {
+    await git(["-C", dir, "config", "--local", "credential.helper", CREDENTIAL_HELPER]);
+  } catch {
+    // Best-effort — a checkout missing the helper still WORKS (the token just
+    // isn't self-healing yet); the next `tot preview`/`tot sync` migrates it.
+  }
   const head = (await git(["-C", dir, "log", "-1", "--oneline"])).trim();
   writeNvmrc(dir); // version-manager hooks land on a supported Node on cd
   return { dir, head };
 }
 
+/**
+ * The cross-tenant PR-clone core (unit u6), composable in-process exactly like
+ * `checkoutTenant`: mint a READ-ONLY credential via `repo_read_credential`, then
+ * (optionally) clone it and materialize PR #<pr>'s head. This is the path `--pr`
+ * ALWAYS takes — own tenant or foreign — because tenant_checkout has no PR-ref
+ * parameter (see the file header). Assumes `client` is already initialized +
+ * has a validated session.
+ *
+ * @param {ReturnType<import("../mcp.mjs").createMcpClient>} client
+ * @param {{ tenant: string, pr: number, cloneDir?: string|null, redact?: (s:string)=>string }} opts
+ * @returns {Promise<{ gitRemote: string, publicUrl: string, cloned: boolean,
+ *   dir: string|null, head: string|null }>}
+ */
+export async function cloneCrossTenantPr(
+  client,
+  { tenant, pr, cloneDir = null, redact = (s) => s },
+) {
+  const minted = await client.callTool("repo_read_credential", { tenant });
+
+  // A non-mint result (unauthenticated / forbidden / invalid_input / error) must
+  // surface the MCP's OWN denial reason + a concrete next step — never a raw
+  // JSON dump, and never a CLI-side re-derivation of the authorization call
+  // (the server's `decideContentRead` is the sole authority here).
+  const err = readCredentialError(minted);
+  if (err) {
+    throw new CliError(redact(err.message), { next: err.next });
+  }
+
+  const repos = Array.isArray(minted.repos) ? minted.repos : [];
+  const target = repos.find((r) => r.repo === tenant || r.owner === tenant) ?? repos[0];
+  if (!target || !target.gitRemote) {
+    throw new CliError(
+      `repo_read_credential minted no usable credential for tenant "${tenant}"`,
+      { next: "confirm the tenant name, then re-run" },
+    );
+  }
+  const gitRemote = target.gitRemote;
+  const u = new URL(gitRemote);
+  const publicUrl = `${u.protocol}//${u.host}${u.pathname}`;
+
+  if (!cloneDir) {
+    return { gitRemote, publicUrl, cloned: false, dir: null, head: null };
+  }
+  const { dir, head } = await cloneRepoAtPrRef(gitRemote, cloneDir, pr, redact);
+  return { gitRemote, publicUrl, cloned: true, dir, head };
+}
+
+/**
+ * git clone the authenticated (READ-ONLY) remote into `dir`, then materialize
+ * PR #<pr>'s head by NUMBER — Gitea exposes every pull request at the standard
+ * `refs/pull/<N>/head` ref, so this needs no separate PR-metadata lookup (see
+ * the file header on why `repo_pr_read` isn't used here). Runs git as a
+ * NON-BLOCKING child process (promisified execFile), same as `cloneRepo`.
+ * `deps.git` is injectable for tests (an async `(cargs) => stdout` runner);
+ * defaults to the real `git` binary. Throws CliError on failure.
+ * @param {string} gitRemote
+ * @param {string} dir
+ * @param {number} pr
+ * @param {(s: string) => string} redact
+ * @param {{ git?: (cargs: string[]) => Promise<string> }} [deps]
+ */
+export async function cloneRepoAtPrRef(gitRemote, dir, pr, redact, deps = {}) {
+  const git = deps.git || (async (cargs) => (await execFileP("git", cargs)).stdout.toString());
+  console.log(`+ git clone → ${dir}`);
+  try {
+    await git(["clone", gitRemote, dir]);
+  } catch (e) {
+    await emitObstacle("clone-failed");
+    throw new CliError(`clone failed: ${redact(String(e.stderr || e.message || e))}`, {
+      next: `check the target dir is empty and you can reach the remote, then re-run`,
+    });
+  }
+  const prRef = `refs/pull/${pr}/head`;
+  console.log(`+ git fetch ${prRef}`);
+  try {
+    await git(["-C", dir, "fetch", "origin", prRef]);
+    await git(["-C", dir, "checkout", "-B", `pr-${pr}`, "FETCH_HEAD"]);
+  } catch (e) {
+    throw new CliError(
+      `couldn't fetch PR #${pr}: ${redact(String(e.stderr || e.message || e))}`,
+      { next: `confirm PR #${pr} exists on this tenant — \`tot pr list --tenant <t>\`, then re-run` },
+    );
+  }
+  const head = (await git(["-C", dir, "log", "-1", "--oneline"])).trim();
+  writeNvmrc(dir);
+  return { dir, head };
+}
+
+/**
+ * Classify a `repo_read_credential` tool result: null when it's a genuine,
+ * usable mint (carries at least one repo with a gitRemote), otherwise a human
+ * { message, next } pair — mirrors `checkoutError`'s contract exactly (never a
+ * raw JSON dump; the MCP's own denial reason + a concrete next step). Pure +
+ * exported so it's unit-tested without any I/O.
+ * @param {unknown} minted
+ * @returns {{ message: string, next: string }|null}
+ */
+export function readCredentialError(minted) {
+  const c = minted && typeof minted === "object" && !Array.isArray(minted) ? minted : null;
+  if (c && Array.isArray(c.repos) && c.repos.some((r) => r && r.gitRemote)) return null;
+  const msg =
+    (c && (c.message || (typeof c.error === "string" ? c.error : c.error?.message))) ||
+    (c && typeof c.raw === "string" && c.raw.trim() ? c.raw.trim() : null) ||
+    null;
+  if (typeof msg === "string" && /not authorized/i.test(msg)) {
+    return {
+      message: msg,
+      next:
+        "a cross-tenant read needs org-wide read authority, ownership of the target, or a " +
+        "per-tenant operator grant — ask your Token of Trust contact for one, or confirm the tenant name",
+    };
+  }
+  if (
+    typeof msg === "string" &&
+    /version-control app is bound|registered version-control app/i.test(msg)
+  ) {
+    return {
+      message: "your account isn't onboarded to read this tenant's content yet",
+      next: "re-run `tot login` to refresh your access, then retry — if it persists, ask your " +
+        "Token of Trust contact to finish onboarding your account",
+    };
+  }
+  return {
+    message: msg || "the read credential couldn't be minted",
+    next: "confirm the tenant name and that you're authorized to read it, then re-run",
+  };
+}
+
 /**
  * Classify a `tenant_checkout` tool result: null when it's a genuine, usable
  * checkout (carries a gitRemote), otherwise a human { message, next } pair so
@@ -271,6 +534,22 @@ export function checkoutError(checkout) {
       next: "ask your Token of Trust contact to finish setting up your store, then re-run",
     };
   }
+  // Entitled, but not yet BOUND to the version-control app (appForCaller resolves
+  // nothing for this identity) — the 08-18 vc-app-binding gap. Distinct from
+  // not-provisioned: the STORE is fine; the developer just isn't onboarded to act
+  // THROUGH the app yet. The checkout preflight tries to self-heal this; if it still
+  // surfaces, the binding seam/backfill hasn't reached this identity — say so plainly
+  // instead of the generic "confirm you're entitled" (they ARE entitled).
+  if (
+    typeof msg === "string" &&
+    /version-control app is bound|registered version-control app/i.test(msg)
+  ) {
+    return {
+      message:
+        "your account isn't onboarded to check out this store yet (no version-control app is bound to your session)",
+      next: "re-run `tot login` to refresh your access, then retry — if it persists, ask your Token of Trust contact to finish onboarding your account",
+    };
+  }
   return {
     message: msg || "the store checkout couldn't be completed",
     next: "confirm you're entitled to this store — `tot clone` (lists your stores)",