@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/commands/re-export.js

@@ -1,334 +1,57 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { multiselect } from '@clack/prompts';
-import { getProjectPaths, loadConfig } from '../core/config.js';
-import { stdioIsInteractive } from '../core/destructive.js';
-import { assertEngineGitReady } from '../core/engine-precondition.js';
-import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
-import { formatPatchNotFoundError } from '../core/patch-identifier-suggest.js';
-import { loadPatchesManifest, resolvePatchIdentifier, stampPatchVersions, } from '../core/patch-manifest.js';
-import { GeneralError, InvalidArgumentError } from '../errors/base.js';
-import { elapsedSince } from '../utils/elapsed.js';
-import { toError } from '../utils/errors.js';
-import { cancel, info, intro, isCancel, outro, spinner, success, warn, } from '../utils/logger.js';
-import { ADJACENT_MEANS, buildAdjacentUnmanagedContext, reportAdjacentCarveOutUsage, } from './re-export-adjacent.js';
-import { loadScanFilesAssignments, withDryRunPurityGuard, withDryRunReExportLock, } from './re-export-bulk-scan.js';
-import { warnUnseenExpectedDrift } from './re-export-drift.js';
-import { reExportFilesInPlace } from './re-export-files.js';
-import { buildReExportLintContext, finishReExportLint } from './re-export-lint.js';
-import { applyReExportFilesPositionalFolding, validateReExportOptionCombinations, } from './re-export-options.js';
-import { validateExpectedRemovals } from './re-export-removed.js';
-import { dropRetiredPathDeclarations } from './re-export-retired-declarations.js';
-import { normalizeEngineRelativeInput, normalizeScanFiles } from './re-export-scan.js';
-import { assignScanFileOwners, scanOptionsForPatch } from './re-export-scan-owner.js';
-import { reExportSinglePatchWithIndexLockRetry, } from './re-export-single.js';
-import { formatReExportRunSummary } from './re-export-summary.js';
-async function resolveSelectedPatches(patches, options, manifest) {
-    if (options.all) {
-        return [...manifest.patches];
-    }
-    if (patches.length > 0) {
-        const selectedPatches = [];
-        for (const identifier of patches) {
-            const match = resolvePatchIdentifier(identifier, manifest.patches);
-            if (!match) {
-                // Suggest close matches instead of dumping the queue: a wrong guess
-                // would otherwise print the whole ~300-entry manifest, burying the
-                // error it was reporting.
-                throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
-            }
-            selectedPatches.push(match);
+import { arg, defineCommand, lockOptions, lockWaitMs, opt } from '../cli/command.js';
+import { withEngineLock } from '../engine/index.js';
+import { loadProject } from '../project/index.js';
+import { reExport as reExportPatches, requirePatchMode } from '../queue/index.js';
+export const reExport = defineCommand({
+    name: 're-export',
+    summary: 'Rewrite patches from the edits engine/ holds now',
+    description: 'Each patch is rewritten so the queue ends in what engine/ holds in its files. An edit to a ' +
+        'file several patches change goes to the last of them being re-exported; the others keep ' +
+        'their change. A patch whose files hold no edit is left byte for byte. A deleted file is ' +
+        'recorded as a deletion; a file the patch created that engine/ no longer has leaves the patch.',
+    group: 'Patches',
+    args: { patches: arg.list('Patches to rewrite (order, filename or name)') },
+    options: {
+        all: opt.flag('Rewrite every patch'),
+        scan: opt.flag("Adopt edits no patch owns in the directories the patches' files are in (into the last such patch)"),
+        dryRun: opt.flag('Report what would change and write nothing'),
+        stamp: opt.flag("Stamp the patches with the project's Firefox version"),
+        ...lockOptions,
+    },
+    constraints: { oneOf: [['patches', 'all']] },
+    json: true,
+    run: async (ctx, { patches }, opts) => {
+        const project = requirePatchMode(await loadProject(ctx.cwd, ctx.env));
+        const result = await withEngineLock(project, {
+            command: 're-export',
+            mode: opts.dryRun ? 'shared' : 'exclusive',
+            waitMs: lockWaitMs(opts.waitLock),
+        }, () => reExportPatches(project, {
+            ...(opts.all ? { all: true } : { patches }),
+            scan: opts.scan,
+            dryRun: opts.dryRun,
+            stamp: opts.stamp,
+        }));
+        const verb = opts.dryRun ? 'Would rewrite' : 'Rewrote';
+        for (const entry of result.patches) {
+            ctx.out.line(`${entry.status === 'rewritten' ? verb : 'Unchanged'} ${entry.patch}`);
+            for (const path of entry.adopted)
+                ctx.out.line(`  + ${path} (adopted)`);
+            for (const path of entry.dropped)
+                ctx.out.line(`  - ${path} (no longer changed)`);
+            if (entry.stamped)
+                ctx.out.line(`  stamped ${project.config.firefox.version}`);
         }
-        return selectedPatches;
-    }
-    // No patches specified: prompt or error
-    const isInteractive = stdioIsInteractive();
-    if (!isInteractive) {
-        throw new InvalidArgumentError('Specify patch identifiers or use --all in non-interactive mode.\n\n' +
-            'Usage: fireforge re-export [patches...] or fireforge re-export --all', 'patches');
-    }
-    const selected = await multiselect({
-        message: 'Select patches to re-export:',
-        options: manifest.patches.map((patch) => ({
-            value: patch.filename,
-            label: `${patch.filename} — ${patch.description || patch.name}`,
-        })),
-    });
-    if (isCancel(selected)) {
-        cancel('Re-export cancelled');
-        return null;
-    }
-    const selectedFilenames = selected;
-    return manifest.patches.filter((p) => selectedFilenames.includes(p.filename));
-}
-/** Refreshes each selected patch in turn, collecting which wrote and which failed. */
-async function reExportEach(args) {
-    const { selectedPatches, options, scanAssignments, progress, startedAt, shared } = args;
-    const written = [];
-    const failed = [];
-    for (const [index, patch] of selectedPatches.entries()) {
-        const patchOptions = scanOptionsForPatch(options, patch.filename, scanAssignments);
-        progress.message(`Re-exporting ${index + 1}/${selectedPatches.length}: ${patch.filename} (${patch.filesAffected.length} file(s), ${elapsedSince(startedAt)} elapsed)...`);
-        try {
-            if (await reExportSinglePatchWithIndexLockRetry({ ...shared, patch, options: patchOptions })) {
-                written.push(patch.filename);
-            }
-        }
-        catch (error) {
-            failed.push(patch.filename);
-            warn(`Failed to re-export ${patch.filename}`);
-            warn(toError(error).message);
-        }
-    }
-    return { written, failed };
-}
-/**
- * Runs the re-export command to regenerate existing patches from current engine state.
- * @param projectRoot - Root directory of the project
- * @param patches - Patch identifiers (numbers or filenames)
- * @param options - Re-export options
- */
-export async function reExportCommand(projectRoot, patches, options) {
-    const normalizedScanFiles = normalizeScanFiles(options.scanFiles);
-    if (normalizedScanFiles !== undefined) {
-        options = { ...options, scanFiles: normalizedScanFiles };
-    }
-    else if (options.scanFiles !== undefined) {
-        const cleanedOptions = { ...options };
-        delete cleanedOptions.scanFiles;
-        options = cleanedOptions;
-    }
-    const isDryRun = options.dryRun === true;
-    // The banner says which mode is in force: a path flag that swallowed
-    // `--dry-run` as its value once turned a preview into a write unnoticed.
-    intro(isDryRun ? 'FireForge Re-export (DRY RUN)' : 'FireForge Re-export (WRITING)');
-    // Accept export-style space-separated paths after --files by folding
-    // path-shaped extra positionals into the file list.
-    ({ patches, options } = applyReExportFilesPositionalFolding(patches, options));
-    validateReExportOptionCombinations(patches, options);
-    const paths = getProjectPaths(projectRoot);
-    await assertEngineGitReady(paths.engine);
-    // Load the manifest
-    const manifest = await loadPatchesManifest(paths.patches);
-    if (!manifest || manifest.patches.length === 0) {
-        throw new GeneralError('No patches found in manifest. Run "fireforge export" to create patches first.');
-    }
-    const scanFilesByPatch = options.scanFilesManifest !== undefined
-        ? await loadScanFilesAssignments(options.scanFilesManifest, manifest)
-        : undefined;
-    // Resolve which patches to re-export
-    const selectedPatches = scanFilesByPatch !== undefined
-        ? manifest.patches.filter((patch) => scanFilesByPatch.has(patch.filename))
-        : await resolveSelectedPatches(patches, options, manifest);
-    if (!selectedPatches)
-        return;
-    const scanAssignments = scanFilesByPatch ?? assignScanFileOwners(options.scanFiles, selectedPatches, manifest);
-    if (selectedPatches.length === 0) {
-        warn('No patches selected');
-        outro('Nothing to re-export');
-        return;
-    }
-    const expectedRemovals = await validateExpectedRemovals(paths, selectedPatches, options, manifest.patches);
-    if (expectedRemovals.length > 0)
-        options = { ...options, expectRemoved: expectedRemovals };
-    if (scanFilesByPatch !== undefined) {
-        info(`Bulk scan assignments from ${options.scanFilesManifest}`);
-        for (const patch of selectedPatches) {
-            const files = scanFilesByPatch.get(patch.filename) ?? [];
-            info(`  ${patch.filename} <= ${files.length} file(s)`);
-            for (const file of files)
-                info(`    + ${file}`);
-        }
-    }
-    // --files path: handled end-to-end here so we can lint the *projected*
-    // shrunken state (not the current queue) and skip the generic re-export
-    // loop. The projection substitutes the target patch's diff and newFiles
-    // with the freshly computed content, then runs lintPatchQueue so any
-    // forward-import introduced or uncovered by the shrink is caught before
-    // we write anything.
-    if (options.files !== undefined) {
-        const filesConfig = await loadConfig(projectRoot);
-        await withDryRunReExportLock(paths.fireforgeDir, isDryRun, () => withDryRunPurityGuard(paths.engine, paths.patches, isDryRun, () => reExportFilesInPlace(paths, selectedPatches, options, filesConfig), { patches: selectedPatches }));
-        return;
-    }
-    const config = await loadConfig(projectRoot);
-    // Classification inputs for the scan-less adjacency advisory, computed
-    // once for the whole run.
-    const adjacentCtx = buildAdjacentUnmanagedContext(options, config.binaryName, await collectFurnaceManagedPrefixes(paths.root));
-    const driftCtx = buildForeignDriftContext(options);
-    // Hoisted lint context, one per run: queue context + checkJs
-    // program + per-patch result cache, shared across every loop iteration.
-    // Taken before the context build, so the elapsed time the progress line
-    // reports includes it.
-    const startedAt = Date.now();
-    const lintCtx = await buildReExportLintContext(projectRoot, paths, config, options.noCache === true, new Set(selectedPatches.map((patch) => patch.filename)));
-    const progress = spinner('Preparing re-export...');
-    const outcome = await withDryRunReExportLock(paths.fireforgeDir, isDryRun, () => withDryRunPurityGuard(paths.engine, paths.patches, isDryRun, () => reExportEach({
-        selectedPatches,
-        options,
-        scanAssignments,
-        progress,
-        startedAt,
-        shared: { paths, manifest, isDryRun, config, adjacentCtx, driftCtx, lintCtx },
-    }), { patches: selectedPatches }));
-    const reExportedFilenames = outcome.written;
-    const failedFilenames = outcome.failed;
-    const reExported = reExportedFilenames.length;
-    await finishReExportLint(lintCtx);
-    warnUnseenExpectedDrift(driftCtx);
-    warnUnseenApprovedUnmanaged(adjacentCtx);
-    const summary = formatReExportRunSummary({
-        selected: selectedPatches.map((patch) => patch.filename),
-        written: reExportedFilenames,
-        failed: failedFilenames,
-        refusedAdjacent: adjacentCtx.refusals.map((r) => r.patchFilename),
-        refusedDrift: driftCtx.refusals.map((r) => r.patchFilename),
-        isDryRun,
-    });
-    if (summary !== undefined)
-        info(summary);
-    throwRunLevelRefusals(adjacentCtx, driftCtx, progress);
-    if (reExported === 0 && selectedPatches.length > 0) {
-        progress.error('Re-export failed');
-        throw new GeneralError('All selected patches failed to re-export. Check the errors above.');
-    }
-    // Declarations on a path this run retired can never be met; drop them
-    // now rather than leave them for the next per-patch lint to report.
-    await dropRetiredPathDeclarations({ paths, manifest, options, selectedPatches, isDryRun });
-    // `--stamp` only fires on a run where every selected patch refreshed
-    // cleanly. A partial success would leave some patches with a stale body
-    // but a new version, the opposite of the "what I tested, what the
-    // manifest says" invariant `sourceEsrVersion` exists to record. A
-    // non-empty `reExportedFilenames` with fewer entries than `selectedPatches`
-    // means a lint failure or missing-file skip landed somewhere in the loop,
-    // which we refuse to version-stamp through.
-    const shouldStamp = options.stamp === true && !isDryRun && reExported > 0 && reExported === selectedPatches.length;
-    if (shouldStamp) {
-        await stampPatchVersions(paths.patches, reExportedFilenames, config.firefox.version, config.firefox.product);
-    }
-    reportReExportOutcome({
-        isDryRun,
-        reExported,
-        selectedCount: selectedPatches.length,
-        reExportedFilenames,
-        failedFilenames,
-        selectedFilenames: selectedPatches.map((patch) => patch.filename),
-        shouldStamp,
-        stampRequested: options.stamp === true,
-        config,
-        progress,
-    });
-}
-/**
- * Foreign-drift guard context, one per run. `--expect` paths
- * are normalized once here so the per-patch comparison matches
- * them against engine-relative diff-section paths.
- */
-function buildForeignDriftContext(options) {
-    return {
-        refuseForeignDrift: options.refuseForeignDrift === true,
-        expectedDriftFiles: new Set((options.expect ?? []).map((file) => normalizeEngineRelativeInput(file, '--expect'))),
-        expectedSeen: new Set(),
-        evaluationRuns: 0,
-        refusals: [],
-    };
-}
-/**
- * Names `--expect-unmanaged` paths that were never met this run. A typo'd
- * carve-out silently leaves the refusal armed for the path it was meant to
- * admit, and reads as an approval that is in force when it is not.
- * A warning rather than a refusal: an approved path legitimately goes unmet
- * when the reviewed file has since been adopted into a patch, which is the
- * outcome the carve-out exists to be retired by. The `--expect-new` and
- * `--adjacent-ignore` accounting is reported first, alongside.
- */
-function warnUnseenApprovedUnmanaged(adjacentCtx) {
-    reportAdjacentCarveOutUsage(adjacentCtx);
-    const unseen = [...adjacentCtx.approvedUnmanaged].filter((file) => !adjacentCtx.approvedSeen.has(file));
-    if (unseen.length === 0)
-        return;
-    warn('--expect-unmanaged path(s) were not met as adjacent unmanaged files this run: ' +
-        `${unseen.join(', ')}. ` +
-        'Causes, in rough order of likelihood: a typo in the path; the file is now owned by a ' +
-        'patch (the carve-out can be dropped); or no selected patch is adjacent to it. The ' +
-        'refusal stayed armed for everything else either way.');
-}
-/**
- * Turns the run's collected `--refuse-adjacent-unmanaged` and
- * `--refuse-foreign-drift` refusals into the non-zero exit,
- * naming every refused patch and the remedy.
- */
-function throwRunLevelRefusals(adjacentCtx, driftCtx, progress) {
-    if (adjacentCtx.refusals.length > 0) {
-        progress.error('Re-export refused');
-        // Each offender is named with the owned directory (or registering
-        // carrier) that made it adjacent: an unattended run reads only this
-        // line, and without the anchor it cannot tell which of a
-        // multi-directory patch's locations the file belongs to.
-        const offenders = adjacentCtx.refusals
-            .map((r) => `${r.patchFilename} (${r.anchored.join(', ')})`)
-            .join('; ');
-        throw new GeneralError(`Refused ${adjacentCtx.refusals.length} patch(es) with adjacent unmanaged files ` +
-            `(--refuse-adjacent-unmanaged): ${offenders}. ${ADJACENT_MEANS} ` +
-            `Adopt reviewed files with --scan --scan-file, or export them as a new patch ` +
-            `(name a file your next export adopts with --expect-new, and a reviewed, deliberately ` +
-            `unmanaged file with --expect-unmanaged or --adjacent-ignore).`);
-    }
-    if (driftCtx.refusals.length > 0) {
-        progress.error('Re-export refused');
-        const names = driftCtx.refusals.map((r) => r.patchFilename).join(', ');
-        const unreadable = driftCtx.refusals.filter((r) => r.reason === 'baseline-unreadable');
-        const unreadablePart = unreadable.length > 0
-            ? ` ${unreadable.length} of these refused because the old patch body was missing or unreadable, so the drift comparison could not run (fail-closed).`
-            : '';
-        throw new GeneralError(`Refused ${driftCtx.refusals.length} patch(es) whose refreshed body would add or drop ` +
-            `lines relative to the old patch body (--refuse-foreign-drift): ${names}.${unreadablePart}\n\n` +
-            'The flag cannot tell WHO wrote those lines, and the two populations have opposite ' +
-            'remedies:\n' +
-            '  - Lines you changed yourself since the last export (the per-file report tags these ' +
-            '"edited since your last export"): name them with --expect <path> so this run captures ' +
-            'them, or re-run without the flag to capture every drifting file.\n' +
-            "  - Lines another session owns: do NOT proceed — commit or stash that session's work " +
-            'first, then re-run.');
-    }
-}
-/**
- * Prints the end-of-run summary and enforces the exit contract: a partial run
- * exits non-zero by default. "Re-exported 2 of 3" printing with exit 0 lets a
- * partial refresh ride an `&&` chain as success. The summary still prints
- * first so the honest "N of M" accounting stays visible. The throw then
- * carries the failed/skipped breakdown. Dry-run included: a preview
- * reporting that the real run would partially fail must not read as a passing
- * preview in scripts.
- */
-function reportReExportOutcome(args) {
-    const { isDryRun, reExported, selectedCount, config, progress } = args;
-    if (isDryRun) {
-        progress.stop('Dry run complete');
-        success(`[dry-run] Would re-export ${reExported} of ${selectedCount} patch(es)`);
-        if (args.stampRequested) {
-            info(`[dry-run] Would stamp sourceVersion=${config.firefox.version} (${config.firefox.product}) on ${reExported} patch(es)`);
-        }
-        outro('Dry run complete');
-    }
-    else {
-        progress.stop('Re-export complete');
-        success(`Re-exported ${reExported} of ${selectedCount} patch(es)`);
-        if (args.shouldStamp) {
-            success(`Stamped sourceVersion=${config.firefox.version} (${config.firefox.product}) on ${args.reExportedFilenames.length} patch(es)`);
-        }
-        else if (args.stampRequested && reExported !== selectedCount) {
-            warn('--stamp was requested but some patches failed or were skipped; refusing to stamp a partial set.');
-        }
-        outro('Re-export complete');
-    }
-    if (reExported < selectedCount) {
-        const failedPart = args.failedFilenames.length > 0 ? ` Failed: ${args.failedFilenames.join(', ')}.` : '';
-        const accounted = new Set([...args.reExportedFilenames, ...args.failedFilenames]);
-        const skipped = args.selectedFilenames.filter((name) => !accounted.has(name));
-        const skippedPart = skipped.length > 0 ? ` Skipped: ${skipped.join(', ')} (see warnings above).` : '';
-        throw new GeneralError(`${isDryRun ? '[dry-run] Would re-export' : 'Re-exported'} only ${reExported} of ` +
-            `${selectedCount} selected patch(es).${failedPart}${skippedPart} ` +
-            'Partial re-export exits non-zero so it cannot pass as success in scripts; ' +
-            'the per-patch errors are listed above.');
-    }
-}
+        ctx.out.json({
+            dryRun: opts.dryRun,
+            patches: result.patches.map((entry) => ({
+                patch: entry.patch,
+                status: entry.status,
+                adopted: [...entry.adopted],
+                dropped: [...entry.dropped],
+                stamped: entry.stamped,
+            })),
+        });
+    },
+});

package/dist/src/commands/rebase.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { defineCommand, lockOptions, lockWaitMs, opt } from '../cli/command.js';
+import { FIREFOX_PRODUCTS } from '../config/index.js';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { step } from '../kernel/log.js';
+import { rebase as rebaseProject } from '../mode/index.js';
+import { loadProject } from '../project/index.js';
+export const rebase = defineCommand({
+    name: 'rebase',
+    summary: 'Move the project to a new Firefox version',
+    description: 'Downloads the new version and writes it to fireforge.json. Patch mode: replaces engine/ ' +
+        'with the new source and re-applies the queue with reduced context, rewriting every patch; ' +
+        'a patch that does not apply pauses the rebase for --continue, or for --abort, which ' +
+        'restores the previous version, its engine and the applied queue. Source mode: ' +
+        'merges every owned file three ways on a committed tree; conflicts are left as markers.',
+    group: 'Project',
+    options: {
+        to: opt.string('The Firefox version to move to, such as 153.8.0esr', {
+            valueName: 'version',
+        }),
+        product: opt.enum(FIREFOX_PRODUCTS, 'Product of the new version (default: by its shape)'),
+        sha256: opt.string('Pinned SHA-256 of the new source archive', { valueName: 'digest' }),
+        candidate: opt.string('Release-candidate build directory of the new version, such as build1', {
+            valueName: 'build',
+        }),
+        continue: opt.flag('Patch mode: resume a paused rebase from the fixed engine'),
+        abort: opt.flag('Patch mode: give up a paused rebase and go back to the version it left'),
+        dryRun: opt.flag('Patch mode: report whether the queue applies, changing nothing'),
+        force: opt.flag('Patch mode: rebase over engine edits no patch has (a recovery snapshot keeps them)'),
+        ...lockOptions,
+    },
+    constraints: {
+        exclusive: [['continue', 'abort', 'dryRun', 'force']],
+        requires: { product: ['to'], sha256: ['to'], candidate: ['to'] },
+    },
+    json: true,
+    run: async (ctx, _args, opts) => {
+        const project = await loadProject(ctx.cwd, ctx.env);
+        const report = await rebaseProject(project, {
+            to: opts.to,
+            product: opts.product,
+            sha256: opts.sha256,
+            candidate: opts.candidate,
+            continue: opts.continue,
+            abort: opts.abort,
+            dryRun: opts.dryRun,
+            force: opts.force,
+            waitMs: lockWaitMs(opts.waitLock),
+            onProgress: step,
+        });
+        for (const entry of report.entries) {
+            if (entry.outcome !== 'kept' && entry.outcome !== 'applied') {
+                ctx.out.line(`${entry.outcome}  ${entry.subject}`);
+            }
+        }
+        for (const conflict of report.conflicts)
+            ctx.out.line(`conflict  ${conflict}`);
+        ctx.out.line(`Rebase ${report.status}: Firefox ${report.pin.version} (${report.pin.product}).`);
+        ctx.out.json({ ...report });
+        if (report.conflicts.length > 0) {
+            throw new FireForgeError('rebase-conflicts', `${report.conflicts.length} conflict(s) need resolving.`, {
+                exitCode: ExitCode.RESOLUTION_ERROR,
+                hint: report.status === 'dry-run'
+                    ? 'Nothing was changed.'
+                    : 'Resolve the conflict markers in the listed files, then commit.',
+            });
+        }
+    },
+});

package/dist/src/commands/register.js

@@ -1,106 +1,65 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
-import { Command } from 'commander';
-import { getProjectPaths } from '../core/config.js';
-import { registerFile } from '../core/moz-manifest-rules.js';
-import { InvalidArgumentError } from '../errors/base.js';
-import { pathExists } from '../utils/fs.js';
-import { info, intro, outro, success, warn } from '../utils/logger.js';
-import { pickDefined } from '../utils/options.js';
-import { stripEnginePrefix } from '../utils/paths.js';
-/**
- * Registers a file in the appropriate build manifest.
- *
- * @param projectRoot - Root directory of the project
- * @param filePath - Path relative to engine/ (a leading `engine/` segment is stripped)
- * @param options - Command options
- */
-export async function registerCommand(projectRoot, filePath, options = {}) {
-    intro('Register');
-    // --after is matched as a substring against existing manifest lines.
-    // Guard against control characters / line terminators that would either
-    // break the match logic or, worse, inject a second line if the value
-    // is ever echoed back to a manifest writer. Null bytes are explicitly
-    // rejected to mirror the hardening already applied to other user-
-    // supplied identifiers (binaryName, furnace targetPath, …).
-    if (options.after !== undefined) {
-        // eslint-disable-next-line no-control-regex -- control chars in --after would break the manifest match
-        const hasControlChar = /[\u0000-\u001f]/.test(options.after);
-        if (options.after.length === 0 || hasControlChar) {
-            throw new InvalidArgumentError('--after must be a non-empty substring without control characters or line terminators.', 'after');
+import { arg, defineCommand, lockOptions, lockWaitMs, opt } from '../cli/command.js';
+import { editTracked, enginePathOf, trackedFiles } from '../mode/index.js';
+import { loadProject } from '../project/index.js';
+import { applyEdits, planRegister } from '../register/index.js';
+export const register = defineCommand({
+    name: 'register',
+    summary: 'Register an engine file in the build manifest it belongs in',
+    description: 'The manifest follows from the path: jar.mn for chrome content, skin and widget files, ' +
+        'the directory moz.build for JS modules, the moz.build above a test manifest for the ' +
+        'manifest, and the directory test manifest for a test file. A file that is already registered is left alone. In source mode the ' +
+        'first edit of an upstream manifest declares its override as a registration.',
+    group: 'Authoring',
+    args: { path: arg.string('Engine file, such as browser/base/content/panel.js') },
+    options: {
+        dryRun: opt.flag('Show the planned edit without writing'),
+        after: opt.string('Place the entry after this one (jar.mn and test manifests only)', {
+            valueName: 'entry',
+        }),
+        createManifest: opt.flag('Create a missing moz.build or test manifest and wire it into its parents'),
+        ...lockOptions,
+    },
+    json: true,
+    run: async (ctx, { path }, opts) => {
+        const project = await loadProject(ctx.cwd, ctx.env);
+        const files = await trackedFiles(project, { declare: true });
+        const enginePath = enginePathOf(project, path);
+        const plan = await planRegister(files, {
+            path: enginePath,
+            moduleDir: `browser/modules/${project.config.binaryName}`,
+            license: project.config.license,
+            mustExist: !opts.dryRun,
+            ...(opts.after === undefined ? {} : { after: opts.after }),
+            ...(opts.createManifest ? { createManifest: true } : {}),
+        });
+        const changes = plan.edits.length > 0;
+        if (changes && !opts.dryRun) {
+            await editTracked(project, {
+                label: `registering ${enginePath}`,
+                command: 'register',
+                waitMs: lockWaitMs(opts.waitLock),
+            }, (tx) => applyEdits(tx, files, plan.edits));
         }
-    }
-    // Accept either repo-root-relative (`engine/browser/...`) or
-    // engine-relative (`browser/...`) inputs. Operators frequently paste
-    // the former from the output of tab completion or `git status`, so
-    // both shapes resolve to the same path instead of a "File not found"
-    // error.
-    const engineRelativePath = stripEnginePrefix(filePath);
-    // Verify the file exists in engine/ (skip for dry-run)
-    if (!options.dryRun) {
-        const paths = getProjectPaths(projectRoot);
-        const fullPath = join(paths.engine, engineRelativePath);
-        if (!(await pathExists(fullPath))) {
-            throw new InvalidArgumentError(`File not found in engine: ${engineRelativePath}`, 'path');
+        const verb = !changes ? 'Already registered' : opts.dryRun ? 'Would register' : 'Registered';
+        ctx.out.line(`${verb} ${enginePath} in ${plan.manifest}`);
+        if (changes) {
+            ctx.out.line(`  entry: ${plan.entry}`);
+            for (const step of plan.steps.slice(1))
+                ctx.out.line(`  also: ${step.path}: ${step.change}`);
+            if (plan.previous !== undefined)
+                ctx.out.line(`  after: ${plan.previous}`);
+            if (plan.afterFallback === true) {
+                ctx.out.line('  --after named no entry, so the entry went in sort order');
+            }
         }
-    }
-    const result = await registerFile(projectRoot, engineRelativePath, options.dryRun, options.after, {
-        ...(options.createManifest !== undefined ? { createManifest: options.createManifest } : {}),
-    });
-    if (options.dryRun) {
-        // Dry-run must surface the idempotency decision too. Always saying
-        // "Would register", even when the rule already knows the entry is
-        // present, makes automation read the plan as "work to do" while the
-        // following real run reports "Already registered".
-        if (result.skipped) {
-            info(`[dry-run] Already registered: ${engineRelativePath} in ${result.manifest}`);
-            outro('Dry run complete');
-            return;
-        }
-        info(`[dry-run] Would register ${engineRelativePath}`);
-        info(`  manifest: ${result.manifest}`);
-        info(`  entry: ${result.entry}`);
-        for (const action of result.scaffoldActions ?? []) {
-            info(`  scaffold: ${action.manifest} — ${action.change}`);
-        }
-        if (result.previousEntry) {
-            info(`  insert after: ${result.previousEntry}`);
-        }
-        else {
-            info('  insert at: start of matching section');
-        }
-        if (result.afterFallback) {
-            warn(`--after target "${options.after}" not found, falling back to alphabetical order`);
-        }
-        outro('Dry run complete');
-        return;
-    }
-    if (result.skipped) {
-        info(`Already registered: ${engineRelativePath} in ${result.manifest}`);
-    }
-    else {
-        if (result.afterFallback) {
-            warn(`--after target "${options.after}" not found, falling back to alphabetical order`);
-        }
-        const position = result.previousEntry ? ` (after ${result.previousEntry})` : '';
-        success(`Registered ${engineRelativePath} in ${result.manifest}${position}`);
-        for (const action of result.scaffoldActions ?? []) {
-            info(`  scaffold: ${action.manifest} — ${action.change}`);
-        }
-        info("hint: Run 'fireforge build --ui' to make the new module available at runtime");
-    }
-    outro('Done');
-}
-/** Registers the browser content registration command on the CLI program. */
-export function registerRegister(program, { getProjectRoot, withErrorHandling }) {
-    program
-        .command('register <path>')
-        .description('Register a file in the appropriate build manifest')
-        .option('--dry-run', 'Show what would be changed without writing')
-        .option('--after <entry>', 'Place entry after line containing this substring (instead of alphabetical); for an ' +
-        'xpcshell test, after the whole section of the xpcshell.toml entry it names')
-        .option('--create-manifest', 'Scaffold a missing manifest (directory moz.build with EXTRA_JS_MODULES / XPCSHELL_TESTS_MANIFESTS, or xpcshell.toml) and wire the parent DIRS chain instead of failing with "Manifest not found"')
-        .action(withErrorHandling(async (path, options) => {
-        await registerCommand(getProjectRoot(), path, pickDefined(options));
-    }));
-}
+        ctx.out.json({
+            path: enginePath,
+            manifest: plan.manifest,
+            entry: plan.entry,
+            changed: changes,
+            dryRun: opts.dryRun,
+            steps: plan.steps.map((step) => ({ ...step })),
+        });
+    },
+});