@nu-art/commando/plugins/basic.d.ts

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

import { BaseCommando } from '../core/BaseCommando.js';
import { CliBlock } from '../types.js';
type Cli_EchoOptions = {
    escape?: boolean;
    toFile?: {
        name: string;
        append?: boolean;
    };
};
type Cli_RmdirOptions = {
    force?: true;
    recursive?: true;
};
type Cli_CpdirOptions = {
    contentOnly?: boolean;
};
/**
 * Basic shell command plugin for Commando.
 *
 * Provides common file system and shell operations:
 * - Directory navigation (`cd`, `pwd`)
 * - File operations (`ls`, `cat`, `mkdir`, `rm`, `rmdir`, `cpdir`)
 * - Variable assignment
 * - Echo with options (escape sequences, file output)
 *
 * **Usage**: Merge with BaseCommando or other Commando classes to add
 * these methods. Typically included via `CommandoPool.allocateCommando()`.
 */
export declare class Commando_Basic extends BaseCommando {
    /**
     * Changes directory and optionally executes commands in that directory.
     *
     * **Behavior**:
     * - Changes to the specified directory
     * - Increases indentation (for script readability)
     * - If `toRun` provided, executes the block and returns to previous directory
     * - If `toRun` not provided, caller must call `cd_()` to return
     *
     * **Note**: Uses `cd -` to return to previous directory (OLDPWD).
     *
     * @param folderName - Directory path to change to
     * @param toRun - Optional command block to execute in the directory
     * @returns This instance for method chaining
     */
    cd(folderName: string, toRun?: CliBlock<this>): this;
    /**
     * Appends a custom command string.
     *
     * Allows adding arbitrary shell commands that aren't covered by
     * the built-in methods.
     *
     * @param command - Custom shell command to append
     * @returns This instance for method chaining
     */
    custom(command: string): this;
    /**
     * Changes directory back to the previous directory.
     * @returns {this} - The Cli instance for method chaining.
     */
    cd_(): this;
    /**
     * Appends an 'ls' command with optional parameters.
     * @param {string} [params] - Optional parameters for the 'ls' command.
     * @returns {this} - The Cli instance for method chaining.
     */
    ls(params?: string): this;
    /**
     * Creates a directory (with parent directories if needed).
     *
     * Uses `mkdir -p` to create directory and all parent directories.
     *
     * @param dirName - Directory path to create
     * @returns This instance for method chaining
     */
    mkdir(dirName: string): this;
    /**
     * Removes a file or directory.
     *
     * @param dirPath - Path to remove
     * @param options - Optional force flag
     * @returns This instance for method chaining
     */
    rm(dirPath: string, options?: Cli_RmdirOptions): this;
    /**
     * Removes a directory recursively.
     *
     * @param dirPath - Directory path to remove
     * @param options - Optional force flag
     * @returns This instance for method chaining
     */
    rmdir(dirPath: string, options?: Cli_RmdirOptions): this;
    /**
     * Copies a directory.
     *
     * @param srcPath - Source directory path
     * @param destPath - Destination directory path
     * @param options - Optional contentOnly flag (copies contents, not directory itself)
     * @returns This instance for method chaining
     */
    cpdir(srcPath: string, destPath: string, options?: Cli_CpdirOptions): this;
    /**
     * Displays file contents.
     *
     * @param fileName - File path to display
     * @returns This instance for method chaining
     */
    cat(fileName: string): this;
    /**
     * Echoes text with optional escape sequences and file output.
     *
     * **Escape Sequences**: When `escape` is true, enables interpretation
     * of backslash escapes (e.g., `\n`, `\t`).
     *
     * **File Output**: Can append or overwrite to a file.
     *
     * **Escaping**: Automatically escapes backslashes, newlines, and tabs
     * in the log string for safe shell execution.
     *
     * @param log - Text to echo
     * @param options - Optional echo configuration
     * @returns This instance for method chaining
     */
    echo(log: string, options?: Cli_EchoOptions): this;
    /**
     * Appends a 'pwd' command to print the current directory.
     * @returns {this} - The Cli instance for method chaining.
     */
    pwd(): this;
    /**
     * Assigns a value to a shell variable (array or scalar).
     *
     * Creates a bash array if value is an array, otherwise creates a scalar variable.
     *
     * @param varName - Variable name
     * @param value - Value(s) to assign (string or array of strings)
     * @returns This instance for method chaining
     */
    assignVar(varName: string, value: string | string[]): this;
}
export {};