@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,162 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { GitError, GitNotFoundError } from '../errors/git.js';
-import { exec, executableExists } from '../utils/process.js';
-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
- * cap overridable lets them retry without recompiling.
- */
-export const GIT_ADD_TIMEOUT_ENV_VAR = 'FIREFORGE_GIT_ADD_TIMEOUT_MS';
-/**
- * Environment variable that overrides the per-chunk `git add -- <dir>`
- * timeout (milliseconds). Paired with {@link GIT_ADD_TIMEOUT_ENV_VAR} so
- * both the monolithic attempt and the chunked fallback can be extended.
- */
-export const GIT_ADD_CHUNK_TIMEOUT_ENV_VAR = 'FIREFORGE_GIT_ADD_CHUNK_TIMEOUT_MS';
-/** Default timeout for `git add -A` on large trees (10 minutes). */
-const DEFAULT_GIT_ADD_TIMEOUT_MS = 10 * 60_000;
-/** Default timeout for chunked `git add` per top-level directory (30 minutes). */
-const DEFAULT_GIT_ADD_CHUNK_TIMEOUT_MS = 30 * 60_000;
-function resolveTimeoutFromEnv(envVar, fallbackMs) {
-    const raw = process.env[envVar];
-    if (raw === undefined || raw.length === 0)
-        return fallbackMs;
-    const parsed = Number.parseInt(raw, 10);
-    if (!Number.isFinite(parsed) || parsed <= 0)
-        return fallbackMs;
-    return parsed;
-}
-/**
- * Resolved timeout for monolithic `git add -A`. Prefers
- * {@link GIT_ADD_TIMEOUT_ENV_VAR} when present (and a positive
- * integer) so operators on slow hosts can extend the default without
- * rebuilding FireForge.
- */
-export const GIT_ADD_TIMEOUT_MS = resolveTimeoutFromEnv(GIT_ADD_TIMEOUT_ENV_VAR, DEFAULT_GIT_ADD_TIMEOUT_MS);
-/**
- * Resolved timeout for each chunk of the chunked fallback path. Generous by
- * design: the fallback is already the last line of defence before aborting,
- * so erring toward "complete the indexing" over "fail fast" matches the
- * real-world recovery workflow.
- */
-export const GIT_ADD_CHUNK_TIMEOUT_MS = resolveTimeoutFromEnv(GIT_ADD_CHUNK_TIMEOUT_ENV_VAR, DEFAULT_GIT_ADD_CHUNK_TIMEOUT_MS);
-/**
- * In-flight or settled successful `git` availability probe.
- *
- * The probe spawns `which git` (or `where` on Windows); running it before
- * every command would mean dozens of extra spawns per `fireforge export`, so
- * the result is shared by every git wrapper in this layer. 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() {
-    gitAvailability ??= (async () => {
-        if (!(await executableExists('git'))) {
-            throw new GitNotFoundError();
-        }
-    })();
-    try {
-        await gitAvailability;
-    }
-    catch (error) {
-        gitAvailability = undefined;
-        throw error;
-    }
-}
-/**
- * Runs a git command in the specified directory.
- * @param args - Git command arguments
- * @param cwd - Working directory
- * @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.
-    const readOnlyIndexEnv = readOnlyGitIndexEnv(cwd);
-    if (options?.env !== undefined || readOnlyIndexEnv !== undefined) {
-        execOptions.env = { ...readOnlyIndexEnv, ...options?.env };
-    }
-    const result = await exec('git', args, execOptions);
-    if (result.exitCode !== 0) {
-        throw new GitError(result.stderr.trim() || 'Git command failed', args.join(' '));
-    }
-    return result.stdout;
-}
-/**
- * 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
- * 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
- * caller merges the per-chunk results into a single Set/Map keyed by path, so
- * how the paths are grouped across invocations never affects the result.
- * @param paths - Pathspecs to chunk
- * @param budgetBytes - Maximum joined byte length per chunk
- * @returns Path chunks, each safe to pass as a single argv tail
- */
-export function chunkPathspecs(paths, budgetBytes = 96_000) {
-    const chunks = [];
-    let current = [];
-    let used = 0;
-    for (const path of paths) {
-        const cost = Buffer.byteLength(path) + 1;
-        if (current.length > 0 && used + cost > budgetBytes) {
-            chunks.push(current);
-            current = [];
-            used = 0;
-        }
-        current.push(path);
-        used += cost;
-    }
-    if (current.length > 0)
-        chunks.push(current);
-    return chunks;
-}
-/**
- * Configures git performance settings for large trees.
- * Enables index preloading, untracked cache, and the manyFiles feature
- * flag which significantly reduces `git add` / `git status` time on
- * repositories with hundreds of thousands of files.
- */
-export async function configureGitPerformance(repoDir) {
-    await git(['config', 'core.preloadindex', 'true'], repoDir);
-    await git(['config', 'core.untrackedCache', 'true'], repoDir);
-    // Explicitly disable fsmonitor to avoid daemon issues on freshly-created repos
-    await git(['config', 'core.fsmonitor', 'false'], repoDir);
-    await git(['config', 'feature.manyFiles', 'true'], repoDir);
-}
-/**
- * Pins the engine repository's line-ending policy to "store and check out
- * exactly what upstream shipped".
- *
- * Git's Windows installer defaults to a global `core.autocrlf=true`, which
- * 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
- * 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.
- */
-export async function configureGitLineEndings(repoDir) {
-    await git(['config', 'core.autocrlf', 'false'], repoDir);
-    await git(['config', 'core.eol', 'lf'], repoDir);
-}

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

@@ -1,40 +0,0 @@
-/** 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

@@ -1,118 +0,0 @@
-// 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 {
-        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

@@ -1,82 +0,0 @@
-/**
- * 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
- * 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 declare function getFileDiff(repoDir: string, filePath: string): Promise<string>;
-/**
- * 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 declare function generateNewFileDiff(repoDir: string, filePath: string): Promise<string>;
-/**
- * Generates a patch for a file.
- * If the file is tracked in HEAD, it generates a standard contextual diff.
- * If the file is untracked (new), it generates a "new file" format patch (snapshot).
- * This ensures standard 3-way mergeable context diffs for existing Mozilla files.
- * @param repoDir - Repository directory
- * @param filePath - Path to the file (relative to repo)
- * @returns Diff content in unified diff format
- */
-export declare function generateFullFilePatch(repoDir: string, filePath: 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
- * go through {@link generateBinaryFilePatch} below. Both arms must stay
- * binary-aware. See {@link getFileDiff} for why.
- * @param repoDir - Repository directory
- * @returns Diff content
- */
-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
- * {@link generateBinaryFilePatch} when the file is binary.
- *
- * Performance: the work is batched into a handful of `git` invocations (one
- * `ls-tree` to classify, one `diff` over all tracked files, one `hash-object`
- * over all new text files) rather than ~2 spawns per file, which dominates
- * the cold-run cost on a Firefox-sized checkout. Binary, directory, and
- * recursion paths stay per-file because they are rare and (for binary)
- * mutate the index.
- *
- * @param repoDir - Repository directory
- * @param files - File paths to diff (relative to repo root)
- * @returns Combined diff content
- */
-export declare function getDiffForFilesAgainstHead(repoDir: string, files: string[]): Promise<string>;
-/**
- * Generates a combined diff for staged files against HEAD.
- * @param repoDir - Repository directory
- * @param files - File paths to diff (relative to repo)
- * @returns Diff content for the staged files
- */
-export declare function getStagedDiffForFiles(repoDir: string, files: string[]): Promise<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
- */
-export declare function generateBinaryFilePatch(repoDir: string, filePath: string): Promise<string>;