@tokenoftrust/cli 1.4.0-rc.15 → 1.4.0-rc.17

package/src/commands/hotfix.mjs

@@ -0,0 +1,428 @@
+/**
+ * `tot hotfix` (unit b22) — the OWNER-ONLY EXCEPTION LANE: release an urgent
+ * production fix from `main` to live WHILE `preview` still contains other unshipped
+ * work, EXCLUDING that unshipped preview head, then automatically forward-integrate
+ * `main` into `preview` and re-validate.
+ *
+ *   tot dev / preview   build + review the fix (a `main`-based candidate)
+ *   tot hotfix --pr N   release THAT reviewed fix from main to live, bypassing preview  ← you are here
+ *
+ * This is a DELIBERATELY DISTINCT verb — NEVER a `--base main` flag on `tot ship`.
+ * `tot ship` publishes the tenant's current green PREVIEW aggregate; `tot hotfix`
+ * does the opposite in the one case that warrants it: it ships a `main`-based fix
+ * that does NOT include the in-flight preview work, and only then carries `main`
+ * forward into `preview`. Because rewinding what goes live around the normal queue
+ * is a serious exception, it ALWAYS shows the exact plan — including the unshipped
+ * preview work it BYPASSES — and requires an explicit confirm.
+ *
+ * THE FLOW (mirrors `tot ship`'s plan → confirm → act → honest-terminal-state):
+ *   1. GET the read-only PLAN from `/api/changes/hotfix` — the candidate, the
+ *      current live rollback target, the unshipped preview work bypassed, and the
+ *      paywall verdict. Zero side effects.
+ *   2. Print the EXACT plan and require ONE explicit confirm (default NO). `--yes`
+ *      confirms non-interactively; a non-TTY without `--yes` REFUSES.
+ *   3. On confirm, POST `/api/changes/hotfix` with `confirmGoLive: true`.
+ *   4. Report the orchestrator's HONEST terminal state verbatim — `shipped`
+ *      (live VERIFIED on the fix; the ONLY "shipped" state), `refused`,
+ *      `merge_failed` / `build_failed` / `promote_failed` / `record_failed`
+ *      (recoverable, never a false live) — PLUS the automatic forward-integration
+ *      outcome (green, or red + a fix-forward nudge; a red forward-integration
+ *      never un-ships the live fix).
+ *
+ * TRANSPORT: the operator-secret Bearer + `X-Tot-Owner`, the SAME transport as
+ * `tot ship` / `tot revert`. Dependency-free (global fetch + the shared plan module).
+ */
+import { fail } from "../errors.mjs";
+import { planForAction, printPlanAndConfirm } from "../plan.mjs";
+import { startProgress } from "../progress.mjs";
+import { openBrowser } from "../open.mjs";
+// Reuse `tot ship`'s operator-secret precedence + live-url derivation verbatim so
+// ship + hotfix speak ONE operator-auth contract.
+import { resolveOperatorSecret, liveUrlFor } from "./ship.mjs";
+
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+const USAGE = `tot hotfix — OWNER-ONLY: release an urgent fix from main to live, bypassing preview
+
+  tot hotfix --pr <N> --tenant <t>
+  tot hotfix --change <changeId> --tenant <t>
+
+  The EXPLICIT EXCEPTION lane for an urgent production fix while \`preview\` holds
+  other unshipped work. It releases the reviewed, main-based fix to live WITHOUT the
+  unshipped preview head, then automatically forward-integrates main → preview and
+  re-validates the aggregate. It is NOT \`tot ship\` with a flag — \`tot ship\`
+  publishes the current green preview aggregate; \`tot hotfix\` deliberately excludes it.
+
+  It ALWAYS prints the exact plan — including the unshipped preview work it BYPASSES —
+  and asks for an explicit confirm. A non-TTY without --yes is refused.
+
+Options:
+  --pr <N>               The reviewed hotfix candidate's PR number.
+  --change <changeId>    The reviewed hotfix candidate's change id (alternative to --pr).
+  --tenant <appDomain>   Target tenant (e.g. tokenoftrust.com). Defaults to the
+                         current checkout's tenant when run inside one.
+  --message <msg>        Optional merge-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 affirmative).
+  --no-open              Don't open the live URL in your browser.
+  --help, -h             Show this help.
+
+  For the ordinary release of the whole green preview aggregate, use \`tot ship\`.
+  To undo something already LIVE, use \`tot rollback\`.
+
+  Operator secret (from env, first found): PREVIEW_RECONCILE_SECRET,
+  GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET (or pass --secret).`;
+
+/** Parse `tot hotfix` argv. Pure — unit-testable. */
+export function parseHotfixArgs(argv) {
+  const a = {
+    pr: null,
+    change: null,
+    tenant: null,
+    message: null,
+    url: null,
+    secret: null,
+    yes: false,
+    noOpen: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--pr") a.pr = argv[++i];
+    else if (t === "--change" || t === "--changeId") a.change = 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 === "--no-open") a.noOpen = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+/** Normalise a `?pr` value to a positive integer, or null. Pure. */
+export function parsePrNumber(raw) {
+  const t = (raw == null ? "" : `${raw}`).trim().replace(/^#/, "");
+  return /^\d+$/.test(t) ? Number(t) : null;
+}
+
+/**
+ * Normalise a `GET /api/changes/hotfix` body — the {@link HotfixReleasePlan} (an
+ * exception ready to confirm) or a refusal. Read defensively (crossed the wire as
+ * JSON). Pure — unit-tested.
+ * @param {any} data
+ */
+export function normalizeHotfixPlan(data) {
+  const o = data && typeof data === "object" ? data : {};
+  if (o.ok === true) {
+    return {
+      ok: true,
+      tenantId: typeof o.tenantId === "string" ? o.tenantId : null,
+      changeId: typeof o.changeId === "string" ? o.changeId : null,
+      prNumber: typeof o.prNumber === "number" ? o.prNumber : null,
+      bypassedPreviewSha: typeof o.bypassedPreviewSha === "string" ? o.bypassedPreviewSha : null,
+      bypassedPrs: Array.isArray(o.bypassedPrs) ? o.bypassedPrs : [],
+      rollbackTarget: o.rollbackTarget && typeof o.rollbackTarget === "object" ? o.rollbackTarget : null,
+      paywall:
+        o.paywall && typeof o.paywall === "object"
+          ? { allowed: o.paywall.allowed === true, message: typeof o.paywall.message === "string" ? o.paywall.message : null }
+          : { allowed: true, message: null },
+    };
+  }
+  return {
+    ok: false,
+    reason: typeof o.reason === "string" ? o.reason : "unknown",
+    message: typeof o.message === "string" ? o.message : "the hotfix plan was refused for an unknown reason",
+  };
+}
+
+/**
+ * Normalise a `POST /api/changes/hotfix` body — the {@link HotfixReleaseResult}.
+ * `state` is the ONLY honest terminal authority: render "shipped live" for
+ * `"shipped"` and nothing else. Pure — unit-tested.
+ * @param {any} data
+ */
+export function normalizeHotfixResult(data) {
+  const o = data && typeof data === "object" ? data : {};
+  const fwd = o.forwardIntegration && typeof o.forwardIntegration === "object" ? o.forwardIntegration : null;
+  return {
+    ok: o.ok === true,
+    state: typeof o.state === "string" ? o.state : "unknown",
+    reason: typeof o.reason === "string" ? o.reason : null,
+    message: typeof o.message === "string" ? o.message : "",
+    mainSha: typeof o.mainSha === "string" ? o.mainSha : null,
+    artifactDigest: typeof o.artifactDigest === "string" ? o.artifactDigest : null,
+    receiptId: typeof o.receiptId === "string" ? o.receiptId : null,
+    rollbackTarget: o.rollbackTarget && typeof o.rollbackTarget === "object" ? o.rollbackTarget : null,
+    forwardIntegration: fwd
+      ? {
+          ok: fwd.ok === true,
+          queueState: typeof fwd.queueState === "string" ? fwd.queueState : null,
+          runState: typeof fwd.runState === "string" ? fwd.runState : null,
+          reason: typeof fwd.reason === "string" ? fwd.reason : null,
+          aggregateSha: typeof fwd.aggregateSha === "string" ? fwd.aggregateSha : null,
+          statusMessage: typeof fwd.statusMessage === "string" ? fwd.statusMessage : null,
+        }
+      : null,
+  };
+}
+
+/** A clear next step per hotfix plan/release refusal reason. Pure. */
+export function hotfixNextStep(reason) {
+  switch (reason) {
+    case "no_candidate":
+      return "pass --pr <N> (or --change <id>) naming the reviewed hotfix candidate";
+    case "paywall":
+      return "upgrade the storefront subscription to enable go-live";
+    case "golive_unconfirmed":
+      return "re-run `tot hotfix` and confirm the plan";
+    case "digest_mismatch":
+      return "main moved under review — re-preview the hotfix against current main, then re-run `tot hotfix`";
+    default:
+      return "re-run `tot hotfix`";
+  }
+}
+
+/** Read a fetch Response body as JSON, tolerating a non-JSON/empty body. */
+async function readJsonSafe(res) {
+  try {
+    return await res.json();
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The hotfix flow: GET the plan, print it + confirm, POST to release, report the
+ * honest terminal state + the forward-integration outcome. `fetch`/`confirmPlan`/
+ * `openUrl`/`progress` are injected so it's unit-tested with no live network/TTY.
+ *
+ * @param {{ tenant:string, prNumber:number|null, changeId:string|null,
+ *   message:string|null, secret:string, storefrontUrl?:string|null,
+ *   yes?:boolean, noOpen?:boolean }} params
+ * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm,
+ *   openUrl?:(u:string)=>boolean, progress?:boolean }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runHotfix(
+  { tenant, prNumber, changeId, message = null, secret, storefrontUrl = null, yes = false, noOpen = 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}` : changeId ? changeId : "the hotfix candidate";
+
+  if (!secret) {
+    console.error(
+      fail(
+        "a hotfix is an OWNER action — it needs an operator secret",
+        "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
+      ),
+    );
+    return 2;
+  }
+
+  const authHeaders = {
+    authorization: `Bearer ${secret}`,
+    "x-tot-owner": tenant,
+    "x-tot-capability": "ship-on-behalf",
+  };
+
+  // 1. GET the read-only plan (candidate + bypassed preview work + rollback + paywall).
+  const query = prNumber != null ? `pr=${encodeURIComponent(prNumber)}` : `changeId=${encodeURIComponent(changeId || "")}`;
+  let planRes;
+  try {
+    planRes = await fetchImpl(`${base}/api/changes/hotfix?${query}`, { method: "GET", headers: authHeaders });
+  } catch (e) {
+    console.error(
+      fail(`couldn't reach the hotfix plan at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+  const planData = await readJsonSafe(planRes);
+  if (!planRes.ok && planData?.ok !== false) {
+    const msg = planData?.error || `HTTP ${planRes.status}`;
+    console.error(
+      fail(
+        `the hotfix plan was refused: ${msg}`,
+        planRes.status === 401 || planRes.status === 403
+          ? "check the operator secret and that it's authorised for this tenant"
+          : "check --tenant / --url / --pr, then re-run",
+      ),
+    );
+    return 1;
+  }
+  const plan = normalizeHotfixPlan(planData);
+  if (!plan.ok) {
+    console.error(fail(plan.message, hotfixNextStep(plan.reason)));
+    return 1;
+  }
+
+  // 2. Print the EXACT plan — including the unshipped preview work it BYPASSES —
+  //    then require ONE explicit confirm (default NO).
+  const liveUrl = liveUrlFor(tenant);
+  const planLines = planForAction({
+    action: "hotfix",
+    tenant,
+    pr: plan.prNumber,
+    changeId: plan.changeId,
+    bypassedPrs: plan.bypassedPrs,
+    bypassedPreviewSha: plan.bypassedPreviewSha,
+    rollbackTarget: plan.rollbackTarget,
+    paywall: plan.paywall,
+    targets: { live: liveUrl },
+  });
+  const { confirmed, reason } = await confirmPlan(planLines, {
+    yes,
+    question: `Release ${label} from main to live for ${tenant}, BYPASSING the unshipped preview work?`,
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error(
+        fail(
+          "`tot hotfix` needs an interactive terminal to confirm this live exception",
+          "run it from a terminal, or pass --yes to confirm non-interactively",
+        ),
+      );
+      return 2;
+    }
+    console.log("  Hotfix cancelled — nothing changed.");
+    return 0;
+  }
+
+  // 3. RELEASE — the human go-live gate (confirmGoLive).
+  const progress = deps.progress === false ? null : startProgress("releasing hotfix…");
+  let res;
+  try {
+    res = await fetchImpl(`${base}/api/changes/hotfix`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...authHeaders },
+      body: JSON.stringify({
+        confirmGoLive: true,
+        ...(prNumber != null ? { prNumber } : {}),
+        ...(plan.changeId ? { changeId: plan.changeId } : {}),
+        ...(message ? { message } : {}),
+      }),
+    });
+  } catch (e) {
+    progress?.stop();
+    console.error(
+      fail(`couldn't reach the hotfix endpoint at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+  const resultData = await readJsonSafe(res);
+  progress?.stop();
+
+  return reportHotfixResult(normalizeHotfixResult(resultData), { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
+}
+
+/**
+ * Report the orchestrator's HONEST terminal state + the automatic forward-integration
+ * outcome. `shipped` is the ONLY state rendered as "shipped live"; a red
+ * forward-integration is surfaced as a fix-forward nudge but never un-ships live.
+ * @returns {number} process exit code
+ */
+export function reportHotfixResult(result, { tenant, liveUrl, noOpen, openUrl }) {
+  if (result.state === "shipped") {
+    console.log(`\n  ✓ shipped hotfix live for ${tenant} — the unshipped preview work was NOT included.`);
+    if (result.mainSha) console.log(`  main:    ${result.mainSha}`);
+    if (result.receiptId) console.log(`  receipt: ${result.receiptId}`);
+    if (liveUrl) {
+      console.log(`  Live: ${liveUrl}`);
+      if (!noOpen && openUrl && openUrl(liveUrl)) console.log("  (opened in your browser)");
+    }
+    // The automatic forward-integration: honest whether green or red.
+    const fwd = result.forwardIntegration;
+    if (fwd && fwd.ok) {
+      console.log(`  forward-integrated main → preview (green${fwd.aggregateSha ? `, ${fwd.aggregateSha}` : ""}).`);
+    } else if (fwd) {
+      console.log(
+        `  ⚠ forward-integration main → preview is ${fwd.queueState ?? "?"}/${fwd.runState ?? "—"}` +
+          `${fwd.reason ? `  (${fwd.reason})` : ""} — the live hotfix is fine, but preview needs a fix-forward.`,
+      );
+      if (fwd.statusMessage) console.log(`    why: ${fwd.statusMessage}`);
+      console.log("    → next: resolve preview against main, then `tot preview`.");
+    }
+    return 0;
+  }
+  if (result.state === "refused") {
+    console.error(fail(result.message || `hotfix refused (${result.reason})`, hotfixNextStep(result.reason)));
+    return 1;
+  }
+  if (
+    result.state === "merge_failed" ||
+    result.state === "build_failed" ||
+    result.state === "promote_failed" ||
+    result.state === "record_failed"
+  ) {
+    console.error(
+      fail(
+        result.message || `hotfix ${result.state.replace("_", " ")}`,
+        "re-run `tot hotfix` — the release is idempotent and safe to retry",
+      ),
+    );
+    return 1;
+  }
+  console.error(
+    fail(
+      `unexpected hotfix response (state: ${result.state})`,
+      "re-run `tot hotfix`; check the storefront logs if it persists",
+    ),
+  );
+  return 1;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseHotfixArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const tenant = (args.tenant || (ctx?.mode === "checkout" ? ctx.tenant : null) || ctx?.tenant || "").trim();
+  if (!tenant) {
+    console.error(
+      fail(
+        "`tot hotfix` needs a target tenant",
+        "pass --tenant <appDomain> (e.g. --tenant tokenoftrust.com), or run inside a store checkout.",
+      ),
+    );
+    return 2;
+  }
+
+  const prNumber = parsePrNumber(args.pr);
+  const changeId = (args.change || "").trim() || null;
+  if (prNumber == null && !changeId) {
+    console.error(
+      fail(
+        "`tot hotfix` needs the reviewed hotfix candidate",
+        "pass --pr <N> (a PR number) or --change <changeId>.",
+      ),
+    );
+    return 2;
+  }
+
+  const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+  return await runHotfix(
+    {
+      tenant,
+      prNumber,
+      changeId,
+      message: (args.message || "").trim() || null,
+      secret: resolveOperatorSecret(args.secret, env),
+      storefrontUrl,
+      yes: args.yes,
+      noOpen: args.noOpen,
+    },
+    { openUrl: (u) => openBrowser(u) },
+  );
+}