@nu-art/commando 0.401.0 → 0.401.2

package/{shell/interactive → interactive}/CommandoInteractive.d.ts

@@ -2,14 +2,39 @@ 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;
+    static create<T extends Constructor<any>[]>(...plugins: T): import("../index.js").MergeTypes<[typeof BaseCommando, typeof CommandoInteractive, ...T]> & BaseCommando & CommandoInteractive;
     /**
      * Constructs a CommandoInteractive instance.
      */
@@ -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 → 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 → 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 → 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/package.json

@@ -1,24 +1,33 @@
 {
   "name": "@nu-art/commando",
-  "version": "0.401.0",
-  "description": "",
+  "version": "0.401.2",
+  "description": "Shell command execution framework with interactive sessions, CLI parameter resolution, and plugin system for building and executing shell scripts programmatically",
   "type": "module",
   "keywords": [
-    "TacB0sS",
-    "infra",
+    "shell",
+    "command-execution",
+    "cli",
+    "bash",
+    "interactive-shell",
+    "shell-scripts",
+    "cli-params",
+    "command-line",
     "nu-art",
-    "commando"
+    "thunderstorm",
+    "commando",
+    "typescript"
   ],
   "homepage": "https://github.com/nu-art-js/thunderstorm",
   "bugs": {
-    "url": "https://github.com/nu-art-js/thunderstorm/issues"
-  },
-  "publishConfig": {
-    "directory": "dist"
+    "url": "https://github.com/nu-art-js/thunderstorm/issues?q=is%3Aissue+label%3Acommando"
   },
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com:nu-art-js/thunderstorm.git"
+    "url": "git+ssh://git@github.com:nu-art-js/thunderstorm.git",
+    "directory": "_thunderstorm/commando"
+  },
+  "publishConfig": {
+    "directory": "dist"
   },
   "license": "Apache-2.0",
   "author": "TacB0sS",
@@ -29,7 +38,11 @@
     "build": "tsc"
   },
   "dependencies": {
-    "@nu-art/ts-common": "0.401.0"
+    "@nu-art/cli-params": "0.401.2",
+    "@nu-art/ts-common": "0.401.2"
+  },
+  "devDependencies": {
+    "@nu-art/testalot": "0.401.2"
   },
   "unitConfig": {
     "type": "typescript-lib"
@@ -38,10 +51,6 @@
     ".": {
       "types": "./index.d.ts",
       "import": "./index.js"
-    },
-    "./*": {
-      "types": "./*.d.ts",
-      "import": "./*.js"
     }
   }
 }

package/plugins/basic.d.ts

@@ -0,0 +1,140 @@
+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 {};

package/plugins/basic.js

@@ -0,0 +1,179 @@
+import { BaseCommando } from '../core/BaseCommando.js';
+/**
+ * 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 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, toRun) {
+        this.append(`cd ${folderName}`);
+        this.indentIn();
+        if (toRun) {
+            toRun(this);
+            this.cd_();
+        }
+        return 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) {
+        this.append(command);
+        return this;
+    }
+    /**
+     * Changes directory back to the previous directory.
+     * @returns {this} - The Cli instance for method chaining.
+     */
+    cd_() {
+        this.indentOut();
+        this.append(`cd -`);
+        return 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 = '') {
+        this.append(`ls ${params}`);
+        return 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) {
+        this.append(`mkdir -p ${dirName}`);
+        return this;
+    }
+    /**
+     * Removes a file or directory.
+     *
+     * @param dirPath - Path to remove
+     * @param options - Optional force flag
+     * @returns This instance for method chaining
+     */
+    rm(dirPath, options) {
+        let command = 'rm';
+        if (options?.force)
+            command += ' -f';
+        this.append(`${command} ${dirPath}`);
+        return this;
+    }
+    /**
+     * Removes a directory recursively.
+     *
+     * @param dirPath - Directory path to remove
+     * @param options - Optional force flag
+     * @returns This instance for method chaining
+     */
+    rmdir(dirPath, options) {
+        let command = 'rm -r';
+        if (options?.force)
+            command += ' -f';
+        this.append(`${command} ${dirPath}`);
+        return 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, destPath, options) {
+        let command = `cp -r ${srcPath}`;
+        if (options?.contentOnly)
+            command += '/*';
+        command += ` ${destPath}`;
+        this.append(command);
+        return this;
+    }
+    /**
+     * Displays file contents.
+     *
+     * @param fileName - File path to display
+     * @returns This instance for method chaining
+     */
+    cat(fileName) {
+        this.append(`cat ${fileName}`);
+        return 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, options) {
+        const _escape = options?.escape ? '-e' : '';
+        const _toFile = options?.toFile ? `>${options.toFile.append ? '>' : ''} ${options.toFile.name}` : '';
+        const escapedLog = log.replace(/\\/g, '\\\\').replace(/\n/g, '\\\\n').replace(/\t/g, '\\\t');
+        this.append(`echo ${_escape} "${escapedLog}" ${_toFile}`);
+        return this;
+    }
+    /**
+     * Appends a 'pwd' command to print the current directory.
+     * @returns {this} - The Cli instance for method chaining.
+     */
+    pwd() {
+        this.append('pwd');
+        return 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, value) {
+        this.append(`${varName}=(${Array.isArray(value) ? value : [value].join(' ')})`);
+        return this;
+    }
+}