@hominis/fireforge 0.55.0 → 0.60.0

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 })),
+        });
+    },
+});

package/dist/src/commands/reset.js

@@ -1,93 +1,30 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { confirm } from '@clack/prompts';
-import { Command } from 'commander';
-import { getProjectPaths } from '../core/config.js';
-import { stdioIsInteractive } from '../core/destructive.js';
-import { assertEngineGitReady } from '../core/engine-precondition.js';
-import { clearAppliedFurnaceState } from '../core/furnace-config.js';
-import { hasChanges, resetChanges } from '../core/git.js';
-import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
-import { warnIfStaticComponentsStale } from '../core/test-stale-check.js';
-import { InvalidArgumentError } from '../errors/base.js';
-import { cancel, info, intro, isCancel, outro, spinner, warn } from '../utils/logger.js';
-import { pickDefined } from '../utils/options.js';
-/**
- * Runs the reset command to restore clean Firefox state.
- * @param projectRoot - Root directory of the project
- * @param options - Reset options
- */
-export async function resetCommand(projectRoot, options) {
-    intro('FireForge Reset');
-    const paths = getProjectPaths(projectRoot);
-    await assertEngineGitReady(paths.engine);
-    // Check for changes
-    const hasUncommittedChanges = await hasChanges(paths.engine);
-    if (!hasUncommittedChanges) {
-        info('No changes to reset');
-        outro('Working tree already clean');
-        return;
-    }
-    // Dry-run: show what would be reset
-    if (options.dryRun) {
-        const statusEntries = await expandUntrackedDirectoryEntries(paths.engine, await getWorkingTreeStatus(paths.engine));
-        info(`Would reset ${statusEntries.length} file${statusEntries.length === 1 ? '' : 's'}:`);
-        for (const entry of statusEntries) {
-            const label = entry.originalPath ? `${entry.originalPath} -> ${entry.file}` : entry.file;
-            info(`  ${label}`);
+import { confirmOptions, defineCommand, lockOptions, lockWaitMs, usageError, } from '../cli/command.js';
+import { withEngineLock } from '../engine/index.js';
+import { confirm } from '../kernel/tty.js';
+import { loadProject } from '../project/index.js';
+import { requirePatchMode, resetEngine } from '../queue/index.js';
+export const reset = defineCommand({
+    name: 'reset',
+    summary: 'Reset engine/ to pristine Firefox, dropping every change',
+    description: 'Tracked files are restored, untracked files removed, build output kept. A paused import or ' +
+        'rebase is dropped. A recovery snapshot keeps what is discarded.',
+    group: 'Patches',
+    options: { ...confirmOptions, ...lockOptions },
+    json: true,
+    run: async (ctx, _args, opts) => {
+        const project = requirePatchMode(await loadProject(ctx.cwd, ctx.env));
+        if (!opts.yes) {
+            if (!ctx.interactive) {
+                throw usageError('reset discards every change in engine/.', 'Pass --yes to confirm.');
+            }
+            if (!(await confirm('Discard every change in engine/?')))
+                return;
         }
-        outro('Dry run complete — no changes made');
-        return;
-    }
-    // Confirm reset unless --yes is specified
-    if (!options.yes) {
-        // Check for non-interactive mode
-        const isInteractive = stdioIsInteractive();
-        if (!isInteractive) {
-            throw new InvalidArgumentError('Interactive confirmation not available. Use --yes flag to reset without confirmation.', 'Use: fireforge reset --yes');
-        }
-        warn('This will discard all uncommitted changes in the engine directory, including staged additions and untracked files.');
-        const confirmed = await confirm({
-            message: 'Are you sure you want to reset?',
-            initialValue: false,
-        });
-        if (isCancel(confirmed) || !confirmed) {
-            cancel('Reset cancelled');
-            return;
-        }
-    }
-    const s = spinner('Resetting changes...');
-    try {
-        await resetChanges(paths.engine);
-        // Clearing furnace-state.json is the honest representation of what just
-        // happened: any previously deployed Furnace files have been discarded
-        // with the engine reset. Without this, a subsequent `furnace apply`
-        // would match on workspace checksums and report "up to date" against
-        // an engine that no longer contains the deployed copies. (The drift
-        // check in apply also catches this, but clearing here keeps state
-        // consistent regardless of the drift oracle.) Preserve pendingRepair:
-        // authoring-side rollback markers are about the workspace/component
-        // tree, not the engine checkout, so reset must not silently forget them.
-        await clearAppliedFurnaceState(projectRoot);
-        s.stop('Changes reset');
-        // The reset may have moved components.conf away from what the last full
-        // build compiled in, so surface that now instead of at the next test
-        // refusal.
-        await warnIfStaticComponentsStale(projectRoot, paths.engine);
-        outro('Working tree restored to clean state');
-    }
-    catch (error) {
-        s.error('Reset failed');
-        throw error;
-    }
-}
-/** Registers the reset command on the CLI program. */
-export function registerReset(program, { getProjectRoot, withErrorHandling }) {
-    program
-        .command('reset')
-        .description('Reset engine/ to clean state')
-        .option('-y, --yes', 'Skip confirmation prompt (required for scripts/CI)')
-        .option('--dry-run', 'Show what would be reset without doing it')
-        .action(withErrorHandling(async (options) => {
-        await resetCommand(getProjectRoot(), pickDefined(options));
-    }));
-}
+        const result = await withEngineLock(project, { command: 'reset', waitMs: lockWaitMs(opts.waitLock) }, () => resetEngine(project));
+        ctx.out.line(result.changed ? 'engine/ is pristine again.' : 'engine/ was already pristine.');
+        if (result.snapshot !== undefined)
+            ctx.out.line(`Recovery snapshot: ${result.snapshot}`);
+        ctx.out.json({ changed: result.changed, snapshot: result.snapshot ?? null });
+    },
+});

package/dist/src/commands/resolve.js

@@ -1,168 +1,21 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
-import { confirm } from '@clack/prompts';
-import { Command } from 'commander';
-import { getProjectPaths, loadConfig, loadState } from '../core/config.js';
-import { stdioIsInteractive } from '../core/destructive.js';
-import { assertEngineGitReady } from '../core/engine-precondition.js';
-import { getStagedDiffForFiles } from '../core/git-diff.js';
-import { stageFiles, unstageFiles } from '../core/git-file-ops.js';
-import { extractAffectedFiles } from '../core/patch-apply.js';
-import { updatePatchAndMetadata } from '../core/patch-export.js';
-import { loadPatchesManifest } from '../core/patch-manifest.js';
-import { buildPatchSourceMetadata } from '../core/patch-source-metadata.js';
-import { GeneralError, ResolutionError } from '../errors/base.js';
-import { toError } from '../utils/errors.js';
-import { pathExists } from '../utils/fs.js';
-import { error as logError, info, intro, isCancel, outro, spinner, success, } from '../utils/logger.js';
-import { addWaitLockOption, resolveWaitLockSeconds } from '../utils/options.js';
-import { clearPendingResolution } from './pending-resolution.js';
-/**
- * Runs the resolve command to fix broken patches.
- * @param projectRoot - Root directory of the project
- * @param options - Optional flags. See {@link ResolveCommandOptions}.
- */
-export async function resolveCommand(projectRoot, options = {}) {
-    intro('FireForge Resolve');
-    const paths = getProjectPaths(projectRoot);
-    const state = await loadState(projectRoot);
-    if (!state.pendingResolution) {
-        info('No patch resolution currently required.');
-        outro('Resolution complete');
-        return;
-    }
-    const { patchFilename } = state.pendingResolution;
-    info(`Resolving conflict for patch: ${patchFilename}`);
-    await assertEngineGitReady(paths.engine);
-    // Non-interactive mode requires an explicit `--yes`: the operator is
-    // asserting the manual merge is complete and the refreshed diff is the one
-    // to record. Without it, an accidental pipe or CI shell could commit
-    // whatever the engine currently contains, but an unconditional TTY
-    // refusal dead-ends a scripted recovery flow.
-    if (!stdioIsInteractive() && !options.yes) {
-        throw new GeneralError('Cannot run "fireforge resolve" in non-interactive mode. Use a terminal with TTY support, or pass "--yes" to skip the interactive confirmation once the manual merge is complete.');
-    }
-    if (!options.yes) {
-        const finished = await confirm({
-            message: 'Have you finished manually fixing the files in engine/?',
-            initialValue: true,
-        });
-        if (isCancel(finished) || !finished) {
-            info('Please fix the conflicts and run "fireforge resolve" again.');
-            outro('Resolution paused');
-            return;
-        }
-    }
-    const manifest = await loadPatchesManifest(paths.patches);
-    if (!manifest) {
-        throw new GeneralError('Patches manifest not found.');
-    }
-    const patchMetadata = manifest.patches.find((p) => p.filename === patchFilename);
-    if (!patchMetadata) {
-        throw new ResolutionError(`Patch ${patchFilename} not found in manifest.`);
-    }
-    // Refuse to proceed if the patch file was deleted between the conflict
-    // and the resolve. Without this check, `updatePatchAndMetadata` would
-    // throw a less actionable "patch file is missing" error from inside
-    // the lock. The explicit precondition lets us point the user at the
-    // exact recovery path.
-    const patchPath = join(paths.patches, patchFilename);
-    if (!(await pathExists(patchPath))) {
-        throw new ResolutionError(`Patch file ${patchFilename} is missing on disk. ` +
-            'Delete the "pendingResolution" key from state.json to clear the stale conflict, ' +
-            'or restore the patch file before re-running resolve.');
-    }
-    const s = spinner(`Updating ${patchFilename}...`);
-    try {
-        const existingFiles = patchMetadata.filesAffected;
-        // Verify all affected files exist in engine/
-        const missingFiles = [];
-        for (const file of existingFiles) {
-            const filePath = join(paths.engine, file);
-            if (!(await pathExists(filePath))) {
-                missingFiles.push(file);
-            }
-        }
-        if (missingFiles.length === existingFiles.length) {
-            throw new ResolutionError(`All affected files for ${patchFilename} are missing.`);
-        }
-        // Filter to only existing files
-        const activeFiles = existingFiles.filter((f) => !missingFiles.includes(f));
-        // Stage, diff, unstage
-        let diffContent;
-        let staged = false;
-        try {
-            await stageFiles(paths.engine, activeFiles);
-            staged = true;
-            diffContent = await getStagedDiffForFiles(paths.engine, activeFiles);
-        }
-        finally {
-            if (staged) {
-                await unstageFiles(paths.engine, activeFiles);
-            }
-        }
-        if (!diffContent.trim()) {
-            s.stop(`No patch update generated for ${patchFilename}`);
-            info('No patch update was generated from the staged diff. Pending resolution was left intact so you can retry. To discard the resolution state, delete the "pendingResolution" key from state.json.');
-            outro('Resolution unchanged');
-            return;
-        }
-        // Atomically write the patch body and the metadata update under the
-        // shared patch-directory lock. A lock-free updatePatch +
-        // updatePatchMetadata sequence can be interleaved by a concurrent
-        // import / export / re-export / patch reorder / patch compact, leaving
-        // the manifest disagreeing with the freshly-written patch body.
-        //
-        // Always recompute `filesAffected` from the diff content itself. When a
-        // manual fix removes every hunk for one file while the file still exists
-        // on disk, a gate of "update filesAffected only when files were deleted
-        // from disk" leaves the manifest claiming a file the patch body no longer
-        // targets, and the next `fireforge import` fails the patch-manifest
-        // consistency check even though resolve reported success.
-        // `extractAffectedFiles` already owns the canonical "parse a diff, return
-        // its target paths" logic used by export and consistency, so using it
-        // here keeps resolve in agreement with every other writer.
-        const diffFilesAffected = extractAffectedFiles(diffContent);
-        const config = await loadConfig(projectRoot);
-        await updatePatchAndMetadata({
-            patchesDir: paths.patches,
-            filename: patchFilename,
-            newContent: diffContent,
-            updates: {
-                filesAffected: diffFilesAffected,
-                ...buildPatchSourceMetadata(config.firefox),
-            },
-            onCommitted: undefined,
-            policyGate: undefined,
-            lockOptions: {
-                waitLockSeconds: resolveWaitLockSeconds(options.waitLock),
-                command: 'resolve',
-            },
-        });
-        // Clear pendingResolution from state.json transactionally so a
-        // concurrent update to unrelated keys (another command writing buildMode
-        // or baseCommit between our load and save) is not clobbered. The updater
-        // runs inside the state-file lock with the freshest on-disk state, so
-        // only pendingResolution is affected.
-        await clearPendingResolution(projectRoot);
-        s.stop(`Updated ${patchFilename}`);
-        success('Patch updated successfully and resolution state cleared.');
-        info('Patch updated. Run "fireforge import" next to resume the queue from this point — resolve only refreshes the one broken patch, it does not continue applying the remaining patches itself.');
-        outro('Resolution complete');
-    }
-    catch (error) {
-        s.error(`Resolution failed for ${patchFilename}`);
-        logError(toError(error).message);
-        throw error;
-    }
-}
-/** Registers the resolve command on the CLI program. */
-export function registerResolve(program, { getProjectRoot, withErrorHandling }) {
-    const command = program
-        .command('resolve')
-        .description('Update a broken patch with manual fixes (then run "fireforge import" to resume the queue)')
-        .option('-y, --yes', 'Skip the interactive confirmation prompt. Use for non-interactive automation flows (CI, scripted recovery) after the manual merge is complete.');
-    addWaitLockOption(command).action(withErrorHandling(async (options) => {
-        await resolveCommand(getProjectRoot(), options);
-    }));
-}
+import { defineCommand, lockOptions, lockWaitMs } from '../cli/command.js';
+import { withEngineLock } from '../engine/index.js';
+import { loadProject } from '../project/index.js';
+import { requirePatchMode, resolvePatchFromEngine } from '../queue/index.js';
+export const resolve = defineCommand({
+    name: 'resolve',
+    summary: 'After a failed import, rewrite the failed patch from engine/',
+    description: "The patch's new body is the change engine/ now holds in the patch's files, relative to what " +
+        'the patches before it leave there. Run "fireforge import --continue" afterwards to apply the rest.',
+    group: 'Patches',
+    options: { ...lockOptions },
+    json: true,
+    run: async (ctx, _args, opts) => {
+        const project = requirePatchMode(await loadProject(ctx.cwd, ctx.env));
+        const resolution = await withEngineLock(project, { command: 'resolve', waitMs: lockWaitMs(opts.waitLock) }, () => resolvePatchFromEngine(project));
+        ctx.out.line(`Rewrote ${resolution.patch} (${resolution.files.length} file(s)).`);
+        ctx.out.line('Run "fireforge import --continue" to apply the rest of the queue.');
+        ctx.out.json({ patch: resolution.patch, files: [...resolution.files] });
+    },
+});

package/dist/src/commands/restore.js

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { arg, defineCommand, opt } from '../cli/command.js';
+import { loadProject } from '../project/index.js';
+import { requireSourceMode, restore as giveBack } from '../source/index.js';
+export const restore = defineCommand({
+    name: 'restore',
+    summary: 'Give an upstream file back: remove its override record and owned file',
+    description: 'The next materialization restores the upstream bytes.',
+    group: 'Source',
+    args: { path: arg.string('Engine path of the overridden file') },
+    options: { discard: opt.flag('Drop uncommitted edits of the owned file') },
+    json: true,
+    run: async (ctx, { path }, opts) => {
+        const project = requireSourceMode(await loadProject(ctx.cwd, ctx.env));
+        const restored = await giveBack(project, path, { discard: opts.discard });
+        ctx.out.line(restored.wasDeletion ? `${path} is no longer deleted.` : `${path} is back to upstream.`);
+        ctx.out.json({ ...restored });
+    },
+});