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

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) },
+  );
+}

package/src/commands/pr.mjs

@@ -21,7 +21,7 @@ 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 { repoNameFromRemote, currentBranch } from "./submit.mjs";
 import {
   defaultCandidateStatePath,
   readActiveChangeId,
@@ -79,11 +79,23 @@ export function matchCandidate(candidates, target) {
   return candidates.find((c) => c.changeId === target) ?? null;
 }
 
-/** One-line candidate summary for `tot pr list`. */
-function line(c) {
+/**
+ * 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. Prefers the candidate's
+ * `previewUrl`, falling back to the PR `url`. `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 url = c.url ? `  ${c.url}` : "";
-  return `  PR ${pr}  ${c.changeId}  [${c.state ?? "?"}]${url}`;
+  const branch = c.branch ? c.branch : "(no branch)";
+  const previewUrl = c.previewUrl || c.url || null;
+  const urlPart = previewUrl ? `  ${previewUrl}` : "";
+  const activePart = active ? "  ← active" : "";
+  return `  PR ${pr}  ${branch}  ${c.changeId}  [${c.state ?? "?"}]${urlPart}${activePart}`;
 }
 
 /** @param {string[]} argv @param {any} ctx */
@@ -128,7 +140,9 @@ export async function run(argv, ctx) {
 
   const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const statePath = defaultCandidateStatePath(env);
-  const scope = { mcpUrl: baseUrl, repo };
+  // 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 });
@@ -146,7 +160,7 @@ export async function run(argv, ctx) {
       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" : ""));
+        console.log(formatCandidateLine(c, { active: !!active && c.changeId === active }));
       }
       return 0;
     }