@hominis/fireforge 0.46.0 → 0.46.1

package/dist/src/core/file-lock.d.ts

@@ -14,15 +14,15 @@ export interface LockHolder {
 /**
  * Live queue state around a contended lock.
  *
- * The lock itself behaves correctly under several concurrent sessions; the
- * gap this closes is VISIBILITY. Waiters advertise themselves in a sibling
+ * The lock itself behaves correctly under several concurrent sessions. The
+ * gap this closes is visibility. Waiters advertise themselves in a sibling
  * directory so both the wait output and `fireforge status --lock` can say
  * how many are queued and how many are ahead of you.
  */
 export interface LockQueueState {
     /** Live waiters currently queued for the lock, including this process. */
     depth: number;
-    /** Live waiters that started waiting BEFORE this process. */
+    /** Live waiters that started waiting before this process. */
     ahead: number;
 }
 export interface FileLockOptions {
@@ -31,7 +31,7 @@ export interface FileLockOptions {
     /**
      * When set, the poll interval doubles after every contended poll (starting
      * from `pollMs`) up to this cap. When absent, polling stays at the fixed
-     * `pollMs` interval — zero behavior change for existing callers.
+     * `pollMs` interval, with zero behavior change for existing callers.
      */
     pollMaxMs?: number;
     staleMs?: number;
@@ -60,17 +60,17 @@ export interface FileLockOptions {
         queue?: LockQueueState | undefined;
     }) => void;
     /**
-     * When set, a wait whose QUEUE POSITION is still improving is granted a
+     * When set, a wait whose queue position is still improving is granted a
      * fresh `timeoutMs` budget on each advance, up to `maxWaitMs` total.
      *
      * A fixed wall-clock budget against a queue whose depth the tool knows is
      * the wrong shape under several concurrent sessions: a wait that expires
      * one position from the head pays the entire wait and gets nothing. The
-     * distinction that matters is not "how long have I waited" but "is this
-     * queue moving" — a stalled queue still starves on the original budget,
+     * question that matters is whether the queue is moving, not how long the
+     * wait has been. A stalled queue still starves on the original budget,
      * which is the case the timeout exists for.
      *
-     * Requires the waiter registry (see {@link LockQueueState}); a lock with
+     * Requires the waiter registry (see {@link LockQueueState}). A lock with
      * no readable queue never extends, because nothing observed an advance.
      */
     extendWhileAdvancing?: {
@@ -82,7 +82,7 @@ export interface FileLockOptions {
      * Separate from {@link onWaitProgress} on purpose: an extension is the one
      * moment the budget the operator asked for stops being the budget in
      * force, and a wait that silently outlives its stated timeout is
-     * indistinguishable from a broken one. `budgetMs` is the new TOTAL budget
+     * indistinguishable from a broken one. `budgetMs` is the new total budget
      * measured from the start of the wait, so it can be compared directly
      * against the requested figure.
      */
@@ -92,7 +92,7 @@ export interface FileLockOptions {
     }) => void;
     onTimeoutMessage?: string;
     onStaleLockMessage?: (ageMs: number) => string | undefined;
-    /** Extra owner-file lines for human diagnostics; ignored by lock mechanics. */
+    /** Extra owner-file lines for human diagnostics. Lock mechanics ignore them. */
     ownerMetadata?: readonly string[];
 }
 /** Derives the sibling lock-directory path used to guard a file-based resource. */
@@ -128,11 +128,11 @@ export declare function readLockStatus(lockPath: string): Promise<LockStatusSnap
  * 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
+ * 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
+ * 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

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

@@ -14,8 +14,8 @@ const DEFAULT_LOCK_POLL_MS = 50;
 const DEFAULT_STALE_LOCK_MS = 5 * 60_000;
 /**
  * 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
+ * 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.
@@ -105,7 +105,7 @@ async function registerWaiter(lockPath, startedAt) {
         await writeFile(file, `${process.pid}\n`, 'utf-8');
     }
     catch (error) {
-        // Advisory only — never fail a lock acquisition over the queue display.
+        // Advisory only. Never fail a lock acquisition over the queue display.
         verbose(`Could not register lock waiter for ${lockPath}: ${toError(error).message}`);
         return async () => {
             /* nothing to remove */
@@ -119,8 +119,8 @@ async function registerWaiter(lockPath, startedAt) {
  * 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.
+ * degrades to `holder: undefined`, since a diagnostic must never break the
+ * wait loop.
  */
 async function probeWaitState(lockPath, startedAt) {
     const owner = await readLockOwner(lockPath);
@@ -135,13 +135,13 @@ async function probeWaitState(lockPath, startedAt) {
  *
  * 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.
+ * own lock, and the other's already-decided `rm` then deletes the fresh
+ * lock, putting 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 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
+ * 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.
  *
@@ -156,7 +156,7 @@ async function reapStaleLock(lockPath, ageMs, onStaleLockMessage) {
     }
     catch (error) {
         if (getNodeErrorCode(error) === 'ENOENT') {
-            // Another reaper won, or the owner released — either way, retry mkdir.
+            // Another reaper won, or the owner released. Either way, retry mkdir.
             verbose(`Stale lock disappeared before reaping completed: ${lockPath}`);
             return true;
         }
@@ -174,7 +174,7 @@ async function reapStaleLock(lockPath, ageMs, onStaleLockMessage) {
         catch (restoreError) {
             // Rename-back can only fail if a third process mkdir'd the lock path
             // in this instant. The displaced live owner keeps running without its
-            // lock — surface it loudly instead of hiding the lost exclusion.
+            // lock, so surface it loudly instead of hiding the lost exclusion.
             warn(`Could not restore live lock for PID ${owner.pid} at ${lockPath} ` +
                 `(${toError(restoreError).message}). Displaced lock kept at ${reapPath} for inspection.`);
         }
@@ -199,10 +199,10 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
     try {
         const lockStat = await stat(lockPath);
         const ageMs = Date.now() - lockStat.mtimeMs;
-        // Check PID FIRST, independent of age. Age-gating everything means a
+        // Check the 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
+        // when its PID file points at a process that has already exited. That is
+        // 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);
@@ -210,8 +210,8 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
             if (!isLockOwnerAlive(owner)) {
                 return await reapStaleLock(lockPath, ageMs, onStaleLockMessage);
             }
-            // The owner is alive (PID exists AND, where `/proc` can tell, it is
-            // the process that acquired the lock, not a recycled PID) — respect
+            // The owner is alive (PID exists and, where `/proc` can tell, it is
+            // the process that acquired the lock, not a recycled PID), so respect
             // it regardless of age. A slow `mach build` legitimately holds the
             // lock past the stale threshold and we don't want to race-remove it.
             verbose(`Lock at ${lockPath} is ${Math.round(ageMs / 1000)}s old but PID ${owner.pid} is still running — not removing`);
@@ -237,8 +237,8 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
 }
 /**
  * Releases a lock previously acquired by this process, verifying ownership
- * first. An unconditional `finally { rm }` would remove *whichever* lock
- * directory is present — if a stale-lock reaper had (in a pathological race)
+ * 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.
@@ -260,11 +260,11 @@ async function releaseLock(lockPath, ownerToken) {
  * 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
+ * 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
+ * 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
@@ -293,8 +293,11 @@ export async function releaseLockIfOwned(lockPath) {
  * 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
+ * identification appended: the reason-first copy stays theirs, the "who
  * holds it" is ours.
+ *
+ * `queue` is read at expiry by the caller, not carried over from the last
+ * progress probe: see {@link formatQueuePositionReached}.
  */
 async function buildLockTimeoutError(lockPath, onTimeoutMessage, cause, queue) {
     const owner = await readLockOwner(lockPath);
@@ -315,15 +318,22 @@ async function buildLockTimeoutError(lockPath, onTimeoutMessage, cause, queue) {
 /**
  * States the queue position the expired wait actually reached.
  *
- * Silence here is what made the worst outcome invisible: a wait that expires
+ * Silence here 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
+ * guess. Omitted when no queue was observed, since an empty registry is not
  * evidence of an empty queue.
+ *
+ * The queue is read at the moment the budget expires rather than taken from
+ * the last progress probe. A probe snapshot is up to one `waitProgressMs`
+ * stale, and, the reason this changed, it may not exist at all: a short
+ * budget can expire before the first probe lands (a slow runner's
+ * `registerWaiter` alone can outlast it), and a caller that configured no
+ * probe at all never had one. Both used to lose the position silently.
  */
 function formatQueuePositionReached(queue) {
-    if (queue === undefined || queue.depth === 0)
+    if (queue.depth === 0)
         return '';
     if (queue.ahead === 0) {
         return ` You were next in a queue of ${queue.depth} when the wait expired — a larger --wait-lock would very likely have got a turn.`;
@@ -352,13 +362,13 @@ async function runWaitProbe(lockPath, startedAt, timeoutMs, options) {
  * 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.
+ * process that is not running, which is 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.
+ * is the check that matters: it stops the sweep deleting a lock a
+ * different process acquired in the meantime.
  */
 const heldLocks = new Set();
 /**
@@ -392,14 +402,12 @@ export async function withFileLock(lockPath, operation, options = {}) {
     let lastStaleProbeAt;
     let currentPollMs = pollMs;
     let lastProbeAt = startedAt;
-    /** Best (lowest) queue position seen so far; used to detect an advance. */
+    /** 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
+    // 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) ||
@@ -426,26 +434,31 @@ export async function withFileLock(lockPath, operation, options = {}) {
                     }
                 }
                 if (Date.now() >= deadline) {
-                    throw await buildLockTimeoutError(lockPath, options.onTimeoutMessage, error, lastQueue);
+                    // The queue is read here, not carried over from the last progress
+                    // probe: the position the wait reached is the one number that says
+                    // whether a larger budget would have helped, and it must not depend
+                    // on a probe having happened to land inside the budget. We are still
+                    // registered at this point. `deregisterWaiter` runs in the `finally`
+                    // below, which is only entered once this refusal has been built.
+                    throw await buildLockTimeoutError(lockPath, options.onTimeoutMessage, error, await readLockQueue(lockPath, startedAt));
                 }
                 if (probeWanted && Date.now() - lastProbeAt >= probeIntervalMs) {
                     lastProbeAt = Date.now();
-                    // Report the budget that is CURRENTLY in force, not the one
+                    // 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 —
+                    // 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`
+                    // 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.
+                    // once, which is the "it does not reliably give up after N
+                    // seconds" behaviour a downstream fork reported.
                     if (hardDeadline !== undefined) {
                         if (bestAhead === undefined) {
                             bestAhead = probe.queue.ahead;
@@ -468,7 +481,7 @@ export async function withFileLock(lockPath, operation, options = {}) {
         }
     }
     finally {
-        // Leaving the queue happens the moment we stop waiting — whether we
+        // Leaving the queue happens the moment we stop waiting, whether we
         // acquired the lock or timed out.
         await deregisterWaiter?.();
     }

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

@@ -16,7 +16,7 @@ export interface ArchiveIntegrityOptions {
  * @param archive - Resolved archive descriptor
  * @param cacheDir - Cache directory
  * @param onProgress - Optional progress callback
- * @param expectedSha256 - Operator-pinned digest; when set it replaces the
+ * @param expectedSha256 - Operator-pinned digest. When set it replaces the
  *   published-SHA256SUMS check
  * @param onCacheProgress - Phase progress messages
  * @param integrity - Default integrity-check options (unpinned downloads)

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

@@ -28,10 +28,10 @@ async function sha256File(filePath) {
  * Fetches Mozilla's published SHA256SUMS for the release and extracts the
  * digest for this archive. Yields a reason instead of a digest when the
  * checksum file cannot be fetched (non-2xx, network error, timeout) or does
- * not list the archive (a captive portal's HTML page lands here too) — the
+ * not list the archive (a captive portal's HTML page lands here too). The
  * caller decides whether that fails closed. The request goes through the
- * same `fetchWithRetry` as the archive download — same 60 s abort ceiling
- * per attempt, same three-attempt back-off on 429/5xx and network errors —
+ * same `fetchWithRetry` as the archive download (same 60 s abort ceiling
+ * per attempt, same three-attempt back-off on 429/5xx and network errors),
  * so an unresponsive checksum host cannot hang the command after the
  * tarball has landed, and one transient blip on the small checksum request
  * does not fail the verification closed and discard the archive.
@@ -65,15 +65,15 @@ async function fetchPublishedSha256(archive) {
 /**
  * Default integrity check for a download with no operator pin: the archive
  * digest must equal the one Mozilla publishes. TLS alone is thin trust for
- * the artifact that becomes the git baseline every patch is built on — a
+ * the artifact that becomes the git baseline every patch is built on: a
  * compromised CDN response would otherwise be trusted with no signal.
  *
- * Fails CLOSED both on a mismatch and when the published digest cannot be
+ * Fails closed both on a mismatch and when the published digest cannot be
  * obtained: a 404, a captive-portal HTML page, or a dropped connection
  * would otherwise quietly downgrade the check to "TLS looked fine", which
- * is precisely the condition an attacker positioned on the network can
+ * is the condition an attacker positioned on the network can
  * arrange. `allowUnverifiedDownload` (an explicit config opt-in for offline
- * mirrors) degrades the unavailable case to a loud warning; a FETCHED but
+ * mirrors) degrades the unavailable case to a loud warning. A fetched but
  * mismatching digest is never accepted.
  */
 async function verifyAgainstPublishedSha256(archive, actualSha256, options) {
@@ -97,7 +97,7 @@ async function verifyAgainstPublishedSha256(archive, actualSha256, options) {
  * @param archive - Resolved archive descriptor
  * @param cacheDir - Cache directory
  * @param onProgress - Optional progress callback
- * @param expectedSha256 - Operator-pinned digest; when set it replaces the
+ * @param expectedSha256 - Operator-pinned digest. When set it replaces the
  *   published-SHA256SUMS check
  * @param onCacheProgress - Phase progress messages
  * @param integrity - Default integrity-check options (unpinned downloads)
@@ -133,7 +133,7 @@ async function cacheEntryExists(archive, cacheDir) {
 async function validateCachedArchive(archive, cacheDir, expectedSha256) {
     const tarballPath = join(cacheDir, archive.filename);
     const metadataPath = join(cacheDir, archive.metadataFilename);
-    // Deliberately outside the try/catch below: a permission error probing the
+    // Outside the try/catch below on purpose: a permission error probing the
     // cache must propagate instead of reading as "invalid cache" and triggering
     // a re-download into a directory we cannot write anyway.
     if (!(await pathExistsStrict(tarballPath)) || !(await pathExistsStrict(metadataPath))) {
@@ -244,6 +244,6 @@ async function removeArchivePartFiles(archive, cacheDir) {
     }
     catch (error) {
         void error;
-        // Cache dir may not exist yet — that's fine.
+        // Cache dir may not exist yet. That's fine.
     }
 }

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

@@ -9,9 +9,9 @@ export type ProgressCallback = (downloaded: number, total: number) => void;
  * Fetches a URL with timeout and bounded retry for transient failures
  * (429/5xx, network errors, the per-request timeout).
  *
- * Any other response — 2xx or a non-retryable failure such as 404 — is
- * returned as-is on the first attempt; the caller decides what a given
- * status means for ITS request. Shared by the tarball download and the
+ * Any other response (2xx or a non-retryable failure such as 404) is
+ * returned as-is on the first attempt. The caller decides what a given
+ * status means for its request. Shared by the tarball download and the
  * SHA256SUMS lookup so both requests the download makes survive the same
  * transient blips: with checksum verification failing closed, an
  * un-retried checksum fetch would throw away a just-landed 600 MB archive

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

@@ -10,8 +10,8 @@ import { DownloadError, VersionNotFoundError } from '../errors/download.js';
 import { sleep } from '../utils/sleep.js';
 /**
  * Per-attempt request timeout in milliseconds (60 seconds). Every request
- * the download makes — the tarball and the SHA256SUMS lookup in
- * `firefox-cache.ts` — goes through {@link fetchWithRetry} and so shares
+ * the download makes (the tarball and the SHA256SUMS lookup in
+ * `firefox-cache.ts`) goes through {@link fetchWithRetry} and so shares
  * this abort ceiling.
  */
 const REQUEST_TIMEOUT_MS = 60_000;
@@ -21,15 +21,15 @@ const MAX_ATTEMPTS = 3;
 const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
 /** Base delay between retries in milliseconds. */
 const RETRY_BASE_DELAY_MS = 1_000;
-/** Stall detection timeout — abort if no data received for this duration (30 seconds). */
+/** Stall detection timeout: abort if no data received for this duration (30 seconds). */
 const DOWNLOAD_STALL_TIMEOUT_MS = 30_000;
 /**
  * Fetches a URL with timeout and bounded retry for transient failures
  * (429/5xx, network errors, the per-request timeout).
  *
- * Any other response — 2xx or a non-retryable failure such as 404 — is
- * returned as-is on the first attempt; the caller decides what a given
- * status means for ITS request. Shared by the tarball download and the
+ * Any other response (2xx or a non-retryable failure such as 404) is
+ * returned as-is on the first attempt. The caller decides what a given
+ * status means for its request. Shared by the tarball download and the
  * SHA256SUMS lookup so both requests the download makes survive the same
  * transient blips: with checksum verification failing closed, an
  * un-retried checksum fetch would throw away a just-landed 600 MB archive

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

@@ -13,9 +13,9 @@ export declare function findUnsafeArchiveEntryName(names: readonly string[]): st
  *
  * A relative link target without `..` segments can only resolve inside the
  * extraction root, so only absolute or `..`-containing targets are rejected.
- * Symlinks are `l`-typed lines with a ` -> target` suffix (the LAST arrow is
+ * Symlinks are `l`-typed lines with a ` -> target` suffix (the last arrow is
  * taken, so a link whose own name contains ` -> ` still parses to its real
- * target); hardlinks print ` link to target` on GNU tar and bsdtar alike.
+ * target). Hardlinks print ` link to target` on GNU tar and bsdtar alike.
  *
  * @param verboseLines - `tar -tvf` listing lines
  * @returns A description of the first unsafe link found, or undefined

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

@@ -22,20 +22,20 @@ function isUnsafeArchivePath(path) {
 /**
  * Returns true when an archive member path has a `.git` segment at any
  * depth (`.git`, `.git/config`, `foo/.git/hooks/pre-commit`). Such a member
- * lands INSIDE the extraction root, so the traversal check passes it — but
+ * lands inside the extraction root, so the traversal check passes it, but
  * the extracted tree is immediately turned into a git repository and
  * committed, and git honours a pre-seeded `.git/config` (`core.fsmonitor`,
  * `core.hooksPath`) or `.git/hooks/*` on that first commit. Only the `.git`
- * directory/file is rejected; `.gitmodules`, `.gitignore` and the like are
+ * directory/file is rejected. `.gitmodules`, `.gitignore` and the like are
  * legitimate upstream files.
  */
 function hasGitSegment(path) {
     return path.split(/[\\/]/).some((segment) => segment.toLowerCase() === '.git');
 }
 /**
- * Returns true when an archive member NAME must be rejected: an escaping
+ * Returns true when an archive member name must be rejected: an escaping
  * path, or a `.git` segment (see {@link hasGitSegment}). Link targets use
- * the narrower {@link isUnsafeArchivePath} — a target can only be reached
+ * the narrower {@link isUnsafeArchivePath}: a target can only be reached
  * through a member name that was checked here.
  */
 function isUnsafeArchiveMemberName(name) {
@@ -62,9 +62,9 @@ export function findUnsafeArchiveEntryName(names) {
  *
  * A relative link target without `..` segments can only resolve inside the
  * extraction root, so only absolute or `..`-containing targets are rejected.
- * Symlinks are `l`-typed lines with a ` -> target` suffix (the LAST arrow is
+ * Symlinks are `l`-typed lines with a ` -> target` suffix (the last arrow is
  * taken, so a link whose own name contains ` -> ` still parses to its real
- * target); hardlinks print ` link to target` on GNU tar and bsdtar alike.
+ * target). Hardlinks print ` link to target` on GNU tar and bsdtar alike.
  *
  * @param verboseLines - `tar -tvf` listing lines
  * @returns A description of the first unsafe link found, or undefined
@@ -93,13 +93,13 @@ export function findUnsafeArchiveLink(verboseLines) {
  * Lists the archive and rejects members that could escape the extraction
  * root before anything is written to disk: absolute names, `..` traversal,
  * and symlink/hardlink targets that are absolute or `..`-escaping. Modern
- * GNU tar / bsdtar refuse most of these at extraction time; the preflight
+ * GNU tar / bsdtar refuse most of these at extraction time. The preflight
  * makes the guarantee explicit and independent of the host tar's defaults.
  *
  * Two listings are needed because they answer different questions and
  * neither is safe to derive from the other: member names come from `-tf`,
- * where the whole line IS the name, while link targets only appear in
- * `-tvf`. Names are deliberately NOT parsed out of the `-tvf` columns — the
+ * where the whole line is the name, while link targets only appear in
+ * `-tvf`. Names are not parsed out of the `-tvf` columns, on purpose: the
  * adjacent uname/gname fields are attacker-controlled in a crafted archive,
  * 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
@@ -138,11 +138,11 @@ function createLineScanner(onLine) {
  *
  * 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
+ * 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
+ * could exploit 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.
+ * 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.
@@ -160,7 +160,7 @@ async function runListingScan(archivePath, tarFlag, checkLine) {
             scanner.push(chunk);
         },
         onStderr: (chunk) => {
-            // Keep a small diagnostic tail; the listing itself is the big stream.
+            // Keep a small diagnostic tail. The listing itself is the big stream.
             stderrTail = (stderrTail + chunk).slice(-4096);
         },
     });

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

@@ -24,10 +24,10 @@ export type FirefoxSourceProgressCallback = (message: string) => void;
  * Sweeps orphaned working directories left behind by interrupted downloads
  * (`<engine>.tmp-*` from extraction, `<engine>.replacement-*` from --force
  * replacement). Both hold multi-GB partial trees, are worthless after the
- * owning process died, and nothing else ever reclaimed them. Deliberately
- * does NOT touch `<engine>.backup-*`: a backup may hold the operator's
- * previous engine after a failed forced replacement and is their recovery
- * copy — callers should surface its existence instead.
+ * owning process died, and nothing else ever reclaimed them. Does not
+ * touch `<engine>.backup-*`: a backup may hold the operator's previous
+ * engine after a failed forced replacement and is their recovery copy, so
+ * callers should surface its existence instead.
  *
  * @returns names of the directories that were removed
  */
@@ -46,7 +46,7 @@ export interface DownloadFirefoxSourceOptions {
     onProgress?: ProgressCallback | undefined;
     /** Called when the run moves from downloading to extracting. */
     onPhase?: FirefoxSourcePhaseCallback | undefined;
-    /** Expected archive checksum; verified after download when supplied. */
+    /** Expected archive checksum, verified after download when supplied. */
     expectedSha256?: string | undefined;
     /** Called with byte progress within the current phase. */
     onPhaseProgress?: FirefoxSourceProgressCallback | undefined;

package/dist/src/core/firefox.js

@@ -18,8 +18,8 @@ export { formatBytes, getFirefoxVersion } from './firefox-extract.js';
 /**
  * Classifies an extraction failure as archive corruption (invalidate the
  * cache and re-download) versus an environmental problem (keep the cached
- * archive; the retry can reuse it). Environmental signatures are the
- * conservative list — anything unrecognized is treated as corruption so a
+ * archive so the retry can reuse it). Environmental signatures are the
+ * conservative list. Anything unrecognized is treated as corruption so a
  * genuinely bad archive can never survive in the cache.
  */
 function isLikelyArchiveCorruptionError(error) {
@@ -32,7 +32,7 @@ function isLikelyArchiveCorruptionError(error) {
         return false;
     }
     // Missing tar binary / preflight refusing an unsafe archive both carry
-    // ExtractionError text that names the condition; a missing tar is
+    // ExtractionError text that names the condition. A missing tar is
     // environmental, an unsafe-entry rejection indicts the archive.
     if (/"tar" command was not found/i.test(message)) {
         return false;
@@ -43,10 +43,10 @@ function isLikelyArchiveCorruptionError(error) {
  * Sweeps orphaned working directories left behind by interrupted downloads
  * (`<engine>.tmp-*` from extraction, `<engine>.replacement-*` from --force
  * replacement). Both hold multi-GB partial trees, are worthless after the
- * owning process died, and nothing else ever reclaimed them. Deliberately
- * does NOT touch `<engine>.backup-*`: a backup may hold the operator's
- * previous engine after a failed forced replacement and is their recovery
- * copy — callers should surface its existence instead.
+ * owning process died, and nothing else ever reclaimed them. Does not
+ * touch `<engine>.backup-*`: a backup may hold the operator's previous
+ * engine after a failed forced replacement and is their recovery copy, so
+ * callers should surface its existence instead.
  *
  * @returns names of the directories that were removed
  */
@@ -95,7 +95,7 @@ export async function downloadFirefoxSource(options) {
     catch (error) {
         await removeDir(tempDir);
         // Only throw away the ~600 MB cached archive when the failure indicts
-        // the ARCHIVE, not the environment. ENOSPC, a permission problem in
+        // the archive, not the environment. ENOSPC, a permission problem in
         // destDir, or tar disappearing mid-run used to invalidate a perfectly
         // good download and force a full re-fetch on retry.
         if (isLikelyArchiveCorruptionError(error)) {

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

@@ -52,7 +52,7 @@ export async function buildCustomDryRunActions(ctx, config, targetDir, entries)
             }
         }
     }
-    // A sharedFtl widget owns its strings via the shared bundle; surface the
+    // 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(ctx, config);

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

@@ -4,9 +4,9 @@
  * per-file LOC budget.
  *
  * Every helper here degrades gracefully: if the locale jar.mn is missing or
- * the FTL tree is non-standard, apply logs an ADVISORY `stepError`
+ * 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 — a missing
+ * 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.
  */
@@ -29,8 +29,8 @@ export declare function describeSharedFtlPrune(ctx: Pick<ComponentApplyContext,
  * in the locale jar.mn.
  *
  * Failure modes (missing jar.mn, regex write error) are captured as
- * stepErrors rather than thrown — a well-formed `.mjs`/`.css` must never be
- * blocked by a broken locale path.
+ * stepErrors rather than thrown, since a well-formed `.mjs`/`.css` must
+ * never be blocked by a broken locale path.
  */
 export declare function applyCustomFtlFile(ctx: Pick<ComponentApplyContext, 'engineDir' | 'name' | 'componentDir' | 'ftlDir'>, affectedPaths: string[], stepErrors: StepError[], rollbackJournal?: RollbackJournal): Promise<void>;
 /**
@@ -41,7 +41,7 @@ export declare function applyCustomFtlFile(ctx: Pick<ComponentApplyContext, 'eng
 export declare function describeLocaleFtlJarMnRegistration(name: string, ftlDir: string, ftlFile: string): DryRunAction | undefined;
 /**
  * Drops the locale jar.mn entry for `fileName` when it's a `.ftl` whose
- * source workspace file has been deleted. Idempotent — absent entries are a
+ * source workspace file has been deleted. Idempotent: absent entries are a
  * no-op. Early-returns for `sharedFtl` components: the shared bundle is
  * owned elsewhere, and dropping its jar.mn line on our component's delete
  * would orphan every other participant.