@hominis/fireforge 0.16.5 → 0.18.0

package/dist/src/core/config.js

@@ -8,11 +8,13 @@
  *   config-mutate.ts   — immutable config mutation
  *   config-state.ts    — state file management
  */
+import { basename } from 'node:path';
 import { ConfigError, ConfigNotFoundError } from '../errors/config.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { getProjectPaths } from './config-paths.js';
 import { validateConfig } from './config-validate.js';
+import { createSiblingLockPath, withFileLock } from './file-lock.js';
 // ---- re-exports ----
 export { mutateConfig } from './config-mutate.js';
 export { CONFIG_FILENAME, CONFIGS_DIR, ENGINE_DIR, FIREFORGE_DIR, getProjectPaths, PATCHES_DIR, SRC_DIR, STATE_FILENAME, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
@@ -97,9 +99,50 @@ export async function writeConfig(root, config) {
  * Writes a raw config document to fireforge.json.
  * This is used by CLI `config --force`, where callers may intentionally write
  * keys or value shapes outside the validated FireForgeConfig schema.
+ *
+ * Individual writes are atomic via {@link writeJson} (temp file + rename),
+ * but atomicity alone does not prevent lost updates across concurrent
+ * writers: each writer reads an old copy, mutates its own in-memory view,
+ * and writes it back, so the second writer's rename clobbers the first
+ * writer's changes. Callers that do read → mutate → write must hold
+ * {@link withConfigFileLock} for the full round-trip to serialise
+ * against other writers.
  */
 export async function writeConfigDocument(root, config) {
     const paths = getProjectPaths(root);
     await writeJson(paths.config, config);
 }
+/**
+ * Runs an operation while holding a sidecar lock on `fireforge.json`.
+ *
+ * Motivating case (2026-04-21 eval): two concurrent `fireforge config
+ * <key> <value>` invocations each ran load → mutate → writeJson against
+ * the same on-disk fireforge.json. The second rename landed after the
+ * first, silently dropping the first writer's key — both commands exited
+ * `0`, but only one change survived. This helper turns the same
+ * read-modify-write sequence into a serialised operation so a concurrent
+ * writer now waits for the lock rather than racing on the document.
+ *
+ * Reads (`loadConfig`, `loadRawConfigDocument`) stay lock-free: writers
+ * always use `writeJson`'s atomic temp-file + rename, so a reader observes
+ * either the pre- or post-write document but never a torn file. The lock
+ * only serialises writers against other writers.
+ *
+ * The lock is a sidecar directory `${config}.fireforge-config.lock`, and
+ * `withFileLock` handles stale-lock recovery (PID-alive probe, age-based
+ * fallback) — a crashed writer does not permanently block future writes.
+ *
+ * @param root - Root directory of the project
+ * @param operation - Async function to run while holding the lock
+ * @returns Whatever the operation returns
+ */
+export async function withConfigFileLock(root, operation) {
+    const paths = getProjectPaths(root);
+    return withFileLock(createSiblingLockPath(paths.config, '.fireforge-config.lock'), operation, {
+        onTimeoutMessage: `Timed out waiting to update ${basename(paths.config)}. ` +
+            'If no other fireforge process is running, remove the stale lock directory and retry.',
+        onStaleLockMessage: (ageMs) => `Removing stale FireForge config lock for ${basename(paths.config)} ` +
+            `(age: ${Math.round(ageMs / 1000)}s). A previous fireforge process may have crashed.`,
+    });
+}
 //# sourceMappingURL=config.js.map

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

@@ -111,9 +111,30 @@ export declare function writeFurnaceConfig(root: string, config: FurnaceConfig):
 export declare function stampFurnaceOverrideBaseVersions(root: string, version: string): Promise<number>;
 /**
  * Creates a default furnace configuration.
- * @returns A valid empty FurnaceConfig
+ *
+ * When a `binaryName` is provided, the default config carries a
+ * `tokenPrefix` derived as `--<binaryName>-`. Without that default,
+ * `fireforge token coverage` on a fresh project reports `0 tokens` and
+ * labels every custom-property reference as `unknown` — the scan has
+ * no prefix to key off. The 2026-04-21 eval walked directly into this
+ * state (`furnace init` → `token add` → `token coverage` → zero
+ * tokens), and only recovered after hand-editing furnace.json. Deriving
+ * the prefix from the binary name matches the convention the scaffolded
+ * tokens CSS already uses for its `--<binaryName>-*` declarations.
+ *
+ * `validateFurnaceConfig` treats `tokenPrefix` as optional, so callers
+ * on the legacy no-arg call shape (existing tests, programmatic callers
+ * bootstrapping from a not-yet-loaded config) still get a valid config
+ * without a prefix; the CLI init path always has a `binaryName` from
+ * `fireforge.json` and always sets one.
+ *
+ * @param options - Optional init context; pass `{ binaryName }` to
+ *   derive the token prefix.
+ * @returns A valid FurnaceConfig
  */
-export declare function createDefaultFurnaceConfig(): FurnaceConfig;
+export declare function createDefaultFurnaceConfig(options?: {
+    binaryName?: string;
+}): FurnaceConfig;
 /**
  * Loads furnace config if it exists, or creates and writes a default config.
  * @param root - Root directory of the project

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

@@ -460,16 +460,39 @@ export async function stampFurnaceOverrideBaseVersions(root, version) {
 }
 /**
  * Creates a default furnace configuration.
- * @returns A valid empty FurnaceConfig
+ *
+ * When a `binaryName` is provided, the default config carries a
+ * `tokenPrefix` derived as `--<binaryName>-`. Without that default,
+ * `fireforge token coverage` on a fresh project reports `0 tokens` and
+ * labels every custom-property reference as `unknown` — the scan has
+ * no prefix to key off. The 2026-04-21 eval walked directly into this
+ * state (`furnace init` → `token add` → `token coverage` → zero
+ * tokens), and only recovered after hand-editing furnace.json. Deriving
+ * the prefix from the binary name matches the convention the scaffolded
+ * tokens CSS already uses for its `--<binaryName>-*` declarations.
+ *
+ * `validateFurnaceConfig` treats `tokenPrefix` as optional, so callers
+ * on the legacy no-arg call shape (existing tests, programmatic callers
+ * bootstrapping from a not-yet-loaded config) still get a valid config
+ * without a prefix; the CLI init path always has a `binaryName` from
+ * `fireforge.json` and always sets one.
+ *
+ * @param options - Optional init context; pass `{ binaryName }` to
+ *   derive the token prefix.
+ * @returns A valid FurnaceConfig
  */
-export function createDefaultFurnaceConfig() {
-    return {
+export function createDefaultFurnaceConfig(options = {}) {
+    const config = {
         version: 1,
         componentPrefix: 'moz-',
         stock: [],
         overrides: {},
         custom: {},
     };
+    if (options.binaryName && options.binaryName.length > 0) {
+        config.tokenPrefix = `--${options.binaryName}-`;
+    }
+    return config;
 }
 /**
  * Loads furnace config if it exists, or creates and writes a default config.

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

@@ -9,7 +9,7 @@ import { verbose } from '../utils/logger.js';
 import { exec } from '../utils/process.js';
 import { ensureGit, git } from './git-base.js';
 import { fileExistsInHead } from './git-file-ops.js';
-import { getUntrackedFiles } from './git-status.js';
+import { getUntrackedFiles, getUntrackedFilesInDir } from './git-status.js';
 async function execGitWithAllowedExitCodes(repoDir, args, allowedExitCodes = [0]) {
     const result = await exec('git', args, { cwd: repoDir });
     if (allowedExitCodes.includes(result.exitCode)) {
@@ -183,7 +183,26 @@ export async function getAllDiff(repoDir) {
  */
 export async function getDiffForFilesAgainstHead(repoDir, files) {
     await ensureGit();
-    const uniqueFiles = [...new Set(files)].sort();
+    // Expand any directory entries (paths ending with `/`) into their
+    // individual untracked files before diffing. `git status --porcelain=v1`
+    // reports collapsed untracked directories as `?? dir/`, and every caller
+    // that feeds the aggregate working-tree state into this function must
+    // not trigger an EISDIR when the diff pass reads `dir/` as if it were a
+    // file. Belt-and-suspenders: the caller-side expansion in `lint.ts`
+    // and `export-all.ts` covers the common path, but a single bad call
+    // site re-introduced the bug in 0.17.0 — guarding here makes the
+    // regression impossible at this layer.
+    const expandedFiles = [];
+    for (const file of files) {
+        if (file.endsWith('/')) {
+            const inner = await getUntrackedFilesInDir(repoDir, file);
+            for (const entry of inner)
+                expandedFiles.push(entry);
+            continue;
+        }
+        expandedFiles.push(file);
+    }
+    const uniqueFiles = [...new Set(expandedFiles)].sort();
     const diffs = [];
     for (const file of uniqueFiles) {
         if (await fileExistsInHead(repoDir, file)) {

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

@@ -60,19 +60,56 @@ export declare function bootstrapWithOutput(engineDir: string): Promise<MachComm
 /**
  * Runs a full mach build. On a non-zero exit, any matched error hints are
  * surfaced on top of the raw mach output so operators get an actionable
- * nudge alongside the cryptic mozbuild traceback.
+ * nudge alongside the cryptic mozbuild traceback. Returns the captured
+ * result so the caller (e.g. `fireforge build`) can inspect the tail
+ * for post-build diagnostics that mach prints AFTER "Your build was
+ * successful!" — notably the stale `config.status is out of date`
+ * notice that mach emits when a tool-managed edit landed on
+ * `moz.configure` before the build.
  * @param engineDir - Path to the engine directory
  * @param jobs - Number of parallel jobs (optional)
- * @returns Exit code
+ * @returns Captured mach result (stdout tail, stderr tail, exit code)
  */
-export declare function build(engineDir: string, jobs?: number): Promise<number>;
+export declare function build(engineDir: string, jobs?: number): Promise<MachCommandResult>;
 /**
  * Runs a fast UI-only build. On a non-zero exit, any matched error hints are
- * surfaced on top of the raw mach output.
+ * surfaced on top of the raw mach output. See {@link build} for why the
+ * full captured result is returned rather than just the exit code.
  * @param engineDir - Path to the engine directory
- * @returns Exit code
+ * @returns Captured mach result
+ */
+export declare function buildUI(engineDir: string): Promise<MachCommandResult>;
+/**
+ * Runs an operation while holding a sidecar build lock keyed on the
+ * project root. Concurrent `fireforge build` / `fireforge build --ui`
+ * invocations against the same tree serialise instead of racing through
+ * the mach obj-dir.
+ *
+ * Motivating case (2026-04-21 eval): a `fireforge build --ui` run
+ * kicked off while a full `fireforge build` was still in flight against
+ * the same engine tree accepted the command and handed off to `mach
+ * build faster`, which failed almost immediately with `No rule to make
+ * target 'XUL'`. The real problem is that the first build had not yet
+ * materialised the full backend; the operator was left staring at a
+ * low-level make error with no link to the actual cause (a concurrent
+ * build in flight). The lock intercepts the second invocation before
+ * it touches mach, and the refusal message names the PID currently
+ * holding the lock so the operator can decide whether to wait or
+ * investigate a hung process.
+ *
+ * Stale-lock recovery: the lock stores the owner PID; a crashed build
+ * (SIGINT, SIGTERM, or a kernel kill) leaves the lock dir behind but
+ * not the owning process, and `withFileLock` removes the lock on the
+ * next attempt when `process.kill(pid, 0)` shows the owner is gone.
+ *
+ * The project-root variant is the right granularity: a single machine
+ * may have several FireForge projects side by side, and nothing says
+ * they cannot build in parallel. The lock serialises *within* one
+ * project, not across unrelated ones.
+ *
+ * Returns whatever the inner operation returns.
  */
-export declare function buildUI(engineDir: string): Promise<number>;
+export declare function withBuildLock<T>(projectRoot: string, operation: () => Promise<T>): Promise<T>;
 /**
  * Runs the built browser.
  * @param engineDir - Path to the engine directory

package/dist/src/core/mach.js

@@ -1,9 +1,10 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { MachNotFoundError } from '../errors/build.js';
 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 { explainMachError } from './mach-error-hints.js';
 import { getPython } from './mach-python.js';
 // Re-export sub-modules so existing `from './mach.js'` imports keep working.
@@ -136,10 +137,15 @@ function surfaceMachErrorHints(result) {
 /**
  * Runs a full mach build. On a non-zero exit, any matched error hints are
  * surfaced on top of the raw mach output so operators get an actionable
- * nudge alongside the cryptic mozbuild traceback.
+ * nudge alongside the cryptic mozbuild traceback. Returns the captured
+ * result so the caller (e.g. `fireforge build`) can inspect the tail
+ * for post-build diagnostics that mach prints AFTER "Your build was
+ * successful!" — notably the stale `config.status is out of date`
+ * notice that mach emits when a tool-managed edit landed on
+ * `moz.configure` before the build.
  * @param engineDir - Path to the engine directory
  * @param jobs - Number of parallel jobs (optional)
- * @returns Exit code
+ * @returns Captured mach result (stdout tail, stderr tail, exit code)
  */
 export async function build(engineDir, jobs) {
     const args = ['build'];
@@ -150,20 +156,64 @@ export async function build(engineDir, jobs) {
     if (result.exitCode !== 0) {
         surfaceMachErrorHints(result);
     }
-    return result.exitCode;
+    return result;
 }
 /**
  * Runs a fast UI-only build. On a non-zero exit, any matched error hints are
- * surfaced on top of the raw mach output.
+ * surfaced on top of the raw mach output. See {@link build} for why the
+ * full captured result is returned rather than just the exit code.
  * @param engineDir - Path to the engine directory
- * @returns Exit code
+ * @returns Captured mach result
  */
 export async function buildUI(engineDir) {
     const result = await runMachInheritCapture(['build', 'faster'], engineDir);
     if (result.exitCode !== 0) {
         surfaceMachErrorHints(result);
     }
-    return result.exitCode;
+    return result;
+}
+/**
+ * Runs an operation while holding a sidecar build lock keyed on the
+ * project root. Concurrent `fireforge build` / `fireforge build --ui`
+ * invocations against the same tree serialise instead of racing through
+ * the mach obj-dir.
+ *
+ * Motivating case (2026-04-21 eval): a `fireforge build --ui` run
+ * kicked off while a full `fireforge build` was still in flight against
+ * the same engine tree accepted the command and handed off to `mach
+ * build faster`, which failed almost immediately with `No rule to make
+ * target 'XUL'`. The real problem is that the first build had not yet
+ * materialised the full backend; the operator was left staring at a
+ * low-level make error with no link to the actual cause (a concurrent
+ * build in flight). The lock intercepts the second invocation before
+ * it touches mach, and the refusal message names the PID currently
+ * holding the lock so the operator can decide whether to wait or
+ * investigate a hung process.
+ *
+ * Stale-lock recovery: the lock stores the owner PID; a crashed build
+ * (SIGINT, SIGTERM, or a kernel kill) leaves the lock dir behind but
+ * not the owning process, and `withFileLock` removes the lock on the
+ * next attempt when `process.kill(pid, 0)` shows the owner is gone.
+ *
+ * The project-root variant is the right granularity: a single machine
+ * may have several FireForge projects side by side, and nothing says
+ * they cannot build in parallel. The lock serialises *within* one
+ * project, not across unrelated ones.
+ *
+ * Returns whatever the inner operation returns.
+ */
+export async function withBuildLock(projectRoot, operation) {
+    const lockPath = createSiblingLockPath(join(projectRoot, '.fireforge-build'), '.lock');
+    return withFileLock(lockPath, operation, {
+        // Default lock timeout is 30s; bump to 24h so a slow full build does
+        // not trip the timeout while the second invocation waits. A real
+        // operator will ^C long before 24h elapses; the ceiling is there
+        // purely so a forgotten lock cannot wedge the command forever.
+        timeoutMs: 24 * 60 * 60 * 1000,
+        onTimeoutMessage: `Timed out waiting for the FireForge build lock at ${lockPath}. ` +
+            'If no other `fireforge build` is running, remove the lock directory and retry.',
+        onStaleLockMessage: (ageMs) => `Removing stale FireForge build lock ${basename(lockPath)} (age: ${Math.round(ageMs / 1000)}s). A previous build process may have crashed.`,
+    });
 }
 /**
  * Runs the built browser.

package/dist/src/core/manifest-rules.js

@@ -24,7 +24,16 @@ export function getRules(binaryName) {
             // proposed a bogus jar.mn entry. The lookahead blocks the match so
             // `getUnregistrableAdvice` gets a chance to emit the correct
             // guidance for the `.inc.xhtml` case.
-            pattern: /^browser\/base\/content\/(?!.+\.inc\.xhtml$)(.+\.(?:js|mjs|xhtml|css))$/,
+            //
+            // Test implementation files under `browser/base/content/test/` are
+            // also excluded: they belong in the nearest `browser.toml` manifest,
+            // not in jar.mn. 2026-04-23 eval 2: `status --unmanaged` proposed
+            // `fireforge register browser/base/content/test/<dir>/browser_*.js`
+            // which would have clutter-registered a test file as browser
+            // chrome content. The negative lookahead routes those paths to
+            // `getUnregistrableAdvice`, which returns the correct
+            // browser.toml-centric guidance.
+            pattern: /^browser\/base\/content\/(?!.+\.inc\.xhtml$)(?!test\/)(.+\.(?:js|mjs|xhtml|css))$/,
             isRegistered: (engineDir, fileName) => isBrowserContentRegistered(engineDir, fileName),
             register: (engineDir, after, dryRun, fileName) => registerBrowserContent(engineDir, fileName, after, undefined, dryRun),
             extractArgs: (m) => [m[1] ?? ''],

package/dist/src/core/manifest-tokenizers.d.ts

@@ -26,6 +26,12 @@ export declare function tokenizeJarMn(lines: string[]): JarMnToken[];
 /**
  * Tokenizes a moz.build Python list block, returning the tokens and their
  * line range within the file.
+ *
+ * Supports both multi-line lists (the common shape) and single-line
+ * empty lists of the form `EXTRA_JS_MODULES += []` — the eval-2 finding
+ * case where a freshly-scaffolded module directory's `moz.build`
+ * started with an empty list and the tokenizer returned `null`,
+ * leaving `register` unable to add the first entry.
  */
 export declare function tokenizeMozBuildList(lines: string[], listPattern: RegExp): {
     tokens: MozBuildToken[];

package/dist/src/core/manifest-tokenizers.js

@@ -44,6 +44,12 @@ export function tokenizeJarMn(lines) {
 /**
  * Tokenizes a moz.build Python list block, returning the tokens and their
  * line range within the file.
+ *
+ * Supports both multi-line lists (the common shape) and single-line
+ * empty lists of the form `EXTRA_JS_MODULES += []` — the eval-2 finding
+ * case where a freshly-scaffolded module directory's `moz.build`
+ * started with an empty list and the tokenizer returned `null`,
+ * leaving `register` unable to add the first entry.
  */
 export function tokenizeMozBuildList(lines, listPattern) {
     const tokens = [];
@@ -53,6 +59,28 @@ export function tokenizeMozBuildList(lines, listPattern) {
         const raw = lines[i] ?? '';
         if (startLine === -1) {
             if (listPattern.test(raw)) {
+                // Single-line empty-list handling: a fresh scaffold sometimes
+                // writes `EXTRA_JS_MODULES += []` on one line. The pre-fix
+                // tokenizer returned `null` because it never saw a line
+                // starting with `]`, which stranded `register` with a "Could
+                // not find module list section" error against the documented
+                // browser/modules/<fork>/ scaffold (eval 2).
+                //
+                // The in-place split rewrites the single-line form into the
+                // canonical multi-line shape so the caller's
+                // `lines.splice(insertIndex, 0, entry)` lands inside the list
+                // body. The tokens are emitted to mirror the new structure.
+                const singleLineMatch = /^([^[]*\[)\s*\]\s*$/.exec(raw);
+                if (singleLineMatch) {
+                    const openPart = singleLineMatch[1] ?? '';
+                    lines[i] = openPart;
+                    lines.splice(i + 1, 0, ']');
+                    startLine = i;
+                    endLine = i + 1;
+                    tokens.push({ type: 'list-open', raw: openPart, lineIndex: i });
+                    tokens.push({ type: 'list-close', raw: ']', lineIndex: i + 1 });
+                    break;
+                }
                 startLine = i;
                 tokens.push({ type: 'list-open', raw, lineIndex: i });
             }

package/dist/src/core/marionette-port.d.ts

@@ -0,0 +1,50 @@
+/** Default Marionette control port set by `-marionette`. */
+export declare const DEFAULT_MARIONETTE_PORT = 2828;
+/**
+ * Information about a process holding the Marionette port.
+ */
+export interface MarionettePortHolder {
+    /** OS process ID. */
+    pid: number;
+    /** Process basename (e.g. `forgefresh`, `firefox`). */
+    command: string;
+    /**
+     * Full command line the holder was launched with, when the probe
+     * can recover it. `lsof` by itself only returns the basename, so
+     * POSIX callers see `command === commandLine`; Windows callers
+     * recover the full command line via `Get-Process`. Used to detect
+     * the `-marionette` flag, which positively identifies a stale
+     * browser rather than an unrelated listener.
+     */
+    commandLine: string;
+}
+/**
+ * Result of a Marionette port probe.
+ */
+export interface MarionettePortProbeResult {
+    /** True when something is listening on the probed port. */
+    inUse: boolean;
+    /** Details about the holder, when the probe recovered them. */
+    holder?: MarionettePortHolder;
+}
+/**
+ * Probes whether the Marionette port is currently bound by a
+ * listener. The probe is best-effort: missing tooling returns
+ * `{ inUse: false }` without failing.
+ *
+ * @param port - Port to probe (default {@link DEFAULT_MARIONETTE_PORT}).
+ */
+export declare function probeMarionettePort(port?: number): Promise<MarionettePortProbeResult>;
+/**
+ * Raises a targeted {@link GeneralError} when the Marionette port
+ * is held by a browser process; raises a softer warning-shaped
+ * error when the holder is unrelated (so the operator still sees
+ * a useful signal but can decide whether to wait it out).
+ *
+ * @param port - Port to probe (default {@link DEFAULT_MARIONETTE_PORT}).
+ * @param options - Extra context for the error message (the project's
+ *   `binaryName` is used to recognise fork-branded browser binaries).
+ */
+export declare function assertMarionettePortAvailable(port?: number, options?: {
+    binaryName?: string;
+}): Promise<void>;