@hominis/fireforge 0.18.0 → 0.18.2

package/dist/src/commands/verify.js

@@ -14,19 +14,74 @@
  * Exits non-zero when any error-severity finding is reported so CI can
  * treat the output as pass/fail.
  */
+import { join } from 'node:path';
 import { getProjectPaths } from '../core/config.js';
 import { buildPatchQueueContext, lintPatchQueue } from '../core/patch-lint.js';
 import { loadPatchesManifest, validatePatchesManifestConsistency } from '../core/patch-manifest.js';
+import { collectPatchRegistrationReferences } from '../core/patch-registration-refs.js';
 import { GeneralError } from '../errors/base.js';
-import { pathExists } from '../utils/fs.js';
+import { pathExists, readText } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
 /**
- * Reports duplicate `filesAffected` entries across patches — the manifest
- * consistency check only flags per-patch duplicates and orphan files, not
- * the case where two different patches claim the same path. `verify`
- * surfaces that here so it can be caught before `export`, `re-export`, or
- * `rebase` hit it.
+ * Walks each patch body in the manifest, extracts the set of
+ * component-shaped registration references it adds (widget paths
+ * implied by jar.mn + customElements.js; FTL paths implied by locale
+ * jar.mn), and confirms every reference is either created by some
+ * patch in the queue OR present as a tracked file in engine/. Any
+ * unreachable reference is a dangling-registration error — the patch
+ * registers a file that nothing in the world supplies, which fails at
+ * install time.
  */
+async function detectDanglingRegistrations(patchesDir, engineDir, patches) {
+    // Aggregate the set of all paths that any patch in the queue is
+    // responsible for (per `filesAffected`). We deliberately do NOT parse
+    // individual patch bodies for new-file creations here: `filesAffected`
+    // is already the contract manifest callers rely on, and
+    // `validatePatchesManifestConsistency` has already ensured the two
+    // are in sync. Using that list keeps this validator fast.
+    const coveredByPatches = new Set();
+    for (const patch of patches) {
+        for (const file of patch.filesAffected) {
+            coveredByPatches.add(file);
+        }
+    }
+    const issues = [];
+    for (const patch of patches) {
+        const patchPath = join(patchesDir, patch.filename);
+        if (!(await pathExists(patchPath)))
+            continue;
+        let body;
+        try {
+            body = await readText(patchPath);
+        }
+        catch {
+            // Bad file read is surfaced by the manifest consistency check
+            // already — skipping here avoids double-reporting the same issue.
+            continue;
+        }
+        const refs = collectPatchRegistrationReferences(body);
+        if (refs.length === 0)
+            continue;
+        for (const ref of refs) {
+            if (coveredByPatches.has(ref.targetPath))
+                continue;
+            // Engine existence check: if the target file is already present
+            // in engine/ (e.g. upstream Firefox ships it, or a separate
+            // baseline branch has it), the registration is not dangling.
+            // We cannot sanely probe "is this tracked by git" without a git
+            // round-trip; existence on disk is a close-enough proxy for
+            // verify's read-only context.
+            if (await pathExists(join(engineDir, ref.targetPath)))
+                continue;
+            issues.push({
+                patchFilename: patch.filename,
+                targetPath: ref.targetPath,
+                source: ref.source,
+            });
+        }
+    }
+    return issues;
+}
 function detectCrossPatchFileClaims(manifestPatches) {
     const claims = new Map();
     for (const patch of manifestPatches) {
@@ -97,6 +152,26 @@ export async function verifyCommand(projectRoot) {
                 warningCount += 1;
         }
     }
+    // 4. Registration-consequence consistency: walk each patch body and
+    // confirm that every widget / locale registration it adds has a
+    // corresponding file body covered by the patch queue OR present in
+    // the engine working tree. 2026-04-24 eval Finding 1: a patch
+    // produced by `export-all --exclude-furnace` referenced
+    // `toolkit/content/widgets/moz-qa-panel/*.mjs` via jar.mn /
+    // customElements.js edits, but the source files themselves were
+    // excluded from the patch. `verify` used to report "clean"; it now
+    // flags each dangling reference as a `dangling-registration` error
+    // naming the specific patch and target path.
+    if (manifest) {
+        const registrationIssues = await detectDanglingRegistrations(paths.patches, paths.engine, manifest.patches);
+        if (registrationIssues.length > 0) {
+            warn(`Dangling registration references (${registrationIssues.length}):`);
+            for (const issue of registrationIssues) {
+                warn(`  ${issue.patchFilename}: registers ${issue.targetPath} via ${issue.source}, but no patch body or engine file supplies it`);
+                errorCount += 1;
+            }
+        }
+    }
     if (errorCount === 0 && warningCount === 0) {
         success('Patch queue is consistent.');
         outro('Verify clean');

package/dist/src/commands/watch.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { delimiter, dirname } from 'node:path';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
 import { buildArtifactMismatchMessage, generateMozconfig, hasBuildArtifacts, hasRunnableBundle, watchWithOutput, } from '../core/mach.js';
@@ -5,8 +7,8 @@ import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
-import { info, intro, outro, spinner } from '../utils/logger.js';
-import { exec, executableExists } from '../utils/process.js';
+import { info, intro, outro, spinner, verbose } from '../utils/logger.js';
+import { exec, findExecutable } from '../utils/process.js';
 const WATCHMAN_PROBE_TIMEOUT_MS = 5000;
 /**
  * Probes watchman by running `watchman --version`. A binary that exists
@@ -55,14 +57,21 @@ function buildWatchmanConfigureTimeMessage() {
 /**
  * Builds the generic unsupported-watch failure message.
  * @param exitCode - Exit code returned by `mach watch`
+ * @param watchmanPath - Optional absolute path to the resolved watchman binary; surfaced in the guidance so the operator can see whether FireForge actually found one.
  * @returns User-facing failure guidance
  */
-function buildUnsupportedWatchMessage(exitCode) {
+function buildUnsupportedWatchMessage(exitCode, watchmanPath) {
+    const watchmanLine = watchmanPath
+        ? `  - FireForge resolved watchman at ${watchmanPath} and prepended its directory to the mach subprocess PATH. If mach still did not see it, ensure that path is stable between runs.\n`
+        : '';
     return (`Watch failed with exit code ${exitCode}. Check the output above for details.\n\n` +
         'Common causes:\n' +
         '  - watchman is not installed or not in PATH right now\n' +
         '  - watchman was installed only after the current obj-* directory was configured; delete obj-* and rebuild\n' +
-        '  - mach watch is unsupported in the current objdir or build environment');
+        '  - mach watch is unsupported in the current objdir or build environment\n' +
+        watchmanLine +
+        '\n' +
+        'If the failure referenced `watch-project` / `FasterBuildException: timed out`, watchman is likely reachable via `which watchman` from your shell but missing from the subprocess PATH. FireForge now prepends the resolved watchman directory automatically; confirm your watchman install is on a stable path (e.g. /opt/homebrew/bin/watchman on macOS).');
 }
 /**
  * Detects the Firefox-side output produced when watchman was missing at configure time.
@@ -86,7 +95,17 @@ export async function watchCommand(projectRoot) {
     if (!(await pathExists(paths.engine))) {
         throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
     }
-    if (!(await executableExists('watchman'))) {
+    // Resolve the watchman binary to an absolute path up-front so we can
+    // (a) refuse fast when it is missing AND (b) prepend its directory to
+    // the mach subprocess PATH. 2026-04-24 eval Finding 12: on macOS,
+    // `which watchman` from the interactive shell returns
+    // `/opt/homebrew/bin/watchman`, but the Node subprocess PATH
+    // frequently omits `/opt/homebrew/bin`, so the shell probe passed and
+    // mach's `watch-project` call then timed out because its own PATH
+    // lookup for watchman failed. Threading the directory through the
+    // subprocess env fixes it.
+    const watchmanPath = await findExecutable('watchman');
+    if (!watchmanPath) {
         throw new GeneralError('Watch mode requires watchman to be installed and available in PATH.\n\n' +
             'Install watchman first, then rerun "fireforge watch".');
     }
@@ -145,9 +164,26 @@ export async function watchCommand(projectRoot) {
     }
     info('Starting watch mode...');
     info('Press Ctrl+C to stop\n');
+    // Compose the subprocess env: start from the parent process env, then
+    // prepend the resolved watchman directory to PATH so the mach
+    // subprocess sees the same binary our probe just validated. Without
+    // this, a watchman install on `/opt/homebrew/bin` (the default
+    // homebrew prefix on Apple Silicon) is absent from the PATH Node
+    // inherits on spawn, and `mach watch` fails at the `watch-project`
+    // subscription step.
+    const watchmanDir = dirname(watchmanPath);
+    const existingPath = process.env['PATH'] ?? '';
+    const pathSegments = existingPath.split(delimiter).filter((segment) => segment.length > 0);
+    const watchmanEnv = pathSegments.includes(watchmanDir)
+        ? { ...process.env }
+        : {
+            ...process.env,
+            PATH: [watchmanDir, ...pathSegments].join(delimiter),
+        };
+    verbose(`watch: resolved watchman at ${watchmanPath}; forwarding directory in subprocess PATH.`);
     let result;
     try {
-        result = await watchWithOutput(paths.engine);
+        result = await watchWithOutput(paths.engine, { env: watchmanEnv });
     }
     catch (error) {
         throw new BuildError('Watch process failed to start', 'mach watch', error instanceof Error ? error : undefined);
@@ -158,7 +194,7 @@ export async function watchCommand(projectRoot) {
             throw new GeneralError(buildWatchmanConfigureTimeMessage());
         }
         // 130 is SIGINT (Ctrl+C), which is expected
-        throw new BuildError(buildUnsupportedWatchMessage(result.exitCode), 'mach watch');
+        throw new BuildError(buildUnsupportedWatchMessage(result.exitCode, watchmanPath), 'mach watch');
     }
     outro('Watch mode stopped');
 }

package/dist/src/core/furnace-constants.d.ts

@@ -4,6 +4,20 @@ export declare const CUSTOM_ELEMENTS_JS = "toolkit/content/customElements.js";
 export declare const JAR_MN = "toolkit/content/jar.mn";
 /** Default Fluent localization directory for toolkit global components, relative to engine root */
 export declare const FTL_DIR = "toolkit/locales/en-US/toolkit/global";
+/**
+ * Suffix for the per-binary xpcshell scaffold parent directory. Components
+ * created with `furnace create --with-tests --xpcshell` land at
+ * `browser/base/content/test/<binaryName>${XPCSHELL_TEST_DIR_SUFFIX}/<component>/`.
+ * Centralised so `create` / `remove` / `rename` / `validate` all agree on
+ * the path template (2026-04-24 eval Finding 5).
+ */
+export declare const XPCSHELL_TEST_DIR_SUFFIX = "-xpcshell";
+/**
+ * Returns the engine-relative directory that holds xpcshell scaffolds for
+ * a given binary. Matches the form `create-xpcshell.ts` writes and the
+ * path `remove.ts` / `rename.ts` / `validate.ts` must clean up.
+ */
+export declare function xpcshellTestParentDir(binaryName: string): string;
 /** File extensions that constitute a Furnace component's source files. */
 export declare const COMPONENT_FILE_EXTENSIONS: readonly [".mjs", ".css", ".ftl"];
 /** Returns true when `fileName` has one of the standard component file extensions. */

package/dist/src/core/furnace-constants.js

@@ -5,6 +5,22 @@ export const CUSTOM_ELEMENTS_JS = 'toolkit/content/customElements.js';
 export const JAR_MN = 'toolkit/content/jar.mn';
 /** Default Fluent localization directory for toolkit global components, relative to engine root */
 export const FTL_DIR = 'toolkit/locales/en-US/toolkit/global';
+/**
+ * Suffix for the per-binary xpcshell scaffold parent directory. Components
+ * created with `furnace create --with-tests --xpcshell` land at
+ * `browser/base/content/test/<binaryName>${XPCSHELL_TEST_DIR_SUFFIX}/<component>/`.
+ * Centralised so `create` / `remove` / `rename` / `validate` all agree on
+ * the path template (2026-04-24 eval Finding 5).
+ */
+export const XPCSHELL_TEST_DIR_SUFFIX = '-xpcshell';
+/**
+ * Returns the engine-relative directory that holds xpcshell scaffolds for
+ * a given binary. Matches the form `create-xpcshell.ts` writes and the
+ * path `remove.ts` / `rename.ts` / `validate.ts` must clean up.
+ */
+export function xpcshellTestParentDir(binaryName) {
+    return `browser/base/content/test/${binaryName}${XPCSHELL_TEST_DIR_SUFFIX}`;
+}
 /** File extensions that constitute a Furnace component's source files. */
 export const COMPONENT_FILE_EXTENSIONS = ['.mjs', '.css', '.ftl'];
 /** Returns true when `fileName` has one of the standard component file extensions. */

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

@@ -1,8 +1,10 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { pathExists } from '../utils/fs.js';
-import { loadConfig } from './config.js';
+import { getProjectPaths, loadConfig } from './config.js';
 import { getFurnacePaths, loadFurnaceConfig } from './furnace-config.js';
+import { xpcshellTestParentDir } from './furnace-constants.js';
 import { detectComposesCycles, validateComposesReferences } from './furnace-graph-utils.js';
 import { validateAccessibility, validateCompatibility, validateJarMnEntries, validateRegistrationPatterns, validateStructure, validateTokenLink, } from './furnace-validate-checks.js';
 import { findOverrideBaseVersionDrift, } from './furnace-version-drift.js';
@@ -175,6 +177,70 @@ export async function validateAllComponents(root) {
         existing.push(issue);
         results.set(issue.component, existing);
     }
+    // 2026-04-24 eval Finding 5: orphan xpcshell scaffold detection.
+    // `furnace create --with-tests --xpcshell` scaffolds a test directory
+    // at `browser/base/content/test/<binary>-xpcshell/<name>/`, and prior
+    // `furnace remove` + `furnace rename` flows did not touch that tree.
+    // A leftover scaffold whose `<name>` is not in furnace.json is almost
+    // always the aftermath of one of those incomplete flows; flag it as
+    // an `orphan-xpcshell-scaffold` error so operators know to delete or
+    // re-create the scaffold instead of discovering the mismatch only at
+    // test run time. Missing engine or missing scaffold parent directory
+    // both degrade silently — this check never introduces noise on a
+    // project that never used xpcshell scaffolding.
+    try {
+        const orphanIssues = await findOrphanXpcshellScaffolds(root, config);
+        for (const issue of orphanIssues) {
+            const existing = results.get(issue.component) ?? [];
+            existing.push(issue);
+            results.set(issue.component, existing);
+        }
+    }
+    catch {
+        // Validation degrades gracefully — the absence of an engine
+        // directory, permission denial reading the scaffold tree, or any
+        // other transient fs issue should never cascade into false
+        // "orphan" reports.
+    }
     return results;
 }
+/**
+ * Scans the per-binary xpcshell scaffold directory for entries whose
+ * component name is not present in furnace.json, and returns an
+ * `orphan-xpcshell-scaffold` issue for each one.
+ */
+async function findOrphanXpcshellScaffolds(root, config) {
+    const forgeConfig = await loadConfig(root);
+    const paths = getProjectPaths(root);
+    const parentRel = xpcshellTestParentDir(forgeConfig.binaryName);
+    const parentAbs = join(paths.engine, parentRel);
+    if (!(await pathExists(parentAbs)))
+        return [];
+    let entries;
+    try {
+        const dirents = await readdir(parentAbs, { withFileTypes: true });
+        entries = dirents.filter((d) => d.isDirectory()).map((d) => d.name);
+    }
+    catch {
+        return [];
+    }
+    const known = new Set([
+        ...Object.keys(config.custom),
+        ...Object.keys(config.overrides),
+        ...config.stock,
+    ]);
+    const issues = [];
+    for (const entry of entries) {
+        if (known.has(entry))
+            continue;
+        issues.push({
+            component: entry,
+            severity: 'error',
+            check: 'orphan-xpcshell-scaffold',
+            message: `Stale xpcshell test scaffold at ${parentRel}/${entry}/ — no matching component is declared in furnace.json. ` +
+                'Delete the scaffold directory manually, or re-run `fireforge furnace create --with-tests --xpcshell` for an existing component with the same name.',
+        });
+    }
+    return issues;
+}
 //# sourceMappingURL=furnace-validate.js.map

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

@@ -1,6 +1,31 @@
-/** Default timeout for `git add -A` on large trees (10 minutes). */
+/**
+ * Environment variable that overrides the monolithic `git add -A` timeout
+ * (milliseconds). 2026-04-24 eval Finding 10: operators on slow or loaded
+ * filesystems legitimately exceeded the 10-minute default during a
+ * 140.10.0esr baseline indexing pass; making the cap overridable lets
+ * them retry without recompiling.
+ */
+export declare const GIT_ADD_TIMEOUT_ENV_VAR = "FIREFORGE_GIT_ADD_TIMEOUT_MS";
+/**
+ * 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 declare const GIT_ADD_CHUNK_TIMEOUT_ENV_VAR = "FIREFORGE_GIT_ADD_CHUNK_TIMEOUT_MS";
+/**
+ * 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 declare const GIT_ADD_TIMEOUT_MS: number;
-/** Timeout for chunked `git add` per top-level directory (20 minutes). */
+/**
+ * Resolved timeout for each chunk of the chunked fallback path. Grew
+ * from 20 to 30 minutes in 0.18.1 because the fallback is already the
+ * last line of defence before aborting — erring on the side of "complete
+ * the indexing" over "fail fast" matches the real-world recovery
+ * workflow.
+ */
 export declare const GIT_ADD_CHUNK_TIMEOUT_MS: number;
 /**
  * Structured git status entry derived from `git status --porcelain=v1 -z`.

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

@@ -1,10 +1,48 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { GitError, GitNotFoundError } from '../errors/git.js';
 import { exec, executableExists } from '../utils/process.js';
+/**
+ * Environment variable that overrides the monolithic `git add -A` timeout
+ * (milliseconds). 2026-04-24 eval Finding 10: operators on slow or loaded
+ * filesystems legitimately exceeded the 10-minute default during a
+ * 140.10.0esr 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). */
-export const GIT_ADD_TIMEOUT_MS = 10 * 60_000;
-/** Timeout for chunked `git add` per top-level directory (20 minutes). */
-export const GIT_ADD_CHUNK_TIMEOUT_MS = 20 * 60_000;
+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. Grew
+ * from 20 to 30 minutes in 0.18.1 because the fallback is already the
+ * last line of defence before aborting — erring on the side of "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);
 /**
  * Ensures git is available in the system.
  * @throws GitNotFoundError if git is not installed

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

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, join } from 'node:path';
 import { GitError } from '../errors/git.js';
@@ -35,6 +35,16 @@ export async function getFileDiff(repoDir, filePath) {
  */
 export async function generateNewFileDiff(repoDir, filePath) {
     const fullPath = join(repoDir, filePath);
+    // Defensive check: a directory here means a caller bypassed the
+    // expansion layers and handed the leaf reader a path it cannot
+    // read. Surface it with an actionable message naming the offending
+    // path rather than the raw `EISDIR` that `readText` would throw —
+    // recurring bug class (see the belt-and-suspenders note in
+    // `getDiffForFilesAgainstHead`).
+    const fileStat = await stat(fullPath);
+    if (fileStat.isDirectory()) {
+        throw new GitError(`expected a file but found a directory at '${filePath}' — caller must expand directory entries before diffing`, `hash-object ${filePath}`);
+    }
     const content = await readText(fullPath);
     // Compute the abbreviated git blob hash for the index line
     let blobHash = '0000000000';
@@ -212,7 +222,29 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
             }
             continue;
         }
-        if (!(await pathExists(join(repoDir, file)))) {
+        const fullPath = join(repoDir, file);
+        if (!(await pathExists(fullPath))) {
+            continue;
+        }
+        // Second defence against the EISDIR regression: a non-HEAD path
+        // that exists on disk is usually a new file, but can also be a
+        // directory that arrived without the trailing slash
+        // `expandUntrackedDirectoryEntries` would have produced (caller
+        // stripped it, submodule entry, tracked-file-replaced-by-dir).
+        // Expand it via the same helper used by the slash branch and
+        // recurse so each contained file is diffed individually; fail
+        // loud when the directory has no readable content rather than
+        // silently skipping it.
+        const fileStat = await stat(fullPath);
+        if (fileStat.isDirectory()) {
+            const innerFiles = await getUntrackedFilesInDir(repoDir, file);
+            if (innerFiles.length === 0) {
+                throw new GitError(`'${file}' is a directory with no untracked content (submodule or gitignored?) — cannot diff as a file`, `ls-files --others -- ${file}`);
+            }
+            const innerDiff = await getDiffForFilesAgainstHead(repoDir, innerFiles);
+            if (innerDiff.trim()) {
+                diffs.push(innerDiff);
+            }
             continue;
         }
         const diff = await generateNewFileDiff(repoDir, file);

package/dist/src/core/git.js

@@ -1,12 +1,12 @@
 // 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 { GitError, GitIndexingTimeoutError, 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 { 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 ──
 /**
@@ -38,12 +38,22 @@ export async function ensureOriginRemote(dir) {
 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).
+ * (SIGTERM → exit code 143) OR an AbortError raised by
+ * `AbortSignal.timeout`. The AbortSignal path is the one observed during
+ * the 2026-04-24 eval (Finding 10): Node's `child_process` layer
+ * rejects with an AbortError when the signal fires, so the timeout
+ * detection here needs to recognise that shape too.
  */
 function isTimeoutError(error) {
+    if (error instanceof Error && error.name === 'AbortError')
+        return true;
     if (!(error instanceof GitError))
         return false;
-    return /SIGTERM|timed out|exit code 143/i.test(error.message);
+    if (/SIGTERM|timed out|exit code 143/i.test(error.message))
+        return true;
+    if (error.cause instanceof Error && error.cause.name === 'AbortError')
+        return true;
+    return false;
 }
 /**
  * Removes `.git/index.lock` left behind by a killed git process.
@@ -59,6 +69,12 @@ async function cleanupIndexLock(dir) {
  * 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.
+ *
+ * 2026-04-24 eval Finding 10: a chunked pass that hits its own timeout
+ * now raises a typed {@link GitIndexingTimeoutError} rather than the
+ * opaque `AbortError: The operation was aborted` the caller otherwise
+ * saw. The typed error carries the environment-variable override so the
+ * operator can extend the budget and re-run.
  */
 async function stageAllFilesChunked(dir, options = {}) {
     const entries = await readdir(dir, { withFileTypes: true });
@@ -66,21 +82,30 @@ async function stageAllFilesChunked(dir, options = {}) {
         .filter((e) => e.isDirectory() && e.name !== '.git')
         .map((e) => e.name)
         .sort();
+    async function runChunk(args, label) {
+        try {
+            await git(args, dir, {
+                timeout: GIT_ADD_CHUNK_TIMEOUT_MS,
+                env: GIT_ADD_ENV,
+            });
+        }
+        catch (error) {
+            if (isTimeoutError(error)) {
+                throw new GitIndexingTimeoutError('chunked', GIT_ADD_CHUNK_TIMEOUT_MS, GIT_ADD_CHUNK_TIMEOUT_ENV_VAR, error instanceof Error ? error : undefined);
+            }
+            verbose(`Chunked staging failed on ${label}: ${toError(error).message}`);
+            throw error;
+        }
+    }
     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,
-        });
+        await runChunk(['add', '--', dirName], dirName);
     }
     // 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,
-        });
+        await runChunk(['add', '--', ...topLevelFiles], 'top-level files');
     }
 }
 /**
@@ -122,11 +147,25 @@ export async function stageAllFiles(dir, options = {}) {
             if (!isTimeoutError(error)) {
                 throw await maybeWrapIndexLockError(dir, error);
             }
-            options.onProgress?.('Monolithic git add timed out; falling back to chunked staging...');
+            // 2026-04-24 eval Finding 10: the fallback transition used to be
+            // an implementation detail invisible to operators watching the
+            // spinner. Emit a loud, one-line banner so non-TTY log scrapers
+            // and TTY operators both see that the monolithic attempt lost and
+            // the chunked pass is starting. This was the missing signal in
+            // the eval log where the heartbeat went quiet for ~600s between
+            // the monolithic timeout and the chunked-pass failure.
+            options.onProgress?.(`Monolithic git add reached the ${Math.round(timeout / 1000)}s timeout; falling back to chunked staging. This pass may take several more minutes on a large tree.`);
         }
         // The killed process may have left an index lock
         await cleanupIndexLock(dir);
-        await stageAllFilesChunked(dir, options);
+        try {
+            await stageAllFilesChunked(dir, options);
+        }
+        catch (error) {
+            if (error instanceof GitIndexingTimeoutError)
+                throw error;
+            throw error;
+        }
     }
     finally {
         if (heartbeatTimer)

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

@@ -168,9 +168,21 @@ export declare function watch(engineDir: string): Promise<number>;
 /**
  * Runs mach watch while preserving stdin and capturing emitted output.
  * @param engineDir - Path to the engine directory
+ * @param options - Optional environment overrides merged into the mach subprocess env
  * @returns Captured output and exit code
- */
-export declare function watchWithOutput(engineDir: string): Promise<MachCommandResult>;
+ *
+ * 2026-04-24 eval Finding 12: the pre-0.18.1 shape accepted no options
+ * and so never forwarded the detected watchman path into the mach
+ * subprocess env. `fireforge watch` could locate `watchman` via PATH
+ * (the probe's `which` succeeded) but the mach subprocess spawned with
+ * the parent's PATH only — on macOS that typically omits
+ * `/opt/homebrew/bin`, so `mach watch` failed at the `watch-project`
+ * subscription step. Accepting `env` here lets the caller prepend the
+ * resolved watchman directory to PATH in a way mach inherits.
+ */
+export declare function watchWithOutput(engineDir: string, options?: {
+    env?: Record<string, string>;
+}): Promise<MachCommandResult>;
 /**
  * Runs mach test with the given test paths.
  * @param engineDir - Path to the engine directory

package/dist/src/core/mach.js

@@ -280,10 +280,20 @@ export async function watch(engineDir) {
 /**
  * Runs mach watch while preserving stdin and capturing emitted output.
  * @param engineDir - Path to the engine directory
+ * @param options - Optional environment overrides merged into the mach subprocess env
  * @returns Captured output and exit code
+ *
+ * 2026-04-24 eval Finding 12: the pre-0.18.1 shape accepted no options
+ * and so never forwarded the detected watchman path into the mach
+ * subprocess env. `fireforge watch` could locate `watchman` via PATH
+ * (the probe's `which` succeeded) but the mach subprocess spawned with
+ * the parent's PATH only — on macOS that typically omits
+ * `/opt/homebrew/bin`, so `mach watch` failed at the `watch-project`
+ * subscription step. Accepting `env` here lets the caller prepend the
+ * resolved watchman directory to PATH in a way mach inherits.
  */
-export async function watchWithOutput(engineDir) {
-    return runMachInheritCapture(['watch'], engineDir);
+export async function watchWithOutput(engineDir, options = {}) {
+    return runMachInheritCapture(['watch'], engineDir, options.env ? { env: options.env } : {});
 }
 /**
  * Runs mach test with the given test paths.