@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -5,6 +5,21 @@
  * Progress callback for download operations.
  */
 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
+ * 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
+ * over one dropped connection.
+ *
+ * @throws DownloadError once every attempt has failed with a retryable error
+ */
+export declare function fetchWithRetry(url: string): Promise<Response>;
 /**
  * Downloads a file from a URL with progress tracking, timeout, and retry.
  * @param url - URL to download

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

@@ -7,7 +7,13 @@ import { basename } from 'node:path';
 import { Readable, Transform } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { DownloadError, VersionNotFoundError } from '../errors/download.js';
-/** Default request timeout in milliseconds (60 seconds). */
+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
+ * this abort ceiling.
+ */
 const REQUEST_TIMEOUT_MS = 60_000;
 /** Maximum number of download attempts. */
 const MAX_ATTEMPTS = 3;
@@ -15,14 +21,23 @@ 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.
+ * Fetches a URL with timeout and bounded retry for transient failures
+ * (429/5xx, network errors, the per-request timeout).
  *
- * Non-retryable errors (e.g. 404) are thrown immediately.
+ * 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
+ * over one dropped connection.
+ *
+ * @throws DownloadError once every attempt has failed with a retryable error
  */
-async function fetchWithRetry(url) {
+export async function fetchWithRetry(url) {
     let lastError;
     for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
         const controller = new AbortController();
@@ -31,23 +46,12 @@ async function fetchWithRetry(url) {
         }, REQUEST_TIMEOUT_MS);
         try {
             const response = await fetch(url, { signal: controller.signal });
-            if (response.status === 404) {
-                throw new VersionNotFoundError(basename(url).replace('.source.tar.xz', ''));
-            }
-            if (RETRYABLE_STATUS_CODES.has(response.status)) {
-                lastError = new DownloadError(`HTTP ${response.status}: ${response.statusText}`, url);
-            }
-            else if (!response.ok) {
-                throw new DownloadError(`HTTP ${response.status}: ${response.statusText}`, url);
-            }
-            else {
+            if (!RETRYABLE_STATUS_CODES.has(response.status)) {
                 return response;
             }
+            lastError = new DownloadError(`HTTP ${response.status}: ${response.statusText}`, url);
         }
         catch (error) {
-            if (error instanceof VersionNotFoundError || error instanceof DownloadError) {
-                throw error;
-            }
             // Network / timeout errors are retryable
             lastError = error;
         }
@@ -55,9 +59,7 @@ async function fetchWithRetry(url) {
             clearTimeout(timer);
         }
         if (attempt < MAX_ATTEMPTS - 1) {
-            await new Promise((resolve) => {
-                setTimeout(resolve, RETRY_BASE_DELAY_MS * (attempt + 1) ** 2);
-            });
+            await sleep(RETRY_BASE_DELAY_MS * (attempt + 1) ** 2);
         }
     }
     if (lastError instanceof DownloadError) {
@@ -65,6 +67,20 @@ async function fetchWithRetry(url) {
     }
     throw new DownloadError(lastError instanceof Error ? lastError.message : 'Download failed after retries', url, lastError instanceof Error ? lastError : undefined);
 }
+/**
+ * Fetches the archive itself: a 404 is the release not existing
+ * (`VersionNotFoundError`), any other non-2xx is a `DownloadError`.
+ */
+async function fetchArchive(url) {
+    const response = await fetchWithRetry(url);
+    if (response.status === 404) {
+        throw new VersionNotFoundError(basename(url).replace('.source.tar.xz', ''));
+    }
+    if (!response.ok) {
+        throw new DownloadError(`HTTP ${response.status}: ${response.statusText}`, url);
+    }
+    return response;
+}
 /**
  * Creates a Transform stream that aborts if no data is received within the stall timeout.
  * The timer resets on each chunk. If it fires, the stream is destroyed with a DownloadError.
@@ -110,7 +126,7 @@ function createStallDetector(url, timeoutMs = DOWNLOAD_STALL_TIMEOUT_MS) {
  * @returns The content-length if available, otherwise undefined
  */
 export async function downloadFile(url, destPath, onProgress) {
-    const response = await fetchWithRetry(url);
+    const response = await fetchArchive(url);
     if (!response.body) {
         throw new DownloadError('No response body received', url);
     }

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

@@ -2,24 +2,25 @@
  * Firefox source extraction and installed version detection.
  */
 /**
- * Validates entry names from a `tar -tf` listing.
+ * Validates entry names from a `tar -tf` listing: escaping paths and
+ * `.git` members are both rejected.
  * @param names - Listing lines (one member name per line)
- * @returns The first unsafe member name, or null when all are safe
+ * @returns The first unsafe member name, or undefined when all are safe
  */
-export declare function findUnsafeArchiveEntryName(names: readonly string[]): string | null;
+export declare function findUnsafeArchiveEntryName(names: readonly string[]): string | undefined;
 /**
  * Validates symlink and hardlink targets from a `tar -tvf` listing.
  *
  * 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 null
+ * @returns A description of the first unsafe link found, or undefined
  */
-export declare function findUnsafeArchiveLink(verboseLines: readonly string[]): string | null;
+export declare function findUnsafeArchiveLink(verboseLines: readonly string[]): string | undefined;
 /**
  * Extracts a tar.xz archive after a listing preflight that rejects
  * path-traversal member names and escaping link targets.

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

@@ -20,31 +20,54 @@ function isUnsafeArchivePath(path) {
     return path.split(/[\\/]/).includes('..');
 }
 /**
- * Validates entry names from a `tar -tf` listing.
+ * 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
+ * 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
+ * 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
+ * path, or a `.git` segment (see {@link hasGitSegment}). Link targets use
+ * the narrower {@link isUnsafeArchivePath}: a target can only be reached
+ * through a member name that was checked here.
+ */
+function isUnsafeArchiveMemberName(name) {
+    return isUnsafeArchivePath(name) || hasGitSegment(name);
+}
+/**
+ * Validates entry names from a `tar -tf` listing: escaping paths and
+ * `.git` members are both rejected.
  * @param names - Listing lines (one member name per line)
- * @returns The first unsafe member name, or null when all are safe
+ * @returns The first unsafe member name, or undefined when all are safe
  */
 export function findUnsafeArchiveEntryName(names) {
     for (const raw of names) {
         const name = raw.trim();
         if (name.length === 0)
             continue;
-        if (isUnsafeArchivePath(name))
+        if (isUnsafeArchiveMemberName(name))
             return name;
     }
-    return null;
+    return undefined;
 }
 /**
  * Validates symlink and hardlink targets from a `tar -tvf` listing.
  *
  * 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 null
+ * @returns A description of the first unsafe link found, or undefined
  */
 export function findUnsafeArchiveLink(verboseLines) {
     for (const line of verboseLines) {
@@ -64,19 +87,19 @@ export function findUnsafeArchiveLink(verboseLines) {
                 return `hardlink target: ${target}`;
         }
     }
-    return null;
+    return undefined;
 }
 /**
  * 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
@@ -111,23 +134,23 @@ function createLineScanner(onLine) {
 }
 /**
  * Runs one tar listing pass, streaming lines through `checkLine` and
- * returning the first unsafe finding (or null) plus the exit code.
+ * returning the first unsafe finding (or undefined) plus the exit code.
  *
  * 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.
     const listEnv = { LC_ALL: 'C', LANG: 'C' };
-    let unsafe = null;
+    let unsafe;
     let stderrTail = '';
     const scanner = createLineScanner((line) => {
-        if (unsafe === null) {
+        if (unsafe === undefined) {
             unsafe = checkLine(line);
         }
     });
@@ -137,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);
         },
     });
@@ -146,24 +169,19 @@ async function runListingScan(archivePath, tarFlag, checkLine) {
 }
 async function preflightArchiveEntries(archivePath) {
     const [nameScan, linkScan] = await Promise.all([
-        runListingScan(archivePath, '-tf', (line) => {
-            const name = line.trim();
-            if (name.length === 0)
-                return null;
-            return isUnsafeArchivePath(name) ? name : null;
-        }),
+        runListingScan(archivePath, '-tf', (line) => findUnsafeArchiveEntryName([line])),
         runListingScan(archivePath, '-tvf', (line) => findUnsafeArchiveLink([line])),
     ]);
     if (nameScan.exitCode !== 0) {
         throw new ExtractionError(archivePath, new Error(`tar -tf preflight exited with code ${nameScan.exitCode}:\n${nameScan.stderrTail}`));
     }
-    if (nameScan.unsafe !== null) {
-        throw new ExtractionError(archivePath, new Error(`Archive rejected: member name could escape the extraction root: ${nameScan.unsafe}`));
+    if (nameScan.unsafe !== undefined) {
+        throw new ExtractionError(archivePath, new Error(`Archive rejected: member name could escape the extraction root or seed .git: ${nameScan.unsafe}`));
     }
     if (linkScan.exitCode !== 0) {
         throw new ExtractionError(archivePath, new Error(`tar -tvf preflight exited with code ${linkScan.exitCode}:\n${linkScan.stderrTail}`));
     }
-    if (linkScan.unsafe !== null) {
+    if (linkScan.unsafe !== undefined) {
         throw new ExtractionError(archivePath, new Error(`Archive rejected: link could escape the extraction root (${linkScan.unsafe})`));
     }
 }

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

@@ -5,26 +5,9 @@
  * {@link downloadFirefoxSource} orchestrator.
  */
 import type { FirefoxProduct } from '../types/config.js';
+import type { ArchiveIntegrityOptions } from './firefox-cache.js';
 import type { ProgressCallback } from './firefox-download.js';
-export { resolveArchive } from './firefox-archive.js';
-export type { ProgressCallback } from './firefox-download.js';
 export { formatBytes, getFirefoxVersion } from './firefox-extract.js';
-/**
- * Gets the download URL for a Firefox source tarball.
- * @param version - Firefox version (e.g., "140.9.0esr")
- * @param product - Firefox product type
- * @param candidate - Optional release-candidate build directory (e.g. "build2")
- * @returns Full URL to the source tarball
- */
-export declare function getDownloadUrl(version: string, product?: FirefoxProduct, candidate?: string): string;
-/**
- * Gets the filename for a Firefox source tarball.
- * @param version - Firefox version
- * @param product - Firefox product type
- * @param candidate - Optional release-candidate build directory (e.g. "build2")
- * @returns Tarball filename
- */
-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
@@ -41,28 +24,43 @@ 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
  */
 export declare function sweepOrphanedEngineWorkDirs(destDir: string): Promise<string[]>;
+/** Inputs for {@link downloadFirefoxSource}. */
+export interface DownloadFirefoxSourceOptions {
+    /** Firefox version to fetch, e.g. `140.9.0esr`. */
+    version: string;
+    /** Product channel the version belongs to. */
+    product: FirefoxProduct;
+    /** Directory the extracted source tree is moved into. */
+    destDir: string;
+    /** Directory holding downloaded tarballs between runs. */
+    cacheDir: string;
+    /** Called with byte progress for the whole transfer. */
+    onProgress?: ProgressCallback | undefined;
+    /** Called when the run moves from downloading to extracting. */
+    onPhase?: FirefoxSourcePhaseCallback | undefined;
+    /** Expected archive checksum, verified after download when supplied. */
+    expectedSha256?: string | undefined;
+    /** Called with byte progress within the current phase. */
+    onPhaseProgress?: FirefoxSourceProgressCallback | undefined;
+    /**
+     * Release-candidate build directory (e.g. `build2`), resolving the archive
+     * under `candidates/` instead of `releases/`.
+     */
+    candidate?: string | undefined;
+    /** Integrity-check defaults for unpinned downloads. */
+    integrity?: ArchiveIntegrityOptions | undefined;
+}
 /**
  * Downloads and extracts Firefox source.
- * @param version - Firefox version to download
- * @param product - Firefox product type
- * @param destDir - Destination directory for extracted source
- * @param cacheDir - Directory to store downloaded tarball
- * @param onProgress - Optional progress callback for the download byte stream
- * @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/`.
+ *
+ * @param options - See {@link DownloadFirefoxSourceOptions}.
  */
-export declare function downloadFirefoxSource(version: string, product: FirefoxProduct, destDir: string, cacheDir: string, onProgress?: ProgressCallback, onPhase?: FirefoxSourcePhaseCallback, expectedSha256?: string, onPhaseProgress?: FirefoxSourceProgressCallback, candidate?: string): Promise<void>;
+export declare function downloadFirefoxSource(options: DownloadFirefoxSourceOptions): Promise<void>;

package/dist/src/core/firefox.js

@@ -14,33 +14,12 @@ import { resolveArchive } from './firefox-archive.js';
 import { ensureCachedArchive, invalidateArchiveCache } from './firefox-cache.js';
 import { extractTarXz } from './firefox-extract.js';
 // ── Re-exports (preserve public API) ──
-export { resolveArchive } from './firefox-archive.js';
 export { formatBytes, getFirefoxVersion } from './firefox-extract.js';
-/**
- * Gets the download URL for a Firefox source tarball.
- * @param version - Firefox version (e.g., "140.9.0esr")
- * @param product - Firefox product type
- * @param candidate - Optional release-candidate build directory (e.g. "build2")
- * @returns Full URL to the source tarball
- */
-export function getDownloadUrl(version, product = 'firefox', candidate) {
-    return resolveArchive(version, product, candidate).url;
-}
-/**
- * Gets the filename for a Firefox source tarball.
- * @param version - Firefox version
- * @param product - Firefox product type
- * @param candidate - Optional release-candidate build directory (e.g. "build2")
- * @returns Tarball filename
- */
-export function getTarballFilename(version, product = 'firefox', candidate) {
-    return resolveArchive(version, product, candidate).filename;
-}
 /**
  * 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) {
@@ -53,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;
@@ -64,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,27 +74,17 @@ export async function sweepOrphanedEngineWorkDirs(destDir) {
 }
 /**
  * Downloads and extracts Firefox source.
- * @param version - Firefox version to download
- * @param product - Firefox product type
- * @param destDir - Destination directory for extracted source
- * @param cacheDir - Directory to store downloaded tarball
- * @param onProgress - Optional progress callback for the download byte stream
- * @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/`.
+ *
+ * @param options - See {@link DownloadFirefoxSourceOptions}.
  */
-export async function downloadFirefoxSource(version, product, destDir, cacheDir, onProgress, onPhase, expectedSha256, onPhaseProgress, candidate) {
+export async function downloadFirefoxSource(options) {
+    const { version, product, destDir, cacheDir, onProgress, onPhase, expectedSha256, onPhaseProgress, candidate, integrity, } = options;
     const archive = resolveArchive(version, product, candidate);
     const tarballPath = join(cacheDir, archive.filename);
     // Ensure cache directory exists
     await ensureDir(cacheDir);
     onPhase?.('download');
-    await ensureCachedArchive(archive, cacheDir, onProgress, expectedSha256, onPhaseProgress);
+    await ensureCachedArchive(archive, cacheDir, onProgress, expectedSha256, onPhaseProgress, integrity);
     // Extract to a unique temporary directory so concurrent downloads for
     // the same destination do not clobber each other.
     onPhase?.('extract');
@@ -126,7 +95,7 @@ export async function downloadFirefoxSource(version, product, destDir, cacheDir,
     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.d.ts

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

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

@@ -9,14 +9,8 @@ import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { describeLocaleFtlJarMnRegistration, describeSharedFtlPrune } from './furnace-apply-ftl.js';
 import { describeFragmentExpansion } from './furnace-css-fragments.js';
+import { isRegularFile } from './furnace-dir-entry.js';
 import { validateCustomElementRegistration, validateJarMnInsertionForFiles, } from './furnace-registration.js';
-function isRegularFile(entry) {
-    if (!entry.isFile())
-        return false;
-    if (typeof entry.isSymbolicLink === 'function' && entry.isSymbolicLink())
-        return false;
-    return true;
-}
 /** Computes the planned dry-run actions (and pre-flight step errors) for a custom component. */
 export async function buildCustomDryRunActions(ctx, config, targetDir, entries) {
     const { engineDir, name, componentDir, ftlDir } = ctx;
@@ -58,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.

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

@@ -5,9 +5,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.
  */
@@ -44,12 +44,12 @@ 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
+ * `insertFTLIfNeeded`) must not carry a per-widget
  * `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
+ * 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
  * pruning one widget cannot orphan the shared bundle. Idempotent: when no
  * dangling entry exists the file is left untouched (no journal churn).
@@ -120,8 +120,8 @@ export async function describeSharedFtlPrune(ctx, config) {
  * 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 async function applyCustomFtlFile(ctx, affectedPaths, stepErrors, rollbackJournal) {
     const { engineDir, name, componentDir, ftlDir } = ctx;
@@ -134,7 +134,7 @@ export async function applyCustomFtlFile(ctx, affectedPaths, stepErrors, rollbac
         await snapshotFile(rollbackJournal, ftlDest);
     }
     await copyFile(ftlSrc, ftlDest);
-    // Sibling pushes on this list are POSIX literals (`localeJarRel`); keep
+    // Sibling pushes on this list are POSIX literals (`localeJarRel`). Keep
     // the computed one in the same spelling.
     affectedPaths.push(normalizePathSlashes(relative(engineDir, ftlDest)));
     const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
@@ -185,7 +185,7 @@ export function describeLocaleFtlJarMnRegistration(name, ftlDir, ftlFile) {
 }
 /**
  * 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.