@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/git-diff.js

@@ -1,52 +1,28 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { basename, join } from 'node:path';
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
 import { GitError } from '../errors/git.js';
 import { toError } from '../utils/errors.js';
-import { pathExists, readText } from '../utils/fs.js';
+import { pathExists } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
-import { exec } from '../utils/process.js';
-import { chunkPathspecs, ensureGit, git } from './git-base.js';
-import { fileExistsInHead, hashObjectBatch, isBinaryFile, listTrackedInHead, } from './git-file-ops.js';
-import { mintDisposableGitIndex, readOnlyGitIndexEnv } from './git-readonly-index.js';
+import { chunkPathspecs, git } from './git-base.js';
+import { readNewFileContent, withForcedBinaryAttribute } from './git-diff-new-file.js';
+import { fileExistsInHead, hashObjectBatch, listTrackedInHead } from './git-file-ops.js';
+import { mintDisposableGitIndex } from './git-readonly-index.js';
 import { getUntrackedFiles, getUntrackedFilesInDir } from './git-status.js';
-async function execGitWithAllowedExitCodes(repoDir, args, allowedExitCodes = [0], envOverride) {
-    // Honour a read-only command's private-index scope: the `--intent-to-add`
-    // / `update-index` staging dance below is a genuine
-    // index write, and inside a read-only command it must land on the
-    // private index, not the primary checkout's.
-    //
-    // `envOverride` wins over that scope: a caller that minted an index for
-    // one specific invocation has said something more specific than the
-    // ambient scope did.
-    const readOnlyIndexEnv = readOnlyGitIndexEnv(repoDir);
-    const env = readOnlyIndexEnv !== undefined || envOverride !== undefined
-        ? { ...readOnlyIndexEnv, ...envOverride }
-        : undefined;
-    const result = await exec('git', args, {
-        cwd: repoDir,
-        ...(env !== undefined ? { env } : {}),
-    });
-    if (allowedExitCodes.includes(result.exitCode)) {
-        return result;
-    }
-    throw new GitError(result.stderr.trim() || 'Git command failed', args.join(' '));
-}
 /**
  * Gets the diff for a specific file.
  *
  * `--binary` is load-bearing: without it git degrades a binary file's section
  * to the informational `Binary files a/x and b/x differ`, which carries none
  * of the bytes and cannot be replayed by `git apply`. It only expands the
- * BINARY section's index line to full hashes (text sections keep their
+ * binary section's index line to full hashes (text sections keep their
  * abbreviated form), so text output stays byte-identical.
  * @param repoDir - Repository directory
  * @param filePath - Path to the file (relative to repo)
  * @returns Diff content
  */
 export async function getFileDiff(repoDir, filePath) {
-    await ensureGit();
     return git(['diff', '--binary', 'HEAD', '--', filePath], repoDir);
 }
 /**
@@ -66,7 +42,7 @@ function abbreviateBlobHash(fullHash) {
 /**
  * Pure formatter for a new (untracked) file's unified diff. Shared by the
  * batched cold-run path in {@link getDiffForFilesAgainstHead} and the
- * standalone {@link generateNewFileDiff} — the only thing that differs is
+ * standalone {@link generateNewFileDiff}. The only thing that differs is
  * where `blobHash` comes from (a single batched `git hash-object` vs a
  * per-file one), never the formatting. Preserves the empty-file form, the
  * trailing-newline handling, and the "No newline at end of file" marker
@@ -113,22 +89,36 @@ function buildNewFileDiffBody(filePath, content, blobHash) {
     return diffLines.join('\n') + '\n';
 }
 /**
- * Generates a unified diff for a new (untracked) file.
+ * Defensive check shared by the new-file readers: a directory here means a
+ * caller bypassed the expansion layers and handed the leaf reader a path it
+ * cannot read. Surfaces an actionable message naming the offending path
+ * rather than the raw `EISDIR` the read would throw. This is a recurring bug
+ * class, hence the guard at every leaf.
+ * @param repoDir - Repository directory
+ * @param filePath - Path to the file (relative to repo)
+ */
+async function rejectDirectory(repoDir, filePath) {
+    const fileStat = await stat(join(repoDir, filePath));
+    if (fileStat.isDirectory()) {
+        throw new GitError(`expected a file but found a directory at '${filePath}' — caller must expand directory entries before diffing`, `hash-object ${filePath}`);
+    }
+}
+/**
+ * Generates a unified diff for a new (untracked) file. A file that is binary
+ * or not valid UTF-8 (see {@link readNewFileContent}) is routed through
+ * {@link generateBinaryFilePatch} instead, because a text body cannot carry
+ * its bytes faithfully.
  * @param repoDir - Repository directory
  * @param filePath - Path to the file (relative to repo)
  * @returns Diff content in unified diff format
  */
 export async function generateNewFileDiff(repoDir, filePath) {
     const fullPath = join(repoDir, filePath);
-    // Defensive check: a directory here means a caller bypassed the expansion
-    // layers and handed the leaf reader a path it cannot read. Surface it with
-    // an actionable message naming the offending path rather than the raw
-    // `EISDIR` that `readText` would throw.
-    const fileStat = await stat(fullPath);
-    if (fileStat.isDirectory()) {
-        throw new GitError(`expected a file but found a directory at '${filePath}' — caller must expand directory entries before diffing`, `hash-object ${filePath}`);
+    await rejectDirectory(repoDir, filePath);
+    const file = await readNewFileContent(repoDir, filePath);
+    if (file.binary) {
+        return generateBinaryFilePatch(repoDir, filePath);
     }
-    const content = await readText(fullPath);
     // Compute the abbreviated git blob hash for the index line
     let blobHash = '0000000000';
     try {
@@ -138,7 +128,7 @@ export async function generateNewFileDiff(repoDir, filePath) {
     catch (error) {
         verbose(`git hash-object failed for ${filePath}; falling back to zero blob hash: ${toError(error).message}`);
     }
-    return buildNewFileDiffBody(filePath, content, blobHash);
+    return buildNewFileDiffBody(filePath, file.content, blobHash);
 }
 /**
  * Generates a patch for a file.
@@ -150,7 +140,6 @@ export async function generateNewFileDiff(repoDir, filePath) {
  * @returns Diff content in unified diff format
  */
 export async function generateFullFilePatch(repoDir, filePath) {
-    await ensureGit();
     // If file exists in HEAD, use standard git diff HEAD -- <file>
     // This generates a contextual diff that is safer for rebasing
     if (await fileExistsInHead(repoDir, filePath)) {
@@ -159,76 +148,26 @@ export async function generateFullFilePatch(repoDir, filePath) {
     // If file is new/untracked, use the full-file "new file" format
     return generateNewFileDiff(repoDir, filePath);
 }
-/**
- * Generates a unified diff between base content and current file content.
- * @param repoDir - Repository directory
- * @param filePath - Path to the file (relative to repo)
- * @param baseContent - The base content to diff against
- * @returns Unified diff in git format
- */
-export async function generateModificationDiff(repoDir, filePath, baseContent) {
-    const fullPath = join(repoDir, filePath);
-    const currentContent = await readText(fullPath);
-    // If contents are identical, return empty diff
-    if (baseContent === currentContent) {
-        return '';
-    }
-    const tempDir = await mkdtemp(join(tmpdir(), 'fireforge-diff-'));
-    const tempFile = join(tempDir, basename(filePath));
-    try {
-        await writeFile(tempFile, baseContent);
-        // git diff --no-index exits code 1 when files differ — that's normal
-        const result = await execGitWithAllowedExitCodes(repoDir, ['diff', '--no-index', '--', tempFile, fullPath], [0, 1]);
-        const output = result.stdout;
-        if (!output) {
-            return '';
-        }
-        // Post-process: fix paths in the diff header only (before the first @@ hunk)
-        const lines = output.split('\n');
-        let pastHeader = false;
-        const fixedLines = lines.map((line) => {
-            if (!pastHeader && line.startsWith('@@')) {
-                pastHeader = true;
-            }
-            if (!pastHeader) {
-                if (line.startsWith('diff --git')) {
-                    return `diff --git a/${filePath} b/${filePath}`;
-                }
-                if (line.startsWith('--- ')) {
-                    return `--- a/${filePath}`;
-                }
-                if (line.startsWith('+++ ')) {
-                    return `+++ b/${filePath}`;
-                }
-            }
-            return line;
-        });
-        return fixedLines.join('\n');
-    }
-    finally {
-        await rm(tempDir, { recursive: true, force: true });
-    }
-}
 /**
  * Gets the diff for all modified files, including untracked (new) files.
  *
- * Tracked binary files round-trip through `git diff --binary`; untracked ones
+ * Tracked binary files round-trip through `git diff --binary`. Untracked ones
  * go through {@link generateBinaryFilePatch} below. Both arms must stay
- * binary-aware — see {@link getFileDiff} for why.
+ * binary-aware. See {@link getFileDiff} for why.
  * @param repoDir - Repository directory
  * @returns Diff content
  */
 export async function getAllDiff(repoDir) {
-    await ensureGit();
     // Get diff for tracked files
     const trackedDiff = await git(['diff', '--binary', 'HEAD'], repoDir);
     // Get untracked files (properly expanded, not directories)
     const untrackedFiles = await getUntrackedFiles(repoDir);
-    // Classify first. `isBinaryFile` reads the file's first 8 KB directly and
-    // spawns nothing, so the only per-file process in this loop is the
-    // `git hash-object` inside `generateNewFileDiff` — one spawn per untracked
-    // TEXT file, uncapped, against a Firefox tree where "untracked" can mean a
-    // very large number. Hence classify → one batched hash → render.
+    // Classify first. `readNewFileContent` reads the file directly and spawns
+    // nothing, so the only per-file process in this loop would be the
+    // `git hash-object` inside `generateNewFileDiff`: one spawn per untracked
+    // text file, uncapped, against a Firefox tree where "untracked" can mean a
+    // very large number. Hence classify → one batched hash → render. The
+    // classification carries each text file's content so it is read once.
     //
     // Everything else here is deliberately untouched: `git diff HEAD` (with
     // renames, unlike the `--no-renames` scoped sibling), the `ls-files`
@@ -236,42 +175,35 @@ export async function getAllDiff(repoDir) {
     // sentinel are all observable. `getAllDiff`'s output is SHA-256'd into
     // every tree fingerprint (tree-store.ts) and written verbatim into `.patch`
     // files (export-all.ts), so its bytes are a contract.
-    const binaryFiles = [];
-    const textFiles = [];
+    const classified = new Map();
     for (const file of untrackedFiles) {
-        if (await isBinaryFile(repoDir, file)) {
-            binaryFiles.push(file);
-        }
-        else {
-            textFiles.push(file);
-        }
+        await rejectDirectory(repoDir, file);
+        classified.set(file, await readNewFileContent(repoDir, file));
     }
-    const textHashes = await hashObjectBatch(repoDir, textFiles.map((file) => join(repoDir, file)));
-    // Binary patches stage into the index and must stay serial; text patches
+    const textHashes = await hashObjectBatch(repoDir, untrackedFiles
+        .filter((file) => classified.get(file)?.binary === false)
+        .map((file) => join(repoDir, file)));
+    // Binary patches stage into the index and must stay serial. Text patches
     // are pure formatting over the already-batched hashes.
     const binaryDiffs = new Map();
-    for (const file of binaryFiles) {
-        binaryDiffs.set(file, await generateBinaryFilePatch(repoDir, file));
+    for (const file of untrackedFiles) {
+        if (classified.get(file)?.binary === true) {
+            binaryDiffs.set(file, await generateBinaryFilePatch(repoDir, file));
+        }
     }
     const untrackedDiffs = [];
     for (const file of untrackedFiles) {
-        const binary = binaryDiffs.get(file);
-        if (binary !== undefined) {
-            untrackedDiffs.push(binary);
+        const entry = classified.get(file);
+        if (entry === undefined || entry.binary) {
+            const binary = binaryDiffs.get(file);
+            if (binary !== undefined)
+                untrackedDiffs.push(binary);
             continue;
         }
         const fullPath = join(repoDir, file);
-        // Same defensive directory check `generateNewFileDiff` carries: a
-        // directory here means a caller bypassed the expansion layers, and its
-        // comment records this as a recurring bug class.
-        const fileStat = await stat(fullPath);
-        if (fileStat.isDirectory()) {
-            throw new GitError(`expected a file but found a directory at '${file}' — caller must expand directory entries before diffing`, `hash-object ${file}`);
-        }
-        const content = await readText(fullPath);
-        untrackedDiffs.push(buildNewFileDiffBody(file, content, abbreviateBlobHash(textHashes.get(fullPath))));
+        untrackedDiffs.push(buildNewFileDiffBody(file, entry.content, abbreviateBlobHash(textHashes.get(fullPath))));
     }
-    // Combine all diffs — each already ends with \n, so concatenate directly
+    // Combine all diffs. Each already ends with \n, so concatenate directly
     // to avoid inserting blank lines between diff sections.
     const allDiffs = [trackedDiff, ...untrackedDiffs].filter((d) => d.trim().length > 0);
     const combined = allDiffs.join('');
@@ -283,8 +215,8 @@ export async function getAllDiff(repoDir) {
  * to (but not including) the next such line. Boundary detection is anchored to
  * column 0 because every diff *body* line is prefixed by a space, `+`, `-`,
  * `\`, or `@`, so a context or added line that merely contains the text
- * `diff --git` can never be mistaken for a header. Paths are deliberately NOT
- * parsed out of the header here — see {@link buildTrackedSections}.
+ * `diff --git` can never be mistaken for a header. Paths are not parsed out
+ * of the header here on purpose. See {@link buildTrackedSections}.
  * @param combined - Combined `git diff` stdout
  * @returns File sections in git's emission order
  */
@@ -311,18 +243,18 @@ function splitDiffSections(combined) {
  *
  * `--binary` is load-bearing: a tracked binary file would otherwise degrade to
  * the un-appliable `Binary files a/x and b/x differ` stub. It expands only the
- * binary section's index line to full hashes, so text sections are unaffected
- * — see {@link getFileDiff}.
+ * binary section's index line to full hashes, so text sections are
+ * unaffected. See {@link getFileDiff}.
  *
  * `--no-renames` is load-bearing: a multi-path diff under a user's
  * `diff.renames=true`/`=copies` could otherwise emit a single 2-path rename
  * section (`a/<old> b/<new>`) that a single-path `git diff HEAD -- <file>` can
- * never produce; `--no-renames` re-splits it into the same delete + add bytes
+ * never produce. `--no-renames` re-splits it into the same delete + add bytes
  * the per-file loop emitted.
  *
- * Sections are attributed to paths by POSITION against a companion
+ * Sections are attributed to paths by position against a companion
  * `git diff --no-renames HEAD -z --name-only` (raw, unquoted, NUL-delimited
- * paths, emitted in the same order as the sections) — never by parsing the
+ * paths, emitted in the same order as the sections), never by parsing the
  * `diff --git` header, which is ambiguous or unparseable under `core.quotePath`
  * (non-ASCII paths are C-quoted), paths containing spaces, or
  * `diff.noprefix`/`diff.mnemonicPrefix`. If the section and name counts ever
@@ -341,14 +273,14 @@ async function buildTrackedSections(repoDir, trackedFiles) {
         const sections = splitDiffSections(combined);
         if (sections.length === names.length) {
             for (let i = 0; i < names.length; i++) {
-                // Exact-path keys (raw git bytes, same encoding as the inputs) — never
+                // Exact-path keys (raw git bytes, same encoding as the inputs), never
                 // a substring/startsWith match, so `foo.txt` cannot capture
                 // `foo.txt.bak`'s section.
                 sectionsByPath.set(names[i], sections[i]);
             }
             continue;
         }
-        // Counts disagree — recover the exact pre-batch per-file bytes for this
+        // Counts disagree, so recover the exact pre-batch per-file bytes for this
         // chunk rather than risk dropping or mis-keying a section.
         for (const file of chunk) {
             const diff = await getFileDiff(repoDir, file);
@@ -361,7 +293,7 @@ async function buildTrackedSections(repoDir, trackedFiles) {
 /**
  * Builds a combined diff against HEAD for the provided files without touching
  * the real git index. Tracked files use `git diff --binary HEAD` (binary
- * sections included); untracked files use synthesized new-file diffs, or
+ * sections included). Untracked files use synthesized new-file diffs, or
  * {@link generateBinaryFilePatch} when the file is binary.
  *
  * Performance: the work is batched into a handful of `git` invocations (one
@@ -376,14 +308,13 @@ async function buildTrackedSections(repoDir, trackedFiles) {
  * @returns Combined diff content
  */
 export async function getDiffForFilesAgainstHead(repoDir, files) {
-    await ensureGit();
     // Expand any directory entries (paths ending with `/`) into their
     // individual untracked files before diffing. `git status --porcelain=v1`
     // reports collapsed untracked directories as `?? dir/`, and every caller
     // that feeds the aggregate working-tree state into this function must not
     // trigger an EISDIR when the diff pass reads `dir/` as if it were a file.
     // The caller-side expansion in `lint.ts` and `export-all.ts` covers the
-    // common path; guarding here makes a single bad call site harmless.
+    // common path. Guarding here makes a single bad call site harmless.
     const expandedFiles = [];
     for (const file of files) {
         if (file.endsWith('/')) {
@@ -405,7 +336,7 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
     const trackedSections = await buildTrackedSections(repoDir, uniqueFiles.filter((file) => tracked.has(file)));
     // Classify the non-tracked files. Directory and binary entries keep their
     // per-file handling (rare, and binary patches mutate the index so they must
-    // stay serial); plain new text files are collected for a single batched
+    // stay serial). Plain new text files are collected for a single batched
     // `git hash-object`. Results land in `sectionByFile`, keyed by path, to be
     // emitted in sorted order below.
     const sectionByFile = new Map();
@@ -422,7 +353,7 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
         // the trailing slash `expandUntrackedDirectoryEntries` would have
         // produced (caller stripped it, submodule entry, tracked-file-replaced-
         // by-dir). Expand it via the same helper used by the slash branch and
-        // recurse so each contained file is diffed individually; fail loud when
+        // recurse so each contained file is diffed individually. Fail loud when
         // the directory has no readable content rather than silently skipping it.
         const fileStat = await stat(fullPath);
         if (fileStat.isDirectory()) {
@@ -435,29 +366,31 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
                 sectionByFile.set(file, innerDiff);
             continue;
         }
-        if (await isBinaryFile(repoDir, file)) {
+        // Binary (by git's NUL heuristic or because the bytes are not valid
+        // UTF-8) takes the byte-faithful binary-patch arm.
+        const newFile = await readNewFileContent(repoDir, file);
+        if (newFile.binary) {
             const diff = await generateBinaryFilePatch(repoDir, file);
             if (diff.trim())
                 sectionByFile.set(file, diff);
             continue;
         }
-        newTextFiles.push(file);
+        newTextFiles.push({ file, content: newFile.content });
     }
     // Batch 3: blob hashes for every new text file in one `git hash-object`.
     // A miss (rare: a path became unreadable after the stat above) falls back to
     // the zero hash with the same verbose log the per-file path emitted.
-    const blobHashes = await hashObjectBatch(repoDir, newTextFiles.map((file) => join(repoDir, file)));
-    for (const file of newTextFiles) {
-        const fullPath = join(repoDir, file);
-        const fullHash = blobHashes.get(fullPath);
+    const blobHashes = await hashObjectBatch(repoDir, newTextFiles.map(({ file }) => join(repoDir, file)));
+    for (const { file, content } of newTextFiles) {
+        const fullHash = blobHashes.get(join(repoDir, file));
         if (fullHash === undefined) {
             verbose(`git hash-object failed for ${file}; falling back to zero blob hash`);
         }
-        const body = buildNewFileDiffBody(file, await readText(fullPath), abbreviateBlobHash(fullHash));
+        const body = buildNewFileDiffBody(file, content, abbreviateBlobHash(fullHash));
         if (body.trim())
             sectionByFile.set(file, body);
     }
-    // Reassemble in the sorted `uniqueFiles` order — NOT git's section order,
+    // Reassemble in the sorted `uniqueFiles` order, not git's section order,
     // which uses git's own collation and diverges from JS `.sort()` for
     // non-ASCII paths. Driving emission off `uniqueFiles` (as the previous
     // per-file loop did) keeps the combined output byte-identical. Do not change
@@ -484,13 +417,12 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
  * @returns Diff content for the staged files
  */
 export async function getStagedDiffForFiles(repoDir, files) {
-    await ensureGit();
     return git(['diff', '--binary', '--cached', 'HEAD', '--', ...files], repoDir);
 }
 /**
  * Serializes the index-mutating untracked-binary path. The bounded per-patch
  * lint pool can call {@link getDiffForFilesAgainstHead} (and thus this) for
- * several patches at once; two concurrent `git add --intent-to-add` / `git
+ * several patches at once. Two concurrent `git add --intent-to-add` / `git
  * reset` sequences would collide on `.git/index.lock` (a hard failure) or
  * interleave one file's stage with another's unstage. This process-level
  * promise chain runs the staging sequences one at a time. Read-only callers
@@ -507,28 +439,37 @@ function runWithBinaryStagingLock(task) {
  * Generates a GIT binary patch for a binary file.
  * For tracked files, uses `git diff --binary HEAD`.
  * For untracked files, temporarily stages with `--intent-to-add` to produce a diff.
+ *
+ * Every `git diff` here runs under {@link withForcedBinaryAttribute}: a
+ * caller sends a file down this arm because a text body cannot carry its
+ * bytes (NUL, or not valid UTF-8), and git's own NUL-only heuristic would
+ * otherwise still render the non-UTF-8 case as text.
  * @param repoDir - Repository directory
  * @param filePath - File path (relative to repo root)
  * @returns The binary diff string, or empty string if no diff
  */
 export async function generateBinaryFilePatch(repoDir, filePath) {
-    await ensureGit();
-    // Try tracked file diff first (read-only — no index lock needed)
-    const result = await execGitWithAllowedExitCodes(repoDir, [
-        'diff',
-        '--binary',
-        'HEAD',
-        '--',
-        filePath,
-    ]);
-    if (result.stdout.trim())
-        return result.stdout;
+    return withForcedBinaryAttribute(filePath, (gitConfigArgs) => generateBinaryFilePatchWithConfig(repoDir, filePath, gitConfigArgs));
+}
+/**
+ * The body of {@link generateBinaryFilePatch}, with the forced-binary config
+ * arguments already resolved.
+ * @param repoDir - Repository directory
+ * @param filePath - File path (relative to repo root)
+ * @param gitConfigArgs - `-c` arguments spliced ahead of every `diff`
+ * @returns The binary diff string, or empty string if no diff
+ */
+async function generateBinaryFilePatchWithConfig(repoDir, filePath, gitConfigArgs) {
+    // Try tracked file diff first (read-only, so no index lock needed)
+    const tracked = await git([...gitConfigArgs, 'diff', '--binary', 'HEAD', '--', filePath], repoDir);
+    if (tracked.trim())
+        return tracked;
     // The diff for an untracked file has to come from an index entry, so one
-    // has to be written. Writing it to a PRIVATE index is what keeps that
+    // has to be written. Writing it to a private index is what keeps that
     // write invisible: the primary `.git/index` never moves, so a concurrent
     // `fireforge test` fingerprinting `engine/` with `git status` cannot
     // observe the transient `--intent-to-add` entry and void its own verdict
-    // on our bookkeeping. That was a real failure mode — parallel gate lanes
+    // on our bookkeeping. That was a real failure mode: parallel gate lanes
     // killed three runs with `FAIL reason=inconclusive` on branding PNGs
     // flapping between `A` and `??`.
     //
@@ -539,9 +480,10 @@ export async function generateBinaryFilePatch(repoDir, filePath) {
     const disposable = await mintDisposableGitIndex(repoDir);
     if (disposable !== undefined) {
         try {
-            await execGitWithAllowedExitCodes(repoDir, ['add', '--intent-to-add', '--', filePath], [0], disposable.env);
-            const diffResult = await execGitWithAllowedExitCodes(repoDir, ['diff', '--binary', '--', filePath], [0], disposable.env);
-            return diffResult.stdout;
+            await git(['add', '--intent-to-add', '--', filePath], repoDir, { env: disposable.env });
+            return await git([...gitConfigArgs, 'diff', '--binary', '--', filePath], repoDir, {
+                env: disposable.env,
+            });
         }
         finally {
             await disposable.dispose();
@@ -556,22 +498,16 @@ export async function generateBinaryFilePatch(repoDir, filePath) {
     verbose(`Binary patch for ${filePath} is staging on the shared index (no private index).`);
     return runWithBinaryStagingLock(async () => {
         // Snapshot the path's exact index entry before touching it. A blanket
-        // `git reset HEAD -- <file>` cleanup restores the path to its HEAD state
-        // — for a path absent from HEAD that means *removing* whatever entry the
+        // `git reset HEAD -- <file>` cleanup restores the path to its HEAD state.
+        // For a path absent from HEAD that means *removing* whatever entry the
         // index carried, silently discarding any staged state that arrived
         // between the read-only diff above and this staging block (a concurrent
         // writer, or a staged-add whose worktree file was deleted). Restoring
         // the captured entry is exact regardless of how the entry got there.
-        const priorEntry = (await execGitWithAllowedExitCodes(repoDir, ['ls-files', '--stage', '--', filePath])).stdout;
+        const priorEntry = await git(['ls-files', '--stage', '--', filePath], repoDir);
         try {
-            await execGitWithAllowedExitCodes(repoDir, ['add', '--intent-to-add', '--', filePath]);
-            const diffResult = await execGitWithAllowedExitCodes(repoDir, [
-                'diff',
-                '--binary',
-                '--',
-                filePath,
-            ]);
-            return diffResult.stdout;
+            await git(['add', '--intent-to-add', '--', filePath], repoDir);
+            return await git([...gitConfigArgs, 'diff', '--binary', '--', filePath], repoDir);
         }
         finally {
             await restoreIndexEntry(repoDir, filePath, priorEntry);
@@ -581,11 +517,12 @@ export async function generateBinaryFilePatch(repoDir, filePath) {
 /**
  * Restores a path's index entry to a previously captured `ls-files --stage`
  * snapshot after a temporary `--intent-to-add` staging. No prior entry means
- * the temporary entry is dropped via `reset HEAD` (the path's HEAD state IS
- * "absent" — this branch only runs for files untracked in HEAD). A prior
+ * the temporary entry is dropped via `reset HEAD` (the path's HEAD state is
+ * "absent", and this branch only runs for files untracked in HEAD). A prior
  * stage-0 entry is re-pointed at its recorded mode and blob. Unmerged entries
- * (stages 1–3) cannot be rebuilt through `--cacheinfo`; that degenerate state
- * keeps the legacy reset-to-HEAD behavior rather than corrupting the conflict.
+ * (stages 1 to 3) cannot be rebuilt through `--cacheinfo`. That degenerate
+ * state keeps the legacy reset-to-HEAD behavior rather than corrupting the
+ * conflict.
  * @param repoDir - Repository directory
  * @param filePath - File path (relative to repo root)
  * @param priorEntry - Raw `git ls-files --stage -- <file>` output from before staging
@@ -595,13 +532,8 @@ async function restoreIndexEntry(repoDir, filePath, priorEntry) {
     const mode = entryMatch?.[1];
     const oid = entryMatch?.[2];
     if (mode === undefined || oid === undefined) {
-        await execGitWithAllowedExitCodes(repoDir, ['reset', 'HEAD', '--', filePath]);
+        await git(['reset', 'HEAD', '--', filePath], repoDir);
         return;
     }
-    await execGitWithAllowedExitCodes(repoDir, [
-        'update-index',
-        '--add',
-        '--cacheinfo',
-        `${mode},${oid},${filePath}`,
-    ]);
+    await git(['update-index', '--add', '--cacheinfo', `${mode},${oid},${filePath}`], repoDir);
 }

package/dist/src/core/git-file-ops.d.ts

@@ -33,10 +33,10 @@ export declare function fileExistsInHead(repoDir: string, filePath: string): Pro
 /**
  * Batched equivalent of {@link fileExistsInHead}: returns the subset of
  * `files` that are tracked in HEAD, using a single `git ls-tree` per ARG_MAX
- * chunk instead of one spawn per file. This is the cold-run hot path — a
- * Firefox-sized checkout has hundreds of affected files.
+ * chunk instead of one spawn per file. This is the cold-run hot path, and
+ * a Firefox-sized checkout has hundreds of affected files.
  *
- * `-r` lists nested blobs by full repo-relative path; `--name-only -z` makes
+ * `-r` lists nested blobs by full repo-relative path. `--name-only -z` makes
  * the output a trivial NUL-split with no quoting to undo. Membership in the
  * returned Set is exactly `await fileExistsInHead(repoDir, file)` for any
  * non-directory `file`. Throws (via {@link git}) when HEAD itself is
@@ -56,10 +56,10 @@ export declare function listTrackedInHead(repoDir: string, files: string[]): Pro
  * Uses {@link import('../utils/process.js').exec} rather than {@link git}
  * (which throws on a non-zero exit) because `git hash-object f1 f2 …` is
  * all-or-nothing: it aborts at the first unreadable path and emits nothing
- * for the rest. To keep the per-file contract — where one bad path zeroes
- * only its own index line — a chunk that does not return exactly one hash
+ * for the rest. To keep the per-file contract, where one bad path zeroes
+ * only its own index line, a chunk that does not return exactly one hash
  * per input falls back to hashing that chunk's paths individually. A path
- * that is still unhashable is left out of the map; the caller applies the
+ * that is still unhashable is left out of the map. The caller applies the
  * `0000000000` zero-hash fallback for any miss. Hashing stays in git rather
  * than in-process so filters and `.gitattributes` are applied per path and
  * the result cannot diverge under `core.autocrlf`/`text` attributes.
@@ -77,13 +77,6 @@ export declare function hashObjectBatch(repoDir: string, fullPaths: string[]): P
  * @returns File content or null if file doesn't exist at that ref
  */
 export declare function getFileContentAtRef(repoDir: string, filePath: string, ref?: string): Promise<string | null>;
-/**
- * Gets the content of a file from HEAD commit.
- * @param repoDir - Repository directory
- * @param filePath - Path to the file (relative to repo)
- * @returns File content or null if file doesn't exist in HEAD
- */
-export declare function getFileContentFromHead(repoDir: string, filePath: string): Promise<string | null>;
 /**
  * Checks if a file is binary by looking for NUL bytes in the first 8KB.
  * Uses the same heuristic as git.