@nu-art/commando 0.401.0 → 0.401.2

package/{shell/core → 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;
     /**
@@ -25,6 +55,7 @@ export declare class BaseCommando {
      * @returns {this} - The BaseCommando instance for method chaining.
      */
     append(command: string): this;
+    mark(): this;
     /**
      * Increases the current indentation level by one.
      * @returns {this} - The BaseCommando instance for method chaining.

package/{shell/core → 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;
@@ -40,6 +70,10 @@ export class BaseCommando {
         this.builder.append(command);
         return this;
     }
+    mark() {
+        this.builder.setMark();
+        return this;
+    }
     /**
      * Increases the current indentation level by one.
      * @returns {this} - The BaseCommando instance for method chaining.

package/core/CliError.d.ts

@@ -0,0 +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/core/CliError.js

@@ -0,0 +1,58 @@
+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;
+        this.stderr = stderr;
+        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(CommandoException, message);
+        this.stdout = stdout;
+        this.stderr = stderr;
+        this.exitCode = exitCode;
+    }
+}

package/{shell/core → 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;
     /**

package/{shell/core → 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/core/CommandoPool.d.ts

@@ -0,0 +1,42 @@
+import { Constructor } from '@nu-art/ts-common';
+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/core/CommandoPool.js

@@ -0,0 +1,48 @@
+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/core/class-merger.d.ts

@@ -0,0 +1,39 @@
+import { Constructor } from '@nu-art/ts-common';
+/**
+ * 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> : {} : {};
+/**
+ * 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>>;
+/**
+ * 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/core/class-merger.js

@@ -0,0 +1,50 @@
+/**
+ * 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 {
+        /**
+         * Constructs an instance of SuperClass, merging properties from all plugins.
+         * @param {...any[]} args - The arguments to pass to the constructors.
+         */
+        constructor(...args) {
+            plugins.forEach(plugin => {
+                Object.getOwnPropertyNames(plugin.prototype).forEach(name => {
+                    const prop = Object.getOwnPropertyDescriptor(plugin.prototype, name);
+                    if (prop) {
+                        Object.defineProperty(this, name, prop);
+                    }
+                });
+            });
+        }
+    }
+    return SuperClass;
+}
+/**
+ * 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);
+    return new SuperClass();
+}

package/index.d.ts

@@ -0,0 +1,11 @@
+export * from './core/BaseCommando.js';
+export * from './core/CliError.js';
+export * from './core/CommandoPool.js';
+export * from './core/class-merger.js';
+export * from './interactive/CommandoInteractive.js';
+export * from './simple/Commando.js';
+export * from './plugins/basic.js';
+export * from './plugins/nvm.js';
+export * from './plugins/pnpm.js';
+export * from './services/pnpm.js';
+export * from './types.js';

package/index.js

@@ -0,0 +1,16 @@
+// Core exports
+export * from './core/BaseCommando.js';
+export * from './core/CliError.js';
+export * from './core/CommandoPool.js';
+export * from './core/class-merger.js';
+// Interactive and Simple commandos
+export * from './interactive/CommandoInteractive.js';
+export * from './simple/Commando.js';
+// Plugins
+export * from './plugins/basic.js';
+export * from './plugins/nvm.js';
+export * from './plugins/pnpm.js';
+// Services
+export * from './services/pnpm.js';
+// Types
+export * from './types.js';