@hominis/fireforge 0.30.1 → 0.31.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.31.0
+
+- Made `patch compact` range-aware: with `patchPolicy.ranges` configured, each category range compacts independently (anchored at its first occupied ordinal, treating reserved orders as non-gaps), so a mid-range gap under `allowGaps: false` can finally be closed without projecting patches across category boundaries. Reserved-range patches and out-of-range strays are left in place with a warning. Without ranges the historical whole-queue renumber from 1 is unchanged.
+- Rewrote `stagedDependencies.forwardImports[].owner` references during every patch renumber (compact, reorder, placement export, rename) and in reorder's dry-run projection, so staged-dependency declarations survive renumbering instead of dangling and surfacing pre-existing forward imports as new errors. `patch delete` now warns when other patches still name the deleted patch as an owner.
+- Added `fireforge patch split <source> --files <paths...> --name <name>` to move files out of a patch into a brand-new patch as one transaction: worktree-derived shrink of the source, new-patch creation with `--order`/`--before`/`--after` placement (default: after the source), and staged-dependency owner rewrites in dependent patches — validated against the final projection only, with dry-run support and reverse-order rollback. `patch move-files` now points at it for the move-to-new-patch case.
+- Scoped plain `re-export --scan` to the patch's exact directory footprint: git pathspecs recurse, so a claimed file in a shallow directory used to sweep every unmanaged file in the subtree into the scan candidates of whichever patch was exported first. Deeper paths now require an explicit `--scan-file` / `--scan-files` assignment; the broad-scan confirmation guard is unchanged.
+- Resolved imports of patch-owned modules to their real sources in the per-patch `checkJs` pass (unique-basename matching for `chrome://`/`resource://` specifiers, with a `.mjs` → `.sys.mjs` fallback), so JSDoc `value is …` type-guard predicates and `@template` generics survive module boundaries instead of degrading to `any`. Unknown or ambiguous specifiers keep the loose ambient-wildcard typing. Note: previously invisible cross-module type errors in patch-owned modules may now surface.
+- Added `ChromeUtils.getClassName`, `ChromeUtils.defineLazyGetter`, and the `Localization` constructor to the shipped Firefox-globals typecheck shim, so per-patch lint accepts these stable chrome globals without local casts. Projects can still extend the ambient set via `patchLint.checkJsExtraShim` / `typecheck.extraShim`.
+- Fixed the exported-method JSDoc `@param` extractor to scan balanced braces, so inline object types containing nested generics (e.g. `@param {{ id: string, args?: Record<string, string | number | boolean> }} message`) no longer fail `jsdoc-class-method-param-mismatch`; optional `[name]` and defaulted `[name=x]` forms now parse too.
+- Rewrote the `observer-topic-naming` check to parse balanced multi-line call sites and inspect the actual topic argument (the second) instead of the first string literal on the line, and added a known-Firefox-topics allowlist (`idle-daily`, the `quit-application` family, lifecycle and `http-on-*` topics) so simulating upstream notifications in tests is never flagged. Constant-named topics remain exempt.
+- Taught `fireforge test` to classify harness runs from their output instead of trusting exit codes or summary lines: recognized harness-crash shapes (macOS mozlog resource-monitor/psutil startup tracebacks, pre-test no-output hangs that still print `Passed: 0`, and post-green "Application shut down (without crashing) in the middle of a test!" re-entries after a focus stall) are retried with a bounded budget (`--harness-retries <n>`, default 2), and a zero-exit run with no `TEST-START` now fails instead of passing silently.
+- Sharded multi-path `fireforge test` invocations into sequential single-file harness runs with per-shard retries, per-shard diagnosis, and an aggregate PASS/FAIL/CRASH summary, avoiding the cross-file profile/pref bleed that destabilized later files in combined runs. `--no-shard` restores the single combined invocation.
+- Added `fireforge test --perf-samples <path>`, which publishes the resolved artifact path to the harness process as `<BINARYNAME>_PERF_SAMPLE_JSON` so downstream perf-budget checkers no longer maintain their own env contract.
+- Fixed named `furnace deploy <component>` to run the same pipeline as deploy-all, so renaming or deleting a component file now prunes the stale engine copy, its `jar.mn` line, and (for a removed main module) the `customElements.js` registration, instead of leaving orphans a later re-export would capture. Unchanged components now skip instead of force-reapplying, and `furnace validate` flags engine-side orphans (`orphaned-engine-file`) left by pre-0.31.0 deploys.
+- Added shared CSS fragments for Furnace widgets: a `/* @fireforge-include <fragment>.css */` directive in a widget stylesheet expands the named `components/shared/` fragment into the deployed copy (fenced, idempotent), keeping the workspace single-sourced across shadow-DOM-isolated widgets. Fragment edits surface as ordinary component drift and redeploy refreshes every consumer; `furnace validate` reports `missing-fragment` and `stale-fragment-expansion`.
+- Added automatic jsconfig `paths` maintenance for multi-file components: with `furnace.json#typecheckJsconfig` set, deploy and sync keep `compilerOptions.paths` entries mapping each registered module's `chrome://global/content/elements/<file>.mjs` URL to its workspace source (no `baseUrl` needed), pruning entries for removed helpers and preserving all hand-written configuration; `furnace validate` reports drift as `jsconfig-paths-drift`.
+- Fixed `token add` double-prefixing bare names that already start with the configured `tokenPrefix` text; such names are now treated as fully qualified with an informational note.
+- Added `token add --create-category`, which declares the missing category banner inside the `:root` block and inserts the token in the same single write; the "Category not found" error now advertises the flag.
+- Added two static release gates: `npm run deadcode:check` (knip, with a `knip.json` tuned to the project's entry points) fails on unused exports/files/dependencies, and `npm run cycles:check` (dpdm) fails on circular imports. Both run in `release:check` and the pre-push hook.
+- Internalized 45 exports that had no consumers outside their defining module, and untangled the seven type-only import cycles (`BuildBaseline`, `RegisterResult`, `ResolvedTestStyle`, and `LintCommandOptions` moved to leaf/type modules) so the cycle gate starts from zero.
+- Refactored the twelve functions with cyclomatic complexity above 30 (worst: `exportCommand` at 48) into focused helpers — behavior-preserving statement moves, verified by the existing suites — and now enforce `complexity: ["error", 30]` via ESLint. The long-standing `max-lines-per-function` suppression on `exportCommand` is gone with the split.
+- Deduplicated four copied sequences: the patch-subcommand preamble (seven commands now share `requirePatchQueue`/`requirePatchTarget`), the changed-since-baseline collector (`build-audit`/`build-prepare`/`test-stale-check` share `collectChangedEnginePaths`), the export supersede+overlap gate (`export`/`export-all` share `runSupersedeAndOverlapGates`), and two same-file clones in `token-dark-mode.ts` and `config-validate-patch-policy.ts`.
+- Restricted `process.exit()` to `bin/fireforge.ts` via lint (`no-restricted-properties`), turning the previously comment-enforced invariant into a build failure.
+- Bumped the TypeScript `target`/`lib` from ES2022 to ES2023 (Node ≥ 22.22.1 fully implements it) and dropped the redundant `@typescript-eslint/eslint-plugin` / `@typescript-eslint/parser` devDependencies already provided by the `typescript-eslint` meta-package.
+
 ## 0.30.0
 
 - Added safe repo-local per-patch lint result caching for `lint --per-patch`, plus `--no-cache` and `lint cache clear` escape hatches while preserving release-gate severity accounting and queue-wide checks. Warm cache hits now skip per-patch diff generation as well as lint rule execution, guarded by patch, config, engine content, queue ownership, and engine HEAD inputs.

package/README.md

@@ -82,6 +82,19 @@ assignment before refreshing the patch. For release whitespace checks, use
 `npm run whitespace:check`; it still checks source diffs while excluding generated
 `patches/*.patch` diff syntax.
 
+Queue maintenance lives under `fireforge patch`: `patch compact` closes ordinal gaps
+(range-aware when `patchPolicy.ranges` is configured), `patch reorder` moves a patch, and
+`patch split <source> --files <paths...> --name <name>` carves files out of a patch into a
+new one as a single transaction — including staged-dependency owner rewrites — with
+`--dry-run` support.
+
+`fireforge test` runs multiple test paths as sequential per-file shards by default
+(`--no-shard` restores one combined invocation), retries recognized harness crashes up to
+`--harness-retries <n>` times (default 2), and can publish a perf-sample artifact path to
+the harness via `--perf-samples <path>` (exported as `<BINARYNAME>_PERF_SAMPLE_JSON`).
+Design tokens are managed with `fireforge token add`; pass `--create-category` to declare a
+new category banner and insert the token in one step.
+
 ## Rebasing Firefox Source
 
 When Mozilla publishes a new Firefox source release you need to update the configured version/product, download the new source code and reapply the patches:
@@ -109,6 +122,15 @@ npx fireforge furnace preview
 
 Use `fireforge furnace --help` for the full set of component commands.
 
+Cross-widget CSS can be single-sourced as shared fragments: place the fragment in
+`components/shared/` and reference it from a widget stylesheet with a
+`/* @fireforge-include <fragment>.css */` comment — deploy expands it into the deployed
+copy only, and editing the fragment surfaces as component drift until the next deploy.
+For typed cross-module imports of multi-file components, set
+`furnace.json#typecheckJsconfig` to a consumer-owned jsconfig and deploy will maintain
+`compilerOptions.paths` entries mapping each deployed
+`chrome://global/content/elements/<file>.mjs` URL to its workspace source.
+
 ## Roadmap
 
 - **Docker builds** Reproducible builds using Docker containers.

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

@@ -5,7 +5,7 @@ import { hasChanges, isGitRepository } 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, findAllPatchesForFiles } from '../core/patch-export.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';
@@ -14,7 +14,7 @@ import { ensureDir, pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { renderDryRunPreview } from './export-flow.js';
-import { autoFixLicenseHeaders, confirmSupersedePatches, guardOwnershipOverlap, promptExportPatchMetadata, runPatchLint, } from './export-shared.js';
+import { autoFixLicenseHeaders, promptExportPatchMetadata, runPatchLint, runSupersedeAndOverlapGates, } from './export-shared.js';
 async function checkBrandingManagedFiles(paths, config) {
     const changedFiles = await getWorkingTreeStatus(paths.engine);
     const brandingManagedFiles = changedFiles
@@ -272,25 +272,15 @@ export async function exportAllCommand(projectRoot, options = {}) {
             outro('Dry run complete — no changes made');
             return;
         }
-        // Check how many existing patches would be superseded
-        const shouldProceed = await confirmSupersedePatches(paths.patches, filesAffected, options.supersede, isInteractive, s);
-        if (!shouldProceed)
-            return;
-        // Overlap gate — see the matching comment in `export.ts`. The same
-        // cross-patch ownership problem applies to `export-all` because a
-        // mixed aggregate diff often touches shared files like manifest
-        // fragments that other patches already claim.
-        const willSupersede = await findAllPatchesForFiles(paths.patches, filesAffected);
-        const supersedingFilenames = new Set(willSupersede.map((p) => p.filename));
-        const shouldProceedPastOverlap = await guardOwnershipOverlap({
+        const shouldProceedPastGates = await runSupersedeAndOverlapGates({
             patchesDir: paths.patches,
             filesAffected,
-            supersedingFilenames,
+            supersede: options.supersede,
             allowOverlap: options.allowOverlap === true,
             isInteractive,
             s,
         });
-        if (!shouldProceedPastOverlap)
+        if (!shouldProceedPastGates)
             return;
         // Get Firefox version for metadata
         const { patchFilename, superseded } = await commitExportedPatch({

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

@@ -19,6 +19,12 @@ export interface PlacementPlan {
     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`.

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

@@ -33,7 +33,12 @@ function prefixWidthForPatches(manifestPatches, requestedOrder) {
 function getSortedRenameEntries(renameMap) {
     return Array.from(renameMap.entries()).sort((a, b) => a[1].newOrder - b[1].newOrder);
 }
-function placementPlansEqual(left, right) {
+/**
+ * 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 function placementPlansEqual(left, right) {
     if (left.insertionOrder !== right.insertionOrder || left.newFilename !== right.newFilename) {
         return false;
     }

package/dist/src/commands/export-placement-gate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Placement-flag gating for `fireforge export`, split out of `export.ts`
+ * to keep the command body inside the per-function and per-file line
+ * budgets. `gatePlacementPlan` owns every policy/confirmation decision a
+ * placement export makes before the locked commit in `export.ts` runs.
+ */
+import type { ExportOptions, PatchMetadata } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+import type { SpinnerHandle } from '../utils/logger.js';
+import { type PlacementPlan } from './export-flow.js';
+/**
+ * Spreadable optional metadata (`tier`, `lintIgnore`) derived from the
+ * export flags. Every manifest-row construction site in this command
+ * shares this shape; with exactOptionalPropertyTypes the keys must be
+ * omitted entirely (not set to undefined) when the flags are absent.
+ */
+export declare function patchMetadataExtras(options: ExportOptions): Partial<Pick<PatchMetadata, 'tier' | 'lintIgnore'>>;
+/**
+ * Resolves and gates the placement plan when any placement flag
+ * (`--order`/`--before`/`--after`) was given: rejects the `--supersede`
+ * combination, enforces reserved ranges and patch policy against the
+ * projected manifest, and routes destructive renumbers (or dry-runs)
+ * through `confirmDestructive`. Returns the plan to commit, or `'stop'`
+ * when the command should end here (dry-run rendered or operator
+ * cancelled — the corresponding outro has already been printed).
+ */
+export declare function gatePlacementPlan(args: {
+    patchesDir: string;
+    options: ExportOptions;
+    selectedCategory: string;
+    patchName: string;
+    description: string;
+    filesAffected: string[];
+    diff: string;
+    config: FireForgeConfig;
+    isDryRun: boolean;
+    s: SpinnerHandle;
+}): Promise<PlacementPlan | 'stop'>;

package/dist/src/commands/export-placement-gate.js

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Placement-flag gating for `fireforge export`, split out of `export.ts`
+ * to keep the command body inside the per-function and per-file line
+ * budgets. `gatePlacementPlan` owns every policy/confirmation decision a
+ * placement export makes before the locked commit in `export.ts` runs.
+ */
+import { confirmDestructive } from '../core/destructive.js';
+import { loadPatchesManifest } from '../core/patch-manifest.js';
+import { applyRenameMapToManifest, buildProjectedManifest, enforcePatchPolicy, } from '../core/patch-policy.js';
+import { buildPatchSourceMetadata } from '../core/patch-source-metadata.js';
+import { InvalidArgumentError } from '../errors/base.js';
+import { outro } from '../utils/logger.js';
+import { placementSummary, projectPlacementForLint, resolvePlacementPlan, } from './export-flow.js';
+import { assertPlacementPreservesReservedRanges } from './export-placement-policy.js';
+/**
+ * Spreadable optional metadata (`tier`, `lintIgnore`) derived from the
+ * export flags. Every manifest-row construction site in this command
+ * shares this shape; with exactOptionalPropertyTypes the keys must be
+ * omitted entirely (not set to undefined) when the flags are absent.
+ */
+export function patchMetadataExtras(options) {
+    return {
+        ...(options.tier !== undefined ? { tier: options.tier } : {}),
+        ...(options.lintIgnore !== undefined && options.lintIgnore.length > 0
+            ? { lintIgnore: options.lintIgnore }
+            : {}),
+    };
+}
+/**
+ * Resolves and gates the placement plan when any placement flag
+ * (`--order`/`--before`/`--after`) was given: rejects the `--supersede`
+ * combination, enforces reserved ranges and patch policy against the
+ * projected manifest, and routes destructive renumbers (or dry-runs)
+ * through `confirmDestructive`. Returns the plan to commit, or `'stop'`
+ * when the command should end here (dry-run rendered or operator
+ * cancelled — the corresponding outro has already been printed).
+ */
+export async function gatePlacementPlan(args) {
+    const { patchesDir, options, selectedCategory, patchName, description, filesAffected, diff, config, isDryRun, s, } = args;
+    if (options.supersede) {
+        throw new InvalidArgumentError('Placement flags (--order/--before/--after) cannot be combined with --supersede.', 'export placement');
+    }
+    const placementPlan = await resolvePlacementPlan(patchesDir, options, selectedCategory, patchName);
+    const currentManifest = await loadPatchesManifest(patchesDir);
+    if (currentManifest !== null) {
+        assertPlacementPreservesReservedRanges(placementPlan, currentManifest.patches, config, selectedCategory);
+    }
+    const conflicts = await projectPlacementForLint(patchesDir, placementPlan, diff);
+    const renamed = currentManifest !== null
+        ? applyRenameMapToManifest(currentManifest, placementPlan.renameMap)
+        : buildProjectedManifest(null, []);
+    enforcePatchPolicy({
+        config,
+        manifest: buildProjectedManifest(renamed, [
+            ...renamed.patches,
+            {
+                filename: placementPlan.newFilename,
+                order: placementPlan.insertionOrder,
+                category: selectedCategory,
+                name: patchName,
+                description,
+                createdAt: new Date().toISOString(),
+                ...buildPatchSourceMetadata(config.firefox),
+                filesAffected,
+                ...patchMetadataExtras(options),
+            },
+        ]),
+        command: 'export',
+        forceUnsafe: options.forceUnsafe === true,
+    });
+    const summary = placementSummary(placementPlan);
+    const renameCount = placementPlan.renameMap.size;
+    // Route through confirmDestructive when the operation is destructive
+    // enough to warrant a prompt (more than one rename) OR when the user
+    // asked for a dry-run. The dry-run branch must always print the
+    // placement summary — previously, single-rename/no-rename dry-runs
+    // exited silently with no filename or projected layout.
+    if (renameCount > 1 || isDryRun) {
+        s.stop();
+        const decision = await confirmDestructive({
+            operation: 'export-order',
+            title: `Export with placement at order ${placementPlan.insertionOrder}`,
+            summary,
+            yes: options.yes === true,
+            dryRun: isDryRun,
+            unsafeOverride: options.forceUnsafe === true,
+            conflicts,
+        });
+        if (decision === 'dry-run') {
+            outro('Dry run complete — no changes made');
+            return 'stop';
+        }
+        if (decision === 'cancelled') {
+            outro('Export cancelled');
+            return 'stop';
+        }
+    }
+    else if (conflicts && options.forceUnsafe !== true) {
+        s.stop();
+        throw new InvalidArgumentError(`Refusing to run export: ${conflicts.reason}. Pass --force-unsafe to override.`, '--force-unsafe');
+    }
+    return placementPlan;
+}
+//# sourceMappingURL=export-placement-gate.js.map

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

@@ -94,3 +94,31 @@ export declare function guardOwnershipOverlap(args: {
     isInteractive: boolean;
     s: SpinnerHandle;
 }): Promise<boolean>;
+/**
+ * Runs the two pre-commit gates shared by `export` and `export-all` in
+ * order: the supersede confirmation, then the cross-patch ownership
+ * overlap guard. The overlap guard receives the filenames of the patches
+ * the export would fully supersede so it does not flag a file claimed by
+ * a patch that is about to be removed (pre-0.16.0 `export` only caught
+ * FULL-coverage supersedes, so a second export targeting a shared file
+ * like `browser/themes/shared/jar.inc.mn` created a queue where two
+ * patches both claimed the file and `verify` failed immediately).
+ *
+ * @param args - Gate inputs shared by both export commands
+ * @param args.patchesDir - Absolute path of the patches directory
+ * @param args.filesAffected - Engine-relative files the export claims
+ * @param args.supersede - The command's `--supersede` flag
+ * @param args.allowOverlap - The command's `--allow-overlap` flag
+ * @param args.isInteractive - Whether prompting the operator is possible
+ * @param args.s - Active spinner, stopped before any prompt
+ * @returns `true` when both gates passed; `false` when the operator
+ *   declined (the caller returns without committing)
+ */
+export declare function runSupersedeAndOverlapGates(args: {
+    patchesDir: string;
+    filesAffected: string[];
+    supersede: boolean | undefined;
+    allowOverlap: boolean;
+    isInteractive: boolean;
+    s: SpinnerHandle;
+}): Promise<boolean>;

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

@@ -315,4 +315,40 @@ export async function guardOwnershipOverlap(args) {
     }
     return true;
 }
+/**
+ * Runs the two pre-commit gates shared by `export` and `export-all` in
+ * order: the supersede confirmation, then the cross-patch ownership
+ * overlap guard. The overlap guard receives the filenames of the patches
+ * the export would fully supersede so it does not flag a file claimed by
+ * a patch that is about to be removed (pre-0.16.0 `export` only caught
+ * FULL-coverage supersedes, so a second export targeting a shared file
+ * like `browser/themes/shared/jar.inc.mn` created a queue where two
+ * patches both claimed the file and `verify` failed immediately).
+ *
+ * @param args - Gate inputs shared by both export commands
+ * @param args.patchesDir - Absolute path of the patches directory
+ * @param args.filesAffected - Engine-relative files the export claims
+ * @param args.supersede - The command's `--supersede` flag
+ * @param args.allowOverlap - The command's `--allow-overlap` flag
+ * @param args.isInteractive - Whether prompting the operator is possible
+ * @param args.s - Active spinner, stopped before any prompt
+ * @returns `true` when both gates passed; `false` when the operator
+ *   declined (the caller returns without committing)
+ */
+export async function runSupersedeAndOverlapGates(args) {
+    const { patchesDir, filesAffected, supersede, allowOverlap, isInteractive, s } = args;
+    const shouldProceed = await confirmSupersedePatches(patchesDir, filesAffected, supersede, isInteractive, s);
+    if (!shouldProceed)
+        return false;
+    const willSupersede = await findAllPatchesForFiles(patchesDir, filesAffected);
+    const supersedingFilenames = new Set(willSupersede.map((p) => p.filename));
+    return guardOwnershipOverlap({
+        patchesDir,
+        filesAffected,
+        supersedingFilenames,
+        allowOverlap,
+        isInteractive,
+        s,
+    });
+}
 //# sourceMappingURL=export-shared.js.map

package/dist/src/commands/export.js

@@ -3,16 +3,14 @@ import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { Option } from 'commander';
 import { getProjectPaths, loadConfig } from '../core/config.js';
-import { appendHistory, confirmDestructive } from '../core/destructive.js';
+import { appendHistory } from '../core/destructive.js';
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { getStatusWithCodes, isGitRepository } from '../core/git.js';
 import { generateBinaryFilePatch, generateFullFilePatch } from '../core/git-diff.js';
 import { isBinaryFile } from '../core/git-file-ops.js';
 import { getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, } from '../core/git-status.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
-import { commitExportedPatch, findAllPatchesForFiles } from '../core/patch-export.js';
-import { loadPatchesManifest } from '../core/patch-manifest.js';
-import { applyRenameMapToManifest, buildProjectedManifest, enforcePatchPolicy, } from '../core/patch-policy.js';
+import { commitExportedPatch } from '../core/patch-export.js';
 import { buildPatchSourceMetadata } from '../core/patch-source-metadata.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
@@ -21,9 +19,9 @@ import { info, intro, outro, spinner, verbose, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { parsePositiveIntegerFlag } from '../utils/validation.js';
-import { commitPlacementExport, placementSummary, projectPlacementForLint, renderDryRunPreview, resolvePlacementPlan, } from './export-flow.js';
-import { assertPlacementPreservesReservedRanges } from './export-placement-policy.js';
-import { autoFixLicenseHeaders, confirmSupersedePatches, guardOwnershipOverlap, promptExportPatchMetadata, runPatchLint, } from './export-shared.js';
+import { commitPlacementExport, renderDryRunPreview } from './export-flow.js';
+import { gatePlacementPlan, patchMetadataExtras } from './export-placement-gate.js';
+import { autoFixLicenseHeaders, promptExportPatchMetadata, runPatchLint, runSupersedeAndOverlapGates, } from './export-shared.js';
 async function collectExportFiles(paths, files) {
     const collectedFiles = new Set();
     let fileStatuses;
@@ -100,20 +98,14 @@ async function generatePatchDiff(engineDir, allFiles) {
     return diffs.join('\n');
 }
 /**
- * Runs the export command to export file changes as a patch.
- * Accepts one or more file/directory paths and bundles them into a single patch.
- * @param projectRoot - Root directory of the project
- * @param files - File or directory paths to export (relative to engine/)
- * @param options - Export options
+ * Validation + diff phase of `exportCommand`: checks flag combinations and
+ * the engine checkout, collects the export file set (honouring
+ * `--exclude-furnace`), generates the diff, auto-fixes license headers,
+ * and prompts for patch metadata. Returns `null` when the operator
+ * cancelled the metadata prompt (the command ends silently, matching the
+ * prompt's own cancel handling).
  */
-// The command body is intentionally linear: validation → diff → placement
-// gate → dry-run/placement/default write. Splitting it further would
-// spread the error-handling (spinner.error, try/catch) across multiple
-// helpers and hurt readability more than it would help.
-// eslint-disable-next-line max-lines-per-function
-export async function exportCommand(projectRoot, files, options) {
-    const isDryRun = options.dryRun === true;
-    intro(isDryRun ? 'FireForge Export (dry run)' : 'FireForge Export');
+async function prepareExport(projectRoot, files, options) {
     // Placement flags are mutually exclusive with each other.
     const placementFlagCount = [
         options.order !== undefined,
@@ -170,7 +162,23 @@ export async function exportCommand(projectRoot, files, options) {
     }
     const metadata = await promptExportPatchMetadata(options, isInteractive, 'export', config);
     if (!metadata)
+        return null;
+    return { paths, placementFlagCount, diff, config, isInteractive, metadata };
+}
+/**
+ * Runs the export command to export file changes as a patch.
+ * Accepts one or more file/directory paths and bundles them into a single patch.
+ * @param projectRoot - Root directory of the project
+ * @param files - File or directory paths to export (relative to engine/)
+ * @param options - Export options
+ */
+export async function exportCommand(projectRoot, files, options) {
+    const isDryRun = options.dryRun === true;
+    intro(isDryRun ? 'FireForge Export (dry run)' : 'FireForge Export');
+    const prepared = await prepareExport(projectRoot, files, options);
+    if (!prepared)
         return;
+    const { paths, placementFlagCount, diff, config, isInteractive, metadata } = prepared;
     const { patchName, selectedCategory, description } = metadata;
     const s = spinner(isDryRun ? 'Planning export...' : 'Exporting patch...');
     try {
@@ -189,71 +197,21 @@ export async function exportCommand(projectRoot, files, options) {
         // exclusive with supersede — the semantics overlap confusingly.
         let placementPlan = null;
         if (placementFlagCount > 0) {
-            if (options.supersede) {
-                throw new InvalidArgumentError('Placement flags (--order/--before/--after) cannot be combined with --supersede.', 'export placement');
-            }
-            placementPlan = await resolvePlacementPlan(paths.patches, options, selectedCategory, patchName);
-            const currentManifest = await loadPatchesManifest(paths.patches);
-            if (currentManifest !== null) {
-                assertPlacementPreservesReservedRanges(placementPlan, currentManifest.patches, config, selectedCategory);
-            }
-            const conflicts = await projectPlacementForLint(paths.patches, placementPlan, diff);
-            const renamed = currentManifest !== null
-                ? applyRenameMapToManifest(currentManifest, placementPlan.renameMap)
-                : buildProjectedManifest(null, []);
-            enforcePatchPolicy({
+            const gated = await gatePlacementPlan({
+                patchesDir: paths.patches,
+                options,
+                selectedCategory,
+                patchName,
+                description,
+                filesAffected,
+                diff,
                 config,
-                manifest: buildProjectedManifest(renamed, [
-                    ...renamed.patches,
-                    {
-                        filename: placementPlan.newFilename,
-                        order: placementPlan.insertionOrder,
-                        category: selectedCategory,
-                        name: patchName,
-                        description,
-                        createdAt: new Date().toISOString(),
-                        ...buildPatchSourceMetadata(config.firefox),
-                        filesAffected,
-                        ...(options.tier !== undefined ? { tier: options.tier } : {}),
-                        ...(options.lintIgnore !== undefined && options.lintIgnore.length > 0
-                            ? { lintIgnore: options.lintIgnore }
-                            : {}),
-                    },
-                ]),
-                command: 'export',
-                forceUnsafe: options.forceUnsafe === true,
+                isDryRun,
+                s,
             });
-            const summary = placementSummary(placementPlan);
-            const renameCount = placementPlan.renameMap.size;
-            // Route through confirmDestructive when the operation is destructive
-            // enough to warrant a prompt (more than one rename) OR when the user
-            // asked for a dry-run. The dry-run branch must always print the
-            // placement summary — previously, single-rename/no-rename dry-runs
-            // exited silently with no filename or projected layout.
-            if (renameCount > 1 || isDryRun) {
-                s.stop();
-                const decision = await confirmDestructive({
-                    operation: 'export-order',
-                    title: `Export with placement at order ${placementPlan.insertionOrder}`,
-                    summary,
-                    yes: options.yes === true,
-                    dryRun: isDryRun,
-                    unsafeOverride: options.forceUnsafe === true,
-                    conflicts,
-                });
-                if (decision === 'dry-run') {
-                    outro('Dry run complete — no changes made');
-                    return;
-                }
-                if (decision === 'cancelled') {
-                    outro('Export cancelled');
-                    return;
-                }
-            }
-            else if (conflicts && options.forceUnsafe !== true) {
-                s.stop();
-                throw new InvalidArgumentError(`Refusing to run export: ${conflicts.reason}. Pass --force-unsafe to override.`, '--force-unsafe');
-            }
+            if (gated === 'stop')
+                return;
+            placementPlan = gated;
         }
         // Dry-run path: compute the plan and print it, never write.
         if (isDryRun && !placementPlan) {
@@ -267,10 +225,7 @@ export async function exportCommand(projectRoot, files, options) {
                 ...buildPatchSourceMetadata(config.firefox),
                 explicitSupersede: options.supersede === true,
                 allowOverlap: options.allowOverlap === true,
-                ...(options.tier !== undefined ? { tier: options.tier } : {}),
-                ...(options.lintIgnore !== undefined && options.lintIgnore.length > 0
-                    ? { lintIgnore: options.lintIgnore }
-                    : {}),
+                ...patchMetadataExtras(options),
                 config,
                 forceUnsafe: options.forceUnsafe === true,
             });
@@ -291,10 +246,7 @@ export async function exportCommand(projectRoot, files, options) {
                 createdAt: new Date().toISOString(),
                 ...buildPatchSourceMetadata(config.firefox),
                 filesAffected,
-                ...(options.tier !== undefined ? { tier: options.tier } : {}),
-                ...(options.lintIgnore !== undefined && options.lintIgnore.length > 0
-                    ? { lintIgnore: options.lintIgnore }
-                    : {}),
+                ...patchMetadataExtras(options),
             };
             const committedPlan = await commitPlacementExport({
                 patchesDir: paths.patches,
@@ -336,29 +288,15 @@ export async function exportCommand(projectRoot, files, options) {
             return;
         }
         // Default (no dry-run, no placement) path: the pre-existing behavior.
-        // Check how many existing patches would be superseded
-        const shouldProceed = await confirmSupersedePatches(paths.patches, filesAffected, options.supersede, isInteractive, s);
-        if (!shouldProceed)
-            return;
-        // Overlap gate: pre-0.16.0 `export` only caught FULL-coverage
-        // supersedes, so a second export targeting a shared file like
-        // `browser/themes/shared/jar.inc.mn` happily created a queue where
-        // two patches both listed the same file in `filesAffected`. `verify`
-        // then failed immediately on "cross-patch filesAffected conflicts".
-        // `confirmSupersedePatches` might already have confirmed full
-        // supersedes above; pass their filenames through so we do not flag
-        // a file claimed by a patch that is about to be removed.
-        const willSupersede = await findAllPatchesForFiles(paths.patches, filesAffected);
-        const supersedingFilenames = new Set(willSupersede.map((p) => p.filename));
-        const shouldProceedPastOverlap = await guardOwnershipOverlap({
+        const shouldProceedPastGates = await runSupersedeAndOverlapGates({
             patchesDir: paths.patches,
             filesAffected,
-            supersedingFilenames,
+            supersede: options.supersede,
             allowOverlap: options.allowOverlap === true,
             isInteractive,
             s,
         });
-        if (!shouldProceedPastOverlap)
+        if (!shouldProceedPastGates)
             return;
         const { patchFilename, superseded } = await commitExportedPatch({
             patchesDir: paths.patches,
@@ -368,10 +306,7 @@ export async function exportCommand(projectRoot, files, options) {
             diff,
             filesAffected,
             ...buildPatchSourceMetadata(config.firefox),
-            ...(options.tier !== undefined ? { tier: options.tier } : {}),
-            ...(options.lintIgnore !== undefined && options.lintIgnore.length > 0
-                ? { lintIgnore: options.lintIgnore }
-                : {}),
+            ...patchMetadataExtras(options),
             config,
             policyCommand: 'export',
             forceUnsafe: options.forceUnsafe === true,

package/dist/src/commands/furnace/chrome-doc-templates.d.ts

@@ -7,19 +7,6 @@
  * upstream Firefox (browser.xhtml, privatebrowsing/aboutPrivateBrowsing.html,
  * etc.) minus the fork-specific wiring. A fork author fills in the body.
  */
-/**
- * Sentinel attribute emitted on every `furnace chrome-doc create`-scaffolded
- * root element. Platform modules (`DevToolsStartup`, `PageActions`,
- * `SessionStore`, `DownloadsButton`, …) that observe
- * `browser-delayed-startup-finished` and walk INTO the window assume the
- * `browser.xhtml` DOM and throw on anything else. A fork-authored patch
- * to such a module can use `hasAttribute(...)` against this sentinel as
- * a cheap, fork-neutral guard to skip the walk on a custom chrome doc.
- *
- * Exposed as a named constant so test code and external checks can
- * reference the exact attribute name without hardcoding the string.
- */
-export declare const FURNACE_CHROME_DOC_SENTINEL = "data-furnace-chrome-doc";
 /**
  * XHTML shell for a top-level chrome document.
  *

package/dist/src/commands/furnace/chrome-doc-templates.js

@@ -20,7 +20,7 @@
  * Exposed as a named constant so test code and external checks can
  * reference the exact attribute name without hardcoding the string.
  */
-export const FURNACE_CHROME_DOC_SENTINEL = 'data-furnace-chrome-doc';
+const FURNACE_CHROME_DOC_SENTINEL = 'data-furnace-chrome-doc';
 /**
  * XHTML shell for a top-level chrome document.
  *