/**
 * @license
 * Copyright 2025 Vybestack LLC
 * SPDX-License-Identifier: Apache-2.0
 */
/**
 * Utilities for safely managing stdin raw mode with proper error handling.
 *
 * Issue #1020: After 28+ minutes, macOS terminals can experience transient I/O
 * errors on stdin when raw mode is enabled. Without error handlers, these crash
 * the entire process.
 *
 * This module provides helpers to:
 * 1. Enable raw mode with error handlers installed
 * 2. Disable raw mode with proper cleanup
 * 3. Handle EIO errors gracefully without crashing
 */
export interface StdinSafetyOptions {
    /** Enable debug logging of I/O errors */
    debug?: boolean;
    /** Custom error handler (optional) */
    onError?: (err: Error) => void;
}
/**
 * Error handler function that catches I/O errors on stdin and prevents crashes
 */
export type StdinErrorHandler = (err: Error) => void;
/**
 * Manages raw mode lifecycle with automatic error handling
 */
export declare class StdinRawModeManager {
    private options?;
    private errorHandler;
    private isEnabled;
    private wasRawBeforeEnable;
    private debugModeEnabled;
    constructor(options?: StdinSafetyOptions | undefined);
    /**
     * Create an error handler for stdin I/O errors
     */
    private createErrorHandler;
    /**
     * Enable raw mode with error handling
     *
     * @returns true if raw mode was enabled, false if it was already in raw mode
     */
    enable(): boolean;
    /**
     * Disable raw mode and clean up error handler
     *
     * @param restorePreviousState If true, restore stdin to the state it was in before enable() was called
     *                              If false, force disable raw mode
     */
    disable(restorePreviousState?: boolean): void;
    /**
     * Check if stdin already has our error handler installed
     */
    private hasErrorHandler;
    /**
     * Check if raw mode is currently managed by this instance
     */
    getManaged(): boolean;
    /**
     * Get the error handler function (useful for manual cleanup or testing)
     */
    getErrorHandler(): StdinErrorHandler;
}
/**
 * Legacy helper function for backward compatibility
 * Installs a global stdin error handler without managing raw mode
 *
 * @deprecated Use StdinRawModeManager instead for better lifecycle management
 *
 * @param options - Error handling options (only used on first call)
 * @returns The error handler function (for removal later)
 */
export declare function installStdinErrorHandler(options?: StdinSafetyOptions): StdinErrorHandler;
/**
 * Reset the global stdin error handler (for testing only)
 * @internal
 */
export declare function _resetGlobalStdinErrorHandler(): void;
/**
 * Helper to safely enable raw mode with error handling
 * Returns a cleanup function that should be called to restore the original state
 *
 * Note: If stdin is not a TTY or raw mode cannot be enabled, the wrapped
 * function still executes but no raw mode changes are made.
 *
 * @param options - Error handling options
 * @returns Cleanup function that restores stdin to its previous state
 */
export declare function withSafeRawMode<T>(fn: () => T | Promise<T>, options?: StdinSafetyOptions): () => T | Promise<T>;
