import type { ChildProcessByStdio, SpawnOptions as NodeSpawnOptions } from "node:child_process";
import { Readable, Writable } from "node:stream";
import type { WriteStream } from "node:tty";
import { styleText } from "node:util";
import { Path } from "path-class";
import type { NodeWithCwd, spawnType, WithExitPromises } from "./spawn";
import { type TrailingNewlineOptions } from "./trimTrailingNewlines";
type StyleTextFormat = Parameters<typeof styleText>[0];
type SingleArgument = string | Path;
type ArgsEntry = SingleArgument | SingleArgument[];
type Args = ArgsEntry[];
declare const ARGUMENT_LINE_WRAPPING_VALUES: readonly ["by-entry", "nested-by-entry", "by-argument", "inline"];
type ArgumentLineWrapping = (typeof ARGUMENT_LINE_WRAPPING_VALUES)[number];
export interface PrintOptions {
    /** Defaults to "" */
    mainIndentation?: string;
    /** Defaults to "  " */
    argIndentation?: string;
    /**
     * - `"auto"`: Quote only arguments that need it for safety. This tries to be
     *   portable and safe across shells, but true safety and portability is hard
     *   to guarantee.
     * - `"extra-safe"`: Quote all arguments, even ones that don't need it. This is
     *   more likely to be safe under all circumstances.
     */
    quoting?: "auto" | "extra-safe";
    /** Line wrapping to use between arguments. Defaults to `"by-entry"`. */
    argumentLineWrapping?: ArgumentLineWrapping;
    /** Include the first arg (or first arg group) on the same line as the command, regardless of the `argumentLineWrapping` setting. */
    skipLineWrapBeforeFirstArg?: true | false;
    /**
     * Style text using `node`'s {@link styleText | `styleText(…)`}.
     *
     * Example usage:
     *
     * ```
     * new PrintableShellCommand("echo", ["hi"]).print({
     *   style: ["green", "underline"],
     * });
     * */
    style?: StyleTextFormat;
}
export interface StreamPrintOptions extends PrintOptions {
    /**
     * Auto-style the text when:
     *
     * - the output stream is detected to be a TTY
     * - `styleTextFormat` is not specified.
     *
     * The current auto style is: `["gray", "bold"]`
     */
    autoStyle?: "tty" | "never";
    stream?: WriteStream | Writable;
}
export type StdinSource = {
    text: string;
} | {
    json: any;
} | {
    path: string | Path;
} | {
    stream: Readable | ReadableStream;
};
interface AllowFailureOptions {
    allowFailure?: boolean;
}
export declare class PrintableShellCommand {
    #private;
    private args;
    constructor(commandName: string | Path, args?: Args);
    get commandName(): string;
    /**
     * For use with `node:child_process`
     *
     * Usage example:
     *
     * ```
     * import { PrintableShellCommand } from "printable-shell-command";
     * import { spawn } from "node:child_process";
     *
     * const command = new PrintableShellCommand( … );
     * const child_process = spawn(...command.toCommandWithFlatArgs()); // Note the `...`
     * ```
     *
     */
    toCommandWithFlatArgs(): [string, string[]];
    getPrintableCommand(options?: PrintOptions): string;
    /**
     * Print the shell command to {@link stderr} (default) or a specified stream.
     *
     * By default, this will be auto-styled (as bold gray) when `.isTTY` is true
     * for the stream. `.isTTY` is populated for the {@link stderr} and
     * {@link stdout} objects. Pass `"autoStyle": "never"` or an explicit
     * `style` to disable this.
     *
     */
    print(options?: StreamPrintOptions): PrintableShellCommand;
    /**
     * Send data to `stdin` of the subprocess.
     *
     * Note that this will overwrite:
     *
     * - Any previous value set using {@link PrintableShellCommand.stdin | `.stdin(…)`}.
     * - Any value set for `stdin` using the `"stdio"` field of {@link PrintableShellCommand.spawn | `.spawn(…)`}.
     */
    stdin(source: StdinSource): PrintableShellCommand;
    /**
     * The returned child process includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313
     */
    spawn: typeof spawnType;
    /** A wrapper for `.spawn(…)` that sets stdio to `"inherit"` (common for
     * invoking commands from scripts whose output and interaction should be
     * surfaced to the user).
     *
     * If there is no other interaction with the shell from the calling process,
     * then it acts "transparent" and allows user to interact with the subprocess
     * in its stead.
     */
    spawnPassthrough(options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">>): ChildProcessByStdio<null, null, null> & WithExitPromises;
    /** @deprecated Use `.spawnPassthrough(…)` instead. */
    spawnTransparently: (...args: Parameters<PrintableShellCommand["spawnPassthrough"]>) => ReturnType<PrintableShellCommand["spawnPassthrough"]>;
    /**
     * A wrapper for {@link PrintableShellCommand.spawn | `.spawn(…)`} that:
     *
     * - sets `detached` to `true`,
     * - sets stdio to `"inherit"`,
     * - calls `.unref()`, and
     * - does not wait for the process to exit.
     *
     * This is similar to starting a command in the background and disowning it (in a shell).
     *
     */
    spawnDetached(options?: NodeWithCwd<Omit<Omit<NodeSpawnOptions, "stdio">, "detached">>): void;
    stdout(options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">> & AllowFailureOptions): Response & {
        text: (options?: TrailingNewlineOptions) => Promise<string>;
    };
    stderr(options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">> & AllowFailureOptions): Response & {
        text: (options?: TrailingNewlineOptions) => Promise<string>;
    };
    /**
     * Convenience function for:
     *
     *     .stdout(options).text()
     *
     * This can make some simple invocations easier to read and/or fit on a single line.
     */
    text(options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">> & TrailingNewlineOptions & AllowFailureOptions): Promise<string>;
    /**
     * Convenience function for:
     *
     *     .stdout(options).json()
     *
     * This can make some simple invocations easier to read and/or fit on a single line.
     */
    json<T>(options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">> & AllowFailureOptions): Promise<T>;
    /**
     * Parse `stdout` into a generator of string values using a NULL delimiter.
     *
     * A trailing NULL delimiter from `stdout` is required and removed.
     */
    text0(options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">> & AllowFailureOptions): AsyncGenerator<string>;
    /**
     * Parse `stdout` into a generator of JSON values using a NULL delimiter.
     *
     * A trailing NULL delimiter from `stdout` is required and removed.
     */
    json0(options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">> & AllowFailureOptions): AsyncGenerator<any>;
    /** Equivalent to:
     *
     * ```
     * await this.print(…).spawnTransparently(…).success;
     * ```
     */
    shellOut(options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">> & {
        print?: StreamPrintOptions | ArgumentLineWrapping | boolean;
    }): Promise<void>;
}
export declare function escapeArg(arg: string, isMainCommand: boolean, options: PrintOptions): string;
export {};