feat(snapshot): gcSnapshots + ocp update --rollback --gc + auto-GC; v3.16.0 (#94)

Adds snapshot garbage collection with retention policy: keep last 5,
keep snapshots within 30 days, always keep the most recent. Configurable
via keepCount / keepDays opts.

Wire-up:
- ocp update --rollback --gc (manual trigger; --dry-run supported)
- runFullUpgrade auto-GC after successful upgrade (best-effort,
  swallows errors)

4 unit tests: keepCount enforcement, keepDays override, never-delete-
most-recent safety, dry-run mode.

Bumps to v3.16.0 (bundles PR #93 --check oauth + this GC feature).

No cli.js citation needed: this is OCP-internal snapshot lifecycle with
no corresponding cli.js operation.

Co-authored-by: dtzp555 <dtzp555@gmail.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

scripts/lib/snapshot.mjs

@@ -1,4 +1,4 @@
-import { mkdirSync, writeFileSync, readFileSync, copyFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { mkdirSync, writeFileSync, readFileSync, copyFileSync, existsSync, readdirSync, statSync, rmSync } from "node:fs";
 import { join } from "node:path";
 
 export function writeSnapshot({ homeDir, fromCommit, fromVersion, toVersion, extraFiles = [] }) {
@@ -50,3 +50,66 @@ export function listSnapshots(homeDir) {
     .map(name => ({ name, path: join(root, name), mtime: statSync(join(root, name)).mtimeMs }))
     .sort((a, b) => a.name.localeCompare(b.name));
 }
+
+/**
+ * Garbage-collect old upgrade snapshots.
+ *
+ * Retention rule (a snapshot is KEPT if any of these is true):
+ *   - It is among the last `keepCount` snapshots (sorted oldest→newest)
+ *   - Its timestamp is within `keepDays` of `now`
+ *   - It is the single most-recent snapshot (always-keep safety net)
+ *
+ * @param {string} homeDir - Root containing ~/.ocp/
+ * @param {object} opts
+ * @param {number} [opts.keepCount=5] - Minimum count to keep
+ * @param {number} [opts.keepDays=30] - Keep snapshots newer than N days
+ * @param {boolean} [opts.dryRun=false] - If true, report plan but don't delete
+ * @param {Date} [opts.now=new Date()] - Override clock for testing
+ * @returns {{kept: Array, removed: Array, dryRun: boolean}}
+ */
+export function gcSnapshots(homeDir, opts = {}) {
+  const keepCount = opts.keepCount ?? 5;
+  const keepDays = opts.keepDays ?? 30;
+  const dryRun = !!opts.dryRun;
+  const now = opts.now || new Date();
+
+  const all = listSnapshots(homeDir);  // sorted oldest→newest
+  if (all.length === 0) return { kept: [], removed: [], dryRun };
+  if (all.length === 1) return { kept: all, removed: [], dryRun };  // always keep most recent
+
+  const cutoffMs = now.getTime() - keepDays * 24 * 60 * 60 * 1000;
+  const lastN = new Set(all.slice(-keepCount).map(s => s.path));
+
+  const kept = [], removed = [];
+  for (let i = 0; i < all.length; i++) {
+    const s = all[i];
+    const isMostRecent = i === all.length - 1;
+    const isInLastN = lastN.has(s.path);
+    const isWithinDays = parseSnapshotTimestamp(s.name) >= cutoffMs;
+    if (isMostRecent || isInLastN || isWithinDays) {
+      kept.push(s);
+    } else {
+      removed.push(s);
+    }
+  }
+
+  if (!dryRun) {
+    for (const s of removed) {
+      try {
+        rmSync(s.path, { recursive: true, force: true });
+      } catch (err) {
+        console.error(`[snapshot] warn: could not remove ${s.path} (${err.code || err.message})`);
+      }
+    }
+  }
+
+  return { kept, removed, dryRun };
+}
+
+function parseSnapshotTimestamp(name) {
+  // upgrade-snapshot-2026-05-11T08:30:00Z → epoch ms
+  const m = name.match(/upgrade-snapshot-(.+)$/);
+  if (!m) return 0;
+  const t = Date.parse(m[1]);
+  return Number.isFinite(t) ? t : 0;
+}

scripts/upgrade.mjs

@@ -14,7 +14,7 @@ import { execSync } from "node:child_process";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { existsSync, copyFileSync } from "node:fs";
-import { writeSnapshot, listSnapshots, readSnapshot } from "./lib/snapshot.mjs";
+import { writeSnapshot, listSnapshots, readSnapshot, gcSnapshots } from "./lib/snapshot.mjs";
 
 export async function runUpgrade(opts = {}) {
   const dryRun = !!opts.dryRun;
@@ -154,6 +154,16 @@ async function runFullUpgrade({ doctor, opts }) {
       phases.push({ name: "post-flight", status: "skipped-mock" });
     }
 
+    // Auto-GC old snapshots after successful upgrade (best-effort, never throws).
+    try {
+      const gc = gcSnapshots(homedir(), { keepCount: 5, keepDays: 30 });
+      if (gc.removed.length > 0) {
+        console.error(`[gc] removed ${gc.removed.length} old snapshots; kept ${gc.kept.length}`);
+      }
+    } catch (e) {
+      console.error(`[gc] warn: snapshot GC failed: ${e.message}`);
+    }
+
     return { path: "upgrade", executed: true, changed: true, snapshotPath, phases };
   } catch (err) {
     if (snapshotPath && !err.snapshotPath) {
@@ -193,6 +203,11 @@ async function runRollback(opts) {
   const homeDir = opts.homeDir || homedir();
   const snapshots = opts.mockSnapshots ?? listSnapshots(homeDir);
 
+  if (opts.gc) {
+    const result = gcSnapshots(homeDir, { dryRun: opts.dryRun });
+    return { path: opts.dryRun ? "rollback-gc-dry-run" : "rollback-gc", ...result };
+  }
+
   if (opts.list) {
     return { path: "rollback-list", snapshots };
   }
@@ -295,6 +310,7 @@ if (_isMain()) {
   const yes = args.includes("--yes");
   const rollback = args.includes("--rollback");
   const list = args.includes("--list");
+  const gc = args.includes("--gc");
   const targetIdx = args.indexOf("--target");
   const target = targetIdx !== -1 ? args[targetIdx + 1] : undefined;
   // First non-flag positional after --rollback is the snapshot path
@@ -305,7 +321,7 @@ if (_isMain()) {
     if (cand && !cand.startsWith("--")) snapshotPath = cand;
   }
   try {
-    const result = await runUpgrade({ dryRun, yes, rollback, list, snapshotPath, target });
+    const result = await runUpgrade({ dryRun, yes, rollback, list, gc, snapshotPath, target });
     if (result.plan) for (const line of result.plan) console.log(line);
     if (result.phases) for (const p of result.phases) console.log(`[${p.name}] ${p.status}${p.cmd ? `: ${p.cmd}` : ""}`);
     if (result.steps) for (const s of result.steps) console.log(`  ${s.status === "ok" ? "✓" : s.status === "skipped-mock" ? "·" : "✗"} ${s.cmd}`);
@@ -313,6 +329,10 @@ if (_isMain()) {
       console.log(`Found ${result.snapshots.length} snapshots:`);
       for (const s of result.snapshots) console.log(`  ${s.name}`);
     }
+    if (result.removed && result.kept) {
+      console.log(`Snapshots: kept ${result.kept.length}, ${result.dryRun ? "would remove" : "removed"} ${result.removed.length}`);
+      for (const s of result.removed) console.log(`  - ${s.name}`);
+    }
     process.exit(0);
   } catch (e) {
     console.error(`✗ ${e.message}`);