@nu-art/commando/simple/Commando.d.ts

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

import { Constructor } from '@nu-art/ts-common';
import { BaseCommando } from '../core/BaseCommando.js';
/**
 * Simple shell command executor extending BaseCommando.
 *
 * Provides a straightforward way to build and execute shell commands
 * using SimpleShell. Supports file execution and remote file execution.
 *
 * **Features**:
 * - Command building via BaseCommando fluent API
 * - File execution with optional interpreter
 * - Remote file execution via curl
 * - Error handling with CliError
 * - UID tagging for log identification
 *
 * **Error Handling**:
 * - Catches CliError and calls callback with error details
 * - Throws ThisShouldNotHappenException for unexpected errors
 * - Always calls callback (even on error) if provided
 */
export declare class Commando extends BaseCommando {
    /** Optional unique identifier for log tagging */
    private uid?;
    /**
     * Creates a Commando instance with plugins.
     *
     * @template T - Array of plugin constructor types
     * @param plugins - Plugin classes to merge
     * @returns Merged Commando instance with plugins
     */
    static create<T extends Constructor<any>[]>(...plugins: T): (import("../index.js").MergeTypes<[typeof BaseCommando, typeof Commando, ...T]> & BaseCommando) & Commando;
    constructor();
    /**
     * Sets a unique identifier for this commando instance.
     *
     * Used for log tagging to identify which commando instance
     * generated log messages.
     *
     * @param uid - Unique identifier string
     * @returns This instance for method chaining
     */
    setUID(uid: string): this;
    /**
     * Executes a local file with an optional interpreter.
     *
     * If an interpreter is provided, prefixes the file path with it.
     * Otherwise executes the file directly (must be executable).
     *
     * @param filePath - Path to file to execute
     * @param interpreter - Optional interpreter (e.g., 'node', 'python3')
     * @returns Promise resolving to command output
     */
    executeFile(filePath: string, interpreter?: string): Promise<{
        stdout: string;
        stderr: string;
    }>;
    /**
     * Executes a remote file by downloading and piping to interpreter.
     *
     * Uses curl to download the file and pipes it directly to the interpreter.
     * Does not save the file locally.
     *
     * **Security Note**: Executes remote code without verification.
     *
     * @param pathToFile - URL to remote file
     * @param interpreter - Interpreter to execute the file (e.g., 'bash', 'node')
     * @returns Promise resolving to command output
     */
    executeRemoteFile(pathToFile: string, interpreter: string): Promise<{
        stdout: string;
        stderr: string;
    }>;
    /**
     * Executes the accumulated commands and optionally processes output.
     *
     * **Behavior**:
     * - Resets the command builder (gets accumulated command)
     * - Creates a new SimpleShell instance with debug mode
     * - Executes the command
     * - On success: calls callback with stdout, stderr, exitCode=0
     * - On error: catches CliError, calls callback with error details, returns result
     * - On unexpected error: throws ThisShouldNotHappenException
     *
     * **Note**: The callback is always called if provided, even on error.
     * This allows handling errors without try/catch.
     *
     * @template T - Return type of callback
     * @param callback - Optional function to process command output
     * @returns Promise resolving to callback result or void
     */
    execute<T>(callback?: (stdout: string, stderr: string, exitCode: number) => T): Promise<T | void>;
}