@hominis/fireforge 0.9.0

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

@@ -0,0 +1,113 @@
+export type { GitStatusEntry } from './git-base.js';
+/**
+ * Checks if a directory is a git repository.
+ * @param dir - Directory to check
+ * @returns True if the directory is a git repository
+ */
+export declare function isGitRepository(dir: string): Promise<boolean>;
+/**
+ * Ensures the repository has an "origin" remote.
+ *
+ * Firefox's mach bootstrap and build scripts shell out to
+ * `git remote get-url origin` and emit noisy errors when the remote is
+ * absent.  This adds a local-only dummy remote so those scripts stay quiet.
+ * Nothing is ever fetched from or pushed to this remote.
+ *
+ * @param dir - Git working directory
+ */
+export declare function ensureOriginRemote(dir: string): Promise<void>;
+/**
+ * Stages all files in the repository.
+ * Tries a monolithic `git add -A` first; if that times out, falls back to
+ * directory-by-directory staged adds.
+ */
+export declare function stageAllFiles(dir: string, options?: {
+    onProgress?: (message: string) => void;
+    timeout?: number;
+}): Promise<void>;
+/**
+ * Initializes a new git repository with an orphan branch.
+ * @param dir - Directory to initialize
+ * @param branchName - Name for the initial branch
+ */
+export declare function initRepository(dir: string, branchName?: string, options?: {
+    onProgress?: (message: string) => void;
+}): Promise<void>;
+/**
+ * Resumes a partially initialized git repository (e.g. after a killed
+ * `git add -A` left an unborn HEAD).  Re-applies performance settings,
+ * cleans up stale locks, stages all files, and creates the initial commit.
+ */
+export declare function resumeRepository(dir: string, options?: {
+    onProgress?: (message: string) => void;
+}): Promise<void>;
+/**
+ * Applies a patch file using git apply.
+ * @param patchPath - Path to the patch file
+ * @param repoDir - Repository directory
+ * @param options - Application options
+ */
+export declare function applyPatch(patchPath: string, repoDir: string, options?: {
+    reject?: boolean;
+}): Promise<void>;
+/**
+ * Applies a patch idempotently using reverse-forward pattern.
+ * First tries to reverse the patch (in case it's already applied),
+ * then applies it forward.
+ * @param patchPath - Path to the patch file
+ * @param repoDir - Repository directory
+ * @param options - Application options
+ */
+export declare function applyPatchIdempotent(patchPath: string, repoDir: string, options?: {
+    reject?: boolean;
+}): Promise<void>;
+/**
+ * Reverses a previously applied patch.
+ * @param patchPath - Path to the patch file
+ * @param repoDir - Repository directory
+ */
+export declare function reversePatch(patchPath: string, repoDir: string): Promise<void>;
+/**
+ * Checks if the repository has uncommitted changes.
+ * @param repoDir - Repository directory
+ * @returns True if there are uncommitted changes
+ */
+export declare function hasChanges(repoDir: string): Promise<boolean>;
+/**
+ * Checks whether an error indicates the repository has no HEAD (e.g. unborn branch).
+ * @param error - The error to check
+ * @returns True if the error is a missing-HEAD error
+ */
+export declare function isMissingHeadError(error: unknown): boolean;
+/**
+ * Gets the current HEAD commit hash.
+ * @param repoDir - Repository directory
+ * @returns Commit hash
+ */
+export declare function getHead(repoDir: string): Promise<string>;
+/**
+ * Gets the current branch name.
+ * @param repoDir - Repository directory
+ * @returns Branch name
+ */
+export declare function getCurrentBranch(repoDir: string): Promise<string>;
+/**
+ * Resets all changes in the repository.
+ * @param repoDir - Repository directory
+ */
+export declare function resetChanges(repoDir: string): Promise<void>;
+/**
+ * Creates a commit with all current changes.
+ * @param repoDir - Repository directory
+ * @param message - Commit message
+ */
+export declare function commit(repoDir: string, message: string): Promise<void>;
+/**
+ * Gets the status of files with their status codes.
+ * @param repoDir - Repository directory
+ * @returns Array of [status, filepath] tuples
+ */
+export declare function getStatusWithCodes(repoDir: string): Promise<Array<{
+    status: string;
+    file: string;
+}>>;

package/dist/src/core/git.js

@@ -0,0 +1,363 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { GitError, GitIndexLockError, PatchApplyError } from '../errors/git.js';
+import { toError } from '../utils/errors.js';
+import { pathExists, removeFile } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+import { exec } from '../utils/process.js';
+import { configureGitPerformance, ensureGit, git, GIT_ADD_CHUNK_TIMEOUT_MS, GIT_ADD_TIMEOUT_MS, } from './git-base.js';
+import { getWorkingTreeStatus } from './git-status.js';
+// ── Functions that remain in this file ──
+/**
+ * Checks if a directory is a git repository.
+ * @param dir - Directory to check
+ * @returns True if the directory is a git repository
+ */
+export async function isGitRepository(dir) {
+    const gitDir = join(dir, '.git');
+    return pathExists(gitDir);
+}
+/**
+ * Ensures the repository has an "origin" remote.
+ *
+ * Firefox's mach bootstrap and build scripts shell out to
+ * `git remote get-url origin` and emit noisy errors when the remote is
+ * absent.  This adds a local-only dummy remote so those scripts stay quiet.
+ * Nothing is ever fetched from or pushed to this remote.
+ *
+ * @param dir - Git working directory
+ */
+export async function ensureOriginRemote(dir) {
+    const result = await exec('git', ['remote', 'get-url', 'origin'], { cwd: dir });
+    if (result.exitCode !== 0) {
+        await git(['remote', 'add', 'origin', 'https://github.com/mozilla-firefox/firefox'], dir);
+    }
+}
+// ── Large-tree staging helpers ──
+const GIT_ADD_ENV = { GIT_INDEX_THREADS: '0' };
+/**
+ * Returns true when the error looks like a process killed by the spawn timeout
+ * (SIGTERM → exit code 143).
+ */
+function isTimeoutError(error) {
+    if (!(error instanceof GitError))
+        return false;
+    return /SIGTERM|timed out|exit code 143/i.test(error.message);
+}
+/**
+ * Removes `.git/index.lock` left behind by a killed git process.
+ */
+async function cleanupIndexLock(dir) {
+    const lockPath = join(dir, '.git', 'index.lock');
+    if (await pathExists(lockPath)) {
+        await removeFile(lockPath);
+        verbose('Cleaned up stale .git/index.lock after timeout');
+    }
+}
+/**
+ * Stages every file by walking top-level directories one at a time.
+ * This avoids a single monolithic `git add -A` that may time out on
+ * very large (~300 K file) trees like Firefox.
+ */
+async function stageAllFilesChunked(dir, options = {}) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const directories = entries
+        .filter((e) => e.isDirectory() && e.name !== '.git')
+        .map((e) => e.name)
+        .sort();
+    for (const dirName of directories) {
+        options.onProgress?.(`Staging directory: ${dirName}/...`);
+        await git(['add', '--', dirName], dir, {
+            timeout: GIT_ADD_CHUNK_TIMEOUT_MS,
+            env: GIT_ADD_ENV,
+        });
+    }
+    // Stage any top-level files
+    const topLevelFiles = entries.filter((e) => e.isFile()).map((e) => e.name);
+    if (topLevelFiles.length > 0) {
+        options.onProgress?.('Staging top-level files...');
+        await git(['add', '--', ...topLevelFiles], dir, {
+            timeout: GIT_ADD_CHUNK_TIMEOUT_MS,
+            env: GIT_ADD_ENV,
+        });
+    }
+}
+/**
+ * Stages all files in the repository.
+ * Tries a monolithic `git add -A` first; if that times out, falls back to
+ * directory-by-directory staged adds.
+ */
+export async function stageAllFiles(dir, options = {}) {
+    const timeout = options.timeout ?? GIT_ADD_TIMEOUT_MS;
+    try {
+        await git(['add', '-A'], dir, { timeout, env: GIT_ADD_ENV });
+        return;
+    }
+    catch (error) {
+        if (!isTimeoutError(error)) {
+            throw await maybeWrapIndexLockError(dir, error);
+        }
+        options.onProgress?.('Monolithic git add timed out; falling back to chunked staging...');
+    }
+    // The killed process may have left an index lock
+    await cleanupIndexLock(dir);
+    await stageAllFilesChunked(dir, options);
+}
+/**
+ * Initializes a new git repository with an orphan branch.
+ * @param dir - Directory to initialize
+ * @param branchName - Name for the initial branch
+ */
+export async function initRepository(dir, branchName = 'main', options = {}) {
+    await ensureGit();
+    const reportProgress = options.onProgress ?? (() => { });
+    // Initialize repository
+    reportProgress('Creating git repository...');
+    await git(['init'], dir);
+    // Create orphan branch
+    reportProgress(`Creating ${branchName} baseline branch...`);
+    await git(['checkout', '--orphan', branchName], dir);
+    // Configure git for the repository
+    reportProgress('Configuring git identity...');
+    await git(['config', 'user.email', 'fireforge@localhost'], dir);
+    await git(['config', 'user.name', 'FireForge'], dir);
+    // Enable performance settings for large trees
+    reportProgress('Configuring git performance settings...');
+    await configureGitPerformance(dir);
+    // Add a local-only origin remote so that Firefox's mach bootstrap and
+    // build scripts (which shell out to `git remote get-url origin`) don't
+    // fail.  Nothing is ever fetched from or pushed to this remote.
+    reportProgress('Configuring origin remote for build compatibility...');
+    await git(['remote', 'add', 'origin', 'https://github.com/mozilla-firefox/firefox'], dir);
+    // Add all files
+    reportProgress('Indexing Firefox source with git add -A (this can take several minutes on large trees)...');
+    await assertNoGitIndexLock(dir);
+    try {
+        await stageAllFiles(dir, { onProgress: reportProgress });
+    }
+    catch (error) {
+        throw await maybeWrapIndexLockError(dir, error);
+    }
+    // Create initial commit
+    reportProgress('Creating initial Firefox source commit...');
+    try {
+        await git(['commit', '-m', 'Initial Firefox source'], dir);
+    }
+    catch (error) {
+        throw await maybeWrapIndexLockError(dir, error);
+    }
+}
+/**
+ * Resumes a partially initialized git repository (e.g. after a killed
+ * `git add -A` left an unborn HEAD).  Re-applies performance settings,
+ * cleans up stale locks, stages all files, and creates the initial commit.
+ */
+export async function resumeRepository(dir, options = {}) {
+    await ensureGit();
+    const reportProgress = options.onProgress ?? (() => { });
+    if (!(await isGitRepository(dir))) {
+        throw new GitError('Not a git repository', 'resume');
+    }
+    reportProgress('Resuming interrupted repository initialization...');
+    // Ensure performance settings are in place (may not have been set)
+    reportProgress('Configuring git performance settings...');
+    await configureGitPerformance(dir);
+    // Clean up any stale index lock left by the killed process
+    await cleanupIndexLock(dir);
+    // Ensure origin remote exists (may have been added before the interrupt)
+    await ensureOriginRemote(dir);
+    // Stage all files
+    reportProgress('Indexing Firefox source (resuming)...');
+    await assertNoGitIndexLock(dir);
+    try {
+        await stageAllFiles(dir, { onProgress: reportProgress });
+    }
+    catch (error) {
+        throw await maybeWrapIndexLockError(dir, error);
+    }
+    // Create initial commit
+    reportProgress('Creating initial Firefox source commit...');
+    try {
+        await git(['commit', '-m', 'Initial Firefox source'], dir);
+    }
+    catch (error) {
+        throw await maybeWrapIndexLockError(dir, error);
+    }
+}
+async function assertNoGitIndexLock(dir) {
+    const lockPath = join(dir, '.git', 'index.lock');
+    if (!(await pathExists(lockPath))) {
+        return;
+    }
+    throw new GitIndexLockError(lockPath, await getLockAgeMs(lockPath));
+}
+async function getLockAgeMs(lockPath) {
+    try {
+        const stats = await stat(lockPath);
+        return Math.max(0, Date.now() - stats.mtimeMs);
+    }
+    catch (error) {
+        void error;
+        return undefined;
+    }
+}
+async function maybeWrapIndexLockError(dir, error) {
+    const lockPath = join(dir, '.git', 'index.lock');
+    if (error instanceof GitError &&
+        /index\.lock/i.test(error.message) &&
+        /(unable to create|another git process seems to be running|file exists)/i.test(error.message)) {
+        return new GitIndexLockError(lockPath);
+    }
+    if (error instanceof GitError &&
+        /(unable to create|locked|lock file)/i.test(error.message) &&
+        (await pathExists(lockPath))) {
+        return new GitIndexLockError(lockPath, await getLockAgeMs(lockPath));
+    }
+    return toError(error);
+}
+/**
+ * Applies a patch file using git apply.
+ * @param patchPath - Path to the patch file
+ * @param repoDir - Repository directory
+ * @param options - Application options
+ */
+export async function applyPatch(patchPath, repoDir, options = {}) {
+    await ensureGit();
+    if (!options.reject) {
+        const checkArgs = ['apply', '--check', '--', patchPath];
+        const result = await exec('git', checkArgs, { cwd: repoDir });
+        if (result.exitCode !== 0) {
+            throw new PatchApplyError(patchPath, new Error(result.stderr));
+        }
+    }
+    // Actually apply the patch
+    const applyArgs = ['apply'];
+    if (options.reject) {
+        applyArgs.push('--reject');
+    }
+    applyArgs.push('--', patchPath);
+    const applyResult = await exec('git', applyArgs, { cwd: repoDir });
+    if (applyResult.exitCode !== 0) {
+        throw new PatchApplyError(patchPath, new Error(applyResult.stderr));
+    }
+}
+/**
+ * Applies a patch idempotently using reverse-forward pattern.
+ * First tries to reverse the patch (in case it's already applied),
+ * then applies it forward.
+ * @param patchPath - Path to the patch file
+ * @param repoDir - Repository directory
+ * @param options - Application options
+ */
+export async function applyPatchIdempotent(patchPath, repoDir, options = {}) {
+    await ensureGit();
+    // Try to reverse the patch (ignore errors if not applied)
+    const reverseResult = await exec('git', ['apply', '--reverse', '--', patchPath], {
+        cwd: repoDir,
+    });
+    // If reverse failed (patch wasn't applied), restore only the files the
+    // patch would have touched so that unrelated local edits are preserved.
+    if (reverseResult.exitCode !== 0) {
+        // Extract the set of files referenced in the patch
+        const listResult = await exec('git', ['apply', '--numstat', '--', patchPath], { cwd: repoDir });
+        const touchedFiles = listResult.stdout
+            .split('\n')
+            .map((line) => line.split('\t')[2])
+            .filter((f) => !!f);
+        if (touchedFiles.length > 0) {
+            // Restore only the files the patch touches
+            await exec('git', ['checkout', 'HEAD', '--', ...touchedFiles], { cwd: repoDir });
+        }
+    }
+    // Apply forward
+    await applyPatch(patchPath, repoDir, options);
+}
+/**
+ * Reverses a previously applied patch.
+ * @param patchPath - Path to the patch file
+ * @param repoDir - Repository directory
+ */
+export async function reversePatch(patchPath, repoDir) {
+    await ensureGit();
+    const result = await exec('git', ['apply', '--reverse', '--', patchPath], { cwd: repoDir });
+    if (result.exitCode !== 0) {
+        throw new PatchApplyError(patchPath, new Error(result.stderr));
+    }
+}
+/**
+ * Checks if the repository has uncommitted changes.
+ * @param repoDir - Repository directory
+ * @returns True if there are uncommitted changes
+ */
+export async function hasChanges(repoDir) {
+    await ensureGit();
+    const entries = await getWorkingTreeStatus(repoDir);
+    return entries.length > 0;
+}
+/**
+ * Checks whether an error indicates the repository has no HEAD (e.g. unborn branch).
+ * @param error - The error to check
+ * @returns True if the error is a missing-HEAD error
+ */
+export function isMissingHeadError(error) {
+    return (error instanceof Error &&
+        /(ambiguous argument 'HEAD'|unknown revision or path not in the working tree)/i.test(error.message));
+}
+/**
+ * Gets the current HEAD commit hash.
+ * @param repoDir - Repository directory
+ * @returns Commit hash
+ */
+export async function getHead(repoDir) {
+    await ensureGit();
+    const output = await git(['rev-parse', 'HEAD'], repoDir);
+    return output.trim();
+}
+/**
+ * Gets the current branch name.
+ * @param repoDir - Repository directory
+ * @returns Branch name
+ */
+export async function getCurrentBranch(repoDir) {
+    await ensureGit();
+    const output = await git(['rev-parse', '--abbrev-ref', 'HEAD'], repoDir);
+    return output.trim();
+}
+/**
+ * Resets all changes in the repository.
+ * @param repoDir - Repository directory
+ */
+export async function resetChanges(repoDir) {
+    await ensureGit();
+    try {
+        await git(['reset', '--hard', 'HEAD'], repoDir);
+    }
+    catch (error) {
+        throw await maybeWrapIndexLockError(repoDir, error);
+    }
+    await git(['clean', '-fd'], repoDir);
+}
+/**
+ * Creates a commit with all current changes.
+ * @param repoDir - Repository directory
+ * @param message - Commit message
+ */
+export async function commit(repoDir, message) {
+    await ensureGit();
+    await stageAllFiles(repoDir);
+    await git(['commit', '-m', message], repoDir);
+}
+/**
+ * Gets the status of files with their status codes.
+ * @param repoDir - Repository directory
+ * @returns Array of [status, filepath] tuples
+ */
+export async function getStatusWithCodes(repoDir) {
+    const entries = await getWorkingTreeStatus(repoDir);
+    return entries.map((entry) => ({
+        status: entry.status.trim(),
+        file: entry.file,
+    }));
+}
+//# sourceMappingURL=git.js.map

package/dist/src/core/license-headers.d.ts

@@ -0,0 +1,36 @@
+import type { ProjectLicense } from '../types/config.js';
+/**
+ * Comment style for license header formatting.
+ * - `js`   — `// ...` line comments
+ * - `css`  — block comments
+ * - `hash` — `# ...` line comments (FTL, shell, etc.)
+ */
+export type CommentStyle = 'js' | 'css' | 'hash';
+/** Default license when fireforge.json omits the license field. */
+export declare const DEFAULT_LICENSE: ProjectLicense;
+/**
+ * Returns a formatted license header comment for the given license and
+ * comment style.
+ *
+ * @param license - SPDX identifier of the project license
+ * @param style   - Comment syntax to wrap the header in
+ * @returns Multi-line string ready to be placed at the top of a source file
+ */
+export declare function getLicenseHeader(license: ProjectLicense, style: CommentStyle): string;
+/**
+ * Returns true if `content` starts with any known license header for the
+ * given comment style.
+ *
+ * @param content - File content to check
+ * @param style   - Comment syntax of the file
+ */
+export declare function hasAnyLicenseHeader(content: string, style: CommentStyle): boolean;
+/**
+ * Prepends the license header to a file on disk if it is not already present.
+ *
+ * @param filePath - Absolute path to the file
+ * @param license  - SPDX identifier of the license to add
+ * @param style    - Comment syntax matching the file type
+ * @returns true if the header was added, false if already present
+ */
+export declare function addLicenseHeaderToFile(filePath: string, license: ProjectLicense, style: CommentStyle): Promise<boolean>;

package/dist/src/core/license-headers.js

@@ -0,0 +1,83 @@
+import { readText, writeText } from '../utils/fs.js';
+/** Default license when fireforge.json omits the license field. */
+export const DEFAULT_LICENSE = 'MPL-2.0';
+/**
+ * Raw (unwrapped) header lines per license.
+ *
+ * Each entry uses the community-recommended file notice for the license.
+ */
+const HEADER_LINES = {
+    'MPL-2.0': [
+        'This Source Code Form is subject to the terms of the Mozilla Public',
+        'License, v. 2.0. If a copy of the MPL was not distributed with this',
+        'file, You can obtain one at http://mozilla.org/MPL/2.0/.',
+    ],
+    'EUPL-1.2': ['SPDX-License-Identifier: EUPL-1.2'],
+    'GPL-2.0-or-later': [
+        'SPDX-License-Identifier: GPL-2.0-or-later',
+        'This file is free software; you can redistribute it and/or modify it',
+        'under the terms of the GNU General Public License as published by the',
+        'Free Software Foundation; either version 2 of the License, or (at your',
+        'option) any later version.',
+    ],
+    '0BSD': ['SPDX-License-Identifier: 0BSD'],
+};
+/**
+ * Returns a formatted license header comment for the given license and
+ * comment style.
+ *
+ * @param license - SPDX identifier of the project license
+ * @param style   - Comment syntax to wrap the header in
+ * @returns Multi-line string ready to be placed at the top of a source file
+ */
+export function getLicenseHeader(license, style) {
+    const lines = HEADER_LINES[license];
+    switch (style) {
+        case 'js':
+            if (lines.length === 1) {
+                return `/* ${lines[0]} */`;
+            }
+            return lines.map((l) => `// ${l}`).join('\n');
+        case 'css':
+            if (lines.length === 1) {
+                return `/* ${lines[0]} */`;
+            }
+            return (`/* ${lines[0]}\n` +
+                lines
+                    .slice(1, -1)
+                    .map((l) => ` * ${l}`)
+                    .join('\n') +
+                (lines.length > 2 ? '\n' : '') +
+                ` * ${lines[lines.length - 1]} */`);
+        case 'hash':
+            return lines.map((l) => `# ${l}`).join('\n');
+    }
+}
+/**
+ * Returns true if `content` starts with any known license header for the
+ * given comment style.
+ *
+ * @param content - File content to check
+ * @param style   - Comment syntax of the file
+ */
+export function hasAnyLicenseHeader(content, style) {
+    const licenses = Object.keys(HEADER_LINES);
+    return licenses.some((license) => content.startsWith(getLicenseHeader(license, style)));
+}
+/**
+ * Prepends the license header to a file on disk if it is not already present.
+ *
+ * @param filePath - Absolute path to the file
+ * @param license  - SPDX identifier of the license to add
+ * @param style    - Comment syntax matching the file type
+ * @returns true if the header was added, false if already present
+ */
+export async function addLicenseHeaderToFile(filePath, license, style) {
+    const content = await readText(filePath);
+    const header = getLicenseHeader(license, style);
+    if (content.startsWith(header))
+        return false;
+    await writeText(filePath, header + '\n' + content);
+    return true;
+}
+//# sourceMappingURL=license-headers.js.map

package/dist/src/core/mach-build-artifacts.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Result of checking for build artifacts.
+ */
+export interface BuildArtifactCheck {
+    /** Whether build artifacts exist */
+    exists: boolean;
+    /** Name of the obj-* directory if found */
+    objDir?: string;
+    /** Whether multiple valid obj-* directories were found */
+    ambiguous?: boolean;
+    /** All candidate obj-* directories with build artifacts */
+    objDirs?: string[];
+    /** Build metadata points at a different source or objdir */
+    metadataMismatch?: {
+        objDir: string;
+        topsrcdir?: string;
+        topobjdir?: string;
+        mozconfig?: string;
+    };
+}
+/**
+ * Checks if build artifacts exist in the engine directory.
+ * Looks for obj-* directories with a dist subdirectory.
+ * @param engineDir - Path to the engine directory
+ * @returns Build artifact check result
+ */
+export declare function hasBuildArtifacts(engineDir: string): Promise<BuildArtifactCheck>;
+/** Builds a user-facing explanation when detected build artifacts belong to another workspace. */
+export declare function buildArtifactMismatchMessage(engineDir: string, buildCheck: BuildArtifactCheck, commandName: string): string | undefined;