/**
 * @fileoverview Interactive output masking utilities for CLI tools.
 * Provides output control with keyboard toggling (ctrl+o).
 *
 * ANSI Escape Sequences Used:
 * - '\r': Carriage return - moves cursor to beginning of current line.
 * - '\x1b[K' or '\x1b[0K': CSI K (erase line) - clear from cursor to end of line.
 * - '\x1b[2K': CSI 2K - erase entire line.
 * - '\x1b[1A': CSI A - move cursor up 1 line.
 *
 * Terminal Control:
 * - Raw mode (setRawMode(true)): Captures keypresses immediately without buffering.
 * - TTY detection: Ensures terminal manipulation only occurs in interactive terminals.
 *
 * Key Features:
 * - Output buffering: Stores up to 1000 lines when masked to prevent memory issues.
 * - Graceful cleanup: Always restores terminal to normal mode on exit/error.
 * - Visual feedback: Uses spinner to indicate process is running when output is masked.
 */
import type { ChildProcess, SpawnOptions } from 'node:child_process';
import readline from 'node:readline';
export interface OutputMaskOptions {
    /** Current working directory */
    cwd?: string;
    /** Environment variables */
    env?: NodeJS.ProcessEnv;
    /** Progress message to display */
    message?: string;
    /** Show output by default instead of masking it */
    showOutput?: boolean;
    /** Text to show after "ctrl+o" in spinner */
    toggleText?: string;
}
export interface OutputMask {
    /** Whether output is currently visible */
    verbose: boolean;
    /** Buffered output lines */
    outputBuffer: string[];
    /** Whether spinner is currently active */
    isSpinning: boolean;
}
/**
 * Create an output mask for controlling command output visibility.
 * The mask tracks whether output should be shown or hidden (buffered).
 * When hidden, output is buffered and a spinner is shown instead.
 */
export declare function createOutputMask(options?: OutputMaskOptions): OutputMask;
/**
 * Create a keyboard handler for toggling output visibility.
 * Handles two key combinations:
 * - ctrl+o: Toggle between showing and hiding output.
 * - ctrl+c: Cancel the running process.
 * The handler manipulates terminal state using ANSI escape sequences.
 */
export declare function createKeyboardHandler(mask: OutputMask, child: ChildProcess, options?: OutputMaskOptions): (_str: string, key: readline.Key) => void;
/**
 * Attach output masking to a child process.
 * Returns a promise that resolves with the exit code.
 * This function:
 * - Sets up keyboard input handling in raw mode for immediate key capture.
 * - Buffers stdout/stderr when not in verbose mode.
 * - Shows a spinner when output is masked.
 * - Allows toggling between masked and unmasked output with ctrl+o.
 */
export declare function attachOutputMask(child: ChildProcess, options?: OutputMaskOptions): Promise<number>;
/**
 * Run a command with interactive output masking.
 * Convenience wrapper around spawn + attachOutputMask.
 * Spawns a child process and attaches the output masking system to it.
 * stdin is inherited, stdout and stderr are piped for masking control.
 */
export declare function runWithMask(command: string, args?: string[], options?: OutputMaskOptions & SpawnOptions): Promise<number>;
