@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/git-base.d.ts

@@ -1,7 +1,7 @@
 /**
  * Environment variable that overrides the monolithic `git add -A` timeout
  * (milliseconds). Operators on slow or loaded filesystems can legitimately
- * exceed the 10-minute default during a baseline indexing pass; making the
+ * exceed the 10-minute default during a baseline indexing pass. Making the
  * cap overridable lets them retry without recompiling.
  */
 export declare const GIT_ADD_TIMEOUT_ENV_VAR = "FIREFORGE_GIT_ADD_TIMEOUT_MS";
@@ -47,7 +47,9 @@ export interface GitStatusEntry {
     isDeleted: boolean;
 }
 /**
- * Ensures git is available in the system.
+ * Ensures git is available in the system. Memoised after the first successful
+ * probe. {@link git} calls it, so callers that go through that wrapper do not
+ * need to.
  * @throws GitNotFoundError if git is not installed
  */
 export declare function ensureGit(): Promise<void>;
@@ -65,7 +67,7 @@ export declare function git(args: string[], cwd: string, options?: {
  * Splits a pathspec list into chunks whose joined byte length stays well under
  * the OS `ARG_MAX` limit, so a single batched `git` invocation over hundreds of
  * Mozilla-length paths cannot fail with `E2BIG`. The 96 KB budget is
- * deliberately conservative — even the smallest historical `ARG_MAX` (256 KB)
+ * conservative on purpose: even the smallest historical `ARG_MAX` (256 KB)
  * leaves room for the fixed git arguments plus the inherited environment.
  *
  * Chunk boundaries are output-neutral for every batched caller here: each
@@ -91,7 +93,7 @@ export declare function configureGitPerformance(repoDir: string): Promise<void>;
  * rewrites LF to CRLF on checkout and back on staging. FireForge cannot
  * tolerate that: patch bodies are byte diffs of the working tree, and
  * `hashObjectBatch` deliberately delegates to git so `.gitattributes` and
- * `core.autocrlf` DO apply to the hashes `status` compares against. Under the
+ * `core.autocrlf` do apply to the hashes `status` compares against. Under the
  * global default the same tree hashes differently on Windows than everywhere
  * else, so exported patches and drift detection disagree across machines.
  * Setting it per-repository leaves the developer's global config alone.

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

@@ -5,7 +5,7 @@ import { readOnlyGitIndexEnv } from './git-readonly-index.js';
 /**
  * Environment variable that overrides the monolithic `git add -A` timeout
  * (milliseconds). Operators on slow or loaded filesystems can legitimately
- * exceed the 10-minute default during a baseline indexing pass; making the
+ * exceed the 10-minute default during a baseline indexing pass. Making the
  * cap overridable lets them retry without recompiling.
  */
 export const GIT_ADD_TIMEOUT_ENV_VAR = 'FIREFORGE_GIT_ADD_TIMEOUT_MS';
@@ -43,12 +43,33 @@ export const GIT_ADD_TIMEOUT_MS = resolveTimeoutFromEnv(GIT_ADD_TIMEOUT_ENV_VAR,
  */
 export const GIT_ADD_CHUNK_TIMEOUT_MS = resolveTimeoutFromEnv(GIT_ADD_CHUNK_TIMEOUT_ENV_VAR, DEFAULT_GIT_ADD_CHUNK_TIMEOUT_MS);
 /**
- * Ensures git is available in the system.
+ * In-flight or settled successful `git` availability probe.
+ *
+ * The probe spawns `which git` (or `where` on Windows), and every git wrapper
+ * in this layer used to run it before each command, which meant dozens of
+ * extra spawns per `fireforge export`. Only success is cached: a rejection
+ * clears the slot so a run that installs git mid-flight (or a test that flips
+ * the probe) sees the new answer instead of a sticky refusal.
+ */
+let gitAvailability;
+/**
+ * Ensures git is available in the system. Memoised after the first successful
+ * probe. {@link git} calls it, so callers that go through that wrapper do not
+ * need to.
  * @throws GitNotFoundError if git is not installed
  */
 export async function ensureGit() {
-    if (!(await executableExists('git'))) {
-        throw new GitNotFoundError();
+    gitAvailability ??= (async () => {
+        if (!(await executableExists('git'))) {
+            throw new GitNotFoundError();
+        }
+    })();
+    try {
+        await gitAvailability;
+    }
+    catch (error) {
+        gitAvailability = undefined;
+        throw error;
     }
 }
 /**
@@ -58,13 +79,14 @@ export async function ensureGit() {
  * @returns Command output
  */
 export async function git(args, cwd, options) {
+    await ensureGit();
     const execOptions = { cwd };
     if (options?.timeout !== undefined) {
         execOptions.timeout = options.timeout;
     }
     // A read-only command's private-index scope overlays GIT_INDEX_FILE so
     // index refreshes never touch the primary checkout.
-    // Merged UNDER the caller's own env so an explicit override still wins.
+    // Merged under the caller's own env so an explicit override still wins.
     const readOnlyIndexEnv = readOnlyGitIndexEnv(cwd);
     if (options?.env !== undefined || readOnlyIndexEnv !== undefined) {
         execOptions.env = { ...readOnlyIndexEnv, ...options?.env };
@@ -79,7 +101,7 @@ export async function git(args, cwd, options) {
  * Splits a pathspec list into chunks whose joined byte length stays well under
  * the OS `ARG_MAX` limit, so a single batched `git` invocation over hundreds of
  * Mozilla-length paths cannot fail with `E2BIG`. The 96 KB budget is
- * deliberately conservative — even the smallest historical `ARG_MAX` (256 KB)
+ * conservative on purpose: even the smallest historical `ARG_MAX` (256 KB)
  * leaves room for the fixed git arguments plus the inherited environment.
  *
  * Chunk boundaries are output-neutral for every batched caller here: each
@@ -128,7 +150,7 @@ export async function configureGitPerformance(repoDir) {
  * rewrites LF to CRLF on checkout and back on staging. FireForge cannot
  * tolerate that: patch bodies are byte diffs of the working tree, and
  * `hashObjectBatch` deliberately delegates to git so `.gitattributes` and
- * `core.autocrlf` DO apply to the hashes `status` compares against. Under the
+ * `core.autocrlf` do apply to the hashes `status` compares against. Under the
  * global default the same tree hashes differently on Windows than everywhere
  * else, so exported patches and drift detection disagree across machines.
  * Setting it per-repository leaves the developer's global config alone.

package/dist/src/core/git-diff-new-file.d.ts

@@ -0,0 +1,40 @@
+/** How a new file is carried in a patch, plus its text when it is text. */
+export type NewFileContent = {
+    readonly binary: true;
+} | {
+    readonly binary: false;
+    readonly content: string;
+};
+/**
+ * Reads a new (untracked) file and classifies it for patch generation.
+ *
+ * A file is binary when git's NUL-byte heuristic says so
+ * ({@link isBinaryFile}) or when its bytes are not valid UTF-8. See the
+ * module comment for why the second arm exists. Text files come back with
+ * their exact decoded content so callers do not read the file twice.
+ *
+ * @param repoDir - Repository directory
+ * @param filePath - File path (relative to repo root)
+ * @returns The classification, with content for text files
+ */
+export declare function readNewFileContent(repoDir: string, filePath: string): Promise<NewFileContent>;
+/**
+ * Runs `task` with git config arguments that force `filePath` to be diffed
+ * as binary.
+ *
+ * `git diff --binary` only emits a `GIT binary patch` for a file git itself
+ * classifies as binary, and git's classifier is the NUL heuristic, so a
+ * Latin-1 file passes it and comes out as a text diff whose high bytes are
+ * then mangled by the UTF-8 decode every subprocess result goes through.
+ * The `-diff` attribute is how git is told otherwise, and a throwaway
+ * `core.attributesFile` naming just this path is the narrowest way to set it
+ * without touching the tree's own `.gitattributes`. (An in-tree attribute
+ * that explicitly sets `diff` for the path would still win. The tree's own
+ * attributes are its business.)
+ *
+ * @param filePath - File path (relative to repo root)
+ * @param task - Receives `['-c', 'core.attributesFile=...']` to splice ahead
+ *   of the git subcommand
+ * @returns Whatever `task` returns
+ */
+export declare function withForcedBinaryAttribute<T>(filePath: string, task: (gitConfigArgs: string[]) => Promise<T>): Promise<T>;

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

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Decides how a new (untracked) file travels inside a patch: as a synthesized
+ * `+`-line text body, or as a `GIT binary patch`.
+ *
+ * The text body is built from a JavaScript string, and the `index` line next
+ * to it comes from `git hash-object` over the file's real bytes. Those two
+ * agree only when the bytes decode losslessly as UTF-8. A Latin-1
+ * `.properties` or `.rc` file has no NUL byte, so git's own binary heuristic
+ * calls it text, but a UTF-8 decode turns every high byte into U+FFFD, so
+ * the patch body and its blob hash disagree, `git apply` writes different
+ * bytes than the tree holds, and every drift check flags the file forever.
+ * A binary patch carries the bytes verbatim, so it is the faithful choice for
+ * anything that is not valid UTF-8. This module is the single place that
+ * decision is made.
+ */
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { isBinaryFile } from './git-file-ops.js';
+// `ignoreBOM: true` keeps a leading U+FEFF in the output instead of silently
+// consuming it, matching `readFile(path, 'utf-8')`, so a BOM-prefixed file
+// still renders the byte the blob hash was computed over.
+const strictUtf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+/**
+ * Decodes bytes as UTF-8, or reports that they are not valid UTF-8.
+ * @param bytes - Raw file bytes
+ * @returns The decoded text, or undefined when any sequence is malformed
+ */
+function decodeStrictUtf8(bytes) {
+    try {
+        return strictUtf8.decode(bytes);
+    }
+    catch (error) {
+        void error;
+        return undefined;
+    }
+}
+/**
+ * Reads a new (untracked) file and classifies it for patch generation.
+ *
+ * A file is binary when git's NUL-byte heuristic says so
+ * ({@link isBinaryFile}) or when its bytes are not valid UTF-8. See the
+ * module comment for why the second arm exists. Text files come back with
+ * their exact decoded content so callers do not read the file twice.
+ *
+ * @param repoDir - Repository directory
+ * @param filePath - File path (relative to repo root)
+ * @returns The classification, with content for text files
+ */
+export async function readNewFileContent(repoDir, filePath) {
+    if (await isBinaryFile(repoDir, filePath)) {
+        return { binary: true };
+    }
+    const content = decodeStrictUtf8(await readFile(join(repoDir, filePath)));
+    if (content === undefined) {
+        return { binary: true };
+    }
+    return { binary: false, content };
+}
+/**
+ * Renders one repo-relative path as an anchored, literal gitattributes
+ * pattern: the whole thing is C-quoted (which gitattributes accepts for
+ * patterns holding spaces or `#`) and glob metacharacters carry a backslash
+ * that survives the unquoting, so git matches them literally.
+ *
+ * Both escapes are applied in a single pass, keyed on the source character.
+ * Escaping in two passes would re-escape the backslashes the first pass just
+ * added, and a backslash that is part of the filename would have to be
+ * escaped for the glob layer as well as the quoting layer, which a
+ * glob-only first pass cannot tell apart from one it emitted itself.
+ *
+ * @param filePath - File path (relative to repo root)
+ * @returns A pattern matching exactly that path
+ */
+function toLiteralAttributePattern(filePath) {
+    // `"` only needs the quoting layer, so one backslash. A glob
+    // metacharacter takes a backslash for the glob layer, which the quoting
+    // layer then doubles into two. A literal `\` is both: the glob layer
+    // doubles it, then the quoting layer doubles that again, for four.
+    const escaped = filePath.replace(/["\\*?[\]]/g, (char) => {
+        if (char === '"')
+            return '\\"';
+        if (char === '\\')
+            return '\\\\\\\\';
+        return `\\\\${char}`;
+    });
+    return `"/${escaped}"`;
+}
+/**
+ * Runs `task` with git config arguments that force `filePath` to be diffed
+ * as binary.
+ *
+ * `git diff --binary` only emits a `GIT binary patch` for a file git itself
+ * classifies as binary, and git's classifier is the NUL heuristic, so a
+ * Latin-1 file passes it and comes out as a text diff whose high bytes are
+ * then mangled by the UTF-8 decode every subprocess result goes through.
+ * The `-diff` attribute is how git is told otherwise, and a throwaway
+ * `core.attributesFile` naming just this path is the narrowest way to set it
+ * without touching the tree's own `.gitattributes`. (An in-tree attribute
+ * that explicitly sets `diff` for the path would still win. The tree's own
+ * attributes are its business.)
+ *
+ * @param filePath - File path (relative to repo root)
+ * @param task - Receives `['-c', 'core.attributesFile=...']` to splice ahead
+ *   of the git subcommand
+ * @returns Whatever `task` returns
+ */
+export async function withForcedBinaryAttribute(filePath, task) {
+    const tempDir = await mkdtemp(join(tmpdir(), 'fireforge-attr-'));
+    try {
+        const attributesFile = join(tempDir, 'attributes');
+        await writeFile(attributesFile, `${toLiteralAttributePattern(filePath)} -diff\n`);
+        return await task(['-c', `core.attributesFile=${attributesFile}`]);
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}

package/dist/src/core/git-diff.d.ts

@@ -4,7 +4,7 @@
  * `--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)
@@ -12,7 +12,10 @@
  */
 export declare function getFileDiff(repoDir: string, filePath: string): Promise<string>;
 /**
- * Generates a unified diff for a new (untracked) file.
+ * 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
@@ -28,20 +31,12 @@ export declare function generateNewFileDiff(repoDir: string, filePath: string):
  * @returns Diff content in unified diff format
  */
 export declare function generateFullFilePatch(repoDir: string, filePath: string): Promise<string>;
-/**
- * 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 declare function generateModificationDiff(repoDir: string, filePath: string, baseContent: string): Promise<string>;
 /**
  * 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
  */
@@ -49,7 +44,7 @@ export declare function getAllDiff(repoDir: string): Promise<string>;
 /**
  * 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
@@ -75,6 +70,11 @@ export declare function getStagedDiffForFiles(repoDir: string, files: string[]):
  * 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