@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/engine/run.js

@@ -0,0 +1,259 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Launching the built browser: interactively, or as a smoke start that
+ * watches the console for a fixed window and judges what it saw.
+ *
+ * Profiles: desktop `mach run` has no profile option of its own, so a profile
+ * reaches Firefox as the program parameter `-profile <dir>`. A temporary
+ * profile is created, seeded and removed here, because the one mach can mint
+ * lives in the object directory and is never removed.
+ */
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ExitCode, FireForgeError, toError } from '../kernel/errors.js';
+import { appendText, listDir, makeTempDir, readText, readTextIfExists, remove, writeFile, } from '../kernel/fs.js';
+import { info, verbose, warn } from '../kernel/log.js';
+import { isProcessAlive, listProcesses } from '../kernel/process/index.js';
+import { onShutdown } from '../kernel/signals.js';
+import { withDisplay } from './hostLocks.js';
+import { runMach } from './mach.js';
+import { requireBuilt } from './objdir.js';
+import { compileAllowlist, createSmokeScan, parseAllowlistFile, smokeFailure, } from './smoke.js';
+const PROFILE_PREFIX = 'fireforge-run-profile-';
+const OWNER_MARKER = '.fireforge-run-owner';
+/** The prefs mach writes into profiles it creates; one passed with `-profile` gets none of them. */
+const SEEDED_PREFS = 'user_pref("browser.shell.checkDefaultBrowser", false);\n' +
+    'user_pref("browser.aboutConfig.showWarning", false);\n';
+/**
+ * Removes temporary profiles whose FireForge was killed before it could.
+ * A browser can outlive its FireForge, so a profile some running process
+ * names on its command line is still in use.
+ */
+async function sweepAbandonedProfiles(root) {
+    const profiles = (await listDir(root).catch(() => [])).filter((entry) => entry.name.startsWith(PROFILE_PREFIX));
+    if (profiles.length === 0)
+        return;
+    const commands = (await listProcesses(['pid', 'command'])).map((row) => row.command);
+    for (const entry of profiles) {
+        const dir = join(root, entry.name);
+        // Without a readable marker nothing proves the directory abandoned.
+        const pid = Number((await readTextIfExists(join(dir, OWNER_MARKER)).catch(() => ''))?.trim());
+        if (!Number.isSafeInteger(pid) || pid <= 0 || pid === process.pid || isProcessAlive(pid)) {
+            continue;
+        }
+        if (commands.some((command) => command.includes(dir)))
+            continue;
+        await remove(dir).catch((error) => {
+            verbose(`Could not remove abandoned run profile ${dir}: ${toError(error).message}`);
+        });
+    }
+}
+/**
+ * Chooses the profile. A named or default profile is launched with
+ * `-purgecaches`: a front-end build keeps the build id a profile's startup
+ * cache is keyed on, so without it a reused profile runs the chrome scripts
+ * an earlier build cached.
+ */
+async function chooseProfile(options) {
+    const none = () => Promise.resolve();
+    if (options.profile !== undefined) {
+        return {
+            args: ['-profile', options.profile, '-purgecaches'],
+            kept: options.profile,
+            dispose: none,
+        };
+    }
+    const fresh = options.tempProfile === true ||
+        options.smokeExit !== undefined ||
+        options.screenshot !== undefined;
+    if (!fresh)
+        return { args: ['-purgecaches'], dispose: none };
+    await sweepAbandonedProfiles(tmpdir());
+    const dir = await makeTempDir(PROFILE_PREFIX);
+    // The marker goes in first, so a directory left by a killed run can be proven abandoned.
+    await writeFile(join(dir, OWNER_MARKER), `${process.pid}\n`, { durable: false });
+    await writeFile(join(dir, 'user.js'), SEEDED_PREFS, { durable: false });
+    verbose(`Temporary run profile: ${dir}`);
+    let removed;
+    const dispose = () => {
+        removed ??= remove(dir).catch((error) => {
+            warn(`Could not remove the temporary run profile ${dir}: ${toError(error).message}`);
+        });
+        return removed;
+    };
+    // An interrupt ends the process before a `finally` runs.
+    const disarm = onShutdown('restore', dispose);
+    return {
+        args: ['-profile', dir],
+        async dispose() {
+            disarm();
+            await dispose();
+        },
+    };
+}
+async function readAllowlist(options) {
+    const allow = compileAllowlist(options.consoleAllow ?? []);
+    if (options.consoleAllowFile === undefined)
+        return allow;
+    let body;
+    try {
+        body = await readText(options.consoleAllowFile);
+    }
+    catch (error) {
+        throw new FireForgeError('invalid-argument', `Cannot read the allowlist file ${options.consoleAllowFile}: ${toError(error).message}`, { exitCode: ExitCode.INVALID_ARGUMENT, cause: error });
+    }
+    return [...allow, ...parseAllowlistFile(body, options.consoleAllowFile)];
+}
+/** A sink appending console lines to a file, in order, without blocking the stream. */
+async function openCapture(path) {
+    if (path === undefined)
+        return { line: () => undefined, close: () => Promise.resolve() };
+    await writeFile(path, '', { durable: false });
+    let buffer = '';
+    let failed = false;
+    let writing = Promise.resolve();
+    const flush = () => {
+        const text = buffer;
+        buffer = '';
+        writing = writing.then(async () => {
+            if (failed || text === '')
+                return;
+            try {
+                await appendText(path, text);
+            }
+            catch (error) {
+                failed = true;
+                warn(`Console capture to ${path} stopped: ${toError(error).message}`);
+            }
+        });
+    };
+    return {
+        line(line) {
+            const idle = buffer === '';
+            buffer += `${line}\n`;
+            // One append per burst of lines: a write is queued when the buffer starts filling.
+            if (idle)
+                queueMicrotask(flush);
+        },
+        async close() {
+            flush();
+            await writing;
+        },
+    };
+}
+function reportSmoke(smoke, windowSeconds) {
+    const seconds = (smoke.elapsedMs / 1000).toFixed(1);
+    info(`Smoke start: ${seconds}s of a ${windowSeconds}s window` +
+        (smoke.timedOut ? ', browser still running and terminated' : ', browser exited by itself'));
+    info(`  Console errors: ${smoke.errors.length} (${smoke.allowedErrors} more allowed)`);
+    for (const entry of smoke.entries) {
+        const cap = entry.maxHits === undefined ? '' : `/${entry.maxHits}`;
+        const stale = entry.hits === 0 ? '  (never matched)' : '';
+        info(`  ${entry.hits}${cap}  ${entry.origin}  ${entry.source}${stale}`);
+    }
+    for (const over of smoke.overCap) {
+        warn(`Allowed pattern "${over.source}" (${over.origin}) matched ${over.hits} lines, over its cap of ${over.maxHits}.`);
+    }
+    for (const line of smoke.errors.slice(0, 10))
+        warn(`  ${line}`);
+    if (smoke.errors.length > 10)
+        warn(`  and ${smoke.errors.length - 10} more.`);
+}
+async function launch(workspace, options, profile) {
+    const headless = options.headless === true || options.screenshot !== undefined;
+    const machArgs = [
+        'run',
+        ...(headless ? ['--headless'] : []),
+        ...profile.args,
+        ...(options.screenshot === undefined ? [] : ['--screenshot', options.screenshot]),
+        ...(options.args ?? []),
+    ];
+    const kept = profile.kept === undefined ? {} : { profile: profile.kept };
+    const shot = options.screenshot === undefined ? {} : { screenshot: options.screenshot };
+    if (options.smokeExit === undefined) {
+        // The browser's output is shown on stderr: stdout carries the command's result.
+        const capture = await openCapture(options.captureConsole);
+        let exitCode;
+        try {
+            ({ exitCode } = await runMach(workspace, machArgs, { onLine: capture.line, hints: false }));
+        }
+        finally {
+            await capture.close();
+        }
+        // 130 and 143: the operator closed it with Ctrl+C, or it was asked to stop.
+        if (exitCode !== 0 && exitCode !== 130 && exitCode !== 143) {
+            throw new FireForgeError('browser-exited', `The browser exited ${exitCode}`, {
+                exitCode: ExitCode.BUILD_ERROR,
+                hint: 'Its output above names the cause; --capture-console <file> keeps a copy of it.',
+            });
+        }
+        return { exitCode, ...kept, ...shot };
+    }
+    const scan = createSmokeScan(await readAllowlist(options));
+    const capture = await openCapture(options.captureConsole);
+    const startedAt = Date.now();
+    let exit;
+    try {
+        exit = await runMach(workspace, machArgs, {
+            timeoutMs: options.smokeExit * 1000,
+            hints: false,
+            onLine: (line) => {
+                scan.line(line);
+                capture.line(line);
+            },
+        });
+    }
+    finally {
+        await capture.close();
+    }
+    const smoke = { ...scan.report(), elapsedMs: Date.now() - startedAt, timedOut: exit.timedOut };
+    reportSmoke(smoke, options.smokeExit);
+    const failure = smokeFailure(smoke, exit);
+    if (failure !== undefined)
+        throw failure;
+    return { exitCode: exit.exitCode, smoke, ...kept, ...shot };
+}
+/**
+ * Launches the workspace's built browser.
+ *
+ * Without `smokeExit` the browser runs until it is closed. With it the run is
+ * a smoke start: the console is scanned for `smokeExit` seconds, then the
+ * browser's process tree is terminated.
+ *
+ * A launch with a window holds the host's display lock, so two sessions
+ * never put a browser on screen at once.
+ *
+ * @param workspace - The workspace holding the build
+ * @param options - See {@link RunOptions}
+ * @throws `build-missing` when nothing is built; `smoke-console-errors` (exit
+ *   code 12) when a smoke start saw unallowed errors; `smoke-launch-failed`
+ *   (exit code 13) when its browser left before the window elapsed;
+ *   `browser-exited` (exit code 5) when a plain launch ended abnormally
+ */
+export async function runBrowser(workspace, options = {}) {
+    if (options.profile !== undefined && options.tempProfile === true) {
+        throw new FireForgeError('invalid-argument', 'A named profile and a temporary profile cannot both be asked for', { exitCode: ExitCode.INVALID_ARGUMENT });
+    }
+    if (options.smokeExit !== undefined) {
+        if (process.platform === 'win32') {
+            throw new FireForgeError('invalid-argument', 'A smoke start needs process groups to end the browser, which Windows does not have', { exitCode: ExitCode.INVALID_ARGUMENT });
+        }
+        if (!Number.isFinite(options.smokeExit) || options.smokeExit <= 0) {
+            throw new FireForgeError('invalid-argument', 'The smoke window must be a positive number of seconds', {
+                exitCode: ExitCode.INVALID_ARGUMENT,
+            });
+        }
+    }
+    await requireBuilt(workspace);
+    const profile = await chooseProfile(options);
+    try {
+        const body = () => launch(workspace, options, profile);
+        const headless = options.headless === true || options.screenshot !== undefined;
+        return headless
+            ? await body()
+            : await withDisplay(workspace.project.host, options.waitMs, body);
+    }
+    finally {
+        await profile.dispose();
+    }
+}

package/dist/src/engine/smoke.js

@@ -0,0 +1,204 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * What a smoke start reads from the browser's console: which lines are
+ * runtime errors, which of those the project allows, and the judgement over
+ * one run's lines. Pure; launching and timing are `run.ts`.
+ *
+ * Error patterns are anchored at the start of the line: Firefox prints these
+ * prefixes at column zero, and the same words inside an unrelated message
+ * must not count.
+ */
+import { ExitCode, FireForgeError, toError } from '../kernel/errors.js';
+import { splitLines } from '../kernel/text.js';
+const ERROR_PATTERNS = [
+    /^\s*JavaScript error:/i,
+    /^\s*console\.error:/i,
+    /^\s*\[JavaScript (Error|Warning)\]/i,
+    // A fatal IPC assertion in the parent process.
+    /^\s*###!!! \[Parent\]/,
+    // A chrome:// or resource:// URL that resolves to nothing. Outside
+    // automation Gecko only prints this; under a test harness the same defect
+    // crashes the process that opened the channel.
+    /^\s*Missing chrome or resource URLs?:/,
+];
+/**
+ * Whether a console line is a runtime error of the browser.
+ *
+ * @param line - One output line
+ */
+export function isSmokeError(line) {
+    return ERROR_PATTERNS.some((pattern) => pattern.test(line));
+}
+/** mach's own log lines carry an elapsed-time prefix; they prove mach ran, not the browser. */
+const MACH_LOG_LINE = /^\s*\d+:\d{2}\.\d{2} /;
+/**
+ * Whether a line is output of the browser rather than of mach.
+ *
+ * @param line - One output line
+ */
+export function isBrowserLine(line) {
+    return line.trim() !== '' && !MACH_LOG_LINE.test(line);
+}
+function invalid(message, cause) {
+    return new FireForgeError('invalid-argument', message, {
+        exitCode: ExitCode.INVALID_ARGUMENT,
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+function compile(source, origin, maxHits) {
+    try {
+        return {
+            pattern: new RegExp(source),
+            source,
+            origin,
+            ...(maxHits === undefined ? {} : { maxHits }),
+        };
+    }
+    catch (error) {
+        throw invalid(`Invalid allowlist pattern at ${origin}: ${toError(error).message}`, error);
+    }
+}
+/**
+ * Compiles allowlist patterns given on the command line.
+ *
+ * @param sources - Regular expressions
+ * @throws `invalid-argument` (exit code 8) naming the pattern that does not compile
+ */
+export function compileAllowlist(sources) {
+    return sources.map((source, index) => compile(source, `--console-allow #${index + 1}`, undefined));
+}
+const MAX_HITS = /^#\s*max-hits:\s*(\S+)\s*$/i;
+/**
+ * Parses an allowlist file: one regular expression per line, blank lines and
+ * `#` comments skipped. A `# max-hits: N` comment caps the entry that follows
+ * it; one that no entry follows is an error, never a silently dropped cap.
+ *
+ * @param body - The file's text
+ * @param path - Its path, for origins and messages
+ * @throws `invalid-argument` (exit code 8) naming the line at fault
+ */
+export function parseAllowlistFile(body, path) {
+    const entries = [];
+    let pending;
+    const orphan = () => {
+        if (pending !== undefined) {
+            throw invalid(`The max-hits directive at ${pending.at} is not followed by an entry`);
+        }
+    };
+    for (const [index, raw] of splitLines(body).entries()) {
+        const line = raw.trim();
+        const at = `${path}:${index + 1}`;
+        if (line === '') {
+            orphan();
+        }
+        else if (line.startsWith('#')) {
+            const value = MAX_HITS.exec(line)?.[1];
+            if (value === undefined)
+                continue;
+            if (!/^[1-9]\d*$/.test(value)) {
+                throw invalid(`The max-hits directive at ${at} needs a positive integer (got "${value}")`);
+            }
+            pending = { maxHits: Number(value), at };
+        }
+        else {
+            entries.push(compile(line, at, pending?.maxHits));
+            pending = undefined;
+        }
+    }
+    orphan();
+    return entries;
+}
+/**
+ * Starts the scan of one run's console.
+ *
+ * @param allowlist - The project's allowed patterns
+ * @returns `line` for each output line, and `report` for the result so far
+ */
+export function createSmokeScan(allowlist) {
+    const hits = allowlist.map(() => 0);
+    const errors = [];
+    let allowedErrors = 0;
+    let browserLines = 0;
+    return {
+        line(line) {
+            if (isBrowserLine(line))
+                browserLines += 1;
+            // The first matching entry is credited, whether or not the line is an
+            // error: the count is what an operator tunes a cap against.
+            const index = allowlist.findIndex((entry) => entry.pattern.test(line));
+            if (index !== -1)
+                hits[index] = (hits[index] ?? 0) + 1;
+            if (!isSmokeError(line))
+                return;
+            if (index === -1)
+                errors.push(line);
+            else
+                allowedErrors += 1;
+        },
+        report() {
+            const entries = allowlist.map((entry, index) => ({
+                source: entry.source,
+                origin: entry.origin,
+                hits: hits[index] ?? 0,
+                ...(entry.maxHits === undefined ? {} : { maxHits: entry.maxHits }),
+            }));
+            return {
+                errors: [...errors],
+                allowedErrors,
+                browserLines,
+                entries,
+                overCap: entries.flatMap((entry) => entry.maxHits !== undefined && entry.hits > entry.maxHits
+                    ? [{ ...entry, maxHits: entry.maxHits }]
+                    : []),
+            };
+        },
+    };
+}
+/**
+ * The judgement over a smoke start, or undefined for a pass. Console errors
+ * outrank everything: a browser that printed one and then lived out its
+ * window still failed. A browser that left before the window elapsed failed
+ * to launch, unless it left cleanly having shown a console. A window that
+ * elapsed without one line from the browser proves no start either.
+ *
+ * @param report - What the console held
+ * @param exit - How the browser ended
+ * @returns `smoke-console-errors` (exit code 12) or `smoke-launch-failed` (exit code 13)
+ */
+export function smokeFailure(report, exit) {
+    if (report.errors.length > 0 || report.overCap.length > 0) {
+        const parts = [
+            ...(report.errors.length > 0 ? [`${report.errors.length} console error(s)`] : []),
+            ...(report.overCap.length > 0
+                ? [
+                    `${report.overCap.length} allowlist entr${report.overCap.length === 1 ? 'y' : 'ies'} over the max-hits cap`,
+                ]
+                : []),
+        ];
+        return new FireForgeError('smoke-console-errors', `The smoke start saw ${parts.join(' and ')}`, {
+            exitCode: ExitCode.SMOKE_EXIT_FAILURE,
+            hint: 'Fix the errors, or allow an expected line with --console-allow <regex>.',
+        });
+    }
+    if (exit.timedOut) {
+        if (report.browserLines > 0)
+            return undefined;
+        return new FireForgeError('smoke-launch-failed', 'The smoke window elapsed without a line from the browser, so nothing shows it started', {
+            exitCode: ExitCode.SMOKE_LAUNCH_FAILURE,
+            hint: 'mach may still have been preparing (a first run sets up its environment), or the browser ' +
+                'is waiting on a dialog such as a locked profile: retry with a longer --smoke-exit, or run ' +
+                'without it to watch the window.',
+        });
+    }
+    const clean = exit.exitCode === 0 || exit.exitCode === 130 || exit.exitCode === 143;
+    if (clean && report.browserLines > 0)
+        return undefined;
+    return new FireForgeError('smoke-launch-failed', clean
+        ? `The browser exited ${exit.exitCode} before the smoke window elapsed without printing anything`
+        : `The browser exited ${exit.exitCode} before the smoke window elapsed`, {
+        exitCode: ExitCode.SMOKE_LAUNCH_FAILURE,
+        hint: clean
+            ? 'A silent early exit means the launch never reached a window: look for a locked profile or a startup-crash streak.'
+            : 'Read the output above for the crash or startup error.',
+    });
+}

package/dist/src/engine/staleness.js

@@ -0,0 +1,229 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Whether a workspace's build still matches its engine. The one answer
+ * `test`, `run` and `package` all ask for.
+ *
+ * A successful build records a baseline in the workspace's state: a snapshot
+ * of the engine's working tree as a git tree (kept alive by a ref in the
+ * engine's repository), a second one for the last full build, and the digest
+ * of the mozconfig. Staleness is the diff from those snapshots to the working
+ * tree now, read through what each changed path means to the build:
+ *
+ *  - compiled sources and build definitions reach the browser only through a
+ *    full build, so they are compared with the last full build;
+ *  - packaged front-end files are compared with the last build of any kind,
+ *    and do not count while the object directory serves them by symlink;
+ *  - a `jar.mn` needs a full build only when the build backend has never
+ *    seen it, or when it installs outside the default chrome root; an entry
+ *    added to a known manifest is installed by a UI build;
+ *  - anything else (tests, documentation) never makes a build stale.
+ */
+import { join } from 'node:path';
+import { captureWorktree, changedPaths, commitTree, readBlobs, resolveRevision, updateRef, } from '../git/index.js';
+import { exists, readTextIfExists } from '../kernel/fs.js';
+import { hash } from '../kernel/hash.js';
+import { s } from '../kernel/schema.js';
+import { defineStateSection, readState, updateState } from '../project/index.js';
+import { deliveryOf, readInstallIndex } from './installManifests.js';
+import { renderMozconfig } from './mozconfig.js';
+import { findBrowserBinary, movedFrom } from './objdir.js';
+const baselineSection = defineStateSection('build', s.object({
+    kind: s.enum(['full', 'ui']),
+    builtAt: s.string(),
+    /** Commit wrapping the engine's working tree as the last build saw it. */
+    tree: s.string({ min: 1 }),
+    /** The same for the last full build. */
+    fullTree: s.string({ min: 1 }),
+    /** SHA-256 of the mozconfig the object directory was configured with. */
+    mozconfig: s.string({ min: 1 }),
+}), 'fireforge build');
+const COMPILED_EXTENSIONS = new Set('c cc cpp cxx h hh hpp m mm rs idl webidl ipdl ipdlh yaml yml s S asm inc tbl def'.split(' '));
+const COMPILED_NAMES = new Set(['Bindings.conf', 'Cargo.toml', 'Cargo.lock', 'components.conf']);
+/** Files the build backend is generated from. */
+const BACKEND_NAMES = new Set(['moz.build', 'moz.configure', 'Makefile.in', 'mozbuild.in']);
+const BACKEND_EXTENSIONS = new Set(['mozbuild', 'configure']);
+/** Directories whose compiled sources never reach the browser binary. */
+const NON_RUNTIME_SEGMENTS = new Set(['test', 'tests', 'gtest', 'testing', 'taskcluster']);
+const PACKAGED_EXTENSIONS = new Set('js mjs jsm css ftl xhtml xul html properties'.split(' '));
+const PACKAGED_FRAGMENTS = ['/app/profile/', '/chrome/', '/locales/'];
+/**
+ * Whether a path belongs to the test tree rather than the browser: a test
+ * directory, the harness tree, or a file named like a test.
+ *
+ * @param path - Engine-relative path
+ */
+export function isTestPath(path) {
+    if (/(?:^|\/)(?:test|tests|testing)\//.test(path))
+        return true;
+    return /^(?:browser|test)_.+\.(?:js|toml|ini)$/.test(path.slice(path.lastIndexOf('/') + 1));
+}
+/**
+ * How a changed engine path bears on the build, by its name alone.
+ *
+ * @param path - Engine-relative path
+ * @returns Undefined for a path no build consumes
+ */
+export function buildInputClass(path) {
+    const name = path.slice(path.lastIndexOf('/') + 1);
+    const extension = name.includes('.') ? name.slice(name.lastIndexOf('.') + 1) : '';
+    if (name === 'jar.mn')
+        return 'jar';
+    if (BACKEND_NAMES.has(name) || BACKEND_EXTENSIONS.has(extension))
+        return 'full';
+    if (COMPILED_EXTENSIONS.has(extension) || COMPILED_NAMES.has(name)) {
+        return path.split('/').some((segment) => NON_RUNTIME_SEGMENTS.has(segment))
+            ? undefined
+            : 'full';
+    }
+    if (PACKAGED_EXTENSIONS.has(extension) ||
+        PACKAGED_FRAGMENTS.some((part) => path.includes(part))) {
+        return 'ui';
+    }
+    return undefined;
+}
+/** A jar declaration that installs under another base directory: `[dir] name.jar:` at column zero. */
+const REDIRECTED_JAR = /^\[[^\]]*\]\s*[^\s[\]]+\.jar:\s*$/m;
+const digest = (text) => hash(text);
+/**
+ * Snapshots the engine as a build is about to read it: what a successful
+ * build then records, so an edit made while the build ran is not taken as
+ * built.
+ *
+ * @param workspace - The workspace
+ */
+export async function snapshotEngine(workspace) {
+    const { engineDir } = workspace;
+    const head = await resolveRevision(engineDir, 'HEAD', 'commit');
+    const tree = await commitTree(engineDir, await captureWorktree(engineDir), {
+        message: 'fireforge build input',
+        parents: head === undefined ? [] : [head],
+    });
+    const mozconfig = digest((await readTextIfExists(join(engineDir, 'mozconfig'))) ?? '');
+    return { tree, mozconfig };
+}
+/**
+ * Records that a build of the workspace succeeded, as the baseline
+ * {@link buildStaleness} measures from.
+ *
+ * @param workspace - The workspace
+ * @param kind - Which build ran
+ * @param snapshot - The engine as the build started reading it
+ * @returns The baseline as recorded
+ */
+export async function recordBuild(workspace, kind, snapshot) {
+    const { engineDir } = workspace;
+    const { tree, mozconfig } = snapshot;
+    await updateRef(engineDir, 'refs/fireforge/build/last', tree);
+    if (kind === 'full')
+        await updateRef(engineDir, 'refs/fireforge/build/full', tree);
+    const recorded = await updateState(workspace, baselineSection, (previous) => ({
+        kind,
+        builtAt: new Date().toISOString(),
+        tree,
+        // A UI build on top of nothing recorded can only follow a full build made elsewhere.
+        fullTree: kind === 'full' ? tree : (previous?.fullTree ?? tree),
+        mozconfig,
+    }));
+    return recorded;
+}
+/**
+ * The baseline of a workspace's last successful build.
+ *
+ * @param workspace - The workspace
+ */
+export function readBuildBaseline(workspace) {
+    return readState(workspace, baselineSection);
+}
+function stale(needs, why, paths = []) {
+    return { state: 'stale', paths: [...paths].sort(), needs, why };
+}
+/** The changed `jar.mn` files that a UI build cannot install. */
+async function escalatingJars(engineDir, jars, fullTree) {
+    if (jars.length === 0)
+        return [];
+    const known = await readBlobs(engineDir, jars.map((path) => `${fullTree}:${path}`));
+    const escalating = [];
+    for (const path of jars) {
+        const text = await readTextIfExists(join(engineDir, path));
+        // Removed: the backend still installs its entries. New: it has no install manifest yet.
+        if (text === undefined || !known.has(`${fullTree}:${path}`) || REDIRECTED_JAR.test(text)) {
+            escalating.push(path);
+        }
+    }
+    return escalating;
+}
+/** The changed front-end files the object directory does not already serve. */
+async function unserved(workspace, paths) {
+    if (paths.length === 0)
+        return [];
+    const { engineDir, objDir } = workspace;
+    const index = await readInstallIndex(engineDir, objDir);
+    const remaining = [];
+    for (const path of paths) {
+        if (!(await exists(join(engineDir, path)))) {
+            // A deleted file is served by nothing; whether it was ever packaged is all that matters.
+            if (!isTestPath(path))
+                remaining.push(path);
+            continue;
+        }
+        const delivery = index === undefined ? 'unlisted' : await deliveryOf(index, engineDir, path);
+        if (delivery === 'live' || delivery === 'at-test')
+            continue;
+        if (delivery === 'unlisted' && isTestPath(path))
+            continue;
+        remaining.push(path);
+    }
+    return remaining;
+}
+/**
+ * Whether the workspace's development build matches its engine.
+ *
+ * @param workspace - The workspace
+ * @returns `fresh`, or what changed and the smallest build that catches up
+ */
+export async function buildStaleness(workspace) {
+    const { engineDir, objDir, project } = workspace;
+    const baseline = await readBuildBaseline(workspace);
+    if (baseline === undefined)
+        return stale('full', 'no build of this workspace is recorded');
+    if ((await findBrowserBinary(objDir, project.config.binaryName)) === undefined) {
+        return stale('full', 'the object directory holds no launchable browser');
+    }
+    if ((await movedFrom(workspace)) !== undefined) {
+        return stale('full', 'the object directory was configured at another path and cannot be used here');
+    }
+    if (digest(await renderMozconfig(workspace)) !== baseline.mozconfig) {
+        return stale('full', 'the build configuration (configs/ or the identity) changed', [
+            'mozconfig',
+        ]);
+    }
+    for (const snapshot of [baseline.tree, baseline.fullTree]) {
+        if ((await resolveRevision(engineDir, snapshot, 'commit')) === undefined) {
+            return stale('full', "the engine's repository does not hold the recorded build");
+        }
+    }
+    const now = await captureWorktree(engineDir);
+    const sinceFull = await changedPaths(engineDir, baseline.fullTree, now);
+    const sinceLast = baseline.tree === baseline.fullTree
+        ? sinceFull
+        : await changedPaths(engineDir, baseline.tree, now);
+    const compiled = sinceFull.filter((path) => buildInputClass(path) === 'full');
+    const jars = await escalatingJars(engineDir, sinceFull.filter((path) => buildInputClass(path) === 'jar'), baseline.fullTree);
+    if (compiled.length > 0 || jars.length > 0) {
+        const what = [
+            ...(compiled.length > 0 ? [`${compiled.length} compiled source or build definition`] : []),
+            ...(jars.length > 0 ? [`${jars.length} jar.mn the build backend must regenerate for`] : []),
+        ];
+        return stale('full', `${what.join(' and ')} changed since the last full build`, [
+            ...compiled,
+            ...jars,
+        ]);
+    }
+    const frontEnd = [
+        ...sinceLast.filter((path) => buildInputClass(path) === 'jar'),
+        ...(await unserved(workspace, sinceLast.filter((path) => buildInputClass(path) === 'ui'))),
+    ];
+    return frontEnd.length === 0
+        ? { state: 'fresh' }
+        : stale('ui', `${frontEnd.length} packaged front-end file(s) changed since the last build`, frontEnd);
+}