@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,361 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { Command } from 'commander';
-import { isBrandingManagedPath } from '../core/branding.js';
-import { getProjectPaths, loadConfig } from '../core/config.js';
-import { stdioIsInteractive } from '../core/destructive.js';
-import { assertEngineGitReady } from '../core/engine-precondition.js';
-import { collectFurnaceManagedPrefixes, furnaceConfigExists, loadFurnaceConfig, } from '../core/furnace-config.js';
-import { hasChanges } from '../core/git.js';
-import { getAllDiff, getDiffForFilesAgainstHead } from '../core/git-diff.js';
-import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
-import { extractAffectedFiles } from '../core/patch-apply.js';
-import { commitExportedPatch } from '../core/patch-export.js';
-import { buildPatchQueueContext, collectNewFileCreatorsByPath, detectNewFilesInDiff, } from '../core/patch-lint.js';
-import { collectPatchRegistrationReferences } from '../core/patch-registration-refs.js';
-import { buildPatchSourceMetadata } from '../core/patch-source-metadata.js';
-import { GeneralError } from '../errors/base.js';
-import { ensureDir, pathExists } from '../utils/fs.js';
-import { info, intro, outro, spinner } from '../utils/logger.js';
-import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../utils/options.js';
-import { renderDryRunPreview } from './export-flow.js';
-import { autoFixLicenseHeaders, promptExportPatchMetadata, runPatchLint, runSupersedeAndOverlapGates, } from './export-shared.js';
-/**
- * The engine paths an export-all entry owns: its current file plus, for a
- * rename, the path it came from. Spelled once because three call sites had
- * copied the same `filter((value): value is string => !!value)` narrowing.
- * @param entry - Export entry carrying `file` and an optional `originalPath`.
- * @returns Both paths when the entry was renamed, otherwise just `file`.
- */
-function ownedPaths(entry) {
-    return [entry.file, entry.originalPath].filter((value) => !!value);
-}
-async function checkBrandingManagedFiles(paths, config) {
-    const changedFiles = await getWorkingTreeStatus(paths.engine);
-    const brandingManagedFiles = changedFiles
-        .flatMap((entry) => ownedPaths(entry))
-        .filter((file) => isBrandingManagedPath(file, config.binaryName));
-    if (brandingManagedFiles.length > 0) {
-        throw new GeneralError('Export-all refuses to capture tool-managed branding changes by default.\n\n' +
-            'Review these files with "fireforge status" first. If you intentionally want a branding patch, export the specific branding paths explicitly with "fireforge export ...".');
-    }
-}
-/**
- * Policy around Furnace-managed files in the aggregate diff.
- *
- * Default behavior refuses the export (Furnace paths belong to
- * `furnace apply`). `--exclude-furnace` flips the policy from refusal to
- * filtering: the command still runs, but the Furnace-managed paths are
- * dropped from the diff and counted in an info line so operators in
- * mixed workspaces can capture only the non-Furnace subset.
- *
- * Returns the set of Furnace-managed paths to exclude (empty when the
- * policy is "refuse" and nothing is in the working tree).
- */
-async function resolveFurnaceExclusionPolicy(paths, projectRoot, excludeFurnace) {
-    const prefixes = await collectFurnaceManagedPrefixes(projectRoot);
-    if (prefixes.size === 0)
-        return new Set();
-    // Expand collapsed `?? dir/` entries before matching against Furnace
-    // prefixes, otherwise a Furnace-introduced directory slips past the
-    // filter and later lands in the non-Furnace path list that feeds the
-    // aggregate diff, where `getDiffForFilesAgainstHead` crashes with EISDIR.
-    const rawStatus = await getWorkingTreeStatus(paths.engine);
-    const changedFiles = await expandUntrackedDirectoryEntries(paths.engine, rawStatus);
-    const furnaceManagedFiles = changedFiles
-        .flatMap((entry) => ownedPaths(entry))
-        .filter((file) => [...prefixes].some((prefix) => file.startsWith(prefix)));
-    if (furnaceManagedFiles.length === 0)
-        return new Set();
-    if (excludeFurnace) {
-        return new Set(furnaceManagedFiles);
-    }
-    throw new GeneralError('Export-all refuses to capture Furnace-managed component changes.\n\n' +
-        'These files are deployed by "fireforge furnace apply" and should be managed through the Furnace workflow. ' +
-        'Review them with "fireforge status" or "fireforge furnace status", ' +
-        'or pass --exclude-furnace to export the non-Furnace subset of the diff.');
-}
-/**
- * Refuses the export when the resulting patch would register furnace
- * component source files it does not itself carry.
- *
- * `export-all --exclude-furnace` after `furnace create --localized
- * --with-tests` otherwise produces a patch that adds
- * `toolkit/content/widgets/<tag>/*` via jar.mn / customElements.js / locale
- * jar.mn while excluding the component source files themselves, a
- * structurally broken queue that `fireforge verify` stays silent about. The
- * operator is asked to either include the component sources (skip
- * `--exclude-furnace`) or revert the furnace changes before exporting.
- *
- * The check runs against the synthesised patch body before
- * `commitExportedPatch` writes anything, so no broken patch is left on disk
- * when the refusal fires.
- */
-async function checkDanglingFurnaceRegistrations(projectRoot, diff, furnaceExcluded) {
-    if (furnaceExcluded.size === 0)
-        return;
-    if (!(await furnaceConfigExists(projectRoot)))
-        return;
-    const refs = collectPatchRegistrationReferences(diff);
-    if (refs.length === 0)
-        return;
-    const config = await loadFurnaceConfig(projectRoot);
-    // Build the set of furnace-managed component names so we can tell
-    // "registers moz-qa-panel (furnace-managed)" apart from "registers
-    // moz-button (an upstream widget this patch legitimately touches)".
-    const furnaceComponentNames = new Set([
-        ...Object.keys(config.custom),
-        ...Object.keys(config.overrides),
-        ...config.stock,
-    ]);
-    const dangling = [];
-    for (const ref of refs) {
-        if (!furnaceExcluded.has(ref.targetPath))
-            continue;
-        const tagMatch = /toolkit\/content\/widgets\/([a-z][a-z0-9-]*)\//.exec(ref.targetPath);
-        const ftlMatch = /toolkit\/locales\/en-US\/toolkit\/global\/([a-z][a-z0-9-]*)\.ftl$/.exec(ref.targetPath);
-        const component = tagMatch?.[1] ?? ftlMatch?.[1];
-        if (!component || !furnaceComponentNames.has(component))
-            continue;
-        dangling.push({ component, targetPath: ref.targetPath, source: ref.source });
-    }
-    if (dangling.length === 0)
-        return;
-    const summary = dangling
-        .map((d) => `  • ${d.component} — registered via ${d.source} → ${d.targetPath}`)
-        .join('\n');
-    throw new GeneralError('Export-all --exclude-furnace would produce a patch that registers furnace-managed components without including their source files.\n\n' +
-        `Dangling registrations:\n${summary}\n\n` +
-        'To proceed, either:\n' +
-        '  1. Drop the --exclude-furnace flag so the source files are captured alongside the registration edits.\n' +
-        '  2. Revert the registration hunks (or the whole furnace workflow) before re-running export-all — registrations belong with their components, and splitting them across separate patches is what "verify" catches post-hoc as a dangling-registration error.');
-}
-/**
- * Refuses the export when the aggregate diff would create (new-file-mode) a
- * path that some existing patch in the queue already creates. `verify`
- * detects this post-hoc via `collectNewFileCreatorsByPath`, but by the time
- * `verify` runs the operator has already landed a patch that irreversibly
- * sits atop the queue, and resolving the conflict from there requires a
- * `patch delete` or hand-surgery on `re-export --files`. Catching it here,
- * pre-write, keeps the queue clean and gives the operator a specific path
- * to narrow with `export` + explicit file scoping (which lets them drop
- * the already-claimed path without losing other edits).
- *
- * Slots in alongside the existing branding and furnace guards so the three
- * "export-all refuses" branches remain the single, symmetric fence around
- * unintended captures.
- */
-async function checkDuplicateNewFileCreations(paths, diff) {
-    if (!(await pathExists(paths.patches)))
-        return;
-    const pendingNewFiles = detectNewFilesInDiff(diff);
-    if (pendingNewFiles.size === 0)
-        return;
-    const ctx = await buildPatchQueueContext(paths.patches);
-    if (ctx.entries.length === 0)
-        return;
-    const creators = collectNewFileCreatorsByPath(ctx);
-    const conflicts = [];
-    for (const path of pendingNewFiles) {
-        const owners = creators.get(path);
-        if (owners && owners.length > 0) {
-            conflicts.push({ path, owners });
-        }
-    }
-    if (conflicts.length === 0)
-        return;
-    const conflictList = conflicts
-        .map(({ path, owners }) => `  • ${path} — already created by ${owners.join(', ')}`)
-        .join('\n');
-    throw new GeneralError('Export-all refuses to capture new-file creations that are already claimed by existing patches.\n\n' +
-        `Conflicting creations:\n${conflictList}\n\n` +
-        'Only one patch may create a given path — two creation hunks on /dev/null cannot coexist in any apply order, so this case is structurally unrecoverable rather than verify-failing. The --allow-overlap escape hatch covers cross-patch MODIFICATION overlap (which yields a queue that fails verify but still applies); it deliberately does NOT cover this case. ' +
-        'Run "fireforge export <path> [...]" with an explicit file list that omits the already-claimed path(s), or resolve the conflict via "fireforge patch delete" / "fireforge re-export --files" before retrying export-all.');
-}
-/**
- * Runs the export-all command to export all changes as a patch.
- * @param projectRoot - Root directory of the project
- * @param options - Export options
- */
-export async function exportAllCommand(projectRoot, options = {}) {
-    const isDryRun = options.dryRun === true;
-    intro(isDryRun ? 'FireForge Export All (dry run)' : 'FireForge Export All');
-    const paths = getProjectPaths(projectRoot);
-    await assertEngineGitReady(paths.engine);
-    // Check for changes
-    if (!(await hasChanges(paths.engine))) {
-        info('No changes to export');
-        outro('Nothing to export');
-        return;
-    }
-    const config = await loadConfig(projectRoot);
-    await checkBrandingManagedFiles(paths, config);
-    const furnaceExcluded = await resolveFurnaceExclusionPolicy(paths, projectRoot, options.excludeFurnace);
-    // Get the full diff. When --exclude-furnace is set and furnaceExcluded
-    // is non-empty, rescope the diff to the non-Furnace path subset so the
-    // resulting patch does not contain any Furnace-managed hunks. We use
-    // `getDiffForFilesAgainstHead` over the filtered path list rather than
-    // post-hoc string surgery on the aggregate diff, which keeps the
-    // output shape aligned with the single-file `export` command.
-    let diff;
-    // Retain the exact scope used to build the aggregate. Interactive
-    // license-header repair mutates engine files and therefore has to rebuild
-    // the diff, but it must not silently widen an --exclude-furnace export.
-    let scopedExportPaths;
-    if (furnaceExcluded.size > 0) {
-        const rawChanged = await getWorkingTreeStatus(paths.engine);
-        const allChanged = await expandUntrackedDirectoryEntries(paths.engine, rawChanged);
-        const nonFurnacePaths = [
-            ...new Set(allChanged
-                .flatMap((entry) => ownedPaths(entry))
-                .filter((file) => !furnaceExcluded.has(file))),
-        ].sort();
-        scopedExportPaths = nonFurnacePaths;
-        if (nonFurnacePaths.length === 0) {
-            info(`Excluded ${furnaceExcluded.size} furnace-managed file(s) from export; no non-Furnace changes remain.`);
-            outro('Nothing to export');
-            return;
-        }
-        diff = await getDiffForFilesAgainstHead(paths.engine, nonFurnacePaths);
-        info(`Excluded ${furnaceExcluded.size} furnace-managed file(s) from export; exporting ${nonFurnacePaths.length} remaining path(s).`);
-    }
-    else {
-        diff = await getAllDiff(paths.engine);
-    }
-    if (!diff.trim()) {
-        info('No diff content to export');
-        outro('Nothing to export');
-        return;
-    }
-    // Duplicate-creation preflight needs the diff in hand to see which paths
-    // the aggregate would newly create, so it runs here instead of alongside
-    // the branding / furnace guards that operate on the raw status list.
-    await checkDuplicateNewFileCreations(paths, diff);
-    // Dangling-furnace-registration preflight. Runs after the diff is
-    // assembled so it can inspect the exact hunks the operator is about to
-    // land, and before any write so a refusal leaves the patches directory
-    // untouched.
-    await checkDanglingFurnaceRegistrations(projectRoot, diff, furnaceExcluded);
-    // Check for non-interactive mode
-    const isInteractive = stdioIsInteractive();
-    // Auto-fix missing license headers on new files (interactive only, and
-    // report-only under --dry-run so the preview never mutates engine/)
-    const headersAdded = await autoFixLicenseHeaders(paths.engine, diff, config, isInteractive, isDryRun);
-    if (headersAdded) {
-        diff =
-            scopedExportPaths === undefined
-                ? await getAllDiff(paths.engine)
-                : await getDiffForFilesAgainstHead(paths.engine, scopedExportPaths);
-    }
-    const metadata = await promptExportPatchMetadata(options, isInteractive, 'export-all', config);
-    if (!metadata)
-        return;
-    const { patchName, selectedCategory, description } = metadata;
-    // Ensure patches directory exists. Skip during a dry-run so the command
-    // is purely read-only. `--dry-run` callers should be safe to invoke
-    // against a project that has never exported a patch without leaving the
-    // empty `patches/` directory behind.
-    if (!isDryRun) {
-        await ensureDir(paths.patches);
-    }
-    const s = spinner(isDryRun ? 'Planning export-all...' : 'Exporting all changes...');
-    try {
-        // Extract affected files from diff
-        const filesAffected = extractAffectedFiles(diff);
-        const patchQueueCtx = (await pathExists(paths.patches))
-            ? await buildPatchQueueContext(paths.patches)
-            : undefined;
-        await runPatchLint({
-            engineDir: paths.engine,
-            filesAffected,
-            diffContent: diff,
-            config,
-            skipLint: options.skipLint,
-            patchQueueCtx,
-        });
-        // Dry-run: enumerate filename, metadata, and supersede coverage without
-        // writing. Mirrors `fireforge export --dry-run` so the same preview
-        // surface is available for both targeted and aggregate exports. Runs
-        // after lint so the operator sees the same lint output they would on
-        // a real run. It runs before the supersede confirmation prompt because
-        // confirming a dry-run is meaningless.
-        if (isDryRun) {
-            s.stop('Plan ready');
-            await renderDryRunPreview({
-                patchesDir: paths.patches,
-                category: selectedCategory,
-                name: patchName,
-                description,
-                filesAffected,
-                ...buildPatchSourceMetadata(config.firefox),
-                explicitSupersede: options.supersede === true,
-                allowOverlap: options.allowOverlap === true,
-                config,
-                forceUnsafe: options.forceUnsafe === true,
-            });
-            outro('Dry run complete — no changes made');
-            return;
-        }
-        const shouldProceedPastGates = await runSupersedeAndOverlapGates({
-            patchesDir: paths.patches,
-            filesAffected,
-            supersede: options.supersede,
-            allowOverlap: options.allowOverlap === true,
-            isInteractive,
-            s,
-        });
-        if (!shouldProceedPastGates)
-            return;
-        // Get Firefox version for metadata
-        const { patchFilename, superseded } = await commitExportedPatch({
-            patchesDir: paths.patches,
-            category: selectedCategory,
-            name: patchName,
-            description,
-            diff,
-            filesAffected,
-            ...buildPatchSourceMetadata(config.firefox),
-            config,
-            policyCommand: 'export-all',
-            forceUnsafe: options.forceUnsafe === true,
-            lockOptions: {
-                waitLockSeconds: resolveWaitLockSeconds(options.waitLock),
-                command: 'export-all',
-            },
-        });
-        for (const oldPatch of superseded) {
-            info(`Superseded: ${oldPatch.filename}`);
-        }
-        s.stop(`Exported to ${patchFilename}`);
-        info(`\nPatch saved to: patches/${patchFilename}`);
-        if (filesAffected.length > 0) {
-            info(`Files affected: ${filesAffected.length}`);
-        }
-        outro('Export complete');
-    }
-    catch (error) {
-        s.error('Export failed');
-        throw error;
-    }
-}
-/** Registers the export-all command on the CLI program. */
-export function registerExportAll(program, { getProjectRoot, withErrorHandling }) {
-    const command = program
-        .command('export-all')
-        .description('Export all changes as a patch')
-        .option('--name <name>', 'Name for the patch')
-        .option('-c, --category <category>', 'Patch category')
-        .option('-d, --description <desc>', 'Description of the patch')
-        .option('--supersede', 'Allow superseding multiple existing patches')
-        .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
-        .option('--exclude-furnace', 'Export the non-Furnace subset of the aggregate diff instead of refusing when Furnace-managed files are modified. Furnace-managed files are still deployed by "fireforge furnace apply"; this flag only changes whether export-all aborts or filters in their presence.')
-        .option('--allow-overlap', 'Acknowledge cross-patch ownership overlap with non-superseded patches (the resulting queue fails verify). Does not bypass the new-file creation guard — two patches creating the same path is structurally unrecoverable, so that case still refuses regardless of this flag.')
-        .option('--dry-run', 'Print the export-all plan (filename, metadata, files affected, supersede preview) without writing anything to patches/. Lint still runs so the operator sees the same lint output a real run would produce.')
-        .option('--force-unsafe', 'Bypass force-mode patchPolicy refusals');
-    addWaitLockOption(command).action(withErrorHandling(async (options) => {
-        const { category, ...rest } = options;
-        await exportAllCommand(getProjectRoot(), {
-            ...pickDefined(rest),
-            ...(category !== undefined ? { category } : {}),
-        });
-    }));
-}

package/dist/src/commands/export-flow.d.ts

@@ -1,124 +0,0 @@
-/**
- * Planning + dry-run + placement helpers extracted from `export.ts`.
- *
- * These functions are pure or narrowly-scoped async helpers that compose
- * into `exportCommand`. Splitting them out keeps `export.ts` under the
- * per-file / per-function line budgets and makes each step individually
- * testable without dragging the whole command harness along for the ride.
- */
-import { type ConflictReport } from '../core/destructive.js';
-import { type PatchRenameEntry } from '../core/patch-manifest.js';
-import type { ExportOptions, PatchCategory, PatchMetadata } from '../types/commands/index.js';
-import type { FireForgeConfig } from '../types/config.js';
-/**
- * Shape for the rename map computed when a placement flag forces existing
- * patches to move out of the new slot. Keys are current filenames.
- */
-export interface PlacementPlan {
-    insertionOrder: number;
-    newFilename: string;
-    renameMap: Map<string, PatchRenameEntry>;
-}
-/**
- * Structural equality for placement plans. Used by placement-mode export
- * and `patch split` to verify the queue did not change between the
- * confirmed preview and the under-lock commit.
- */
-export declare function placementPlansEqual(left: PlacementPlan, right: PlacementPlan): boolean;
-/**
- * Computes the shift map that moves existing patches out of the requested
- * slot to make room for a new patch at `requestedOrder`.
- */
-export declare function computePlacementPlan(manifestPatches: PatchMetadata[], newPatchCategory: PatchCategory, newPatchName: string, requestedOrder: number): PlacementPlan;
-/**
- * Computes an exact sparse placement plan for `--order <N>`. Unlike
- * positional insertion, this never renumbers existing patches: the order
- * must be unused, and policy validation decides whether the requested
- * category/order is allowed.
- */
-export declare function computeExactPlacementPlan(manifestPatches: PatchMetadata[], newPatchCategory: PatchCategory, newPatchName: string, requestedOrder: number): PlacementPlan;
-/**
- * Resolves a placement plan from CLI flags against the current manifest.
- * When `config` is provided, positional plans (`--before`/`--after`) are
- * refused up front if their renumber would touch a reserved range, giving
- * one error for the whole shift instead of per-patch policy findings. The
- * exact `--order` branch never renames, so it bypasses that gate.
- */
-export declare function resolvePlacementPlan(patchesDir: string, options: ExportOptions, category: PatchCategory, name: string, config?: FireForgeConfig): Promise<PlacementPlan>;
-/**
- * Projects the placement through cross-patch lint to detect forward-imports
- * the renumber would introduce, or that the new patch itself would
- * introduce by landing earlier than one of its dependencies. Returns null
- * when the projection is clean.
- */
-export declare function projectPlacementForLint(patchesDir: string, plan: PlacementPlan, diff: string, config?: FireForgeConfig): Promise<ConflictReport | null>;
-/**
- * Builds the change-summary lines printed by the placement confirmation.
- */
-export declare function placementSummary(plan: PlacementPlan): string[];
-/**
- * Writes a placement-mode export under the patch directory lock after
- * re-resolving the plan against the current queue state. If the queue has
- * changed since the user confirmed the preview, the command aborts instead
- * of silently applying a different renumber than the one that was shown.
- */
-export interface CommitPlacementExportInput {
-    patchesDir: string;
-    options: ExportOptions;
-    category: PatchCategory;
-    name: string;
-    diff: string;
-    metadata: PatchMetadata;
-    expectedPlan: PlacementPlan;
-    unsafeOverride?: boolean;
-    /** Project config, used only when opt-in patchPolicy is present. */
-    config?: FireForgeConfig;
-    /** Whether --force-unsafe was supplied by the mutating command. */
-    forceUnsafe?: boolean;
-    /**
-     * Optional post-commit hook that runs inside the patch directory lock,
-     * after the mutation has succeeded but before the lock is released.
-     * Intended for the caller's history-log append so the audit record
-     * lands atomically with the mutation. A crash between mutation and
-     * hook leaves no room for another process's history record to sneak
-     * in first.
-     *
-     * Failures in the hook are warned but never re-thrown: by the time it
-     * runs, the mutation is already committed, and there is nothing to
-     * roll back. History is advisory.
-     */
-    onCommitted?: (plan: PlacementPlan) => Promise<void>;
-}
-/**
- * Commits a previously-confirmed placement export under the patch
- * directory lock. Re-resolves the placement plan against the current
- * queue and aborts if anything changed since the preview so the command
- * never applies a silently different rename set than the user saw.
- */
-export declare function commitPlacementExport(input: CommitPlacementExportInput): Promise<PlacementPlan>;
-export interface DryRunPreviewInput {
-    patchesDir: string;
-    category: PatchCategory;
-    name: string;
-    description: string;
-    filesAffected: string[];
-    sourceEsrVersion: string;
-    sourceProduct?: FireForgeConfig['firefox']['product'];
-    sourceVersion?: string;
-    explicitSupersede: boolean;
-    allowOverlap: boolean;
-    /** Optional `PatchMetadata.tier` opt-in carried from the CLI. */
-    tier?: 'branding';
-    /** Optional `PatchMetadata.lintIgnore` carried from the CLI. */
-    lintIgnore?: string[];
-    /** Project config, used only when opt-in patchPolicy is present. */
-    config?: FireForgeConfig;
-    /** Whether --force-unsafe was supplied by the mutating command. */
-    forceUnsafe?: boolean;
-}
-/**
- * Renders the plain (non-placement) dry-run preview: calls planExport,
- * prints the allocated filename + metadata, and with supersede enumerates
- * the per-patch coverage detail that was opaque before this refactor.
- */
-export declare function renderDryRunPreview(input: DryRunPreviewInput): Promise<void>;