@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -11,17 +11,22 @@ export interface ExecResult {
     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
+     * 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 — a truncated listing looks exactly like
-     * a complete one otherwise.
+     * 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 command execution.
+ * 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 */
@@ -29,40 +34,54 @@ export interface ExecOptions {
     /** Environment variables */
     env?: Record<string, string>;
     /**
-     * Environment variables to REMOVE from the child's inherited environment,
+     * 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 for their PRESENCE — mozbuild's `is_running_under_coding_agent()`
+     * 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
+     * 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.
+     * 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;
     };
-    /** Timeout in milliseconds */
-    timeout?: number;
+}
+/**
+ * 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
+     * (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 — non-mach consumers are unaffected.
+     * (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
+     * 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;
@@ -78,11 +97,11 @@ export declare function exec(command: string, args: string[], options?: ExecOpti
 /**
  * Callback for streaming output.
  */
-export type StreamCallback = (data: string) => void;
+type StreamCallback = (data: string) => void;
 /**
  * Options for streaming command execution.
  */
-export interface StreamOptions extends ExecOptions {
+interface StreamOptions extends ExecOptions, ProcessGroupOptions {
     /** Callback for stdout data */
     onStdout?: StreamCallback;
     /** Callback for stderr data */
@@ -102,7 +121,7 @@ export declare function execStream(command: string, args: string[], options?: St
  * 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
+ * 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.
@@ -111,7 +130,7 @@ export declare function execStream(command: string, args: string[], options?: St
  * Registers a child whose shutdown {@link waitForActiveChildShutdown} must
  * wait for, and returns the handle that deregisters it.
  *
- * @returns `settle()` — call from both the child's `close` and `error`
+ * @returns `settle()`. Call from both the child's `close` and `error`
  *   handlers so a dead child never holds the shutdown wait open
  */
 export declare function trackChildClosure(): {
@@ -124,13 +143,21 @@ export declare function trackChildClosure(): {
  * 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
+ * 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.
@@ -140,14 +167,12 @@ export declare function waitForActiveChildShutdown(timeoutMs: number): Promise<v
  * @param options - Execution options
  * @returns Exit code of the process
  */
-export declare function execInherit(command: string, args: string[], options?: ExecOptions & {
-    shutdownGraceMs?: number;
-}): Promise<number>;
+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; 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
+ * (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.
  */
@@ -162,36 +187,34 @@ export declare function installGracefulShutdownForwarder(child: ReturnType<typeo
  * @param options - Execution options
  * @returns Execution result with stdout, stderr, and exit code
  */
-export declare function execInheritCapture(command: string, args: string[], options?: ExecOptions & {
-    shutdownGraceMs?: number;
-}): Promise<ExecResult>;
+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}.
  *
- * Deliberately omits `ExecOptions.timeout`: the smoke run's only deadline is
+ * Omits `ExecOptions.timeout`: the smoke run's only deadline is
  * {@link SmokeRunOptions.smokeTimeoutMs}, which signals the whole process
- * group. Inheriting `timeout` is a leaky trap — accepted by the type but
- * silently ignored, so a caller setting it gets no deadline at all.
+ * 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.
  *
- * `processGroup` is omitted 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.
+ * {@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.
  */
-export interface SmokeRunOptions extends Omit<ExecOptions, 'processGroup' | 'timeout'> {
+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),
-     * not a failure.
+     * {@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 ~5–10 s to flush in-memory
+     * 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;
@@ -199,25 +222,15 @@ export interface SmokeRunOptions extends Omit<ExecOptions, 'processGroup' | 'tim
     onStdoutLine?: SmokeLineCallback;
     /** Invoked once per complete line of stderr. Final partial line is flushed on close. */
     onStderrLine?: SmokeLineCallback;
-    /**
-     * Optional writable stream to mirror captured output to (e.g. an
-     * operator-supplied `--capture-console` file). Writes happen inline
-     * with line dispatch and the stream is NOT closed here — the caller
-     * owns its lifecycle.
-     */
-    mirror?: {
-        stdout?: NodeJS.WritableStream;
-        stderr?: NodeJS.WritableStream;
-    };
 }
 /** 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
+     * 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.
+     * should not be treated as a child-driven failure.
      */
     timedOut: boolean;
 }
@@ -236,9 +249,10 @@ export interface SmokeRunResult extends ExecResult {
  *
  * 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 — both the deadline
- * and the grace re-invocation are forced kills, so Windows children get
- * no shutdown window (best-effort; Windows is untested, see README).
+ * 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.
  */
@@ -255,3 +269,4 @@ export declare function findExecutable(name: string): Promise<string | undefined
  * @returns True if the executable exists
  */
 export declare function executableExists(name: string): Promise<boolean>;
+export {};