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

package/bin/tot.mjs

@@ -15,6 +15,8 @@
  *   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         ← 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
@@ -63,6 +65,10 @@ tot — Token of Trust developer CLI
   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 (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.11",
+  "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/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;
+  }
+}