@hominis/fireforge 0.44.4 → 0.46.0

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

@@ -9,8 +9,9 @@ import { loadPatchesManifest, resolvePatchIdentifier, stampPatchVersions, } from
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { elapsedSince } from '../utils/elapsed.js';
 import { toError } from '../utils/errors.js';
-import { cancel, info, intro, isCancel, outro, spinner, success, warn } from '../utils/logger.js';
+import { cancel, info, intro, isCancel, outro, spinner, success, warn, } from '../utils/logger.js';
 import { loadScanFilesAssignments, withDryRunPurityGuard, withDryRunReExportLock, } from './re-export-bulk-scan.js';
+import { warnUnseenExpectedDrift } from './re-export-drift.js';
 import { reExportFilesInPlace } from './re-export-files.js';
 import { buildReExportLintContext, finishReExportLint } from './re-export-lint.js';
 import { applyReExportFilesPositionalFolding, validateReExportOptionCombinations, } from './re-export-options.js';
@@ -123,6 +124,8 @@ export async function reExportCommand(projectRoot, patches, options) {
         binaryName: config.binaryName,
         furnacePrefixes: await collectFurnaceManagedPrefixes(paths.root),
         refuseAdjacentUnmanaged: options.refuseAdjacentUnmanaged === true,
+        approvedUnmanaged: new Set((options.expectUnmanaged ?? []).map((file) => normalizeEngineRelativeInput(file, '--expect-unmanaged'))),
+        approvedSeen: new Set(),
         refusals: [],
     };
     const driftCtx = buildForeignDriftContext(options);
@@ -140,7 +143,17 @@ export async function reExportCommand(projectRoot, patches, options) {
             const patchOptions = assignedScanFiles !== undefined ? { ...options, scanFiles: assignedScanFiles } : options;
             progress.message(`Re-exporting ${index + 1}/${selectedPatches.length}: ${patch.filename} (${patch.filesAffected.length} file(s), ${elapsedSince(startedAt)} elapsed)...`);
             try {
-                const exported = await reExportSinglePatchWithIndexLockRetry(patch, paths, manifest, patchOptions, isDryRun, config, adjacentCtx, driftCtx, lintCtx);
+                const exported = await reExportSinglePatchWithIndexLockRetry({
+                    patch,
+                    paths,
+                    manifest,
+                    options: patchOptions,
+                    isDryRun,
+                    config,
+                    adjacentCtx,
+                    driftCtx,
+                    lintCtx,
+                });
                 if (exported) {
                     reExported++;
                     reExportedFilenames.push(patch.filename);
@@ -155,6 +168,7 @@ export async function reExportCommand(projectRoot, patches, options) {
     }));
     await finishReExportLint(lintCtx);
     warnUnseenExpectedDrift(driftCtx);
+    warnUnseenApprovedUnmanaged(adjacentCtx);
     throwRunLevelRefusals(adjacentCtx, driftCtx, progress);
     if (reExported === 0 && selectedPatches.length > 0) {
         progress.error('Re-export failed');
@@ -198,26 +212,22 @@ function buildForeignDriftContext(options) {
     };
 }
 /**
- * Names `--expect` paths that never drifted this run. A typo'd
- * `--expect` path silently degrades the flag back to refusing the slice it
- * was meant to admit, so surface the mismatch — but only as a warning: an
- * expected file legitimately shows no drift when the slice was already
- * captured by an earlier export.
+ * Names `--expect-unmanaged` paths that were never met this run. A typo'd
+ * carve-out silently leaves the refusal armed for the path it was meant to
+ * admit — and, worse, reads as an approval that is in force when it is not.
+ * A warning rather than a refusal: an approved path legitimately goes unmet
+ * when the reviewed file has since been adopted into a patch, which is the
+ * outcome the carve-out exists to be retired by.
  */
-function warnUnseenExpectedDrift(driftCtx) {
-    const unseen = [...driftCtx.expectedDriftFiles].filter((file) => !driftCtx.expectedSeen.has(file));
+function warnUnseenApprovedUnmanaged(adjacentCtx) {
+    const unseen = [...adjacentCtx.approvedUnmanaged].filter((file) => !adjacentCtx.approvedSeen.has(file));
     if (unseen.length === 0)
         return;
-    if (driftCtx.evaluationRuns === 0) {
-        warn(`--expect path(s) were not evaluated because no selected patch reached the drift check (for example, an earlier refusal): ${unseen.join(', ')}`);
-        return;
-    }
-    warn('--expect path(s) showed no drift this run: ' +
+    warn('--expect-unmanaged path(s) were not met as adjacent unmanaged files this run: ' +
         `${unseen.join(', ')}. ` +
-        'Causes, in rough order of likelihood: a typo in the path; the slice was already ' +
-        'captured by an earlier export in this session; or the engine content already matches ' +
-        'the patch body — a concurrent session may have exported the same change, so the drift ' +
-        'converged before this run looked.');
+        'Causes, in rough order of likelihood: a typo in the path; the file is now owned by a ' +
+        'patch (the carve-out can be dropped); or no selected patch is adjacent to it. The ' +
+        'refusal stayed armed for everything else either way.');
 }
 /**
  * Turns the run's collected `--refuse-adjacent-unmanaged` and
@@ -227,19 +237,26 @@ function warnUnseenExpectedDrift(driftCtx) {
 function throwRunLevelRefusals(adjacentCtx, driftCtx, progress) {
     if (adjacentCtx.refusals.length > 0) {
         progress.error('Re-export refused');
-        const names = adjacentCtx.refusals.map((r) => r.patchFilename).join(', ');
-        throw new GeneralError(`Refused ${String(adjacentCtx.refusals.length)} patch(es) with adjacent unmanaged files ` +
-            `(--refuse-adjacent-unmanaged): ${names}. Adopt reviewed files with --scan --scan-file, ` +
-            `or export them as a new patch.`);
+        // Each offender is named with the owned directory that made it
+        // adjacent: an unattended run reads only this line, and without the
+        // anchor it cannot tell which of a multi-directory patch's locations
+        // the file sits beside.
+        const offenders = adjacentCtx.refusals
+            .map((r) => `${r.patchFilename} (${r.anchored.join(', ')})`)
+            .join('; ');
+        throw new GeneralError(`Refused ${adjacentCtx.refusals.length} patch(es) with adjacent unmanaged files ` +
+            `(--refuse-adjacent-unmanaged): ${offenders}. Adjacent means the file sits in a ` +
+            `directory the patch already owns a file in. Adopt reviewed files with ` +
+            `--scan --scan-file, or export them as a new patch.`);
     }
     if (driftCtx.refusals.length > 0) {
         progress.error('Re-export refused');
         const names = driftCtx.refusals.map((r) => r.patchFilename).join(', ');
         const unreadable = driftCtx.refusals.filter((r) => r.reason === 'baseline-unreadable');
         const unreadablePart = unreadable.length > 0
-            ? ` ${String(unreadable.length)} of these refused because the old patch body was missing or unreadable, so the drift comparison could not run (fail-closed).`
+            ? ` ${unreadable.length} of these refused because the old patch body was missing or unreadable, so the drift comparison could not run (fail-closed).`
             : '';
-        throw new GeneralError(`Refused ${String(driftCtx.refusals.length)} patch(es) whose refreshed body would absorb ` +
+        throw new GeneralError(`Refused ${driftCtx.refusals.length} patch(es) whose refreshed body would absorb ` +
             `engine edits not present in the old patch body (--refuse-foreign-drift): ${names}.${unreadablePart}\n\n` +
             'The flag cannot tell WHO wrote those lines, and the two populations have opposite ' +
             'remedies:\n' +
@@ -283,9 +300,9 @@ function reportReExportOutcome(args) {
     if (reExported < selectedCount) {
         const skippedCount = selectedCount - reExported - args.failedFilenames.length;
         const failedPart = args.failedFilenames.length > 0 ? ` Failed: ${args.failedFilenames.join(', ')}.` : '';
-        const skippedPart = skippedCount > 0 ? ` Skipped: ${String(skippedCount)} patch(es) (see warnings above).` : '';
-        throw new GeneralError(`${isDryRun ? '[dry-run] Would re-export' : 'Re-exported'} only ${String(reExported)} of ` +
-            `${String(selectedCount)} selected patch(es).${failedPart}${skippedPart} ` +
+        const skippedPart = skippedCount > 0 ? ` Skipped: ${skippedCount} patch(es) (see warnings above).` : '';
+        throw new GeneralError(`${isDryRun ? '[dry-run] Would re-export' : 'Re-exported'} only ${reExported} of ` +
+            `${selectedCount} selected patch(es).${failedPart}${skippedPart} ` +
             'Partial re-export exits non-zero so it cannot pass as success in scripts; ' +
             'the per-patch errors are listed above.');
     }

package/dist/src/commands/rebase/abort.js

@@ -2,12 +2,13 @@
 /**
  * Rebase abort flow.
  */
-import { getProjectPaths, updateState } from '../../core/config.js';
+import { getProjectPaths } from '../../core/config.js';
 import { clearAppliedFurnaceState } from '../../core/furnace-config.js';
 import { resetChanges } from '../../core/git.js';
 import { clearRebaseSession, getRebaseSessionPath, readRebaseSession, } from '../../core/rebase-session.js';
 import { NoRebaseSessionError } from '../../errors/rebase.js';
 import { intro, outro, spinner, success, warn } from '../../utils/logger.js';
+import { clearPendingResolution } from '../pending-resolution.js';
 import { confirmDirtyEngineReset } from './confirm.js';
 /**
  * Handles `fireforge rebase --abort`.
@@ -57,13 +58,7 @@ export async function handleAbort(projectRoot, yes) {
     // idempotently re-clear furnace state.
     await clearAppliedFurnaceState(projectRoot);
     // Step 3: clear pending resolution transactionally.
-    await updateState(projectRoot, (current) => {
-        if (!current.pendingResolution)
-            return current;
-        const next = { ...current };
-        delete next.pendingResolution;
-        return next;
-    });
+    await clearPendingResolution(projectRoot);
     // Step 4: clear the rebase session LAST so a failure in any prior step
     // preserves the session on disk and a retry of --abort can succeed.
     await clearRebaseSession(projectRoot);

package/dist/src/commands/rebase/continue.js

@@ -3,7 +3,7 @@
  * Rebase --continue flow.
  */
 import { join } from 'node:path';
-import { getProjectPaths, updateState } from '../../core/config.js';
+import { getProjectPaths } from '../../core/config.js';
 import { getStagedDiffForFiles } from '../../core/git-diff.js';
 import { stageFiles, unstageFiles } from '../../core/git-file-ops.js';
 import { updatePatchAndMetadata } from '../../core/patch-export.js';
@@ -14,6 +14,7 @@ import { GeneralError } from '../../errors/base.js';
 import { CorruptRebaseSessionError, NoRebaseSessionError, RebaseError, } from '../../errors/rebase.js';
 import { pathExists } from '../../utils/fs.js';
 import { info, intro, success, warn } from '../../utils/logger.js';
+import { clearPendingResolution } from '../pending-resolution.js';
 import { runPatchLoop } from './patch-loop.js';
 /**
  * Handles `fireforge rebase --continue`.
@@ -77,10 +78,15 @@ export async function handleContinue(projectRoot, maxFuzz, waitLockSeconds) {
         // updatePatchMetadata sequence can interleave with a concurrent export /
         // re-export / patch reorder / patch compact and leave the manifest
         // disagreeing with the freshly-written patch body. Mirrors resolve.ts.
-        await updatePatchAndMetadata(paths.patches, currentPatch.filename, diffContent, {
-            sourceEsrVersion: session.toVersion,
-            sourceVersion: session.toVersion,
-            ...(session.toProduct !== undefined ? { sourceProduct: session.toProduct } : {}),
+        await updatePatchAndMetadata({
+            patchesDir: paths.patches,
+            filename: currentPatch.filename,
+            newContent: diffContent,
+            updates: {
+                sourceEsrVersion: session.toVersion,
+                sourceVersion: session.toVersion,
+                ...(session.toProduct !== undefined ? { sourceProduct: session.toProduct } : {}),
+            },
         });
     }
     finally {
@@ -104,13 +110,7 @@ export async function handleContinue(projectRoot, maxFuzz, waitLockSeconds) {
         await saveRebaseSession(projectRoot, session);
         // Clear pending resolution transactionally so concurrent state-file
         // writes to unrelated keys are not clobbered by a stale reload.
-        await updateState(projectRoot, (current) => {
-            if (!current.pendingResolution)
-                return current;
-            const next = { ...current };
-            delete next.pendingResolution;
-            return next;
-        });
+        await clearPendingResolution(projectRoot);
     });
     success(`Resolved ${currentPatch.filename}`);
     // Continue applying remaining patches

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

@@ -17,7 +17,7 @@ import { clearAppliedFurnaceState } from '../../core/furnace-config.js';
 import { getHead, resetChanges } from '../../core/git.js';
 import { discoverPatches } from '../../core/patch-files.js';
 import { loadPatchesManifest } from '../../core/patch-manifest.js';
-import { getPatchSourceProduct, getPatchSourceVersion } from '../../core/patch-source-metadata.js';
+import { getPatchSourceVersion } from '../../core/patch-source-metadata.js';
 import { getRebaseSessionPath, readRebaseSession, saveRebaseSession, } from '../../core/rebase-session.js';
 import { GeneralError } from '../../errors/base.js';
 import { CorruptRebaseSessionError, RebaseSessionExistsError } from '../../errors/rebase.js';
@@ -59,7 +59,7 @@ async function handleFreshStart(projectRoot, options) {
     }
     // Determine the "from" version from the patches
     const patchVersions = new Set(manifest.patches.map((p) => getPatchSourceVersion(p)));
-    const patchProducts = new Set(manifest.patches.map((p) => getPatchSourceProduct(p)).filter(Boolean));
+    const patchProducts = new Set(manifest.patches.map((p) => p.sourceProduct).filter(Boolean));
     const sortedVersions = [...patchVersions].sort();
     const fromVersion = sortedVersions[0] ?? currentVersion;
     const fromProduct = [...patchProducts].sort()[0] ?? config.firefox.product;

package/dist/src/commands/rebase/patch-loop.d.ts

@@ -1,8 +1,8 @@
 /**
  * Patch application loop and re-export flow.
  */
-import type { getProjectPaths } from '../../core/config.js';
 import type { RebaseSession } from '../../core/rebase-session.js';
+import type { ProjectPaths } from '../../types/config.js';
 /**
  * Runs the patch application loop, re-exports applied patches, and stamps versions.
  *
@@ -12,4 +12,4 @@ import type { RebaseSession } from '../../core/rebase-session.js';
  * @param maxFuzz - Maximum context-reduction steps for `git apply -C<n>`
  * @param waitLockSeconds - `--wait-lock` budget for the patch-directory lock
  */
-export declare function runPatchLoop(projectRoot: string, session: RebaseSession, paths: ReturnType<typeof getProjectPaths>, maxFuzz: number, waitLockSeconds?: number): Promise<void>;
+export declare function runPatchLoop(projectRoot: string, session: RebaseSession, paths: ProjectPaths, maxFuzz: number, waitLockSeconds?: number): Promise<void>;

package/dist/src/commands/rebase/patch-loop.js

@@ -20,6 +20,7 @@ import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
 import { error, info, outro, spinner, success, warn } from '../../utils/logger.js';
 import { isValidFirefoxVersion } from '../../utils/validation.js';
+import { clearPendingResolution } from '../pending-resolution.js';
 import { buildRebaseConflictSummary } from './conflict-summary.js';
 import { printSummary } from './summary.js';
 /**
@@ -208,13 +209,7 @@ export async function runPatchLoop(projectRoot, session, paths, maxFuzz, waitLoc
     await clearRebaseSession(projectRoot);
     // Clear pending resolution if any (transactionally, so a concurrent
     // state write to an unrelated key is not clobbered by a stale reload).
-    await updateState(projectRoot, (current) => {
-        if (!current.pendingResolution)
-            return current;
-        const next = { ...current };
-        delete next.pendingResolution;
-        return next;
-    });
+    await clearPendingResolution(projectRoot);
     info('');
     success(`All patches re-exported with sourceVersion=${session.toVersion}`);
     outro('Rebase complete!');

package/dist/src/commands/resolve.js

@@ -2,7 +2,7 @@
 import { join } from 'node:path';
 import { confirm } from '@clack/prompts';
 import { Command } from 'commander';
-import { getProjectPaths, loadConfig, loadState, updateState } from '../core/config.js';
+import { getProjectPaths, loadConfig, loadState } from '../core/config.js';
 import { stdioIsInteractive } from '../core/destructive.js';
 import { assertEngineGitReady } from '../core/engine-precondition.js';
 import { getStagedDiffForFiles } from '../core/git-diff.js';
@@ -16,6 +16,7 @@ import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { error as logError, info, intro, isCancel, outro, spinner, success, } from '../utils/logger.js';
 import { addWaitLockOption, resolveWaitLockSeconds } from '../utils/options.js';
+import { clearPendingResolution } from './pending-resolution.js';
 /**
  * Runs the resolve command to fix broken patches.
  * @param projectRoot - Root directory of the project
@@ -123,20 +124,27 @@ export async function resolveCommand(projectRoot, options = {}) {
         // here keeps resolve in agreement with every other writer.
         const diffFilesAffected = extractAffectedFiles(diffContent);
         const config = await loadConfig(projectRoot);
-        await updatePatchAndMetadata(paths.patches, patchFilename, diffContent, {
-            filesAffected: diffFilesAffected,
-            ...buildPatchSourceMetadata(config.firefox),
-        }, undefined, undefined, { waitLockSeconds: resolveWaitLockSeconds(options.waitLock), command: 'resolve' });
+        await updatePatchAndMetadata({
+            patchesDir: paths.patches,
+            filename: patchFilename,
+            newContent: diffContent,
+            updates: {
+                filesAffected: diffFilesAffected,
+                ...buildPatchSourceMetadata(config.firefox),
+            },
+            onCommitted: undefined,
+            policyGate: undefined,
+            lockOptions: {
+                waitLockSeconds: resolveWaitLockSeconds(options.waitLock),
+                command: 'resolve',
+            },
+        });
         // Clear pendingResolution from state.json transactionally so a
         // concurrent update to unrelated keys (another command writing buildMode
         // or baseCommit between our load and save) is not clobbered. The updater
         // runs inside the state-file lock with the freshest on-disk state, so
         // only pendingResolution is affected.
-        await updateState(projectRoot, (current) => {
-            const next = { ...current };
-            delete next.pendingResolution;
-            return next;
-        });
+        await clearPendingResolution(projectRoot);
         s.stop(`Updated ${patchFilename}`);
         success('Patch updated successfully and resolution state cleared.');
         info('Patch updated. Run "fireforge import" next to resume the queue from this point — resolve only refreshes the one broken patch, it does not continue applying the remaining patches itself.');

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

@@ -1,19 +1,6 @@
 import { Command } from 'commander';
 import type { CommandContext } from '../types/cli.js';
 import type { RunOptions } from '../types/commands/index.js';
-/**
- * Exit code returned by smoke-run mode when the captured console stream
- * produced one or more error lines that did NOT match the operator's
- * allowlist.
- */
-export declare const SMOKE_EXIT_FAILURE: 12;
-/**
- * Exit code returned by smoke-run mode when the browser itself exited
- * with a non-clean status before the smoke window elapsed — i.e. a
- * launch-side failure we could NOT observe as a console error line
- * (crash before console wiring, missing profile, etc.).
- */
-export declare const SMOKE_LAUNCH_FAILURE: 13;
 /**
  * Runs the run command to launch the built browser.
  * @param projectRoot - Root directory of the project

package/dist/src/commands/run.js

@@ -17,19 +17,6 @@ import { toError } from '../utils/errors.js';
 import { pathExists, removeDir, removeFile } from '../utils/fs.js';
 import { info, intro, verbose, warn } from '../utils/logger.js';
 import { commanderArgParser, pickDefined, stringListOption } from '../utils/options.js';
-/**
- * Exit code returned by smoke-run mode when the captured console stream
- * produced one or more error lines that did NOT match the operator's
- * allowlist.
- */
-export const SMOKE_EXIT_FAILURE = ExitCode.SMOKE_EXIT_FAILURE;
-/**
- * Exit code returned by smoke-run mode when the browser itself exited
- * with a non-clean status before the smoke window elapsed — i.e. a
- * launch-side failure we could NOT observe as a console error line
- * (crash before console wiring, missing profile, etc.).
- */
-export const SMOKE_LAUNCH_FAILURE = ExitCode.SMOKE_LAUNCH_FAILURE;
 /** Recommendation surfaced when the smoke window is shorter than a typical cold start. */
 const SMOKE_COLD_START_THRESHOLD_MS = 30_000;
 /** Maximum number of unallowed error lines to surface in the terminal summary. */
@@ -157,7 +144,7 @@ async function runSmokeExit(engineDir, options) {
         // Not an error — cold starts just tend to exceed the window. Surfacing
         // the hint here instead of failing lets agents run shorter windows
         // intentionally (e.g. warm-cache smoke checks).
-        verbose(`Smoke window is ${String(smokeExit)}s; cold starts on slow machines often exceed 30s.`);
+        verbose(`Smoke window is ${smokeExit}s; cold starts on slow machines often exceed 30s.`);
     }
     const allowlist = await buildAllowlist(options);
     const captureStream = options.captureConsole
@@ -216,7 +203,7 @@ async function runSmokeExit(engineDir, options) {
             'console capture and can fail the run. Pass --headless (or run on an unattended host) ' +
             'for reliable smoke checks.');
     }
-    info(`Launching browser (smoke-exit after ${String(smokeExit)}s)...\n`);
+    info(`Launching browser (smoke-exit after ${smokeExit}s)...\n`);
     const startedAt = Date.now();
     let result;
     try {
@@ -248,7 +235,7 @@ async function runSmokeExit(engineDir, options) {
     });
     // Exit contract (precedence: unallowed errors dominate timed-out).
     if (findings.length > 0) {
-        throw new SmokeRunError(`Smoke run observed ${String(findings.length)} unallowed console error(s).`, SMOKE_EXIT_FAILURE);
+        throw new SmokeRunError(`Smoke run observed ${findings.length} unallowed console error(s).`, ExitCode.SMOKE_EXIT_FAILURE);
     }
     if (result.timedOut) {
         // Clean window — SIGTERM from us. Treat as success.
@@ -257,7 +244,7 @@ async function runSmokeExit(engineDir, options) {
     if (result.exitCode === 0 || result.exitCode === 130 || result.exitCode === 143) {
         return;
     }
-    throw new SmokeRunError(`Browser exited with code ${String(result.exitCode)} before smoke-exit window elapsed.`, SMOKE_LAUNCH_FAILURE);
+    throw new SmokeRunError(`Browser exited with code ${result.exitCode} before smoke-exit window elapsed.`, ExitCode.SMOKE_LAUNCH_FAILURE);
 }
 /**
  * Compiles the active allowlist from `--console-allow` CLI values and
@@ -298,15 +285,15 @@ function reportSmokeSummary(args) {
     const suffix = args.timedOut ? ' (deadline fired — SIGTERM sent to process group)' : '';
     info('');
     info(`Smoke run complete: ${seconds}s elapsed of ${windowSeconds}s window${suffix}`);
-    info(`  Unallowed errors: ${String(args.findings.length)}`);
+    info(`  Unallowed errors: ${args.findings.length}`);
     // The "suppressed errors" count is what the exit contract cares about — the
     // subset of allowlisted hits that would otherwise have been tallied as
     // findings. The "all allowlisted lines" count answers the operator's mental
     // model ("my --console-allow pattern matched N console lines"), without
     // which a visibly matching regex reports 0 hits.
-    info(`  Allowlisted error hits (suppressed): ${String(args.allowlistedErrorHits)}`);
-    info(`  Allowlisted lines total: ${String(args.allowlistedTotalHits)}`);
-    info(`  Child exit code:  ${String(args.exitCode)}`);
+    info(`  Allowlisted error hits (suppressed): ${args.allowlistedErrorHits}`);
+    info(`  Allowlisted lines total: ${args.allowlistedTotalHits}`);
+    info(`  Child exit code:  ${args.exitCode}`);
     // Per-entry attribution: first-match credit per line, with
     // zero-hit entries always visible — an allowlist entry whose suppressed
     // shape changed upstream is only detectable as a 0× row.
@@ -315,19 +302,19 @@ function reportSmokeSummary(args) {
         args.allowlist.forEach((entry, index) => {
             const hits = args.allowlistHits[index] ?? 0;
             const zeroSuffix = hits === 0 ? '  (never matched — candidate for removal)' : '';
-            info(`    ${String(hits)}×  ${entry.origin}  ${entry.source}${zeroSuffix}`);
+            info(`    ${hits}×  ${entry.origin}  ${entry.source}${zeroSuffix}`);
         });
     }
     if (args.findings.length === 0)
         return;
     warn('');
-    warn(`Unallowed console errors (first ${String(SMOKE_UNALLOWED_PREVIEW_MAX)}):`);
+    warn(`Unallowed console errors (first ${SMOKE_UNALLOWED_PREVIEW_MAX}):`);
     args.findings.slice(0, SMOKE_UNALLOWED_PREVIEW_MAX).forEach((finding, index) => {
-        warn(`  ${String(index + 1)}. [${finding.stream}] ${finding.line}`);
+        warn(`  ${index + 1}. [${finding.stream}] ${finding.line}`);
     });
     if (args.findings.length > SMOKE_UNALLOWED_PREVIEW_MAX) {
         const remaining = args.findings.length - SMOKE_UNALLOWED_PREVIEW_MAX;
-        warn(`  …and ${String(remaining)} more.`);
+        warn(`  …and ${remaining} more.`);
     }
 }
 /** Registers the run command on the CLI program. */

package/dist/src/commands/setup-support.d.ts

@@ -9,10 +9,22 @@ export interface ResolvedSetupInputs {
     finalProduct: FirefoxProduct;
     finalLicense: ProjectLicense;
 }
-/** Parses an optional Firefox product flag into a typed product value. */
-export declare function parseFirefoxProductOption(product: string | undefined): FirefoxProduct | undefined;
-/** Parses an optional license flag into a validated SPDX identifier. */
-export declare function parseProjectLicenseOption(license: string | undefined): ProjectLicense | undefined;
+/**
+ * Narrows a raw CLI or prompt value to a supported Firefox product.
+ * @param value - Raw value from `--product` or the setup prompt.
+ * @param field - Field name quoted in the refusal (e.g. `--product`).
+ * @returns The validated product.
+ * @throws {@link InvalidArgumentError} when the value names no supported product.
+ */
+export declare function resolveFirefoxProduct(value: unknown, field: string): FirefoxProduct;
+/**
+ * Narrows a raw CLI or prompt value to a supported SPDX licence identifier.
+ * @param value - Raw value from `--license` or the setup prompt.
+ * @param field - Field name quoted in the refusal (e.g. `--license`).
+ * @returns The validated licence identifier.
+ * @throws {@link InvalidArgumentError} when the value names no supported licence.
+ */
+export declare function resolveProjectLicense(value: unknown, field: string): ProjectLicense;
 /** Validates non-interactive setup options before project scaffolding begins. */
 export declare function validateSetupOptions(options: SetupOptions): void;
 /** Resolves setup inputs from CLI flags and optional interactive prompts. */

package/dist/src/commands/setup-support.js

@@ -18,7 +18,14 @@ function renderLicenseTemplate(license, template, vendor, now = new Date()) {
     }
     return template.replace(/\[year\]/g, String(now.getFullYear())).replace(/\[fullname\]/g, vendor);
 }
-function resolveFirefoxProduct(value, field) {
+/**
+ * Narrows a raw CLI or prompt value to a supported Firefox product.
+ * @param value - Raw value from `--product` or the setup prompt.
+ * @param field - Field name quoted in the refusal (e.g. `--product`).
+ * @returns The validated product.
+ * @throws {@link InvalidArgumentError} when the value names no supported product.
+ */
+export function resolveFirefoxProduct(value, field) {
     // Matches the sibling `resolveProjectLicense`, which already delegates to
     // its guard. The `||` chain this replaced spelled the member list twice —
     // once as the predicate and once in the message.
@@ -27,26 +34,19 @@ function resolveFirefoxProduct(value, field) {
     }
     throw new InvalidArgumentError(`Invalid product (use: ${FIREFOX_PRODUCTS.join(', ')})`, field);
 }
-function resolveProjectLicense(value, field) {
+/**
+ * Narrows a raw CLI or prompt value to a supported SPDX licence identifier.
+ * @param value - Raw value from `--license` or the setup prompt.
+ * @param field - Field name quoted in the refusal (e.g. `--license`).
+ * @returns The validated licence identifier.
+ * @throws {@link InvalidArgumentError} when the value names no supported licence.
+ */
+export function resolveProjectLicense(value, field) {
     if (typeof value === 'string' && isValidProjectLicense(value)) {
         return value;
     }
     throw new InvalidArgumentError('Invalid license (use: EUPL-1.2, MPL-2.0, 0BSD, GPL-2.0-or-later)', field);
 }
-/** Parses an optional Firefox product flag into a typed product value. */
-export function parseFirefoxProductOption(product) {
-    if (product === undefined) {
-        return undefined;
-    }
-    return resolveFirefoxProduct(product, '--product');
-}
-/** Parses an optional license flag into a validated SPDX identifier. */
-export function parseProjectLicenseOption(license) {
-    if (license === undefined) {
-        return undefined;
-    }
-    return resolveProjectLicense(license, '--license');
-}
 /** Validates non-interactive setup options before project scaffolding begins. */
 export function validateSetupOptions(options) {
     if (options.name !== undefined) {

package/dist/src/commands/setup.js

@@ -8,7 +8,7 @@ import { ConfigError } from '../errors/config.js';
 import { cancel, intro, isCancel, note, outro, spinner } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { FIREFOX_PRODUCTS, PROJECT_LICENSES } from '../utils/validation.js';
-import { buildSetupConfig, parseFirefoxProductOption, parseProjectLicenseOption, resolveSetupInputs, validateSetupOptions, writeSetupProjectFiles, } from './setup-support.js';
+import { buildSetupConfig, resolveFirefoxProduct, resolveProjectLicense, resolveSetupInputs, validateSetupOptions, writeSetupProjectFiles, } from './setup-support.js';
 /**
  * Runs the setup command.
  * @param projectRoot - Root directory for the project
@@ -83,16 +83,10 @@ export function registerSetup(program, { withErrorHandling }) {
         if (yes === true)
             setupOptions.force = true;
         if (product !== undefined) {
-            const parsedProduct = parseFirefoxProductOption(product);
-            if (parsedProduct !== undefined) {
-                setupOptions.product = parsedProduct;
-            }
+            setupOptions.product = resolveFirefoxProduct(product, '--product');
         }
         if (license !== undefined) {
-            const parsedLicense = parseProjectLicenseOption(license);
-            if (parsedLicense !== undefined) {
-                setupOptions.license = parsedLicense;
-            }
+            setupOptions.license = resolveProjectLicense(license, '--license');
         }
         await setupCommand(resolve(process.cwd()), setupOptions);
     }));

package/dist/src/commands/source.js

@@ -87,7 +87,14 @@ export async function sourceSetCommand(projectRoot, options) {
 }
 /** Registers the source command on the CLI program. */
 export function registerSource(program, { getProjectRoot, withErrorHandling }) {
-    const source = program.command('source').description('Manage Firefox source configuration');
+    const source = program
+        .command('source')
+        .description('Manage Firefox source configuration')
+        // No-subcommand contract shared with `patch`/`token`/`furnace`: help on
+        // stdout, exit 0 (see `handleParseError` for the groups without an action).
+        .action(() => {
+        source.outputHelp();
+    });
     source
         .command('set')
         .description('Atomically set Firefox source version, product, and optional checksum')

package/dist/src/commands/status-check.js

@@ -95,9 +95,9 @@ export function runStatusCheck(classified, policy) {
     const offending = collectStatusCheckOffenders(classified, policy).map((offender) => {
         const preview = offender.files.slice(0, CHECK_FILE_PREVIEW_MAX).join(', ');
         const more = offender.count > CHECK_FILE_PREVIEW_MAX
-            ? `, +${String(offender.count - CHECK_FILE_PREVIEW_MAX)} more`
+            ? `, +${offender.count - CHECK_FILE_PREVIEW_MAX} more`
             : '';
-        return `${String(offender.count)} ${offender.classification} (${preview}${more})`;
+        return `${offender.count} ${offender.classification} (${preview}${more})`;
     });
     if (offending.length === 0)
         return;

package/dist/src/commands/status-output.js

@@ -219,7 +219,7 @@ export function renderTestCoverageStatus(baseline) {
         return;
     }
     const list = coverage.map((path) => `  - ${path}`).join('\n');
-    info(`Test packaging coverage: scoped to ${String(coverage.length)} path(s):\n${list}\n` +
+    info(`Test packaging coverage: scoped to ${coverage.length} path(s):\n${list}\n` +
         'A "fireforge test" over paths outside this list will be refused as uncovered.');
-    outro(`Coverage: scoped (${String(coverage.length)} paths)`);
+    outro(`Coverage: scoped (${coverage.length} paths)`);
 }

package/dist/src/commands/status.js

@@ -15,7 +15,7 @@ import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { FIREFORGE_TMP_PATH_PATTERN, pathExists } from '../utils/fs.js';
 import { info, intro, isMachineOutputMode, outro, setMachineOutputMode, warn, } from '../utils/logger.js';
 import { emitMachineError } from '../utils/machine-output.js';
-import { resolveStatusCheckPolicy, runStatusCheck } from './status-check.js';
+import { resolveStatusCheckPolicy, runStatusCheck, } from './status-check.js';
 import { renderJsonStatus, renderJsonSummaryStatus } from './status-json.js';
 import { renderDefaultStatus, renderTestCoverageStatus, renderUnmanagedOnly, } from './status-output.js';
 import { buildOwnershipJsonBlock, collectOwnershipRows, summarizeOwnership, } from './status-ownership.js';
@@ -253,7 +253,6 @@ async function runStatusCommandBody(projectRoot, options) {
     const config = await loadConfig(projectRoot);
     // Shared envelope: see src/utils/machine-output.ts and
     // docs/machine-output.md. `status` was the only command that had one.
-    const emitJsonError = emitMachineError;
     // Ownership mode is a flat file→patch table; sources are the manifest's
     // filesAffected, any worktree drift, and the cross-patch
     // duplicate-new-file-creation map produced by walking each patch body. The
@@ -292,14 +291,14 @@ async function runStatusCommandBody(projectRoot, options) {
     // message is kept identical to the helper's on purpose.
     if (!(await pathExists(paths.engine))) {
         if (options.json) {
-            emitJsonError('engine-missing', 'Firefox source not found. Run "fireforge download" first.');
+            emitMachineError('engine-missing', 'Firefox source not found. Run "fireforge download" first.');
         }
         throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
     }
     // Check if it's a git repository
     if (!(await isGitRepository(paths.engine))) {
         if (options.json) {
-            emitJsonError('engine-not-git', 'Engine directory is not a git repository. Run "fireforge download" to initialize.');
+            emitMachineError('engine-not-git', 'Engine directory is not a git repository. Run "fireforge download" to initialize.');
         }
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }