@tokenoftrust/cli 1.4.0-rc.9 → 1.4.1

package/src/commands/retire.mjs

@@ -0,0 +1,203 @@
+/**
+ * `tot retire --tenant <t> --pr <N>` — OPERATOR retire/GC (unit U7).
+ *
+ * Evict a candidate PR's hosted preview — its `ReviewEnvironment` projection +
+ * its immutable site version — to RECLAIM SPACE. It calls the
+ * session-authenticated storefront endpoint `POST /api/preview/retire` (unit
+ * U7), which deletes the candidate record + prunes the tenant index and evicts
+ * the candidate version (guarded: it refuses any version a channel points at).
+ *
+ * DISTINCT FROM `tot accept` / reject: retire touches NO change lifecycle — the
+ * change stays open. It is REVERSIBLE-BY-REBUILD: because U1 build-on-demand
+ * (`tot preview build`) + the U2 fallback page can rematerialize the PR head on
+ * request, a retired PR degrades to "not built yet", NOT a dead 404.
+ *
+ * IDEMPOTENT — retiring an already-absent candidate is a clean success
+ * (nothing to evict). Unlike `tot preview build`, retire needs NO head sha: it
+ * targets an EXISTING candidate by `--pr` (→ `pr-<N>`) or an explicit
+ * `--change-id`.
+ *
+ * AUTH — the storefront endpoint accepts the headless Bearer-operator-secret
+ * path (`resolveOwnerSession` fallback). This verb sends `Authorization: Bearer
+ * <secret>` (from `PREVIEW_RECONCILE_SECRET` / `GRANTS_ADMIN_SECRET` /
+ * `TOT_OPERATOR_SECRET`, or `--secret`), `X-Tot-Owner: <tenant>`, and
+ * `X-Tot-Capability: ship-on-behalf` — mirroring `tot preview build` and the
+ * `/admin` AdminPublishTab retire call.
+ *
+ * SELF-DECLARING — it prints the EXACT plan (which PR → which tenant → evict +
+ * rebuildable) and confirms before acting (`--yes` to skip; a non-TTY without
+ * `--yes` aborts rather than acting silently). Retire is INERT re: shared
+ * channels — it flips no preview/live channel and touches no live pointer — so
+ * this is a teardown, not a deploy. The plan itself is built by the SHARED plan
+ * module (`../plan.mjs`, unit U10) — the same affordance every other mutating
+ * operator verb (build/accept/ship) and the `/admin` confirm dialog use, per
+ * decision `operator-verb-and-hosting-model`.
+ *
+ * Dependency-free (global fetch + the shared plan module).
+ */
+import { planForAction, printPlanAndConfirm } from "../plan.mjs";
+
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+/** Parse `tot retire` argv. Pure — unit-testable. */
+export function parseRetireArgs(argv) {
+  const a = {
+    tenant: null,
+    pr: null,
+    changeId: null,
+    url: null,
+    secret: null,
+    yes: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--pr") a.pr = argv[++i];
+    else if (t === "--change-id") a.changeId = 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;
+}
+
+export function renderUsage() {
+  return `tot retire — operator retire/GC: evict a candidate PR's hosted preview
+
+Usage:
+  tot retire --tenant <appDomain> --pr <N> [options]
+  tot retire --tenant <appDomain> --change-id <id> [options]
+
+Evicts the candidate preview for PR #N of <tenant> — its review environment +
+immutable version — to reclaim space. REVERSIBLE: rebuild it any time with
+\`tot preview build\` (the change stays open; this is NOT reject). It flips NO
+shared channel and is NOT go-live.
+
+Options:
+  --tenant <appDomain>   Target tenant (e.g. tokenoftrust.com). Defaults to the
+                         current checkout's tenant when run inside one.
+  --pr <N>               PR number to retire (identifies the candidate pr-<N>).
+  --change-id <id>       Optional explicit candidate id (defaults to pr-<N>).
+  --url <origin>         Storefront origin. Defaults to $TOT_STOREFRONT_URL or
+                         ${DEFAULT_STOREFRONT_URL}.
+  --secret <s>           Operator secret. Prefer the env vars below.
+  --yes, -y              Skip the confirmation prompt.
+  --help, -h             Show this help.
+
+Auth (operator secret, from env, first found):
+  PREVIEW_RECONCILE_SECRET, GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET`;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx — detected CLI context (ctx.tenant when in a checkout)
+ */
+export async function run(argv, ctx) {
+  const args = parseRetireArgs(argv);
+  if (args.help) {
+    console.log(renderUsage());
+    return 0;
+  }
+
+  const base = (args.url || process.env.TOT_STOREFRONT_URL || process.env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL)
+    .trim()
+    .replace(/\/+$/, "");
+
+  const tenant = (args.tenant || ctx?.tenant || "").trim();
+  if (!tenant) {
+    console.error(
+      "✗ no target tenant.\n\n  → next: pass --tenant <appDomain> (e.g. --tenant tokenoftrust.com), " +
+        "or run inside a store checkout.",
+    );
+    return 2;
+  }
+
+  const prRaw = args.pr;
+  const pr = prRaw != null && `${prRaw}`.trim() && Number.isFinite(Number(prRaw)) ? Number(prRaw) : null;
+  const changeId = (args.changeId || "").trim() || null;
+  if (pr == null && !changeId) {
+    console.error(
+      "✗ no candidate to retire.\n\n  → next: pass --pr <N> (the PR number to retire), or --change-id <id>.",
+    );
+    return 2;
+  }
+
+  const secret = (args.secret || process.env.PREVIEW_RECONCILE_SECRET || process.env.GRANTS_ADMIN_SECRET || process.env.TOT_OPERATOR_SECRET || "").trim();
+  if (!secret) {
+    console.error(
+      "✗ no operator secret.\n\n  → next: set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / " +
+        "TOT_OPERATOR_SECRET) in the environment.",
+    );
+    return 2;
+  }
+
+  // Self-declaring: state the EXACT plan before acting (the shared plan module).
+  const planLines = planForAction({
+    action: "retire",
+    tenant,
+    pr,
+    changeId,
+    endpoint: `${base}/api/preview/retire`,
+  });
+  const { confirmed, reason } = await printPlanAndConfirm(planLines, {
+    yes: args.yes,
+    question: "Retire this preview now?",
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error("✗ refusing to retire without confirmation on a non-TTY.\n\n  → next: re-run with --yes.");
+      return 1;
+    }
+    console.log("Aborted — nothing was retired.");
+    return 1;
+  }
+
+  const body = {
+    ...(pr != null ? { pr } : {}),
+    ...(changeId ? { changeId } : {}),
+  };
+
+  let res;
+  try {
+    res = await fetch(`${base}/api/preview/retire`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${secret}`,
+        "x-tot-owner": tenant,
+        "x-tot-capability": "ship-on-behalf",
+      },
+      body: JSON.stringify(body),
+    });
+  } catch (e) {
+    console.error(`✗ could not reach ${base}: ${e?.message || e}\n\n  → next: check --url / your network.`);
+    return 1;
+  }
+
+  let data = {};
+  try {
+    data = await res.json();
+  } catch {
+    /* non-JSON error body */
+  }
+
+  const label = pr != null ? `PR #${pr}` : changeId;
+
+  if (res.ok && data?.ok) {
+    if (data.evicted) {
+      console.log(`✓ Retired ${label} for ${tenant} — the preview was evicted (rebuildable on demand).`);
+    } else {
+      console.log(`✓ Retire ${label} for ${tenant}: nothing to evict (already retired).`);
+    }
+    console.log("\n  → rebuild any time: `tot preview build --tenant " + tenant + (pr != null ? " --pr " + pr : "") + "`\n");
+    return 0;
+  }
+
+  // A refusal (e.g. 409 version-pinned) or an auth/other failure.
+  const message = data?.error || `HTTP ${res.status}`;
+  console.error(`✗ Retire did not succeed (HTTP ${res.status}).`);
+  console.error(`  • ${message}`);
+  return 1;
+}

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