@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/project/index.js

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The project context every command starts from: root discovery, the loaded
+ * configuration and mode, every well-known location, the git checkout, the
+ * project state document, and the owned-change model both modes produce.
+ */
+export { createChangeSet, netChange, textContent, } from './changes.js';
+export { readCheckout } from './checkout.js';
+export { hasLicenseHeader, hasUpstreamMplHeader, licenseHeader, mentionsLicense, } from './license.js';
+export { configuredPath, findProjectRoot, hostPaths, loadProject, projectPaths, } from './project.js';
+export { defineStateSection, readState, updateState } from './state.js';

package/dist/src/project/license.js

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * License headers of the fork's files: the header text of each project
+ * license per comment style, and recognising a header at the top of a file.
+ */
+import { PROJECT_LICENSES } from '../config/index.js';
+const HEADER_LINES = {
+    'MPL-2.0': [
+        'This Source Code Form is subject to the terms of the Mozilla Public',
+        'License, v. 2.0. If a copy of the MPL was not distributed with this',
+        'file, You can obtain one at http://mozilla.org/MPL/2.0/.',
+    ],
+    'EUPL-1.2': ['SPDX-License-Identifier: EUPL-1.2'],
+    'GPL-2.0-or-later': [
+        'SPDX-License-Identifier: GPL-2.0-or-later',
+        'This file is free software; you can redistribute it and/or modify it',
+        'under the terms of the GNU General Public License as published by the',
+        'Free Software Foundation; either version 2 of the License, or (at your',
+        'option) any later version.',
+    ],
+    '0BSD': ['SPDX-License-Identifier: 0BSD'],
+};
+/**
+ * The header the project writes at the top of a new file.
+ *
+ * @param license - The project license
+ * @param style - The file's comment style
+ */
+export function licenseHeader(license, style) {
+    const lines = HEADER_LINES[license];
+    if (style === 'hash')
+        return lines.map((line) => `# ${line}`).join('\n');
+    if (lines.length === 1)
+        return `/* ${lines[0] ?? ''} */`;
+    if (style === 'js')
+        return lines.map((line) => `// ${line}`).join('\n');
+    const [first, ...rest] = lines;
+    return [`/* ${first ?? ''}`, ...rest.map((line) => ` * ${line}`)].join('\n') + ' */';
+}
+const EDITOR_DIRECTIVE = /^[ \t]*\/\*[^\r\n]*?(?:-\*-|\bvim:)[^\r\n]*?\*\/[ \t]*\r?\n?/;
+/** Drops leading blank lines and `-*- … -*-` / `vim:` directive comments. */
+function withoutDirectives(content) {
+    let result = content;
+    for (let previous = ''; result !== previous;) {
+        previous = result;
+        result = result.replace(/^[ \t]*\r?\n/, '').replace(EDITOR_DIRECTIVE, '');
+    }
+    return result;
+}
+const normalize = (text) => text.replace(/\s+/g, ' ').trim();
+/** Upstream writes the MPL address with either scheme; headers are compared with one. */
+const oneScheme = (text) => text.replace('https://mozilla.org/MPL/2.0/', 'http://mozilla.org/MPL/2.0/');
+const MPL_TEXT = normalize(HEADER_LINES['MPL-2.0'].join(' '));
+/** The text of the leading comment, continuation markers removed, whitespace collapsed. */
+function leadingCommentText(content, style) {
+    const source = content.replace(/\r\n?/g, '\n');
+    const lineRun = (marker) => {
+        const parts = [];
+        for (const line of source.split('\n')) {
+            const match = marker.exec(line);
+            if (!match)
+                break;
+            parts.push(match[1] ?? '');
+        }
+        return normalize(parts.join(' '));
+    };
+    if (style === 'hash')
+        return lineRun(/^[ \t]*#[ \t]?(.*)$/);
+    if (style === 'js' && /^[ \t]*\/\//.test(source))
+        return lineRun(/^[ \t]*\/\/[ \t]?(.*)$/);
+    const block = /^[ \t]*\/\*([\s\S]*?)\*\//.exec(source);
+    if (!block)
+        return '';
+    return normalize((block[1] ?? '').replace(/^[ \t]*-[ \t]+/, '').replace(/\n[ \t]*[*-][ \t]*/g, ' '));
+}
+/**
+ * Whether content starts with any project license's header in the style,
+ * or with the MPL text however it is wrapped, behind any editor directives.
+ *
+ * @param content - File content
+ * @param style - The comment style to read
+ */
+export function hasLicenseHeader(content, style) {
+    const text = oneScheme(content);
+    return [text, withoutDirectives(text)].some((candidate) => PROJECT_LICENSES.some((license) => candidate.startsWith(licenseHeader(license, style))) ||
+        (style === 'js' && candidate.startsWith(licenseHeader('MPL-2.0', 'css'))) ||
+        leadingCommentText(candidate, style).startsWith(MPL_TEXT));
+}
+/**
+ * Whether content starts with the upstream MPL block header (`/* … *\/`),
+ * however wrapped, behind any editor directives: what a file copied from
+ * Firefox keeps for provenance.
+ *
+ * @param content - File content
+ */
+export function hasUpstreamMplHeader(content) {
+    const text = oneScheme(content);
+    return [text, withoutDirectives(text)].some((candidate) => candidate.startsWith(licenseHeader('MPL-2.0', 'css')) ||
+        leadingCommentText(candidate, 'css').startsWith(MPL_TEXT));
+}
+/** The start of a comment's continuation line: `//`, `*`, `#` or the `-` of a markup comment. */
+const CONTINUATION = /\n[ \t]*(?:\/\/+|[*#-])[ \t]*/g;
+/**
+ * Whether a license notice is mentioned anywhere near the top of a file,
+ * in any comment form and however the notice is wrapped across lines.
+ *
+ * @param content - File content
+ */
+export function mentionsLicense(content) {
+    const head = normalize(content.replace(/\r\n?/g, '\n').split('\n').slice(0, 10).join('\n').replace(CONTINUATION, ' '));
+    return ([
+        'Mozilla Public License',
+        'SPDX-License-Identifier',
+        'Apache License',
+        'MIT License',
+        'GNU General Public License',
+    ].some((marker) => head.includes(marker)) ||
+        /dedicated to the public domain|creativecommons\.org\/publicdomain\/zero\/1\.0|spdx-license-identifier:\s*cc0-1\.0\b/i.test(head));
+}

package/dist/src/project/project.js

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The project every command starts from: where it is, its validated
+ * configuration, its mode, and every well-known location named once.
+ */
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { CONFIG_FILE, loadConfig, } from '../config/index.js';
+import { defined, ExitCode, FireForgeError } from '../kernel/errors.js';
+import { exists } from '../kernel/fs.js';
+import { readCheckout } from './checkout.js';
+/**
+ * The locations both modes share, for a project directory.
+ *
+ * @param root - The project directory
+ */
+export function projectPaths(root) {
+    const stateDir = join(root, '.fireforge');
+    return {
+        root,
+        config: join(root, CONFIG_FILE),
+        furnace: join(root, 'furnace.json'),
+        stateDir,
+        state: join(stateDir, 'state.json'),
+        patches: join(root, 'patches'),
+        components: join(root, 'components'),
+        configs: join(root, 'configs'),
+    };
+}
+/**
+ * The per-host state locations: `FIREFORGE_HOME` when set, else `~/.fireforge`.
+ *
+ * @param env - The environment to read `FIREFORGE_HOME` from
+ * @throws `fireforge-home-invalid` (exit code 2) when it is set to a relative path
+ */
+export function hostPaths(env = process.env) {
+    const configured = env['FIREFORGE_HOME'];
+    if (configured !== undefined && configured !== '' && !isAbsolute(configured)) {
+        throw new FireForgeError('fireforge-home-invalid', `FIREFORGE_HOME must be an absolute path (got "${configured}")`, { exitCode: ExitCode.CONFIG_ERROR, hint: 'Set it to an absolute directory, or unset it.' });
+    }
+    const root = configured === undefined || configured === '' ? join(homedir(), '.fireforge') : configured;
+    return {
+        root,
+        pristine: join(root, 'pristine'),
+        workspaces: join(root, 'workspaces'),
+        locks: join(root, 'locks'),
+        cache: join(root, 'cache'),
+    };
+}
+/**
+ * The project directory: `cwd` or the nearest directory above it holding
+ * `fireforge.json`.
+ *
+ * @param cwd - Where the command was run
+ * @throws `project-not-found` (exit code 2) when no directory up to the file-system root has one
+ */
+export async function findProjectRoot(cwd) {
+    for (let current = resolve(cwd);; current = dirname(current)) {
+        if (await exists(join(current, CONFIG_FILE)))
+            return current;
+        if (dirname(current) === current)
+            break;
+    }
+    throw new FireForgeError('project-not-found', `No ${CONFIG_FILE} in ${resolve(cwd)} or any directory above it`, {
+        exitCode: ExitCode.CONFIG_ERROR,
+        hint: 'Run the command inside a project, or create one with "fireforge setup".',
+    });
+}
+/**
+ * Finds and loads the project containing `cwd`: its validated configuration,
+ * its locations, the host locations and the git checkout it sits in.
+ *
+ * @param cwd - Where the command was run
+ * @param env - The environment of the invocation
+ * @throws `project-not-found`, `config-missing` or `config-invalid` (exit code 2)
+ */
+export async function loadProject(cwd, env = process.env) {
+    const root = await findProjectRoot(cwd);
+    const config = await loadConfig(root);
+    const base = { root, host: hostPaths(env), checkout: await readCheckout(root) };
+    const paths = projectPaths(root);
+    if (config.mode === 'patches') {
+        return { ...base, mode: 'patches', config, paths: { ...paths, engine: join(root, 'engine') } };
+    }
+    const source = defined(config.source, 'the schema requires a source block in source mode');
+    return {
+        ...base,
+        mode: 'source',
+        config: { ...config, mode: 'source', source },
+        paths: {
+            ...paths,
+            source: join(root, source.root),
+            sourceMetadata: join(root, source.metadataRoot),
+        },
+    };
+}
+/**
+ * Which file a path written in the configuration names: `engine/<path>` is
+ * engine file `<path>`, wherever the engine is; anything else is relative to
+ * the project directory.
+ *
+ * @param path - A relative path as configured
+ */
+export function configuredPath(path) {
+    const normalized = path.replace(/^(?:\.\/)+/, '');
+    if (normalized === 'engine')
+        return { tree: 'engine', path: '' };
+    return normalized.startsWith('engine/')
+        ? { tree: 'engine', path: normalized.slice('engine/'.length) }
+        : { tree: 'project', path: normalized };
+}

package/dist/src/project/state.js

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The project state document, `.fireforge/state.json`. It is one JSON object
+ * of named sections; each module that keeps state declares its section with
+ * {@link defineStateSection} and its own schema, and reads and updates only
+ * that section. Sections it does not know are carried through untouched.
+ *
+ * A section that fails its schema is an error naming the section, the key
+ * path and the command that repairs it; it is never silently reset. Updates
+ * are serialised by a lock, and the file is replaced atomically, so a reader
+ * never sees a half-written document and no update is lost.
+ */
+import { join } from 'node:path';
+import { ExitCode, FireForgeError, invariant } from '../kernel/errors.js';
+import { readJsonIfExists, writeJson } from '../kernel/json.js';
+import { withLock } from '../kernel/lock.js';
+import { s } from '../kernel/schema.js';
+/**
+ * Declares a section of the state document.
+ *
+ * @param key - Top-level key, unique across modules
+ * @param schema - What the section holds
+ * @param repair - The command that repairs an invalid section
+ */
+export function defineStateSection(key, schema, repair) {
+    return { key, schema, repair };
+}
+const StateDocument = s.record(s.unknown());
+async function readDocument(paths) {
+    const document = await readJsonIfExists(paths.state, StateDocument, {
+        code: 'state-invalid',
+        exitCode: ExitCode.CONFIG_ERROR,
+        hint: `Move ${paths.state} aside; each command recreates the state it needs.`,
+    });
+    return document ?? {};
+}
+function sectionOf(paths, document, section) {
+    const raw = document[section.key];
+    if (raw === undefined)
+        return undefined;
+    const result = section.schema.validate(raw);
+    if (result.ok)
+        return result.value;
+    const lines = result.issues.map((issue) => {
+        const at = issue.path === '' ? '' : issue.path.startsWith('[') ? issue.path : `.${issue.path}`;
+        return `"${section.key}${at}" ${issue.message}`;
+    });
+    throw new FireForgeError('state-invalid', `${paths.state}: ${lines.join('; ')}`, {
+        exitCode: ExitCode.CONFIG_ERROR,
+        hint: `Run "${section.repair}" to repair it.`,
+    });
+}
+/**
+ * Reads one section of the state document.
+ *
+ * @param project - The project whose state to read
+ * @param section - The section
+ * @returns The section, or undefined when the document or the section is absent
+ * @throws `state-invalid` (exit code 2) when the document or the section is malformed
+ */
+export async function readState(project, section) {
+    return sectionOf(project.paths, await readDocument(project.paths), section);
+}
+/**
+ * Replaces one section of the state document with what `update` returns,
+ * under the state lock. Returning undefined removes the section.
+ *
+ * @param project - The project whose state to update
+ * @param section - The section
+ * @param update - Receives the current section (undefined when absent) and returns the next
+ * @returns The section as written
+ * @throws `state-invalid` (exit code 2) when the current document or section is malformed
+ */
+export async function updateState(project, section, update) {
+    const { paths } = project;
+    const lock = join(paths.stateDir, 'state.lock');
+    return withLock(lock, { label: 'project state' }, async () => {
+        const document = await readDocument(paths);
+        const next = update(sectionOf(paths, document, section));
+        invariant(next === undefined || section.schema.validate(next).ok, () => `the update of state section "${section.key}" does not match its schema`);
+        // An undefined value is dropped by serialisation, which removes the section.
+        await writeJson(paths.state, { ...document, [section.key]: next });
+        return next;
+    });
+}

package/dist/src/project/tracked.js

@@ -0,0 +1 @@
+export {};

package/dist/src/queue/apply.js

@@ -0,0 +1,270 @@
+import { apply, emptyTree, listTree, writeTree } from '../git/index.js';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { resolveContained } from '../kernel/fs.js';
+import { pathsOf, readQueue } from './queue.js';
+/** `-C` values after the exact attempt: git's default context is three lines. */
+const REDUCED_CONTEXT = [2, 1, 0];
+/**
+ * Whether engine path `path` is `root` or lies under it. The empty root
+ * covers every path.
+ *
+ * @param root - An engine file or directory, a trailing slash allowed
+ * @param path - An engine path
+ */
+export function covers(root, path) {
+    const prefix = root.replace(/\/+$/, '');
+    return prefix === '' || path === prefix || path.startsWith(`${prefix}/`);
+}
+/** Why an engine path in a patch is unsafe to write, or undefined. */
+function unsafePath(path) {
+    if (path === '' || path.includes('\0') || path.includes('\\'))
+        return 'is not a valid path';
+    if (path.startsWith('/'))
+        return 'is absolute';
+    const segments = path.split('/');
+    if (segments.some((segment) => segment === '..' || segment === '.' || segment === '')) {
+        return 'leaves the engine or is not canonical';
+    }
+    return segments[0]?.toLowerCase() === '.git' ? 'is inside .git' : undefined;
+}
+/** Path and content problems that make a patch unappliable before git sees it. */
+export function patchProblems(diff) {
+    const problems = [];
+    if (diff.files.length === 0 && diff.preamble.some((line) => line.trim() !== '')) {
+        problems.push({ path: '', reason: 'the body holds text but no diff section' });
+    }
+    for (const file of diff.files) {
+        for (const path of new Set([file.oldPath, file.newPath])) {
+            const why = unsafePath(path);
+            if (why !== undefined)
+                problems.push({ path, reason: `path ${why}` });
+        }
+        if (file.binary === 'stub') {
+            problems.push({
+                path: file.path,
+                reason: 'binary section carries no content ("Binary files … differ"); re-export the patch',
+            });
+        }
+    }
+    return problems;
+}
+function refused(conflicts, message) {
+    return { applied: false, conflicts, message };
+}
+async function ladder(repo, tree, body, fuzz) {
+    const exact = await apply(repo, body, { target: { tree } });
+    if (exact.applied && exact.tree !== undefined)
+        return { tree: exact.tree, fuzz: 0 };
+    if (fuzz) {
+        for (const [step, context] of REDUCED_CONTEXT.entries()) {
+            const reduced = await apply(repo, body, { target: { tree }, context });
+            if (reduced.applied && reduced.tree !== undefined) {
+                return { tree: reduced.tree, fuzz: step + 1 };
+            }
+        }
+    }
+    return { conflicts: exact.conflicts, message: exact.stderr.trim() };
+}
+/** New-file sections whose target the tree already holds from upstream. */
+function occupiedNewFiles(diff, conflicts, replaceable) {
+    const occupied = new Set(conflicts.filter((conflict) => conflict.reason.startsWith('already exists')).map((c) => c.path));
+    const sections = diff.files.filter((file) => file.status === 'added' && occupied.has(file.path));
+    return sections.every((file) => replaceable.has(file.path)) ? sections : [];
+}
+/**
+ * Applies a patch to a tree, index-only. Nothing in the repository's index
+ * or working tree moves.
+ *
+ * @param repo - The repository holding the tree and the blobs the patch needs
+ * @param tree - The tree to apply to
+ * @param patch - The patch
+ * @param options - `fuzz` allows reduced context after the exact attempt;
+ *   `replaceable` names the paths holding upstream content that a new-file
+ *   section may replace
+ */
+export async function applyToTree(repo, tree, patch, options = {}) {
+    const problems = patchProblems(patch.diff);
+    if (problems.length > 0) {
+        return refused(problems, problems.map((problem) => `${problem.path}: ${problem.reason}`).join('\n'));
+    }
+    const fuzz = options.fuzz === true;
+    const first = await ladder(repo, tree, patch.body, fuzz);
+    if ('tree' in first)
+        return { applied: true, ...first, replaced: [] };
+    const occupied = occupiedNewFiles(patch.diff, first.conflicts, options.replaceable ?? new Set());
+    if (occupied.length === 0)
+        return refused(first.conflicts, first.message);
+    const cleared = await writeTree(repo, occupied.map((file) => ({ path: file.path, remove: true })), tree);
+    const second = await ladder(repo, cleared, patch.body, fuzz);
+    if (!('tree' in second))
+        return refused(first.conflicts, first.message);
+    return { applied: true, ...second, replaced: occupied.map((file) => file.path) };
+}
+/**
+ * Takes a patch back out of a tree, index-only and exactly: the tree the
+ * patch, applied, would turn into `tree`.
+ *
+ * @param repo - The repository holding the tree
+ * @param tree - A tree holding the patch's result
+ * @param patch - The patch
+ */
+export async function unapplyFromTree(repo, tree, patch) {
+    const problems = patchProblems(patch.diff);
+    if (problems.length > 0) {
+        return refused(problems, problems.map((problem) => `${problem.path}: ${problem.reason}`).join('\n'));
+    }
+    const result = await apply(repo, patch.body, { target: { tree }, reverse: true });
+    return result.applied && result.tree !== undefined
+        ? { applied: true, tree: result.tree, fuzz: 0, replaced: [] }
+        : refused(result.conflicts, result.stderr.trim());
+}
+/**
+ * Applies the hunks of a patch that fit to the working tree and leaves the
+ * rest in `<file>.rej` files, for the user to finish by hand.
+ *
+ * @param engine - The engine checkout
+ * @param patch - The patch that did not apply to a tree
+ * @throws `path-escape` (exit code 8) when a path leaves the engine or passes through a symlink
+ */
+export async function applyWithRejects(engine, patch) {
+    const problems = patchProblems(patch.diff);
+    if (problems.length > 0) {
+        return {
+            applied: false,
+            rejects: [],
+            conflicts: problems,
+            message: problems.map((problem) => `${problem.path}: ${problem.reason}`).join('\n'),
+        };
+    }
+    for (const file of patch.diff.files) {
+        for (const path of new Set([file.oldPath, file.newPath]))
+            await resolveContained(engine, path);
+    }
+    const result = await apply(engine, patch.body, { reject: true });
+    return {
+        applied: result.applied,
+        rejects: result.rejected.map((path) => `${path}.rej`),
+        conflicts: result.conflicts,
+        message: result.stderr.trim(),
+    };
+}
+/**
+ * The tree of `commit` cut down to `paths`: the starting point of a replay.
+ *
+ * @param repo - The repository
+ * @param commit - A commit or tree
+ * @param paths - Engine paths; directories are not expected
+ */
+export async function sparseTree(repo, commit, paths) {
+    if (paths.length === 0)
+        return emptyTree(repo);
+    const entries = await listTree(repo, commit, { paths });
+    return writeTree(repo, entries
+        .filter((entry) => entry.type === 'blob')
+        .map((entry) => ({ path: entry.path, oid: entry.oid, mode: entry.mode })));
+}
+/**
+ * The state of each path in a tree; a path the tree lacks maps to null.
+ *
+ * @param repo - The repository
+ * @param tree - The tree
+ * @param paths - The paths to look up
+ */
+export async function statesIn(repo, tree, paths) {
+    const states = new Map(paths.map((path) => [path, null]));
+    if (paths.length === 0)
+        return states;
+    for (const entry of await listTree(repo, tree, { paths })) {
+        if (entry.type === 'blob' && states.has(entry.path)) {
+            states.set(entry.path, { oid: entry.oid, mode: entry.mode });
+        }
+    }
+    return states;
+}
+/**
+ * Applies patches in order, each to the tree the previous one produced.
+ *
+ * @param repo - The repository
+ * @param start - The tree to start from (see {@link sparseTree})
+ * @param patches - The patches, in apply order
+ * @param options - `fuzz` allows reduced context; `keepGoing` continues past
+ *   a patch that does not apply, from the tree before it, so later verdicts
+ *   are still reported (and may follow from the earlier failure); `upstream`
+ *   is the tree holding the upstream files a new-file section may replace,
+ *   when `start` already holds earlier patches' work (default `start`)
+ */
+export async function replay(repo, start, patches, options = {}) {
+    const allPaths = pathsOf(patches);
+    const current = await statesIn(repo, start, allPaths);
+    const upstream = options.upstream === undefined || options.upstream === start
+        ? new Map(current)
+        : await statesIn(repo, options.upstream, allPaths);
+    const steps = [];
+    const failures = [];
+    let tree = start;
+    for (const [index, patch] of patches.entries()) {
+        const replaceable = new Set(patch.files.filter((path) => {
+            const state = upstream.get(path) ?? null;
+            const now = current.get(path) ?? null;
+            return state !== null && now?.oid === state.oid && now.mode === state.mode;
+        }));
+        const outcome = await applyToTree(repo, tree, patch, {
+            fuzz: options.fuzz === true,
+            replaceable,
+        });
+        if (!outcome.applied) {
+            failures.push({
+                index,
+                patch: patch.filename,
+                conflicts: outcome.conflicts,
+                message: outcome.message,
+            });
+            if (options.keepGoing === true)
+                continue;
+            break;
+        }
+        const after = await statesIn(repo, outcome.tree, patch.files);
+        const changes = [];
+        for (const [path, state] of after) {
+            const before = current.get(path) ?? null;
+            if (before?.oid !== state?.oid || before?.mode !== state?.mode) {
+                changes.push({ path, state });
+                current.set(path, state);
+            }
+        }
+        steps.push({
+            patch: patch.filename,
+            tree: outcome.tree,
+            fuzz: outcome.fuzz,
+            replaced: outcome.replaced,
+            changes,
+        });
+        tree = outcome.tree;
+    }
+    return { steps, failures, tree };
+}
+/**
+ * Applies the queue stored in a directory onto a commit, index-only, and
+ * returns the resulting full tree: what an engine at that commit holds once
+ * the queue is applied. Independent of any project.
+ *
+ * @param repo - A repository holding the commit (a pristine repository)
+ * @param commit - The commit to apply onto
+ * @param queueDir - A queue directory (manifest and patch files)
+ * @returns The tree's id
+ * @throws `queue-does-not-apply` (exit code 6) naming the first patch that does not apply
+ */
+export async function replayQueue(repo, commit, queueDir) {
+    const queue = await readQueue(queueDir);
+    const paths = pathsOf(queue.patches);
+    const result = await replay(repo, await sparseTree(repo, commit, paths), queue.patches);
+    const failure = result.failures[0];
+    if (failure !== undefined) {
+        throw new FireForgeError('queue-does-not-apply', `${failure.patch} does not apply to ${commit}: ${failure.message}`, {
+            exitCode: ExitCode.PATCH_ERROR,
+            hint: 'Run "fireforge import", fix the engine where it stops, then "fireforge resolve".',
+        });
+    }
+    const states = await statesIn(repo, result.tree, paths);
+    return writeTree(repo, [...states].map(([path, state]) => state === null ? { path, remove: true } : { path, oid: state.oid, mode: state.mode }), commit);
+}