@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/register/register.js

@@ -0,0 +1,359 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Build-manifest registration: which manifest an engine file belongs in, as
+ * a function of its path, and the edit that puts it there. Parsing and
+ * editing the manifests is `mozbuild`'s; this file is the policy, and the
+ * one place that says where a test, a test manifest, a chrome file or a
+ * custom element file is registered.
+ */
+import { posix } from 'node:path';
+import { usageError } from '../cli/command.js';
+import { FireForgeError } from '../kernel/errors.js';
+import { escapeRegExp } from '../kernel/text.js';
+import { addTest, addToMozBuildList, findJarEntries, findMozBuildLists, insertJarEntry, mozBuildTestManifests, newTestManifest, parseMozBuild, TEST_MANIFEST_VARIABLES, testManifestFlavor, } from '../mozbuild/index.js';
+import { licenseHeader } from '../project/index.js';
+import { EditSession } from './files.js';
+/**
+ * The jar.mn entry of a chrome file packaged by `browser/base/jar.mn`.
+ *
+ * @param target - The path in the jar, such as `content/browser/panel.js`
+ * @param source - The source, relative to `browser/base`
+ */
+export function browserJarTarget(target, source) {
+    return {
+        kind: 'jar',
+        manifest: 'browser/base/jar.mn',
+        entry: { target, source },
+        indent: '        ',
+        minGap: 4,
+    };
+}
+/**
+ * The jar.mn entry of a custom element file, packaged by
+ * `toolkit/content/jar.mn` under `chrome://global/content/elements/`.
+ *
+ * @param sourceDir - The file's directory, relative to `toolkit/content`
+ * @param file - The file name
+ */
+export function elementJarEntry(sourceDir, file) {
+    return { target: `content/global/elements/${file}`, source: `${sourceDir}/${file}` };
+}
+/** The test manifest a test file goes in by default, by its name. */
+function defaultTestManifest(name) {
+    if (/^browser_.+\.js$/.test(name))
+        return 'browser.toml';
+    if (/^test_.+\.js$/.test(name))
+        return 'xpcshell.toml';
+    if (/^test_.+\.(?:x?html)$/.test(name))
+        return 'mochitest.toml';
+    return undefined;
+}
+/**
+ * The manifest entry a path calls for, or undefined when the path is not
+ * one FireForge knows how to register.
+ */
+function classify(path, moduleDir, testManifest) {
+    let match;
+    if ((match = /^browser\/themes\/shared\/(.+)\.css$/.exec(path))) {
+        const name = match[1] ?? '';
+        return {
+            kind: 'jar',
+            manifest: 'browser/themes/shared/jar.inc.mn',
+            entry: { target: `skin/classic/browser/${name}.css`, source: `../shared/${name}.css` },
+            aliases: [`content/browser/${name}.css`],
+            indent: '  ',
+            minGap: 4,
+        };
+    }
+    if ((match =
+        /^browser\/base\/content\/(?!.+\.inc\.xhtml$)(?!test\/)(.+\.(?:js|mjs|xhtml|css))$/.exec(path))) {
+        const file = match[1] ?? '';
+        return browserJarTarget(`content/browser/${file}`, `content/${file}`);
+    }
+    const flavor = testManifestFlavor(path);
+    if (flavor !== undefined) {
+        const variable = Object.keys(TEST_MANIFEST_VARIABLES).find((name) => TEST_MANIFEST_VARIABLES[name] === flavor);
+        if (variable !== undefined)
+            return { kind: 'manifest', path, variable };
+    }
+    const module = new RegExp(`^${escapeRegExp(moduleDir)}/(.+\\.sys\\.mjs)$`).exec(path);
+    if (module) {
+        return {
+            kind: 'list',
+            manifest: `${moduleDir}/moz.build`,
+            variables: [`EXTRA_JS_MODULES.${posix.basename(moduleDir)}`, 'EXTRA_JS_MODULES'],
+            value: module[1] ?? '',
+        };
+    }
+    if ((match = /^toolkit\/content\/widgets\/([^/]+)\/(.+\.(?:mjs|css))$/.exec(path))) {
+        const [, tag = '', file = ''] = match;
+        return {
+            kind: 'jar',
+            manifest: 'toolkit/content/jar.mn',
+            entry: elementJarEntry(`widgets/${tag}`, file),
+            indent: '   ',
+            minGap: 2,
+        };
+    }
+    const name = posix.basename(path);
+    const manifest = testManifest ?? defaultTestManifest(name);
+    if (manifest !== undefined && path.includes('/')) {
+        return { kind: 'test', manifest: `${posix.dirname(path)}/${manifest}`, name };
+    }
+    return undefined;
+}
+/** Guidance for a path that has no entry of its own, or undefined when none applies. */
+function adviceFor(path) {
+    if (path.endsWith('.ftl')) {
+        return 'Locale files are found by jar.mn globs and need no registration.';
+    }
+    if (/^browser\/base\/content\/.+\.inc\.xhtml$/.test(path)) {
+        return ('An .inc.xhtml fragment is pulled in by #include from a registered chrome document and has ' +
+            'no jar.mn entry of its own. Run "fireforge wire <name> --dom <path>" to add the #include.');
+    }
+    return undefined;
+}
+function unknownPath(path, moduleDir) {
+    return usageError(adviceFor(path) ??
+        `Unknown file pattern: "${path}". Supported patterns:\n` +
+            '  browser/themes/shared/*.css\n' +
+            '  browser/base/content/*.{js,mjs,xhtml,css}\n' +
+            `  ${moduleDir}/*.sys.mjs\n` +
+            '  toolkit/content/widgets/*/*.{mjs,css}\n' +
+            '  **/{browser,xpcshell,mochitest,chrome,a11y}*.toml (into the moz.build above it)\n' +
+            "  **/browser_*.js, **/test_*.js, **/test_*.html (into the directory's test manifest)");
+}
+function missingManifest(manifest, hint) {
+    return new FireForgeError('manifest-not-found', `Manifest not found: ${manifest}`, { hint });
+}
+function chainMissing(path, variable) {
+    return new FireForgeError('manifest-chain-missing', `No moz.build exists above ${path}, so ${variable} cannot be wired.`, { hint: 'Check the path.' });
+}
+function placed(placement) {
+    return {
+        entry: (placement.text.split('\n')[placement.line] ?? '').trim(),
+        previous: placement.previous,
+        afterFallback: placement.afterFallback,
+    };
+}
+/**
+ * Plans one jar.mn entry, or finds it (or an alias) already present.
+ *
+ * @param session - The plan's edits so far
+ * @param target - The entry and its manifest
+ * @param after - Place it after the entry this names
+ */
+export async function planJar(session, target, after) {
+    const text = await session.read(target.manifest);
+    if (text === undefined)
+        throw missingManifest(target.manifest, 'Check the path.');
+    const { entry } = target;
+    const known = findJarEntries(text, {
+        target: [entry.target, ...(target.aliases ?? [])],
+        ...(entry.source === undefined ? {} : { source: entry.source }),
+    })[0];
+    const placement = known === undefined
+        ? insertJarEntry(text, entry, {
+            indent: target.indent,
+            minGap: target.minGap,
+            ...(after === undefined ? {} : { after }),
+        })
+        : { text, changed: false, line: known.line };
+    if (placement.changed)
+        session.set(target.manifest, placement.text);
+    return {
+        manifest: target.manifest,
+        ...placed(placement),
+        steps: [
+            {
+                path: target.manifest,
+                change: `${entry.target} (${entry.source ?? ''})`,
+                present: !placement.changed,
+            },
+        ],
+    };
+}
+/** Plans the edits of one request; `session` collects them. */
+class Planner {
+    request;
+    session;
+    constructor(files, request) {
+        this.request = request;
+        this.session = new EditSession(files);
+    }
+    header() {
+        return licenseHeader(this.request.license, 'hash');
+    }
+    /** Adds `value` to a moz.build list, creating the list, and the file with the project header, when absent. */
+    async addToMozBuild(path, variable, value) {
+        const text = await this.session.read(path);
+        const edit = addToMozBuildList(text ?? '', variable, value, { create: true });
+        if (edit.changed) {
+            this.session.set(path, text === undefined ? `${this.header()}\n\n${edit.text.trimStart()}` : edit.text);
+        }
+        return { path, change: `${variable} += ["${value}"]`, present: !edit.changed };
+    }
+    /**
+     * Wires a new directory into the DIRS of its parents: every parent without
+     * a moz.build gets one, up to the nearest parent that has one.
+     */
+    async wireParents(dir) {
+        const steps = [];
+        let child = dir;
+        for (let parent = posix.dirname(dir); parent !== '.'; parent = posix.dirname(parent)) {
+            const manifest = `${parent}/moz.build`;
+            const exists = await this.session.exists(manifest);
+            steps.push(await this.addToMozBuild(manifest, 'DIRS', posix.basename(child)));
+            if (exists)
+                return steps;
+            child = parent;
+        }
+        throw chainMissing(dir, 'DIRS');
+    }
+    async list(target) {
+        const { manifest, value } = target;
+        const first = target.variables[0] ?? '';
+        const text = await this.session.read(manifest);
+        if (text === undefined) {
+            if (this.request.createManifest !== true) {
+                throw missingManifest(manifest, 'Pass --create-manifest to create it and wire its parent DIRS.');
+            }
+            const step = await this.addToMozBuild(manifest, first, value);
+            return {
+                manifest,
+                entry: `"${value}",`,
+                steps: [step, ...(await this.wireParents(posix.dirname(manifest)))],
+            };
+        }
+        const present = target.variables
+            .map((variable) => ({
+            variable,
+            line: findMozBuildLists(text, variable)
+                .flatMap((list) => list.items)
+                .find((candidate) => candidate.value === value)?.line,
+        }))
+            .find((found) => found.line !== undefined);
+        const variable = present?.variable ??
+            target.variables.find((candidate) => findMozBuildLists(text, candidate).length > 0) ??
+            first;
+        const placement = present?.line === undefined
+            ? addToMozBuildList(text, variable, value, { create: true })
+            : { text, changed: false, line: present.line };
+        if (placement.changed)
+            this.session.set(manifest, placement.text);
+        return {
+            manifest,
+            ...placed(placement),
+            steps: [
+                { path: manifest, change: `${variable} += ["${value}"]`, present: !placement.changed },
+            ],
+        };
+    }
+    /**
+     * Registers a test manifest: present when a moz.build above it lists it;
+     * otherwise in the nearest moz.build above it with a list of its flavour,
+     * else one with any test manifest list, else one with any list at all
+     * (a moz.build holding only `with Files` metadata is not in the build),
+     * else the nearest.
+     */
+    async manifest(target) {
+        const owners = [];
+        for (let dir = posix.dirname(target.path); dir !== '.'; dir = posix.dirname(dir)) {
+            const path = `${dir}/moz.build`;
+            const text = await this.session.read(path);
+            if (text === undefined)
+                continue;
+            const listed = mozBuildTestManifests(path, text).find((entry) => entry.path === target.path);
+            if (listed !== undefined) {
+                const line = findMozBuildLists(text, listed.variable, { conditional: true })
+                    .flatMap((list) => list.items)
+                    .find((item) => item.value === listed.value)?.line;
+                const change = `${listed.variable} += ["${listed.value}"]`;
+                return {
+                    manifest: path,
+                    entry: (text.split('\n')[line ?? 0] ?? '').trim(),
+                    steps: [{ path, change, present: true }],
+                };
+            }
+            owners.push({ path, text });
+        }
+        const lists = (text) => parseMozBuild(text).lists;
+        const owner = owners.find((candidate) => findMozBuildLists(candidate.text, target.variable).length > 0) ??
+            owners.find((candidate) => lists(candidate.text).some((list) => list.name in TEST_MANIFEST_VARIABLES)) ??
+            owners.find((candidate) => lists(candidate.text).length > 0) ??
+            owners[0];
+        if (owner === undefined)
+            throw chainMissing(target.path, target.variable);
+        const value = posix.relative(posix.dirname(owner.path), target.path);
+        const placement = addToMozBuildList(owner.text, target.variable, value, { create: true });
+        this.session.set(owner.path, placement.text);
+        return {
+            manifest: owner.path,
+            ...placed(placement),
+            steps: [{ path: owner.path, change: `${target.variable} += ["${value}"]`, present: false }],
+        };
+    }
+    async test(target) {
+        const { manifest, name } = target;
+        const { after } = this.request;
+        const text = await this.session.read(manifest);
+        if (text === undefined) {
+            const flavor = testManifestFlavor(manifest);
+            const variable = Object.keys(TEST_MANIFEST_VARIABLES).find((key) => TEST_MANIFEST_VARIABLES[key] === flavor);
+            if (this.request.createManifest !== true || variable === undefined) {
+                throw missingManifest(manifest, `Pass --create-manifest to create it and wire ${variable ?? 'it'} into a moz.build.`);
+            }
+            this.session.set(manifest, newTestManifest(manifest, name, {
+                header: this.header(),
+                ...(this.request.manifestDefaults === undefined
+                    ? {}
+                    : { defaults: this.request.manifestDefaults }),
+            }));
+            const created = {
+                path: manifest,
+                change: `["${name}"] (new file)`,
+                present: false,
+            };
+            const wired = await this.manifest({ kind: 'manifest', path: manifest, variable });
+            return { manifest, entry: `["${name}"]`, steps: [created, ...wired.steps] };
+        }
+        const placement = addTest(manifest, text, name, after === undefined ? {} : { after });
+        if (placement.changed)
+            this.session.set(manifest, placement.text);
+        return {
+            manifest,
+            ...placed(placement),
+            steps: [{ path: manifest, change: `["${name}"]`, present: !placement.changed }],
+        };
+    }
+}
+/**
+ * Plans the registration of one engine file in the build manifest its path
+ * calls for. Registering a file that is already registered plans nothing.
+ *
+ * @param files - Where the manifests live
+ * @param request - The file and the options
+ * @throws `invalid-argument` for a path with no manifest or an unsupported `after`;
+ *   `manifest-not-found` when the manifest is missing and not to be created
+ */
+export async function planRegister(files, request) {
+    const { path, moduleDir, after } = request;
+    const target = classify(path, moduleDir, request.testManifest);
+    if (target === undefined)
+        throw unknownPath(path, moduleDir);
+    if (after !== undefined && (target.kind === 'list' || target.kind === 'manifest')) {
+        throw usageError(`--after does not apply to ${path}: moz.build entries are kept in sorted order.`, 'Drop --after.');
+    }
+    if (request.mustExist === true && !(await files.exists(path))) {
+        throw usageError(`File not found: ${path}`, 'Create the file before registering it.');
+    }
+    const planner = new Planner(files, request);
+    const outcome = target.kind === 'jar'
+        ? await planJar(planner.session, target, after)
+        : target.kind === 'list'
+            ? await planner.list(target)
+            : target.kind === 'manifest'
+                ? await planner.manifest(target)
+                : await planner.test(target);
+    return { ...outcome, edits: planner.session.edits() };
+}

package/dist/src/register/wire.js

@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Wiring a chrome subscript into the browser: the `loadSubScript` call, the
+ * optional init and destroy calls, the optional `#include` of a DOM fragment
+ * into the top-level chrome document, and the jar.mn entry that packages it.
+ */
+import { posix } from 'node:path';
+import { usageError } from '../cli/command.js';
+import { FireForgeError } from '../kernel/errors.js';
+import { escapeRegExp } from '../kernel/text.js';
+import { lineStart } from '../syntax/index.js';
+import { EditSession } from './files.js';
+import { addDestroy, addInit, addSubscript, validateWireExpression, validateWireName, } from './js.js';
+import { browserJarTarget, planJar } from './register.js';
+/** Where the browser's chrome scripts live. */
+const BROWSER_MAIN = 'browser/base/content/browser-main.js';
+const BROWSER_INIT = 'browser/base/content/browser-init.js';
+const BROWSER_BASE = 'browser/base';
+function missing(path, hint) {
+    return new FireForgeError('wire-file-missing', `${path} not found.`, { hint });
+}
+const ID = (id) => `(?<![\\w-])id\\s*=\\s*["']${escapeRegExp(id)}["']`;
+/**
+ * The lines of `target` that inline the fragment's root element, from its
+ * start tag to the matching end tag, replaced by the directive. Undefined
+ * when the document has no element of that tag and id, or it does not
+ * occupy whole lines.
+ */
+function replaceInlined(target, fragment, directive) {
+    const root = /<([A-Za-z][\w:.-]*)\b[^>]*?(?<![\w-])id\s*=\s*["']([^"']+)["']/.exec(fragment);
+    const [tag, id] = [root?.[1], root?.[2]];
+    if (tag === undefined || id === undefined)
+        return undefined;
+    const name = escapeRegExp(tag);
+    const open = new RegExp(`<${name}\\b[^>]*?${ID(id)}`).exec(target);
+    if (open === null)
+        return undefined;
+    const tags = new RegExp(`<(/?)${name}\\b[^>]*?(/?)>`, 'g');
+    tags.lastIndex = open.index;
+    let depth = 0;
+    let end;
+    for (let match = tags.exec(target); match !== null; match = tags.exec(target)) {
+        if (match[1] === '/')
+            depth--;
+        else if (match[2] !== '/')
+            depth++;
+        if (depth === 0) {
+            end = match.index + match[0].length;
+            break;
+        }
+    }
+    if (end === undefined)
+        return undefined;
+    const start = lineStart(target, open.index);
+    const lineEnd = target.indexOf('\n', end);
+    const stop = lineEnd === -1 ? target.length : lineEnd;
+    if (target.slice(start, open.index).trim() !== '' || target.slice(end, stop).trim() !== '') {
+        return undefined;
+    }
+    return target.slice(0, start) + directive + target.slice(stop);
+}
+/**
+ * Adds `#include <fragment>` to a chrome document: before the
+ * `browser-sets.inc` include, else after `<html:body>`. A fragment already
+ * inlined in the document is replaced by the include.
+ *
+ * @returns The new text, or undefined when the include is already there
+ */
+async function addDomInclude(session, dom) {
+    const text = await session.read(dom.target);
+    if (text === undefined) {
+        throw missing(dom.target, 'Pass --target <path>, or set the chrome document in the project.');
+    }
+    const directive = `#include ${posix.relative(posix.dirname(dom.target), dom.file)}`;
+    if (new RegExp(`^${escapeRegExp(directive)}$`, 'm').test(text))
+        return undefined;
+    const fragment = await session.read(dom.file);
+    const inlined = fragment === undefined ? undefined : replaceInlined(text, fragment, directive);
+    if (inlined !== undefined)
+        return inlined;
+    const lines = text.split('\n');
+    const sets = lines.findIndex((line) => /^\s*#include\s+.*browser-sets\.inc/.test(line));
+    const body = lines.findIndex((line) => /<html:body/.test(line));
+    const at = sets !== -1 ? sets : body !== -1 ? body + 1 : -1;
+    if (at === -1) {
+        throw new FireForgeError('wire-no-anchor', `${dom.target} has neither "#include browser-sets.inc" nor <html:body> to insert before.`, { hint: 'Add one of them, or target a chrome document that has one with --target.' });
+    }
+    lines.splice(at, 0, directive);
+    return lines.join('\n');
+}
+/**
+ * Plans a subscript's wiring. Every step is computed before anything is
+ * written, so a step that cannot be done leaves the browser untouched.
+ *
+ * @param files - Where the browser's files live
+ * @param request - What to wire
+ * @throws `invalid-argument` for a name or expression that is not safe to generate code from
+ */
+export async function planWire(files, request) {
+    const { name, marker } = request;
+    validateWireName(name);
+    if (request.after !== undefined)
+        validateWireName(request.after, 'after name');
+    if (request.init !== undefined)
+        validateWireExpression(request.init, 'init expression');
+    if (request.destroy !== undefined)
+        validateWireExpression(request.destroy, 'destroy expression');
+    const subscript = `${request.subscriptDir}/${name}.js`;
+    if (request.requireSubscript === true && !(await files.exists(subscript))) {
+        throw usageError(`Subscript file not found: ${subscript}`, 'Create the file before wiring it.');
+    }
+    if (request.dom !== undefined && !(await files.exists(request.dom.file))) {
+        throw usageError(`DOM fragment not found: ${request.dom.file}`);
+    }
+    const session = new EditSession(files);
+    const steps = [];
+    const edit = async (path, change, make) => {
+        const text = await session.read(path);
+        if (text === undefined)
+            throw missing(path, 'Check that the project has this file.');
+        const next = make(text);
+        if (next !== undefined)
+            session.set(path, next);
+        steps.push({ path, change, present: next === undefined });
+    };
+    await edit(BROWSER_MAIN, `loadSubScript ${name}.js`, (text) => addSubscript(text, name, marker));
+    if (request.init !== undefined) {
+        const { init, after } = request;
+        await edit(BROWSER_INIT, `onLoad: ${init}`, (text) => addInit(text, init, { after, marker }));
+    }
+    if (request.destroy !== undefined) {
+        const { destroy } = request;
+        await edit(BROWSER_INIT, `onUnload: ${destroy}`, (text) => addDestroy(text, destroy, marker));
+    }
+    if (request.dom !== undefined) {
+        const { dom } = request;
+        const next = await addDomInclude(session, dom);
+        if (next !== undefined)
+            session.set(dom.target, next);
+        steps.push({ path: dom.target, change: `#include ${dom.file}`, present: next === undefined });
+    }
+    const source = posix.join(posix.relative(BROWSER_BASE, request.subscriptDir), `${name}.js`);
+    const jar = await planJar(session, browserJarTarget(`content/browser/${name}.js`, source), undefined);
+    steps.push(...jar.steps);
+    return { edits: session.edits(), steps };
+}

package/dist/src/source/adopt.js

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Adopting a tree: the source half of moving a patch-mode project to source
+ * mode. The caller replays the patch queue onto the pristine commit and
+ * hands over the resulting tree; this writes the owned files and override
+ * records that express the difference: a modified upstream file becomes
+ * its postimage plus a record, a deleted one a tombstone record, a new one
+ * a created file.
+ */
+import { join } from 'node:path';
+import { changedPaths, listTree, readBlobs } from '../git/index.js';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { listDir, writeFile } from '../kernel/fs.js';
+import { completedAttributes } from './merge.js';
+import { compareText, COMPONENT_PATTERN, encodeRecord, unownableReason, } from './records.js';
+function regular(entry, side) {
+    if (entry === undefined)
+        return undefined;
+    if (entry.type === 'blob' && (entry.mode === '100644' || entry.mode === '100755'))
+        return entry;
+    throw new FireForgeError('adopt-unsupported-kind', `${entry.path} is an entry of mode ${entry.mode} in the ${side} tree; source mode owns regular files only.`, { exitCode: ExitCode.PATCH_ERROR });
+}
+async function assertEmpty(directory) {
+    if ((await listDir(directory)).length > 0) {
+        throw new FireForgeError('adopt-destination-not-empty', `${directory} is not empty.`, {
+            exitCode: ExitCode.INVALID_ARGUMENT,
+            hint: 'Adopt into a new directory.',
+        });
+    }
+}
+/**
+ * Writes owned files and override records for the difference between the
+ * pristine commit and a result tree. Records name `pristine.commit` as
+ * their base. The source and metadata roots under the destination must be
+ * absent or empty; a failure leaves what was written for the caller to
+ * discard.
+ *
+ * @param pristine - The pinned pristine repository
+ * @param result - A tree and a repository holding both it and `pristine.commit`
+ * @param options - See {@link AdoptOptions}
+ * @throws `adopt-unsupported-kind` for a link or submodule among the changes,
+ *   `adopt-unownable-path` for a change source mode cannot own (a `.gitignore`),
+ *   `adopt-destination-not-empty`, `source-invalid-component`
+ */
+export async function adoptTrees(pristine, result, options) {
+    const sourceRoot = join(options.destination, options.sourceRoot);
+    const overrides = join(options.destination, options.metadataRoot, 'overrides');
+    await assertEmpty(sourceRoot);
+    await assertEmpty(join(options.destination, options.metadataRoot));
+    const paths = await changedPaths(result.repo, pristine.commit, result.tree);
+    const unownable = paths.flatMap((path) => {
+        const reason = unownableReason(path);
+        return reason === undefined ? [] : [`  ${path} ${reason}`];
+    });
+    if (unownable.length > 0) {
+        throw new FireForgeError('adopt-unownable-path', `Source mode cannot own these changed paths:\n${unownable.join('\n')}`, {
+            exitCode: ExitCode.PATCH_ERROR,
+            hint: 'Drop those changes from the patch queue (keep them in a file of the fork itself), then try again.',
+        });
+    }
+    const [before, after] = await Promise.all([pristine.commit, result.tree].map(async (treeish) => {
+        const entries = await listTree(result.repo, treeish, { paths, recursive: false });
+        return new Map(entries.map((entry) => [entry.path, entry]));
+    }));
+    const contents = await readBlobs(result.repo, [...(after?.values() ?? [])].map((entry) => entry.oid));
+    const adopted = { created: [], overridden: [], deleted: [] };
+    for (const path of [...paths].sort(compareText)) {
+        const old = regular(before?.get(path), 'pristine');
+        const next = regular(after?.get(path), 'result');
+        if (next !== undefined) {
+            await writeFile(join(sourceRoot, path), contents.get(next.oid) ?? Buffer.alloc(0), {
+                mode: next.mode === '100755' ? 0o755 : 0o644,
+                durable: false,
+            });
+        }
+        if (old === undefined) {
+            adopted.created.push(path);
+            continue;
+        }
+        const owner = options.ownerOf(path);
+        if (!COMPONENT_PATTERN.test(owner.component)) {
+            throw new FireForgeError('source-invalid-component', `"${owner.component}" (the component of ${path}) is not a component name.`, {
+                exitCode: ExitCode.INVALID_ARGUMENT,
+                hint: 'Rename the patch so that its first word is a component name: lowercase letters, digits and hyphens.',
+            });
+        }
+        const record = {
+            kind: next === undefined ? 'delete' : 'override',
+            base: { commit: pristine.commit, blob: old.oid, mode: old.mode },
+            component: owner.component,
+            classification: owner.adr === undefined ? 'registration' : 'exception',
+            ...(owner.adr === undefined ? {} : { adr: owner.adr }),
+        };
+        await writeFile(join(overrides, `${path}.json`), encodeRecord(record), { durable: false });
+        (next === undefined ? adopted.deleted : adopted.overridden).push(path);
+    }
+    await writeFile(join(sourceRoot, '.gitattributes'), completedAttributes(undefined) ?? '');
+    return adopted;
+}