/**
 * Process spawning primitives for `@agentuity/cli`.
 *
 * Replaces direct `Bun.spawn(...)` / `Bun.spawnSync(...)` calls. Two
 * shapes cover ~95% of the CLI's needs:
 *
 *   - `run(opts)` — capture-mode. Spawns a command, waits for exit,
 *     returns `{ exitCode, stdout, stderr }`. Use this when the
 *     caller wants the output as strings.
 *
 *   - `spawnInherit(opts)` — passthrough-mode. Spawns a command with
 *     stdio inherited from the parent (so the child draws to the
 *     same TTY), waits for exit, returns `{ exitCode }`. Use this
 *     for interactive subprocesses (`ssh`, `scp`, the user's dev
 *     server, etc.).
 *
 * Why a thin layer:
 *
 * - `Bun.spawn`'s API uses `{ cmd: [...], cwd, env, stdout, stderr,
 *   stdin }` with stdio mode names (`'inherit'`, `'pipe'`, `'ignore'`).
 *   `child_process.spawn` takes `(command, args, options)` with a
 *   single `stdio` triple. Translating is mechanical but verbose.
 * - `Bun.spawn`'s `proc.exited` resolves to the exit code; on Node
 *   we have to wire up the `'exit'` / `'close'` events ourselves.
 * - Capture-mode (`stdout: 'pipe'` then `proc.stdout.text()`) needs
 *   an explicit `streamConsumers.text(...)` on Node.
 *
 * Centralizing all of this keeps callers in plain
 * `await run({ cmd: [...] })` / `await spawnInherit({ cmd: [...] })`
 * shape regardless of runtime.
 */
import { type ChildProcess } from 'node:child_process';
/** Options for `run()` and `spawnInherit()`. */
export interface ProcOptions {
    /** Command and arguments. `cmd[0]` is the executable. */
    cmd: string[];
    /** Working directory. Defaults to the current process cwd. */
    cwd?: string;
    /** Additional / overriding environment variables. Merged onto `process.env`. */
    env?: Record<string, string | undefined>;
    /**
     * Optional input to write to the child's stdin before reading
     * stdout. If provided, stdin is opened in pipe mode regardless of
     * other settings.
     */
    stdin?: string | Buffer | Uint8Array;
    /**
     * Whether to merge `process.env` with `env`. Defaults to `true`.
     * Set to `false` to launch with only the explicit env (rare; use
     * for hermetic invocations).
     */
    inheritEnv?: boolean;
    /**
     * Soft timeout in milliseconds. If exceeded, the child is sent
     * SIGTERM, then SIGKILL after a grace period. The returned
     * `timedOut` flag indicates whether the timeout fired.
     */
    timeoutMs?: number;
}
/** Result of a `run()` call. */
export interface RunResult {
    /** Exit code, or `null` if the process was killed by a signal. */
    exitCode: number | null;
    /** Captured standard output, decoded as UTF-8. */
    stdout: string;
    /** Captured standard error, decoded as UTF-8. */
    stderr: string;
    /** True if the process was killed by `timeoutMs`. */
    timedOut: boolean;
}
/** Result of a `spawnInherit()` call. */
export interface SpawnInheritResult {
    exitCode: number | null;
}
/**
 * Spawn a process, capture its stdout/stderr, and wait for exit.
 *
 * Equivalent to Bun's
 *   `const p = Bun.spawn({ cmd, stdout: 'pipe', stderr: 'pipe' });
 *    const stdout = await new Response(p.stdout).text();
 *    const exitCode = await p.exited;`
 * but factored so each call site stays one line.
 */
export declare function run(opts: ProcOptions): Promise<RunResult>;
/**
 * Spawn a process with stdio inherited from the parent and wait for
 * exit. Use this for interactive subprocesses (ssh, scp, the user's
 * dev server) where the child should draw directly to the user's
 * terminal.
 */
export declare function spawnInherit(opts: ProcOptions): Promise<SpawnInheritResult>;
/**
 * Spawn a process detached, ignoring stdio. Caller does not wait for
 * exit. Returns the underlying `ChildProcess` handle in case the
 * caller wants to track it.
 *
 * Used for "open this URL in the browser" / "open this file in the
 * default app" kinds of operations where we want to fire-and-forget.
 */
export declare function spawnDetached(opts: Omit<ProcOptions, 'stdin' | 'timeoutMs'>): ChildProcess;
/**
 * Spawn a process and expose its stdout/stderr as Web
 * `ReadableStream<Uint8Array>`s for the caller to consume
 * incrementally. Use this when the caller wants to render output
 * progressively (e.g. a TUI spinner that shows the latest stderr
 * line). Returns a promise that resolves to the final exit code
 * once both streams have closed.
 *
 * Note: callers must `await exited` after they finish reading the
 * streams, otherwise the child may stay live indefinitely (the OS
 * pipe stays open).
 */
export declare function spawnStreamingOutput(opts: Omit<ProcOptions, 'stdin' | 'timeoutMs'>): {
    stdout: ReadableStream<Uint8Array>;
    stderr: ReadableStream<Uint8Array>;
    exited: Promise<{
        exitCode: number | null;
    }>;
};
//# sourceMappingURL=proc.d.ts.map