@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,531 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { randomUUID } from 'node:crypto';
-import { mkdir, rename, rm, stat } from 'node:fs/promises';
-import { dirname } from 'node:path';
-import { LockContentionError } from '../errors/base.js';
-import { getNodeErrorCode, toError } from '../utils/errors.js';
-import { ensureDir } from '../utils/fs.js';
-import { verbose, warn } from '../utils/logger.js';
-import { sleep } from '../utils/sleep.js';
-import { isLockOwnerAlive, LOCK_PID_FILE, readLockOwner, writeLockOwner, } from './file-lock-owner.js';
-import { readLockQueue, registerWaiter, } from './file-lock-queue.js';
-import { countLiveSharedHolders, registerSharedHold, releaseSharedHoldsForSignal, } from './file-lock-shared.js';
-export { LOCK_PID_FILE };
-export { formatLockQueuePosition } from './file-lock-queue.js';
-const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
-const DEFAULT_LOCK_POLL_MS = 50;
-const DEFAULT_STALE_LOCK_MS = 5 * 60_000;
-/**
- * Minimum interval between stale-lock probes while a waiter polls. Probing
- * exactly once per waiter means a holder that dies after that probe leaves
- * the waiter polling a permanently dead lock until `timeoutMs`, up to 24
- * hours for the build lock (see `withBuildLock` in mach.ts). Re-probing on a
- * small interval bounds that to seconds while keeping the per-poll cost
- * negligible: one stat plus one small read every ~5 s.
- */
-const STALE_REPROBE_INTERVAL_MS = 5_000;
-/**
- * Default interval between wait probes (holder + queue) when a caller wants
- * deadline extension but no progress line of its own.
- */
-const WAIT_PROBE_INTERVAL_MS = 5_000;
-/** Derives the sibling lock-directory path used to guard a file-based resource. */
-export function createSiblingLockPath(filePath, suffix = '.fireforge.lock') {
-    return `${filePath}${suffix}`;
-}
-/**
- * Inspects a lock without acquiring it. Read-only and fail-open: a missing
- * lock is reported as free, never as an error.
- */
-export async function readLockStatus(lockPath) {
-    const queue = await readLockQueue(lockPath);
-    const shared = await countLiveSharedHolders(lockPath, { reap: false });
-    const sharedPart = shared > 0 ? { sharedHolders: shared } : {};
-    let heldForMs;
-    try {
-        // Clamped: filesystem mtime resolution can round a just-created lock
-        // fractionally ahead of `Date.now()`, and a negative age is nonsense
-        // in a status report.
-        heldForMs = Math.max(0, Date.now() - (await stat(lockPath)).mtimeMs);
-    }
-    catch {
-        return { held: false, queueDepth: queue.depth, ...sharedPart };
-    }
-    const owner = await readLockOwner(lockPath);
-    const holder = owner.present
-        ? { pid: owner.pid, alive: isLockOwnerAlive(owner), metadata: owner.metadata }
-        : undefined;
-    return { held: true, holder, heldForMs, queueDepth: queue.depth, ...sharedPart };
-}
-/**
- * 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`, since a diagnostic must never break the
- * wait loop.
- */
-async function probeWaitState(lockPath, self) {
-    const owner = await readLockOwner(lockPath);
-    const holder = owner.present
-        ? { pid: owner.pid, alive: isLockOwnerAlive(owner), metadata: owner.metadata }
-        : undefined;
-    return { holder, queue: await readLockQueue(lockPath, self) };
-}
-/**
- * Reaps a lock directory believed to be stale, safely against concurrent
- * reapers and a concurrent legitimate re-acquisition.
- *
- * 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, 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
- * lock was released and re-acquired between the staleness read and the
- * rename), it is renamed back instead of reaped.
- *
- * @returns true when the caller should immediately retry `mkdir` (the lock
- *   path is now free or was freed by someone else), false when the lock is
- *   legitimately held and the caller should keep waiting.
- */
-async function reapStaleLock(lockPath, ageMs, onStaleLockMessage) {
-    const reapPath = `${lockPath}.reaping-${process.pid}-${randomUUID()}`;
-    try {
-        await rename(lockPath, reapPath);
-    }
-    catch (error) {
-        if (getNodeErrorCode(error) === 'ENOENT') {
-            // Another reaper won, or the owner released. Either way, retry mkdir.
-            verbose(`Stale lock disappeared before reaping completed: ${lockPath}`);
-            return true;
-        }
-        verbose(`Could not rename stale lock aside (${lockPath}): ${toError(error).message}`);
-        return false;
-    }
-    // We exclusively own reapPath now. Re-verify: the owner may have changed
-    // between the staleness probe and the rename (release + fresh acquire).
-    const owner = await readLockOwner(reapPath);
-    if (owner.present && isLockOwnerAlive(owner)) {
-        try {
-            await rename(reapPath, lockPath);
-            verbose(`Aborted stale-lock reap of ${lockPath}: owner PID ${owner.pid} is alive (lock was re-acquired mid-probe)`);
-        }
-        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, 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.`);
-        }
-        return false;
-    }
-    const staleMessage = onStaleLockMessage?.(ageMs);
-    if (staleMessage) {
-        warn(staleMessage);
-    }
-    else {
-        verbose(`Removing stale lock ${lockPath} (age: ${Math.round(ageMs / 1000)}s)`);
-    }
-    await rm(reapPath, { recursive: true, force: true });
-    return true;
-}
-/**
- * Probes a contended lock for staleness and reaps it when the owner is gone.
- *
- * @returns true when the caller should immediately retry `mkdir`.
- */
-async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
-    try {
-        const lockStat = await stat(lockPath);
-        const ageMs = Date.now() - lockStat.mtimeMs;
-        // 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. 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);
-        if (owner.present) {
-            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), 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`);
-            return false;
-        }
-        // No readable PID file. Fall back to the age-only heuristic so locks
-        // written by earlier FireForge releases (which may not have written a
-        // PID file) still clear after the staleness window elapses.
-        if (ageMs <= staleMs) {
-            return false;
-        }
-        return await reapStaleLock(lockPath, ageMs, onStaleLockMessage);
-    }
-    catch (error) {
-        const code = getNodeErrorCode(error);
-        if (code === 'ENOENT') {
-            verbose(`Stale lock disappeared before cleanup completed: ${lockPath}`);
-            return true;
-        }
-        verbose(`Stale lock check failed for ${lockPath}: ${toError(error).message}`);
-        throw toError(error);
-    }
-}
-/**
- * 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)
- * 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.
- *
- * The owner record is always present here: `writeLockOwner` is fatal, so an
- * acquisition whose record failed to write never reached the operation.
- */
-async function releaseLock(lockPath, ownerToken) {
-    const owner = await readLockOwner(lockPath);
-    if (owner.present &&
-        (owner.pid !== process.pid || (owner.token !== undefined && owner.token !== ownerToken))) {
-        warn(`Not removing lock ${lockPath}: it is now owned by PID ${owner.pid} — ` +
-            'this process no longer holds it.');
-        return;
-    }
-    await rm(lockPath, { recursive: true, force: true });
-}
-/**
- * Removes a lock directory only if this process still owns it, for callers
- * that hold no acquisition token.
- *
- * The ownership half of {@link releaseLock}, minus the token check: a
- * signal-time sweeper knows which lock paths its own operations opened, but
- * not the per-acquisition UUID those acquisitions minted. The PID check is
- * still the one that matters: it stops the sweeper deleting a lock a
- * different process acquired in the window between our operation dying and
- * the sweep running.
- *
- * Never throws: callers are shutdown paths where a slow or failing I/O must
- * not prevent the process from exiting. Returns whether the directory was
- * removed so callers can log accurately.
- *
- * @param lockPath - Lock directory to remove
- * @returns True when the lock was removed, false when it was left in place
- */
-export async function releaseLockIfOwned(lockPath) {
-    try {
-        const owner = await readLockOwner(lockPath);
-        if (owner.present && owner.pid !== process.pid) {
-            return false;
-        }
-        await rm(lockPath, { recursive: true, force: true });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Builds the contention refusal thrown when the wait budget expires.
- *
- * Typed as {@link LockContentionError} (a `FireForgeError`) so the CLI
- * boundary prints the refusal as one clean line instead of an "Unexpected
- * error" stack. Callers supplying `onTimeoutMessage` still get the holder
- * identification appended: the reason-first copy stays theirs, the "who
- * holds it" is ours.
- *
- * `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);
-    const liveHolder = owner.present && isLockOwnerAlive(owner) ? owner : undefined;
-    const details = liveHolder !== undefined && liveHolder.metadata.length > 0
-        ? ` (${liveHolder.metadata.join(', ')})`
-        : '';
-    const position = formatQueuePositionReached(queue);
-    if (onTimeoutMessage !== undefined) {
-        const identifiedHolder = liveHolder !== undefined ? ` The lock is held by PID ${liveHolder.pid}${details}.` : '';
-        return new LockContentionError(`${onTimeoutMessage}${identifiedHolder}${position}`, cause);
-    }
-    const holderHint = liveHolder !== undefined
-        ? ` It is held by running process ${liveHolder.pid}${details} — wait for it to finish, or stop it and retry.`
-        : ' If no other FireForge process is running, remove the lock directory and retry.';
-    return new LockContentionError(`Timed out waiting for file lock ${lockPath}.${holderHint}${position}`, cause);
-}
-/**
- * States the queue position the expired wait actually reached.
- *
- * 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, 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 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 has one.
- */
-function formatQueuePositionReached(queue) {
-    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.`;
-    }
-    return ` You were still ${queue.ahead} from the head of a queue of ${queue.depth} when the wait expired; re-run with a larger --wait-lock.`;
-}
-/**
- * Runs one wait probe: reads holder and queue, and reports progress when the
- * caller asked for it. Split out of the wait loop so the loop stays a
- * readable state machine.
- */
-async function runWaitProbe(lockPath, self, timeoutMs, options) {
-    const { holder, queue } = await probeWaitState(lockPath, self);
-    options.onWaitProgress?.({
-        waitedMs: Date.now() - self.startedAt,
-        timeoutMs,
-        holder,
-        queue,
-    });
-    return { queue };
-}
-/**
- * Whether it is this waiter's turn to contend for the lock: no live waiter
- * arrived before it. Ties and dead or stalled tickets are settled by
- * {@link readLockQueue}, so every waiter agrees on who is at the head.
- */
-async function isWaiterTurn(lockPath, startedAt, waiter) {
-    return (await readLockQueue(lockPath, { startedAt, ticket: waiter.ticket })).ahead === 0;
-}
-/**
- * Lock directories this process currently holds.
- *
- * `withFileLock`'s `finally` never runs across a `process.exit`, so a
- * SIGTERM'd command leaves its lock on disk. The next contender reclaims it
- * immediately (the PID-first staleness check sees a dead owner), but in the
- * window between, `fireforge status --lock` reports the lock held by a
- * process that is not running, which is the question an operator asks after
- * a kill. The signal sweep closes that window.
- *
- * Paths only: the per-acquisition token lives in `withFileLock`'s frame and
- * a sweeper cannot see it. {@link releaseLockIfOwned} checks the PID, which
- * is the check that matters: it stops the sweep deleting a lock a
- * different process acquired in the meantime.
- */
-const heldLocks = new Set();
-/**
- * Releases every lock this process still holds, for the signal path.
- *
- * Never throws and never rejects: a shutdown path must not be able to keep
- * the process alive. Returns the paths actually removed so the caller can
- * report accurately.
- */
-export async function forceReleaseHeldLocksForSignal() {
-    const paths = [...heldLocks];
-    const removed = [];
-    for (const lockPath of paths) {
-        heldLocks.delete(lockPath);
-        if (await releaseLockIfOwned(lockPath)) {
-            removed.push(lockPath);
-        }
-    }
-    removed.push(...(await releaseSharedHoldsForSignal()));
-    return removed;
-}
-/** Runs an async operation while holding a directory lock, with stale-lock recovery. */
-export async function withFileLock(lockPath, operation, options = {}) {
-    const timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
-    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 startedAt = Date.now();
-    const extend = options.extendWhileAdvancing;
-    const hardDeadline = extend !== undefined ? startedAt + extend.maxWaitMs : undefined;
-    let deadline = startedAt + timeoutMs;
-    let lastStaleProbeAt;
-    let currentPollMs = pollMs;
-    let lastProbeAt = startedAt;
-    /** Best (lowest) queue position seen so far. Used to detect an advance. */
-    let bestAhead;
-    /**
-     * This waiter's ticket in the queue. Taken on first contention, or up
-     * front when others are already queued, so an uncontended acquire never
-     * writes one.
-     */
-    let waiter;
-    /** The last `EEXIST`, carried as the cause of a timeout refusal. */
-    let contention;
-    // One cadence drives both the progress line and the deadline extension.
-    // Either feature alone is enough to want the probe. Neither is worth a
-    // second timer.
-    const probeIntervalMs = options.waitProgressMs ?? WAIT_PROBE_INTERVAL_MS;
-    const probeWanted = (options.onWaitProgress !== undefined && options.waitProgressMs !== undefined) ||
-        extend !== undefined;
-    await ensureDir(dirname(lockPath));
-    try {
-        // Arrival order: a newcomer that finds others already queued takes a
-        // ticket behind them instead of racing them for the next free moment.
-        // Without this a fresh command could take the lock in the gap between
-        // the holder's release and the head waiter's next poll.
-        if ((await readLockQueue(lockPath)).depth > 0) {
-            waiter = await registerWaiter(lockPath, startedAt);
-        }
-        for (;;) {
-            // Only the head of the queue contends for the lock. A waiter without
-            // a ticket (no contention seen yet, or a registry that could not be
-            // written) contends as every waiter did before tickets existed.
-            if (waiter?.ticket === undefined || (await isWaiterTurn(lockPath, startedAt, waiter))) {
-                try {
-                    await mkdir(lockPath);
-                    break;
-                }
-                catch (error) {
-                    if (getNodeErrorCode(error) !== 'EEXIST') {
-                        throw error;
-                    }
-                    contention = error;
-                }
-            }
-            // Take a ticket so the queue is visible to the wait output and to
-            // `fireforge status --lock`, and so the grant follows arrival order.
-            waiter ??= await registerWaiter(lockPath, startedAt);
-            await waiter.heartbeat();
-            const self = { startedAt, ticket: waiter.ticket };
-            if (lastStaleProbeAt === undefined || Date.now() - lastStaleProbeAt >= staleReprobeMs) {
-                lastStaleProbeAt = Date.now();
-                if (await removeIfStaleLock(lockPath, staleMs, options.onStaleLockMessage)) {
-                    continue;
-                }
-            }
-            // The probe runs before the deadline check, so a due progress line is
-            // written before the refusal that follows it, never lost to it. On a
-            // slow host (a cold Windows CI runner) the first iteration alone, with
-            // its waiter registration and stale probe, can outlast a short budget;
-            // checked the other way round, the wait timed out having reported
-            // nothing, and an advance that probe would have seen could not extend
-            // the deadline it was about to miss.
-            if (probeWanted && Date.now() - lastProbeAt >= probeIntervalMs) {
-                lastProbeAt = Date.now();
-                // Report the budget that is currently in force, not the one
-                // originally requested: once an extension has been granted, the
-                // requested figure is stale, and a progress line that keeps
-                // quoting it reads as a timeout that does not fire.
-                const probe = await runWaitProbe(lockPath, self, deadline - startedAt, options);
-                // 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. Counted as an
-                // advance, the opening probe would hand out a free full budget: a
-                // `--wait-lock 300` run would outlive its 300 s even against a queue
-                // that never moved once.
-                if (hardDeadline !== undefined) {
-                    if (bestAhead === undefined) {
-                        bestAhead = probe.queue.ahead;
-                    }
-                    else if (probe.queue.ahead < bestAhead) {
-                        bestAhead = probe.queue.ahead;
-                        deadline = Math.min(Date.now() + timeoutMs, hardDeadline);
-                        options.onWaitExtended?.({
-                            ahead: probe.queue.ahead,
-                            budgetMs: deadline - startedAt,
-                        });
-                    }
-                }
-            }
-            if (Date.now() >= deadline) {
-                // 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. The ticket is returned in the `finally`
-                // below, which is only entered once this refusal has been built.
-                throw await buildLockTimeoutError(lockPath, options.onTimeoutMessage, contention, await readLockQueue(lockPath, self));
-            }
-            await sleep(currentPollMs);
-            if (options.pollMaxMs !== undefined) {
-                currentPollMs = Math.min(currentPollMs * 2, options.pollMaxMs);
-            }
-        }
-    }
-    finally {
-        // Leaving the queue happens the moment we stop waiting, whether we
-        // acquired the lock or timed out.
-        await waiter?.deregister();
-    }
-    // Stamp ownership (PID + per-acquisition token + acquisition time) into
-    // the lock directory so stale-lock recovery can check liveness and release
-    // can verify the lock is still ours before removing it. Fatal on failure:
-    // an owner-less lock is reaped by the age heuristic after five minutes,
-    // which for a multi-hour build meant a second holder mid-critical-section.
-    // `writeLockOwner` removes the just-created directory before throwing.
-    const ownerToken = randomUUID();
-    await writeLockOwner(lockPath, ownerToken, options.ownerMetadata);
-    return runWhileHeld(lockPath, ownerToken, operation, options, {
-        deadline: Math.max(deadline, Date.now() + pollMs),
-        pollMs,
-    });
-}
-/**
- * Runs `operation` once the turnstile is ours: as a shared holder (turnstile
- * released at once), or exclusively once every shared holder has drained.
- */
-async function runWhileHeld(lockPath, ownerToken, operation, options, drain) {
-    if (options.mode === 'shared') {
-        // The exclusive lock was only the turnstile: record the shared hold and
-        // let the next waiter in. See file-lock-shared.ts.
-        let hold;
-        try {
-            hold = await registerSharedHold(lockPath, options.ownerMetadata);
-        }
-        finally {
-            await releaseLock(lockPath, ownerToken);
-        }
-        try {
-            return await operation();
-        }
-        finally {
-            await hold.release();
-        }
-    }
-    heldLocks.add(lockPath);
-    try {
-        await waitForSharedHoldersToDrain(lockPath, drain.deadline, drain.pollMs);
-        return await operation();
-    }
-    finally {
-        heldLocks.delete(lockPath);
-        await releaseLock(lockPath, ownerToken);
-    }
-}
-/**
- * Holds an exclusive acquisition until every live shared holder has gone.
- * The turnstile is already ours, so no new shared holder can join meanwhile.
- *
- * @throws LockContentionError when shared holders outlast the budget
- */
-async function waitForSharedHoldersToDrain(lockPath, deadline, pollMs) {
-    let announced = false;
-    for (;;) {
-        const live = await countLiveSharedHolders(lockPath);
-        if (live === 0)
-            return;
-        if (Date.now() >= deadline) {
-            throw new LockContentionError(`Timed out waiting for file lock ${lockPath}: ${live} shared holder(s) (build-less ` +
-                'test runs under a shared lock) still hold it. Wait for them to finish, or retry ' +
-                'with a larger --wait-lock.');
-        }
-        if (!announced) {
-            verbose(`Waiting for ${live} shared holder(s) of ${lockPath} to finish.`);
-            announced = true;
-        }
-        await sleep(Math.max(pollMs, 100));
-    }
-}

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

@@ -1,45 +0,0 @@
-/**
- * Archive metadata validation and archive identity resolution.
- */
-import type { FirefoxProduct } from '../types/config.js';
-/**
- * Resolved archive descriptor for URL generation and cache storage.
- */
-export interface ResolvedArchive {
-    requestedVersion: string;
-    product: FirefoxProduct;
-    archiveVersion: string;
-    url: string;
-    filename: string;
-    metadataFilename: string;
-    /** URL of Mozilla's published SHA256SUMS file for the release. */
-    checksumsUrl: string;
-    /** The archive's path as listed inside SHA256SUMS (relative to the release dir). */
-    pathInChecksums: string;
-}
-/**
- * Sidecar metadata stored alongside a cached archive.
- */
-export interface ArchiveMetadata {
-    requestedVersion: string;
-    product: FirefoxProduct;
-    archiveVersion: string;
-    url: string;
-    contentLength?: number | undefined;
-    sha256?: string | undefined;
-    downloadedAt: string;
-}
-/**
- * Validates raw JSON data as ArchiveMetadata.
- * @param data - Unknown data to validate
- * @returns Validated ArchiveMetadata
- */
-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, candidate?: string): ResolvedArchive;

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

@@ -1,96 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Archive metadata validation and archive identity resolution.
- */
-import { ConfigError } from '../errors/config.js';
-import { parseObject } from '../utils/parse.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';
-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
- * @returns Validated ArchiveMetadata
- */
-export function validateArchiveMetadata(data) {
-    const rec = parseObject(data, 'Archive metadata');
-    const requestedVersion = rec.string('requestedVersion');
-    const product = rec.stringEnum('product', (v) => isValidFirefoxProduct(v), 'a supported Firefox product');
-    const archiveVersion = rec.string('archiveVersion');
-    const url = rec.string('url');
-    const downloadedAt = rec.string('downloadedAt');
-    const contentLength = rec.optionalNonNegativeInteger('contentLength');
-    const sha256 = rec.optionalString('sha256');
-    return {
-        requestedVersion,
-        product,
-        archiveVersion,
-        url,
-        downloadedAt,
-        ...(contentLength !== undefined ? { contentLength } : {}),
-        ...(sha256 !== undefined ? { sha256 } : {}),
-    };
-}
-/**
- * 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', 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.
-    const cleanVersion = version.replace(/esr$/i, '');
-    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: `${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: `${dirUrl}/SHA256SUMS`,
-        pathInChecksums: `source/firefox-${archiveVersion}.source.tar.xz`,
-    };
-}