penthera 1.1.1 → 1.4.0

package/lib/deps/report.js

@@ -0,0 +1,173 @@
+/**
+ * Rendering for `penthera deps`: the terminal section, the Markdown section of
+ * the full report, and a short PR comment centred on the capability diff.
+ */
+import { CAPABILITIES, CAPABILITY_ORDER } from "./capabilities.js";
+
+const plain = (s) => s;
+const label = (id) => CAPABILITIES[id]?.label || id;
+const RISKY = new Set(["install-scripts", "shell", "network", "fs-write", "env-bulk", "eval", "obfuscated", "ai-config-write", "ai-cli-invoke", "token-harvest"]);
+
+function countsLine(counts) {
+  return CAPABILITY_ORDER.filter((id) => counts[id]).map((id) => `${label(id)} ${counts[id]}`).join(" · ");
+}
+
+/**
+ * Terminal lines for result.deps. `c` holds color helpers (bold, dim, red, yellow, green, cyan).
+ */
+export function formatDepsTerminal(deps, c = {}, opts = {}) {
+  const k = { bold: plain, dim: plain, red: plain, yellow: plain, green: plain, cyan: plain, ...c };
+  const L = [];
+  const missing = deps.notInstalled.length;
+  L.push(`  Packages   ${k.bold(String(deps.total))} in ${deps.lockfile} ${k.dim(`(v${deps.lockfileVersion}${deps.prod ? ", prod only" : ""}, ${deps.network})`)}`);
+  L.push(`  Scanned    ${deps.scanned}${missing ? k.yellow(` · ${missing} not installed or cached`) : ""}${deps.skippedOptional ? k.dim(` · ${deps.skippedOptional} optional for other platforms`) : ""}`);
+  const cl = countsLine(deps.capabilityCounts);
+  if (cl) L.push(`  Can do     ${k.dim(cl)}`);
+  if (deps.typosquats.length) L.push(`  Names      ${k.yellow(`${deps.typosquats.length} look like popular packages`)}`);
+
+  const d = deps.diff;
+  if (d) {
+    const gained = d.upgraded.filter((u) => u.gained?.length);
+    const notable = d.added.filter((a) => (a.capabilities || []).some((id) => RISKY.has(id)));
+    L.push(`  Diff       vs ${k.cyan(d.base)}: ${d.added.length} added · ${d.upgraded.length} changed · ${d.removed.length} removed`);
+    L.push("");
+    if (gained.length === 0 && notable.length === 0) {
+      L.push(`  ${k.green("✓")} No package gained capabilities, and no new package can reach shell, network or install-time code.`);
+    } else {
+      L.push(`  ${k.bold("Gained capabilities")}`);
+      L.push("");
+      for (const u of gained) {
+        L.push(`  ${k.yellow("▲")} ${k.bold(u.name)} ${u.from} → ${u.to}  ${k.red("+ " + u.gained.map(label).join(", "))}`);
+        for (const id of u.gained) {
+          for (const e of (d.evidence[`${u.name}@${u.to}`]?.[id] || []).slice(0, opts.verbose ? 5 : 1)) {
+            L.push(`      ${k.dim(`${e.file}:${e.line}`)}  ${e.snippet}`);
+          }
+        }
+      }
+      for (const a of notable) {
+        const ids = a.capabilities.filter((id) => RISKY.has(id));
+        L.push(`  ${k.yellow("+")} ${k.bold(a.name)} ${a.version} ${k.dim("(new)")}  ${ids.map(label).join(", ")}`);
+        for (const id of ids.slice(0, opts.verbose ? ids.length : 2)) {
+          const e = d.evidence[`${a.name}@${a.version}`]?.[id]?.[0];
+          if (e) L.push(`      ${k.dim(`${e.file}:${e.line}`)}  ${e.snippet}`);
+        }
+      }
+    }
+    const lost = d.upgraded.filter((u) => u.lost?.length);
+    if (lost.length && opts.verbose) {
+      L.push("");
+      for (const u of lost) L.push(`  ${k.green("▼")} ${u.name} ${u.from} → ${u.to}  ${k.dim("- " + u.lost.map(label).join(", "))}`);
+    }
+    const unavailable = d.upgraded.filter((u) => u.unavailable);
+    if (unavailable.length) {
+      L.push("");
+      L.push(`  ${k.dim(`Not compared (old version not available offline): ${unavailable.map((u) => `${u.name} ${u.from}`).join(", ")}`)}`);
+    }
+  }
+  return L;
+}
+
+const esc = (s) => String(s ?? "").replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\n/g, " ");
+const code = (s) => "`" + String(s).replace(/`/g, "ˋ") + "`";
+
+/** Capability diff as Markdown (used in the full report and the PR comment). */
+export function formatDiffMarkdown(deps) {
+  const d = deps.diff;
+  const L = [];
+  if (!d) return "";
+  const gained = d.upgraded.filter((u) => u.gained?.length);
+  const added = d.added.filter((a) => (a.capabilities || []).length);
+  L.push(`Compared against \`${esc(d.base)}\`: **${d.added.length}** added · **${d.upgraded.length}** changed · **${d.removed.length}** removed.`);
+  L.push("");
+  if (gained.length === 0 && !added.some((a) => a.capabilities.some((id) => RISKY.has(id)))) {
+    L.push("No package gained capabilities, and no new package can reach shell, network or install-time code.");
+    L.push("");
+  }
+  if (gained.length) {
+    L.push("### Upgrades that gained capabilities");
+    L.push("");
+    L.push("| Package | Version | Gained | Evidence |");
+    L.push("|---|---|---|---|");
+    for (const u of gained) {
+      const ev = u.gained.map((id) => d.evidence[`${u.name}@${u.to}`]?.[id]?.[0]).filter(Boolean)[0];
+      L.push(`| **${esc(u.name)}** | ${esc(u.from)} → ${esc(u.to)} | ${u.gained.map(label).join(", ")} | ${ev ? `${code(`${ev.file}:${ev.line}`)}` : ""} |`);
+    }
+    L.push("");
+  }
+  if (added.length) {
+    L.push("### New packages");
+    L.push("");
+    L.push("| Package | Version | Can do |");
+    L.push("|---|---|---|");
+    for (const a of added) L.push(`| ${esc(a.name)} | ${esc(a.version)} | ${a.capabilities.map((id) => (RISKY.has(id) ? `**${label(id)}**` : label(id))).join(", ")} |`);
+    L.push("");
+  }
+  const unavailable = d.upgraded.filter((u) => u.unavailable);
+  if (unavailable.length) {
+    L.push(`> Not compared, old version not available offline: ${unavailable.map((u) => `${esc(u.name)} ${esc(u.from)}`).join(", ")}. Install the base tree and pass it to \`--diff\`, or use \`--online\`.`);
+    L.push("");
+  }
+  const withEvidence = [...gained.map((u) => [`${u.name}@${u.to}`, u.gained]), ...added.map((a) => [`${a.name}@${a.version}`, a.capabilities.filter((id) => RISKY.has(id))])]
+    .filter(([, ids]) => ids.length);
+  if (withEvidence.length) {
+    L.push("<details><summary>Evidence (file:line)</summary>");
+    L.push("");
+    for (const [key, ids] of withEvidence) {
+      L.push(`**${esc(key)}**`);
+      L.push("");
+      for (const id of ids) {
+        for (const e of (d.evidence[key]?.[id] || []).slice(0, 3)) L.push(`- ${label(id)}: ${code(`${e.file}:${e.line}`)} ${code(e.snippet)}`);
+      }
+      L.push("");
+    }
+    L.push("</details>");
+    L.push("");
+  }
+  return L.join("\n");
+}
+
+/** Dependencies section of the full Markdown report. */
+export function formatDepsMarkdown(deps) {
+  const L = [];
+  L.push("## Dependencies");
+  L.push("");
+  L.push(`**${deps.total}** packages in \`${esc(deps.lockfile)}\` (lockfile v${deps.lockfileVersion}${deps.prod ? ", production only" : ""}), ${deps.scanned} scanned ${deps.network}.${deps.notInstalled.length ? ` ${deps.notInstalled.length} not installed or cached.` : ""}`);
+  L.push("");
+  const rows = CAPABILITY_ORDER.filter((id) => deps.capabilityCounts[id]);
+  if (rows.length) {
+    L.push("| Capability | Packages |");
+    L.push("|---|---|");
+    for (const id of rows) L.push(`| ${label(id)} | ${deps.capabilityCounts[id]} |`);
+    L.push("");
+  }
+  if (deps.diff) {
+    L.push("### Capability diff");
+    L.push("");
+    L.push(formatDiffMarkdown(deps));
+  }
+  L.push(`_Static analysis of package code, offline. A capability is what code can do, not proof it is malicious. Typosquat names checked against ${esc(deps.popularList)}._`);
+  L.push("");
+  return L.join("\n");
+}
+
+const MARKER = "<!-- penthera-deps -->";
+
+/** Short PR comment: the capability diff plus the risk findings. */
+export function formatPrComment(result, opts = {}) {
+  const deps = result.deps;
+  const L = [MARKER, "## Dependency capability diff", ""];
+  if (deps.diff) L.push(formatDiffMarkdown(deps));
+  else L.push(`No base to compare against; ${deps.total} packages scanned.\n`);
+  const risks = (result.findings || []).filter((f) => f.severity !== "info" && f.method !== "deps-capability-diff");
+  if (risks.length) {
+    L.push("### Risk signals");
+    L.push("");
+    const order = { critical: 0, high: 1, medium: 2, low: 3 };
+    for (const f of [...risks].sort((a, b) => (order[a.severity] ?? 4) - (order[b.severity] ?? 4))) {
+      L.push(`- **${f.severity}** ${esc(f.title)}${f.confidence === "potential" ? " _(potential)_" : ""}${f.url ? ` ${code(`${f.url}${f.line ? `:${f.line}` : ""}`)}` : ""}`);
+    }
+    L.push("");
+  }
+  L.push(`<sub>[penthera deps](https://github.com/danoszz/penthera)${opts.version ? ` v${opts.version}` : ""}: offline static analysis, no telemetry. Capabilities are what code can do, not a verdict.</sub>`);
+  return L.join("\n") + "\n";
+}

package/lib/deps/source.js

@@ -0,0 +1,171 @@
+/**
+ * Where a package's files come from, offline.
+ *
+ * The capability scanner reads files through a small source interface so the
+ * same code can scan an installed folder in node_modules or a tarball from
+ * npm's local content cache. The cache is what makes `--diff` work without a
+ * network: npm stores every tarball it has downloaded under its integrity hash,
+ * and a lockfile records that hash, so an old version can be read back exactly
+ * and verified byte for byte.
+ */
+import { readFileSync, readdirSync, lstatSync, existsSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { createHash } from "node:crypto";
+import { gunzipSync } from "node:zlib";
+import { homedir } from "node:os";
+
+const MAX_FILES = 5000;
+
+/** Files of an installed package folder. Skips nested node_modules and symlinks. */
+export class DirSource {
+  constructor(dir) {
+    this.dir = dir;
+    this.kind = "installed";
+  }
+
+  files() {
+    if (this._files) return this._files;
+    const out = [];
+    const walk = (d) => {
+      let entries;
+      try { entries = readdirSync(d, { withFileTypes: true }); } catch { return; }
+      entries.sort((a, b) => a.name.localeCompare(b.name));
+      for (const e of entries) {
+        if (out.length >= MAX_FILES) return;
+        const p = join(d, e.name);
+        if (e.isSymbolicLink()) continue;
+        if (e.isDirectory()) {
+          if (e.name === "node_modules" || e.name === ".git") continue;
+          walk(p);
+        } else if (e.isFile()) {
+          out.push(relative(this.dir, p).split(sep).join("/"));
+        }
+      }
+    };
+    walk(this.dir);
+    this._files = out;
+    return out;
+  }
+
+  size(rel) {
+    try { return lstatSync(join(this.dir, rel)).size; } catch { return 0; }
+  }
+
+  read(rel) {
+    return readFileSync(join(this.dir, rel));
+  }
+}
+
+/** Files of an unpacked tarball, held in memory. */
+export class MapSource {
+  constructor(map, kind = "npm-cache") {
+    this.map = map;
+    this.kind = kind;
+  }
+
+  files() {
+    return [...this.map.keys()].sort().slice(0, MAX_FILES);
+  }
+
+  size(rel) {
+    return this.map.get(rel)?.length || 0;
+  }
+
+  read(rel) {
+    return this.map.get(rel);
+  }
+}
+
+// ── Tarballs ──────────────────────────────────────────────────────────────
+
+function cstr(buf, start, len) {
+  const s = buf.subarray(start, start + len);
+  const z = s.indexOf(0);
+  return (z === -1 ? s : s.subarray(0, z)).toString("utf-8");
+}
+
+/**
+ * Minimal tar reader (ustar + pax/GNU long names). Returns Map<path, Buffer>
+ * with the leading "package/" directory stripped. Only regular files are kept;
+ * paths that try to climb out ("..") are dropped.
+ */
+export function untar(buf) {
+  const files = new Map();
+  let off = 0;
+  let longName = null;
+  while (off + 512 <= buf.length) {
+    const header = buf.subarray(off, off + 512);
+    if (header.every((b) => b === 0)) break;
+    let name = cstr(header, 0, 100);
+    const size = parseInt(cstr(header, 124, 12).trim() || "0", 8) || 0;
+    const type = String.fromCharCode(header[156] || 48);
+    const prefix = cstr(header, 345, 155);
+    if (prefix) name = `${prefix}/${name}`;
+    const body = buf.subarray(off + 512, off + 512 + size);
+    off += 512 + Math.ceil(size / 512) * 512;
+
+    if (type === "x") { // pax extended header
+      const m = body.toString("utf-8").match(/\d+ path=([^\n]*)\n/);
+      if (m) longName = m[1];
+      continue;
+    }
+    if (type === "L") { // GNU long name
+      longName = cstr(body, 0, body.length);
+      continue;
+    }
+    if (type === "g") continue;
+    if (longName) { name = longName; longName = null; }
+    if (type !== "0" && type !== "\0" && type !== "7") continue;
+    const parts = name.split("/").filter(Boolean);
+    parts.shift(); // top-level folder, usually "package"
+    if (parts.length === 0 || parts.includes("..")) continue;
+    files.set(parts.join("/"), Buffer.from(body));
+  }
+  return files;
+}
+
+/** Split an SRI string into { algo, hex } entries. */
+export function parseIntegrity(sri) {
+  return String(sri || "").split(/\s+/).filter(Boolean).map((s) => {
+    const i = s.indexOf("-");
+    if (i === -1) return null;
+    const algo = s.slice(0, i);
+    const b64 = s.slice(i + 1).replace(/\?.*$/, "");
+    return { algo, hex: Buffer.from(b64, "base64").toString("hex") };
+  }).filter((x) => x && /^sha(1|256|384|512)$/.test(x.algo) && x.hex);
+}
+
+/** True when the bytes match the SRI integrity string. */
+export function verifyIntegrity(bytes, sri) {
+  const entries = parseIntegrity(sri);
+  if (entries.length === 0) return false;
+  return entries.some(({ algo, hex }) => createHash(algo).update(bytes).digest("hex") === hex);
+}
+
+/** npm's cache directory: npm_config_cache, else ~/.npm. */
+export function npmCacheDir(env = process.env) {
+  return env.npm_config_cache || env.NPM_CONFIG_CACHE || join(homedir(), ".npm");
+}
+
+/**
+ * Read a package tarball from npm's content-addressed cache (cacache) by its
+ * lockfile integrity, verify it, and unpack it. Returns a MapSource or null.
+ */
+export function sourceFromNpmCache(integrity, cacheDir = npmCacheDir()) {
+  for (const { algo, hex } of parseIntegrity(integrity)) {
+    const p = join(cacheDir, "_cacache", "content-v2", algo, hex.slice(0, 2), hex.slice(2, 4), hex.slice(4));
+    if (!existsSync(p)) continue;
+    try {
+      const tgz = readFileSync(p);
+      if (!verifyIntegrity(tgz, integrity)) continue;
+      return new MapSource(untar(gunzipSync(tgz)), "npm-cache");
+    } catch { /* corrupt entry, try the next hash */ }
+  }
+  return null;
+}
+
+/** Unpack a verified tarball buffer (used by --online). */
+export function sourceFromTarball(tgz, integrity, kind = "registry") {
+  if (integrity && !verifyIntegrity(tgz, integrity)) return null;
+  return new MapSource(untar(gunzipSync(tgz)), kind);
+}

package/lib/deps/typosquat.js

@@ -0,0 +1,113 @@
+/**
+ * Typosquat and slopsquat checks for npm package names (`penthera deps`).
+ *
+ * Compares each dependency name against a vendored list of popular package
+ * names (lib/deps/popular-packages.json, refreshed at release time by
+ * scripts/refresh-popular-packages.mjs; never fetched at runtime). A name that
+ * is one or two edits away from a popular package, but is not itself popular,
+ * is worth a second look: that is how `crossenv` (for cross-env) and
+ * `electorn` (for electron) shipped malware.
+ *
+ * Slopsquatting is the same attack aimed at AI assistants: registering names
+ * a model is likely to hallucinate. Offline, the useful signal is the same
+ * near-miss check, plus (with --online) a very young publish date.
+ */
+import { readFileSync } from "node:fs";
+
+let _popular = null;
+
+/** The vendored popular-name list: { source, names: string[] }. */
+export function loadPopular() {
+  if (!_popular) {
+    const data = JSON.parse(readFileSync(new URL("./popular-packages.json", import.meta.url), "utf-8"));
+    _popular = { ...data, set: new Set(data.names), rank: new Map(data.names.map((n, i) => [n, i + 1])) };
+  }
+  return _popular;
+}
+
+/** Damerau-Levenshtein (optimal string alignment) distance, capped at max+1. */
+export function editDistance(a, b, max = 2) {
+  if (a === b) return 0;
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  const m = a.length;
+  const n = b.length;
+  let prev2 = null;
+  let prev = Array.from({ length: n + 1 }, (_, i) => i);
+  for (let i = 1; i <= m; i++) {
+    const cur = [i];
+    let rowMin = i;
+    for (let k = 1; k <= n; k++) {
+      const cost = a[i - 1] === b[k - 1] ? 0 : 1;
+      let v = Math.min(prev[k] + 1, cur[k - 1] + 1, prev[k - 1] + cost);
+      if (prev2 && i > 1 && k > 1 && a[i - 1] === b[k - 2] && a[i - 2] === b[k - 1]) v = Math.min(v, prev2[k - 2] + 1);
+      cur[k] = v;
+      if (v < rowMin) rowMin = v;
+    }
+    if (rowMin > max) return max + 1;
+    prev2 = prev;
+    prev = cur;
+  }
+  return prev[n];
+}
+
+const JS_SUFFIX = /(?:[.-]?js|-node)$/;
+
+/** Separator- and scope-insensitive form: "@types/lodash.merge" -> "typeslodashmerge". */
+const squash = (s) => s.replace(/^@/, "").replace(/[-_./]/g, "");
+
+/**
+ * Find the popular package a name is likely imitating, or null.
+ * @returns {null | { target, distance, kind, rank }}
+ */
+export function checkName(name, popular = loadPopular()) {
+  if (!name || popular.set.has(name)) return null;
+  const bare = name.replace(/^@[^/]+\//, "");
+  const isScoped = bare !== name;
+  // Short names collide with each other constantly; a 1-edit window over
+  // three-letter names would flag half the registry.
+  const max = bare.length >= 12 ? 2 : bare.length >= 5 ? 1 : 0;
+  const scope = isScoped ? name.slice(0, name.indexOf("/")) : null;
+
+  let best = null;
+  for (const target of popular.names) {
+    if (target === name) return null;
+    // Nobody can publish into a scope they don't own, so siblings in one scope
+    // (@img/sharp-linux-arm vs -arm64) are the same publisher, not a squat.
+    if (scope && target.startsWith(`${scope}/`)) continue;
+    let distance;
+    let kind;
+    const tSquash = squash(target);
+    if (squash(name) === tSquash) {
+      distance = 1;
+      kind = "separator or scope swap";
+    } else if (name.replace(JS_SUFFIX, "") === target) {
+      distance = 1;
+      kind = "popular name plus a js/node suffix";
+    } else if (max > 0 && !isScoped === !target.startsWith("@")) {
+      distance = editDistance(name, target, max);
+      if (distance > max) continue;
+      kind = distance === 1 ? "one edit away" : "two edits away";
+    } else {
+      continue;
+    }
+    const rank = popular.rank.get(target);
+    if (!best || distance < best.distance || (distance === best.distance && rank < best.rank)) {
+      best = { target, distance, kind, rank };
+    }
+  }
+  return best;
+}
+
+/**
+ * Check a list of package names. Returns hits sorted by name.
+ * @param {string[]} names
+ */
+export function findTyposquats(names) {
+  const popular = loadPopular();
+  const out = [];
+  for (const name of [...new Set(names)].sort()) {
+    const hit = checkName(name, popular);
+    if (hit) out.push({ name, ...hit });
+  }
+  return out;
+}

package/lib/fix/apply.js

@@ -0,0 +1,95 @@
+/**
+ * applyDiff: the one place fix recipes' diffs get written to disk.
+ *
+ * Planning never writes. Applying is a separate, explicit step that refuses to
+ * write outside the repo, into .git, or into a dirty git tree (unless the caller
+ * passes allowDirty), and writes nothing unless every hunk applies.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { execFileSync } from "node:child_process";
+import { parsePatch, applyHunks } from "./diff.js";
+
+export class FixError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "FixError";
+    this.code = code;
+  }
+}
+
+function inside(root, p) {
+  const rel = relative(root, p);
+  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+
+/** Resolve a diff path to an absolute path inside the repo, or throw. */
+function safeTarget(root, file) {
+  if (!file || isAbsolute(file) || file.includes("\0")) {
+    throw new FixError(`Refusing to write ${JSON.stringify(file)}: paths in a diff must be relative to the repo`, "OUTSIDE_REPO");
+  }
+  const target = resolve(root, file);
+  if (!inside(root, target)) throw new FixError(`Refusing to write ${file}: it is outside the repo`, "OUTSIDE_REPO");
+  if (relative(root, target).split(sep)[0] === ".git") throw new FixError(`Refusing to write ${file}: it is inside .git`, "OUTSIDE_REPO");
+  // Follow symlinks: the real location of the file (or its nearest existing
+  // parent, for a new file) must still be inside the repo.
+  let probe = target;
+  while (!existsSync(probe)) probe = dirname(probe);
+  if (!inside(root, realpathSync(probe))) throw new FixError(`Refusing to write ${file}: it resolves outside the repo`, "OUTSIDE_REPO");
+  return target;
+}
+
+/** Throws unless repoPath is in a git work tree with no uncommitted changes under it. */
+export function assertCleanTree(repoPath) {
+  let status;
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: repoPath, stdio: ["ignore", "pipe", "ignore"] });
+    status = execFileSync("git", ["status", "--porcelain", "--", "."], { cwd: repoPath, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+  } catch {
+    throw new FixError(`${repoPath} is not a git work tree, so a fix could not be reviewed or reverted. Commit it to git first, or pass --allow-dirty.`, "NOT_GIT");
+  }
+  if (status.trim()) {
+    throw new FixError(`${repoPath} has uncommitted changes. Commit or stash them first so the fix is its own reviewable change, or pass --allow-dirty.`, "DIRTY");
+  }
+}
+
+/**
+ * Apply a unified diff to files under repoPath.
+ *
+ * @param {string} repoPath
+ * @param {string} diff
+ * @param {{ dryRun?: boolean, allowDirty?: boolean }} [opts]
+ * @returns {{ applied: boolean, files: { path: string, created: boolean }[] }}
+ */
+export function applyDiff(repoPath, diff, opts = {}) {
+  const root = realpathSync(resolve(repoPath));
+  const parsed = parsePatch(diff);
+  if (parsed.length === 0) throw new FixError("The diff contains no file changes", "EMPTY");
+  if (!opts.allowDirty) assertCleanTree(root);
+
+  const writes = [];
+  for (const f of parsed) {
+    if (!f.newPath) throw new FixError(`Refusing to delete ${f.oldPath}: fix diffs never delete files`, "DELETE");
+    if (f.oldPath && f.oldPath !== f.newPath) throw new FixError(`Refusing to rename ${f.oldPath}: fix diffs never rename files`, "RENAME");
+    const target = safeTarget(root, f.newPath);
+    const exists = existsSync(target);
+    if (!f.oldPath && exists) throw new FixError(`${f.newPath} already exists; the plan expected to create it`, "CONFLICT");
+    if (f.oldPath && !exists) throw new FixError(`${f.newPath} does not exist; the plan expected to edit it`, "CONFLICT");
+    const before = exists ? readFileSync(target, "utf-8") : null;
+    let after;
+    try {
+      after = applyHunks(before, f.hunks);
+    } catch (e) {
+      throw new FixError(`${f.newPath}: ${e.message}`, "CONFLICT");
+    }
+    writes.push({ path: f.newPath, target, after, created: !exists });
+  }
+
+  if (!opts.dryRun) {
+    for (const w of writes) {
+      mkdirSync(dirname(w.target), { recursive: true });
+      writeFileSync(w.target, w.after);
+    }
+  }
+  return { applied: !opts.dryRun, files: writes.map((w) => ({ path: w.path, created: w.created })) };
+}