@biffo/cli 0.159.0 → 0.161.0

package/dist/index.js

@@ -506,15 +506,317 @@ import { Command as Command3 } from "commander";
 
 // src/adapters/git/index.ts
 import { randomUUID } from "crypto";
-import { existsSync as existsSync4, mkdtempSync, rmSync } from "fs";
+import { existsSync as existsSync6, mkdtempSync as mkdtempSync2, rmSync as rmSync2 } from "fs";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join6 } from "path";
+import { execa as execa2 } from "execa";
+
+// src/lib/core-upgrade.ts
+import {
+  chmodSync,
+  existsSync as existsSync5,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync as readFileSync4,
+  rmSync,
+  statSync,
+  writeFileSync as writeFileSync2
+} from "fs";
 import { tmpdir } from "os";
-import { join as join4 } from "path";
+import { dirname as dirname3, join as join5 } from "path";
 import { execa } from "execa";
+
+// src/lib/core-ownership-guard.ts
+import { existsSync as existsSync4, readFileSync as readFileSync3 } from "fs";
+import { join as join4 } from "path";
+import { z as z3 } from "zod";
+var DIVERGENCE_FILE = "biffo.divergence.json";
+var DivergenceEntrySchema = z3.object({
+  prefix: z3.string().min(1),
+  reason: z3.string().min(1),
+  upstream: z3.string().min(1)
+});
+var DivergenceConfigSchema = z3.object({
+  note: z3.string().optional(),
+  warnOnly: z3.array(DivergenceEntrySchema).default([])
+});
+function readDivergenceConfig(repoRoot) {
+  const path = join4(repoRoot, DIVERGENCE_FILE);
+  if (!existsSync4(path)) return { warnOnly: [] };
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync3(path, "utf8"));
+  } catch (err) {
+    throw new Error(`${DIVERGENCE_FILE} is not valid JSON: ${err.message}`);
+  }
+  const parsed = DivergenceConfigSchema.safeParse(raw);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => `  ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new Error(`${DIVERGENCE_FILE} is invalid:
+${issues}`);
+  }
+  return parsed.data;
+}
+function parseTrailer(commitMessage, key) {
+  const body = commitMessage.split("\n").filter((line) => !line.startsWith("#")).join("\n");
+  const match = new RegExp(String.raw`^Core-${key}:[ \t]*(\S.*?)[ \t]*$`, "m").exec(body);
+  return match?.[1] ?? null;
+}
+function parseDivergenceTrailer(commitMessage) {
+  return parseTrailer(commitMessage, "Divergence");
+}
+function parseConvergenceTrailer(commitMessage) {
+  return parseTrailer(commitMessage, "Convergence");
+}
+function resolveBranch(env, gitBranch) {
+  return (env["GITHUB_HEAD_REF"] || env["GITHUB_REF_NAME"] || gitBranch).trim();
+}
+function parseNameStatus(stdout) {
+  const changed = [];
+  const deleted = [];
+  for (const line of stdout.split("\n")) {
+    const parts = line.split("	").filter(Boolean);
+    const status = parts[0];
+    const path = parts[parts.length - 1];
+    if (!status || !path || parts.length < 2) continue;
+    changed.push(path);
+    if (status.startsWith("D")) deleted.push(path);
+  }
+  return { changed, deleted };
+}
+function checkCoreOwnership({
+  changedFiles,
+  manifest,
+  isInstance,
+  branch = "",
+  commitMessage = "",
+  warnOnly = []
+}) {
+  const empty = { blocked: [], warned: [], divergenceReason: null, convergenceReason: null };
+  if (!isInstance) return { skipped: "template", ...empty };
+  if (branch.startsWith(UPGRADE_BRANCH_PREFIX)) return { skipped: "upgrade-branch", ...empty };
+  const templateOwned = changedFiles.filter((f) => isTemplateOwned(f, manifest));
+  const acknowledged = (path) => warnOnly.filter((entry) => path.startsWith(entry.prefix)).reduce(
+    (best, entry) => !best || entry.prefix.length > best.prefix.length ? entry : best,
+    void 0
+  );
+  const warned = [];
+  const offending = [];
+  for (const path of templateOwned) {
+    const entry = acknowledged(path);
+    if (entry) warned.push({ path, entry });
+    else offending.push(path);
+  }
+  const divergenceReason = parseDivergenceTrailer(commitMessage);
+  const convergenceReason = parseConvergenceTrailer(commitMessage);
+  if (offending.length > 0) {
+    if (divergenceReason !== null) {
+      return {
+        skipped: "divergence-trailer",
+        blocked: [],
+        warned,
+        divergenceReason,
+        convergenceReason: null
+      };
+    }
+    if (convergenceReason !== null) {
+      return {
+        skipped: "convergence-trailer",
+        blocked: [],
+        warned,
+        divergenceReason: null,
+        convergenceReason
+      };
+    }
+  }
+  return {
+    skipped: null,
+    blocked: offending,
+    warned,
+    divergenceReason: null,
+    convergenceReason: null
+  };
+}
+
+// src/lib/core-upgrade.ts
+var gitMergeFile = async (base, ours, theirs) => {
+  const dir = mkdtempSync(join5(tmpdir(), "biffo-merge-"));
+  try {
+    const b = join5(dir, "base");
+    const o = join5(dir, "ours");
+    const t = join5(dir, "theirs");
+    writeFileSync2(b, base);
+    writeFileSync2(o, ours);
+    writeFileSync2(t, theirs);
+    const result = await execa("git", ["merge-file", "-p", o, b, t], {
+      reject: false,
+      stripFinalNewline: false
+    });
+    if (typeof result.exitCode !== "number" || result.exitCode < 0) {
+      throw new Error(`git merge-file failed: ${result.stderr}`);
+    }
+    return { conflicted: result.exitCode > 0, content: result.stdout };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+};
+function read(root, rel) {
+  return readFileSync4(join5(root, rel), "utf8");
+}
+var EMPTY_SUMMARY = () => ({
+  unchanged: 0,
+  "take-theirs": 0,
+  "keep-ours": 0,
+  merged: 0,
+  conflict: 0,
+  added: 0,
+  "add-conflict": 0,
+  restored: 0,
+  removed: 0,
+  "remove-conflict": 0
+});
+async function planCoreUpgrade(options) {
+  const mergeFile = options.mergeFile ?? gitMergeFile;
+  const base = new Set(listTemplateOwnedFiles(options.baseDir, options.manifest));
+  const ours = new Set(listTemplateOwnedFiles(options.oursDir, options.manifest));
+  const theirs = new Set(listTemplateOwnedFiles(options.theirsDir, options.manifest));
+  const divergentPrefixes = readDivergenceConfig(options.oursDir).warnOnly.map((e) => e.prefix);
+  const isDeclaredDivergent = (path) => divergentPrefixes.some((prefix) => path.startsWith(prefix));
+  const paths = [.../* @__PURE__ */ new Set([...base, ...ours, ...theirs])].sort();
+  const entries = [];
+  const divergenceSkips = [];
+  for (const path of paths) {
+    entries.push(
+      await classify(
+        path,
+        base,
+        ours,
+        theirs,
+        options,
+        mergeFile,
+        isDeclaredDivergent,
+        (p) => divergenceSkips.push(p)
+      )
+    );
+  }
+  const summary = EMPTY_SUMMARY();
+  for (const e of entries) summary[e.status]++;
+  const changes = entries.filter((e) => e.status !== "unchanged" && e.status !== "keep-ours");
+  const conflicts = entries.filter((e) => e.conflicted);
+  return { entries, changes, conflicts, summary, divergenceSkips };
+}
+async function classify(path, base, ours, theirs, opts, mergeFile, isDeclaredDivergent, noteDivergenceSkip) {
+  const inBase = base.has(path);
+  const inOurs = ours.has(path);
+  const inTheirs = theirs.has(path);
+  if (!inBase && !inTheirs) {
+    return { path, status: "keep-ours", conflicted: false };
+  }
+  if (!inBase && inTheirs) {
+    const theirsContent2 = read(opts.theirsDir, path);
+    if (!inOurs) return { path, status: "added", conflicted: false, content: theirsContent2 };
+    const oursContent2 = read(opts.oursDir, path);
+    if (oursContent2 === theirsContent2) return { path, status: "unchanged", conflicted: false };
+    return { path, status: "add-conflict", conflicted: true, content: theirsContent2 };
+  }
+  if (inBase && !inTheirs) {
+    if (!inOurs) return { path, status: "removed", conflicted: false };
+    const baseContent2 = read(opts.baseDir, path);
+    const oursContent2 = read(opts.oursDir, path);
+    if (oursContent2 === baseContent2) return { path, status: "removed", conflicted: false };
+    return { path, status: "remove-conflict", conflicted: true };
+  }
+  const baseContent = read(opts.baseDir, path);
+  const theirsContent = read(opts.theirsDir, path);
+  if (!inOurs) {
+    if (isDeclaredDivergent(path)) {
+      noteDivergenceSkip(path);
+      return { path, status: "removed", conflicted: false };
+    }
+    return { path, status: "restored", conflicted: false, content: theirsContent };
+  }
+  const oursContent = read(opts.oursDir, path);
+  const oursChanged = oursContent !== baseContent;
+  const theirsChanged = theirsContent !== baseContent;
+  if (!theirsChanged) {
+    return { path, status: oursChanged ? "keep-ours" : "unchanged", conflicted: false };
+  }
+  if (!oursChanged) {
+    return { path, status: "take-theirs", conflicted: false, content: theirsContent };
+  }
+  if (oursContent === theirsContent) {
+    return { path, status: "unchanged", conflicted: false };
+  }
+  const { conflicted, content } = await mergeFile(baseContent, oursContent, theirsContent);
+  return { path, status: conflicted ? "conflict" : "merged", conflicted, content };
+}
+function applyUpgradePlan(instanceDir, plan, theirsDir) {
+  const written = [];
+  const deleted = [];
+  for (const e of plan.entries) {
+    const abs = join5(instanceDir, e.path);
+    if (e.status === "removed") {
+      if (existsSync5(abs)) {
+        rmSync(abs);
+        deleted.push(e.path);
+      }
+      continue;
+    }
+    if (e.content !== void 0) {
+      mkdirSync(dirname3(abs), { recursive: true });
+      writeFileSync2(abs, e.content);
+      if (theirsDir !== void 0) {
+        const source = join5(theirsDir, e.path);
+        if (existsSync5(source) && (statSync(source).mode & 73) !== 0) {
+          chmodSync(abs, 493);
+        }
+      }
+      written.push(e.path);
+    }
+  }
+  return { written, deleted };
+}
+function parseGitHubRepo(remoteUrl) {
+  const ssh = /^git@[^:]+:([^/]+)\/(.+?)(?:\.git)?\/?$/.exec(remoteUrl);
+  if (ssh && ssh[1] && ssh[2]) return { owner: ssh[1], repo: ssh[2] };
+  const https = /^https?:\/\/[^/]+\/([^/]+)\/(.+?)(?:\.git)?\/?$/.exec(remoteUrl);
+  if (https && https[1] && https[2]) return { owner: https[1], repo: https[2] };
+  throw new Error(`Could not parse a GitHub owner/repo from remote URL: ${remoteUrl}`);
+}
+var UPGRADE_BRANCH_PREFIX = "biffo/core-upgrade-";
+function upgradeBranchName(from, to) {
+  return `${UPGRADE_BRANCH_PREFIX}${from}-to-${to}`.replace(/[^a-zA-Z0-9._/-]/g, "-");
+}
+
+// src/lib/upgrade-branch-reaper.ts
+var BRANCH_REF_FORMAT = "%(refname:short)	%(upstream)	%(upstream:track)";
+function parseBranchRefs(stdout) {
+  return stdout.split("\n").map((line) => line.trimEnd()).filter((line) => line !== "").map((line) => {
+    const [name = "", upstream = "", track = ""] = line.split("	");
+    return { name, upstream, track };
+  }).filter((ref) => ref.name !== "");
+}
+function classifyUpgradeBranches(refs, currentBranch) {
+  const reapable = [];
+  const unverifiable = [];
+  for (const ref of refs) {
+    if (!ref.name.startsWith(UPGRADE_BRANCH_PREFIX)) continue;
+    if (ref.name === currentBranch) continue;
+    if (ref.track.includes("gone")) {
+      reapable.push(ref.name);
+    } else if (ref.upstream === "") {
+      unverifiable.push(ref.name);
+    }
+  }
+  return { reapable, unverifiable };
+}
+
+// src/adapters/git/index.ts
 var GitAdapter = class {
   /** True if `cwd` is inside a git working tree. */
   async isGitRepo(cwd) {
     try {
-      await execa("git", ["rev-parse", "--is-inside-work-tree"], { cwd });
+      await execa2("git", ["rev-parse", "--is-inside-work-tree"], { cwd });
       return true;
     } catch {
       return false;
@@ -536,16 +838,16 @@ var GitAdapter = class {
    * or a crash report.
    */
   async cloneToTemp(repoUrl, namePrefix, token) {
-    const dir = mkdtempSync(join4(tmpdir(), `${namePrefix}-${randomUUID().slice(0, 8)}-`));
+    const dir = mkdtempSync2(join6(tmpdir2(), `${namePrefix}-${randomUUID().slice(0, 8)}-`));
     const cloneUrl = token ? injectToken(repoUrl, token) : repoUrl;
     try {
-      await execa("git", ["clone", "--depth", "1", cloneUrl, dir]);
+      await execa2("git", ["clone", "--depth", "1", cloneUrl, dir]);
     } catch (err) {
-      rmSync(dir, { recursive: true, force: true });
+      rmSync2(dir, { recursive: true, force: true });
       throw new Error(`Failed to clone ${repoUrl}: ${err.message}`);
     }
-    const gitDir = join4(dir, ".git");
-    if (existsSync4(gitDir)) rmSync(gitDir, { recursive: true, force: true });
+    const gitDir = join6(dir, ".git");
+    if (existsSync6(gitDir)) rmSync2(gitDir, { recursive: true, force: true });
     return dir;
   }
   /**
@@ -559,19 +861,19 @@ var GitAdapter = class {
    * method have no need for.
    */
   async cloneForEditing(repoUrl, namePrefix, token) {
-    const dir = mkdtempSync(join4(tmpdir(), `${namePrefix}-${randomUUID().slice(0, 8)}-`));
+    const dir = mkdtempSync2(join6(tmpdir2(), `${namePrefix}-${randomUUID().slice(0, 8)}-`));
     const cloneUrl = token ? injectToken(repoUrl, token) : repoUrl;
     try {
-      await execa("git", ["clone", cloneUrl, dir]);
+      await execa2("git", ["clone", cloneUrl, dir]);
     } catch (err) {
-      rmSync(dir, { recursive: true, force: true });
+      rmSync2(dir, { recursive: true, force: true });
       throw new Error(`Failed to clone ${repoUrl}: ${err.message}`);
     }
     return dir;
   }
   /** Removes a directory created by cloneToTemp/cloneForEditing. Safe to call more than once. */
   cleanup(dir) {
-    rmSync(dir, { recursive: true, force: true });
+    rmSync2(dir, { recursive: true, force: true });
   }
   /**
    * `git init` a fresh working tree — for `biffo sibling create` (ADR-0007),
@@ -586,26 +888,26 @@ var GitAdapter = class {
    * repo uses (#559).
    */
   async init(cwd, initialBranch = "dev") {
-    await execa("git", ["init", "-b", initialBranch], { cwd });
+    await execa2("git", ["init", "-b", initialBranch], { cwd });
   }
   /** Adds a remote. Fails if a remote with this name already exists. */
   async addRemote(cwd, name, url) {
-    await execa("git", ["remote", "add", name, url], { cwd });
+    await execa2("git", ["remote", "add", name, url], { cwd });
   }
   async add(cwd, paths) {
-    await execa("git", ["add", ...paths], { cwd });
+    await execa2("git", ["add", ...paths], { cwd });
   }
   async commit(cwd, message) {
-    await execa("git", ["commit", "-m", message], { cwd });
+    await execa2("git", ["commit", "-m", message], { cwd });
   }
   /** The current branch name (e.g. "dev"). */
   async currentBranch(cwd) {
-    const { stdout } = await execa("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd });
+    const { stdout } = await execa2("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd });
     return stdout.trim();
   }
   /** True if the working tree or index has uncommitted changes. */
   async hasUncommittedChanges(cwd) {
-    const { stdout } = await execa("git", ["status", "--porcelain"], { cwd });
+    const { stdout } = await execa2("git", ["status", "--porcelain"], { cwd });
     return stdout.trim().length > 0;
   }
   /** Best-effort fetch of the tracking remote, so the ahead/behind check below
@@ -613,13 +915,13 @@ var GitAdapter = class {
    * offline or a missing remote must not block an upgrade on its own — the
    * ahead/behind check that follows simply works from whatever is local. */
   async fetch(cwd, remote = "origin") {
-    await execa("git", ["fetch", "--quiet", remote], { cwd, reject: false });
+    await execa2("git", ["fetch", "--quiet", remote], { cwd, reject: false });
   }
   /** HEAD's position relative to its upstream. `hasUpstream` is false when the
    * branch tracks nothing (or HEAD is detached), in which case currency cannot
    * be established and ahead/behind are 0 (#394). */
   async aheadBehind(cwd) {
-    const { stdout, exitCode } = await execa(
+    const { stdout, exitCode } = await execa2(
       "git",
       ["rev-list", "--left-right", "--count", "HEAD...@{upstream}"],
       { cwd, reject: false }
@@ -630,12 +932,48 @@ var GitAdapter = class {
   }
   /** The fetch URL of a remote (default "origin"). */
   async getRemoteUrl(cwd, remote = "origin") {
-    const { stdout } = await execa("git", ["remote", "get-url", remote], { cwd });
+    const { stdout } = await execa2("git", ["remote", "get-url", remote], { cwd });
     return stdout.trim();
   }
+  /**
+   * Prunes remote-tracking refs whose remote branch is gone, so `upstream:track`
+   * reports `[gone]` for a merged-and-deleted branch (#758).
+   *
+   * `fetch()` above deliberately does NOT prune: it exists to make the currency
+   * check compare against reality, and pruning is a side effect no caller of it
+   * asked for. Reaping genuinely needs it — without a prune, a branch whose
+   * remote copy was deleted last month still looks alive — so it is a separate,
+   * equally best-effort call.
+   */
+  async fetchPrune(cwd, remote = "origin") {
+    await execa2("git", ["fetch", "--quiet", "--prune", remote], { cwd, reject: false });
+  }
+  /** Every local branch with its upstream and tracking state (#758). */
+  async listBranchRefs(cwd) {
+    const { stdout, exitCode } = await execa2(
+      "git",
+      ["for-each-ref", `--format=${BRANCH_REF_FORMAT}`, "refs/heads"],
+      { cwd, reject: false }
+    );
+    if (exitCode !== 0) return [];
+    return parseBranchRefs(stdout);
+  }
+  /**
+   * Force-deletes a local branch, returning whether it went.
+   *
+   * `-D` rather than `-d` because these branches are squash-merged: their tips
+   * are never ancestors of the base, so `-d` refuses every one of them. That is
+   * precisely why nobody ever cleaned them up by hand. The safety that `-d`
+   * would have provided is supplied instead by the caller, which only ever
+   * passes branches whose upstream git reports as gone.
+   */
+  async deleteBranch(cwd, branch) {
+    const { exitCode } = await execa2("git", ["branch", "-D", branch], { cwd, reject: false });
+    return exitCode === 0;
+  }
   /** Create and switch to a new branch. Fails if it already exists. */
   async createBranch(cwd, branch) {
-    await execa("git", ["switch", "-c", branch], { cwd });
+    await execa2("git", ["switch", "-c", branch], { cwd });
   }
   /**
    * Push the current HEAD to `branch` on the remote. When `token` is given and
@@ -653,7 +991,7 @@ var GitAdapter = class {
       if (authed !== url) target = authed;
     }
     try {
-      await execa("git", ["push", target, `HEAD:refs/heads/${branch}`], { cwd });
+      await execa2("git", ["push", target, `HEAD:refs/heads/${branch}`], { cwd });
     } catch {
       throw new Error(`Failed to push branch '${branch}' to remote '${remote}'.`);
     }
@@ -704,9 +1042,9 @@ var GitAdapter = class {
    */
   async setUpstreamAfterPush(cwd, branch, remote) {
     const opts = { cwd, reject: false };
-    await execa("git", ["update-ref", `refs/remotes/${remote}/${branch}`, "HEAD"], opts);
-    await execa("git", ["config", `branch.${branch}.remote`, remote], opts);
-    await execa("git", ["config", `branch.${branch}.merge`, `refs/heads/${branch}`], opts);
+    await execa2("git", ["update-ref", `refs/remotes/${remote}/${branch}`, "HEAD"], opts);
+    await execa2("git", ["config", `branch.${branch}.remote`, remote], opts);
+    await execa2("git", ["config", `branch.${branch}.merge`, `refs/heads/${branch}`], opts);
   }
 };
 function injectToken(repoUrl, token) {
@@ -1441,8 +1779,8 @@ var GitHubAdapter = class {
 
 // src/lib/core-migrations.ts
 import { createHash } from "crypto";
-import { existsSync as existsSync5, mkdirSync, readFileSync as readFileSync3, readdirSync as readdirSync2, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname3, join as join5 } from "path";
+import { existsSync as existsSync7, mkdirSync as mkdirSync2, readFileSync as readFileSync5, readdirSync as readdirSync2, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname4, join as join7 } from "path";
 var MIGRATIONS_VERSIONS_DIR = "services/api/migrations/versions";
 var REVISION_RE = /^(revision\b[^=\n]*=\s*)(.+)$/m;
 var DOWN_REVISION_RE = /^(down_revision\b[^=\n]*=\s*)(.+)$/m;
@@ -1481,8 +1819,8 @@ function parseMigration(file, content) {
   return { file, revision, downRevision, content };
 }
 function readMigrations(versionsDir) {
-  if (!existsSync5(versionsDir)) return [];
-  return readdirSync2(versionsDir).filter((f) => f.endsWith(".py") && f !== "__init__.py").sort().map((f) => parseMigration(f, readFileSync3(join5(versionsDir, f), "utf8")));
+  if (!existsSync7(versionsDir)) return [];
+  return readdirSync2(versionsDir).filter((f) => f.endsWith(".py") && f !== "__init__.py").sort().map((f) => parseMigration(f, readFileSync5(join7(versionsDir, f), "utf8")));
 }
 function rechainMigration(content, revision, downRevision) {
   let out = content.replace(REVISION_RE, (_m, lhs) => `${lhs}${renderLiteral(revision)}`);
@@ -1599,8 +1937,8 @@ function migrationSlug(file) {
   return file.replace(/\.py$/, "").replace(/^[0-9a-f]+_/i, "");
 }
 function planMigrationCarry(options) {
-  const templateVersions = join5(options.templateDir, MIGRATIONS_VERSIONS_DIR);
-  const instanceVersions = join5(options.instanceDir, MIGRATIONS_VERSIONS_DIR);
+  const templateVersions = join7(options.templateDir, MIGRATIONS_VERSIONS_DIR);
+  const instanceVersions = join7(options.instanceDir, MIGRATIONS_VERSIONS_DIR);
   const template = readMigrations(templateVersions);
   const instance = readMigrations(instanceVersions);
   const instanceHead = validateChain(instance, `${MIGRATIONS_VERSIONS_DIR} (instance)`);
@@ -1639,414 +1977,137 @@ function planMigrationCarry(options) {
           file: m.file,
           instanceFile: already.instance.file,
           how: already.how
-        });
-      }
-      continue;
-    }
-    let revision = m.revision;
-    let reissuedFrom;
-    if (usedRevisions.has(revision)) {
-      const replacement = reissuedRevisionId(m.file);
-      if (usedRevisions.has(replacement)) {
-        throw new Error(
-          `Cannot carry ${m.file}: its revision id "${revision}" is already used in the instance, and so is the deterministic replacement "${replacement}". Resolve manually.`
-        );
-      }
-      reissuedFrom = revision;
-      revision = replacement;
-    }
-    const entry = {
-      path: `${MIGRATIONS_VERSIONS_DIR}/${m.file}`,
-      file: m.file,
-      revision,
-      downRevision: head,
-      // Stamped before re-chaining so the instance's copy records which template
-      // migration it is, whatever it is later renamed or renumbered to.
-      content: rechainMigration(stampCarriedFrom(m.content, m.file), revision, head)
-    };
-    if (reissuedFrom !== void 0) entry.reissuedFrom = reissuedFrom;
-    entries.push(entry);
-    usedRevisions.add(revision);
-    head = revision;
-  }
-  validateChain(
-    [
-      ...instance,
-      ...entries.map((e) => ({
-        file: e.file,
-        revision: e.revision,
-        downRevision: e.downRevision,
-        content: e.content
-      }))
-    ],
-    `${MIGRATIONS_VERSIONS_DIR} (after carry)`
-  );
-  const templateFiles = new Set(template.map((m) => m.file));
-  const staleDeclines = [...declinedIndex.keys()].filter((f) => !templateFiles.has(f));
-  return {
-    entries,
-    instanceHead,
-    skipped,
-    recognised,
-    declined,
-    staleDeclines,
-    divergedBodies
-  };
-}
-var TEST_PATH_RE = /(^|\/)tests?\/.*\btest_[^/]*\.py$/;
-function findMigrationTestPairings(changes, divergedBodies) {
-  if (divergedBodies.length === 0) return [];
-  const pairings = [];
-  for (const change of changes) {
-    if (!TEST_PATH_RE.test(change.path)) continue;
-    const content = change.content;
-    if (content === void 0) continue;
-    for (const d of divergedBodies) {
-      if (content.includes(d.file)) {
-        pairings.push({ testPath: change.path, migration: d.file, instanceFile: d.instanceFile });
-      }
-    }
-  }
-  return pairings;
-}
-function indexInstanceMigrations(instance) {
-  const index = {
-    byCarriedFrom: /* @__PURE__ */ new Map(),
-    byFile: /* @__PURE__ */ new Map(),
-    byBody: /* @__PURE__ */ new Map(),
-    bySlug: /* @__PURE__ */ new Map()
-  };
-  for (const m of instance) {
-    index.byFile.set(m.file, m);
-    const from = parseCarriedFrom(m.content);
-    if (from !== null) index.byCarriedFrom.set(from, m);
-    const body = migrationBodyHash(m.content);
-    index.byBody.set(body, [...index.byBody.get(body) ?? [], m]);
-    const slug = migrationSlug(m.file);
-    index.bySlug.set(slug, [...index.bySlug.get(slug) ?? [], m]);
-  }
-  return index;
-}
-function alreadyCarried(m, index, templateBodyCounts) {
-  const byProvenance = index.byCarriedFrom.get(m.file);
-  if (byProvenance) return { instance: byProvenance, how: "provenance" };
-  const byFile = index.byFile.get(m.file);
-  if (byFile) return { instance: byFile, how: "filename" };
-  const body = migrationBodyHash(m.content);
-  const bodyMatches = index.byBody.get(body) ?? [];
-  if (bodyMatches.length === 1 && templateBodyCounts.get(body) === 1) {
-    return { instance: bodyMatches[0], how: "body" };
-  }
-  const slugMatches = (index.bySlug.get(migrationSlug(m.file)) ?? []).filter(
-    // A file already claimed as a copy of some OTHER template migration is not
-    // an ambiguous match for this one.
-    (candidate) => parseCarriedFrom(candidate.content) === null
-  );
-  if (slugMatches.length > 0) {
-    const names = slugMatches.map((c) => c.file).join(", ");
-    throw new Error(
-      `Cannot carry ${m.file}: the instance has ${names}, which describes the same migration but whose contents differ, and which carries no provenance marker. Refusing to guess.
-
-  If it IS this migration (carried before provenance was recorded, then renamed or edited), add this line above its 'revision' assignment and re-run:
-
-      ${CARRIED_FROM_MARKER} ${m.file}
-
-  If it is unrelated, rename it so the descriptions differ.
-
-  Carrying it blindly would re-issue an already-applied migration and run its DDL against a database that already has those objects (#366).`
-    );
-  }
-  return null;
-}
-function applyMigrationCarry(instanceDir, plan) {
-  const written = [];
-  for (const e of plan.entries) {
-    const abs = join5(instanceDir, e.path);
-    if (existsSync5(abs)) {
-      throw new Error(`Refusing to overwrite an existing migration: ${e.path}`);
-    }
-    mkdirSync(dirname3(abs), { recursive: true });
-    writeFileSync2(abs, e.content);
-    written.push(e.path);
-  }
-  return written;
-}
-
-// src/lib/core-upgrade.ts
-import {
-  chmodSync,
-  existsSync as existsSync7,
-  mkdirSync as mkdirSync2,
-  mkdtempSync as mkdtempSync2,
-  readFileSync as readFileSync5,
-  rmSync as rmSync2,
-  statSync,
-  writeFileSync as writeFileSync3
-} from "fs";
-import { tmpdir as tmpdir2 } from "os";
-import { dirname as dirname4, join as join7 } from "path";
-import { execa as execa2 } from "execa";
-
-// src/lib/core-ownership-guard.ts
-import { existsSync as existsSync6, readFileSync as readFileSync4 } from "fs";
-import { join as join6 } from "path";
-import { z as z3 } from "zod";
-var DIVERGENCE_FILE = "biffo.divergence.json";
-var DivergenceEntrySchema = z3.object({
-  prefix: z3.string().min(1),
-  reason: z3.string().min(1),
-  upstream: z3.string().min(1)
-});
-var DivergenceConfigSchema = z3.object({
-  note: z3.string().optional(),
-  warnOnly: z3.array(DivergenceEntrySchema).default([])
-});
-function readDivergenceConfig(repoRoot) {
-  const path = join6(repoRoot, DIVERGENCE_FILE);
-  if (!existsSync6(path)) return { warnOnly: [] };
-  let raw;
-  try {
-    raw = JSON.parse(readFileSync4(path, "utf8"));
-  } catch (err) {
-    throw new Error(`${DIVERGENCE_FILE} is not valid JSON: ${err.message}`);
-  }
-  const parsed = DivergenceConfigSchema.safeParse(raw);
-  if (!parsed.success) {
-    const issues = parsed.error.issues.map((i) => `  ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
-    throw new Error(`${DIVERGENCE_FILE} is invalid:
-${issues}`);
-  }
-  return parsed.data;
-}
-function parseTrailer(commitMessage, key) {
-  const body = commitMessage.split("\n").filter((line) => !line.startsWith("#")).join("\n");
-  const match = new RegExp(String.raw`^Core-${key}:[ \t]*(\S.*?)[ \t]*$`, "m").exec(body);
-  return match?.[1] ?? null;
-}
-function parseDivergenceTrailer(commitMessage) {
-  return parseTrailer(commitMessage, "Divergence");
-}
-function parseConvergenceTrailer(commitMessage) {
-  return parseTrailer(commitMessage, "Convergence");
-}
-function resolveBranch(env, gitBranch) {
-  return (env["GITHUB_HEAD_REF"] || env["GITHUB_REF_NAME"] || gitBranch).trim();
-}
-function parseNameStatus(stdout) {
-  const changed = [];
-  const deleted = [];
-  for (const line of stdout.split("\n")) {
-    const parts = line.split("	").filter(Boolean);
-    const status = parts[0];
-    const path = parts[parts.length - 1];
-    if (!status || !path || parts.length < 2) continue;
-    changed.push(path);
-    if (status.startsWith("D")) deleted.push(path);
-  }
-  return { changed, deleted };
-}
-function checkCoreOwnership({
-  changedFiles,
-  manifest,
-  isInstance,
-  branch = "",
-  commitMessage = "",
-  warnOnly = []
-}) {
-  const empty = { blocked: [], warned: [], divergenceReason: null, convergenceReason: null };
-  if (!isInstance) return { skipped: "template", ...empty };
-  if (branch.startsWith(UPGRADE_BRANCH_PREFIX)) return { skipped: "upgrade-branch", ...empty };
-  const templateOwned = changedFiles.filter((f) => isTemplateOwned(f, manifest));
-  const acknowledged = (path) => warnOnly.filter((entry) => path.startsWith(entry.prefix)).reduce(
-    (best, entry) => !best || entry.prefix.length > best.prefix.length ? entry : best,
-    void 0
-  );
-  const warned = [];
-  const offending = [];
-  for (const path of templateOwned) {
-    const entry = acknowledged(path);
-    if (entry) warned.push({ path, entry });
-    else offending.push(path);
-  }
-  const divergenceReason = parseDivergenceTrailer(commitMessage);
-  const convergenceReason = parseConvergenceTrailer(commitMessage);
-  if (offending.length > 0) {
-    if (divergenceReason !== null) {
-      return {
-        skipped: "divergence-trailer",
-        blocked: [],
-        warned,
-        divergenceReason,
-        convergenceReason: null
-      };
+        });
+      }
+      continue;
     }
-    if (convergenceReason !== null) {
-      return {
-        skipped: "convergence-trailer",
-        blocked: [],
-        warned,
-        divergenceReason: null,
-        convergenceReason
-      };
+    let revision = m.revision;
+    let reissuedFrom;
+    if (usedRevisions.has(revision)) {
+      const replacement = reissuedRevisionId(m.file);
+      if (usedRevisions.has(replacement)) {
+        throw new Error(
+          `Cannot carry ${m.file}: its revision id "${revision}" is already used in the instance, and so is the deterministic replacement "${replacement}". Resolve manually.`
+        );
+      }
+      reissuedFrom = revision;
+      revision = replacement;
     }
+    const entry = {
+      path: `${MIGRATIONS_VERSIONS_DIR}/${m.file}`,
+      file: m.file,
+      revision,
+      downRevision: head,
+      // Stamped before re-chaining so the instance's copy records which template
+      // migration it is, whatever it is later renamed or renumbered to.
+      content: rechainMigration(stampCarriedFrom(m.content, m.file), revision, head)
+    };
+    if (reissuedFrom !== void 0) entry.reissuedFrom = reissuedFrom;
+    entries.push(entry);
+    usedRevisions.add(revision);
+    head = revision;
   }
+  validateChain(
+    [
+      ...instance,
+      ...entries.map((e) => ({
+        file: e.file,
+        revision: e.revision,
+        downRevision: e.downRevision,
+        content: e.content
+      }))
+    ],
+    `${MIGRATIONS_VERSIONS_DIR} (after carry)`
+  );
+  const templateFiles = new Set(template.map((m) => m.file));
+  const staleDeclines = [...declinedIndex.keys()].filter((f) => !templateFiles.has(f));
   return {
-    skipped: null,
-    blocked: offending,
-    warned,
-    divergenceReason: null,
-    convergenceReason: null
+    entries,
+    instanceHead,
+    skipped,
+    recognised,
+    declined,
+    staleDeclines,
+    divergedBodies
   };
 }
-
-// src/lib/core-upgrade.ts
-var gitMergeFile = async (base, ours, theirs) => {
-  const dir = mkdtempSync2(join7(tmpdir2(), "biffo-merge-"));
-  try {
-    const b = join7(dir, "base");
-    const o = join7(dir, "ours");
-    const t = join7(dir, "theirs");
-    writeFileSync3(b, base);
-    writeFileSync3(o, ours);
-    writeFileSync3(t, theirs);
-    const result = await execa2("git", ["merge-file", "-p", o, b, t], {
-      reject: false,
-      stripFinalNewline: false
-    });
-    if (typeof result.exitCode !== "number" || result.exitCode < 0) {
-      throw new Error(`git merge-file failed: ${result.stderr}`);
+var TEST_PATH_RE = /(^|\/)tests?\/.*\btest_[^/]*\.py$/;
+function findMigrationTestPairings(changes, divergedBodies) {
+  if (divergedBodies.length === 0) return [];
+  const pairings = [];
+  for (const change of changes) {
+    if (!TEST_PATH_RE.test(change.path)) continue;
+    const content = change.content;
+    if (content === void 0) continue;
+    for (const d of divergedBodies) {
+      if (content.includes(d.file)) {
+        pairings.push({ testPath: change.path, migration: d.file, instanceFile: d.instanceFile });
+      }
     }
-    return { conflicted: result.exitCode > 0, content: result.stdout };
-  } finally {
-    rmSync2(dir, { recursive: true, force: true });
   }
-};
-function read(root, rel) {
-  return readFileSync5(join7(root, rel), "utf8");
+  return pairings;
 }
-var EMPTY_SUMMARY = () => ({
-  unchanged: 0,
-  "take-theirs": 0,
-  "keep-ours": 0,
-  merged: 0,
-  conflict: 0,
-  added: 0,
-  "add-conflict": 0,
-  restored: 0,
-  removed: 0,
-  "remove-conflict": 0
-});
-async function planCoreUpgrade(options) {
-  const mergeFile = options.mergeFile ?? gitMergeFile;
-  const base = new Set(listTemplateOwnedFiles(options.baseDir, options.manifest));
-  const ours = new Set(listTemplateOwnedFiles(options.oursDir, options.manifest));
-  const theirs = new Set(listTemplateOwnedFiles(options.theirsDir, options.manifest));
-  const divergentPrefixes = readDivergenceConfig(options.oursDir).warnOnly.map((e) => e.prefix);
-  const isDeclaredDivergent = (path) => divergentPrefixes.some((prefix) => path.startsWith(prefix));
-  const paths = [.../* @__PURE__ */ new Set([...base, ...ours, ...theirs])].sort();
-  const entries = [];
-  const divergenceSkips = [];
-  for (const path of paths) {
-    entries.push(
-      await classify(
-        path,
-        base,
-        ours,
-        theirs,
-        options,
-        mergeFile,
-        isDeclaredDivergent,
-        (p) => divergenceSkips.push(p)
-      )
-    );
+function indexInstanceMigrations(instance) {
+  const index = {
+    byCarriedFrom: /* @__PURE__ */ new Map(),
+    byFile: /* @__PURE__ */ new Map(),
+    byBody: /* @__PURE__ */ new Map(),
+    bySlug: /* @__PURE__ */ new Map()
+  };
+  for (const m of instance) {
+    index.byFile.set(m.file, m);
+    const from = parseCarriedFrom(m.content);
+    if (from !== null) index.byCarriedFrom.set(from, m);
+    const body = migrationBodyHash(m.content);
+    index.byBody.set(body, [...index.byBody.get(body) ?? [], m]);
+    const slug = migrationSlug(m.file);
+    index.bySlug.set(slug, [...index.bySlug.get(slug) ?? [], m]);
   }
-  const summary = EMPTY_SUMMARY();
-  for (const e of entries) summary[e.status]++;
-  const changes = entries.filter((e) => e.status !== "unchanged" && e.status !== "keep-ours");
-  const conflicts = entries.filter((e) => e.conflicted);
-  return { entries, changes, conflicts, summary, divergenceSkips };
+  return index;
 }
-async function classify(path, base, ours, theirs, opts, mergeFile, isDeclaredDivergent, noteDivergenceSkip) {
-  const inBase = base.has(path);
-  const inOurs = ours.has(path);
-  const inTheirs = theirs.has(path);
-  if (!inBase && !inTheirs) {
-    return { path, status: "keep-ours", conflicted: false };
-  }
-  if (!inBase && inTheirs) {
-    const theirsContent2 = read(opts.theirsDir, path);
-    if (!inOurs) return { path, status: "added", conflicted: false, content: theirsContent2 };
-    const oursContent2 = read(opts.oursDir, path);
-    if (oursContent2 === theirsContent2) return { path, status: "unchanged", conflicted: false };
-    return { path, status: "add-conflict", conflicted: true, content: theirsContent2 };
-  }
-  if (inBase && !inTheirs) {
-    if (!inOurs) return { path, status: "removed", conflicted: false };
-    const baseContent2 = read(opts.baseDir, path);
-    const oursContent2 = read(opts.oursDir, path);
-    if (oursContent2 === baseContent2) return { path, status: "removed", conflicted: false };
-    return { path, status: "remove-conflict", conflicted: true };
-  }
-  const baseContent = read(opts.baseDir, path);
-  const theirsContent = read(opts.theirsDir, path);
-  if (!inOurs) {
-    if (isDeclaredDivergent(path)) {
-      noteDivergenceSkip(path);
-      return { path, status: "removed", conflicted: false };
-    }
-    return { path, status: "restored", conflicted: false, content: theirsContent };
-  }
-  const oursContent = read(opts.oursDir, path);
-  const oursChanged = oursContent !== baseContent;
-  const theirsChanged = theirsContent !== baseContent;
-  if (!theirsChanged) {
-    return { path, status: oursChanged ? "keep-ours" : "unchanged", conflicted: false };
-  }
-  if (!oursChanged) {
-    return { path, status: "take-theirs", conflicted: false, content: theirsContent };
+function alreadyCarried(m, index, templateBodyCounts) {
+  const byProvenance = index.byCarriedFrom.get(m.file);
+  if (byProvenance) return { instance: byProvenance, how: "provenance" };
+  const byFile = index.byFile.get(m.file);
+  if (byFile) return { instance: byFile, how: "filename" };
+  const body = migrationBodyHash(m.content);
+  const bodyMatches = index.byBody.get(body) ?? [];
+  if (bodyMatches.length === 1 && templateBodyCounts.get(body) === 1) {
+    return { instance: bodyMatches[0], how: "body" };
   }
-  if (oursContent === theirsContent) {
-    return { path, status: "unchanged", conflicted: false };
+  const slugMatches = (index.bySlug.get(migrationSlug(m.file)) ?? []).filter(
+    // A file already claimed as a copy of some OTHER template migration is not
+    // an ambiguous match for this one.
+    (candidate) => parseCarriedFrom(candidate.content) === null
+  );
+  if (slugMatches.length > 0) {
+    const names = slugMatches.map((c) => c.file).join(", ");
+    throw new Error(
+      `Cannot carry ${m.file}: the instance has ${names}, which describes the same migration but whose contents differ, and which carries no provenance marker. Refusing to guess.
+
+  If it IS this migration (carried before provenance was recorded, then renamed or edited), add this line above its 'revision' assignment and re-run:
+
+      ${CARRIED_FROM_MARKER} ${m.file}
+
+  If it is unrelated, rename it so the descriptions differ.
+
+  Carrying it blindly would re-issue an already-applied migration and run its DDL against a database that already has those objects (#366).`
+    );
   }
-  const { conflicted, content } = await mergeFile(baseContent, oursContent, theirsContent);
-  return { path, status: conflicted ? "conflict" : "merged", conflicted, content };
+  return null;
 }
-function applyUpgradePlan(instanceDir, plan, theirsDir) {
+function applyMigrationCarry(instanceDir, plan) {
   const written = [];
-  const deleted = [];
   for (const e of plan.entries) {
     const abs = join7(instanceDir, e.path);
-    if (e.status === "removed") {
-      if (existsSync7(abs)) {
-        rmSync2(abs);
-        deleted.push(e.path);
-      }
-      continue;
-    }
-    if (e.content !== void 0) {
-      mkdirSync2(dirname4(abs), { recursive: true });
-      writeFileSync3(abs, e.content);
-      if (theirsDir !== void 0) {
-        const source = join7(theirsDir, e.path);
-        if (existsSync7(source) && (statSync(source).mode & 73) !== 0) {
-          chmodSync(abs, 493);
-        }
-      }
-      written.push(e.path);
+    if (existsSync7(abs)) {
+      throw new Error(`Refusing to overwrite an existing migration: ${e.path}`);
     }
+    mkdirSync2(dirname4(abs), { recursive: true });
+    writeFileSync3(abs, e.content);
+    written.push(e.path);
   }
-  return { written, deleted };
-}
-function parseGitHubRepo(remoteUrl) {
-  const ssh = /^git@[^:]+:([^/]+)\/(.+?)(?:\.git)?\/?$/.exec(remoteUrl);
-  if (ssh && ssh[1] && ssh[2]) return { owner: ssh[1], repo: ssh[2] };
-  const https = /^https?:\/\/[^/]+\/([^/]+)\/(.+?)(?:\.git)?\/?$/.exec(remoteUrl);
-  if (https && https[1] && https[2]) return { owner: https[1], repo: https[2] };
-  throw new Error(`Could not parse a GitHub owner/repo from remote URL: ${remoteUrl}`);
-}
-var UPGRADE_BRANCH_PREFIX = "biffo/core-upgrade-";
-function upgradeBranchName(from, to) {
-  return `${UPGRADE_BRANCH_PREFIX}${from}-to-${to}`.replace(/[^a-zA-Z0-9._/-]/g, "-");
+  return written;
 }
 
 // src/lib/core-template-trees.ts
@@ -2446,7 +2507,10 @@ var coreUpgradeCommand = new Command3("upgrade").description("Three-way-merge te
 ).option(
   "--allow-dirty",
   "Compute the plan even with uncommitted changes in the instance tree (they become part of the merge)"
-).option("--base <branch>", "Base branch for the PR (defaults to the repo\u2019s default branch)").option("--remote <name>", "Git remote to push to and open the PR on (default: origin)").action(
+).option("--base <branch>", "Base branch for the PR (defaults to the repo\u2019s default branch)").option("--remote <name>", "Git remote to push to and open the PR on (default: origin)").option(
+  "--reap",
+  "Delete local branches previous upgrade runs left behind, once their PR has merged (#758)"
+).action(
   async (options) => {
     const cwd = options.cwd ? resolve3(options.cwd) : process.cwd();
     const runOptions = {
@@ -2462,6 +2526,7 @@ var coreUpgradeCommand = new Command3("upgrade").description("Three-way-merge te
     if (options.toTemplate) runOptions.theirsDir = resolve3(options.toTemplate);
     if (options.base) runOptions.base = options.base;
     if (options.remote) runOptions.remote = options.remote;
+    if (options.reap) runOptions.reap = true;
     try {
       await runCoreUpgrade(runOptions);
     } catch (err) {
@@ -2496,10 +2561,45 @@ async function runCoreUpgrade(options, deps = defaultDeps()) {
   const cleanups = [];
   try {
     await runCoreUpgradeResolved(options, deps, cleanups);
+    await reportUpgradeBranches(options, deps);
   } finally {
     for (const c of cleanups) c();
   }
 }
+async function reportUpgradeBranches(options, deps) {
+  const git = deps.git;
+  if (git.listBranchRefs === void 0 || git.fetchPrune === void 0) return;
+  try {
+    if (!await git.isGitRepo(options.cwd)) return;
+    await git.fetchPrune(options.cwd, options.remote);
+    const refs = await git.listBranchRefs(options.cwd);
+    const current = await git.currentBranch(options.cwd);
+    const { reapable, unverifiable } = classifyUpgradeBranches(refs, current);
+    if (reapable.length === 0 && unverifiable.length === 0) return;
+    if (reapable.length > 0 && options.reap === true && git.deleteBranch !== void 0) {
+      let deleted = 0;
+      for (const branch of reapable) {
+        if (await git.deleteBranch(options.cwd, branch)) deleted++;
+      }
+      log.success(`Reaped ${String(deleted)} merged upgrade branch(es).`);
+    } else if (reapable.length > 0) {
+      console.log(
+        chalk4.dim(
+          `
+  ${String(reapable.length)} previous upgrade branch(es) are merged and their remote copies are gone. Re-run with --reap to delete them.`
+        )
+      );
+    }
+    if (unverifiable.length > 0) {
+      console.log(
+        chalk4.dim(
+          `  ${String(unverifiable.length)} older upgrade branch(es) have no upstream recorded (created before #761), so they cannot be proven merged and are left alone.`
+        )
+      );
+    }
+  } catch {
+  }
+}
 async function checkInstanceCurrency(git, cwd, allowDirty) {
   if (!await git.isGitRepo(cwd)) return;
   const branch = await git.currentBranch(cwd);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.159.0",
+  "version": "0.161.0",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",