@nu-art/commando 0.400.14 → 0.401.1

package/shell/core/CommandBuilder.js

@@ -5,9 +5,26 @@ const defaultOptions = {
     newlineDelimiter: '\n',
     indentation: 2,
 };
+/**
+ * Builds shell commands with indentation and formatting support.
+ *
+ * Accumulates commands in an array and formats them with proper indentation.
+ * Supports custom newline delimiters and indentation levels. Commands can
+ * be split across multiple lines using the newline delimiter.
+ *
+ * **Behavior**:
+ * - Commands are trimmed before adding
+ * - Empty commands are preserved (for spacing)
+ * - Indentation is applied per line when commands contain newlines
+ * - `reset()` returns the accumulated command and clears the builder
+ */
 export class CommandBuilder {
-    commands = [];
+    initialCommands = [];
+    /** Array of accumulated command strings */
+    commands;
+    /** Current indentation level (number of indent steps) */
     indentation = 0;
+    /** Configuration options for formatting */
     option = defaultOptions;
     /**
      * Constructs a CommandBuilder instance with given options.
@@ -15,6 +32,7 @@ export class CommandBuilder {
      */
     constructor(options = defaultOptions) {
         this.option = options;
+        this.commands = [...this.initialCommands];
     }
     /**
      * Generates a string of spaces for indentation based on the current indentation level.
@@ -23,6 +41,9 @@ export class CommandBuilder {
     getIndentation = () => {
         return ' '.repeat(this.option.indentation * this.indentation);
     };
+    setMark() {
+        this.initialCommands = [...this.commands];
+    }
     /**
      * Increases the current indentation level by one.
      */
@@ -45,8 +66,15 @@ export class CommandBuilder {
     }
     /**
      * Appends a command to the command list with proper indentation.
-     * @param {string} command - The command to append.
-     * @returns {this} - The CommandBuilder instance for method chaining.
+     *
+     * **Behavior**:
+     * - Splits the command by the newline delimiter (allows multi-line commands)
+     * - Trims each line
+     * - Applies current indentation to non-empty lines
+     * - Preserves empty lines as-is (for spacing)
+     *
+     * @param command - Command string to append (can contain newlines)
+     * @returns This instance for method chaining
      */
     append = (command) => {
         const commands = command.split(this.option.newlineDelimiter);
@@ -73,6 +101,7 @@ export class CommandBuilder {
     reset() {
         const command = this.getCommand();
         this.commands.length = 0;
+        this.commands.push(...this.initialCommands);
         return command;
     }
 }

package/shell/core/CommandoPool.d.ts

@@ -3,7 +3,40 @@ import { CommandoInteractive } from '../interactive/CommandoInteractive.js';
 import { BaseCommando } from './BaseCommando.js';
 import { Commando_Basic } from '../plugins/basic.js';
 import { MergeTypes } from './class-merger.js';
+/**
+ * Pool manager for Commando instances with lifecycle management.
+ *
+ * Tracks all allocated Commando instances and provides a way to kill
+ * all of them at once. Useful for cleanup in long-running processes
+ * or test teardown.
+ *
+ * **Behavior**:
+ * - All allocated commandos are stored in an internal pool
+ * - `allocateCommando()` always includes Commando_Basic plugin
+ * - `killAll()` terminates all tracked commandos asynchronously
+ *
+ * **Use Case**: Managing multiple interactive commandos that need
+ * to be cleaned up together (e.g., test suites, long-running scripts).
+ */
 export declare const CommandoPool: {
+    /**
+     * Allocates a new Commando instance and adds it to the pool.
+     *
+     * Creates a CommandoInteractive instance with the provided plugins
+     * plus Commando_Basic (always included). The instance is tracked
+     * in the pool for later cleanup.
+     *
+     * @template T - Array of plugin constructor types
+     * @param uid - Unique identifier for this commando instance
+     * @param plugins - Plugin classes to merge with the commando
+     * @returns Merged commando instance with all plugins
+     */
     allocateCommando: <T extends Constructor<any>[]>(uid: string, ...plugins: T) => MergeTypes<[...T]> & CommandoInteractive & BaseCommando & Commando_Basic;
+    /**
+     * Kills all allocated commando instances.
+     *
+     * Calls `kill()` on all commandos in the pool asynchronously.
+     * Useful for cleanup in test teardown or application shutdown.
+     */
     killAll: () => Promise<void>;
 };

package/shell/core/CommandoPool.js

@@ -1,13 +1,47 @@
 import { CommandoInteractive } from '../interactive/CommandoInteractive.js';
 import { Commando_Basic } from '../plugins/basic.js';
+/** Internal pool of allocated commando instances */
 const commandoPool = [];
+/**
+ * Pool manager for Commando instances with lifecycle management.
+ *
+ * Tracks all allocated Commando instances and provides a way to kill
+ * all of them at once. Useful for cleanup in long-running processes
+ * or test teardown.
+ *
+ * **Behavior**:
+ * - All allocated commandos are stored in an internal pool
+ * - `allocateCommando()` always includes Commando_Basic plugin
+ * - `killAll()` terminates all tracked commandos asynchronously
+ *
+ * **Use Case**: Managing multiple interactive commandos that need
+ * to be cleaned up together (e.g., test suites, long-running scripts).
+ */
 export const CommandoPool = {
+    /**
+     * Allocates a new Commando instance and adds it to the pool.
+     *
+     * Creates a CommandoInteractive instance with the provided plugins
+     * plus Commando_Basic (always included). The instance is tracked
+     * in the pool for later cleanup.
+     *
+     * @template T - Array of plugin constructor types
+     * @param uid - Unique identifier for this commando instance
+     * @param plugins - Plugin classes to merge with the commando
+     * @returns Merged commando instance with all plugins
+     */
     allocateCommando: (uid, ...plugins) => {
         const commando = CommandoInteractive.create(...plugins, Commando_Basic);
         commando.setUID(uid);
         commandoPool.push(commando);
         return commando;
     },
+    /**
+     * Kills all allocated commando instances.
+     *
+     * Calls `kill()` on all commandos in the pool asynchronously.
+     * Useful for cleanup in test teardown or application shutdown.
+     */
     killAll: async () => {
         await Promise.all(commandoPool.map(c => c.kill()));
     }

package/shell/core/class-merger.d.ts

@@ -1,20 +1,39 @@
 import { Constructor } from '@nu-art/ts-common';
 /**
- * Type utility to recursively merge the types of constructors in an array.
- * @template T - An array of constructors.
+ * Recursively merges the instance types of multiple constructors.
+ *
+ * Creates an intersection type of all constructor instance types.
+ * Used for the plugin system to combine multiple classes into one.
+ *
+ * @template T - Array of constructor types
  */
 export type MergeTypes<T extends Constructor<any>[]> = T extends [a: Constructor<infer A>, ...rest: infer R] ? R extends Constructor<any>[] ? A & MergeTypes<R> : {} : {};
 /**
- * Function to merge multiple classes into a single class.
- * @template T - An array of constructors.
- * @param {...T} plugins - The constructors to merge.
- * @returns {Constructor<MergeTypes<T>>} - A new constructor that merges all the provided constructors.
+ * Merges multiple classes into a single class constructor.
+ *
+ * Creates a new class that combines all properties and methods from
+ * the provided plugin classes. Properties are copied from prototype
+ * descriptors during construction.
+ *
+ * **Use Case**: Plugin system for Commando - allows combining
+ * BaseCommando with plugin classes (e.g., Commando_Git, Commando_NVM).
+ *
+ * **Limitation**: Only copies own properties from prototypes, not
+ * inherited properties or static members.
+ *
+ * @template T - Array of constructor types
+ * @param plugins - Constructor classes to merge
+ * @returns New constructor that merges all plugin classes
  */
 export declare function MergeClass<T extends Constructor<any>[]>(...plugins: T): Constructor<MergeTypes<T>>;
 /**
- * Function to create an instance of a class that merges multiple classes.
- * @template T - An array of constructors.
- * @param {...T} plugins - The constructors to merge.
- * @returns {MergeTypes<T>} - An instance of the merged class.
+ * Creates an instance of a merged class from multiple constructors.
+ *
+ * Convenience function that merges classes and immediately instantiates
+ * the result. Used by BaseCommando._create() to create plugin instances.
+ *
+ * @template T - Array of constructor types
+ * @param plugins - Constructor classes to merge and instantiate
+ * @returns Instance of the merged class
  */
 export declare function CreateMergedInstance<T extends Constructor<any>[]>(...plugins: T): MergeTypes<T>;

package/shell/core/class-merger.js

@@ -1,8 +1,19 @@
 /**
- * Function to merge multiple classes into a single class.
- * @template T - An array of constructors.
- * @param {...T} plugins - The constructors to merge.
- * @returns {Constructor<MergeTypes<T>>} - A new constructor that merges all the provided constructors.
+ * Merges multiple classes into a single class constructor.
+ *
+ * Creates a new class that combines all properties and methods from
+ * the provided plugin classes. Properties are copied from prototype
+ * descriptors during construction.
+ *
+ * **Use Case**: Plugin system for Commando - allows combining
+ * BaseCommando with plugin classes (e.g., Commando_Git, Commando_NVM).
+ *
+ * **Limitation**: Only copies own properties from prototypes, not
+ * inherited properties or static members.
+ *
+ * @template T - Array of constructor types
+ * @param plugins - Constructor classes to merge
+ * @returns New constructor that merges all plugin classes
  */
 export function MergeClass(...plugins) {
     class SuperClass {
@@ -24,10 +35,14 @@ export function MergeClass(...plugins) {
     return SuperClass;
 }
 /**
- * Function to create an instance of a class that merges multiple classes.
- * @template T - An array of constructors.
- * @param {...T} plugins - The constructors to merge.
- * @returns {MergeTypes<T>} - An instance of the merged class.
+ * Creates an instance of a merged class from multiple constructors.
+ *
+ * Convenience function that merges classes and immediately instantiates
+ * the result. Used by BaseCommando._create() to create plugin instances.
+ *
+ * @template T - Array of constructor types
+ * @param plugins - Constructor classes to merge and instantiate
+ * @returns Instance of the merged class
  */
 export function CreateMergedInstance(...plugins) {
     const SuperClass = MergeClass(...plugins);

package/shell/interactive/CommandoInteractive.d.ts

@@ -2,12 +2,37 @@ import { Constructor, LogLevel } from '@nu-art/ts-common';
 import { ShellLogProcessor, ShellPidListener } from './InteractiveShell.js';
 import { LogTypes } from '../types.js';
 import { BaseCommando } from '../core/BaseCommando.js';
+/**
+ * Interactive shell command executor extending BaseCommando.
+ *
+ * Maintains a persistent bash session and executes commands in sequence,
+ * allowing state to persist between commands. Provides advanced features:
+ * - Log processing and filtering
+ * - Exit code extraction
+ * - Background process management
+ * - PID tracking for subprocesses
+ *
+ * **Key Differences from Commando**:
+ * - Uses InteractiveShell (persistent session) vs SimpleShell (one-shot)
+ * - Commands execute in the same shell context (variables persist)
+ * - Supports log processors for reactive command execution
+ * - Can run background processes and track their PIDs
+ *
+ * **Exit Code Extraction**:
+ * Uses a unique key pattern (`echo ${key}=$?`) to extract exit codes
+ * from both stdout and stderr, ensuring accurate exit code detection.
+ */
 export declare class CommandoInteractive extends BaseCommando {
+    /** Interactive shell instance managing the persistent session */
     private shell;
     /**
-     * Creates a new instance of CommandoInteractive merged with the provided plugins.
-     * @param {Constructor<any>[]} plugins - The plugins to merge with CommandoInteractive.
-     * @returns {CommandoInteractive} - The new instance of CommandoInteractive merged with the plugins.
+     * Creates a CommandoInteractive instance with plugins.
+     *
+     * Initializes the InteractiveShell after merging plugins.
+     *
+     * @template T - Array of plugin constructor types
+     * @param plugins - Plugin classes to merge
+     * @returns Merged CommandoInteractive instance with plugins
      */
     static create<T extends Constructor<any>[]>(...plugins: T): import("../core/class-merger.js").MergeTypes<[typeof BaseCommando, typeof CommandoInteractive, ...T]> & BaseCommando & CommandoInteractive;
     /**
@@ -50,9 +75,27 @@ export declare class CommandoInteractive extends BaseCommando {
      */
     onLog(filter: string | RegExp, callback: (match: RegExpMatchArray) => any): this;
     /**
-     * Executes commands and processes logs to extract exit code.
-     * @param {Function} [callback] - A callback function to handle the command output.
-     * @returns {Promise<T>} - The result of the callback function.
+     * Executes accumulated commands and extracts exit code from shell output.
+     *
+     * **Exit Code Extraction Strategy**:
+     * - Appends `echo ${uniqueKey}=$?` to both stdout and stderr
+     * - Uses log processors to detect the unique key pattern
+     * - Waits for both outputs (stdout and stderr) to capture exit code
+     * - Falls back to shell close event if pattern not detected
+     *
+     * **Log Processing**:
+     * - Adds temporary log processors to capture stdout/stderr
+     * - Accumulates all output until exit code is detected
+     * - Removes processors after execution (in finally block)
+     *
+     * **Behavior**:
+     * - Resolves when exit code is detected or shell closes
+     * - Calls callback with accumulated stdout, stderr, and exit code
+     * - Always cleans up log processors (even on error)
+     *
+     * @template T - Return type of callback
+     * @param callback - Function to process command output
+     * @returns Promise resolving to callback result
      */
     execute<T>(callback?: (stdout: string, stderr: string, exitCode: number) => T): Promise<T>;
     /**
@@ -75,6 +118,23 @@ export declare class CommandoInteractive extends BaseCommando {
      * @returns {this} - The CommandoInteractive instance for method chaining.
      */
     append(command: string): this;
+    mark(): this;
+    /**
+     * Appends a command to run in the background and tracks its PID.
+     *
+     * **Behavior**:
+     * - Runs command with `&` (background)
+     * - Captures PID using `pid=$!` and echoes it with unique key
+     * - Waits for the process to complete
+     * - Calls pidListener when PID is detected
+     *
+     * **Use Case**: Running long-running processes while continuing
+     * to execute other commands in the same shell session.
+     *
+     * @param command - Command to run in background
+     * @param pidListener - Optional callback when PID is detected
+     * @returns This instance for method chaining
+     */
     appendAsync(command: string, pidListener?: ShellPidListener): this;
     getCommand(): string;
 }

package/shell/interactive/CommandoInteractive.js

@@ -1,12 +1,37 @@
 import { generateHex } from '@nu-art/ts-common';
 import { InteractiveShell } from './InteractiveShell.js';
 import { BaseCommando } from '../core/BaseCommando.js';
+/**
+ * Interactive shell command executor extending BaseCommando.
+ *
+ * Maintains a persistent bash session and executes commands in sequence,
+ * allowing state to persist between commands. Provides advanced features:
+ * - Log processing and filtering
+ * - Exit code extraction
+ * - Background process management
+ * - PID tracking for subprocesses
+ *
+ * **Key Differences from Commando**:
+ * - Uses InteractiveShell (persistent session) vs SimpleShell (one-shot)
+ * - Commands execute in the same shell context (variables persist)
+ * - Supports log processors for reactive command execution
+ * - Can run background processes and track their PIDs
+ *
+ * **Exit Code Extraction**:
+ * Uses a unique key pattern (`echo ${key}=$?`) to extract exit codes
+ * from both stdout and stderr, ensuring accurate exit code detection.
+ */
 export class CommandoInteractive extends BaseCommando {
+    /** Interactive shell instance managing the persistent session */
     shell;
     /**
-     * Creates a new instance of CommandoInteractive merged with the provided plugins.
-     * @param {Constructor<any>[]} plugins - The plugins to merge with CommandoInteractive.
-     * @returns {CommandoInteractive} - The new instance of CommandoInteractive merged with the plugins.
+     * Creates a CommandoInteractive instance with plugins.
+     *
+     * Initializes the InteractiveShell after merging plugins.
+     *
+     * @template T - Array of plugin constructor types
+     * @param plugins - Plugin classes to merge
+     * @returns Merged CommandoInteractive instance with plugins
      */
     static create(...plugins) {
         const _commando = BaseCommando._create(CommandoInteractive, ...plugins);
@@ -80,9 +105,27 @@ export class CommandoInteractive extends BaseCommando {
         return this;
     }
     /**
-     * Executes commands and processes logs to extract exit code.
-     * @param {Function} [callback] - A callback function to handle the command output.
-     * @returns {Promise<T>} - The result of the callback function.
+     * Executes accumulated commands and extracts exit code from shell output.
+     *
+     * **Exit Code Extraction Strategy**:
+     * - Appends `echo ${uniqueKey}=$?` to both stdout and stderr
+     * - Uses log processors to detect the unique key pattern
+     * - Waits for both outputs (stdout and stderr) to capture exit code
+     * - Falls back to shell close event if pattern not detected
+     *
+     * **Log Processing**:
+     * - Adds temporary log processors to capture stdout/stderr
+     * - Accumulates all output until exit code is detected
+     * - Removes processors after execution (in finally block)
+     *
+     * **Behavior**:
+     * - Resolves when exit code is detected or shell closes
+     * - Calls callback with accumulated stdout, stderr, and exit code
+     * - Always cleans up log processors (even on error)
+     *
+     * @template T - Return type of callback
+     * @param callback - Function to process command output
+     * @returns Promise resolving to callback result
      */
     async execute(callback) {
         let logProcessor;
@@ -171,6 +214,26 @@ export class CommandoInteractive extends BaseCommando {
         this.builder.append(command);
         return this;
     }
+    mark() {
+        this.builder.setMark();
+        return this;
+    }
+    /**
+     * Appends a command to run in the background and tracks its PID.
+     *
+     * **Behavior**:
+     * - Runs command with `&` (background)
+     * - Captures PID using `pid=$!` and echoes it with unique key
+     * - Waits for the process to complete
+     * - Calls pidListener when PID is detected
+     *
+     * **Use Case**: Running long-running processes while continuing
+     * to execute other commands in the same shell session.
+     *
+     * @param command - Command to run in background
+     * @param pidListener - Optional callback when PID is detected
+     * @returns This instance for method chaining
+     */
     appendAsync(command, pidListener) {
         const pidUniqueKey = generateHex(16);
         const regexp = new RegExp(`${pidUniqueKey}=(\\d+)`);

package/shell/interactive/InteractiveShell.d.ts

@@ -1,8 +1,46 @@
 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;

package/shell/interactive/InteractiveShell.js

@@ -1,6 +1,31 @@
 import { addItemToArrayAtIndex, currentTimeMillis, generateHex, Logger, LogLevel, removeItemFromArray } from '@nu-art/ts-common';
 import { spawn } from 'node:child_process';
+/**
+ * Default log level filter: Error for stderr, Info for stdout.
+ */
 const defaultLogLevelFilter = (log, std) => std === 'err' ? LogLevel.Error : LogLevel.Info;
+/**
+ * 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 class InteractiveShell extends Logger {
     _debug = false;
     logProcessors = [];

package/shell/plugins/basic.d.ts

@@ -15,16 +15,43 @@ type Cli_CpdirOptions = {
     contentOnly?: boolean;
 };
 /**
- * Represents a Command Line Interface (CLI) to build and execute shell commands.
+ * 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 a block of commands in that directory.
-     * @param {string} folderName - Name of the directory to change to.
-     * @param {CliBlock} [toRun] - Optional block of commands to execute in the directory.
-     * @returns {this} - The Cli instance for method chaining.
+     * 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.
@@ -37,11 +64,62 @@ export declare class Commando_Basic extends BaseCommando {
      * @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.
@@ -49,10 +127,13 @@ export declare class Commando_Basic extends BaseCommando {
      */
     pwd(): this;
     /**
-     * Assigns a value to a variable in the script.
-     * @param {string} varName - The name of the variable.
-     * @param {string | string[]} value - The value to assign to the variable.
-     * @returns {this} - The Cli instance for method chaining.
+     * 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;
 }