@nu-art/commando 0.400.14 → 0.401.1

package/shell/plugins/pnpm.js

@@ -4,7 +4,25 @@ import { Commando_Basic } from './basic.js';
 import { Commando_Programming } from './programming.js';
 import { Commando_NVM } from './nvm.js';
 const Super = MergeClass(BaseCommando, Commando_Programming, Commando_Basic, Commando_NVM);
+/**
+ * PNPM package manager plugin for Commando.
+ *
+ * Provides PNPM operations:
+ * - Install PNPM
+ * - Get PNPM version
+ * - Install packages (with store prune and force flags)
+ *
+ * Extends Commando_NVM, Commando_Programming, and Commando_Basic (merged).
+ * Requires NVM for Node.js version management.
+ */
 export class Commando_PNPM extends Super {
+    /**
+     * Installs packages using PNPM.
+     *
+     * Prunes the store, then installs with force flag and no frozen lockfile.
+     *
+     * @returns This instance for method chaining
+     */
     async installPackages() {
         await this
             .append(`pnpm store prune`)
@@ -12,12 +30,25 @@ export class Commando_PNPM extends Super {
             .execute();
         return this;
     }
+    /**
+     * Installs PNPM by downloading and executing the install script.
+     *
+     * @param version - PNPM version to install
+     * @returns This instance for method chaining
+     */
     async install(version) {
         await this
             .append(`curl -fsSL "https://get.pnpm.io/install.sh" | env PNPM_VERSION=${version} bash -`)
             .execute();
         return this;
     }
+    /**
+     * Gets the installed PNPM version.
+     *
+     * Only executes if PNPM is available (checks with `command -v pnpm`).
+     *
+     * @returns Promise resolving to PNPM version string (trimmed)
+     */
     async getVersion() {
         return this.if('[[ -x "$(command -v pnpm)" ]]', (commando) => {
             commando.append('pnpm --version');

package/shell/plugins/programming.d.ts

@@ -1,5 +1,16 @@
 import { BaseCommando } from '../core/BaseCommando.js';
 import { CliBlock } from '../types.js';
+/**
+ * Programming constructs plugin for Commando.
+ *
+ * Provides control flow structures for building shell scripts:
+ * - Conditionals (`if`/`else`)
+ * - Loops (`for`, `while`)
+ * - Functions
+ *
+ * These methods build shell script structures with proper indentation
+ * and syntax, allowing programmatic construction of complex shell scripts.
+ */
 export declare class Commando_Programming extends BaseCommando {
     /**
      * Constructs an if-else conditional command structure.
@@ -19,17 +30,26 @@ export declare class Commando_Programming extends BaseCommando {
     for(varName: string, arrayNameOrValues: string | string[], loop: CliBlock<this>): this;
     /**
      * Appends a 'continue' command for loop control.
-     * @returns {this} - The Cli instance for method chaining.
+     *
+     * Skips to the next iteration of the innermost loop.
+     *
+     * @returns This instance for method chaining
      */
     continue(): this;
     /**
      * Appends a 'break' command for loop control.
-     * @returns {this} - The Cli instance for method chaining.
+     *
+     * Exits the innermost loop.
+     *
+     * @returns This instance for method chaining
      */
     break(): this;
     /**
      * Appends a 'return' command for exiting a function or script.
-     * @returns {this} - The Cli instance for method chaining.
+     *
+     * Exits the current function or script with optional exit code.
+     *
+     * @returns This instance for method chaining
      */
     return(): this;
 }

package/shell/plugins/programming.js

@@ -1,4 +1,15 @@
 import { BaseCommando } from '../core/BaseCommando.js';
+/**
+ * Programming constructs plugin for Commando.
+ *
+ * Provides control flow structures for building shell scripts:
+ * - Conditionals (`if`/`else`)
+ * - Loops (`for`, `while`)
+ * - Functions
+ *
+ * These methods build shell script structures with proper indentation
+ * and syntax, allowing programmatic construction of complex shell scripts.
+ */
 export class Commando_Programming extends BaseCommando {
     /**
      * Constructs an if-else conditional command structure.
@@ -46,7 +57,10 @@ export class Commando_Programming extends BaseCommando {
     }
     /**
      * Appends a 'continue' command for loop control.
-     * @returns {this} - The Cli instance for method chaining.
+     *
+     * Skips to the next iteration of the innermost loop.
+     *
+     * @returns This instance for method chaining
      */
     continue() {
         this.append('continue');
@@ -54,7 +68,10 @@ export class Commando_Programming extends BaseCommando {
     }
     /**
      * Appends a 'break' command for loop control.
-     * @returns {this} - The Cli instance for method chaining.
+     *
+     * Exits the innermost loop.
+     *
+     * @returns This instance for method chaining
      */
     break() {
         this.append('break');
@@ -62,7 +79,10 @@ export class Commando_Programming extends BaseCommando {
     }
     /**
      * Appends a 'return' command for exiting a function or script.
-     * @returns {this} - The Cli instance for method chaining.
+     *
+     * Exits the current function or script with optional exit code.
+     *
+     * @returns This instance for method chaining
      */
     return() {
         this.append('return');

package/shell/plugins/python.d.ts

@@ -2,9 +2,40 @@ import { BaseCommando } from '../core/BaseCommando.js';
 import { Commando_Programming } from './programming.js';
 import { Commando_Basic } from './basic.js';
 declare const Super: import("@nu-art/ts-common").Constructor<BaseCommando & Commando_Programming & Commando_Basic>;
+/**
+ * Python 3 plugin for Commando.
+ *
+ * Provides Python virtual environment operations:
+ * - Create virtual environments
+ * - Activate virtual environments
+ * - Install requirements from requirements.txt
+ *
+ * Extends Commando_Programming and Commando_Basic (merged).
+ */
 export declare class Commando_Python3 extends Super {
+    /**
+     * Activates a Python virtual environment.
+     *
+     * Sources the activation script for the virtual environment.
+     *
+     * @param venvFolder - Virtual environment folder path (default: '.venv')
+     * @returns This instance for method chaining
+     */
     sourceVenv(venvFolder?: string): this;
+    /**
+     * Creates a Python virtual environment.
+     *
+     * @param venvFolder - Virtual environment folder path (default: '.venv')
+     * @returns This instance for method chaining
+     * @throws Exception if virtual environment creation fails
+     */
     installVenv(venvFolder?: string): Promise<this>;
+    /**
+     * Installs Python packages from a requirements file.
+     *
+     * @param pathToRequirementsFile - Path to requirements.txt file (default: './requirements.txt')
+     * @returns This instance for method chaining
+     */
     installRequirements(pathToRequirementsFile?: string): Promise<this>;
 }
 export {};

package/shell/plugins/python.js

@@ -4,12 +4,38 @@ import { MergeClass } from '../core/class-merger.js';
 import { Commando_Basic } from './basic.js';
 import { Exception } from '@nu-art/ts-common';
 const Super = MergeClass(BaseCommando, Commando_Programming, Commando_Basic);
+/** Default virtual environment folder name */
 const DefaultVenvFolder = '.venv';
+/**
+ * Python 3 plugin for Commando.
+ *
+ * Provides Python virtual environment operations:
+ * - Create virtual environments
+ * - Activate virtual environments
+ * - Install requirements from requirements.txt
+ *
+ * Extends Commando_Programming and Commando_Basic (merged).
+ */
 export class Commando_Python3 extends Super {
+    /**
+     * Activates a Python virtual environment.
+     *
+     * Sources the activation script for the virtual environment.
+     *
+     * @param venvFolder - Virtual environment folder path (default: '.venv')
+     * @returns This instance for method chaining
+     */
     sourceVenv(venvFolder = DefaultVenvFolder) {
         this.append(`source ${venvFolder}/bin/activate`);
         return this;
     }
+    /**
+     * Creates a Python virtual environment.
+     *
+     * @param venvFolder - Virtual environment folder path (default: '.venv')
+     * @returns This instance for method chaining
+     * @throws Exception if virtual environment creation fails
+     */
     async installVenv(venvFolder = DefaultVenvFolder) {
         this.append(`python3 -m venv ${venvFolder}`);
         await this.execute((stdout, stderr, exitCode) => {
@@ -18,6 +44,12 @@ export class Commando_Python3 extends Super {
         });
         return this;
     }
+    /**
+     * Installs Python packages from a requirements file.
+     *
+     * @param pathToRequirementsFile - Path to requirements.txt file (default: './requirements.txt')
+     * @returns This instance for method chaining
+     */
     async installRequirements(pathToRequirementsFile = './requirements.txt') {
         await this.append(`pip3 install -r ${pathToRequirementsFile}`)
             .execute();

package/shell/services/nvm.d.ts

@@ -1,5 +1,17 @@
 import { Logger } from '@nu-art/ts-common';
 import { Commando_NVM } from '../plugins/nvm.js';
+/**
+ * NVM (Node Version Manager) service for managing Node.js installations.
+ *
+ * Handles installation, version management, and configuration of NVM.
+ * Works with Commando_NVM plugin to execute NVM commands.
+ *
+ * **Features**:
+ * - Install/uninstall NVM
+ * - Configure shell RC files (.bashrc, .zshrc)
+ * - Version management
+ * - Integration with .nvmrc files
+ */
 export declare class Cli_NVM extends Logger {
     private _expectedVersion;
     private _homeEnvVar;
@@ -8,11 +20,57 @@ export declare class Cli_NVM extends Logger {
     set homeEnvVar(value: string);
     get expectedVersion(): string;
     set expectedVersion(value: string);
-    install: (commando: Commando_NVM) => Promise<boolean | this | undefined>;
+    /**
+     * Installs NVM and configures shell RC files.
+     *
+     * **Behavior**:
+     * - Checks if NVM is already installed with expected version
+     * - Uninstalls if version mismatch
+     * - Installs NVM via Commando_NVM
+     * - Configures .bashrc with NVM initialization (if not already present)
+     *
+     *
+     * @param commando - Commando_NVM instance to use for installation
+     * @returns This instance for method chaining
+     */
+    install: (commando: Commando_NVM) => Promise<this | undefined>;
+    /**
+     * Checks if NVM is installed.
+     *
+     * Verifies both environment variable and directory existence.
+     *
+     * @returns True if NVM is installed
+     */
     isInstalled: () => boolean;
+    /**
+     * Reads the required Node.js version from .nvmrc file.
+     *
+     * @returns Promise resolving to version string from .nvmrc
+     * @throws Error if .nvmrc file doesn't exist
+     */
     getRequiredNode_Version: () => Promise<string>;
+    /**
+     * Installs required Node.js version if not already installed.
+     *
+     * Reads .nvmrc, checks installed versions, and installs if missing.
+     *
+     * @param commando - Commando_NVM instance to use
+     * @returns True if version was installed, false if already present
+     */
     installRequiredVersionIfNeeded: (commando: Commando_NVM) => Promise<boolean>;
+    /**
+     * Uninstalls NVM by removing its directory.
+     *
+     * @returns Promise that resolves when uninstall completes
+     */
     uninstall: () => Promise<void>;
+    /**
+     * Installs a specific Node.js version via NVM.
+     *
+     * @param commando - Commando_NVM instance to use
+     * @param requiredVersion - Optional version (defaults to .nvmrc value)
+     * @returns Promise that resolves when installation completes
+     */
     private installVersion;
 }
 export declare const NVM: Cli_NVM;

package/shell/services/nvm.js

@@ -3,6 +3,18 @@ import { promises as _fs } from 'fs';
 import * as path from 'path';
 import { Logger, LogLevel } from '@nu-art/ts-common';
 const CONST__FILE_NVMRC = '.nvmrc';
+/**
+ * NVM (Node Version Manager) service for managing Node.js installations.
+ *
+ * Handles installation, version management, and configuration of NVM.
+ * Works with Commando_NVM plugin to execute NVM commands.
+ *
+ * **Features**:
+ * - Install/uninstall NVM
+ * - Configure shell RC files (.bashrc, .zshrc)
+ * - Version management
+ * - Integration with .nvmrc files
+ */
 export class Cli_NVM extends Logger {
     _expectedVersion = '0.39.7';
     _homeEnvVar = '$NVM_DIR';
@@ -22,6 +34,19 @@ export class Cli_NVM extends Logger {
     set expectedVersion(value) {
         this._expectedVersion = value;
     }
+    /**
+     * Installs NVM and configures shell RC files.
+     *
+     * **Behavior**:
+     * - Checks if NVM is already installed with expected version
+     * - Uninstalls if version mismatch
+     * - Installs NVM via Commando_NVM
+     * - Configures .bashrc with NVM initialization (if not already present)
+     *
+     *
+     * @param commando - Commando_NVM instance to use for installation
+     * @returns This instance for method chaining
+     */
     install = async (commando) => {
         if (this.isInstalled()) {
             const version = (await commando.getVersion()).trim();
@@ -34,18 +59,34 @@ export class Cli_NVM extends Logger {
         let rcFileContent = '';
         if (fs.existsSync(rcFile)) {
             rcFileContent = await _fs.readFile(rcFile, { encoding: 'utf8' });
-            return rcFileContent.includes('NVM_DIR');
+            // If NVM is already configured, don't add it again
+            if (rcFileContent.includes('NVM_DIR'))
+                return this;
         }
-        rcFileContent = `${rcFileContent}\n${rcFileContent.endsWith('\n') ? '' : '\n'}`;
+        // Append NVM initialization to the end of the file
+        rcFileContent = `${rcFileContent}${rcFileContent.endsWith('\n') ? '' : '\n'}`;
         rcFileContent += `# generated NVM - start\n`;
-        rcFileContent += `echo 'export NVM_DIR="$HOME/.nvm"'\n`;
-        rcFileContent += `echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm'\n`;
-        rcFileContent += `echo '[ -s "$NVM_DIR/bash_completion" ] && \\. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion'\n`;
+        rcFileContent += `export NVM_DIR="$HOME/.nvm"\n`;
+        rcFileContent += `[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm\n`;
+        rcFileContent += `[ -s "$NVM_DIR/bash_completion" ] && \\. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion\n`;
         rcFileContent += `# generated NVM - end\n`;
         await _fs.writeFile(rcFile, rcFileContent, { encoding: 'utf8' });
         return this;
     };
+    /**
+     * Checks if NVM is installed.
+     *
+     * Verifies both environment variable and directory existence.
+     *
+     * @returns True if NVM is installed
+     */
     isInstalled = () => !!process.env[this._homeEnvVar] && fs.existsSync(process.env[this._homeEnvVar]);
+    /**
+     * Reads the required Node.js version from .nvmrc file.
+     *
+     * @returns Promise resolving to version string from .nvmrc
+     * @throws Error if .nvmrc file doesn't exist
+     */
     getRequiredNode_Version = async () => {
         const absolutePathToNvmrcFile = path.resolve(CONST__FILE_NVMRC);
         if (!fs.existsSync(absolutePathToNvmrcFile))
@@ -53,6 +94,14 @@ export class Cli_NVM extends Logger {
         const content = await _fs.readFile(absolutePathToNvmrcFile, { encoding: 'utf-8' });
         return content.trim();
     };
+    /**
+     * Installs required Node.js version if not already installed.
+     *
+     * Reads .nvmrc, checks installed versions, and installs if missing.
+     *
+     * @param commando - Commando_NVM instance to use
+     * @returns True if version was installed, false if already present
+     */
     installRequiredVersionIfNeeded = async (commando) => {
         const requiredVersion = await this.getRequiredNode_Version();
         const installedVersions = await commando.getInstalledNodeVersions();
@@ -62,13 +111,25 @@ export class Cli_NVM extends Logger {
         await this.installVersion(commando, requiredVersion);
         return true;
     };
+    /**
+     * Uninstalls NVM by removing its directory.
+     *
+     * @returns Promise that resolves when uninstall completes
+     */
     uninstall = async () => {
-        this.logDebug('Uninstalling PNPM');
+        this.logDebug('Uninstalling NVM');
         const absolutePathToNVM_Home = process.env[this._homeEnvVar];
         if (!absolutePathToNVM_Home)
             return;
         fs.rmSync(absolutePathToNVM_Home, { recursive: true, force: true });
     };
+    /**
+     * Installs a specific Node.js version via NVM.
+     *
+     * @param commando - Commando_NVM instance to use
+     * @param requiredVersion - Optional version (defaults to .nvmrc value)
+     * @returns Promise that resolves when installation completes
+     */
     installVersion = async (commando, requiredVersion) => {
         requiredVersion ??= await this.getRequiredNode_Version();
         this.logDebug(`Installing version: ${requiredVersion}`);

package/shell/services/pnpm.d.ts

@@ -1,5 +1,17 @@
 import { Logger } from '@nu-art/ts-common';
 import { Commando_PNPM } from '../plugins/pnpm.js';
+/**
+ * PNPM package manager service for managing PNPM installations.
+ *
+ * Handles installation, version management, and package operations.
+ * Works with Commando_PNPM plugin to execute PNPM commands.
+ *
+ * **Features**:
+ * - Install/uninstall PNPM
+ * - Version management
+ * - Package installation
+ * - Environment variable configuration
+ */
 export declare class Cli_PNPM extends Logger {
     private _expectedVersion;
     private _homeEnvVar;
@@ -8,9 +20,38 @@ export declare class Cli_PNPM extends Logger {
     set homeEnvVar(value: string);
     get expectedVersion(): string;
     set expectedVersion(value: string);
+    /**
+     * Installs PNPM with the expected version.
+     *
+     * Checks if PNPM is already installed with the expected version.
+     * Uninstalls and reinstalls if version mismatch.
+     *
+     * @param commando - Commando_PNPM instance to use for installation
+     * @returns This instance for method chaining
+     */
     install: (commando: Commando_PNPM) => Promise<this | undefined>;
+    /**
+     * Checks if PNPM is installed.
+     *
+     * Verifies environment variable is set.
+     *
+     * @returns True if PNPM_HOME environment variable is set
+     */
     isInstalled: () => boolean;
+    /**
+     * Installs packages using PNPM.
+     *
+     * Delegates to Commando_PNPM.installPackages().
+     *
+     * @param commando - Commando_PNPM instance to use
+     * @returns Promise that resolves when packages are installed
+     */
     installPackages: (commando: Commando_PNPM) => Promise<Commando_PNPM>;
+    /**
+     * Uninstalls PNPM by removing its home directory.
+     *
+     * @returns Promise that resolves when uninstall completes
+     */
     uninstall: () => Promise<void>;
     /**
      * Asynchronously creates a workspace file with a list of packages.

package/shell/services/pnpm.js

@@ -1,6 +1,18 @@
 import { promises as fs } from 'fs';
 import { Logger, LogLevel } from '@nu-art/ts-common';
 import { convertToFullPath } from '../tools.js';
+/**
+ * PNPM package manager service for managing PNPM installations.
+ *
+ * Handles installation, version management, and package operations.
+ * Works with Commando_PNPM plugin to execute PNPM commands.
+ *
+ * **Features**:
+ * - Install/uninstall PNPM
+ * - Version management
+ * - Package installation
+ * - Environment variable configuration
+ */
 export class Cli_PNPM extends Logger {
     _expectedVersion = '10.7.0';
     _homeEnvVar = 'PNPM_HOME';
@@ -20,6 +32,15 @@ export class Cli_PNPM extends Logger {
     set expectedVersion(value) {
         this._expectedVersion = value;
     }
+    /**
+     * Installs PNPM with the expected version.
+     *
+     * Checks if PNPM is already installed with the expected version.
+     * Uninstalls and reinstalls if version mismatch.
+     *
+     * @param commando - Commando_PNPM instance to use for installation
+     * @returns This instance for method chaining
+     */
     install = async (commando) => {
         if (this.isInstalled()) {
             const version = (await commando.getVersion());
@@ -31,10 +52,30 @@ export class Cli_PNPM extends Logger {
         await commando.install(this._expectedVersion);
         return this;
     };
+    /**
+     * Checks if PNPM is installed.
+     *
+     * Verifies environment variable is set.
+     *
+     * @returns True if PNPM_HOME environment variable is set
+     */
     isInstalled = () => !!process.env[this._homeEnvVar];
+    /**
+     * Installs packages using PNPM.
+     *
+     * Delegates to Commando_PNPM.installPackages().
+     *
+     * @param commando - Commando_PNPM instance to use
+     * @returns Promise that resolves when packages are installed
+     */
     installPackages = async (commando) => {
         return await commando.installPackages();
     };
+    /**
+     * Uninstalls PNPM by removing its home directory.
+     *
+     * @returns Promise that resolves when uninstall completes
+     */
     uninstall = async () => {
         this.logDebug('Uninstalling PNPM');
         const absolutePathToPNPM_Home = process.env[this._homeEnvVar];

package/shell/simple/Commando.d.ts

@@ -1,17 +1,92 @@
 import { Constructor } from '@nu-art/ts-common';
 import { BaseCommando } from '../core/BaseCommando.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 declare class Commando extends BaseCommando {
+    /** Optional unique identifier for log tagging */
     private 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<T extends Constructor<any>[]>(...plugins: T): (import("../core/class-merger.js").MergeTypes<[typeof BaseCommando, typeof Commando, ...T]> & BaseCommando) & Commando;
     constructor();
+    /**
+     * 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: string): 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: string, interpreter?: string): Promise<{
         stdout: string;
         stderr: string;
     }>;
+    /**
+     * 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: string, interpreter: string): Promise<{
         stdout: string;
         stderr: string;
     }>;
+    /**
+     * 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
+     */
     execute<T>(callback?: (stdout: string, stderr: string, exitCode: number) => T): Promise<T | void>;
 }