@nu-art/commando 0.401.0 → 0.401.1

package/cli-params/CLIParamsResolver.d.ts

@@ -1,12 +1,65 @@
 import { BaseCliParam, CliParams } from './types.js';
+/**
+ * Type-safe CLI parameter resolver and parser.
+ *
+ * Parses command-line arguments (`process.argv`) into a typed object based on
+ * parameter definitions. Supports:
+ * - Multiple keys/aliases per parameter
+ * - Type validation and conversion
+ * - Default values and initial values
+ * - Option validation (restrict to specific values)
+ * - Array parameters (collect multiple values)
+ * - Dependencies (set other params based on current param)
+ * - Quoted string handling
+ *
+ * **Usage**:
+ * ```typescript
+ * const resolver = CLIParamsResolver.create(
+ *   { keys: ['--name', '-n'], keyName: 'name', type: 'string', description: 'Name' },
+ *   { keys: ['--count'], keyName: 'count', type: 'number', defaultValue: 1 }
+ * );
+ * const params = resolver.resolveParamValue();
+ * // params.name: string, params.count: number
+ * ```
+ *
+ * @template T - Array of BaseCliParam definitions
+ * @template Output - Resolved parameters object type
+ */
 export declare class CLIParamsResolver<T extends BaseCliParam<string, any>[], Output extends CliParams<T> = CliParams<T>> {
+    /** Processed parameters with all required fields filled */
     private params;
+    /**
+     * Creates a CLIParamsResolver instance.
+     *
+     * @template T - Array of BaseCliParam definitions
+     * @param params - Parameter definitions
+     * @returns New CLIParamsResolver instance
+     */
     static create<T extends BaseCliParam<string, any>[]>(...params: T): CLIParamsResolver<T, CliParams<T>>;
+    /**
+     * Creates a CLIParamsResolver and processes parameters.
+     *
+     * @param params - Parameter definitions (may be incomplete)
+     */
     constructor(params: BaseCliParam<string, any>[]);
     /**
-     * Format current input params and return it structured by the app params type.
-     * @param inputParams current console input arguments
-     * @returns CliParamsObject
+     * Parses command-line arguments into a typed parameters object.
+     *
+     * **Parsing Behavior**:
+     * - Splits arguments by `=` (e.g., `--key=value`)
+     * - Strips quotes from values and unescapes quotes
+     * - Processes values using parameter processors
+     * - Validates against options if provided
+     * - Handles dependencies (sets dependent params)
+     * - Accumulates array values (removes duplicates)
+     * - Applies initial values for missing params
+     * - Warns when overriding non-array values
+     *
+     * **Input Format**: `--key=value` or `--key value` (space-separated not supported)
+     *
+     * @param inputParams - Command-line arguments (default: `process.argv.slice(2)`)
+     * @returns Typed object with resolved parameter values
+     * @throws Error if value not in options, or if required value missing
      */
     resolveParamValue(inputParams?: string[]): Output;
     /**

package/cli-params/CLIParamsResolver.js

@@ -1,17 +1,70 @@
 import { asArray, exists, filterDuplicates, StaticLogger } from '@nu-art/ts-common';
 import { DefaultProcessorsMapper } from './consts.js';
+/**
+ * Type-safe CLI parameter resolver and parser.
+ *
+ * Parses command-line arguments (`process.argv`) into a typed object based on
+ * parameter definitions. Supports:
+ * - Multiple keys/aliases per parameter
+ * - Type validation and conversion
+ * - Default values and initial values
+ * - Option validation (restrict to specific values)
+ * - Array parameters (collect multiple values)
+ * - Dependencies (set other params based on current param)
+ * - Quoted string handling
+ *
+ * **Usage**:
+ * ```typescript
+ * const resolver = CLIParamsResolver.create(
+ *   { keys: ['--name', '-n'], keyName: 'name', type: 'string', description: 'Name' },
+ *   { keys: ['--count'], keyName: 'count', type: 'number', defaultValue: 1 }
+ * );
+ * const params = resolver.resolveParamValue();
+ * // params.name: string, params.count: number
+ * ```
+ *
+ * @template T - Array of BaseCliParam definitions
+ * @template Output - Resolved parameters object type
+ */
 export class CLIParamsResolver {
+    /** Processed parameters with all required fields filled */
     params;
+    /**
+     * Creates a CLIParamsResolver instance.
+     *
+     * @template T - Array of BaseCliParam definitions
+     * @param params - Parameter definitions
+     * @returns New CLIParamsResolver instance
+     */
     static create(...params) {
         return new CLIParamsResolver(params);
     }
+    /**
+     * Creates a CLIParamsResolver and processes parameters.
+     *
+     * @param params - Parameter definitions (may be incomplete)
+     */
     constructor(params) {
         this.params = this.translate(params);
     }
     /**
-     * Format current input params and return it structured by the app params type.
-     * @param inputParams current console input arguments
-     * @returns CliParamsObject
+     * Parses command-line arguments into a typed parameters object.
+     *
+     * **Parsing Behavior**:
+     * - Splits arguments by `=` (e.g., `--key=value`)
+     * - Strips quotes from values and unescapes quotes
+     * - Processes values using parameter processors
+     * - Validates against options if provided
+     * - Handles dependencies (sets dependent params)
+     * - Accumulates array values (removes duplicates)
+     * - Applies initial values for missing params
+     * - Warns when overriding non-array values
+     *
+     * **Input Format**: `--key=value` or `--key value` (space-separated not supported)
+     *
+     * @param inputParams - Command-line arguments (default: `process.argv.slice(2)`)
+     * @returns Typed object with resolved parameter values
+     * @throws Error if value not in options, or if required value missing
      */
     resolveParamValue(inputParams = process.argv.slice(2, process.argv.length)) {
         const runtimeParams = inputParams.reduce((output, inputParam) => {

package/cli-params/consts.d.ts

@@ -1,6 +1,43 @@
 import { TypedMap } from '@nu-art/ts-common';
 import { CliParam } from './types.js';
+/**
+ * Default processor for boolean CLI parameters.
+ *
+ * Returns the defaultValue or `true` if the flag is present
+ *
+ * @param input - Optional input string (flag presence indicator)
+ * @param defaultValue - Optional default value if flag is absent
+ * @returns `true` if flag is present, otherwise `defaultValue ?? false`
+ */
 export declare const DefaultProcessor_Boolean: CliParam<any, boolean>['process'];
+/**
+ * Default processor for string CLI parameters.
+ *
+ * Returns the input string, or defaultValue if input is empty/missing.
+ * Throws if input is empty and no default is provided.
+ *
+ * @param input - Optional input string
+ * @param defaultValue - Optional default value
+ * @returns Processed string value
+ * @throws Error if input is empty and no default provided
+ */
 export declare const DefaultProcessor_String: CliParam<any, string>['process'];
+/**
+ * Default processor for number CLI parameters.
+ *
+ * Parses the input as a number, or returns defaultValue if input is missing.
+ * Throws if input is not a valid number or if input is empty and no default provided.
+ *
+ * @param input - Optional input string
+ * @param defaultValue - Optional default value
+ * @returns Parsed number value
+ * @throws Error if input is not a number or missing with no default
+ */
 export declare const DefaultProcessor_Number: CliParam<any, number>['process'];
+/**
+ * Map of default processors by type name.
+ *
+ * Used by CLIParamsResolver to assign processors when not provided.
+ * Keys match the type strings from `TypeOfTypeAsString`.
+ */
 export declare const DefaultProcessorsMapper: TypedMap<CliParam<any, any>['process']>;

package/cli-params/consts.js

@@ -1,7 +1,27 @@
 import { exists } from '@nu-art/ts-common';
+/**
+ * Default processor for boolean CLI parameters.
+ *
+ * Returns the defaultValue or `true` if the flag is present
+ *
+ * @param input - Optional input string (flag presence indicator)
+ * @param defaultValue - Optional default value if flag is absent
+ * @returns `true` if flag is present, otherwise `defaultValue ?? false`
+ */
 export const DefaultProcessor_Boolean = (input, defaultValue) => {
-    return true;
+    return defaultValue ?? true;
 };
+/**
+ * Default processor for string CLI parameters.
+ *
+ * Returns the input string, or defaultValue if input is empty/missing.
+ * Throws if input is empty and no default is provided.
+ *
+ * @param input - Optional input string
+ * @param defaultValue - Optional default value
+ * @returns Processed string value
+ * @throws Error if input is empty and no default provided
+ */
 export const DefaultProcessor_String = (input, defaultValue) => {
     if (!input || !input.length) {
         if (!exists(defaultValue))
@@ -10,6 +30,17 @@ export const DefaultProcessor_String = (input, defaultValue) => {
     }
     return input;
 };
+/**
+ * Default processor for number CLI parameters.
+ *
+ * Parses the input as a number, or returns defaultValue if input is missing.
+ * Throws if input is not a valid number or if input is empty and no default provided.
+ *
+ * @param input - Optional input string
+ * @param defaultValue - Optional default value
+ * @returns Parsed number value
+ * @throws Error if input is not a number or missing with no default
+ */
 export const DefaultProcessor_Number = (input, defaultValue) => {
     if (!input) {
         if (!exists(defaultValue))
@@ -20,6 +51,12 @@ export const DefaultProcessor_Number = (input, defaultValue) => {
         throw new Error('expected number value');
     return Number(input);
 };
+/**
+ * Map of default processors by type name.
+ *
+ * Used by CLIParamsResolver to assign processors when not provided.
+ * Keys match the type strings from `TypeOfTypeAsString`.
+ */
 export const DefaultProcessorsMapper = {
     string: DefaultProcessor_String,
     boolean: DefaultProcessor_Boolean,

package/cli-params/types.d.ts

@@ -8,18 +8,46 @@ export type DependencyParam<T extends Primitive | Primitive[]> = {
     param: BaseCliParam<string, T>;
     value: T | ((currentValue: any) => T);
 };
+/**
+ * Base CLI parameter definition (before processing).
+ *
+ * Defines a command-line parameter with keys, type, and optional features.
+ * Can be incomplete (missing name/process) and will be filled by CLIParamsResolver.
+ *
+ * **Features**:
+ * - Multiple keys (aliases): `['--help', '-h']`
+ * - Type validation: `'string'`, `'number'`, `'boolean'`, `'string[]'`, etc.
+ * - Options validation: Restrict values to specific options
+ * - Dependencies: Set other params based on this param's value
+ * - Array support: Collect multiple values
+ *
+ * @template K - Key name type (string literal)
+ * @template V - Value type (primitive or array)
+ */
 export type BaseCliParam<K extends string, V extends Primitive | Primitive[]> = {
+    /** Array of CLI keys/aliases (e.g., `['--help', '-h']`) */
     keys: string[];
+    /** Unique key name for the resolved object */
     keyName: K;
+    /** Type string representation (e.g., `'string'`, `'number[]'`) */
     type: TypeOfTypeAsString<V>;
+    /** Human-readable description */
     description: string;
+    /** Optional parameter name (defaults to keyName) */
     name?: string;
+    /** Optional array of allowed values (validates input) */
     options?: string[];
+    /** Initial value if param not provided */
     initialValue?: V;
+    /** Default value if param provided but empty */
     defaultValue?: V;
+    /** Optional processor function (defaults by type) */
     process?: (value?: string, defaultValue?: V) => V;
+    /** Whether this param accepts multiple values (array) */
     isArray?: true;
+    /** Optional grouping for help/validation */
     group?: string;
+    /** Parameters that depend on this one */
     dependencies?: DependencyParam<any>[];
 };
 export type CliParam<K extends string, V extends Primitive | Primitive[]> = BaseCliParam<K, V> & {

package/package.json

@@ -1,24 +1,33 @@
 {
   "name": "@nu-art/commando",
-  "version": "0.401.0",
-  "description": "",
+  "version": "0.401.1",
+  "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,10 @@
     "build": "tsc"
   },
   "dependencies": {
-    "@nu-art/ts-common": "0.401.0"
+    "@nu-art/ts-common": "0.401.1"
+  },
+  "devDependencies": {
+    "@nu-art/testalot": "0.401.1"
   },
   "unitConfig": {
     "type": "typescript-lib"

package/shell/core/BaseCommando.d.ts

@@ -1,12 +1,39 @@
 import { Constructor } from '@nu-art/ts-common';
 import { CommandBuilder } from './CommandBuilder.js';
+/**
+ * Base class for shell command execution with plugin support.
+ *
+ * Provides a fluent API for building shell commands with indentation support.
+ * Uses a plugin system that merges multiple classes into a single instance
+ * using the class-merger utility.
+ *
+ * **Plugin System**: The `_create()` method uses class merging to combine
+ * BaseCommando with plugin classes, creating a single instance with methods
+ * from all merged classes.
+ *
+ * **Command Building**: Commands are built using the CommandBuilder, which
+ * supports indentation and newline handling. The builder accumulates commands
+ * until `execute()` is called.
+ *
+ * **Note**: The `builder` field is marked readonly but is actually set via
+ * `@ts-ignore` in `_create()`. This is a type safety issue.
+ */
 export declare class BaseCommando {
+    /** Command builder for accumulating shell commands */
     protected readonly builder: CommandBuilder;
+    /** Debug mode flag (enables verbose logging) */
     protected _debug: boolean;
     /**
-     * Creates a new instance of BaseCommando merged with the provided plugins.
-     * @param {Constructor<any>[]} plugins - The plugins to merge with BaseCommando.
-     * @returns The Super type merged of BaseCommando and all the plugins provided new instance of BaseCommando merged with the plugins.
+     * Creates a new BaseCommando instance merged with provided plugins.
+     *
+     * Uses class merging to combine BaseCommando with plugin classes into
+     * a single instance. The builder is initialized after merging.
+     *
+     * **Note**: Uses `@ts-ignore` to set the readonly `builder` field.
+     *
+     * @template T - Array of constructor types to merge
+     * @param plugins - Plugin classes to merge with BaseCommando
+     * @returns Merged instance with BaseCommando and all plugin methods
      */
     static _create<T extends Constructor<any>[]>(...plugins: T): import("./class-merger.js").MergeTypes<[typeof BaseCommando, ...T]> & BaseCommando;
     /**
@@ -14,9 +41,12 @@ export declare class BaseCommando {
      */
     constructor();
     /**
-     * Toggles or sets the debug mode.
-     * @param {boolean} [debug] - If provided, sets the debug mode to this value. Otherwise, toggles the current debug mode.
-     * @returns {boolean} - The current state of debug mode.
+     * Toggles or sets debug mode.
+     *
+     * When debug is enabled, shell execution provides verbose logging.
+     *
+     * @param debug - Optional value to set (if omitted, toggles current state)
+     * @returns This instance for method chaining
      */
     debug(debug?: boolean): this;
     /**

package/shell/core/BaseCommando.js

@@ -1,13 +1,40 @@
 import { ImplementationMissingException } from '@nu-art/ts-common';
 import { CommandBuilder } from './CommandBuilder.js';
 import { CreateMergedInstance } from './class-merger.js';
+/**
+ * Base class for shell command execution with plugin support.
+ *
+ * Provides a fluent API for building shell commands with indentation support.
+ * Uses a plugin system that merges multiple classes into a single instance
+ * using the class-merger utility.
+ *
+ * **Plugin System**: The `_create()` method uses class merging to combine
+ * BaseCommando with plugin classes, creating a single instance with methods
+ * from all merged classes.
+ *
+ * **Command Building**: Commands are built using the CommandBuilder, which
+ * supports indentation and newline handling. The builder accumulates commands
+ * until `execute()` is called.
+ *
+ * **Note**: The `builder` field is marked readonly but is actually set via
+ * `@ts-ignore` in `_create()`. This is a type safety issue.
+ */
 export class BaseCommando {
+    /** Command builder for accumulating shell commands */
     builder;
+    /** Debug mode flag (enables verbose logging) */
     _debug = false;
     /**
-     * Creates a new instance of BaseCommando merged with the provided plugins.
-     * @param {Constructor<any>[]} plugins - The plugins to merge with BaseCommando.
-     * @returns The Super type merged of BaseCommando and all the plugins provided new instance of BaseCommando merged with the plugins.
+     * Creates a new BaseCommando instance merged with provided plugins.
+     *
+     * Uses class merging to combine BaseCommando with plugin classes into
+     * a single instance. The builder is initialized after merging.
+     *
+     * **Note**: Uses `@ts-ignore` to set the readonly `builder` field.
+     *
+     * @template T - Array of constructor types to merge
+     * @param plugins - Plugin classes to merge with BaseCommando
+     * @returns Merged instance with BaseCommando and all plugin methods
      */
     static _create(...plugins) {
         const _commando = CreateMergedInstance(BaseCommando, ...plugins);
@@ -23,9 +50,12 @@ export class BaseCommando {
         this.builder = new CommandBuilder();
     }
     /**
-     * Toggles or sets the debug mode.
-     * @param {boolean} [debug] - If provided, sets the debug mode to this value. Otherwise, toggles the current debug mode.
-     * @returns {boolean} - The current state of debug mode.
+     * Toggles or sets debug mode.
+     *
+     * When debug is enabled, shell execution provides verbose logging.
+     *
+     * @param debug - Optional value to set (if omitted, toggles current state)
+     * @returns This instance for method chaining
      */
     debug(debug) {
         this._debug = debug ?? !this._debug;

package/shell/core/CliError.d.ts

@@ -1,14 +1,49 @@
 import { CustomException } from '@nu-art/ts-common';
 import { ExecException } from 'child_process';
+/**
+ * Exception thrown when a shell command execution fails.
+ *
+ * Contains the command output (stdout/stderr) and the underlying
+ * ExecException from Node.js child_process.
+ */
 export declare class CliError extends CustomException {
+    /** Standard output from the failed command */
     stdout: string;
+    /** Standard error from the failed command */
     stderr: string;
+    /** Underlying Node.js ExecException */
     cause: ExecException;
+    /**
+     * Creates a CliError instance.
+     *
+     * @param message - Error message
+     * @param stdout - Standard output from command
+     * @param stderr - Standard error from command
+     * @param cause - Underlying ExecException
+     */
     constructor(message: string, stdout: string, stderr: string, cause: ExecException);
 }
+/**
+ * Exception for commando-specific errors with exit code.
+ *
+ * Similar to CliError but includes an explicit exit code rather than
+ * extracting it from the ExecException.
+ *
+ */
 export declare class CommandoException extends CustomException {
+    /** Standard output from the command */
     stdout: string;
+    /** Standard error from the command */
     stderr: string;
+    /** Exit code from the command */
     exitCode: number;
+    /**
+     * Creates a CommandoException instance.
+     *
+     * @param message - Error message
+     * @param stdout - Standard output
+     * @param stderr - Standard error
+     * @param exitCode - Command exit code
+     */
     constructor(message: string, stdout: string, stderr: string, exitCode: number);
 }

package/shell/core/CliError.js

@@ -1,8 +1,25 @@
 import { CustomException } from '@nu-art/ts-common';
+/**
+ * Exception thrown when a shell command execution fails.
+ *
+ * Contains the command output (stdout/stderr) and the underlying
+ * ExecException from Node.js child_process.
+ */
 export class CliError extends CustomException {
+    /** Standard output from the failed command */
     stdout;
+    /** Standard error from the failed command */
     stderr;
+    /** Underlying Node.js ExecException */
     cause;
+    /**
+     * Creates a CliError instance.
+     *
+     * @param message - Error message
+     * @param stdout - Standard output from command
+     * @param stderr - Standard error from command
+     * @param cause - Underlying ExecException
+     */
     constructor(message, stdout, stderr, cause) {
         super(CliError, message, cause);
         this.stdout = stdout;
@@ -10,12 +27,30 @@ export class CliError extends CustomException {
         this.cause = cause;
     }
 }
+/**
+ * Exception for commando-specific errors with exit code.
+ *
+ * Similar to CliError but includes an explicit exit code rather than
+ * extracting it from the ExecException.
+ *
+ */
 export class CommandoException extends CustomException {
+    /** Standard output from the command */
     stdout;
+    /** Standard error from the command */
     stderr;
+    /** Exit code from the command */
     exitCode;
+    /**
+     * Creates a CommandoException instance.
+     *
+     * @param message - Error message
+     * @param stdout - Standard output
+     * @param stderr - Standard error
+     * @param exitCode - Command exit code
+     */
     constructor(message, stdout, stderr, exitCode) {
-        super(CliError, message);
+        super(CommandoException, message);
         this.stdout = stdout;
         this.stderr = stderr;
         this.exitCode = exitCode;

package/shell/core/CommandBuilder.d.ts

@@ -5,9 +5,26 @@ type Options = {
     newlineDelimiter: string;
     indentation: number;
 };
+/**
+ * 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 declare class CommandBuilder {
+    private initialCommands;
+    /** Array of accumulated command strings */
     commands: string[];
+    /** Current indentation level (number of indent steps) */
     private indentation;
+    /** Configuration options for formatting */
     private option;
     /**
      * Constructs a CommandBuilder instance with given options.
@@ -19,6 +36,7 @@ export declare class CommandBuilder {
      * @returns {string} - A string containing spaces for the current indentation level.
      */
     protected getIndentation: () => string;
+    setMark(): void;
     /**
      * Increases the current indentation level by one.
      */
@@ -34,8 +52,15 @@ export declare class CommandBuilder {
     emptyLine(): this;
     /**
      * 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
      */
     readonly append: (command: string) => this;
     /**