@tokenoftrust/cli 1.4.0-rc.2 → 1.4.0-rc.20

package/src/commands/revert.mjs

@@ -0,0 +1,322 @@
+/**
+ * `tot revert --preview <PR|integration-sha>` (unit b21) — OPERATOR verb: REMOVE
+ * already-integrated content from the protected `preview` AGGREGATE by creating a
+ * NEW auditable revert commit, then rebuilding the aggregate. It is the explicit,
+ * safe answer to "several candidates are accepted, but one must be removed"
+ * (branch-lifecycle contract): NEVER a force-reset, NEVER a branch delete — a revert
+ * is a new commit on `preview`, and the shared preview moves only when the rebuilt
+ * aggregate is green again. Full history is preserved.
+ *
+ * DISTINCT from `tot ship`: revert is NOT go-live. It touches NO `main` and NO live
+ * channel; it only rewinds the SHARED preview aggregate. The verb is `--preview`-only
+ * by construction — there is no `--main` revert. To undo something already LIVE, use
+ * `tot rollback` (a live re-point), not this.
+ *
+ * TARGET — `--preview <target>` names EITHER a PR number (`42` or `#42`) OR an exact
+ * `preview` integration SHA. A numeric target is sent as `prNumber`; anything else as
+ * `integrationSha`. The server resolves either to the exact integration commit to
+ * undo (unit b21's resolver, inside the tenant-serialized queue lock), and REFUSES a
+ * target that was never integrated or has already been reverted.
+ *
+ * TRANSPORT — `POST /api/changes/revert` (the ONE call site of b07's
+ * `TenantIntegrationQueue.enqueueRevert`). Like `tot accept` / `tot ship`, the CLI
+ * reaches it with the OPERATOR-SECRET Bearer transport (`resolveOperatorSecret` +
+ * `X-Tot-Owner` + `x-tot-capability`). The response is the honest terminal aggregate
+ * state — `queueState` / `runState` / `pointerMoved` / `aggregateSha` /
+ * `revertedSha` / `statusMessage` — rendered VERBATIM, never a bare "reverted".
+ *
+ * HUMAN GATE — rewinding the shared preview is a decision a human makes, so this
+ * ALWAYS states the EXACT plan (a NEW revert commit, NO force-reset, NO touch to
+ * main/live) and requires an explicit confirm. `--yes` is an explicit affirmative; a
+ * non-TTY without `--yes` is refused (mirrors `tot accept` / `tot ship`).
+ *
+ * Dependency-free (global fetch + the shared plan module).
+ */
+import { fail } from "../errors.mjs";
+import { planForAction, printPlanAndConfirm } from "../plan.mjs";
+// Reuse `tot ship`'s operator-secret precedence verbatim so accept + ship + revert
+// speak ONE operator-auth contract.
+import { resolveOperatorSecret } from "./ship.mjs";
+
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+const USAGE = `tot revert — remove already-integrated content from the preview aggregate (auditable)
+
+  tot revert --preview <PR|integration-sha> --tenant <t>
+
+  Creates a NEW auditable revert commit on the tenant's protected \`preview\`
+  aggregate that undoes one prior integration, then rebuilds the aggregate and
+  runs combined evidence. The shared preview advances only when it is GREEN
+  again. A revert is NEVER a force-reset and NEVER deletes commits — full history
+  is preserved. It does NOT touch main and does NOT go live.
+
+  <PR|integration-sha> is EITHER a PR number (e.g. 42 or #42) OR an exact preview
+  integration SHA. A target that was never integrated, or has already been
+  reverted, is refused before any change is made.
+
+  Rewinding the shared preview is a human decision: this ALWAYS prints the exact
+  plan and asks for an explicit confirm. A non-TTY without --yes is refused.
+
+Options:
+  --preview <PR|sha>     REQUIRED. The PR number or integration SHA to revert.
+  --tenant <appDomain>   Target tenant (e.g. tokenoftrust.com). Defaults to the
+                         current checkout's tenant when run inside one.
+  --message <msg>        Optional revert-commit message.
+  --url <origin>         storefront origin (default: env TOT_STOREFRONT_URL)
+  --secret <s>           operator secret (prefer the env vars below)
+  --yes, -y              Skip the interactive confirm (still an explicit human
+                         affirmative — there is no default-yes).
+  --help, -h             Show this help.
+
+  To undo something already LIVE, use \`tot rollback\` — not \`tot revert\`.
+
+  Operator secret (from env, first found): PREVIEW_RECONCILE_SECRET,
+  GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET (or pass --secret).`;
+
+/** Parse `tot revert` argv. Pure — unit-testable. */
+export function parseRevertArgs(argv) {
+  const a = {
+    preview: null,
+    tenant: null,
+    message: null,
+    url: null,
+    secret: null,
+    yes: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--preview") a.preview = argv[++i];
+    else if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--message" || t === "-m") a.message = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--secret") a.secret = argv[++i];
+    else if (t === "--yes" || t === "-y") a.yes = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+/**
+ * Classify a `--preview` target into `{ prNumber }` or `{ integrationSha }`. A bare
+ * integer (optionally `#`-prefixed) is a PR number; anything else (a hex-ish SHA) is
+ * an integration SHA. Pure — unit-tested.
+ * @param {string|null} raw
+ * @returns {{ prNumber:number|null, integrationSha:string|null }}
+ */
+export function classifyRevertTarget(raw) {
+  const t = (raw || "").trim().replace(/^#/, "");
+  if (!t) return { prNumber: null, integrationSha: null };
+  if (/^\d+$/.test(t)) return { prNumber: Number(t), integrationSha: null };
+  return { prNumber: null, integrationSha: t };
+}
+
+/**
+ * Normalise a `POST /api/changes/revert` body to the honest terminal aggregate
+ * fields this verb renders. Reads defensively so a plausible field rename degrades
+ * rather than crashes. Pure — unit-tested.
+ * @param {any} data
+ */
+export function normalizeRevertResponse(data) {
+  const o = data && typeof data === "object" ? data : {};
+  return {
+    ok: o.ok === true,
+    queueState: typeof o.queueState === "string" ? o.queueState : null,
+    runState: typeof o.runState === "string" ? o.runState : null,
+    pointerMoved: o.pointerMoved === true,
+    aggregateSha: typeof o.aggregateSha === "string" ? o.aggregateSha : null,
+    revertedSha: typeof o.revertedSha === "string" ? o.revertedSha : null,
+    statusMessage: typeof o.statusMessage === "string" ? o.statusMessage : null,
+    reason: typeof o.reason === "string" ? o.reason : null,
+    changeId: typeof o.changeId === "string" ? o.changeId : null,
+    error: typeof o.error === "string" ? o.error : null,
+    raw: data,
+  };
+}
+
+/**
+ * Render the terminal aggregate status in house style — the honest queue/run state,
+ * NEVER a bare "reverted". Pure given its inputs; returns the process exit code.
+ * @param {ReturnType<typeof normalizeRevertResponse>} result
+ * @param {{ tenant:string, label:string }} ctx
+ * @returns {number}
+ */
+export function reportReverted(result, { tenant, label }) {
+  const state = `${result.queueState ?? "?"}/${result.runState ?? "—"}`;
+  if (result.ok) {
+    console.log(`\n  ✓ reverted ${label} out of ${tenant}'s preview aggregate — it is GREEN.`);
+    console.log(`  aggregate: ${state}${result.aggregateSha ? `  (${result.aggregateSha})` : ""}`);
+    if (result.revertedSha) console.log(`  reverted integration commit: ${result.revertedSha}`);
+    if (result.pointerMoved) console.log("  the shared preview pointer moved to the reverted aggregate.");
+    console.log("  → next: review the aggregate preview, then `tot ship` to publish it live.");
+    return 0;
+  }
+  // Honest non-green: the revert did NOT land in the shippable aggregate.
+  console.log(`\n  ✗ ${label} was NOT reverted out of ${tenant}'s preview aggregate.`);
+  console.log(`  aggregate: ${state}${result.reason ? `  (${result.reason})` : ""}`);
+  if (result.statusMessage) console.log(`  why: ${result.statusMessage}`);
+  if (result.reason === "target_not_found" || result.reason === "already_reverted") {
+    console.log(`  → check the target: \`tot ship\` shows the aggregate's included PRs.`);
+  } else {
+    console.log("  → the aggregate is unchanged (last green preserved); fix forward or retry.");
+  }
+  return 1;
+}
+
+/**
+ * The revert flow after args are parsed: state the exact plan, confirm, then POST
+ * `/api/changes/revert` (operator-secret transport) and render the honest terminal
+ * aggregate status. `fetch`/`confirmPlan` injected so it is unit-tested with no
+ * network/TTY.
+ *
+ * @param {{ tenant:string, prNumber:number|null, integrationSha:string|null,
+ *   message:string|null, secret:string, storefrontUrl?:string|null, yes?:boolean }} params
+ * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runRevert(
+  { tenant, prNumber, integrationSha, message = null, secret, storefrontUrl = null, yes = false },
+  deps = {},
+) {
+  const fetchImpl = deps.fetch || globalThis.fetch;
+  const confirmPlan = deps.confirmPlan || printPlanAndConfirm;
+  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+  const label = prNumber != null ? `PR #${prNumber}` : `integration ${integrationSha}`;
+
+  // 1. State the EXACT plan (shared U10 affordance) — a NEW revert commit on
+  //    preview, NO force-reset, NO touch to main/live — and gate on a confirm.
+  const planLines = planForAction({
+    action: "revert",
+    tenant,
+    pr: prNumber,
+    integrationSha,
+  });
+  const { confirmed, reason } = await confirmPlan(planLines, {
+    yes,
+    question: `Revert ${label} out of ${tenant}'s preview aggregate (a new revert commit)?`,
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error(
+        fail(
+          "refusing to revert 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 reverted.");
+    return 1;
+  }
+
+  // 2. Operator-secret transport — the CLI holds no storefront cookie.
+  if (!secret) {
+    console.error(
+      fail(
+        "reverting the preview aggregate is an OPERATOR action — it needs an operator secret",
+        "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
+      ),
+    );
+    return 2;
+  }
+  const authHeaders = {
+    "content-type": "application/json",
+    authorization: `Bearer ${secret}`,
+    "x-tot-owner": tenant,
+    "x-tot-capability": "ship-on-behalf",
+  };
+  const requestBody = {
+    repo: tenant,
+    ...(prNumber != null ? { prNumber } : {}),
+    ...(integrationSha ? { integrationSha } : {}),
+    ...(message ? { message } : {}),
+  };
+
+  // 3. POST the honest revert path (b07 queue enqueueRevert) and render terminal state.
+  let res;
+  try {
+    res = await fetchImpl(`${base}/api/changes/revert`, {
+      method: "POST",
+      headers: authHeaders,
+      body: JSON.stringify(requestBody),
+    });
+  } catch (e) {
+    console.error(
+      fail(`couldn't reach the revert endpoint at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+
+  let data = {};
+  try {
+    data = await res.json();
+  } catch {
+    /* non-JSON / empty body */
+  }
+  const result = normalizeRevertResponse(data);
+
+  // A pre-flight error (auth, unknown tenant, bad body) is an HTTP 4xx with
+  // `{ error }` and no queue verdict — surface it distinctly from a red run.
+  if (!res.ok && result.queueState == null) {
+    const msg = result.error || `HTTP ${res.status}`;
+    console.error(
+      fail(
+        `the revert request was refused: ${msg}`,
+        res.status === 401 || res.status === 403
+          ? "check the operator secret and that it's authorised for this tenant"
+          : "check --tenant / --url / --preview, then re-run",
+      ),
+    );
+    return 1;
+  }
+
+  return reportReverted(result, { tenant, label });
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseRevertArgs(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 { prNumber, integrationSha } = classifyRevertTarget(args.preview);
+  if (prNumber == null && !integrationSha) {
+    console.error(
+      fail(
+        "no revert target.",
+        "pass --preview <PR|integration-sha> (a PR number like 42, or an exact preview integration SHA).",
+      ),
+    );
+    return 2;
+  }
+
+  const storefrontUrl =
+    args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+
+  return await runRevert({
+    tenant,
+    prNumber,
+    integrationSha,
+    message: (args.message || "").trim() || null,
+    secret: resolveOperatorSecret(args.secret, env),
+    storefrontUrl,
+    yes: args.yes,
+  });
+}