@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/lib/worktree/finish-backup.js

@@ -1,52 +1,6 @@
-/**
- * finish-backup.js — the backups `finish` and `worktree remove` leave under
- * `.git/morph-spec/finish-backup/`: how one is written, how they are listed,
- * and how long each one lives.
- *
- * A backup exists so that removing a worktree (or shedding the root-side
- * scaffold) never destroys the only exemplar of a file. That is a reason to keep
- * the last ones, not all of them, and a worktree's `.env.e2e` — the e2e stack's
- * credentials — has no business living inside `.git/` indefinitely. So every
- * backup is subject to a retention policy, on by default:
- *
- *   maxCount          — the newest this many backups per namespace always stay
- *   maxAgeDays        — no age cut unless configured: a quiet month must never
- *                       empty the backups of the last features closed
- *   secretMaxAgeDays  — `.env*` files inside a backup go away after this
- *
- * `config.json → finishBackup.retention` can change the numbers or turn the
- * whole thing off (`false`); a project without the key gets the defaults, and a
- * value that cannot be read skips the prune for that run.
- *
- * A backup without its manifest was written before this retention existed. The
- * automatic prune (end of `finish`, end of `worktree remove`) never deletes it,
- * never strips its `.env*` and does not count it against the budget — it only
- * reports how many wait (`legacyPending`). The first prune of those is the
- * explicit `doctor --worktrees --prune`, which ranks them with the rest and
- * gives each one it keeps a manifest, so from then on they are ordinary backups.
- *
- * Layout, and what counts as ONE backup:
- *
- *   {feature}-{stamp}/                     the feature scope the shed discards
- *   {feature}-{stamp}-worktree-ignored/    the worktree's exclusive gitignored
- *   {folder}.manifest.json                 sidecar: what was copied, the secrets
- *   task/{name}-{stamp}-worktree-ignored/  a namespace (task isolation trees)
- *
- * One finish writes both folders with the SAME stamp, so they are one backup —
- * the unit the count applies to; a folder with no same-stamp sibling counts
- * alone. The `task/` namespace has its own budget: a fan-out of twenty
- * sub-agent worktrees must not evict the backup of the feature finished a
- * minute earlier. The backup the calling run just wrote is never pruned by it.
- *
- * Deletion is PROVE-or-DECLINE, as everywhere else near a worktree: a backup
- * holding a reparse point is never removed, links are never descended, and
- * nothing outside the backup directory is touched. Not because `rmSync` would
- * follow a junction — it unlinks the link itself; what once emptied a primary
- * root was `git worktree remove` — but because a link inside a backup is not
- * something this code put there. A first-level entry that is neither a backup
- * nor `task/` is left alone, even empty — it is not ours to judge.
- */
-
+// Folders with the SAME stamp are one backup; `task/` has its own count budget.
+// A backup without manifest predates retention: only the explicit `--prune` touches it.
+// Deletion is prove-or-decline: a backup holding a reparse point is never removed.
 import {
   cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync,
   rmdirSync, rmSync, unlinkSync,
@@ -62,41 +16,30 @@ export const FINISH_BACKUP_RETENTION_DEFAULTS = Object.freeze({
   secretMaxAgeDays: 7,
 });
 
-/** The keys whose `null` means "no limit" rather than an invalid value. */
 const NULLABLE_RETENTION_KEYS = new Set(['maxAgeDays']);
 
 const DAY_MS = 86_400_000;
 const WORKTREE_IGNORED_SUFFIX = '-worktree-ignored';
 const MANIFEST_SUFFIX = '.manifest.json';
 const NAME_RE = /^(.+)-(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z(-worktree-ignored)?$/;
-/** How many names a payload carries; the counts are always complete. */
 const SAMPLE = 5;
 
-/** @param {string} root - the primary root */
 export function morphSpecStoreDir(root) {
   return join(root, '.git', 'morph-spec');
 }
 
-/** @param {string} root - the primary root */
 export function finishBackupDir(root) {
   return join(morphSpecStoreDir(root), 'finish-backup');
 }
 
-/** The stamp in a backup's name — filesystem-safe ISO-8601. */
 export function newBackupStamp(date = new Date()) {
   return date.toISOString().replace(/[:.]/g, '-');
 }
 
-/** `.env`, `.env.e2e`, `.env.local`… — the files that hold a stack's secrets. */
 export function isSecretFileName(name) {
   return name.startsWith('.env');
 }
 
-/**
- * @param {string} name - one directory name under finish-backup/ (or under a namespace)
- * @returns {{ base: string, feature: string, stamp: string,
- *   kind: 'feature-scope'|'worktree-ignored', createdAt: number }|null}
- */
 export function parseBackupName(name) {
   const m = NAME_RE.exec(name);
   if (!m) return null;
@@ -122,16 +65,8 @@ const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArr
 const shown = (v) => JSON.stringify(v) ?? String(v);
 const skippedPolicy = (reason) => ({ enabled: false, skipped: reason, ...FINISH_BACKUP_RETENTION_DEFAULTS });
 
-/**
- * The policy in force, from a parsed config.json. A config without the key
- * gets the defaults (retention on) and an explicit `false` turns it off. What
- * this cannot recognise SKIPS the prune for the run instead: the operation
- * deletes, and a value nobody can read — `{ enabled: false }`, `"false"`, a
- * `maxCount` of `0` — may well have been meant as "keep everything".
- *
- * @param {object|null} config - null when there is no config.json at all
- * @returns {{ enabled: boolean, skipped?: string, maxCount: number, maxAgeDays: number|null, secretMaxAgeDays: number }}
- */
+// A value this cannot recognise SKIPS the prune instead of falling back to the
+// defaults: the operation deletes, and `"false"` or `maxCount: 0` may mean "keep all".
 export function resolveBackupRetention(config) {
   const d = FINISH_BACKUP_RETENTION_DEFAULTS;
   const skip = skippedPolicy;
@@ -156,13 +91,8 @@ export function resolveBackupRetention(config) {
   return policy;
 }
 
-/**
- * Unlike `readMorphConfig`, a config.json that exists and does not parse is
- * not "no config": the defaults would turn on a prune its author may have
- * switched off in the part that failed to parse.
- *
- * @param {string} root
- */
+// Unlike `readMorphConfig`, an unparseable config.json is not "no config": the
+// defaults would turn on a prune its author may have switched off.
 export function readBackupRetention(root) {
   const path = join(root, CONFIG_FILE_NAME);
   if (!existsSync(path)) return resolveBackupRetention(null);
@@ -196,13 +126,6 @@ function isStrictlyInside(parent, child) {
   return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
 }
 
-/**
- * Every `.env*` REAL file under `dir`, relative to it. Links are neither
- * followed nor reported: a link is not bytes this backup holds.
- *
- * @param {string} dir
- * @returns {string[]}
- */
 export function secretFilesIn(dir) {
   const out = [];
   const stack = [''];
@@ -224,13 +147,7 @@ export function secretFilesIn(dir) {
   return out.sort();
 }
 
-/**
- * Bytes and files under `dir`, by lstat — a link counts as itself, never as
- * what it points at. `null` when the walk could not start.
- *
- * @param {string} dir
- * @returns {{ bytes: number, files: number }|null}
- */
+/** By lstat: a link counts as itself. `null` when the walk could not start. */
 export function measureDir(dir) {
   if (!isRealDir(dir)) return null;
   let bytes = 0;
@@ -247,7 +164,7 @@ export function measureDir(dir) {
     for (const e of entries) {
       const p = join(current, e.name);
       if (e.isDirectory() && !e.isSymbolicLink()) { stack.push(p); continue; }
-      try { bytes += lstatSync(p).size; files += 1; } catch { /* vanished */ }
+      try { bytes += lstatSync(p).size; files += 1; } catch {}
     }
   }
   return { bytes, files };
@@ -265,30 +182,16 @@ function readManifest(backupPath) {
   }
 }
 
-/**
- * Bookkeeping, never a precondition: a backup whose bytes are on disk is a
- * backup, with or without its manifest. One whose manifest failed to be written
- * reads as legacy, which is the safe side — the automatic prune leaves it alone.
- */
+// Fail-open: a backup whose manifest failed reads as legacy, the safe side.
 function writeManifest(backupPath, manifest) {
   try {
     atomicWriteJson(manifestPathFor(backupPath), { version: 1, ...manifest });
-  } catch { /* fail-open */ }
+  } catch {}
 }
 
-/**
- * Copy the worktree's exclusive gitignored leftovers out before the removal
- * deletes them. Caches are excluded at every depth, not only as top-level
- * entries: git reports an ignored directory as ONE entry when the directory
- * itself matches a pattern, so an exclusive `apps/x/` would otherwise drag its
- * `node_modules/` and `.next/` along. They are regenerable, and the removal
- * deletes them either way.
- *
- * @param {{ worktreePath: string, root: string, feature: string, rels: string[], stamp?: string }} args
- * @returns {string|null} the backup path, or null if ANY copy failed (the caller
- *   must then decline the removal — a partial backup authorizes nothing) or if
- *   none of `rels` exists anymore
- */
+// Caches are excluded at every depth: git reports an ignored dir as ONE entry,
+// so `apps/x/` would drag its `node_modules/` along.
+/** `null` if ANY copy failed — the caller must then decline the removal. */
 export function writeWorktreeIgnoredBackup({ worktreePath, root, feature, rels, stamp = newBackupStamp() }) {
   const dest = join(finishBackupDir(root), `${feature}-${stamp}${WORKTREE_IGNORED_SUFFIX}`);
   const copied = [];
@@ -297,7 +200,7 @@ export function writeWorktreeIgnoredBackup({ worktreePath, root, feature, rels,
   try {
     for (const rel of rels) {
       const src = join(worktreePath, rel);
-      if (!existsSync(src)) continue; // a directory entry already covered by its children
+      if (!existsSync(src)) continue;
       if (isDisposableBuildArtifact(relOf(src))) {
         excludedCaches.push(relOf(src));
         continue;
@@ -332,17 +235,8 @@ export function writeWorktreeIgnoredBackup({ worktreePath, root, feature, rels,
   return dest;
 }
 
-/**
- * Copy the feature's root-side scope to a backup OUTSIDE the working tree, so
- * the shed can never be the reason something is lost.
- *
- * Lives under `.git/` on purpose: it is not a working-tree path, so it can never
- * dirty `git status` (which the very next validation reads) and is never merged,
- * committed, or cleaned by `git clean`.
- *
- * @param {{ root: string, feature: string, stamp?: string }} args
- * @returns {string|null} absolute backup path, or null if the copy failed
- */
+// Under `.git/` so it never dirties the `git status` the next validation reads.
+/** `null` if the copy failed: the caller must not shed. */
 export function writeFeatureScopeBackup({ root, feature, stamp = newBackupStamp() }) {
   const src = join(root, '.morph', 'features', feature);
   if (!existsSync(src)) return null;
@@ -351,7 +245,7 @@ export function writeFeatureScopeBackup({ root, feature, stamp = newBackupStamp(
     mkdirSync(dirname(dest), { recursive: true });
     cpSync(src, dest, { recursive: true });
   } catch {
-    return null; // caller MUST treat this as "do not shed"
+    return null;
   }
   writeManifest(dest, {
     kind: 'feature-scope',
@@ -363,26 +257,10 @@ export function writeFeatureScopeBackup({ root, feature, stamp = newBackupStamp(
   return dest;
 }
 
-/**
- * The first-level directories that hold backups instead of being one: `task/`
- * is where the `task/{name}` key of a task isolation tree (see
- * `envKeyForWorktree` in worktree.js) lands. Any other first-level directory
- * that is not a backup was put there by someone else — never listed, never
- * removed, not even empty.
- */
+// Any other first-level directory that is not a backup is not ours: never removed.
 const BACKUP_NAMESPACES = new Set(['task']);
 
-/**
- * Every backup folder on disk: the first level, plus one level down inside a
- * namespace of BACKUP_NAMESPACES. A link is never descended, at either level.
- *
- * @param {string} root
- * `managed` is whether the folder has its manifest — the one criterion that
- * tells a backup of this retention from one written before it.
- *
- * @returns {Array<{ name: string, path: string, namespace: string, set: string,
- *   feature: string, stamp: string, kind: string, createdAt: number, managed: boolean }>}
- */
+/** `managed` = has its manifest; without one the backup predates retention. */
 export function listFinishBackups(root) {
   const base = finishBackupDir(root);
   if (!isRealDir(base)) return [];
@@ -396,7 +274,7 @@ export function listFinishBackups(root) {
     }
     for (const e of entries) {
       const path = join(dir, e.name);
-      if (!isRealDir(path)) continue; // manifests, temp files and links
+      if (!isRealDir(path)) continue;
       const parsed = parseBackupName(e.name);
       if (parsed) {
         const prefix = namespace ? `${namespace}/` : '';
@@ -420,30 +298,8 @@ export function listFinishBackups(root) {
   return out;
 }
 
-/**
- * Which backups the policy removes, and which it keeps but strips of `.env*`.
- * Pure: the caller supplies the listing and the clock.
- *
- * Two kinds of set are never removed. The ones stamped with `protectStamps` —
- * the backup the calling run just wrote: a retention that runs after a backup
- * exists to make room for it, not to take it. And the ones stamped AFTER `now`
- * (a clock that ran ahead and was corrected): their age is unknowable, so they
- * stay and do not take a place in the count — otherwise a handful of them
- * would push every new backup out the moment it is written.
- *
- * A set is legacy unless EVERY folder in it has its manifest. Without
- * `includeLegacy` (the automatic prune) legacy sets are out of the plan
- * altogether — no removal, no strip, no place in the count — and only counted
- * in `legacy`. With it (the explicit prune) they are ranked like the rest, and
- * the ones kept are listed in `adopt`.
- *
- * @param {ReturnType<typeof listFinishBackups>} backups
- * @param {ReturnType<typeof resolveBackupRetention>} retention
- * @param {number} now - epoch ms
- * @param {{ protectStamps?: string[], includeLegacy?: boolean }} [opts]
- * @returns {{ sets: number, legacy: number, remove: object[], stripSecrets: object[], adopt: object[] }}
- *   each entry a `{ set, namespace, stamp, createdAt, managed, members }`
- */
+// Sets stamped after `now` (clock ran ahead) stay and take no place in the count,
+// or a handful of them would evict every new backup the moment it is written.
 export function planBackupRetention(backups, retention, now, { protectStamps = [], includeLegacy = false } = {}) {
   const sets = new Map();
   for (const b of backups) {
@@ -486,27 +342,8 @@ export function planBackupRetention(backups, retention, now, { protectStamps = [
   return plan;
 }
 
-/**
- * Apply the policy: remove what it drops, strip `.env*` from what it keeps past
- * the short retention, and record the stripped names in the manifest. A backup
- * whose removal is declined (a reparse point inside, a locked file) is stripped
- * instead: the policy wanted it gone, and its secrets are the part that must not
- * linger. A policy that could not be read (`skipped`) prunes nothing. Never
- * throws — a retention that fails must never be the reason a `finish` fails.
- *
- * Legacy backups (no manifest) are touched only with `includeLegacy` — the
- * explicit `doctor --worktrees --prune`; otherwise they are counted in
- * `legacyPending`. The explicit prune writes a manifest into every legacy
- * backup it keeps (`adopted`), which makes it an ordinary backup from then on.
- *
- * @param {string} root
- * @param {{ now?: number, retention?: ReturnType<typeof resolveBackupRetention>,
- *   protectStamps?: string[], includeLegacy?: boolean }} [opts]
- *   `protectStamps`: the stamp(s) the calling run wrote its backup under
- * @returns {{ enabled: boolean, skipped?: string, removed: string[],
- *   secretsStripped: Array<{ backup: string, files: string[] }>, declined: Array<{ backup: string, reason: string }>,
- *   legacyPending: number, adopted: string[] }}
- */
+// A backup whose removal is declined still loses its `.env*`. Never throws:
+// a failed retention must never be the reason a `finish` fails.
 export function applyBackupRetention(root, { now = Date.now(), retention, protectStamps = [], includeLegacy = false } = {}) {
   const result = { enabled: true, removed: [], secretsStripped: [], declined: [], legacyPending: 0, adopted: [] };
   try {
@@ -539,7 +376,7 @@ export function applyBackupRetention(root, { now = Date.now(), retention, protec
           toStrip.push(m);
           continue;
         }
-        try { rmSync(manifestPathFor(m.path), { force: true }); } catch { /* the sidecar is bookkeeping */ }
+        try { rmSync(manifestPathFor(m.path), { force: true }); } catch {}
         result.removed.push(m.name);
       }
     }
@@ -550,7 +387,7 @@ export function applyBackupRetention(root, { now = Date.now(), retention, protec
         try {
           unlinkSync(join(m.path, rel));
           stripped.push(rel);
-        } catch { /* locked — the next run tries again */ }
+        } catch {}
       }
       if (!stripped.length) continue;
       const manifest = readManifest(m.path) ?? { kind: m.kind, feature: m.feature, createdAt: new Date(m.createdAt).toISOString() };
@@ -567,27 +404,16 @@ export function applyBackupRetention(root, { now = Date.now(), retention, protec
       result.adopted.push(m.name);
     }
 
-    // A namespace emptied by the removals goes too; rmdir refuses anything else.
     for (const name of BACKUP_NAMESPACES) {
       const p = join(base, name);
       if (isRealDir(p)) {
-        try { rmdirSync(p); } catch { /* not empty */ }
+        try { rmdirSync(p); } catch {}
       }
     }
-  } catch { /* fail-open */ }
+  } catch {}
   return result;
 }
 
-/**
- * What a prune WOULD do now, without doing it. `includeLegacy` picks which
- * prune: without it, the automatic one (what `finish --dry-run` announces);
- * with it, the explicit `doctor --worktrees --prune` (what the doctor reports).
- *
- * @param {string} root
- * @param {{ now?: number, retention?: ReturnType<typeof resolveBackupRetention>, includeLegacy?: boolean }} [opts]
- * @returns {{ policy: object, sets: number, folders: number, legacy: number,
- *   outsideRetention: number, overdueSecrets: string[] }}
- */
 export function inspectFinishBackups(root, { now = Date.now(), retention, includeLegacy = false } = {}) {
   const policy = retention ?? readBackupRetention(root);
   const backups = listFinishBackups(root);
@@ -603,7 +429,6 @@ export function inspectFinishBackups(root, { now = Date.now(), retention, includ
   };
 }
 
-/** The sentence both the audit and the store line say about what `--prune` would do. */
 function pendingParts(report, { long = false } = {}) {
   const { maxCount, maxAgeDays, secretMaxAgeDays } = report.policy;
   const parts = [];
@@ -632,16 +457,7 @@ function formatSize(bytes) {
   return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
 }
 
-/**
- * The default `doctor`'s line about `.git/morph-spec/`: its size and the
- * backups in it, in the check shape the doctor renders. The size rides in the
- * NAME because an `ok` line prints only its name. `ok` or `warn`, never a
- * failure; `null` — no line — when nothing was ever stored there.
- *
- * @param {string} root - the primary root
- * @param {{ now?: number }} [opts]
- * @returns {{ name: string, status: 'ok'|'warn', msg?: string }|null}
- */
+// The size rides in the NAME because the doctor prints only the name of an `ok` line.
 export function morphStoreCheck(root, { now = Date.now() } = {}) {
   let store;
   let report;
@@ -659,17 +475,6 @@ export function morphStoreCheck(root, { now = Date.now() } = {}) {
   return { name, status: 'warn', msg: `${pending.join(', ')} — rode morph-spec doctor --worktrees --prune` };
 }
 
-/**
- * The retention as an audit finding, in the shape `auditWorktrees` returns:
- * what the explicit `--prune` would do, including the legacy backups only it
- * prunes. `warn`, never a failure — backups waiting for a prune are
- * housekeeping. A policy that could not be read is a finding too: until it is
- * fixed, nothing is ever pruned.
- *
- * @param {string} root
- * @param {{ now?: number }} [opts]
- * @returns {Array<{ type: string, severity: string, detail: string, fix: string }>}
- */
 export function auditFinishBackups(root, opts = {}) {
   let report;
   try {
@@ -697,14 +502,7 @@ export function auditFinishBackups(root, opts = {}) {
   }];
 }
 
-/**
- * A payload-sized account of one retention run: complete counts, a short
- * sample of names; `{ skipped }` when the policy could not be read. `null` when
- * the run changed nothing and nothing waits for the explicit prune.
- *
- * @param {ReturnType<typeof applyBackupRetention>} result
- * @returns {object|null}
- */
+/** `null` when the run changed nothing and nothing waits for the explicit prune. */
 export function summarizeRetention(result) {
   if (!result) return null;
   if (result.skipped) return { skipped: result.skipped };
@@ -721,15 +519,7 @@ export function summarizeRetention(result) {
   return Object.keys(out).length ? out : null;
 }
 
-/**
- * The retention step every writer of backups runs after its own backup:
- * apply + summarize, fail-open. `protectStamps` is the stamp that backup was
- * written under — never pruned by this run.
- *
- * @param {string} root
- * @param {{ protectStamps?: string[] }} [opts]
- * @returns {object|null}
- */
+/** `protectStamps`: the stamp the caller just wrote its backup under, never pruned by this run. */
 export function enforceBackupRetention(root, { protectStamps = [] } = {}) {
   try {
     return summarizeRetention(applyBackupRetention(root, { protectStamps }));