@mmerterden/multi-agent-pipeline 20.24.0 → 20.25.0

package/pipeline/scripts/dep-bump.mjs

@@ -0,0 +1,1556 @@
+#!/usr/bin/env node
+/**
+ * dep-bump.mjs  -  the deterministic half of /multi-agent:deps.
+ *
+ * Lists dependency candidates per ecosystem from the manifests, classifies the
+ * semver risk of a bump, applies ONE named bump to the manifest and its
+ * lockfile, and reports the bump's API surface so a fix round can be held to
+ * the breakage the bump caused. The model never edits a manifest version by
+ * hand: this script does, and it either applies the whole bump or nothing.
+ *
+ * Ecosystems: SwiftPM (Package.swift, Package.resolved), Gradle version
+ * catalogs (gradle/*.versions.toml), npm (package.json plus the lockfile of the
+ * resolved package manager) and pip (requirements*.txt, pyproject.toml).
+ *
+ * Listing works offline from the manifests and from what is already on disk:
+ * the lockfile for the current version, SwiftPM checkout tags and the Gradle
+ * module cache for newer ones. The registry is queried only with --registry,
+ * through the ecosystem's own tool (npm view, git ls-remote, curl for Maven
+ * and PyPI metadata); a query that fails is noted per package, never fatal.
+ *
+ * Usage:
+ *   dep-bump.mjs detect   --dir <repo>
+ *   dep-bump.mjs list     --dir <repo> [--ecosystem <e>] [--name <pkg>] [--registry]
+ *   dep-bump.mjs apply    --dir <repo> --ecosystem <e> --name <pkg> --to <ver>
+ *                         [--manifest <rel>] [--allow-major] [--no-lock]
+ *   dep-bump.mjs surface  --dir <repo> --ecosystem <e> --name <pkg>
+ *   dep-bump.mjs scope    --dir <repo> [--log <build-or-test-log>]
+ *   dep-bump.mjs notes    --dir <repo> --ecosystem <e> --name <pkg> --from <v> --to <v>
+ *   dep-bump.mjs rollback --dir <repo>
+ *   dep-bump.mjs config
+ *   dep-bump.mjs help
+ *
+ * Output is JSON on stdout (help prints plain usage). Exit codes: 0 ok, 1
+ * failure (not found, dirty tree, lockfile tool failed, files changed outside
+ * the bump's surface), 2 usage or a --to that is not a version, 3 a major,
+ * unclassifiable or prerelease bump without --allow-major.
+ *
+ * @module pipeline/scripts/dep-bump
+ */
+
+import { spawnSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, extname, join, relative } from "node:path";
+
+import { detect as detectPackageManager } from "./package-manager.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+export const ECOSYSTEMS = ["swiftpm", "gradle", "npm", "pip"];
+export const RECORD = join(".pipeline", "dep-bump.json");
+const PREF_MAX_FIX_ROUNDS = "depBump.maxFixRounds";
+const PREF_QUERY_REGISTRY = "depBump.queryRegistry";
+const DEFAULT_MAX_FIX_ROUNDS = 2;
+const TOOL_TIMEOUT_MS = 10 * 60 * 1000;
+const QUERY_TIMEOUT_MS = 30 * 1000;
+const OUTPUT_TAIL = 4000;
+const PRUNE = new Set([
+  "node_modules",
+  ".build",
+  "build",
+  ".git",
+  "Pods",
+  ".gradle",
+  ".pipeline",
+  "venv",
+  ".venv",
+  "dist",
+  "DerivedData",
+  "Carthage",
+  ".worktrees",
+  "__pycache__",
+]);
+const MAX_DEPTH = 4;
+
+class UsageError extends Error {}
+
+export const USAGE = `Usage:
+  dep-bump.mjs detect   --dir <repo>
+  dep-bump.mjs list     --dir <repo> [--ecosystem <e>] [--name <pkg>] [--registry]
+  dep-bump.mjs apply    --dir <repo> --ecosystem <e> --name <pkg> --to <ver>
+                        [--manifest <rel>] [--allow-major] [--no-lock]
+  dep-bump.mjs surface  --dir <repo> --ecosystem <e> --name <pkg>
+  dep-bump.mjs scope    --dir <repo> [--log <build-or-test-log>]
+  dep-bump.mjs notes    --dir <repo> --ecosystem <e> --name <pkg> --from <v> --to <v>
+  dep-bump.mjs rollback --dir <repo>
+  dep-bump.mjs config
+  dep-bump.mjs help
+
+Ecosystems: ${ECOSYSTEMS.join(", ")}.
+JSON on stdout. Exit: 0 ok, 1 failure, 2 usage, 3 a major, unknown or
+prerelease bump without --allow-major.
+`;
+
+// ─── semver ────────────────────────────────────────────────────────────────
+
+// Maven marks a release with a qualifier (-jre, -android, .Final, -RELEASE,
+// .GA, .SP1): for gradle that suffix is part of a stable version, not a
+// prerelease tag.
+const MAVEN_STABLE = /[.-](?:final|release|ga|jre|android|sp\d*)$/i;
+
+/**
+ * Loose semver: `v1.2`, `1.2.3`, `1.2.3-rc.1`; `+build` metadata is dropped.
+ * Under gradle a Maven release qualifier is stripped and a dotted qualifier
+ * (`1.0.0.Beta2`) reads as a prerelease tag. Anything else is null.
+ */
+export function parseVersion(v, ecosystem) {
+  let text = String(v ?? "").trim();
+  if (ecosystem === "gradle") {
+    text = text.replace(MAVEN_STABLE, "").replace(/^(\d+(?:\.\d+){0,2})\.(?=[A-Za-z])/, "$1-");
+  }
+  const m = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(
+    text,
+  );
+  if (!m) return null;
+  return { major: +m[1], minor: +(m[2] ?? 0), patch: +(m[3] ?? 0), pre: m[4] ?? "" };
+}
+
+function comparePre(a, b) {
+  if (a === b) return 0;
+  if (!a) return 1;
+  if (!b) return -1;
+  const pa = a.split(".");
+  const pb = b.split(".");
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    if (pa[i] === undefined) return -1;
+    if (pb[i] === undefined) return 1;
+    const na = /^\d+$/.test(pa[i]);
+    const nb = /^\d+$/.test(pb[i]);
+    if (na && nb && +pa[i] !== +pb[i]) return +pa[i] - +pb[i];
+    if (na !== nb) return na ? -1 : 1;
+    if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+export function compareVersions(a, b, ecosystem) {
+  const x = parseVersion(a, ecosystem);
+  const y = parseVersion(b, ecosystem);
+  if (!x || !y) return NaN;
+  return x.major - y.major || x.minor - y.minor || x.patch - y.patch || comparePre(x.pre, y.pre);
+}
+
+/**
+ * Risk of moving from `from` to `to`. Under 0.x a minor step is breaking and
+ * under 0.0.x every step is, which is what semver says those ranges mean.
+ */
+export function classifyRisk(from, to, ecosystem) {
+  const a = parseVersion(from, ecosystem);
+  const b = parseVersion(to, ecosystem);
+  if (!a || !b) return { risk: "unknown", prerelease: false };
+  const prerelease = Boolean(b.pre);
+  const cmp = compareVersions(from, to, ecosystem);
+  if (cmp === 0) return { risk: "none", prerelease };
+  if (cmp > 0) return { risk: "downgrade", prerelease };
+  if (a.major !== b.major) return { risk: "major", prerelease };
+  if (a.major === 0 && a.minor !== b.minor) return { risk: "major", prerelease };
+  if (a.major === 0 && a.minor === 0) return { risk: "major", prerelease };
+  if (a.minor !== b.minor) return { risk: "minor", prerelease };
+  return { risk: "patch", prerelease };
+}
+
+/** Highest stable version above `current`, and the highest that is not breaking. */
+export function pickTargets(current, versions, ecosystem) {
+  const parsed = (v) => parseVersion(v, ecosystem);
+  const newer = versions
+    .filter((v) => parsed(v) && !parsed(v).pre)
+    .map((v) => v.replace(/^v/, ""))
+    .filter((v) => !current || !parsed(current) || compareVersions(v, current, ecosystem) > 0)
+    .sort((x, y) => compareVersions(x, y, ecosystem));
+  if (newer.length === 0) return { latest: null, latestInMajor: null };
+  const latest = newer[newer.length - 1];
+  const compatible = current
+    ? newer.filter((v) => classifyRisk(current, v, ecosystem).risk !== "major")
+    : [];
+  return { latest, latestInMajor: compatible.length ? compatible[compatible.length - 1] : null };
+}
+
+// --to is written into a manifest as text, so it must be a version in the
+// ecosystem's own grammar: no quote, comma, semicolon, bracket or whitespace can
+// pass, whatever the risk of the bump.
+const SEMVER_TAIL =
+  "(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?";
+const TARGET_GRAMMAR = {
+  swiftpm: new RegExp(`^\\d+\\.\\d+\\.\\d+${SEMVER_TAIL}$`),
+  npm: new RegExp(`^\\d+(?:\\.\\d+){0,2}${SEMVER_TAIL}$`),
+  gradle: /^\d[0-9A-Za-z._-]{0,63}$/,
+  pip: /^(?:\d+!)?\d+(?:\.\d+)*(?:(?:a|b|c|rc|alpha|beta|pre|preview)\.?\d*)?(?:\.?post\d*)?(?:\.?dev\d*)?(?:\+[a-z0-9]+(?:\.[a-z0-9]+)*)?$/i,
+};
+
+export function validTarget(ecosystem, to) {
+  return typeof to === "string" && Boolean(TARGET_GRAMMAR[ecosystem]?.test(to));
+}
+
+// ─── manifest readers ──────────────────────────────────────────────────────
+
+function lineOf(text, index) {
+  return text.slice(0, index).split("\n").length;
+}
+
+/**
+ * `text` with every Swift comment replaced by spaces, newlines kept, so offsets
+ * still index the original. String literals are skipped whole.
+ */
+export function blankSwiftComments(text) {
+  const out = text.split("");
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === '"') {
+      for (i++; i < text.length && text[i] !== '"' && text[i] !== "\n"; i++)
+        if (text[i] === "\\") i++;
+    } else if (text.startsWith("//", i)) {
+      for (; i < text.length && text[i] !== "\n"; i++) out[i] = " ";
+    } else if (text.startsWith("/*", i)) {
+      const end = text.indexOf("*/", i + 2);
+      const stop = end === -1 ? text.length : end + 2;
+      for (; i < stop; i++) if (text[i] !== "\n") out[i] = " ";
+      i--;
+    }
+  }
+  return out.join("");
+}
+
+/** Balanced-paren segments of every `.package(` call outside comments. */
+function packageCalls(text) {
+  const code = blankSwiftComments(text);
+  const calls = [];
+  let i = code.indexOf(".package(");
+  while (i !== -1) {
+    let depth = 0;
+    let j = i + ".package".length;
+    for (; j < code.length; j++) {
+      if (code[j] === "(") depth++;
+      else if (code[j] === ")" && --depth === 0) break;
+    }
+    calls.push({ start: i, end: j + 1, body: text.slice(i, j + 1) });
+    i = code.indexOf(".package(", j);
+  }
+  return calls;
+}
+
+export function swiftIdentity(url) {
+  return basename(String(url).replace(/\/+$/, ""))
+    .replace(/\.git$/, "")
+    .toLowerCase();
+}
+
+const SWIFT_REQUIREMENTS = [
+  ["upToNextMajor", /upToNextMajor\(\s*from:\s*"([^"]+)"/],
+  ["upToNextMinor", /upToNextMinor\(\s*from:\s*"([^"]+)"/],
+  ["exact", /\bexact:\s*"([^"]+)"/],
+  ["from", /\bfrom:\s*"([^"]+)"/],
+  ["range", /"([^"]+)"\s*\.\.[<.]\s*"([^"]+)"/],
+];
+
+export function readPackageSwift(text) {
+  const deps = [];
+  for (const call of packageCalls(text)) {
+    const url = /url:\s*"([^"]+)"/.exec(call.body)?.[1];
+    if (!url) continue;
+    for (const [kind, re] of SWIFT_REQUIREMENTS) {
+      const m = re.exec(call.body);
+      if (!m) continue;
+      deps.push({
+        name: swiftIdentity(url),
+        url,
+        kind,
+        declared: m[1],
+        line: lineOf(text, call.start),
+      });
+      break;
+    }
+  }
+  return deps;
+}
+
+function swiftProducts(text, identity) {
+  const out = new Set();
+  const re = /\.product\(\s*name:\s*"([^"]+)"\s*,\s*package:\s*"([^"]+)"/g;
+  for (const m of text.matchAll(re)) if (m[2].toLowerCase() === identity) out.add(m[1]);
+  return [...out];
+}
+
+function readResolvedPins(text) {
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const p of json.pins ?? json.object?.pins ?? []) {
+    const url = p.location ?? p.repositoryURL ?? "";
+    const id = (p.identity ?? swiftIdentity(url || p.package || "")).toLowerCase();
+    if (p.state?.version)
+      out.push({ name: id, url, declared: p.state.version, current: p.state.version });
+  }
+  return out;
+}
+
+function readResolved(text) {
+  const pins = new Map();
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    return pins;
+  }
+  for (const p of json.pins ?? json.object?.pins ?? []) {
+    const id = p.identity ?? swiftIdentity(p.location ?? p.repositoryURL ?? p.package ?? "");
+    if (p.state?.version) pins.set(id.toLowerCase(), p.state.version);
+  }
+  return pins;
+}
+
+function tomlSections(text) {
+  const out = [];
+  let section = "";
+  const lines = text.split("\n");
+  lines.forEach((raw, idx) => {
+    const line = raw.replace(/\s+#.*$/, "");
+    const head = /^\s*\[([^\]]+)\]\s*$/.exec(line);
+    if (head) {
+      section = head[1].trim();
+      return;
+    }
+    out.push({ section, line, idx });
+  });
+  return out;
+}
+
+export function readVersionCatalog(text) {
+  const rows = tomlSections(text);
+  const versions = new Map();
+  for (const { section, line } of rows) {
+    if (section !== "versions") continue;
+    const m = /^\s*([\w.-]+)\s*=\s*(?:"([^"]+)"|\{[^}]*?"([^"]+)")/.exec(line);
+    if (m) versions.set(m[1], m[2] ?? m[3]);
+  }
+  const deps = [];
+  for (const { section, line, idx } of rows) {
+    if (section !== "libraries" && section !== "plugins") continue;
+    const m = /^\s*([\w.-]+)\s*=\s*(.+)$/.exec(line);
+    if (!m) continue;
+    const [, alias, rhs] = m;
+    const kind = section === "plugins" ? "plugin" : "library";
+    let name;
+    let declared;
+    let versionRef;
+    const str = /^"([^"]+)"/.exec(rhs);
+    if (str) {
+      const parts = str[1].split(":");
+      if (kind === "library" && parts.length === 3)
+        [name, declared] = [`${parts[0]}:${parts[1]}`, parts[2]];
+      else if (kind === "plugin" && parts.length === 2) [name, declared] = parts;
+      else continue;
+    } else {
+      const get = (k) => new RegExp(`\\b${k.replace(".", "\\.")}\\s*=\\s*"([^"]+)"`).exec(rhs)?.[1];
+      name =
+        kind === "plugin"
+          ? get("id")
+          : (get("module") ??
+            (get("group") && get("name") ? `${get("group")}:${get("name")}` : null));
+      versionRef = get("version.ref") ?? /version\s*=\s*\{\s*ref\s*=\s*"([^"]+)"/.exec(rhs)?.[1];
+      declared = versionRef ? versions.get(versionRef) : get("version");
+    }
+    if (!name || !declared) continue;
+    deps.push({
+      name,
+      alias,
+      kind,
+      declared,
+      ...(versionRef ? { versionRef } : {}),
+      line: idx + 1,
+    });
+  }
+  return deps;
+}
+
+const PEP508_HEAD = /^([A-Za-z0-9][A-Za-z0-9._-]*)\s*(\[[^\]]*\])?\s*\(?([^;#]*)/;
+const PEP440_CLAUSE = /^\s*(===|==|~=|>=|<=|!=|>|<)\s*([^\s,;#()]+)\s*$/;
+const PRIMARY_OPS = new Set(["===", "==", "~=", ">=", ">"]);
+
+/**
+ * A PEP 508 requirement split into its version clauses. The primary clause is
+ * the first exact or lower bound; `<`, `<=` and `!=` only constrain it, so a
+ * requirement made of those alone has nothing to bump and reads as null.
+ */
+export function parsePep508(text) {
+  const m = PEP508_HEAD.exec(String(text).trim());
+  if (!m) return null;
+  const spec = m[3].replace(/\)\s*$/, "").trim();
+  if (!spec) return null;
+  const clauses = [];
+  for (const part of spec.split(",")) {
+    const c = PEP440_CLAUSE.exec(part);
+    if (!c) return null;
+    clauses.push({ op: c[1], version: c[2] });
+  }
+  const primary = clauses.find((c) => PRIMARY_OPS.has(c.op));
+  if (!primary) return null;
+  return { name: m[1], op: primary.op, declared: primary.version, clauses };
+}
+
+export function readRequirements(text) {
+  const deps = [];
+  text.split("\n").forEach((raw, idx) => {
+    const line = raw.replace(/\s#.*$/, "").trim();
+    if (!line || line.startsWith("#") || line.startsWith("-")) return;
+    const d = parsePep508(line);
+    if (d) deps.push({ ...d, line: idx + 1 });
+  });
+  return deps;
+}
+
+/** The clause of a pip requirement that `to` would violate, or null. */
+export function pipExclusion(dep, to) {
+  for (const c of dep.clauses ?? []) {
+    if (c.op === dep.op && c.version === dep.declared) continue;
+    const label = `${c.op}${c.version}`;
+    if (c.version.endsWith(".*")) {
+      const prefix = c.version.slice(0, -2);
+      const inside = to === prefix || to.startsWith(`${prefix}.`);
+      if ((c.op === "!=" && inside) || (c.op === "==" && !inside)) return label;
+      continue;
+    }
+    const cmp = compareVersions(to, c.version);
+    if (Number.isNaN(cmp)) return label;
+    const ok = {
+      "<": cmp < 0,
+      "<=": cmp <= 0,
+      "!=": cmp !== 0,
+      "==": cmp === 0,
+      "===": cmp === 0,
+      ">": cmp > 0,
+      ">=": cmp >= 0,
+      "~=": cmp >= 0,
+    }[c.op];
+    if (!ok) return label;
+  }
+  return null;
+}
+
+export function readPyproject(text) {
+  const deps = [];
+  for (const { section, line, idx } of tomlSections(text)) {
+    if (/^tool\.poetry\.(group\.[^.]+\.)?(dev-)?dependencies$/.test(section)) {
+      const m = /^\s*([A-Za-z0-9][\w.-]*)\s*=\s*(?:"([^"]+)"|\{[^}]*version\s*=\s*"([^"]+)")/.exec(
+        line,
+      );
+      if (!m || m[1] === "python") continue;
+      const spec = m[2] ?? m[3];
+      const v = /^(\^|~=|~|>=|==)?\s*(\d[\w.-]*)$/.exec(spec);
+      if (v)
+        deps.push({ name: m[1], op: v[1] ?? "", declared: v[2], line: idx + 1, style: "poetry" });
+      continue;
+    }
+    if (
+      section === "project" ||
+      section === "project.optional-dependencies" ||
+      section === "dependency-groups"
+    ) {
+      for (const q of line.matchAll(/"([^"]+)"/g)) {
+        const d = parsePep508(q[1]);
+        if (d) deps.push({ ...d, line: idx + 1, style: "pep621" });
+      }
+    }
+  }
+  return deps;
+}
+
+const NPM_SECTIONS = ["dependencies", "devDependencies", "optionalDependencies"];
+const NPM_SPEC = /^(\^|~|>=|=)?v?(\d+(?:\.\d+){0,2}(?:-[\w.]+)?)$/;
+
+export function readPackageJson(text) {
+  const pkg = JSON.parse(text);
+  const deps = [];
+  for (const section of NPM_SECTIONS) {
+    for (const [name, spec] of Object.entries(pkg[section] ?? {})) {
+      const m = NPM_SPEC.exec(String(spec).trim());
+      if (m) deps.push({ name, section, spec, op: m[1] ?? "", declared: m[2] });
+    }
+  }
+  return deps;
+}
+
+function readNpmLock(dir) {
+  const p = join(dir, "package-lock.json");
+  if (!existsSync(p)) return new Map();
+  try {
+    const lock = JSON.parse(readFileSync(p, "utf8"));
+    const out = new Map();
+    for (const [k, v] of Object.entries(lock.packages ?? {})) {
+      if (k.startsWith("node_modules/") && !k.slice(13).includes("node_modules/") && v.version) {
+        out.set(k.slice(13), v.version);
+      }
+    }
+    for (const [k, v] of Object.entries(lock.dependencies ?? {}))
+      if (!out.has(k) && v.version) out.set(k, v.version);
+    return out;
+  } catch {
+    return new Map();
+  }
+}
+
+function readPyLock(dir) {
+  const out = new Map();
+  for (const f of ["poetry.lock", "uv.lock"]) {
+    const p = join(dir, f);
+    if (!existsSync(p)) continue;
+    const text = readFileSync(p, "utf8");
+    for (const m of text.matchAll(
+      /\[\[package\]\]\s*\nname\s*=\s*"([^"]+)"\s*\nversion\s*=\s*"([^"]+)"/g,
+    )) {
+      out.set(normalizePy(m[1]), m[2]);
+    }
+  }
+  return out;
+}
+
+const normalizePy = (n) => n.toLowerCase().replace(/[-_.]+/g, "-");
+
+// ─── discovery ─────────────────────────────────────────────────────────────
+
+// An Xcode project keeps its own SwiftPM pins inside the bundle; the bundle is
+// probed at that one path and never walked.
+const XCODE_RESOLVED_IN = {
+  ".xcodeproj": "project.xcworkspace/xcshareddata/swiftpm/Package.resolved",
+  ".xcworkspace": "xcshareddata/swiftpm/Package.resolved",
+};
+const XCODE_RESOLVED =
+  /\.(xcodeproj\/project\.xcworkspace|xcworkspace)\/xcshareddata\/swiftpm\/Package\.resolved$/;
+const XCODE_NOTE =
+  "pinned by an Xcode project: the requirement lives in project.pbxproj, which dep-bump does not edit; bump it in Xcode (File > Packages) instead";
+
+const isXcodeResolved = (manifest) => XCODE_RESOLVED.test(manifest);
+
+function walk(root, visit, rel = "", depth = 0) {
+  let entries;
+  try {
+    entries = readdirSync(join(root, rel), { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const r = rel ? `${rel}/${e.name}` : e.name;
+    if (e.isDirectory()) {
+      const xcode = XCODE_RESOLVED_IN[extname(e.name)];
+      if (xcode) {
+        if (existsSync(join(root, r, xcode))) visit(`${r}/${xcode}`, "Package.resolved");
+      } else if (!PRUNE.has(e.name) && depth < MAX_DEPTH) walk(root, visit, r, depth + 1);
+    } else if (e.isFile()) visit(r, e.name);
+  }
+}
+
+function manifestEcosystem(rel, name) {
+  if (name === "Package.swift" || isXcodeResolved(rel)) return "swiftpm";
+  if (name === "package.json") return "npm";
+  if (name.endsWith(".versions.toml") && /(^|\/)gradle\/[^/]+$/.test(rel)) return "gradle";
+  if (/^requirements[\w.-]*\.txt$/.test(name) || name === "pyproject.toml") return "pip";
+  return null;
+}
+
+export function detect(dir) {
+  const found = [];
+  walk(dir, (rel, name) => {
+    const ecosystem = manifestEcosystem(rel, name);
+    if (!ecosystem) return;
+    if (isXcodeResolved(rel))
+      found.push({ ecosystem, manifest: rel, lockfile: null, readOnly: true });
+    else {
+      const lockError = ecosystem === "npm" ? npmLockRoot(dir, rel).error : undefined;
+      found.push({
+        ecosystem,
+        manifest: rel,
+        lockfile: lockfileFor(dir, ecosystem, rel),
+        ...(lockError ? { lockError } : {}),
+      });
+    }
+  });
+  found.sort(
+    (a, b) => a.ecosystem.localeCompare(b.ecosystem) || a.manifest.localeCompare(b.manifest),
+  );
+  return found;
+}
+
+/** The directory a Gradle catalog belongs to is the one holding `gradle/`. */
+function manifestRoot(dir, ecosystem, manifest) {
+  const d = dirname(join(dir, manifest));
+  return ecosystem === "gradle" ? dirname(d) : d;
+}
+
+const NPM_LOCKFILES = [
+  "package-lock.json",
+  "npm-shrinkwrap.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "bun.lock",
+  "bun.lockb",
+];
+
+function isWorkspaceRoot(d) {
+  if (existsSync(join(d, "pnpm-workspace.yaml"))) return true;
+  try {
+    return Boolean(JSON.parse(readFileSync(join(d, "package.json"), "utf8")).workspaces);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Where an npm manifest's lockfile lives. A workspace member has none of its
+ * own: the nearest lockfile above it, up to the repo root, belongs to the
+ * workspace root, and the lockfile tool runs there. A lockfile above a manifest
+ * in a directory that declares no workspaces is reported as `error`, so the
+ * bump fails instead of going ahead with no lockfile.
+ */
+function npmLockRoot(dir, manifest) {
+  const own = dirname(join(dir, manifest));
+  const top = join(dir);
+  for (let d = own; ; d = dirname(d)) {
+    const hit = NPM_LOCKFILES.find((f) => existsSync(join(d, f)));
+    if (hit) {
+      const lockfile = relative(dir, join(d, hit));
+      if (d === own || isWorkspaceRoot(d)) return { root: d, lockfile };
+      return {
+        root: own,
+        lockfile,
+        error: `${lockfile} sits above ${manifest} in a directory that declares no workspaces`,
+      };
+    }
+    if (d === top || d === dirname(d)) return { root: own, lockfile: null };
+  }
+}
+
+function lockfileFor(dir, ecosystem, manifest) {
+  if (ecosystem === "npm") return npmLockRoot(dir, manifest).lockfile;
+  const root = manifestRoot(dir, ecosystem, manifest);
+  const candidates = {
+    swiftpm: ["Package.resolved"],
+    gradle: ["gradle.lockfile"],
+    pip: basename(manifest) === "pyproject.toml" ? ["poetry.lock", "uv.lock"] : [],
+  }[ecosystem];
+  const hit = candidates.find((f) => existsSync(join(root, f)));
+  return hit ? relative(dir, join(root, hit)) : null;
+}
+
+function readDeps(dir, ecosystem, manifest) {
+  const text = readFileSync(join(dir, manifest), "utf8");
+  const root = manifestRoot(dir, ecosystem, manifest);
+  if (ecosystem === "swiftpm" && isXcodeResolved(manifest)) {
+    return readResolvedPins(text).map((p) => ({ ...p, kind: "xcode-pin", readOnly: true }));
+  }
+  if (ecosystem === "swiftpm") {
+    const pins = existsSync(join(root, "Package.resolved"))
+      ? readResolved(readFileSync(join(root, "Package.resolved"), "utf8"))
+      : new Map();
+    return readPackageSwift(text).map((d) => ({ ...d, current: pins.get(d.name) ?? d.declared }));
+  }
+  if (ecosystem === "gradle")
+    return readVersionCatalog(text).map((d) => ({ ...d, current: d.declared }));
+  if (ecosystem === "npm") {
+    const lock = readNpmLock(npmLockRoot(dir, manifest).root);
+    return readPackageJson(text).map((d) => ({ ...d, current: lock.get(d.name) ?? d.declared }));
+  }
+  const lock = readPyLock(root);
+  const deps =
+    basename(manifest) === "pyproject.toml" ? readPyproject(text) : readRequirements(text);
+  return deps.map((d) => ({ ...d, current: lock.get(normalizePy(d.name)) ?? d.declared }));
+}
+
+// ─── version sources ───────────────────────────────────────────────────────
+
+function sh(cmd, args, opts = {}) {
+  const res = spawnSync(cmd, args, {
+    encoding: "utf8",
+    timeout: opts.timeout ?? QUERY_TIMEOUT_MS,
+    cwd: opts.cwd,
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  const output = `${res.stdout ?? ""}${res.stderr ?? ""}`;
+  return {
+    ok: res.status === 0 && !res.error,
+    stdout: res.stdout ?? "",
+    output: res.error ? `${res.error.code ?? res.error.message}` : output,
+  };
+}
+
+function gradleCacheVersions(dep) {
+  const home = process.env.GRADLE_USER_HOME || join(homedir(), ".gradle");
+  const [group, artifact] =
+    dep.kind === "plugin" ? [dep.name, `${dep.name}.gradle.plugin`] : dep.name.split(":");
+  const d = join(home, "caches", "modules-2", "files-2.1", group, artifact ?? "");
+  try {
+    return readdirSync(d).filter((v) => statSync(join(d, v)).isDirectory());
+  } catch {
+    return [];
+  }
+}
+
+function checkoutTags(root, dep) {
+  const co = join(root, ".build", "checkouts", dep.name);
+  if (!existsSync(co)) return [];
+  const r = sh("git", ["-C", co, "tag", "--list"]);
+  return r.ok ? r.stdout.split("\n").filter(Boolean) : [];
+}
+
+function offlineVersions(dir, ecosystem, manifest, dep) {
+  if (ecosystem === "gradle") return { versions: gradleCacheVersions(dep), source: "gradle-cache" };
+  if (ecosystem === "swiftpm") {
+    return {
+      versions: checkoutTags(manifestRoot(dir, ecosystem, manifest), dep),
+      source: "checkout-tags",
+    };
+  }
+  return { versions: [], source: null };
+}
+
+function mavenMetadataUrl(dep) {
+  const [group, artifact] =
+    dep.kind === "plugin" ? [dep.name, `${dep.name}.gradle.plugin`] : dep.name.split(":");
+  const google = /^(androidx\.|com\.android\.|com\.google\.android\.)/.test(group);
+  const base = google
+    ? "https://dl.google.com/android/maven2"
+    : "https://repo.maven.apache.org/maven2";
+  return `${base}/${group.replace(/\./g, "/")}/${artifact}/maven-metadata.xml`;
+}
+
+// Names and urls come from the repo's manifests, so each one is checked against
+// its ecosystem's grammar before it reaches a tool's argv: a value that starts
+// with "-" would otherwise be parsed as an option (git --upload-pack runs a
+// command, npm --registry redirects the query).
+const REMOTE_URL = /^(?:(?:https?|ssh|git|file):\/\/[^\s]+|git@[^\s]+:[^\s]+)$/;
+const NAME_GRAMMAR = {
+  npm: /^(?:@[a-z0-9~][a-z0-9._~-]*\/)?[a-z0-9~][a-z0-9._~-]*$/i,
+  gradle: /^[A-Za-z0-9_][A-Za-z0-9._-]*(?::[A-Za-z0-9_][A-Za-z0-9._-]*)?$/,
+  pip: /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/,
+};
+
+/** Why `dep` may not be queried, or null when its name or url is well formed. */
+export function queryRefusal(ecosystem, dep) {
+  if (ecosystem === "swiftpm") {
+    return REMOTE_URL.test(String(dep.url ?? ""))
+      ? null
+      : `url ${JSON.stringify(dep.url)} is not an http(s), ssh, git, file or git@host: url`;
+  }
+  return NAME_GRAMMAR[ecosystem]?.test(String(dep.name ?? ""))
+    ? null
+    : `name ${JSON.stringify(dep.name)} is not a valid ${ecosystem} package name`;
+}
+
+// Every tool runs in the manifest's directory, so the repo's own configuration
+// (.npmrc registries and scopes, git and curl settings) applies to the query.
+function registryVersions(ecosystem, dep, cwd) {
+  const refusal = queryRefusal(ecosystem, dep);
+  if (refusal) return { skipped: refusal };
+  let r;
+  if (ecosystem === "npm") {
+    r = sh("npm", ["view", "--json", "--", dep.name, "versions"], { cwd });
+    if (!r.ok) return { error: r.output.trim().split("\n").pop() };
+    try {
+      const parsed = JSON.parse(r.stdout);
+      const list = Array.isArray(parsed) ? parsed : (parsed.versions ?? [parsed]);
+      return { versions: list.map(String) };
+    } catch {
+      return { error: "unparseable npm view output" };
+    }
+  }
+  if (ecosystem === "swiftpm") {
+    r = sh("git", ["ls-remote", "--tags", "--refs", "--", dep.url], { cwd });
+    if (!r.ok) return { error: r.output.trim().split("\n").pop() };
+    return { versions: [...r.stdout.matchAll(/refs\/tags\/(\S+)/g)].map((m) => m[1]) };
+  }
+  if (ecosystem === "gradle") {
+    r = sh("curl", ["-fsSL", "--max-time", "20", mavenMetadataUrl(dep)], { cwd });
+    if (!r.ok) return { error: r.output.trim().split("\n").pop() };
+    return { versions: [...r.stdout.matchAll(/<version>([^<]+)<\/version>/g)].map((m) => m[1]) };
+  }
+  r = sh("curl", ["-fsSL", "--max-time", "20", `https://pypi.org/pypi/${dep.name}/json`], {
+    cwd,
+  });
+  if (!r.ok) return { error: r.output.trim().split("\n").pop() };
+  try {
+    return { versions: Object.keys(JSON.parse(r.stdout).releases ?? {}) };
+  } catch {
+    return { error: "unparseable PyPI response" };
+  }
+}
+
+export function list(dir, { ecosystem, name, registry = false } = {}) {
+  const candidates = [];
+  for (const m of detect(dir)) {
+    if (ecosystem && m.ecosystem !== ecosystem) continue;
+    let deps;
+    try {
+      deps = readDeps(dir, m.ecosystem, m.manifest);
+    } catch (err) {
+      candidates.push({ ecosystem: m.ecosystem, manifest: m.manifest, error: String(err.message) });
+      continue;
+    }
+    for (const dep of deps) {
+      if (name && dep.name !== name) continue;
+      let versions = [];
+      let source = null;
+      let note;
+      if (registry) {
+        const r = registryVersions(m.ecosystem, dep, dirname(join(dir, m.manifest)));
+        if (r.skipped) note = `registry query skipped: ${r.skipped}`;
+        else if (r.error) note = `registry query failed: ${r.error}`;
+        else [versions, source] = [r.versions, "registry"];
+      }
+      if (!source) {
+        const off = offlineVersions(dir, m.ecosystem, m.manifest, dep);
+        if (off.versions.length) [versions, source] = [off.versions, off.source];
+      }
+      const t = pickTargets(dep.current, versions, m.ecosystem);
+      candidates.push({
+        ecosystem: m.ecosystem,
+        manifest: m.manifest,
+        name: dep.name,
+        declared: dep.declared,
+        current: dep.current,
+        latest: t.latest,
+        latestInMajor: t.latestInMajor,
+        risk: t.latest ? classifyRisk(dep.current, t.latest, m.ecosystem).risk : null,
+        riskInMajor: t.latestInMajor
+          ? classifyRisk(dep.current, t.latestInMajor, m.ecosystem).risk
+          : null,
+        source,
+        ...(dep.readOnly ? { readOnly: true } : {}),
+        ...(note || dep.readOnly
+          ? { note: [dep.readOnly ? XCODE_NOTE : null, note].filter(Boolean).join("; ") }
+          : {}),
+      });
+    }
+  }
+  return {
+    dir,
+    registry: registry
+      ? {
+          queried: true,
+          note: "registry queried through the ecosystem tool; failures are noted per package",
+        }
+      : {
+          queried: false,
+          note: "registry query skipped (offline listing from manifests, lockfiles and local caches; pass --registry to query)",
+        },
+    candidates,
+  };
+}
+
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+
+// ─── apply ─────────────────────────────────────────────────────────────────
+
+function replaceAt(text, start, end, from, to) {
+  const seg = text.slice(start, end);
+  const i = seg.indexOf(from);
+  if (i === -1) return null;
+  return text.slice(0, start) + seg.slice(0, i) + to + seg.slice(i + from.length) + text.slice(end);
+}
+
+function lineSpan(text, line) {
+  let start = 0;
+  for (let i = 1; i < line; i++) start = text.indexOf("\n", start) + 1;
+  const nl = text.indexOf("\n", start);
+  return [start, nl === -1 ? text.length : nl];
+}
+
+function editSwift(text, dep, to) {
+  const call = packageCalls(text).find(
+    (c) => swiftIdentity(/url:\s*"([^"]+)"/.exec(c.body)?.[1] ?? "") === dep.name,
+  );
+  if (!call) return null;
+  if (dep.kind === "range") {
+    const m = /"([^"]+)"(\s*)(\.\.[<.])(\s*)"([^"]+)"/.exec(call.body);
+    if (!m) return null;
+    const [, , gapA, op, gapB, upper] = m;
+    const cmp = compareVersions(to, upper);
+    const inside = op === "..." ? cmp <= 0 : cmp < 0;
+    const range = inside
+      ? `"${to}"${gapA}${op}${gapB}"${upper}"`
+      : `"${to}"${gapA}..<${gapB}"${parseVersion(to).major + 1}.0.0"`;
+    const body = call.body.slice(0, m.index) + range + call.body.slice(m.index + m[0].length);
+    return text.slice(0, call.start) + body + text.slice(call.end);
+  }
+  return replaceAt(text, call.start, call.end, `"${dep.declared}"`, `"${to}"`);
+}
+
+function editCatalog(text, dep, to) {
+  if (dep.versionRef) {
+    const rows = tomlSections(text).filter(
+      (r) =>
+        r.section === "versions" &&
+        new RegExp(`^\\s*${dep.versionRef.replace(/[.-]/g, "\\$&")}\\s*=`).test(r.line),
+    );
+    if (!rows.length) return null;
+    const [s, e] = lineSpan(text, rows[0].idx + 1);
+    return replaceAt(text, s, e, `"${dep.declared}"`, `"${to}"`);
+  }
+  const [s, e] = lineSpan(text, dep.line);
+  return replaceAt(text, s, e, `${dep.declared}"`, `${to}"`);
+}
+
+/** [start, end) of the object value of top-level key `key` in a JSON text. */
+export function jsonObjectSpan(text, key) {
+  let depth = 0;
+  let pendingKey = null;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '"') {
+      let j = i + 1;
+      while (j < text.length && text[j] !== '"') j += text[j] === "\\" ? 2 : 1;
+      const str = text.slice(i + 1, j);
+      if (depth === 1 && /^\s*:/.test(text.slice(j + 1))) pendingKey = str;
+      i = j;
+      continue;
+    }
+    if (ch === "{" || ch === "[") {
+      if (depth === 1 && ch === "{" && pendingKey === key) {
+        let d = 0;
+        for (let k = i; k < text.length; k++) {
+          const c = text[k];
+          if (c === '"') {
+            k++;
+            while (k < text.length && text[k] !== '"') k += text[k] === "\\" ? 2 : 1;
+          } else if (c === "{") d++;
+          else if (c === "}" && --d === 0) return [i, k + 1];
+        }
+        return null;
+      }
+      depth++;
+      pendingKey = null;
+    } else if (ch === "}" || ch === "]") depth--;
+    else if (ch === ",") pendingKey = null;
+  }
+  return null;
+}
+
+function editNpm(text, dep, to) {
+  const span = jsonObjectSpan(text, dep.section);
+  if (!span) return null;
+  const seg = text.slice(span[0], span[1]);
+  const re = new RegExp(`("${esc(dep.name)}"\\s*:\\s*")${esc(dep.spec)}"`);
+  const next = seg.replace(re, `$1${dep.op}${to}"`);
+  return next === seg ? null : text.slice(0, span[0]) + next + text.slice(span[1]);
+}
+
+function editPip(text, dep, to) {
+  const [s, e] = lineSpan(text, dep.line);
+  const seg = text.slice(s, e);
+  if (dep.style === "poetry") {
+    const re = new RegExp(`"${esc(dep.op || "")}\\s*${esc(dep.declared)}"`);
+    const replaced = seg.replace(re, `"${dep.op}${to}"`);
+    return replaced === seg ? null : text.slice(0, s) + replaced + text.slice(e);
+  }
+  const at = new RegExp(`(^|["'\\s])${esc(dep.name)}(?=\\s*[\\[(<>=!~])`).exec(seg);
+  if (!at) return null;
+  const from = at.index + at[0].length;
+  const stop = seg.slice(from).search(/["';#]/);
+  const to_ = stop === -1 ? seg.length : from + stop;
+  const spec = seg.slice(from, to_);
+  const clause = new RegExp(`(^|[\\s,(\\]])${esc(dep.op)}(\\s*)${esc(dep.declared)}(?![\\w.*])`);
+  const next = spec.replace(clause, (_, lead, gap) => `${lead}${dep.op}${gap}${to}`);
+  if (next === spec) return null;
+  return text.slice(0, s) + seg.slice(0, from) + next + seg.slice(to_) + text.slice(e);
+}
+
+const EDITORS = { swiftpm: editSwift, gradle: editCatalog, npm: editNpm, pip: editPip };
+
+/** Major version a tool reports for --version, or null when it cannot say. */
+function toolMajor(cmd, cwd) {
+  const r = sh(cmd, ["--version"], { cwd });
+  const m = r.ok ? /(\d+)\.\d+/.exec(r.stdout) : null;
+  return m ? +m[1] : null;
+}
+
+function lockCommand(dir, ecosystem, manifest, lockfile, name) {
+  const cwd =
+    ecosystem === "npm" ? npmLockRoot(dir, manifest).root : manifestRoot(dir, ecosystem, manifest);
+  if (ecosystem === "swiftpm") return { cwd, cmd: "swift", args: ["package", "resolve"] };
+  if (ecosystem === "gradle") {
+    const wrapper = existsSync(join(cwd, "gradlew"));
+    return { cwd, cmd: wrapper ? "./gradlew" : "gradle", args: ["dependencies", "--write-locks"] };
+  }
+  if (ecosystem === "npm") {
+    const pm = detectPackageManager(cwd).pm;
+    const yarnBerry = pm === "yarn" && (toolMajor("yarn", cwd) ?? 1) >= 2;
+    const args = {
+      npm: ["install", "--package-lock-only", "--ignore-scripts", "--no-audit", "--no-fund"],
+      pnpm: ["install", "--lockfile-only", "--ignore-scripts"],
+      yarn: yarnBerry ? ["install", "--mode=skip-build"] : ["install", "--ignore-scripts"],
+      bun: ["install", "--ignore-scripts"],
+    }[pm];
+    return args ? { cwd, cmd: pm, args } : null;
+  }
+  if (basename(lockfile) === "poetry.lock") {
+    const modern = (toolMajor("poetry", cwd) ?? 1) >= 2;
+    return { cwd, cmd: "poetry", args: modern ? ["lock"] : ["lock", "--no-update"] };
+  }
+  return { cwd, cmd: "uv", args: ["lock", "--upgrade-package", name] };
+}
+
+function git(dir, args) {
+  return sh("git", ["-C", dir, ...args], { timeout: 60000 });
+}
+
+function untracked(dir) {
+  const r = git(dir, ["ls-files", "--others", "--exclude-standard"]);
+  return r.ok ? r.stdout.split("\n").filter((f) => f && !f.startsWith(".pipeline/")) : [];
+}
+
+/** Tracked files with uncommitted changes; empty outside a git checkout. */
+function dirtyTracked(dir) {
+  const r = git(dir, ["status", "--porcelain", "--untracked-files=no"]);
+  if (!r.ok) return [];
+  return r.stdout
+    .split("\n")
+    .filter(Boolean)
+    .map((l) => l.slice(3).replace(/^.* -> /, ""))
+    .filter((f) => !f.startsWith(".pipeline/"));
+}
+
+function writeRecord(dir, rec) {
+  mkdirSync(join(dir, ".pipeline"), { recursive: true });
+  writeFileSync(join(dir, RECORD), `${JSON.stringify(rec, null, 2)}\n`);
+}
+
+function resolveTarget(dir, ecosystem, name, manifest) {
+  const hits = [];
+  for (const m of detect(dir)) {
+    if (m.ecosystem !== ecosystem || (manifest && m.manifest !== manifest)) continue;
+    for (const d of readDeps(dir, ecosystem, m.manifest)) {
+      const same = ecosystem === "swiftpm" ? d.name === name.toLowerCase() : d.name === name;
+      if (same || d.alias === name) hits.push({ ...m, dep: d });
+    }
+  }
+  return hits;
+}
+
+export function apply(dir, opts) {
+  const { ecosystem, name, to, manifest, allowMajor = false, lock = true } = opts;
+  if (!validTarget(ecosystem, to))
+    return { code: 2, out: { error: `${JSON.stringify(to)} is not a valid ${ecosystem} version` } };
+  const found = resolveTarget(dir, ecosystem, name, manifest);
+  const hits = found.filter((h) => !h.readOnly);
+  if (hits.length === 0 && found.length) {
+    return {
+      code: 1,
+      out: {
+        error: `${name} is ${XCODE_NOTE.replace(/^pinned/, "only pinned")}`,
+        manifests: found.map((h) => h.manifest),
+      },
+    };
+  }
+  if (hits.length === 0)
+    return { code: 1, out: { error: `${name} is not declared in any ${ecosystem} manifest` } };
+  if (hits.length > 1) {
+    return {
+      code: 1,
+      out: {
+        error: `${name} is declared in several manifests; pass --manifest`,
+        manifests: hits.map((h) => h.manifest),
+      },
+    };
+  }
+  const hit = hits[0];
+  const dep = hit.dep;
+  if (hit.lockError)
+    return {
+      code: 1,
+      out: { error: `${hit.lockError}; add it to the workspaces or bump it from there` },
+    };
+  const from = dep.current;
+  const { risk, prerelease } = classifyRisk(from, to, ecosystem);
+  const base = { ecosystem, name: dep.name, manifest: hit.manifest, from, to, risk, prerelease };
+  if (risk === "none" || risk === "downgrade")
+    return { code: 1, out: { ...base, error: `${to} is not newer than ${from}` } };
+  if ((risk === "major" || risk === "unknown" || prerelease) && !allowMajor) {
+    const what = prerelease ? `prerelease ${risk}` : risk;
+    return {
+      code: 3,
+      out: { ...base, error: `${what} bump needs --allow-major (or explicit confirmation)` },
+    };
+  }
+
+  const dirty = dirtyTracked(dir);
+  if (dirty.length) {
+    return {
+      code: 1,
+      out: {
+        ...base,
+        error: "the worktree has uncommitted changes to tracked files; commit or stash them first",
+        dirty,
+      },
+    };
+  }
+
+  if (ecosystem === "pip") {
+    const excluded = pipExclusion(dep, to);
+    if (excluded)
+      return {
+        code: 1,
+        out: {
+          ...base,
+          error: `${excluded} in ${hit.manifest} excludes ${to}; dep-bump does not rewrite other bounds, so this bump needs a decision on that bound first`,
+        },
+      };
+  }
+
+  const manifestPath = join(dir, hit.manifest);
+  const before = readFileSync(manifestPath, "utf8");
+  const after = EDITORS[ecosystem](before, dep, to);
+  if (!after)
+    return {
+      code: 1,
+      out: { ...base, error: `could not locate the version text for ${name} in ${hit.manifest}` },
+    };
+
+  const alsoMoves =
+    ecosystem === "gradle" && dep.versionRef
+      ? readVersionCatalog(before)
+          .filter((d) => d.versionRef === dep.versionRef && d.name !== dep.name)
+          .map((d) => d.name)
+      : [];
+
+  const head = git(dir, ["rev-parse", "HEAD"]);
+  const record = {
+    ...base,
+    baseSha: head.ok ? head.stdout.trim() : null,
+    untrackedAtStart: untracked(dir),
+    lockfile: hit.lockfile,
+    surface: [],
+    appliedAt: new Date().toISOString(),
+  };
+
+  const lockBefore = hit.lockfile ? readFileSync(join(dir, hit.lockfile)) : null;
+  writeFileSync(manifestPath, after);
+  let lockResult = { file: hit.lockfile, status: hit.lockfile ? "skipped" : "absent" };
+  if (hit.lockfile && lock) {
+    const c = lockCommand(dir, ecosystem, hit.manifest, hit.lockfile, dep.name);
+    if (!c) {
+      lockResult = {
+        file: hit.lockfile,
+        status: "failed",
+        output: "no lockfile tool for this package manager",
+      };
+    } else {
+      const r = sh(c.cmd, c.args, { cwd: c.cwd, timeout: TOOL_TIMEOUT_MS });
+      lockResult = {
+        file: hit.lockfile,
+        command: [c.cmd, ...c.args].join(" "),
+        status: r.ok ? "updated" : "failed",
+        output: r.output.slice(-OUTPUT_TAIL),
+      };
+    }
+    if (lockResult.status === "failed") {
+      writeFileSync(manifestPath, before);
+      writeFileSync(join(dir, hit.lockfile), lockBefore);
+      return {
+        code: 1,
+        out: {
+          ...base,
+          lock: lockResult,
+          error: "lockfile update failed; manifest and lockfile restored",
+        },
+      };
+    }
+  }
+
+  record.surface = surface(dir, ecosystem, dep.name, alsoMoves).files;
+  writeRecord(dir, { ...record, alsoMoves, lock: lockResult });
+
+  return {
+    code: 0,
+    out: {
+      ...base,
+      edits: [{ file: hit.manifest, before: dep.declared, after: to }],
+      alsoMoves,
+      lock: lockResult,
+      record: RECORD,
+      commitMessage: `chore(deps): bump ${dep.name} from ${from} to ${to}`,
+    },
+  };
+}
+
+// ─── surface, scope, rollback ──────────────────────────────────────────────
+
+function sourceFiles(dir) {
+  const r = git(dir, ["ls-files", "--cached", "--others", "--exclude-standard"]);
+  if (r.ok) return r.stdout.split("\n").filter((f) => f && !f.startsWith(".pipeline/"));
+  const out = [];
+  walk(dir, (rel) => out.push(rel));
+  return out;
+}
+
+/**
+ * Module names a SwiftPM package can be imported under: its identity, the
+ * repository name as written in the url, the products other targets name with
+ * `.product(name:package:)`, and by-name target dependencies that match the
+ * identity. Identities compare case-insensitively, module names do not.
+ */
+function swiftModules(dir, name) {
+  const identity = name.toLowerCase();
+  const modules = new Set([name, identity]);
+  for (const m of detect(dir).filter((x) => x.ecosystem === "swiftpm")) {
+    const raw = readFileSync(join(dir, m.manifest), "utf8");
+    if (m.readOnly) {
+      for (const p of readResolvedPins(raw))
+        if (p.name === identity) modules.add(basename(p.url).replace(/\.git$/, ""));
+      continue;
+    }
+    for (const d of readPackageSwift(raw))
+      if (d.name === identity)
+        modules.add(basename(d.url.replace(/\/+$/, "")).replace(/\.git$/, ""));
+    const code = blankSwiftComments(raw);
+    for (const p of swiftProducts(code, identity)) modules.add(p);
+    for (const q of code.matchAll(/"([A-Za-z_]\w*)"/g))
+      if (q[1].toLowerCase() === identity) modules.add(q[1]);
+  }
+  return modules;
+}
+
+function surfaceMatchers(dir, ecosystem, name, alsoMoves) {
+  if (ecosystem === "npm") {
+    const n = esc(name);
+    return [
+      {
+        ext: /\.(c|m)?(j|t)sx?$|\.(vue|svelte)$/,
+        re: new RegExp(
+          `(from\\s*|require\\(\\s*|import\\(\\s*|import\\s+)["'\`]${n}(/[^"'\`]*)?["'\`]`,
+        ),
+      },
+    ];
+  }
+  if (ecosystem === "swiftpm") {
+    const alt = [...swiftModules(dir, name)].map(esc).join("|");
+    return [
+      {
+        ext: /\.swift$/,
+        re: new RegExp(`^\\s*(@testable\\s+)?import\\s+(\\w+\\s+)?(${alt})\\b`, "m"),
+      },
+    ];
+  }
+  if (ecosystem === "gradle") {
+    const names = [name, ...alsoMoves];
+    const aliases = [];
+    const stems = new Set();
+    const stemOf = (s) => /^[A-Za-z_]\w*/.exec(s)?.[0];
+    for (const m of detect(dir).filter((x) => x.ecosystem === "gradle")) {
+      for (const d of readVersionCatalog(readFileSync(join(dir, m.manifest), "utf8"))) {
+        if (!names.includes(d.name)) continue;
+        aliases.push(d.alias.replace(/[-_]/g, "."));
+        stems.add(stemOf(d.alias));
+      }
+    }
+    for (const n of names.filter((x) => x.includes(":"))) stems.add(stemOf(n.split(":")[1]));
+    stems.delete(undefined);
+    // A JVM package root is often the group (com.google.code.gson), but just as
+    // often the artifact or alias stem with a major suffix (okhttp3, retrofit2).
+    const groups = [
+      ...names.filter((n) => n.includes(":")).map((n) => esc(n.split(":")[0])),
+      ...[...stems].map((st) => `${esc(st)}\\d*`),
+    ];
+    const out = [];
+    if (aliases.length) {
+      out.push({
+        ext: /\.gradle(\.kts)?$/,
+        re: new RegExp(`libs\\.(plugins\\.)?(${aliases.map(esc).join("|")})\\b`),
+      });
+    }
+    if (groups.length)
+      out.push({
+        ext: /\.(kt|kts|java)$/,
+        re: new RegExp(`^\\s*import\\s+(${groups.join("|")})\\.`, "m"),
+      });
+    return out;
+  }
+  const mod = esc(name.replace(/-/g, "_"));
+  return [{ ext: /\.py$/, re: new RegExp(`^\\s*(import|from)\\s+${mod}\\b`, "mi") }];
+}
+
+export function surface(dir, ecosystem, name, alsoMoves = []) {
+  const matchers = surfaceMatchers(dir, ecosystem, name, alsoMoves);
+  const files = [];
+  for (const rel of sourceFiles(dir)) {
+    const ms = matchers.filter((m) => m.ext.test(rel));
+    if (!ms.length) continue;
+    let text;
+    try {
+      text = readFileSync(join(dir, rel), "utf8");
+    } catch {
+      continue;
+    }
+    if (ms.some((m) => m.re.test(text))) files.push(rel);
+  }
+  return { ecosystem, name, files: files.sort() };
+}
+
+function readRecord(dir) {
+  const p = join(dir, RECORD);
+  if (!existsSync(p)) throw new UsageError(`no bump recorded in ${RECORD}; run apply first`);
+  return JSON.parse(readFileSync(p, "utf8"));
+}
+
+const ERROR_LINE = /\b(error|errors|fail|failed|failure|failing|exception)\b/i;
+
+/** The first build or test error line in `logText` that names `file`. */
+function citation(logText, file) {
+  return (
+    logText
+      .split("\n")
+      .find((l) => l.includes(file) && ERROR_LINE.test(l))
+      ?.trim() ?? null
+  );
+}
+
+/**
+ * Splits the files changed since apply. Only the surface recorded at apply time
+ * is in scope, with the manifest and lockfile: a file that imports the
+ * dependency only after the bump is a new importer, which passes only when the
+ * build or test log (--log) has an error line naming it.
+ */
+export function scope(dir, { log } = {}) {
+  const rec = readRecord(dir);
+  if (!rec.baseSha)
+    throw new UsageError("the recorded bump has no base commit; scope needs a git checkout");
+  const logText = log ? readFileSync(log, "utf8") : "";
+  const changed = changedSince(dir, rec);
+  const allowed = new Set([rec.manifest, rec.lockfile, ...rec.surface].filter(Boolean));
+  if (rec.ecosystem === "swiftpm")
+    allowed.add(join(dirname(rec.manifest), "Package.resolved").replace(/^\.\//, ""));
+  const importers = new Set(surface(dir, rec.ecosystem, rec.name, rec.alsoMoves ?? []).files);
+  const inScope = changed.filter((f) => allowed.has(f));
+  const rest = changed.filter((f) => !allowed.has(f));
+  const newImporters = rest
+    .filter((f) => importers.has(f))
+    .map((file) => ({ file, cited: citation(logText, file) }));
+  const outOfScope = rest.filter((f) => !importers.has(f));
+  const uncited = newImporters.some((n) => !n.cited);
+  const touched = new Set([...(rec.touched ?? []), ...inScope, ...newImporters.map((n) => n.file)]);
+  writeRecord(dir, { ...rec, touched: [...touched].sort() });
+  return {
+    code: outOfScope.length || uncited ? 1 : 0,
+    out: { name: rec.name, from: rec.from, to: rec.to, inScope, newImporters, outOfScope },
+  };
+}
+
+function changedSince(dir, rec) {
+  const diff = git(dir, ["diff", "--name-only", rec.baseSha]);
+  return [
+    ...new Set([...(diff.ok ? diff.stdout.split("\n") : []), ...untracked(dir)].filter(Boolean)),
+  ].filter((f) => !f.startsWith(".pipeline/") && !rec.untrackedAtStart.includes(f));
+}
+
+/**
+ * Puts back only what the bump owns: the manifest, the lockfile and the files
+ * scope saw the fix rounds touch inside the bump's reach. A file the base
+ * commit has is checked out from it, one it lacks is removed; every other
+ * change in the worktree is left in place and listed under `kept`.
+ */
+export function rollback(dir) {
+  const rec = readRecord(dir);
+  if (!rec.baseSha)
+    throw new UsageError("the recorded bump has no base commit; rollback needs a git checkout");
+  const owned = new Set([rec.manifest, rec.lockfile, ...(rec.touched ?? [])].filter(Boolean));
+  if (rec.ecosystem === "swiftpm")
+    owned.add(join(dirname(rec.manifest), "Package.resolved").replace(/^\.\//, ""));
+  const changed = changedSince(dir, rec);
+  const targets = changed.filter((f) => owned.has(f));
+  const atBase = new Set();
+  if (targets.length) {
+    const ls = git(dir, ["ls-tree", "-r", "--name-only", rec.baseSha, "--", ...targets]);
+    if (!ls.ok) return { code: 1, out: { error: `git ls-tree failed: ${ls.output.trim()}` } };
+    for (const f of ls.stdout.split("\n")) if (f) atBase.add(f);
+  }
+  const restored = targets.filter((f) => atBase.has(f));
+  if (restored.length) {
+    const r = git(dir, ["checkout", rec.baseSha, "--", ...restored]);
+    if (!r.ok) return { code: 1, out: { error: `git checkout failed: ${r.output.trim()}` } };
+  }
+  const removed = targets.filter((f) => !atBase.has(f));
+  for (const f of removed) rmSync(join(dir, f), { force: true });
+  const kept = changed.filter((f) => !owned.has(f)).sort();
+  writeRecord(dir, { ...rec, rolledBackAt: new Date().toISOString() });
+  return {
+    code: 0,
+    out: {
+      rolledBackTo: rec.baseSha,
+      restored: restored.sort(),
+      removed: removed.sort(),
+      kept,
+      name: rec.name,
+      from: rec.from,
+      to: rec.to,
+    },
+  };
+}
+
+// ─── release notes ─────────────────────────────────────────────────────────
+
+const CHANGELOG = /^(changelog|changes|history|releases|news)(\.md|\.markdown|\.txt)?$/i;
+
+function packageDir(dir, ecosystem, name) {
+  if (ecosystem === "npm") return join(dir, "node_modules", name);
+  if (ecosystem === "swiftpm") return join(dir, ".build", "checkouts", name);
+  return null;
+}
+
+export function changelogExcerpt(text, from, to) {
+  const out = [];
+  let keep = false;
+  for (const line of text.split("\n")) {
+    const h = /^#{1,3}\s*\[?v?(\d+\.\d+(?:\.\d+)?(?:-[\w.]+)?)\]?/.exec(line);
+    if (h) keep = compareVersions(h[1], from) > 0 && compareVersions(h[1], to) <= 0;
+    if (keep) out.push(line);
+  }
+  return out.join("\n").trim();
+}
+
+export function notes(dir, ecosystem, name, from, to) {
+  const pd = packageDir(dir, ecosystem, name);
+  const hint = {};
+  if (pd && existsSync(join(pd, "package.json"))) {
+    try {
+      const repo = JSON.parse(readFileSync(join(pd, "package.json"), "utf8")).repository;
+      hint.repository = typeof repo === "string" ? repo : repo?.url;
+    } catch {
+      hint.repository = undefined;
+    }
+  }
+  if (ecosystem === "swiftpm") {
+    const dep = resolveTarget(dir, ecosystem, name)[0]?.dep;
+    if (dep) hint.repository = dep.url;
+  }
+  if (pd && existsSync(pd)) {
+    const file = readdirSync(pd).find((f) => CHANGELOG.test(f));
+    if (file) {
+      const excerpt = changelogExcerpt(readFileSync(join(pd, file), "utf8"), from, to);
+      return { source: relative(dir, join(pd, file)), excerpt: excerpt || null, ...hint };
+    }
+  }
+  return {
+    source: null,
+    excerpt: null,
+    note: "no local changelog; read the release notes from the repository (gh release list / view) when reachable",
+    ...hint,
+  };
+}
+
+// ─── config ────────────────────────────────────────────────────────────────
+
+function readPrefs() {
+  const p =
+    process.env.MULTI_AGENT_PREFS ||
+    join(process.env.HOME || homedir(), ".claude", "multi-agent-preferences.json");
+  try {
+    return JSON.parse(readFileSync(p, "utf8"))?.global ?? {};
+  } catch {
+    return {};
+  }
+}
+
+const atPath = (obj, path) => path.split(".").reduce((o, k) => (o == null ? undefined : o[k]), obj);
+
+export function config(prefs = readPrefs()) {
+  const rounds = atPath(prefs, PREF_MAX_FIX_ROUNDS);
+  const registry = atPath(prefs, PREF_QUERY_REGISTRY);
+  return {
+    maxFixRounds:
+      Number.isInteger(rounds) && rounds >= 0 && rounds <= 5 ? rounds : DEFAULT_MAX_FIX_ROUNDS,
+    queryRegistry: typeof registry === "boolean" ? registry : true,
+  };
+}
+
+// ─── cli ───────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const [cmd, ...rest] = argv;
+  const opts = { cmd };
+  const flags = { "--registry": "registry", "--allow-major": "allowMajor", "--no-lock": "noLock" };
+  const values = {
+    "--dir": "dir",
+    "--ecosystem": "ecosystem",
+    "--name": "name",
+    "--to": "to",
+    "--from": "from",
+    "--manifest": "manifest",
+    "--log": "log",
+  };
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (flags[a]) opts[flags[a]] = true;
+    else if (values[a]) {
+      if (rest[i + 1] === undefined) throw new UsageError(`${a} needs a value`);
+      opts[values[a]] = rest[++i];
+    } else throw new UsageError(`unexpected argument ${a}`);
+  }
+  if (opts.ecosystem && !ECOSYSTEMS.includes(opts.ecosystem)) {
+    throw new UsageError(`--ecosystem must be one of ${ECOSYSTEMS.join(", ")}`);
+  }
+  return opts;
+}
+
+function need(opts, ...keys) {
+  for (const k of keys) if (!opts[k]) throw new UsageError(`${opts.cmd} needs --${k}`);
+}
+
+export function main(argv) {
+  if (["help", "--help", "-h"].includes(argv[0])) return { code: 0, text: USAGE };
+  const opts = parseArgs(argv);
+  const dir = opts.dir ?? process.cwd();
+  switch (opts.cmd) {
+    case "detect":
+      return { code: 0, out: { dir, ecosystems: detect(dir) } };
+    case "list":
+      return { code: 0, out: list(dir, opts) };
+    case "apply":
+      need(opts, "ecosystem", "name", "to");
+      return apply(dir, { ...opts, lock: !opts.noLock });
+    case "surface":
+      need(opts, "ecosystem", "name");
+      return { code: 0, out: surface(dir, opts.ecosystem, opts.name) };
+    case "scope":
+      return scope(dir, opts);
+    case "notes":
+      need(opts, "ecosystem", "name", "from", "to");
+      return { code: 0, out: notes(dir, opts.ecosystem, opts.name, opts.from, opts.to) };
+    case "rollback":
+      return rollback(dir);
+    case "config":
+      return { code: 0, out: config() };
+    default:
+      throw new UsageError(
+        "command must be detect, list, apply, surface, scope, notes, rollback, config or help",
+      );
+  }
+}
+
+if (invokedDirectly(import.meta.url)) {
+  let result;
+  try {
+    result = main(process.argv.slice(2));
+  } catch (err) {
+    const usage = err instanceof UsageError;
+    result = { code: usage ? 2 : 1, out: { error: `dep-bump: ${err.message}` } };
+  }
+  process.stdout.write(result.text ?? `${JSON.stringify(result.out, null, 2)}\n`);
+  process.exitCode = result.code;
+}