@hominis/fireforge 0.46.0 → 0.46.1

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

@@ -23,7 +23,7 @@ const GIT_INDEX_LOCK_RETRY_MS = 300;
  * Retries a single patch re-export exactly once when the failure is
  * transient git `index.lock` contention (an external git process holding
  * the engine repo's index). The retry re-enters `reExportSinglePatch`
- * from the top, so it re-reads clean state; a second lock failure
+ * from the top, so it re-reads clean state. A second lock failure
  * propagates to the loop's honest "N of M" accounting.
  */
 export async function reExportSinglePatchWithIndexLockRetry(args) {
@@ -53,10 +53,10 @@ async function reExportSinglePatch(args) {
             ...(options.scanFiles !== undefined ? { scanFiles: options.scanFiles } : {}),
         });
         // Forward-import gate at adoption time (runs in dry-run too): refuse
-        // to adopt unmanaged files that import modules created by LATER
-        // patches — the after-the-fact lint failure this leaves behind is the
-        // field-reported footgun. Applies to broad --scan, --scan-file, and
-        // the --scan-files bulk assignments alike.
+        // to adopt unmanaged files that import modules created by later
+        // patches, because the after-the-fact lint failure this leaves behind
+        // is the field-reported footgun. Applies to broad --scan, --scan-file,
+        // and the --scan-files bulk assignments alike.
         await assertScanAdoptionsHaveNoForwardImports({
             patchesDir: paths.patches,
             engineDir: paths.engine,
@@ -82,7 +82,7 @@ async function reExportSinglePatch(args) {
         // When neither `--scan` nor `--files` is set and some of the manifest's
         // claimed files no longer exist on disk, the re-export silently writes a
         // refreshed body whose filesAffected still names the vanished paths.
-        // That is the documented contract, but it is also a footgun — a later
+        // That is the documented contract, but it is also a footgun: a later
         // `verify` then fails on manifest-consistency with no obvious trigger.
         // Emit one advisory warning up-front when the drift is cheap to detect,
         // so the operator can re-run with `--scan` or `--files` before the stale
@@ -92,9 +92,9 @@ async function reExportSinglePatch(args) {
             return false;
     }
     // --- Explicit file-subset path ---
-    // When --files is given, the target filesAffected is authoritative — drop
+    // When --files is given, the target filesAffected is authoritative: drop
     // anything not in the list, add anything new. This is the surgical repair
-    // primitive that replaces hand-editing patches.json; the user has already
+    // primitive that replaces hand-editing patches.json. The user has already
     // acknowledged via confirmDestructive (done in the caller) that any drop
     // is intentional.
     if (options.files !== undefined) {
@@ -109,16 +109,16 @@ async function reExportSinglePatch(args) {
     }
     // Stale-furnace-source gate: re-export captures deployed engine copies, so
     // a component source edited after the last furnace apply would land in the
-    // patch as its OLD deployed content. Refuse (or warn under
+    // patch as its old deployed content. Refuse (or warn under
     // --allow-stale-furnace) before diffing. Runs in dry-run too so the failure
     // surfaces early.
     await enforceFreshFurnaceSources(paths.root, currentFilesAffected, options.allowStaleFurnace === true, 're-export');
     const absentFiles = await findMissingFiles(paths.engine, currentFilesAffected);
-    // A path absent from disk but tracked in engine HEAD is a DELETION, and
+    // A path absent from disk but tracked in engine HEAD is a deletion, and
     // `git diff HEAD` renders it as a real `deleted file mode` section. Only
     // a never-tracked path has nothing to diff. Skipping both alike meant a
     // retired file quietly left the patch body while staying in its file
-    // list — the patch then claimed a file it could not restore.
+    // list, so the patch then claimed a file it could not restore.
     const trackedAbsent = await listTrackedInHead(paths.engine, absentFiles);
     const deletedFiles = absentFiles.filter((f) => trackedAbsent.has(f));
     const untrackedAbsent = absentFiles.filter((f) => !trackedAbsent.has(f));
@@ -148,9 +148,9 @@ async function reExportSinglePatch(args) {
     }
     // Foreign-drift preview + optional hard stop: show which
     // payload lines are about to enter the body that the old body did not
-    // carry — the case where a concurrent session's uncommitted edits in
-    // OWNED files would be silently absorbed. Always previews (including
-    // dry-run and --scan); refuses only under --refuse-foreign-drift.
+    // carry, the case where a concurrent session's uncommitted edits in
+    // owned files would be silently absorbed. Always previews (including
+    // dry-run and --scan). Refuses only under --refuse-foreign-drift.
     if (await reportForeignDrift({
         patch,
         patchesDir: paths.patches,
@@ -167,7 +167,7 @@ async function reExportSinglePatch(args) {
         command: 're-export',
         forceUnsafe: options.forceUnsafe === true,
     });
-    // Lint against the ONCE-per-invocation hoisted context (queue context +
+    // Lint against the once-per-invocation hoisted context (queue context +
     // queue-wide checkJs program + per-patch result cache) instead of
     // rebuilding ~37 s of setup for every patch in the loop.
     const projectedMetadata = { ...patch, ...updates };
@@ -213,8 +213,8 @@ async function reExportSinglePatch(args) {
  * directory lock (a split write would let a concurrent queue mutation
  * leave body and `filesAffected` disagreeing), then keeps the run's
  * in-memory state honest: the queue context entry is refreshed and the
- * fresh lint result is stored keyed against the just-written body — the
- * state a repeat invocation will observe — and the in-memory
+ * fresh lint result is stored keyed against the just-written body (the
+ * state a repeat invocation will observe), and the in-memory
  * manifest row mirrors the on-disk write for later loop iterations
  * (notably `--all --scan`, where `getClaimedFiles` reads this manifest).
  */
@@ -246,8 +246,8 @@ async function commitRefreshedPatch(args) {
             };
         }
     }
-    // A bulk run refreshes every patch; saying "Re-exported" for one whose body
-    // did not move buries the patches that DID move. The run still counts this
+    // A bulk run refreshes every patch. Saying "Re-exported" for one whose body
+    // did not move buries the patches that did move. The run still counts this
     // patch as successfully refreshed, so `--stamp` completeness is unaffected.
     if (bodyChanged) {
         success(`Re-exported ${patch.filename}`);
@@ -258,7 +258,7 @@ async function commitRefreshedPatch(args) {
 }
 /**
  * Threads the patch's own `lintIgnore` list through so the per-patch
- * suppression honoured by export/export-all is also honoured here — a
+ * suppression honoured by export/export-all is also honoured here. A
  * re-export could otherwise not refresh an advisory-noisy but intentional
  * patch without the blunt `--skip-lint`. The paired `patch.tier` threads the
  * explicit branding-threshold opt-in the same way. The CLI flags `--tier`

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

@@ -26,15 +26,16 @@ async function resolveSelectedPatches(patches, options, manifest) {
         for (const identifier of patches) {
             const match = resolvePatchIdentifier(identifier, manifest.patches);
             if (!match) {
-                // Suggest, never dump: a wrong guess would otherwise print the
-                // whole ~300-entry manifest, burying the error it was reporting.
+                // Suggest close matches instead of dumping the queue: a wrong guess
+                // would otherwise print the whole ~300-entry manifest, burying the
+                // error it was reporting.
                 throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
             }
             selectedPatches.push(match);
         }
         return selectedPatches;
     }
-    // No patches specified — prompt or error
+    // No patches specified: prompt or error
     const isInteractive = stdioIsInteractive();
     if (!isInteractive) {
         throw new InvalidArgumentError('Specify patch identifiers or use --all in non-interactive mode.\n\n' +
@@ -176,7 +177,7 @@ export async function reExportCommand(projectRoot, patches, options) {
     }
     // `--stamp` only fires on a run where every selected patch refreshed
     // cleanly. A partial success would leave some patches with a stale body
-    // but a new version — the opposite of the "what I tested, what the
+    // but a new version, the opposite of the "what I tested, what the
     // manifest says" invariant `sourceEsrVersion` exists to record. A
     // non-empty `reExportedFilenames` with fewer entries than `selectedPatches`
     // means a lint failure or missing-file skip landed somewhere in the loop,
@@ -214,7 +215,7 @@ function buildForeignDriftContext(options) {
 /**
  * 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.
+ * admit, and 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.
@@ -271,7 +272,7 @@ function throwRunLevelRefusals(adjacentCtx, driftCtx, progress) {
  * Prints the end-of-run summary and enforces the exit contract: a partial run
  * exits non-zero by default. "Re-exported 2 of 3" printing with exit 0 lets a
  * partial refresh ride an `&&` chain as success. The summary still prints
- * first so the honest "N of M" accounting stays visible; the throw then
+ * first so the honest "N of M" accounting stays visible. The throw then
  * carries the failed/skipped breakdown. Dry-run included: a preview
  * reporting that the real run would partially fail must not read as a passing
  * preview in scripts.

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

@@ -15,9 +15,9 @@ import { confirmDirtyEngineReset } from './confirm.js';
  */
 export async function handleAbort(projectRoot, yes) {
     intro('FireForge Rebase — Abort');
-    // Abort is the escape hatch, so it deliberately does NOT require a *valid*
-    // session — only that one is present. Nothing below reads the session
-    // object (the restore works off `paths.engine` and `resetChanges`), and an
+    // Abort is the escape hatch, so it does not require a valid session, only
+    // that one is present. Nothing below reads the session object (the restore
+    // works off `paths.engine` and `resetChanges`), and an
     // `if (!session) throw` would refuse to run against a corrupt file, which
     // is the only thing that could have cleared it.
     const read = await readRebaseSession(projectRoot);
@@ -40,8 +40,8 @@ export async function handleAbort(projectRoot, yes) {
         return;
     }
     const s = spinner('Restoring engine to pre-rebase state...');
-    // Step 1: git reset. If this fails, the rebase session MUST stay on disk
-    // so the user can retry the abort — resetChanges is the only irreversible
+    // Step 1: git reset. If this fails, the rebase session must stay on disk
+    // so the user can retry the abort: resetChanges is the only irreversible
     // operation in this handler and everything downstream assumes it ran.
     try {
         await resetChanges(paths.engine);
@@ -59,7 +59,7 @@ export async function handleAbort(projectRoot, yes) {
     await clearAppliedFurnaceState(projectRoot);
     // Step 3: clear pending resolution transactionally.
     await clearPendingResolution(projectRoot);
-    // Step 4: clear the rebase session LAST so a failure in any prior step
+    // 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);
     success('Rebase aborted and session cleared.');

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

@@ -21,7 +21,7 @@ import { runPatchLoop } from './patch-loop.js';
  */
 export async function handleContinue(projectRoot, maxFuzz, waitLockSeconds) {
     intro('FireForge Rebase — Continue');
-    // A present-but-unreadable session is NOT "no session in progress" — that
+    // A present-but-unreadable session is not "no session in progress". That
     // conflation is what made a corrupt file unrecoverable. Name the file and
     // point at --abort, which can now clear it.
     const read = await readRebaseSession(projectRoot);
@@ -34,10 +34,10 @@ export async function handleContinue(projectRoot, maxFuzz, waitLockSeconds) {
     const paths = getProjectPaths(projectRoot);
     // Special case: every patch has already applied but a previous run failed
     // somewhere in the post-apply work (re-export, version stamping). In that
-    // state currentIndex is past the end of the queue; jumping straight back
+    // state currentIndex is past the end of the queue. Jumping straight back
     // into runPatchLoop replays the no-op apply loop and re-attempts the
-    // post-apply pipeline. Without this branch the user would be stuck —
-    // there is no failed patch to resolve, but the session is still active.
+    // post-apply pipeline. Without this branch the user would be stuck: there
+    // is no failed patch to resolve, but the session is still active.
     if (session.currentIndex >= session.patches.length) {
         info('All patches already applied; retrying post-apply re-export and version stamping.');
         await runPatchLoop(projectRoot, session, paths, maxFuzz, waitLockSeconds);
@@ -99,9 +99,10 @@ export async function handleContinue(projectRoot, maxFuzz, waitLockSeconds) {
     // clear is held until both writes land, matching the guarantee the apply
     // loop in patch-loop.ts provides.
     await runInSignalCriticalSection(`rebase-continue:${currentPatch.filename}`, async () => {
-        // Replaced, not mutated: flipping `status` in place leaves the
-        // failure's `error` and `conflictingFiles` on a now-resolved entry, and
-        // persist that to the session file. The union makes it impossible.
+        // The entry is replaced rather than mutated. Flipping `status` in place
+        // would leave the failure's `error` and `conflictingFiles` on a
+        // now-resolved entry and persist that to the session file. The union
+        // type rules that out.
         session.patches[session.currentIndex] = {
             filename: currentPatch.filename,
             status: 'resolved',

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

@@ -1,5 +1,5 @@
 /**
- * `fireforge rebase` — semi-automated Firefox source version upgrade.
+ * `fireforge rebase`: semi-automated Firefox source version upgrade.
  *
  * Orchestrates the full patch-rebase workflow:
  *   1. Reset engine to baseline

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge rebase` — semi-automated Firefox source version upgrade.
+ * `fireforge rebase`: semi-automated Firefox source version upgrade.
  *
  * Orchestrates the full patch-rebase workflow:
  *   1. Reset engine to baseline
@@ -33,7 +33,7 @@ async function handleFreshStart(projectRoot, options) {
     const isDryRun = options.dryRun === true;
     const maxFuzz = options.maxFuzz ?? 3;
     intro(isDryRun ? 'FireForge Rebase (dry run)' : 'FireForge Rebase');
-    // One read decides liveness AND validity: a pathExists pre-probe here left
+    // One read decides liveness and validity: a pathExists pre-probe here left
     // a window where the file vanished between probe and read, reporting
     // "already in progress" with no session on disk.
     const existing = await readRebaseSession(projectRoot);
@@ -93,7 +93,7 @@ async function handleFreshStart(projectRoot, options) {
     const resetSpinner = spinner('Resetting engine to baseline...');
     await resetChanges(paths.engine);
     resetSpinner.stop('Engine reset to baseline');
-    // Clear Furnace state — the engine no longer contains deployed components.
+    // Clear Furnace state: the engine no longer contains deployed components.
     await clearAppliedFurnaceState(projectRoot);
     // Create rebase session
     const allPatches = await discoverPatches(paths.patches);

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

@@ -26,8 +26,8 @@ import { printSummary } from './summary.js';
 /**
  * Builds the session entry for a patch-apply outcome.
  *
- * Constructing a whole entry rather than assigning fields is what the
- * discriminated union buys: a status can never be flipped while the previous
+ * The entry is constructed whole rather than assigned field by field, so the
+ * discriminated union stops a status being flipped while the previous
  * status's payload stays behind, which is how
  * `{ status: 'resolved', error, conflictingFiles }` reaches the session file.
  *
@@ -68,9 +68,10 @@ export async function runPatchLoop(projectRoot, session, paths, maxFuzz, waitLoc
         const patchFile = allPatches.find((p) => p.filename === entry.filename);
         if (!patchFile) {
             warn(`Patch file not found for ${entry.filename}, skipping.`);
-            // Replaced, not mutated: the entry is a discriminated union, so a status
-            // change is a new value rather than a field assignment. That is what
-            // stops a status flip stranding the previous status's payload.
+            // The entry is replaced rather than mutated: it is a discriminated
+            // union, so a status change is a new value rather than a field
+            // assignment, and a status flip cannot strand the previous status's
+            // payload.
             session.patches[i] = { filename: entry.filename, status: 'skipped' };
             session.currentIndex = i + 1;
             await saveRebaseSession(projectRoot, session);
@@ -101,9 +102,9 @@ export async function runPatchLoop(projectRoot, session, paths, maxFuzz, waitLoc
         }
         else {
             // Set pendingResolution in state for visibility. Kept outside the
-            // critical section — it is advisory UX, not a correctness invariant,
-            // and its absence would at most cause `fireforge status` to omit the
-            // pending-conflict hint until the next state write.
+            // critical section, since it is advisory UX rather than a correctness
+            // invariant, and its absence would at most cause `fireforge status`
+            // to omit the pending-conflict hint until the next state write.
             await updateState(projectRoot, (current) => ({
                 ...current,
                 pendingResolution: {
@@ -145,7 +146,7 @@ export async function runPatchLoop(projectRoot, session, paths, maxFuzz, waitLoc
     s.stop('All patches applied');
     // Re-export all successfully applied patches. Failures here mean the
     // engine has been rebased onto the new Firefox version but some .patch
-    // files were not refreshed — the queue would lie about what version each
+    // files were not refreshed, so the queue would lie about what version each
     // patch was tested against if we proceeded to stamp. Refuse to claim
     // success and leave the session in place so the user can recover via
     // `fireforge rebase --continue` after fixing the underlying cause.
@@ -164,7 +165,7 @@ export async function runPatchLoop(projectRoot, session, paths, maxFuzz, waitLoc
             `still describe the pre-rebase source. Re-export them manually (e.g. ` +
             `"fireforge re-export") and verify the overlapping hunks before the next import.`);
     }
-    // Stamp versions — only for patches whose .patch file now actually
+    // Stamp versions, only for patches whose .patch file now actually
     // reflects the new source (overlap-skipped ones keep their old stamp so
     // the queue does not lie about what each patch was tested against).
     const overlapSkippedSet = new Set(overlapSkipped);
@@ -177,19 +178,19 @@ export async function runPatchLoop(projectRoot, session, paths, maxFuzz, waitLoc
     }
     // Stamp every Furnace override's `baseVersion` to match the rebased
     // Firefox source version. Without it, a successful source bump leaves
-    // overrides in a doctor-failing drift state — each still claiming the
-    // pre-rebase source as its baseline — and every subsequent
+    // overrides in a doctor-failing drift state, each still claiming the
+    // pre-rebase source as its baseline, and every subsequent
     // `fireforge doctor` fails `Furnace component validation`. The stamp is
     // unconditional per the helper's contract: rebase already succeeded on
     // the patch side, so the operator is committing to the new source
-    // baseline; per-component health checking stays with
+    // baseline. Per-component health checking stays with
     // `fireforge furnace validate` / `doctor --repair-furnace`.
     //
     // "Unconditional" means unconditional on component health, not on the
     // value: `stampFurnaceOverrideBaseVersions` assigns and persists whatever
     // string it is handed, so a session whose `toVersion` is not a real
     // Firefox version would rewrite every override's baseline to that value.
-    // `isValidSession` rejects such a session at read time; this refuses to
+    // `isValidSession` rejects such a session at read time. This refuses to
     // persist it even if a future caller reaches here another way.
     if (!isValidFirefoxVersion(session.toVersion)) {
         throw new RebaseError(`Refusing to stamp Furnace override baseVersion(s): the rebase session's target version ` +
@@ -220,13 +221,13 @@ async function reExportAppliedPatches(session, paths, waitLockSeconds) {
     const manifest = await loadPatchesManifest(paths.patches);
     if (!manifest)
         return { failures, overlapSkipped };
-    // Re-export writes `getDiffForFilesAgainstHead(files)` — the CUMULATIVE
+    // Re-export writes `getDiffForFilesAgainstHead(files)`, the cumulative
     // diff of those files. For a file claimed by two patches (a supported
-    // `--allow-overlap` queue), that diff contains BOTH patches' hunks, so
+    // `--allow-overlap` queue), that diff contains both patches' hunks, so
     // rewriting each patch with it would duplicate the shared file's hunks
     // into every owner: the very next import then fails or silently
     // double-materialises. Refuse to auto-re-export any patch whose files
-    // overlap another patch; the operator re-exports those manually where
+    // overlap another patch. The operator re-exports those manually where
     // per-patch attribution is possible.
     const fileOwners = new Map();
     for (const patch of manifest.patches) {

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

@@ -20,7 +20,7 @@ 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');
@@ -37,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.');
@@ -64,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))) {

package/dist/src/commands/run.js

@@ -25,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.
@@ -74,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);
@@ -104,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');
     }
@@ -141,7 +141,7 @@ 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 ${smokeExit}s; cold starts on slow machines often exceed 30s.`);
@@ -153,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}`);
@@ -171,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.
@@ -193,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.
@@ -238,7 +238,7 @@ async function runSmokeExit(engineDir, options) {
         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) {
@@ -248,9 +248,9 @@ async function runSmokeExit(engineDir, options) {
 }
 /**
  * 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 = [];
@@ -286,7 +286,7 @@ function reportSmokeSummary(args) {
     info('');
     info(`Smoke run complete: ${seconds}s elapsed of ${windowSeconds}s window${suffix}`);
     info(`  Unallowed errors: ${args.findings.length}`);
-    // The "suppressed errors" count is what the exit contract cares about — the
+    // 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
@@ -294,9 +294,9 @@ function reportSmokeSummary(args) {
     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.
+    // 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) => {

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

@@ -27,7 +27,7 @@ function renderLicenseTemplate(license, template, vendor, now = new Date()) {
  */
 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;
@@ -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;