@hominis/fireforge 0.37.0 → 0.39.0

package/dist/src/core/discard-baseline.js

@@ -0,0 +1,232 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Patch-aware restore planning for `fireforge discard` (FORGE F1, P0).
+ *
+ * The engine convention is: HEAD = pristine upstream Firefox, and the
+ * applied patch queue lives as UNCOMMITTED worktree changes on top of it
+ * (`git apply` without `--index` → patch-edited tracked files are unstaged
+ * modifications, patch-created files are untracked). The pre-0.39.0
+ * `discard` was purely git-mechanical — it restored to HEAD and deleted
+ * untracked files, silently reverting patch-backed files PAST their owning
+ * patch and deleting patch-created files outright.
+ *
+ * This module classifies each status entry against the patch manifest's
+ * ownership claims and plans the correct restore target: the PATCH-APPLIED
+ * baseline (HEAD content folded through every affecting patch in order) for
+ * claimed files, and the legacy git mechanics for unmanaged ones.
+ */
+import { join } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { readText, removeFile, writeText } from '../utils/fs.js';
+import { discardStatusEntry, fileExistsInHead, listTrackedInHead, restoreTrackedPath, unstageFiles, } from './git-file-ops.js';
+import { createPatchedContentComputer } from './patch-apply.js';
+import { loadPatchesManifestState } from './patch-manifest-io.js';
+import { parseDiffSections } from './patch-parse.js';
+import { buildPatchClaims } from './status-classify.js';
+/** Builds an all-unmanaged plan set — the `--to-upstream` (legacy) shape. */
+export function planUpstreamDiscards(entries) {
+    return entries.map((entry) => ({ entry, kind: 'unmanaged', owners: [], conflicted: false }));
+}
+/**
+ * Plans the restore target for each status entry. Entries claimed by the
+ * patch manifest restore to the patch-applied baseline; unclaimed entries
+ * keep the legacy git mechanics. A missing patches dir or empty manifest
+ * degrades every plan to `unmanaged` (identical to pre-0.39.0 behavior).
+ *
+ * A corrupt manifest or an unreconstructible patch baseline REFUSES with a
+ * GeneralError naming `--to-upstream` — silently falling back to pristine
+ * HEAD is exactly the data-loss path this module exists to close.
+ */
+export async function planDiscardBaselines(patchesDir, engineDir, entries) {
+    const state = await loadPatchesManifestState(patchesDir);
+    if (state.exists && state.parseError) {
+        throw new GeneralError('patches/patches.json is unreadable — refusing to discard while patch ownership cannot be ' +
+            'determined. Fix the manifest, or pass --to-upstream to explicitly revert to pristine ' +
+            'upstream (HEAD).');
+    }
+    const claims = state.manifest
+        ? buildPatchClaims(state.manifest.patches)
+        : new Map();
+    const plans = [];
+    const claimedEntries = entries.filter((entry) => claims.has(entry.file) || (entry.originalPath !== undefined && claims.has(entry.originalPath)));
+    if (claimedEntries.length === 0) {
+        return planUpstreamDiscards(entries);
+    }
+    const computePatched = await createPatchedContentComputer(patchesDir, engineDir);
+    const claimedFiles = [
+        ...new Set(claimedEntries.flatMap((entry) => entry.originalPath !== undefined ? [entry.file, entry.originalPath] : [entry.file])),
+    ];
+    const trackedInHead = await listTrackedInHead(engineDir, claimedFiles);
+    const computeExpected = async (path) => {
+        try {
+            return await computePatched(path);
+        }
+        catch (error) {
+            throw new GeneralError(`Cannot reconstruct the patch baseline for ${path} (${toError(error).message}). ` +
+                'Fix the owning patch, or pass --to-upstream to explicitly revert to pristine ' +
+                'upstream (HEAD).');
+        }
+    };
+    // `computePatchedContent` folds a deletion into an empty string (an
+    // apply-to-content limitation), which is indistinguishable from a
+    // legitimately empty file. Consult the owning patches' diff sections
+    // directly: the LAST section (highest-ordered owner) naming the path
+    // decides whether the baseline is "absent".
+    const sectionCache = new Map();
+    const isDeletedAtBaseline = async (path, owners) => {
+        for (let i = owners.length - 1; i >= 0; i--) {
+            const owner = owners[i];
+            if (owner === undefined)
+                continue;
+            let sections = sectionCache.get(owner);
+            if (!sections) {
+                try {
+                    sections = parseDiffSections(await readText(join(patchesDir, owner)));
+                }
+                catch {
+                    sections = [];
+                }
+                sectionCache.set(owner, sections);
+            }
+            for (const section of sections) {
+                if (section.targetPath === path || section.sourcePath === path) {
+                    return section.isDeletedFile;
+                }
+            }
+        }
+        return false;
+    };
+    for (const entry of entries) {
+        const owners = [
+            ...new Set([
+                ...(claims.get(entry.file) ?? []),
+                ...(entry.originalPath !== undefined ? (claims.get(entry.originalPath) ?? []) : []),
+            ]),
+        ];
+        if (owners.length === 0) {
+            plans.push({ entry, kind: 'unmanaged', owners, conflicted: false });
+            continue;
+        }
+        let expectedContent = claims.has(entry.file) ? await computeExpected(entry.file) : null;
+        if (expectedContent !== null &&
+            (await isDeletedAtBaseline(entry.file, claims.get(entry.file) ?? []))) {
+            expectedContent = null;
+        }
+        const expectedOriginalContent = entry.originalPath !== undefined && claims.has(entry.originalPath)
+            ? await computeExpected(entry.originalPath)
+            : undefined;
+        const kind = expectedContent === null
+            ? 'patch-deleted'
+            : trackedInHead.has(entry.file)
+                ? 'patch-backed'
+                : 'patch-created';
+        plans.push({
+            entry,
+            kind,
+            owners,
+            conflicted: owners.length > 1,
+            expectedContent,
+            ...(expectedOriginalContent !== undefined ? { expectedOriginalContent } : {}),
+        });
+    }
+    return plans;
+}
+/**
+ * Applies one restore plan. Patch-claimed paths end up exactly as `import`
+ * leaves them: patched content as an unstaged worktree state (tracked files
+ * read ` M`, created files `??`), nothing staged. Unmanaged plans delegate
+ * to the legacy {@link discardStatusEntry} mechanics.
+ */
+export async function applyDiscardBaseline(engineDir, plan) {
+    if (plan.kind === 'unmanaged') {
+        await discardStatusEntry(engineDir, plan.entry);
+        return;
+    }
+    const { entry } = plan;
+    // Drop any staged edits/adds/renames first so the rewritten content is a
+    // plain worktree state (harmless when nothing is staged; skipped for
+    // purely-untracked entries which have no index footprint).
+    if (!entry.isUntracked) {
+        const indexPaths = entry.originalPath !== undefined ? [entry.file, entry.originalPath] : [entry.file];
+        await unstageFiles(engineDir, indexPaths);
+    }
+    if (plan.expectedContent === null || plan.expectedContent === undefined) {
+        await removeFile(join(engineDir, entry.file));
+    }
+    else {
+        await writeText(join(engineDir, entry.file), plan.expectedContent);
+    }
+    // A rename/copy's original side restores to ITS baseline too: the patch
+    // baseline when claimed, else the legacy HEAD restore (matching what
+    // discardStatusEntry does for that side).
+    if (entry.originalPath !== undefined) {
+        if (plan.expectedOriginalContent !== undefined) {
+            if (plan.expectedOriginalContent === null) {
+                await removeFile(join(engineDir, entry.originalPath));
+            }
+            else {
+                await writeText(join(engineDir, entry.originalPath), plan.expectedOriginalContent);
+            }
+        }
+        else if (await fileExistsInHead(engineDir, entry.originalPath)) {
+            await restoreTrackedPath(engineDir, entry.originalPath);
+        }
+    }
+}
+/** One-line annotation for dry-run listings and confirmation summaries. */
+export function describeDiscardBaseline(plan) {
+    const owners = plan.owners.join(' + ');
+    switch (plan.kind) {
+        case 'unmanaged':
+            return plan.entry.isUntracked ? 'unmanaged — delete' : 'unmanaged — revert to upstream';
+        case 'patch-backed':
+            return `patch baseline: ${owners}${plan.conflicted ? ' (conflict)' : ''}`;
+        case 'patch-created':
+            return `re-materialize from ${owners}${plan.conflicted ? ' (conflict)' : ''}`;
+        case 'patch-deleted':
+            return `delete — ${owners} removes it`;
+    }
+}
+/** Single-file outro naming the baseline that was restored. */
+export function describeDiscardOutcome(plan, toUpstream) {
+    if (toUpstream)
+        return 'File restored to pristine upstream (HEAD)';
+    const owners = plan.owners.join(' + ');
+    switch (plan.kind) {
+        case 'unmanaged':
+            return 'File restored to original state';
+        case 'patch-backed':
+            return `File restored to patch baseline (${owners})`;
+        case 'patch-created':
+            return `File re-materialized from patch baseline (${owners})`;
+        case 'patch-deleted':
+            return `File removed to match patch baseline (${owners} deletes it)`;
+    }
+}
+/** Batch outro summarising how many files restored to which baseline. */
+export function summarizeDiscardBaselines(plans, succeeded) {
+    const patchBacked = plans.filter((p) => p.kind === 'patch-backed').length;
+    const created = plans.filter((p) => p.kind === 'patch-created').length;
+    const deleted = plans.filter((p) => p.kind === 'patch-deleted').length;
+    const unmanaged = plans.filter((p) => p.kind === 'unmanaged').length;
+    if (patchBacked + created + deleted === 0) {
+        return `${String(succeeded)} file(s) restored to upstream state`;
+    }
+    const parts = [];
+    if (patchBacked > 0)
+        parts.push(`${String(patchBacked)} to patch baseline`);
+    if (created > 0)
+        parts.push(`${String(created)} re-materialized`);
+    if (deleted > 0)
+        parts.push(`${String(deleted)} removed per patch baseline`);
+    if (unmanaged > 0)
+        parts.push(`${String(unmanaged)} to upstream state`);
+    return `${String(succeeded)} file(s) restored: ${parts.join(', ')}`;
+}
+/** Warn text for a multi-owner (conflicted) restore. */
+export function describeConflictWarning(plan) {
+    return (`${plan.entry.file} is claimed by ${String(plan.owners.length)} patches ` +
+        `(${plan.owners.join(', ')}). Restored the cumulative baseline; run ` +
+        '"fireforge status --ownership" to resolve ownership.');
+}

package/dist/src/core/engine-session-lock.d.ts

@@ -1,7 +1,16 @@
+export interface EngineSessionLockOptions {
+    /**
+     * Wait up to this many seconds for the engine session lock instead of the
+     * legacy ~1 s fail-fast. Enables exponential poll backoff (100 ms → 2 s)
+     * and a holder-identified progress line roughly every 5 s. `undefined`
+     * preserves the historical fail-fast behavior exactly.
+     */
+    waitLockSeconds?: number | undefined;
+}
 /**
  *
  */
-export declare function withEngineSessionLock<T>(projectRoot: string, command: string, operation: () => Promise<T>): Promise<T>;
+export declare function withEngineSessionLock<T>(projectRoot: string, command: string, operation: () => Promise<T>, options?: EngineSessionLockOptions): Promise<T>;
 /**
  *
  */

package/dist/src/core/engine-session-lock.js

@@ -1,19 +1,45 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { GeneralError } from '../errors/base.js';
+import { info } from '../utils/logger.js';
 import { withFileLock } from './file-lock.js';
 import { git } from './git-base.js';
 const ENGINE_SESSION_LOCK_PATH = join('.fireforge', 'engine-session.lock');
+/**
+ * Formats the periodic operator-facing waiting line printed while `--wait-lock`
+ * polls a contended engine session lock. The holder identification comes from
+ * the lock's owner-metadata lines (`command=…`, `started=…`); an unreadable
+ * owner file degrades to the anonymous form.
+ */
+function formatWaitProgressLine(waitedMs, timeoutMs, holder) {
+    const progress = `${String(Math.round(waitedMs / 1000))}s of up to ${String(Math.round(timeoutMs / 1000))}s`;
+    if (holder === undefined) {
+        return `Waiting for the FireForge engine lock — ${progress}.`;
+    }
+    const details = holder.metadata.length > 0 ? ` (${holder.metadata.join(', ')})` : '';
+    return `Waiting for the FireForge engine lock held by PID ${String(holder.pid)}${details} — ${progress}.`;
+}
 /**
  *
  */
-export async function withEngineSessionLock(projectRoot, command, operation) {
+export async function withEngineSessionLock(projectRoot, command, operation, options = {}) {
     if (process.env['FIREFORGE_ENABLE_ENGINE_SESSION_LOCK_IN_TEST'] !== '1' &&
         (process.env['NODE_ENV'] === 'test' || process.env['VITEST'] !== undefined)) {
         return operation();
     }
+    const { waitLockSeconds } = options;
     return withFileLock(join(projectRoot, ENGINE_SESSION_LOCK_PATH), operation, {
-        timeoutMs: 1000,
+        timeoutMs: waitLockSeconds !== undefined ? waitLockSeconds * 1000 : 1000,
+        ...(waitLockSeconds !== undefined
+            ? {
+                pollMs: 100,
+                pollMaxMs: 2000,
+                waitProgressMs: 5000,
+                onWaitProgress: ({ waitedMs, timeoutMs, holder }) => {
+                    info(formatWaitProgressLine(waitedMs, timeoutMs, holder));
+                },
+            }
+            : {}),
         ownerMetadata: [`command=${command}`, `started=${new Date().toISOString()}`],
         onTimeoutMessage: `Another FireForge engine-mutating command is already running. ` +
             `Wait for it to finish, then retry \`${command}\`.`,

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

@@ -1,6 +1,23 @@
+/**
+ * Snapshot of the current lock holder handed to {@link FileLockOptions.onWaitProgress}.
+ * `metadata` carries the pid file's human-diagnostic lines (line 3 onward,
+ * e.g. `command=build`, `started=…`) written via
+ * {@link FileLockOptions.ownerMetadata}.
+ */
+export interface LockHolder {
+    pid: number;
+    alive: boolean;
+    metadata: string[];
+}
 export interface FileLockOptions {
     timeoutMs?: number;
     pollMs?: number;
+    /**
+     * 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.
+     */
+    pollMaxMs?: number;
     staleMs?: number;
     /**
      * Interval between stale-lock probes while waiting (defaults to
@@ -8,6 +25,22 @@ export interface FileLockOptions {
      * the mid-wait reaping path without multi-second sleeps.
      */
     staleReprobeMs?: number;
+    /**
+     * Interval between {@link onWaitProgress} callbacks while the lock is
+     * contended. Progress reporting is off unless both this and
+     * `onWaitProgress` are set.
+     */
+    waitProgressMs?: number;
+    /**
+     * Invoked roughly every `waitProgressMs` while waiting for a contended
+     * lock. `holder` is `undefined` when the owner PID file is missing or
+     * unreadable.
+     */
+    onWaitProgress?: (progress: {
+        waitedMs: number;
+        timeoutMs: number;
+        holder: LockHolder | undefined;
+    }) => void;
     onTimeoutMessage?: string;
     onStaleLockMessage?: (ageMs: number) => string | undefined;
     /** Extra owner-file lines for human diagnostics; ignored by lock mechanics. */

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

@@ -50,7 +50,8 @@ function isProcessAlive(pid) {
     }
 }
 /**
- * Reads the owner PID (line 1) and acquisition token (line 2) from a lock
+ * Reads the owner PID (line 1), acquisition token (line 2), and diagnostic
+ * metadata (lines 3+, see {@link FileLockOptions.ownerMetadata}) from a lock
  * directory's PID file. Returns `{ present: false }` when the PID file is
  * missing or the PID does not parse as a finite integer (caller falls back
  * to the age-only staleness heuristic).
@@ -62,14 +63,15 @@ function isProcessAlive(pid) {
 async function readLockOwner(lockPath) {
     try {
         const pidContent = await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8');
-        const [pidLine, tokenLine] = pidContent.split('\n');
+        const [pidLine, tokenLine, ...metadataLines] = pidContent.split('\n');
         const pid = parseInt((pidLine ?? '').trim(), 10);
         if (Number.isFinite(pid)) {
+            const metadata = metadataLines.map((line) => line.trim()).filter((line) => line.length > 0);
             const token = tokenLine?.trim();
             if (token !== undefined && token.length > 0) {
-                return { present: true, pid, token };
+                return { present: true, pid, token, metadata };
             }
-            return { present: true, pid };
+            return { present: true, pid, metadata };
         }
     }
     catch {
@@ -77,6 +79,18 @@ async function readLockOwner(lockPath) {
     }
     return { present: false };
 }
+/**
+ * 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.
+ */
+async function reportWaitProgress(lockPath, waitedMs, timeoutMs, onWaitProgress) {
+    const owner = await readLockOwner(lockPath);
+    const holder = owner.present
+        ? { pid: owner.pid, alive: isProcessAlive(owner.pid), metadata: owner.metadata }
+        : undefined;
+    onWaitProgress({ waitedMs, timeoutMs, holder });
+}
 /**
  * Reaps a lock directory believed to be stale, safely against concurrent
  * reapers and a concurrent legitimate re-acquisition.
@@ -216,8 +230,11 @@ export async function withFileLock(lockPath, operation, options = {}) {
     const pollMs = options.pollMs ?? DEFAULT_LOCK_POLL_MS;
     const staleMs = options.staleMs ?? DEFAULT_STALE_LOCK_MS;
     const staleReprobeMs = options.staleReprobeMs ?? STALE_REPROBE_INTERVAL_MS;
-    const deadline = Date.now() + timeoutMs;
+    const startedAt = Date.now();
+    const deadline = startedAt + timeoutMs;
     let lastStaleProbeAt;
+    let currentPollMs = pollMs;
+    let lastProgressAt = startedAt;
     await ensureDir(dirname(lockPath));
     for (;;) {
         try {
@@ -246,7 +263,16 @@ export async function withFileLock(lockPath, operation, options = {}) {
                     : ' If no other FireForge process is running, remove the lock directory and retry.';
                 throw new Error(options.onTimeoutMessage ?? `Timed out waiting for file lock ${lockPath}.${holderHint}`, { cause: error });
             }
-            await sleep(pollMs);
+            if (options.onWaitProgress !== undefined &&
+                options.waitProgressMs !== undefined &&
+                Date.now() - lastProgressAt >= options.waitProgressMs) {
+                lastProgressAt = Date.now();
+                await reportWaitProgress(lockPath, Date.now() - startedAt, timeoutMs, options.onWaitProgress);
+            }
+            await sleep(currentPollMs);
+            if (options.pollMaxMs !== undefined) {
+                currentPollMs = Math.min(currentPollMs * 2, options.pollMaxMs);
+            }
         }
     }
     // Stamp ownership (PID + per-acquisition token) into the lock directory so

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

@@ -39,6 +39,7 @@ export declare function validateArchiveMetadata(data: unknown): ArchiveMetadata;
  * Resolves archive identity for URL generation and cache storage.
  * @param version - Requested Firefox version
  * @param product - Firefox product type
+ * @param candidate - Optional release-candidate build directory (e.g. "build2")
  * @returns Resolved archive descriptor
  */
-export declare function resolveArchive(version: string, product?: FirefoxProduct): ResolvedArchive;
+export declare function resolveArchive(version: string, product?: FirefoxProduct, candidate?: string): ResolvedArchive;

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

@@ -4,15 +4,26 @@
  */
 import { ConfigError } from '../errors/config.js';
 import { parseObject } from '../utils/parse.js';
-import { isValidFirefoxProduct } from '../utils/validation.js';
+import { isValidFirefoxCandidate, isValidFirefoxProduct } from '../utils/validation.js';
 /**
  * Base URLs for Firefox source archives on archive.mozilla.org.
  */
-const FIREFOX_ARCHIVE_BASE_URL = 'https://archive.mozilla.org/pub/firefox/releases';
-const DEVEDITION_ARCHIVE_BASE_URL = 'https://archive.mozilla.org/pub/devedition/releases';
+const FIREFOX_ARCHIVE_BASE_URL = 'https://archive.mozilla.org/pub/firefox';
+const DEVEDITION_ARCHIVE_BASE_URL = 'https://archive.mozilla.org/pub/devedition';
 function getArchiveBaseUrl(product) {
     return product === 'firefox-devedition' ? DEVEDITION_ARCHIVE_BASE_URL : FIREFOX_ARCHIVE_BASE_URL;
 }
+/**
+ * Directory holding the release's artifacts: `releases/<version>/` for
+ * final releases, `candidates/<version>-candidates/<buildN>/` when a
+ * release-candidate build is requested for pre-release verification.
+ */
+function getArchiveDirUrl(product, archiveVersion, candidate) {
+    const base = getArchiveBaseUrl(product);
+    return candidate === undefined
+        ? `${base}/releases/${archiveVersion}`
+        : `${base}/candidates/${archiveVersion}-candidates/${candidate}`;
+}
 /**
  * Validates raw JSON data as ArchiveMetadata.
  * @param data - Unknown data to validate
@@ -41,13 +52,20 @@ export function validateArchiveMetadata(data) {
  * Resolves archive identity for URL generation and cache storage.
  * @param version - Requested Firefox version
  * @param product - Firefox product type
+ * @param candidate - Optional release-candidate build directory (e.g. "build2")
  * @returns Resolved archive descriptor
  */
-export function resolveArchive(version, product = 'firefox') {
+export function resolveArchive(version, product = 'firefox', candidate) {
     // Reject versions containing path traversal characters
     if (version.includes('/') || version.includes('..') || version.includes('\\')) {
         throw new ConfigError(`Invalid Firefox version "${version}": contains disallowed characters`, 'firefox.version');
     }
+    // Defense-in-depth: config validation enforces this shape already, but a
+    // caller-supplied candidate becomes both a URL path segment and part of
+    // the cache filename, so re-validate here like the version check above.
+    if (candidate !== undefined && !isValidFirefoxCandidate(candidate)) {
+        throw new ConfigError(`Invalid Firefox candidate "${candidate}": must look like "buildN" (e.g. "build2")`, 'firefox.candidate');
+    }
     // ESR status is determined solely by the product field. Config validation
     // ensures product and version are consistent, so we never need to infer
     // ESR from the version string independently.
@@ -55,18 +73,24 @@ export function resolveArchive(version, product = 'firefox') {
     const isEsr = product === 'firefox-esr';
     const archiveVersion = isEsr ? `${cleanVersion}esr` : cleanVersion;
     const safeProduct = product.replace(/[^a-z0-9-]/gi, '-');
+    const dirUrl = getArchiveDirUrl(product, archiveVersion, candidate);
+    // Candidate artifacts get a `-<candidate>` filename suffix so a build2
+    // archive can never collide with the final release artifact (same
+    // archiveVersion, potentially different bytes) in .fireforge/cache.
+    const candidateSuffix = candidate === undefined ? '' : `-${candidate}`;
+    const filename = `firefox-${safeProduct}-${archiveVersion}${candidateSuffix}.source.tar.xz`;
     return {
         requestedVersion: version,
         product,
         archiveVersion,
-        url: `${getArchiveBaseUrl(product)}/${archiveVersion}/source/firefox-${archiveVersion}.source.tar.xz`,
-        filename: `firefox-${safeProduct}-${archiveVersion}.source.tar.xz`,
-        metadataFilename: `firefox-${safeProduct}-${archiveVersion}.source.tar.xz.json`,
+        url: `${dirUrl}/source/firefox-${archiveVersion}.source.tar.xz`,
+        filename,
+        metadataFilename: `${filename}.json`,
         // Mozilla publishes one SHA256SUMS per release directory listing every
         // artifact by its release-relative path. Downloads verify against it by
         // default (fail closed on mismatch), so a compromised CDN response
         // cannot silently become the trusted git baseline.
-        checksumsUrl: `${getArchiveBaseUrl(product)}/${archiveVersion}/SHA256SUMS`,
+        checksumsUrl: `${dirUrl}/SHA256SUMS`,
         pathInChecksums: `source/firefox-${archiveVersion}.source.tar.xz`,
     };
 }

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

@@ -13,16 +13,18 @@ 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): string;
+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): string;
+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
@@ -57,5 +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 candidate - Optional release-candidate build directory (e.g.
+ *   "build2") resolving the archive under `candidates/` instead of
+ *   `releases/`.
  */
-export declare function downloadFirefoxSource(version: string, product: FirefoxProduct, destDir: string, cacheDir: string, onProgress?: ProgressCallback, onPhase?: FirefoxSourcePhaseCallback, expectedSha256?: string, onPhaseProgress?: FirefoxSourceProgressCallback): Promise<void>;
+export declare function downloadFirefoxSource(version: string, product: FirefoxProduct, destDir: string, cacheDir: string, onProgress?: ProgressCallback, onPhase?: FirefoxSourcePhaseCallback, expectedSha256?: string, onPhaseProgress?: FirefoxSourceProgressCallback, candidate?: string): Promise<void>;

package/dist/src/core/firefox.js

@@ -19,19 +19,21 @@ 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') {
-    return resolveArchive(version, product).url;
+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') {
-    return resolveArchive(version, product).filename;
+export function getTarballFilename(version, product = 'firefox', candidate) {
+    return resolveArchive(version, product, candidate).filename;
 }
 /**
  * Classifies an extraction failure as archive corruption (invalidate the
@@ -100,9 +102,12 @@ 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 candidate - Optional release-candidate build directory (e.g.
+ *   "build2") resolving the archive under `candidates/` instead of
+ *   `releases/`.
  */
-export async function downloadFirefoxSource(version, product, destDir, cacheDir, onProgress, onPhase, expectedSha256, onPhaseProgress) {
-    const archive = resolveArchive(version, product);
+export async function downloadFirefoxSource(version, product, destDir, cacheDir, onProgress, onPhase, expectedSha256, onPhaseProgress, candidate) {
+    const archive = resolveArchive(version, product, candidate);
     const tarballPath = join(cacheDir, archive.filename);
     // Ensure cache directory exists
     await ensureDir(cacheDir);

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

@@ -27,10 +27,33 @@ export function hasPositiveTabindex(content) {
         return value !== undefined && parseInt(value, 10) > 0;
     });
 }
+/**
+ * Collects `[start, end)` spans of `<label>…</label>` elements whose content
+ * includes actual label text. Labels cannot nest per HTML, so the non-greedy
+ * inner match is sound. A span qualifies only when the inner content minus
+ * tags still contains non-whitespace — an empty or tag-only wrapper provides
+ * no accessible name. A `${…}` Lit binding counts as label text: dynamic
+ * (usually localized) text is a legitimate accessible name.
+ */
+function collectLabelledSpans(content) {
+    const spans = [];
+    const labelPattern = /<label\b[^>]*>([\s\S]*?)<\/label>/gi;
+    let labelMatch;
+    while ((labelMatch = labelPattern.exec(content)) !== null) {
+        const inner = labelMatch[1] ?? '';
+        if (/\S/.test(inner.replace(/<[^>]*>/g, ' '))) {
+            spans.push({ start: labelMatch.index, end: labelMatch.index + labelMatch[0].length });
+        }
+    }
+    return spans;
+}
 /** Detects form inputs without associated labels. */
 export function hasUnlabelledFormInput(content) {
     // Look for <input> or <select> or <textarea> without aria-label, aria-labelledby, or id
-    // (id implies an external <label for="..."> could exist)
+    // (id implies an external <label for="..."> could exist). A control wrapped
+    // in a <label> that carries actual text is implicitly associated and is
+    // exempt as well.
+    const labelledSpans = collectLabelledSpans(content);
     const inputPattern = /<(input|select|textarea)\b([^>]*)>/gi;
     let inputMatch;
     while ((inputMatch = inputPattern.exec(content)) !== null) {
@@ -41,6 +64,10 @@ export function hasUnlabelledFormInput(content) {
             /type\s*=\s*["']hidden["']/i.test(attrs)) {
             continue;
         }
+        const index = inputMatch.index;
+        if (labelledSpans.some((span) => index >= span.start && index < span.end)) {
+            continue;
+        }
         return true;
     }
     return false;