@hominis/fireforge 0.28.1 → 0.28.5

package/CHANGELOG.md

@@ -2,7 +2,13 @@
 
 ## 0.28.0
 
+- Restored mach lint compatibility for FireForge-managed Git-backed Firefox checkouts by materializing a `.hgignore` copy of `.gitignore` when Firefox's ignorefile linter config is present.
 - Added the product-resolved Firefox source archive URL to `source set` output so pinned checksums can be verified against the exact archive target before download.
+- Added dry-run locking for `re-export` so parallel previews serialize engine git inspection instead of racing on `.git/index.lock`.
+- Added `re-export --scan --scan-files <manifest>` for dry-runnable bulk generated-file assignment across owner patches, with ambiguity and ownership refusals.
+- Improved `fireforge test` diagnostics for harness startup failures and zero selected tests run, including the actionable harness line before generic failure output.
+- Improved build failure summaries so real make/mach failures and target context outrank trailing warning-only output.
+- Normalized whitespace-only blank hunk payloads in generated patch artifacts while documenting `npm run whitespace:check` as the release-safe source whitespace gate.
 - Fixed re-export serialization so blank context lines keep their unified-diff context marker, preventing FireForge-generated patches from producing false patch-owned drift warnings during `verify`.
 - Fixed partial `re-export` manifest writes so legacy source metadata is preserved on unselected patch rows unless `--stamp` or another source metadata update explicitly targets them.
 - Added regression coverage for targeted and full stamped re-export round-trips with blank context lines.

package/README.md

@@ -55,14 +55,32 @@ After setup you should have a `fireforge.json`, an `engine/` directory containin
 npx fireforge status
 npx fireforge export browser/base/content/browser.js --name custom-toolbar --category ui
 npx fireforge re-export custom-toolbar
+npx fireforge re-export --scan --scan-files generated-assets.json --dry-run
 npx fireforge lint --per-patch
 npx fireforge verify
+npm run whitespace:check
 npx fireforge build
 npx fireforge test browser/base/content/test/browser/
 ```
 
 Use `fireforge --help` for the full set of commands.
 
+For large generated asset batches, `re-export --scan --scan-files <manifest>` assigns files to
+their owner patches without broad directory scanning. The manifest is JSON:
+
+```json
+{
+  "assignments": [
+    { "patch": "002-branding-runtime-icons.patch", "files": ["browser/branding/hominis/icon.svg"] }
+  ]
+}
+```
+
+The command is dry-runnable, refuses ambiguous ownership, and reports each file-to-patch
+assignment before refreshing the patch. For release whitespace checks, use
+`npm run whitespace:check`; it still checks source diffs while excluding generated
+`patches/*.patch` diff syntax.
+
 ## Rebasing Firefox Source
 
 When Mozilla publishes a new Firefox source release you need to update the configured version/product, download the new source code and reapply the patches:

package/dist/src/commands/build.js

@@ -77,27 +77,53 @@ function tailLines(text, maxLines) {
     return lines.slice(-maxLines).join('\n');
 }
 function extractLastMakeError(captured) {
-    const lines = captured.split(/\r?\n/).filter((line) => /\bmake(?:\[\d+\])?: \*\*\*/.test(line));
-    return lines.at(-1)?.trim();
+    const lines = captured.split(/\r?\n/).filter((line) => /\bg?make(?:\[\d+\])?: \*\*\*/.test(line));
+    const actionable = lines.filter((line) => !/\[\s*(?:all|build|default)\s*\]\s+Error\s+\d+/i.test(line));
+    return (actionable.at(-1) ?? lines.at(-1))?.trim();
+}
+function isWarningOnlyLine(line) {
+    if (/\b(?:error|failed|fatal)\b/i.test(line))
+        return false;
+    return (/\bwarning\b/i.test(line) ||
+        /urllib3|LibreSSL|NotOpenSSLWarning|InsecurePlatformWarning/i.test(line));
+}
+function extractRecentMakeContext(captured) {
+    const lines = captured
+        .split(/\r?\n/)
+        .map((line) => line.trimEnd())
+        .filter((line) => line.trim().length > 0);
+    const makeLines = lines.filter((line) => /\b(?:g?make)(?:\[\d+\])?:/.test(line));
+    if (makeLines.length === 0)
+        return undefined;
+    return makeLines.slice(-6).join('\n');
 }
 function extractLikelyFailingCommand(captured) {
     const lines = captured
         .split(/\r?\n/)
         .map((line) => line.trim())
         .filter((line) => line.length > 0);
+    let lastMakeErrorIndex = -1;
     for (let index = lines.length - 1; index >= 0; index--) {
+        if (/\bg?make(?:\[\d+\])?: \*\*\*/.test(lines[index] ?? '')) {
+            lastMakeErrorIndex = index;
+            break;
+        }
+    }
+    const startIndex = lastMakeErrorIndex > 0 ? lastMakeErrorIndex - 1 : lines.length - 1;
+    for (let index = startIndex; index >= 0; index--) {
         const line = lines[index];
         if (!line)
             continue;
+        if (isWarningOnlyLine(line))
+            continue;
         if (/^make(?:\[\d+\])?:/.test(line))
             continue;
         if (/^g?make(?:\[\d+\])?:/.test(line))
             continue;
         if (/^Error running mach:/.test(line))
             continue;
-        if (/^\d+:\d+\.\d+\s+/.test(line))
-            continue;
-        if (/\b(?:cp|clang|clang\+\+|rustc|python|node|make|install_name_tool)\b/.test(line)) {
+        const comparable = line.replace(/^\d+:\d+\.\d+\s+/, '');
+        if (/\b(?:cp|clang|clang\+\+|rustc|python|node|make|install_name_tool)\b/.test(comparable)) {
             return line;
         }
     }
@@ -108,6 +134,7 @@ function buildFailureDiagnostics(result, engineDir, objDir, machCommand) {
     const stderrTail = tailLines(result.stderr, 20);
     const combinedTail = tailLines(captured, 30);
     const makeError = extractLastMakeError(captured);
+    const makeContext = extractRecentMakeContext(captured);
     const failingCommand = extractLikelyFailingCommand(captured);
     const logHint = objDir
         ? `engine/${objDir}/ (inspect build logs, warnings, and generated make targets under this objdir)`
@@ -119,6 +146,7 @@ function buildFailureDiagnostics(result, engineDir, objDir, machCommand) {
         `Build failed with exit code ${result.exitCode}.`,
         `Mach phase: ${machCommand}`,
         makeError ? `Last make error: ${makeError}` : undefined,
+        makeContext ? `Recent make context:\n${makeContext}` : undefined,
         failingCommand ? `Final failing command/error line: ${failingCommand}` : undefined,
         stderrTail ? `Captured stderr tail:\n${stderrTail}` : undefined,
         `Captured output tail:\n${combinedTail}`,

package/dist/src/commands/re-export-bulk-scan.d.ts

@@ -0,0 +1,5 @@
+import type { PatchesManifest } from '../types/commands/index.js';
+/** Loads and validates a `re-export --scan-files` assignment manifest. */
+export declare function loadScanFilesAssignments(manifestPath: string, manifest: PatchesManifest): Promise<Map<string, string[]>>;
+/** Serializes dry-run re-export git inspection against the same project tree. */
+export declare function withDryRunReExportLock<T>(fireforgeDir: string, isDryRun: boolean, operation: () => Promise<T>): Promise<T>;

package/dist/src/commands/re-export-bulk-scan.js

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { createSiblingLockPath, withFileLock } from '../core/file-lock.js';
+import { resolvePatchIdentifier } from '../core/patch-manifest.js';
+import { InvalidArgumentError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { readText } from '../utils/fs.js';
+import { normalizeEngineRelativeInput } from './re-export-scan.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseScanFilesManifest(raw, manifestPath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new InvalidArgumentError(`--scan-files manifest is not valid JSON (${manifestPath}): ${toError(error).message}`, '--scan-files');
+    }
+    if (!isRecord(parsed) || !Array.isArray(parsed['assignments'])) {
+        throw new InvalidArgumentError('--scan-files manifest must contain an assignments array.', '--scan-files');
+    }
+    const assignments = [];
+    for (const [index, assignment] of parsed['assignments'].entries()) {
+        if (!isRecord(assignment)) {
+            throw new InvalidArgumentError(`--scan-files assignments[${index}] must be an object.`, '--scan-files');
+        }
+        const { patch, files } = assignment;
+        if (typeof patch !== 'string' || patch.trim().length === 0) {
+            throw new InvalidArgumentError(`--scan-files assignments[${index}].patch must be a non-empty string.`, '--scan-files');
+        }
+        if (!Array.isArray(files) ||
+            files.length === 0 ||
+            !files.every((file) => typeof file === 'string')) {
+            throw new InvalidArgumentError(`--scan-files assignments[${index}].files must be a non-empty string array.`, '--scan-files');
+        }
+        assignments.push({ patch, files });
+    }
+    if (assignments.length === 0) {
+        throw new InvalidArgumentError('--scan-files manifest must assign at least one file.', '--scan-files');
+    }
+    return { assignments };
+}
+/** Loads and validates a `re-export --scan-files` assignment manifest. */
+export async function loadScanFilesAssignments(manifestPath, manifest) {
+    const parsed = parseScanFilesManifest(await readText(manifestPath), manifestPath);
+    const filesByPatch = new Map();
+    const ownerByFile = new Map();
+    for (const assignment of parsed.assignments) {
+        const patch = resolvePatchIdentifier(assignment.patch, manifest.patches);
+        if (!patch) {
+            const available = manifest.patches.map((entry) => entry.filename).join(', ');
+            throw new InvalidArgumentError(`--scan-files patch "${assignment.patch}" not found in manifest.\n\nAvailable patches: ${available}`, '--scan-files');
+        }
+        const patchFiles = filesByPatch.get(patch.filename) ?? new Set();
+        filesByPatch.set(patch.filename, patchFiles);
+        for (const rawFile of assignment.files) {
+            const file = normalizeEngineRelativeInput(rawFile, '--scan-files');
+            const previousOwner = ownerByFile.get(file);
+            if (previousOwner !== undefined && previousOwner !== patch.filename) {
+                throw new InvalidArgumentError(`--scan-files path is assigned to more than one patch: ${file} (${previousOwner}, ${patch.filename})`, '--scan-files');
+            }
+            ownerByFile.set(file, patch.filename);
+            patchFiles.add(file);
+        }
+    }
+    return new Map([...filesByPatch.entries()].map(([patchFilename, files]) => [patchFilename, [...files].sort()]));
+}
+/** Serializes dry-run re-export git inspection against the same project tree. */
+export async function withDryRunReExportLock(fireforgeDir, isDryRun, operation) {
+    if (!isDryRun)
+        return operation();
+    const lockPath = createSiblingLockPath(join(fireforgeDir, 're-export-dry-run'), '.lock');
+    return withFileLock(lockPath, operation, {
+        timeoutMs: 24 * 60 * 60 * 1000,
+        onTimeoutMessage: `Timed out waiting for the FireForge re-export dry-run lock at ${lockPath}. ` +
+            'If no other `fireforge re-export --dry-run` is running, remove the lock directory and retry.',
+        onStaleLockMessage: (ageMs) => `Removing stale FireForge re-export dry-run lock (age: ${Math.round(ageMs / 1000)}s). A previous dry-run process may have crashed.`,
+    });
+}
+//# sourceMappingURL=re-export-bulk-scan.js.map

package/dist/src/commands/re-export-options.d.ts

@@ -0,0 +1,3 @@
+import type { ReExportOptions } from '../types/commands/index.js';
+/** Validates mutually exclusive `re-export` targeting and metadata options. */
+export declare function validateReExportOptionCombinations(patches: readonly string[], options: ReExportOptions): void;

package/dist/src/commands/re-export-options.js

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { InvalidArgumentError } from '../errors/base.js';
+/** Validates mutually exclusive `re-export` targeting and metadata options. */
+export function validateReExportOptionCombinations(patches, options) {
+    if (options.files !== undefined) {
+        if (options.all || options.scan) {
+            throw new InvalidArgumentError('--files cannot be combined with --scan or --all.', '--files');
+        }
+        if (options.scanFilesManifest !== undefined) {
+            throw new InvalidArgumentError('--files cannot be combined with --scan-files.', '--files');
+        }
+        if (patches.length !== 1) {
+            throw new InvalidArgumentError('--files operates on exactly one target patch. Pass a single patch identifier.', '--files');
+        }
+    }
+    if (options.scanFiles !== undefined) {
+        if (!options.scan)
+            throw new InvalidArgumentError('--scan-file requires --scan.', '--scan-file');
+        if (options.scanFilesManifest !== undefined) {
+            throw new InvalidArgumentError('--scan-file cannot be combined with --scan-files.', '--scan-file');
+        }
+        if (options.all || patches.length !== 1) {
+            throw new InvalidArgumentError('--scan-file operates on exactly one target patch. Pass a single patch identifier.', '--scan-file');
+        }
+    }
+    if (options.scanFilesManifest !== undefined) {
+        if (!options.scan)
+            throw new InvalidArgumentError('--scan-files requires --scan.', '--scan-files');
+        if (options.all || patches.length > 0) {
+            throw new InvalidArgumentError('--scan-files selects patches from its manifest and cannot be combined with positional patches or --all.', '--scan-files');
+        }
+    }
+    const usingTierFlag = options.tier !== undefined;
+    const usingLintIgnoreFlag = options.lintIgnore !== undefined && options.lintIgnore.length > 0;
+    if (options.all && (usingTierFlag || usingLintIgnoreFlag)) {
+        throw new InvalidArgumentError('--tier and --lint-ignore require explicit patch identifiers and cannot be combined with --all (different patches typically need different metadata).', '--all');
+    }
+}
+//# sourceMappingURL=re-export-options.js.map

package/dist/src/commands/re-export-scan.d.ts

@@ -6,6 +6,8 @@ export interface ScanResult {
 }
 /** Normalizes repeatable `--scan-file` inputs into safe engine-relative paths. */
 export declare function normalizeScanFiles(scanFiles: readonly string[] | undefined): string[] | undefined;
+/** Normalizes one CLI-provided path into a safe engine-relative path. */
+export declare function normalizeEngineRelativeInput(rawPath: string, flagName: string): string;
 /** Scans either broad sibling directories or explicit `--scan-file` paths for re-export. */
 export declare function scanPatchFilesForReExport(args: {
     currentFilesAffected: string[];

package/dist/src/commands/re-export-scan.js

@@ -17,7 +17,8 @@ export function normalizeScanFiles(scanFiles) {
         .sort();
     return normalized.length > 0 ? normalized : undefined;
 }
-function normalizeEngineRelativeInput(rawPath, flagName) {
+/** Normalizes one CLI-provided path into a safe engine-relative path. */
+export function normalizeEngineRelativeInput(rawPath, flagName) {
     const normalized = normalizePathSlashes(stripEnginePrefix(rawPath).trim());
     if (normalized.length === 0) {
         throw new InvalidArgumentError(`${flagName} requires a non-empty engine-relative path.`, flagName);

package/dist/src/commands/re-export.js

@@ -16,7 +16,9 @@ import { pathExists } from '../utils/fs.js';
 import { cancel, info, intro, isCancel, outro, spinner, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { runPatchLint } from './export-shared.js';
+import { loadScanFilesAssignments, withDryRunReExportLock } from './re-export-bulk-scan.js';
 import { reExportFilesInPlace } from './re-export-files.js';
+import { validateReExportOptionCombinations } from './re-export-options.js';
 import { assertScanFileAdditionsHaveDiffHunks, confirmBroadScanAdditions, normalizeScanFiles, scanPatchFilesForReExport, } from './re-export-scan.js';
 async function findMissingFiles(engineDir, files) {
     const missingFiles = [];
@@ -277,33 +279,7 @@ export async function reExportCommand(projectRoot, patches, options) {
     }
     const isDryRun = options.dryRun === true;
     intro(isDryRun ? 'FireForge Re-export (dry run)' : 'FireForge Re-export');
-    // --files is mutually exclusive with --scan and --all: they select
-    // different scope contracts.
-    if (options.files !== undefined) {
-        if (options.all || options.scan) {
-            throw new InvalidArgumentError('--files cannot be combined with --scan or --all.', '--files');
-        }
-        if (patches.length !== 1) {
-            throw new InvalidArgumentError('--files operates on exactly one target patch. Pass a single patch identifier.', '--files');
-        }
-    }
-    if (options.scanFiles !== undefined) {
-        if (!options.scan) {
-            throw new InvalidArgumentError('--scan-file requires --scan.', '--scan-file');
-        }
-        if (options.all || patches.length !== 1) {
-            throw new InvalidArgumentError('--scan-file operates on exactly one target patch. Pass a single patch identifier.', '--scan-file');
-        }
-    }
-    // --tier and --lint-ignore are per-patch metadata edits; combining them
-    // with --all silently rewrites every patch's tier/ignore list, which is
-    // virtually always wrong (different patches have different shapes).
-    // Refuse the combination so the operator must enumerate the targets.
-    const usingTierFlag = options.tier !== undefined;
-    const usingLintIgnoreFlag = options.lintIgnore !== undefined && options.lintIgnore.length > 0;
-    if (options.all && (usingTierFlag || usingLintIgnoreFlag)) {
-        throw new InvalidArgumentError('--tier and --lint-ignore require explicit patch identifiers and cannot be combined with --all (different patches typically need different metadata).', '--all');
-    }
+    validateReExportOptionCombinations(patches, options);
     const paths = getProjectPaths(projectRoot);
     // Check if engine exists
     if (!(await pathExists(paths.engine))) {
@@ -318,8 +294,13 @@ export async function reExportCommand(projectRoot, patches, options) {
     if (!manifest || manifest.patches.length === 0) {
         throw new GeneralError('No patches found in manifest. Run "fireforge export" to create patches first.');
     }
+    const scanFilesByPatch = options.scanFilesManifest !== undefined
+        ? await loadScanFilesAssignments(options.scanFilesManifest, manifest)
+        : undefined;
     // Resolve which patches to re-export
-    const selectedPatches = await resolveSelectedPatches(patches, options, manifest);
+    const selectedPatches = scanFilesByPatch !== undefined
+        ? manifest.patches.filter((patch) => scanFilesByPatch.has(patch.filename))
+        : await resolveSelectedPatches(patches, options, manifest);
     if (!selectedPatches)
         return;
     if (selectedPatches.length === 0) {
@@ -327,6 +308,15 @@ export async function reExportCommand(projectRoot, patches, options) {
         outro('Nothing to re-export');
         return;
     }
+    if (scanFilesByPatch !== undefined) {
+        info(`Bulk scan assignments from ${options.scanFilesManifest}`);
+        for (const patch of selectedPatches) {
+            const files = scanFilesByPatch.get(patch.filename) ?? [];
+            info(`  ${patch.filename} <= ${files.length} file(s)`);
+            for (const file of files)
+                info(`    + ${file}`);
+        }
+    }
     // --files path: handled end-to-end here so we can lint the *projected*
     // shrunken state (not the current queue) and skip the generic re-export
     // loop. The projection substitutes the target patch's diff and newFiles
@@ -335,7 +325,7 @@ export async function reExportCommand(projectRoot, patches, options) {
     // we write anything.
     if (options.files !== undefined) {
         const filesConfig = await loadConfig(projectRoot);
-        await reExportFilesInPlace(paths, selectedPatches, options, filesConfig);
+        await withDryRunReExportLock(paths.fireforgeDir, isDryRun, () => reExportFilesInPlace(paths, selectedPatches, options, filesConfig));
         return;
     }
     const config = await loadConfig(projectRoot);
@@ -343,20 +333,24 @@ export async function reExportCommand(projectRoot, patches, options) {
     const reExportedFilenames = [];
     const progress = spinner('Preparing re-export...');
     const startedAt = Date.now();
-    for (const [index, patch] of selectedPatches.entries()) {
-        progress.message(`Re-exporting ${index + 1}/${selectedPatches.length}: ${patch.filename} (${patch.filesAffected.length} file(s), ${elapsedSince(startedAt)} elapsed)...`);
-        try {
-            const exported = await reExportSinglePatch(patch, paths, manifest, options, isDryRun, config);
-            if (exported) {
-                reExported++;
-                reExportedFilenames.push(patch.filename);
+    await withDryRunReExportLock(paths.fireforgeDir, isDryRun, async () => {
+        for (const [index, patch] of selectedPatches.entries()) {
+            const assignedScanFiles = scanFilesByPatch?.get(patch.filename);
+            const patchOptions = assignedScanFiles !== undefined ? { ...options, scanFiles: assignedScanFiles } : options;
+            progress.message(`Re-exporting ${index + 1}/${selectedPatches.length}: ${patch.filename} (${patch.filesAffected.length} file(s), ${elapsedSince(startedAt)} elapsed)...`);
+            try {
+                const exported = await reExportSinglePatch(patch, paths, manifest, patchOptions, isDryRun, config);
+                if (exported) {
+                    reExported++;
+                    reExportedFilenames.push(patch.filename);
+                }
+            }
+            catch (error) {
+                warn(`Failed to re-export ${patch.filename}`);
+                warn(toError(error).message);
             }
         }
-        catch (error) {
-            warn(`Failed to re-export ${patch.filename}`);
-            warn(toError(error).message);
-        }
-    }
+    });
     if (reExported === 0 && selectedPatches.length > 0) {
         progress.error('Re-export failed');
         throw new GeneralError('All selected patches failed to re-export. Check the errors above.');
@@ -402,6 +396,7 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .option('-a, --all', 'Re-export all patches')
         .option('-s, --scan', 'Scan directories for new/removed files and update filesAffected')
         .option('--scan-file <path>', 'With --scan, add this explicit engine-relative file to one target patch without collecting adjacent files. Repeatable.', (value, prev) => [...prev, value], [])
+        .option('--scan-files <manifest>', 'With --scan, bulk-assign generated files from a JSON manifest: {"assignments":[{"patch":"002-name.patch","files":["path"]}]}. Selects patches from the manifest.')
         .option('--files <paths>', 'Restrict the re-exported filesAffected to this comma-separated list (single target patch only)', (value) => value
         .split(',')
         .map((v) => v.trim())
@@ -415,10 +410,11 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .addOption(new Option('--tier <tier>', 'Force a tier override on the selected patch (only "branding" recognised). Mutually exclusive with --all.').choices(['branding']))
         .option('--lint-ignore <check-id>', 'Append a lint check ID to the patch\'s PatchMetadata.lintIgnore (union, de-duped, repeatable). Mutually exclusive with --all. Use "fireforge patch lint-ignore" for --remove / --clear.', (value, prev) => [...prev, value], [])
         .action(withErrorHandling(async (patches, options) => {
-        const { tier, lintIgnore, scanFile, ...rest } = options;
+        const { tier, lintIgnore, scanFile, scanFiles, ...rest } = options;
         await reExportCommand(getProjectRoot(), patches, {
             ...pickDefined(rest),
             ...(scanFile !== undefined && scanFile.length > 0 ? { scanFiles: scanFile } : {}),
+            ...(scanFiles !== undefined ? { scanFilesManifest: scanFiles } : {}),
             ...(tier !== undefined ? { tier: tier } : {}),
             ...(lintIgnore !== undefined && lintIgnore.length > 0 ? { lintIgnore } : {}),
         });

package/dist/src/commands/test-appdir.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resolves and appends an xpcshell `--app-path=<abs>` argument when the
+ * selected manifest requests a browser appdir that rebranded forks otherwise
+ * fail to discover.
+ */
+export declare function maybeInjectAppdirArg(engineDir: string, normalizedPaths: readonly string[], objDir: string | undefined, extraArgs: string[]): Promise<boolean>;

package/dist/src/commands/test-appdir.js

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { operatorAlreadySetAppPath, resolveXpcshellAppdirArg, } from '../core/xpcshell-appdir.js';
+import { info, warn } from '../utils/logger.js';
+/**
+ * Resolves and appends an xpcshell `--app-path=<abs>` argument when the
+ * selected manifest requests a browser appdir that rebranded forks otherwise
+ * fail to discover.
+ */
+export async function maybeInjectAppdirArg(engineDir, normalizedPaths, objDir, extraArgs) {
+    if (!objDir)
+        return false;
+    if (operatorAlreadySetAppPath(extraArgs))
+        return false;
+    const outcome = await resolveXpcshellAppdirArg(engineDir, normalizedPaths, objDir);
+    switch (outcome.kind) {
+        case 'none':
+            return false;
+        case 'mismatch':
+            warn(`xpcshell appdir auto-injection skipped — multiple test paths resolved to different app dirs (${outcome.values.join(', ')}). Pass --mach-arg=--app-path=<abs> to disambiguate.`);
+            return false;
+        case 'unresolved':
+            warn(`xpcshell appdir auto-injection skipped — manifest at ${outcome.manifestPath} requests appdir "${outcome.relativeAppdir}" but no matching directory exists under ${objDir}/dist/. Build artifacts may be stale.`);
+            return false;
+        case 'injected':
+            extraArgs.push(`--app-path=${outcome.result.appPath}`);
+            info(`xpcshell appdir auto-injected: --app-path=${outcome.result.appPath} (from ${outcome.result.manifestPath} firefox-appdir=${outcome.result.relativeAppdir}).`);
+            return true;
+    }
+}
+//# sourceMappingURL=test-appdir.js.map

package/dist/src/commands/test.js

@@ -5,15 +5,17 @@ import { getProjectPaths, loadConfig } from '../core/config.js';
 import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, testWithOutput, withBuildLock, } from '../core/mach.js';
 import { assertMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
+import { buildHarnessEarlyExitMessage, classifyHarnessEarlyExit, } from '../core/test-harness-output.js';
 import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
 import { tryRepairStaleXpcshellTestSymlink } from '../core/test-stale-symlink.js';
-import { findNearestXpcshellManifest, operatorAlreadySetAppPath, resolveXpcshellAppdirArg, } from '../core/xpcshell-appdir.js';
+import { findNearestXpcshellManifest } from '../core/xpcshell-appdir.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { stripEnginePrefix } from '../utils/paths.js';
+import { maybeInjectAppdirArg } from './test-appdir.js';
 async function assertTestPathsExist(engineDir, testPaths) {
     const missingPaths = [];
     for (const testPath of testPaths) {
@@ -193,6 +195,10 @@ function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted
     if (/UNKNOWN TEST\b/i.test(combinedOutput)) {
         throw new GeneralError(buildUnknownTestMessage(normalizedPaths));
     }
+    const earlyExit = classifyHarnessEarlyExit(combinedOutput, normalizedPaths);
+    if (earlyExit) {
+        throw new GeneralError(buildHarnessEarlyExitMessage(earlyExit, normalizedPaths));
+    }
     // Fork-owned module load failures must beat the branding stale-build
     // branch: 2026-04-21 eval (Finding #14) saw a fork's test fail with
     // `Failed to load resource:///modules/mybrowser/MyBrowserStore.sys.mjs`
@@ -449,33 +455,6 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     }
     handleNonZeroTestExit(result, normalizedPaths, appdirInjection, projectConfig.binaryName);
 }
-/**
- * Resolves and (when applicable) appends an `--app-path=<abs>` arg to
- * `extraArgs`. Returns true iff the arg was injected. The logging branches
- * mirror the {@link XpcshellAppdirOutcome} variants so an operator can tell
- * from the test output whether FireForge tried to help and what it found.
- */
-async function maybeInjectAppdirArg(engineDir, normalizedPaths, objDir, extraArgs) {
-    if (!objDir)
-        return false;
-    if (operatorAlreadySetAppPath(extraArgs))
-        return false;
-    const outcome = await resolveXpcshellAppdirArg(engineDir, normalizedPaths, objDir);
-    switch (outcome.kind) {
-        case 'none':
-            return false;
-        case 'mismatch':
-            warn(`xpcshell appdir auto-injection skipped — multiple test paths resolved to different app dirs (${outcome.values.join(', ')}). Pass --mach-arg=--app-path=<abs> to disambiguate.`);
-            return false;
-        case 'unresolved':
-            warn(`xpcshell appdir auto-injection skipped — manifest at ${outcome.manifestPath} requests appdir "${outcome.relativeAppdir}" but no matching directory exists under ${objDir}/dist/. Build artifacts may be stale.`);
-            return false;
-        case 'injected':
-            extraArgs.push(`--app-path=${outcome.result.appPath}`);
-            info(`xpcshell appdir auto-injected: --app-path=${outcome.result.appPath} (from ${outcome.result.manifestPath} firefox-appdir=${outcome.result.relativeAppdir}).`);
-            return true;
-    }
-}
 /** Registers the test command on the CLI program. */
 export function registerTest(program, { getProjectRoot, withErrorHandling }) {
     program

package/dist/src/core/firefox-ignorefile.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Result of normalizing Firefox's Mercurial ignore file for Git-backed
+ * checkouts.
+ */
+export type FirefoxIgnorefileCompatibilityResult = 'created' | 'existing' | 'skipped';
+/**
+ * Ensures Firefox's mozlint ignorefile configuration can be parsed in
+ * Git-backed source trees.
+ *
+ * Firefox's `tools/lint/ignorefile.yml` includes both `.gitignore` and
+ * `.hgignore`. Source archives and some Git mirrors may omit `.hgignore`,
+ * which makes `mach lint --fix <files>` fail before it reaches the scoped
+ * linter. For FireForge-managed Git checkouts, copying `.gitignore` gives
+ * mozlint the missing include and keeps the ignorefile linter's pattern
+ * comparison equivalent without patching upstream lint configuration.
+ */
+export declare function ensureFirefoxIgnorefileCompatibility(engineDir: string): Promise<FirefoxIgnorefileCompatibilityResult>;

package/dist/src/core/firefox-ignorefile.js

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { pathExists, readText, writeText } from '../utils/fs.js';
+/**
+ * Ensures Firefox's mozlint ignorefile configuration can be parsed in
+ * Git-backed source trees.
+ *
+ * Firefox's `tools/lint/ignorefile.yml` includes both `.gitignore` and
+ * `.hgignore`. Source archives and some Git mirrors may omit `.hgignore`,
+ * which makes `mach lint --fix <files>` fail before it reaches the scoped
+ * linter. For FireForge-managed Git checkouts, copying `.gitignore` gives
+ * mozlint the missing include and keeps the ignorefile linter's pattern
+ * comparison equivalent without patching upstream lint configuration.
+ */
+export async function ensureFirefoxIgnorefileCompatibility(engineDir) {
+    const lintConfigPath = join(engineDir, 'tools', 'lint', 'ignorefile.yml');
+    if (!(await pathExists(lintConfigPath))) {
+        return 'skipped';
+    }
+    const hgignorePath = join(engineDir, '.hgignore');
+    if (await pathExists(hgignorePath)) {
+        return 'existing';
+    }
+    const gitignorePath = join(engineDir, '.gitignore');
+    if (!(await pathExists(gitignorePath))) {
+        return 'skipped';
+    }
+    await writeText(hgignorePath, await readText(gitignorePath));
+    return 'created';
+}
+//# sourceMappingURL=firefox-ignorefile.js.map

package/dist/src/core/git.js

@@ -7,6 +7,7 @@ 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 { ensureFirefoxIgnorefileCompatibility } from './firefox-ignorefile.js';
 import { configureGitPerformance, ensureGit, git, GIT_ADD_CHUNK_TIMEOUT_ENV_VAR, 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 ──
@@ -291,6 +292,8 @@ export async function initRepository(dir, branchName = 'main', options = {}) {
     reportProgress('Configuring origin remote for build compatibility...');
     await git(['remote', 'add', 'origin', 'https://github.com/mozilla-firefox/firefox'], dir);
     reportProgress('Git phase complete: source git repository metadata initialized.');
+    reportProgress('Normalizing Firefox ignore files for Git-backed mach lint compatibility...');
+    await ensureFirefoxIgnorefileCompatibility(dir);
     // Add all files
     reportProgress('Indexing Firefox source with git add -A (this can take several minutes on large trees)...');
     await assertNoGitIndexLock(dir);
@@ -327,6 +330,8 @@ export async function resumeRepository(dir, options = {}) {
     await cleanupIndexLock(dir);
     // Ensure origin remote exists (may have been added before the interrupt)
     await ensureOriginRemote(dir);
+    reportProgress('Normalizing Firefox ignore files for Git-backed mach lint compatibility...');
+    await ensureFirefoxIgnorefileCompatibility(dir);
     // Stage all files
     reportProgress('Indexing Firefox source (resuming)...');
     await assertNoGitIndexLock(dir);

package/dist/src/core/mach.js

@@ -5,6 +5,7 @@ import { pathExists } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
 import { exec, execInherit, execInheritCapture, execSmokeRun, execStream, } from '../utils/process.js';
 import { createSiblingLockPath, withFileLock } from './file-lock.js';
+import { ensureFirefoxIgnorefileCompatibility } from './firefox-ignorefile.js';
 import { explainMachError } from './mach-error-hints.js';
 import { getPython } from './mach-python.js';
 // Re-export sub-modules so existing `from './mach.js'` imports keep working.
@@ -32,6 +33,7 @@ export async function ensureMach(engineDir) {
 export async function runMach(args, engineDir, options = {}) {
     const python = await getPython(engineDir);
     await ensureMach(engineDir);
+    await ensureFirefoxIgnorefileCompatibility(engineDir);
     const machPath = join(engineDir, 'mach');
     const execOptions = {
         cwd: engineDir,
@@ -59,6 +61,7 @@ const CAPTURE_TAIL_LIMIT = 2 * 1024 * 1024;
 export async function runMachCapture(args, engineDir, options = {}) {
     const python = await getPython(engineDir);
     await ensureMach(engineDir);
+    await ensureFirefoxIgnorefileCompatibility(engineDir);
     const machPath = join(engineDir, 'mach');
     let stdout = '';
     let stderr = '';
@@ -89,6 +92,7 @@ export async function runMachCapture(args, engineDir, options = {}) {
 export async function runMachInheritCapture(args, engineDir, options = {}) {
     const python = await getPython(engineDir);
     await ensureMach(engineDir);
+    await ensureFirefoxIgnorefileCompatibility(engineDir);
     const machPath = join(engineDir, 'mach');
     return execInheritCapture(python, [machPath, ...args], {
         cwd: engineDir,
@@ -237,6 +241,7 @@ export async function run(engineDir, args = []) {
 export async function runMachSmoke(args, engineDir, options) {
     const python = await getPython(engineDir);
     await ensureMach(engineDir);
+    await ensureFirefoxIgnorefileCompatibility(engineDir);
     const machPath = join(engineDir, 'mach');
     return execSmokeRun(python, [machPath, ...args], {
         cwd: engineDir,

package/dist/src/core/patch-artifact-normalize.d.ts

@@ -1,9 +1,10 @@
 /**
  * Normalizes generated patch files before they are written to disk.
  *
- * Kept as a narrow chokepoint for future artifact-level fixes. It must not
- * rewrite hunk body lines: unified diffs encode a blank context line as a
- * physical line containing the leading context marker (`" "`), and FireForge's
- * verifier relies on that marker when replaying patch output.
+ * Kept as a narrow chokepoint for future artifact-level fixes. It must keep
+ * unified-diff hunk markers intact, but marker-only blank payload lines should
+ * not carry extra trailing whitespace (`"+ "` / `"- "` / `"  "`), because raw
+ * repository whitespace checks flag those generated patch artifact lines even
+ * when the engine diff is clean.
  */
 export declare function normalizePatchArtifact(content: string): string;

package/dist/src/core/patch-artifact-normalize.js

@@ -2,12 +2,21 @@
 /**
  * Normalizes generated patch files before they are written to disk.
  *
- * Kept as a narrow chokepoint for future artifact-level fixes. It must not
- * rewrite hunk body lines: unified diffs encode a blank context line as a
- * physical line containing the leading context marker (`" "`), and FireForge's
- * verifier relies on that marker when replaying patch output.
+ * Kept as a narrow chokepoint for future artifact-level fixes. It must keep
+ * unified-diff hunk markers intact, but marker-only blank payload lines should
+ * not carry extra trailing whitespace (`"+ "` / `"- "` / `"  "`), because raw
+ * repository whitespace checks flag those generated patch artifact lines even
+ * when the engine diff is clean.
  */
 export function normalizePatchArtifact(content) {
-    return content;
+    return content
+        .split('\n')
+        .map((line) => {
+        if (/^[ +-]\s+$/.test(line)) {
+            return line[0] ?? line;
+        }
+        return line;
+    })
+        .join('\n');
 }
 //# sourceMappingURL=patch-artifact-normalize.js.map

package/dist/src/core/test-harness-output.d.ts

@@ -0,0 +1,9 @@
+export type HarnessEarlyExitKind = 'startup' | 'zero-tests';
+export interface HarnessEarlyExit {
+    kind: HarnessEarlyExitKind;
+    line: string;
+}
+/** Classifies mach output where no requested test actually began running. */
+export declare function classifyHarnessEarlyExit(output: string, normalizedPaths: readonly string[]): HarnessEarlyExit | undefined;
+/** Builds the user-facing message for a harness startup or zero-run failure. */
+export declare function buildHarnessEarlyExitMessage(earlyExit: HarnessEarlyExit, normalizedPaths: readonly string[]): string;

package/dist/src/core/test-harness-output.js

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: EUPL-1.2
+function getNonEmptyOutputLines(output) {
+    return output
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+function findFirstMatchingLine(lines, patterns) {
+    return lines.find((line) => patterns.some((pattern) => pattern.test(line)));
+}
+/** Classifies mach output where no requested test actually began running. */
+export function classifyHarnessEarlyExit(output, normalizedPaths) {
+    const lines = getNonEmptyOutputLines(output);
+    const startupLine = findFirstMatchingLine(lines, [
+        /HominisBrowserUnavailableError/i,
+        /Marionette.*(?:session|startup|start).*fail/i,
+        /(?:failed|unable) to (?:start|create|open).*Marionette/i,
+        /SessionNotCreatedException/i,
+        /Browser process exited during spawn/i,
+    ]);
+    if (startupLine) {
+        return { kind: 'startup', line: startupLine };
+    }
+    if (normalizedPaths.length === 0)
+        return undefined;
+    const zeroTestsLine = findFirstMatchingLine(lines, [
+        /\bRan 0 tests?\b/i,
+        /\b0 tests? ran\b/i,
+        /\b0 tests? selected\b/i,
+        /\b0 subtests\b/i,
+        /\bno tests (?:were )?(?:run|ran|selected|collected|found)\b/i,
+    ]);
+    if (zeroTestsLine) {
+        return { kind: 'zero-tests', line: zeroTestsLine };
+    }
+    return undefined;
+}
+/** Builds the user-facing message for a harness startup or zero-run failure. */
+export function buildHarnessEarlyExitMessage(earlyExit, normalizedPaths) {
+    const reason = earlyExit.kind === 'startup'
+        ? 'The test harness failed during browser/session startup before the selected tests began.'
+        : 'The test harness exited after reporting that zero selected tests ran.';
+    const paths = normalizedPaths.length > 0 ? normalizedPaths.join(', ') : '(all tests)';
+    return (`mach test did not run the selected tests.\n\n` +
+        `${reason}\n\n` +
+        `Actionable harness line: ${earlyExit.line}\n\n` +
+        `Requested paths: ${paths}\n\n` +
+        'Fix the harness startup/discovery issue above before interpreting this as a test failure.');
+}
+//# sourceMappingURL=test-harness-output.js.map

package/dist/src/types/commands/options.d.ts

@@ -183,6 +183,13 @@ export interface ReExportOptions {
      * Requires `--scan` and exactly one target patch.
      */
     scanFiles?: string[];
+    /**
+     * Path to a JSON manifest containing bulk scan assignments:
+     * `{ "assignments": [{ "patch": "<patch>", "files": ["path"] }] }`.
+     * Requires `--scan`; mutually exclusive with positional patches, `--all`,
+     * `--scan-file`, and `--files`.
+     */
+    scanFilesManifest?: string;
     /**
      * Restrict the re-exported patch's filesAffected to this explicit list.
      * Files currently in the patch but not in this list are dropped (shrink);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.28.1",
+  "version": "0.28.5",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",