@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/commands/migrate.js

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { defineCommand, opt } from '../cli/command.js';
+import { step } from '../kernel/log.js';
+import { migrate as toSourceMode, upgrade, verifyOutcome } from '../mode/index.js';
+import { loadProject } from '../project/index.js';
+export const migrate = defineCommand({
+    name: 'migrate',
+    summary: 'Upgrade a project of the previous format, or convert a patch queue to source mode',
+    description: 'Without options: brings a project written by the previous FireForge to the current format, ' +
+        'in place: fireforge.json keys, override records, waivers, the merge driver, and files ' +
+        'nothing reads any more. Everything rewritten or dropped is listed; anything that needs a ' +
+        'decision stops the upgrade before a file is written. A project already current is left ' +
+        'alone. It ends by running verify.\n\n' +
+        '--to-source converts a patch-mode project to source mode: the queue is replayed onto the ' +
+        'pinned Firefox and written as owned files under src/ with an override record per changed ' +
+        'upstream file (component: the patch), and the result is proven to reproduce the tree the ' +
+        'queue replays to.\n\n' +
+        'Both need a committed tree: git is the undo.',
+    group: 'Project',
+    options: {
+        toSource: opt.flag('Convert a patch-mode project to source mode'),
+    },
+    json: true,
+    run: async (ctx, _args, opts) => {
+        if (opts.toSource) {
+            const result = await toSourceMode(await loadProject(ctx.cwd, ctx.env));
+            ctx.out.line(`${result.created.length} created, ${result.overridden.length} overridden and ` +
+                `${result.deleted.length} deleted upstream file(s) are now owned files under src/.`);
+            ctx.out.line('engine/ is no longer used and can be removed. Review and commit the result.');
+            ctx.out.json({ ...result });
+            return;
+        }
+        const result = await upgrade(ctx.cwd, ctx.env, { onProgress: step });
+        if (result.state === 'current') {
+            ctx.out.line('The project is in the current format; nothing was changed.');
+        }
+        else {
+            const list = (title, notes) => {
+                if (notes.length === 0)
+                    return;
+                ctx.out.line(`${title}:`);
+                for (const note of notes)
+                    ctx.out.line(`  ${note.key}: ${note.message}`);
+            };
+            list('Converted', result.converted);
+            list('Removed', result.removed);
+            list('For you to check or decide', result.manual);
+            if (result.deleted.length > 0) {
+                ctx.out.line(`Deleted files: ${result.deleted.join(', ')}`);
+            }
+            ctx.out.line(`${result.rewritten.length} file(s) rewritten, ${result.deleted.length} deleted.`);
+            for (const line of result.followUp)
+                ctx.out.line(`Left for you: ${line}`);
+            ctx.out.line('Review the result with "git diff" and commit it; "git checkout ." undoes it.');
+        }
+        for (const problem of result.verify.problems) {
+            const subject = problem.subject === undefined ? '' : `${problem.subject}: `;
+            ctx.out.line(`${problem.code}  ${subject}${problem.message}`);
+            if (problem.hint !== undefined)
+                ctx.out.line(`  ${problem.hint}`);
+        }
+        const outcome = verifyOutcome(result.verify);
+        if ('sound' in outcome)
+            ctx.out.line(outcome.sound);
+        ctx.out.json({
+            ...result,
+            converted: result.converted.map((note) => ({ ...note })),
+            removed: result.removed.map((note) => ({ ...note })),
+            manual: result.manual.map((note) => ({ ...note })),
+            pass: result.verify.problems.length === 0,
+        });
+        if ('failure' in outcome)
+            throw outcome.failure;
+    },
+});

package/dist/src/commands/override.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { arg, defineCommand, opt } from '../cli/command.js';
+import { pinnedPristine } from '../mode/index.js';
+import { loadProject } from '../project/index.js';
+import { override as declareOverride, requireSourceMode } from '../source/index.js';
+export const override = defineCommand({
+    name: 'override',
+    summary: 'Declare the first touch of an upstream file',
+    description: 'Writes the override record holding the upstream identity and, unless --delete, seeds the ' +
+        'owned copy under the source root (src/<path> by default; source.root in fireforge.json) ' +
+        'with the pristine bytes to edit. An existing undeclared edit is refused: move it aside, ' +
+        "declare, then reapply it. The first override also configures FireForge's merge driver in " +
+        "the repository's git config.",
+    group: 'Source',
+    args: { path: arg.string('Engine path of the upstream file, such as browser/base/jar.mn') },
+    options: {
+        delete: opt.flag('Delete the upstream file instead of editing it'),
+        component: opt.string('Component the change belongs to (default: the top directory)', {
+            valueName: 'name',
+        }),
+        classification: opt.enum(['registration', 'exception'], 'registration wires an addition in; exception is a reviewed upstream change', { default: 'registration' }),
+        adr: opt.string('Decision record approving an exception, relative to the project', {
+            valueName: 'path',
+        }),
+    },
+    json: true,
+    run: async (ctx, { path }, opts) => {
+        const project = requireSourceMode(await loadProject(ctx.cwd, ctx.env));
+        const { record, driverInstalled } = await declareOverride(project, await pinnedPristine(project), path, {
+            delete: opts.delete,
+            classification: opts.classification,
+            ...(opts.component === undefined ? {} : { component: opts.component }),
+            ...(opts.adr === undefined ? {} : { adr: opts.adr }),
+        });
+        ctx.out.line(record.kind === 'delete'
+            ? `Declared the deletion of ${path} (component ${record.component}).`
+            : `Declared ${path} (component ${record.component}); edit ${project.config.source.root}/${path}.`);
+        if (driverInstalled) {
+            ctx.out.line('Configured the merge driver (merge.fireforge.driver) in git config, so merges of owned files start from the pristine file.');
+        }
+        ctx.out.json({ path, record, driverInstalled });
+    },
+});

package/dist/src/commands/package.js

@@ -1,78 +1,49 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { Command } from 'commander';
-import { validateBrandOverride } from '../core/brand-validation.js';
-import { prepareBuildEnvironment } from '../core/build-prepare.js';
-import { getProjectPaths, loadConfig } from '../core/config.js';
-import { assertEngineExists } from '../core/engine-precondition.js';
-import { hasBuildArtifacts, machPackageCapture } from '../core/mach.js';
-import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
-import { explainMachError } from '../core/mach-error-hints.js';
-import { BuildError } from '../errors/build.js';
-import { elapsedSince } from '../utils/elapsed.js';
-import { error, info, intro, outro, verbose } from '../utils/logger.js';
-import { pickDefined } from '../utils/options.js';
-/**
- * Runs the package command to create a distribution package.
- * @param projectRoot - Root directory of the project
- * @param options - Package options
- */
-export async function packageCommand(projectRoot, options) {
-    const brandInfo = options.brand ? ` [${options.brand}]` : '';
-    intro(`FireForge Package${brandInfo}`);
-    // Load configuration
-    const config = await loadConfig(projectRoot);
-    const paths = getProjectPaths(projectRoot);
-    validateBrandOverride(config.binaryName, options.brand);
-    // Check if engine exists
-    await assertEngineExists(paths.engine);
-    const buildCheck = await hasBuildArtifacts(paths.engine);
-    assertBuildArtifacts(paths.engine, buildCheck, {
-        label: 'Package',
-        requirement: 'Packaging requires a completed build.',
-        remediation: "Run 'fireforge build' first, then rerun 'fireforge package'.",
-        requireExisting: true,
-    });
-    // Log brand info if specified
-    if (options.brand) {
-        verbose(`Packaging with brand: ${options.brand}`);
-        info(`Brand: ${options.brand}`);
-    }
-    // Shared pre-flight: branding, Furnace, mozconfig
-    await prepareBuildEnvironment(projectRoot, paths, config);
-    // Run package
-    info('Creating distribution package...');
-    info('This may take a while.\n');
-    const startTime = Date.now();
-    let result;
-    try {
-        // `machPackageCapture` streams output live and captures the tail for
-        // post-run diagnostics. An inherit-only dispatch leaves the hint
-        // translator unable to see the failure text. The captured stderr is fed
-        // through `explainMachError` below so recognised failure modes get an
-        // actionable hint prepended to the raw mach output.
-        result = await machPackageCapture(paths.engine);
-    }
-    catch (error) {
-        throw new BuildError('Package process failed to start', 'mach package', error instanceof Error ? error : undefined);
-    }
-    const timeStr = elapsedSince(startTime);
-    if (result.exitCode !== 0) {
-        error(`Packaging failed after ${timeStr}`);
-        const combinedOutput = `${result.stdout}\n${result.stderr}`;
-        const hints = explainMachError(combinedOutput);
-        const hintBlock = hints.length > 0 ? `\n\nHint:\n${hints.map((h) => `  ${h}`).join('\n')}` : '';
-        throw new BuildError(`Packaging failed with exit code ${result.exitCode}.${hintBlock}`, 'mach package');
-    }
-    info(`\nPackage created in obj-*/dist/`);
-    outro(`Packaging completed in ${timeStr}!`);
-}
-/** Registers the package command on the CLI program. */
-export function registerPackage(program, { getProjectRoot, withErrorHandling }) {
-    program
-        .command('package')
-        .description('Create distribution package')
-        .option('--brand <name>', 'Package specific brand')
-        .action(withErrorHandling(async (options) => {
-        await packageCommand(getProjectRoot(), pickDefined(options));
-    }));
-}
+import { defineCommand, lockWaitMs, opt } from '../cli/command.js';
+import { ensureBuilt, packageBrowser } from '../engine/index.js';
+import { deployComponents, withWorkspace } from '../mode/index.js';
+import { loadProject } from '../project/index.js';
+import { workspaceOptions } from './workspace.js';
+export const packageCommand = defineCommand({
+    name: 'package',
+    summary: 'Create a distribution package',
+    description: 'Packages the development build, which must match the source (--build brings it up to ' +
+        'date). --release builds and packages with the build.release recipe in its own object directory.',
+    group: 'Daily',
+    options: {
+        release: opt.flag('Build and package a release with build.release'),
+        build: opt.flag('Build first when the development build is older than the engine'),
+        out: opt.path("Where a release's outputs go (default .fireforge/release-output)"),
+        jobs: opt.integer('Parallel jobs of the release build (default build.jobs)', {
+            short: 'j',
+            min: 1,
+        }),
+        ...workspaceOptions,
+    },
+    constraints: { exclusive: [['release', 'build']], requires: { out: ['release'] } },
+    json: true,
+    run: async (ctx, _args, opts) => {
+        const project = await loadProject(ctx.cwd, ctx.env);
+        const waitMs = lockWaitMs(opts.waitLock);
+        const result = await withWorkspace(project, { command: 'package', workspace: opts.workspace, waitMs }, async (workspace) => {
+            await deployComponents(workspace, { waitMs });
+            if (!opts.release)
+                await ensureBuilt(workspace, { build: opts.build, waitMs });
+            return packageBrowser(workspace, {
+                release: opts.release,
+                ...(opts.out === undefined ? {} : { outputDir: opts.out }),
+                ...(opts.jobs === undefined ? {} : { jobs: opts.jobs }),
+                waitMs,
+            });
+        });
+        for (const output of result.outputs)
+            ctx.out.line(output);
+        if (result.outputs.length === 0)
+            ctx.out.line('Packaging produced no output file.');
+        ctx.out.json({
+            objDir: result.objDir,
+            outputs: result.outputs,
+            outputDir: result.outputDir ?? null,
+        });
+    },
+});

package/dist/src/commands/patch.js

@@ -0,0 +1,221 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { arg, defineCommand, lockOptions, lockWaitMs, opt } from '../cli/command.js';
+import { withEngineLock } from '../engine/index.js';
+import { defined } from '../kernel/errors.js';
+import { loadProject } from '../project/index.js';
+import { compactQueue, deletePatch, enginePaths, moveFiles, renamePatch, reorderPatch, requirePatchMode, retirePatch, setPatchMeta, splitPatch, stagedDependencyOf, } from '../queue/index.js';
+/** Loads the patch-mode project and runs `body` under the exclusive engine lock. */
+async function locked(ctx, command, waitLock, body) {
+    const project = requirePatchMode(await loadProject(ctx.cwd, ctx.env));
+    return withEngineLock(project, { command: `patch ${command}`, waitMs: lockWaitMs(waitLock) }, () => body(project));
+}
+function report(ctx, edit, extra = {}) {
+    for (const { from, to } of edit.renamed)
+        ctx.out.line(`Renamed ${from} -> ${to}`);
+    for (const filename of edit.created)
+        ctx.out.line(`Created ${filename}`);
+    for (const filename of edit.rewritten)
+        ctx.out.line(`Rewrote ${filename}`);
+    for (const filename of edit.removed)
+        ctx.out.line(`Removed ${filename}`);
+    const changed = edit.renamed.length + edit.created.length + edit.removed.length;
+    if (changed + edit.rewritten.length === 0)
+        ctx.out.line('Nothing changed.');
+    ctx.out.json({
+        renamed: edit.renamed.map(({ from, to }) => ({ from, to })),
+        created: [...edit.created],
+        rewritten: [...edit.rewritten],
+        removed: [...edit.removed],
+        ...extra,
+    });
+}
+const placementOptions = {
+    order: opt.integer('Place the patch at this order', { min: 1 }),
+    before: opt.string('Place the patch right before this patch', { valueName: 'patch' }),
+    after: opt.string('Place the patch right after this patch', { valueName: 'patch' }),
+};
+function placementOf(opts) {
+    if (opts.order !== undefined)
+        return { order: opts.order };
+    if (opts.before !== undefined)
+        return { before: opts.before };
+    if (opts.after !== undefined)
+        return { after: opts.after };
+    return undefined;
+}
+const rename = defineCommand({
+    name: 'rename',
+    summary: 'Rename a patch',
+    description: 'The order, body and metadata stay; the file follows the name.',
+    args: {
+        patch: arg.string('The patch (order, filename or name)'),
+        name: arg.string('The new name: lowercase words joined by hyphens, the first the category'),
+    },
+    options: { ...lockOptions },
+    json: true,
+    run: async (ctx, { patch, name }, opts) => {
+        report(ctx, await locked(ctx, 'rename', opts.waitLock, (project) => renamePatch(project, patch, name)));
+    },
+});
+const reorder = defineCommand({
+    name: 'reorder',
+    summary: 'Move a patch to another place in the apply order',
+    description: 'An occupied order is freed by moving the run of patches above it up by one. Refused when ' +
+        'the queue would then produce different content: patches that change the same lines keep ' +
+        'their relative order.',
+    args: { patch: arg.string('The patch (order, filename or name)') },
+    options: { ...placementOptions, ...lockOptions },
+    constraints: { oneOf: [['order', 'before', 'after']] },
+    json: true,
+    run: async (ctx, { patch }, opts) => {
+        const placement = defined(placementOf(opts), 'reorder is given exactly one placement');
+        report(ctx, await locked(ctx, 'reorder', opts.waitLock, (project) => reorderPatch(project, patch, placement)));
+    },
+});
+const split = defineCommand({
+    name: 'split',
+    summary: 'Move some files of a patch into a new patch',
+    description: 'The new patch goes right after the source unless placed elsewhere, and keeps its stamp and ' +
+        'tier. Staged dependencies declared on the moved files go with them. Refused when the queue ' +
+        'would then produce different content.',
+    args: {
+        patch: arg.string('The patch to split'),
+        files: arg.list('Engine files (or directories) of the patch to move', { required: true }),
+    },
+    options: {
+        name: opt.string('Name of the new patch', { required: true, valueName: 'name' }),
+        description: opt.string('What the new patch does', { short: 'd', valueName: 'text' }),
+        ...placementOptions,
+        ...lockOptions,
+    },
+    constraints: { exclusive: [['order', 'before', 'after']] },
+    json: true,
+    run: async (ctx, { patch, files }, opts) => {
+        const placement = placementOf(opts);
+        const edit = await locked(ctx, 'split', opts.waitLock, (project) => splitPatch(project, patch, {
+            files: enginePaths(project.paths.engine, ctx.cwd, files),
+            name: opts.name,
+            ...(opts.description === undefined ? {} : { description: opts.description }),
+            ...(placement === undefined ? {} : { placement }),
+        }));
+        report(ctx, edit);
+    },
+});
+const moveFilesCommand = defineCommand({
+    name: 'move-files',
+    summary: 'Move files from one patch into another',
+    description: 'Where the target already changes a moved file, the two changes are combined. A source left ' +
+        'with no files is removed. Refused when the queue would then produce different content.',
+    args: {
+        from: arg.string('The patch the files leave'),
+        to: arg.string('The patch they join'),
+        files: arg.list('Engine files (or directories) to move', { required: true }),
+    },
+    options: { ...lockOptions },
+    json: true,
+    run: async (ctx, { from, to, files }, opts) => {
+        const edit = await locked(ctx, 'move-files', opts.waitLock, (project) => moveFiles(project, from, to, enginePaths(project.paths.engine, ctx.cwd, files)));
+        report(ctx, edit);
+    },
+});
+const remove = defineCommand({
+    name: 'delete',
+    summary: 'Delete a patch',
+    description: 'Refused when another patch no longer applies without it. engine/ is not touched: the ' +
+        'files the patch changed keep their content and belong to no patch ("fireforge discard" ' +
+        'puts them back).',
+    args: { patch: arg.string('The patch (order, filename or name)') },
+    options: { ...lockOptions },
+    json: true,
+    run: async (ctx, { patch }, opts) => {
+        const removal = await locked(ctx, 'delete', opts.waitLock, (project) => deletePatch(project, patch));
+        report(ctx, removal, { files: [...removal.files] });
+    },
+});
+const retire = defineCommand({
+    name: 'retire',
+    summary: 'Delete a patch and keep its order as a retired slot',
+    description: 'Like "patch delete", but the order stays recorded in patches.json, so it is not given to ' +
+        'another patch and the gap check sees no gap.',
+    args: { patch: arg.string('The patch (order, filename or name)') },
+    options: {
+        reason: opt.string('Why, recorded with the slot', { valueName: 'text' }),
+        ...lockOptions,
+    },
+    json: true,
+    run: async (ctx, { patch }, opts) => {
+        const removal = await locked(ctx, 'retire', opts.waitLock, (project) => retirePatch(project, patch, opts.reason));
+        report(ctx, removal, { files: [...removal.files] });
+    },
+});
+const compact = defineCommand({
+    name: 'compact',
+    summary: 'Close the gaps in the queue numbering',
+    description: 'Keeps the apply order. With patchPolicy ranges, each category range is numbered from its ' +
+        'first patch; otherwise the queue is numbered from 1.',
+    options: { ...lockOptions },
+    json: true,
+    run: async (ctx, _args, opts) => {
+        report(ctx, await locked(ctx, 'compact', opts.waitLock, (project) => compactQueue(project)));
+    },
+});
+const set = defineCommand({
+    name: 'set',
+    summary: "Edit a patch's metadata",
+    description: 'Description, tier, lint waivers and staged dependencies, in one transaction; the body is ' +
+        'not touched. A waiver for a rule replaces any waiver the patch has for it; with --max ' +
+        '(and --reason) it waives a size rule only up to that measurement. A staged dependency ' +
+        '<file>:<creates> declares that <file> in this patch imports or registers <creates>, which ' +
+        'a later patch creates.',
+    args: { patch: arg.string('The patch (order, filename or name)') },
+    options: {
+        description: opt.string('What the patch does', { short: 'd', valueName: 'text' }),
+        tier: opt.enum(['branding', 'none'], 'Size tier the patch is held to'),
+        lintIgnore: opt.list('Waive this lint rule for the patch', { valueName: 'rule' }),
+        max: opt.integer('Waive the --lint-ignore size rules only up to this measurement', {
+            min: 0,
+        }),
+        reason: opt.string('Why, for the waivers and staged dependencies added', {
+            valueName: 'text',
+        }),
+        removeLintIgnore: opt.list('Drop the waiver of this rule', { valueName: 'rule' }),
+        stagedDependency: opt.list('Declare a staged dependency', { valueName: 'file:creates' }),
+        removeStagedDependency: opt.list('Drop a staged dependency', { valueName: 'file:creates' }),
+        ...lockOptions,
+    },
+    constraints: { requires: { max: ['lintIgnore', 'reason'] } },
+    json: true,
+    run: async (ctx, { patch }, opts) => {
+        const reason = opts.reason === undefined ? {} : { reason: opts.reason };
+        const result = await locked(ctx, 'set', opts.waitLock, (project) => setPatchMeta(project, patch, {
+            ...(opts.description === undefined ? {} : { description: opts.description }),
+            ...(opts.tier === undefined ? {} : { tier: opts.tier === 'none' ? null : opts.tier }),
+            lintIgnore: {
+                add: opts.lintIgnore.map((rule) => opts.max === undefined ? rule : { rule, max: opts.max, reason: opts.reason ?? '' }),
+                remove: opts.removeLintIgnore,
+            },
+            stagedDependencies: {
+                add: opts.stagedDependency.map((spec) => ({ ...stagedDependencyOf(spec), ...reason })),
+                remove: opts.removeStagedDependency.map(stagedDependencyOf),
+            },
+        }));
+        ctx.out.line(result.changed ? `Updated ${result.patch}` : `${result.patch} already says so.`);
+        const { entry } = result;
+        ctx.out.json({
+            patch: result.patch,
+            changed: result.changed,
+            description: entry.description,
+            tier: entry.tier ?? null,
+            lintIgnore: (entry.lintIgnore ?? []).map((waiver) => typeof waiver === 'string'
+                ? waiver
+                : { rule: waiver.rule, max: waiver.max, reason: waiver.reason }),
+            stagedDependencies: (entry.stagedDependencies ?? []).map((declared) => ({ ...declared })),
+        });
+    },
+});
+export const patch = defineCommand({
+    name: 'patch',
+    summary: 'Rename, reorder, split, delete and annotate patches, and move files between them',
+    group: 'Patches',
+    subcommands: [rename, reorder, split, moveFilesCommand, remove, retire, compact, set],
+});