@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/utils/process-input.js

@@ -1,46 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Stdin-fed command execution with byte-exact stdout.
- */
-import { spawn } from 'node:child_process';
-import { buildChildEnv } from './child-env.js';
-import { exitCodeFromClose } from './process.js';
-/**
- * Runs a command, writes `input` to its stdin, and returns stdout as raw
- * bytes. For batch protocols (`git cat-file --batch`) whose framing counts
- * bytes: the decoded, 50 MB-capped collector `exec` uses would corrupt
- * both. The caller bounds the input, and so the output.
- * @param command - Command to execute
- * @param args - Command arguments
- * @param input - Bytes written to stdin, which is then closed
- * @param options - Execution options
- */
-export async function execWithInput(command, args, input, options = {}) {
-    return new Promise((resolve, reject) => {
-        const child = spawn(command, args, {
-            cwd: options.cwd,
-            env: buildChildEnv(options),
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-        const out = [];
-        const err = [];
-        child.stdout.on('data', (chunk) => {
-            out.push(chunk);
-        });
-        child.stderr.on('data', (chunk) => {
-            err.push(chunk);
-        });
-        // A child that exits before reading all of stdin (a bad ref, say) makes
-        // the write fail with EPIPE. The close handler reports the real outcome.
-        child.stdin.on('error', () => undefined);
-        child.stdin.end(input);
-        child.on('error', reject);
-        child.on('close', (code, signal) => {
-            resolve({
-                stdout: Buffer.concat(out),
-                stderr: Buffer.concat(err).toString('utf8'),
-                exitCode: exitCodeFromClose(code, signal),
-            });
-        });
-    });
-}

package/dist/src/utils/process.d.ts

@@ -1,293 +0,0 @@
-import { spawn } from 'node:child_process';
-/**
- * Result of executing a command.
- */
-export interface ExecResult {
-    /** Standard output content */
-    stdout: string;
-    /** Standard error content */
-    stderr: string;
-    /** Process exit code */
-    exitCode: number;
-    /**
-     * True when `stdout` was cut off at the 50 MB collector cap. Optional so
-     * existing mocks stay valid. Absent means "not truncated". Callers that
-     * feed the output into safety decisions (e.g. archive-listing scans) must
-     * treat `true` as a hard failure, since a truncated listing otherwise
-     * looks exactly like a complete one.
-     */
-    stdoutTruncated?: boolean;
-    /** True when `stderr` was cut off at the 50 MB collector cap. See {@link ExecResult.stdoutTruncated}. */
-    stderrTruncated?: boolean;
-}
-/**
- * Options for plain `exec()`, the pipe-capturing, non-grouped, non-mirrored
- * path. The other wrappers extend this with the fields they actually read:
- * `processGroup` lives in {@link ProcessGroupOptions}, `mirror` in
- * {@link MirrorOptions}. Neither belongs here because `exec()` reads
- * neither, and a field the type accepts but the function ignores is a trap
- * (the caller believes it got a process group, and never did).
- */
-export interface ExecOptions {
-    /** Working directory for the command */
-    cwd?: string;
-    /** Environment variables */
-    env?: Record<string, string>;
-    /**
-     * Environment variables to remove from the child's inherited environment,
-     * applied after {@link ExecOptions.env} is merged over `process.env`.
-     *
-     * Needed because `env` can only add or overwrite, and some variables are
-     * read only for their presence: mozbuild's `is_running_under_coding_agent()`
-     * keys on `CLAUDECODE`, so setting it empty would not unset it. An
-     * explicit delete says what it means. Relying on Node dropping
-     * `undefined`-valued env entries would be a semantics gamble at a layer
-     * that must not have any.
-     */
-    envUnset?: readonly string[];
-    /** Timeout in milliseconds */
-    timeout?: number;
-}
-/**
- * Output mirroring for the wrappers that capture through a collector
- * ({@link execInheritCapture}, {@link execSmokeRun}).
- */
-export interface MirrorOptions {
-    /**
-     * Streams to mirror the child's output into, replacing the default
-     * `process.stdout` / `process.stderr` on the stdio-inheriting capture
-     * path, or an operator-supplied `--capture-console` file on the smoke
-     * path. Lets a caller tee the live output somewhere else (a run log)
-     * without a second per-chunk hook. Writes happen inline with capture and
-     * the stream is not closed here. The caller owns its lifecycle.
-     */
-    mirror?: {
-        stdout?: NodeJS.WritableStream;
-        stderr?: NodeJS.WritableStream;
-    };
-}
-/**
- * Process-group reaping for the long-lived wrappers ({@link execStream},
- * {@link execInherit}, {@link execInheritCapture}).
- */
-export interface ProcessGroupOptions {
-    /**
-     * POSIX: spawn the child as a process-group leader and route every kill
-     * (parent-signal forwarding, abort, escalation) to the whole group, then
-     * sweep the group for survivors after close, so a harness that dies at
-     * startup cannot strand spinning `multiprocessing` workers, which reparent
-     * to launchd and busy-spin at 100% CPU indefinitely. Win32: tree-kill via
-     * `taskkill /T /F` on abort/signals only, no post-run sweep
-     * (best-effort). Default false, so non-mach consumers are unaffected.
-     *
-     * NOTE for callers: a detached group leader does not receive terminal
-     * Ctrl+C. The exec layer installs its own group-aware signal forwarder
-     * whenever this option is set.
-     */
-    processGroup?: boolean;
-    /**
-     * Receives the process-group id (the detached child's pid) right after a
-     * group-leader spawn. Lets a caller expose the group to a supervisor that
-     * cannot signal FireForge itself gracefully (`fireforge test --pgid-file`),
-     * or hold it for a teardown of its own. Not called when no group was
-     * created (`processGroup` unset, or win32).
-     */
-    onProcessGroup?: (pgid: number) => void;
-    /**
-     * Extra teardown the caller owns, awaited after the child's `close` and
-     * the post-run group sweep, before the child's closure settles. Placed
-     * here rather than after the wrapper resolves so the bin signal handler's
-     * `waitForActiveChildShutdown` covers it too: a reap that ran after the
-     * wrapper resolved would race `process.exit` on a forwarded SIGTERM. Must
-     * never throw; a rejection is swallowed so it cannot mask the child's
-     * result.
-     */
-    postCloseSweep?: () => Promise<void>;
-}
-/** A child's exit code, with a signal death mapped to 128 + its number. */
-export declare function exitCodeFromClose(code: number | null, signal: NodeJS.Signals | null): number;
-/**
- * Executes a command and returns its output.
- * @param command - Command to execute
- * @param args - Command arguments
- * @param options - Execution options
- * @returns Execution result with stdout, stderr, and exit code
- */
-export declare function exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
-/**
- * Callback for streaming output.
- */
-type StreamCallback = (data: string) => void;
-/**
- * Options for streaming command execution.
- */
-interface StreamOptions extends ExecOptions, ProcessGroupOptions {
-    /** Callback for stdout data */
-    onStdout?: StreamCallback;
-    /** Callback for stderr data */
-    onStderr?: StreamCallback;
-}
-/**
- * Executes a command and streams its output.
- * @param command - Command to execute
- * @param args - Command arguments
- * @param options - Execution options
- * @returns Exit code of the process
- */
-export declare function execStream(command: string, args: string[], options?: StreamOptions): Promise<number>;
-/**
- * Registers a child with {@link waitForActiveChildShutdown}.
- *
- * Exported for the one legitimate spawn outside this module:
- * `core/marionette-preflight.ts` keeps its own `spawn` because it needs the
- * live `ChildProcess` mid-run, returns while the child is still running, and
- * aborts on a TCP byte rather than a deadline, none of which any wrapper
- * here can express. It still needs the shutdown contract, and a second
- * hand-rolled copy is what lets a Ctrl+C orphan the whole mach → Firefox
- * tree.
- */
-/**
- * Registers a child whose shutdown {@link waitForActiveChildShutdown} must
- * wait for, and returns the handle that deregisters it.
- *
- * @returns `settle()`. Call after child closure and required teardown finish.
- *   An abort's `error` event does not prove closure; do not settle there.
- *   A failed start may settle when no live child or teardown remains.
- */
-export declare function trackChildClosure(): {
-    settle: () => void;
-};
-/**
- * Waits (bounded) for every tracked child process to close. Called by the
- * bin signal handler after forwarding SIGINT/SIGTERM, so the parent stays
- * alive long enough for the grace-then-SIGKILL escalation to actually run.
- * Resolves immediately when no children are active.
- */
-export declare function waitForActiveChildShutdown(timeoutMs: number): Promise<void>;
-/** Options for {@link execInherit}. */
-export interface InheritOptions extends ExecOptions, ProcessGroupOptions {
-    /** Grace period between the forwarded SIGTERM and the SIGKILL escalation (default 1500 ms). */
-    shutdownGraceMs?: number;
-}
-/** Options for {@link execInheritCapture}: the inherit path plus output mirroring. */
-export interface InheritCaptureOptions extends InheritOptions, MirrorOptions {
-}
-/**
- * Executes a command and inherits stdio (shows output directly).
- *
- * Graceful shutdown: when the FireForge process receives SIGINT/SIGTERM, the
- * signal is forwarded to the child as SIGTERM and a short grace timer (default
- * 1500ms) runs before escalating to SIGKILL. A second matching signal during
- * the grace period triggers an immediate SIGKILL, matching the usual
- * "hit Ctrl-C again to force-quit" UX. Without this, Firefox's AsyncShutdown
- * / profileBeforeChange blockers (which flush in-memory state to disk) can be
- * racing the OS child-exit path, losing the last few seconds of edits.
- *
- * @param command - Command to execute
- * @param args - Command arguments
- * @param options - Execution options
- * @returns Exit code of the process
- */
-export declare function execInherit(command: string, args: string[], options?: InheritOptions): Promise<number>;
-/**
- * Wires parent-process SIGINT/SIGTERM to a child: first signal → child.kill
- * (SIGTERM) + grace timer. A second matching signal → immediate SIGKILL.
- * Grace timer expiry → SIGKILL. Returns a `dispose()` that clears the
- * listeners and any outstanding timer. Callers must invoke `dispose()` from both the child's
- * `close` and `error` handlers so the process does not accumulate signal
- * listeners across repeated spawns.
- */
-export declare function installGracefulShutdownForwarder(child: ReturnType<typeof spawn>, graceMs: number, killTarget?: (signal: NodeJS.Signals) => void): {
-    dispose: () => void;
-};
-/**
- * Executes a command while inheriting stdin, streaming stdout/stderr live,
- * and capturing the emitted output for diagnostics.
- * @param command - Command to execute
- * @param args - Command arguments
- * @param options - Execution options
- * @returns Execution result with stdout, stderr, and exit code
- */
-export declare function execInheritCapture(command: string, args: string[], options?: InheritCaptureOptions): Promise<ExecResult>;
-/** Per-line callback for smoke-run stream dispatch. */
-export type SmokeLineCallback = (line: string) => void;
-/**
- * Options for {@link execSmokeRun}.
- *
- * Omits `ExecOptions.timeout`: the smoke run's only deadline is
- * {@link SmokeRunOptions.smokeTimeoutMs}, which signals the whole process
- * group. Inheriting `timeout` would be a leaky trap, accepted by the type
- * but silently ignored, so a caller setting it gets no deadline at all.
- *
- * {@link ProcessGroupOptions} is not mixed in for the same reason: a smoke
- * run is always detached on POSIX (`usesProcessGroup` is derived from
- * `process.platform` alone), so the field would be accepted and never read.
- */
-interface SmokeRunOptions extends Omit<ExecOptions, 'timeout'>, MirrorOptions {
-    /**
-     * Hard deadline in milliseconds. When it elapses the child process
-     * group is sent SIGTERM and, after `killGraceMs`, SIGKILL. The returned
-     * {@link SmokeRunResult.timedOut} is `true` when the deadline fires.
-     * Callers treat that as a clean smoke window (no child-driven error)
-     * rather than a failure.
-     */
-    smokeTimeoutMs: number;
-    /**
-     * Grace period between SIGTERM and SIGKILL when the deadline fires.
-     * Defaults to 10000 ms because Firefox's AsyncShutdown and
-     * profileBeforeChange blockers can take roughly 5 to 10 s to flush in-memory
-     * state. A shorter grace risks corrupting the dev profile mid-quit.
-     */
-    killGraceMs?: number;
-    /** Invoked once per complete line of stdout. Final partial line is flushed on close. */
-    onStdoutLine?: SmokeLineCallback;
-    /** Invoked once per complete line of stderr. Final partial line is flushed on close. */
-    onStderrLine?: SmokeLineCallback;
-}
-/** Result of {@link execSmokeRun}. */
-export interface SmokeRunResult extends ExecResult {
-    /**
-     * `true` when the smoke deadline fired and we SIGTERMed the child
-     * ourselves. Callers that want to distinguish "smoke window elapsed
-     * cleanly" from "child exited on its own" check this flag: the
-     * `exitCode` in the timedOut path is almost always 143 (SIGTERM) and
-     * should not be treated as a child-driven failure.
-     */
-    timedOut: boolean;
-}
-/**
- * Spawns `command` with `args` in its own process group (POSIX), streams
- * stdout/stderr line-by-line to the caller, enforces a deadline by
- * SIGTERMing the whole group when it elapses, and returns the captured
- * output alongside a `timedOut` flag.
- *
- * Process-group semantics matter here because `mach run` execs a Python
- * wrapper that then forks Firefox, which itself spawns content processes.
- * Sending SIGTERM only to the Python PID leaves an orphan Firefox tree
- * behind. Running the child as a process-group leader (`detached: true`
- * on POSIX) and signalling `-pid` routes the kill to every descendant
- * that inherited the group.
- *
- * Windows fallback: `detached: true` does not create an equivalent group
- * there, so we kill the descendant tree with `taskkill /pid <pid> /T /F`
- * instead. taskkill has no graceful-signal equivalent, so both the deadline
- * and the grace re-invocation are forced kills and Windows children get
- * no shutdown window. This is best-effort and Windows is untested, see
- * README.
- * `child.kill()` is still sent as a direct-child fallback in case
- * taskkill itself is unavailable.
- */
-export declare function execSmokeRun(command: string, args: string[], options: SmokeRunOptions): Promise<SmokeRunResult>;
-/**
- * Finds an executable in the system PATH.
- * @param name - Name of the executable
- * @returns Full path to the executable, or undefined if not found
- */
-export declare function findExecutable(name: string): Promise<string | undefined>;
-/**
- * Checks if an executable exists in the system PATH.
- * @param name - Name of the executable
- * @returns True if the executable exists
- */
-export declare function executableExists(name: string): Promise<boolean>;
-export {};