@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/mode/report.js

@@ -0,0 +1,157 @@
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { queueStatus, verifyQueue } from '../queue/index.js';
+import { sourceStatus, verifySource } from '../source/index.js';
+import { componentGroups } from './changes.js';
+import { pinnedPristine, requireEngine } from './pristine.js';
+const PENDING = {
+    modified: (path) => ({
+        code: 'unexported',
+        message: 'edited since its patch was written',
+        hint: `fireforge re-export, or fireforge discard ${path}`,
+    }),
+    unmanaged: (path) => ({
+        code: 'unmanaged',
+        message: 'changed, and no patch holds it',
+        hint: `fireforge export ${path}, or fireforge discard ${path}`,
+    }),
+    unapplied: () => ({
+        code: 'unapplied',
+        message: 'the queue changes it, and the engine holds the upstream state',
+        hint: 'fireforge import',
+    }),
+    outdated: () => ({
+        code: 'outdated',
+        message: 'the engine still holds what an earlier import wrote, and the queue has moved on',
+        hint: 'fireforge import',
+    }),
+    missing: (path) => ({
+        code: 'missing',
+        message: 'absent from the engine, where the queue leaves a file',
+        hint: `fireforge discard ${path}`,
+    }),
+};
+/**
+ * The owned changes and anything unaccounted for: in patch mode edits no
+ * patch holds and a queue that is not applied; in source mode undeclared
+ * upstream edits and stale records.
+ *
+ * @param project - The project
+ */
+export async function status(project) {
+    if (project.mode === 'source') {
+        const report = await sourceStatus(project, await pinnedPristine(project));
+        return {
+            mode: 'source',
+            owned: report.owned.map((entry) => ({ path: entry.path, group: entry.group })),
+            groups: [
+                ...report.groups.map((group) => ({ ...group })),
+                ...(await componentGroups(project)).map((group) => ({
+                    id: group.id,
+                    kind: 'furnace',
+                    paths: group.paths.length,
+                })),
+            ],
+            pending: report.problems.map((problem) => ({
+                code: problem.kind,
+                subject: problem.path,
+                message: problem.message,
+                hint: problem.hint,
+            })),
+        };
+    }
+    await requireEngine(project);
+    const report = await queueStatus(project);
+    const pending = [];
+    if (report.session !== undefined) {
+        const { kind, done, total, current } = report.session;
+        pending.push({
+            code: 'session-paused',
+            ...(current === undefined ? {} : { subject: current.patch }),
+            message: `the ${kind} is unfinished at patch ${done} of ${total}`,
+            hint: `fireforge ${kind} --continue`,
+        });
+    }
+    if (report.failure !== undefined) {
+        pending.push({
+            code: 'does-not-apply',
+            subject: report.failure.patch,
+            message: report.failure.message,
+            hint: 'fireforge import',
+        });
+    }
+    for (const entry of report.paths) {
+        const describe = PENDING[entry.state];
+        if (describe !== undefined)
+            pending.push({ subject: entry.path, ...describe(entry.path) });
+    }
+    const owned = report.paths.flatMap((entry) => entry.owners[0] === undefined ? [] : [{ path: entry.path, group: entry.owners[0] }]);
+    const sizes = new Map();
+    for (const entry of owned)
+        sizes.set(entry.group, (sizes.get(entry.group) ?? 0) + 1);
+    return {
+        mode: 'patches',
+        owned,
+        groups: [...sizes]
+            .sort(([a], [b]) => (a < b ? -1 : 1))
+            .map(([id, paths]) => ({ id, kind: 'patch', paths })),
+        pending,
+    };
+}
+/**
+ * The integrity of the storage: the manifest and queue in patch mode, the
+ * override records and owned files against the pristine repository in
+ * source mode.
+ *
+ * @param project - The project
+ */
+export async function verify(project) {
+    if (project.mode === 'source') {
+        const problems = await verifySource(project, await pinnedPristine(project));
+        return {
+            mode: 'source',
+            problems: problems.map((problem) => ({
+                code: problem.kind,
+                subject: problem.path,
+                message: problem.message,
+                hint: problem.hint,
+            })),
+        };
+    }
+    const { problems } = await verifyQueue(project);
+    return {
+        mode: 'patches',
+        problems: problems.map((problem) => ({
+            code: problem.code,
+            ...(problem.patch === undefined ? {} : { subject: problem.patch }),
+            message: problem.message,
+        })),
+    };
+}
+const STORAGE = {
+    patches: {
+        sound: 'The patch queue is sound.',
+        name: 'patch queue',
+        exitCode: ExitCode.PATCH_ERROR,
+    },
+    source: {
+        sound: 'The owned files and records are sound.',
+        name: 'owned files and records',
+        exitCode: ExitCode.CONFIG_ERROR,
+    },
+};
+/**
+ * How a verify report ends: the line for a sound storage, or the failure.
+ *
+ * @param report - From {@link verify}
+ */
+export function verifyOutcome(report) {
+    const storage = STORAGE[report.mode];
+    if (report.problems.length === 0)
+        return { sound: storage.sound };
+    return {
+        failure: new FireForgeError('verify-failed', `${report.problems.length} problem(s) in the ${storage.name}.`, {
+            exitCode: storage.exitCode,
+            hint: 'Fix each problem listed above, then run "fireforge verify" again.',
+        }),
+    };
+}

package/dist/src/mode/setup.js

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Creating a project: `fireforge.json`, the mozconfig templates, the
+ * license text and the ignore rules, in either mode. A source-mode project
+ * pins the pristine commit of its Firefox, so creating one downloads and
+ * imports that Firefox when the host does not have it yet.
+ */
+import { join } from 'node:path';
+import { packageRoot } from '../cli/version.js';
+import { CONFIG_FILE, configSchema, } from '../config/index.js';
+import { ensurePristine } from '../engine/index.js';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { exists, listDir, readText, readTextIfExists, writeFile } from '../kernel/fs.js';
+import { stringifyJson } from '../kernel/json.js';
+import { hostPaths } from '../project/index.js';
+import { completedAttributes } from '../source/index.js';
+const SOURCE_ROOT = 'src';
+const METADATA_ROOT = '.fireforge-sources';
+/** Adds the lines an ignore file lacks, keeping what it has. */
+async function ignore(root, entries) {
+    const path = join(root, '.gitignore');
+    const current = (await readTextIfExists(path)) ?? '';
+    const present = new Set(current.split('\n').map((line) => line.trim().replace(/\/$/, '')));
+    const missing = entries.filter((entry) => !present.has(entry.replace(/\/$/, '')));
+    if (missing.length === 0)
+        return;
+    const separator = current === '' || current.endsWith('\n') ? '' : '\n';
+    await writeFile(path, `${current}${separator}${missing.join('\n')}\n`);
+}
+/**
+ * Refuses a directory that already holds a project: setup only ever creates one.
+ *
+ * @param root - The directory
+ * @throws `project-exists` (exit code 2)
+ */
+export async function refuseExistingProject(root) {
+    const configPath = join(root, CONFIG_FILE);
+    if (!(await exists(configPath)))
+        return;
+    throw new FireForgeError('project-exists', `${configPath} already exists.`, {
+        exitCode: ExitCode.CONFIG_ERROR,
+        hint: 'Change its settings with "fireforge config set", or run setup in a new directory.',
+    });
+}
+/**
+ * Writes a new project into a directory. Files that exist are kept; a
+ * directory that already holds a project is refused.
+ *
+ * @param root - The project directory
+ * @param spec - See {@link ProjectSpec}
+ * @param options - `env` locates the host state; `onProgress` receives download progress
+ * @returns The project-relative files written
+ * @throws `project-exists` (exit code 2), `config-invalid` naming the value
+ *   at fault, and in source mode the download errors
+ */
+export async function createProject(root, spec, options = {}) {
+    await refuseExistingProject(root);
+    const firefox = { version: spec.firefoxVersion, product: spec.product };
+    const identity = {
+        name: spec.name,
+        vendor: spec.vendor,
+        appId: spec.appId,
+        binaryName: spec.binaryName,
+        license: spec.license,
+    };
+    const pin = configSchema.parse({ ...identity, firefox }, { source: 'the new project', code: 'config-invalid', exitCode: ExitCode.INVALID_ARGUMENT }).firefox;
+    const source = spec.mode === 'source'
+        ? {
+            mode: 'source',
+            source: {
+                root: SOURCE_ROOT,
+                metadataRoot: METADATA_ROOT,
+                pristineCommit: (await ensurePristine(hostPaths(options.env), pin, options.onProgress === undefined ? {} : { onProgress: options.onProgress })).commit,
+            },
+        }
+        : {};
+    const written = [];
+    const write = async (file, content) => {
+        if (await exists(join(root, file)))
+            return;
+        await writeFile(join(root, file), content);
+        written.push(file);
+    };
+    await write(CONFIG_FILE, stringifyJson({ ...identity, ...source, firefox }));
+    const templates = join(await packageRoot(), 'templates');
+    for (const entry of await listDir(join(templates, 'configs'))) {
+        await write(`configs/${entry.name}`, await readText(join(templates, 'configs', entry.name)));
+    }
+    const license = await readTextIfExists(join(templates, 'licenses', `${spec.license}.md`));
+    if (license !== undefined) {
+        // Only the 0BSD text names its holder.
+        await write('LICENSE', spec.license === '0BSD'
+            ? license
+                .replaceAll('[year]', String(new Date().getFullYear()))
+                .replaceAll('[fullname]', spec.vendor)
+            : license);
+    }
+    if (spec.mode === 'source') {
+        await write(`${SOURCE_ROOT}/.gitattributes`, completedAttributes(undefined) ?? '');
+    }
+    await ignore(root, spec.mode === 'source' ? ['.fireforge/'] : ['engine/', '.fireforge/']);
+    return written;
+}

package/dist/src/mode/tracked.js

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The engine files a project tracks, for the commands that edit them
+ * (`register`, `wire`, `token`, `furnace`). Patch mode edits `engine/`
+ * itself. Source mode edits the owned copy under the source root, read over
+ * the pristine bytes.
+ *
+ * An upstream file is owned only behind an override record. The helpers
+ * whose edits are registrations by definition (build manifests, wiring,
+ * component registration) pass `declare`, and their first touch of an
+ * upstream file writes the record as `fireforge override <path>` would,
+ * classified `registration`. Without `declare` such a write is refused
+ * with that command as the hint.
+ */
+import { isAbsolute, join, posix, relative } from 'node:path';
+import { listPristineTree, withEngineLock } from '../engine/index.js';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { exists, isInside, readTextIfExists, resolveContained, toPosixPath } from '../kernel/fs.js';
+import { transaction } from '../kernel/journal.js';
+import { override, readSourceFile, writeSourceFile } from '../source/index.js';
+import { pinnedPristine } from './pristine.js';
+/** The directory holding the project's tracked engine files: `engine/`, or the source root. */
+function trackedDir(project) {
+    return project.mode === 'patches' ? project.paths.engine : project.paths.source;
+}
+function sourceFiles(project, pristine, declare) {
+    const read = (path) => readSourceFile(project, pristine, path);
+    return {
+        read: async (path) => (await read(path))?.toString('utf8'),
+        exists: async (path) => (await read(path)) !== undefined,
+        async write(tx, path, content) {
+            const bytes = Buffer.from(content, 'utf8');
+            try {
+                await writeSourceFile(project, pristine, path, bytes, { tx });
+            }
+            catch (error) {
+                const undeclared = error instanceof FireForgeError && error.code === 'source-override-required';
+                if (!undeclared || !declare)
+                    throw error;
+                await override(project, pristine, path, { tx });
+                await writeSourceFile(project, pristine, path, bytes, { tx });
+            }
+        },
+        async remove(tx, path) {
+            if ((await listPristineTree(pristine, [path])).some((entry) => entry.path === path)) {
+                throw new FireForgeError('source-upstream-file', `${path} is an upstream file; removing it is a declared deletion.`, {
+                    exitCode: ExitCode.INVALID_ARGUMENT,
+                    hint: `Run "fireforge override --delete ${path}", or "fireforge restore ${path}" to give an override back.`,
+                });
+            }
+            await tx.remove(join(project.paths.source, path));
+        },
+        locate: (path) => join(project.paths.source, path),
+    };
+}
+/**
+ * The writer for the engine files the project tracks.
+ *
+ * @param project - The project
+ * @param options - `declare`: in source mode, declare the first touch of an
+ *   upstream file as a registration instead of refusing it
+ * @throws `pristine-missing` in source mode before `download`
+ */
+export async function trackedFiles(project, options = {}) {
+    if (project.mode === 'source') {
+        return sourceFiles(project, await pinnedPristine(project), options.declare === true);
+    }
+    const engine = project.paths.engine;
+    return {
+        read: (path) => readTextIfExists(join(engine, path)),
+        exists: (path) => exists(join(engine, path)),
+        write: async (tx, path, content) => tx.write(await resolveContained(engine, path), content),
+        remove: async (tx, path) => tx.remove(await resolveContained(engine, path)),
+        locate: (path) => join(engine, path),
+    };
+}
+/**
+ * The engine-relative POSIX path for a path as the user typed it:
+ * engine-relative, prefixed with the tracked directory (`engine/…`,
+ * `src/…`), or absolute inside it.
+ *
+ * @param project - The project
+ * @param input - The path as typed
+ * @throws `invalid-argument` (exit code 8) for a path outside the engine
+ */
+export function enginePathOf(project, input) {
+    const dir = trackedDir(project);
+    const prefix = `${toPosixPath(relative(project.root, dir))}/`;
+    const typed = input.replaceAll('\\', '/').replace(/^\.\//, '');
+    const text = isAbsolute(input)
+        ? toPosixPath(relative(dir, input))
+        : typed.startsWith(prefix)
+            ? typed.slice(prefix.length)
+            : typed;
+    const path = posix.normalize(text);
+    if (path === '.' || path === '..' || path.startsWith('../') || !isInside(dir, path)) {
+        throw new FireForgeError('invalid-argument', `Path is outside the engine: ${input}`, {
+            exitCode: ExitCode.INVALID_ARGUMENT,
+        });
+    }
+    return path;
+}
+/**
+ * Runs an edit of tracked files as one transaction: every write lands, or
+ * none. Patch mode holds the engine lock exclusively for it.
+ *
+ * @param project - The project
+ * @param options - `label` names the edit in messages; `command` and `waitMs` are for the lock
+ * @param body - Makes the edits through the transaction
+ */
+export function editTracked(project, options, body) {
+    const run = () => transaction(join(project.paths.stateDir, 'tracked-edit.journal'), options.label, body);
+    return project.mode === 'patches'
+        ? withEngineLock(project, { command: options.command, waitMs: options.waitMs }, run)
+        : run();
+}

package/dist/src/mode/upgrade.js

@@ -0,0 +1,281 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Bringing a project written by the previous FireForge to the current
+ * format, in place. Each owning module knows its own previous format
+ * (`config/previous.ts`, `source/previous.ts`); this file decides the order,
+ * carries what one conversion tells another, and makes the whole change one
+ * journaled transaction on a committed tree, so a failure leaves the project
+ * as it was and `git` undoes a success.
+ *
+ * Nothing is guessed. A key or file that cannot be converted without a
+ * decision stops the upgrade before anything is written, named with what to
+ * do; everything rewritten or dropped is reported. A project already in the
+ * current format is left untouched.
+ */
+import { join, relative } from 'node:path';
+import { CONFIG_FILE, readConfigDocument, upgradeConfig, } from '../config/index.js';
+import { withoutObjdir } from '../engine/index.js';
+import { getConfig, status as gitStatus } from '../git/index.js';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { exists, listDir, readText, readTextIfExists, toPosixPath, walkFiles, } from '../kernel/fs.js';
+import { transaction } from '../kernel/journal.js';
+import { isRecord, omitKeys, stringifyJson, } from '../kernel/json.js';
+import { editJsonText } from '../kernel/json-edit.js';
+import { findProjectRoot, loadProject, projectPaths, readCheckout, } from '../project/index.js';
+import { installMergeDriver, parsePreviousWaivers, parseScopeDecisions, PREVIOUS_MERGE_DRIVER, PREVIOUS_METADATA_FILES, requireSourceMode, sourceStatus, upgradeAttributes, upgradeRecord, } from '../source/index.js';
+import { componentGroups } from './changes.js';
+import { placeWaivers, withWaivers } from './previousWaivers.js';
+import { download } from './pristine.js';
+import { verify } from './report.js';
+function section(document, key) {
+    const value = document[key];
+    return isRecord(value) ? value : {};
+}
+/** Drops the scope rules a reviewed `policy.json` retired; a retained one needs a person. */
+async function applyScopeDecisions(plan, root, previous) {
+    const metadataRoot = section(plan.document, 'source')['metadataRoot'];
+    const policy = section(plan.document, 'patchPolicy');
+    const rules = section(previous, 'patchPolicy')['scopeRules'];
+    if (typeof metadataRoot !== 'string' || !Array.isArray(rules) || rules.length === 0)
+        return;
+    const file = join(root, metadataRoot, 'policy.json');
+    const text = await readTextIfExists(file);
+    if (text === undefined || !Array.isArray(policy['scopeRules']))
+        return;
+    const decisions = parseScopeDecisions(text, file, rules);
+    const kept = [];
+    for (const [index, rule] of policy['scopeRules'].entries()) {
+        const decision = decisions[index];
+        const key = `patchPolicy.scopeRules[${index}]`;
+        if (decision?.decision === 'retire') {
+            plan.removed.push({
+                key,
+                message: `was retired by ${metadataRoot}/policy.json: ${decision.reason}`,
+            });
+        }
+        else if (decision?.decision === 'retain') {
+            plan.blockers.push({
+                key,
+                message: `was retained by ${metadataRoot}/policy.json as a scope over paths, which a scope over groups cannot express. ` +
+                    'Remove the rule, or rewrite it with a "group" expression, then run migrate again',
+            });
+            kept.push(rule);
+        }
+        else {
+            kept.push(rule);
+        }
+    }
+    plan.document = {
+        ...plan.document,
+        patchPolicy: kept.length === 0 ? omitKeys(policy, 'scopeRules') : { ...policy, scopeRules: kept },
+    };
+}
+/** The file changes a source-mode project's metadata needs. */
+async function planSource(plan, root) {
+    const source = section(plan.document, 'source');
+    const [sourceRoot, metadataRoot] = [source['root'], source['metadataRoot']];
+    if (typeof sourceRoot !== 'string' || typeof metadataRoot !== 'string')
+        return;
+    const overrides = join(root, metadataRoot, 'overrides');
+    let records = 0;
+    for (const file of await walkFiles(overrides)) {
+        if (!file.endsWith('.json'))
+            continue;
+        const path = `${metadataRoot}/overrides/${file}`;
+        const result = upgradeRecord(await readText(join(overrides, file)), file.slice(0, -'.json'.length));
+        if (result.state === 'invalid')
+            plan.blockers.push({ key: path, message: result.problem });
+        if (result.state === 'converted') {
+            plan.files.push({ path, content: result.text });
+            records += 1;
+        }
+    }
+    if (records > 0) {
+        plan.converted.push({
+            key: `${metadataRoot}/overrides`,
+            message: `${records} override record(s) rewritten without schemaVersion, path and base.pin`,
+        });
+    }
+    const attributes = `${sourceRoot}/.gitattributes`;
+    const text = await readTextIfExists(join(root, attributes));
+    const next = text === undefined ? undefined : upgradeAttributes(text);
+    if (next !== undefined) {
+        plan.files.push({ path: attributes, content: next });
+        plan.converted.push({ key: attributes, message: `names the merge driver "fireforge"` });
+    }
+    const waivers = join(root, metadataRoot, 'waivers.json');
+    const waiverText = await readTextIfExists(waivers);
+    if (waiverText !== undefined)
+        plan.waivers = parsePreviousWaivers(waiverText, waivers);
+    for (const name of PREVIOUS_METADATA_FILES) {
+        if (!(await exists(join(root, metadataRoot, name))))
+            continue;
+        plan.files.push({ path: `${metadataRoot}/${name}` });
+        plan.removed.push({
+            key: `${metadataRoot}/${name}`,
+            message: name === 'waivers.json'
+                ? 'its waivers are now patchLint.waivers and exportQueue.componentTiers'
+                : name === 'policy.json'
+                    ? 'its scope decisions are applied to patchPolicy.scopeRules; groups of created files are judged file by file, not by size'
+                    : 'nothing reads it',
+        });
+    }
+}
+/** Everything the upgrade would change, read without writing. */
+async function planUpgrade(root) {
+    const { document: previous } = await readConfigDocument(root);
+    const config = upgradeConfig(previous);
+    const plan = {
+        config,
+        document: config.document,
+        mode: config.document['mode'] === 'source' ? 'source' : 'patches',
+        files: [],
+        converted: [...config.converted],
+        removed: [...config.removed],
+        blockers: [...config.blockers],
+        waivers: [],
+    };
+    if (plan.blockers.length > 0)
+        return plan;
+    if (plan.mode === 'source') {
+        await applyScopeDecisions(plan, root, previous);
+        await planSource(plan, root);
+    }
+    const { configs } = projectPaths(root);
+    for (const entry of await listDir(configs)) {
+        if (entry.kind !== 'file' || !entry.name.endsWith('.mozconfig'))
+            continue;
+        const next = withoutObjdir(await readText(join(configs, entry.name)));
+        if (next === undefined)
+            continue;
+        plan.files.push({ path: `configs/${entry.name}`, content: next });
+        plan.removed.push({
+            key: `configs/${entry.name}`,
+            message: 'its MOZ_OBJDIR declaration: FireForge places the object directory itself',
+        });
+    }
+    const fragment = 'fireforge.fragment.json';
+    if (await exists(join(root, fragment))) {
+        plan.files.push({ path: fragment });
+        plan.removed.push({ key: fragment, message: 'nothing reads it' });
+    }
+    return plan;
+}
+function blocked(blockers) {
+    const lines = blockers.map((note) => `  ${note.key}: ${note.message}`);
+    return new FireForgeError('migrate-blocked', `${blockers.length} thing(s) cannot be converted without a decision:\n${lines.join('\n')}`, {
+        exitCode: ExitCode.CONFIG_ERROR,
+        hint: 'Nothing was written. Change each one as its line says, commit, and run "fireforge migrate" again.',
+    });
+}
+async function assertCommitted(root) {
+    const { worktree } = await readCheckout(root);
+    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, 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 ?? ''}.`);
+    }
+}
+/**
+ * Upgrades the project at or above `cwd` from the previous format, in
+ * place, and checks the result with `verify`.
+ *
+ * @param cwd - Where the command was run
+ * @param env - The environment of the invocation
+ * @param options - See {@link UpgradeOptions}
+ * @throws `migrate-blocked` (exit code 2) naming everything that needs a
+ *   decision, `migrate-needs-clean-tree` (exit code 4), and, for a
+ *   source-mode project whose pin this host lacks, what `download` throws
+ */
+export async function upgrade(cwd, env, options = {}) {
+    const root = await findProjectRoot(cwd);
+    const plan = await planUpgrade(root);
+    if (plan.blockers.length > 0)
+        throw blocked(plan.blockers);
+    const pending = plan.converted.length + plan.removed.length + plan.files.length > 0;
+    if (!pending) {
+        const project = await loadProject(root, env);
+        return {
+            state: 'current',
+            mode: project.mode,
+            converted: [],
+            removed: [],
+            rewritten: [],
+            deleted: [],
+            manual: [],
+            followUp: [],
+            verify: await verify(project),
+        };
+    }
+    await assertCommitted(root);
+    const configPath = join(root, CONFIG_FILE);
+    const configText = await readText(configPath);
+    const render = (document) => editJsonText(configText, document) ?? stringifyJson(document);
+    const { converted, removed } = plan;
+    const manual = [...plan.config.manual];
+    const project = await transaction(join(projectPaths(root).stateDir, 'migrate.journal'), 'the format upgrade', async (tx) => {
+        await tx.write(configPath, render(plan.document));
+        for (const file of plan.files) {
+            if (file.content === undefined)
+                await tx.remove(join(root, file.path));
+            else
+                await tx.write(join(root, file.path), file.content);
+        }
+        const loaded = await loadProject(root, env);
+        if (loaded.mode !== 'source')
+            return loaded;
+        // The pin's pristine repository is what the waivers' groups and the closing verify are read against.
+        const { pristine } = await download(loaded, options);
+        if (plan.waivers.length === 0)
+            return loaded;
+        const declared = new Set((loaded.config.exportQueue.groups ?? []).map((group) => group.name));
+        const waivers = placeWaivers(plan.waivers, await sourceStatus(loaded, pristine), declared, await componentGroups(loaded));
+        if (waivers.blockers.length > 0)
+            throw blocked(waivers.blockers);
+        converted.push(...waivers.converted, {
+            key: 'waivers.json',
+            message: `${waivers.waivers.length} waiver(s) are now patchLint.waivers`,
+        });
+        removed.push(...waivers.removed);
+        manual.push(...waivers.manual);
+        await tx.write(configPath, render(withWaivers(plan.document, waivers)));
+        const final = await loadProject(root, env);
+        const regrouped = await sourceStatus(requireSourceMode(final), pristine);
+        for (const group of waivers.groups) {
+            const held = regrouped.owned.filter((entry) => entry.group === group.name);
+            if (held.length !== group.paths.length) {
+                throw new FireForgeError('migrate-mismatch', `Group "${group.name}" would hold ${held.length} file(s), not the ${group.paths.length} its waiver covered.`, { exitCode: ExitCode.CONFIG_ERROR, hint: 'Nothing was kept. Report this.' });
+            }
+        }
+        return final;
+    });
+    const followUp = [];
+    if (project.mode === 'source') {
+        await installMergeDriver(project);
+        const worktree = project.checkout.worktree ?? root;
+        if ((await getConfig(worktree, `merge.${PREVIOUS_MERGE_DRIVER}.driver`)) !== undefined) {
+            followUp.push(`The repository's git configuration still declares the merge driver "${PREVIOUS_MERGE_DRIVER}", which checkouts ` +
+                `not yet upgraded use. Once none is left: git config --remove-section merge.${PREVIOUS_MERGE_DRIVER}`);
+        }
+    }
+    return {
+        state: 'upgraded',
+        mode: project.mode,
+        converted,
+        removed,
+        manual,
+        rewritten: [
+            CONFIG_FILE,
+            ...plan.files.flatMap((file) => (file.content === undefined ? [] : [file.path])),
+        ],
+        deleted: plan.files.flatMap((file) => (file.content === undefined ? [file.path] : [])),
+        followUp,
+        verify: await verify(project),
+    };
+}