@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/commands/register.js

@@ -17,8 +17,8 @@ import { stripEnginePrefix } from '../utils/paths.js';
  */
 export async function registerCommand(projectRoot, filePath, options = {}) {
     intro('Register');
-    // --after is matched as a substring against existing manifest lines;
-    // guard against control characters / line terminators that would either
+    // --after is matched as a substring against existing manifest lines.
+    // Guard against control characters / line terminators that would either
     // break the match logic or, worse, inject a second line if the value
     // is ever echoed back to a manifest writer. Null bytes are explicitly
     // rejected to mirror the hardening already applied to other user-
@@ -31,7 +31,7 @@ export async function registerCommand(projectRoot, filePath, options = {}) {
         }
     }
     // Accept either repo-root-relative (`engine/browser/...`) or
-    // engine-relative (`browser/...`) inputs — operators frequently paste
+    // engine-relative (`browser/...`) inputs. Operators frequently paste
     // the former from the output of tab completion or `git status`, and
     // the mismatch used to produce a "File not found" error that named
     // the original path with no hint that dropping `engine/` would fix it.
@@ -49,8 +49,8 @@ export async function registerCommand(projectRoot, filePath, options = {}) {
     });
     if (options.dryRun) {
         // Dry-run must surface the idempotency decision too. Always saying
-        // "Would register" — even when the rule already knows the entry is
-        // present — makes automation read the plan as "work to do" while the
+        // "Would register", even when the rule already knows the entry is
+        // present, makes automation read the plan as "work to do" while the
         // following real run reports "Already registered".
         if (result.skipped) {
             info(`[dry-run] Already registered: ${engineRelativePath} in ${result.manifest}`);

package/dist/src/commands/reset.js

@@ -70,7 +70,7 @@ export async function resetCommand(projectRoot, options) {
         await clearAppliedFurnaceState(projectRoot);
         s.stop('Changes reset');
         // The reset may have moved components.conf away from what the last full
-        // build compiled in — surface that now instead of at the next test
+        // build compiled in, so surface that now instead of at the next test
         // refusal.
         await warnIfStaticComponentsStale(projectRoot, paths.engine);
         outro('Working tree restored to clean state');

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

@@ -15,7 +15,7 @@ export interface ResolveCommandOptions {
      * and the command proceeds straight to the patch-refresh + state-clear
      * path.
      *
-     * The guard without `--yes` is preserved — running `resolve` with no TTY
+     * The guard without `--yes` is preserved: running `resolve` with no TTY
      * and no `--yes` still refuses, so an accidental pipe-into invocation does
      * not silently commit whatever the engine happens to contain.
      */
@@ -29,7 +29,7 @@ export interface ResolveCommandOptions {
 /**
  * Runs the resolve command to fix broken patches.
  * @param projectRoot - Root directory of the project
- * @param options - Optional flags; see {@link ResolveCommandOptions}.
+ * @param options - Optional flags. See {@link ResolveCommandOptions}.
  */
 export declare function resolveCommand(projectRoot: string, options?: ResolveCommandOptions): Promise<void>;
 /** Registers the resolve command on the CLI program. */

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,10 +16,11 @@ 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
- * @param options - Optional flags; see {@link ResolveCommandOptions}.
+ * @param options - Optional flags. See {@link ResolveCommandOptions}.
  */
 export async function resolveCommand(projectRoot, options = {}) {
     intro('FireForge Resolve');
@@ -36,7 +37,7 @@ export async function resolveCommand(projectRoot, options = {}) {
     // Non-interactive mode requires an explicit `--yes`: the operator is
     // asserting the manual merge is complete and the refreshed diff is the one
     // to record. Without it, an accidental pipe or CI shell could commit
-    // whatever the engine currently contains — but an unconditional TTY
+    // whatever the engine currently contains, but an unconditional TTY
     // refusal dead-ends a scripted recovery flow.
     if (!stdioIsInteractive() && !options.yes) {
         throw new GeneralError('Cannot run "fireforge resolve" in non-interactive mode. Use a terminal with TTY support, or pass "--yes" to skip the interactive confirmation once the manual merge is complete.');
@@ -63,7 +64,7 @@ export async function resolveCommand(projectRoot, options = {}) {
     // Refuse to proceed if the patch file was deleted between the conflict
     // and the resolve. Without this check, `updatePatchAndMetadata` would
     // throw a less actionable "patch file is missing" error from inside
-    // the lock; the explicit precondition lets us point the user at the
+    // the lock. The explicit precondition lets us point the user at the
     // exact recovery path.
     const patchPath = join(paths.patches, patchFilename);
     if (!(await pathExists(patchPath))) {
@@ -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. */
@@ -38,10 +25,10 @@ const SMOKE_UNALLOWED_PREVIEW_MAX = 10;
  * Cleans the dev profile to prevent stale-state startup failures.
  *
  * Removes two things:
- * 1. **startupCache/** — Firefox caches compiled chrome JS bytecode here.
+ * 1. `startupCache/`: Firefox caches compiled chrome JS bytecode here.
  *    When chrome scripts change between builds, the stale cache causes silent
  *    crashes on startup.
- * 2. **.parentlock** — A zero-byte lock file that persists if the previous
+ * 2. `.parentlock`: a zero-byte lock file that persists if the previous
  *    session was killed (Ctrl-C, crash, `kill`). Firefox checks this on
  *    startup and silently exits if it exists, assuming another instance owns
  *    the profile.
@@ -87,13 +74,13 @@ export async function runCommand(projectRoot, options = {}) {
         remediation: "Run 'fireforge build' first, then rerun 'fireforge run'.",
         requireExisting: true,
     });
-    // `hasBuildArtifacts` only checks for an `obj-*/dist/` directory; a build
+    // `hasBuildArtifacts` only checks for an `obj-*/dist/` directory. A build
     // that configured but has not yet produced the launchable binary passes
     // that check, and `mach run` then fails on the missing binary path.
     // `hasRunnableBundle` narrows the probe to the actual executable so
     // `fireforge run` refuses with a targeted message before handing control
     // to mach. `fireforge watch` stays permissive and surfaces the same
-    // information as a banner suffix; watch exists to drive rebuilds of
+    // information as a banner suffix. Watch exists to drive rebuilds of
     // partially-built trees, so blocking there would defeat it.
     if (buildCheck.objDir) {
         const config = await loadConfig(projectRoot);
@@ -117,12 +104,12 @@ export async function runCommand(projectRoot, options = {}) {
     info('Launching browser...\n');
     const exitCode = await run(paths.engine, options.headless ? ['--headless'] : []);
     // Exit-code whitelist:
-    //   0   — clean shutdown
-    //   130 — SIGINT (Ctrl+C), user-initiated termination
-    //   143 — SIGTERM, graceful-shutdown termination
-    // SIGKILL (137) and other signal-induced codes are intentionally NOT
-    // whitelisted: those indicate abnormal termination the operator should
-    // see surface as a build-time error.
+    //   0:   clean shutdown
+    //   130: SIGINT (Ctrl+C), user-initiated termination
+    //   143: SIGTERM, graceful-shutdown termination
+    // SIGKILL (137) and other signal-induced codes are not whitelisted: those
+    // indicate abnormal termination the operator should see surface as a
+    // build-time error.
     if (exitCode !== 0 && exitCode !== 130 && exitCode !== 143) {
         throw new BuildError(`Browser exited with code ${exitCode}`, 'mach run');
     }
@@ -154,10 +141,10 @@ async function runSmokeExit(engineDir, options) {
     }
     const smokeTimeoutMs = smokeExit * 1000;
     if (smokeTimeoutMs < SMOKE_COLD_START_THRESHOLD_MS) {
-        // Not an error — cold starts just tend to exceed the window. Surfacing
+        // 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
@@ -166,9 +153,9 @@ async function runSmokeExit(engineDir, options) {
     // createWriteStream opens the fd asynchronously, so ENOENT / EACCES /
     // EISDIR / EROFS surface as an 'error' event *after* the constructor
     // returns. Without a listener Node re-throws as uncaughtException and
-    // kills the CLI mid-smoke-run — orphaning the mach → python → firefox
+    // kills the CLI mid-smoke-run, orphaning the mach → python → firefox
     // tree because the deadline timer never fires. Swallow the event into a
-    // warning so the smoke run still terminates cleanly; subsequent mirror
+    // warning so the smoke run still terminates cleanly. Subsequent mirror
     // writes on the errored stream are silent no-ops.
     captureStream?.on('error', (err) => {
         warn(`--capture-console stream error: ${err.message}`);
@@ -184,10 +171,10 @@ async function runSmokeExit(engineDir, options) {
         const sink = stream === 'stdout' ? process.stdout : process.stderr;
         sink.write(`${line}\n`);
         // Count allowlist hits up-front, regardless of error-pattern match.
-        // Incrementing only when the line ALSO matches an error pattern makes an
+        // Incrementing only when the line also matches an error pattern makes an
         // allowlist regex that visibly matches `console.warn: RSLoader:` report 0
-        // hits, because `console.warn:` is not a smoke error class — confusing
-        // for operators tuning their allowlist. Two numbers are surfaced: the
+        // hits, because `console.warn:` is not a smoke error class, which
+        // confuses operators tuning their allowlist. Two numbers are surfaced: the
         // total set of allowlisted lines (what the operator sees in the console)
         // and the subset that were error-class (what the smoke exit contract
         // cares about). The exit contract itself is unchanged.
@@ -206,8 +193,8 @@ async function runSmokeExit(engineDir, options) {
         findings.push({ stream, line });
     };
     // A headed smoke window on a developer desktop absorbs live input: a human
-    // interacting with the window mid-run can trigger console errors — a
-    // password-manager import scan probing an unreadable profile dir, say —
+    // interacting with the window mid-run can trigger console errors (a
+    // password-manager import scan probing an unreadable profile dir, say)
     // that fail the smoke run looking like a product regression. CI hosts (CI
     // env var set) are assumed display-free and unattended, so the notice
     // stays quiet there.
@@ -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,22 +235,22 @@ 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.
+        // Clean window: SIGTERM came from us. Treat as success.
         return;
     }
     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
- * the optional `--console-allow-file`. Fails fast on a bad regex —
- * better to surface the typo at parse time than to silently let it
- * match nothing and turn every allowed hit into a smoke failure.
+ * the optional `--console-allow-file`. Fails fast on a bad regex, so the
+ * typo surfaces at parse time instead of silently matching nothing and
+ * turning every allowed hit into a smoke failure.
  */
 async function buildAllowlist(options) {
     const allow = [];
@@ -298,36 +285,36 @@ 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)}`);
-    // The "suppressed errors" count is what the exit contract cares about — the
+    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)}`);
-    // 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.
+    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, since an allowlist entry whose suppressed shape
+    // changed upstream is only detectable as a 0× row.
     if (args.allowlist.length > 0) {
         info('  Allowlist attribution (first matching entry per line):');
         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,35 +18,35 @@ 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 —
+    // its guard. The `||` chain this replaced spelled the member list twice,
     // once as the predicate and once in the message.
     if (typeof value === 'string' && isValidFirefoxProduct(value)) {
         return value;
     }
     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) {
@@ -194,7 +194,7 @@ function finalizePromptedSetupInputs(project) {
     // Project names that contain no ASCII alphanumerics (e.g. "----", "漢字",
     // emoji-only) collapse to an empty sanitised slug, which would silently
     // produce an invalid `appId` ("org..browser") and an empty `binaryName`.
-    // Refuse to derive defaults from such names — the user must supply
+    // Refuse to derive defaults from such names. The user must supply
     // explicit appId / binaryName values instead.
     const explicitAppId = typeof project.appId === 'string' ? project.appId.trim() : '';
     const explicitBinaryName = typeof project.binaryName === 'string' ? project.binaryName.trim() : '';
@@ -270,7 +270,7 @@ export function buildSetupConfig(inputs) {
 /**
  * Creates or updates the root `package.json` so its `license` field matches
  * the project license selected during setup. When the file already exists
- * ONLY the `license` field is touched — preserving `name`, `description`,
+ * only the `license` field is touched, preserving `name`, `description`,
  * `dependencies`, `scripts`, and every other author-editorial field. Without
  * this sync, a `fireforge setup --force` that picks a new license leaves the
  * old one in `package.json`, so the two files describe different projects.
@@ -296,7 +296,7 @@ async function syncRootPackageJson(projectRoot, license) {
     }
     catch {
         // Malformed package.json is the operator's editorial responsibility to
-        // repair; rewriting it would risk clobbering hand-authored content that
+        // repair. Rewriting it would risk clobbering hand-authored content that
         // the parser happens to reject. Leave the file alone and rely on the
         // doctor / lint paths that already surface invalid JSON.
         return;

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
@@ -73,7 +73,7 @@ export function registerSetup(program, { withErrorHandling }) {
         .option('-f, --force', 'Overwrite existing configuration without prompting')
         // `--yes` is a plain alias here: `setup`'s only bypass is the overwrite
         // prompt, so the two flags mean exactly the same thing. Seventeen other
-        // commands spell this bypass `--yes`; accepting it means a scripted
+        // commands spell this bypass `--yes`. Accepting it means a scripted
         // sequence can use one spelling throughout.
         .option('-y, --yes', 'Alias for --force: skip the overwrite confirmation')
         .action(withErrorHandling(async (options) => {
@@ -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

@@ -10,7 +10,7 @@ function cloneRawConfig(raw) {
     if (!isObject(cloned)) {
         throw new GeneralError('Cannot update fireforge.json: config clone was not an object.');
     }
-    // A structured clone of a JSON document is itself a JSON document; the
+    // A structured clone of a JSON document is itself a JSON document. The
     // object check above is the only invariant left to establish.
     return cloned;
 }
@@ -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.d.ts

@@ -4,8 +4,8 @@
  * classification outside {patch-backed, branding, furnace}, and
  * `--fail-on <class,...>` replaces that set for finer control.
  *
- * Helper module consumed by status.ts (which sits at the max-lines budget);
- * no top-level registrar is exported and none is wanted.
+ * Helper module consumed by status.ts, which sits at the max-lines budget.
+ * No top-level registrar is exported and none is wanted.
  */
 import type { ClassifiedFile, FileClassification } from '../core/status-classify.js';
 /** Resolved `--check`/`--fail-on` policy for one status invocation. */
@@ -15,7 +15,7 @@ export interface StatusCheckPolicy {
 }
 /**
  * Resolves the enforcement policy from the raw flags: `--fail-on` implies
- * `--check` and replaces the default set; both are refused alongside the
+ * `--check` and replaces the default set. Both are refused alongside the
  * modes that skip (or elide) classification.
  */
 export declare function resolveStatusCheckPolicy(options: {

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

@@ -10,9 +10,9 @@ const ALL_CLASSIFICATIONS = [
 ];
 /**
  * Default `--check` policy: everything outside {patch-backed, branding,
- * furnace, binary-unsupported} fails. `binary-unsupported` is deliberately
- * excluded — an honest "cannot compare" must not keep the gate permanently
- * red; strict CI can opt in via `--fail-on binary-unsupported`.
+ * furnace, binary-unsupported} fails. `binary-unsupported` is excluded so
+ * an honest "cannot compare" does not keep the gate permanently red.
+ * Strict CI can opt in via `--fail-on binary-unsupported`.
  */
 const DEFAULT_FAIL_CLASSIFICATIONS = [
     'unmanaged',
@@ -21,7 +21,7 @@ const DEFAULT_FAIL_CLASSIFICATIONS = [
 ];
 /**
  * Resolves the enforcement policy from the raw flags: `--fail-on` implies
- * `--check` and replaces the default set; both are refused alongside the
+ * `--check` and replaces the default set. Both are refused alongside the
  * modes that skip (or elide) classification.
  */
 export function resolveStatusCheckPolicy(options) {
@@ -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-json.d.ts

@@ -1,31 +1,32 @@
 /**
  * `status --json` payload rendering (schemaVersion 1). Helper module
- * consumed by status.ts (which sits at the max-lines budget); no top-level
+ * consumed by status.ts (which sits at the max-lines budget). No top-level
  * registrar is exported and none is wanted.
  *
  * Two shapes share one counting pass:
- * - the full payload (`renderJsonStatus`) with the per-file `files[]` list;
+ * - the full payload (`renderJsonStatus`) with the per-file `files[]` list,
  * - the `--summary` gate payload (`renderJsonSummaryStatus`), which omits
- *   `files[]` entirely — engine-clean gates need the verdict, per-class
- *   counts, and offender names, not a payload that grows with the queue
- *   (175 KB+ on a large one).
+ *   `files[]` entirely, because engine-clean gates need the verdict,
+ *   per-class counts, and offender names, not a payload that grows with
+ *   the queue (175 KB+ on a large one).
  */
 import type { ClassifiedFile } from '../core/status-classify.js';
 import { type StatusCheckPolicy } from './status-check.js';
 import type { OwnershipJsonBlock } from './status-ownership.js';
 /**
- * Full `--json` payload: summary plus the per-file `files[]` list, and —
- * under `--include-ownership` — the additive `ownership` block.
+ * Full `--json` payload: summary plus the per-file `files[]` list, and,
+ * under `--include-ownership`, the additive `ownership` block.
  * Additive within schemaVersion 1: a consumer that does not ask for the
  * block never sees the key.
  */
 export declare function renderJsonStatus(classified: readonly ClassifiedFile[], ownership?: OwnershipJsonBlock): void;
 /**
- * Summary-only `--json --summary` payload: counts always; when the
- * `--check`/`--fail-on` policy is active, a `check` block with the active
- * fail set, the verdict, and the offending files per fail-set
- * classification (sourced from the same collector as the human `--check`
- * message, so the two views can never disagree). The absent `files[]` is
- * the mode signal within schemaVersion 1 — consumers opt in via the flag.
+ * Summary-only `--json --summary` payload. Counts are always present. When
+ * the `--check`/`--fail-on` policy is active, the payload adds a `check`
+ * block with the active fail set, the verdict, and the offending files per
+ * fail-set classification (sourced from the same collector as the human
+ * `--check` message, so the two views can never disagree). The absent
+ * `files[]` is the mode signal within schemaVersion 1. Consumers opt in via
+ * the flag.
  */
 export declare function renderJsonSummaryStatus(classified: readonly ClassifiedFile[], policy: StatusCheckPolicy, ownership?: OwnershipJsonBlock): void;