/**
 * Options for shell-free command execution.
 */
export interface ExecFileOptions {
    /**
     * Working directory for the command.
     */
    readonly cwd: string;
    /**
     * Additional environment variables, merged on top of `process.env`.
     */
    readonly env?: Record<string, string | undefined>;
    /**
     * For `capture`/`tryCapture`: interleave STDERR into the captured output
     * instead of only capturing STDOUT.
     *
     * @default false
     */
    readonly captureStderr?: boolean;
}
/**
 * Options for {@link Tool.run}.
 */
export interface RunOptions extends ExecFileOptions {
    /**
     * Stream the child's stdout and stderr straight to the parent's stdout and
     * stderr (full inheritance), instead of redirecting stdout to stderr and
     * capturing stderr (the default).
     *
     * Use this when launching a child process whose stdout is meaningful and
     * whose output should stream live to the user (e.g. the projen CLI).
     *
     * @default false
     */
    readonly inheritStdio?: boolean;
}
/**
 * A shell-free handle for invoking a single program by name or path.
 *
 * Each argument is passed to the program verbatim (no shell parsing), so there
 * is no quoting to get right for values such as tags, versions, branch names
 * or file paths.
 *
 * Note: the program is executed directly, without a shell. On Windows this
 * means it must be a real executable - `.cmd`/`.bat` shims (such as
 * npm-installed CLIs like npm/npx/yarn/pnpm) cannot be invoked this way.
 */
export interface Tool {
    /**
     * Runs `<tool> <args>`, inheriting stdout. Throws on non-zero exit.
     */
    run(args: string[], options: RunOptions): void;
    /**
     * Runs `<tool> <args>` and returns its trimmed STDOUT. Throws on non-zero exit.
     */
    capture(args: string[], options: ExecFileOptions): string;
    /**
     * Runs `<tool> <args>` and returns its trimmed STDOUT, or `undefined` if the
     * command failed or produced no output.
     */
    tryCapture(args: string[], options: ExecFileOptions): string | undefined;
}
/**
 * Creates a shell-free {@link Tool} for the given program.
 *
 * @example const git = tool("git"); git.run(["tag", "--delete", tag], { cwd });
 */
export declare function tool(file: string): Tool;
/**
 * Shell-free helper for invoking `git`.
 *
 * @example git.run(["tag", "--delete", tag], { cwd });
 */
export declare const git: Tool;
/**
 * Shell-free helper for invoking `uv` (ships as a native binary on all
 * platforms).
 */
export declare const uv: Tool;
/**
 * Shell-free helper for invoking `poetry`.
 */
export declare const poetry: Tool;
/**
 * Shell-free helper for invoking the current Node.js executable
 * (`process.execPath`).
 */
export declare const node: Tool;
/**
 * Async, dax-backed equivalent of {@link Tool} for programs that may be a
 * Windows `.cmd`/`.bat` shim (e.g. `npx`, `npm`).
 */
export interface AsyncTool {
    /**
     * Runs `<tool> <args>`, inheriting stdout. Rejects on non-zero exit.
     */
    run(args: string[], options: ExecFileOptions): Promise<void>;
    /**
     * Runs `<tool> <args>` and resolves its trimmed STDOUT. Rejects on non-zero
     * exit.
     */
    capture(args: string[], options: ExecFileOptions): Promise<string>;
}
/**
 * Cross-platform helper for `npm` (a Windows `.cmd` shim).
 */
export declare const npm: AsyncTool;
/**
 * Cross-platform helper for `npx` (a Windows `.cmd` shim).
 */
export declare const npx: AsyncTool;
export declare const rawShell: {
    /**
     * Runs a user-supplied shell command line and resolves its trimmed
     * STDOUT. Rejects if the command exits non-zero.
     */
    capture: (command: string, options: {
        cwd: string;
        env?: Record<string, string>;
    }) => Promise<string>;
    /**
     * Runs a user-supplied shell command line and resolves its trimmed
     * STDOUT, or `undefined` if the command failed or produced no output.
     */
    tryCapture: (command: string, options: {
        cwd: string;
        env?: Record<string, string>;
    }) => Promise<string | undefined>;
};
/**
 * Normalized result of running a command through the system shell (a subset of
 * node's `SpawnSyncReturns`).
 */
export interface SystemShellResult {
    /** Exit code, or `null` if terminated by a signal or never spawned. */
    readonly status: number | null;
    /** Captured stdout, or `null` when stdout was inherited. */
    readonly stdout: Buffer | null;
    /** Captured stderr, or `null` when stderr was inherited. */
    readonly stderr: Buffer | null;
    /** An error raised while attempting to spawn (not a non-zero exit). */
    readonly error?: Error;
}
/**
 * Runs a command line through the operating system's default shell (`/bin/sh`
 * on POSIX, `cmd.exe` on Windows). Never throws for a non-zero exit (that is
 * reported via `status`); a spawn failure is reported via `error`. The caller
 * supplies the full `env`.
 */
export declare function systemShell(command: string, options: {
    cwd: string;
    env?: NodeJS.ProcessEnv;
    capture?: boolean;
}): SystemShellResult;
