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

package/src/commands/rollback.mjs

@@ -0,0 +1,401 @@
+/**
+ * `tot rollback [<versionId>]` — instant re-point to a prior live version.
+ *
+ * The CLI counterpart to `tot ship`, for the moment ship goes wrong:
+ *
+ *   tot rollback              list promotion history (the rollback targets)
+ *   tot rollback <versionId>  re-point the live channel back to that version
+ *
+ * This does NOT reimplement pointer moves. Every selection and every move goes
+ * through u3's MCP-side live-pointer seam (`promotion_status` /
+ * `promotion_rollback`, tot-mcp `src/modules/mcp/change/promotion-pointer-tools.ts`
+ * + `promotion-pointer-store.ts`) — the SAME primitive `tot ship`'s eventual
+ * orchestrator composes (decision storefront-atomic-accept-is-ship-orchestrator).
+ * There is no dg4 ship-orchestrator service in-tree yet, so this calls the u3 seam
+ * DIRECTLY; when the orchestrator lands it should absorb the physical
+ * publish+verify this command currently leaves to it (see the seam's own
+ * "NOT a live claim" caveat, echoed in `reportRolledBack` below) — a follow-on can
+ * route through it instead without changing this file's UX.
+ *
+ * Fail-closed (decision static-publish-fails-closed-reviewed-sha): rollback selects
+ * an immutable prior digest/versionId recorded by a PRIOR promote; a missing or
+ * ineligible target is refused with a clear next step, never a silent no-op dressed
+ * up as success. The eligibility check and the pointer move both come from the
+ * seam's own dry-run preview (`promotion_rollback` with `dryRun:true`) rather than
+ * a second, CLI-side reimplementation of "what counts as a prior version" — so the
+ * two can never drift.
+ *
+ * Confirm-before-acting UX mirrors `ship.mjs`: ALWAYS render what would change,
+ * require ONE explicit [y/N] (default NO), no --yes/--force, and refuse outright in
+ * a non-TTY. On confirm, the REAL terminal state comes back from the seam's
+ * dryRun:false response — never assumed from the confirm alone.
+ *
+ * Dependency-free (global fetch via the MCP client); pure helpers are exported and
+ * unit-tested with a mock client, no network, no TTY.
+ */
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { fail } from "../errors.mjs";
+import { isInteractive, promptYesNo } from "../prompt.mjs";
+import { startProgress } from "../progress.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+// The only publish channel the seam is exercised against today (see the u3 tests
+// and `promotion_set`'s own default). A future multi-target store can override with
+// `--target`; nothing here assumes there's only ever one.
+const DEFAULT_TARGET = "production";
+
+const USAGE = `tot rollback [<versionId>] — instant re-point to a prior live version
+
+  tot rollback                list promotion history (the rollback targets)
+  tot rollback <versionId>    re-point the live channel back to that version
+  tot rollback --target <t>   the publish channel to act on (default: production)
+  tot rollback --identity <id> sign in as a specific identity for this rollback
+  tot rollback --mcp <url>    MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+
+  With no versionId, rollback lists the versions you can roll back to — read the
+  first column and re-run \`tot rollback <that versionId>\`. Rollback ALWAYS shows
+  you what would change and asks for a single y/N confirmation first; there is no
+  --yes/--force, and it refuses to run without an interactive terminal. It only
+  ever selects an immutable version this channel previously had live — never an
+  arbitrary or rebuilt one.`;
+
+/** Parse `tot rollback` argv. Pure. Deliberately NO --yes/--force (see the header). */
+export function parseRollbackArgs(argv) {
+  const a = { versionId: null, target: null, mcp: null, identity: null, help: false };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--mcp") a.mcp = argv[++i];
+    else if (t === "--target") a.target = argv[++i];
+    else if (t === "--identity") a.identity = argv[++i];
+    else if (t === "--help" || t === "-h") a.help = true;
+    else positional.push(t);
+  }
+  a.versionId = positional[0] ?? null;
+  return a;
+}
+
+// ─── Response normalisation (defensive — one MCP, but shapes may vary) ───────────
+
+/**
+ * Normalise a `promotion_status` result to the fields rollback lists on. The
+ * action-tool harness merges the tool's `data` fields flat into the response
+ * (alongside `summary`/`status`), so `found`/`pointer` are read at the top level —
+ * mirrors how `ship.mjs`'s normalizers read `change_accept`'s flattened response.
+ * Pure — unit-tested.
+ * @param {any} r
+ * @returns {{found:boolean, current:Record<string,unknown>|null,
+ *   history:Record<string,unknown>[], raw:any}}
+ */
+export function normalizeStatus(r) {
+  const o = r && typeof r === "object" ? r : {};
+  const pointer = o.pointer && typeof o.pointer === "object" ? o.pointer : null;
+  const current = pointer && pointer.current && typeof pointer.current === "object" ? pointer.current : null;
+  return {
+    found: o.found === true,
+    current,
+    history: pointer && Array.isArray(pointer.history) ? pointer.history : [],
+    raw: r,
+  };
+}
+
+/**
+ * Normalise a `promotion_rollback` dry-run (`dryRun:true`) preview response — the
+ * eligibility verdict THIS command gates confirmation on, straight from the seam
+ * (never recomputed here). Pure — unit-tested.
+ * @param {any} r
+ * @returns {{eligible:boolean, wouldSelectVersionId:string|null, summary:string|null,
+ *   pointer:Record<string,unknown>|null}}
+ */
+export function normalizeRollbackPreview(r) {
+  const o = r && typeof r === "object" ? r : {};
+  return {
+    eligible: o.eligible === true,
+    wouldSelectVersionId: typeof o.wouldSelectVersionId === "string" ? o.wouldSelectVersionId : null,
+    summary: typeof o.summary === "string" ? o.summary : null,
+    pointer: o.pointer && typeof o.pointer === "object" ? o.pointer : null,
+  };
+}
+
+/**
+ * Normalise a `promotion_rollback` commit (`dryRun:false`) response — the REAL
+ * terminal state (`changed` is false only for an idempotent no-op: the requested
+ * version was already designated live). Pure — unit-tested.
+ * @param {any} r
+ * @returns {{changed:boolean, versionId:string|null, digest:string|null,
+ *   rolledBackFrom:string|null, summary:string|null}}
+ */
+export function normalizeRollbackResult(r) {
+  const o = r && typeof r === "object" ? r : {};
+  return {
+    changed: o.changed === true,
+    versionId: typeof o.designatedVersionId === "string" ? o.designatedVersionId : null,
+    digest: typeof o.pinnedDigest === "string" ? o.pinnedDigest : null,
+    rolledBackFrom: typeof o.rolledBackFrom === "string" ? o.rolledBackFrom : null,
+    summary: typeof o.summary === "string" ? o.summary : null,
+  };
+}
+
+// ─── Revision links (pure, unit u5) ───────────────────────────────────────────────
+
+/**
+ * The immutable `/preview/<tenant>/rev/<sha>/` deep-link for a promoted
+ * `versionId` — u4's route, and per `gitea-only-tenant-content-authority` the
+ * `versionId` recorded by a promote IS the tenant Gitea sha, so no extra lookup
+ * is needed to build it. `null` when there's no `base` (storefront origin) or no
+ * `versionId` to link, so a caller can render the history line either way.
+ * Pure — unit-tested.
+ * @param {string|null|undefined} base storefront origin, e.g. `https://acme.com`
+ * @param {string} tenant
+ * @param {string|null|undefined} versionId
+ * @returns {string|null}
+ */
+export function revisionUrl(base, tenant, versionId) {
+  if (!base || !versionId) return null;
+  return `${String(base).replace(/\/+$/, "")}/preview/${encodeURIComponent(tenant)}/rev/${encodeURIComponent(versionId)}/`;
+}
+
+// ─── Candidate selection + rendering (pure) ──────────────────────────────────────
+
+/**
+ * The prior versions eligible as a rollback target: every PROMOTE entry in history
+ * other than the one currently live (rolling back to the live version is a no-op,
+ * not a "prior" target), newest first. Mirrors — but doesn't replace — the seam's
+ * own default selection (`promotion_rollback` with no `toVersionId`); this is
+ * listing surface only, the seam still decides eligibility when you act. Pure —
+ * unit-tested.
+ * @param {Record<string,unknown>[]} history
+ * @param {string|null} currentVersionId
+ * @returns {Record<string,unknown>[]}
+ */
+export function rollbackCandidates(history, currentVersionId) {
+  return [...history]
+    .filter((e) => e && e.op === "promote" && e.versionId !== currentVersionId)
+    .reverse();
+}
+
+/** Render the `tot rollback` (no args) history listing — the rollback-target
+ *  picker (unit u2), each entry annotated with its immutable `/rev/<sha>` link
+ *  (unit u5) when a storefront origin is available. Pure — unit-tested.
+ * @param {{ tenant:string, target:string, current:Record<string,unknown>|null,
+ *   candidates:Record<string,unknown>[], revisionBase?:string|null }} input
+ * @returns {string[]}
+ */
+export function renderHistory({ tenant, target, current, candidates, revisionBase }) {
+  const lines = ["", `  Promotion history for ${tenant} on "${target}":`];
+  if (current) {
+    const link = revisionUrl(revisionBase, tenant, current.versionId);
+    lines.push(`    live now: ${current.versionId} (pinned tree ${current.digest})${link ? `  ${link}` : ""}`);
+  }
+  if (!candidates.length) {
+    lines.push("    (no prior version recorded yet — nothing to roll back to)");
+    return lines;
+  }
+  lines.push("", "    rollback targets, newest first:");
+  for (const e of candidates) {
+    const link = revisionUrl(revisionBase, tenant, e.versionId);
+    lines.push(`      ${e.versionId}  ${e.digest}  ${e.at}${link ? `  ${link}` : ""}`);
+  }
+  lines.push("", `    tot rollback <versionId>   to roll ${target} back to one of these`);
+  return lines;
+}
+
+/** Render the "what goes live" block for a rollback preview. Pure — unit-tested.
+ * @param {{ tenant:string, target:string, toVersionId:string,
+ *   preview:ReturnType<typeof normalizeRollbackPreview> }} input
+ * @returns {string[]}
+ */
+export function renderRollbackPreview({ tenant, target, toVersionId, preview }) {
+  const lines = ["", `  This rollback will change the LIVE site for ${tenant}:`];
+  const current = preview.pointer?.current;
+  if (current) lines.push(`    ${target}: ${current.versionId} → ${toVersionId}`);
+  else lines.push(`    ${target}: → ${toVersionId}`);
+  return lines;
+}
+
+// ─── Orchestration ───────────────────────────────────────────────────────────────
+
+/**
+ * The rollback flow after a session is established — list (no target) or preview →
+ * confirm → commit (with a target). Split out from `run` so it's driven in tests
+ * with a mock client + injected confirm/interactive, no network/TTY.
+ *
+ * @param {{callTool:Function}} client an MCP client (real or mock)
+ * @param {{ tenant:string, target:string, toVersionId:string|null,
+ *   revisionBase?:string|null }} params `revisionBase` is the storefront origin
+ *   the listing's `/rev/<sha>` links resolve against (unit u5); omit to list
+ *   without links.
+ * @param {{ interactive?:()=>boolean, confirm?:(q:string,d:boolean)=>Promise<boolean>,
+ *   progress?:boolean }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runRollback(client, { tenant, target, toVersionId, revisionBase }, deps = {}) {
+  const interactive = deps.interactive || isInteractive;
+  const confirm = deps.confirm || promptYesNo;
+
+  // 0. No target given — list promotion history as the set of rollback targets.
+  if (!toVersionId) {
+    let status;
+    try {
+      status = normalizeStatus(await client.callTool("promotion_status", { target }));
+    } catch (e) {
+      console.error(
+        fail(
+          `couldn't read promotion history: ${String(e?.message || e)}`,
+          "check your connection and that you're signed in, then re-run",
+        ),
+      );
+      return 1;
+    }
+    if (!status.found) {
+      console.error(
+        fail(
+          `no live pointer yet for ${tenant} on "${target}"`,
+          "ship a version first with `tot ship`, then rollback targets will appear here",
+        ),
+      );
+      return 1;
+    }
+    const candidates = rollbackCandidates(status.history, status.current?.versionId ?? null);
+    for (const line of renderHistory({ tenant, target, current: status.current, candidates, revisionBase })) {
+      console.log(line);
+    }
+    return 0;
+  }
+
+  // 1. Preview the selection through the seam itself (dryRun:true) — the ONE place
+  //    eligibility is decided; we never recompute "is this a valid prior version".
+  let preview;
+  try {
+    preview = normalizeRollbackPreview(
+      await client.callTool("promotion_rollback", { target, toVersionId, dryRun: true }),
+    );
+  } catch (e) {
+    console.error(
+      fail(
+        `couldn't preview this rollback: ${String(e?.message || e)}`,
+        "check your connection and that you're signed in, then re-run",
+      ),
+    );
+    return 1;
+  }
+  // Fail-closed: an ineligible target (missing / never promoted here) is refused,
+  // never silently treated as a no-op.
+  if (!preview.eligible) {
+    console.error(
+      fail(
+        preview.summary || `${toVersionId} isn't an eligible rollback target for ${tenant} on "${target}"`,
+        "run `tot rollback` with no arguments to see eligible prior versions",
+      ),
+    );
+    return 1;
+  }
+
+  // 2. ALWAYS render what would change, then require ONE explicit y/N confirm.
+  for (const line of renderRollbackPreview({ tenant, target, toVersionId, preview })) console.log(line);
+
+  // NON-TTY: refuse rather than auto-confirm — nothing rolls back without a human yes.
+  if (!interactive()) {
+    console.error(
+      fail(
+        "`tot rollback` needs an interactive terminal to confirm the live change",
+        "run it from a terminal (there is intentionally no --yes/--force)",
+      ),
+    );
+    return 2;
+  }
+  const proceed = await confirm(`\n  Roll ${tenant} on "${target}" back to ${toVersionId}?`, false);
+  if (!proceed) {
+    console.log("  Rollback cancelled — nothing changed.");
+    return 0;
+  }
+
+  // 3. Commit — the REAL terminal state comes back from this call, never assumed
+  //    from the confirm.
+  const progress = deps.progress === false ? null : startProgress("rolling back…");
+  let result;
+  try {
+    result = normalizeRollbackResult(
+      await client.callTool("promotion_rollback", { target, toVersionId, dryRun: false }),
+    );
+  } catch (e) {
+    console.error(
+      fail(
+        `the rollback seam refused this change: ${String(e?.message || e)}`,
+        "run `tot rollback` with no arguments to recheck eligible versions, then retry",
+      ),
+    );
+    return 1;
+  } finally {
+    progress?.stop();
+  }
+  return reportRolledBack(result, { tenant, target, toVersionId });
+}
+
+/** Report the rollback result honestly — a pointer DESIGNATION, not a live claim
+ *  (the seam's own boundary; see the module header on the orchestrator gap). */
+function reportRolledBack(result, { tenant, target, toVersionId }) {
+  const versionId = result.versionId || toVersionId;
+  const pin = result.digest ? ` (pinned tree ${result.digest})` : "";
+  if (result.changed) {
+    console.log(`\n  ✓ rolled back ${tenant} on "${target}" to ${versionId}${pin}.`);
+  } else {
+    console.log(`\n  ~ ${versionId} was already the designated-live version for ${tenant} on "${target}" (no-op).`);
+  }
+  console.log(
+    "  This designates the pointer — the storefront ship orchestrator performs the physical" +
+      " publish and is the only authority that confirms it's serving live.",
+  );
+  return 0;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseRollbackArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (ctx.mode !== "checkout") {
+    console.error(
+      fail(
+        "`tot rollback` runs from inside a tenant checkout",
+        "tot clone <tenant> <dir>   (then `cd` in, and `tot rollback`)",
+      ),
+    );
+    return 2;
+  }
+
+  const tenant = ctx.tenant;
+  const target = args.target?.trim() || DEFAULT_TARGET;
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  // The storefront origin the listing's /rev/<sha> links resolve against (unit
+  // u5) — owner == appDomain on this platform, mirroring go-live.mjs's default.
+  const revisionBase = env.TOT_STOREFRONT_URL || (tenant ? `https://${tenant}` : null);
+  const client = createMcpClient(baseUrl);
+  try {
+    await establishSession(client, { env, prefer: args.identity || undefined });
+    // Bind the active tenant so the promotion tools read/write the right scope.
+    await client.callTool("client_switch", { tenant });
+
+    return await runRollback(client, { tenant, target, toVersionId: args.versionId, revisionBase });
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      console.error(fail("sign in to roll back", e.hint || "run `tot login`, then re-run `tot rollback`"));
+      return 1;
+    }
+    console.error(
+      fail(
+        `couldn't reach the rollback service: ${String(e?.message || e)}`,
+        "check your connection and that you're signed in, then re-run",
+      ),
+    );
+    return 1;
+  }
+}