@hominis/fireforge 0.19.2 → 0.19.4

package/CHANGELOG.md

@@ -10,6 +10,11 @@
 ### Hardening
 
 - **`modified-file-missing-header` — standard Mozilla MPL-2.0 block headers with wrapped line breaks.** The upstream fallback scan required a contiguous `Mozilla Public License` substring in the first few lines, so files that follow Mozilla’s usual `/* … Mozilla Public` / ` * License, v. 2.0 … */` wrap (including after Emacs/vim directive blocks) were warned despite a valid notice. `containsUpstreamLicenseText` in `src/core/license-headers.ts` now normalizes common block-comment continuation prefixes before matching, so forks need not add SPDX solely to satisfy patch lint.
+- **`fireforge test` — `--marionette-port` auto-forward matches toolkit mochitests and mixed suites.** Auto-forward of `--setpref=marionette.port=<n>` previously keyed off a path heuristic that missed `toolkit/content/tests/**` widget HTML tests (no `/mochitest/` segment), so the preflight could use the operator’s port while mach still defaulted to **2828**. Forwarding now runs whenever `--marionette-port` is set unless `--mach-arg` explicitly includes `--flavor=xpcshell` / `xpcshell-tests` (the pref is unused there). `isMarionetteFlavor` also treats `toolkit/content/tests/` paths as Marionette-relevant unless they sit under `/tests/xpcshell/`, for consistency with other callers of that helper.
+
+### Documentation
+
+- **README — mochitest timeouts vs Marionette.** The Test harness section documents long idle timeouts (~370s, `TEST_END: TIMEOUT`) on fork custom chrome, `--marionette-port` behaviour with xpcshell flavor, and pointers to fork-side prefs and investigation (for example Hominis `AGENT_RULES.md`).
 
 ## 0.18.0
 

package/README.md

@@ -638,6 +638,12 @@ xpcshell has a chrome-URI boundary that is worth knowing before writing assertio
 
 The two flags can be combined — `--with-tests --xpcshell` writes both harnesses.
 
+### Mochitest stalls and `--marionette-port`
+
+When you pass `--marionette-port <n>`, FireForge uses that port for the stale-listener probe and for `--doctor`, and it forwards `--setpref=marionette.port=<n>` to `mach test` so the harness binds the same port. The only exception is an explicit `--mach-arg --flavor=xpcshell` (or `--flavor=xpcshell-tests`): that harness ignores the pref, so FireForge skips auto-forward and logs a short notice instead. Toolkit widget mochitests under `toolkit/content/tests/` (for example `test_*.html` next to `browser_*.js` suites) therefore stay aligned with the probe without duplicating `--mach-arg=--setpref=marionette.port=…`.
+
+Some forks see mochitests end with **`TEST_END: TIMEOUT`** after on the order of **370 seconds** with **no harness output** — including runs where mozinfo reports `headless: false`, so the failure is not explained by SWGL headless alone. When tests wait on custom chrome (for example a fork tile shell that never sets a `_readyForTesting` gate), the hang is **engine-side**; use your fork’s test docs and `browser.toml` defaults (for Hominis-style trees, see the fork’s `AGENT_RULES.md` for `hominis.testing.*` prefs). Operationally: ensure Marionette port **2828** is free, pass **`--marionette-port`** when you use a non-default port (FireForge keeps preflight and mach consistent as above), and narrow the failure with `--doctor` or by splitting a lighter smoke test that does not depend on full chrome init.
+
 ### Stale-build preflight on `fireforge test`
 
 `fireforge test <path>` (without `--build`) now runs a preflight that diffs engine HEAD and the workdir against the last successful `fireforge build` (recorded at `.fireforge/last-build.json`). When packageable engine files have changed since that baseline, the command prints a single up-front warning naming the paths and pointing at `fireforge test --build`. This catches the class of failure where a newly scaffolded chrome resource or pref file is registered correctly but `obj-*/dist/` still holds the pre-edit bundle, so the test reads stale packaged artifacts and errors out with a cryptic `NS_ERROR_FILE_NOT_FOUND` inside xpcshell / mach test. The preflight is warn-only — a fork that rebuilt out-of-band (direct `./mach build`, IDE plugin, separate CI stage) is not blocked. Passing `--build` skips the preflight because the rebuild just refreshed the bundle.

package/dist/src/commands/bootstrap-checks.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { execFile } from 'node:child_process';
-import { failure, warning } from './doctor.js';
+import { failure, warning } from './doctor-check-core.js';
 /**
  * Scans bootstrap output for known failure patterns and returns structured
  * issue tags. A Python traceback paired with an HTTP 403 is collapsed into

package/dist/src/commands/doctor-check-core.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Doctor check types and lightweight result builders shared between
+ * `doctor.ts` and sibling check modules. Kept separate so registries can import
+ * these symbols without creating cycles through `doctor.ts`.
+ */
+import type { DoctorCheck, DoctorOptions } from '../types/commands/index.js';
+import type { FireForgeConfig, FireForgeState, ProjectPaths } from '../types/config.js';
+import type { FurnaceConfig } from '../types/furnace.js';
+/**
+ * Shared state available to every doctor check during a single run.
+ *
+ * The context is populated lazily by the doctor runner. Individual checks
+ * can record side-observations (e.g. the parsed `fireforge.json`) into the
+ * context for later checks to consume without re-parsing.
+ */
+export interface DoctorCheckContext {
+    projectRoot: string;
+    paths: ProjectPaths;
+    state: FireForgeState;
+    options: DoctorOptions;
+    /**
+     * Whether the engine/ directory exists on disk. Populated before checks
+     * run so downstream checks can skip git/mach inspections cheaply.
+     */
+    engineExists: boolean;
+    /**
+     * The loaded project config, set by the "fireforge.json is valid" check
+     * when it succeeds. Undefined before that check runs and whenever loading
+     * failed.
+     */
+    config: FireForgeConfig | undefined;
+    /**
+     * Whether `furnace.json` exists on disk. Populated before checks run so
+     * the furnace group can skipIf cheaply when the subsystem is not in use.
+     */
+    furnaceConfigExists: boolean;
+    /**
+     * The parsed furnace config, set by the "Furnace configuration" check
+     * when it succeeds. Later furnace checks read from this so they do not
+     * re-parse the file; undefined when the config could not be loaded.
+     */
+    furnaceConfig: FurnaceConfig | undefined;
+}
+/**
+ * Result a check may return. A single object is the common case; an array
+ * lets a single check emit multiple related rows (e.g. the engine branch
+ * check which may report on branch + detached state together).
+ */
+export type CheckResult = DoctorCheck | DoctorCheck[];
+/**
+ * Declarative definition of a single doctor check.
+ *
+ * Every check opts into the shared execution/reporting pipeline by
+ * implementing only its inspection logic in `run`. Cross-cutting concerns
+ * (result aggregation, summary, exit codes) live in the runner instead of
+ * being duplicated at each call site.
+ */
+export interface DoctorCheckDefinition {
+    /**
+     * Human-readable name surfaced in the check report (e.g. "Git installed").
+     * Not required to be unique, but tests assert on it.
+     */
+    name: string;
+    /**
+     * When `true`, the check is silently skipped. Used for checks that only
+     * apply when the engine is present, or only when specific state flags
+     * are set. Skipped checks contribute nothing to the final report.
+     */
+    skipIf?: (ctx: DoctorCheckContext) => boolean;
+    /**
+     * Names of checks that must appear earlier in the registry and run before
+     * this check. Enforced at startup via validateCheckDependencies so
+     * accidental reorders surface immediately instead of producing subtle
+     * context-population bugs at runtime.
+     */
+    dependsOn?: readonly string[];
+    /**
+     * Runs the inspection. Throwing is shorthand for "this check failed with
+     * severity 'error'" — the runner converts the exception message into a
+     * DoctorCheck. Returning a DoctorCheck (or array) lets the check control
+     * severity, warnings, and fix hints directly.
+     */
+    run: (ctx: DoctorCheckContext) => CheckResult | Promise<CheckResult>;
+    /**
+     * Optional recovery hint attached to the auto-generated failure result
+     * when `run` throws. Ignored when `run` returns a DoctorCheck explicitly.
+     */
+    fix?: string;
+}
+/**
+ * Builds a DoctorCheck object representing a successful "OK" check.
+ */
+export declare function ok(name: string): DoctorCheck;
+/**
+ * Builds a DoctorCheck object representing a warning result.
+ */
+export declare function warning(name: string, message: string, fix?: string): DoctorCheck;
+/**
+ * Builds a DoctorCheck object representing a failure result.
+ */
+export declare function failure(name: string, message: string, fix?: string): DoctorCheck;

package/dist/src/commands/doctor-check-core.js

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Doctor check types and lightweight result builders shared between
+ * `doctor.ts` and sibling check modules. Kept separate so registries can import
+ * these symbols without creating cycles through `doctor.ts`.
+ */
+/**
+ * Builds a DoctorCheck object representing a successful "OK" check.
+ */
+export function ok(name) {
+    return { name, passed: true, severity: 'ok', message: 'OK' };
+}
+/**
+ * Builds a DoctorCheck object representing a warning result.
+ */
+export function warning(name, message, fix) {
+    return {
+        name,
+        passed: true,
+        severity: 'warning',
+        warning: true,
+        message,
+        ...(fix ? { fix } : {}),
+    };
+}
+/**
+ * Builds a DoctorCheck object representing a failure result.
+ */
+export function failure(name, message, fix) {
+    return { name, passed: false, severity: 'error', message, ...(fix ? { fix } : {}) };
+}
+//# sourceMappingURL=doctor-check-core.js.map

package/dist/src/commands/doctor-furnace-manifest-sync.d.ts

@@ -14,5 +14,5 @@
  * Lives in a sibling module to keep `doctor-furnace.ts` under the
  * per-file LOC budget.
  */
-import type { DoctorCheckDefinition } from './doctor.js';
+import type { DoctorCheckDefinition } from './doctor-check-core.js';
 export declare const furnaceManifestSyncCheck: DoctorCheckDefinition;

package/dist/src/commands/doctor-furnace-manifest-sync.js

@@ -20,7 +20,7 @@ import { join } from 'node:path';
 import { getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig } from '../core/furnace-config.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readJson } from '../utils/fs.js';
-import { failure, ok, warning } from './doctor.js';
+import { failure, ok, warning } from './doctor-check-core.js';
 async function listComponentDirs(dir) {
     if (!(await pathExists(dir)))
         return [];

package/dist/src/commands/doctor-furnace.d.ts

@@ -1,4 +1,4 @@
-import type { DoctorCheckDefinition } from './doctor.js';
+import type { DoctorCheckDefinition } from './doctor-check-core.js';
 /**
  * The ordered furnace check group. Exported as an array so `doctor.ts`
  * can splice it into the main registry at the right position. The order

package/dist/src/commands/doctor-furnace.js

@@ -9,7 +9,7 @@ import { getFurnaceLockPath, runFurnaceMutation } from '../core/furnace-operatio
 import { validateAllComponents } from '../core/furnace-validate.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
-import { failure, ok, warning } from './doctor.js';
+import { failure, ok, warning } from './doctor-check-core.js';
 import { furnaceManifestSyncCheck } from './doctor-furnace-manifest-sync.js';
 const ENGINE_REPAIRABLE_OPERATIONS = [
     'preview-teardown',

package/dist/src/commands/doctor-working-tree.d.ts

@@ -10,7 +10,7 @@
  * budget; see the call site in `runEngineGitChecks`.
  */
 import type { DoctorCheck } from '../types/commands/index.js';
-import type { DoctorCheckContext } from './doctor.js';
+import type { DoctorCheckContext } from './doctor-check-core.js';
 /**
  * Inspects the engine working tree and returns a single
  * `DoctorCheck`. Ownership-aware: patch-backed / branding / furnace

package/dist/src/commands/doctor-working-tree.js

@@ -13,7 +13,7 @@
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
 import { classifyFiles } from '../core/status-classify.js';
-import { ok, warning } from './doctor.js';
+import { ok, warning } from './doctor-check-core.js';
 function summarizeWorkingTreeChangeCount(changeCount) {
     return `Engine working tree has ${changeCount} local change${changeCount === 1 ? '' : 's'}. Some FireForge commands assume a clean baseline and may behave differently until these are exported, discarded, or committed.`;
 }

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

@@ -2,113 +2,7 @@ import { Command } from 'commander';
 import { ExitCode } from '../errors/codes.js';
 import type { CommandContext } from '../types/cli.js';
 import type { DoctorCheck, DoctorOptions } from '../types/commands/index.js';
-import type { FireForgeConfig, FireForgeState, ProjectPaths } from '../types/config.js';
-import type { FurnaceConfig } from '../types/furnace.js';
-/**
- * Shared state available to every doctor check during a single run.
- *
- * The context is populated lazily by the doctor runner. Individual checks
- * can record side-observations (e.g. the parsed `fireforge.json`) into the
- * context for later checks to consume without re-parsing.
- *
- * Exported so sibling modules (e.g. `doctor-furnace.ts`) can declare
- * `DoctorCheckDefinition` entries against the same shared context.
- */
-export interface DoctorCheckContext {
-    projectRoot: string;
-    paths: ProjectPaths;
-    state: FireForgeState;
-    options: DoctorOptions;
-    /**
-     * Whether the engine/ directory exists on disk. Populated before checks
-     * run so downstream checks can skip git/mach inspections cheaply.
-     */
-    engineExists: boolean;
-    /**
-     * The loaded project config, set by the "fireforge.json is valid" check
-     * when it succeeds. Undefined before that check runs and whenever loading
-     * failed.
-     */
-    config: FireForgeConfig | undefined;
-    /**
-     * Whether `furnace.json` exists on disk. Populated before checks run so
-     * the furnace group can skipIf cheaply when the subsystem is not in use.
-     * A missing furnace.json is not an error — plenty of projects never touch
-     * the subsystem — so the doctor stays silent rather than failing.
-     */
-    furnaceConfigExists: boolean;
-    /**
-     * The parsed furnace config, set by the "Furnace configuration" check
-     * when it succeeds. Later furnace checks read from this so they do not
-     * re-parse the file; undefined when the config could not be loaded.
-     */
-    furnaceConfig: FurnaceConfig | undefined;
-}
-/**
- * Result a check may return. A single object is the common case; an array
- * lets a single check emit multiple related rows (e.g. the engine branch
- * check which may report on branch + detached state together).
- */
-export type CheckResult = DoctorCheck | DoctorCheck[];
-/**
- * Declarative definition of a single doctor check.
- *
- * Every check opts into the shared execution/reporting pipeline by
- * implementing only its inspection logic in `run`. Cross-cutting concerns
- * (result aggregation, summary, exit codes) live in the runner instead of
- * being duplicated at each call site.
- *
- * Exported so sibling modules (e.g. `doctor-furnace.ts`) can declare
- * new checks without re-deriving the shape.
- */
-export interface DoctorCheckDefinition {
-    /**
-     * Human-readable name surfaced in the check report (e.g. "Git installed").
-     * Not required to be unique, but tests assert on it.
-     */
-    name: string;
-    /**
-     * When `true`, the check is silently skipped. Used for checks that only
-     * apply when the engine is present, or only when specific state flags
-     * are set. Skipped checks contribute nothing to the final report.
-     */
-    skipIf?: (ctx: DoctorCheckContext) => boolean;
-    /**
-     * Names of checks that must appear earlier in the registry and run before
-     * this check. Enforced at startup via {@link validateCheckDependencies} so
-     * accidental reorders surface immediately instead of producing subtle
-     * context-population bugs at runtime.
-     */
-    dependsOn?: readonly string[];
-    /**
-     * Runs the inspection. Throwing is shorthand for "this check failed with
-     * severity 'error'" — the runner converts the exception message into a
-     * DoctorCheck. Returning a DoctorCheck (or array) lets the check control
-     * severity, warnings, and fix hints directly.
-     */
-    run: (ctx: DoctorCheckContext) => CheckResult | Promise<CheckResult>;
-    /**
-     * Optional recovery hint attached to the auto-generated failure result
-     * when `run` throws. Ignored when `run` returns a DoctorCheck explicitly.
-     */
-    fix?: string;
-}
-/**
- * Builds a DoctorCheck object representing a successful "OK" check.
- * Exported for sibling check modules that declare `DoctorCheckDefinition`
- * entries out-of-file (e.g. `doctor-furnace.ts`).
- */
-export declare function ok(name: string): DoctorCheck;
-/**
- * Builds a DoctorCheck object representing a warning result.
- * Exported for sibling check modules — see {@link ok}.
- */
-export declare function warning(name: string, message: string, fix?: string): DoctorCheck;
-/**
- * Builds a DoctorCheck object representing a failure result.
- * Exported for sibling check modules — see {@link ok}.
- */
-export declare function failure(name: string, message: string, fix?: string): DoctorCheck;
+import type { DoctorCheckDefinition } from './doctor-check-core.js';
 /**
  * Validates that every check's `dependsOn` entries appear earlier in the
  * registry. Called once at module load time so a broken reorder surfaces

package/dist/src/commands/doctor.js

@@ -10,37 +10,9 @@ import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { error, info, intro, outro, success, warn } from '../utils/logger.js';
 import { findExecutable } from '../utils/process.js';
+import { failure, ok, warning } from './doctor-check-core.js';
 import { FURNACE_DOCTOR_CHECKS } from './doctor-furnace.js';
 import { inspectEngineWorkingTree } from './doctor-working-tree.js';
-/**
- * Builds a DoctorCheck object representing a successful "OK" check.
- * Exported for sibling check modules that declare `DoctorCheckDefinition`
- * entries out-of-file (e.g. `doctor-furnace.ts`).
- */
-export function ok(name) {
-    return { name, passed: true, severity: 'ok', message: 'OK' };
-}
-/**
- * Builds a DoctorCheck object representing a warning result.
- * Exported for sibling check modules — see {@link ok}.
- */
-export function warning(name, message, fix) {
-    return {
-        name,
-        passed: true,
-        severity: 'warning',
-        warning: true,
-        message,
-        ...(fix ? { fix } : {}),
-    };
-}
-/**
- * Builds a DoctorCheck object representing a failure result.
- * Exported for sibling check modules — see {@link ok}.
- */
-export function failure(name, message, fix) {
-    return { name, passed: false, severity: 'error', message, ...(fix ? { fix } : {}) };
-}
 /**
  * Runs a single check definition, converting thrown errors into
  * DoctorCheck failure rows. Always returns an array so the caller can

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

@@ -1,21 +1,4 @@
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';
-import { furnaceApplyCommand } from './apply.js';
-import { furnaceChromeDocCreateCommand } from './chrome-doc.js';
-import { furnaceCreateCommand } from './create.js';
-import { furnaceDeployCommand } from './deploy.js';
-import { furnaceDiffCommand } from './diff.js';
-import { furnaceInitCommand } from './init.js';
-import { furnaceListCommand } from './list.js';
-import { furnaceBatchOverrideCommand, furnaceOverrideCommand } from './override.js';
-import { furnacePreviewCommand } from './preview.js';
-import { furnaceRefreshCommand } from './refresh.js';
-import { furnaceRemoveCommand } from './remove.js';
-import { furnaceRenameCommand } from './rename.js';
-import { furnaceScanCommand } from './scan.js';
-import { furnaceStatusCommand } from './status.js';
-import { furnaceSyncCommand } from './sync.js';
-import { furnaceValidateCommand } from './validate.js';
-export { furnaceApplyCommand, furnaceBatchOverrideCommand, furnaceChromeDocCreateCommand, furnaceCreateCommand, furnaceDeployCommand, furnaceDiffCommand, furnaceInitCommand, furnaceListCommand, furnaceOverrideCommand, furnacePreviewCommand, furnaceRefreshCommand, furnaceRemoveCommand, furnaceRenameCommand, furnaceScanCommand, furnaceStatusCommand, furnaceSyncCommand, furnaceValidateCommand, };
 /** Registers the furnace command on the CLI program. */
 export declare function registerFurnace(program: Command, context: CommandContext): void;

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

@@ -17,7 +17,6 @@ import { furnaceScanCommand } from './scan.js';
 import { furnaceStatusCommand } from './status.js';
 import { furnaceSyncCommand } from './sync.js';
 import { furnaceValidateCommand } from './validate.js';
-export { furnaceApplyCommand, furnaceBatchOverrideCommand, furnaceChromeDocCreateCommand, furnaceCreateCommand, furnaceDeployCommand, furnaceDiffCommand, furnaceInitCommand, furnaceListCommand, furnaceOverrideCommand, furnacePreviewCommand, furnaceRefreshCommand, furnaceRemoveCommand, furnaceRenameCommand, furnaceScanCommand, furnaceStatusCommand, furnaceSyncCommand, furnaceValidateCommand, };
 /**
  * Registers Furnace commands for querying component state: status, scan,
  * and action commands like apply, deploy, and create.

package/dist/src/commands/furnace/validate.d.ts

@@ -1,9 +1,8 @@
+import type { FurnaceValidateOptions } from '../../types/commands/index.js';
 /**
  * Runs the furnace validate command to perform static analysis on components.
  * @param projectRoot - Root directory of the project
  * @param name - Optional component name to validate (validates all if omitted)
  * @param options - Optional command options (e.g. --fix)
  */
-export declare function furnaceValidateCommand(projectRoot: string, name?: string, options?: {
-    fix?: boolean;
-}): Promise<void>;
+export declare function furnaceValidateCommand(projectRoot: string, name?: string, options?: FurnaceValidateOptions): Promise<void>;

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

@@ -7,12 +7,6 @@
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';
-export { patchCompactCommand } from './compact.js';
-export { patchDeleteCommand } from './delete.js';
-export { patchLintIgnoreCommand } from './lint-ignore.js';
-export { patchRenameCommand } from './rename.js';
-export { patchReorderCommand } from './reorder.js';
-export { patchTierCommand } from './tier.js';
 /**
  * Registers the `patch` subcommand parent and its verbs on the CLI.
  *

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

@@ -12,12 +12,6 @@ import { registerPatchLintIgnore } from './lint-ignore.js';
 import { registerPatchRename } from './rename.js';
 import { registerPatchReorder } from './reorder.js';
 import { registerPatchTier } from './tier.js';
-export { patchCompactCommand } from './compact.js';
-export { patchDeleteCommand } from './delete.js';
-export { patchLintIgnoreCommand } from './lint-ignore.js';
-export { patchRenameCommand } from './rename.js';
-export { patchReorderCommand } from './reorder.js';
-export { patchTierCommand } from './tier.js';
 /**
  * Registers the `patch` subcommand parent and its verbs on the CLI.
  *

package/dist/src/commands/test.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, testWithOutput, } from '../core/mach.js';
-import { assertMarionettePortAvailable, extractForwardedMarionettePort, isMarionetteFlavor, } from '../core/marionette-port.js';
+import { assertMarionettePortAvailable, extractForwardedMarionettePort, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
 import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
 import { operatorAlreadySetAppPath, resolveXpcshellAppdirArg, } from '../core/xpcshell-appdir.js';
@@ -326,21 +326,22 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     //
     // Skip forwarding when the operator already supplied an equivalent arg
     // via `--mach-arg` — duplicates would be confusing without changing
-    // semantics. Skip with a notice for clearly-non-marionette flavours
-    // (xpcshell, or paths that don't look browser-chrome/mochitest) so the
-    // operator knows the preflight took the override but mach was not
-    // auto-configured. Same escape valve applies: any mach arg can still
-    // be supplied via `--mach-arg`.
+    // semantics. Skip when mach args explicitly request `--flavor=xpcshell`
+    // (or `xpcshell-tests`): the preflight still honours `--marionette-port`,
+    // but mach does not use the marionette.port pref on that harness. Any
+    // other arg shape still forwards so toolkit widget paths and mixed suites
+    // stay aligned with the probe without duplicate `--mach-arg` flags.
     if (options.marionettePort !== undefined) {
         const operatorAlreadyForwarded = forwardedPort !== undefined;
+        const machArgs = options.machArg ?? [];
         if (operatorAlreadyForwarded) {
             info(`--marionette-port=${options.marionettePort} set, but the same port is already forwarded via --mach-arg; skipping auto-forward.`);
         }
-        else if (isMarionetteFlavor(normalizedPaths, options.machArg ?? [])) {
+        else if (shouldAutoForwardMarionettePortToMach(machArgs)) {
             extraArgs.push(`--setpref=marionette.port=${options.marionettePort}`);
         }
         else {
-            info(`--marionette-port=${options.marionettePort} applied to the preflight probe, but the test paths do not look browser-chrome/mochitest — mach is not auto-configured. Pass --mach-arg --setpref=marionette.port=${options.marionettePort} explicitly if mach should also use this port.`);
+            info(`--marionette-port=${options.marionettePort} applied to the preflight probe, but --flavor=xpcshell is set — mach is not auto-configured with --setpref=marionette.port (xpcshell ignores that pref). Pass --mach-arg --setpref=marionette.port=${options.marionettePort} explicitly if you still need mach to see the port.`);
         }
     }
     // xpcshell appdir auto-injection — see src/core/xpcshell-appdir.ts for the
@@ -408,7 +409,7 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         acc.push(value);
         return acc;
     }, [])
-        .option('--marionette-port <port>', 'Override the Marionette control port (default 2828) for the stale-browser probe, the --doctor preflight, and the auto-forwarded --setpref=marionette.port=<n> arg passed to mach. Use this when a stale process holds 2828 or a CI runner reserves a different port.', (raw) => {
+        .option('--marionette-port <port>', 'Override the Marionette control port (default 2828) for the stale-browser probe, the --doctor preflight, and (unless --mach-arg includes --flavor=xpcshell) the auto-forwarded --setpref=marionette.port=<n> passed to mach. Use this when a stale process holds 2828 or a CI runner reserves a different port.', (raw) => {
         const n = Number.parseInt(raw, 10);
         if (!Number.isFinite(n) || n < 1 || n > 65535) {
             throw new GeneralError(`--marionette-port must be an integer in 1..65535 (got "${raw}")`);

package/dist/src/commands/wire.js

@@ -111,6 +111,38 @@ async function assertDomTargetIsWireable(projectRoot, domFilePath, domTargetPath
             '`--target <path>`.', 'target');
     }
 }
+async function resolveWireSubscriptDir(projectRoot, options) {
+    let subscriptDir = DEFAULT_BROWSER_SUBSCRIPT_DIR;
+    try {
+        const config = await loadConfig(projectRoot);
+        if (config.wire?.subscriptDir) {
+            subscriptDir = config.wire.subscriptDir;
+        }
+    }
+    catch (error) {
+        warn(`Using default wire.subscriptDir because fireforge.json could not be loaded: ${toError(error).message}`);
+    }
+    if (options.subscriptDir) {
+        if (!isContainedRelativePath(options.subscriptDir)) {
+            throw new InvalidArgumentError(`Subscript directory must stay within engine/: ${options.subscriptDir}`, 'subscriptDir');
+        }
+        subscriptDir = options.subscriptDir;
+    }
+    return subscriptDir;
+}
+async function ensureSubscriptSourceExists(projectRoot, subscriptDir, name, dryRun) {
+    const paths = getProjectPaths(projectRoot);
+    const subscriptPath = join(paths.engine, subscriptDir, `${name}.js`);
+    if (!(await pathExists(subscriptPath))) {
+        if (dryRun) {
+            info(`Note: ${subscriptDir}/${name}.js does not exist yet — the real wire command will require it before writing. Create the file before re-running without --dry-run.`);
+        }
+        else {
+            throw new InvalidArgumentError(`Subscript file not found: ${subscriptDir}/${name}.js\n` +
+                'Create the file in engine/ before wiring.', 'name');
+        }
+    }
+}
 /**
  * Wires a chrome subscript into the browser.
  *
@@ -144,23 +176,7 @@ export async function wireCommand(projectRoot, name, options = {}) {
         validateWireExpression(options.destroy, 'destroy expression');
     }
     consumeParserFallbackEvents();
-    // Resolve subscript directory: CLI flag > fireforge.json > default
-    let subscriptDir = DEFAULT_BROWSER_SUBSCRIPT_DIR;
-    try {
-        const config = await loadConfig(projectRoot);
-        if (config.wire?.subscriptDir) {
-            subscriptDir = config.wire.subscriptDir;
-        }
-    }
-    catch (error) {
-        warn(`Using default wire.subscriptDir because fireforge.json could not be loaded: ${toError(error).message}`);
-    }
-    if (options.subscriptDir) {
-        if (!isContainedRelativePath(options.subscriptDir)) {
-            throw new InvalidArgumentError(`Subscript directory must stay within engine/: ${options.subscriptDir}`, 'subscriptDir');
-        }
-        subscriptDir = options.subscriptDir;
-    }
+    const subscriptDir = await resolveWireSubscriptDir(projectRoot, options);
     // Validate DOM fragment file exists and compute path relative to engine root.
     //
     // Accepts three shapes:
@@ -235,21 +251,7 @@ export async function wireCommand(projectRoot, name, options = {}) {
     // 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.
-    if (!options.dryRun) {
-        const paths = getProjectPaths(projectRoot);
-        const subscriptPath = join(paths.engine, subscriptDir, `${name}.js`);
-        if (!(await pathExists(subscriptPath))) {
-            throw new InvalidArgumentError(`Subscript file not found: ${subscriptDir}/${name}.js\n` +
-                'Create the file in engine/ before wiring.', 'name');
-        }
-    }
-    else {
-        const paths = getProjectPaths(projectRoot);
-        const subscriptPath = join(paths.engine, subscriptDir, `${name}.js`);
-        if (!(await pathExists(subscriptPath))) {
-            info(`Note: ${subscriptDir}/${name}.js does not exist yet — the real wire command will require it before writing. Create the file before re-running without --dry-run.`);
-        }
-    }
+    await ensureSubscriptSourceExists(projectRoot, subscriptDir, name, options.dryRun ?? false);
     if (options.dryRun) {
         printWireDryRun(getProjectPaths(projectRoot).engine, name, subscriptDir, domFilePath, domTargetPath, options);
         return;

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

@@ -9,8 +9,8 @@
  */
 import type { FireForgeConfig } from '../types/config.js';
 export { mutateConfig } from './config-mutate.js';
-export { CONFIG_FILENAME, CONFIGS_DIR, ENGINE_DIR, FIREFORGE_DIR, getProjectPaths, PATCHES_DIR, SRC_DIR, STATE_FILENAME, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
-export { loadState, saveState, updateState, validateFireForgeState } from './config-state.js';
+export { CONFIG_FILENAME, FIREFORGE_DIR, getProjectPaths, STATE_FILENAME, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
+export { loadState, saveState, updateState } from './config-state.js';
 export { validateConfig } from './config-validate.js';
 /**
  * Checks if a fireforge.json exists in the given directory.

package/dist/src/core/config.js

@@ -17,8 +17,8 @@ import { validateConfig } from './config-validate.js';
 import { createSiblingLockPath, withFileLock } from './file-lock.js';
 // ---- re-exports ----
 export { mutateConfig } from './config-mutate.js';
-export { CONFIG_FILENAME, CONFIGS_DIR, ENGINE_DIR, FIREFORGE_DIR, getProjectPaths, PATCHES_DIR, SRC_DIR, STATE_FILENAME, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
-export { loadState, saveState, updateState, validateFireForgeState } from './config-state.js';
+export { CONFIG_FILENAME, FIREFORGE_DIR, getProjectPaths, STATE_FILENAME, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
+export { loadState, saveState, updateState } from './config-state.js';
 export { validateConfig } from './config-validate.js';
 // ---- config I/O (stays here because it bridges paths + validation) ----
 /**

package/dist/src/core/furnace-apply-helpers.js

@@ -8,7 +8,7 @@ import { copyFile, ensureDir, pathExists, readText, removeFile } from '../utils/
 import { verbose } from '../utils/logger.js';
 import { applyCustomFtlFile, describeLocaleFtlJarMnRegistration, removeCustomFtlJarMnEntry, } from './furnace-apply-ftl.js';
 import { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
-import { addCustomElementRegistration, addJarMnEntries, validateCustomElementRegistration, validateJarMnEntries, } from './furnace-registration.js';
+import { addCustomElementRegistration, addJarMnEntries, validateCustomElementRegistration, validateJarMnInsertionForFiles, } from './furnace-registration.js';
 import { recordCreatedDir, snapshotFile } from './furnace-rollback.js';
 import { checkRegistrationConsistency } from './furnace-validate-registration.js';
 import { isGitRepository } from './git.js';
@@ -352,7 +352,7 @@ async function buildCustomDryRunActions(name, componentDir, engineDir, config, t
         .map((entry) => entry.name);
     if (copiedFileNames.length > 0) {
         try {
-            await validateJarMnEntries(engineDir, name, copiedFileNames);
+            await validateJarMnInsertionForFiles(engineDir, name, copiedFileNames);
         }
         catch (error) {
             stepErrors.push({