@hominis/fireforge 0.22.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.24.0
+
+- Moved branding vendor identity into generated branding configure scripts and made `browser/moz.configure` vendor patching optional.
+- Added metadata-backed staged forward-import declarations plus `patch staged-dependency` editing.
+- Added stale xpcshell `_tests` symlink repair with a single safe retry.
+- Added `patch move-files` for previewable ownership-transfer repair plans.
+- Improved queue self-containment guidance for staged dependencies and patch repairs.
+
+## 0.23.0
+
+- Improved xpcshell test argument filtering and mixed-harness diagnostics.
+- Locked pre-test build phases and improved stale harness diagnostics.
+- Fixed binary-safe re-export for new untracked files.
+- Improved additive `re-export --files` and lint warning guidance.
+
 ## 0.22.0
 
 - Added `doctor --clear-resolution` with verify-backed safety checks.

package/dist/src/commands/lint.js

@@ -161,6 +161,12 @@ async function resolveLintDiff(engineDir, files, binaryName, furnacePrefixes) {
     }
     return diff;
 }
+function buildMaxWarningsMessage(count, maxWarnings, scope) {
+    const scoped = scope ? ` ${scope}` : '';
+    const base = `Patch lint found ${count} warning(s)${scoped}, exceeding --max-warnings ${maxWarnings}.`;
+    return (base +
+        ' If this is a release gate, run with --per-patch to identify the owning patch. For intentional staged imports, use patch staged-dependency; for ownership repairs, preview patch move-files, patch reorder --dry-run, or re-export --files --dry-run; add scoped lintIgnore only after review.');
+}
 /**
  * Filters aggregate-mode lint issues against per-patch `lintIgnore`
  * lists drawn from the manifest. An issue is dropped when at least one
@@ -373,7 +379,7 @@ export async function lintCommand(projectRoot, files, options = {}) {
     }
     if (options.maxWarnings !== undefined && warnings.length > options.maxWarnings) {
         outro('Lint failed');
-        throw new GeneralError(`Patch lint found ${warnings.length} warning(s), exceeding --max-warnings ${options.maxWarnings}.`);
+        throw new GeneralError(buildMaxWarningsMessage(warnings.length, options.maxWarnings));
     }
     // Notices are advisory and don't count as warnings — emitting "passed
     // with warnings" when only notices fired contradicts the preceding
@@ -493,7 +499,7 @@ async function lintPerPatch(projectRoot, paths, options = {}) {
     }
     if (options.maxWarnings !== undefined && warnings.length > options.maxWarnings) {
         outro('Lint failed');
-        throw new GeneralError(`Patch lint found ${warnings.length} warning(s) across ${linted} patch(es), exceeding --max-warnings ${options.maxWarnings}.`);
+        throw new GeneralError(buildMaxWarningsMessage(warnings.length, options.maxWarnings, `across ${linted} patch(es)`));
     }
     if (warnings.length > 0) {
         outro('Lint passed with warnings');

package/dist/src/commands/patch/index.d.ts

@@ -1,7 +1,8 @@
 /**
  * `fireforge patch <verb>` parent command. Groups single-patch
- * mutations (`compact`, `delete`, `lint-ignore`, `rename`, `reorder`,
- * `tier`) so they do not clutter the top-level command list.
+ * mutations and planners (`compact`, `delete`, `lint-ignore`, `move-files`,
+ * `rename`, `reorder`, `staged-dependency`, `tier`) so they do not clutter the top-level command
+ * list.
  * Queue-level verbs like `lint`, `export`, `verify`, and `status` stay
  * flat.
  */

package/dist/src/commands/patch/index.js

@@ -1,16 +1,19 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * `fireforge patch <verb>` parent command. Groups single-patch
- * mutations (`compact`, `delete`, `lint-ignore`, `rename`, `reorder`,
- * `tier`) so they do not clutter the top-level command list.
+ * mutations and planners (`compact`, `delete`, `lint-ignore`, `move-files`,
+ * `rename`, `reorder`, `staged-dependency`, `tier`) so they do not clutter the top-level command
+ * list.
  * Queue-level verbs like `lint`, `export`, `verify`, and `status` stay
  * flat.
  */
 import { registerPatchCompact } from './compact.js';
 import { registerPatchDelete } from './delete.js';
 import { registerPatchLintIgnore } from './lint-ignore.js';
+import { registerPatchMoveFiles } from './move-files.js';
 import { registerPatchRename } from './rename.js';
 import { registerPatchReorder } from './reorder.js';
+import { registerPatchStagedDependency } from './staged-dependency.js';
 import { registerPatchTier } from './tier.js';
 /**
  * Registers the `patch` subcommand parent and its verbs on the CLI.
@@ -21,7 +24,7 @@ import { registerPatchTier } from './tier.js';
 export function registerPatch(program, context) {
     const patch = program
         .command('patch')
-        .description('Manage individual patches in the queue (compact, delete, lint-ignore, rename, reorder, tier)')
+        .description('Manage individual patches in the queue (compact, delete, lint-ignore, move-files, rename, reorder, staged-dependency, tier)')
         // Match `fireforge furnace`'s no-args contract: print the group's help and
         // exit 0. Without this default action, commander routes `fireforge patch`
         // (no subcommand) through its own help-then-exit-1 path, so scripts that
@@ -34,8 +37,10 @@ export function registerPatch(program, context) {
     registerPatchCompact(patch, context);
     registerPatchDelete(patch, context);
     registerPatchLintIgnore(patch, context);
+    registerPatchMoveFiles(patch, context);
     registerPatchRename(patch, context);
     registerPatchReorder(patch, context);
+    registerPatchStagedDependency(patch, context);
     registerPatchTier(patch, context);
 }
 //# sourceMappingURL=index.js.map

package/dist/src/commands/patch/move-files.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `fireforge patch move-files <from> <to>` previews the explicit
+ * re-export choreography needed to move file ownership between two patches.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../../types/cli.js';
+import type { PatchMoveFilesOptions } from '../../types/commands/index.js';
+/**
+ * Builds and prints a safe, no-write file ownership move plan.
+ *
+ * @param projectRoot - Project root directory
+ * @param fromIdentifier - Patch filename, ordinal, or manifest name that currently owns the files
+ * @param toIdentifier - Patch filename, ordinal, or manifest name that should own the files
+ * @param options - Files to move and display mode
+ */
+export declare function patchMoveFilesCommand(projectRoot: string, fromIdentifier: string, toIdentifier: string, options?: PatchMoveFilesOptions): Promise<void>;
+/**
+ * Registers the preview-only `patch move-files` subcommand.
+ *
+ * @param parent - Parent `patch` command
+ * @param context - Shared CLI registration context
+ */
+export declare function registerPatchMoveFiles(parent: Command, context: CommandContext): void;

package/dist/src/commands/patch/move-files.js

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch move-files <from> <to>` previews the explicit
+ * re-export choreography needed to move file ownership between two patches.
+ */
+import { relative } from 'node:path';
+import { getProjectPaths } from '../../core/config.js';
+import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
+import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-manifest.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { pathExists } from '../../utils/fs.js';
+import { info, intro, note, outro, warn } from '../../utils/logger.js';
+function collectOption(value, previous) {
+    previous.push(value);
+    return previous;
+}
+function normalizeFileList(files) {
+    const cleaned = (files ?? []).map((file) => file.trim()).filter((file) => file.length > 0);
+    return [...new Set(cleaned)].sort((left, right) => left.localeCompare(right));
+}
+function shellQuote(value) {
+    if (/^[A-Za-z0-9_./:=@%+-]+$/.test(value))
+        return value;
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function formatFiles(files) {
+    return files.length === 0 ? '(none)' : files.map((file) => `  - ${file}`).join('\n');
+}
+function formatReExportCommand(identifier, files, extraFlags) {
+    return [
+        'fireforge',
+        're-export',
+        shellQuote(identifier),
+        '--files',
+        ...files.map(shellQuote),
+        ...extraFlags,
+    ].join(' ');
+}
+function assertPatchHasFiles(owner, files) {
+    const owned = new Set(owner.filesAffected);
+    const missing = files.filter((file) => !owned.has(file));
+    if (missing.length === 0)
+        return;
+    throw new InvalidArgumentError(`${owner.filename} does not currently own ${missing.length} requested file(s):\n${formatFiles(missing)}`, 'patch move-files');
+}
+function assertTargetDoesNotAlreadyOwnFiles(target, files) {
+    const owned = new Set(target.filesAffected);
+    const duplicates = files.filter((file) => owned.has(file));
+    if (duplicates.length === 0)
+        return;
+    throw new InvalidArgumentError(`${target.filename} already owns ${duplicates.length} requested file(s):\n${formatFiles(duplicates)}`, 'patch move-files');
+}
+function computeFileMovePlan(source, target, files) {
+    const moved = new Set(files);
+    return {
+        sourceAfter: source.filesAffected.filter((file) => !moved.has(file)).sort(),
+        targetAfter: [...new Set([...target.filesAffected, ...files])].sort(),
+    };
+}
+/**
+ * Builds and prints a safe, no-write file ownership move plan.
+ *
+ * @param projectRoot - Project root directory
+ * @param fromIdentifier - Patch filename, ordinal, or manifest name that currently owns the files
+ * @param toIdentifier - Patch filename, ordinal, or manifest name that should own the files
+ * @param options - Files to move and display mode
+ */
+export async function patchMoveFilesCommand(projectRoot, fromIdentifier, toIdentifier, options = {}) {
+    intro('FireForge patch move-files');
+    if (fromIdentifier === toIdentifier) {
+        throw new InvalidArgumentError('Source and target patch identifiers must be different.', 'patch move-files');
+    }
+    const files = normalizeFileList(options.file);
+    if (files.length === 0) {
+        throw new InvalidArgumentError('Specify at least one --file path to move.', 'patch move-files');
+    }
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.patches))) {
+        throw new GeneralError('Patches directory not found.');
+    }
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (!manifest || manifest.patches.length === 0) {
+        throw new GeneralError('No patches in manifest.');
+    }
+    const source = resolvePatchIdentifier(fromIdentifier, manifest.patches);
+    if (!source) {
+        throw new InvalidArgumentError(formatPatchNotFoundError(fromIdentifier, manifest.patches), fromIdentifier);
+    }
+    const target = resolvePatchIdentifier(toIdentifier, manifest.patches);
+    if (!target) {
+        throw new InvalidArgumentError(formatPatchNotFoundError(toIdentifier, manifest.patches), toIdentifier);
+    }
+    if (source.filename === target.filename) {
+        throw new InvalidArgumentError('Source and target resolved to the same patch.', 'patch move-files');
+    }
+    assertPatchHasFiles(source, files);
+    assertTargetDoesNotAlreadyOwnFiles(target, files);
+    const { sourceAfter, targetAfter } = computeFileMovePlan(source, target, files);
+    if (sourceAfter.length === 0) {
+        throw new InvalidArgumentError(`${source.filename} would have no filesAffected after this move. Delete or re-export that patch explicitly instead.`, 'patch move-files');
+    }
+    for (const file of files) {
+        if (!(await pathExists(`${paths.engine}/${file}`))) {
+            warn(`engine/${file} does not exist in the current worktree; re-export may drop or fail it.`);
+        }
+    }
+    const relativePatchesDir = relative(projectRoot, paths.patches) || 'patches';
+    info(`Planning ownership move in ${relativePatchesDir}/patches.json.`);
+    info(`Move ${files.length} file(s) from ${source.filename} to ${target.filename}:`);
+    note(formatFiles(files), 'Files');
+    note(formatFiles(sourceAfter), `${source.filename} files after move`);
+    note(formatFiles(targetAfter), `${target.filename} files after move`);
+    const dryRunSource = formatReExportCommand(source.filename, sourceAfter, ['--dry-run']);
+    const dryRunTarget = formatReExportCommand(target.filename, targetAfter, ['--dry-run']);
+    const applySource = formatReExportCommand(source.filename, sourceAfter, ['--yes']);
+    const applyTarget = formatReExportCommand(target.filename, targetAfter, []);
+    note(`${dryRunSource}\n${dryRunTarget}`, 'Preview commands');
+    note(`${applySource}\n${applyTarget}`, 'Apply commands');
+    outro('Move plan complete - no changes made');
+}
+/**
+ * Registers the preview-only `patch move-files` subcommand.
+ *
+ * @param parent - Parent `patch` command
+ * @param context - Shared CLI registration context
+ */
+export function registerPatchMoveFiles(parent, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    parent
+        .command('move-files <from> <to>')
+        .description('Preview the re-export commands needed to move file ownership between patches.')
+        .option('--file <path>', 'File path relative to engine/ to move (repeatable)', collectOption, [])
+        .action(withErrorHandling(async (from, to, options) => {
+        await patchMoveFilesCommand(getProjectRoot(), from, to, options);
+    }));
+}
+//# sourceMappingURL=move-files.js.map

package/dist/src/commands/patch/staged-dependency.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `fireforge patch staged-dependency <name>` — edits
+ * PatchMetadata.stagedDependencies without rewriting the .patch body.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../../types/cli.js';
+import type { PatchStagedDependencyOptions, PatchStagedForwardImport } from '../../types/commands/index.js';
+type StagedDependencyMode = 'add' | 'remove' | 'clear';
+/**
+ * Renders a one-line summary of a staged-dependency metadata change.
+ */
+export declare function describeStagedDependencyChange(before: readonly PatchStagedForwardImport[], after: readonly PatchStagedForwardImport[], mode: StagedDependencyMode, dependency: PatchStagedForwardImport | undefined): string;
+/**
+ * Runs the metadata-only staged-dependency mutation command.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest name
+ * @param options - Mutation mode and forward-import fields
+ */
+export declare function patchStagedDependencyCommand(projectRoot: string, identifier: string, options?: PatchStagedDependencyOptions): Promise<void>;
+/**
+ * Registers the `patch staged-dependency` subcommand.
+ *
+ * @param parent - Parent `patch` command
+ * @param context - Shared CLI registration context
+ */
+export declare function registerPatchStagedDependency(parent: Command, context: CommandContext): void;
+export {};

package/dist/src/commands/patch/staged-dependency.js

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch staged-dependency <name>` — edits
+ * PatchMetadata.stagedDependencies without rewriting the .patch body.
+ */
+import { getProjectPaths } from '../../core/config.js';
+import { appendHistory } from '../../core/destructive.js';
+import { mutatePatchMetadata } from '../../core/patch-export.js';
+import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
+import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-manifest.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { pathExists } from '../../utils/fs.js';
+import { info, intro, outro, warn } from '../../utils/logger.js';
+function modeFromOptions(options) {
+    const adding = options.add === true;
+    const removing = options.remove === true;
+    const clearing = options.clear === true;
+    const modeCount = [adding, removing, clearing].filter(Boolean).length;
+    if (modeCount > 1) {
+        throw new InvalidArgumentError('--add, --remove, and --clear are mutually exclusive. Pick one mode per invocation.', 'patch staged-dependency');
+    }
+    if (modeCount === 0) {
+        throw new InvalidArgumentError('Specify --add, --remove, or --clear.', 'patch staged-dependency');
+    }
+    return adding ? 'add' : removing ? 'remove' : 'clear';
+}
+function requireForwardImportOptions(options, mode) {
+    if (!options.file || !options.specifier || !options.creates) {
+        throw new InvalidArgumentError(`--${mode} requires --file, --specifier, and --creates.`, 'patch staged-dependency');
+    }
+    const dependency = {
+        file: options.file,
+        specifier: options.specifier,
+        creates: options.creates,
+    };
+    if (options.owner !== undefined)
+        dependency.owner = options.owner;
+    if (options.reason !== undefined)
+        dependency.reason = options.reason;
+    return dependency;
+}
+function dependencyKey(dependency) {
+    return [dependency.file, dependency.specifier, dependency.creates, dependency.owner ?? ''].join('\0');
+}
+function dependencyLabel(dependency) {
+    const owner = dependency.owner ? ` owner=${dependency.owner}` : '';
+    const reason = dependency.reason ? ` reason="${dependency.reason}"` : '';
+    return `${dependency.file} imports "${dependency.specifier}" from ${dependency.creates}${owner}${reason}`;
+}
+function removeMatching(existing, target) {
+    return existing.filter((dependency) => dependency.file !== target.file ||
+        dependency.specifier !== target.specifier ||
+        dependency.creates !== target.creates ||
+        (target.owner !== undefined && dependency.owner !== target.owner));
+}
+function applyMode(existing, mode, dependency) {
+    if (mode === 'clear')
+        return [];
+    if (!dependency)
+        return [...existing];
+    if (mode === 'remove')
+        return removeMatching(existing, dependency);
+    const seen = new Set(existing.map(dependencyKey));
+    if (seen.has(dependencyKey(dependency)))
+        return [...existing];
+    return [...existing, dependency];
+}
+/**
+ * Renders a one-line summary of a staged-dependency metadata change.
+ */
+export function describeStagedDependencyChange(before, after, mode, dependency) {
+    if (mode === 'clear') {
+        return before.length === 0
+            ? 'stagedDependencies was already empty — no change'
+            : `cleared ${before.length} staged forward-import declaration(s)`;
+    }
+    if (!dependency)
+        return 'stagedDependencies unchanged';
+    if (mode === 'add') {
+        return after.length === before.length
+            ? `staged forward-import already present: ${dependencyLabel(dependency)}`
+            : `added staged forward-import: ${dependencyLabel(dependency)}`;
+    }
+    return after.length === before.length
+        ? `no staged forward-import matched: ${dependencyLabel(dependency)}`
+        : `removed ${before.length - after.length} staged forward-import declaration(s): ${dependencyLabel(dependency)}`;
+}
+/**
+ * Runs the metadata-only staged-dependency mutation command.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest name
+ * @param options - Mutation mode and forward-import fields
+ */
+export async function patchStagedDependencyCommand(projectRoot, identifier, options = {}) {
+    const isDryRun = options.dryRun === true;
+    intro(isDryRun ? 'FireForge patch staged-dependency (dry run)' : 'FireForge patch staged-dependency');
+    const mode = modeFromOptions(options);
+    const dependency = mode === 'clear' ? undefined : requireForwardImportOptions(options, mode);
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.patches))) {
+        throw new GeneralError('Patches directory not found.');
+    }
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (!manifest || manifest.patches.length === 0) {
+        throw new GeneralError('No patches in manifest.');
+    }
+    const target = resolvePatchIdentifier(identifier, manifest.patches);
+    if (!target) {
+        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
+    }
+    const existing = target.stagedDependencies?.forwardImports ?? [];
+    const projected = applyMode(existing, mode, dependency);
+    const summary = describeStagedDependencyChange(existing, projected, mode, dependency);
+    if (isDryRun) {
+        info(`[dry-run] ${target.filename}: ${summary}.`);
+        outro('Dry run complete — no changes made');
+        return;
+    }
+    const result = await mutatePatchMetadata(paths.patches, target.filename, (current) => {
+        const before = current.stagedDependencies?.forwardImports ?? [];
+        const after = applyMode(before, mode, dependency);
+        if (after.length === 0)
+            return { unset: ['stagedDependencies'] };
+        return { set: { stagedDependencies: { forwardImports: after } } };
+    });
+    if (!result) {
+        throw new GeneralError(`Patch ${target.filename} disappeared from the manifest during the update. Re-run after investigating.`);
+    }
+    const before = result.before.stagedDependencies?.forwardImports ?? [];
+    const after = result.after.stagedDependencies?.forwardImports ?? [];
+    info(`${target.filename}: ${describeStagedDependencyChange(before, after, mode, dependency)}.`);
+    try {
+        await appendHistory(paths.patches, {
+            operation: 'patch-staged-dependency',
+            args: {
+                filename: target.filename,
+                mode,
+                before,
+                after,
+            },
+            ...(options.yes === true ? { yes: true } : {}),
+            result: 'ok',
+        });
+    }
+    catch (historyError) {
+        warn(`History log append failed after patch staged-dependency committed (${target.filename}): ${toError(historyError).message}`);
+    }
+    outro('Patch staged-dependency complete');
+}
+/**
+ * Registers the `patch staged-dependency` subcommand.
+ *
+ * @param parent - Parent `patch` command
+ * @param context - Shared CLI registration context
+ */
+export function registerPatchStagedDependency(parent, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    parent
+        .command('staged-dependency <name>')
+        .description('Edit PatchMetadata.stagedDependencies on a single patch (no .patch body rewrite).')
+        .option('--add', 'Add a staged forward-import declaration')
+        .option('--remove', 'Remove matching staged forward-import declaration(s)')
+        .option('--clear', 'Drop the stagedDependencies field entirely')
+        .option('--file <path>', 'Importing file path relative to engine/')
+        .option('--specifier <specifier>', 'Exact import specifier as it appears in source')
+        .option('--creates <path>', 'Later-created file path relative to engine/')
+        .option('--owner <patch>', 'Exact later patch filename expected to create --creates')
+        .option('--reason <text>', 'Human-readable rationale stored with the declaration')
+        .option('--dry-run', 'Show what would change without writing')
+        .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .action(withErrorHandling(async (name, options) => {
+        await patchStagedDependencyCommand(getProjectRoot(), name, options);
+    }));
+}
+//# sourceMappingURL=staged-dependency.js.map

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

@@ -175,9 +175,10 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
             forceUnsafe: options.forceUnsafe === true,
         });
     }
-    // Shrinks are destructive (previously-owned files become unmanaged).
-    // Additive-only changes still deserve a prompt because --files asserts
-    // an authoritative file set.
+    // Shrinks are destructive (previously-owned files become unmanaged), so
+    // they keep the explicit confirmation gate. Additive-only scopes are safe
+    // to run non-interactively after lint/policy projection because no existing
+    // patch ownership is being dropped.
     const summary = [
         `re-export ${target.filename} with --files scope`,
         `current files (${target.filesAffected.length}): ${target.filesAffected.join(', ') || '(none)'}`,
@@ -196,7 +197,7 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
         operation: 're-export-files',
         title: `Re-export ${target.filename} with --files`,
         summary,
-        yes: options.yes === true,
+        yes: removed.length === 0 && missingFiles.length === 0 ? true : options.yes === true,
         dryRun: isDryRun,
         unsafeOverride: options.forceUnsafe === true,
         conflicts,

package/dist/src/commands/test.js

@@ -2,11 +2,12 @@
 import { join } from 'node:path';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
-import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, testWithOutput, } from '../core/mach.js';
+import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, testWithOutput, withBuildLock, } from '../core/mach.js';
 import { assertMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
 import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
-import { operatorAlreadySetAppPath, resolveXpcshellAppdirArg, } from '../core/xpcshell-appdir.js';
+import { tryRepairStaleXpcshellTestSymlink } from '../core/test-stale-symlink.js';
+import { findNearestXpcshellManifest, operatorAlreadySetAppPath, resolveXpcshellAppdirArg, } from '../core/xpcshell-appdir.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
@@ -36,6 +37,43 @@ function buildStaleBuildMessage() {
         'The failing output referenced missing branding or distribution resources, which usually means the current obj-* build does not match recent engine or branding changes.\n\n' +
         'Re-run "fireforge build --ui" or "fireforge test --build" and then retry.');
 }
+async function classifyTestHarnesses(engineDir, normalizedPaths) {
+    const result = { xpcshell: [], nonXpcshell: [] };
+    for (const testPath of normalizedPaths) {
+        const manifest = await findNearestXpcshellManifest(engineDir, testPath);
+        if (manifest) {
+            result.xpcshell.push(testPath);
+        }
+        else {
+            result.nonXpcshell.push(testPath);
+        }
+    }
+    return result;
+}
+function buildMixedHarnessMessage(classification) {
+    return ('FireForge cannot run xpcshell and browser/mochitest paths in the same mach invocation.\n\n' +
+        'Split this into separate `fireforge test` commands so each manifest selects its own harness:\n' +
+        `  - xpcshell: ${classification.xpcshell.join(', ')}\n` +
+        `  - browser/mochitest: ${classification.nonXpcshell.join(', ')}`);
+}
+function filterRedundantXpcshellFlavorArgs(machArgs, classification) {
+    if (classification.xpcshell.length === 0 || classification.nonXpcshell.length > 0) {
+        return [...machArgs];
+    }
+    const filtered = [];
+    for (let i = 0; i < machArgs.length; i += 1) {
+        const arg = machArgs[i] ?? '';
+        if (/^--flavor=xpcshell(?:-tests)?$/.test(arg)) {
+            continue;
+        }
+        if (arg === '--flavor' && /^xpcshell(?:-tests)?$/.test(machArgs[i + 1] ?? '')) {
+            i += 1;
+            continue;
+        }
+        filtered.push(arg);
+    }
+    return filtered;
+}
 function hasStaleBuildArtifactsSignal(output) {
     // Deliberately narrow: only fire on branding-specific resource paths
     // that are always a stale-artifact symptom. The earlier pattern also
@@ -101,6 +139,36 @@ function buildXpcshellAppdirMessage(injectionAttempted) {
         '  - Remove `firefox-appdir = "browser"` from the xpcshell.toml [DEFAULT] and move browser-chrome dependencies into a browser-chrome mochitest (see `fireforge furnace create --test-style=browser-chrome`).\n' +
         '  - If the test only touches toolkit chrome (chrome://global/*), drop the `firefox-appdir` setting entirely — toolkit chrome is registered without it.');
 }
+function buildHarnessSymlinkMessage() {
+    return ('mach failed while preparing test harness symlinks before the requested tests ran.\n\n' +
+        'This usually means the objdir contains stale harness setup from an earlier run. Re-run with `fireforge test --build` to refresh the harness state, or remove the stale harness symlink in the active obj-* directory before retrying.');
+}
+async function resolveLaunchablePathForTests(engineDir, binaryName, objDir) {
+    if (!objDir)
+        return undefined;
+    const bundleCheck = await hasRunnableBundle(engineDir, binaryName, objDir);
+    if (!bundleCheck.runnable) {
+        const expectedSuffix = bundleCheck.expectedPath
+            ? ` (expected at engine/${bundleCheck.expectedPath})`
+            : '';
+        throw new GeneralError(`Tests require a complete launchable build${expectedSuffix}. ` +
+            'The obj-*/dist/ tree exists but the launchable binary is missing — typically the result of an interrupted or partially failed `fireforge build`.\n\n' +
+            'Run "fireforge build" again and let it finish before retrying "fireforge test".');
+    }
+    return bundleCheck.expectedPath;
+}
+async function runPreTestBuild(projectRoot, paths, projectConfig) {
+    await withBuildLock(projectRoot, async () => {
+        await prepareBuildEnvironment(projectRoot, paths, projectConfig);
+        const s = spinner('Running incremental build...');
+        const buildResult = await buildUI(paths.engine);
+        if (buildResult.exitCode !== 0) {
+            s.error('Pre-test build failed');
+            throw new BuildError('Pre-test build failed', 'mach build faster');
+        }
+        s.stop('Build complete');
+    });
+}
 // Detects the `AttributeError: 'MochitestDesktop' object has no attribute
 // 'http3Server'` teardown crash. The attribute is lazy-initialized inside
 // harness code paths that presume chrome://branding resolves correctly; a
@@ -153,6 +221,10 @@ function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted
     if (hasMochitestHttp3ServerSignal(combinedOutput)) {
         throw new GeneralError(buildMochitestHttp3ServerMessage());
     }
+    if (/FileExistsError/i.test(combinedOutput) &&
+        /(mochitest|xpcshell|_tests)/i.test(combinedOutput)) {
+        throw new GeneralError(buildHarnessSymlinkMessage());
+    }
     if (/invalid filename/i.test(combinedOutput) ||
         /chrome:\/\/mochitests.*not found/i.test(combinedOutput)) {
         info('Hint: The test file may not be registered in browser.toml or jar.mn.');
@@ -201,29 +273,10 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // here so `test --doctor` against an incomplete build surfaces the
     // missing-bundle path instead of a cryptic `Browser process exited
     // during spawn (exit code 1, signal none). stderr tail: (empty)`.
-    let launchablePath;
-    if (buildCheck.objDir) {
-        const bundleCheck = await hasRunnableBundle(paths.engine, projectConfig.binaryName, buildCheck.objDir);
-        launchablePath = bundleCheck.expectedPath;
-        if (!bundleCheck.runnable) {
-            const expectedSuffix = bundleCheck.expectedPath
-                ? ` (expected at engine/${bundleCheck.expectedPath})`
-                : '';
-            throw new GeneralError(`Tests require a complete launchable build${expectedSuffix}. ` +
-                'The obj-*/dist/ tree exists but the launchable binary is missing — typically the result of an interrupted or partially failed `fireforge build`.\n\n' +
-                'Run "fireforge build" again and let it finish before retrying "fireforge test".');
-        }
-    }
+    const launchablePath = await resolveLaunchablePathForTests(paths.engine, projectConfig.binaryName, buildCheck.objDir);
     // Run incremental build if requested
     if (options.build) {
-        await prepareBuildEnvironment(projectRoot, paths, projectConfig);
-        const s = spinner('Running incremental build...');
-        const buildResult = await buildUI(paths.engine);
-        if (buildResult.exitCode !== 0) {
-            s.error('Pre-test build failed');
-            throw new BuildError('Pre-test build failed', 'mach build faster');
-        }
-        s.stop('Build complete');
+        await runPreTestBuild(projectRoot, paths, projectConfig);
         info('');
     }
     else {
@@ -309,6 +362,13 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // previous case-insensitive + leading-whitespace-tolerant contract.
     const normalizedPaths = testPaths.map((p) => stripEnginePrefix(p).trim());
     await assertTestPathsExist(paths.engine, normalizedPaths);
+    const classification = await classifyTestHarnesses(paths.engine, normalizedPaths);
+    if (classification.xpcshell.length > 0 && classification.nonXpcshell.length > 0) {
+        throw new GeneralError(buildMixedHarnessMessage(classification));
+    }
+    const forwardedMachArgs = options.machArg && options.machArg.length > 0
+        ? filterRedundantXpcshellFlavorArgs(options.machArg, classification)
+        : [];
     // Build extra args
     const extraArgs = [];
     if (options.headless) {
@@ -319,8 +379,8 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // above for the motivating case). Appended AFTER --headless so mach sees
     // the FireForge-managed flags first and the escape-valve ones last, which
     // keeps the override precedence predictable.
-    if (options.machArg && options.machArg.length > 0) {
-        extraArgs.push(...options.machArg);
+    if (forwardedMachArgs.length > 0) {
+        extraArgs.push(...forwardedMachArgs);
     }
     // Auto-forward the Marionette port to mach when `--marionette-port` is
     // set. `--setpref=marionette.port=<n>` configures where the browser
@@ -379,6 +439,14 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     catch (error) {
         throw new BuildError('Test process failed to start', 'mach test', error instanceof Error ? error : undefined);
     }
+    if (result.exitCode !== 0 &&
+        classification.xpcshell.length > 0 &&
+        classification.nonXpcshell.length === 0) {
+        const repaired = await tryRepairStaleXpcshellTestSymlink(paths.engine, buildCheck.objDir, `${result.stdout}\n${result.stderr}`);
+        if (repaired) {
+            result = await testWithOutput(paths.engine, normalizedPaths, extraArgs);
+        }
+    }
     handleNonZeroTestExit(result, normalizedPaths, appdirInjection, projectConfig.binaryName);
 }
 /**

package/dist/src/commands/verify.js

@@ -223,7 +223,7 @@ export async function verifyCommand(projectRoot) {
     info(`\nVerify: ${health.errorCount} error(s), ${health.warningCount} warning(s)`);
     if (health.errorCount > 0) {
         outro('Verify failed');
-        throw new GeneralError(`fireforge verify found ${health.errorCount} error(s). Fix these before running export/import/rebase.`);
+        throw new GeneralError(`fireforge verify found ${health.errorCount} error(s). Fix these before running export/import/rebase. Use "patch staged-dependency" for intentional staged imports, or preview "patch move-files" / "patch reorder --dry-run" / "re-export --files --dry-run" for ownership repairs.`);
     }
     outro('Verify passed with warnings');
 }

package/dist/src/core/branding.js

@@ -96,6 +96,7 @@ function buildConfigureScriptContent(config) {
     return `${header}
 
 MOZ_APP_DISPLAYNAME="${escapeShellValue(config.name)}"
+MOZ_APP_VENDOR="${escapeShellValue(config.vendor)}"
 MOZ_MACBUNDLE_ID="${escapeShellValue(config.appId)}"
 `;
 }
@@ -148,21 +149,24 @@ trademarkInfo = { " " }
 `;
 }
 /**
- * Patches browser/moz.configure to set custom vendor.
+ * Patches browser/moz.configure to set custom vendor when the upstream
+ * configure surface still owns an existing MOZ_APP_VENDOR imply_option.
  *
- * Mozilla's build system requires MOZ_APP_VENDOR to be set via imply_option
- * in moz.configure, not through mozconfig.
+ * Newer FireForge branding writes MOZ_APP_VENDOR from the branding-owned
+ * configure.sh instead, so an absent browser/moz.configure line is valid.
+ * Keeping this best-effort replacement preserves compatibility for queues
+ * that still carry the older process-wide registration line.
  */
 async function patchMozConfigure(engineDir, config) {
     const mozConfigurePath = join(engineDir, 'browser', 'moz.configure');
     if (!(await pathExists(mozConfigurePath))) {
-        throw new BrandingError(`browser/moz.configure not found at ${mozConfigurePath}`);
+        return;
     }
     let content = await readText(mozConfigurePath);
     // Replace MOZ_APP_VENDOR imply_option
     const vendorRegex = /imply_option\("MOZ_APP_VENDOR",\s*"[^"]*"\)/;
     if (!vendorRegex.test(content)) {
-        throw new BrandingError('Could not find MOZ_APP_VENDOR imply_option in browser/moz.configure');
+        return;
     }
     content = content.replace(vendorRegex, buildMozConfigureVendorLine(config));
     await writeTextIfChanged(mozConfigurePath, content);
@@ -223,7 +227,6 @@ export async function isBrandingSetup(engineDir, config) {
     const configureShPath = join(brandingDir, 'configure.sh');
     const propsPath = join(brandingDir, 'locales', 'en-US', 'brand.properties');
     const ftlPath = join(brandingDir, 'locales', 'en-US', 'brand.ftl');
-    const mozConfigurePath = join(engineDir, 'browser', 'moz.configure');
     if (!(await pathExists(configureShPath))) {
         return false;
     }
@@ -243,11 +246,7 @@ export async function isBrandingSetup(engineDir, config) {
             return false;
         }
     }
-    if (!(await pathExists(mozConfigurePath))) {
-        return false;
-    }
-    const mozConfigureContent = await readText(mozConfigurePath);
-    return mozConfigureContent.includes(buildMozConfigureVendorLine(config));
+    return configureContent.includes(`MOZ_APP_VENDOR="${escapeShellValue(config.vendor)}"`);
 }
 /**
  * Checks whether a file path belongs to the tool-managed branding directory.

package/dist/src/core/git-diff.js

@@ -8,7 +8,7 @@ import { pathExists, readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { exec } from '../utils/process.js';
 import { ensureGit, git } from './git-base.js';
-import { fileExistsInHead } from './git-file-ops.js';
+import { fileExistsInHead, isBinaryFile } from './git-file-ops.js';
 import { getUntrackedFiles, getUntrackedFilesInDir } from './git-status.js';
 async function execGitWithAllowedExitCodes(repoDir, args, allowedExitCodes = [0]) {
     const result = await exec('git', args, { cwd: repoDir });
@@ -174,7 +174,9 @@ export async function getAllDiff(repoDir) {
     // Generate diffs for untracked files
     const untrackedDiffs = [];
     for (const file of untrackedFiles) {
-        const diff = await generateNewFileDiff(repoDir, file);
+        const diff = (await isBinaryFile(repoDir, file))
+            ? await generateBinaryFilePatch(repoDir, file)
+            : await generateNewFileDiff(repoDir, file);
         untrackedDiffs.push(diff);
     }
     // Combine all diffs — each already ends with \n, so concatenate directly
@@ -247,7 +249,9 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
             }
             continue;
         }
-        const diff = await generateNewFileDiff(repoDir, file);
+        const diff = (await isBinaryFile(repoDir, file))
+            ? await generateBinaryFilePatch(repoDir, file)
+            : await generateNewFileDiff(repoDir, file);
         if (diff.trim()) {
             diffs.push(diff);
         }

package/dist/src/core/marionette-port.js

@@ -291,9 +291,12 @@ export function forwardedMachArgsIncludeMarionetteClient(machArgs) {
  * for runs where the pref is ignored anyway.
  */
 export function hasExplicitXpcshellFlavor(machArgs) {
-    for (const arg of machArgs) {
+    for (let i = 0; i < machArgs.length; i += 1) {
+        const arg = machArgs[i] ?? '';
         if (/^--flavor=xpcshell\b/.test(arg) || arg === '--flavor=xpcshell-tests')
             return true;
+        if (arg === '--flavor' && /^xpcshell(?:-tests)?$/.test(machArgs[i + 1] ?? ''))
+            return true;
     }
     return false;
 }

package/dist/src/core/patch-export-metadata.d.ts

@@ -5,7 +5,7 @@ import type { PatchMetadata } from '../types/commands/index.js';
 /**
  * Optional `PatchMetadata` keys safe to clear via the helpers below.
  */
-export type ClearablePatchMetadataField = 'tier' | 'lintIgnore';
+export type ClearablePatchMetadataField = 'tier' | 'lintIgnore' | 'stagedDependencies';
 /**
  * Updates metadata for a patch in the manifest.
  *

package/dist/src/core/patch-export-metadata.js

@@ -17,6 +17,9 @@ function applyMetadataUpdate(existing, updates, unset) {
             case 'lintIgnore':
                 delete next.lintIgnore;
                 break;
+            case 'stagedDependencies':
+                delete next.stagedDependencies;
+                break;
         }
     }
     return next;

package/dist/src/core/patch-lint-cross.js

@@ -327,6 +327,22 @@ export function findForwardImportIgnoreLines(source) {
     }
     return ignored;
 }
+function stagedDependencyKey(entry, dependency) {
+    return [
+        entry.filename,
+        dependency.file,
+        dependency.specifier,
+        dependency.creates,
+        dependency.owner ?? '',
+    ].join('\0');
+}
+function findMatchingStagedDependency(entry, sitePath, specifier, laterOwners) {
+    const declarations = entry.metadata?.stagedDependencies?.forwardImports ?? [];
+    return declarations.find((dependency) => dependency.file === sitePath &&
+        dependency.specifier === specifier &&
+        laterOwners.some((owner) => owner.fullPath === dependency.creates &&
+            (dependency.owner === undefined || dependency.owner === owner.filename)));
+}
 /**
  * Cross-patch lint rule: a patch imports a module that a later patch is
  * responsible for creating.
@@ -361,6 +377,7 @@ export function lintPatchQueueForwardImports(ctx) {
         }
     }
     const issues = [];
+    const usedStagedDeclarations = new Set();
     // Runs the forward-import check against one source site — either a file
     // the patch creates (`content` = full file) or a file the patch modifies
     // (`content` = concatenated added lines only). We deliberately scan added
@@ -389,6 +406,11 @@ export function lintPatchQueueForwardImports(ctx) {
                 (owner.order === entry.order && owner.filename > entry.filename));
             if (laterOwners.length === 0)
                 continue;
+            const stagedDependency = findMatchingStagedDependency(entry, sitePath, specifier, laterOwners);
+            if (stagedDependency) {
+                usedStagedDeclarations.add(stagedDependencyKey(entry, stagedDependency));
+                continue;
+            }
             const ownersSummary = laterOwners
                 .map((o) => `${o.filename} (creates ${o.fullPath})`)
                 .join(', ');
@@ -407,7 +429,8 @@ export function lintPatchQueueForwardImports(ctx) {
                 message: `${sitePath} in ${entry.filename} imports "${specifier}", ` +
                     `but the matching new file is created by a later patch: ${ownersSummary}. ` +
                     'Reorder the patches so the dependency is created first, move the import ' +
-                    'into the later patch, or mark the import with ' +
+                    'into the later patch, declare the intentional staged dependency with ' +
+                    '"fireforge patch staged-dependency --add", or mark the import with ' +
                     `"// ${FORWARD_IMPORT_IGNORE_MARKER}" if the basename collision is a false positive. ` +
                     `Closest legal ordinal that satisfies this dependency: ${suggestedOrder}.`,
                 severity: 'error',
@@ -420,6 +443,21 @@ export function lintPatchQueueForwardImports(ctx) {
         for (const [path, added] of entry.modifiedFileAdditions)
             checkSite(entry, path, added);
     }
+    for (const entry of ctx.entries) {
+        for (const dependency of entry.metadata?.stagedDependencies?.forwardImports ?? []) {
+            if (usedStagedDeclarations.has(stagedDependencyKey(entry, dependency)))
+                continue;
+            issues.push({
+                file: dependency.file,
+                check: 'staged-dependency-unused',
+                fingerprint: `staged-dependency-unused|${entry.filename}|${dependency.file}|${dependency.specifier}|${dependency.creates}|${dependency.owner ?? ''}`,
+                message: `${entry.filename} declares a staged forward import from ${dependency.file} ` +
+                    `to "${dependency.specifier}" / ${dependency.creates}, but that exact forward dependency was not found. ` +
+                    'Remove the stale declaration with "fireforge patch staged-dependency --remove" or update it to match the current queue.',
+                severity: 'warning',
+            });
+        }
+    }
     return issues;
 }
 /**

package/dist/src/core/patch-manifest-validate.js

@@ -4,6 +4,35 @@
  */
 import { parseObject } from '../utils/parse.js';
 import { isArray, isObject, isValidFirefoxVersion, PATCH_CATEGORIES } from '../utils/validation.js';
+function parseForwardImports(data, label) {
+    if (!isArray(data)) {
+        throw new Error(`${label} must be an array`);
+    }
+    return data.map((entry, index) => {
+        const rec = parseObject(entry, `${label}[${index}]`);
+        const dependency = {
+            file: rec.string('file'),
+            specifier: rec.string('specifier'),
+            creates: rec.string('creates'),
+        };
+        const owner = rec.optionalString('owner');
+        if (owner !== undefined)
+            dependency.owner = owner;
+        const reason = rec.optionalString('reason');
+        if (reason !== undefined)
+            dependency.reason = reason;
+        return dependency;
+    });
+}
+function parseStagedDependencies(data, label) {
+    const rec = parseObject(data, label);
+    const rawForwardImports = rec.raw('forwardImports');
+    const staged = {};
+    if (rawForwardImports !== undefined) {
+        staged.forwardImports = parseForwardImports(rawForwardImports, `${label}.forwardImports`);
+    }
+    return staged;
+}
 /**
  * Validates a single patch metadata entry from raw data.
  * @param data - Raw data to validate
@@ -56,6 +85,10 @@ export function validatePatchMetadata(data, index) {
         result.lintIgnore = lintIgnore;
     if (tier !== undefined)
         result.tier = tier;
+    const rawStagedDependencies = rec.raw('stagedDependencies');
+    if (rawStagedDependencies !== undefined) {
+        result.stagedDependencies = parseStagedDependencies(rawStagedDependencies, `patches[${index}].stagedDependencies`);
+    }
     return result;
 }
 /** Validates raw patches.json data and returns the typed manifest shape. */

package/dist/src/core/test-stale-symlink.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Safe stale test-harness symlink repair for xpcshell setup failures.
+ */
+/**
+ * Removes one stale xpcshell `_tests` symlink when mach reports a
+ * FileExistsError during test installation.
+ *
+ * The guard rails are deliberately narrow: only quoted FileExistsError
+ * destinations inside the active objdir's `_tests` tree are considered, and
+ * only when lstat confirms the destination itself is a symlink.
+ */
+export declare function tryRepairStaleXpcshellTestSymlink(engineDir: string, objDir: string | undefined, output: string): Promise<boolean>;

package/dist/src/core/test-stale-symlink.js

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Safe stale test-harness symlink repair for xpcshell setup failures.
+ */
+import { isAbsolute, relative, resolve } from 'node:path';
+import { isSymlink, removeFile } from '../utils/fs.js';
+import { warn } from '../utils/logger.js';
+function extractFileExistsDestination(output) {
+    const match = /FileExistsError[^\n]*File exists:\s+(?:(?:'[^']*'|"[^"]*")\s*->\s*)?['"]([^'"]+)['"]/i.exec(output);
+    return match?.[1];
+}
+function isInsideDirectory(parent, candidate) {
+    const rel = relative(parent, candidate);
+    return rel.length === 0 || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+/**
+ * Removes one stale xpcshell `_tests` symlink when mach reports a
+ * FileExistsError during test installation.
+ *
+ * The guard rails are deliberately narrow: only quoted FileExistsError
+ * destinations inside the active objdir's `_tests` tree are considered, and
+ * only when lstat confirms the destination itself is a symlink.
+ */
+export async function tryRepairStaleXpcshellTestSymlink(engineDir, objDir, output) {
+    if (!objDir || !/FileExistsError/i.test(output))
+        return false;
+    const destination = extractFileExistsDestination(output);
+    if (!destination)
+        return false;
+    const resolvedDestination = resolve(destination);
+    const testsRoot = resolve(engineDir, objDir, '_tests');
+    if (!isInsideDirectory(testsRoot, resolvedDestination))
+        return false;
+    if (!(await isSymlink(resolvedDestination)))
+        return false;
+    await removeFile(resolvedDestination);
+    warn(`Removed stale xpcshell harness symlink under ${objDir}/_tests and retrying mach test once: ${relative(resolve(engineDir), resolvedDestination)}`);
+    return true;
+}
+//# sourceMappingURL=test-stale-symlink.js.map

package/dist/src/types/commands/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * Re-exports all command-related types from focused sub-modules.
  */
-export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, GlobalOptions, ImportOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchRenameOptions, PatchReorderOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
-export type { ImportSummary, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, } from './patches.js';
+export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, GlobalOptions, ImportOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchMoveFilesOptions, PatchRenameOptions, PatchReorderOptions, PatchStagedDependencyOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
+export type { ImportSummary, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, PatchStagedDependencies, PatchStagedForwardImport, } from './patches.js';
 export type { DoctorCheck, ProjectStatus, TokenCoverageFileEntry, TokenCoverageReport, } from './project.js';

package/dist/src/types/commands/options.d.ts

@@ -240,6 +240,42 @@ export interface PatchLintIgnoreOptions {
     /** Skip the confirmation prompt (required for non-TTY). */
     yes?: boolean;
 }
+/**
+ * Options for the `fireforge patch staged-dependency` subcommand. Modes are
+ * mutually exclusive: add a declaration, remove one or more matching
+ * declarations, or clear all staged dependencies from the patch.
+ */
+export interface PatchStagedDependencyOptions {
+    /** Add a forward-import staged dependency. */
+    add?: boolean;
+    /** Remove matching forward-import staged dependency declarations. */
+    remove?: boolean;
+    /** Drop the stagedDependencies field entirely. */
+    clear?: boolean;
+    /** Importing file path relative to engine/. */
+    file?: string;
+    /** Exact import specifier as it appears in source. */
+    specifier?: string;
+    /** Later-created file path relative to engine/. */
+    creates?: string;
+    /** Optional exact patch filename expected to create `creates`. */
+    owner?: string;
+    /** Optional human-readable rationale stored with the declaration. */
+    reason?: string;
+    /** Print the planned change without writing. */
+    dryRun?: boolean;
+    /** Skip the confirmation prompt (required for non-TTY). */
+    yes?: boolean;
+}
+/**
+ * Options for the preview-only `fireforge patch move-files` subcommand.
+ * It validates an ownership transfer and prints the explicit
+ * `re-export --files` commands needed to perform it.
+ */
+export interface PatchMoveFilesOptions {
+    /** File paths relative to engine/ to move from the source patch to the target patch. */
+    file?: string[];
+}
 /**
  * Options for the rebase command.
  */

package/dist/src/types/commands/patches.d.ts

@@ -97,6 +97,33 @@ export interface PatchMetadata {
      * rejected by the manifest validator, not silently stripped.
      */
     tier?: 'branding';
+    /**
+     * Optional declarations for intentional staged dependencies between
+     * patches. These are metadata-only escape hatches for cases where an
+     * early patch must import or register a helper created later in the
+     * queue during a staged migration. They keep tooling-specific markers
+     * out of Firefox source while remaining exact enough that unrelated
+     * forward imports still fail.
+     */
+    stagedDependencies?: PatchStagedDependencies;
+}
+/** Staged dependency metadata owned by a patch. */
+export interface PatchStagedDependencies {
+    /** Exact forward-import declarations allowed for this patch. */
+    forwardImports?: PatchStagedForwardImport[];
+}
+/** A single intentional forward import to a later-created file. */
+export interface PatchStagedForwardImport {
+    /** Importing file path relative to engine/. */
+    file: string;
+    /** Exact import specifier as it appears in source. */
+    specifier: string;
+    /** Later-created file path relative to engine/. */
+    creates: string;
+    /** Optional exact patch filename expected to create `creates`. */
+    owner?: string;
+    /** Optional human-readable rationale for the staged dependency. */
+    reason?: string;
 }
 /**
  * Schema for patches/patches.json file.

package/dist/src/utils/fs.d.ts

@@ -28,6 +28,13 @@ export declare function removeDir(path: string): Promise<void>;
  * @param path - File path to remove
  */
 export declare function removeFile(path: string): Promise<void>;
+/**
+ * Returns true when a path exists and is a symbolic link.
+ *
+ * Uses lstat rather than stat so a symlink to a missing target is still
+ * classified as a symlink. That matters for cleanup of stale harness links.
+ */
+export declare function isSymlink(path: string): Promise<boolean>;
 /**
  * Copies a file from source to destination.
  * Creates parent directories if needed.

package/dist/src/utils/fs.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { randomUUID } from 'node:crypto';
-import { access, chmod, copyFile as fsCopyFile, mkdir, open, readdir, readFile, rename, rm, stat, statfs, } from 'node:fs/promises';
+import { access, chmod, copyFile as fsCopyFile, lstat, mkdir, open, readdir, readFile, rename, rm, stat, statfs, } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 const RETRIABLE_REMOVE_ERRORS = new Set(['ENOTEMPTY', 'EBUSY', 'EPERM']);
 function sleep(ms) {
@@ -84,6 +84,21 @@ export async function removeDir(path) {
 export async function removeFile(path) {
     await rm(path, { force: true });
 }
+/**
+ * Returns true when a path exists and is a symbolic link.
+ *
+ * Uses lstat rather than stat so a symlink to a missing target is still
+ * classified as a symlink. That matters for cleanup of stale harness links.
+ */
+export async function isSymlink(path) {
+    try {
+        return (await lstat(path)).isSymbolicLink();
+    }
+    catch (error) {
+        void error;
+        return false;
+    }
+}
 /**
  * Copies a file from source to destination.
  * Creates parent directories if needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -66,7 +66,7 @@
     "@vitest/coverage-v8": "^4.1.2",
     "eslint": "^10.0.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-jsdoc": "^62.9.0",
+    "eslint-plugin-jsdoc": "^63.0.0",
     "eslint-plugin-simple-import-sort": "^13.0.0",
     "fast-check": "^4.6.0",
     "husky": "^9.1.7",