@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/mach.js

@@ -16,11 +16,11 @@ import { detectHarnessCrashSignature } from './test-harness-crash.js';
 // This block is a frozen compatibility list, not a barrel to grow: every name
 // here already had a `from './mach.js'` import when the module was split.
 // New helpers belong in their own sub-module and are imported from it
-// directly — adding to this list pulls the whole sub-module into every suite
+// directly. Adding to this list pulls the whole sub-module into every suite
 // that mocks `mach.js`.
 export { attemptMozinfoRewrite, buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, } from './mach-build-artifacts.js';
 export { generateMozconfig } from './mach-mozconfig.js';
-export { ensurePython, resetResolvedPython } from './mach-python.js';
+export { ensurePython } from './mach-python.js';
 /**
  * Ensures mach is available in the engine directory.
  * @param engineDir - Path to the engine directory
@@ -51,8 +51,8 @@ export async function runMach(args, engineDir, options = {}) {
     if (options.inherit) {
         // Group-reap every long-lived inherited mach dispatch (bootstrap, run,
         // watch): a mach dying at startup must not strand multiprocessing
-        // workers. Short-lived metadata queries below stay on plain exec() —
-        // adding groups there would touch every non-mach exec consumer's path
+        // workers. Short-lived metadata queries below stay on plain exec().
+        // Adding groups there would touch every non-mach exec consumer's path
         // for no reaping benefit.
         return execInherit(python, [machPath, ...args], { ...execOptions, processGroup: true });
     }
@@ -79,7 +79,7 @@ export async function runMachCapture(args, engineDir, options = {}) {
     const machPath = join(engineDir, 'mach');
     let stdout = '';
     let stderr = '';
-    // Echo-path filters only: the captured strings above accumulate RAW so the
+    // Echo-path filters only: the captured strings above accumulate raw so the
     // classifier still sees the full teardown traceback. When the option is
     // off, the filters are absent and echo is a straight write (unchanged).
     // One shutdown context per run, shared by both stream filters: the
@@ -94,18 +94,18 @@ export async function runMachCapture(args, engineDir, options = {}) {
         ...(options.envUnset ? { envUnset: options.envUnset } : {}),
         // Every capture dispatch (test suites, protected builds, package,
         // storybook) runs as a process-group leader and is group-reaped on
-        // exit/abort — see ExecOptions.processGroup.
+        // exit/abort. See ExecOptions.processGroup.
         processGroup: true,
         onStdout: (data) => {
             stdout += data;
             if (stdout.length > CAPTURE_TAIL_LIMIT) {
                 stdout = stdout.slice(-CAPTURE_TAIL_LIMIT);
             }
-            // RAW into the log, filtered into the echo. The log exists to be
+            // Raw into the log, filtered into the echo. The log exists to be
             // re-read after the fact by whoever is diagnosing the run, and the
-            // echo filter's whole purpose is to shorten what a HUMAN scrolls
-            // past — collapsing a traceback in the artifact would reintroduce
-            // the loss this log exists to prevent.
+            // echo filter only exists to shorten what a human scrolls past.
+            // Collapsing a traceback in the artifact would reintroduce the loss
+            // this log exists to prevent.
             writeToActiveRunLog(data);
             process.stdout.write(stdoutFilter ? stdoutFilter.transform(data) : data);
         },
@@ -149,14 +149,6 @@ export async function runMachInheritCapture(args, engineDir, options = {}) {
         processGroup: true,
     });
 }
-/**
- * Runs mach bootstrap to install build dependencies.
- * @param engineDir - Path to the engine directory
- * @returns Exit code
- */
-export async function bootstrap(engineDir) {
-    return runMach(['bootstrap', '--application-choice', 'browser'], engineDir, { inherit: true });
-}
 /**
  * Runs mach bootstrap while preserving stdin and capturing the emitted output.
  * @param engineDir - Path to the engine directory
@@ -171,9 +163,9 @@ export async function bootstrapWithOutput(engineDir) {
  * propagates so the hint sits immediately below the raw mach error in the
  * operator's terminal.
  *
- * The scanner is passed the concatenation of stderr AND stdout because mach
+ * The scanner is passed the concatenation of stderr and stdout because mach
  * streams its subcommand output through a timestamp-prefixing wrapper that
- * writes both streams to whatever FD the subprocess chose — `rustc` errors
+ * writes both streams to whatever FD the subprocess chose, so `rustc` errors
  * from `mach build` can land on stdout, so feeding only `result.stderr`
  * silently loses the match.
  */
@@ -194,10 +186,10 @@ function surfaceMachErrorHints(result) {
  */
 const DEFAULT_BUILD_CRASH_RETRIES = 2;
 /**
- * Names the known mozsystemmonitor teardown traceback when a BUILD carried
- * it. The test path collapses this signature in the echo; a build cannot
+ * Names the known mozsystemmonitor teardown traceback when a build carried
+ * it. The test path collapses this signature in the echo. A build cannot
  * (see `mach-known-noise-filter.ts`), so it reached operators as an
- * unexplained traceback in a build log — a recognized, documented upstream
+ * unexplained traceback in a build log: a recognized, documented upstream
  * defect wearing the appearance of a new one. The output is left verbatim
  * and this one line is added beside it, so the same signature reads the same
  * in both phases.
@@ -209,20 +201,20 @@ function noteKnownTeardownNoiseInBuild(result) {
 }
 /**
  * The single protected path every FireForge mach build dispatch routes
- * through — `build`, `build --ui`, and the pre-test `--build` step all use
+ * through. `build`, `build --ui`, and the pre-test `--build` step all use
  * it, so no entry point is left unprotected with a different retry budget:
  *
- *  1. installs the resource-monitor degrade guard IN the mach virtualenvs
- *     (plus the PYTHONPATH fallback) — re-installed before every attempt, so
+ *  1. installs the resource-monitor degrade guard in the mach virtualenvs
+ *     (plus the PYTHONPATH fallback), re-installed before every attempt, so
  *     a venv materialized by a crashed first attempt is guarded on the next
- *     one instead of every retry dying on the same wedged state;
- *  2. spawns a fresh mach process per attempt;
- *  3. retries ONLY the recognized harness-crash family (resource monitor /
- *     psutil startup tracebacks) up to the uniform budget — an ordinary
+ *     one instead of every retry dying on the same wedged state.
+ *  2. spawns a fresh mach process per attempt.
+ *  3. retries only the recognized harness-crash family (resource monitor /
+ *     psutil startup tracebacks) up to the uniform budget. An ordinary
  *     compile error is never retried.
  *
  * The protected path never runs `mach configure`, never clobbers, and never
- * widens the requested build kind — a `faster` dispatch retries as
+ * widens the requested build kind: a `faster` dispatch retries as
  * `mach build faster`, so it cannot invalidate more of the objdir than the
  * command the operator asked for.
  */
@@ -258,8 +250,8 @@ export async function runProtectedMachBuild(kind, engineDir, options = {}) {
  * hints are surfaced on top of the raw mach output so operators get an
  * actionable nudge alongside the cryptic mozbuild traceback. Returns the
  * captured result so the caller (e.g. `fireforge build`) can inspect the
- * tail for post-build diagnostics that mach prints AFTER "Your build was
- * successful!" — notably the stale `config.status is out of date`
+ * tail for post-build diagnostics that mach prints after "Your build was
+ * successful!", notably the stale `config.status is out of date`
  * notice that mach emits when a tool-managed edit landed on
  * `moz.configure` before the build.
  * @param engineDir - Path to the engine directory
@@ -287,13 +279,13 @@ export async function buildUI(engineDir) {
  *
  * Without it, a `build --ui` started while a full `build` is still in flight
  * hands off to `mach build faster` and fails almost immediately with `No
- * rule to make target 'XUL'` — the real problem being that the first build
+ * rule to make target 'XUL'`, the real problem being that the first build
  * has not yet materialised the full backend, with nothing in the low-level
  * make error pointing at the concurrent run. The lock intercepts the second
  * invocation before it touches mach, and the refusal names the PID holding
  * the lock so the operator can decide whether to wait or investigate.
  *
- * Stale-lock recovery: the lock stores the owner PID; a crashed build
+ * Stale-lock recovery: the lock stores the owner PID. A crashed build
  * (SIGINT, SIGTERM, or a kernel kill) leaves the lock dir behind but not the
  * owning process, and `withFileLock` removes the lock on the next attempt
  * when `process.kill(pid, 0)` shows the owner is gone.
@@ -307,9 +299,9 @@ export async function buildUI(engineDir) {
 export async function withBuildLock(projectRoot, operation) {
     const lockPath = createSiblingLockPath(join(projectRoot, '.fireforge-build'), '.lock');
     return withFileLock(lockPath, operation, {
-        // Default lock timeout is 30s; bump to 24h so a slow full build does
-        // not trip the timeout while the second invocation waits. A real
-        // operator will ^C long before 24h elapses; the ceiling is there
+        // Default lock timeout is 30s. Bump it to 24h so a slow full build
+        // does not trip the timeout while the second invocation waits. A real
+        // operator will ^C long before 24h elapses. The ceiling is there
         // purely so a forgotten lock cannot wedge the command forever.
         timeoutMs: 24 * 60 * 60 * 1000,
         onTimeoutMessage: `Timed out waiting for the FireForge build lock at ${lockPath}. ` +
@@ -331,7 +323,7 @@ export async function run(engineDir, args = []) {
  * enforces a deadline by SIGTERMing the whole process group, and returns
  * the captured output alongside a `timedOut` flag.
  *
- * Unlike {@link run}, this variant does NOT inherit stdio. The child
+ * Unlike {@link run}, this variant does not inherit stdio. The child
  * stdout/stderr are piped back through the line callbacks so the caller
  * can scan for `JavaScript error:` / `console.error:` without coupling
  * the runner to chrome-specific pattern logic.
@@ -351,20 +343,10 @@ export async function runMachSmoke(args, engineDir, options) {
         ...(options.mirror ? { mirror: options.mirror } : {}),
     });
 }
-/**
- * Creates a distribution package.
- * @param engineDir - Path to the engine directory
- * @returns Exit code
- */
-export async function machPackage(engineDir) {
-    return runMach(['package'], engineDir, { inherit: true });
-}
 /**
  * Creates a distribution package while streaming output to the terminal
- * and capturing the stderr tail for post-run diagnostics. Callers that
- * want to consult {@link explainMachError} on failure should use this
- * variant; the inherit-only `machPackage` above remains for callers that
- * just need an exit code.
+ * and capturing the stderr tail for post-run diagnostics, so callers can
+ * consult {@link explainMachError} on failure.
  *
  * @param engineDir - Path to the engine directory
  * @returns Captured mach result (stdout tail, stderr tail, exit code)
@@ -372,21 +354,13 @@ export async function machPackage(engineDir) {
 export async function machPackageCapture(engineDir) {
     return runMachCapture(['package'], engineDir);
 }
-/**
- * Runs mach watch for auto-rebuilding.
- * @param engineDir - Path to the engine directory
- * @returns Exit code
- */
-export async function watch(engineDir) {
-    return runMach(['watch'], engineDir, { inherit: true });
-}
 /**
  * Runs mach watch while preserving stdin and capturing emitted output.
  *
  * `env` is threaded through so the caller can prepend the resolved watchman
  * directory to PATH in a way mach inherits: `fireforge watch` can locate
  * `watchman` via `which`, but the mach subprocess spawns with the parent's
- * PATH only — on macOS that typically omits `/opt/homebrew/bin`, so
+ * PATH only, and on macOS that typically omits `/opt/homebrew/bin`, so
  * `mach watch` fails at the `watch-project` subscription step.
  *
  * @param engineDir - Path to the engine directory
@@ -397,28 +371,18 @@ export async function watch(engineDir) {
 export async function watchWithOutput(engineDir, options = {}) {
     return runMachInheritCapture(['watch'], engineDir, options.env ? { env: options.env } : {});
 }
-/**
- * Runs mach test with the given test paths.
- * @param engineDir - Path to the engine directory
- * @param testPaths - Test file or directory paths (relative to engine)
- * @param args - Additional arguments to pass to mach test
- * @returns Exit code
- */
-export async function test(engineDir, testPaths = [], args = []) {
-    return runMach(['test', ...testPaths, ...args], engineDir, { inherit: true });
-}
 /**
  * Environment markers mozbuild reads to decide it is running under a coding
  * agent (`mozbuild.util.is_running_under_coding_agent`), which quiets
  * terminal output to warnings and errors.
  *
- * The quieting is genuinely useful for BUILDS — that is most of what an
- * agent session prints — but it applies to test runs too, where it removes
+ * The quieting is genuinely useful for builds, which are most of what an
+ * agent session prints, but it applies to test runs too, where it removes
  * `TEST_START` and console INFO: exactly the lines a hang or stall
  * diagnosis needs, and the ones FireForge's own classifier reads
  * (`Ran N checks`, `Unexpected results:`, `TEST-UNEXPECTED-*`). Unsetting
  * the variable globally would give up the build half as well, so the
- * dispatchers below unset it per TEST dispatch and leave the build path
+ * dispatchers below unset it per test dispatch and leave the build path
  * alone.
  */
 const CODING_AGENT_ENV_MARKERS = ['CLAUDECODE'];
@@ -433,52 +397,20 @@ function testVerbosityEnvUnset(fullOutput) {
     return fullOutput === true ? CODING_AGENT_ENV_MARKERS : undefined;
 }
 /**
- * Runs mach test while capturing streamed output for better diagnostics.
+ * Runs one mach test command (`mach test` / `mach xpcshell-test` / `mach
+ * mochitest`) while capturing streamed output for better diagnostics. The
+ * three commands share every other detail of the dispatch (resource guard,
+ * verbosity env, teardown-noise annotation), so they share one entry point
+ * keyed by `kind` rather than three copies that drift.
  *
- * @param engineDir - Absolute path to the engine checkout
- * @param testPaths - Test paths to pass to `mach test`; empty runs the default set
- * @param args - Extra `mach test` arguments appended after the paths
- * @param env - Optional extra environment variables for the mach process
- *   (merged over `process.env` by the exec layer). Used by
- *   `fireforge test --perf-samples` to publish the artifact-path contract.
- */
-export async function testWithOutput(engineDir, testPaths = [], args = [], env, fullOutput) {
-    const guard = await installMachResourceGuard(engineDir);
-    const envUnset = testVerbosityEnvUnset(fullOutput);
-    return runMachCapture(['test', ...testPaths, ...args], engineDir, {
-        env: { ...guard.env, ...env },
-        ...(envUnset ? { envUnset } : {}),
-        annotateKnownTeardownNoise: true,
-    });
-}
-/**
- * Runs `mach xpcshell-test` (the suite-specific xpcshell command) while
- * capturing output. Unlike the generic `mach test`, the suite-specific
- * commands degrade a broken mozlog resource monitor to a warning instead of
- * crashing at startup, so `fireforge test` dispatches single-suite runs here
- * to stay resilient to the host psutil failure.
- *
- * Signature mirrors {@link testWithOutput} so the two are interchangeable in
- * the dispatch path.
- */
-export async function xpcshellTestWithOutput(engineDir, testPaths = [], args = [], env, fullOutput) {
-    const guard = await installMachResourceGuard(engineDir);
-    const envUnset = testVerbosityEnvUnset(fullOutput);
-    return runMachCapture(['xpcshell-test', ...testPaths, ...args], engineDir, {
-        env: { ...guard.env, ...env },
-        ...(envUnset ? { envUnset } : {}),
-        annotateKnownTeardownNoise: true,
-    });
-}
-/**
- * Runs `mach mochitest` (covers browser-chrome / mochitest flavors) while
- * capturing output. The suite-specific counterpart to {@link testWithOutput}
- * for non-xpcshell single-suite runs — see {@link xpcshellTestWithOutput}.
+ * @param kind - Which mach command to run
+ * @param options - Engine checkout, test paths, extra args, env, verbosity
  */
-export async function mochitestWithOutput(engineDir, testPaths = [], args = [], env, fullOutput) {
+export async function runMachTestSuite(kind, options) {
+    const { engineDir, testPaths = [], args = [], env, fullOutput } = options;
     const guard = await installMachResourceGuard(engineDir);
     const envUnset = testVerbosityEnvUnset(fullOutput);
-    return runMachCapture(['mochitest', ...testPaths, ...args], engineDir, {
+    return runMachCapture([kind, ...testPaths, ...args], engineDir, {
         env: { ...guard.env, ...env },
         ...(envUnset ? { envUnset } : {}),
         annotateKnownTeardownNoise: true,

package/dist/src/core/marionette-port.d.ts

@@ -11,7 +11,7 @@ export interface MarionettePortHolder {
     /**
      * Full command line the holder was launched with, when the probe
      * can recover it. `lsof` by itself only returns the basename, so
-     * POSIX callers see `command === commandLine`; Windows callers
+     * POSIX callers see `command === commandLine`. Windows callers
      * recover the full command line via `Get-Process`. Used to detect
      * the `-marionette` flag, which positively identifies a stale
      * browser rather than an unrelated listener.
@@ -33,7 +33,7 @@ export interface RunningBundleProcess {
     commandLine: string;
     /**
      * Elapsed wall-clock seconds since the process started, from `ps
-     * etime=`. `NaN` when the field was absent or unparseable — callers must
+     * etime=`. `NaN` when the field was absent or unparseable, and callers must
      * omit the clause rather than print a zero, because "started 0s ago" is
      * exactly the wrong attribution for a peer session's long-lived browser.
      */
@@ -44,7 +44,7 @@ export interface RunningBundleProcess {
  * regression-testable.
  *
  * Reads `pid etime args` where the middle field is a `ps` duration. The
- * elapsed field is parsed OPTIMISTICALLY: a listing produced without
+ * elapsed field is parsed optimistically: a listing produced without
  * `etime=` still parses, with the duration reported as `NaN` and the whole
  * second field folded back into the command line, so a caller that lost the
  * column degrades to the old behaviour instead of dropping the process.
@@ -62,17 +62,17 @@ export declare function ensureLaunchableBrowserNotRunning(launchableBinary: stri
 /**
  * Builds the refusal for a running objdir browser.
  *
- * Reports the EVIDENCE rather than a bare PID: the elapsed time and the
+ * Reports the evidence rather than a bare PID: the elapsed time and the
  * command line are what let an operator on a shared checkout decide whose
  * process it is, without reconstructing PID ancestry by hand. A downstream
- * fork hit exactly this — the message named a PID belonging to a peer
+ * fork hit exactly this: the message named a PID belonging to a peer
  * session's live browser and offered a flag that would have killed a
  * multi-hour evaluation run.
  *
- * So `--kill-stale-marionette` is offered ONLY for a marionette-driven
+ * So `--kill-stale-marionette` is offered only for a marionette-driven
  * browser. For a bare launch the message says what it found and stops:
  * FireForge cannot tell a dead run's orphan from someone's live window, and
- * the flag is the right MANUAL clear once ownership is verified, never an
+ * the flag is the right manual clear once ownership is verified, never an
  * automatic one.
  *
  * Exported for direct unit testing.
@@ -88,7 +88,7 @@ export declare function describeRunningBundleRefusal(holder: RunningBundleProces
 export declare function probeMarionettePort(port?: number): Promise<MarionettePortProbeResult>;
 /**
  * Raises a targeted {@link GeneralError} when the Marionette port
- * is held by a browser process; raises a softer warning-shaped
+ * is held by a browser process. Raises a softer warning-shaped
  * error when the holder is unrelated (so the operator still sees
  * a useful signal but can decide whether to wait it out).
  *
@@ -118,18 +118,20 @@ export declare function ensureMarionettePortAvailable(port?: number, options?: {
  * the test command auto-forwards to mach.
  *
  * @param machArgs - Forwarded mach args as they would appear on the command
- *   line (one element per token; `--foo=bar` and `--foo bar` both supported).
- * @returns The integer port if a recognised arg is present and parses; else
- *   `undefined`.
+ *   line (one element per token, with `--foo=bar` and `--foo bar` both
+ *   supported).
+ * @returns The integer port if a recognised arg is present and parses,
+ *   otherwise `undefined`.
  */
 export declare function extractForwardedMarionettePort(machArgs: string[]): number | undefined;
 /**
  * True when forwarded mach args already set a Marionette **client** address
  * for mach/mochitest (`--marionette=host:port` or `--marionette host:port`).
  * Used only to avoid duplicating FireForge's auto-injected
- * `--marionette=127.0.0.1:<n>`; this is not a full URL validator (IPv6, etc.).
+ * `--marionette=127.0.0.1:<n>`. This is not a full URL validator (IPv6,
+ * etc.).
  *
- * Deliberately does **not** treat `--marionette-port` as a client endpoint.
+ * Does not treat `--marionette-port` as a client endpoint.
  */
 export declare function forwardedMachArgsIncludeMarionetteClient(machArgs: string[]): boolean;
 /**
@@ -147,20 +149,3 @@ export declare function hasExplicitXpcshellFlavor(machArgs: string[]): boolean;
  * Marionette-driven browser).
  */
 export declare function shouldAutoForwardMarionettePortToMach(machArgs: string[]): boolean;
-/**
- * Heuristic: do the test paths or forwarded mach args indicate a flavour
- * that actually launches a Marionette-driven browser? Browser-chrome and
- * mochitest do; xpcshell does not. A no-paths invocation (the default "run
- * all tests" shape) is treated as marionette-relevant since it includes
- * browser-chrome.
- *
- * Note: `fireforge test` auto-forward of `--marionette-port` to mach uses
- * {@link shouldAutoForwardMarionettePortToMach} (mach-arg flavor gate) rather
- * than this function alone, so toolkit paths without `/mochitest/` still get
- * the listener pref and harness `--marionette=127.0.0.1:<n>` when appropriate.
- *
- * @param testPaths - Engine-relative paths after `stripEnginePrefix`.
- * @param machArgs - Forwarded mach args (post-`--mach-arg`).
- * @returns `true` when the run is likely to bind a Marionette listener.
- */
-export declare function isMarionetteFlavor(testPaths: string[], machArgs: string[]): boolean;