@hominis/fireforge 0.21.4 → 0.23.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/lint.js

@@ -161,6 +161,12 @@ async function resolveLintDiff(engineDir, files, binaryName, furnacePrefixes) {
     }
     return diff;
 }
+function buildMaxWarningsMessage(count, maxWarnings, scope) {
+    const scoped = scope ? ` ${scope}` : '';
+    const base = `Patch lint found ${count} warning(s)${scoped}, exceeding --max-warnings ${maxWarnings}.`;
+    return (base +
+        ' If this is a release gate and the warnings are historical patch-size advisories, run with --per-patch to identify the owning patch and split/re-export that patch, or add a scoped lintIgnore entry only after review.');
+}
 /**
  * Filters aggregate-mode lint issues against per-patch `lintIgnore`
  * lists drawn from the manifest. An issue is dropped when at least one
@@ -373,7 +379,7 @@ export async function lintCommand(projectRoot, files, options = {}) {
     }
     if (options.maxWarnings !== undefined && warnings.length > options.maxWarnings) {
         outro('Lint failed');
-        throw new GeneralError(`Patch lint found ${warnings.length} warning(s), exceeding --max-warnings ${options.maxWarnings}.`);
+        throw new GeneralError(buildMaxWarningsMessage(warnings.length, options.maxWarnings));
     }
     // Notices are advisory and don't count as warnings — emitting "passed
     // with warnings" when only notices fired contradicts the preceding
@@ -493,7 +499,7 @@ async function lintPerPatch(projectRoot, paths, options = {}) {
     }
     if (options.maxWarnings !== undefined && warnings.length > options.maxWarnings) {
         outro('Lint failed');
-        throw new GeneralError(`Patch lint found ${warnings.length} warning(s) across ${linted} patch(es), exceeding --max-warnings ${options.maxWarnings}.`);
+        throw new GeneralError(buildMaxWarningsMessage(warnings.length, options.maxWarnings, `across ${linted} patch(es)`));
     }
     if (warnings.length > 0) {
         outro('Lint passed with warnings');

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/re-export-files.js

@@ -175,9 +175,10 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
             forceUnsafe: options.forceUnsafe === true,
         });
     }
-    // Shrinks are destructive (previously-owned files become unmanaged).
-    // Additive-only changes still deserve a prompt because --files asserts
-    // an authoritative file set.
+    // Shrinks are destructive (previously-owned files become unmanaged), so
+    // they keep the explicit confirmation gate. Additive-only scopes are safe
+    // to run non-interactively after lint/policy projection because no existing
+    // patch ownership is being dropped.
     const summary = [
         `re-export ${target.filename} with --files scope`,
         `current files (${target.filesAffected.length}): ${target.filesAffected.join(', ') || '(none)'}`,
@@ -196,7 +197,7 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
         operation: 're-export-files',
         title: `Re-export ${target.filename} with --files`,
         summary,
-        yes: options.yes === true,
+        yes: removed.length === 0 && missingFiles.length === 0 ? true : options.yes === true,
         dryRun: isDryRun,
         unsafeOverride: options.forceUnsafe === true,
         conflicts,

package/dist/src/commands/test.js

@@ -2,11 +2,11 @@
 import { join } from 'node:path';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
-import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, testWithOutput, } from '../core/mach.js';
+import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, testWithOutput, withBuildLock, } from '../core/mach.js';
 import { assertMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
 import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
-import { operatorAlreadySetAppPath, resolveXpcshellAppdirArg, } from '../core/xpcshell-appdir.js';
+import { findNearestXpcshellManifest, operatorAlreadySetAppPath, resolveXpcshellAppdirArg, } from '../core/xpcshell-appdir.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
@@ -36,6 +36,43 @@ function buildStaleBuildMessage() {
         'The failing output referenced missing branding or distribution resources, which usually means the current obj-* build does not match recent engine or branding changes.\n\n' +
         'Re-run "fireforge build --ui" or "fireforge test --build" and then retry.');
 }
+async function classifyTestHarnesses(engineDir, normalizedPaths) {
+    const result = { xpcshell: [], nonXpcshell: [] };
+    for (const testPath of normalizedPaths) {
+        const manifest = await findNearestXpcshellManifest(engineDir, testPath);
+        if (manifest) {
+            result.xpcshell.push(testPath);
+        }
+        else {
+            result.nonXpcshell.push(testPath);
+        }
+    }
+    return result;
+}
+function buildMixedHarnessMessage(classification) {
+    return ('FireForge cannot run xpcshell and browser/mochitest paths in the same mach invocation.\n\n' +
+        'Split this into separate `fireforge test` commands so each manifest selects its own harness:\n' +
+        `  - xpcshell: ${classification.xpcshell.join(', ')}\n` +
+        `  - browser/mochitest: ${classification.nonXpcshell.join(', ')}`);
+}
+function filterRedundantXpcshellFlavorArgs(machArgs, classification) {
+    if (classification.xpcshell.length === 0 || classification.nonXpcshell.length > 0) {
+        return [...machArgs];
+    }
+    const filtered = [];
+    for (let i = 0; i < machArgs.length; i += 1) {
+        const arg = machArgs[i] ?? '';
+        if (/^--flavor=xpcshell(?:-tests)?$/.test(arg)) {
+            continue;
+        }
+        if (arg === '--flavor' && /^xpcshell(?:-tests)?$/.test(machArgs[i + 1] ?? '')) {
+            i += 1;
+            continue;
+        }
+        filtered.push(arg);
+    }
+    return filtered;
+}
 function hasStaleBuildArtifactsSignal(output) {
     // Deliberately narrow: only fire on branding-specific resource paths
     // that are always a stale-artifact symptom. The earlier pattern also
@@ -101,6 +138,36 @@ function buildXpcshellAppdirMessage(injectionAttempted) {
         '  - Remove `firefox-appdir = "browser"` from the xpcshell.toml [DEFAULT] and move browser-chrome dependencies into a browser-chrome mochitest (see `fireforge furnace create --test-style=browser-chrome`).\n' +
         '  - If the test only touches toolkit chrome (chrome://global/*), drop the `firefox-appdir` setting entirely — toolkit chrome is registered without it.');
 }
+function buildMochitestSymlinkMessage() {
+    return ('mach failed while preparing mochitest harness symlinks before the requested tests ran.\n\n' +
+        'This usually means the objdir contains stale harness setup from an earlier run. Re-run with `fireforge test --build` to refresh the harness state, or remove the stale mochitest symlink in the active obj-* directory before retrying.');
+}
+async function resolveLaunchablePathForTests(engineDir, binaryName, objDir) {
+    if (!objDir)
+        return undefined;
+    const bundleCheck = await hasRunnableBundle(engineDir, binaryName, objDir);
+    if (!bundleCheck.runnable) {
+        const expectedSuffix = bundleCheck.expectedPath
+            ? ` (expected at engine/${bundleCheck.expectedPath})`
+            : '';
+        throw new GeneralError(`Tests require a complete launchable build${expectedSuffix}. ` +
+            'The obj-*/dist/ tree exists but the launchable binary is missing — typically the result of an interrupted or partially failed `fireforge build`.\n\n' +
+            'Run "fireforge build" again and let it finish before retrying "fireforge test".');
+    }
+    return bundleCheck.expectedPath;
+}
+async function runPreTestBuild(projectRoot, paths, projectConfig) {
+    await withBuildLock(projectRoot, async () => {
+        await prepareBuildEnvironment(projectRoot, paths, projectConfig);
+        const s = spinner('Running incremental build...');
+        const buildResult = await buildUI(paths.engine);
+        if (buildResult.exitCode !== 0) {
+            s.error('Pre-test build failed');
+            throw new BuildError('Pre-test build failed', 'mach build faster');
+        }
+        s.stop('Build complete');
+    });
+}
 // Detects the `AttributeError: 'MochitestDesktop' object has no attribute
 // 'http3Server'` teardown crash. The attribute is lazy-initialized inside
 // harness code paths that presume chrome://branding resolves correctly; a
@@ -153,6 +220,9 @@ function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted
     if (hasMochitestHttp3ServerSignal(combinedOutput)) {
         throw new GeneralError(buildMochitestHttp3ServerMessage());
     }
+    if (/FileExistsError/i.test(combinedOutput) && /mochitest/i.test(combinedOutput)) {
+        throw new GeneralError(buildMochitestSymlinkMessage());
+    }
     if (/invalid filename/i.test(combinedOutput) ||
         /chrome:\/\/mochitests.*not found/i.test(combinedOutput)) {
         info('Hint: The test file may not be registered in browser.toml or jar.mn.');
@@ -201,29 +271,10 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // here so `test --doctor` against an incomplete build surfaces the
     // missing-bundle path instead of a cryptic `Browser process exited
     // during spawn (exit code 1, signal none). stderr tail: (empty)`.
-    let launchablePath;
-    if (buildCheck.objDir) {
-        const bundleCheck = await hasRunnableBundle(paths.engine, projectConfig.binaryName, buildCheck.objDir);
-        launchablePath = bundleCheck.expectedPath;
-        if (!bundleCheck.runnable) {
-            const expectedSuffix = bundleCheck.expectedPath
-                ? ` (expected at engine/${bundleCheck.expectedPath})`
-                : '';
-            throw new GeneralError(`Tests require a complete launchable build${expectedSuffix}. ` +
-                'The obj-*/dist/ tree exists but the launchable binary is missing — typically the result of an interrupted or partially failed `fireforge build`.\n\n' +
-                'Run "fireforge build" again and let it finish before retrying "fireforge test".');
-        }
-    }
+    const launchablePath = await resolveLaunchablePathForTests(paths.engine, projectConfig.binaryName, buildCheck.objDir);
     // Run incremental build if requested
     if (options.build) {
-        await prepareBuildEnvironment(projectRoot, paths, projectConfig);
-        const s = spinner('Running incremental build...');
-        const buildResult = await buildUI(paths.engine);
-        if (buildResult.exitCode !== 0) {
-            s.error('Pre-test build failed');
-            throw new BuildError('Pre-test build failed', 'mach build faster');
-        }
-        s.stop('Build complete');
+        await runPreTestBuild(projectRoot, paths, projectConfig);
         info('');
     }
     else {
@@ -309,6 +360,13 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // previous case-insensitive + leading-whitespace-tolerant contract.
     const normalizedPaths = testPaths.map((p) => stripEnginePrefix(p).trim());
     await assertTestPathsExist(paths.engine, normalizedPaths);
+    const classification = await classifyTestHarnesses(paths.engine, normalizedPaths);
+    if (classification.xpcshell.length > 0 && classification.nonXpcshell.length > 0) {
+        throw new GeneralError(buildMixedHarnessMessage(classification));
+    }
+    const forwardedMachArgs = options.machArg && options.machArg.length > 0
+        ? filterRedundantXpcshellFlavorArgs(options.machArg, classification)
+        : [];
     // Build extra args
     const extraArgs = [];
     if (options.headless) {
@@ -319,8 +377,8 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // above for the motivating case). Appended AFTER --headless so mach sees
     // the FireForge-managed flags first and the escape-valve ones last, which
     // keeps the override precedence predictable.
-    if (options.machArg && options.machArg.length > 0) {
-        extraArgs.push(...options.machArg);
+    if (forwardedMachArgs.length > 0) {
+        extraArgs.push(...forwardedMachArgs);
     }
     // Auto-forward the Marionette port to mach when `--marionette-port` is
     // set. `--setpref=marionette.port=<n>` configures where the browser

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');
 }