@hominis/fireforge 0.43.0 → 0.44.0

package/dist/src/core/file-lock.js

@@ -10,14 +10,19 @@ const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
 const DEFAULT_LOCK_POLL_MS = 50;
 const DEFAULT_STALE_LOCK_MS = 5 * 60_000;
 /**
- * Minimum interval between stale-lock probes while a waiter polls. The probe
- * used to run exactly once per waiter: if the holder died *after* that single
- * probe, the waiter polled a permanently dead lock until `timeoutMs` — for
- * the build lock that meant up to 24 hours (see `withBuildLock` in mach.ts).
- * Re-probing on a small interval bounds that hang to seconds while keeping
- * the per-poll cost negligible (one stat + one small read every ~5 s).
+ * Minimum interval between stale-lock probes while a waiter polls. Probing
+ * exactly once per waiter means a holder that dies *after* that probe leaves
+ * the waiter polling a permanently dead lock until `timeoutMs` — up to 24
+ * hours for the build lock (see `withBuildLock` in mach.ts). Re-probing on a
+ * small interval bounds that to seconds while keeping the per-poll cost
+ * negligible: one stat plus one small read every ~5 s.
  */
 const STALE_REPROBE_INTERVAL_MS = 5_000;
+/**
+ * Default interval between wait probes (holder + queue) when a caller wants
+ * deadline extension but no progress line of its own.
+ */
+const WAIT_PROBE_INTERVAL_MS = 5_000;
 function sleep(ms) {
     return new Promise((resolve) => {
         setTimeout(resolve, ms);
@@ -41,9 +46,9 @@ export const LOCK_PID_FILE = 'pid';
  * missing or the PID does not parse as a finite integer (caller falls back
  * to the age-only staleness heuristic).
  *
- * File format note: external readers (`doctor-furnace.ts`, older FireForge
- * releases) do `parseInt(content.trim(), 10)`, which parses the leading
- * digits of a multi-line file — so adding the token line stays compatible.
+ * File format note: external readers do `parseInt(content.trim(), 10)`,
+ * which parses the leading digits of a multi-line file — so the token line
+ * stays compatible.
  */
 async function readLockOwner(lockPath) {
     try {
@@ -150,37 +155,34 @@ async function registerWaiter(lockPath, startedAt) {
     };
 }
 /**
- * Reads the contended lock's owner and reports wait progress to the caller's
- * `onWaitProgress` callback. Failure to read the owner degrades to
- * `holder: undefined` — progress reporting must never break the wait loop.
+ * Reads the contended lock's owner and queue in one go. One probe per cycle
+ * serves both the progress line and the deadline extension, so the two can
+ * never disagree about the position they saw. Failure to read the owner
+ * degrades to `holder: undefined` — a diagnostic must never break the wait
+ * loop.
  */
-async function reportWaitProgress(lockPath, waitedMs, timeoutMs, startedAt, onWaitProgress) {
+async function probeWaitState(lockPath, startedAt) {
     const owner = await readLockOwner(lockPath);
     const holder = owner.present
         ? { pid: owner.pid, alive: isProcessAlive(owner.pid), metadata: owner.metadata }
         : undefined;
-    onWaitProgress({
-        waitedMs,
-        timeoutMs,
-        holder,
-        queue: await readLockQueue(lockPath, startedAt),
-    });
+    return { holder, queue: await readLockQueue(lockPath, startedAt) };
 }
 /**
  * Reaps a lock directory believed to be stale, safely against concurrent
  * reapers and a concurrent legitimate re-acquisition.
  *
- * The naive stat → read-PID → `rm` sequence had a TOCTOU hole: two waiters
- * could both observe the dead owner, one would remove the stale dir and
- * `mkdir` its own lock, and the other's already-decided `rm` then deleted
- * the *fresh* lock — two processes inside the critical section at once.
+ * A naive stat → read-PID → `rm` sequence has a TOCTOU hole: two waiters
+ * both observe the dead owner, one removes the stale dir and `mkdir`s its
+ * own lock, and the other's already-decided `rm` then deletes the *fresh*
+ * lock — two processes inside the critical section at once.
  *
  * Rename-aside closes it: `rename()` is atomic, so exactly one reaper wins
- * ownership of the directory (the loser gets ENOENT and simply re-polls),
- * and nothing ever deletes the live path directly. After winning the rename
- * we re-read the owner from the renamed dir — if it is now a *live* process
- * (the lock was released and re-acquired between our staleness read and the
- * rename), we rename it back instead of reaping.
+ * ownership of the directory (the loser gets ENOENT and re-polls), and
+ * nothing ever deletes the live path directly. After winning the rename the
+ * owner is re-read from the renamed dir — if it is now a *live* process (the
+ * lock was released and re-acquired between the staleness read and the
+ * rename), it is renamed back instead of reaped.
  *
  * @returns true when the caller should immediately retry `mkdir` (the lock
  *   path is now free or was freed by someone else), false when the lock is
@@ -236,15 +238,12 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
     try {
         const lockStat = await stat(lockPath);
         const ageMs = Date.now() - lockStat.mtimeMs;
-        // Check PID FIRST, independent of age. Before this ordering change the
-        // function age-gated everything: a lock younger than `staleMs` (default
-        // 5 minutes) was never removed even when its PID file pointed at a
-        // process that had already exited. That's the exact situation an
-        // operator lands in after SIGINT'ing `furnace preview` — the signal
-        // handler calls `process.exit`, `withFileLock`'s release never runs,
-        // and the next command has to either wait 5 minutes for the staleness
-        // gate or manually remove the lock directory. With the PID-first check,
-        // an explicitly-dead owner unblocks immediately.
+        // Check PID FIRST, independent of age. Age-gating everything means a
+        // lock younger than `staleMs` (default 5 minutes) is never removed even
+        // when its PID file points at a process that has already exited — the
+        // situation after SIGINT'ing `furnace preview`, where the signal handler
+        // calls `process.exit` and `withFileLock`'s release never runs. With the
+        // PID-first check an explicitly-dead owner unblocks immediately.
         const owner = await readLockOwner(lockPath);
         if (owner.present) {
             if (!isProcessAlive(owner.pid)) {
@@ -276,16 +275,15 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
 }
 /**
  * Releases a lock previously acquired by this process, verifying ownership
- * first. The unconditional `finally { rm }` this replaces would remove
- * *whichever* lock directory was present — if a stale-lock reaper had (in a
- * pathological race) replaced our lock, we deleted the new owner's lock and
- * compounded the double-acquisition. When the PID file no longer names us,
- * warn and leave the directory alone.
+ * first. An unconditional `finally { rm }` would remove *whichever* lock
+ * directory is present — if a stale-lock reaper had (in a pathological race)
+ * replaced our lock, that deletes the new owner's lock and compounds the
+ * double-acquisition. When the PID file no longer names us, warn and leave
+ * the directory alone.
  *
  * `ownerFileWritten` is false when our own owner-file write failed at
- * acquisition (non-fatal there); ownership then cannot be verified and we
- * fall back to unconditional removal — identical to the historical behavior
- * and strictly better than leaking the lock.
+ * acquisition (non-fatal there); ownership then cannot be verified and the
+ * removal is unconditional, which is strictly better than leaking the lock.
  */
 async function releaseLock(lockPath, ownerToken, ownerFileWritten) {
     if (ownerFileWritten) {
@@ -299,31 +297,130 @@ async function releaseLock(lockPath, ownerToken, ownerFileWritten) {
     }
     await rm(lockPath, { recursive: true, force: true });
 }
+/**
+ * Removes a lock directory only if this process still owns it, for callers
+ * that hold no acquisition token.
+ *
+ * The ownership half of {@link releaseLock}, minus the token check — a
+ * signal-time sweeper knows which lock paths its own operations opened, but
+ * not the per-acquisition UUID those acquisitions minted. The PID check is
+ * still the one that matters: it stops the sweeper deleting a lock a
+ * DIFFERENT process acquired in the window between our operation dying and
+ * the sweep running.
+ *
+ * Never throws: callers are shutdown paths where a slow or failing I/O must
+ * not prevent the process from exiting. Returns whether the directory was
+ * removed so callers can log accurately.
+ *
+ * @param lockPath - Lock directory to remove
+ * @returns True when the lock was removed, false when it was left in place
+ */
+export async function releaseLockIfOwned(lockPath) {
+    try {
+        const owner = await readLockOwner(lockPath);
+        if (owner.present && owner.pid !== process.pid) {
+            return false;
+        }
+        await rm(lockPath, { recursive: true, force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Builds the contention refusal thrown when the wait budget expires.
  *
  * Typed as {@link LockContentionError} (a `FireForgeError`) so the CLI
  * boundary prints the refusal as one clean line instead of an "Unexpected
- * error" stack. Callers supplying `onTimeoutMessage` still get
- * the holder identification appended — the reason-first copy stays theirs,
- * the "who holds it" is ours.
+ * error" stack. Callers supplying `onTimeoutMessage` still get the holder
+ * identification appended — the reason-first copy stays theirs, the "who
+ * holds it" is ours.
  */
-async function buildLockTimeoutError(lockPath, onTimeoutMessage, cause) {
+async function buildLockTimeoutError(lockPath, onTimeoutMessage, cause, queue) {
     const owner = await readLockOwner(lockPath);
     const liveHolder = owner.present && isProcessAlive(owner.pid) ? owner : undefined;
     const details = liveHolder !== undefined && liveHolder.metadata.length > 0
         ? ` (${liveHolder.metadata.join(', ')})`
         : '';
+    const position = formatQueuePositionReached(queue);
     if (onTimeoutMessage !== undefined) {
         const identifiedHolder = liveHolder !== undefined
             ? ` The lock is held by PID ${String(liveHolder.pid)}${details}.`
             : '';
-        return new LockContentionError(`${onTimeoutMessage}${identifiedHolder}`, cause);
+        return new LockContentionError(`${onTimeoutMessage}${identifiedHolder}${position}`, cause);
     }
     const holderHint = liveHolder !== undefined
         ? ` It is held by running process ${String(liveHolder.pid)}${details} — wait for it to finish, or stop it and retry.`
         : ' If no other FireForge process is running, remove the lock directory and retry.';
-    return new LockContentionError(`Timed out waiting for file lock ${lockPath}.${holderHint}`, cause);
+    return new LockContentionError(`Timed out waiting for file lock ${lockPath}.${holderHint}${position}`, cause);
+}
+/**
+ * States the queue position the expired wait actually reached.
+ *
+ * Silence here is what made the worst outcome invisible: a wait that expires
+ * one position from the head has paid the whole budget for nothing, and the
+ * operator cannot tell that from a queue that never moved. Naming the
+ * position turns "raise the budget" into an informed decision instead of a
+ * guess. Omitted when no queue was observed — an empty registry is not
+ * evidence of an empty queue.
+ */
+function formatQueuePositionReached(queue) {
+    if (queue === undefined || queue.depth === 0)
+        return '';
+    if (queue.ahead === 0) {
+        return ` You were next in a queue of ${String(queue.depth)} when the wait expired — a larger --wait-lock would very likely have got a turn.`;
+    }
+    return ` You were still ${String(queue.ahead)} from the head of a queue of ${String(queue.depth)} when the wait expired; re-run with a larger --wait-lock.`;
+}
+/**
+ * Runs one wait probe: reads holder and queue, and reports progress when the
+ * caller asked for it. Split out of the wait loop so the loop stays a
+ * readable state machine.
+ */
+async function runWaitProbe(lockPath, startedAt, timeoutMs, options) {
+    const { holder, queue } = await probeWaitState(lockPath, startedAt);
+    options.onWaitProgress?.({
+        waitedMs: Date.now() - startedAt,
+        timeoutMs,
+        holder,
+        queue,
+    });
+    return { queue };
+}
+/**
+ * Lock directories this process currently holds.
+ *
+ * `withFileLock`'s `finally` never runs across a `process.exit`, so a
+ * SIGTERM'd command leaves its lock on disk. The next contender reclaims it
+ * immediately (the PID-first staleness check sees a dead owner), but in the
+ * window between, `fireforge status --lock` reports the lock held by a
+ * process that is not running — which is exactly the question an operator
+ * asks after a kill. The signal sweep closes that window.
+ *
+ * Paths only: the per-acquisition token lives in `withFileLock`'s frame and
+ * a sweeper cannot see it. {@link releaseLockIfOwned} checks the PID, which
+ * is the check that matters — it stops the sweep deleting a lock a
+ * DIFFERENT process acquired in the meantime.
+ */
+const heldLocks = new Set();
+/**
+ * Releases every lock this process still holds, for the signal path.
+ *
+ * Never throws and never rejects: a shutdown path must not be able to keep
+ * the process alive. Returns the paths actually removed so the caller can
+ * report accurately.
+ */
+export async function forceReleaseHeldLocksForSignal() {
+    const paths = [...heldLocks];
+    const removed = [];
+    for (const lockPath of paths) {
+        heldLocks.delete(lockPath);
+        if (await releaseLockIfOwned(lockPath)) {
+            removed.push(lockPath);
+        }
+    }
+    return removed;
 }
 /** Runs an async operation while holding a directory lock, with stale-lock recovery. */
 export async function withFileLock(lockPath, operation, options = {}) {
@@ -332,12 +429,24 @@ export async function withFileLock(lockPath, operation, options = {}) {
     const staleMs = options.staleMs ?? DEFAULT_STALE_LOCK_MS;
     const staleReprobeMs = options.staleReprobeMs ?? STALE_REPROBE_INTERVAL_MS;
     const startedAt = Date.now();
-    const deadline = startedAt + timeoutMs;
+    const extend = options.extendWhileAdvancing;
+    const hardDeadline = extend !== undefined ? startedAt + extend.maxWaitMs : undefined;
+    let deadline = startedAt + timeoutMs;
     let lastStaleProbeAt;
     let currentPollMs = pollMs;
-    let lastProgressAt = startedAt;
+    let lastProbeAt = startedAt;
+    /** Best (lowest) queue position seen so far; used to detect an advance. */
+    let bestAhead;
+    /** Last observed queue state, so the timeout refusal can name the position reached. */
+    let lastQueue;
     /** Set on first contention so an uncontended acquire costs nothing. */
     let deregisterWaiter;
+    // One cadence drives both the progress line and the deadline extension.
+    // Either feature alone is enough to want the probe; neither is worth a
+    // second timer.
+    const probeIntervalMs = options.waitProgressMs ?? WAIT_PROBE_INTERVAL_MS;
+    const probeWanted = (options.onWaitProgress !== undefined && options.waitProgressMs !== undefined) ||
+        extend !== undefined;
     await ensureDir(dirname(lockPath));
     try {
         for (;;) {
@@ -360,13 +469,39 @@ export async function withFileLock(lockPath, operation, options = {}) {
                     }
                 }
                 if (Date.now() >= deadline) {
-                    throw await buildLockTimeoutError(lockPath, options.onTimeoutMessage, error);
+                    throw await buildLockTimeoutError(lockPath, options.onTimeoutMessage, error, lastQueue);
                 }
-                if (options.onWaitProgress !== undefined &&
-                    options.waitProgressMs !== undefined &&
-                    Date.now() - lastProgressAt >= options.waitProgressMs) {
-                    lastProgressAt = Date.now();
-                    await reportWaitProgress(lockPath, Date.now() - startedAt, timeoutMs, startedAt, options.onWaitProgress);
+                if (probeWanted && Date.now() - lastProbeAt >= probeIntervalMs) {
+                    lastProbeAt = Date.now();
+                    // Report the budget that is CURRENTLY in force, not the one
+                    // originally requested: once an extension has been granted, the
+                    // requested figure is stale, and a progress line that keeps
+                    // quoting it reads as a timeout that does not fire.
+                    const probe = await runWaitProbe(lockPath, startedAt, deadline - startedAt, options);
+                    lastQueue = probe.queue;
+                    // An advance — someone ahead of us took their turn and finished —
+                    // buys a fresh budget, because the wait is working. Only a queue
+                    // that stops moving starves, which is the case the timeout is for.
+                    //
+                    // The FIRST observation is a seed, never an advance. `bestAhead`
+                    // used to start `undefined`, so the opening probe always satisfied
+                    // this test and handed out a free full budget: a `--wait-lock 300`
+                    // run outlived its 300 s even against a queue that never moved
+                    // once, which is exactly the "it does not reliably give up after N
+                    // seconds" a downstream fork reported.
+                    if (hardDeadline !== undefined) {
+                        if (bestAhead === undefined) {
+                            bestAhead = probe.queue.ahead;
+                        }
+                        else if (probe.queue.ahead < bestAhead) {
+                            bestAhead = probe.queue.ahead;
+                            deadline = Math.min(Date.now() + timeoutMs, hardDeadline);
+                            options.onWaitExtended?.({
+                                ahead: probe.queue.ahead,
+                                budgetMs: deadline - startedAt,
+                            });
+                        }
+                    }
                 }
                 await sleep(currentPollMs);
                 if (options.pollMaxMs !== undefined) {
@@ -396,10 +531,12 @@ export async function withFileLock(lockPath, operation, options = {}) {
         // Non-fatal: stale recovery falls back to age-only heuristic and release
         // falls back to unconditional removal.
     }
+    heldLocks.add(lockPath);
     try {
         return await operation();
     }
     finally {
+        heldLocks.delete(lockPath);
         await releaseLock(lockPath, ownerToken, ownerFileWritten);
     }
 }

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

@@ -4,7 +4,7 @@
  */
 import { createHash, randomUUID } from 'node:crypto';
 import { createReadStream } from 'node:fs';
-import { rename } from 'node:fs/promises';
+import { readdir, rename, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { ChecksumMismatchError } from '../errors/download.js';
@@ -108,7 +108,6 @@ async function validateCachedArchive(archive, cacheDir, expectedSha256) {
             return false;
         }
         if (metadata.contentLength !== undefined) {
-            const { stat } = await import('node:fs/promises');
             const archiveStats = await stat(tarballPath);
             if (archiveStats.size !== metadata.contentLength) {
                 return false;
@@ -213,7 +212,6 @@ export async function invalidateArchiveCache(archive, cacheDir) {
 async function removeArchivePartFiles(archive, cacheDir) {
     const partPrefix = `${archive.filename}.part`;
     try {
-        const { readdir } = await import('node:fs/promises');
         const entries = await readdir(cacheDir);
         await Promise.all(entries
             .filter((name) => name.startsWith(partPrefix))

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

@@ -5,7 +5,7 @@
 import { join } from 'node:path';
 import { ExtractionError } from '../errors/download.js';
 import { elapsedSince } from '../utils/elapsed.js';
-import { ensureDir, pathExists } from '../utils/fs.js';
+import { ensureDir, pathExists, readText } from '../utils/fs.js';
 import { exec, execStream, executableExists } from '../utils/process.js';
 /**
  * Returns true when an archive member path could land outside the
@@ -81,11 +81,8 @@ export function findUnsafeArchiveLink(verboseLines) {
  * so a date-shaped owner name could shift the column boundary and hide an
  * absolute member name from the check. Each listing pass costs one full
  * decompression, so the two run concurrently and overlap almost perfectly
- * (they are CPU-bound on separate cores). Measured on a real Firefox ESR
- * 140.9 source tarball (601 MB, bsdtar 3.5.3, macOS): -tf 21.7 s, -tvf
- * 22.1 s, both concurrent 22 s wall, extraction itself 58 s (file-creation
- * syscalls dominate it, not decompression) — so the preflight adds ~22 s
- * (~38%) to this one-time extraction step, versus ~44 s if run
+ * (CPU-bound on separate cores): on a 601 MB Firefox ESR source tarball the
+ * preflight adds ~22 s to a ~58 s extraction, versus ~44 s if run
  * sequentially.
  */
 /**
@@ -116,13 +113,13 @@ function createLineScanner(onLine) {
  * Runs one tar listing pass, streaming lines through `checkLine` and
  * returning the first unsafe finding (or null) plus the exit code.
  *
- * Streaming matters for safety, not just memory: the buffered `exec`
- * collector silently truncates at 50 MB, and a full Firefox `-tvf` listing
- * already sits in the 40–50 MB range — so the buffered implementation could
- * scan only the head of the listing while reporting the archive safe. A
- * crafted archive could exploit exactly that by padding benign entries
- * first and hiding a traversal name or absolute link target past the cap.
- * With per-line streaming EVERY entry is scanned, with bounded memory.
+ * Streaming matters for safety, not just memory: a buffered `exec` collector
+ * silently truncates at 50 MB, and a full Firefox `-tvf` listing already
+ * sits in the 40–50 MB range — so a buffered implementation scans only the
+ * head of the listing while reporting the archive safe. A crafted archive
+ * could exploit exactly that by padding benign entries first and hiding a
+ * traversal name or absolute link target past the cap. Per-line streaming
+ * scans EVERY entry with bounded memory.
  */
 async function runListingScan(archivePath, tarFlag, checkLine) {
     // LC_ALL=C keeps the -tvf column format stable for the link parse.
@@ -213,7 +210,6 @@ export async function getFirefoxVersion(engineDir) {
     if (!(await pathExists(versionPath))) {
         return undefined;
     }
-    const { readText } = await import('../utils/fs.js');
     const version = await readText(versionPath);
     return version.trim();
 }

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

@@ -27,11 +27,11 @@ export declare function getDownloadUrl(version: string, product?: FirefoxProduct
 export declare function getTarballFilename(version: string, product?: FirefoxProduct, candidate?: string): string;
 /**
  * Lifecycle phase reported by {@link downloadFirefoxSource}. The download
- * CLI command uses this to swap spinners between the bytes-on-the-wire
- * phase and the silent tar-xz decompression phase that follows — before
- * this, a single spinner stuck at "Downloading Firefox … 100%" covered
- * both phases, making the first-run setup look hung precisely when the
- * archive was already on disk and `tar` was the long pole.
+ * CLI command uses this to swap spinners between the bytes-on-the-wire phase
+ * and the silent tar-xz decompression phase that follows: a single spinner
+ * covering both sticks at "Downloading Firefox … 100%" and makes first-run
+ * setup look hung precisely when the archive is already on disk and `tar` is
+ * the long pole.
  */
 export type FirefoxSourcePhase = 'download' | 'extract';
 /** Callback fired at phase transitions during {@link downloadFirefoxSource}. */
@@ -59,6 +59,8 @@ export declare function sweepOrphanedEngineWorkDirs(destDir: string): Promise<st
  * @param onPhase - Optional callback fired when the function transitions
  *   between phases (`'download'` → `'extract'`). Fires exactly once per
  *   phase even if the cached archive path skips the wire entirely.
+ * @param expectedSha256 - Expected archive checksum; verified after download when supplied
+ * @param onPhaseProgress - Called with byte progress within the current phase
  * @param candidate - Optional release-candidate build directory (e.g.
  *   "build2") resolving the archive under `candidates/` instead of
  *   `releases/`.

package/dist/src/core/firefox.js

@@ -6,8 +6,8 @@
  * {@link downloadFirefoxSource} orchestrator.
  */
 import { randomUUID } from 'node:crypto';
-import { rename } from 'node:fs/promises';
-import { join } from 'node:path';
+import { readdir, rename } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
 import { getNodeErrorCode, toError } from '../utils/errors.js';
 import { ensureDir, removeDir } from '../utils/fs.js';
 import { resolveArchive } from './firefox-archive.js';
@@ -72,8 +72,6 @@ function isLikelyArchiveCorruptionError(error) {
  * @returns names of the directories that were removed
  */
 export async function sweepOrphanedEngineWorkDirs(destDir) {
-    const { readdir } = await import('node:fs/promises');
-    const { basename, dirname } = await import('node:path');
     const parent = dirname(destDir);
     const enginePrefixTmp = `${basename(destDir)}.tmp-`;
     const enginePrefixReplacement = `${basename(destDir)}.replacement-`;
@@ -105,6 +103,8 @@ export async function sweepOrphanedEngineWorkDirs(destDir) {
  * @param onPhase - Optional callback fired when the function transitions
  *   between phases (`'download'` → `'extract'`). Fires exactly once per
  *   phase even if the cached archive path skips the wire entirely.
+ * @param expectedSha256 - Expected archive checksum; verified after download when supplied
+ * @param onPhaseProgress - Called with byte progress within the current phase
  * @param candidate - Optional release-candidate build directory (e.g.
  *   "build2") resolving the archive under `candidates/` instead of
  *   `releases/`.
@@ -136,7 +136,6 @@ export async function downloadFirefoxSource(version, product, destDir, cacheDir,
     }
     // Firefox source extracts to a subdirectory (e.g., firefox-140.0/)
     // Find it dynamically since ESR versions may have different naming
-    const { readdir } = await import('node:fs/promises');
     const entries = await readdir(tempDir, { withFileTypes: true });
     const extractedSubdir = entries.find((entry) => entry.isDirectory() && entry.name.startsWith('firefox-'));
     if (extractedSubdir) {

package/dist/src/core/furnace-apply-dry-run.d.ts

@@ -3,14 +3,14 @@
  * `furnace-apply-helpers.ts` so the apply path and its dry-run mirror each
  * stay within the per-file line budget. Consumed only by that module.
  */
-import type { CustomComponentConfig, DryRunAction, StepError } from '../types/furnace.js';
+import type { ComponentApplyContext, CustomComponentConfig, DryRunAction, StepError } from '../types/furnace.js';
 interface DirectoryEntry {
     isFile(): boolean;
     isSymbolicLink?(): boolean;
     name: string;
 }
 /** Computes the planned dry-run actions (and pre-flight step errors) for a custom component. */
-export declare function buildCustomDryRunActions(name: string, componentDir: string, engineDir: string, config: CustomComponentConfig, targetDir: string, entries: DirectoryEntry[], ftlDir: string): Promise<{
+export declare function buildCustomDryRunActions(ctx: Pick<ComponentApplyContext, 'engineDir' | 'name' | 'componentDir' | 'ftlDir'>, config: CustomComponentConfig, targetDir: string, entries: DirectoryEntry[]): Promise<{
     actions: DryRunAction[];
     stepErrors: StepError[];
 }>;

package/dist/src/core/furnace-apply-dry-run.js

@@ -18,7 +18,8 @@ function isRegularFile(entry) {
     return true;
 }
 /** Computes the planned dry-run actions (and pre-flight step errors) for a custom component. */
-export async function buildCustomDryRunActions(name, componentDir, engineDir, config, targetDir, entries, ftlDir) {
+export async function buildCustomDryRunActions(ctx, config, targetDir, entries) {
+    const { engineDir, name, componentDir, ftlDir } = ctx;
     const actions = [];
     const stepErrors = [];
     for (const entry of entries) {
@@ -60,7 +61,7 @@ export async function buildCustomDryRunActions(name, componentDir, engineDir, co
     // A sharedFtl widget owns its strings via the shared bundle; surface the
     // removal of any dangling per-widget locale jar.mn entry so the dry-run
     // plan matches what apply will do (and explains the unblocked build).
-    const pruneAction = await describeSharedFtlPrune(engineDir, name, ftlDir, config);
+    const pruneAction = await describeSharedFtlPrune(ctx, config);
     if (pruneAction) {
         actions.push(pruneAction);
     }

package/dist/src/core/furnace-apply-ftl.d.ts

@@ -6,26 +6,24 @@
  * Every helper here degrades gracefully: if the locale jar.mn is missing or
  * the FTL tree is non-standard, apply logs an ADVISORY `stepError`
  * (`advisory: true`) rather than aborting the whole command. Advisory step
- * errors are reported as warnings and never trigger rollback — missing
- * jar.mn on a fork without a locale package should not block a working
- * `.mjs`/`.css` from shipping (the blocking/advisory split exists because
- * this contract used to be contradicted: any FTL step error rolled back
- * the whole apply).
+ * errors are reported as warnings and never trigger rollback — a missing
+ * jar.mn on a fork without a locale package must not block a working
+ * `.mjs`/`.css` from shipping.
  */
-import type { CustomComponentConfig, DryRunAction, StepError } from '../types/furnace.js';
+import type { ComponentApplyContext, CustomComponentConfig, DryRunAction, StepError } from '../types/furnace.js';
 import { type RollbackJournal } from './furnace-rollback.js';
 /**
  * Apply-path wrapper around {@link pruneSharedFtlPerWidgetLocaleEntry} that
  * records the affected path / step error in the caller's collectors, mirroring
  * {@link applyCustomFtlFile}'s contract so the main apply helper stays terse.
  */
-export declare function applySharedFtlPrune(engineDir: string, name: string, ftlDir: string, config: CustomComponentConfig, affectedPaths: string[], stepErrors: StepError[], rollbackJournal?: RollbackJournal): Promise<void>;
+export declare function applySharedFtlPrune(ctx: Pick<ComponentApplyContext, 'engineDir' | 'name' | 'ftlDir'>, config: CustomComponentConfig, affectedPaths: string[], stepErrors: StepError[], rollbackJournal?: RollbackJournal): Promise<void>;
 /**
  * Read-only dry-run describer for {@link pruneSharedFtlPerWidgetLocaleEntry}:
  * returns an action when a dangling per-widget locale entry exists for a
  * `sharedFtl` widget, else `undefined`.
  */
-export declare function describeSharedFtlPrune(engineDir: string, name: string, ftlDir: string, config: CustomComponentConfig): Promise<DryRunAction | undefined>;
+export declare function describeSharedFtlPrune(ctx: Pick<ComponentApplyContext, 'engineDir' | 'name' | 'ftlDir'>, config: CustomComponentConfig): Promise<DryRunAction | undefined>;
 /**
  * Copies a component's `.ftl` into the FTL tree and registers the chrome URI
  * in the locale jar.mn.
@@ -34,7 +32,7 @@ export declare function describeSharedFtlPrune(engineDir: string, name: string,
  * stepErrors rather than thrown — a well-formed `.mjs`/`.css` must never be
  * blocked by a broken locale path.
  */
-export declare function applyCustomFtlFile(engineDir: string, name: string, componentDir: string, ftlDir: string, affectedPaths: string[], stepErrors: StepError[], rollbackJournal?: RollbackJournal): Promise<void>;
+export declare function applyCustomFtlFile(ctx: Pick<ComponentApplyContext, 'engineDir' | 'name' | 'componentDir' | 'ftlDir'>, affectedPaths: string[], stepErrors: StepError[], rollbackJournal?: RollbackJournal): Promise<void>;
 /**
  * Returns a dry-run action for registering a locale jar.mn entry for the
  * `.ftl` that `applyCustomFtlFile` would write. `undefined` when the FTL

package/dist/src/core/furnace-apply-ftl.js

@@ -7,11 +7,9 @@
  * Every helper here degrades gracefully: if the locale jar.mn is missing or
  * the FTL tree is non-standard, apply logs an ADVISORY `stepError`
  * (`advisory: true`) rather than aborting the whole command. Advisory step
- * errors are reported as warnings and never trigger rollback — missing
- * jar.mn on a fork without a locale package should not block a working
- * `.mjs`/`.css` from shipping (the blocking/advisory split exists because
- * this contract used to be contradicted: any FTL step error rolled back
- * the whole apply).
+ * errors are reported as warnings and never trigger rollback — a missing
+ * jar.mn on a fork without a locale package must not block a working
+ * `.mjs`/`.css` from shipping.
  */
 import { join, relative } from 'node:path';
 import { toError } from '../utils/errors.js';
@@ -46,10 +44,9 @@ function resolveSharedFtlPruneTarget(name, ftlDir) {
  * A `localized: true` widget that opts into a feature-scoped `sharedFtl`
  * bundle (its strings live under `browser/...` and load via
  * `insertFTLIfNeeded`) must NOT carry a per-widget
- * `locale/@AB_CD@/<chromeSubPath>/<name>.ftl` line. Such a line — written by
- * an older FireForge before the sharedFtl apply guard, or by a layout
- * migration — points at a `.ftl` that does not exist, so `mach build` fails
- * hard (`Cannot find <chromeSubPath>/<name>.ftl`) and blocks every build.
+ * `locale/@AB_CD@/<chromeSubPath>/<name>.ftl` line. Such a line points at a
+ * `.ftl` that does not exist, so `mach build` fails hard (`Cannot find
+ * <chromeSubPath>/<name>.ftl`) and blocks every build.
  *
  * The pruned line is the per-widget toolkit entry only; the shared bundle's
  * own line (a different chrome sub-path / base name) is never matched, so
@@ -83,7 +80,8 @@ async function pruneSharedFtlPerWidgetLocaleEntry(engineDir, name, ftlDir, confi
  * records the affected path / step error in the caller's collectors, mirroring
  * {@link applyCustomFtlFile}'s contract so the main apply helper stays terse.
  */
-export async function applySharedFtlPrune(engineDir, name, ftlDir, config, affectedPaths, stepErrors, rollbackJournal) {
+export async function applySharedFtlPrune(ctx, config, affectedPaths, stepErrors, rollbackJournal) {
+    const { engineDir, name, ftlDir } = ctx;
     try {
         const prunedPath = await pruneSharedFtlPerWidgetLocaleEntry(engineDir, name, ftlDir, config, rollbackJournal);
         if (prunedPath)
@@ -98,7 +96,8 @@ export async function applySharedFtlPrune(engineDir, name, ftlDir, config, affec
  * returns an action when a dangling per-widget locale entry exists for a
  * `sharedFtl` widget, else `undefined`.
  */
-export async function describeSharedFtlPrune(engineDir, name, ftlDir, config) {
+export async function describeSharedFtlPrune(ctx, config) {
+    const { engineDir, name, ftlDir } = ctx;
     if (!config.sharedFtl)
         return undefined;
     const target = resolveSharedFtlPruneTarget(name, ftlDir);
@@ -123,7 +122,8 @@ export async function describeSharedFtlPrune(engineDir, name, ftlDir, config) {
  * stepErrors rather than thrown — a well-formed `.mjs`/`.css` must never be
  * blocked by a broken locale path.
  */
-export async function applyCustomFtlFile(engineDir, name, componentDir, ftlDir, affectedPaths, stepErrors, rollbackJournal) {
+export async function applyCustomFtlFile(ctx, affectedPaths, stepErrors, rollbackJournal) {
+    const { engineDir, name, componentDir, ftlDir } = ctx;
     const ftlFile = `${name}.ftl`;
     const ftlSrc = join(componentDir, ftlFile);
     if (!(await pathExists(ftlSrc)))