@tokenoftrust/cli 1.4.0-rc.10 → 1.4.0-rc.12

package/README.md

@@ -9,7 +9,8 @@ tot clone                    # list the stores you can build on
 tot clone <tenant> my-store  # mirrors `git clone`; dir defaults to <tenant>
 cd my-store
 tot dev                      # run it locally with save→reload — no Docker needed
-tot submit                   # (coming) submit it for preview
+tot preview                  # bundle your edits into a compliance-reviewed preview
+tot ship                     # promote a reconciled preview live (diff + one confirm)
 ```
 
 **Prerequisites: Node.js and an invite. Nothing else.** `tot dev` downloads the
@@ -23,9 +24,11 @@ be fetched.)
 | Command | Status | What it does |
 | --- | --- | --- |
 | `tot clone [<tenant>] [<dir>]` | **built** | Clone a store you're entitled to build on (mirrors `git clone`), with an authenticated remote configured. Dir defaults to `<tenant>`. No arg → list your stores. |
-| `tot validate` | next | Lint your store before you submit. |
+| `tot validate` | next | Lint your store before you preview. |
 | `tot dev` | **built** | Run your store locally with save→reload — NATIVELY (no Docker; falls back to it with `--docker` or automatically if the native artifact isn't available). |
-| `tot submit` | next | Submit your store for preview (pushes the preview ref, reports the reconcile/compliance verdict + preview URL). |
+| `tot preview` | **built** | Bundle your edits into a compliance-reviewed preview (validates, auto-commits the known content trees, pushes the preview ref, opens/updates a candidate PR, reports the reconcile/compliance verdict + preview URL). `tot submit` / `tot deploy` still work as teaching aliases for this same flow. |
+| `tot ship` | **built** | Promote a reconciled preview live: always shows a diff-vs-live and asks for one `[y/N]` confirm (no `--yes`, refuses outside a terminal); records an approval request if you're not authorised to ship yourself. |
+| `tot pr [list\|view\|close]` | **built** | See and manage the candidate PRs `tot preview` opens (`gh pr`-shaped). |
 | `tot doctor` | built | Check this machine is ready and show which context `tot` detected. |
 
 ## Context-aware
@@ -42,7 +45,7 @@ The same `tot` does the right thing wherever you run it (walks up like `git`):
 
 `tot` talks to the Token of Trust MCP (default `https://mcp.tokenoftrust.com`, override with `--mcp` or `MCP_BASE_URL`). It is **single-plane**: the only identity is **you**, signed in against the MCP over OAuth.
 
-- Run `tot login` once — it opens your browser (or falls back to a device code on a headless box), you sign in as yourself, and the session is cached at `~/.tot/credentials.json` and refreshed silently. Every later command (`tot clone`, `tot start`, `tot submit`, …) runs as you, with no re-auth. Entitlement is derived server-side from your ToT memberships.
+- Run `tot login` once — it opens your browser (or falls back to a device code on a headless box), you sign in as yourself, and the session is cached at `~/.tot/credentials.json` and refreshed silently. Every later command (`tot clone`, `tot start`, `tot preview`, `tot ship`, …) runs as you, with no re-auth. Entitlement is derived server-side from your ToT memberships.
 - Not signed in? On a terminal, `tot start` / `tot clone` **offer to sign you in right there** and continue in-flow — no "run `tot login`, then re-run".
 - The old operator env-triple (`TOT_API_KEY` / `TOT_SECRET_KEY` / `TOT_APP_DOMAIN`) **no longer signs the CLI in** — tot-mcp went OAuth-first on 2026-07-23. If those vars are set, `tot` prints a one-line advisory and uses your `tot login` session anyway; it never reads them for auth.
 

package/bin/tot.mjs

@@ -14,7 +14,9 @@
  *   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 preview               push your store to a reviewable preview   ← built (validate + push preview ref; MCP preview_status read-back). `submit`/`deploy` are teaching aliases.
- *   tot ship                  promote a reconciled preview live         ← stub (registered; real ship logic lands in a later unit)
+ *   tot ship                  promote a reconciled preview live         ← built (diff-vs-live + y/N confirm → change_accept; refuses non-TTY / unreconciled)
+ *   tot accept / tot merge    merge a PR into main (operator verb)      ← built (plan + y/N confirm → the SAME change_accept ship uses; no deploy; refuses non-TTY without --yes)
+ *   tot rollback [<version>]  instant re-point to a prior live version  ← built (u3 promotion_status/promotion_rollback seam; diff + y/N confirm; refuses non-TTY / ineligible)
  *   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
@@ -62,7 +64,11 @@ tot — Token of Trust developer CLI
   tot validate              lint your store before you submit
   tot dev                   run your store locally with save→reload
   tot preview               push your store to a reviewable preview
-  tot ship                  promote a reconciled preview live (coming soon)
+  tot ship                  promote a reconciled preview live (diff → confirm → ship)
+  tot accept / tot merge    merge a PR into main — operator verb, no deploy (plan → confirm → merge)
+  tot rollback [<version>]  instant re-point to a prior live version (list → confirm → rollback)
+  tot retire                evict a candidate PR's preview to reclaim space — operator verb, rebuildable (plan → confirm → evict)
+  tot go-live               cut the apex domain over to the storefront (readiness → confirm → cutover)
   tot pr                    list / view / close your candidate PRs
   tot doctor                check this machine is ready
   tot ideas                 copy-paste AI prompts that reliably wow
@@ -168,6 +174,33 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  // `accept` merges a PR into main (no deploy) — a DISTINCT operator verb from
+  // `ship`, backed by the SAME change_accept pipeline (see accept.mjs's header).
+  // `merge` is a first-class alias, not a teaching nudge: both dispatch straight
+  // to the same command.
+  if (cmd === "accept" || cmd === "merge") {
+    const { run } = await import("../src/commands/accept.mjs");
+    return run(rest, ctx);
+  }
+
+  if (cmd === "rollback") {
+    const { run } = await import("../src/commands/rollback.mjs");
+    return run(rest, ctx);
+  }
+
+  // `retire` evicts a candidate PR's hosted preview to reclaim space (unit U7) —
+  // a DISTINCT operator verb from `accept`/reject: retire touches no change
+  // lifecycle and is reversible-by-rebuild (`tot preview build`). See retire.mjs.
+  if (cmd === "retire") {
+    const { run } = await import("../src/commands/retire.mjs");
+    return run(rest, ctx);
+  }
+
+  if (cmd === "go-live") {
+    const { run } = await import("../src/commands/go-live.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "pr") {
     const { run } = await import("../src/commands/pr.mjs");
     return run(rest, ctx);

package/package.json

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

@@ -13,8 +13,14 @@
  *   - 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
+ * ONE file, `~/.tot/candidates.json`, a map keyed by `<mcpUrl>::<repo>` on the
+ * DEFAULT branch and `<mcpUrl>::<repo>::<branch>` on any other (u4 — branch-bound
+ * candidates): a different MCP, repo, OR non-default git branch is a different
+ * candidate namespace, so a feature branch gets its OWN candidate PR instead of
+ * fighting main's over the same handle. The default branch deliberately keeps the
+ * OLD branch-less key so existing devs' state is byte-identical (zero migration),
+ * and a branch-scoped read that misses FALLS BACK to that old key so state written
+ * before the rekey (or by the default branch) is never orphaned. 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).
  */
@@ -31,11 +37,38 @@ export function defaultCandidateStatePath(env = process.env) {
   return join(home, ".tot", "candidates.json");
 }
 
-/** Namespace key for one (MCP, repo) candidate pointer. */
-function stateKey(mcpUrl, repo) {
+/**
+ * Branch names that are treated as the repo's DEFAULT — their candidates keep the
+ * OLD branch-less key (zero migration). A null/empty/detached ("HEAD") branch is
+ * treated as default too, so an environment where the branch can't be resolved
+ * degrades to exactly today's behavior rather than minting a spurious namespace.
+ */
+export const DEFAULT_BRANCHES = new Set(["main", "master"]);
+
+/** Whether `branch` should use the OLD branch-less candidate key. Pure. */
+export function isDefaultBranch(branch) {
+  return !branch || branch === "HEAD" || DEFAULT_BRANCHES.has(branch);
+}
+
+/** The legacy (branch-less) namespace key — today's exact `<mcpUrl>::<repo>`. */
+function legacyStateKey(mcpUrl, repo) {
   return `${mcpUrl}::${repo}`;
 }
 
+/**
+ * Namespace key for one (MCP, repo, branch) candidate pointer. The DEFAULT branch
+ * keeps the legacy `<mcpUrl>::<repo>` key byte-for-byte (zero migration); any other
+ * branch gets its own `<mcpUrl>::<repo>::<branch>` namespace. Pure.
+ */
+function stateKey(mcpUrl, repo, branch) {
+  return isDefaultBranch(branch) ? legacyStateKey(mcpUrl, repo) : `${mcpUrl}::${repo}::${branch}`;
+}
+
+/** Extract a usable changeId from a stored record, or null. Pure. */
+function recordChangeId(rec) {
+  return rec && typeof rec.changeId === "string" && rec.changeId ? rec.changeId : null;
+}
+
 function readMap(filePath) {
   try {
     const parsed = JSON.parse(readFileSync(filePath, "utf8"));
@@ -54,26 +87,33 @@ function writeMap(filePath, map) {
 }
 
 /**
- * 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.
+ * The remembered active changeId for `(mcpUrl, repo, branch)`, or null when there
+ * isn't one (absent/unreadable/malformed) — a miss means "use the stable default".
+ * On a non-default branch whose branch-scoped key misses, FALLS BACK to the legacy
+ * branch-less key so state written before the rekey (or by the default branch)
+ * isn't orphaned. 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;
+export function readActiveChangeId(filePath, { mcpUrl, repo, branch }) {
+  const map = readMap(filePath);
+  const primary = recordChangeId(map[stateKey(mcpUrl, repo, branch)]);
+  if (primary) return primary;
+  // Legacy fallback: a branch-scoped miss reads the old branch-less key (a no-op
+  // when we're already on the default branch, which IS the legacy key).
+  if (!isDefaultBranch(branch)) return recordChangeId(map[legacyStateKey(mcpUrl, repo)]);
+  return null;
 }
 
-/** Remember `changeId` as the active candidate for `(mcpUrl, repo)`, atomically. */
-export function writeActiveChangeId(filePath, { mcpUrl, repo, changeId }) {
+/** Remember `changeId` as the active candidate for `(mcpUrl, repo, branch)`, atomically. */
+export function writeActiveChangeId(filePath, { mcpUrl, repo, branch, changeId }) {
   const map = readMap(filePath);
-  map[stateKey(mcpUrl, repo)] = { changeId, updatedAt: Date.now() };
+  map[stateKey(mcpUrl, repo, branch)] = { 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 }) {
+/** Forget the active candidate for `(mcpUrl, repo, branch)` (e.g. after closing it). */
+export function clearActiveChangeId(filePath, { mcpUrl, repo, branch }) {
   const map = readMap(filePath);
-  const key = stateKey(mcpUrl, repo);
+  const key = stateKey(mcpUrl, repo, branch);
   if (key in map) {
     delete map[key];
     writeMap(filePath, map);

package/src/commands/accept.mjs

@@ -0,0 +1,247 @@
+/**
+ * `tot accept --tenant <t> --pr <N>` (alias: `tot merge`) — OPERATOR verb: MERGE
+ * a PR into main. DISTINCT from `tot ship`: per board decision
+ * `operator-verb-and-hosting-model`, accepting a PR merges it into main; main
+ * becomes default-hosted on preview + live only after the NEXT `tot ship` /
+ * deploy — accept itself does not deploy. (`tot ship` run by the developer in
+ * their own checkout stays accept-THEN-deploy in one gated step — see
+ * `ship-context-dependent-semantics` in `../plan.mjs`; this verb is the
+ * explicit, deploy-free half of that, for an operator who just wants the merge.)
+ *
+ * TRANSPORT — reuses the EXISTING accept pipeline `tot ship` already drives over
+ * MCP (merge → reconcile → promote → verify): the SAME `change_accept` tool,
+ * the SAME session/auth pattern (`createMcpClient` + `establishSession`), and
+ * the SAME result normaliser/poll (`normalizeChangeResult` / `pollChangeShipped`,
+ * imported straight from `./ship.mjs` rather than re-implemented). No new
+ * transport, no new wire contract.
+ *
+ * TARGET RESOLUTION — `--pr N --tenant t` names the PR, but there is no
+ * PR→change-record lookup on the wire, and even if there were, this CLI's own
+ * identity may not have cross-tenant forge read access to resolve one for a PR
+ * that isn't the developer's own (`resolveChangeRecordId` in ship.mjs only works
+ * because it reads the DEVELOPER'S OWN local git HEAD — an operator targeting an
+ * arbitrary PR has no local checkout of it to read). So this verb requires the
+ * change-RECORD id explicitly via `--change-id` (the `chg_<uuid>` a prior
+ * change_open/change_ready minted — e.g. from the PR author's own `tot ship`
+ * review step, or the `/admin` confirm flow) and an optional `--head-sha`
+ * (passed through as `expectedHeadSha` — an optimistic-concurrency guard so
+ * accept refuses if the PR moved since the operator looked at it).
+ *
+ *   // u9: auto-resolve PR→changeId via forge PR-read (candidate_status), so an
+ *   // operator who DOES have forge access can omit --change-id and pass --pr
+ *   // alone. Not implemented here — deliberately out of scope for this unit.
+ *
+ * HUMAN GATE — merging to main is a decision a human makes at the keyboard, so
+ * this verb ALWAYS states the EXACT plan (shared `planForAction`, unit U10:
+ * which PR, which tenant, "merge into main", plus a note that live/preview
+ * don't move until the next ship/deploy) and requires an explicit confirm.
+ * `--yes` is still an explicit affirmative supplied on the command line — there
+ * is deliberately NO default-yes, and a non-TTY without `--yes` is refused
+ * rather than silently proceeding (mirrors `tot ship`'s non-TTY refusal).
+ *
+ * Dependency-free (the MCP client + the shared plan module).
+ */
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { fail } from "../errors.mjs";
+import { planForAction, printPlanAndConfirm } from "../plan.mjs";
+import { normalizeChangeResult, pollChangeShipped } from "./ship.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+const USAGE = `tot accept — merge a PR into main (alias: tot merge)
+
+  tot accept --tenant <t> --pr <N> --change-id <chg_...>
+  tot merge   --tenant <t> --pr <N> --change-id <chg_...>   (same command)
+
+  Merges the given PR into main via the existing accept pipeline (merge →
+  reconcile → promote → verify) — the SAME gate \`tot ship\` uses. Distinct
+  from \`tot ship\`: accepting does NOT deploy. Main becomes default-hosted on
+  preview + live only after the next \`tot ship\` / deploy.
+
+  Merge-to-main is a human decision: this ALWAYS prints the exact plan and asks
+  for an explicit confirm. There is no default-yes; a non-TTY without --yes is
+  refused rather than silently proceeding.
+
+Options:
+  --tenant <appDomain>   Target tenant (e.g. tokenoftrust.com). Defaults to the
+                         current checkout's tenant when run inside one.
+  --pr <N>               PR number to merge (for the plan text / labeling).
+  --change-id <id>       The change-record id (chg_...) to accept. REQUIRED —
+                         there is no PR→changeId auto-resolution yet (u9); pass
+                         the id a prior change_open/change_ready minted (e.g.
+                         from the author's own \`tot ship\` review step, or the
+                         /admin confirm flow).
+  --head-sha <sha>       Optional expected PR head sha (expectedHeadSha) — an
+                         optimistic-concurrency guard against a PR that moved.
+  --mcp <url>            MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+  --identity <id>        sign in as a specific identity for this accept
+  --yes, -y              Skip the interactive confirm (still an explicit human
+                         affirmative — there is no default-yes).
+  --help, -h             Show this help.`;
+
+/** Parse `tot accept` / `tot merge` argv. Pure — unit-testable. */
+export function parseAcceptArgs(argv) {
+  const a = {
+    tenant: null,
+    pr: null,
+    changeId: null,
+    headSha: null,
+    mcp: null,
+    identity: null,
+    yes: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--pr") a.pr = argv[++i];
+    else if (t === "--change-id") a.changeId = argv[++i];
+    else if (t === "--head-sha" || t === "--head") a.headSha = argv[++i];
+    else if (t === "--mcp") a.mcp = argv[++i];
+    else if (t === "--identity") a.identity = argv[++i];
+    else if (t === "--yes" || t === "-y") a.yes = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+/** Report the accept result in house style. Pure given its inputs. */
+function reportAccepted(accept, status, { tenant, pr, changeId }) {
+  const label = pr != null ? `PR #${pr}` : changeId;
+  const merged = Boolean(status?.shipped || accept?.shipped);
+  if (merged) {
+    console.log(`\n  ✓ merged ${label} into main for ${tenant}.`);
+    console.log(
+      "  → next: `tot ship` (or an operator `tot ship`/deploy) to promote main to preview + live.",
+    );
+    return 0;
+  }
+  // The accept committed but the terminal state hasn't been observed yet (the
+  // pipeline may still be landing reconcile/promote/verify) — report honestly.
+  console.log(`\n  ~ accept committed for ${label} on ${tenant}; the merge is landing now.`);
+  console.log("  → next: re-check shortly, then `tot ship` / deploy to go live.");
+  return 0;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseAcceptArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const tenant = (args.tenant || ctx?.tenant || "").trim();
+  if (!tenant) {
+    console.error(
+      fail(
+        "no target tenant.",
+        "pass --tenant <appDomain> (e.g. --tenant tokenoftrust.com), or run inside a store checkout.",
+      ),
+    );
+    return 2;
+  }
+
+  const prRaw = args.pr;
+  const pr = prRaw != null && `${prRaw}`.trim() && Number.isFinite(Number(prRaw)) ? Number(prRaw) : null;
+  if (pr == null && !args.changeId) {
+    console.error(
+      fail("no PR or change to accept.", "pass --pr <N> (the PR number to merge) and --change-id <chg_...>."),
+    );
+    return 2;
+  }
+
+  const changeId = (args.changeId || "").trim();
+  if (!changeId) {
+    // u9: auto-resolve PR→changeId via forge PR-read (candidate_status) — until
+    // then an operator targeting a specific PR must supply the change-record id
+    // directly (there's no cross-tenant forge lookup this CLI can do for a PR
+    // that isn't the caller's own checkout).
+    console.error(
+      fail(
+        `no --change-id for PR #${pr} — can't auto-resolve it yet.`,
+        "pass --change-id <chg_...> (the change record a prior review step opened/readied), " +
+          "or run `tot ship` from the PR author's own checkout instead.",
+      ),
+    );
+    return 2;
+  }
+
+  const headSha = (args.headSha || "").trim() || null;
+
+  // Self-declaring: state the EXACT plan before acting (the shared plan module,
+  // unit U10) plus the accept-specific caveat that main doesn't go live/preview
+  // until the next ship/deploy.
+  const planLines = [
+    ...planForAction({ action: "accept", tenant, pr, changeId, headSha }),
+    "  note:      main becomes default-hosted on preview + live only after the next `tot ship` / deploy.",
+  ];
+  const { confirmed, reason } = await printPlanAndConfirm(planLines, {
+    yes: args.yes,
+    question: "Merge this into main?",
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error(
+        fail(
+          "refusing to merge without confirmation on a non-TTY.",
+          "re-run with --yes (an explicit human affirmative), or from an interactive terminal.",
+        ),
+      );
+      return 2;
+    }
+    console.log("Aborted — nothing was merged.");
+    return 1;
+  }
+
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createMcpClient(baseUrl);
+  try {
+    await establishSession(client, { env, prefer: args.identity || undefined });
+    // Bind the active tenant so change_accept/change_status read the right scope.
+    await client.callTool("client_switch", { tenant });
+
+    let accept;
+    try {
+      accept = normalizeChangeResult(
+        await client.callTool("change_accept", {
+          id: changeId,
+          tenant,
+          dryRun: false,
+          ...(headSha ? { expectedHeadSha: headSha } : {}),
+          // Stable per (changeId, head): a re-run after a blip returns the
+          // original accept instead of double-merging.
+          idempotencyKey: `accept-${changeId}-${headSha || pr || "pr"}`,
+        }),
+      );
+    } catch (e) {
+      console.error(
+        fail(
+          `the accept pipeline refused to merge this change: ${String(e?.message || e)}`,
+          "check its review/reconcile status, then re-run `tot accept`",
+        ),
+      );
+      return 1;
+    }
+
+    const status = await pollChangeShipped(client, { id: changeId, tenant });
+    return reportAccepted(accept, status, { tenant, pr, changeId });
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      console.error(fail("sign in to accept a change", e.hint || "run `tot login`, then re-run `tot accept`"));
+      return 1;
+    }
+    console.error(
+      fail(
+        `couldn't reach the accept service: ${String(e?.message || e)}`,
+        "check your connection and that you're signed in, then re-run",
+      ),
+    );
+    return 1;
+  }
+}