@nu-art/commando/interactive/InteractiveShell.d.ts

Shell command execution framework with interactive sessions, CLI parameter resolution, and plugin system for building and executing shell scripts programmatically

import { Logger, LogLevel } from '@nu-art/ts-common';
import { LogTypes } from '../types.js';
/**
 * Function that processes log messages from shell output.
 *
 * Returns `false` to consume the log (prevent default logging),
 * `true` to continue processing, or a Promise resolving to boolean.
 *
 * Processors are called in order until one returns `false`.
 */
export type ShellLogProcessor = (log: string, std: LogTypes) => (Promise<boolean> | boolean);
/**
 * Function called when a subprocess PID is detected.
 *
 * Used with `appendAsync()` to notify when a background process starts.
 */
export type ShellPidListener = (pid: number) => (Promise<any> | any);
/**
 * Listener called when the shell process closes.
 */
type OnCloseListener = (exitCode: number) => void;
/**
 * Interactive shell session manager using Node.js child_process spawn.
 *
 * Maintains a persistent bash session and provides:
 * - Command execution in the same shell context
 * - Log processing pipeline (multiple processors)
 * - Subprocess management (PID tracking, killing)
 * - Exit code extraction via echo commands
 *
 * **Key Features**:
 * - Detached process (session leader) for proper signal handling
 * - Log processors can consume or pass through messages
 * - Automatic log level filtering (stderr=Error, stdout=Info)
 * - PID tracking for background processes
 * - Graceful shutdown with timeout
 *
 * **Process Management**:
 * - Spawns `/bin/bash` as detached process
 * - Removes NODE_OPTIONS to prevent debug flags from propagating
 * - Tracks process lifecycle (alive state)
 * - Supports killing main shell or subprocesses independently
 */
export declare class InteractiveShell extends Logger {
    private _debug;
    private logProcessors;
    private onCloseListeners;
    private shell;
    private alive;
    private logLevelFilter;
    /**
     * Constructs an InteractiveShell instance, initializes a detached shell session, and sets up log processors.
     */
    constructor();
    /**
     * Toggles or sets the debug mode.
     * @param {boolean} [debug] - If provided, sets the debug mode to this value. Otherwise, toggles the current debug mode.
     * @returns {boolean} - The current state of debug mode.
     */
    debug(debug?: boolean): this;
    /**
     * Executes a command in the interactive shell.
     * @param {string} command - The command to execute.
     */
    execute: (command: string) => void;
    /**
     * Awaits for the end of the interactive shell session.
     */
    endInteractive: () => Promise<void>;
    isAlive: (pid: number) => boolean;
    waitForExit: (pid: number, timeout?: number, sampleInterval?: number) => Promise<void>;
    kill: (signal?: NodeJS.Signals, timeout?: number) => Promise<void>;
    killSubprocess: (pid: number, signal?: NodeJS.Signals, timeout?: number) => Promise<void>;
    /**
     * Adds a log processor to handle log messages.
     * @param {(log: string, std: LogTypes) => boolean} processor - The log processor function.
     * @param index -
     * @returns {this} - The InteractiveShell instance for method chaining.
     */
    addLogProcessor(processor: ShellLogProcessor, index?: number): this;
    setLogLevelFilter(logLevelFilter: (log: string, std: LogTypes) => LogLevel | undefined): this;
    addOnCloseListener(listener: OnCloseListener): this;
    removeOnCloseListener(listener: OnCloseListener): this;
    /**
     * Removes a log processor from handling log messages.
     * @param {(log: string, std: LogTypes) => boolean} processor - The log processor function to remove.
     * @returns {this} - The InteractiveShell instance for method chaining.
     */
    removeLogProcessor(processor: ShellLogProcessor): this;
    /**
     * Sets a unique identifier for the shell session.
     * @param {string} uid - The unique identifier.
     * @returns {this} - The InteractiveShell instance for method chaining.
     */
    setUID(uid: string): this;
}
export {};