@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/mode/migrate.js

@@ -0,0 +1,181 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Moving a patch-mode project to source mode: the queue is replayed onto the
+ * pristine commit, the resulting tree is adopted as owned files and override
+ * records, and `fireforge.json` takes the `mode` and `source` keys plus what
+ * the manifest carried per patch (tier, waivers) and the created-file groups
+ * that keep each patch's files together in an export.
+ *
+ * The conversion is in place and needs a committed git tree: everything
+ * written is undone on failure, and afterwards `git` is the undo.
+ */
+import { join, relative } from 'node:path';
+import { CONFIG_FILE, configSchema, readConfigDocument } from '../config/index.js';
+import { listTree, status as gitStatus } from '../git/index.js';
+import { defined, ExitCode, FireForgeError } from '../kernel/errors.js';
+import { remove, toPosixPath, writeFile } from '../kernel/fs.js';
+import { isRecord, stringifyJson } from '../kernel/json.js';
+import { loadProject } from '../project/index.js';
+import { readQueue, replayQueue, requirePatchMode } from '../queue/index.js';
+import { adoptTrees, installMergeDriver, requireSourceMode, sourceChanges, } from '../source/index.js';
+import { ownedTree } from './export.js';
+import { pinnedPristine } from './pristine.js';
+const SOURCE_ROOT = 'src';
+const METADATA_ROOT = '.fireforge-sources';
+const ancestors = (path) => {
+    const parts = path.split('/').slice(0, -1);
+    return parts.map((_, index) => parts.slice(0, index + 1).join('/'));
+};
+/**
+ * The globs that select each patch's created files: `<dir>/**` for the
+ * shallowest directory the project itself created whose files all belong to
+ * that patch, else the file. A directory upstream has is never claimed
+ * whole, so a file created there later is not swept into the group.
+ */
+function createdGlobs(owners, upstream) {
+    const directoryOwners = new Map();
+    for (const [path, owner] of owners) {
+        for (const directory of ancestors(path)) {
+            directoryOwners.set(directory, (directoryOwners.get(directory) ?? new Set()).add(owner));
+        }
+    }
+    const globs = new Map();
+    for (const [path, owner] of owners) {
+        const whole = ancestors(path).find((directory) => !upstream.has(directory) && directoryOwners.get(directory)?.size === 1);
+        globs.set(owner, (globs.get(owner) ?? new Set()).add(whole === undefined ? path : `${whole}/**`));
+    }
+    return new Map([...globs].sort(([a], [b]) => (a < b ? -1 : 1)).map(([owner, set]) => [owner, [...set].sort()]));
+}
+function section(document, key) {
+    const value = document[key];
+    return isRecord(value) ? value : {};
+}
+/** The source-mode `fireforge.json` document for the migrated project. */
+function migratedConfig(document, queue, adopted, pristine) {
+    const ownerOf = (path) => queue.patches.find((patch) => patch.files.includes(path))?.name;
+    const createdOwners = new Map(adopted.created.flatMap((path) => {
+        const owner = ownerOf(path);
+        return owner === undefined ? [] : [[path, owner]];
+    }));
+    const tiers = new Map(queue.patches.flatMap((patch) => patch.tier === undefined ? [] : [[patch.name, patch.tier]]));
+    const upstreamOwners = new Set([...adopted.overridden, ...adopted.deleted].map((path) => ownerOf(path)));
+    // A patch that changed upstream files and created others becomes two
+    // groups, and two groups may not share an ID.
+    const createdGroup = (patch) => upstreamOwners.has(patch) ? `${patch}-created` : patch;
+    const groups = [...createdGlobs(createdOwners, pristine.directories)].map(([name, paths]) => ({
+        name: createdGroup(name),
+        paths,
+        ...(tiers.has(name) ? { tier: tiers.get(name) } : {}),
+    }));
+    const componentTiers = Object.fromEntries([...tiers].filter(([name]) => upstreamOwners.has(name)));
+    const created = new Set(createdOwners.values());
+    const waivers = queue.patches.flatMap((patch) => [
+        ...(upstreamOwners.has(patch.name) ? [patch.name] : []),
+        ...(created.has(patch.name) ? [createdGroup(patch.name)] : []),
+    ].flatMap((group) => (patch.lintIgnore ?? []).map((entry) => typeof entry === 'string'
+        ? { group, rule: entry, reason: `Carried over from patch ${patch.name}` }
+        : {
+            group,
+            rule: entry.rule,
+            max: entry.max,
+            reason: entry.reason,
+            ...(entry.share === undefined ? {} : { share: entry.share }),
+        })));
+    const exportQueue = {
+        ...section(document, 'exportQueue'),
+        ...(groups.length === 0 ? {} : { groups }),
+        ...(Object.keys(componentTiers).length === 0 ? {} : { componentTiers }),
+    };
+    const patchLint = {
+        ...section(document, 'patchLint'),
+        ...(waivers.length === 0 ? {} : { waivers }),
+    };
+    return {
+        ...document,
+        mode: 'source',
+        source: { root: SOURCE_ROOT, metadataRoot: METADATA_ROOT, pristineCommit: pristine.commit },
+        ...(Object.keys(exportQueue).length === 0 ? {} : { exportQueue }),
+        ...(Object.keys(patchLint).length === 0 ? {} : { patchLint }),
+    };
+}
+async function assertCommitted(project) {
+    const worktree = project.checkout.worktree;
+    const refuse = (message) => new FireForgeError('migrate-needs-clean-tree', message, {
+        exitCode: ExitCode.GIT_ERROR,
+        hint: 'Commit the project first: git is the undo of a migration.',
+    });
+    if (worktree === undefined)
+        throw refuse('The project is not in a git repository.');
+    const inside = toPosixPath(relative(worktree, project.root));
+    const dirty = await gitStatus(worktree, inside === '' ? {} : { paths: [inside] });
+    if (dirty.length > 0) {
+        throw refuse(`The project has ${dirty.length} uncommitted change(s), such as ${dirty[0]?.path ?? ''}.`);
+    }
+}
+/**
+ * Converts a patch-mode project to source mode, in place, and proves the
+ * result: the tree re-derived from the written owned files and records must
+ * equal the tree the queue replays to. `patches/` is removed; `export`
+ * writes it again as generated output.
+ *
+ * @param project - A committed patch-mode project whose pin has been downloaded
+ * @throws `patch-mode-required`, `pristine-missing`, `queue-does-not-apply`,
+ *   `migrate-needs-clean-tree`, `adopt-destination-not-empty`,
+ *   `migrate-mismatch` (exit code 6) when the result does not reproduce the queue
+ */
+export async function migrate(project) {
+    const patches = requirePatchMode(project);
+    const { root } = project;
+    await assertCommitted(project);
+    const pristine = await pinnedPristine(project);
+    const queue = await readQueue(patches.paths.patches);
+    const tree = await replayQueue(pristine.repo, pristine.commit, queue.dir);
+    const { document, text } = await readConfigDocument(root);
+    const configPath = join(root, CONFIG_FILE);
+    let adopted;
+    let migrated;
+    try {
+        adopted = await adoptTrees(pristine, { repo: pristine.repo, tree }, {
+            destination: root,
+            sourceRoot: SOURCE_ROOT,
+            metadataRoot: METADATA_ROOT,
+            ownerOf: (path) => ({
+                component: defined(queue.patches.find((patch) => patch.files.includes(path))?.name, 'a path the replay changed is in a patch'),
+            }),
+        });
+        // Listing a directory's entries proves the directory and every ancestor of it.
+        const upstream = await listTree(pristine.repo, pristine.commit, {
+            paths: [...new Set(adopted.created.flatMap(ancestors))].map((directory) => `${directory}/`),
+            recursive: false,
+        });
+        const config = migratedConfig(document, queue, adopted, {
+            commit: pristine.commit,
+            directories: new Set(upstream.flatMap((entry) => ancestors(entry.path))),
+        });
+        configSchema.parse(config, { source: configPath, code: 'config-invalid' });
+        await writeFile(configPath, stringifyJson(config));
+        migrated = requireSourceMode(await loadProject(root, { FIREFORGE_HOME: project.host.root }));
+        const derived = await ownedTree(pristine, await sourceChanges(migrated, pristine));
+        if (derived !== tree) {
+            throw new FireForgeError('migrate-mismatch', 'The owned files and records written do not reproduce the tree the patch queue replays to.', { exitCode: ExitCode.PATCH_ERROR, hint: 'Nothing was kept. Report this.' });
+        }
+    }
+    catch (error) {
+        // A source or metadata root that was refused as occupied holds nothing of ours to undo.
+        const occupied = error instanceof FireForgeError && error.code === 'adopt-destination-not-empty';
+        if (!occupied) {
+            await remove(join(root, SOURCE_ROOT));
+            await remove(join(root, METADATA_ROOT));
+            await writeFile(configPath, text);
+        }
+        throw error;
+    }
+    await remove(patches.paths.patches);
+    await installMergeDriver(migrated);
+    return {
+        created: [...adopted.created],
+        overridden: [...adopted.overridden],
+        deleted: [...adopted.deleted],
+        pristineCommit: pristine.commit,
+    };
+}

package/dist/src/mode/previousWaivers.js

@@ -0,0 +1,206 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Placing the waivers of the previous format on groups. A previous waiver
+ * named the paths one patch had held; a current one names a group, so each
+ * check goes to the groups that hold exactly those paths:
+ *
+ * - A size check measured the upstream changes of the waiver's component,
+ *   which is a group by the same name.
+ * - Any other check applied per path. Upstream paths are in their
+ *   component's group. Created paths are reached through the declared
+ *   `exportQueue.groups` they fill completely; the rest get a group of their
+ *   own, named after the component, so the waiver reaches them and no other
+ *   file. Files a Furnace component deploys are in that component's group,
+ *   which no configuration can split.
+ *
+ * A check is never placed where it would reach a file the previous waiver
+ * did not cover: it is a blocker, or, where only a person can decide to
+ * waive the wider group, it is left out and reported.
+ */
+import { LINT_RULE_IDS } from '../config/index.js';
+import { isRecord } from '../kernel/json.js';
+import { exportedPatchName } from '../source/index.js';
+/** Rules that measure a whole group rather than judge one path. */
+const SIZE_RULES = new Set(['large-patch-lines', 'large-patch-files']);
+/**
+ * The groups a per-path check of one waiver lands on, or the reason it
+ * cannot be placed. Creates the waiver's own group of created files when it
+ * needs one.
+ */
+function perPathGroups(waiver, owned, plan) {
+    const covered = new Set(waiver.paths);
+    const inside = (group) => (owned.members.get(group) ?? []).every((path) => covered.has(path));
+    const live = waiver.paths.flatMap((path) => owned.entries.get(path) ?? []);
+    const upstream = new Set(live.filter((entry) => entry.kind !== 'create').map((entry) => entry.group));
+    const widened = [...upstream].filter((group) => !inside(group));
+    if (widened.length > 0) {
+        return {
+            blocker: `covers some upstream paths of component ${widened.join(', ')} and not others; a waiver names a whole group`,
+        };
+    }
+    const whole = new Set();
+    const partial = new Set();
+    const loose = [];
+    for (const entry of live.filter((candidate) => candidate.kind === 'create')) {
+        const fixed = owned.declared.has(entry.group) || owned.furnace.has(entry.group);
+        if (fixed && inside(entry.group))
+            whole.add(entry.group);
+        else if (owned.furnace.has(entry.group))
+            partial.add(entry.group);
+        else
+            loose.push(entry.path);
+    }
+    if (loose.length === 0)
+        return { groups: [...upstream, ...whole], partial: [...partial] };
+    const name = exportedPatchName(waiver.component);
+    if (!plan.groups.some((group) => group.name === name)) {
+        const unsafe = loose.find((path) => /[*?]/.test(path));
+        if (unsafe !== undefined)
+            return { blocker: `covers ${unsafe}, which a glob cannot name literally` };
+        if (owned.taken.has(name)) {
+            return {
+                blocker: `needs a group "${name}" for the created files it covers, and that ID is taken; declare an exportQueue.groups entry holding exactly those files`,
+            };
+        }
+        owned.taken.add(name);
+        plan.groups.push({ name, paths: [...loose].sort() });
+        plan.converted.push({
+            key: `waivers.json ${waiver.component}`,
+            message: `its ${loose.length} created file(s) are now exportQueue group "${name}", which its waivers name`,
+        });
+    }
+    return { groups: [...upstream, ...whole, name], partial: [...partial] };
+}
+function placeWaiver(waiver, owned, plan) {
+    const at = `waivers.json ${waiver.component}`;
+    const isComponent = owned.components.has(waiver.component);
+    const add = (entry) => {
+        const same = (other) => other.group === entry.group && other.rule === entry.rule && other.share === entry.share;
+        if (!plan.waivers.some(same))
+            plan.waivers.push(entry);
+    };
+    if (waiver.tier !== undefined && isComponent) {
+        plan.componentTiers[waiver.component] = waiver.tier;
+        plan.converted.push({ key: `${at} tier`, message: 'is now exportQueue.componentTiers' });
+    }
+    else if (waiver.tier !== undefined) {
+        plan.removed.push({
+            key: `${at} tier`,
+            message: 'the tier bounded the upstream changes of the component, which has none',
+        });
+    }
+    for (const [index, check] of waiver.checks.entries()) {
+        const key = `${at} checks[${index}]`;
+        const rule = typeof check === 'string' ? check : check.rule;
+        if (!LINT_RULE_IDS.includes(rule)) {
+            plan.blockers.push({ key, message: `waives "${rule}", which is not a lint rule` });
+            continue;
+        }
+        const entry = (group) => typeof check === 'string'
+            ? { group, rule, reason: `Carried over from ${waiver.component}` }
+            : {
+                group,
+                rule,
+                max: check.max,
+                reason: check.reason,
+                ...(check.share === undefined ? {} : { share: check.share }),
+            };
+        if (typeof check !== 'string' && check.meta !== undefined) {
+            plan.removed.push({
+                key: `${key}.meta`,
+                message: `a waiver holds no notes besides its reason; it held ${JSON.stringify(check.meta)}`,
+            });
+        }
+        if (SIZE_RULES.has(rule)) {
+            if (isComponent)
+                add(entry(waiver.component));
+            else {
+                plan.removed.push({
+                    key,
+                    message: `"${rule}" bounded the upstream changes of the component, which has none`,
+                });
+            }
+            continue;
+        }
+        const placed = perPathGroups(waiver, owned, plan);
+        if ('blocker' in placed) {
+            plan.blockers.push({ key, message: placed.blocker });
+            continue;
+        }
+        if (placed.groups.length + placed.partial.length === 0) {
+            plan.removed.push({ key, message: `"${rule}" covered paths the project no longer owns` });
+        }
+        for (const group of placed.groups)
+            add(entry(group));
+        for (const group of placed.partial) {
+            plan.manual.push({
+                key,
+                message: `"${rule}" covered some files of Furnace component ${group} and not others; a waiver names a whole group. ` +
+                    `It was not carried over: add ${JSON.stringify(entry(group))} to patchLint.waivers to waive the whole component, or fix what lint reports`,
+            });
+        }
+    }
+}
+/**
+ * Places every previous waiver on the groups of the project's owned paths.
+ *
+ * @param previous - The waivers of the previous format
+ * @param status - The owned paths and their groups
+ * @param declared - The names of the declared `exportQueue.groups`
+ * @param components - The files each Furnace component deploys
+ */
+export function placeWaivers(previous, status, declared, components = []) {
+    const plan = {
+        waivers: [],
+        componentTiers: {},
+        groups: [],
+        converted: [],
+        removed: [],
+        manual: [],
+        blockers: [],
+    };
+    const deployed = components.flatMap((component) => component.paths.map((path) => ({ path, kind: 'create', group: component.id })));
+    // A path the source root owns stays the source root's.
+    const entries = new Map([...deployed, ...status.owned].map((entry) => [entry.path, entry]));
+    const members = new Map();
+    for (const entry of entries.values()) {
+        members.set(entry.group, [...(members.get(entry.group) ?? []), entry.path]);
+    }
+    const owned = {
+        entries,
+        members,
+        components: new Set(status.groups.filter((group) => group.kind === 'component').map((group) => group.id)),
+        declared,
+        furnace: new Set(components.map((component) => component.id)),
+        taken: new Set([...status.groups, ...components].map((group) => group.id)),
+    };
+    for (const waiver of previous)
+        placeWaiver(waiver, owned, plan);
+    return plan;
+}
+/**
+ * A `fireforge.json` document with a placement merged into `patchLint` and
+ * `exportQueue`.
+ *
+ * @param document - The document in the current format
+ * @param plan - From {@link placeWaivers}
+ */
+export function withWaivers(document, plan) {
+    const object = (value) => (isRecord(value) ? value : {});
+    const list = (value) => (Array.isArray(value) ? value : []);
+    const lint = object(document['patchLint']);
+    const queue = object(document['exportQueue']);
+    const tiers = { ...object(queue['componentTiers']), ...plan.componentTiers };
+    const exportQueue = {
+        ...queue,
+        ...(plan.groups.length === 0 ? {} : { groups: [...plan.groups, ...list(queue['groups'])] }),
+        ...(Object.keys(tiers).length === 0 ? {} : { componentTiers: tiers }),
+    };
+    return {
+        ...document,
+        ...(plan.waivers.length === 0
+            ? {}
+            : { patchLint: { ...lint, waivers: [...list(lint['waivers']), ...plan.waivers] } }),
+        ...(Object.keys(exportQueue).length === 0 ? {} : { exportQueue }),
+    };
+}

package/dist/src/mode/pristine.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { ensurePristine, findPristine, installProjectEngine, pinKey, } from '../engine/index.js';
+import { isRepository } from '../git/index.js';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+/**
+ * The pristine repository of the project's pin, from the host store. A
+ * source-mode project also pins the commit, and a store that imported the
+ * archive as another commit is refused.
+ *
+ * @param project - The project
+ * @throws `pristine-missing` (exit code 3) when the host never downloaded the pin,
+ *   `pristine-commit-mismatch` (exit code 2)
+ */
+export async function pinnedPristine(project) {
+    const pristine = await findPristine(project.host, project.config.firefox);
+    if (pristine === undefined) {
+        throw new FireForgeError('pristine-missing', `This host has no pristine source for ${pinKey(project.config.firefox)}.`, { exitCode: ExitCode.DOWNLOAD_ERROR, hint: 'Run "fireforge download".' });
+    }
+    const pinned = project.config.source?.pristineCommit;
+    if (pinned !== undefined && pinned !== pristine.commit) {
+        throw new FireForgeError('pristine-commit-mismatch', `The pristine source of ${pinKey(project.config.firefox)} is commit ${pristine.commit}, not the pinned ${pinned}.`, {
+            exitCode: ExitCode.CONFIG_ERROR,
+            hint: 'The pin and the archive disagree: check firefox.version and source.pristineCommit.',
+        });
+    }
+    return pristine;
+}
+/**
+ * Refuses a patch-mode project whose `engine/` has not been downloaded yet.
+ *
+ * @param project - A patch-mode project
+ * @throws `engine-missing` (exit code 1)
+ */
+export async function requireEngine(project) {
+    if (await isRepository(project.paths.engine))
+        return;
+    throw new FireForgeError('engine-missing', `There is no Firefox source at ${project.paths.engine}`, { exitCode: ExitCode.GENERAL_ERROR, hint: 'Run "fireforge download" first.' });
+}
+/**
+ * Fetches the pinned Firefox: imports it into the host pristine store when
+ * the host lacks it and, in patch mode, makes `engine/` a checkout of it.
+ * A source-mode project needs no engine of its own; its workspaces are
+ * checked out of the store when leased.
+ *
+ * @param project - The project
+ * @param options - `force` replaces an existing `engine/`; `waitMs` is for the engine lock
+ * @returns The pristine repository, and the engine install in patch mode
+ */
+export async function download(project, options = {}) {
+    const pristine = await ensurePristine(project.host, project.config.firefox, {
+        ...(options.onProgress === undefined ? {} : { onProgress: options.onProgress }),
+        expectCommit: project.config.source?.pristineCommit,
+    });
+    if (project.mode === 'source')
+        return { pristine };
+    const engine = await installProjectEngine(project, pristine, {
+        force: options.force === true,
+        waitMs: options.waitMs,
+    });
+    return { pristine, engine };
+}

package/dist/src/mode/rebase.js

@@ -0,0 +1,197 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Moving a project to a new Firefox pin.
+ *
+ * Source mode merges every owned path three ways against the new pristine
+ * commit and leaves conflicts as markers; `source.refreshPin` writes the new
+ * pin with the merge, in one transaction.
+ *
+ * Patch mode replaces `engine/` with a checkout of the new pin, writes the
+ * pin, and re-applies the queue with reduced context, rewriting every patch
+ * against the new source. A patch that does not apply pauses the rebase
+ * (`--continue`, `--abort`). The pin the rebase left is recorded in the
+ * project state until the rebase completes, and an abort goes back to it:
+ * `fireforge.json`, a checkout of that pin in `engine/`, and the queue
+ * applied.
+ */
+import { inferFirefoxProduct, setConfigValue, } from '../config/index.js';
+import { ensurePristine, installProjectEngine, withEngineLock } from '../engine/index.js';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { exists } from '../kernel/fs.js';
+import { s } from '../kernel/schema.js';
+import { defineStateSection, loadProject, readState, updateState, } from '../project/index.js';
+import { importQueue, queueStatus, rebaseQueue, replayQueue, requirePatchMode, } from '../queue/index.js';
+import { refreshPin } from '../source/index.js';
+import { pinnedPristine } from './pristine.js';
+function usage(message, hint) {
+    return new FireForgeError('invalid-argument', message, {
+        exitCode: ExitCode.INVALID_ARGUMENT,
+        ...(hint === undefined ? {} : { hint }),
+    });
+}
+/** The `firefox` block of the new pin: the current one's download policy, the new release. */
+function newPin(project, options) {
+    const current = project.config.firefox;
+    const inferred = inferFirefoxProduct(options.to);
+    const product = options.product ??
+        (inferred === 'firefox-beta' && current.product === 'firefox-devedition'
+            ? current.product
+            : inferred);
+    return {
+        version: options.to,
+        product,
+        allowUnverifiedDownload: current.allowUnverifiedDownload,
+        ...(options.sha256 === undefined ? {} : { sha256: options.sha256 }),
+        ...(options.candidate === undefined ? {} : { candidate: options.candidate }),
+    };
+}
+function progress(options) {
+    return options.onProgress === undefined ? {} : { onProgress: options.onProgress };
+}
+/** The pin as `fireforge.json` holds it: defaults are not written out. */
+function pinDocument(pin) {
+    const { allowUnverifiedDownload, ...rest } = pin;
+    return { ...rest, ...(allowUnverifiedDownload ? { allowUnverifiedDownload } : {}) };
+}
+async function rebaseSource(project, options) {
+    if ([options.continue, options.abort, options.dryRun, options.force].includes(true)) {
+        throw usage('A source-mode rebase is one merge: it has nothing to continue, abort, dry-run or force.', 'Resolve the conflict markers and commit; "git restore" and "git clean" undo the merge.');
+    }
+    if (options.to === undefined)
+        throw usage('rebase needs the new version: --to <version>.');
+    const pin = newPin(project, { ...options, to: options.to });
+    const current = await pinnedPristine(project);
+    const next = await ensurePristine(project.host, pin, progress(options));
+    const result = await refreshPin(project, current, next, pinDocument(pin));
+    return {
+        status: result.conflicts.length > 0 ? 'conflicts' : 'complete',
+        pin: { version: pin.version, product: pin.product },
+        entries: result.paths.map((path) => ({
+            subject: path.path,
+            outcome: path.reason === undefined ? path.outcome : `${path.outcome} (${path.reason})`,
+        })),
+        conflicts: [...result.conflicts],
+    };
+}
+/** The `firefox` block a patch-mode rebase moved away from, as `fireforge.json` held it. */
+const originSection = defineStateSection('rebaseOrigin', s.object({ firefox: s.string({ min: 1 }) }), 'fireforge rebase --abort');
+const reload = async (project) => requirePatchMode(await loadProject(project.root, { FIREFORGE_HOME: project.host.root }));
+/** Puts a patch-mode project's engine and configuration on a new pin. */
+async function movePin(project, pin, options) {
+    if (await exists(project.paths.engine)) {
+        const status = await withEngineLock(project, { command: 'rebase', mode: 'shared', waitMs: options.waitMs }, () => queueStatus(project));
+        if (status.session !== undefined) {
+            throw new FireForgeError('session-active', `A ${status.session.kind} is paused.`, {
+                exitCode: ExitCode.PATCH_ERROR,
+                hint: `Finish it with "fireforge ${status.session.kind} --continue" or drop it with "fireforge rebase --abort".`,
+            });
+        }
+        const unexported = status.paths.filter((path) => path.state === 'modified' || path.state === 'unmanaged');
+        if (unexported.length > 0 && options.force !== true) {
+            throw new FireForgeError('engine-unexported-edits', `engine/ holds ${unexported.length} edit(s) no patch has, such as ${unexported[0]?.path ?? ''}; a rebase replaces the engine.`, {
+                exitCode: ExitCode.PATCH_ERROR,
+                hint: 'Capture them with "fireforge export" or "fireforge re-export", drop them with "fireforge discard", or pass --force (a recovery snapshot keeps them).',
+            });
+        }
+    }
+    const interrupted = await readState(project, originSection);
+    if (interrupted !== undefined) {
+        throw new FireForgeError('rebase-interrupted', `A rebase away from ${interrupted.firefox} did not finish.`, {
+            exitCode: ExitCode.PATCH_ERROR,
+            hint: 'Go back to that version with "fireforge rebase --abort", or finish with "fireforge rebase --continue".',
+        });
+    }
+    const pristine = await ensurePristine(project.host, pin, progress(options));
+    await updateState(project, originSection, () => ({
+        firefox: JSON.stringify(pinDocument(project.config.firefox)),
+    }));
+    await installProjectEngine(project, pristine, { force: true, waitMs: options.waitMs });
+    await setConfigValue(project.root, 'firefox', JSON.stringify(pinDocument(pin)));
+    return reload(project);
+}
+/**
+ * Takes an aborted rebase back to the pin it started from: the configuration,
+ * a checkout of that pin, and the queue applied to it. A rebase that changed
+ * no pin has nothing to go back to.
+ */
+async function restoreOrigin(project, options) {
+    const origin = await readState(project, originSection);
+    if (origin === undefined)
+        return project;
+    await setConfigValue(project.root, 'firefox', origin.firefox);
+    const restored = await reload(project);
+    const pristine = await ensurePristine(restored.host, restored.config.firefox, progress(options));
+    await installProjectEngine(restored, pristine, { force: true, waitMs: options.waitMs });
+    await withEngineLock(restored, { command: 'rebase', waitMs: options.waitMs }, () => importQueue(restored));
+    await updateState(restored, originSection, () => undefined);
+    return restored;
+}
+async function rebasePatches(project, options) {
+    const resuming = options.continue === true || options.abort === true;
+    if (resuming && options.to !== undefined) {
+        throw usage('--to starts a rebase; --continue and --abort act on the paused one.');
+    }
+    const pin = options.to === undefined ? undefined : newPin(project, { ...options, to: options.to });
+    if (pin !== undefined && options.dryRun === true) {
+        const pristine = await ensurePristine(project.host, pin, progress(options));
+        const failure = await replayQueue(pristine.repo, pristine.commit, project.paths.patches).then(() => undefined, (error) => {
+            if (error instanceof FireForgeError && error.code === 'queue-does-not-apply')
+                return error;
+            throw error;
+        });
+        return {
+            status: 'dry-run',
+            pin: { version: pin.version, product: pin.product },
+            entries: [],
+            conflicts: failure === undefined ? [] : [failure.message],
+        };
+    }
+    const target = pin === undefined ? project : await movePin(project, pin, options);
+    const result = await withEngineLock(target, { command: 'rebase', waitMs: options.waitMs }, () => rebaseQueue(target, {
+        ...(options.continue === true ? { continue: true } : {}),
+        ...(options.abort === true ? { abort: true } : {}),
+        ...(options.dryRun === true ? { dryRun: true } : {}),
+        ...(options.force === true ? { force: true } : {}),
+    })).catch(async (error) => {
+        // A rebase interrupted before its queue was applied has no paused session, only its origin.
+        const unapplied = options.abort === true &&
+            error instanceof FireForgeError &&
+            error.code === 'no-session' &&
+            (await readState(target, originSection)) !== undefined;
+        if (!unapplied)
+            throw error;
+        return { status: 'aborted', patches: [], written: [], emptied: [] };
+    });
+    const settled = options.abort === true ? await restoreOrigin(target, options) : target;
+    if (result.status === 'complete' || result.status === 'up-to-date') {
+        await updateState(target, originSection, () => undefined);
+    }
+    const { version, product } = settled.config.firefox;
+    return {
+        status: result.status,
+        pin: { version, product },
+        entries: result.patches.map((patch) => ({
+            subject: patch.patch,
+            outcome: result.emptied.includes(patch.patch) ? 'emptied' : patch.status,
+        })),
+        conflicts: result.patches.flatMap((patch) => patch.conflicts === undefined || patch.conflicts.length === 0 ? [] : [patch.patch]),
+    };
+}
+/**
+ * Moves the project to a new Firefox pin (see the module comment).
+ *
+ * @param project - The project
+ * @param options - See {@link RebaseOptions}
+ * @throws `invalid-argument` for options the mode has no meaning for; the
+ *   download errors of the engine module; in patch mode the paused-session
+ *   error naming the patch that did not apply, `engine-unexported-edits`;
+ *   in source mode `refresh-dirty` and `refresh-pin-unchanged`
+ */
+export async function rebase(project, options = {}) {
+    if (options.to === project.config.firefox.version && options.product === undefined) {
+        throw usage(`The project is already on Firefox ${options.to}.`);
+    }
+    return project.mode === 'source'
+        ? rebaseSource(project, options)
+        : rebasePatches(project, options);
+}