@hominis/fireforge 0.21.4 → 0.22.0

package/dist/src/commands/doctor-furnace-manifest-sync.js

@@ -15,7 +15,7 @@
  * Lives in a sibling module to keep `doctor-furnace.ts` under the
  * per-file LOC budget.
  */
-import { readdir } from 'node:fs/promises';
+import { readdir, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig } from '../core/furnace-config.js';
 import { toError } from '../utils/errors.js';
@@ -120,6 +120,37 @@ async function repairOrphanOverrides(projectRoot, orphans) {
     }
     return { restored, unrecoverable };
 }
+async function repairCustomOrphans(projectRoot, customNames) {
+    const deleted = [];
+    const retained = [];
+    const errors = [];
+    if (customNames.length === 0)
+        return { deleted, retained, errors };
+    const furnacePaths = getFurnacePaths(projectRoot);
+    for (const name of customNames) {
+        const dir = join(furnacePaths.customDir, name);
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            errors.push(`${name}: ${toError(err).message}`);
+            continue;
+        }
+        if (entries.length > 0) {
+            retained.push(name);
+            continue;
+        }
+        try {
+            await rm(dir);
+            deleted.push(name);
+        }
+        catch (err) {
+            errors.push(`${name}: ${toError(err).message}`);
+        }
+    }
+    return { deleted, retained, errors };
+}
 export const furnaceManifestSyncCheck = {
     name: 'Furnace manifest sync',
     dependsOn: ['Furnace configuration'],
@@ -142,6 +173,7 @@ export const furnaceManifestSyncCheck = {
         if (repairResult.writeError) {
             return failure('Furnace manifest sync', `Repair failed while writing furnace.json: ${repairResult.writeError}`, 'Fix the underlying filesystem error and retry the doctor command.');
         }
+        const customRepair = await repairCustomOrphans(ctx.projectRoot, orphans.customNames);
         const { restored, unrecoverable } = repairResult;
         const restoreDetail = restored.length > 0
             ? `Re-registered ${restored.length} override${restored.length === 1 ? '' : 's'} (${restored.join(', ')}) from their override.json sidecars.`
@@ -149,10 +181,16 @@ export const furnaceManifestSyncCheck = {
         const unrecoverableDetail = unrecoverable.length > 0
             ? ` Could not recover ${unrecoverable.length} override${unrecoverable.length === 1 ? '' : 's'} without a valid override.json (${unrecoverable.join(', ')}) — delete components/overrides/<name> or re-run "fireforge furnace override" to restore the entry.`
             : '';
-        const customDetail = customCount > 0
-            ? ` ${customCount} custom ${customCount === 1 ? 'directory requires' : 'directories require'} manual action: re-run "fireforge furnace create" or delete components/custom/<name>/ to reconcile.`
+        const customDetail = customRepair.deleted.length > 0
+            ? ` Deleted ${customRepair.deleted.length} empty custom orphan ${customRepair.deleted.length === 1 ? 'directory' : 'directories'} (${customRepair.deleted.join(', ')}).`
+            : '';
+        const retainedCustomDetail = customRepair.retained.length > 0
+            ? ` ${customRepair.retained.length} non-empty custom orphan ${customRepair.retained.length === 1 ? 'directory requires' : 'directories require'} manual action (${customRepair.retained.join(', ')}): re-run "fireforge furnace create" or delete components/custom/<name>/ to reconcile.`
+            : '';
+        const customErrorDetail = customRepair.errors.length > 0
+            ? ` Could not inspect or delete ${customRepair.errors.length} custom orphan ${customRepair.errors.length === 1 ? 'directory' : 'directories'} (${customRepair.errors.join('; ')}).`
             : '';
-        return warning('Furnace manifest sync', `${restoreDetail}${unrecoverableDetail}${customDetail}`.trim() ||
+        return warning('Furnace manifest sync', `${restoreDetail}${unrecoverableDetail}${customDetail}${retainedCustomDetail}${customErrorDetail}`.trim() ||
             'Nothing to repair (orphans surfaced but all were already recoverable).');
     },
 };

package/dist/src/commands/doctor.js

@@ -1,4 +1,4 @@
-import { configExists, getProjectPaths, loadConfig, loadState } from '../core/config.js';
+import { configExists, getProjectPaths, loadConfig, loadState, updateState, } from '../core/config.js';
 import { furnaceConfigExists as checkFurnaceConfigExists } from '../core/furnace-config.js';
 import { getCurrentBranch, getHead, isGitRepository, isMissingHeadError } from '../core/git.js';
 import { ensureGit } from '../core/git-base.js';
@@ -13,6 +13,7 @@ import { findExecutable } from '../utils/process.js';
 import { failure, ok, warning } from './doctor-check-core.js';
 import { FURNACE_DOCTOR_CHECKS } from './doctor-furnace.js';
 import { inspectEngineWorkingTree } from './doctor-working-tree.js';
+import { collectPatchQueueHealth } from './verify.js';
 /**
  * Runs a single check definition, converting thrown errors into
  * DoctorCheck failure rows. Always returns an array so the caller can
@@ -184,9 +185,21 @@ const DOCTOR_CHECKS = [
     {
         name: 'Pending Resolution',
         skipIf: (ctx) => !ctx.state.pendingResolution,
-        run: (ctx) => {
+        run: async (ctx) => {
             const patchFilename = ctx.state.pendingResolution?.patchFilename ?? 'unknown';
-            return failure('Pending Resolution', `You are currently resolving a conflict for patch ${patchFilename}.`, 'Build and Export commands may behave unexpectedly until "fireforge resolve" is completed.');
+            if (ctx.options.clearResolution) {
+                const health = await collectPatchQueueHealth(ctx.projectRoot);
+                if (health.errorCount > 0) {
+                    return failure('Pending Resolution', `Refusing to clear pending resolution for ${patchFilename}: patch queue health check found ${health.errorCount} error(s).`, 'Run "fireforge verify" for details, fix the queue, then retry "fireforge doctor --clear-resolution".');
+                }
+                await updateState(ctx.projectRoot, (current) => {
+                    const next = { ...current };
+                    delete next.pendingResolution;
+                    return next;
+                });
+                return ok('Pending Resolution');
+            }
+            return failure('Pending Resolution', `You are currently resolving a conflict for patch ${patchFilename}.`, 'Build and Export commands may behave unexpectedly until "fireforge resolve" is completed. If the queue now verifies cleanly, run "fireforge doctor --clear-resolution" to discard the stale marker.');
         },
     },
     {
@@ -452,6 +465,7 @@ export function registerDoctor(program, { getProjectRoot, withErrorHandling }) {
         .description('Diagnose project issues')
         .option('--repair-patches-manifest', 'Rebuild patches/patches.json from the current patch files before reporting results')
         .option('--repair-furnace', 'Reconcile furnace state: clear stale furnace-state.json entries, re-run furnace apply to fix engine drift, and clear the pending-repair marker set by a failed preview teardown')
+        .option('--clear-resolution', 'Clear stale pendingResolution state after the patch queue health check reports no errors')
         .action(withErrorHandling(async (options) => {
         const result = await doctorCommand(getProjectRoot(), options);
         if (result.exitCode !== 0) {

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

@@ -6,10 +6,11 @@
  * 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 { getProjectPaths, loadConfig } 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 { applyRenameMapToManifest, enforcePatchPolicy } from '../../core/patch-policy.js';
 import { GeneralError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
@@ -44,6 +45,7 @@ function computeCompactRenameMap(patches) {
 export async function patchCompactCommand(projectRoot, options = {}) {
     intro(options.dryRun ? 'FireForge patch compact (dry run)' : 'FireForge patch compact');
     const paths = getProjectPaths(projectRoot);
+    const config = await loadConfig(projectRoot);
     if (!(await pathExists(paths.patches))) {
         throw new GeneralError('Patches directory not found.');
     }
@@ -62,12 +64,19 @@ export async function patchCompactCommand(projectRoot, options = {}) {
     for (const [oldFilename, entry] of sorted) {
         summary.push(`  ${oldFilename}  →  ${entry.newFilename}  (order ${entry.newOrder})`);
     }
+    enforcePatchPolicy({
+        config,
+        manifest: applyRenameMapToManifest(manifest, renameMap),
+        command: 'patch compact',
+        forceUnsafe: options.forceUnsafe === true,
+    });
     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,
+        unsafeOverride: options.forceUnsafe === true,
     });
     if (decision === 'dry-run') {
         outro('Dry run complete — no changes made');
@@ -87,6 +96,12 @@ export async function patchCompactCommand(projectRoot, options = {}) {
             info('Patch queue was compacted by another process. Nothing to do.');
             return;
         }
+        enforcePatchPolicy({
+            config,
+            manifest: applyRenameMapToManifest(currentManifest, currentRenameMap),
+            command: 'patch compact',
+            forceUnsafe: options.forceUnsafe === true,
+        });
         await renumberPatchesInManifest(paths.patches, currentRenameMap);
         const historyEntry = {
             operation: 'patch-compact',
@@ -100,6 +115,7 @@ export async function patchCompactCommand(projectRoot, options = {}) {
                 })),
             },
             ...(options.yes === true ? { yes: true } : {}),
+            ...(options.forceUnsafe === true ? { unsafeOverride: true } : {}),
             result: 'ok',
         };
         try {
@@ -125,6 +141,7 @@ export function registerPatchCompact(parent, context) {
         .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)')
+        .option('--force-unsafe', 'Bypass force-mode patchPolicy refusals')
         .action(withErrorHandling(async (options) => {
         await patchCompactCommand(getProjectRoot(), pickDefined(options));
     }));

package/dist/src/commands/verify.d.ts

@@ -15,6 +15,24 @@
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../types/cli.js';
+interface VerifyIssueGroup {
+    title: string;
+    issues: string[];
+    errorCount: number;
+    warningCount: number;
+}
+export interface PatchQueueHealth {
+    hasPatchesDirectory: boolean;
+    groups: VerifyIssueGroup[];
+    errorCount: number;
+    warningCount: number;
+}
+/**
+ * Collects the same queue-health findings reported by `fireforge verify`
+ * without printing. Used by doctor recovery paths that need a read-only
+ * "is this queue healthy?" decision before clearing stale state.
+ */
+export declare function collectPatchQueueHealth(projectRoot: string): Promise<PatchQueueHealth>;
 /**
  * Runs the `verify` command: manifest consistency + cross-patch lint.
  * Read-only; exits non-zero on any error-severity finding.
@@ -29,3 +47,4 @@ export declare function verifyCommand(projectRoot: string): Promise<void>;
  * @param context - Shared CLI registration context
  */
 export declare function registerVerify(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;
+export {};

package/dist/src/commands/verify.js

@@ -101,100 +101,129 @@ function detectCrossPatchFileClaims(manifestPatches) {
     return results;
 }
 /**
- * Runs the `verify` command: manifest consistency + cross-patch lint.
- * Read-only; exits non-zero on any error-severity finding.
- *
- * @param projectRoot - Project root directory
+ * Collects the same queue-health findings reported by `fireforge verify`
+ * without printing. Used by doctor recovery paths that need a read-only
+ * "is this queue healthy?" decision before clearing stale state.
  */
-export async function verifyCommand(projectRoot) {
-    intro('FireForge Verify');
+export async function collectPatchQueueHealth(projectRoot) {
     const paths = getProjectPaths(projectRoot);
     const config = await loadConfig(projectRoot);
     if (!(await pathExists(paths.patches))) {
-        info('No patches directory. Nothing to verify.');
-        outro('Verify clean');
-        return;
+        return {
+            hasPatchesDirectory: false,
+            groups: [],
+            errorCount: 0,
+            warningCount: 0,
+        };
     }
+    const groups = [];
     let errorCount = 0;
     let warningCount = 0;
-    // 1. Manifest consistency: orphan patch files, missing entries,
-    // files-affected mismatch, duplicate entries, unparseable manifest.
     const consistencyIssues = await validatePatchesManifestConsistency(paths.patches);
     if (consistencyIssues.length > 0) {
-        warn(`Manifest consistency issues (${consistencyIssues.length}):`);
-        for (const issue of consistencyIssues) {
-            warn(`  [${issue.code}] ${issue.message}`);
-            errorCount += 1;
-        }
+        const issues = consistencyIssues.map((issue) => `[${issue.code}] ${issue.message}`);
+        groups.push({
+            title: `Manifest consistency issues (${consistencyIssues.length})`,
+            issues,
+            errorCount: consistencyIssues.length,
+            warningCount: 0,
+        });
+        errorCount += consistencyIssues.length;
     }
-    // 2. Cross-patch file claims: two or more manifest entries listing the
-    // same path in filesAffected. Not caught by per-patch consistency.
     const manifest = await loadPatchesManifest(paths.patches);
     if (manifest) {
         const policyIssues = evaluatePatchPolicy(config, manifest);
         if (policyIssues.length > 0) {
-            warn(`Patch policy issues (${policyIssues.length}):`);
-            for (const issue of policyIssues) {
-                const label = issue.severity === 'error' ? 'ERROR' : 'WARN';
-                warn(`  ${label} [${issue.code}] ${issue.filename}: ${issue.message}`);
-                if (issue.severity === 'error')
-                    errorCount += 1;
-                else
-                    warningCount += 1;
-            }
+            const policyErrors = policyIssues.filter((issue) => issue.severity === 'error').length;
+            const policyWarnings = policyIssues.length - policyErrors;
+            groups.push({
+                title: `Patch policy issues (${policyIssues.length})`,
+                issues: policyIssues.map((issue) => {
+                    const label = issue.severity === 'error' ? 'ERROR' : 'WARN';
+                    return `${label} [${issue.code}] ${issue.filename}: ${issue.message}`;
+                }),
+                errorCount: policyErrors,
+                warningCount: policyWarnings,
+            });
+            errorCount += policyErrors;
+            warningCount += policyWarnings;
         }
         const crossClaims = detectCrossPatchFileClaims(manifest.patches);
         if (crossClaims.length > 0) {
-            warn(`Cross-patch filesAffected conflicts (${crossClaims.length}):`);
-            for (const claim of crossClaims) {
-                warn(`  ${claim.path}  claimed by: ${claim.filenames.join(', ')}`);
-                errorCount += 1;
-            }
+            groups.push({
+                title: `Cross-patch filesAffected conflicts (${crossClaims.length})`,
+                issues: crossClaims.map((claim) => `${claim.path}  claimed by: ${claim.filenames.join(', ')}`),
+                errorCount: crossClaims.length,
+                warningCount: 0,
+            });
+            errorCount += crossClaims.length;
         }
     }
-    // 3. Cross-patch lint: duplicate /dev/null creation + forward imports.
     const ctx = await buildPatchQueueContext(paths.patches);
     const lintIssues = lintPatchQueue(ctx);
     if (lintIssues.length > 0) {
-        warn(`Cross-patch lint issues (${lintIssues.length}):`);
-        for (const issue of lintIssues) {
-            const label = issue.severity === 'error' ? 'ERROR' : issue.severity === 'warning' ? 'WARN' : 'NOTICE';
-            warn(`  ${label} [${issue.check}] ${issue.file}: ${issue.message}`);
-            if (issue.severity === 'error')
-                errorCount += 1;
-            else if (issue.severity === 'warning')
-                warningCount += 1;
-        }
+        const lintErrors = lintIssues.filter((issue) => issue.severity === 'error').length;
+        const lintWarnings = lintIssues.filter((issue) => issue.severity === 'warning').length;
+        groups.push({
+            title: `Cross-patch lint issues (${lintIssues.length})`,
+            issues: lintIssues.map((issue) => {
+                const label = issue.severity === 'error' ? 'ERROR' : issue.severity === 'warning' ? 'WARN' : 'NOTICE';
+                return `${label} [${issue.check}] ${issue.file}: ${issue.message}`;
+            }),
+            errorCount: lintErrors,
+            warningCount: lintWarnings,
+        });
+        errorCount += lintErrors;
+        warningCount += lintWarnings;
     }
-    // 4. Registration-consequence consistency: walk each patch body and
-    // confirm that every widget / locale registration it adds has a
-    // corresponding file body covered by the patch queue OR present in
-    // the engine working tree. 2026-04-24 eval Finding 1: a patch
-    // produced by `export-all --exclude-furnace` referenced
-    // `toolkit/content/widgets/moz-qa-panel/*.mjs` via jar.mn /
-    // customElements.js edits, but the source files themselves were
-    // excluded from the patch. `verify` used to report "clean"; it now
-    // flags each dangling reference as a `dangling-registration` error
-    // naming the specific patch and target path.
     if (manifest) {
         const registrationIssues = await detectDanglingRegistrations(paths.patches, paths.engine, manifest.patches);
         if (registrationIssues.length > 0) {
-            warn(`Dangling registration references (${registrationIssues.length}):`);
-            for (const issue of registrationIssues) {
-                warn(`  ${issue.patchFilename}: registers ${issue.targetPath} via ${issue.source}, but no patch body or engine file supplies it`);
-                errorCount += 1;
-            }
+            groups.push({
+                title: `Dangling registration references (${registrationIssues.length})`,
+                issues: registrationIssues.map((issue) => `${issue.patchFilename}: registers ${issue.targetPath} via ${issue.source}, but no patch body or engine file supplies it`),
+                errorCount: registrationIssues.length,
+                warningCount: 0,
+            });
+            errorCount += registrationIssues.length;
+        }
+    }
+    return {
+        hasPatchesDirectory: true,
+        groups,
+        errorCount,
+        warningCount,
+    };
+}
+/**
+ * Runs the `verify` command: manifest consistency + cross-patch lint.
+ * Read-only; exits non-zero on any error-severity finding.
+ *
+ * @param projectRoot - Project root directory
+ */
+export async function verifyCommand(projectRoot) {
+    intro('FireForge Verify');
+    const health = await collectPatchQueueHealth(projectRoot);
+    if (!health.hasPatchesDirectory) {
+        info('No patches directory. Nothing to verify.');
+        outro('Verify clean');
+        return;
+    }
+    for (const group of health.groups) {
+        warn(`${group.title}:`);
+        for (const issue of group.issues) {
+            warn(`  ${issue}`);
         }
     }
-    if (errorCount === 0 && warningCount === 0) {
+    if (health.errorCount === 0 && health.warningCount === 0) {
         success('Patch queue is consistent.');
         outro('Verify clean');
         return;
     }
-    info(`\nVerify: ${errorCount} error(s), ${warningCount} warning(s)`);
-    if (errorCount > 0) {
+    info(`\nVerify: ${health.errorCount} error(s), ${health.warningCount} warning(s)`);
+    if (health.errorCount > 0) {
         outro('Verify failed');
-        throw new GeneralError(`fireforge verify found ${errorCount} error(s). Fix these before running export/import/rebase.`);
+        throw new GeneralError(`fireforge verify found ${health.errorCount} error(s). Fix these before running export/import/rebase.`);
     }
     outro('Verify passed with warnings');
 }

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

@@ -552,6 +552,8 @@ export interface PatchCompactOptions {
     yes?: boolean;
     /** Print what would happen without writing anything. */
     dryRun?: boolean;
+    /** Bypass force-mode patchPolicy refusals. */
+    forceUnsafe?: boolean;
 }
 /**
  * Options for the status command.
@@ -584,6 +586,12 @@ export interface TokenAddOptions {
  */
 export interface DoctorOptions {
     repairPatchesManifest?: boolean;
+    /**
+     * Clear a stale `pendingResolution` marker, but only after the same
+     * read-only queue health checks used by `fireforge verify` report no
+     * error-severity findings.
+     */
+    clearResolution?: boolean;
     /**
      * Opt-in repair path for furnace-specific checks. When true, doctor will:
      * - clear stale `.fireforge/furnace-state.json` entries whose component is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.21.4",
+  "version": "0.22.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",