@nu-art/commando 0.400.14 → 0.401.1

package/shell/simple/Commando.js

@@ -2,8 +2,34 @@ import { ThisShouldNotHappenException } from '@nu-art/ts-common';
 import { SimpleShell } from './SimpleShell.js';
 import { BaseCommando } from '../core/BaseCommando.js';
 import { CliError } from '../core/CliError.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 class Commando extends BaseCommando {
+    /** Optional unique identifier for log tagging */
     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(...plugins) {
         const _commando = BaseCommando._create(Commando, ...plugins);
         return _commando;
@@ -11,10 +37,29 @@ export class Commando extends BaseCommando {
     constructor() {
         super();
     }
+    /**
+     * 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) {
         this.uid = uid;
         return 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, interpreter) {
         let command = filePath;
         // If an interpreter is provided, prefix the command with it.
@@ -23,10 +68,40 @@ export class Commando extends BaseCommando {
         }
         return new SimpleShell().execute(command);
     }
+    /**
+     * 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, interpreter) {
         const command = `curl -o- "${pathToFile}" | ${interpreter}`;
         return new SimpleShell().execute(command);
     }
+    /**
+     * 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
+     */
     async execute(callback) {
         const command = this.builder.reset();
         const simpleShell = new SimpleShell().debug(this._debug);

package/shell/simple/SimpleShell.d.ts

@@ -1,14 +1,41 @@
 import { ExecOptions } from 'child_process';
 import { Logger } from '@nu-art/ts-common';
+/**
+ * Extended ExecOptions with encoding support.
+ */
 export type CliOptions = ExecOptions & {
     encoding: BufferEncoding | string | null;
 };
+/**
+ * Simple shell command executor using Node.js child_process.
+ *
+ * Executes shell commands synchronously via `exec()` and handles
+ * output conversion. Supports debug logging and custom shell/options.
+ *
+ * **Behavior**:
+ * - Uses `/bin/bash` as default shell
+ * - Converts Buffer output to UTF-8 strings
+ * - Logs stdout as info, stderr as error
+ * - Throws CliError on command failure
+ * - Supports UID tagging for log identification
+ */
 export declare class SimpleShell extends Logger {
+    /** Debug mode flag (enables verbose command logging) */
     private _debug;
+    /** Execution options for child_process.exec() */
     private cliOptions;
     /**
-     * Executes the accumulated commands in the command list.
-     * @returns {Promise<string>} A promise that resolves with the standard output of the executed command.
+     * Executes a shell command and returns stdout/stderr.
+     *
+     * **Behavior**:
+     * - Logs command in debug mode (wrapped in triple quotes)
+     * - Converts Buffer output to UTF-8 strings
+     * - Logs stdout as info, stderr as error
+     * - Throws CliError if command fails (non-zero exit code)
+     *
+     * @param command - Shell command string to execute
+     * @returns Promise resolving to stdout and stderr strings
+     * @throws CliError if command execution fails
      */
     execute: (command: string) => Promise<{
         stdout: string;

package/shell/simple/SimpleShell.js

@@ -1,6 +1,12 @@
 import { exec } from 'child_process';
 import { Logger } from '@nu-art/ts-common';
 import { CliError } from '../core/CliError.js';
+/**
+ * Converts input to string, handling Buffer and ArrayBufferLike types.
+ *
+ * @param input - String, Buffer, or ArrayBufferLike to convert
+ * @returns UTF-8 string representation
+ */
 function toStringWithNewlines(input) {
     if (typeof input === 'string')
         return input;
@@ -8,12 +14,36 @@ function toStringWithNewlines(input) {
         ? input.toString('utf8')
         : Buffer.from(input).toString('utf8');
 }
+/**
+ * Simple shell command executor using Node.js child_process.
+ *
+ * Executes shell commands synchronously via `exec()` and handles
+ * output conversion. Supports debug logging and custom shell/options.
+ *
+ * **Behavior**:
+ * - Uses `/bin/bash` as default shell
+ * - Converts Buffer output to UTF-8 strings
+ * - Logs stdout as info, stderr as error
+ * - Throws CliError on command failure
+ * - Supports UID tagging for log identification
+ */
 export class SimpleShell extends Logger {
+    /** Debug mode flag (enables verbose command logging) */
     _debug = false;
+    /** Execution options for child_process.exec() */
     cliOptions = { shell: '/bin/bash' };
     /**
-     * Executes the accumulated commands in the command list.
-     * @returns {Promise<string>} A promise that resolves with the standard output of the executed command.
+     * Executes a shell command and returns stdout/stderr.
+     *
+     * **Behavior**:
+     * - Logs command in debug mode (wrapped in triple quotes)
+     * - Converts Buffer output to UTF-8 strings
+     * - Logs stdout as info, stderr as error
+     * - Throws CliError if command fails (non-zero exit code)
+     *
+     * @param command - Shell command string to execute
+     * @returns Promise resolving to stdout and stderr strings
+     * @throws CliError if command execution fails
      */
     execute = async (command) => {
         if (this._debug)

package/shell/tools.d.ts

@@ -1,3 +1,33 @@
 import { AbsolutePath } from '@nu-art/ts-common';
+/**
+ * Removes ANSI escape codes from a string.
+ *
+ * Strips color codes and formatting sequences (e.g., `\x1B[31m` for red text)
+ * from shell command output. Useful for processing command output that
+ * contains terminal formatting.
+ *
+ * **Regex**: Matches ANSI escape sequences starting with `\x1B[` followed by
+ * digits, optional semicolon, more digits, and ending with `m`.
+ *
+ * @param text - Text containing ANSI escape codes
+ * @returns Text with all ANSI codes removed
+ */
 export declare function removeAnsiCodes(text: string): string;
+/**
+ * Converts a relative or absolute path to a full absolute path.
+ *
+ * **Behavior**:
+ * - Removes leading slashes (normalizes paths like `/path/to/file`)
+ * - Resolves relative to `assetParentPath` (defaults to `process.cwd()`)
+ * - Returns a branded `AbsolutePath` type
+ *
+ * **Note**: The commented-out validation that checks if the resolved path
+ * is within `assetParentPath` is disabled. This could be a security concern
+ * if used with user-provided paths.
+ *
+ * @param pathToFile - Path to convert (relative or absolute)
+ * @param assetParentPath - Base path for resolution (default: `process.cwd()`)
+ * @returns Absolute path as branded type
+ * @throws Error if path is not provided or is empty
+ */
 export declare function convertToFullPath(pathToFile: string, assetParentPath?: string): AbsolutePath;

package/shell/tools.js

@@ -1,8 +1,38 @@
 import * as path from 'path';
+/**
+ * Removes ANSI escape codes from a string.
+ *
+ * Strips color codes and formatting sequences (e.g., `\x1B[31m` for red text)
+ * from shell command output. Useful for processing command output that
+ * contains terminal formatting.
+ *
+ * **Regex**: Matches ANSI escape sequences starting with `\x1B[` followed by
+ * digits, optional semicolon, more digits, and ending with `m`.
+ *
+ * @param text - Text containing ANSI escape codes
+ * @returns Text with all ANSI codes removed
+ */
 export function removeAnsiCodes(text) {
     // This regular expression matches the escape codes and removes them
     return text.replace(/\x1B\[\d+;?\d*m/g, '');
 }
+/**
+ * Converts a relative or absolute path to a full absolute path.
+ *
+ * **Behavior**:
+ * - Removes leading slashes (normalizes paths like `/path/to/file`)
+ * - Resolves relative to `assetParentPath` (defaults to `process.cwd()`)
+ * - Returns a branded `AbsolutePath` type
+ *
+ * **Note**: The commented-out validation that checks if the resolved path
+ * is within `assetParentPath` is disabled. This could be a security concern
+ * if used with user-provided paths.
+ *
+ * @param pathToFile - Path to convert (relative or absolute)
+ * @param assetParentPath - Base path for resolution (default: `process.cwd()`)
+ * @returns Absolute path as branded type
+ * @throws Error if path is not provided or is empty
+ */
 export function convertToFullPath(pathToFile, assetParentPath = process.cwd()) {
     if (!pathToFile)
         throw new Error('Path not provided');

package/shell/types.d.ts

@@ -1,3 +1,17 @@
 import { BaseCommando } from './core/BaseCommando.js';
+/**
+ * Log output types for shell commands.
+ *
+ * - `'out'`: Standard output (stdout)
+ * - `'err'`: Standard error (stderr)
+ */
 export type LogTypes = 'out' | 'err';
+/**
+ * Function type for command blocks that operate on a Commando instance.
+ *
+ * Used for composing command sequences where a function receives
+ * a Commando instance and builds commands on it.
+ *
+ * @template Commando - Commando type (must extend BaseCommando)
+ */
 export type CliBlock<Commando extends BaseCommando> = (cli: Commando) => void;