@hominis/fireforge 0.55.0 → 0.60.0

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

@@ -1,284 +0,0 @@
-import { type SmokeLineCallback, type SmokeRunResult } from '../utils/process.js';
-import { type HarnessCrashSignature } from './test-harness-crash.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 declare function ensureMach(engineDir: string): Promise<void>;
-/**
- * Options for running mach commands.
- */
-export interface MachOptions {
-    /** Additional environment variables */
-    env?: Record<string, string>;
-    /** Whether to inherit stdio (show output directly) */
-    inherit?: boolean;
-    /**
-     * Collapse the known mozsystemmonitor teardown traceback to one labeled
-     * line in the terminal echo (capture-only option). The captured
-     * stdout/stderr stay raw, because the harness classifier depends on the raw
-     * traceback. Unrecognized tracebacks always echo verbatim. Opted into by
-     * the test dispatchers only.
-     *
-     * Consumed by {@link runMachCapture} alone. `runMachInheritCapture` accepts
-     * it in the type and ignores it: the inherit path has no per-chunk hook,
-     * only a mirror stream that feeds the terminal and the run log the same
-     * string, so filtering there would strip the traceback from the raw log
-     * too. The build path uses the recognition note instead. See
-     * `mach-known-noise-filter.ts`.
-     */
-    annotateKnownTeardownNoise?: boolean;
-    /**
-     * Environment variables to unset for this dispatch. Threaded to the exec
-     * layer's {@link ExecOptions.envUnset}.
-     */
-    envUnset?: readonly string[];
-    /**
-     * Observes every raw output chunk of a capture dispatch, on either stream,
-     * before the echo filter. The test dispatchers feed the harness helper-pid
-     * tracker from it. Capture-only, like `annotateKnownTeardownNoise`.
-     */
-    onOutputChunk?: (stream: 'stdout' | 'stderr', chunk: string) => void;
-    /** Exec-layer hook, see {@link ProcessGroupOptions.onProcessGroup}. Capture-only. */
-    onProcessGroup?: (pgid: number) => void;
-    /** Exec-layer hook, see {@link ProcessGroupOptions.postCloseSweep}. Capture-only. */
-    postCloseSweep?: () => Promise<void>;
-    /**
-     * Prefix for every echoed and logged line (concurrent `test --jobs`
-     * instances). The capture and `onOutputChunk` stay raw. Capture-only.
-     */
-    outputPrefix?: string | undefined;
-}
-/**
- * Result of running a mach command while capturing streamed output.
- */
-export interface MachCommandResult {
-    stdout: string;
-    stderr: string;
-    exitCode: number;
-}
-/**
- * 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 declare function runMach(args: string[], engineDir: string, options?: MachOptions): Promise<number>;
-/**
- * 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 declare function runMachCapture(args: string[], engineDir: string, options?: Omit<MachOptions, 'inherit'>): Promise<MachCommandResult>;
-/**
- * Runs a mach command while inheriting stdin, streaming output live, and
- * capturing stdout/stderr for post-run diagnostics.
- */
-export declare function runMachInheritCapture(args: string[], engineDir: string, options?: Omit<MachOptions, 'inherit'>): Promise<MachCommandResult>;
-/**
- * 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 declare function bootstrapWithOutput(engineDir: string): Promise<MachCommandResult>;
-/** Which mach build entry a protected dispatch runs. */
-export type ProtectedBuildKind = 'full' | 'faster';
-/** Options for {@link runProtectedMachBuild}. */
-export interface ProtectedMachBuildOptions {
-    /** Parallel jobs for the full build (ignored for `faster`). */
-    jobs?: number | undefined;
-    /** Recognized-crash retry budget (0 disables retries). */
-    retries?: number | undefined;
-    /** Called before each retry with the detected crash signature. */
-    onRetry?: (signature: HarnessCrashSignature, nextAttempt: number, maxAttempts: number) => void;
-}
-/** Captured result of a protected (guarded, retried) mach build dispatch. */
-export interface ProtectedMachBuildResult extends MachCommandResult {
-    /** How many mach processes were spawned (1 = no retry needed). */
-    attempts: number;
-    /** Crash signature of the final failed attempt, when recognized. */
-    crashSignature?: HarnessCrashSignature;
-}
-/**
- * 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 declare function runProtectedMachBuild(kind: ProtectedBuildKind, engineDir: string, options?: ProtectedMachBuildOptions): Promise<ProtectedMachBuildResult>;
-/**
- * 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 declare function build(engineDir: string, jobs?: number): Promise<ProtectedMachBuildResult>;
-/**
- * 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 declare function buildUI(engineDir: string): Promise<ProtectedMachBuildResult>;
-/**
- * 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 declare function withBuildLock<T>(projectRoot: string, operation: () => Promise<T>): Promise<T>;
-/**
- * Runs the built browser.
- * @param engineDir - Path to the engine directory
- * @param args - Additional arguments to pass to the browser
- * @returns Exit code
- */
-export declare function run(engineDir: string, args?: string[]): Promise<number>;
-/**
- * Options for {@link runMachSmoke}.
- */
-export interface RunMachSmokeOptions {
-    env?: Record<string, string>;
-    smokeTimeoutMs: number;
-    killGraceMs?: number;
-    onStdoutLine?: SmokeLineCallback;
-    onStderrLine?: SmokeLineCallback;
-    mirror?: {
-        stdout?: NodeJS.WritableStream;
-        stderr?: NodeJS.WritableStream;
-    };
-}
-/**
- * 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 declare function runMachSmoke(args: string[], engineDir: string, options: RunMachSmokeOptions): Promise<SmokeRunResult>;
-/**
- * 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 declare function machPackageCapture(engineDir: string): Promise<MachCommandResult>;
-/**
- * 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 declare function watchWithOutput(engineDir: string, options?: {
-    env?: Record<string, string>;
-}): Promise<MachCommandResult>;
-/**
- * Which mach test command a capturing test dispatch runs.
- *
- * - `test`: the generic `mach test` (mixed/all-tests runs, or the
- *   `--generic-mach-test` opt-out).
- * - `xpcshell-test` / `mochitest`: the suite-specific commands. Unlike the
- *   generic `mach test`, these degrade a broken mozlog resource monitor to a
- *   warning instead of crashing at startup, so `fireforge test` dispatches
- *   single-suite runs to them to stay resilient to the host psutil failure.
- */
-export type MachTestSuiteKind = 'test' | 'xpcshell-test' | 'mochitest';
-/** Options for {@link runMachTestSuite}. */
-export interface MachTestSuiteOptions {
-    /** Absolute path to the engine checkout. */
-    engineDir: string;
-    /** Test paths to pass to the mach command. Empty runs the default set. */
-    testPaths?: string[];
-    /** Extra mach arguments appended after the paths. */
-    args?: string[];
-    /**
-     * 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.
-     */
-    env?: Record<string, string> | undefined;
-    /**
-     * Pass full mozbuild verbosity through by unsetting the coding-agent
-     * markers that quiet it. See {@link CODING_AGENT_ENV_MARKERS}.
-     */
-    fullOutput?: boolean | undefined;
-    /**
-     * Harness teardown hooks (`fireforge test`): the helper-pid tracker feed,
-     * the process-group announcement, and the post-close reap of the helpers
-     * the harness launched. See {@link MachOptions}.
-     */
-    teardown?: Pick<MachOptions, 'onOutputChunk' | 'onProcessGroup' | 'postCloseSweep'> | undefined;
-    /** Line prefix for echo and run log, see {@link MachOptions.outputPrefix}. */
-    outputPrefix?: string | 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 declare function runMachTestSuite(kind: MachTestSuiteKind, options: MachTestSuiteOptions): Promise<MachCommandResult>;