@tokenoftrust/cli 1.4.1 → 1.5.0

package/src/commands/preview-doctor.mjs

@@ -0,0 +1,225 @@
+/**
+ * `tot preview doctor --tenant <t>` — the merge self-serve DIAGNOSIS in the terminal.
+ *
+ * Calls the hosted merge-doctor seam `GET /<tenant>/api/preview/merge-doctor`
+ * — which composes the SAME two server-side reads the admin Publish tab builds
+ * (`GET /api/changes` + `GET /api/changes/branches`) through the PURE `analyzeMerge`
+ * taxonomy — and prints its `{ scopeKnown, verdict, findings, counts }` as the compact,
+ * ordered (blocker → warn → info) report, each finding carrying who-owns-it and its
+ * remedy/action. It composes NO per-PR forge calls of its own: one GET, one answer.
+ *
+ * READ-ONLY — it mutates nothing, so there is NO plan/confirm gate (unlike `tot
+ * accept` / `tot preview build`). It just answers "what's blocking my merges, and
+ * what do I do about it?" in seconds.
+ *
+ * AUTH — the endpoint is session-gated exactly like `GET /api/changes`, so this
+ * reaches it by EITHER of the two transports `tot accept` already speaks:
+ *   - OPERATOR SECRET (operators / headless CI): Bearer + `X-Tot-Owner` on the
+ *     generic storefront origin (from PREVIEW_RECONCILE_SECRET / GRANTS_ADMIN_SECRET
+ *     / TOT_OPERATOR_SECRET, or `--secret`).
+ *   - VIEWER SESSION (an invited developer with no secret): mint a `tot_session`
+ *     from their own `tot login` on the tenant's own host (`resolveViewerTransport`).
+ * A caller who cannot see the accept queue cannot get a diagnosis of it — an auth
+ * refusal (401/403) is relayed as a clean house-style failure, not a wrapped verdict.
+ *
+ * EXIT CODE — mirrors the `scripts/tenant/gitea-merge-doctor.mjs` driver: a report
+ * with any blocker exits 1 (so a CI gate fails on a blocked merge), otherwise 0.
+ *
+ * The rendering helpers are the SHARED port in `../merge-doctor-report.mjs` (a
+ * faithful PORT of the analyzer's own `formatReport`/`attentionBanner`/
+ * `supportContext` — mergeDoctor.ts §render / the gitea-merge-doctor.mjs mirror);
+ * this package is the dependency-free published `@tokenoftrust/cli`, so it cannot
+ * import the app/scripts source, and the port is kept in sync with that taxonomy by
+ * hand. They live in their own module so `tot accept` / `tot ship` can reuse the same
+ * fetch + compact render without a cycle back through this command's transports.
+ *
+ * Dependency-free (global fetch + the shared viewer/operator transports).
+ */
+import { fail } from "../errors.mjs";
+import { resolveOperatorSecret } from "./ship.mjs";
+import { resolveViewerTransport } from "../viewer-session.mjs";
+import {
+  DOCTOR_PATH,
+  normalizeAnalysis,
+  attentionBanner,
+  supportContext,
+  formatReport,
+} from "../merge-doctor-report.mjs";
+
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+const USAGE = `tot preview doctor — diagnose what's blocking this tenant's merges
+
+  tot preview doctor                    diagnose the current checkout's tenant
+  tot preview doctor --tenant <t>       diagnose <t> (works without a checkout)
+  tot preview doctor --json             emit the raw { scopeKnown, verdict, findings, counts }
+
+  Calls the hosted merge-doctor (GET /api/preview/merge-doctor), which composes the
+  SAME reads the admin Publish tab builds and runs them through the shared analyzer,
+  and prints the ordered report: blockers first, then warnings, then info — each
+  finding names who resolves it (you / on-us / housekeeping) and the exact remedy.
+  Read-only: it mutates nothing and needs no confirmation.
+
+  Exit code: 1 if the report has any blocker (so it can gate CI), else 0.
+
+Options:
+  --tenant <appDomain>   Target tenant (e.g. tokenoftrust.com). Defaults to the
+                         current checkout's tenant when run inside one.
+  --url <origin>         Storefront origin for the operator-secret path
+                         (default: env TOT_STOREFRONT_URL or ${DEFAULT_STOREFRONT_URL}).
+  --secret <s>           Operator secret (prefer the env vars below).
+  --json                 Print the raw analysis JSON instead of the report.
+  --help, -h             Show this help.
+
+  Operator secret (from env, first found): PREVIEW_RECONCILE_SECRET,
+  GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET (or pass --secret). Without one, an
+  invited developer's own \`tot login\` session is used.`;
+
+/** Parse `tot preview doctor` argv. Pure — unit-testable. */
+export function parsePreviewDoctorArgs(argv) {
+  const a = { tenant: null, url: null, secret: null, json: 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 === "--url") a.url = argv[++i];
+    else if (t === "--secret") a.secret = argv[++i];
+    else if (t === "--json") a.json = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+// The render/normalize helpers (normalizeAnalysis / attentionBanner /
+// supportContext / formatReport) are the shared port in ../merge-doctor-report.mjs,
+// imported at the top of this file.
+
+// ── run ────────────────────────────────────────────────────────────────────────
+
+/**
+ * Fetch + render the merge-doctor report for one tenant. Resolves the SAME two
+ * transports `tot accept` uses (operator secret → generic origin + X-Tot-Owner;
+ * else viewer session → tenant host + cookie), GETs the hosted seam, and prints the
+ * ordered report (or raw JSON). `fetch`/`resolveViewerTransport` are injected so it
+ * is unit-tested with no network. Returns the process exit code (blocker → 1).
+ *
+ * @param {{ tenant:string, secret:string, storefrontUrl?:string|null,
+ *   json?:boolean, env?:NodeJS.ProcessEnv }} params
+ * @param {{ fetch?:typeof fetch, resolveViewerTransport?:typeof resolveViewerTransport }} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runDoctor(
+  { tenant, secret, storefrontUrl = null, json = false, env = process.env },
+  deps = {},
+) {
+  const fetchImpl = deps.fetch || globalThis.fetch;
+  const resolveViewer = deps.resolveViewerTransport || resolveViewerTransport;
+
+  // Resolve the transport — operator secret preferred, else the developer's own
+  // viewer session on the tenant host.
+  let base;
+  let authHeaders;
+  if (secret) {
+    base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+    authHeaders = {
+      authorization: `Bearer ${secret}`,
+      "x-tot-owner": tenant,
+      "x-tot-capability": "ship-on-behalf",
+    };
+  } else {
+    const viewer = await resolveViewer({ tenant, env, fetchImpl });
+    if (!viewer.ok) {
+      console.error(fail(viewer.message, viewer.hint));
+      return 2;
+    }
+    base = viewer.base;
+    authHeaders = viewer.authHeaders;
+  }
+
+  let res;
+  try {
+    res = await fetchImpl(`${base}${DOCTOR_PATH}`, { method: "GET", headers: authHeaders });
+  } catch (e) {
+    console.error(
+      fail(
+        `couldn't reach the merge-doctor 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 */
+  }
+
+  // Session gating: the endpoint relays the queue read's auth refusal verbatim, so a
+  // caller who cannot see the accept queue cannot diagnose it.
+  if (res.status === 401 || res.status === 403) {
+    console.error(
+      fail(
+        `not authorized to diagnose ${tenant}'s merges: ${data?.error || `HTTP ${res.status}`}`,
+        "you need a live ship-on-behalf grant on this tenant (ask the store owner), or an operator secret authorised for it — then re-run",
+      ),
+    );
+    return 2;
+  }
+
+  if (!res.ok) {
+    console.error(
+      fail(
+        `the merge-doctor did not answer for ${tenant}: ${data?.error || `HTTP ${res.status}`}`,
+        "check --tenant / --url, then re-run",
+      ),
+    );
+    return 1;
+  }
+
+  const analysis = normalizeAnalysis(data);
+
+  if (json) {
+    console.log(JSON.stringify(analysis, null, 2));
+  } else {
+    console.log(formatReport(analysis));
+  }
+
+  // Mirror the scripts driver: any blocker fails the run so a CI gate catches it.
+  return analysis.counts.blocker > 0 ? 1 : 0;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx — detected CLI context (ctx.tenant when in a checkout)
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parsePreviewDoctorArgs(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 storefrontUrl =
+    args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+
+  return await runDoctor({
+    tenant,
+    secret: resolveOperatorSecret(args.secret, env),
+    storefrontUrl,
+    json: args.json,
+    env,
+  });
+}

package/src/commands/preview-retry-evidence.mjs

@@ -0,0 +1,156 @@
+/**
+ * `tot preview retry-evidence --tenant <t> --pr <N>` — OPERATOR recovery verb.
+ *
+ * Re-push evidence for an ALREADY-BUILT candidate whose `change_report_evidence`
+ * push to MCP failed (surfaced as `evidence.pushFailed` on the candidate — see
+ * `formatOperatorCandidateLine`'s `[evidence push failed]` tag in `tot pr list
+ * --tenant`). Calls the session-authenticated `POST
+ * /api/changes/candidate-evidence-retry`, which recomputes + re-pushes evidence
+ * for the candidate's EXISTING version — no rebuild, no new content, safe to
+ * run repeatedly.
+ *
+ * DISTINCT FROM `tot preview build`: build re-runs the full reconcile against a
+ * head sha (for an orphaned/never-built PR). This targets an ALREADY-ready
+ * candidate whose content is fine but whose evidence never reached MCP — a
+ * narrower, cheaper fix for fb-1787938036559-ppmu4e.
+ *
+ * AUTH — same headless Bearer-operator-secret path as `tot preview build`:
+ * `Authorization: Bearer <secret>`, `X-Tot-Owner: <tenant>`,
+ * `X-Tot-Capability: ship-on-behalf`.
+ *
+ * Non-destructive + idempotent — no confirmation prompt.
+ *
+ * Dependency-free (global fetch).
+ */
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+/** Parse `tot preview retry-evidence` argv. Pure — unit-testable. */
+export function parseRetryEvidenceArgs(argv) {
+  const a = { tenant: null, pr: null, changeId: null, url: null, secret: null, 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 === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+export function renderUsage() {
+  return `tot preview retry-evidence — operator recovery: re-push a candidate's evidence to MCP
+
+Usage:
+  tot preview retry-evidence --tenant <appDomain> --pr <N> [options]
+  tot preview retry-evidence --tenant <appDomain> --change-id <id> [options]
+
+Re-computes and re-pushes evidence for an ALREADY-BUILT candidate whose MCP
+push failed (shown as "[evidence push failed]" in \`tot pr list --tenant\`).
+Does NOT rebuild or change content — safe to run repeatedly.
+
+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 retry evidence for.
+  --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.
+  --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 = parseRetryEvidenceArgs(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 retry evidence for.\n\n  → next: pass --pr <N> (the PR number), 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;
+  }
+
+  const body = {
+    ...(pr != null ? { pr } : {}),
+    ...(changeId ? { changeId } : {}),
+  };
+
+  let res;
+  try {
+    res = await fetch(`${base}/api/changes/candidate-evidence-retry`, {
+      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 && data?.pushed) {
+    console.log(`✓ Evidence re-pushed for ${label} on ${tenant} (promotable: ${data.promotable}).`);
+    return 0;
+  }
+  if (res.ok && data?.ok && !data?.pushed) {
+    console.error(`✗ Evidence push still failed for ${label} on ${tenant}.`);
+    if (data.error) console.error(`  • ${data.error}`);
+    console.error("\n  → next: check MCP reachability, then re-run this command.");
+    return 1;
+  }
+
+  const message = data?.error || `HTTP ${res.status}`;
+  console.error(`✗ Retry did not succeed (HTTP ${res.status}).`);
+  console.error(`  • ${message}`);
+  return 1;
+}

package/src/commands/preview.mjs

@@ -5,7 +5,7 @@
  *
  *   tot dev        run your store locally with save→reload
  *   tot preview    push it to a reviewable preview (validate → reconcile → compliance)  ← you are here
- *   tot ship       promote a reconciled preview live                                     ← unit u3
+ *   tot ship       promote a reconciled preview live
  *
  * The whole preview flow (validate, push the preview ref, open/update the PR-backed
  * candidate, stream the reconcile/compliance/preview result) lives in submit.mjs — this
@@ -45,12 +45,12 @@ export function postRunHint(code, alias) {
 /**
  * @param {string[]} argv
  * @param {any} ctx
- * @param {{ alias?: string|null }} [opts] — `alias` is the old verb the developer typed
+ * @param {{ alias?: string|null }} [opts] - `alias` is the old verb the developer typed
  *   (`"submit"` / `"deploy"`) when this flow is reached as a teaching alias; null/omitted
  *   for the first-class `tot preview`.
  */
 export async function run(argv, ctx, { alias = null } = {}) {
-  // `tot preview build …` is the OPERATOR build-on-demand subcommand (unit U3) —
+  // `tot preview build …` is the OPERATOR build-on-demand subcommand —
   // a distinct verb from the developer preview flow, so it's dispatched BEFORE the
   // submit-flow arg parse. Only the first-class `tot preview` carries it (not the
   // `submit`/`deploy` teaching aliases, which are the push-your-checkout flow).
@@ -59,6 +59,22 @@ export async function run(argv, ctx, { alias = null } = {}) {
     return runBuild(argv.slice(1), ctx);
   }
 
+  // `tot preview doctor …` is the read-only merge DIAGNOSIS subcommand —
+  // a distinct verb from the developer preview flow, dispatched before the submit-
+  // flow arg parse (like `build`). Only the first-class `tot preview` carries it.
+  if (!alias && argv[0] === "doctor") {
+    const { run: runDoctor } = await import("./preview-doctor.mjs");
+    return runDoctor(argv.slice(1), ctx);
+  }
+
+  // `tot preview retry-evidence …` is the OPERATOR recovery subcommand for a
+  // candidate whose evidence push to MCP failed (fb-1787938036559-ppmu4e) —
+  // dispatched before the submit-flow arg parse, like `build`/`doctor`.
+  if (!alias && argv[0] === "retry-evidence") {
+    const { run: runRetryEvidence } = await import("./preview-retry-evidence.mjs");
+    return runRetryEvidence(argv.slice(1), ctx);
+  }
+
   const verb = alias || "preview";
   const args = parseArgs(argv);
 

package/src/commands/revert.mjs

@@ -1,5 +1,5 @@
 /**
- * `tot revert --preview <PR|integration-sha>` (unit b21) — OPERATOR verb: REMOVE
+ * `tot revert --preview <PR|integration-sha>` — 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"
@@ -15,10 +15,10 @@
  * 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
+ * undo (the 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
+ * TRANSPORT — `POST /api/changes/revert` (the ONE call site of
  * `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
@@ -183,7 +183,7 @@ export async function runRevert(
   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
+  // 1. State the EXACT plan (shared 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",
@@ -232,7 +232,7 @@ export async function runRevert(
     ...(message ? { message } : {}),
   };
 
-  // 3. POST the honest revert path (b07 queue enqueueRevert) and render terminal state.
+  // 3. POST the honest revert path (queue enqueueRevert) and render terminal state.
   let res;
   try {
     res = await fetchImpl(`${base}/api/changes/revert`, {

package/src/commands/rollback.mjs

@@ -7,17 +7,17 @@
  *   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` /
+ * through the 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
+ * orchestrator composes.
+ * There is no ship-orchestrator service in-tree yet, so this calls that 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
+ * Fail-closed: 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
@@ -41,7 +41,7 @@ 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
+// The only publish channel the seam is exercised against today (see the 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";
@@ -63,7 +63,9 @@ const USAGE = `tot rollback [<versionId>] — instant re-point to a prior live v
 
 /** Parse `tot rollback` argv. Pure. Deliberately NO --yes/--force (see the header). */
 export function parseRollbackArgs(argv) {
+  /** @type {{ versionId: string|null, target: string|null, mcp: string|null, identity: string|null, help: boolean }} */
   const a = { versionId: null, target: null, mcp: null, identity: null, help: false };
+  /** @type {string[]} */
   const positional = [];
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
@@ -138,11 +140,11 @@ export function normalizeRollbackResult(r) {
   };
 }
 
-// ─── Revision links (pure, unit u5) ───────────────────────────────────────────────
+// ─── Revision links (pure) ───────────────────────────────────────────────
 
 /**
  * The immutable `/preview/<tenant>/rev/<sha>/` deep-link for a promoted
- * `versionId` — u4's route, and per `gitea-only-tenant-content-authority` the
+ * `versionId` — this 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.
@@ -177,10 +179,10 @@ export function rollbackCandidates(history, currentVersionId) {
 }
 
 /** 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
+ *  picker, each entry annotated with its immutable `/rev/<sha>` link
+ *  when a storefront origin is available. Pure — unit-tested.
+ * @param {{ tenant:string, target:string, current:any,
+ *   candidates:any[], revisionBase?:string|null }} input
  * @returns {string[]}
  */
 export function renderHistory({ tenant, target, current, candidates, revisionBase }) {
@@ -209,7 +211,7 @@ export function renderHistory({ tenant, target, current, candidates, revisionBas
  */
 export function renderRollbackPreview({ tenant, target, toVersionId, preview }) {
   const lines = ["", `  This rollback will change the LIVE site for ${tenant}:`];
-  const current = preview.pointer?.current;
+  const current = /** @type {any} */ (preview.pointer?.current);
   if (current) lines.push(`    ${target}: ${current.versionId} → ${toVersionId}`);
   else lines.push(`    ${target}: → ${toVersionId}`);
   return lines;
@@ -225,7 +227,7 @@ export function renderRollbackPreview({ tenant, target, toVersionId, preview })
  * @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
+ *   the listing's `/rev/<sha>` links resolve against; omit to list
  *   without links.
  * @param {{ interactive?:()=>boolean, confirm?:(q:string,d:boolean)=>Promise<boolean>,
  *   progress?:boolean }} [deps]
@@ -258,7 +260,7 @@ export async function runRollback(client, { tenant, target, toVersionId, revisio
       );
       return 1;
     }
-    const candidates = rollbackCandidates(status.history, status.current?.versionId ?? null);
+    const candidates = rollbackCandidates(status.history, /** @type {any} */ (status).current?.versionId ?? null);
     for (const line of renderHistory({ tenant, target, current: status.current, candidates, revisionBase })) {
       console.log(line);
     }
@@ -375,8 +377,8 @@ export async function run(argv, ctx) {
   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.
+  // The storefront origin the listing's /rev/<sha> links resolve against
+  // — 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 {