@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/engine/archive.js

@@ -0,0 +1,396 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The Firefox source archive of a pin: where Mozilla publishes it, the
+ * verified copy in the host cache, and its extraction.
+ *
+ * The archive becomes the commit every owned change is measured against, so
+ * its digest is always checked: against `firefox.sha256` when the project
+ * pins one, otherwise against the `SHA256SUMS` Mozilla publishes beside it.
+ * A digest that cannot be fetched fails the download unless the project
+ * opted into `firefox.allowUnverifiedDownload`, and a cached archive records
+ * how it was verified, so removing that opt-in re-verifies the cache.
+ */
+import { basename, dirname, join } from 'node:path';
+import { ExitCode, FireForgeError, toError } from '../kernel/errors.js';
+import { ensureDir, listDir, makeTempDir, move, pathInfo, remove, writeFileFromStream, } from '../kernel/fs.js';
+import { hashFile } from '../kernel/hash.js';
+import { readJsonIfExists, writeJson } from '../kernel/json.js';
+import { verbose, warn } from '../kernel/log.js';
+import { findExecutable, run } from '../kernel/process/index.js';
+import { s } from '../kernel/schema.js';
+import { tailLines } from '../kernel/text.js';
+import { sleep } from '../kernel/time.js';
+/**
+ * Resolves a pin to its source archive.
+ *
+ * @param pin - The pin
+ */
+export function sourceArchive(pin) {
+    const base = pin.product === 'firefox-devedition'
+        ? 'https://archive.mozilla.org/pub/devedition'
+        : 'https://archive.mozilla.org/pub/firefox';
+    const directory = pin.candidate === undefined
+        ? `${base}/releases/${pin.version}`
+        : `${base}/candidates/${pin.version}-candidates/${pin.candidate}`;
+    const pathInChecksums = `source/firefox-${pin.version}.source.tar.xz`;
+    const candidate = pin.candidate === undefined ? '' : `-${pin.candidate}`;
+    return {
+        url: `${directory}/${pathInChecksums}`,
+        filename: `firefox-${pin.product}-${pin.version}${candidate}.source.tar.xz`,
+        checksumsUrl: `${directory}/SHA256SUMS`,
+        pathInChecksums,
+    };
+}
+function downloadError(code, message, hint, cause) {
+    return new FireForgeError(code, message, {
+        exitCode: ExitCode.DOWNLOAD_ERROR,
+        ...(hint === undefined ? {} : { hint }),
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);
+const ATTEMPTS = 3;
+/**
+ * Requests a URL and hands the response to `consume`, with one deadline over
+ * both, up to three times. A 429 or 5xx status, a network failure, a failing
+ * `consume` and an expired deadline are retried; any other response reaches
+ * `consume` on the first attempt. The deadline holds even when the body
+ * ignores the abort signal.
+ *
+ * @param url - What to request
+ * @param consume - Reads the response; its result is returned
+ * @param options - See {@link RetryOptions}
+ * @throws `download-failed` (exit code 3) once every attempt has failed
+ */
+export async function fetchWithRetry(url, consume, options = {}) {
+    const request = options.fetch ?? fetch;
+    const timeoutMs = options.timeoutMs ?? 60_000;
+    let failure;
+    for (let attempt = 1; attempt <= ATTEMPTS; attempt += 1) {
+        const controller = new AbortController();
+        let timer;
+        const deadline = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                controller.abort();
+                reject(new Error(`the request or its response body timed out after ${timeoutMs} ms`));
+            }, timeoutMs);
+        });
+        try {
+            return await Promise.race([
+                deadline,
+                (async () => {
+                    const response = await request(url, { signal: controller.signal });
+                    if (RETRYABLE_STATUS.has(response.status)) {
+                        throw new Error(`HTTP ${response.status} ${response.statusText}`.trim());
+                    }
+                    return consume(response);
+                })(),
+            ]);
+        }
+        catch (error) {
+            // A refusal `consume` already worded is final: retrying cannot change it.
+            if (error instanceof FireForgeError)
+                throw error;
+            failure = error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (attempt < ATTEMPTS)
+            await sleep((options.retryDelayMs ?? 1_000) * attempt ** 2);
+    }
+    throw downloadError('download-failed', `Could not fetch ${url}: ${toError(failure).message}`, 'Check the network connection and retry.', failure);
+}
+/** No data for this long ends a transfer. */
+const STALL_MS = 30_000;
+/** The body's chunks, failing when none arrives within `stallMs`. */
+async function* unstalled(body, url, stallMs, onChunk) {
+    const reader = body.getReader();
+    try {
+        for (;;) {
+            let timer;
+            const stalled = new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    reject(downloadError('download-failed', `The download of ${url} stalled: no data for ${Math.round(stallMs / 1000)} seconds`, 'Retry the command; the transfer starts over.'));
+                }, stallMs);
+            });
+            const next = await Promise.race([reader.read(), stalled]).finally(() => {
+                clearTimeout(timer);
+            });
+            if (next.done)
+                return;
+            onChunk(next.value.byteLength);
+            yield next.value;
+        }
+    }
+    finally {
+        void reader.cancel().catch(() => undefined);
+    }
+}
+/** Downloads the archive to `target`, which appears only once the transfer is complete. */
+async function downloadArchive(archive, target, options) {
+    const response = await fetchWithRetry(archive.url, (reply) => Promise.resolve(reply), options);
+    if (response.status === 404) {
+        throw downloadError('version-not-found', `Mozilla publishes no source archive at ${archive.url}`, 'Check firefox.version, firefox.product and firefox.candidate in fireforge.json.');
+    }
+    if (!response.ok || response.body === null) {
+        throw downloadError('download-failed', `Could not download ${archive.url}: HTTP ${response.status} ${response.statusText}`.trim());
+    }
+    const total = Number(response.headers.get('content-length') ?? 0);
+    let received = 0;
+    let reported = 0;
+    return writeFileFromStream(target, unstalled(response.body, archive.url, STALL_MS, (bytes) => {
+        received += bytes;
+        const tenth = total > 0 ? Math.floor((received / total) * 10) : 0;
+        if (tenth > reported) {
+            reported = tenth;
+            options.onProgress?.(`Downloading ${archive.filename}: ${tenth * 10}%`);
+        }
+    }));
+}
+/** The digest `SHA256SUMS` lists for the archive, or why there is none. */
+async function publishedDigest(archive, options) {
+    let reply;
+    try {
+        reply = await fetchWithRetry(archive.checksumsUrl, async (response) => ({
+            ok: response.ok,
+            status: response.status,
+            body: response.ok ? await response.text() : '',
+        }), options);
+    }
+    catch (error) {
+        return { sha256: undefined, reason: toError(error).message };
+    }
+    if (!reply.ok)
+        return { sha256: undefined, reason: `HTTP ${reply.status} fetching SHA256SUMS` };
+    for (const line of reply.body.split('\n')) {
+        // `<digest>  <path>` or `<digest> *<path>`.
+        const match = /^([0-9a-f]{64})\s+\*?(.+)$/.exec(line.trim());
+        if (match?.[1] !== undefined && match[2] === archive.pathInChecksums) {
+            return { sha256: match[1] };
+        }
+    }
+    return {
+        sha256: undefined,
+        reason: `SHA256SUMS does not list ${archive.pathInChecksums} (the wrong file, or a response that is not Mozilla's)`,
+    };
+}
+function mismatch(archive, expected, actual, source) {
+    return downloadError('checksum-mismatch', `${archive.filename} has SHA-256 ${actual}, but ${source} says ${expected}`, 'The archive is not the one that was pinned or published. Do not build on it; retry the download, and check firefox.sha256.');
+}
+/** Holds a digest to the project's pin, or else to the published one. */
+async function verifyDigest(archive, pin, actual, options) {
+    if (pin.sha256 !== undefined) {
+        if (actual !== pin.sha256)
+            throw mismatch(archive, pin.sha256, actual, 'firefox.sha256');
+        return 'pinned';
+    }
+    options.onProgress?.(`Verifying ${archive.filename} against the published SHA256SUMS`);
+    const published = await publishedDigest(archive, options);
+    if (published.sha256 !== undefined) {
+        if (actual !== published.sha256) {
+            throw mismatch(archive, published.sha256, actual, archive.checksumsUrl);
+        }
+        return 'published';
+    }
+    if (!pin.allowUnverifiedDownload) {
+        throw downloadError('checksum-unavailable', `Could not verify ${archive.filename}: ${published.reason} (${archive.checksumsUrl})`, 'Retry when the SHA256SUMS file is reachable, pin firefox.sha256, or set firefox.allowUnverifiedDownload to trust TLS alone.');
+    }
+    warn(`Could not verify ${archive.filename} against the published SHA256SUMS (${published.reason}). ` +
+        'firefox.allowUnverifiedDownload is set, so the download is trusted on TLS alone.');
+    return 'unverified';
+}
+const ArchiveRecord = s.object({
+    url: s.string(),
+    size: s.int({ min: 0 }),
+    sha256: s.string({ pattern: /^[a-f0-9]{64}$/ }),
+    verification: s.enum(['pinned', 'published', 'unverified']),
+    downloadedAt: s.string(),
+});
+/** The cached archive's record when the file on disk is the one it describes. */
+async function validCacheEntry(archive, path) {
+    let record;
+    try {
+        record = await readJsonIfExists(`${path}.json`, ArchiveRecord);
+    }
+    catch (error) {
+        verbose(`Ignoring the cache record of ${path}: ${toError(error).message}`);
+        return undefined;
+    }
+    const info = await pathInfo(path);
+    if (record === undefined || info?.kind !== 'file')
+        return undefined;
+    if (record.url !== archive.url || record.size !== info.size)
+        return undefined;
+    return (await hashFile(path)) === record.sha256 ? record : undefined;
+}
+/**
+ * The pin's source archive in the host cache, downloaded if it is not there
+ * and verified either way. Callers serialise per pin; `ensurePristine` does.
+ *
+ * @param host - The host locations
+ * @param pin - The pin
+ * @param options - See {@link DownloadOptions}
+ * @returns The archive's path
+ * @throws `version-not-found`, `download-failed`, `checksum-mismatch` or
+ *   `checksum-unavailable` (exit code 3)
+ */
+export async function ensureArchive(host, pin, options = {}) {
+    const archive = sourceArchive(pin);
+    const path = join(host.cache, archive.filename);
+    const cached = await validCacheEntry(archive, path);
+    if (cached !== undefined) {
+        // A pin is checked on every use; a published digest once. An entry that
+        // was accepted unverified is held to the current rule again.
+        if (pin.sha256 !== undefined || cached.verification !== 'published') {
+            const verification = await verifyDigest(archive, pin, cached.sha256, options);
+            if (verification !== cached.verification) {
+                await writeJson(`${path}.json`, { ...cached, verification });
+            }
+        }
+        options.onProgress?.(`Using the cached ${archive.filename}`);
+        return path;
+    }
+    await discardArchive(path);
+    await ensureDir(host.cache);
+    options.onProgress?.(`Downloading ${archive.url}`);
+    const size = await downloadArchive(archive, path, options);
+    try {
+        const sha256 = await hashFile(path);
+        const verification = await verifyDigest(archive, pin, sha256, options);
+        const record = {
+            url: archive.url,
+            size,
+            sha256,
+            verification,
+            downloadedAt: new Date().toISOString(),
+        };
+        await writeJson(`${path}.json`, record);
+    }
+    catch (error) {
+        await discardArchive(path);
+        throw error;
+    }
+    return path;
+}
+/**
+ * Removes an archive and its record from the cache.
+ *
+ * @param path - The archive's path
+ */
+async function discardArchive(path) {
+    await remove(path);
+    await remove(`${path}.json`);
+}
+function escapes(path) {
+    if (path.startsWith('/') || path.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(path))
+        return true;
+    return path.split(/[\\/]/).includes('..');
+}
+/**
+ * Why a member name from a `tar -tf` listing must not be extracted, or
+ * undefined: an absolute or `..` path lands outside the extraction root, and
+ * a `.git` segment at any depth would seed configuration or hooks into the
+ * repository the tree is about to become.
+ *
+ * @param name - One listing line
+ */
+export function unsafeArchiveMember(name) {
+    const member = name.trim();
+    if (member === '')
+        return undefined;
+    if (escapes(member))
+        return `member ${member} leaves the extraction root`;
+    return member.split(/[\\/]/).some((segment) => segment.toLowerCase() === '.git')
+        ? `member ${member} would seed a .git directory`
+        : undefined;
+}
+/**
+ * Why a line of a `tar -tvf` listing names a link that must not be
+ * extracted, or undefined: a symlink (` -> target`) or hard link
+ * (` link to target`) whose target is absolute or climbs with `..`.
+ *
+ * @param line - One verbose listing line
+ */
+export function unsafeArchiveLink(line) {
+    const arrow = line.startsWith('l') ? line.lastIndexOf(' -> ') : -1;
+    const hard = line.lastIndexOf(' link to ');
+    const target = arrow !== -1
+        ? line.slice(arrow + 4).trim()
+        : hard !== -1
+            ? line.slice(hard + 9).trim()
+            : undefined;
+    return target !== undefined && escapes(target)
+        ? `link target ${target} leaves the extraction root`
+        : undefined;
+}
+function extractError(archivePath, why, hint) {
+    return downloadError('extract-failed', `Could not extract ${basename(archivePath)}: ${why}`, hint ?? 'Retry the command; a damaged archive is downloaded again.');
+}
+/**
+ * Scans one listing of the archive. Member names come from `-tf`, where the
+ * whole line is the name; link targets only appear in `-tvf`. Names are never
+ * parsed out of the verbose columns, whose owner fields an archive controls.
+ */
+async function scanListing(archivePath, flag, check) {
+    let unsafe;
+    const listing = await run('tar', [flag, archivePath], {
+        env: { LC_ALL: 'C', LANG: 'C' },
+        onLine: (line, stream) => {
+            if (stream === 'stdout')
+                unsafe ??= check(line);
+        },
+    });
+    if (listing.exitCode !== 0) {
+        const tail = tailLines(listing.stderr, 5).join('\n');
+        throw extractError(archivePath, `tar ${flag} exited ${listing.exitCode}\n${tail}`);
+    }
+    if (unsafe !== undefined)
+        throw extractError(archivePath, `the archive is refused: ${unsafe}`);
+}
+const ENVIRONMENTAL = /No space left on device|Permission denied|Disk quota exceeded/i;
+/**
+ * Extracts a source archive so that `destination` becomes the source tree:
+ * the archive's single `firefox-*` directory, or its root when it has none.
+ * Every member is checked first, so nothing can be written outside the tree
+ * and no `.git` can be planted in it. A failure that indicts the archive
+ * removes it from the cache; one of the environment (a full disk, a missing
+ * `tar`) keeps it for the retry.
+ *
+ * @param archivePath - The archive, in the host cache
+ * @param destination - The directory to create; must not exist
+ * @throws `extract-failed` (exit code 3)
+ */
+export async function extractArchive(archivePath, destination) {
+    if ((await findExecutable('tar')) === undefined) {
+        throw new FireForgeError('command-not-found', 'Extracting the Firefox source needs "tar"', {
+            exitCode: ExitCode.MISSING_DEPENDENCY,
+            hint: 'Install tar and make sure it is on PATH.',
+        });
+    }
+    const staging = await makeTempDir(`${basename(destination)}.extract-`, dirname(destination));
+    try {
+        // Each listing decompresses the whole archive, so the two run side by side.
+        await Promise.all([
+            scanListing(archivePath, '-tf', unsafeArchiveMember),
+            scanListing(archivePath, '-tvf', unsafeArchiveLink),
+        ]).catch(async (error) => {
+            await discardArchive(archivePath);
+            throw error;
+        });
+        const extracted = await run('tar', ['-xf', archivePath, '-C', staging]);
+        if (extracted.exitCode !== 0) {
+            const tail = tailLines(extracted.stderr, 5).join('\n');
+            if (ENVIRONMENTAL.test(extracted.stderr)) {
+                throw extractError(archivePath, `tar could not write the source tree\n${tail}`, 'Free disk space or fix the permissions, then retry; the downloaded archive is kept.');
+            }
+            await discardArchive(archivePath);
+            throw extractError(archivePath, `tar exited ${extracted.exitCode}\n${tail}`);
+        }
+        const top = (await listDir(staging)).filter((entry) => entry.kind === 'directory' && entry.name.startsWith('firefox-'));
+        await move(top.length === 1 ? join(staging, top[0]?.name ?? '') : staging, destination);
+    }
+    finally {
+        await remove(staging);
+    }
+}

package/dist/src/engine/audit.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The post-build packaging audit: front-end files that changed since the
+ * previous build and that nothing packages. Such a file builds without
+ * complaint and is simply absent from the browser. Warn-only: the audit can
+ * be wrong about a file reached some other way, which is what
+ * `buildAudit.unpackaged` declares.
+ */
+import { join, posix } from 'node:path';
+import { captureWorktree, changedPaths, resolveRevision } from '../git/index.js';
+import { exists, readTextIfExists } from '../kernel/fs.js';
+import { matchesGlob } from '../kernel/glob.js';
+import { manifestReferencesFile } from '../mozbuild/index.js';
+import { deliveryOf, readInstallIndex } from './installManifests.js';
+import { buildInputClass, isTestPath } from './staleness.js';
+/** Files a registered document pulls in itself, and files only a development tool reads. */
+const NEVER_PACKAGED = /\.inc\.xhtml$|\.stories\.mjs$/;
+/**
+ * The changed front-end files that no install manifest of the finished build
+ * installs and no `jar.mn` or `moz.build` in their directory or above it
+ * names, leaving out those the project declares in `buildAudit.unpackaged`.
+ *
+ * @param workspace - The workspace, after a successful build
+ * @param since - Tree-ish of the previous build's snapshot; default the engine's HEAD
+ * @returns Engine-relative paths, sorted
+ */
+export async function unpackagedChanges(workspace, since) {
+    const { engineDir, objDir, project } = workspace;
+    const base = since !== undefined && (await resolveRevision(engineDir, since, 'commit')) !== undefined
+        ? since
+        : 'HEAD';
+    const declared = (project.config.buildAudit?.unpackaged ?? []).map((entry) => entry.path);
+    const index = await readInstallIndex(engineDir, objDir);
+    const manifests = new Map();
+    const manifest = async (path) => {
+        if (!manifests.has(path))
+            manifests.set(path, await readTextIfExists(join(engineDir, path)));
+        return manifests.get(path);
+    };
+    const named = async (file) => {
+        for (let directory = posix.dirname(file);; directory = posix.dirname(directory)) {
+            for (const name of ['jar.mn', 'moz.build']) {
+                const path = directory === '.' ? name : `${directory}/${name}`;
+                const text = await manifest(path);
+                if (text !== undefined && manifestReferencesFile(path, text, file))
+                    return true;
+            }
+            if (directory === '.')
+                return false;
+        }
+    };
+    const unpackaged = [];
+    for (const path of await changedPaths(engineDir, base, await captureWorktree(engineDir))) {
+        if (buildInputClass(path) !== 'ui' || isTestPath(path) || NEVER_PACKAGED.test(path))
+            continue;
+        if (declared.some((glob) => matchesGlob(path, glob)))
+            continue;
+        if (!(await exists(join(engineDir, path))))
+            continue;
+        if (index !== undefined && (await deliveryOf(index, engineDir, path)) !== 'unlisted')
+            continue;
+        if (!(await named(path)))
+            unpackaged.push(path);
+    }
+    return unpackaged;
+}

package/dist/src/engine/build.js

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Building a workspace: write the mozconfig, discard an object directory
+ * that was configured at another path, pick the smallest build that is
+ * correct, run it under a host build slot, and record the baseline staleness
+ * is measured from.
+ */
+import { constants as osConstants } from 'node:os';
+import { ExitCode, FireForgeError, toError } from '../kernel/errors.js';
+import { exists, freeDiskSpace } from '../kernel/fs.js';
+import { info, verbose, warn } from '../kernel/log.js';
+import { formatDuration } from '../kernel/time.js';
+import { unpackagedChanges } from './audit.js';
+import { withBuildSlot } from './hostLocks.js';
+import { machFailure, runMach } from './mach.js';
+import { writeMozconfig } from './mozconfig.js';
+import { discardMovedObjdir } from './objdir.js';
+import { buildStaleness, readBuildBaseline, recordBuild, snapshotEngine, } from './staleness.js';
+/** A first full build writes about this much. */
+const FULL_BUILD_BYTES = 20 * 1024 ** 3;
+/**
+ * An exit status of 128 + N means the process died of signal N: it was
+ * interrupted from outside rather than failing, and its log may stop mid-step.
+ */
+function signalNote(exitCode) {
+    if (exitCode <= 128 || exitCode > 192)
+        return '';
+    const signal = Object.entries(osConstants.signals).find(([, value]) => value === exitCode - 128);
+    return ` (killed by ${signal?.[0] ?? `signal ${exitCode - 128}`}: interrupted from outside, not a compile error)`;
+}
+function buildFailure(command, result, durationMs) {
+    const how = result.timedOut
+        ? 'timed out'
+        : `exited ${result.exitCode}${signalNote(result.exitCode)}`;
+    return new FireForgeError('build-failed', `${command} ${how} after ${formatDuration(durationMs)}`, { exitCode: ExitCode.BUILD_ERROR, hint: 'The first error in the output above is the cause.' });
+}
+/** What changed since the build, with the first few paths. */
+function describeStaleness(staleness) {
+    const sample = staleness.paths.slice(0, 5).join(', ');
+    return `${staleness.why}${sample === '' ? '' : ` (${sample}${staleness.paths.length > 5 ? ', ...' : ''})`}`;
+}
+/** The build that is correct for what was asked: a UI build only when nothing needs more. */
+async function chooseBuild(workspace, ui) {
+    if (!ui)
+        return { kind: 'full' };
+    const staleness = await buildStaleness(workspace);
+    if (staleness.state === 'fresh' || staleness.needs === 'ui')
+        return { kind: 'ui' };
+    const escalated = describeStaleness(staleness);
+    warn(`Running a full build instead of a UI build: ${escalated}.`);
+    return { kind: 'full', escalated };
+}
+/**
+ * Builds the workspace's engine.
+ *
+ * @param workspace - The workspace
+ * @param options - See {@link BuildOptions}
+ * @throws `build-failed` (exit code 5) when mach fails, `mozconfig-invalid`
+ *   (exit code 2), `lock-timeout` (exit code 15) when no build slot came free
+ */
+export async function build(workspace, options = {}) {
+    const { project } = workspace;
+    await writeMozconfig(workspace);
+    const discardedObjdirOf = await discardMovedObjdir(workspace);
+    if (discardedObjdirOf !== undefined) {
+        warn(`The object directory of workspace "${workspace.name}" was configured for ${discardedObjdirOf}, ` +
+            `not ${workspace.engineDir}. A build cannot be moved to another path, so it was removed and this is a full build from nothing.`);
+    }
+    const { kind, escalated } = await chooseBuild(workspace, options.ui === true);
+    const previous = await readBuildBaseline(workspace);
+    if (kind === 'full' && !(await exists(workspace.objDir))) {
+        const free = await freeDiskSpace(workspace.engineDir);
+        if (free !== undefined && free < FULL_BUILD_BYTES) {
+            warn(`Only ${Math.floor(free / 1024 ** 3)} GB are free at ${workspace.engineDir}; a first full build needs about 20 GB.`);
+        }
+    }
+    const jobs = options.jobs ?? project.config.build?.jobs;
+    const args = kind === 'ui'
+        ? ['build', 'faster']
+        : ['build', ...(jobs === undefined ? [] : ['-j', String(jobs)])];
+    const startedAt = Date.now();
+    const { result, snapshot } = await withBuildSlot(project.host, options.waitMs, async () => {
+        const taken = await snapshotEngine(workspace);
+        info(`Running mach ${args.join(' ')} in workspace "${workspace.name}".`);
+        return { result: await runMach(workspace, args), snapshot: taken };
+    });
+    const durationMs = Date.now() - startedAt;
+    if (result.exitCode !== 0)
+        throw buildFailure(`mach ${args.join(' ')}`, result, durationMs);
+    let unpackaged = [];
+    try {
+        unpackaged = await unpackagedChanges(workspace, previous?.tree);
+    }
+    catch (error) {
+        verbose(`The packaging audit did not run: ${toError(error).message}`);
+    }
+    if (unpackaged.length > 0) {
+        warn(`${unpackaged.length} changed file(s) are not packaged into the browser: ${unpackaged.join(', ')}. ` +
+            'Register each in a jar.mn or moz.build ("fireforge register <path>"), or declare it in buildAudit.unpackaged.');
+    }
+    await recordBuild(workspace, kind, snapshot);
+    return {
+        kind,
+        ...(escalated === undefined ? {} : { escalated }),
+        ...(discardedObjdirOf === undefined ? {} : { discardedObjdirOf }),
+        durationMs,
+        unpackaged,
+    };
+}
+/**
+ * Installs Firefox's build dependencies with `mach bootstrap`, which prompts
+ * and may ask for elevated rights, so it gets the terminal.
+ *
+ * @param workspace - Any workspace on the project's pin
+ * @throws `mach-failed` (exit code 5) when mach fails
+ */
+export async function bootstrap(workspace) {
+    const result = await runMach(workspace, ['bootstrap', '--application-choice', 'browser'], {
+        terminal: true,
+    });
+    if (result.exitCode !== 0) {
+        throw machFailure('mach bootstrap', result, 'Fix what the output above names, then run "fireforge bootstrap" again.');
+    }
+}
+/**
+ * Makes sure the workspace's build matches its engine before a command uses
+ * it. A stale build is refused with the command that fixes it, unless
+ * `build` asks for that build to run now, once, as the smallest one that
+ * catches up.
+ *
+ * @param workspace - The workspace
+ * @param options - `build` builds instead of refusing; `waitMs` is for the host build slot
+ * @returns The build that ran, or undefined when the build was fresh
+ * @throws `build-stale` naming what changed and the build that catches up
+ */
+export async function ensureBuilt(workspace, options = {}) {
+    const staleness = await buildStaleness(workspace);
+    if (staleness.state === 'fresh')
+        return undefined;
+    const why = describeStaleness(staleness);
+    const ui = staleness.needs === 'ui';
+    if (options.build === true) {
+        info(`Building first: ${why}.`);
+        return build(workspace, { ui, waitMs: options.waitMs });
+    }
+    throw new FireForgeError('build-stale', `The build of workspace "${workspace.name}" is older than its engine: ${why}.`, {
+        exitCode: ExitCode.GENERAL_ERROR,
+        hint: `Run "fireforge build${ui ? ' --ui' : ''}", or pass --build to build first.`,
+    });
+}

package/dist/src/engine/hostLocks.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * What every project and checkout on one host shares besides the workspace
+ * pool: the host configuration file, and the two locks that keep parallel
+ * sessions from fighting over the screen and the CPU.
+ */
+import { isAbsolute, join } from 'node:path';
+import { ExitCode } from '../kernel/errors.js';
+import { readJsonIfExists } from '../kernel/json.js';
+import { COMMAND_WAIT_MS, withLock } from '../kernel/lock.js';
+import { s } from '../kernel/schema.js';
+const HostConfigSchema = s.object({
+    buildSlots: s
+        .int({ min: 1 })
+        .describe('How many compiles may run at once on this host')
+        .default(1),
+    releaseSecrets: s
+        .string({ min: 1 })
+        .refine((path) => (isAbsolute(path) ? undefined : 'must be an absolute path'))
+        .describe('Directory holding the secret files release builds read')
+        .optional(),
+});
+/**
+ * Reads `host.json`. A host without one has the defaults.
+ *
+ * @param host - The host locations
+ * @throws `host-config-invalid` (exit code 2) when the file does not match its schema
+ */
+export async function readHostConfig(host) {
+    const path = join(host.root, 'host.json');
+    const config = await readJsonIfExists(path, HostConfigSchema, {
+        code: 'host-config-invalid',
+        exitCode: ExitCode.CONFIG_ERROR,
+        hint: `Fix ${path}: it takes "buildSlots" (a count) and "releaseSecrets" (a directory).`,
+    });
+    return config ?? HostConfigSchema.parse({});
+}
+/**
+ * Runs `body` as the one command on this host showing a browser window.
+ *
+ * @param host - The host locations
+ * @param waitMs - How long to wait for the display (default {@link COMMAND_WAIT_MS})
+ * @param body - The work
+ * @throws `lock-timeout` (exit code 15) naming the holder when the wait expires
+ */
+export function withDisplay(host, waitMs, body) {
+    return withLock(join(host.locks, 'display'), { label: 'display', waitMs: waitMs ?? COMMAND_WAIT_MS }, body);
+}
+/**
+ * Runs `body` holding one of the host's build slots, so no more compiles run
+ * at once than `host.json` allows.
+ *
+ * @param host - The host locations
+ * @param waitMs - How long to wait for a slot (default {@link COMMAND_WAIT_MS})
+ * @param body - The compile
+ * @throws `lock-timeout` (exit code 15) naming the holders when the wait expires
+ */
+export async function withBuildSlot(host, waitMs, body) {
+    const { buildSlots } = await readHostConfig(host);
+    return withLock(join(host.locks, 'build'), {
+        mode: 'shared',
+        limit: buildSlots,
+        label: 'build',
+        waitMs: waitMs ?? COMMAND_WAIT_MS,
+    }, body);
+}