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

package/src/commands/cleanup.mjs

@@ -0,0 +1,268 @@
+/**
+ * `tot cleanup` — owner-confirmed branch GC (P1 items 9+10 of the
+ * branch-lifecycle-and-integration-preview contract's "Current gaps").
+ *
+ * `tot cleanup --dry-run` runs the SAME fresh server-side classification
+ * `tot branches` shows (b13's `candidate_list` MCP tool) and prints exactly
+ * which refs are eligible to delete and WHY — no writes, ever, no matter what
+ * else is passed. An owner-confirmed execution mode (`--yes`, or an
+ * interactive y/N via the shared plan affordance) then deletes ONLY that
+ * exact eligible set: one `candidate_delete` call per ref. The server
+ * RE-CLASSIFIES FRESH before every single delete (see branch-cleanup-tools.ts)
+ * — this CLI's dry-run read is a convenience for the human, never the source
+ * of truth the delete trusts.
+ *
+ * Distinct from `tot retire` (evicts a HOSTED PREVIEW artifact, rebuildable,
+ * touches no git ref) — `tot cleanup` is branch GC: an irreversible ref
+ * delete. See retire.mjs's header for that distinction.
+ *
+ * THE CONTRACT'S HARD RULES, ENFORCED SERVER-SIDE AND NEVER RELAXED HERE:
+ *   - age alone NEVER makes an open candidate deletable (`stale-open` is a
+ *     WARN bucket only);
+ *   - `main`/`preview` classify as `protected` and are never eligible;
+ *   - an `orphan` (no PR record in any state) is quarantined for owner
+ *     review, never auto-deleted.
+ * This CLI does not re-derive eligibility — it only ever deletes a ref the
+ * server's `candidate_list` marked `eligibleForDelete: true` moments earlier,
+ * and the server independently re-checks that before acting.
+ *
+ * Dependency-free (global fetch via mcp.mjs's client + the shared plan module).
+ */
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { fail } from "../errors.mjs";
+import { planForAction, printPlanAndConfirm } from "../plan.mjs";
+import { resolveRepoAndTenant, renderBranchesTable, formatBranchRow } from "./branches.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+const USAGE = `tot cleanup — owner-confirmed branch GC (deletes terminal candidate branches only)
+
+  tot cleanup --dry-run              classify + print the eligible-to-delete set; delete nothing
+  tot cleanup                        classify, print the plan, then ask to confirm before deleting
+  tot cleanup --yes                  classify and delete the eligible set without prompting
+
+  Deletes ONLY branches the server just (re-)classified as "integrated" (PR
+  merged) or "closed-or-rejected" (PR closed without merging). NEVER deletes
+  by age alone, NEVER touches \`main\`/\`preview\`, and NEVER deletes an orphan
+  (no PR record) — orphans are reported, not removed. \`tot retire\` is a
+  DIFFERENT verb: it evicts a hosted preview artifact (rebuildable), not a
+  git branch.
+
+Options:
+  --tenant <appDomain>       Target tenant/repo. Defaults to the current
+                             checkout's tenant when run inside one.
+  --repo <name>              Explicit repo name, if it differs from --tenant.
+  --stale-after-days <n>     Idle-day threshold for the "stale-open" warn
+                             bucket. Defaults to the server's policy (14).
+  --ref <ref>                Narrow deletion to exactly this one eligible ref
+                             (still refused if it isn't eligible).
+  --dry-run                  Classify and print the eligible set; delete nothing.
+  --yes, -y                  Skip the confirmation prompt.
+  --mcp <url>                MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+  --identity <id>            Prefer this cached identity over the default.
+  --help, -h                 Show this help.`;
+
+/** Parse `tot cleanup` argv. Pure — unit-testable. */
+export function parseCleanupArgs(argv) {
+  const a = {
+    tenant: null,
+    repo: null,
+    staleAfterDays: null,
+    ref: null,
+    dryRun: false,
+    yes: false,
+    mcp: null,
+    identity: 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 === "--repo") a.repo = argv[++i];
+    else if (t === "--stale-after-days") a.staleAfterDays = Number(argv[++i]);
+    else if (t === "--ref") a.ref = argv[++i];
+    else if (t === "--dry-run") a.dryRun = true;
+    else if (t === "--yes" || t === "-y") a.yes = true;
+    else if (t === "--mcp") a.mcp = argv[++i];
+    else if (t === "--identity") a.identity = argv[++i];
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+/** Branches the fresh classification marked eligible. Pure. */
+export function eligibleRefs(report) {
+  return (report?.branches || []).filter((b) => b.eligibleForDelete === true);
+}
+
+/** Branches the fresh classification quarantined (orphans). Pure. */
+export function quarantinedRefs(report) {
+  return (report?.branches || []).filter((b) => b.quarantine === true);
+}
+
+/**
+ * Render the dry-run view: the same table `tot branches` renders, then the
+ * exact eligible set + why, then the quarantined orphans + why they are NOT
+ * in that set. Pure — unit-tested.
+ * @param {any} report
+ * @param {ReturnType<typeof eligibleRefs>} eligible
+ * @returns {string[]}
+ */
+export function renderCleanupDryRun(report, eligible) {
+  const lines = [];
+  const repoLabel = report?.repo || "(unknown repo)";
+  lines.push(
+    `Branch cleanup classification for ${repoLabel} — generated ${report?.generatedAtUtc || "(unknown)"} ` +
+      `(stale-after ${report?.staleAfterDays ?? "?"}d)`,
+  );
+  lines.push("");
+  lines.push(...renderBranchesTable((report?.branches || []).map(formatBranchRow)));
+  lines.push("");
+  if (!eligible.length) {
+    lines.push("Eligible to delete: none.");
+  } else {
+    lines.push(`Eligible to delete (${eligible.length}):`);
+    for (const b of eligible) {
+      lines.push(`  ${b.ref}  (${b.sha || "—"})`);
+      lines.push(`    reason: ${b.reason}`);
+    }
+  }
+  const quarantined = quarantinedRefs(report);
+  if (quarantined.length) {
+    lines.push("");
+    lines.push(
+      `Quarantined orphans (${quarantined.length}) — no PR record in any state; NOT deleted, needs owner review:`,
+    );
+    for (const b of quarantined) lines.push(`  ${b.ref}  (${b.sha || "—"})`);
+  }
+  return lines;
+}
+
+/** @param {string[]} argv @param {any} ctx */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseCleanupArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const { repo, tenant, error } = resolveRepoAndTenant(args, ctx);
+  if (error) {
+    console.error(error);
+    return 2;
+  }
+
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createMcpClient(baseUrl);
+  try {
+    await establishSession(client, { env, prefer: args.identity || undefined });
+    if (tenant) await client.callTool("client_switch", { tenant });
+
+    const report = await client.callTool("candidate_list", {
+      repo,
+      ...(args.staleAfterDays != null && Number.isFinite(args.staleAfterDays)
+        ? { staleAfterDays: args.staleAfterDays }
+        : {}),
+    });
+
+    if (report?.status === "error" || report?.status === "invalid_input" || report?.error) {
+      console.error(
+        fail(
+          `couldn't classify branches for ${repo}: ${report.error || report.message || "unknown error"}`,
+          "check --tenant / --repo, then re-run",
+        ),
+      );
+      return 1;
+    }
+
+    let eligible = eligibleRefs(report);
+
+    if (args.ref) {
+      const only = eligible.find((b) => b.ref === args.ref);
+      if (!only) {
+        console.error(
+          fail(
+            `"${args.ref}" is not currently eligible for deletion`,
+            "run `tot cleanup --dry-run` to see the current eligible set",
+          ),
+        );
+        return 1;
+      }
+      eligible = [only];
+    }
+
+    console.log(renderCleanupDryRun(report, eligible).join("\n"));
+
+    if (args.dryRun) {
+      console.log("\nDry run — nothing was deleted.");
+      return 0;
+    }
+    if (!eligible.length) {
+      console.log("\nNothing eligible to delete.");
+      return 0;
+    }
+
+    const planLines = planForAction({
+      action: "cleanup",
+      tenant: tenant || repo,
+      refs: eligible.map((b) => ({ ref: b.ref, sha: b.sha, reason: b.reason })),
+    });
+    const { confirmed, reason } = await printPlanAndConfirm(planLines, {
+      yes: args.yes,
+      question: `Delete these ${eligible.length} eligible branch(es) now?`,
+    });
+    if (!confirmed) {
+      if (reason === "non-tty") {
+        console.error(
+          fail(
+            "refusing to delete branches 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 deleted.");
+      return 1;
+    }
+
+    let failures = 0;
+    for (const b of eligible) {
+      try {
+        const res = await client.callTool("candidate_delete", {
+          repo,
+          ref: b.ref,
+          expectedSha: b.sha,
+        });
+        if (res?.deleted) {
+          console.log(`✓ deleted ${b.ref}${res.alreadyAbsent ? " (already absent)" : ""}`);
+        } else {
+          failures++;
+          console.error(`✗ ${b.ref}: ${res?.error || res?.message || res?.status || "not deleted"}`);
+        }
+      } catch (e) {
+        failures++;
+        console.error(`✗ ${b.ref}: ${String(e?.message || e)}`);
+      }
+    }
+    if (failures) {
+      console.error(`\n${failures} of ${eligible.length} deletion(s) failed — see above.`);
+      return 1;
+    }
+    console.log(`\n✓ deleted ${eligible.length} branch(es).`);
+    return 0;
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      console.error(fail("sign in to clean up branches", e.hint || "run `tot login`, then re-run"));
+      return 1;
+    }
+    console.error(
+      fail(
+        `couldn't reach the candidate service: ${String(e?.message || e)}`,
+        "check your connection and that you're signed in, then re-run",
+      ),
+    );
+    return 1;
+  }
+}