@tokenoftrust/cli 1.4.0-rc.9 → 1.4.1

package/src/commands/doctor.mjs

@@ -187,7 +187,8 @@ export async function run(argv, ctx) {
   }
   console.log(
     failed === 0
-      ? "\n✔ Ready. Try: tot start   (checks out your store and runs it), or tot clone\n"
+      ? "\n✔ Ready. Try: tot start   (checks out your store and runs it), or tot clone." +
+        "\n  The loop: tot dev → tot preview → tot ship.\n"
       : args.fix
         ? `\n✖ ${failed} check(s) still failing — see the exact next command(s) above, then re-run \`tot doctor\`.\n`
         : `\n✖ ${failed} check(s) failed — try \`tot doctor --fix\`, or fix the above, then re-run \`tot doctor\`.\n`,

package/src/commands/git-credential.mjs

@@ -0,0 +1,180 @@
+/**
+ * `tot git-credential` — git's own credential-helper protocol (see `git help
+ * gitcredentials`), implemented over the developer's cached `tot login`
+ * session (unit u10, workstream tot-merge-conflict-resolution-ux). `tot
+ * clone` configures a fresh checkout's `credential.helper` to run this (see
+ * ../git-credential.mjs's CREDENTIAL_HELPER), so `git fetch`/`git push`/`git
+ * pull` — run DIRECTLY by the developer, not just through `tot preview` —
+ * transparently mint a fresh forge token instead of ever needing one
+ * persisted in `.git/config`. This is the fix for the "the panel-prescribed
+ * `git fetch origin` fails even after `tot login`" dead-end: `tot login`
+ * only ever refreshed the CLI's OWN MCP session, never the token baked into
+ * a checkout's remote URL at clone time.
+ *
+ * git invokes this with ONE positional arg (`get`/`store`/`erase`) and the
+ * request on stdin (key=value lines, blank-line/EOF terminated). Only `get`
+ * does real work — this CLI never persists a forge credential of its own
+ * beyond the short-lived cache in ../git-credential.mjs, so `store`/`erase`
+ * are no-ops (git calls them after a successful/failed auth respectively; we
+ * just drain stdin and exit 0, the correct behavior for a stateless helper).
+ *
+ * FAILS SILENT, NEVER LOUD: `get` prints NOTHING and exits non-zero on any
+ * problem (not signed in, MCP unreachable, cwd isn't a recognizable tenant
+ * checkout) — git then falls through to its next configured helper or its
+ * own prompt, exactly as if this helper weren't configured. A stack trace or
+ * a malformed credential line here would otherwise corrupt EVERY git
+ * operation in the checkout. It also NEVER triggers an interactive sign-in —
+ * this runs as a non-interactive subprocess of `git`, so a missing session
+ * fails through rather than trying to open a browser mid-`git fetch`.
+ *
+ * Dependency-free (global fetch + `git`, via the same MCP client + auth
+ * module every other command uses).
+ */
+import { readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession } from "../auth.mjs";
+import { checkoutTenant } from "./clone.mjs";
+import { detectContext } from "../context.mjs";
+import { repoNameFromRemote, tagFromRepoName } from "./submit.mjs";
+import {
+  parseCredentialInput, formatCredentialOutput, splitAuthedRemote,
+  credentialCachePath, readCachedCredential, writeCachedCredential,
+} from "../git-credential.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+/** Does `remoteUrl`'s host equal `host` (case-insensitive)? An unparseable or
+ *  missing remote URL never matches — fail closed. Exported for testing. */
+export function hostMatches(remoteUrl, host) {
+  if (!remoteUrl || !host) return false;
+  try {
+    // scp-like remotes (git@host:owner/repo.git) have no scheme — synthesize one so URL can parse the host.
+    const normalized = /^[^/]+@[^/:]+:/.test(remoteUrl) ? `ssh://${remoteUrl.replace(":", "/")}` : remoteUrl;
+    return new URL(normalized).host.toLowerCase() === host.toLowerCase();
+  } catch {
+    return false;
+  }
+}
+
+/** Read the credential request git writes to stdin — blocking is correct
+ *  here: git writes the request then closes its end, so this returns as
+ *  soon as it's fully sent. Never blocks on an interactive terminal (git
+ *  NEVER attaches a TTY to a credential helper's stdin — only a human
+ *  poking at this command directly by hand would) and never throws (an
+ *  unreadable/absent stdin is treated as an empty request). Exported so a
+ *  test can inject a canned request instead of touching real fd 0. */
+export function readStdin() {
+  if (process.stdin.isTTY) return "";
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Mint (or reuse a cached) forge credential for the tenant the CURRENT
+ * directory checks out — the same `tenant_checkout` MCP call `tot clone`
+ * itself uses, so the credential is exactly as push-capable. Returns null on
+ * ANY failure (wrong dir, not signed in, MCP unreachable) rather than
+ * throwing — `get` treats null as "say nothing, exit non-zero".
+ *
+ * `createClient`/`establish`/`checkout` are injected (default to the real MCP
+ * client + auth + clone.mjs's checkoutTenant) purely so this is testable
+ * without a live MCP — same DI shape as chooseChangeId's injected `mint` /
+ * resolveDeveloperSession's injected `fetchImpl` elsewhere in this CLI.
+ * SCOPED TO THE CHECKOUT'S OWN REMOTE: `expectedHost` (git's requested host,
+ * from the credential-helper request) is checked against the host of this
+ * checkout's `origin` remote before a credential is ever minted or returned
+ * — a `get` for any OTHER host returns null (silent fail), never handing the
+ * tenant's forge token to a host this checkout doesn't itself push to. This
+ * matters because `credential.helper` is invoked per-URL by git, and a
+ * globally-scoped helper (or a checkout with a submodule / unrelated remote)
+ * must not become a way to exfiltrate the token to an arbitrary host.
+ * @param {{
+ *   env?: NodeJS.ProcessEnv, cwd?: string, expectedHost?: string,
+ *   createClient?: typeof createMcpClient,
+ *   establish?: typeof establishSession,
+ *   checkout?: typeof checkoutTenant,
+ * }} [opts]
+ * @returns {Promise<{username:string,password:string}|null>}
+ */
+export async function mintOrCacheCredential({
+  env = process.env, cwd = process.cwd(), expectedHost = null,
+  createClient = createMcpClient, establish = establishSession, checkout = checkoutTenant,
+} = {}) {
+  const ctx = detectContext(cwd);
+  if (ctx.mode !== "checkout" || !ctx.tenant) return null;
+
+  const git = (cargs) =>
+    execFileSync("git", ["-C", ctx.workspacePath, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+  let originUrl = null;
+  let repoName = null;
+  try {
+    originUrl = git(["remote", "get-url", "origin"]).trim();
+    repoName = repoNameFromRemote(originUrl);
+  } catch {
+    /* fall through — tagFromRepoName degrades to "main" on a null repo name */
+  }
+  if (expectedHost && !hostMatches(originUrl, expectedHost)) return null;
+  const tag = tagFromRepoName(repoName, ctx.tenant);
+
+  const cachePath = credentialCachePath(ctx.tenant, tag, env);
+  const cached = readCachedCredential(cachePath);
+  if (cached) return { username: cached.username, password: cached.password };
+
+  const baseUrl = env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createClient(baseUrl);
+  try {
+    await establish(client, { env });
+  } catch {
+    return null; // not signed in (or session unrefreshable) — nothing this helper can do
+  }
+  try {
+    const res = await checkout(client, { tenant: ctx.tenant, tag, cloneDir: null });
+    const cred = splitAuthedRemote(res.gitRemote || "");
+    if (!cred) return null;
+    const fresh = { username: cred.username, password: cred.token };
+    writeCachedCredential(cachePath, fresh);
+    return fresh;
+  } catch {
+    return null; // MCP unreachable / tenant_checkout refused — say nothing, exit non-zero
+  }
+}
+
+const USAGE = `tot git-credential — git credential-helper protocol over your \`tot login\` session
+
+  Configured automatically by \`tot clone\` (credential.helper = !tot git-credential)
+  in every checkout it creates — you should never need to run this by hand.
+  See \`git help gitcredentials\` for the protocol this implements.`;
+
+/**
+ * @param {string[]} argv  argv[0] is git's operation: get|store|erase
+ * @param {any} _ctx  unused — this command derives its OWN context from cwd
+ *   (mintOrCacheCredential), since git invokes it with the credentialed
+ *   repo's directory as cwd, which may differ from wherever `tot` itself
+ *   was dispatched from.
+ * @param {{ env?: NodeJS.ProcessEnv, cwd?: string, readStdin?: typeof readStdin }
+ *   & Parameters<typeof mintOrCacheCredential>[0]} [opts]
+ */
+export async function run(argv, _ctx, opts = {}) {
+  const { env = process.env, readStdin: read = readStdin } = opts;
+  const op = argv[0];
+  if (!op || op === "--help" || op === "-h") {
+    console.log(USAGE);
+    return op ? 0 : 2;
+  }
+  // git always writes a request to stdin, even for store/erase — drain it either way
+  // so the subprocess exits cleanly instead of leaving git's write blocked on a full pipe.
+  const request = parseCredentialInput(read());
+
+  if (op !== "get") return 0; // store/erase: stateless, nothing to persist or drop.
+
+  const cred = await mintOrCacheCredential({ ...opts, expectedHost: request.host });
+  if (!cred) return 1; // silent — let git fall through to its next helper / its own prompt.
+  process.stdout.write(formatCredentialOutput({
+    protocol: request.protocol, host: request.host, username: cred.username, password: cred.password,
+  }));
+  return 0;
+}

package/src/commands/go-live.mjs

@@ -0,0 +1,482 @@
+/**
+ * `tot go-live` — cut the apex domain over to the storefront (unit u9). The CLI
+ * counterpart to the admin Publish tab's Domain "Connect" button: it drives the
+ * SAME go-live CI/dispatch the button does (the storefront `/api/domain/dispatch`
+ * → `www-domain` repository_dispatch → `cutover-dns.mjs`), gated by the SAME
+ * server-authoritative readiness gate the admin display reads
+ * (`GET /api/domain/readiness`, unit u9). This command CONSUMES those seams — it
+ * does NOT reimplement the DNS cutover, the readiness policy, or the revert.
+ *
+ *   tot go-live               show apex readiness, then (if ready) connect the apex
+ *   tot go-live --rehearsal   dispatch a DRY-RUN cutover (never moves DNS state)
+ *   tot go-live --rollback    restore the captured prior DNS records (the one-line revert)
+ *
+ * The contract, deliberately strict — this is the apex DNS cutover of the live
+ * site (mirrors `tot ship` / `tot rollback`):
+ *
+ *   1. GET the readiness verdict and ALWAYS print the itemization (owner
+ *      capability, dual-run parity, target health, evidence freshness, captured
+ *      revert). Fail-closed: a CONNECT is refused unless the server reports
+ *      `ready:true` — the CLI never recomputes readiness, it reads the same gate
+ *      the cutover is governed by, so they cannot diverge.
+ *   2. Owner-only: the server resolves owner capability (u10); a non-owner is
+ *      DENIED with the itemized reason. The CLI does not assert ownership itself.
+ *   3. ALWAYS require ONE explicit [y/N] confirm (default NO). There is NO
+ *      `--yes`/`--force`; in a NON-TTY (CI, piped) it REFUSES rather than
+ *      auto-confirm — nothing cuts over without a human at the keyboard.
+ *   4. On confirm, POST the dispatch and report the REAL terminal state — a
+ *      dispatched run is IN FLIGHT until the CI HMAC callback lands; the CLI polls
+ *      `/api/domain/status` and never claims "cut over" before the callback
+ *      confirms it. A tested one-line revert (`tot go-live --rollback`) is always
+ *      surfaced.
+ *
+ * Dependency-free (global fetch); pure helpers are exported and unit-tested with a
+ * mock HTTP client, no network, no TTY, and NO live DNS.
+ */
+import { fail } from "../errors.mjs";
+import { isInteractive, promptYesNo } from "../prompt.mjs";
+import { startProgress } from "../progress.mjs";
+import { openBrowser } from "../open.mjs";
+
+const USAGE = `tot go-live — cut the apex domain over to the storefront
+
+  tot go-live                 show apex readiness, then (if ready) connect the apex
+  tot go-live --rehearsal     dispatch a DRY-RUN cutover (never moves DNS state)
+  tot go-live --rollback      restore the captured prior DNS records (the revert)
+  tot go-live --url <base>    storefront base URL (default: env TOT_STOREFRONT_URL / https://<owner>)
+  tot go-live --owner <domain> owner/appDomain to act on (default: env TOT_STOREFRONT_OWNER / checkout tenant)
+  tot go-live --no-open       don't open the store in your browser afterward
+
+  go-live drives the SAME apex cutover the admin Domain button does, gated by the
+  same server readiness gate. It ALWAYS shows you the readiness itemization and
+  asks for a single y/N confirmation first; a CONNECT is refused unless the server
+  reports ready. There is no --yes/--force, and it refuses to run without an
+  interactive terminal. Reversible: \`tot go-live --rollback\`.`;
+
+/** Parse `tot go-live` argv. Pure. Deliberately NO --yes/--force (see the header). */
+export function parseGoLiveArgs(argv) {
+  const a = {
+    action: "connect",
+    rehearsal: false,
+    url: null,
+    owner: null,
+    identity: null,
+    noOpen: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--rehearsal" || t === "--dry-run") a.rehearsal = true;
+    else if (t === "--rollback") a.action = "rollback";
+    else if (t === "--connect") a.action = "connect";
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--owner") a.owner = argv[++i];
+    else if (t === "--identity") a.identity = argv[++i];
+    else if (t === "--no-open") a.noOpen = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+    else if (t === "rollback") a.action = "rollback";
+    else if (t === "connect") a.action = "connect";
+  }
+  return a;
+}
+
+// ─── Response normalisation (defensive — one server, but shapes may vary) ─────────
+
+/**
+ * Normalise a `GET /api/domain/readiness` response to what the gate needs:
+ * whether the acting principal is owner-capable, the readiness verdict + its
+ * itemized checks, and the current domain platform. TRI-STATE-safe: `ready`/
+ * `ownerCapable` are only true when the server clearly says so, so an unrecognised
+ * shape fails CLOSED (we never connect on ambiguity). Pure — unit-tested.
+ * @param {any} r
+ */
+export function normalizeReadiness(r) {
+  const o = r && typeof r === "object" ? r : {};
+  const rd = o.readiness && typeof o.readiness === "object" ? o.readiness : {};
+  const checks = Array.isArray(rd.checks)
+    ? rd.checks
+        .filter((c) => c && typeof c === "object")
+        .map((c) => ({
+          id: typeof c.id === "string" ? c.id : "?",
+          label: typeof c.label === "string" ? c.label : c.id || "?",
+          ok: c.ok === true,
+          detail: typeof c.detail === "string" ? c.detail : "",
+        }))
+    : [];
+  return {
+    ownerCapable: o.ownerCapable === true,
+    ready: rd.ready === true,
+    checks,
+    blockedReasons: Array.isArray(rd.blockedReasons)
+      ? rd.blockedReasons.filter((s) => typeof s === "string")
+      : checks.filter((c) => !c.ok).map((c) => c.detail),
+    appDomain: typeof o.appDomain === "string" ? o.appDomain : null,
+    domainState: rd && o.domain && typeof o.domain === "object" ? o.domain : null,
+  };
+}
+
+/**
+ * Normalise a `POST /api/domain/dispatch` response to { dispatched, runId, error }.
+ * `dispatched` is true only when the server confirms it fired the CI dispatch. Pure.
+ * @param {any} r
+ */
+export function normalizeDispatch(r) {
+  const o = r && typeof r === "object" ? r : {};
+  return {
+    dispatched: o.dispatched === true,
+    runId: typeof o.runId === "string" ? o.runId : null,
+    error: typeof o.error === "string" ? o.error : null,
+    domain: o.domain && typeof o.domain === "object" ? o.domain : null,
+  };
+}
+
+/**
+ * Normalise a `GET /api/domain/status` response's run to a terminal verdict:
+ * { status: "dispatched"|"succeeded"|"failed"|null, runUrl, error, state }. The
+ * connect is CUT OVER only when the last run reports `succeeded` (non-rehearsal) —
+ * never inferred from the dispatch. Pure — unit-tested.
+ * @param {any} r
+ */
+export function normalizeRunStatus(r) {
+  const o = r && typeof r === "object" ? r : {};
+  const domain = o.domain && typeof o.domain === "object" ? o.domain : {};
+  const run = domain.lastRun && typeof domain.lastRun === "object" ? domain.lastRun : {};
+  return {
+    status: typeof run.status === "string" ? run.status : null,
+    action: typeof run.action === "string" ? run.action : null,
+    rehearsal: run.rehearsal === true,
+    runUrl: typeof run.runUrl === "string" ? run.runUrl : null,
+    error: typeof run.error === "string" ? run.error : null,
+    platformState: typeof domain.state === "string" ? domain.state : null,
+  };
+}
+
+// ─── The go-live gate (pure) ──────────────────────────────────────────────────────
+
+/**
+ * Decide, from the normalised readiness, whether a CONNECT may proceed — PURE so
+ * every branch is unit-tested without HTTP/TTY. Order: owner first (the most
+ * fundamental denial), then the full readiness verdict. A rollback does NOT gate
+ * on dual-run parity (it restores prior records); the server's `beginDomainRun`
+ * enforces "no captured prior records ⇒ refused", so rollback only needs owner +
+ * not-in-flight here and lets the server be the authority.
+ *
+ * @param {ReturnType<typeof normalizeReadiness>} readiness
+ * @param {"connect"|"rollback"} action
+ * @returns {{ kind: "not-owner"|"not-ready"|"ready", blockers: string[] }}
+ */
+export function goLiveReadinessGate(readiness, action) {
+  if (!readiness.ownerCapable) {
+    return {
+      kind: "not-owner",
+      blockers: [
+        "apex cutover is owner-only — sign in as the store owner (a ship-on-behalf developer cannot cut over the apex)",
+      ],
+    };
+  }
+  if (action === "rollback") {
+    // Rollback readiness = owner (above) + not mid-run. The server enforces the
+    // captured-records precondition; don't block the revert on connect-only signals.
+    const inFlight = readiness.checks.find((c) => c.id === "no-run-in-flight");
+    if (inFlight && !inFlight.ok) {
+      return { kind: "not-ready", blockers: [inFlight.detail] };
+    }
+    return { kind: "ready", blockers: [] };
+  }
+  if (!readiness.ready) {
+    return { kind: "not-ready", blockers: readiness.blockedReasons };
+  }
+  return { kind: "ready", blockers: [] };
+}
+
+// ─── Rendering (pure) ─────────────────────────────────────────────────────────────
+
+/** Render the readiness itemization — one ✓/✗ line per check + a headline. Pure. */
+export function renderReadiness({ appDomain, readiness, action }) {
+  const lines = ["", `  Apex ${action === "rollback" ? "rollback" : "cutover"} readiness for ${appDomain ?? "this store"}:`];
+  for (const c of readiness.checks) {
+    lines.push(`    ${c.ok ? "✓" : "✗"} ${c.label}${c.detail ? ` — ${c.detail}` : ""}`);
+  }
+  if (action === "connect") {
+    lines.push(
+      "",
+      readiness.ready
+        ? "  All preconditions green — this cutover is permitted."
+        : "  Not ready — the failing preconditions above block the cutover.",
+    );
+  }
+  return lines;
+}
+
+// ─── Status poll ───────────────────────────────────────────────────────────────────
+
+/**
+ * Poll `GET /api/domain/status` until the in-flight run reaches a terminal state
+ * (succeeded|failed) or the attempts budget runs out. The dispatch is async — CI
+ * runs then POSTs the HMAC callback — so this CONFIRMS the real outcome instead of
+ * assuming it from the dispatch. Injectable delay/attempts. Returns the last
+ * normalised run status (may still be "dispatched" if CI is slow — reported honestly).
+ * @param {{ get:(path:string)=>Promise<any> }} http
+ */
+export async function pollRunTerminal(http, { attempts = 8, delayMs = 2000, sleep } = {}) {
+  const wait = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let last = null;
+  for (let i = 0; i < attempts; i++) {
+    last = normalizeRunStatus(await http.get("/api/domain/status"));
+    if (last.status === "succeeded" || last.status === "failed") return last;
+    if (i < attempts - 1) await wait(delayMs);
+  }
+  return last;
+}
+
+// ─── Orchestration ───────────────────────────────────────────────────────────────
+
+/**
+ * The go-live flow over an HTTP client — read readiness, render, gate, confirm,
+ * dispatch, poll, report. Split out from `run` so it's driven in tests with a mock
+ * `{ get, post }` HTTP client + injected confirm/interactive, no network / TTY /
+ * live DNS.
+ *
+ * @param {{ get:(path:string)=>Promise<any>, post:(path:string,body:any)=>Promise<any> }} http
+ * @param {{ appDomain:string, action:"connect"|"rollback", rehearsal:boolean, noOpen?:boolean }} params
+ * @param {{ interactive?:()=>boolean, confirm?:(q:string,d:boolean)=>Promise<boolean>,
+ *   poll?:typeof pollRunTerminal, openUrl?:(u:string)=>boolean, progress?:boolean }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runGoLive(http, { appDomain, action, rehearsal, noOpen }, deps = {}) {
+  const interactive = deps.interactive || isInteractive;
+  const confirm = deps.confirm || promptYesNo;
+  const poll = deps.poll || pollRunTerminal;
+
+  // 1. Read the server-authoritative readiness verdict + ALWAYS itemize it.
+  let readiness;
+  try {
+    readiness = normalizeReadiness(await http.get("/api/domain/readiness"));
+  } catch (e) {
+    console.error(
+      fail(
+        `couldn't read apex readiness: ${String(e?.message || e)}`,
+        "check your connection and that the operator token/owner are set, then re-run",
+      ),
+    );
+    return 1;
+  }
+  const domain = appDomain || readiness.appDomain;
+  for (const line of renderReadiness({ appDomain: domain, readiness, action })) console.log(line);
+
+  // 2. Gate — owner-only + (for connect) fail-closed on the readiness verdict.
+  const gate = goLiveReadinessGate(readiness, action);
+  if (gate.kind === "not-owner") {
+    console.error(fail(gate.blockers[0], "the admin Domain tab connects the apex from the owner's signed-in session"));
+    return 1;
+  }
+  if (gate.kind !== "ready") {
+    console.error(
+      fail(
+        `apex ${action} is not ready`,
+        "clear the failing preconditions above (e.g. run the dual-run, capture prior records), then re-run",
+      ),
+    );
+    return 1;
+  }
+
+  // 3. ALWAYS require one explicit y/N confirm; refuse in a NON-TTY.
+  if (!interactive()) {
+    console.error(
+      fail(
+        `\`tot go-live${action === "rollback" ? " --rollback" : ""}\` needs an interactive terminal to confirm the live change`,
+        "run it from a terminal (there is intentionally no --yes/--force)",
+      ),
+    );
+    return 2;
+  }
+  const verb = action === "rollback" ? "roll the apex DNS back" : rehearsal ? "REHEARSE the apex cutover" : "cut the apex over";
+  const proceed = await confirm(`\n  ${cap(verb)} for ${domain}?`, false);
+  if (!proceed) {
+    console.log("  Cancelled — nothing changed.");
+    return 0;
+  }
+
+  // 4. Dispatch the SAME go-live CI action the admin button fires. The connect
+  //    requires the typed domain confirmation server-side (confirmDomain).
+  let dispatch;
+  try {
+    dispatch = normalizeDispatch(
+      await http.post("/api/domain/dispatch", {
+        action,
+        rehearsal,
+        ...(action === "connect" ? { confirmDomain: domain } : {}),
+      }),
+    );
+  } catch (e) {
+    console.error(
+      fail(
+        `the go-live dispatch was refused: ${String(e?.message || e)}`,
+        "the server gates the cutover (owner session + readiness); resolve the reason it reported, then re-run",
+      ),
+    );
+    return 1;
+  }
+  if (!dispatch.dispatched) {
+    console.error(
+      fail(
+        dispatch.error || "the go-live dispatch did not fire",
+        "the server refused the cutover — recheck `tot go-live` readiness and that you're the signed-in owner",
+      ),
+    );
+    return 1;
+  }
+
+  // 5. Poll for the REAL terminal state — never claim "cut over" before the CI
+  //    callback confirms it.
+  const progress = deps.progress === false ? null : startProgress(action === "rollback" ? "rolling back…" : "cutting over…");
+  let status;
+  try {
+    status = await poll(http);
+  } finally {
+    progress?.stop();
+  }
+  return reportGoLive({ status, dispatch, action, rehearsal, domain, noOpen, openUrl: deps.openUrl });
+}
+
+/** Report the go-live outcome honestly + always surface the one-line revert. */
+function reportGoLive({ status, dispatch, action, rehearsal, domain, noOpen, openUrl }) {
+  const runUrl = status?.runUrl || null;
+  const revertHint = "  Revert (one line): tot go-live --rollback";
+
+  if (status?.status === "succeeded") {
+    if (rehearsal) {
+      console.log(`\n  ✓ rehearsal succeeded for ${domain} — DNS state unchanged (dry run).`);
+    } else if (action === "rollback") {
+      console.log(`\n  ✓ rolled the apex DNS back for ${domain} to the captured prior records.`);
+    } else {
+      console.log(`\n  ✓ apex cut over for ${domain} — the storefront is now live on the apex.`);
+      const url = `https://${domain}`;
+      console.log(`  Live: ${url}`);
+      if (!noOpen && openUrl && openUrl(url)) console.log("  (opened in your browser)");
+    }
+    if (action !== "rollback") console.log(revertHint);
+    return 0;
+  }
+
+  if (status?.status === "failed") {
+    console.error(
+      fail(
+        `the apex ${action} run failed${status.error ? `: ${status.error}` : ""}`,
+        action === "rollback"
+          ? "check the CI run, then retry"
+          : "the DNS was not changed if the run failed before cutover; check the CI run, then retry — or `tot go-live --rollback`",
+      ),
+    );
+    if (runUrl) console.error(`  CI run: ${runUrl}`);
+    return 1;
+  }
+
+  // Dispatched but not yet terminal — CI is still running. Report honestly.
+  console.log(`\n  ~ ${action} dispatched for ${domain}${dispatch.runId ? ` (run ${dispatch.runId})` : ""}; it's running now.`);
+  if (runUrl) console.log(`  Track it: ${runUrl}`);
+  console.log("  Re-run `tot go-live` (or watch the admin Domain tab) for the terminal state.");
+  if (action !== "rollback") console.log(revertHint);
+  return 0;
+}
+
+function cap(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/**
+ * Build an HTTP client over the storefront apex-domain endpoints. Auth mirrors the
+ * headless operator trust boundary the storefront's `resolveOwnerSession` Path 2
+ * accepts: a Bearer operator secret + `X-Tot-Owner`, plus the `x-tot-capability`
+ * ship floor. Throws on a non-2xx with the server's error message (so the caller
+ * surfaces the real refusal). `fetchImpl` is injectable for tests.
+ * @param {string} base
+ * @param {{ token:string|undefined, owner:string, capability?:string, fetchImpl?:typeof fetch }} auth
+ */
+export function createStorefrontHttp(base, { token, owner, capability = "ship-on-behalf", fetchImpl } = {}) {
+  const root = base.replace(/\/+$/, "");
+  const doFetch = fetchImpl || fetch;
+  const headers = () => ({
+    ...(token ? { authorization: `Bearer ${token}` } : {}),
+    ...(owner ? { "x-tot-owner": owner } : {}),
+    "x-tot-capability": capability,
+  });
+  const parse = async (res) => {
+    const text = await res.text();
+    let body = null;
+    try {
+      body = text ? JSON.parse(text) : null;
+    } catch {
+      body = null;
+    }
+    if (!res.ok) {
+      const msg = (body && typeof body === "object" && typeof body.error === "string" && body.error) ||
+        `HTTP ${res.status}`;
+      throw new Error(msg);
+    }
+    return body;
+  };
+  return {
+    async get(path) {
+      return parse(await doFetch(`${root}${path}`, { method: "GET", headers: headers() }));
+    },
+    async post(path, body) {
+      return parse(
+        await doFetch(`${root}${path}`, {
+          method: "POST",
+          headers: { ...headers(), "content-type": "application/json" },
+          body: JSON.stringify(body ?? {}),
+        }),
+      );
+    },
+  };
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseGoLiveArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (ctx.mode !== "checkout") {
+    console.error(
+      fail(
+        "`tot go-live` runs from inside a tenant checkout",
+        "tot clone <tenant> <dir>   (then `cd` in, and `tot go-live`)",
+      ),
+    );
+    return 2;
+  }
+
+  // The owner/appDomain to act on, and the storefront base URL. Owner defaults to
+  // the checkout's tenant (owner == appDomain in this platform); the base URL
+  // defaults to https://<owner> unless overridden.
+  const owner = args.owner || env.TOT_STOREFRONT_OWNER || ctx.tenant;
+  if (!owner) {
+    console.error(
+      fail(
+        "couldn't resolve the store owner/appDomain for this checkout",
+        "pass --owner <appDomain> or set TOT_STOREFRONT_OWNER",
+      ),
+    );
+    return 1;
+  }
+  const base = args.url || env.TOT_STOREFRONT_URL || `https://${owner}`;
+  const token = env.TOT_STOREFRONT_OPERATOR_TOKEN || env.PREVIEW_RECONCILE_SECRET;
+
+  // The storefront apex-domain endpoints authenticate via the operator token +
+  // X-Tot-Owner (resolveOwnerSession Path 2), NOT the MCP OAuth session — so there
+  // is no MCP sign-in step here. Owner INTENT is enforced by the explicit confirm
+  // below and, authoritatively, by the server's owner-only readiness/dispatch gate.
+  const http = createStorefrontHttp(base, { token, owner });
+  return await runGoLive(
+    http,
+    { appDomain: owner, action: args.action, rehearsal: args.rehearsal, noOpen: args.noOpen },
+    { openUrl: (u) => openBrowser(u) },
+  );
+}