@hominis/fireforge 0.43.0 → 0.44.0

package/dist/src/commands/typecheck.js

@@ -1,19 +1,17 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge typecheck` — whole-project TypeScript type checking
- * driven by user-supplied jsconfig.json paths.
+ * `fireforge typecheck` — whole-project TypeScript type checking driven by
+ * user-supplied jsconfig.json paths.
  *
- * Distinct from `patchLint.checkJs`: that pass is patch-hygiene
- * (scoped to patch-owned `.sys.mjs`, run automatically by
- * `fireforge lint`); this command is CI-grade — it runs whole
- * projects with the user's own compiler options and is intended as
- * a CI gate. The two share their Firefox-globals shim and the same
- * suppressed-diagnostic set so a file that lints clean cannot fail
- * typecheck for a reason the operator could not have inferred from
- * the docs.
+ * Distinct from `patchLint.checkJs`: that pass is patch-hygiene (scoped to
+ * patch-owned `.sys.mjs`, run automatically by `fireforge lint`); this
+ * command is CI-grade — it runs whole projects with the user's own compiler
+ * options. The two share their Firefox-globals shim and the same
+ * suppressed-diagnostic set so a file that lints clean cannot fail typecheck
+ * for a reason the operator could not have inferred from the docs.
  *
- * Exits non-zero on any error-severity diagnostic. Warnings print
- * but do not fail. Designed for CI use.
+ * Exits non-zero on any error-severity diagnostic. Warnings print but do not
+ * fail.
  */
 import { Command } from 'commander';
 import { getProjectPaths, loadConfig } from '../core/config.js';
@@ -22,7 +20,7 @@ import { findJsconfigPathsDrift, syncFurnaceJsconfigPaths } from '../core/furnac
 import { withPrivateGitIndex } from '../core/git-readonly-index.js';
 import { buildPatchQueueContext } from '../core/patch-lint.js';
 import { relativeForDisplay, runTypecheck } from '../core/typecheck.js';
-import { GeneralError } from '../errors/base.js';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { buildPerRunCheckJs } from './lint-per-run-checkjs.js';
@@ -34,7 +32,7 @@ import { buildPerRunCheckJs } from './lint-per-run-checkjs.js';
 export function resolveTypecheckProjects(configTypecheck, override) {
     if (override !== undefined) {
         if (override.trim() === '') {
-            throw new GeneralError('--project requires a non-empty path');
+            throw new InvalidArgumentError('--project requires a non-empty path', '--project');
         }
         return {
             projects: [override],
@@ -69,8 +67,8 @@ function formatIssue(projectRoot, issue) {
  */
 export async function typecheckCommand(projectRoot, options) {
     intro('FireForge typecheck');
-    // Read-only to the operator, an index WRITER to git without this scope
-    //: the Furnace jsconfig reconciler and the project resolution
+    // Read-only to the operator, an index WRITER to git without this scope:
+    // the Furnace jsconfig reconciler and the project resolution
     // below touch `engine/`, and any git plumbing they reach would refresh
     // the primary checkout's index under a concurrent `fireforge test`.
     return withPrivateGitIndex(getProjectPaths(projectRoot).engine, () => runTypecheckCommandBody(projectRoot, options));
@@ -84,10 +82,9 @@ async function runTypecheckCommandBody(projectRoot, options) {
     const config = await loadConfig(projectRoot);
     const cfg = resolveTypecheckProjects(config.typecheck, options.project);
     // Regenerate a stale Furnace-managed jsconfig before running: the generated
-    // `compilerOptions.paths` shim drifts when components are added/renamed
+    // `compilerOptions.paths` shim drifts when components are added or renamed
     // without a re-deploy, and a stale shim reports type errors in files the
-    // session never touched (e.g. 47 phantom errors from an out-of-date
-    // chrome-module mapping). Run the same reconciler `furnace deploy`/`sync`
+    // session never touched. Run the same reconciler `furnace deploy`/`sync`
     // use so typecheck checks against the current workspace.
     await regenerateStaleGeneratedJsconfig(projectRoot);
     info(`Running typecheck across ${String(cfg.projects.length)} project(s): ${cfg.projects.join(', ')}`);
@@ -95,11 +92,11 @@ async function runTypecheckCommandBody(projectRoot, options) {
     // Fold the EXPORT-TIME authority into this pass. Per-patch lint runs
     // checkJs over the queue's patch-owned modules in relative isolation and
     // resolves imported typedefs differently from the whole-project pass, so
-    // `typecheck` could report 0 errors across every
-    // project while the very next `export` failed per-patch lint with
-    // `checkjs-type-error` findings. Two authorities that disagree, with the
-    // stricter one speaking only at export time, is not a usable CI gate:
-    // running both here makes `typecheck` green MEAN export-clean types.
+    // `typecheck` can report 0 errors across every project while the very next
+    // `export` fails per-patch lint with `checkjs-type-error` findings. Two
+    // authorities that disagree, with the stricter one speaking only at export
+    // time, is not a usable CI gate: running both here makes `typecheck` green
+    // MEAN export-clean types.
     const patchIssues = await collectPatchLintCheckJsIssues(projectRoot);
     reportResults(projectRoot, results, patchIssues);
 }
@@ -154,9 +151,9 @@ async function regenerateStaleGeneratedJsconfig(projectRoot) {
 export function reportResults(projectRoot, results, patchLintIssues = []) {
     let totalErrors = 0;
     let totalWarnings = 0;
-    // Per-patch checkJs findings are reported in the SAME tally:
-    // a split report would let an operator read "0 errors" off the project
-    // summary and still be refused at export.
+    // Per-patch checkJs findings are reported in the SAME tally: a split
+    // report would let an operator read "0 errors" off the project summary
+    // and still be refused at export.
     for (const issue of patchLintIssues) {
         if (issue.severity === 'error')
             totalErrors += 1;

package/dist/src/commands/verify.js

@@ -42,12 +42,12 @@ import { info, intro, outro, success, warn } from '../utils/logger.js';
  * install time.
  */
 async function detectDanglingRegistrations(patchesDir, engineDir, patches) {
-    // Aggregate the set of all paths that any patch in the queue is
-    // responsible for (per `filesAffected`). We deliberately do NOT parse
-    // individual patch bodies for new-file creations here: `filesAffected`
-    // is already the contract manifest callers rely on, and
-    // `validatePatchesManifestConsistency` has already ensured the two
-    // are in sync. Using that list keeps this validator fast.
+    // Aggregate the set of all paths any patch in the queue is responsible for
+    // (per `filesAffected`). Individual patch bodies are deliberately NOT
+    // parsed for new-file creations here: `filesAffected` is already the
+    // contract manifest callers rely on, and
+    // `validatePatchesManifestConsistency` has already ensured the two are in
+    // sync. Using that list keeps this validator fast.
     const coveredByPatches = new Set();
     for (const patch of patches) {
         for (const file of patch.filesAffected) {
@@ -74,12 +74,11 @@ async function detectDanglingRegistrations(patchesDir, engineDir, patches) {
         for (const ref of refs) {
             if (coveredByPatches.has(ref.targetPath))
                 continue;
-            // Engine existence check: if the target file is already present
-            // in engine/ (e.g. upstream Firefox ships it, or a separate
-            // baseline branch has it), the registration is not dangling.
-            // We cannot sanely probe "is this tracked by git" without a git
-            // round-trip; existence on disk is a close-enough proxy for
-            // verify's read-only context.
+            // Engine existence check: if the target file is already present in
+            // engine/ (upstream Firefox ships it, or a separate baseline branch
+            // has it), the registration is not dangling. "Is this tracked by git"
+            // cannot be probed without a git round-trip; existence on disk is a
+            // close-enough proxy for verify's read-only context.
             if (await pathExists(join(engineDir, ref.targetPath)))
                 continue;
             issues.push({
@@ -171,9 +170,8 @@ export async function collectPatchQueueHealth(projectRoot) {
         }
         // Engine-aware module-resolution preflight. The queue-level
         // `unregistered-system-module` rule only sees modules a patch NEWLY
-        // CREATES; this asks the same question of the engine, so an import
-        // ADDED to an existing module — the shape that recurred and cost a
-        // rebuild cycle — is named as text instead of surfacing later as a
+        // CREATES; this asks the same question of the engine, so an import ADDED
+        // to an existing module is named as text instead of surfacing later as a
         // bare `xpcshell return code: -11` with zero output.
         if (await pathExists(paths.engine)) {
             const unresolved = await findUnresolvedSystemModuleImports(paths.engine, manifest.patches.flatMap((patch) => patch.filesAffected));

package/dist/src/commands/watch.js

@@ -2,13 +2,13 @@
 import { delimiter, dirname } from 'node:path';
 import { Command } from 'commander';
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { assertEngineExists } from '../core/engine-precondition.js';
 import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
 import { generateMozconfig, hasBuildArtifacts, hasRunnableBundle, watchWithOutput, } from '../core/mach.js';
 import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
 import { GeneralError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
-import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner, verbose } from '../utils/logger.js';
 import { exec, findExecutable } from '../utils/process.js';
 const WATCHMAN_PROBE_TIMEOUT_MS = 5000;
@@ -56,15 +56,18 @@ function buildWatchmanConfigureTimeMessage() {
     return ('Watch mode cannot use the current obj-* build because watchman was not available when Firefox was configured.\n\n' +
         'Install watchman, delete the current obj-* directory, run "fireforge build" again, then retry "fireforge watch".');
 }
+function hasWatchPermissionFailure(output) {
+    return /Operation not permitted|EPERM|EACCES/i.test(output);
+}
 /**
  * Builds the generic unsupported-watch failure message.
+ *
  * @param exitCode - Exit code returned by `mach watch`
- * @param watchmanPath - Optional absolute path to the resolved watchman binary; surfaced in the guidance so the operator can see whether FireForge actually found one.
+ * @param watchmanPath - Optional absolute path to the resolved watchman
+ *   binary; surfaced in the guidance so the operator can see whether
+ *   FireForge actually found one.
  * @returns User-facing failure guidance
  */
-function hasWatchPermissionFailure(output) {
-    return /Operation not permitted|EPERM|EACCES/i.test(output);
-}
 function buildUnsupportedWatchMessage(exitCode, watchmanPath, output = '') {
     const watchmanLine = watchmanPath
         ? `  - FireForge resolved watchman at ${watchmanPath} and prepended its directory to the mach subprocess PATH. If mach still did not see it, ensure that path is stable between runs.\n`
@@ -101,18 +104,14 @@ export async function watchCommand(projectRoot) {
     const config = await loadConfig(projectRoot);
     const paths = getProjectPaths(projectRoot);
     // Check if engine exists
-    if (!(await pathExists(paths.engine))) {
-        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
-    }
-    // Resolve the watchman binary to an absolute path up-front so we can
-    // (a) refuse fast when it is missing AND (b) prepend its directory to
-    // the mach subprocess PATH. 2026-04-24 eval Finding 12: on macOS,
-    // `which watchman` from the interactive shell returns
-    // `/opt/homebrew/bin/watchman`, but the Node subprocess PATH
-    // frequently omits `/opt/homebrew/bin`, so the shell probe passed and
-    // mach's `watch-project` call then timed out because its own PATH
-    // lookup for watchman failed. Threading the directory through the
-    // subprocess env fixes it.
+    await assertEngineExists(paths.engine);
+    // Resolve the watchman binary to an absolute path up-front so we can (a)
+    // refuse fast when it is missing AND (b) prepend its directory to the mach
+    // subprocess PATH. On macOS, `which watchman` from an interactive shell
+    // returns `/opt/homebrew/bin/watchman`, but the Node subprocess PATH
+    // frequently omits `/opt/homebrew/bin` — so the shell probe passes and
+    // mach's `watch-project` call then times out on its own failed PATH
+    // lookup. Threading the directory through the subprocess env fixes it.
     const watchmanPath = await findExecutable('watchman');
     if (!watchmanPath) {
         throw new GeneralError('Watch mode requires watchman to be installed and available in PATH.\n\n' +
@@ -166,12 +165,11 @@ export async function watchCommand(projectRoot) {
     info('Starting watch mode...');
     info('Press Ctrl+C to stop\n');
     // Compose the subprocess env: start from the parent process env, then
-    // prepend the resolved watchman directory to PATH so the mach
-    // subprocess sees the same binary our probe just validated. Without
-    // this, a watchman install on `/opt/homebrew/bin` (the default
-    // homebrew prefix on Apple Silicon) is absent from the PATH Node
-    // inherits on spawn, and `mach watch` fails at the `watch-project`
-    // subscription step.
+    // prepend the resolved watchman directory to PATH so the mach subprocess
+    // sees the same binary the probe just validated. Without it, a watchman
+    // install under `/opt/homebrew/bin` is absent from the PATH Node inherits
+    // on spawn and `mach watch` fails at the `watch-project` subscription
+    // step.
     const watchmanDir = dirname(watchmanPath);
     const existingPath = process.env['PATH'] ?? '';
     const pathSegments = existingPath.split(delimiter).filter((segment) => segment.length > 0);

package/dist/src/commands/wire.js

@@ -19,10 +19,9 @@ function printWireDryRun(engineDir, name, subscriptDir, domFilePath, domTargetPa
     info(`  source: ${subscriptDir}/${name}.js`);
     info(`  browser-main.js: loadSubScript("chrome://browser/content/${name}.js")`);
     if (options.init) {
-        // Show the coerced form so the preview matches the emitted block.
-        // Before 0.16.0 the preview echoed the raw input ("EvalStartup.init"),
-        // which did not reflect that the real run writes `EvalStartup.init();`
-        // to browser-init.js.
+        // Show the coerced form so the preview matches the emitted block —
+        // echoing the raw input ("X.init") does not reflect that the real run
+        // writes `X.init();` to browser-init.js.
         info(`  browser-init.js: ${coerceToCall(options.init)}`);
     }
     if (options.destroy) {
@@ -85,14 +84,13 @@ function validateWireName(name) {
     }
 }
 /**
- * Asserts that the resolved chrome document both exists on disk AND
- * exposes an insertion anchor (`#include browser-sets.inc` or
- * `<html:body>`) that `addDomFragment` can splice into. Fires the same
- * check in dry-run and real-run mode, so the preview and execution
- * agree on whether the target is wireable before any disk mutations
- * happen. Before 0.16.0 this check only ran on the real branch, which
- * let the dry-run produce a plausible-looking plan that the real run
- * then refused with `Could not find insertion point in chrome document`.
+ * Asserts that the resolved chrome document both exists on disk AND exposes
+ * an insertion anchor (`#include browser-sets.inc` or `<html:body>`) that
+ * `addDomFragment` can splice into. Fires in dry-run and real-run mode
+ * alike, so the preview and execution agree on whether the target is
+ * wireable before any disk mutations happen. Running it only on the real
+ * branch lets the dry-run produce a plausible-looking plan the real run then
+ * refuses with `Could not find insertion point in chrome document`.
  */
 async function assertDomTargetIsWireable(projectRoot, domFilePath, domTargetPath) {
     const paths = getProjectPaths(projectRoot);
@@ -151,37 +149,35 @@ async function ensureSubscriptSourceExists(projectRoot, subscriptDir, name, dryR
  * engine/. Returns undefined when `--dom` was not supplied.
  */
 async function resolveDomFragmentPath(projectRoot, dom) {
-    // Validate DOM fragment file exists and compute path relative to engine root.
-    //
-    // Accepts three shapes:
+    // Validate the DOM fragment file exists and compute its path relative to
+    // the engine root. Accepts three shapes:
     //  - Absolute paths (`/project/engine/browser/base/content/foo.inc.xhtml`)
     //  - Repo-root-relative forms (`engine/browser/base/content/foo.inc.xhtml`)
     //  - Engine-relative forms (`browser/base/content/foo.inc.xhtml`)
     //
-    // Before the engine-prefix normalization, passing an `engine/…`-prefixed
-    // relative path from the repo root double-rooted through
-    // `toRootRelativePath(engineDir, …)` — `resolve(engineDir, 'engine/…')`
-    // landed at `engineDir/engine/…`, which is still "inside" engineDir but
-    // named as a second-level `engine/…` entry. The computed `#include`
-    // then read `../../../engine/browser/base/content/foo.inc.xhtml`,
-    // packaging-breaking nonsense. For absolute inputs this pre-existing
-    // contract was fine — `toRootRelativePath` handles absolute candidates
-    // correctly — so we only strip the prefix when the input is relative.
+    // Without the engine-prefix normalization, an `engine/…`-prefixed relative
+    // path from the repo root double-roots through
+    // `toRootRelativePath(engineDir, …)`: `resolve(engineDir, 'engine/…')`
+    // lands at `engineDir/engine/…`, still "inside" engineDir but named as a
+    // second-level `engine/…` entry, and the computed `#include` then reads
+    // `../../../engine/browser/base/content/foo.inc.xhtml`. Absolute inputs are
+    // already handled correctly by `toRootRelativePath`, so the prefix is only
+    // stripped when the input is relative.
     if (!dom)
         return undefined;
     {
         const paths = getProjectPaths(projectRoot);
         const domCandidate = isExplicitAbsolutePath(dom) ? dom : stripEnginePrefix(dom);
-        // `pathExists` resolves relative paths against CWD, so an engine-
-        // relative `domCandidate` (e.g. `browser/base/content/foo.inc.xhtml`)
-        // would be probed inside the operator's shell directory rather than
-        // the engine root and fail "DOM fragment file not found" even when
-        // the file is sitting at engine/<path>. Mirror `register.ts`: probe
-        // the absolute path as-is, otherwise join with `paths.engine` first.
-        // The `isPathInsideRoot` / `toRootRelativePath` calls below keep
-        // operating on `domCandidate` because they internally resolve
-        // relative candidates against the engine root, which matches the
-        // probe path we just built.
+        // `pathExists` resolves relative paths against CWD, so an
+        // engine-relative `domCandidate` (e.g.
+        // `browser/base/content/foo.inc.xhtml`) would be probed inside the
+        // operator's shell directory rather than the engine root and fail "DOM
+        // fragment file not found" even when the file is sitting at
+        // engine/<path>. Mirror `register.ts`: probe the absolute path as-is,
+        // otherwise join with `paths.engine` first. The `isPathInsideRoot` /
+        // `toRootRelativePath` calls below keep operating on `domCandidate`
+        // because they internally resolve relative candidates against the engine
+        // root, matching the probe path built here.
         const domProbePath = isExplicitAbsolutePath(domCandidate)
             ? domCandidate
             : join(paths.engine, domCandidate);
@@ -281,15 +277,11 @@ export async function wireCommand(projectRoot, name, options = {}) {
         // --after and have it forwarded unchanged to the lookup layer.
         validateWireName(options.after);
     }
-    // Validate init/destroy expressions BEFORE the dry-run/real fork so
-    // both paths enforce the same contract. Pre-0.16.0, validation only
-    // ran inside `addInitToBrowserInit`/`addDestroyToBrowserInit` (the
-    // real-execution path), so `--dry-run --init 'void 0'` succeeded and
-    // rendered a plausible-looking preview even though the real run would
-    // reject the same arguments. Dropping `void 0` into the template
-    // silently (or breaking out of the string literal) was already
-    // prevented downstream — this hoist just makes the failure surface
-    // identical in preview mode.
+    // Validate init/destroy expressions BEFORE the dry-run/real fork so both
+    // paths enforce the same contract. Validating only inside
+    // `addInitToBrowserInit`/`addDestroyToBrowserInit` — the real-execution
+    // path — lets `--dry-run --init 'void 0'` succeed and render a plausible
+    // preview even though the real run rejects the same arguments.
     if (options.init !== undefined) {
         validateWireExpression(options.init, 'init expression');
     }
@@ -299,14 +291,15 @@ export async function wireCommand(projectRoot, name, options = {}) {
     consumeParserFallbackEvents();
     const subscriptDir = await resolveWireSubscriptDir(projectRoot, options);
     const domFilePath = await resolveDomFragmentPath(projectRoot, options.dom);
-    // Resolve the chrome document the `#include` directive will land in.
-    // Only consulted when `--dom` is supplied — we still resolve it here so
-    // the dry-run plan can print the target accurately.
+    // Resolve the chrome document the `#include` directive will land in. Only
+    // consulted when `--dom` is supplied — resolved here anyway so the dry-run
+    // plan can print the target accurately.
     //
-    // `stripEnginePrefix` is applied so `--target engine/browser/base/browser.xhtml`
-    // and `--target browser/base/browser.xhtml` are treated identically,
-    // matching the `--dom` normalization above. Absolute `--target` paths
-    // stay absolute (the containment check downstream rejects them).
+    // `stripEnginePrefix` is applied so
+    // `--target engine/browser/base/browser.xhtml` and
+    // `--target browser/base/browser.xhtml` are treated identically, matching
+    // the `--dom` normalization above. Absolute `--target` paths stay absolute
+    // (the containment check downstream rejects them).
     const normalizedTarget = options.target !== undefined && !isExplicitAbsolutePath(options.target)
         ? stripEnginePrefix(options.target)
         : options.target;
@@ -317,19 +310,16 @@ export async function wireCommand(projectRoot, name, options = {}) {
     if (domFilePath) {
         await assertDomTargetIsWireable(projectRoot, domFilePath, domTargetPath);
     }
-    // Verify the subscript file exists in engine/ (skip for dry-run:
-    // dry-run is meant to preview the mutation plan without requiring
-    // the subscript to already exist, matching the "plan before write"
-    // pattern operators rely on for setup scripts).
+    // Verify the subscript file exists in engine/, skipping for dry-run:
+    // preview is meant to show the mutation plan without requiring the
+    // subscript to already exist, matching the "plan before write" pattern
+    // setup scripts rely on.
     //
-    // Dry-run keeps the existence check advisory rather than fatal: the
-    // "wire first, create file after" workflow is a legitimate use of
-    // preview, but operators who run dry-run over a typo were surprised
-    // when the real command then refused with `Subscript file not
-    // found`. 2026-04-23 eval (Finding in eval 2): dry-run produced a
-    // plausible plan and the non-dry-run invocation then errored. The
-    // info line surfaces the mismatch in preview mode so the operator
-    // can act on the warning before re-running without --dry-run.
+    // The check stays advisory rather than fatal in dry-run because
+    // "wire first, create file after" is a legitimate use of preview — but a
+    // dry-run over a typo would otherwise produce a plausible plan and the
+    // real command then refuse with `Subscript file not found`. The info line
+    // surfaces the mismatch in preview mode.
     await ensureSubscriptSourceExists(projectRoot, subscriptDir, name, options.dryRun ?? false);
     if (options.dryRun) {
         printWireDryRun(getProjectPaths(projectRoot).engine, name, subscriptDir, domFilePath, domTargetPath, options);

package/dist/src/core/ast-utils.d.ts

@@ -36,14 +36,15 @@ export declare function parseModule(content: string, onComment?: acorn.Comment[]
  *
  * **Caller obligation: you must already have discriminated on `node.type`.**
  * This performs no runtime check — it exists to attach acorn's `start`/`end`
- * offsets to a node the caller has *already* narrowed, typically inside a
- * `if (node.type === 'CallExpression')` branch or an equivalent walker guard.
- * Calling it on an undiscriminated node produces a value whose type is a lie.
+ * offsets to a node the caller has *already* narrowed, typically inside an
+ * `if (node.type === 'CallExpression')` branch or an equivalent walker
+ * guard. Calling it on an undiscriminated node produces a value whose type
+ * is a lie.
  *
- * A runtime `type` assertion was considered and rejected: every call site sits
- * in the hot loop of a lint or registration walker, and all of them are
- * already post-narrowing, so the check would cost traversal time on every node
- * to re-prove something the enclosing branch established.
+ * No runtime `type` assertion: every call site sits in the hot loop of a lint
+ * or registration walker and is already post-narrowing, so the check would
+ * cost traversal time on every node to re-prove what the enclosing branch
+ * established.
  */
 export declare function asEstree<T extends estree.Node>(node: estree.Node): AcornESTreeNode<T>;
 /**

package/dist/src/core/ast-utils.js

@@ -55,14 +55,15 @@ export function parseModule(content, onComment) {
  *
  * **Caller obligation: you must already have discriminated on `node.type`.**
  * This performs no runtime check — it exists to attach acorn's `start`/`end`
- * offsets to a node the caller has *already* narrowed, typically inside a
- * `if (node.type === 'CallExpression')` branch or an equivalent walker guard.
- * Calling it on an undiscriminated node produces a value whose type is a lie.
+ * offsets to a node the caller has *already* narrowed, typically inside an
+ * `if (node.type === 'CallExpression')` branch or an equivalent walker
+ * guard. Calling it on an undiscriminated node produces a value whose type
+ * is a lie.
  *
- * A runtime `type` assertion was considered and rejected: every call site sits
- * in the hot loop of a lint or registration walker, and all of them are
- * already post-narrowing, so the check would cost traversal time on every node
- * to re-prove something the enclosing branch established.
+ * No runtime `type` assertion: every call site sits in the hot loop of a lint
+ * or registration walker and is already post-narrowing, so the check would
+ * cost traversal time on every node to re-prove what the enclosing branch
+ * established.
  */
 export function asEstree(node) {
     return node;

package/dist/src/core/branding.d.ts

@@ -15,12 +15,10 @@ export declare class BrandingError extends FireForgeError {
  * fails deep inside moz.build resolution with a confusing "path does not
  * exist" message. Surface it as an actionable preflight instead.
  *
- * The root cause is that setup renders templates under `configs/` with
- * `${binaryName}` baked in at setup time; a subsequent edit to
- * `fireforge.json`'s `binaryName` (or a re-setup without re-templating)
- * leaves those baked-in names stale while `setupBranding` continues to use
- * the current `config.binaryName`. Both directions (mozconfig ahead of
- * config, config ahead of mozconfig) produce the same class of build break.
+ * Setup renders templates under `configs/` with `${binaryName}` baked in; a
+ * later edit to `fireforge.json`'s `binaryName` (or a re-setup without
+ * re-templating) leaves those names stale while `setupBranding` keeps using
+ * the current value. Both directions produce the same class of build break.
  */
 export declare class BrandingMozconfigMismatchError extends FireForgeError {
     readonly expectedBrandingDir: string;
@@ -46,9 +44,8 @@ export interface BrandingConfig {
      * Project license (from fireforge.json). Used to stamp the generated
      * `configure.sh`, `brand.properties`, and `brand.ftl` files with the
      * matching header so `patch-lint` does not flag them for
-     * `missing-license-header` when the project is not MPL-2.0. Optional for
-     * backwards compatibility with pre-0.16 callers that did not thread the
-     * license through — falls back to {@link DEFAULT_LICENSE}.
+     * `missing-license-header` when the project is not MPL-2.0. Optional;
+     * falls back to {@link DEFAULT_LICENSE}.
      */
     license?: ProjectLicense;
 }
@@ -56,12 +53,10 @@ export interface BrandingConfig {
  * Splits the reverse-domain `appId` for macOS bundle identity. Upstream
  * `toolkit/moz.configure` composes `CFBundleIdentifier` as
  * `<--with-distribution-id>.<MOZ_MACBUNDLE_ID>` (the distribution id
- * defaults to `org.mozilla`), so branding `configure.sh` must carry only
- * the LEAF segment while the generated mozconfig carries the remainder as
+ * defaults to `org.mozilla`), so branding `configure.sh` must carry only the
+ * LEAF segment while the generated mozconfig carries the remainder as
  * `--with-distribution-id`. Writing the full appId into `MOZ_MACBUNDLE_ID`
- * double-prefixes the shipped bundle id (observed:
- * `org.mozilla.org.hominis.browser`, and with a distribution-id flag,
- * `org.hominis.org.hominis.browser`). Config validation guarantees a
+ * double-prefixes the shipped bundle id. Config validation guarantees a
  * reverse-domain id, so the split always has both halves.
  */
 export declare function splitAppId(appId: string): {

package/dist/src/core/branding.js

@@ -22,12 +22,10 @@ export class BrandingError extends FireForgeError {
  * fails deep inside moz.build resolution with a confusing "path does not
  * exist" message. Surface it as an actionable preflight instead.
  *
- * The root cause is that setup renders templates under `configs/` with
- * `${binaryName}` baked in at setup time; a subsequent edit to
- * `fireforge.json`'s `binaryName` (or a re-setup without re-templating)
- * leaves those baked-in names stale while `setupBranding` continues to use
- * the current `config.binaryName`. Both directions (mozconfig ahead of
- * config, config ahead of mozconfig) produce the same class of build break.
+ * Setup renders templates under `configs/` with `${binaryName}` baked in; a
+ * later edit to `fireforge.json`'s `binaryName` (or a re-setup without
+ * re-templating) leaves those names stale while `setupBranding` keeps using
+ * the current value. Both directions produce the same class of build break.
  */
 export class BrandingMozconfigMismatchError extends FireForgeError {
     expectedBrandingDir;
@@ -57,12 +55,10 @@ export class BrandingMozconfigMismatchError extends FireForgeError {
  * Splits the reverse-domain `appId` for macOS bundle identity. Upstream
  * `toolkit/moz.configure` composes `CFBundleIdentifier` as
  * `<--with-distribution-id>.<MOZ_MACBUNDLE_ID>` (the distribution id
- * defaults to `org.mozilla`), so branding `configure.sh` must carry only
- * the LEAF segment while the generated mozconfig carries the remainder as
+ * defaults to `org.mozilla`), so branding `configure.sh` must carry only the
+ * LEAF segment while the generated mozconfig carries the remainder as
  * `--with-distribution-id`. Writing the full appId into `MOZ_MACBUNDLE_ID`
- * double-prefixes the shipped bundle id (observed:
- * `org.mozilla.org.hominis.browser`, and with a distribution-id flag,
- * `org.hominis.org.hominis.browser`). Config validation guarantees a
+ * double-prefixes the shipped bundle id. Config validation guarantees a
  * reverse-domain id, so the split always has both halves.
  */
 export function splitAppId(appId) {

package/dist/src/core/browser-wire.d.ts

@@ -1,4 +1,4 @@
-import type { RegisterResult } from './manifest-register.js';
+import type { RegisterResult } from './moz-manifest-register.js';
 export declare const DEFAULT_BROWSER_SUBSCRIPT_DIR = "browser/base/content";
 /**
  * Result of a wire operation.

package/dist/src/core/browser-wire.js

@@ -6,7 +6,7 @@ import { verbose } from '../utils/logger.js';
 import { toRootRelativePath } from '../utils/paths.js';
 import { getProjectPaths, loadConfig } from './config.js';
 import { assertSnapshotted, createRollbackJournal, restoreRollbackJournal, snapshotFile, } from './furnace-rollback.js';
-import { registerBrowserContent } from './manifest-register.js';
+import { registerBrowserContent } from './moz-manifest-register.js';
 import { DEFAULT_DOM_TARGET } from './wire-dom-fragment.js';
 import { addDestroyToBrowserInit, addDomFragment, addInitToBrowserInit, addSubscriptToBrowserMain, } from './wire-targets.js';
 export const DEFAULT_BROWSER_SUBSCRIPT_DIR = 'browser/base/content';
@@ -41,17 +41,14 @@ export async function wireSubscript(root, name, options = {}) {
             },
         };
     }
-    // Snapshot every file the five mutation steps might touch so a mid-sequence
-    // failure (most commonly the chrome-document insertion not finding an
-    // anchor) does not leave a half-wired browser behind. Before the rollback
-    // journal landed here, a failed `wire` would still have written new
-    // `loadSubScript` calls into browser-main.js, new init/destroy expressions
-    // into browser-init.js, and a new entry into browser/base/jar.mn — the
-    // operator then had to grep the engine tree for the partial mutation and
-    // hand-revert, or re-download. The snapshots cover the targets on every
-    // code path (init/destroy/DOM are conditional, so we snapshot only when
-    // the corresponding option would fire a write) plus the two files every
-    // wire touches.
+    // Snapshot every file the five mutation steps might touch so a
+    // mid-sequence failure (most commonly the chrome-document insertion not
+    // finding an anchor) does not leave a half-wired browser behind: new
+    // `loadSubScript` calls in browser-main.js, new init/destroy expressions
+    // in browser-init.js, and a new entry in browser/base/jar.mn, with no way
+    // back but a hand-revert or a re-download. Init/destroy/DOM are
+    // conditional, so those targets are snapshotted only when the
+    // corresponding option would fire a write.
     const journal = createRollbackJournal();
     const effectiveDomTargetPath = options.domFilePath
         ? toRootRelativePath(engineDir, options.domTargetPath ?? DEFAULT_DOM_TARGET)
@@ -64,14 +61,12 @@ export async function wireSubscript(root, name, options = {}) {
         await snapshotFile(journal, join(engineDir, effectiveDomTargetPath));
     }
     await snapshotFile(journal, join(engineDir, 'browser/base/jar.mn'));
-    // Compute the project-scoped patch-lint marker (`// <BINARY>:`) so
-    // every wire mutator can stamp it into the emitted comment block.
-    // Without this, `lintModificationComments` trips
-    // `missing-modification-comment` on wire-generated edits the next
-    // time the operator exports — the same tool wrote the code and a
-    // sibling tool then rejected it (eval 1 Finding #9). A broken config
+    // Compute the project-scoped patch-lint marker (`// <BINARY>:`) so every
+    // wire mutator can stamp it into the emitted comment block. Without it,
+    // `lintModificationComments` trips `missing-modification-comment` on
+    // wire-generated edits the next time the operator exports. A broken config
     // should not block the wire, so the fallback marker keeps the
-    // previous lint-friendly default when the config cannot be loaded.
+    // lint-friendly default when the config cannot be loaded.
     let marker = 'FIREFORGE:';
     try {
         const config = await loadConfig(root);