@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/commands/patch/lint-ignore.js

@@ -1,11 +1,10 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge patch lint-ignore <name>` — adds, removes, or clears entries
+ * `fireforge patch lint-ignore <name>`: adds, removes, or clears entries
  * in `PatchMetadata.lintIgnore` without rewriting the `.patch` file body.
  *
  * Companion to `fireforge re-export <name> --lint-ignore <id>` (which is
- * append-only). Existence is justified by the cases re-export cannot
- * express:
+ * append-only). It exists for the cases re-export cannot express:
  * - Removing a single entry without dropping the rest of the list.
  * - Clearing the entire list when the operator wants the rule(s) to
  *   start firing again.
@@ -16,23 +15,24 @@
  * `--clear` must be supplied per invocation. The read-modify-write
  * happens inside the patch directory lock via {@link mutatePatchMetadata}
  * so a concurrent writer cannot interleave between the read and the
- * write — important when an operator scripts repeated invocations or
+ * write, which matters when an operator scripts repeated invocations or
  * runs `--add` and `--remove` back-to-back.
  */
 import { Command } from 'commander';
-import { appendHistory, confirmDestructive } from '../../core/destructive.js';
+import { confirmDestructive } from '../../core/destructive.js';
+import { appendHistoryBestEffort } from '../../core/history-log.js';
 import { mutatePatchMetadata } from '../../core/patch-export.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
-import { toError } from '../../utils/errors.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
 import { addWaitLockOption, resolveWaitLockSeconds, stringListOption, } from '../../utils/options.js';
+import { proceedAfterDecision } from '../destructive-decision.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
 /**
  * Printed whenever `--add` lands a new check id. The waiver this command
  * writes turns per-patch lint green immediately, but consumer projects
- * commonly audit lintIgnore lists against a reviewed allow-map — discovering
- * that the map also needs updating otherwise costs a full downstream gate
- * run.
+ * commonly audit lintIgnore lists against a reviewed allow-map, and
+ * discovering that the map also needs updating otherwise costs a full
+ * downstream gate run.
  */
 const LINT_IGNORE_REVIEW_WARNING = "This lint waiver is subject to the project's patch-policy review process. " +
     'Downstream policy audits that mirror lintIgnore lists in a reviewed allow-map ' +
@@ -65,7 +65,7 @@ function applyMode(existing, mode, values) {
  * `info()` / dry-run / history args. Exported for unit-testing the
  * message format directly without mocking the logger transport.
  */
-export function describeChange(before, after, mode, values) {
+function describeChange(before, after, mode, values) {
     const beforeSet = new Set(before);
     const afterSet = new Set(after);
     if (mode === 'clear') {
@@ -102,8 +102,8 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
     const isDryRun = options.dryRun === true;
     intro(isDryRun ? 'FireForge patch lint-ignore (dry run)' : 'FireForge patch lint-ignore');
     // Mode mutex: exactly one mode per invocation. Combinations like
-    // `--add foo --remove bar` are rejected — an operator who needs both
-    // runs the command twice (clearer audit trail) and `--clear` plus a
+    // `--add foo --remove bar` are rejected: an operator who needs both
+    // runs the command twice (clearer audit trail), and `--clear` plus a
     // mode is contradictory.
     const adding = (options.add?.length ?? 0) > 0;
     const removing = (options.remove?.length ?? 0) > 0;
@@ -122,8 +122,8 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
     // Destructive-operation contract (docs/lifecycle-invariants.md): manifest
     // metadata mutations get summary + dry-run + confirmation/--yes + history
     // uniformly. Accepting --yes without ever prompting makes the flag appear
-    // only in the history record — and suppressing lint findings is precisely
-    // the mutation an operator should consciously approve.
+    // only in the history record, and suppressing lint findings is the kind
+    // of mutation an operator should approve consciously.
     const currentList = target.lintIgnore ?? [];
     const projectedList = applyMode(currentList, mode, values) ?? [];
     const addsNewIds = mode === 'add' && projectedList.length > currentList.length;
@@ -135,30 +135,24 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
         yes: options.yes === true,
         dryRun: isDryRun,
     });
-    if (decision === 'dry-run') {
-        if (addsNewIds) {
-            warn(LINT_IGNORE_REVIEW_WARNING);
-        }
-        outro('Dry run complete — no changes made');
-        return;
+    if (decision === 'dry-run' && addsNewIds) {
+        warn(LINT_IGNORE_REVIEW_WARNING);
     }
-    if (decision === 'declined') {
-        outro('Cancelled — no changes made');
+    if (!proceedAfterDecision(decision, 'Cancelled — no changes made'))
         return;
-    }
     const result = await mutatePatchMetadata(paths.patches, target.filename, (existing) => {
         const next = applyMode(existing.lintIgnore ?? [], mode, values);
         // Either set the new list when non-empty or unset the field
         // entirely. The mutation API splits these to keep the
-        // exactOptionalPropertyTypes contract clean — only set values land
+        // exactOptionalPropertyTypes contract clean: only set values land
         // in the typed `Partial<PatchMetadata>`, and the unset list is
         // applied via `delete` after spread.
         return next !== undefined ? { set: { lintIgnore: next } } : { unset: ['lintIgnore'] };
     }, { waitLockSeconds: resolveWaitLockSeconds(options.waitLock), command: 'patch lint-ignore' });
     if (!result) {
         // Race: target vanished between the manifest read above and the
-        // locked mutate. Surfacing as a hard error rather than a silent
-        // no-op — the operator's intent did not land.
+        // locked mutate. Surfaced as a hard error rather than a silent
+        // no-op, because the operator's intent did not land.
         throw new GeneralError(`Patch ${target.filename} disappeared from the manifest during the update. Re-run after investigating.`);
     }
     const existing = result.before.lintIgnore ?? [];
@@ -167,23 +161,18 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
     if (mode === 'add' && projected.length > existing.length) {
         warn(LINT_IGNORE_REVIEW_WARNING);
     }
-    try {
-        await appendHistory(paths.patches, {
-            operation: 'patch-lint-ignore',
-            args: {
-                filename: target.filename,
-                mode,
-                values: [...values],
-                before: existing,
-                after: projected,
-            },
-            ...(options.yes === true ? { yes: true } : {}),
-            result: 'ok',
-        });
-    }
-    catch (historyError) {
-        warn(`History log append failed after patch lint-ignore committed (${target.filename}): ${toError(historyError).message}`);
-    }
+    await appendHistoryBestEffort(paths.patches, {
+        operation: 'patch-lint-ignore',
+        args: {
+            filename: target.filename,
+            mode,
+            values: [...values],
+            before: existing,
+            after: projected,
+        },
+        ...(options.yes === true ? { yes: true } : {}),
+        result: 'ok',
+    }, `patch lint-ignore committed (${target.filename})`);
     outro('Patch lint-ignore complete');
 }
 /**
@@ -205,7 +194,7 @@ export function registerPatchLintIgnore(parent, context) {
     addWaitLockOption(command).action(withErrorHandling(async (name, options) => {
         // Commander defaults `--add`/`--remove` to `[]` so they appear in
         // the options object even when unused. Strip empty arrays so
-        // `pickDefined` sees them as absent — otherwise the mode-count
+        // `pickDefined` sees them as absent. Otherwise the mode-count
         // mutex would treat zero-length arrays as a present mode.
         const normalized = {};
         if (options.add !== undefined && options.add.length > 0)

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

@@ -1,12 +1,12 @@
 /**
- * `fireforge patch move-files <from> <to> --create --order <n>` — creates
+ * `fireforge patch move-files <from> <to> --create --order <n>` creates
  * the target patch at the requested sparse order and moves the files into it
  * as one transaction. This is the transactional bootstrap of a split:
  * without it, moving files into a not-yet-existing patch requires a manual
  * shrink-then-export dance with hand-repointed staged-dependency owners.
  *
  * Mirrors `patch split` end-to-end (same planning, projection lint, policy
- * enforcement, and locked commit); the `<to>` argument becomes the new
+ * enforcement, and locked commit). The `<to>` argument becomes the new
  * patch's name/slug the way `split --name` does.
  */
 import type { PatchMoveFilesOptions } from '../../types/commands/index.js';

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

@@ -1,13 +1,13 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge patch move-files <from> <to> --create --order <n>` — creates
+ * `fireforge patch move-files <from> <to> --create --order <n>` creates
  * the target patch at the requested sparse order and moves the files into it
  * as one transaction. This is the transactional bootstrap of a split:
  * without it, moving files into a not-yet-existing patch requires a manual
  * shrink-then-export dance with hand-repointed staged-dependency owners.
  *
  * Mirrors `patch split` end-to-end (same planning, projection lint, policy
- * enforcement, and locked commit); the `<to>` argument becomes the new
+ * enforcement, and locked commit). The `<to>` argument becomes the new
  * patch's name/slug the way `split --name` does.
  */
 import { getProjectPaths, loadConfig } from '../../core/config.js';
@@ -15,10 +15,12 @@ import { assertConfirmationAvailable, confirmDestructive } from '../../core/dest
 import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { buildPatchQueueContext } from '../../core/patch-lint.js';
 import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-manifest.js';
+import { formatPatchOrder } from '../../core/patch-parse.js';
 import { enforcePatchPolicy } from '../../core/patch-policy.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { info, intro, outro, success } from '../../utils/logger.js';
 import { normalizePatchDisplayName } from '../../utils/validation.js';
+import { proceedAfterDecision } from '../destructive-decision.js';
 import { resolvePlacementPlan } from '../export-flow.js';
 import { runPatchLint } from '../export-shared.js';
 import { commitPatchSplit } from './split.js';
@@ -31,7 +33,7 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
     intro(options.dryRun === true
         ? 'FireForge patch move-files --create (dry run)'
         : 'FireForge patch move-files --create');
-    // Refuse a prompt-less run BEFORE the diff/lint work, not after it.
+    // Refuse a prompt-less run before the diff/lint work, not after it.
     assertConfirmationAvailable('patch move-files --create', options);
     const paths = getProjectPaths(projectRoot);
     const config = await loadConfig(projectRoot);
@@ -65,7 +67,7 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
     const placementOptions = { order: options.order };
     const placement = await resolvePlacementPlan(paths.patches, placementOptions, category, newPatchName, config);
     // The filename slug pipeline (resolvePlacementPlan above) strips redundant
-    // category prefixes; the manifest display name must agree with the bare-slug
+    // category prefixes. The manifest display name must agree with the bare-slug
     // naming policy, exactly as `export --name` already does.
     const displayName = normalizePatchDisplayName(newPatchName, category);
     if (displayName !== newPatchName) {
@@ -91,12 +93,30 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
     // The whole-queue context (built once, with the config so it carries the
     // same patch-policy shape as the committed `lint --per-patch` gate) makes
     // cross-patch `resource:///` imports and sibling head.js harness roots
-    // resolve exactly as they will after the move lands — without it the
+    // resolve exactly as they will after the move lands. Without it the
     // projection lint is blind.
     const patchQueueCtx = await buildPatchQueueContext(paths.patches, config);
     const ignoreChecks = source.lintIgnore ? new Set(source.lintIgnore) : undefined;
-    await runPatchLint(paths.engine, remainingFiles, remainingDiff, config, options.skipLint, patchQueueCtx, ignoreChecks, source.tier);
-    await runPatchLint(paths.engine, movedFiles, movedDiff, config, options.skipLint, patchQueueCtx, ignoreChecks, source.tier);
+    await runPatchLint({
+        engineDir: paths.engine,
+        filesAffected: remainingFiles,
+        diffContent: remainingDiff,
+        config,
+        skipLint: options.skipLint,
+        patchQueueCtx,
+        ignoreChecks,
+        patchTier: source.tier,
+    });
+    await runPatchLint({
+        engineDir: paths.engine,
+        filesAffected: movedFiles,
+        diffContent: movedDiff,
+        config,
+        skipLint: options.skipLint,
+        patchQueueCtx,
+        ignoreChecks,
+        patchTier: source.tier,
+    });
     const { conflicts, stagedDependencyAdditions } = runProjectedSplitLint(plan, patchQueueCtx);
     plan.stagedDependencyAdditions = stagedDependencyAdditions;
     const newMetadata = buildNewPatchMetadata(plan, config);
@@ -118,16 +138,10 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
         unsafeOverride: options.forceUnsafe === true,
         conflicts,
     });
-    if (decision === 'dry-run') {
-        outro('Dry run complete — no changes made');
+    if (!proceedAfterDecision(decision, 'Move cancelled'))
         return;
-    }
-    if (decision === 'declined') {
-        outro('Move cancelled');
-        return;
-    }
     await commitPatchSplit(paths.patches, plan, newMetadata, options, config);
-    success(`Created ${placement.newFilename} (order ${String(placement.insertionOrder).padStart(3, '0')}) ` +
+    success(`Created ${placement.newFilename} (order ${formatPatchOrder(placement.insertionOrder)}) ` +
         `and moved ${plan.movedFiles.length} file(s) out of ${source.filename}`);
     if (plan.ownerRewrites.length > 0) {
         info(`Re-pointed staged-dependency owners in: ${plan.ownerRewrites.join(', ')}`);

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

@@ -1,10 +1,10 @@
 /**
- * Transactional file-ownership move into an EXISTING patch.
+ * Transactional file-ownership move into an existing patch.
  *
  * A preview-only `patch move-files <from> <to>` prints two
  * `re-export --files` commands whose real execution costs three further
  * refusals (`--allow-shrink`, `--yes`, and a projected
- * `duplicate-new-file-creation` unless the SHRINK lands first — while the
+ * `duplicate-new-file-creation` unless the shrink lands first, while the
  * printed plan lists the grow first). This module performs the same
  * shrink→grow as one transaction under the patch-directory lock with
  * rollback, mirroring `patch split` / `move-files --create`.

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

@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Transactional file-ownership move into an EXISTING patch.
+ * Transactional file-ownership move into an existing patch.
  *
  * A preview-only `patch move-files <from> <to>` prints two
  * `re-export --files` commands whose real execution costs three further
  * refusals (`--allow-shrink`, `--yes`, and a projected
- * `duplicate-new-file-creation` unless the SHRINK lands first — while the
+ * `duplicate-new-file-creation` unless the shrink lands first, while the
  * printed plan lists the grow first). This module performs the same
  * shrink→grow as one transaction under the patch-directory lock with
  * rollback, mirroring `patch split` / `move-files --create`.
@@ -15,24 +15,21 @@
  * the worktree.
  */
 import { join } from 'node:path';
-import { appendHistory, assertConfirmationAvailable, confirmDestructive, } from '../../core/destructive.js';
-import { normalizePatchArtifact } from '../../core/patch-artifact-normalize.js';
-import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, collectForwardImportEdges, formatPatchLintIssue, lintPatchQueue, } from '../../core/patch-lint.js';
+import { assertConfirmationAvailable, confirmDestructive, } from '../../core/destructive.js';
+import { appendHistoryBestEffort } from '../../core/history-log.js';
+import { buildPatchQueueContext, collectForwardImportEdges, formatPatchLintIssue, lintPatchQueue, } from '../../core/patch-lint.js';
 import { computeProjectedLintRegressions } from '../../core/patch-lint-projection.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, savePatchesManifest, validatePatchesManifest, } from '../../core/patch-manifest.js';
-import { buildNewFileTextProjection } from '../../core/patch-transform.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { readText, writeText } from '../../utils/fs.js';
 import { info, outro, success, warn } from '../../utils/logger.js';
 import { resolveWaitLockSeconds } from '../../utils/options.js';
+import { proceedAfterDecision } from '../destructive-decision.js';
 import { runPatchLint } from '../export-shared.js';
+import { projectEntryBody } from './entry-projection.js';
 import { buildSplitDiff, findOwnerRewriteHolders, mergeStagedForwardImports, rewriteSplitOwners, } from './split-plan.js';
-function projectEntryBody(diff) {
-    const newFiles = buildNewFileTextProjection(diff);
-    return { diff, newFiles, modifiedFileAdditions: buildModifiedFileAdditionsFromDiff(diff) };
-}
 /**
  * Projects the post-move queue through cross-patch lint, auto-declaring the
  * forward edges the move introduces into the target (an importer that used
@@ -121,9 +118,9 @@ async function commitMoveInto(patchesDir, plan, waitLockSeconds) {
         let sourceWritten = false;
         let targetWritten = false;
         try {
-            await writeText(sourcePath, normalizePatchArtifact(plan.sourceDiff));
+            await writeText(sourcePath, plan.sourceDiff);
             sourceWritten = true;
-            await writeText(targetPath, normalizePatchArtifact(plan.targetDiff));
+            await writeText(targetPath, plan.targetDiff);
             targetWritten = true;
             const updatedPatches = manifest.patches.map((patch) => {
                 let updated = rewriteSplitOwners(patch, plan.source.filename, movedSet, plan.target.filename);
@@ -140,21 +137,16 @@ async function commitMoveInto(patchesDir, plan, waitLockSeconds) {
             });
             const updated = validatePatchesManifest({ ...manifest, patches: updatedPatches });
             await savePatchesManifest(patchesDir, updated);
-            try {
-                await appendHistory(patchesDir, {
-                    operation: 'patch-move-files',
-                    args: {
-                        source: plan.source.filename,
-                        target: plan.target.filename,
-                        files: plan.movedFiles,
-                        ownerRewrites: plan.ownerRewrites,
-                    },
-                    result: 'ok',
-                });
-            }
-            catch (historyError) {
-                warn(`History log append failed after patch move-files committed: ${toError(historyError).message}`);
-            }
+            await appendHistoryBestEffort(patchesDir, {
+                operation: 'patch-move-files',
+                args: {
+                    source: plan.source.filename,
+                    target: plan.target.filename,
+                    files: plan.movedFiles,
+                    ownerRewrites: plan.ownerRewrites,
+                },
+                result: 'ok',
+            }, `patch move-files committed`);
         }
         catch (error) {
             if (targetWritten) {
@@ -190,7 +182,7 @@ async function commitMoveInto(patchesDir, plan, waitLockSeconds) {
  */
 export async function runMoveFilesInto(args) {
     const { enginePath, patchesDir, source, target, files, sourceAfter, targetAfter, options } = args;
-    // Refuse a prompt-less run BEFORE the diff/lint work, not after it.
+    // Refuse a prompt-less run before the diff/lint work, not after it.
     assertConfirmationAvailable('patch move-files', options);
     const sourceDiff = await buildSplitDiff(enginePath, sourceAfter, 'remaining', source.filename);
     const targetDiff = await buildSplitDiff(enginePath, targetAfter, 'moved', target.filename);
@@ -199,8 +191,26 @@ export async function runMoveFilesInto(args) {
     // parity) resolves cross-patch imports and sibling head.js harness roots
     // instead of linting each projected body blind.
     const patchQueueCtx = await buildPatchQueueContext(patchesDir, args.config);
-    await runPatchLint(enginePath, sourceAfter, sourceDiff, args.config, options.skipLint, patchQueueCtx, source.lintIgnore ? new Set(source.lintIgnore) : undefined, source.tier);
-    await runPatchLint(enginePath, targetAfter, targetDiff, args.config, options.skipLint, patchQueueCtx, target.lintIgnore ? new Set(target.lintIgnore) : undefined, target.tier);
+    await runPatchLint({
+        engineDir: enginePath,
+        filesAffected: sourceAfter,
+        diffContent: sourceDiff,
+        config: args.config,
+        skipLint: options.skipLint,
+        patchQueueCtx,
+        ignoreChecks: source.lintIgnore ? new Set(source.lintIgnore) : undefined,
+        patchTier: source.tier,
+    });
+    await runPatchLint({
+        engineDir: enginePath,
+        filesAffected: targetAfter,
+        diffContent: targetDiff,
+        config: args.config,
+        skipLint: options.skipLint,
+        patchQueueCtx,
+        ignoreChecks: target.lintIgnore ? new Set(target.lintIgnore) : undefined,
+        patchTier: target.tier,
+    });
     const manifest = await loadPatchesManifest(patchesDir);
     const plan = {
         source,
@@ -231,14 +241,8 @@ export async function runMoveFilesInto(args) {
         unsafeOverride: options.forceUnsafe === true,
         conflicts,
     });
-    if (decision === 'dry-run') {
-        outro('Dry run complete — no changes made');
-        return;
-    }
-    if (decision === 'declined') {
-        outro('Move cancelled');
+    if (!proceedAfterDecision(decision, 'Move cancelled'))
         return;
-    }
     await commitMoveInto(patchesDir, plan, resolveWaitLockSeconds(options.waitLock));
     success(`Moved ${files.length} file(s) from ${source.filename} to ${target.filename}`);
     if (plan.ownerRewrites.length > 0) {

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

@@ -13,13 +13,10 @@ import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-ma
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { pathExists } from '../../utils/fs.js';
 import { info, intro, note, warn } from '../../utils/logger.js';
-import { addWaitLockOption, commanderArgParser, pickDefined } from '../../utils/options.js';
+import { addWaitLockOption, commanderArgParser, pickDefined, stringListOption, } from '../../utils/options.js';
+import { parsePositiveIntegerFlag } from '../../utils/validation.js';
 import { patchMoveFilesCreateCommand } from './move-files-create.js';
 import { runMoveFilesInto } from './move-files-into.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));
@@ -131,7 +128,7 @@ export async function patchMoveFilesCommand(projectRoot, fromIdentifier, toIdent
     note(formatFiles(targetAfter), `${target.filename} files after move`);
     // Manual fallback (e.g. when the worktree cannot carry both patches'
     // content right now): the equivalent re-export choreography, in
-    // EXECUTABLE order — the shrink must land before the grow, or the
+    // executable order. The shrink must land before the grow, or the
     // projected cross-patch lint refuses the pair with
     // duplicate-new-file-creation.
     const applySource = formatReExportCommand(source.filename, sourceAfter, [
@@ -165,15 +162,9 @@ export function registerPatchMoveFiles(parent, context) {
         .command('move-files <from> <to>')
         .description('Preview the re-export commands needed to move file ownership between patches, ' +
         'or create the target patch and move the files in one transaction with --create --order <n>.')
-        .option('--file <path>', 'File path relative to engine/ to move (repeatable)', collectOption, [])
+        .option('--file <path>', 'File path relative to engine/ to move (repeatable)', ...stringListOption())
         .option('--create', 'Create <to> as a new patch and move the files into it (requires --order)')
-        .option('--order <n>', 'Exact sparse order for the created patch (only valid with --create)', commanderArgParser((raw) => {
-        const n = Number.parseInt(raw, 10);
-        if (!Number.isInteger(n) || n <= 0) {
-            throw new InvalidArgumentError(`--order must be a positive integer, got "${raw}".`, '--order');
-        }
-        return n;
-    }))
+        .option('--order <n>', 'Exact sparse order for the created patch (only valid with --create)', commanderArgParser((raw) => parsePositiveIntegerFlag('--order', raw)))
         .option('--category <category>', "Category for the created patch (default: the source patch's)")
         .option('-d, --description <desc>', 'Description for the created patch')
         .option('--dry-run', 'Show what would happen without writing')

package/dist/src/commands/patch/patch-context.d.ts

@@ -10,7 +10,7 @@ import type { ProjectPaths } from '../../types/config.js';
 export interface PatchQueueContext {
     /** Project paths resolved from the project root. */
     paths: ProjectPaths;
-    /** The loaded manifest; guaranteed to contain at least one patch. */
+    /** The loaded manifest, guaranteed to contain at least one patch. */
     manifest: PatchesManifest;
 }
 /**

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

@@ -1,14 +1,14 @@
 /**
- * `fireforge patch rename <name>` — relabels a patch's filename, manifest
+ * `fireforge patch rename <name>`: relabels a patch's filename, manifest
  * `name`, and (optionally) `description` without rewriting the `.patch` file
  * body.
  *
  * Companion to `re-export --files <subset>`. Re-export shrinks the body and
  * `filesAffected` but leaves the patch's identity describing the pre-shrink
  * scope. The only alternative for that drift is `delete` + re-export, which
- * briefly removes the patch from the queue — any forward-import dependent
- * then refuses the re-export until the deleted patch's siblings are
- * rewritten.
+ * briefly removes the patch from the queue, and any forward-import
+ * dependent then refuses the re-export until the deleted patch's siblings
+ * are rewritten.
  *
  * The filename rename and the manifest mutation happen under the patch
  * directory lock so concurrent exports cannot allocate the new filename, and