@tokenoftrust/cli 2.0.5 → 2.0.7

package/bin/tot.mjs

@@ -205,11 +205,12 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
-  // `revert --preview <PR|integration-sha>` removes already-integrated content from
-  // the protected `preview` aggregate via a NEW auditable revert commit — NO
-  // force-reset, NO touch to main/live. Backed by POST /api/changes/revert
-  // (TenantIntegrationQueue.enqueueRevert). To undo something already LIVE, that's
-  // `tot rollback`, not this. See revert.mjs's header.
+  // `revert --preview <PR|change-id>` undoes an already-integrated PR out of the
+  // protected `preview` aggregate by opening a NEW corrective candidate and
+  // merging it through the SAME accept pipeline — NO force-reset, NO touch to
+  // main/live. Backed by POST /api/changes/revert (TenantIntegrationQueue.enqueue,
+  // the same pipeline `tot accept` drives). To undo something already LIVE,
+  // that's `tot rollback`, not this. See revert.mjs's header.
   if (cmd === "revert") {
     const { run } = await import("../src/commands/revert.mjs");
     return run(rest, ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/commands/revert.mjs

@@ -1,34 +1,41 @@
 /**
- * `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"
- * (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.
+ * `tot revert --preview <PR|change-id>` — OPERATOR verb: undo an
+ * already-integrated PR OUT of the protected `preview` AGGREGATE by opening a
+ * NEW CORRECTIVE CANDIDATE — cut from the exact state of `preview` the instant
+ * before that PR landed — and running it through the SAME `candidate_open` +
+ * `candidate_accept` pipeline every other change uses. NEVER a force-reset,
+ * NEVER a bespoke revert-commit engine, NEVER a branch delete: Gitea's own real
+ * 3-way merge is the conflict detector, so a genuine overlap with something that
+ * landed since surfaces as an ORDINARY `merge_failed` refusal on that corrective
+ * candidate — the identical shape any other candidate's conflict produces.
  *
- * 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.
+ * DISTINCT from `tot ship`: revert is NOT go-live. It touches NO `main` and NO
+ * live channel; it only corrects 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 (the resolver, inside the tenant-serialized queue lock), and REFUSES a
- * target that was never integrated or has already been reverted.
+ * TARGET — `--preview <target>` names EITHER a PR number (`42` or `#42`) OR the
+ * change's own id (as shown by `tot ship`'s included-PR listing). A numeric
+ * target is sent as `prNumber`; anything else as `changeId`. The server resolves
+ * either against the aggregate's OWN integration-run history to the exact
+ * `preview` state to undo from, and refuses honestly — before opening
+ * anything — when there's nothing TO undo (never integrated, no longer part of
+ * the current aggregate, or already undone).
  *
- * 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
- * state — `queueState` / `runState` / `pointerMoved` / `aggregateSha` /
- * `revertedSha` / `statusMessage` — rendered VERBATIM, never a bare "reverted".
+ * TRANSPORT — `POST /api/changes/revert` (opens the corrective candidate, then
+ * runs it through the SAME `TenantIntegrationQueue.enqueue` accept pipeline
+ * `tot accept` drives). 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` / `changeId` (the
+ * corrective candidate's own id) / `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`).
+ * HUMAN GATE — correcting the shared preview is a decision a human makes, so
+ * this ALWAYS states the EXACT plan (a NEW corrective candidate, merged through
+ * the normal accept pipeline, 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).
  */
@@ -40,28 +47,48 @@ 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)
+// Refusal reasons where there is honestly nothing TO undo right now (never
+// integrated / dropped out of the current aggregate generation / already
+// undone / the first-ever integration with no recorded prior state / the
+// target's own integration commit touched nothing) — a calm, non-alarming
+// message, never framed as an error to fix.
+const NOTHING_TO_UNDO_REASONS = new Set([
+  "not_integrated",
+  "not_currently_integrated",
+  "already_undone",
+  "no_prior_state",
+  "no_changes",
+]);
 
-  tot revert --preview <PR|integration-sha> --tenant <t>
+const RUNBOOK_URI = "runbook://undo-an-integrated-pr-from-the-shared-preview-aggregate";
 
-  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.
+const USAGE = `tot revert — undo an already-integrated PR out of the preview aggregate
 
-  <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.
+  tot revert --preview <PR|change-id> --tenant <t>
 
-  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.
+  Opens a NEW corrective candidate that undoes one prior integration — cut from
+  the exact \`preview\` state just before it landed — and merges it through the
+  SAME accept pipeline every other change uses. The shared preview advances
+  only when that merge lands GREEN. This is NEVER a force-reset and NEVER
+  deletes commits — full history is preserved. It does NOT touch main and does
+  NOT go live.
+
+  <PR|change-id> is EITHER a PR number (e.g. 42 or #42) OR the change's own id.
+  A target that was never integrated, is no longer part of the current
+  aggregate, or has already been undone, is refused before anything is opened.
+  A genuine conflict (something else touched the same content since) opens the
+  corrective candidate anyway and reports it honestly — resolve it with
+  \`tot preview resolve\`, or hand ${RUNBOOK_URI} to your AI agent.
+
+  Correcting 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.
+  --preview <PR|change-id>  REQUIRED. The PR number or change id to undo.
   --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.
+  --message <msg>        Optional note recorded on the corrective candidate.
   --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
@@ -98,23 +125,31 @@ export function parseRevertArgs(argv) {
 }
 
 /**
- * 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.
+ * Classify a `--preview` target into `{ prNumber }` or `{ changeId }`. A bare
+ * integer (optionally `#`-prefixed) is a PR number; anything else is the
+ * change's own id, sent verbatim (the server resolves either against the
+ * aggregate's own integration-run history — no local sha/shape validation).
+ * Pure — unit-tested.
  * @param {string|null} raw
- * @returns {{ prNumber:number|null, integrationSha:string|null }}
+ * @returns {{ prNumber:number|null, changeId: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 };
+  if (!t) return { prNumber: null, changeId: null };
+  if (/^\d+$/.test(t)) return { prNumber: Number(t), changeId: null };
+  return { prNumber: null, changeId: 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.
+ *
+ * `changeId` here is the SERVER's response field — the corrective candidate's
+ * own id (`undo-<original>`), not the CLI's `--preview` input. There is no
+ * "revertedSha" concept anymore (undo is a merge, not a direct commit rewrite);
+ * `aggregateSha` is the honest replacement — the aggregate sha the corrective
+ * candidate landed at.
  * @param {any} data
  */
 export function normalizeRevertResponse(data) {
@@ -125,7 +160,6 @@ export function normalizeRevertResponse(data) {
     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,
@@ -135,8 +169,9 @@ export function normalizeRevertResponse(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.
+ * 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}
@@ -144,19 +179,31 @@ export function normalizeRevertResponse(data) {
 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(`\n  ✓ undid ${label} in ${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.");
+    if (result.changeId) console.log(`  corrective candidate: ${result.changeId}`);
+    if (result.pointerMoved) console.log("  the shared preview pointer moved to the corrected 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.`);
+  // Honest non-green: the undo did NOT land in the shippable aggregate.
+  console.log(`\n  ✗ ${label} was NOT undone in ${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.`);
+
+  if (result.reason === "merge_failed") {
+    // A genuine conflict: the corrective candidate WAS opened, but something
+    // else touched the same content since — the ordinary conflict path, not a
+    // special "revert" failure. Point at the manual/agent recovery, naming the
+    // ALREADY-OPEN candidate so it's resolved, not re-derived from scratch.
+    console.log("  → this is a genuine merge conflict: something else touched the same content since.");
+    console.log("  → resolve it with `tot preview resolve`, or hand this to your AI agent:");
+    console.log(`      Read ${RUNBOOK_URI} via the Token of Trust MCP and follow it.`);
+    if (result.changeId) {
+      console.log(`      The corrective candidate "${result.changeId}" is ALREADY OPEN — resolve that one, don't start over.`);
+    }
+  } else if (result.reason && NOTHING_TO_UNDO_REASONS.has(result.reason)) {
+    console.log(`  → nothing to do here: ${label} isn't something this can currently undo.`);
   } else {
     console.log("  → the aggregate is unchanged (last green preserved); fix forward or retry.");
   }
@@ -169,43 +216,44 @@ export function reportReverted(result, { tenant, label }) {
  * aggregate status. `fetch`/`confirmPlan` injected so it is unit-tested with no
  * network/TTY.
  *
- * @param {{ tenant:string, prNumber:number|null, integrationSha:string|null,
+ * @param {{ tenant:string, prNumber:number|null, changeId: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 },
+  { tenant, prNumber, changeId, 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}`;
+  const label = prNumber != null ? `PR #${prNumber}` : `change ${changeId}`;
 
-  // 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.
+  // 1. State the EXACT plan (shared affordance) — a NEW corrective candidate
+  //    merged through the normal accept pipeline, NO force-reset, NO touch to
+  //    main/live — and gate on a confirm.
   const planLines = planForAction({
     action: "revert",
     tenant,
     pr: prNumber,
-    integrationSha,
+    changeId,
   });
   const { confirmed, reason } = await confirmPlan(planLines, {
     yes,
-    question: `Revert ${label} out of ${tenant}'s preview aggregate (a new revert commit)?`,
+    question: `Undo ${label} out of ${tenant}'s preview aggregate (a new corrective candidate)?`,
   });
   if (!confirmed) {
     if (reason === "non-tty") {
       console.error(
         fail(
-          "refusing to revert without confirmation on a non-TTY.",
+          "refusing to undo 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.");
+    console.log("Aborted — nothing was undone.");
     return 1;
   }
 
@@ -213,7 +261,7 @@ export async function runRevert(
   if (!secret) {
     console.error(
       fail(
-        "reverting the preview aggregate is an OPERATOR action — it needs an operator secret",
+        "undoing an integrated PR is an OPERATOR action — it needs an operator secret",
         "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
       ),
     );
@@ -228,11 +276,11 @@ export async function runRevert(
   const requestBody = {
     repo: tenant,
     ...(prNumber != null ? { prNumber } : {}),
-    ...(integrationSha ? { integrationSha } : {}),
+    ...(changeId ? { changeId } : {}),
     ...(message ? { message } : {}),
   };
 
-  // 3. POST the honest revert path (queue enqueueRevert) and render terminal state.
+  // 3. POST the honest undo-as-candidate path and render the terminal state.
   let res;
   try {
     res = await fetchImpl(`${base}/api/changes/revert`, {
@@ -296,12 +344,12 @@ export async function run(argv, ctx) {
     return 2;
   }
 
-  const { prNumber, integrationSha } = classifyRevertTarget(args.preview);
-  if (prNumber == null && !integrationSha) {
+  const { prNumber, changeId } = classifyRevertTarget(args.preview);
+  if (prNumber == null && !changeId) {
     console.error(
       fail(
         "no revert target.",
-        "pass --preview <PR|integration-sha> (a PR number like 42, or an exact preview integration SHA).",
+        "pass --preview <PR|change-id> (a PR number like 42, or the change's own id).",
       ),
     );
     return 2;
@@ -313,7 +361,7 @@ export async function run(argv, ctx) {
   return await runRevert({
     tenant,
     prNumber,
-    integrationSha,
+    changeId,
     message: (args.message || "").trim() || null,
     secret: resolveOperatorSecret(args.secret, env),
     storefrontUrl,

package/src/git-credential.mjs

@@ -159,7 +159,15 @@ export function forgeShimPath(env = process.env) {
 /** The shim's contents: pin the ABSOLUTE node + CLI entry active at write time, with a
  *  PATH-search fallback for node, and FAIL LOUD to stderr (never silently) when no node
  *  is found — so a broken helper says how to fix itself instead of yielding an opaque
- *  "Repository not found". Pure — unit-tested. */
+ *  "Repository not found". Pure — unit-tested.
+ *
+ *  The pinned ENTRY gets the same fail-loud treatment as NODE, because the path pinned at
+ *  write time can stop existing: running the CLI from a dev checkout or a git worktree pins
+ *  the shim to THAT tree, and reaping it breaks forge git auth for every checkout on the
+ *  machine — including ones created by the globally-installed `tot`. Unguarded, the failure
+ *  surfaces three layers away as a raw node MODULE_NOT_FOUND followed by git's
+ *  "could not read Username" / "Repository not found", which names neither the stale path
+ *  nor the fix. */
 export function renderForgeShim(nodePath, entryPath) {
   return [
     "#!/bin/sh",
@@ -171,7 +179,18 @@ export function renderForgeShim(nodePath, entryPath) {
     '  echo "tot: no node runtime for the git credential helper — reinstall: npm i -g @tokenoftrust/cli@latest" >&2',
     "  exit 1",
     "fi",
-    `exec "$NODE" ${shq(entryPath)} git-credential "$@"`,
+    `ENTRY=${shq(entryPath)}`,
+    'if [ ! -f "$ENTRY" ]; then',
+    '  echo "tot: the git credential helper points at a CLI that no longer exists:" >&2',
+    '  echo "       $ENTRY" >&2',
+    '  echo "     This shim was pinned by whichever tot ran last — if that was a dev" >&2',
+    '  echo "     checkout or a git worktree that has since been removed, forge git auth" >&2',
+    '  echo "     is broken for EVERY checkout on this machine until it is re-pinned." >&2',
+    '  echo "     Fix: run any tot command that touches git (e.g. \\`tot clone <tenant>\\`)" >&2',
+    '  echo "     from an installed tot, or reinstall: npm i -g @tokenoftrust/cli@latest" >&2',
+    "  exit 1",
+    "fi",
+    'exec "$NODE" "$ENTRY" git-credential "$@"',
     "",
   ].join("\n");
 }

package/src/plan.mjs

@@ -162,14 +162,17 @@ export function planForAction({
       break;
     }
     case "revert": {
-      // Revert: REMOVE already-integrated content from the protected `preview`
-      // aggregate by creating a NEW auditable revert commit — never a force-reset,
-      // never a branch delete. The aggregate rebuilds and ships only when green
-      // again. State exactly that: preview-only, a new commit, NO touch to main.
+      // Undo: pull an already-integrated PR back OUT of the protected `preview`
+      // aggregate by opening a NEW corrective candidate — cut from the exact
+      // `preview` state just before it landed — and merging it through the SAME
+      // accept pipeline every other change uses. Never a force-reset, never a
+      // bespoke revert-commit engine, never a branch delete: a genuine conflict
+      // with something that landed since surfaces as an ordinary merge_failed
+      // on that candidate. State exactly that: preview-only, no touch to main.
       const from = tenant ? `${tenant}'s preview aggregate` : "the preview aggregate";
-      const what = integrationSha ? `integration ${integrationSha}` : label;
       lines.push(
-        `  effect:    revert ${what} out of ${from} — a NEW revert commit, NO force-reset, NO merge to main, NO go-live.`,
+        `  effect:    undo ${label} — open a NEW corrective candidate that undoes it, ` +
+          `then attempt to merge it into ${from}. NO force-reset, NO merge to main, NO go-live.`,
       );
       break;
     }