/**
 * @fileoverview Command execution engine with timeout, memory limits, and process management.
 * Provides safe execution of external programs (C++, Python, Java) with resource constraints.
 * Handles process lifecycle, cleanup, and cross-platform compatibility.
 */
/**
 * Result of a command execution containing output and status information.
 *
 * @interface ExecutionResult
 * @property {string} stdout - Standard output from the process
 * @property {string} stderr - Standard error from the process
 * @property {number} exitCode - Process exit code (0 = success)
 * @property {boolean} success - Whether execution was successful
 * @property {boolean} [timedOut] - Whether process exceeded time limit
 * @property {boolean} [memoryExceeded] - Whether process exceeded memory limit
 *
 * @example
 * const result = await executor.execute('./solution', { timeout: 1000 });
 * if (result.success) {
 *   console.log(result.stdout);
 * }
 */
export interface ExecutionResult {
    stdout: string;
    stderr: string;
    exitCode: number;
    success: boolean;
    timedOut?: boolean;
    memoryExceeded?: boolean;
}
/**
 * Options for configuring command execution behavior.
 *
 * @interface ExecutionOptions
 * @property {number} timeout - Maximum execution time in milliseconds
 * @property {number} [memoryLimitMB] - Memory limit in megabytes (optional)
 * @property {string} [cwd] - Working directory for execution (optional)
 * @property {Function} [onSuccess] - Callback on successful execution
 * @property {Function} [onError] - Callback on execution error
 * @property {Function} [onTimeout] - Callback on timeout
 * @property {Function} [onMemoryExceeded] - Callback on memory limit exceeded
 * @property {boolean} [silent] - Suppress console output if true
 *
 * @example
 * const options = {
 *   timeout: 2000,
 *   memoryLimitMB: 256,
 *   onTimeout: (result) => console.log('Process timed out'),
 *   silent: false
 * };
 */
export interface ExecutionOptions {
    timeout: number;
    memoryLimitMB?: number;
    cwd?: string;
    onSuccess?: (result: ExecutionResult) => void;
    onError?: (result: ExecutionResult) => void;
    onTimeout?: (result: ExecutionResult) => void;
    onMemoryExceeded?: (result: ExecutionResult) => void;
    silent?: boolean;
}
/**
 * Command executor for running external programs with resource constraints.
 * Manages process lifecycle, timeout enforcement, memory limits, and cleanup.
 * Supports cross-platform execution (Unix/Windows) with platform-specific optimizations.
 *
 * @class CommandExecutor
 * @example
 * import { executor } from './executor';
 *
 * const result = await executor.execute('./solution', {
 *   timeout: 2000,
 *   memoryLimitMB: 256,
 *   silent: false
 * });
 */
export declare class CommandExecutor {
    private tempFiles;
    private activeProcesses;
    /**
     * Execute a shell command with timeout and memory limits.
     * Automatically kills the process if it exceeds time or memory constraints.
     *
     * @param {string} command - Shell command to execute
     * @param {ExecutionOptions} options - Execution configuration
     * @returns {Promise<ExecutionResult>} Execution result with stdout, stderr, and status
     *
     * @throws {Error} If command fails and no onError callback is provided
     * @throws {Error} If timeout occurs and no onTimeout callback is provided
     * @throws {Error} If memory limit exceeded and no onMemoryExceeded callback is provided
     *
     * @example
     * // Run a C++ solution
     * const result = await executor.execute('./solution', {
     *   timeout: 1000,
     *   memoryLimitMB: 256
     * });
     *
     * @example
     * // With error handling
     * const result = await executor.execute('./buggy_solution', {
     *   timeout: 2000,
     *   onError: (result) => console.log('Solution failed:', result.stderr),
     *   onTimeout: (result) => console.log('TLE')
     * });
     */
    execute(command: string, options: ExecutionOptions): Promise<ExecutionResult>;
    /**
     * Applies memory limit to a command using platform-specific methods.
     * For Java programs, uses -Xmx flag. For Unix, uses ulimit.
     * Windows memory limits are not fully supported.
     *
     * @private
     * @param {string} command - Command to wrap with memory limit
     * @param {number} [memoryLimitMB] - Memory limit in megabytes
     * @returns {string} Command wrapped with memory limit enforcement
     *
     * @example
     * // Java command
     * applyMemoryLimit('java Solution', 256)
     * // Returns: 'java -Xmx256m Solution'
     *
     * @example
     * // C++ command on Unix
     * applyMemoryLimit('./solution', 256)
     * // Returns: '(ulimit -v 262144; ./solution)'
     */
    private applyMemoryLimit;
    /**
     * Spawns a child process for command execution.
     * Creates a detached process in shell mode to allow process tree management.
     * Registers process in active processes set for cleanup tracking.
     *
     * @private
     * @param {string} command - Shell command to spawn
     * @param {ExecutionOptions} options - Execution options including cwd
     * @returns {{process: ChildProcess, result: ExecutionResult}} Spawned process and empty result object
     *
     * @example
     * const { process, result } = this.spawnProcess('./solution', { timeout: 1000 });
     */
    private spawnProcess;
    /**
     * Creates an empty execution result object with default values.
     * Used as initial state before process execution completes.
     *
     * @private
     * @returns {ExecutionResult} Empty result with default values
     *
     * @example
     * const result = this.createEmptyResult();
     * // Returns: { stdout: '', stderr: '', exitCode: 0, success: false, ... }
     */
    private createEmptyResult;
    /**
     * Creates output collectors for stdout and stderr streams.
     * Attaches data event handlers to accumulate process output.
     * Tracks whether the result has been resolved to prevent race conditions.
     *
     * @private
     * @param {ChildProcess} child - Child process to collect output from
     * @returns {{stdout: string, stderr: string, isResolved: boolean}} Output collectors object
     *
     * @example
     * const collectors = this.createOutputCollectors(child);
     * // collectors.stdout and collectors.stderr accumulate as process runs
     */
    private createOutputCollectors;
    /**
     * Creates a cancellable delay promise for timeout implementation.
     * Returns both the timeout promise and a cancel function.
     * Cancel function clears the timeout to prevent unnecessary process kills.
     *
     * @private
     * @param {number} ms - Delay duration in milliseconds
     * @returns {[Promise<void>, () => void]} Tuple of [timeout promise, cancel function]
     *
     * @example
     * const [timeoutPromise, cancelTimeout] = this.cancellableDelay(1000);
     * timeoutPromise.then(() => console.log('Timed out'));
     * // Later, if process finishes early:
     * cancelTimeout();
     */
    private cancellableDelay;
    /**
     * Handles timeout scenario when process exceeds time limit.
     * Kills the process tree, updates result with timeout status, and invokes callbacks.
     * Uses SIGKILL after grace period to ensure process termination.
     *
     * @private
     * @param {ChildProcess} child - Process that timed out
     * @param {ExecutionOptions} options - Execution options with timeout callback
     * @param {ExecutionResult} result - Result object to update
     * @param {{stdout: string, stderr: string, isResolved: boolean}} collectors - Output collectors
     * @param {(value: ExecutionResult) => void} resolve - Promise resolve function
     * @param {(reason?: unknown) => void} reject - Promise reject function
     *
     * @example
     * // Called internally when timeout occurs
     * this.handleTimeout(child, options, result, collectors, resolve, reject);
     */
    private handleTimeout;
    /**
     * Attaches event handlers for process lifecycle events (close, error).
     * Handles process completion, cleanup, and error scenarios.
     * Ensures timeout is cancelled when process ends naturally.
     *
     * @private
     * @param {ChildProcess} child - Child process to attach handlers to
     * @param {ExecutionOptions} options - Execution options
     * @param {ExecutionResult} result - Result object to populate
     * @param {{stdout: string, stderr: string, isResolved: boolean}} collectors - Output collectors
     * @param {() => void} cancelTimeout - Function to cancel timeout
     * @param {(value: ExecutionResult) => void} resolve - Promise resolve function
     * @param {(reason?: unknown) => void} reject - Promise reject function
     *
     * @example
     * // Called internally during execute()
     * this.attachEventHandlers(child, options, result, collectors, cancelTimeout, resolve, reject);
     */
    private attachEventHandlers;
    /**
     * Handles process close event and determines outcome.
     * Routes to appropriate handler based on exit code and signals.
     * Checks for memory errors, success (code 0), or general errors.
     *
     * @private
     * @param {number | null} code - Process exit code
     * @param {NodeJS.Signals | null} signal - Process termination signal
     * @param {ExecutionOptions} options - Execution options
     * @param {ExecutionResult} result - Result object to populate
     * @param {{stdout: string, stderr: string}} collectors - Output collectors
     * @param {(value: ExecutionResult) => void} resolve - Promise resolve function
     * @param {(reason?: unknown) => void} reject - Promise reject function
     *
     * @example
     * // Called internally by close event handler
     * this.handleProcessClose(0, null, options, result, collectors, resolve, reject);
     */
    private handleProcessClose;
    /**
     * Detects if process failed due to memory issues.
     * Checks both exit codes (137, SIGABRT) and error messages in stderr.
     * Recognizes common memory error patterns across languages.
     *
     * @private
     * @param {number | null} code - Process exit code
     * @param {NodeJS.Signals | null} signal - Process termination signal
     * @param {string} stderr - Standard error output
     * @returns {boolean} True if memory error detected
     *
     * @example
     * // Exit code 137 indicates OOM kill
     * this.isMemoryError(137, null, '') // returns true
     *
     * @example
     * // C++ bad_alloc exception
     * this.isMemoryError(1, null, 'terminate called after throwing bad_alloc') // returns true
     */
    private isMemoryError;
    /**
     * Handles memory limit exceeded scenario.
     * Updates result with MLE status and invokes appropriate callback.
     * Displays warning unless silent mode is enabled.
     *
     * @private
     * @param {number | null} code - Process exit code
     * @param {NodeJS.Signals | null} signal - Process termination signal
     * @param {ExecutionOptions} options - Execution options with MLE callback
     * @param {ExecutionResult} result - Result object to update
     * @param {(value: ExecutionResult) => void} resolve - Promise resolve function
     * @param {(reason?: unknown) => void} reject - Promise reject function
     *
     * @example
     * // Called when OOM detected
     * this.handleMemoryError(137, null, options, result, resolve, reject);
     */
    private handleMemoryError;
    /**
     * Handles successful process execution (exit code 0).
     * Updates result status, displays output unless silent, and invokes success callback.
     *
     * @private
     * @param {ExecutionOptions} options - Execution options with success callback
     * @param {ExecutionResult} result - Result object to update
     * @param {(value: ExecutionResult) => void} resolve - Promise resolve function
     *
     * @example
     * // Called when process exits with code 0
     * this.handleSuccess(options, result, resolve);
     */
    private handleSuccess;
    /**
     * Handles failed process execution (non-zero exit code).
     * Updates result status, displays error unless silent, and invokes error callback or rejects.
     *
     * @private
     * @param {ExecutionOptions} options - Execution options with error callback
     * @param {ExecutionResult} result - Result object to update
     * @param {(value: ExecutionResult) => void} resolve - Promise resolve function
     * @param {(reason?: unknown) => void} reject - Promise reject function
     *
     * @example
     * // Called when process exits with non-zero code
     * this.handleError(options, result, resolve, reject);
     */
    private handleError;
    /**
     * Handles process spawn errors (e.g., command not found, permission denied).
     * Updates result with error information and invokes error callback or rejects.
     *
     * @private
     * @param {Error} err - Error from process spawn
     * @param {ExecutionOptions} options - Execution options with error callback
     * @param {ExecutionResult} result - Result object to update
     * @param {(value: ExecutionResult) => void} resolve - Promise resolve function
     * @param {(reason?: unknown) => void} reject - Promise reject function
     *
     * @example
     * // Called when spawn() throws error
     * this.handleProcessError(new Error('ENOENT'), options, result, resolve, reject);
     */
    private handleProcessError;
    /**
     * Kills a process and its entire child process tree.
     * Uses platform-specific methods: taskkill on Windows, process groups on Unix.
     * Attempts to kill process group first, falls back to single process.
     *
     * @private
     * @param {number} pid - Process ID to kill
     *
     * @example
     * // Kill process tree on Unix
     * this.killProcessTree(12345);
     * // Sends SIGKILL to -12345 (process group)
     *
     * @example
     * // Kill process tree on Windows
     * this.killProcessTree(12345);
     * // Runs: taskkill /pid 12345 /T /F
     */
    private killProcessTree;
    /**
     * Execute a command with input/output file redirection.
     * Wraps the execute method with automatic stdin/stdout redirection.
     *
     * @param {string} command - Shell command to execute
     * @param {ExecutionOptions} options - Execution configuration
     * @param {string} [inputFile] - Path to file for stdin redirection (optional)
     * @param {string} [outputFile] - Path to file for stdout redirection (optional)
     * @returns {Promise<ExecutionResult>} Execution result
     *
     * @example
     * // Run solution with test input and capture output
     * await executor.executeWithRedirect(
     *   './solution',
     *   { timeout: 1000 },
     *   'tests/test1.txt',
     *   'output.txt'
     * );
     */
    executeWithRedirect(command: string, options: ExecutionOptions, inputFile?: string, outputFile?: string): Promise<ExecutionResult>;
    /**
     * Builds a shell command with input/output redirection.
     * Appends stdin (<) and stdout (>) redirections as needed.
     *
     * @private
     * @param {string} command - Base command to execute
     * @param {string} [inputFile] - Optional input file path for stdin
     * @param {string} [outputFile] - Optional output file path for stdout
     * @returns {string} Command with redirection operators
     *
     * @example
     * buildRedirectedCommand('./solution', 'input.txt', 'output.txt')
     * // Returns: './solution < input.txt > output.txt'
     *
     * @example
     * buildRedirectedCommand('./solution', 'input.txt')
     * // Returns: './solution < input.txt'
     */
    private buildRedirectedCommand;
    /**
     * Register a temporary file for tracking.
     * Useful for cleanup operations after execution completes.
     *
     * @param {string} filePath - Path to the temporary file
     *
     * @example
     * executor.registerTempFile('/tmp/test_output.txt');
     */
    registerTempFile(filePath: string): void;
    /**
     * Clean up all active processes and clear temp file registry.
     * Kills any running processes and resets internal state.
     * Should be called when shutting down or after batch operations.
     *
     * @example
     * try {
     *   await runAllTests();
     * } finally {
     *   executor.cleanup();
     * }
     */
    cleanup(): void;
    /**
     * Kills all currently active processes tracked by the executor.
     * Iterates through active processes set and kills each process tree.
     * Used during cleanup or shutdown operations.
     *
     * @private
     *
     * @example
     * // Called by cleanup() method
     * this.killAllActiveProcesses();
     */
    private killAllActiveProcesses;
    /**
     * Get a copy of the registered temporary files list.
     *
     * @returns {string[]} Array of temporary file paths
     *
     * @example
     * const tempFiles = executor.getTempFiles();
     * tempFiles.forEach(file => fs.unlinkSync(file));
     */
    getTempFiles(): string[];
}
/**
 * Singleton instance of CommandExecutor.
 * Import and use this instance throughout the application.
 *
 * @constant
 * @type {CommandExecutor}
 * @example
 * import { executor } from './executor';
 *
 * const result = await executor.execute('./solution', {
 *   timeout: 2000,
 *   memoryLimitMB: 256
 * });
 */
export declare const executor: CommandExecutor;
//# sourceMappingURL=executor.d.ts.map