@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/core/mach.js

@@ -1,445 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { basename, dirname, join } from 'node:path';
-import { MachNotFoundError } from '../errors/build.js';
-import { pathExists } from '../utils/fs.js';
-import { info, warn } from '../utils/logger.js';
-import { exec, execInherit, execInheritCapture, execSmokeRun, execStream, } from '../utils/process.js';
-import { withBuildRunRecord } from './build-run-record.js';
-import { createSiblingLockPath, withFileLock } from './file-lock.js';
-import { ensureFirefoxIgnorefileCompatibility } from './firefox-ignorefile.js';
-import { createLinePrefixer } from './line-prefixer.js';
-import { explainMachError } from './mach-error-hints.js';
-import { createKnownTeardownNoiseFilter, createTeardownNoiseContext, hasKnownTeardownNoise, KNOWN_TEARDOWN_NOISE_BUILD_NOTE, } from './mach-known-noise-filter.js';
-import { getPython } from './mach-python.js';
-import { installMachResourceGuard } from './mach-resource-shim.js';
-import { teeToRunLog, writeToActiveRunLog } from './run-log.js';
-import { detectHarnessCrashSignature } from './test-harness-crash.js';
-// Re-export sub-modules so existing `from './mach.js'` imports keep working.
-// 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
-// that mocks `mach.js`.
-export { attemptMozinfoRewrite, buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, } from './mach-build-artifacts.js';
-export { generateMozconfig } from './mach-mozconfig.js';
-export { ensurePython } from './mach-python.js';
-/**
- * Ensures mach is available in the engine directory.
- * @param engineDir - Path to the engine directory
- * @throws MachNotFoundError if mach is not found
- */
-export async function ensureMach(engineDir) {
-    const machPath = join(engineDir, 'mach');
-    if (!(await pathExists(machPath))) {
-        throw new MachNotFoundError(engineDir);
-    }
-}
-/**
- * Runs a mach command in the engine directory.
- * @param args - mach command and arguments
- * @param engineDir - Path to the engine directory
- * @param options - Command options
- * @returns Exit code
- */
-export async function runMach(args, engineDir, options = {}) {
-    const python = await getPython(engineDir);
-    await ensureMach(engineDir);
-    await ensureFirefoxIgnorefileCompatibility(engineDir);
-    const machPath = join(engineDir, 'mach');
-    const execOptions = {
-        cwd: engineDir,
-        ...(options.env ? { env: options.env } : {}),
-    };
-    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
-        // for no reaping benefit.
-        return execInherit(python, [machPath, ...args], { ...execOptions, processGroup: true });
-    }
-    const result = await exec(python, [machPath, ...args], execOptions);
-    return result.exitCode;
-}
-/**
- * Maximum bytes retained per stream in `runMachCapture`. Only the tail of
- * output is kept so long-lived processes (Storybook, `mach build`) do not
- * grow the Node heap without bound. 2 MB is enough for post-run error
- * diagnosis while staying well below the 50 MB cap in `createStreamCollector`.
- */
-const CAPTURE_TAIL_LIMIT = 2 * 1024 * 1024;
-/**
- * Runs a mach command while streaming output to the terminal and capturing
- * the tail of stdout/stderr for post-run diagnostics. Output beyond
- * {@link CAPTURE_TAIL_LIMIT} is discarded from the head to prevent unbounded
- * memory growth during long-lived processes like Storybook.
- */
-export async function runMachCapture(args, engineDir, options = {}) {
-    const python = await getPython(engineDir);
-    await ensureMach(engineDir);
-    await ensureFirefoxIgnorefileCompatibility(engineDir);
-    const machPath = join(engineDir, 'mach');
-    let stdout = '';
-    let stderr = '';
-    // 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
-    // SUITE_END marker usually arrives on stdout while the teardown traceback
-    // lands on stderr, so the shutdown-seen flag must span the pair.
-    const noiseContext = options.annotateKnownTeardownNoise === true ? createTeardownNoiseContext() : undefined;
-    const stdoutFilter = noiseContext && createKnownTeardownNoiseFilter(noiseContext);
-    const stderrFilter = noiseContext && createKnownTeardownNoiseFilter(noiseContext);
-    const prefix = options.outputPrefix;
-    const prefixers = prefix === undefined
-        ? undefined
-        : {
-            stdoutLog: createLinePrefixer(prefix),
-            stdoutEcho: createLinePrefixer(prefix),
-            stderrLog: createLinePrefixer(prefix),
-            stderrEcho: createLinePrefixer(prefix),
-        };
-    const exitCode = await execStream(python, [machPath, ...args], {
-        cwd: engineDir,
-        ...(options.env ? { env: options.env } : {}),
-        ...(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.
-        processGroup: true,
-        ...(options.onProcessGroup ? { onProcessGroup: options.onProcessGroup } : {}),
-        ...(options.postCloseSweep ? { postCloseSweep: options.postCloseSweep } : {}),
-        onStdout: (data) => {
-            options.onOutputChunk?.('stdout', 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
-            // re-read after the fact by whoever is diagnosing the run, and the
-            // 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(prefixers ? prefixers.stdoutLog.transform(data) : data);
-            const echo = stdoutFilter ? stdoutFilter.transform(data) : data;
-            process.stdout.write(prefixers ? prefixers.stdoutEcho.transform(echo) : echo);
-        },
-        onStderr: (data) => {
-            options.onOutputChunk?.('stderr', data);
-            stderr += data;
-            if (stderr.length > CAPTURE_TAIL_LIMIT) {
-                stderr = stderr.slice(-CAPTURE_TAIL_LIMIT);
-            }
-            writeToActiveRunLog(prefixers ? prefixers.stderrLog.transform(data) : data);
-            const echo = stderrFilter ? stderrFilter.transform(data) : data;
-            process.stderr.write(prefixers ? prefixers.stderrEcho.transform(echo) : echo);
-        },
-    });
-    if (stdoutFilter) {
-        const residue = stdoutFilter.flush();
-        if (residue.length > 0) {
-            process.stdout.write(prefixers ? prefixers.stdoutEcho.transform(residue) : residue);
-        }
-    }
-    if (stderrFilter) {
-        const residue = stderrFilter.flush();
-        if (residue.length > 0) {
-            process.stderr.write(prefixers ? prefixers.stderrEcho.transform(residue) : residue);
-        }
-    }
-    return { stdout, stderr, exitCode };
-}
-/**
- * Runs a mach command while inheriting stdin, streaming output live, and
- * capturing stdout/stderr for post-run diagnostics.
- */
-export async function runMachInheritCapture(args, engineDir, options = {}) {
-    const python = await getPython(engineDir);
-    await ensureMach(engineDir);
-    await ensureFirefoxIgnorefileCompatibility(engineDir);
-    const machPath = join(engineDir, 'mach');
-    return execInheritCapture(python, [machPath, ...args], {
-        cwd: engineDir,
-        ...(options.env ? { env: options.env } : {}),
-        ...(options.envUnset ? { envUnset: options.envUnset } : {}),
-        // This path streams through the collectors' mirror rather than per-chunk
-        // callbacks, so the run-log tee rides the mirror. `mach build` is here.
-        mirror: { stdout: teeToRunLog(process.stdout), stderr: teeToRunLog(process.stderr) },
-        processGroup: true,
-    });
-}
-/**
- * Runs mach bootstrap while preserving stdin and capturing the emitted output.
- * @param engineDir - Path to the engine directory
- * @returns Captured output and exit code
- */
-export async function bootstrapWithOutput(engineDir) {
-    return runMachInheritCapture(['bootstrap', '--application-choice', 'browser'], engineDir);
-}
-/**
- * Prints any matched {@link MachErrorHint} hints for the captured mach
- * output. No-op when nothing matches. Always called before a non-zero exit
- * 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
- * streams its subcommand output through a timestamp-prefixing wrapper that
- * 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.
- */
-function surfaceMachErrorHints(result) {
-    const combined = `${result.stderr}\n${result.stdout}`;
-    const hints = explainMachError(combined);
-    if (hints.length === 0)
-        return;
-    for (const hint of hints) {
-        warn(`Hint: ${hint}`);
-    }
-}
-/**
- * Uniform recognized-crash retry budget for the protected mach build
- * dispatches (`fireforge build`, `build --ui`, and the pre-test `--build`
- * step). Matches the test harness default so every mach dispatch retries
- * the same crash family the same number of times.
- */
-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
- * (see `mach-known-noise-filter.ts`), so it reached operators as an
- * 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.
- */
-function noteKnownTeardownNoiseInBuild(result) {
-    if (!hasKnownTeardownNoise(`${result.stdout}\n${result.stderr}`))
-        return;
-    info(KNOWN_TEARDOWN_NOISE_BUILD_NOTE);
-}
-/**
- * The single protected path every FireForge mach build dispatch routes
- * 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
- *     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
- *     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
- * `mach build faster`, so it cannot invalidate more of the objdir than the
- * command the operator asked for.
- */
-export async function runProtectedMachBuild(kind, engineDir, options = {}) {
-    const args = kind === 'faster' ? ['build', 'faster'] : ['build'];
-    if (kind === 'full' && options.jobs !== undefined) {
-        args.push('-j', String(options.jobs));
-    }
-    // The run record lets any session see why a bundle is missing after this
-    // build dies part-way (see build-run-record.ts). The engine directory is
-    // always `<projectRoot>/engine`.
-    return withBuildRunRecord(dirname(engineDir), `mach ${args.join(' ')}`, () => runProtectedMachBuildAttempts(args, kind, engineDir, options));
-}
-async function runProtectedMachBuildAttempts(args, kind, engineDir, options) {
-    const maxAttempts = Math.max(1, (options.retries ?? DEFAULT_BUILD_CRASH_RETRIES) + 1);
-    for (let attempt = 1;; attempt += 1) {
-        const { env } = await installMachResourceGuard(engineDir);
-        const result = await runMachInheritCapture(args, engineDir, { env });
-        if (result.exitCode === 0) {
-            noteKnownTeardownNoiseInBuild(result);
-            return { ...result, attempts: attempt };
-        }
-        const signature = detectHarnessCrashSignature(`${result.stdout}\n${result.stderr}`);
-        if (signature && attempt < maxAttempts) {
-            options.onRetry?.(signature, attempt + 1, maxAttempts);
-            warn(`mach ${kind === 'faster' ? 'build faster' : 'build'} hit a recognized harness crash ` +
-                `(${signature.reason}): ${signature.line}\n` +
-                `Retrying with a fresh process (attempt ${attempt + 1} of ${maxAttempts})...`);
-            continue;
-        }
-        surfaceMachErrorHints(result);
-        noteKnownTeardownNoiseInBuild(result);
-        return { ...result, attempts: attempt, ...(signature ? { crashSignature: signature } : {}) };
-    }
-}
-/**
- * Runs a full mach build through the protected dispatch path (resource
- * guard + recognized-crash retries). On a non-zero exit, any matched error
- * 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`
- * notice that mach emits when a tool-managed edit landed on
- * `moz.configure` before the build.
- * @param engineDir - Path to the engine directory
- * @param jobs - Number of parallel jobs (optional)
- * @returns Captured mach result (stdout tail, stderr tail, exit code)
- */
-export async function build(engineDir, jobs) {
-    return runProtectedMachBuild('full', engineDir, { jobs });
-}
-/**
- * Runs a fast UI-only build through the same protected dispatch path as
- * {@link build}. See {@link build} for why the full captured result is
- * returned rather than just the exit code.
- * @param engineDir - Path to the engine directory
- * @returns Captured mach result
- */
-export async function buildUI(engineDir) {
-    return runProtectedMachBuild('faster', engineDir);
-}
-/**
- * Runs an operation while holding a sidecar build lock keyed on the project
- * root. Concurrent `fireforge build` / `fireforge build --ui` invocations
- * against the same tree serialise instead of racing through the mach
- * obj-dir.
- *
- * 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
- * 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
- * (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.
- *
- * The project-root variant is the right granularity: a single machine may
- * have several FireForge projects side by side and nothing says they cannot
- * build in parallel. The lock serialises *within* one project.
- *
- * Returns whatever the inner operation returns.
- */
-export async function withBuildLock(projectRoot, operation) {
-    const lockPath = createSiblingLockPath(join(projectRoot, '.fireforge-build'), '.lock');
-    return withFileLock(lockPath, operation, {
-        // 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}. ` +
-            'If no other `fireforge build` is running, remove the lock directory and retry.',
-        onStaleLockMessage: (ageMs) => `Removing stale FireForge build lock ${basename(lockPath)} (age: ${Math.round(ageMs / 1000)}s). A previous build process may have crashed.`,
-    });
-}
-/**
- * Runs the built browser.
- * @param engineDir - Path to the engine directory
- * @param args - Additional arguments to pass to the browser
- * @returns Exit code
- */
-export async function run(engineDir, args = []) {
-    return runMach(['run', ...args], engineDir, { inherit: true });
-}
-/**
- * Launches `mach run` under the smoke-run wrapper: streams line-by-line,
- * 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
- * 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.
- */
-export async function runMachSmoke(args, engineDir, options) {
-    const python = await getPython(engineDir);
-    await ensureMach(engineDir);
-    await ensureFirefoxIgnorefileCompatibility(engineDir);
-    const machPath = join(engineDir, 'mach');
-    return execSmokeRun(python, [machPath, ...args], {
-        cwd: engineDir,
-        ...(options.env ? { env: options.env } : {}),
-        smokeTimeoutMs: options.smokeTimeoutMs,
-        ...(options.killGraceMs !== undefined ? { killGraceMs: options.killGraceMs } : {}),
-        ...(options.onStdoutLine ? { onStdoutLine: options.onStdoutLine } : {}),
-        ...(options.onStderrLine ? { onStderrLine: options.onStderrLine } : {}),
-        ...(options.mirror ? { mirror: options.mirror } : {}),
-    });
-}
-/**
- * Creates a distribution package while streaming output to the terminal
- * 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)
- */
-export async function machPackageCapture(engineDir) {
-    return runMachCapture(['package'], engineDir);
-}
-/**
- * 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, 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
- * @param options - Optional environment overrides merged into the mach
- *   subprocess env
- * @returns Captured output and exit code
- */
-export async function watchWithOutput(engineDir, options = {}) {
-    return runMachInheritCapture(['watch'], engineDir, options.env ? { env: options.env } : {});
-}
-/**
- * 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, 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
- * alone.
- */
-const CODING_AGENT_ENV_MARKERS = ['CLAUDECODE'];
-/**
- * The `envUnset` list for a test dispatch: the coding-agent markers when
- * full verbosity was requested, nothing otherwise.
- *
- * Opt-in rather than unconditional: this changes how much a third party
- * prints, and an operator who wants mozbuild's quieting should keep it.
- */
-function testVerbosityEnvUnset(fullOutput) {
-    return fullOutput === true ? CODING_AGENT_ENV_MARKERS : undefined;
-}
-/**
- * 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 kind - Which mach command to run
- * @param options - Engine checkout, test paths, extra args, env, verbosity
- */
-export async function runMachTestSuite(kind, options) {
-    const { engineDir, testPaths = [], args = [], env, fullOutput, teardown, outputPrefix } = options;
-    const guard = await installMachResourceGuard(engineDir);
-    const envUnset = testVerbosityEnvUnset(fullOutput);
-    return runMachCapture([kind, ...testPaths, ...args], engineDir, {
-        env: { ...guard.env, ...env },
-        ...(envUnset ? { envUnset } : {}),
-        ...teardown,
-        ...(outputPrefix === undefined ? {} : { outputPrefix }),
-        annotateKnownTeardownNoise: true,
-    });
-}

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

@@ -1,153 +0,0 @@
-/** Default Marionette control port set by `-marionette`. */
-export declare const DEFAULT_MARIONETTE_PORT = 2828;
-/**
- * Information about a process holding the Marionette port.
- */
-export interface MarionettePortHolder {
-    /** OS process ID. */
-    pid: number;
-    /** Process basename (e.g. `forgefresh`, `firefox`). */
-    command: string;
-    /**
-     * 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
-     * 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.
-     */
-    commandLine: string;
-}
-/**
- * Result of a Marionette port probe.
- */
-export interface MarionettePortProbeResult {
-    /** True when something is listening on the probed port. */
-    inUse: boolean;
-    /** Details about the holder, when the probe recovered them. */
-    holder?: MarionettePortHolder;
-}
-/** A Firefox-family process launched from this project's built bundle. */
-export interface RunningBundleProcess {
-    pid: number;
-    commandLine: string;
-    /**
-     * Elapsed wall-clock seconds since the process started, from `ps
-     * 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.
-     */
-    elapsedSeconds: number;
-    parentPid?: number;
-    owner?: string;
-}
-/**
- * Pure parser kept exported so platform output handling is
- * regression-testable.
- *
- * Reads `pid etime args` where the middle field is a `ps` duration. The
- * 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.
- */
-export declare function parseProcessList(stdout: string, launchableBinary: string): RunningBundleProcess[];
-/**
- * Refuses a browser-harness launch when this objdir's app is already alive,
- * or terminates the parent when the operator explicitly opted into stale
- * browser cleanup. This closes the no-listening-port variant of the stale
- * Marionette process failure.
- */
-export declare function ensureLaunchableBrowserNotRunning(launchableBinary: string, options?: {
-    killStaleBrowser?: boolean;
-}): Promise<void>;
-/**
- * Builds the refusal for a running objdir browser.
- *
- * 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
- * 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
- * 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
- * automatic one.
- *
- * Exported for direct unit testing.
- */
-export declare function describeRunningBundleRefusal(holder: RunningBundleProcess): string;
-/**
- * Probes whether the Marionette port is currently bound by a
- * listener. The probe is best-effort: missing tooling returns
- * `{ inUse: false }` without failing.
- *
- * @param port - Port to probe (default {@link DEFAULT_MARIONETTE_PORT}).
- */
-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
- * error when the holder is unrelated (so the operator still sees
- * a useful signal but can decide whether to wait it out).
- *
- * @param port - Port to probe (default {@link DEFAULT_MARIONETTE_PORT}).
- * @param options - Extra context for the error message (the project's
- *   `binaryName` is used to recognise fork-branded browser binaries).
- */
-export declare function assertMarionettePortAvailable(port?: number, options?: {
-    binaryName?: string;
-}): Promise<void>;
-/**
- * Ensures the Marionette port is usable, optionally terminating a stale
- * Firefox-family browser holder first. Unrelated listeners still fail.
- */
-export declare function ensureMarionettePortAvailable(port?: number, options?: {
-    binaryName?: string;
-    killStaleBrowser?: boolean;
-}): Promise<void>;
-/**
- * Extracts a `--marionette-port=N` (or `--marionette-port N`) argument from
- * a list of forwarded mach args, if present. Used so an operator passing the
- * port via `--mach-arg --marionette-port=NNNN` gets the same preflight
- * override they would from a first-class `--marionette-port` option, rather
- * than the wrapper probing the default port and refusing.
- *
- * Also recognises `--setpref=marionette.port=NNNN` since that is the path
- * the test command auto-forwards to mach.
- *
- * @param machArgs - Forwarded mach args as they would appear on the command
- *   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.).
- *
- * Does not treat `--marionette-port` as a client endpoint.
- */
-export declare function forwardedMachArgsIncludeMarionetteClient(machArgs: string[]): boolean;
-/**
- * True when forwarded mach args explicitly select the xpcshell harness.
- * Used so `--marionette-port` auto-forward skips `--setpref=marionette.port`
- * for runs where the pref is ignored anyway.
- */
-export declare function hasExplicitXpcshellFlavor(machArgs: string[]): boolean;
-/**
- * Whether `fireforge test` should append `--setpref=marionette.port=<n>` and
- * `--marionette=127.0.0.1:<n>` when the operator passed `--marionette-port`.
- * Forwards for every harness except an explicit `--flavor=xpcshell` /
- * `xpcshell-tests` (toolkit widget mochitests under `toolkit/content/tests/`
- * do not match the older path-only heuristic but still launch a
- * Marionette-driven browser).
- */
-export declare function shouldAutoForwardMarionettePortToMach(machArgs: string[]): boolean;