@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -19,10 +19,20 @@ import { info, intro, outro, spinner } from '../utils/logger.js';
 import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../utils/options.js';
 import { renderDryRunPreview } from './export-flow.js';
 import { autoFixLicenseHeaders, promptExportPatchMetadata, runPatchLint, runSupersedeAndOverlapGates, } from './export-shared.js';
+/**
+ * The engine paths an export-all entry owns: its current file plus, for a
+ * rename, the path it came from. Spelled once because three call sites had
+ * copied the same `filter((value): value is string => !!value)` narrowing.
+ * @param entry - Export entry carrying `file` and an optional `originalPath`.
+ * @returns Both paths when the entry was renamed, otherwise just `file`.
+ */
+function ownedPaths(entry) {
+    return [entry.file, entry.originalPath].filter((value) => !!value);
+}
 async function checkBrandingManagedFiles(paths, config) {
     const changedFiles = await getWorkingTreeStatus(paths.engine);
     const brandingManagedFiles = changedFiles
-        .flatMap((entry) => [entry.file, entry.originalPath].filter((value) => !!value))
+        .flatMap((entry) => ownedPaths(entry))
         .filter((file) => isBrandingManagedPath(file, config.binaryName));
     if (brandingManagedFiles.length > 0) {
         throw new GeneralError('Export-all refuses to capture tool-managed branding changes by default.\n\n' +
@@ -46,13 +56,13 @@ async function resolveFurnaceExclusionPolicy(paths, projectRoot, excludeFurnace)
     if (prefixes.size === 0)
         return new Set();
     // Expand collapsed `?? dir/` entries before matching against Furnace
-    // prefixes — otherwise a Furnace-introduced directory slips past the
+    // prefixes, otherwise a Furnace-introduced directory slips past the
     // filter and later lands in the non-Furnace path list that feeds the
     // aggregate diff, where `getDiffForFilesAgainstHead` crashes with EISDIR.
     const rawStatus = await getWorkingTreeStatus(paths.engine);
     const changedFiles = await expandUntrackedDirectoryEntries(paths.engine, rawStatus);
     const furnaceManagedFiles = changedFiles
-        .flatMap((entry) => [entry.file, entry.originalPath].filter((value) => !!value))
+        .flatMap((entry) => ownedPaths(entry))
         .filter((file) => [...prefixes].some((prefix) => file.startsWith(prefix)));
     if (furnaceManagedFiles.length === 0)
         return new Set();
@@ -71,7 +81,7 @@ async function resolveFurnaceExclusionPolicy(paths, projectRoot, excludeFurnace)
  * `export-all --exclude-furnace` after `furnace create --localized
  * --with-tests` otherwise produces a patch that adds
  * `toolkit/content/widgets/<tag>/*` via jar.mn / customElements.js / locale
- * jar.mn while excluding the component source files themselves — a
+ * jar.mn while excluding the component source files themselves, a
  * structurally broken queue that `fireforge verify` stays silent about. The
  * operator is asked to either include the component sources (skip
  * `--exclude-furnace`) or revert the furnace changes before exporting.
@@ -124,7 +134,7 @@ async function checkDanglingFurnaceRegistrations(projectRoot, diff, furnaceExclu
  * path that some existing patch in the queue already creates. `verify`
  * detects this post-hoc via `collectNewFileCreatorsByPath`, but by the time
  * `verify` runs the operator has already landed a patch that irreversibly
- * sits atop the queue — resolving the conflict from there requires a
+ * sits atop the queue, and resolving the conflict from there requires a
  * `patch delete` or hand-surgery on `re-export --files`. Catching it here,
  * pre-write, keeps the queue clean and gives the operator a specific path
  * to narrow with `export` + explicit file scoping (which lets them drop
@@ -196,7 +206,7 @@ export async function exportAllCommand(projectRoot, options = {}) {
         const allChanged = await expandUntrackedDirectoryEntries(paths.engine, rawChanged);
         const nonFurnacePaths = [
             ...new Set(allChanged
-                .flatMap((entry) => [entry.file, entry.originalPath].filter((value) => !!value))
+                .flatMap((entry) => ownedPaths(entry))
                 .filter((file) => !furnaceExcluded.has(file))),
         ].sort();
         scopedExportPaths = nonFurnacePaths;
@@ -222,12 +232,12 @@ export async function exportAllCommand(projectRoot, options = {}) {
     await checkDuplicateNewFileCreations(paths, diff);
     // Dangling-furnace-registration preflight. Runs after the diff is
     // assembled so it can inspect the exact hunks the operator is about to
-    // land, and BEFORE any write so a refusal leaves the patches directory
+    // land, and before any write so a refusal leaves the patches directory
     // untouched.
     await checkDanglingFurnaceRegistrations(projectRoot, diff, furnaceExcluded);
     // Check for non-interactive mode
     const isInteractive = stdioIsInteractive();
-    // Auto-fix missing license headers on new files (interactive only;
+    // Auto-fix missing license headers on new files (interactive only, and
     // report-only under --dry-run so the preview never mutates engine/)
     const headersAdded = await autoFixLicenseHeaders(paths.engine, diff, config, isInteractive, isDryRun);
     if (headersAdded) {
@@ -241,7 +251,7 @@ export async function exportAllCommand(projectRoot, options = {}) {
         return;
     const { patchName, selectedCategory, description } = metadata;
     // Ensure patches directory exists. Skip during a dry-run so the command
-    // is purely read-only — `--dry-run` callers should be safe to invoke
+    // is purely read-only. `--dry-run` callers should be safe to invoke
     // against a project that has never exported a patch without leaving the
     // empty `patches/` directory behind.
     if (!isDryRun) {
@@ -254,12 +264,19 @@ export async function exportAllCommand(projectRoot, options = {}) {
         const patchQueueCtx = (await pathExists(paths.patches))
             ? await buildPatchQueueContext(paths.patches)
             : undefined;
-        await runPatchLint(paths.engine, filesAffected, diff, config, options.skipLint, patchQueueCtx);
+        await runPatchLint({
+            engineDir: paths.engine,
+            filesAffected,
+            diffContent: diff,
+            config,
+            skipLint: options.skipLint,
+            patchQueueCtx,
+        });
         // Dry-run: enumerate filename, metadata, and supersede coverage without
         // writing. Mirrors `fireforge export --dry-run` so the same preview
         // surface is available for both targeted and aggregate exports. Runs
-        // AFTER lint so the operator sees the same lint output they would on
-        // a real run; runs BEFORE the supersede confirmation prompt because
+        // after lint so the operator sees the same lint output they would on
+        // a real run. It runs before the supersede confirmation prompt because
         // confirming a dry-run is meaningless.
         if (isDryRun) {
             s.stop('Plan ready');

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

@@ -20,7 +20,7 @@ export interface PlacementPlan {
     renameMap: Map<string, PatchRenameEntry>;
 }
 /**
- * Structural equality for placement plans — used by placement-mode export
+ * Structural equality for placement plans. Used by placement-mode export
  * and `patch split` to verify the queue did not change between the
  * confirmed preview and the under-lock commit.
  */
@@ -40,14 +40,14 @@ export declare function computeExactPlacementPlan(manifestPatches: PatchMetadata
 /**
  * Resolves a placement plan from CLI flags against the current manifest.
  * When `config` is provided, positional plans (`--before`/`--after`) are
- * refused up front if their renumber would touch a reserved range — one
- * error for the whole shift instead of per-patch policy findings. The
+ * refused up front if their renumber would touch a reserved range, giving
+ * one error for the whole shift instead of per-patch policy findings. The
  * exact `--order` branch never renames, so it bypasses that gate.
  */
 export declare function resolvePlacementPlan(patchesDir: string, options: ExportOptions, category: PatchCategory, name: string, config?: FireForgeConfig): Promise<PlacementPlan>;
 /**
  * Projects the placement through cross-patch lint to detect forward-imports
- * the renumber would introduce *or* that the new patch itself would
+ * the renumber would introduce, or that the new patch itself would
  * introduce by landing earlier than one of its dependencies. Returns null
  * when the projection is clean.
  */
@@ -79,7 +79,7 @@ export interface CommitPlacementExportInput {
      * Optional post-commit hook that runs inside the patch directory lock,
      * after the mutation has succeeded but before the lock is released.
      * Intended for the caller's history-log append so the audit record
-     * lands atomically with the mutation — a crash between mutation and
+     * lands atomically with the mutation. A crash between mutation and
      * hook leaves no room for another process's history record to sneak
      * in first.
      *

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

@@ -10,14 +10,12 @@
 import { join } from 'node:path';
 import {} from '../core/destructive.js';
 import { detectMovedCodeOverlaps, formatAdoptThenSplitRemedy, } from '../core/export-moved-code-shape.js';
-import { normalizePatchArtifact } from '../core/patch-artifact-normalize.js';
-import { findAllPatchesForFilesWithDetails, patchNameSlug, planExport, } from '../core/patch-export.js';
-import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, lintPatchQueue, } from '../core/patch-lint.js';
+import { buildPlanExportInput, findAllPatchesForFilesWithDetails, patchNameSlug, planExport, } from '../core/patch-export.js';
+import { buildPatchQueueContext, lintPatchQueue } from '../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../core/patch-lock.js';
 import { addPatchToManifest, loadPatchesManifest, loadPatchesManifestForWrite, renumberPatchesInManifest, resolvePatchIdentifier, savePatchesManifest, } from '../core/patch-manifest.js';
-import { requirePatchOrder } from '../core/patch-parse.js';
+import { formatPatchOrder, requirePatchOrder } from '../core/patch-parse.js';
 import { applyRenameMapToManifest, buildProjectedManifest, enforcePatchPolicy, } from '../core/patch-policy.js';
-import { buildNewFileTextProjection } from '../core/patch-transform.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, removeFile, writeText } from '../utils/fs.js';
@@ -25,6 +23,8 @@ import { info, warn } from '../utils/logger.js';
 import { groupProjectedPlacementErrors } from './export-placement-conflicts.js';
 import { assertPlacementAvoidsReservedRanges } from './export-placement-policy.js';
 import { findPartialOwnershipOverlap } from './export-shared.js';
+import { projectEntryBody } from './patch/entry-projection.js';
+import { getSortedRenameEntries, renameMapsEqual } from './patch-rename-map.js';
 function buildFilenameForPlacement(category, name, order, width) {
     const padded = String(order).padStart(Math.max(3, width), '0');
     return `${padded}-${category}-${patchNameSlug(name, category)}.patch`;
@@ -35,11 +35,8 @@ function prefixWidthForPatches(manifestPatches, requestedOrder) {
         return Math.max(width, match?.[1]?.length ?? 3, String(requestedOrder).length);
     }, 3);
 }
-function getSortedRenameEntries(renameMap) {
-    return Array.from(renameMap.entries()).sort((a, b) => a[1].newOrder - b[1].newOrder);
-}
 /**
- * Structural equality for placement plans — used by placement-mode export
+ * Structural equality for placement plans. Used by placement-mode export
  * and `patch split` to verify the queue did not change between the
  * confirmed preview and the under-lock commit.
  */
@@ -47,20 +44,7 @@ export function placementPlansEqual(left, right) {
     if (left.insertionOrder !== right.insertionOrder || left.newFilename !== right.newFilename) {
         return false;
     }
-    const leftEntries = getSortedRenameEntries(left.renameMap);
-    const rightEntries = getSortedRenameEntries(right.renameMap);
-    if (leftEntries.length !== rightEntries.length) {
-        return false;
-    }
-    return leftEntries.every(([leftFilename, leftEntry], index) => {
-        const rightTuple = rightEntries[index];
-        if (!rightTuple)
-            return false;
-        const [rightFilename, rightEntry] = rightTuple;
-        return (leftFilename === rightFilename &&
-            leftEntry.newFilename === rightEntry.newFilename &&
-            leftEntry.newOrder === rightEntry.newOrder);
-    });
+    return renameMapsEqual(left.renameMap, right.renameMap);
 }
 /**
  * Computes the shift map that moves existing patches out of the requested
@@ -72,13 +56,13 @@ export function computePlacementPlan(manifestPatches, newPatchCategory, newPatch
     // Failing fast here prevents a NaN requestedOrder from producing a
     // filename like "NaN-ui-foo.patch".
     if (!Number.isInteger(requestedOrder) || requestedOrder <= 0) {
-        throw new InvalidArgumentError(`computePlacementPlan requires a positive integer order, got ${String(requestedOrder)}.`, 'requestedOrder');
+        throw new InvalidArgumentError(`computePlacementPlan requires a positive integer order, got ${requestedOrder}.`, 'requestedOrder');
     }
     const sorted = [...manifestPatches].sort((a, b) => a.order - b.order);
     const renameMap = new Map();
     const prefixWidth = prefixWidthForPatches(sorted, requestedOrder);
     // Patches at requestedOrder or later shift up by one, but only until the
-    // cascade reaches a free ordinal — a gap absorbs the insert, so the tail
+    // cascade reaches a free ordinal. A gap absorbs the insert, so the tail
     // beyond it (including any reserved block) keeps its numbering.
     let cursor = requestedOrder;
     for (const patch of sorted) {
@@ -90,7 +74,7 @@ export function computePlacementPlan(manifestPatches, newPatchCategory, newPatch
         }
         const newOrder = cursor + 1;
         const currentRest = patch.filename.replace(/^\d+-/, '');
-        const newFilename = `${String(newOrder).padStart(prefixWidth, '0')}-${currentRest}`;
+        const newFilename = `${formatPatchOrder(newOrder, prefixWidth)}-${currentRest}`;
         renameMap.set(patch.filename, { newOrder, newFilename });
         cursor = newOrder;
     }
@@ -109,11 +93,11 @@ export function computePlacementPlan(manifestPatches, newPatchCategory, newPatch
  */
 export function computeExactPlacementPlan(manifestPatches, newPatchCategory, newPatchName, requestedOrder) {
     if (!Number.isInteger(requestedOrder) || requestedOrder <= 0) {
-        throw new InvalidArgumentError(`--order must be a positive integer, got ${String(requestedOrder)}.`, '--order');
+        throw new InvalidArgumentError(`--order must be a positive integer, got ${requestedOrder}.`, '--order');
     }
     const occupied = manifestPatches.find((patch) => patch.order === requestedOrder);
     if (occupied) {
-        throw new InvalidArgumentError(`--order ${String(requestedOrder)} is already occupied by ${occupied.filename}. ` +
+        throw new InvalidArgumentError(`--order ${requestedOrder} is already occupied by ${occupied.filename}. ` +
             'Choose an unused order or use --before/--after for positional insertion.', '--order');
     }
     return {
@@ -125,22 +109,22 @@ export function computeExactPlacementPlan(manifestPatches, newPatchCategory, new
 /**
  * Resolves a placement plan from CLI flags against the current manifest.
  * When `config` is provided, positional plans (`--before`/`--after`) are
- * refused up front if their renumber would touch a reserved range — one
- * error for the whole shift instead of per-patch policy findings. The
+ * refused up front if their renumber would touch a reserved range, giving
+ * one error for the whole shift instead of per-patch policy findings. The
  * exact `--order` branch never renames, so it bypasses that gate.
  */
 export async function resolvePlacementPlan(patchesDir, options, category, name, config) {
-    // ForWrite: placement planning feeds a manifest rewrite; a corrupt
+    // ForWrite: placement planning feeds a manifest rewrite. A corrupt
     // manifest read as empty would allocate colliding orders.
     const manifest = await loadPatchesManifestForWrite(patchesDir);
     const existingPatches = manifest?.patches ?? [];
     let targetOrder;
     if (options.order !== undefined) {
-        // Defense-in-depth — argParser covers the CLI path, but this
+        // Defense-in-depth: argParser covers the CLI path, but this
         // function is called directly from the command body which could
         // reach here with a NaN/0/negative value passed in via test harness.
         if (!Number.isInteger(options.order) || options.order <= 0) {
-            throw new InvalidArgumentError(`--order must be a positive integer, got ${String(options.order)}.`, '--order');
+            throw new InvalidArgumentError(`--order must be a positive integer, got ${options.order}.`, '--order');
         }
         return computeExactPlacementPlan(existingPatches, category, name, options.order);
     }
@@ -168,7 +152,7 @@ export async function resolvePlacementPlan(patchesDir, options, category, name,
 }
 /**
  * Projects the placement through cross-patch lint to detect forward-imports
- * the renumber would introduce *or* that the new patch itself would
+ * the renumber would introduce, or that the new patch itself would
  * introduce by landing earlier than one of its dependencies. Returns null
  * when the projection is clean.
  */
@@ -181,8 +165,8 @@ export async function projectPlacementForLint(patchesDir, plan, diff, config) {
         return { ...entry, filename: rename.newFilename, order: rename.newOrder };
     });
     // Synthetic entry for the pending patch, populated with both its new-file
-    // content AND its added-line content for files it modifies, so the
-    // forward-import rule can inspect imports the patch *itself* authors —
+    // content and its added-line content for files it modifies, so the
+    // forward-import rule can inspect imports the patch itself authors,
     // 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.
@@ -190,9 +174,7 @@ export async function projectPlacementForLint(patchesDir, plan, diff, config) {
         filename: plan.newFilename,
         order: plan.insertionOrder,
         metadata: null,
-        diff,
-        newFiles: buildNewFileTextProjection(diff),
-        modifiedFileAdditions: buildModifiedFileAdditionsFromDiff(diff),
+        ...projectEntryBody(diff),
     });
     projectedEntries.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
     const policyRest = baseCtx.patchPolicy ? { patchPolicy: baseCtx.patchPolicy } : {};
@@ -202,9 +184,9 @@ export async function projectPlacementForLint(patchesDir, plan, diff, config) {
     }).filter((i) => i.severity === 'error');
     if (projectedIssues.length === 0)
         return null;
-    // Baseline lint over the UN-renumbered queue: an error present here is
-    // pre-existing breakage, not a consequence of this placement — calling
-    // it one would misattribute. Entries are already in memory,
+    // Baseline lint over the un-renumbered queue: an error present here is
+    // pre-existing breakage rather than a consequence of this placement, and
+    // calling it one would misattribute. Entries are already in memory,
     // so this second pass costs no additional IO.
     const baselineIssues = lintPatchQueue({
         entries: baseCtx.entries,
@@ -292,9 +274,9 @@ export async function commitPlacementExport(input) {
                 await renumberPatchesInManifest(input.patchesDir, currentPlan.renameMap);
                 renumberApplied = true;
             }
-            // Normalize identically to commitExportedPatch — the two export
+            // Normalize identically to commitExportedPatch: the two export
             // paths must produce one artifact contract for the same diff.
-            await writeText(patchPath, normalizePatchArtifact(input.diff));
+            await writeText(patchPath, input.diff);
             await addPatchToManifest(input.patchesDir, {
                 ...input.metadata,
                 filename: currentPlan.newFilename,
@@ -307,7 +289,7 @@ export async function commitPlacementExport(input) {
                 catch (hookError) {
                     // Mutation has already committed and is not reversible. Warn
                     // so operators know the audit trail has a gap, but do not
-                    // re-throw — that would look like the export itself failed.
+                    // re-throw, which would look like the export itself failed.
                     warn(`History log append failed after export committed (export-order, ${currentPlan.newFilename}): ` +
                         toError(hookError).message);
                 }
@@ -380,19 +362,7 @@ export async function renderDryRunPreview(input) {
     const overlap = manifest !== null
         ? findPartialOwnershipOverlap(manifest, input.filesAffected, supersedingFilenames)
         : new Map();
-    const plan = await planExport({
-        patchesDir: input.patchesDir,
-        category: input.category,
-        name: input.name,
-        description: input.description,
-        filesAffected: input.filesAffected,
-        sourceEsrVersion: input.sourceEsrVersion,
-        ...(input.sourceProduct !== undefined ? { sourceProduct: input.sourceProduct } : {}),
-        ...(input.sourceVersion !== undefined ? { sourceVersion: input.sourceVersion } : {}),
-        ...(input.tier !== undefined ? { tier: input.tier } : {}),
-        ...(input.lintIgnore !== undefined ? { lintIgnore: input.lintIgnore } : {}),
-        ...(input.config !== undefined ? { config: input.config } : {}),
-    });
+    const plan = await planExport(buildPlanExportInput(input));
     if (input.config !== undefined) {
         enforcePatchPolicy({
             config: input.config,
@@ -426,7 +396,7 @@ export async function renderDryRunPreview(input) {
     }
     if (overlap.size > 0) {
         const entries = [...overlap.entries()].sort(([a], [b]) => a.localeCompare(b));
-        warn(`\n[dry-run] Would create cross-patch ownership overlap on ${String(entries.length)} file${entries.length === 1 ? '' : 's'}:`);
+        warn(`\n[dry-run] Would create cross-patch ownership overlap on ${entries.length} file${entries.length === 1 ? '' : 's'}:`);
         for (const [file, owners] of entries) {
             warn(`  - ${file} already claimed by: ${owners.join(', ')}`);
         }

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

@@ -7,9 +7,9 @@ export interface PlacementAttributionPlan {
     renameMap: Map<string, PatchRenameEntry>;
 }
 /**
- * Partitions the projected placement errors into three labeled groups —
- * defects in the exported content, consequences of the renumbering, and
- * errors the queue already had — rendered as indented detail lines for
+ * Partitions the projected placement errors into three labeled groups
+ * (defects in the exported content, consequences of the renumbering, and
+ * errors the queue already had), rendered as indented detail lines for
  * {@link ConflictReport.details}. Grouping travels through the plain
  * `details: string[]`, so both refusal sites and confirmDestructive's
  * conflict printer show it without changes.

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

@@ -3,31 +3,31 @@
  * Attribution of projected placement lint errors, split out of
  * export-flow.ts for the line budget.
  *
- * A placement projection lints one merged queue — the renumbered existing
- * patches plus a synthetic entry for the pending patch — so a flat error
- * list reads as though the NEW patch caused every one of them. A renumbering
+ * A placement projection lints one merged queue (the renumbered existing
+ * patches plus a synthetic entry for the pending patch), so a flat error
+ * list reads as though the new patch caused every one of them. A renumbering
  * that re-evaluates pre-existing staged relationships (patch 455 importing a
  * module created by 456, legal only at their current ordinals) then sends
  * the operator auditing a perfectly fine export.
  *
- * Consumed by export-flow.ts; no top-level registrar is exported and none is
+ * Consumed by export-flow.ts. No top-level registrar is exported and none is
  * wanted.
  */
 import { formatPatchLintIssue } from '../core/patch-lint.js';
 /**
  * Identity for baseline comparison: check + site file + implicated
- * patches, with projected filenames mapped BACK through the rename map so
+ * patches, with projected filenames mapped back through the rename map so
  * a pre-existing error keeps its identity across the renumber. Never
- * parses the fingerprint — it is documented rename-sensitive.
+ * parses the fingerprint. It is documented rename-sensitive.
  */
 function issueKey(issue, mapBackToOldName) {
     const patches = (issue.patches ?? []).map(mapBackToOldName).sort((a, b) => a.localeCompare(b));
     return `${issue.check}|${issue.file}|${patches.join(',')}`;
 }
 /**
- * Partitions the projected placement errors into three labeled groups —
- * defects in the exported content, consequences of the renumbering, and
- * errors the queue already had — rendered as indented detail lines for
+ * Partitions the projected placement errors into three labeled groups
+ * (defects in the exported content, consequences of the renumbering, and
+ * errors the queue already had), rendered as indented detail lines for
  * {@link ConflictReport.details}. Grouping travels through the plain
  * `details: string[]`, so both refusal sites and confirmDestructive's
  * conflict printer show it without changes.
@@ -66,10 +66,10 @@ export function groupProjectedPlacementErrors(projectedErrors, baselineErrors, p
             details.push(`  ${formatPatchLintIssue(issue)}`);
         }
     };
-    pushGroup(`errors in the exported patch content (${String(exported.length)}):`, exported);
+    pushGroup(`errors in the exported patch content (${exported.length}):`, exported);
     pushGroup(`consequences of renumbering existing patches to make room at ordinal ` +
-        `${String(plan.insertionOrder)} (${String(renumbering.length)}) — these come from ` +
+        `${plan.insertionOrder} (${renumbering.length}) — these come from ` +
         'renumbering, NOT from the exported content:', renumbering);
-    pushGroup(`errors already present in the queue before this export (${String(preExisting.length)}):`, preExisting);
+    pushGroup(`errors already present in the queue before this export (${preExisting.length}):`, preExisting);
     return details;
 }

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

@@ -11,7 +11,7 @@ import { type PlacementPlan } from './export-flow.js';
 /**
  * Spreadable optional metadata (`tier`, `lintIgnore`) derived from the
  * export flags. Every manifest-row construction site in this command
- * shares this shape; with exactOptionalPropertyTypes the keys must be
+ * 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'>>;
@@ -22,7 +22,7 @@ export declare function patchMetadataExtras(options: ExportOptions): Partial<Pic
  * projected manifest, and routes destructive renumbers (or dry-runs)
  * through `confirmDestructive`. Returns the plan to commit, or `'stop'`
  * when the command should end here (dry-run rendered or operator
- * cancelled — the corresponding outro has already been printed).
+ * cancelled, and the corresponding outro has already been printed).
  */
 export declare function gatePlacementPlan(args: {
     patchesDir: string;

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

@@ -10,12 +10,12 @@ import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { applyRenameMapToManifest, buildProjectedManifest, enforcePatchPolicy, } from '../core/patch-policy.js';
 import { buildPatchSourceMetadata } from '../core/patch-source-metadata.js';
 import { InvalidArgumentError } from '../errors/base.js';
-import { outro } from '../utils/logger.js';
+import { proceedAfterDecision } from './destructive-decision.js';
 import { placementSummary, projectPlacementForLint, resolvePlacementPlan, } from './export-flow.js';
 /**
  * Spreadable optional metadata (`tier`, `lintIgnore`) derived from the
  * export flags. Every manifest-row construction site in this command
- * shares this shape; with exactOptionalPropertyTypes the keys must be
+ * shares this shape. With exactOptionalPropertyTypes the keys must be
  * omitted entirely (not set to undefined) when the flags are absent.
  */
 export function patchMetadataExtras(options) {
@@ -33,7 +33,7 @@ export function patchMetadataExtras(options) {
  * projected manifest, and routes destructive renumbers (or dry-runs)
  * through `confirmDestructive`. Returns the plan to commit, or `'stop'`
  * when the command should end here (dry-run rendered or operator
- * cancelled — the corresponding outro has already been printed).
+ * cancelled, and the corresponding outro has already been printed).
  */
 export async function gatePlacementPlan(args) {
     const { patchesDir, options, selectedCategory, patchName, description, filesAffected, diff, config, isDryRun, s, } = args;
@@ -41,7 +41,7 @@ export async function gatePlacementPlan(args) {
         throw new InvalidArgumentError('Placement flags (--order/--before/--after) cannot be combined with --supersede.', 'export placement');
     }
     // resolvePlacementPlan runs the reserved-range gate itself when config
-    // is passed — one up-front error per run instead of per-patch findings.
+    // is passed: one up-front error per run instead of per-patch findings.
     const placementPlan = await resolvePlacementPlan(patchesDir, options, selectedCategory, patchName, config);
     const currentManifest = await loadPatchesManifest(patchesDir);
     const conflicts = await projectPlacementForLint(patchesDir, placementPlan, diff, config);
@@ -70,9 +70,9 @@ export async function gatePlacementPlan(args) {
     const summary = placementSummary(placementPlan);
     const renameCount = placementPlan.renameMap.size;
     // Route through confirmDestructive when the operation is destructive
-    // enough to warrant a prompt (more than one rename) OR when the user asked
+    // enough to warrant a prompt (more than one rename) or when the user asked
     // for a dry-run. The dry-run branch must always print the placement
-    // summary; otherwise single-rename and no-rename dry-runs exit silently
+    // summary. Otherwise single-rename and no-rename dry-runs exit silently
     // with no filename or projected layout.
     if (renameCount > 1 || isDryRun) {
         s.stop();
@@ -85,14 +85,8 @@ export async function gatePlacementPlan(args) {
             unsafeOverride: options.forceUnsafe === true,
             conflicts,
         });
-        if (decision === 'dry-run') {
-            outro('Dry run complete — no changes made');
+        if (!proceedAfterDecision(decision, 'Export cancelled'))
             return 'stop';
-        }
-        if (decision === 'declined') {
-            outro('Export cancelled');
-            return 'stop';
-        }
     }
     else if (conflicts && options.forceUnsafe !== true) {
         s.stop();

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

@@ -12,7 +12,7 @@ export interface PlacementPolicyPlan {
 }
 /**
  * Refuses positional placement plans whose renumber would touch a
- * `patchPolicy.reservedRanges` block — either by moving a patch INTO a
+ * `patchPolicy.reservedRanges` block, either by moving a patch into a
  * reserved range or by moving a patch that currently sits inside one.
  * Throws a single up-front error for the first reserved range hit (the
  * per-patch alternative surfaced one confusing finding per shifted

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

@@ -2,10 +2,8 @@
 /**
  * Policy-aware checks for export placement plans.
  */
+import { formatOrderRange, formatPatchOrder } from '../core/patch-parse.js';
 import { InvalidArgumentError } from '../errors/base.js';
-function reservedRangeLabel(range) {
-    return `${String(range.from).padStart(3, '0')}-${String(range.to).padStart(3, '0')}`;
-}
 function findReservedRange(config, order) {
     return (config.patchPolicy?.reservedRanges?.find((range) => order >= range.from && order <= range.to) ??
         null);
@@ -25,7 +23,7 @@ function firstFreeOrderBelowReservedRange(patches, range) {
 }
 /**
  * Refuses positional placement plans whose renumber would touch a
- * `patchPolicy.reservedRanges` block — either by moving a patch INTO a
+ * `patchPolicy.reservedRanges` block, either by moving a patch into a
  * reserved range or by moving a patch that currently sits inside one.
  * Throws a single up-front error for the first reserved range hit (the
  * per-patch alternative surfaced one confusing finding per shifted
@@ -42,11 +40,11 @@ export function assertPlacementAvoidsReservedRanges(plan, manifestPatches, confi
             (oldOrder !== undefined ? findReservedRange(config, oldOrder) : null);
         if (reserved === null)
             continue;
-        const label = reservedRangeLabel(reserved);
+        const label = formatOrderRange(reserved);
         const freeOrder = firstFreeOrderBelowReservedRange(manifestPatches, reserved);
         if (freeOrder !== null) {
             throw new InvalidArgumentError(`Positional insert would renumber the reserved range ${label}; ` +
-                `pass --order ${String(freeOrder).padStart(3, '0')} (first free order below the ` +
+                `pass --order ${formatPatchOrder(freeOrder)} (first free order below the ` +
                 'reserved block) to place the new patch without renumbering reserved patches.', 'export placement');
         }
         throw new InvalidArgumentError(`Positional insert would renumber the reserved range ${label}; ` +