@hominis/fireforge 0.49.2 → 0.51.0

package/dist/src/commands/export-adopt-check.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The advice an export placement refusal appends for new files: "register
+ * first" when a new system module only lacks its moz.build line, and
+ * adopt-then-split for a real moved-code block, but only after checking
+ * that the adopt itself would pass.
+ *
+ * The advice used to be offered on the moved-code heuristic alone. On one
+ * queue it told the operator to adopt six new modules into an existing
+ * patch when the only error was the missing registration; the adopt then
+ * refused one module for importing later patches, and without it breached
+ * the source patch's hard size limit. Split out of export-flow.ts for the
+ * line budget.
+ */
+import { type PatchQueueContext } from '../core/patch-lint.js';
+import type { PatchLintIssue } from '../types/commands/index.js';
+/**
+ * Why adopting `diff` into `sourceFilename` would itself be refused: the
+ * forward imports the adopted files would give the source patch, and the
+ * source patch's hard size limit. Empty when the adopt is clean.
+ *
+ * @param baseCtx - The current queue
+ * @param sourceFilename - The patch the adopt would grow
+ * @param diff - The pending export's diff
+ */
+export declare function findAdoptBlockers(baseCtx: PatchQueueContext, sourceFilename: string, diff: string): string[];
+/**
+ * Detail lines for a placement refusal: register-first and moved-code
+ * advice, each only when the projection supports it.
+ *
+ * @param baseCtx - The current queue
+ * @param diff - The pending export's diff
+ * @param projectedIssues - Error findings of the placement projection
+ * @param plan - The placement's new filename and order
+ */
+export declare function describePlacementAdvice(baseCtx: PatchQueueContext, diff: string, projectedIssues: readonly PatchLintIssue[], plan: {
+    newFilename: string;
+    insertionOrder: number;
+}): string[];

package/dist/src/commands/export-adopt-check.js

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The advice an export placement refusal appends for new files: "register
+ * first" when a new system module only lacks its moz.build line, and
+ * adopt-then-split for a real moved-code block, but only after checking
+ * that the adopt itself would pass.
+ *
+ * The advice used to be offered on the moved-code heuristic alone. On one
+ * queue it told the operator to adopt six new modules into an existing
+ * patch when the only error was the missing registration; the adopt then
+ * refused one module for importing later patches, and without it breached
+ * the source patch's hard size limit. Split out of export-flow.ts for the
+ * line budget.
+ */
+import { detectMovedCodeOverlaps, formatMovedCodeAdvice } from '../core/export-moved-code-shape.js';
+import { countNonBinaryDiffLines, getPatchSizeThresholds, lintPatchQueue, resolvePatchSizeTier, } from '../core/patch-lint.js';
+import { computeProjectedLintRegressions } from '../core/patch-lint-projection.js';
+import { projectEntryBody } from './patch/entry-projection.js';
+/**
+ * Why adopting `diff` into `sourceFilename` would itself be refused: the
+ * forward imports the adopted files would give the source patch, and the
+ * source patch's hard size limit. Empty when the adopt is clean.
+ *
+ * @param baseCtx - The current queue
+ * @param sourceFilename - The patch the adopt would grow
+ * @param diff - The pending export's diff
+ */
+export function findAdoptBlockers(baseCtx, sourceFilename, diff) {
+    const source = baseCtx.entries.find((entry) => entry.filename === sourceFilename);
+    if (source === undefined)
+        return [];
+    const blockers = [];
+    const pending = projectEntryBody(diff);
+    const adopted = {
+        ...source,
+        diff: `${source.diff}\n${diff}`,
+        newFiles: new Map([...source.newFiles, ...pending.newFiles]),
+        createdFiles: new Set([...source.createdFiles, ...pending.createdFiles]),
+        modifiedFileAdditions: new Map([
+            ...source.modifiedFileAdditions,
+            ...pending.modifiedFileAdditions,
+        ]),
+    };
+    const isError = (issue) => issue.severity === 'error';
+    const baseline = lintPatchQueue(baseCtx).filter(isError);
+    const projected = lintPatchQueue({
+        ...baseCtx,
+        entries: baseCtx.entries.map((entry) => (entry.filename === sourceFilename ? adopted : entry)),
+    }).filter(isError);
+    for (const issue of computeProjectedLintRegressions(baseline, projected)) {
+        if (issue.check !== 'forward-import' || !issue.patches?.includes(sourceFilename))
+            continue;
+        for (const declaration of issue.stagedDeclarations ?? []) {
+            blockers.push(`${declaration.file} imports "${declaration.specifier ?? ''}", created by ` +
+                `${declaration.owner}, which applies after ${sourceFilename} (forward-import)`);
+        }
+    }
+    if (!(source.metadata?.lintIgnore ?? []).includes('large-patch-lines')) {
+        const tier = resolvePatchSizeTier([...(source.metadata?.filesAffected ?? []), ...pending.newFiles.keys()], source.metadata?.tier);
+        const limit = getPatchSizeThresholds(tier.tier).lines.error;
+        const lines = countNonBinaryDiffLines(source.diff).textLines + countNonBinaryDiffLines(diff).textLines;
+        if (lines > limit) {
+            blockers.push(`${sourceFilename} would grow to about ${lines} lines, over its ${tier.tier} hard limit ` +
+                `of ${limit} (large-patch-lines)`);
+        }
+    }
+    return blockers;
+}
+/**
+ * Detail lines for a placement refusal: register-first and moved-code
+ * advice, each only when the projection supports it.
+ *
+ * @param baseCtx - The current queue
+ * @param diff - The pending export's diff
+ * @param projectedIssues - Error findings of the placement projection
+ * @param plan - The placement's new filename and order
+ */
+export function describePlacementAdvice(baseCtx, diff, projectedIssues, plan) {
+    const newFiles = projectEntryBody(diff).newFiles;
+    const exported = projectedIssues.filter((issue) => issue.patches?.includes(plan.newFilename) ?? issue.message.includes(plan.newFilename));
+    const unregisteredModules = [
+        ...new Set(exported
+            .filter((issue) => issue.check === 'unregistered-system-module' && newFiles.has(issue.file))
+            .map((issue) => issue.file)),
+    ];
+    const registrationResolvesAll = unregisteredModules.length > 0 &&
+        exported.every((issue) => issue.check === 'unregistered-system-module');
+    const overlaps = registrationResolvesAll ? [] : detectMovedCodeOverlaps(diff, baseCtx.entries);
+    const strongest = overlaps[0];
+    return formatMovedCodeAdvice({
+        overlaps,
+        newPatchName: plan.newFilename,
+        insertionOrder: plan.insertionOrder,
+        unregisteredModules,
+        registrationResolvesAll,
+        adoptBlockers: strongest !== undefined ? findAdoptBlockers(baseCtx, strongest.sourcePatch, diff) : [],
+    });
+}

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

@@ -7,11 +7,11 @@
  * per-file / per-function line budgets and makes each step individually
  * testable without dragging the whole command harness along for the ride.
  */
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import {} from '../core/destructive.js';
-import { detectMovedCodeOverlaps, formatAdoptThenSplitRemedy, } from '../core/export-moved-code-shape.js';
 import { buildPlanExportInput, findAllPatchesForFilesWithDetails, patchNameSlug, planExport, } from '../core/patch-export.js';
 import { buildPatchQueueContext, lintPatchQueue } from '../core/patch-lint.js';
+import { formatLintIgnoreList } from '../core/patch-lint-ignore.js';
 import { withPatchDirectoryLock } from '../core/patch-lock.js';
 import { addPatchToManifest, loadPatchesManifest, loadPatchesManifestForWrite, renumberPatchesInManifest, resolvePatchIdentifier, savePatchesManifest, } from '../core/patch-manifest.js';
 import { formatPatchOrder, requirePatchOrder } from '../core/patch-parse.js';
@@ -20,9 +20,11 @@ import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, removeFile, writeText } from '../utils/fs.js';
 import { info, warn } from '../utils/logger.js';
+import { describePlacementAdvice } from './export-adopt-check.js';
 import { groupProjectedPlacementErrors } from './export-placement-conflicts.js';
 import { assertPlacementAvoidsReservedRanges } from './export-placement-policy.js';
 import { findPartialOwnershipOverlap } from './export-shared.js';
+import { acceptTreeRegisteredModules } from './export-staged-registration.js';
 import { projectEntryBody } from './patch/entry-projection.js';
 import { getSortedRenameEntries, renameMapsEqual } from './patch-rename-map.js';
 function buildFilenameForPlacement(category, name, order, width) {
@@ -170,18 +172,31 @@ export async function projectPlacementForLint(patchesDir, plan, diff, config) {
     // whether they live in a brand-new file or are added to an existing one.
     // Leaving either map empty lets a patch land before one of its own
     // dependencies and still pass the gate.
+    const pendingBody = projectEntryBody(diff);
     projectedEntries.push({
         filename: plan.newFilename,
         order: plan.insertionOrder,
         metadata: null,
-        ...projectEntryBody(diff),
+        ...pendingBody,
     });
     projectedEntries.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
     const policyRest = baseCtx.patchPolicy ? { patchPolicy: baseCtx.patchPolicy } : {};
-    const projectedIssues = lintPatchQueue({
-        entries: projectedEntries,
-        ...policyRest,
-    }).filter((i) => i.severity === 'error');
+    // A new module whose moz.build line is declared (staged registration)
+    // and present in the working tree, but not yet exported by its owner, is
+    // accepted with a "re-export the owner next" note instead of refused.
+    const registration = await acceptTreeRegisteredModules({
+        engineDir: join(dirname(patchesDir), 'engine'),
+        baseCtx,
+        newFilename: plan.newFilename,
+        pendingNewFiles: new Set(pendingBody.newFiles.keys()),
+        projectedIssues: lintPatchQueue({
+            entries: projectedEntries,
+            ...policyRest,
+        }).filter((i) => i.severity === 'error'),
+    });
+    for (const note of registration.accepted)
+        warn(note);
+    const projectedIssues = registration.remaining;
     if (projectedIssues.length === 0)
         return null;
     // Baseline lint over the un-renumbered queue: an error present here is
@@ -192,16 +207,16 @@ export async function projectPlacementForLint(patchesDir, plan, diff, config) {
         entries: baseCtx.entries,
         ...policyRest,
     }).filter((i) => i.severity === 'error');
-    // New-file + moved-code slice: when the refusal is caused by
-    // the source patch still carrying lines the new patch would gain, name
-    // the adopt-then-split sequence instead of leaving the operator to
-    // derive it from two individually-correct guards that together dead-end.
-    const movedCode = detectMovedCodeOverlaps(diff, baseCtx.entries);
+    // Register-first and new-file + moved-code advice: name the working
+    // sequence instead of leaving the operator to derive it from two
+    // individually-correct guards that together dead-end, but only offer
+    // adopt-then-split for a real moved block whose adopt would itself pass.
     return {
         reason: `placement would introduce ${projectedIssues.length} cross-patch lint error(s)`,
         details: [
             ...groupProjectedPlacementErrors(projectedIssues, baselineIssues, plan),
-            ...formatAdoptThenSplitRemedy(movedCode, plan.newFilename, plan.insertionOrder),
+            ...registration.advice,
+            ...describePlacementAdvice(baseCtx, diff, projectedIssues, plan),
         ],
     };
 }
@@ -380,7 +395,7 @@ export async function renderDryRunPreview(input) {
         info(`  tier: ${plan.metadata.tier}`);
     }
     if (plan.metadata.lintIgnore !== undefined && plan.metadata.lintIgnore.length > 0) {
-        info(`  lintIgnore: ${plan.metadata.lintIgnore.join(', ')}`);
+        info(`  lintIgnore: ${formatLintIgnoreList(plan.metadata.lintIgnore)}`);
     }
     if (supersedeDetails.length > 0) {
         info(`\n[dry-run] Would supersede ${supersedeDetails.length} existing patch(es):`);

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

@@ -4,7 +4,7 @@
  * 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 { ExportOptions } 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';
@@ -14,7 +14,11 @@ import { type PlacementPlan } from './export-flow.js';
  * 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'>>;
+export declare function patchMetadataExtras(options: ExportOptions): {
+    tier?: 'branding';
+    /** CLI flags only ever carry bare check IDs. */
+    lintIgnore?: string[];
+};
 /**
  * Resolves and gates the placement plan when any placement flag
  * (`--order`/`--before`/`--after`) was given: rejects the `--supersede`

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

@@ -8,6 +8,7 @@
 import { confirmDestructive } from '../core/destructive.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { applyRenameMapToManifest, buildProjectedManifest, enforcePatchPolicy, } from '../core/patch-policy.js';
+import { reservationAt } from '../core/patch-retired.js';
 import { buildPatchSourceMetadata } from '../core/patch-source-metadata.js';
 import { InvalidArgumentError } from '../errors/base.js';
 import { proceedAfterDecision } from './destructive-decision.js';
@@ -68,6 +69,13 @@ export async function gatePlacementPlan(args) {
         forceUnsafe: options.forceUnsafe === true,
     });
     const summary = placementSummary(placementPlan);
+    const reservation = reservationAt(currentManifest, placementPlan.insertionOrder);
+    if (reservation !== undefined) {
+        const notice = `order ${placementPlan.insertionOrder} is reserved by ${reservation.owner}; ` +
+            'this export fills the reservation';
+        summary.push(notice);
+        s.message(notice);
+    }
     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

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

@@ -1,3 +1,4 @@
+import type { LintIgnoreChecks } from '../core/patch-lint-ignore.js';
 import type { PatchesManifest, PatchLintIssue } from '../types/commands/index.js';
 import type { ExportOptions, PatchCategory } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
@@ -22,7 +23,7 @@ export interface RunPatchLintOptions {
      * `large-patch-lines` on a cohesive branding bundle that genuinely cannot
      * be split.
      */
-    ignoreChecks?: ReadonlySet<string> | undefined;
+    ignoreChecks?: LintIgnoreChecks | undefined;
     /**
      * Optional explicit tier override (threaded from `PatchMetadata.tier`).
      * Forces the branding-tier thresholds when set, independent of the

package/dist/src/commands/export-staged-registration.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Lets `export --order` land a new system module whose moz.build line is
+ * still unexported working-tree drift in the patch that registers it.
+ *
+ * The two refusals used to deadlock: the module's export failed
+ * `unregistered-system-module` because no patch body carried its moz.build
+ * line yet, and the registering patch could not be re-exported first
+ * because its line named a file no patch created. The way through is
+ * declared intent plus evidence: when the registering patch carries a
+ * staged registration for the module and the working tree's moz.build has
+ * exactly that line, the export is accepted and the operator is told to
+ * re-export the registering patch next. Without the declaration the
+ * refusal names the steps, with the exact `patch staged-dependency`
+ * command, instead of stopping at "register it".
+ *
+ * Consumed by export-flow.ts.
+ */
+import type { PatchQueueContext } from '../core/patch-lint.js';
+import type { PatchLintIssue } from '../types/commands/index.js';
+/** Result of {@link acceptTreeRegisteredModules}. */
+export interface TreeRegistrationOutcome {
+    /** The projected errors left after accepted modules are removed. */
+    remaining: PatchLintIssue[];
+    /** One note per accepted module, naming the re-export to run next. */
+    accepted: string[];
+    /** Detail lines for modules whose registration is in the tree but undeclared. */
+    advice: string[];
+}
+/**
+ * Removes `unregistered-system-module` findings for modules the pending
+ * export creates when a queue patch declares their registration as a
+ * staged dependency and the working tree's moz.build carries that line.
+ * For a module whose line is in the tree but undeclared, returns the steps
+ * that make it acceptable.
+ *
+ * @param args - The engine directory (the working tree), the current queue,
+ *   the filename the pending export would take, the files it creates, and
+ *   the placement projection's error findings
+ */
+export declare function acceptTreeRegisteredModules(args: {
+    engineDir: string;
+    baseCtx: PatchQueueContext;
+    newFilename: string;
+    pendingNewFiles: ReadonlySet<string>;
+    projectedIssues: readonly PatchLintIssue[];
+}): Promise<TreeRegistrationOutcome>;

package/dist/src/commands/export-staged-registration.js

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Lets `export --order` land a new system module whose moz.build line is
+ * still unexported working-tree drift in the patch that registers it.
+ *
+ * The two refusals used to deadlock: the module's export failed
+ * `unregistered-system-module` because no patch body carried its moz.build
+ * line yet, and the registering patch could not be re-exported first
+ * because its line named a file no patch created. The way through is
+ * declared intent plus evidence: when the registering patch carries a
+ * staged registration for the module and the working tree's moz.build has
+ * exactly that line, the export is accepted and the operator is told to
+ * re-export the registering patch next. Without the declaration the
+ * refusal names the steps, with the exact `patch staged-dependency`
+ * command, instead of stopping at "register it".
+ *
+ * Consumed by export-flow.ts.
+ */
+import { basename, dirname, join } from 'node:path';
+import { STAGED_DEPENDENCY_REASON_PLACEHOLDER } from '../core/patch-lint-staged-registration.js';
+import { pathExists, readText } from '../utils/fs.js';
+async function readLines(path) {
+    if (!(await pathExists(path)))
+        return undefined;
+    return (await readText(path)).split('\n').map((line) => line.trim());
+}
+/** The nearest moz.build at or above `modulePath` whose lines name `leaf` quoted. */
+async function findTreeRegistration(engineDir, modulePath) {
+    const leaf = basename(modulePath);
+    let dir = dirname(modulePath);
+    for (;;) {
+        const file = dir === '.' ? 'moz.build' : `${dir}/moz.build`;
+        const line = (await readLines(join(engineDir, file)))?.find((candidate) => candidate.includes(`"${leaf}"`) || candidate.includes(`'${leaf}'`));
+        if (line !== undefined)
+            return { file, line };
+        if (dir === '.' || dir === '')
+            return undefined;
+        const parent = dirname(dir);
+        dir = parent === dir ? '.' : parent;
+    }
+}
+/**
+ * Removes `unregistered-system-module` findings for modules the pending
+ * export creates when a queue patch declares their registration as a
+ * staged dependency and the working tree's moz.build carries that line.
+ * For a module whose line is in the tree but undeclared, returns the steps
+ * that make it acceptable.
+ *
+ * @param args - The engine directory (the working tree), the current queue,
+ *   the filename the pending export would take, the files it creates, and
+ *   the placement projection's error findings
+ */
+export async function acceptTreeRegisteredModules(args) {
+    const outcome = { remaining: [], accepted: [], advice: [] };
+    for (const issue of args.projectedIssues) {
+        if (issue.check !== 'unregistered-system-module' || !args.pendingNewFiles.has(issue.file)) {
+            outcome.remaining.push(issue);
+            continue;
+        }
+        const declared = args.baseCtx.entries.flatMap((entry) => (entry.metadata?.stagedDependencies?.registrations ?? [])
+            .filter((registration) => registration.creates === issue.file &&
+            (registration.owner === undefined || registration.owner === args.newFilename))
+            .map((registration) => ({ holder: entry.filename, registration })));
+        let accepted = false;
+        for (const { holder, registration } of declared) {
+            const lines = await readLines(join(args.engineDir, registration.file));
+            if (lines?.includes(registration.line.trim()) !== true)
+                continue;
+            outcome.accepted.push(`${issue.file} is registered by the working tree's ${registration.file} ` +
+                `("${registration.line.trim()}"), which ${holder} declares as a staged registration ` +
+                `but has not exported yet. Re-export ${holder} right after this export to land the ` +
+                `line: fireforge re-export ${holder}`);
+            accepted = true;
+            break;
+        }
+        if (accepted)
+            continue;
+        outcome.remaining.push(issue);
+        const tree = await findTreeRegistration(args.engineDir, issue.file);
+        if (tree === undefined)
+            continue;
+        const owner = args.baseCtx.entries.find((entry) => entry.metadata?.filesAffected.includes(tree.file))?.filename;
+        if (owner === undefined)
+            continue;
+        outcome.advice.push('', `${issue.file} is registered in the working tree's ${tree.file}, but ${owner} has not ` +
+            'exported that line. Land both without untangling the tree:', `  1. fireforge patch staged-dependency ${owner} --add --kind registration --file ${tree.file} ` +
+            `--line "${tree.line.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}" --creates ${issue.file} ` +
+            `--owner ${args.newFilename} ${STAGED_DEPENDENCY_REASON_PLACEHOLDER}`, '  2. re-run this export (a declared registration present in the working tree is accepted)', `  3. fireforge re-export ${owner}`);
+    }
+    return outcome;
+}

package/dist/src/commands/forward-import-remedy.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The remedy printed under a forward-import refusal from `re-export`
+ * (plain refresh and `--scan` adoption alike): the earliest order the files
+ * can take as their own later patch, and the exact `patch staged-dependency
+ * --add` commands that declare the edges instead.
+ *
+ * The refusal used to end with "export them with --order <n> or run
+ * patch staged-dependency --add", which left the operator to work out both
+ * the number and every flag of the declaration from the finding text.
+ */
+import type { PatchesManifest, PatchLintIssue } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+/** Inputs to {@link formatForwardImportRemedy}. */
+export interface ForwardImportRemedyInput {
+    /** What to do after the fix, e.g. "re-running the scan". */
+    reRunHint: string;
+    /** The refusal's findings; only `forward-import` and `forward-registration` ones are read. */
+    issues: readonly PatchLintIssue[];
+    /** Current manifest (null when unavailable: the order is then not named). */
+    manifest: PatchesManifest | null;
+    /** Project config; only `patchPolicy` is read. */
+    config?: Pick<FireForgeConfig, 'patchPolicy'>;
+    /** Category the files would be exported under (the refused patch's). */
+    category?: string;
+}
+/**
+ * Renders the remedy lines. Falls back to the generic sentence when the
+ * findings carry no structured declarations.
+ *
+ * @param input - See {@link ForwardImportRemedyInput}
+ */
+export declare function formatForwardImportRemedy(input: ForwardImportRemedyInput): string;

package/dist/src/commands/forward-import-remedy.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The remedy printed under a forward-import refusal from `re-export`
+ * (plain refresh and `--scan` adoption alike): the earliest order the files
+ * can take as their own later patch, and the exact `patch staged-dependency
+ * --add` commands that declare the edges instead.
+ *
+ * The refusal used to end with "export them with --order <n> or run
+ * patch staged-dependency --add", which left the operator to work out both
+ * the number and every flag of the declaration from the finding text.
+ */
+import { STAGED_DEPENDENCY_REASON_PLACEHOLDER } from '../core/patch-lint-staged-registration.js';
+import { earliestLegalOrderAfter } from '../core/patch-order-legal.js';
+import { formatPatchOrder } from '../core/patch-parse.js';
+function quoteArg(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+function declarationCommand(declaration) {
+    const anchor = declaration.kind === 'import'
+        ? `--specifier ${quoteArg(declaration.specifier ?? '')}`
+        : `--kind registration --line ${quoteArg(declaration.line ?? '')}`;
+    return (`fireforge patch staged-dependency ${declaration.patch} --add --file ${declaration.file} ` +
+        `${anchor} --creates ${declaration.creates} --owner ${declaration.owner} ` +
+        STAGED_DEPENDENCY_REASON_PLACEHOLDER);
+}
+/**
+ * Renders the remedy lines. Falls back to the generic sentence when the
+ * findings carry no structured declarations.
+ *
+ * @param input - See {@link ForwardImportRemedyInput}
+ */
+export function formatForwardImportRemedy(input) {
+    const declarations = input.issues
+        .filter((issue) => issue.check === 'forward-import' || issue.check === 'forward-registration')
+        .flatMap((issue) => issue.stagedDeclarations ?? []);
+    const ownerOrders = declarations
+        .map((declaration) => input.manifest?.patches.find((patch) => patch.filename === declaration.owner)?.order)
+        .filter((order) => order !== undefined);
+    const latestOwner = ownerOrders.length > 0 ? Math.max(...ownerOrders) : undefined;
+    const legalOrder = latestOwner !== undefined && input.manifest !== null && input.category !== undefined
+        ? earliestLegalOrderAfter(input.config ?? {}, input.manifest, input.category, latestOwner)
+        : null;
+    const orderText = legalOrder !== null
+        ? `"fireforge export <files> --order ${formatPatchOrder(legalOrder)}"; ` +
+            `${formatPatchOrder(legalOrder)} is the earliest legal order after the latest creator ` +
+            `(${formatPatchOrder(latestOwner ?? legalOrder)})`
+        : '"fireforge export --order <n>"';
+    const lines = [
+        `Export those files as their own later patch (${orderText}; or ` +
+            '"fireforge patch split --order <n>"), or declare the intentional dependency with ' +
+            `"fireforge patch staged-dependency --add" before ${input.reRunHint}` +
+            (declarations.length > 0 ? ':' : '.'),
+    ];
+    const seen = new Set();
+    for (const declaration of declarations) {
+        const command = declarationCommand(declaration);
+        if (seen.has(command))
+            continue;
+        seen.add(command);
+        lines.push(`  ${command}`);
+    }
+    return lines.join('\n');
+}

package/dist/src/commands/furnace/apply.js

@@ -2,7 +2,7 @@
 import { watch as fsWatch } from 'node:fs';
 import { loadConfig } from '../../core/config.js';
 import { applyAllComponents, computeComponentChecksums } from '../../core/furnace-apply.js';
-import { logApplyResult } from '../../core/furnace-apply-output.js';
+import { formatSkipBreakdown, logApplyResult } from '../../core/furnace-apply-output.js';
 import { getFurnacePaths } from '../../core/furnace-config.js';
 import { isComponentSourceFile } from '../../core/furnace-constants.js';
 import { runFurnaceMutation, waitLockMutationOptions } from '../../core/furnace-operation.js';
@@ -108,7 +108,7 @@ async function runWatchLoop(projectRoot) {
             }
             const applied = result.applied.length;
             const skipped = result.skipped.length;
-            info(`Re-applied: ${applied} applied, ${skipped} skipped`);
+            info(`Re-applied: ${applied} applied, ${skipped} skipped${formatSkipBreakdown(result.skipped)}`);
             retryNeeded = false;
             lastChecksums = await snapshotWatchedChecksums(watchDirs);
         }
@@ -318,7 +318,7 @@ export async function furnaceApplyCommand(projectRoot, name, options = {}) {
         outro(`Dry run complete — would apply ${appliedCount}, skip ${skippedCount}`);
     }
     else {
-        outro(`Applied ${appliedCount}, skipped ${skippedCount}`);
+        outro(`Applied ${appliedCount}, skipped ${skippedCount}${formatSkipBreakdown(result.skipped)}`);
     }
     // Watch mode: re-apply on file changes in component directories
     if (options.watch && !dryRun) {

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

@@ -2,8 +2,9 @@
  * `fireforge furnace chrome-doc remove <name>` removes the files and
  * registrations created by `furnace chrome-doc create`.
  */
+import type { FurnaceLockWaitable } from '../../types/commands/index.js';
 /** Options for `furnace chrome-doc remove`. */
-export interface FurnaceChromeDocRemoveOptions {
+export interface FurnaceChromeDocRemoveOptions extends FurnaceLockWaitable {
     /** Skip confirmation. Required for real non-interactive removal. */
     yes?: boolean;
     /** Print the removal plan without writing files. */

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

@@ -8,7 +8,7 @@ import { join } from 'node:path';
 import { confirm } from '@clack/prompts';
 import { loadConfig } from '../../core/config.js';
 import { stdioIsInteractive } from '../../core/destructive.js';
-import { completeJournalRollback, runFurnaceMutation, } from '../../core/furnace-operation.js';
+import { completeJournalRollback, runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
 import { assertFurnaceEngineReady } from '../../core/furnace-precondition.js';
 import { createRollbackJournal, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { FurnaceError } from '../../errors/furnace.js';
@@ -138,7 +138,7 @@ export async function furnaceChromeDocRemoveCommand(projectRoot, name, options =
         plan,
         binaryName: forgeConfig.binaryName,
         operationContext: ctx,
-    }));
+    }), waitLockMutationOptions(options.waitLockSeconds));
     info(`Removed ${result.removedFiles} source file${result.removedFiles === 1 ? '' : 's'} and ` +
         `${result.removedJarEntries} jar registration${result.removedJarEntries === 1 ? '' : 's'} for "${name}".`);
     if (result.removedTestDir) {

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

@@ -15,8 +15,9 @@
  * mid-scaffold restores every touched file. A successful run leaves the tree
  * ready for `fireforge build`.
  */
+import type { FurnaceLockWaitable } from '../../types/commands/index.js';
 /** Options for `furnace chrome-doc create`. */
-export interface FurnaceChromeDocCreateOptions {
+export interface FurnaceChromeDocCreateOptions extends FurnaceLockWaitable {
     /**
      * Emit the titlebar-buttonbox markup and leave platform window controls
      * visible. Defaults to `true` because the common case is a full chrome

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

@@ -19,7 +19,7 @@
 import { join } from 'node:path';
 import { loadConfig } from '../../core/config.js';
 import { furnaceConfigExists, loadFurnaceConfig } from '../../core/furnace-config.js';
-import { completeJournalRollback, runFurnaceMutation, } from '../../core/furnace-operation.js';
+import { completeJournalRollback, runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
 import { assertFurnaceEngineReady } from '../../core/furnace-precondition.js';
 import { createRollbackJournal, recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { DEFAULT_LICENSE, getLicenseHeader } from '../../core/license-headers.js';
@@ -343,7 +343,7 @@ export async function furnaceChromeDocCreateCommand(projectRoot, name, options =
         browserWindow,
         binaryName: forgeConfig.binaryName,
         operationContext: ctx,
-    }));
+    }), waitLockMutationOptions(options.waitLockSeconds));
     const nextSteps = [
         `  1. Edit engine/browser/base/content/${name}.xhtml and fill in the body.`,
         `  2. Localize strings in engine/browser/locales/en-US/browser/${name}.ftl.`,

package/dist/src/commands/furnace/create.js

@@ -5,7 +5,7 @@ import { getProjectPaths, loadConfig } from '../../core/config.js';
 import { stdioIsInteractive } from '../../core/destructive.js';
 import { getFurnacePaths, writeFurnaceConfig } from '../../core/furnace-config.js';
 import { resolveFtlChromeSubPath, tagNameToClassName, WIDGETS_DIR, } from '../../core/furnace-constants.js';
-import { completeJournalRollback, runFurnaceMutation, } from '../../core/furnace-operation.js';
+import { completeJournalRollback, runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
 import { CUSTOM_ELEMENT_TAG_PATTERN, CUSTOM_ELEMENT_TAG_RULES, describeTagNameProblem, } from '../../core/furnace-registration-validate.js';
 import { createRollbackJournal, recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { isComponentInEngine, scanWidgetsDirectory } from '../../core/furnace-scanner.js';
@@ -394,7 +394,7 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         testStyle,
         testDir,
         operationContext: ctx,
-    }));
+    }), waitLockMutationOptions(options.waitLockSeconds));
     note(formatSuccessNote({
         componentName,
         files,