@hominis/fireforge 0.45.0 → 0.46.0

package/dist/src/core/furnace-validate-registration.js

@@ -1,9 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { createHash } from 'node:crypto';
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
+import { sha256Hex } from '../utils/hash.js';
 import { warn } from '../utils/logger.js';
 import { escapeRegex, stripJsComments } from '../utils/regex.js';
 import { getProjectPaths, loadConfig } from './config.js';
@@ -129,8 +129,8 @@ export async function checkRegistrationConsistency(root, name, config, ftlDir) {
             // comparisons hashed raw bytes, so on a CRLF checkout `furnace status`
             // and `furnace validate` reported drift for files apply had just
             // decided were identical.
-            const srcHash = createHash('sha256').update(normalizeForChecksum(srcContent)).digest('hex');
-            const destHash = createHash('sha256').update(normalizeForChecksum(destContent)).digest('hex');
+            const srcHash = sha256Hex(normalizeForChecksum(srcContent));
+            const destHash = sha256Hex(normalizeForChecksum(destContent));
             if (srcHash !== destHash) {
                 status.driftedFiles.push(entry.name);
                 status.filesInSync = false;
@@ -155,10 +155,8 @@ export async function checkRegistrationConsistency(root, name, config, ftlDir) {
             else {
                 const srcContent = await readText(ftlSrc);
                 const destContent = await readText(ftlDest);
-                const srcHash = createHash('sha256').update(normalizeForChecksum(srcContent)).digest('hex');
-                const destHash = createHash('sha256')
-                    .update(normalizeForChecksum(destContent))
-                    .digest('hex');
+                const srcHash = sha256Hex(normalizeForChecksum(srcContent));
+                const destHash = sha256Hex(normalizeForChecksum(destContent));
                 if (srcHash !== destHash) {
                     status.driftedFiles.push(ftlName);
                     status.filesInSync = false;

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

@@ -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>;

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

@@ -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 — 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,6 +79,7 @@ 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;

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 — 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 — 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 — 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

@@ -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,14 +31,6 @@ 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.
  *
@@ -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