@tokenoftrust/cli 1.4.0-rc.8 → 1.4.0-rc.9

package/bin/tot.mjs

@@ -14,6 +14,7 @@
  *   tot validate              lint your store before you submit         ← built
  *   tot dev                   run your store locally with save→reload   ← built (monorepo: host astro; standalone: runs the published runner image)
  *   tot submit                submit your store for preview             ← built (validate + push preview ref; MCP preview_status read-back)
+ *   tot pr                    list / view / close your candidate PRs    ← built (candidate_status/candidate_close; gh-pr-shaped)
  *   tot doctor                check this machine is ready
  *   tot ideas                 copy-paste AI prompts that reliably wow
  *   tot feedback              send a note to ToT + your recent CLI activity  ← built (activity-log.mjs → feedback_submit MCP tool)
@@ -60,6 +61,7 @@ tot — Token of Trust developer CLI
   tot validate              lint your store before you submit
   tot dev                   run your store locally with save→reload
   tot submit                submit your store for preview
+  tot pr                    list / view / close your candidate PRs
   tot doctor                check this machine is ready
   tot ideas                 copy-paste AI prompts that reliably wow
   tot feedback "<msg>"      send feedback to Token of Trust (attaches recent activity)
@@ -151,6 +153,11 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  if (cmd === "pr") {
+    const { run } = await import("../src/commands/pr.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "app") {
     const { run } = await import("../src/commands/app/index.mjs");
     return run(rest, ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.4.0-rc.8",
+  "version": "1.4.0-rc.9",
   "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/candidate-state.mjs

@@ -0,0 +1,97 @@
+/**
+ * The "active candidate" pointer — which open candidate PR a plain `tot submit`
+ * updates, per forge repo.
+ *
+ * `tot submit` is idempotent on a STABLE changeId (`deriveChangeId`) so a re-submit
+ * updates the same PR by default — the common case needs NO state and writes
+ * nothing here (backward-compatible with the stateless original). This file only
+ * records a DIVERGENCE from that stable default:
+ *
+ *   - `tot submit --new` forks a fresh candidate and remembers it here, so the
+ *     NEXT plain `tot submit` keeps updating the NEW PR (like pushing more commits
+ *     to a `gh pr` branch), not the old one; and
+ *   - a terminal-roll (the active candidate was merged/closed) records the fresh
+ *     candidate it rolled to, so you're never wedged submitting to a dead PR.
+ *
+ * ONE file, `~/.tot/candidates.json`, a map keyed by `<mcpUrl>::<repo>` — a
+ * different MCP or repo is a different candidate namespace. Same atomic-write
+ * discipline as last-tenant.mjs (0600 in a 0700 dir, write-tmp-then-rename).
+ * Dependency-free (node:fs/os/path). `TOT_HOME` overrides home (tests).
+ */
+import {
+  readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+
+/** Absolute path to the active-candidate map for this machine. */
+export function defaultCandidateStatePath(env = process.env) {
+  const home = env.TOT_HOME || homedir();
+  return join(home, ".tot", "candidates.json");
+}
+
+/** Namespace key for one (MCP, repo) candidate pointer. */
+function stateKey(mcpUrl, repo) {
+  return `${mcpUrl}::${repo}`;
+}
+
+function readMap(filePath) {
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeMap(filePath, map) {
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+  const tmp = `${filePath}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(map, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmp, filePath);
+  chmodSync(filePath, 0o600);
+}
+
+/**
+ * The remembered active changeId for `(mcpUrl, repo)`, or null when there isn't
+ * one (absent/unreadable/malformed) — a miss means "use the stable default".
+ * Never throws.
+ */
+export function readActiveChangeId(filePath, { mcpUrl, repo }) {
+  const rec = readMap(filePath)[stateKey(mcpUrl, repo)];
+  return rec && typeof rec.changeId === "string" && rec.changeId ? rec.changeId : null;
+}
+
+/** Remember `changeId` as the active candidate for `(mcpUrl, repo)`, atomically. */
+export function writeActiveChangeId(filePath, { mcpUrl, repo, changeId }) {
+  const map = readMap(filePath);
+  map[stateKey(mcpUrl, repo)] = { changeId, updatedAt: Date.now() };
+  writeMap(filePath, map);
+}
+
+/** Forget the active candidate for `(mcpUrl, repo)` (e.g. after closing it). */
+export function clearActiveChangeId(filePath, { mcpUrl, repo }) {
+  const map = readMap(filePath);
+  const key = stateKey(mcpUrl, repo);
+  if (key in map) {
+    delete map[key];
+    writeMap(filePath, map);
+  }
+}
+
+/**
+ * A fresh candidate handle forked from a stable base — `<baseId>-<suffix>`, still
+ * matching candidate_open's `[a-z0-9._-]` handle grammar. The suffix defaults to
+ * 6 random hex chars (so two `--new` runs never collide); tests inject a fixed
+ * suffix. Pure given `suffix`.
+ */
+export function mintFreshChangeId(baseId, suffix = randomBytes(3).toString("hex")) {
+  const safe = String(suffix).toLowerCase().replace(/[^a-z0-9]/g, "").slice(0, 12) || "new";
+  return `${baseId}-${safe}`;
+}
+
+/** Whether a forge candidate state means "no open PR to update" (rolled past). */
+export function isTerminalCandidateState(state) {
+  return state === "merged" || state === "closed";
+}

package/src/commands/pr.mjs

@@ -0,0 +1,200 @@
+/**
+ * `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`).
+ */
+import { execFileSync } from "node:child_process";
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { fail } from "../errors.mjs";
+import { repoNameFromRemote } from "./submit.mjs";
+import {
+  defaultCandidateStatePath,
+  readActiveChangeId,
+  clearActiveChangeId,
+} from "../candidate-state.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+const SUBCOMMANDS = ["list", "view", "close"];
+
+const USAGE = `tot pr — see and manage your candidate PRs
+
+  tot pr [list]              list your open candidate PRs for this store
+  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)
+
+  A candidate PR is what \`tot submit\` opens for review. A re-submit updates your
+  open one by default; \`tot submit --new\` forks another. Use these to see and
+  manage them.`;
+
+/** Parse `tot pr` argv into { sub, target, reason, mcp, identity, help }. Pure. */
+export function parsePrArgs(argv) {
+  const a = { sub: null, target: null, reason: null, mcp: null, identity: 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 === "--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`. */
+function line(c) {
+  const pr = typeof c.prNumber === "number" ? `#${c.prNumber}` : "#—";
+  const url = c.url ? `  ${c.url}` : "";
+  return `  PR ${pr}  ${c.changeId}  [${c.state ?? "?"}]${url}`;
+}
+
+/** @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;
+  }
+  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)"),
+    );
+    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 statePath = defaultCandidateStatePath(env);
+  const scope = { mcpUrl: baseUrl, repo };
+  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) {
+        console.log(line(c) + (active && c.changeId === active ? "  ← 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 ?? "?"}`);
+      if (match.url) console.log(`  ${match.url}`);
+      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;
+  }
+}

package/src/commands/submit.mjs

@@ -46,12 +46,19 @@ import { validateTenant, ERROR } from "../validate.mjs";
 import { openBrowser } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
 import { fail } from "../errors.mjs";
+import {
+  defaultCandidateStatePath,
+  readActiveChangeId,
+  writeActiveChangeId,
+  mintFreshChangeId,
+  isTerminalCandidateState,
+} from "../candidate-state.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 const DEFAULT_REF = "preview";
 
 export function parseArgs(argv) {
-  const a = { mcp: null, identity: null, ref: DEFAULT_REF, skipValidate: false, noWait: false, watch: false, noOpen: false, message: null, summary: null, help: false };
+  const a = { mcp: null, identity: null, ref: DEFAULT_REF, skipValidate: false, noWait: false, watch: false, noOpen: false, message: null, summary: null, new: false, help: false };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--mcp") a.mcp = argv[++i];
@@ -63,6 +70,7 @@ export function parseArgs(argv) {
     else if (t === "--no-wait") a.noWait = true;
     else if (t === "--watch") a.watch = true;
     else if (t === "--no-open") a.noOpen = true;
+    else if (t === "--new") a.new = true;
     else if (t === "--help" || t === "-h") a.help = true;
   }
   return a;
@@ -71,6 +79,7 @@ export function parseArgs(argv) {
 const USAGE = `tot submit — submit your store for preview
 
   tot submit                    validate → push the preview ref → stream the result
+  tot submit --new              open a NEW candidate PR instead of updating your open one
   tot submit --watch            stay attached through reconcile + compliance + accept (long-poll)
   tot submit --skip-validate    push without the local lint (not recommended)
   tot submit --ref <name>       push ref (default: ${DEFAULT_REF})
@@ -80,6 +89,12 @@ const USAGE = `tot submit — submit your store for preview
   tot submit --no-open          don't open the preview URL in the browser on success
   tot submit --mcp <url>        MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
 
+  By default a re-submit UPDATES your open candidate PR (like pushing more commits
+  to a GitHub PR), rather than opening a new one each time. Use --new to fork a
+  fresh candidate PR; the next plain \`tot submit\` then updates THAT one. Manage your
+  open candidates with \`tot pr\` (list / view / close). If your candidate was already
+  merged or closed, a re-submit automatically opens a fresh one.
+
   If you omit -m, a summary is generated from git (commit subject + the diff vs
   what's live in preview) so the change record the approver reviews is never blank.`;
 
@@ -289,7 +304,7 @@ export async function run(argv, ctx) {
     console.error(
       fail(
         "`tot submit` runs from inside a tenant checkout",
-        "tot checkout <tenant> --clone <dir>   (then `cd` in, commit your work, and re-run)",
+        "tot clone <tenant> <dir>   (then `cd` in, commit your work, and re-run)",
       ),
     );
     return 2;
@@ -381,13 +396,40 @@ export async function run(argv, ctx) {
     // 2b. PR-backed candidate (g1b candidate_open, unit c1) — best-effort: a
     // failure here (older MCP, VC not configured, preview-access capability) is
     // reported and swallowed, never blocking the preview push that already landed.
-    await submitCandidate(client, {
-      repo: repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim()),
-      changeId: deriveChangeId(tenant, actorKeyFor(session)),
-      changeSummary,
-      patchEntries,
-      readBlob: (path) => execFileSync("git", ["-C", workspace, "show", `HEAD:${path}`], { stdio: ["ignore", "pipe", "pipe"] }),
-    });
+    //
+    // Which candidate this submit lands on (gh-pr-like):
+    //   --new           → fork a FRESH candidate and remember it as active;
+    //   otherwise       → the remembered active candidate (from a prior --new /
+    //                     roll), else the STABLE per-dev-per-tenant default.
+    // If the chosen candidate turns out to be merged/closed, roll to a fresh one
+    // so a re-submit is never wedged on a dead PR.
+    const repo = repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim());
+    const readBlob = (path) => execFileSync("git", ["-C", workspace, "show", `HEAD:${path}`], { stdio: ["ignore", "pipe", "pipe"] });
+    const statePath = defaultCandidateStatePath(env);
+    const stableId = deriveChangeId(tenant, actorKeyFor(session));
+    const active = repo ? readActiveChangeId(statePath, { mcpUrl: baseUrl, repo }) : null;
+    let changeId = args.new ? mintFreshChangeId(stableId) : (active || stableId);
+    // Persist when we diverge from the stable default (a --new fork, or a
+    // previously-remembered active pointer) so the next plain submit follows it.
+    let persist = args.new || (!!active && active !== stableId);
+
+    let candidate = await submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob });
+
+    if (candidate && isTerminalCandidateState(candidate.state)) {
+      const rolled = mintFreshChangeId(stableId);
+      console.log(`  ~ candidate ${changeId} is ${candidate.state} — opening a fresh candidate PR instead.`);
+      changeId = rolled;
+      persist = true;
+      candidate = await submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob });
+    }
+
+    // Remember the active candidate only on a real, non-terminal open (best-effort;
+    // never let a state-write failure break the submit).
+    if (persist && repo && candidate && !isTerminalCandidateState(candidate.state)) {
+      try {
+        writeActiveChangeId(statePath, { mcpUrl: baseUrl, repo, changeId });
+      } catch { /* best-effort local hint — a miss just re-derives the stable id */ }
+    }
 
     let status;
     if (args.noWait) {