@nu-art/commando 0.401.0 → 0.401.2

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

@@ -0,0 +1,41 @@
+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/plugins/python.js

@@ -0,0 +1,58 @@
+import { BaseCommando } from '../core/BaseCommando.js';
+import { Commando_Programming } from './programming.js';
+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) => {
+            if (exitCode !== 0)
+                throw new Exception(`Error installing VENV - exit code (${exitCode})`);
+        });
+        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();
+        return this;
+    }
+}

package/services/nvm.d.ts

@@ -0,0 +1,76 @@
+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;
+    constructor();
+    get homeEnvVar(): string;
+    set homeEnvVar(value: string);
+    get expectedVersion(): string;
+    set expectedVersion(value: string);
+    /**
+     * 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 → 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/services/pnpm.d.ts

@@ -0,0 +1,67 @@
+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;
+    constructor();
+    get homeEnvVar(): string;
+    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.
+     * Each package is listed under the 'packages:' section in the file.
+     *
+     * @param listOfLibs An array of library names to include in the workspace.
+     * @param pathToWorkspaceFolder The filesystem path where the workspace file will be written.
+     * @example
+     * await createWorkspace(['pack1', 'pack2'], './path/to/workspace.yaml');
+     */
+    createWorkspace: (listOfLibs: string[], pathToWorkspaceFolder?: string) => Promise<void>;
+}
+export declare const PNPM: Cli_PNPM;

package/{shell/services → 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/simple/Commando.d.ts

@@ -0,0 +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("../index.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>;
+}