projen/lib/util/exec.d.ts

CDK for software projects

export declare const MAX_BUFFER: number;
/**
 * 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;