@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/commands/tree.js

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge tree` — copy-on-write verification clones.
+ * `fireforge tree`: copy-on-write verification clones.
  *
- * Trees enable concurrent READ-MOSTLY verification (lint, typecheck, status,
+ * Trees enable concurrent read-mostly verification (lint, typecheck, status,
  * verify, doctor, export dry-runs) beside a busy primary tree. Exports and
- * every other mutation stay strictly serial in the primary — a tree's
+ * every other mutation stay strictly serial in the primary, because a tree's
  * patches/components are snapshots with no merge model, and the tree guard
  * (cli.ts preAction + core/tree-guard.ts) refuses mutating commands inside a
  * tree.
@@ -13,8 +13,8 @@
  * directory, rewrites its mozinfo.json to the tree, and runs `mach configure`
  * inside the tree so the remaining configure output (config.status,
  * backend.mk, Makefile, config/autoconf.mk) stops naming the primary. That is
- * fail-closed by design — mach objdirs embed absolute source paths, and an
- * unrelocated clone would silently operate against the primary — and it is
+ * fail-closed by design (mach objdirs embed absolute source paths, and an
+ * unrelocated clone would silently operate against the primary), and it is
  * what admits build-less `fireforge test` inside that tree.
  */
 import { spawn } from 'node:child_process';
@@ -61,14 +61,14 @@ async function resolveObjdirForClone(projectRoot) {
 /**
  * Runs `mach configure` inside the tree's engine so the configure-generated
  * root files (config.status, backend.mk, Makefile, config/autoconf.mk) are
- * regenerated against the tree's paths — the mozinfo rewrite alone leaves
+ * regenerated against the tree's paths. The mozinfo rewrite alone leaves
  * those naming the primary, and a build-less in-tree `test` must never
  * consult primary state. Exit code 0 is not trusted on its own: configure
  * obeys MOZCONFIG / MOZ_OBJDIR, so the postcondition is verified afterwards
- * via `findObjdirRelocationViolation` — the intended objdir was configured,
+ * via `findObjdirRelocationViolation`: the intended objdir was configured,
  * its mozinfo points into the tree, and none of those root files still
  * names the primary engine (nested Makefiles are products of the verified
- * config.status; `.deps` build products are out of scope — see the
+ * config.status, and `.deps` build products are out of scope, see the
  * checker's doc). A failure throws before `cloneTree` writes the marker,
  * so the tree is removed and `clonedObjdir` is never recorded (fail-closed).
  */
@@ -102,7 +102,7 @@ export async function treeCreateCommand(projectRoot, name, options = {}) {
     intro('FireForge Tree Create');
     assertValidTreeName(name);
     // A marker we cannot parse still means "something claims this is a tree", so
-    // it must block nesting too — otherwise a corrupt marker is a licence to
+    // it must block nesting too. Otherwise a corrupt marker is a licence to
     // clone a snapshot into itself.
     const markerState = await readTreeMarker(projectRoot);
     if (markerState.kind !== 'absent') {
@@ -128,15 +128,15 @@ export async function treeCreateCommand(projectRoot, name, options = {}) {
             warn('No copy-on-write support detected — performing a full physical copy (--force-copy).');
         }
         // Courtesy fast-fail: refuse obvious no-build cases before waiting on
-        // locks. The result is DISCARDED — a build can still start before the
+        // locks. The result is discarded: a build can still start before the
         // locks below are held, so only the re-resolution under the build lock
         // is authoritative for what actually gets cloned.
         if (options.withObjdir === true) {
             await resolveObjdirForClone(projectRoot);
         }
-        // Snapshot under the PRIMARY engine-session lock so a mid-mutation
-        // state (half-applied export, furnace deploy) is never captured; an
-        // objdir snapshot additionally holds the primary BUILD lock, under
+        // Snapshot under the primary engine-session lock so a mid-mutation
+        // state (half-applied export, furnace deploy) is never captured. An
+        // objdir snapshot additionally holds the primary build lock, under
         // which the objdir is re-validated immediately before cloning so a
         // concurrent `fireforge build` can neither tear the obj-* mid-write
         // nor swap it after preflight. A failed clone (including the
@@ -183,8 +183,8 @@ export async function treeCreateCommand(projectRoot, name, options = {}) {
 export async function treeListCommand(projectRoot, options = {}) {
     if (options.json === true) {
         // stdout belongs exclusively to the JSON payload: engage machine mode so
-        // any diagnostic — including a listTrees failure rendered later by
-        // withErrorHandling, which also resets the mode — routes to stderr.
+        // any diagnostic, including a listTrees failure rendered later by
+        // withErrorHandling (which also resets the mode), routes to stderr.
         setMachineOutputMode(true);
         try {
             const trees = await listTrees(projectRoot);
@@ -280,17 +280,17 @@ async function treeExecCommand(projectRoot, name, args) {
             resolvePromise(code ?? 1);
         });
     }).finally(() => {
-        // With `stdio: 'inherit'` the child owned stdout — including any
-        // FIREFORGE-VERDICT line it emitted as its LAST stdout write. From here
+        // With `stdio: 'inherit'` the child owned stdout, including any
+        // FIREFORGE-VERDICT line it emitted as its last stdout write. From here
         // on the parent must not write stdout again, or its own refusal text
-        // (the GeneralError below, rendered by withErrorHandling) prints AFTER
+        // (the GeneralError below, rendered by withErrorHandling) prints after
         // the child's verdict and breaks the "verdict is the run's last stdout
         // line" contract at the tree-exec boundary. Sealing routes the parent's
-        // remaining output to stderr; withErrorHandling's finally clears it.
+        // remaining output to stderr. withErrorHandling's finally clears it.
         setStdoutSealed(true);
     });
     if (exitCode !== 0) {
-        throw new GeneralError(`tree exec: fireforge ${args.join(' ')} exited with code ${String(exitCode)}.`);
+        throw new GeneralError(`tree exec: fireforge ${args.join(' ')} exited with code ${exitCode}.`);
     }
 }
 /** Registers the tree command group on the CLI program. */
@@ -298,7 +298,12 @@ export function registerTree(program, context) {
     const { getProjectRoot, withErrorHandling } = context;
     const tree = program
         .command('tree')
-        .description('Manage copy-on-write verification clones of this project for concurrent read-mostly work (lint, typecheck, status, verify, export/re-export --dry-run; build-less test with create --with-objdir). Mutation commands are refused inside a tree.');
+        .description('Manage copy-on-write verification clones of this project for concurrent read-mostly work (lint, typecheck, status, verify, export/re-export --dry-run; build-less test with create --with-objdir). Mutation commands are refused inside a tree.')
+        // No-subcommand contract shared with `patch`/`token`/`furnace`: help on
+        // stdout, exit 0 (see `handleParseError` for the groups without an action).
+        .action(() => {
+        tree.outputHelp();
+    });
     addWaitLockOption(tree
         .command('create <name>')
         .description('Clone the project (engine included, obj-* excluded) into .fireforge/trees/<name> using filesystem copy-on-write (APFS clonefile / btrfs-XFS reflink). Refuses on filesystems without CoW support unless --force-copy explicitly accepts a full physical copy.')

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

@@ -1,10 +1,10 @@
 /**
- * `fireforge typecheck` — whole-project TypeScript type checking driven by
+ * `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
+ * 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.
@@ -21,15 +21,15 @@ import type { TypecheckProjectResult } from '../types/typecheck.js';
 export interface TypecheckCommandOptions {
     /**
      * Override `typecheck.projects` with a single jsconfig.json path
-     * for one-off verification. Replaces (does not augment) the config
-     * — useful to re-run a single project after fixing one of its
+     * for one-off verification. Replaces (does not augment) the config,
+     * which is useful to re-run a single project after fixing one of its
      * issues without waiting for the full set.
      */
     project?: string;
 }
 /**
  * Resolves the project list to type-check. `--project` wins over
- * config; if neither is set, throws a clear error pointing at both
+ * config. If neither is set, throws a clear error pointing at both
  * paths to a fix (add the config field or pass --project).
  */
 export declare function resolveTypecheckProjects(configTypecheck: TypecheckConfig | undefined, override: string | undefined): TypecheckConfig;

package/dist/src/commands/typecheck.js

@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge typecheck` — whole-project TypeScript type checking driven by
+ * `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
+ * 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.
@@ -26,7 +26,7 @@ import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { buildPerRunCheckJs } from './lint-per-run-checkjs.js';
 /**
  * Resolves the project list to type-check. `--project` wins over
- * config; if neither is set, throws a clear error pointing at both
+ * config. If neither is set, throws a clear error pointing at both
  * paths to a fix (add the config field or pass --project).
  */
 export function resolveTypecheckProjects(configTypecheck, override) {
@@ -57,8 +57,8 @@ export function resolveTypecheckProjects(configTypecheck, override) {
  */
 function formatIssue(projectRoot, issue) {
     const file = relativeForDisplay(projectRoot, issue.file);
-    const codeLabel = issue.code > 0 ? ` TS${String(issue.code)}` : '';
-    return `[${issue.project}] ${file}:${String(issue.line)}:${String(issue.column)}${codeLabel} ${issue.message}`;
+    const codeLabel = issue.code > 0 ? ` TS${issue.code}` : '';
+    return `[${issue.project}] ${file}:${issue.line}:${issue.column}${codeLabel} ${issue.message}`;
 }
 /**
  * Top-level entry point invoked by the registered Commander action.
@@ -75,7 +75,7 @@ export async function typecheckCommand(projectRoot, options) {
 }
 async function runTypecheckCommandBody(projectRoot, options) {
     // Validate project is initialised. `loadConfig` throws on missing
-    // fireforge.json — withErrorHandling at the CLI layer renders the
+    // fireforge.json, and withErrorHandling at the CLI layer renders the
     // resulting `ConfigNotFoundError` cleanly, so we don't need to
     // re-wrap.
     getProjectPaths(projectRoot);
@@ -87,7 +87,7 @@ async function runTypecheckCommandBody(projectRoot, options) {
     // 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(', ')}`);
+    info(`Running typecheck across ${cfg.projects.length} project(s): ${cfg.projects.join(', ')}`);
     const results = await runTypecheck(projectRoot, cfg);
     // Fold the EXPORT-TIME authority into this pass. Per-patch lint runs
     // checkJs over the queue's patch-owned modules in relative isolation and
@@ -101,8 +101,8 @@ async function runTypecheckCommandBody(projectRoot, options) {
     reportResults(projectRoot, results, patchIssues);
 }
 /**
- * Runs the per-patch-lint checkJs pass — the same program `export` and
- * `lint --per-patch` use — and returns its findings.
+ * Runs the per-patch-lint checkJs pass (the same program `export` and
+ * `lint --per-patch` use) and returns its findings.
  *
  * Returns an empty list when `patchLint.checkJs` is off or the project has
  * no patch queue: there is no second authority to reconcile then.
@@ -139,8 +139,8 @@ async function regenerateStaleGeneratedJsconfig(projectRoot) {
     if (!drift.changed)
         return;
     info(`Regenerating stale generated jsconfig ${furnaceConfig.typecheckJsconfig} before typecheck ` +
-        `(+${String(drift.added.length)} added, ~${String(drift.updated.length)} updated, ` +
-        `-${String(drift.pruned.length)} pruned).`);
+        `(+${drift.added.length} added, ~${drift.updated.length} updated, ` +
+        `-${drift.pruned.length} pruned).`);
     await syncFurnaceJsconfigPaths(projectRoot, furnaceConfig);
 }
 /**
@@ -171,10 +171,10 @@ export function reportResults(projectRoot, results, patchLintIssues = []) {
         for (const issue of errors)
             warn(formatIssue(projectRoot, issue));
     }
-    const summary = `Typecheck: ${String(totalErrors)} error(s), ${String(totalWarnings)} warning(s) across ` +
-        `${String(results.length)} project(s)` +
+    const summary = `Typecheck: ${totalErrors} error(s), ${totalWarnings} warning(s) across ` +
+        `${results.length} project(s)` +
         (patchLintIssues.length > 0
-            ? ` (including ${String(patchLintIssues.length)} per-patch checkJs finding(s))`
+            ? ` (including ${patchLintIssues.length} per-patch checkJs finding(s))`
             : '');
     if (totalErrors === 0) {
         success(summary);
@@ -183,7 +183,7 @@ export function reportResults(projectRoot, results, patchLintIssues = []) {
     }
     info(summary);
     outro('Typecheck failed');
-    throw new GeneralError(`Typecheck found ${String(totalErrors)} error(s) across ${String(results.length)} project(s).`);
+    throw new GeneralError(`Typecheck found ${totalErrors} error(s) across ${results.length} project(s).`);
 }
 /**
  * Registers the `typecheck` command on the CLI program.

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

@@ -1,10 +1,10 @@
 /**
- * `fireforge verify` — read-only fsck for the patch queue.
+ * `fireforge verify`: read-only fsck for the patch queue.
  *
  * Combines the manifest consistency check (orphan files, missing entries,
  * files-affected mismatch, duplicate entries) with the cross-patch lint
  * rules (duplicate /dev/null creation, forward imports). Does not run
- * `planExport` per patch — that is intentionally out of scope because it
+ * `planExport` per patch. That is out of scope because it
  * would couple verify to engine state and make the command too slow to be
  * useful as a pre-flight gate. Engine-level patch application issues are
  * still covered by the existing `fireforge doctor` and `fireforge import`
@@ -35,7 +35,7 @@ export interface PatchQueueHealth {
 export declare function collectPatchQueueHealth(projectRoot: string): Promise<PatchQueueHealth>;
 /**
  * Runs the `verify` command: manifest consistency + cross-patch lint.
- * Read-only; exits non-zero on any error-severity finding.
+ * Read-only. Exits non-zero on any error-severity finding.
  *
  * @param projectRoot - Project root directory
  */

package/dist/src/commands/verify.js

@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge verify` — read-only fsck for the patch queue.
+ * `fireforge verify`: read-only fsck for the patch queue.
  *
  * Combines the manifest consistency check (orphan files, missing entries,
  * files-affected mismatch, duplicate entries) with the cross-patch lint
  * rules (duplicate /dev/null creation, forward imports). Does not run
- * `planExport` per patch — that is intentionally out of scope because it
+ * `planExport` per patch. That is out of scope because it
  * would couple verify to engine state and make the command too slow to be
  * useful as a pre-flight gate. Engine-level patch application issues are
  * still covered by the existing `fireforge doctor` and `fireforge import`
@@ -34,16 +34,16 @@ import { info, intro, outro, success, warn } from '../utils/logger.js';
 /**
  * Walks each patch body in the manifest, extracts the set of
  * component-shaped registration references it adds (widget paths
- * implied by jar.mn + customElements.js; FTL paths implied by locale
+ * implied by jar.mn + customElements.js, and FTL paths implied by locale
  * jar.mn), and confirms every reference is either created by some
- * patch in the queue OR present as a tracked file in engine/. Any
- * unreachable reference is a dangling-registration error — the patch
+ * patch in the queue or present as a tracked file in engine/. Any
+ * unreachable reference is a dangling-registration error: the patch
  * registers a file that nothing in the world supplies, which fails at
  * install time.
  */
 async function detectDanglingRegistrations(patchesDir, engineDir, patches) {
     // Aggregate the set of all paths any patch in the queue is responsible for
-    // (per `filesAffected`). Individual patch bodies are deliberately NOT
+    // (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
@@ -65,7 +65,7 @@ async function detectDanglingRegistrations(patchesDir, engineDir, patches) {
         }
         catch {
             // Bad file read is surfaced by the manifest consistency check
-            // already — skipping here avoids double-reporting the same issue.
+            // already. Skipping here avoids double-reporting the same issue.
             continue;
         }
         const refs = collectPatchRegistrationReferences(body);
@@ -77,7 +77,7 @@ async function detectDanglingRegistrations(patchesDir, engineDir, patches) {
             // 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
+            // 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;
@@ -170,7 +170,7 @@ 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
+        // 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)) {
@@ -253,7 +253,7 @@ export async function collectPatchQueueHealth(projectRoot) {
 }
 /**
  * Runs the `verify` command: manifest consistency + cross-patch lint.
- * Read-only; exits non-zero on any error-severity finding.
+ * Read-only. Exits non-zero on any error-severity finding.
  *
  * @param projectRoot - Project root directory
  */

package/dist/src/commands/watch.js

@@ -17,7 +17,7 @@ const WATCHMAN_PROBE_TIMEOUT_MS = 5000;
  * in PATH but cannot respond (corrupt install, server crashed mid-session,
  * permission denied on the state directory) would otherwise surface as a
  * confusing mid-watch failure. Returns the trimmed version string when
- * the probe succeeds; throws a {@link GeneralError} with actionable
+ * the probe succeeds. Throws a {@link GeneralError} with actionable
  * remediation when it does not.
  */
 async function probeWatchman() {
@@ -64,7 +64,7 @@ function hasWatchPermissionFailure(output) {
  *
  * @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
+ *   binary, surfaced in the guidance so the operator can see whether
  *   FireForge actually found one.
  * @returns User-facing failure guidance
  */
@@ -106,10 +106,10 @@ export async function watchCommand(projectRoot) {
     // Check if engine exists
     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
+    // 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
+    // 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');
@@ -117,7 +117,7 @@ export async function watchCommand(projectRoot) {
         throw new GeneralError('Watch mode requires watchman to be installed and available in PATH.\n\n' +
             'Install watchman first, then rerun "fireforge watch".');
     }
-    // Verify watchman actually responds — a binary that is in PATH but
+    // Verify watchman actually responds: a binary that is in PATH but
     // unable to respond (broken install, crashed server, bad state dir
     // permissions) would otherwise surface as a confusing mid-build failure
     // instead of an actionable preflight error.
@@ -125,7 +125,7 @@ export async function watchCommand(projectRoot) {
     // Check for build artifacts before starting watch
     // The mismatch rung rejects copied or relocated obj-* dirs whose mozinfo
     // metadata (topsrcdir, topobjdir, mozconfig) still points at a different
-    // source tree; mach watch against stale metadata produces confusing errors.
+    // source tree. mach watch against stale metadata produces confusing errors.
     const buildCheck = await hasBuildArtifacts(paths.engine);
     assertBuildArtifacts(paths.engine, buildCheck, {
         label: 'Watch mode',
@@ -136,7 +136,7 @@ export async function watchCommand(projectRoot) {
     // Report bundle state alongside the "Using build artifacts..." banner
     // so an operator watching a mid-build tree can see why `fireforge run`
     // would refuse right now while watch is still going. Watch remains
-    // permissive (it exists to drive rebuilds) — this is informational.
+    // permissive (it exists to drive rebuilds), so this is informational.
     // The `hasBuildArtifacts` check already passed at this point, so
     // `objDir` is always defined.
     const bundleCheck = buildCheck.objDir
@@ -148,7 +148,7 @@ export async function watchCommand(projectRoot) {
     info(`Using build artifacts from ${buildCheck.objDir}/${bundleSuffix}`);
     // Advisory: warn when Furnace components have drifted since the last
     // apply so the user doesn't launch watch-mode builds with stale
-    // components baked in. Mirrors the check in `fireforge run` — without
+    // components baked in. Mirrors the check in `fireforge run`: without
     // it, users editing a component then running `watch` would see their
     // change never surface in the rebuilt browser.
     await warnIfFurnaceStale(projectRoot);
@@ -173,7 +173,7 @@ export async function watchCommand(projectRoot) {
     const watchmanDir = dirname(watchmanPath);
     const existingPath = process.env['PATH'] ?? '';
     const pathSegments = existingPath.split(delimiter).filter((segment) => segment.length > 0);
-    // Both arms filter identically; the cast this replaced laundered
+    // Both arms filter identically. The cast this replaced laundered
     // `string | undefined` on one arm while the other built the annotated shape
     // honestly.
     const baseEnv = {};
@@ -197,8 +197,8 @@ export async function watchCommand(projectRoot) {
     }
     // On Ctrl+C the bin signal handler now waits for the mach child to shut
     // down (waitForActiveChildShutdown) before exiting, so this continuation
-    // can run and whitelist the SIGINT exit code — though the bin may still
-    // win the race and terminate first; both outcomes are acceptable.
+    // can run and whitelist the SIGINT exit code, though the bin may still
+    // win the race and terminate first. Both outcomes are acceptable.
     if (result.exitCode !== 0 && result.exitCode !== 130) {
         const combinedOutput = `${result.stdout}\n${result.stderr}`;
         if (hasConfigureTimeWatchmanFailure(combinedOutput)) {

package/dist/src/commands/wire.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join, relative } from 'node:path';
 import { Command } from 'commander';
-import { DEFAULT_BROWSER_SUBSCRIPT_DIR, wireSubscript } from '../core/browser-wire.js';
+import { DEFAULT_BROWSER_SUBSCRIPT_DIR, wireSubscript, } from '../core/browser-wire.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { furnaceConfigExists as checkFurnaceConfigExists, loadFurnaceConfig, } from '../core/furnace-config.js';
 import { consumeParserFallbackEvents } from '../core/parser-fallback.js';
@@ -13,14 +13,15 @@ import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { isContainedRelativePath, isExplicitAbsolutePath, isPathInsideRoot, stripEnginePrefix, toRootRelativePath, } from '../utils/paths.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 const BROWSER_BASE_DIR = 'browser/base';
 function printWireDryRun(engineDir, name, subscriptDir, domFilePath, domTargetPath, options) {
     info('[dry-run] Would wire subscript:');
     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 —
-        // echoing the raw input ("X.init") does not reflect that the real run
+        // 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)}`);
     }
@@ -28,10 +29,10 @@ function printWireDryRun(engineDir, name, subscriptDir, domFilePath, domTargetPa
         info(`  browser-init.js onUnload(): ${coerceToCall(options.destroy)}`);
     }
     if (domFilePath) {
-        const includePath = relative(join(engineDir, subscriptDir), join(engineDir, domFilePath)).replace(/\\/g, '/');
+        const includePath = normalizePathSlashes(relative(join(engineDir, subscriptDir), join(engineDir, domFilePath)));
         info(`  ${domTargetPath}: #include ${includePath}`);
     }
-    const relPath = relative(join(engineDir, BROWSER_BASE_DIR), join(engineDir, subscriptDir)).replace(/\\/g, '/');
+    const relPath = normalizePathSlashes(relative(join(engineDir, BROWSER_BASE_DIR), join(engineDir, subscriptDir)));
     info(`  jar.mn: content/browser/${name}.js (${relPath}/${name}.js)`);
     outro('Dry run complete');
 }
@@ -41,11 +42,11 @@ function printWireDryRun(engineDir, name, subscriptDir, domFilePath, domTargetPa
  * Preference order:
  *   1. `--target <path>` CLI flag (explicit caller intent)
  *   2. First entry of `furnace.json.tokenHostDocuments` (fork-configured
- *      chrome doc list; already consumed by the missing-token-link
+ *      chrome doc list, already consumed by the missing-token-link
  *      validator and the doctor check)
  *   3. `browser/base/content/browser.xhtml` (upstream default)
  *
- * Step 2 is silent — a missing / invalid furnace.json falls through to the
+ * Step 2 is silent: a missing or invalid furnace.json falls through to the
  * upstream default rather than surfacing a warning, because forks that don't
  * use furnace shouldn't have to configure anything.
  */
@@ -62,7 +63,7 @@ async function resolveDomTargetPath(projectRoot, explicit) {
             }
         }
         catch {
-            // Fall through to default — a broken furnace.json should not block
+            // Fall through to the default. A broken furnace.json should not block
             // the wire command. The doctor surfaces that issue separately.
         }
     }
@@ -84,7 +85,7 @@ function validateWireName(name) {
     }
 }
 /**
- * Asserts that the resolved chrome document both exists on disk AND exposes
+ * 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
@@ -145,7 +146,7 @@ async function ensureSubscriptSourceExists(projectRoot, subscriptDir, name, dryR
 /**
  * Validates the `--dom` fragment argument and computes its engine-root-
  * relative path. Accepts absolute, repo-root-relative (`engine/...`), and
- * engine-relative inputs; rejects missing files and paths escaping
+ * engine-relative inputs. Rejects missing files and paths escaping
  * engine/. Returns undefined when `--dom` was not supplied.
  */
 async function resolveDomFragmentPath(projectRoot, dom) {
@@ -277,10 +278,10 @@ 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
+    // 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
+    // `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');
@@ -292,8 +293,8 @@ export async function wireCommand(projectRoot, name, options = {}) {
     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 — resolved here anyway so the dry-run
-    // plan can print the target accurately.
+    // consulted when `--dom` is supplied, but resolved here anyway so the
+    // dry-run plan can print the target accurately.
     //
     // `stripEnginePrefix` is applied so
     // `--target engine/browser/base/browser.xhtml` and
@@ -316,7 +317,7 @@ export async function wireCommand(projectRoot, name, options = {}) {
     // setup scripts rely on.
     //
     // The check stays advisory rather than fatal in dry-run because
-    // "wire first, create file after" is a legitimate use of preview — but a
+    // "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.

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

@@ -4,7 +4,7 @@ import { walk } from 'estree-walker';
 /**
  * An ESTree node augmented with acorn's character-offset positions.
  * At runtime `acorn.parse` produces objects that carry both the ESTree
- * shape *and* `start`/`end` indices, but the type system doesn't know that.
+ * shape and `start`/`end` indices, but the type system doesn't know that.
  * This intersection type bridges the gap so we can safely use both APIs.
  */
 export type AcornESTreeNode<T extends estree.Node = estree.Node> = T & {
@@ -12,7 +12,7 @@ export type AcornESTreeNode<T extends estree.Node = estree.Node> = T & {
     end: number;
 };
 /**
- * Parse JavaScript source as a **script** (not an ES module).
+ * Parse JavaScript source as a script, not an ES module.
  * All Mozilla chrome JS files (`browser-main.js`, `browser-init.js`,
  * `customElements.js`, etc.) are scripts that run in a privileged scope.
  *
@@ -22,7 +22,7 @@ export type AcornESTreeNode<T extends estree.Node = estree.Node> = T & {
  */
 export declare function parseScript(content: string, onComment?: acorn.Comment[]): AcornESTreeNode<estree.Program>;
 /**
- * Parse JavaScript source as an **ES module**.
+ * Parse JavaScript source as an ES module.
  * Used for `.sys.mjs` files which use static import/export syntax.
  *
  * @param content - Source text to parse
@@ -34,12 +34,12 @@ export declare function parseModule(content: string, onComment?: acorn.Comment[]
  * Convenience cast from `acorn.Node` (or the generic ESTree union returned
  * by estree-walker callbacks) to a positioned, narrowly-typed node.
  *
- * **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 an
+ * 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 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.
+ * is wrong.
  *
  * 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

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

@@ -6,15 +6,15 @@ import { walk } from 'estree-walker';
  * `acorn.parse` produces nodes that carry both the ESTree shape and
  * `start`/`end` offsets at runtime, but its static `acorn.Program` type is
  * nominally distinct from `estree.Program`, so the compiler cannot verify
- * the conversion structurally — hence the double assertion. This helper is
- * the single sanctioned crossing point between the two type worlds.
+ * the conversion structurally, hence the double assertion. This helper is the
+ * only sanctioned crossing point between the two types.
  */
 function toPositionedProgram(program) {
     // eslint-disable-next-line no-restricted-syntax -- the sanctioned acorn→estree bridge this rule's message points at
     return program;
 }
 /**
- * Parse JavaScript source as a **script** (not an ES module).
+ * Parse JavaScript source as a script, not an ES module.
  * All Mozilla chrome JS files (`browser-main.js`, `browser-init.js`,
  * `customElements.js`, etc.) are scripts that run in a privileged scope.
  *
@@ -32,7 +32,7 @@ export function parseScript(content, onComment) {
     return toPositionedProgram(acorn.parse(content, opts));
 }
 /**
- * Parse JavaScript source as an **ES module**.
+ * Parse JavaScript source as an ES module.
  * Used for `.sys.mjs` files which use static import/export syntax.
  *
  * @param content - Source text to parse
@@ -53,12 +53,12 @@ export function parseModule(content, onComment) {
  * Convenience cast from `acorn.Node` (or the generic ESTree union returned
  * by estree-walker callbacks) to a positioned, narrowly-typed node.
  *
- * **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 an
+ * 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 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.
+ * is wrong.
  *
  * 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