@hominis/fireforge 0.13.1 → 0.14.0

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

@@ -135,13 +135,16 @@ async function restoreOverrideEngineFiles(engineDir, overrideDir, overrideConfig
  * the failure.
  */
 async function cleanupCustomTestFiles(name, projectRoot, journal) {
+    const partialFailures = [];
     let forgeConfig;
     try {
         forgeConfig = await loadConfig(projectRoot);
     }
     catch (error) {
-        warn(`Could not load config for test cleanup — ${toError(error).message}. Remove test files manually if needed.`);
-        return;
+        const msg = `Could not load config for test cleanup — ${toError(error).message}. Remove test files manually if needed.`;
+        warn(msg);
+        partialFailures.push(msg);
+        return { partialFailures };
     }
     const paths = getProjectPaths(projectRoot);
     const binaryName = forgeConfig.binaryName;
@@ -153,7 +156,7 @@ async function cleanupCustomTestFiles(name, projectRoot, journal) {
     const testFileName = `browser_${binaryName}_${underscored}.js`;
     const testDir = join(paths.engine, 'browser/base/content/test', binaryName);
     if (!(await pathExists(testDir)))
-        return;
+        return { partialFailures };
     // Step 1: Delete the test file itself
     try {
         const testFilePath = join(testDir, testFileName);
@@ -164,7 +167,9 @@ async function cleanupCustomTestFiles(name, projectRoot, journal) {
         }
     }
     catch (error) {
-        warn(`Could not delete test file ${testFileName} — ${toError(error).message}. Remove it manually if needed.`);
+        const msg = `Could not delete test file ${testFileName} — ${toError(error).message}. Remove it manually if needed.`;
+        warn(msg);
+        partialFailures.push(msg);
     }
     // Step 2: Remove the test entry from browser.toml
     try {
@@ -180,7 +185,9 @@ async function cleanupCustomTestFiles(name, projectRoot, journal) {
         }
     }
     catch (error) {
-        warn(`Could not update browser.toml — ${toError(error).message}. Remove the test entry manually if needed.`);
+        const msg = `Could not update browser.toml — ${toError(error).message}. Remove the test entry manually if needed.`;
+        warn(msg);
+        partialFailures.push(msg);
     }
     // Step 3: Clean up empty test directory and deregister from moz.build
     try {
@@ -198,8 +205,11 @@ async function cleanupCustomTestFiles(name, projectRoot, journal) {
         }
     }
     catch (error) {
-        warn(`Could not clean up test directory — ${toError(error).message}. Remove it manually if needed.`);
+        const msg = `Could not clean up test directory — ${toError(error).message}. Remove it manually if needed.`;
+        warn(msg);
+        partialFailures.push(msg);
     }
+    return { partialFailures };
 }
 function dropChecksumsByPrefix(state, prefix) {
     const result = { ...state };
@@ -211,6 +221,38 @@ function dropChecksumsByPrefix(state, prefix) {
     }
     return result;
 }
+/**
+ * Confirms the remove operation interactively when TTY is available, or
+ * enforces the `--yes` contract in non-interactive mode. Returns `false`
+ * when the user cancelled and the caller should exit silently.
+ */
+async function confirmFurnaceRemove(name, type, options, isInteractive) {
+    if (!isInteractive && !options.yes) {
+        throw new FurnaceError(`Cannot remove "${name}" in non-interactive mode without --yes flag.`, name);
+    }
+    if (!options.yes && isInteractive) {
+        const confirmed = await confirm({
+            message: `Remove ${type} component "${name}"?`,
+        });
+        if (isCancel(confirmed) || !confirmed) {
+            cancel('Remove cancelled');
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Enforces the engine-as-git precondition for both override and custom
+ * removals. Runs BEFORE the lock is acquired or a journal is registered so
+ * the failure path does not involve any rollback infrastructure.
+ */
+async function requireGitEngineForRemove(type, name, engineDir) {
+    if (type !== 'override' && type !== 'custom')
+        return;
+    if (!(await isGitRepository(engineDir))) {
+        throw new FurnaceError(`Cannot remove ${type} component "${name}": engine is not a git repository. Run "fireforge download" to initialise it.`, name);
+    }
+}
 /**
  * Runs the furnace remove command to remove a component from the workspace.
  * @param projectRoot - Root directory of the project
@@ -229,19 +271,8 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
     if (!type) {
         throw new FurnaceError(`Component "${name}" not found in furnace.json. Run "fireforge furnace list" to see registered components.`, name);
     }
-    // Require --yes in non-interactive mode to prevent silent removals
-    if (!isInteractive && !options.yes) {
-        throw new FurnaceError(`Cannot remove "${name}" in non-interactive mode without --yes flag.`, name);
-    }
-    // Confirm removal (skip if --yes)
-    if (!options.yes && isInteractive) {
-        const confirmed = await confirm({
-            message: `Remove ${type} component "${name}"?`,
-        });
-        if (isCancel(confirmed) || !confirmed) {
-            cancel('Remove cancelled');
-            return;
-        }
+    if (!(await confirmFurnaceRemove(name, type, options, isInteractive))) {
+        return;
     }
     // Begin transactional mutation: every file deleted or rewritten is first
     // snapshotted in a rollback journal so any failure mid-removal restores the
@@ -249,6 +280,7 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
     // the furnace-wide lock and is registered with the global SIGINT/SIGTERM
     // rollback pathway.
     const paths = getProjectPaths(projectRoot);
+    await requireGitEngineForRemove(type, name, paths.engine);
     await runFurnaceMutation(projectRoot, 'remove-rollback', async (ctx) => {
         const journal = createRollbackJournal();
         ctx.registerJournal(journal);
@@ -279,6 +311,12 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
             }
             else if (type === 'custom') {
                 const customConfig = config.custom[name];
+                // Custom-component removal mutates engine files (jar.mn,
+                // customElements.js, deployed widgets, optional .ftl) and the
+                // rollback journal is the only safety net for those edits while
+                // the command runs. The git-as-engine precondition is enforced
+                // before the lock is acquired (see furnaceRemoveCommand above)
+                // so if we reach this point, the engine is a git repository.
                 if (customConfig?.register) {
                     // customElements.js is the only file removeCustomElementRegistration touches.
                     await snapshotFile(journal, join(paths.engine, 'toolkit/content/customElements.js'));
@@ -317,8 +355,10 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
                     }
                 }
             }
+            let testCleanupFailures = [];
             if (type === 'custom') {
-                await cleanupCustomTestFiles(name, projectRoot, journal);
+                const result = await cleanupCustomTestFiles(name, projectRoot, journal);
+                testCleanupFailures = result.partialFailures;
             }
             // Remove entry from furnace.json
             if (type === 'stock') {
@@ -337,6 +377,14 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
             // entire remove operation is a single atomic unit.
             await snapshotFile(journal, furnacePaths.furnaceState);
             await updateFurnaceState(projectRoot, (state) => dropChecksumsByPrefix(state, `${type}/${name}/`));
+            // Test-cleanup failures are warn-and-continue by design (test files
+            // are secondary artefacts), but the caller deserves a single summary
+            // line pointing at the residue so they don't have to re-scan earlier
+            // warn output to realise the removal was partial.
+            if (testCleanupFailures.length > 0) {
+                warn(`Component "${name}" removed with ${testCleanupFailures.length} test-cleanup warning(s) above. ` +
+                    `The component is deregistered, but test files may linger in the engine — review and delete manually if needed.`);
+            }
         }
         catch (error) {
             try {

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

@@ -14,6 +14,26 @@ import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { copyFile, ensureDir, pathExists, readText, removeDir, removeFile, writeText, } from '../../utils/fs.js';
 import { info, intro, note, outro, warn } from '../../utils/logger.js';
+/** Escapes regex metacharacters so a user-supplied name is literal inside a RegExp. */
+function escapeRegex(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Applies the component rename to a filename. Only replaces the leading
+ * component name when it is followed by `.` (extension) or equals the
+ * filename exactly; every other filename is returned unchanged so stray
+ * assets, editor backups, or files whose name coincidentally contains the
+ * old component name in the middle or at the end are not accidentally
+ * renamed.
+ */
+function renameComponentFileName(fileName, oldName, newName) {
+    if (fileName === oldName)
+        return newName;
+    if (fileName.startsWith(oldName + '.')) {
+        return newName + fileName.slice(oldName.length);
+    }
+    return fileName;
+}
 function updateConfigForCustomRename(config, oldName, newName) {
     const oldConfig = config.custom[oldName];
     if (!oldConfig)
@@ -122,7 +142,15 @@ async function performRenameMutations(args) {
                 if (!entry.isFile())
                     continue;
                 const oldFileName = entry.name;
-                const newFileName = oldFileName.replace(oldName, newName);
+                // Rename only when the filename starts with the component name — the
+                // scaffolding convention for both create and override is `${name}.ext`.
+                // A plain `replace(oldName, newName)` produced wrong results when the
+                // old name occurred more than once (e.g. `foo-foo.mjs` renamed `foo` →
+                // `bar` became `bar-foo.mjs` instead of `bar-bar.mjs`) and also when
+                // the old name appeared inside a file that was not the component
+                // scaffold itself (e.g. a sibling helper). Unrelated files (stray
+                // assets, editor backups) are copied verbatim.
+                const newFileName = renameComponentFileName(oldFileName, oldName, newName);
                 const oldPath = join(oldDir, oldFileName);
                 const newPath = join(newDir, newFileName);
                 if (isComponentSourceFile(oldFileName)) {
@@ -130,8 +158,8 @@ async function performRenameMutations(args) {
                     // Use word-boundary-aware patterns so substrings in other
                     // identifiers (e.g. "moz-panel" inside "moz-panel-group") are
                     // not replaced.
-                    const tagPattern = new RegExp(`(?<![\\w-])${oldName.replace(/-/g, '\\-')}(?![\\w-])`, 'g');
-                    const classPattern = new RegExp(`\\b${oldClassName}\\b`, 'g');
+                    const tagPattern = new RegExp(`(?<![\\w-])${escapeRegex(oldName)}(?![\\w-])`, 'g');
+                    const classPattern = new RegExp(`\\b${escapeRegex(oldClassName)}\\b`, 'g');
                     content = content.replace(tagPattern, newName);
                     content = content.replace(classPattern, newClassName);
                     await writeText(newPath, content);

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

@@ -58,6 +58,14 @@ async function promptAddComponents(components, tracked, projectRoot) {
         await snapshotFile(journal, furnacePaths.furnaceConfig);
         try {
             const config = await ensureFurnaceConfig(projectRoot);
+            // Defensive: `selected` is already filtered to exclude components
+            // currently in config.stock (see untrackedComponents above). This
+            // re-filter catches the edge case where the config on disk changed
+            // between the scan's read and the write (concurrent scan / manual
+            // edit). Without it a duplicate scan would introduce duplicate
+            // entries into stock; writeFurnaceConfig's validator would then
+            // reject the write, but the error would be less actionable than
+            // silently de-duplicating here.
             const toAdd = selected.filter((s) => !config.stock.includes(s));
             config.stock.push(...toAdd);
             await writeFurnaceConfig(projectRoot, config);

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

@@ -43,9 +43,17 @@ async function autoFixIssues(projectRoot, issues) {
     // Fix jar.mn entries
     for (const [componentName, files] of jarMnFixesByComponent) {
         try {
-            await addJarMnEntries(engineDir, componentName, files);
-            fixed += files.length;
-            info(`Fixed: added ${files.join(', ')} to jar.mn for ${componentName}`);
+            // addJarMnEntries is idempotent and reports how many entries it
+            // actually wrote. Only count + log the files that were added so the
+            // reported "fixed" number matches the on-disk change.
+            const added = await addJarMnEntries(engineDir, componentName, files);
+            fixed += added;
+            if (added > 0) {
+                info(`Fixed: added ${files.join(', ')} to jar.mn for ${componentName}`);
+            }
+            else {
+                info(`No-op: jar.mn entries for ${componentName} were already present`);
+            }
         }
         catch (err) {
             warn(`Could not fix jar.mn for ${componentName}: ${err instanceof Error ? err.message : String(err)}`);
@@ -162,13 +170,30 @@ export async function furnaceValidateCommand(projectRoot, name, options = {}) {
             }
         }
     }
-    // Auto-fix fixable issues when --fix is passed
+    // Auto-fix fixable issues when --fix is passed. The auto-fix counter
+    // returned by `autoFixIssues` only counts function calls that did not
+    // throw — a write that succeeded but did not actually resolve the issue
+    // (e.g. addJarMnEntries appended to a file mach later ignores) would
+    // still bump the count. Re-validate the affected components and compute
+    // the *actual* drop in fixable issues so the reported number is honest.
     if (options.fix && allIssues.length > 0) {
         const fixableIssues = allIssues.filter((issue) => FIXABLE_CHECKS.has(issue.check));
         if (fixableIssues.length > 0) {
-            const fixedCount = await autoFixIssues(projectRoot, fixableIssues);
-            if (fixedCount > 0) {
-                info(`\nAuto-fixed ${fixedCount} issue(s). Re-run validate to confirm.`);
+            await autoFixIssues(projectRoot, fixableIssues);
+            const reValidated = await reValidateComponents(projectRoot, config, furnacePaths, new Set(fixableIssues.map((issue) => issue.component)));
+            const fixableBefore = fixableIssues.length;
+            const fixableAfter = reValidated.issues.filter((issue) => FIXABLE_CHECKS.has(issue.check)).length;
+            const actuallyFixed = Math.max(0, fixableBefore - fixableAfter);
+            // Replace the pre-fix issue totals with the post-fix view so the
+            // summary reflects current reality. Issues that auto-fix could not
+            // address still count toward totalErrors / totalWarnings.
+            totalErrors = reValidated.totalErrors;
+            totalWarnings = reValidated.totalWarnings;
+            if (actuallyFixed > 0) {
+                info(`\nAuto-fixed ${actuallyFixed} issue(s).`);
+            }
+            if (fixableAfter > 0) {
+                warn(`${fixableAfter} fixable issue(s) remain after auto-fix — investigate manually.`);
             }
         }
         else {
@@ -184,4 +209,42 @@ export async function furnaceValidateCommand(projectRoot, name, options = {}) {
     }
     outro('Validation passed');
 }
+/**
+ * Re-validates a specific set of components after an auto-fix pass and
+ * returns the post-fix issue list with the recomputed error / warning
+ * totals. Used by the `--fix` path to honestly report what auto-fix
+ * actually accomplished.
+ */
+async function reValidateComponents(projectRoot, config, furnacePaths, componentNames) {
+    const issues = [];
+    let totalErrors = 0;
+    let totalWarnings = 0;
+    for (const componentName of componentNames) {
+        let type;
+        let componentDir;
+        if (componentName in config.overrides) {
+            type = 'override';
+            componentDir = join(furnacePaths.overridesDir, componentName);
+        }
+        else if (componentName in config.custom) {
+            type = 'custom';
+            componentDir = join(furnacePaths.customDir, componentName);
+        }
+        else {
+            // Stock or removed components are not local-validated; skip silently.
+            continue;
+        }
+        if (!(await pathExists(componentDir)))
+            continue;
+        const componentIssues = await validateComponent(componentDir, componentName, type, config, projectRoot);
+        issues.push(...componentIssues);
+        for (const issue of componentIssues) {
+            if (issue.severity === 'error')
+                totalErrors += 1;
+            else
+                totalWarnings += 1;
+        }
+    }
+    return { issues, totalErrors, totalWarnings };
+}
 //# sourceMappingURL=validate.js.map

package/dist/src/commands/import.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { confirm } from '@clack/prompts';
-import { getProjectPaths, loadConfig, loadState, saveState } from '../core/config.js';
+import { getProjectPaths, loadConfig, loadState, updateState } from '../core/config.js';
 import { getHead } from '../core/git.js';
 import { getDirtyFiles } from '../core/git-status.js';
 import { applyPatchesWithContinue, computePatchedContent, countPatches, discoverPatches, extractAffectedFiles, PatchError, } from '../core/patch-apply.js';
@@ -11,6 +11,19 @@ import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { error, info, intro, isCancel, outro, spinner, success, verbose, warn, } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
+/**
+ * Errno codes for filesystem-level failures against the working file.
+ * These are safe to fall through as "unmanaged" because they describe the
+ * *state of the engine directory*, not the integrity of the patch stack.
+ * Manifest / patch-parse / PatchError failures do NOT match this set and
+ * are re-thrown so the root cause surfaces instead of being silently
+ * reclassified as a spurious dirty file.
+ */
+const SAFE_IO_FALLBACK_CODES = new Set(['ENOENT', 'EACCES', 'EPERM', 'EISDIR', 'EBUSY']);
+function isSafeIoFallback(error) {
+    const code = error?.code;
+    return typeof code === 'string' && SAFE_IO_FALLBACK_CODES.has(code);
+}
 async function getUnmanagedDirtyFiles(engineDir, patchesDir, dirtyFiles) {
     const classifications = await Promise.all(dirtyFiles.map(async (file) => {
         try {
@@ -22,7 +35,19 @@ async function getUnmanagedDirtyFiles(engineDir, patchesDir, dirtyFiles) {
             return actual === expected ? null : file;
         }
         catch (error) {
-            verbose(`Treating ${file} as unmanaged because patched-content classification failed: ${toError(error).message}`);
+            // PatchError, manifest corruption, and patch-parse failures are
+            // *structural* problems with the patch stack — masking them as
+            // "unmanaged dirty file" would let the user `--force` past a real
+            // root cause (e.g. "patch 003 missing from manifest") and compound
+            // the corruption. Only swallow the pure-IO fallback cases where
+            // the working file itself can't be read.
+            if (error instanceof PatchError) {
+                throw error;
+            }
+            if (!isSafeIoFallback(error)) {
+                throw error;
+            }
+            verbose(`Treating ${file} as unmanaged because patched-content classification failed with IO error: ${toError(error).message}`);
             return file;
         }
     }));
@@ -64,14 +89,22 @@ async function checkUncommittedPatchFiles(engineDir, patchesDir, forceImport) {
         }
     }
 }
-async function handlePatchFailures(summary, state, projectRoot) {
+async function handlePatchFailures(summary, projectRoot) {
     const firstFailed = summary.failed[0];
     if (firstFailed) {
-        state.pendingResolution = {
-            patchFilename: firstFailed.patch.filename,
-            originalError: firstFailed.error ?? 'Unknown error',
-        };
-        await saveState(projectRoot, state);
+        // Transactional update rather than `loadState` + mutate + `saveState`. The
+        // caller captures `state` at the start of the import run, and the run can
+        // span a long window (drift-check prompt, patch apply loop). A concurrent
+        // command (`fireforge download`, `rebase`, another state mutation) writing
+        // unrelated fields during that window would be silently clobbered when the
+        // stale state object was written back.
+        await updateState(projectRoot, (current) => ({
+            ...current,
+            pendingResolution: {
+                patchFilename: firstFailed.patch.filename,
+                originalError: firstFailed.error ?? 'Unknown error',
+            },
+        }));
     }
     for (const result of summary.failed) {
         error(`\nFailed: ${result.patch.filename}`);
@@ -187,14 +220,35 @@ export async function importCommand(projectRoot, options = {}) {
             }
         }
     }
-    // Validate patch integrity (detect orphaned modification patches)
+    // Validate patch integrity (detect orphaned modification patches). Warn
+    // and prompt the operator to confirm before proceeding — the legacy
+    // warn-and-continue behaviour hid the real root cause because import
+    // would later fail during patch application with a secondary, unrelated
+    // error that made diagnosis harder.
     const integrityIssues = await validatePatchIntegrity(paths.patches, paths.engine);
     if (integrityIssues.length > 0) {
         warn('\nPatch integrity issues detected:');
         for (const issue of integrityIssues) {
             warn(`  ${issue.filename}: ${issue.message}`);
         }
-        info('Run "fireforge doctor" for more details.\n');
+        info('Run "fireforge doctor" for more details.');
+        if (forceImport) {
+            warn('Continuing because --force was provided. Integrity issues were not resolved.\n');
+        }
+        else if (!process.stdin.isTTY) {
+            throw new GeneralError(`Refusing to import while ${integrityIssues.length} patch integrity issue(s) are unresolved. ` +
+                `Fix the issues reported above (see "fireforge doctor") or re-run with --force to continue anyway.`);
+        }
+        else {
+            const shouldContinue = await confirm({
+                message: 'Patch integrity issues detected. Continuing may fail with cascading errors during patch application. Continue anyway?',
+                initialValue: false,
+            });
+            if (isCancel(shouldContinue) || !shouldContinue) {
+                outro('Import cancelled — fix the integrity issues and re-run');
+                return;
+            }
+        }
     }
     // Dry-run: list patches that would be applied and exit
     if (isDryRun) {
@@ -226,7 +280,7 @@ export async function importCommand(projectRoot, options = {}) {
         // Handle failures
         if (summary.failed.length > 0) {
             s.error(`${summary.failed.length} patch(es) failed`);
-            await handlePatchFailures(summary, state, projectRoot);
+            await handlePatchFailures(summary, projectRoot);
         }
         // Count auto-resolved patches
         const autoResolved = summary.succeeded.filter((r) => r.autoResolved);

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

@@ -0,0 +1,25 @@
+/**
+ * `fireforge patch compact` — closes ordinal gaps in the patch queue.
+ *
+ * After deletes or splits, patch ordinals may have gaps (e.g. 1, 3, 7).
+ * This command renumbers all patches to sequential ordinals (1, 2, 3, …)
+ * in a single atomic operation, preserving relative order.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../../types/cli.js';
+import type { PatchCompactOptions } from '../../types/commands/index.js';
+/**
+ * Runs the `patch compact` command: renumbers all patches to close ordinal
+ * gaps in a single atomic operation.
+ *
+ * @param projectRoot - Project root directory
+ * @param options - Command options
+ */
+export declare function patchCompactCommand(projectRoot: string, options?: PatchCompactOptions): Promise<void>;
+/**
+ * Registers the `patch compact` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export declare function registerPatchCompact(parent: Command, context: CommandContext): void;

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

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch compact` — closes ordinal gaps in the patch queue.
+ *
+ * After deletes or splits, patch ordinals may have gaps (e.g. 1, 3, 7).
+ * This command renumbers all patches to sequential ordinals (1, 2, 3, …)
+ * in a single atomic operation, preserving relative order.
+ */
+import { getProjectPaths } from '../../core/config.js';
+import { appendHistory, confirmDestructive } from '../../core/destructive.js';
+import { withPatchDirectoryLock } from '../../core/patch-lock.js';
+import { loadPatchesManifest, renumberPatchesInManifest, } from '../../core/patch-manifest.js';
+import { GeneralError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { pathExists } from '../../utils/fs.js';
+import { info, intro, outro, warn } from '../../utils/logger.js';
+import { pickDefined } from '../../utils/options.js';
+import { rebuildFilenameForOrder } from './reorder.js';
+/**
+ * Computes a rename map that assigns sequential ordinals (1, 2, 3, …)
+ * to all patches, sorted by their current order.
+ */
+function computeCompactRenameMap(patches) {
+    const sorted = [...patches].sort((a, b) => a.order - b.order);
+    const renames = new Map();
+    for (const [i, patch] of sorted.entries()) {
+        const newOrder = i + 1;
+        if (patch.order !== newOrder) {
+            renames.set(patch.filename, {
+                newOrder,
+                newFilename: rebuildFilenameForOrder(patch, newOrder),
+            });
+        }
+    }
+    return renames;
+}
+/**
+ * Runs the `patch compact` command: renumbers all patches to close ordinal
+ * gaps in a single atomic operation.
+ *
+ * @param projectRoot - Project root directory
+ * @param options - Command options
+ */
+export async function patchCompactCommand(projectRoot, options = {}) {
+    intro(options.dryRun ? 'FireForge patch compact (dry run)' : 'FireForge patch compact');
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.patches))) {
+        throw new GeneralError('Patches directory not found.');
+    }
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (!manifest || manifest.patches.length === 0) {
+        throw new GeneralError('No patches in manifest.');
+    }
+    const renameMap = computeCompactRenameMap(manifest.patches);
+    if (renameMap.size === 0) {
+        info('Patch queue is already compact. Nothing to do.');
+        outro('Compact complete (no-op)');
+        return;
+    }
+    const sorted = [...renameMap.entries()].sort((a, b) => a[1].newOrder - b[1].newOrder);
+    const summary = [`${renameMap.size} patch(es) would be renumbered:`];
+    for (const [oldFilename, entry] of sorted) {
+        summary.push(`  ${oldFilename}  →  ${entry.newFilename}  (order ${entry.newOrder})`);
+    }
+    const decision = await confirmDestructive({
+        operation: 'patch-compact',
+        title: `Compact ${manifest.patches.length} patches (${renameMap.size} rename(s))`,
+        summary,
+        yes: options.yes === true,
+        dryRun: options.dryRun === true,
+    });
+    if (decision === 'dry-run') {
+        outro('Dry run complete — no changes made');
+        return;
+    }
+    if (decision === 'cancelled') {
+        outro('Compact cancelled');
+        return;
+    }
+    await withPatchDirectoryLock(paths.patches, async () => {
+        const currentManifest = await loadPatchesManifest(paths.patches);
+        if (!currentManifest) {
+            throw new GeneralError('Manifest disappeared while waiting for lock.');
+        }
+        const currentRenameMap = computeCompactRenameMap(currentManifest.patches);
+        if (currentRenameMap.size === 0) {
+            info('Patch queue was compacted by another process. Nothing to do.');
+            return;
+        }
+        await renumberPatchesInManifest(paths.patches, currentRenameMap);
+        const historyEntry = {
+            operation: 'patch-compact',
+            args: {
+                renames: [...currentRenameMap.entries()]
+                    .sort((a, b) => a[1].newOrder - b[1].newOrder)
+                    .map(([from, entry]) => ({
+                    from,
+                    to: entry.newFilename,
+                    order: entry.newOrder,
+                })),
+            },
+            ...(options.yes === true ? { yes: true } : {}),
+            result: 'ok',
+        };
+        try {
+            await appendHistory(paths.patches, historyEntry);
+        }
+        catch (historyError) {
+            warn(`History log append failed after patch compact committed: ${toError(historyError).message}`);
+        }
+    });
+    info(`Compacted ${renameMap.size} patch(es).`);
+    outro('Compact complete');
+}
+/**
+ * Registers the `patch compact` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export function registerPatchCompact(parent, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    parent
+        .command('compact')
+        .description('Close ordinal gaps in the patch queue (renumber sequentially)')
+        .option('--dry-run', 'Show what would happen without writing')
+        .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .action(withErrorHandling(async (options) => {
+        await patchCompactCommand(getProjectRoot(), pickDefined(options));
+    }));
+}
+//# sourceMappingURL=compact.js.map

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

@@ -6,6 +6,7 @@
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';
+export { patchCompactCommand } from './compact.js';
 export { patchDeleteCommand } from './delete.js';
 export { patchReorderCommand } from './reorder.js';
 /**

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

@@ -5,8 +5,10 @@
  * command list. Queue-level verbs like `lint`, `export`, `verify`, and
  * `status` stay flat.
  */
+import { registerPatchCompact } from './compact.js';
 import { registerPatchDelete } from './delete.js';
 import { registerPatchReorder } from './reorder.js';
+export { patchCompactCommand } from './compact.js';
 export { patchDeleteCommand } from './delete.js';
 export { patchReorderCommand } from './reorder.js';
 /**
@@ -18,7 +20,8 @@ export { patchReorderCommand } from './reorder.js';
 export function registerPatch(program, context) {
     const patch = program
         .command('patch')
-        .description('Manage individual patches in the queue (delete, reorder)');
+        .description('Manage individual patches in the queue (compact, delete, reorder)');
+    registerPatchCompact(patch, context);
     registerPatchDelete(patch, context);
     registerPatchReorder(patch, context);
 }