@tokenoftrust/cli 1.4.0-rc.19 → 1.4.0-rc.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.4.0-rc.19",
+  "version": "1.4.0-rc.20",
   "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

@@ -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";
@@ -43,6 +64,7 @@ function parseArgs(argv) {
     tenant: null,
     dir: null,
     tag: "main",
+    pr: null,
     remoteOnly: false,
     mcp: null,
     printRemote: false,
@@ -51,6 +73,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 +87,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 +150,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 +188,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`,
@@ -257,6 +348,134 @@ async function cloneRepo(gitRemote, dir, redact) {
   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

package/src/commands/start.mjs

@@ -695,8 +695,7 @@ function printCheckoutLanding(dir, cockpitUrl = null) {
 
 /** The crafted "you're live" ending — a PROMINENT milestone banner (u2) that,
  * when we hold a Developer Cockpit URL, explicitly sends the developer BACK to
- * their cockpit as the next place to look; then the AI-wow (G), seeded with
- * IDEAS[0] (G2/G3 — one prompt list shared with `tot ideas`, no drift). */
+ * their cockpit as the next place to look. */
 function printLiveEnding(tenant, url, elapsed, cockpitUrl = null) {
   const lines = [
     `✨  You're live.${elapsed ? `  (${elapsed})` : ""}`,
@@ -711,11 +710,6 @@ function printLiveEnding(tenant, url, elapsed, cockpitUrl = null) {
   console.log(milestoneBanner(lines));
   console.log("  " + versionStamp("native"));
   console.log("");
-  console.log("  Now try, in Claude:");
-  console.log(`     "${IDEAS[0]}"`);
-  console.log("");
-  console.log("  More ideas: tot ideas");
-  console.log("");
 }
 
 /**