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

package/src/commands/login.mjs

@@ -4,7 +4,7 @@
  * Runs the MCP OAuth 2.1 PKCE loopback (the same ceremony `claude mcp add` runs):
  * opens the browser to the MCP's authorize page, the developer signs in with their
  * ToT identity + approves, and the loopback catches the code and exchanges it for a
- * token cached at ~/.tot/credentials.json. Every later command (`tot checkout`,
+ * token cached at ~/.tot/credentials.json. Every later command (`tot clone`,
  * `tot submit`, …) then runs as that developer with NO re-auth.
  *
  * The MCP defaults to the same target `tot submit` talks to (env MCP_BASE_URL /
@@ -25,6 +25,7 @@ import { openBrowser } from "../open.mjs";
 import { fail } from "../errors.mjs";
 import { cockpitRecoveryUrl, normalizeEmailHint, redactEmailForHint, emailFromJwt } from "../auth.mjs";
 import { isInteractive, promptYesNo } from "../prompt.mjs";
+import { versionStamp } from "../mcp.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
@@ -108,7 +109,7 @@ const USAGE = `tot login — sign in to Token of Trust
   link a later \`tot feedback\` report to your invite + session) — not meant to be
   typed by hand.
 
-After signing in, run \`tot whoami\` to confirm, then \`tot checkout\` / \`tot submit\`.`;
+After signing in, run \`tot whoami\` to confirm, then \`tot clone\` / \`tot submit\`.`;
 
 /**
  * The core of `tot login`: run the OAuth ceremony (browser loopback, or the
@@ -255,6 +256,10 @@ export async function run(argv, _ctx) {
     return 0;
   }
 
+  // Show which CLI/runtime is actually running BEFORE anything else — the first thing
+  // a "why did sign-in behave oddly" investigation needs (e.g. a stale shadowing `tot`).
+  console.error(versionStamp());
+
   const mcpUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
 
   if (args.code) {
@@ -265,7 +270,7 @@ export async function run(argv, _ctx) {
       cacheTraceId(env, args.traceId);
       cacheEmailHint(env, args.emailHint);
       console.log(`\n+ signed in. Session cached to ${defaultCredentialsPath(env)}.`);
-      console.log("  Next: `tot whoami` to confirm, or `tot checkout` / `tot submit` to build.");
+      console.log("  Next: `tot whoami` to confirm, or `tot clone` / `tot submit` to build.");
       return 0;
     } catch (e) {
       console.error(
@@ -283,7 +288,7 @@ export async function run(argv, _ctx) {
     await loginAndCache(mcpUrl, env, { log: (m) => console.error(m), device: args.device });
     cacheTraceId(env, args.traceId);
     console.log(`\n+ signed in. Session cached to ${defaultCredentialsPath(env)}.`);
-    console.log("  Next: `tot whoami` to confirm, or `tot checkout` / `tot submit` to build.");
+    console.log("  Next: `tot whoami` to confirm, or `tot clone` / `tot submit` to build.");
     return 0;
   } catch (e) {
     console.error(

package/src/commands/pr.mjs

@@ -0,0 +1,424 @@
+/**
+ * `tot pr` — see and manage the candidate PRs `tot submit` opens, mirroring
+ * `gh pr`.
+ *
+ *   tot pr [list]        list your OPEN candidate PRs for this store
+ *   tot pr view <N|id>   show one candidate (by PR number or changeId)
+ *   tot pr close <N|id>  close (reject) a candidate without merging
+ *
+ * A candidate PR is the reviewable unit `tot submit` creates. By default a
+ * re-submit UPDATES your open candidate; `tot submit --new` forks another. This
+ * command fills the gap the raw submit loop left — a first-party way to list your
+ * open candidates and to close one (candidate close was otherwise gated to
+ * version-control apps only).
+ *
+ * Runs from inside a tenant checkout (it derives the forge repo from the
+ * checkout's origin remote, exactly as `tot submit` does) and reads over the MCP
+ * `candidate_status` / `candidate_close` tools. Dependency-free (global fetch +
+ * `git`).
+ *
+ * OPERATOR MODE (unit U17). `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>` (U16). It reuses U16's exact transport: the SAME `GET /api/changes`
+ * HTTP endpoint + operator-secret Bearer auth (`resolveOperatorSecret`,
+ * `normalizeChangesQueue` from ship.mjs). `view`/`close` stay developer-only.
+ */
+import { execFileSync } from "node:child_process";
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { fail } from "../errors.mjs";
+import { repoNameFromRemote, currentBranch } from "./submit.mjs";
+// U17 reuses U16's operator-secret transport helpers verbatim (same env precedence,
+// same queue normalisation) so the operator `tot pr list` and `tot ship --pr` speak
+// one wire, not two.
+import { resolveOperatorSecret, normalizeChangesQueue } from "./ship.mjs";
+import {
+  defaultCandidateStatePath,
+  readActiveChangeId,
+  clearActiveChangeId,
+} from "../candidate-state.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+const SUBCOMMANDS = ["list", "view", "close"];
+
+/**
+ * The storefront-owned, shareable `/preview/<tenant>/pr/<N>` link — NEVER the
+ * forge/Gitea `url` (2026-08-18 incident: a raw forge PR URL reached an
+ * owner). `candidate_status` (the local-checkout MCP tool) has no
+ * `previewUrl` field at all, unlike the operator `GET /api/changes` path — so
+ * this constructs it the same way `runPrListOperator`'s caller resolves
+ * `storefrontUrl`, from the same env/--url override chain. Pure.
+ * @param {string} storefrontUrl
+ * @param {string} tenant
+ * @param {number|null|undefined} prNumber
+ * @returns {string|null}
+ */
+export function buildPreviewUrl(storefrontUrl, tenant, prNumber) {
+  if (typeof prNumber !== "number" || !tenant) return null;
+  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+  return `${base}/preview/${tenant}/pr/${prNumber}`;
+}
+
+const USAGE = `tot pr — see and manage candidate PRs
+
+  tot pr [list]              list your open candidate PRs for this store
+  tot pr list --tenant <t>   OPERATOR: list a tenant's open candidate PRs (no checkout)
+  tot pr view <N|id>         show one candidate PR (by PR number or changeId)
+  tot pr close <N|id>        close (reject) a candidate PR without merging
+  tot pr close <N|id> --reason "<why>"   record why it was closed (audit note)
+  tot pr --mcp <url>         MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+
+  DEVELOPER (default) — run inside your OWN store checkout: lists/manages the
+  candidates \`tot submit\` opens. A re-submit updates your open one by default;
+  \`tot submit --new\` forks another.
+
+  OPERATOR — \`tot pr list --tenant <appDomain>\` lists ANY tenant's open candidate
+  queue WITHOUT a checkout (the read-only companion to \`tot ship --pr <N> --tenant\`).
+  It reads \`GET /api/changes\` with an operator secret:
+
+    tot pr list --tenant <t>   list <t>'s open candidate PRs
+    tot pr list --url <origin> storefront origin (default: env TOT_STOREFRONT_URL)
+    tot pr list --secret <s>   operator secret (prefer the env vars below)
+
+  Operator secret (from env, first found): PREVIEW_RECONCILE_SECRET,
+  GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET (or pass --secret).`;
+
+/** Parse `tot pr` argv into { sub, target, reason, mcp, identity, tenant, url, secret, help }. Pure. */
+export function parsePrArgs(argv) {
+  const a = {
+    sub: null,
+    target: null,
+    reason: null,
+    mcp: null,
+    identity: null,
+    tenant: null,
+    url: null,
+    secret: null,
+    help: false,
+  };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--mcp") a.mcp = argv[++i];
+    else if (t === "--identity") a.identity = argv[++i];
+    else if (t === "--reason") a.reason = argv[++i];
+    else if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--secret") a.secret = argv[++i];
+    else if (t === "--help" || t === "-h") a.help = true;
+    else positional.push(t);
+  }
+  a.sub = positional[0] || "list";
+  a.target = positional[1] ?? null;
+  return a;
+}
+
+/** Normalize the `candidate_status` list response to a flat candidate array. Pure. */
+export function extractCandidates(result) {
+  if (Array.isArray(result)) return result;
+  if (result && Array.isArray(result.candidates)) return result.candidates;
+  if (result && Array.isArray(result.environments)) return result.environments;
+  if (result && typeof result.changeId === "string") return [result];
+  return [];
+}
+
+/** Find a candidate by PR number (all-digits target) or exact changeId. Pure. */
+export function matchCandidate(candidates, target) {
+  if (target == null) return null;
+  if (/^\d+$/.test(target)) {
+    const n = Number(target);
+    return candidates.find((c) => c.prNumber === n) ?? null;
+  }
+  return candidates.find((c) => c.changeId === target) ?? null;
+}
+
+/**
+ * One-line candidate summary for `tot pr list` — surfaces branch ↔ PR# ↔ preview
+ * URL so a dev sees, at a glance, which git branch each candidate belongs to (u4 —
+ * branch-bound candidates) and where its preview lives. ONLY `previewUrl` (the
+ * storefront-owned `/preview/<tenant>/pr/<N>` link) — NEVER `url` (the forge/
+ * Gitea `html_url`), which must never reach a terminal (2026-08-18 incident:
+ * a raw forge PR URL reached an owner). `active` marks the one
+ * THIS checkout's branch resolves to. Pure — unit-tested.
+ * @param {{prNumber?:number|null, branch?:string|null, changeId:string, state?:string|null,
+ *   previewUrl?:string|null, url?:string|null}} c
+ * @param {{ active?: boolean }} [opts]
+ */
+export function formatCandidateLine(c, { active = false } = {}) {
+  const pr = typeof c.prNumber === "number" ? `#${c.prNumber}` : "#—";
+  const branch = c.branch ? c.branch : "(no branch)";
+  const urlPart = c.previewUrl ? `  ${c.previewUrl}` : "";
+  const activePart = active ? "  ← active" : "";
+  return `  PR ${pr}  ${branch}  ${c.changeId}  [${c.state ?? "?"}]${urlPart}${activePart}`;
+}
+
+// ─── Operator queue listing (unit U17) ──────────────────────────────────────────────
+//
+// The read-only companion to `tot ship --pr <N> --tenant <t>` (U16): list a tenant's
+// OPEN candidate queue WITHOUT a checkout. It reuses U16's exact transport — the SAME
+// `GET /api/changes` endpoint (operator accept queue) + Bearer operator-secret auth
+// (`resolveOperatorSecret` / `normalizeChangesQueue` from ship.mjs) — so a listing and
+// a ship read one wire. NO merge/deploy/side-effect; pure listing.
+
+/**
+ * One-line summary of an OPEN operator-queue candidate for `tot pr list --tenant`.
+ * Two shapes come off `GET /api/changes`:
+ *   - BUILT candidate (`built:true`, has a `changeId`): PR # / status / changeId /
+ *     short head sha / preview URL — the fields an operator needs to pick a PR to ship.
+ *   - NOT-BUILT forge PR (`built:false` / `changeId:null` / `status:"not-built"`): an
+ *     open PR with no preview yet. Render it DISTINCTLY — no changeId (there is none),
+ *     a `[not built]` tag, and a build HINT instead of a preview URL — so an operator
+ *     sees it's listable but must `tot preview build` before it can ship.
+ * Adapts `formatCandidateLine`'s house style to the `GET /api/changes` shape (`status`
+ * not `state`; `previewUrl`; a `headSha` to short-render). Pure — unit-tested.
+ * @param {{prNumber?:number|null, status?:string|null, changeId?:string|null,
+ *   headSha?:string|null, previewUrl?:string|null, built?:boolean}} c
+ * @returns {string}
+ */
+export function formatOperatorCandidateLine(c) {
+  const pr = typeof c.prNumber === "number" ? `#${c.prNumber}` : "#—";
+  const head = c.headSha ? c.headSha.slice(0, 8) : "(no head)";
+  // A not-built PR: no changeId, so route the operator to build it first.
+  const notBuilt = c.built === false || (!c.changeId && c.status === "not-built");
+  if (notBuilt) {
+    const hint =
+      typeof c.prNumber === "number"
+        ? `  → tot preview build --pr ${c.prNumber}`
+        : "  → tot preview build";
+    return `  PR ${pr}  [not built]  ${head}${hint}`;
+  }
+  const status = c.status ?? "?";
+  const urlPart = c.previewUrl ? `  ${c.previewUrl}` : "";
+  return `  PR ${pr}  [${status}]  ${c.changeId}  ${head}${urlPart}`;
+}
+
+/**
+ * Sort an OPEN candidate queue by PR number DESC (newest PR first); candidates
+ * without a PR number sort last, then stably by changeId. Pure — unit-tested.
+ * @param {ReturnType<typeof normalizeChangesQueue>} changes
+ */
+export function sortQueueByPrDesc(changes) {
+  return [...(changes || [])].sort((a, b) => {
+    const ap = typeof a.prNumber === "number" ? a.prNumber : -Infinity;
+    const bp = typeof b.prNumber === "number" ? b.prNumber : -Infinity;
+    if (ap !== bp) return bp - ap;
+    return String(a.changeId).localeCompare(String(b.changeId));
+  });
+}
+
+/**
+ * The OPERATOR `tot pr list --tenant <t>` flow: fetch the tenant's OPEN candidate
+ * queue over `GET /api/changes` (Bearer operator secret + `X-Tot-Owner` +
+ * `x-tot-capability: ship-on-behalf`, mirroring U16) and print each candidate one per
+ * line, sorted by PR number desc. Fail-closed: no secret → honest refusal (exit 2)
+ * BEFORE any network. `fetch` is injected so it's unit-tested with no live network.
+ *
+ * @param {{ tenant:string, secret:string, storefrontUrl?:string|null }} params
+ * @param {{ fetch?:typeof fetch }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runPrListOperator({ tenant, secret, storefrontUrl = null }, deps = {}) {
+  const fetchImpl = deps.fetch || globalThis.fetch;
+  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+
+  if (!secret) {
+    console.error(
+      fail(
+        "listing a tenant's queue is an OPERATOR action — it needs an operator secret",
+        "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
+      ),
+    );
+    return 2;
+  }
+
+  const authHeaders = {
+    authorization: `Bearer ${secret}`,
+    "x-tot-owner": tenant,
+    "x-tot-capability": "ship-on-behalf",
+  };
+
+  let res;
+  try {
+    res = await fetchImpl(`${base}/api/changes`, { method: "GET", headers: authHeaders });
+  } catch (e) {
+    console.error(
+      fail(`couldn't reach the candidate queue at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+
+  let data = {};
+  try {
+    data = await res.json();
+  } catch {
+    /* non-JSON / empty body */
+  }
+  if (!res.ok) {
+    const msg = data?.error || `HTTP ${res.status}`;
+    console.error(
+      fail(
+        `the candidate queue refused the request: ${msg}`,
+        res.status === 401 || res.status === 403
+          ? "check the operator secret and that it's authorised for this tenant"
+          : "check --tenant / --url, then re-run",
+      ),
+    );
+    return 1;
+  }
+
+  const changes = sortQueueByPrDesc(normalizeChangesQueue(data));
+  if (!changes.length) {
+    console.log(`No open candidate PRs for ${tenant}.`);
+    return 0;
+  }
+  console.log(`Open PRs for ${tenant}:`);
+  for (const c of changes) {
+    console.log(formatOperatorCandidateLine(c));
+  }
+  return 0;
+}
+
+/** @param {string[]} argv @param {any} ctx */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parsePrArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (!SUBCOMMANDS.includes(args.sub)) {
+    console.error(fail(`unknown subcommand: \`tot pr ${args.sub}\``, "tot pr list | view <N> | close <N>"));
+    return 2;
+  }
+
+  // OPERATOR MODE (U17): `--tenant <t>` lists that tenant's OPEN candidate queue with
+  // NO checkout, over the same HTTP transport `tot ship --pr` uses. Only `list` has an
+  // operator path today — `view`/`close` stay developer-only (checkout-bound).
+  if (args.tenant && `${args.tenant}`.trim()) {
+    if (args.sub !== "list") {
+      console.error(
+        fail(
+          `\`tot pr ${args.sub} --tenant\` isn't wired — only \`tot pr list --tenant\` has an operator path`,
+          "use `tot pr list --tenant <t>` to list, then act from a checkout",
+        ),
+      );
+      return 2;
+    }
+    const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+    return await runPrListOperator({
+      tenant: `${args.tenant}`.trim(),
+      secret: resolveOperatorSecret(args.secret, env),
+      storefrontUrl,
+    });
+  }
+
+  if (ctx.mode !== "checkout") {
+    console.error(
+      fail(
+        "`tot pr` runs from inside a tenant checkout",
+        "tot clone <tenant> <dir>   (then `cd` in and re-run), or `tot pr list --tenant <t>` for operator mode",
+      ),
+    );
+    return 2;
+  }
+  if ((args.sub === "view" || args.sub === "close") && !args.target) {
+    console.error(fail(`\`tot pr ${args.sub}\` needs a PR number or changeId`, `tot pr ${args.sub} <N>`));
+    return 2;
+  }
+
+  const workspace = ctx.workspacePath;
+  const tenant = ctx.tenant;
+  const gitSafe = (cargs) => {
+    try {
+      return execFileSync("git", ["-C", workspace, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+    } catch {
+      return "";
+    }
+  };
+  const repo = repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim());
+  if (!repo) {
+    console.error(
+      fail("couldn't derive the forge repo from this checkout's remote", "run this from a `tot clone`d store"),
+    );
+    return 1;
+  }
+
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+  const statePath = defaultCandidateStatePath(env);
+  // Branch-bound (u4): the active-pointer namespace is scoped to the current git
+  // branch, so the "← active" marker reflects THIS branch's candidate.
+  const scope = { mcpUrl: baseUrl, repo, branch: currentBranch(gitSafe) };
+  const client = createMcpClient(baseUrl);
+  try {
+    const session = await establishSession(client, { env, prefer: args.identity || undefined });
+    void session;
+    // Bind the active tenant so candidate_status/close read the right scope.
+    await client.callTool("client_switch", { tenant });
+
+    const candidates = extractCandidates(await client.callTool("candidate_status", { repo }));
+
+    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 }));
+      }
+      return 0;
+    }
+
+    const match = matchCandidate(candidates, args.target);
+    if (!match) {
+      console.error(fail(`no open candidate matches "${args.target}"`, "tot pr list   (to see your open candidates)"));
+      return 1;
+    }
+
+    if (args.sub === "view") {
+      const active = readActiveChangeId(statePath, scope);
+      console.log(`PR ${typeof match.prNumber === "number" ? `#${match.prNumber}` : "#—"} — ${match.changeId}${match.changeId === active ? "  (active)" : ""}`);
+      console.log(`  state:            ${match.state ?? "?"}`);
+      if (match.branch) console.log(`  branch:           ${match.branch}`);
+      if (match.headSha) console.log(`  head:             ${match.headSha}`);
+      if (match.baseSha) console.log(`  base:             ${match.baseSha}`);
+      console.log(`  mergeable (forge): ${match.mergeable ?? "?"}`);
+      // ONLY the storefront-owned preview link -- never the raw forge/Gitea `url`.
+      const previewUrl = match.previewUrl ?? buildPreviewUrl(storefrontUrl, tenant, match.prNumber);
+      if (previewUrl) console.log(`  ${previewUrl}`);
+      return 0;
+    }
+
+    // close
+    await client.callTool("candidate_close", {
+      repo,
+      changeId: match.changeId,
+      ...(args.reason ? { reason: args.reason } : {}),
+    });
+    console.log(`✓ closed candidate ${match.changeId}${typeof match.prNumber === "number" ? ` (PR #${match.prNumber})` : ""}.`);
+    // If we just closed the remembered active candidate, forget it so the next
+    // plain `tot submit` starts a fresh one rather than resurrecting this handle.
+    if (readActiveChangeId(statePath, scope) === match.changeId) {
+      try {
+        clearActiveChangeId(statePath, scope);
+      } catch { /* best-effort */ }
+    }
+    return 0;
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      console.error(fail("sign in to manage candidate PRs", e.hint || "run `tot login`, then re-run"));
+      return 1;
+    }
+    console.error(
+      fail(
+        `couldn't reach the candidate service: ${String(e?.message || e)}`,
+        "check your connection and that you're signed in, then re-run",
+      ),
+    );
+    return 1;
+  }
+}