@nu-art/commando 0.400.14 → 0.401.1

package/shell/plugins/basic.js

@@ -1,13 +1,31 @@
 import { BaseCommando } from '../core/BaseCommando.js';
 /**
- * Represents a Command Line Interface (CLI) to build and execute shell commands.
+ * Basic shell command plugin for Commando.
+ *
+ * Provides common file system and shell operations:
+ * - Directory navigation (`cd`, `pwd`)
+ * - File operations (`ls`, `cat`, `mkdir`, `rm`, `rmdir`, `cpdir`)
+ * - Variable assignment
+ * - Echo with options (escape sequences, file output)
+ *
+ * **Usage**: Merge with BaseCommando or other Commando classes to add
+ * these methods. Typically included via `CommandoPool.allocateCommando()`.
  */
 export class Commando_Basic extends BaseCommando {
     /**
-     * Changes directory and optionally executes a block of commands in that directory.
-     * @param {string} folderName - Name of the directory to change to.
-     * @param {CliBlock} [toRun] - Optional block of commands to execute in the directory.
-     * @returns {this} - The Cli instance for method chaining.
+     * Changes directory and optionally executes commands in that directory.
+     *
+     * **Behavior**:
+     * - Changes to the specified directory
+     * - Increases indentation (for script readability)
+     * - If `toRun` provided, executes the block and returns to previous directory
+     * - If `toRun` not provided, caller must call `cd_()` to return
+     *
+     * **Note**: Uses `cd -` to return to previous directory (OLDPWD).
+     *
+     * @param folderName - Directory path to change to
+     * @param toRun - Optional command block to execute in the directory
+     * @returns This instance for method chaining
      */
     cd(folderName, toRun) {
         this.append(`cd ${folderName}`);
@@ -18,6 +36,15 @@ export class Commando_Basic extends BaseCommando {
         }
         return this;
     }
+    /**
+     * Appends a custom command string.
+     *
+     * Allows adding arbitrary shell commands that aren't covered by
+     * the built-in methods.
+     *
+     * @param command - Custom shell command to append
+     * @returns This instance for method chaining
+     */
     custom(command) {
         this.append(command);
         return this;
@@ -40,10 +67,25 @@ export class Commando_Basic extends BaseCommando {
         this.append(`ls ${params}`);
         return this;
     }
+    /**
+     * Creates a directory (with parent directories if needed).
+     *
+     * Uses `mkdir -p` to create directory and all parent directories.
+     *
+     * @param dirName - Directory path to create
+     * @returns This instance for method chaining
+     */
     mkdir(dirName) {
         this.append(`mkdir -p ${dirName}`);
         return this;
     }
+    /**
+     * Removes a file or directory.
+     *
+     * @param dirPath - Path to remove
+     * @param options - Optional force flag
+     * @returns This instance for method chaining
+     */
     rm(dirPath, options) {
         let command = 'rm';
         if (options?.force)
@@ -51,6 +93,13 @@ export class Commando_Basic extends BaseCommando {
         this.append(`${command} ${dirPath}`);
         return this;
     }
+    /**
+     * Removes a directory recursively.
+     *
+     * @param dirPath - Directory path to remove
+     * @param options - Optional force flag
+     * @returns This instance for method chaining
+     */
     rmdir(dirPath, options) {
         let command = 'rm -r';
         if (options?.force)
@@ -58,6 +107,14 @@ export class Commando_Basic extends BaseCommando {
         this.append(`${command} ${dirPath}`);
         return this;
     }
+    /**
+     * Copies a directory.
+     *
+     * @param srcPath - Source directory path
+     * @param destPath - Destination directory path
+     * @param options - Optional contentOnly flag (copies contents, not directory itself)
+     * @returns This instance for method chaining
+     */
     cpdir(srcPath, destPath, options) {
         let command = `cp -r ${srcPath}`;
         if (options?.contentOnly)
@@ -66,10 +123,31 @@ export class Commando_Basic extends BaseCommando {
         this.append(command);
         return this;
     }
+    /**
+     * Displays file contents.
+     *
+     * @param fileName - File path to display
+     * @returns This instance for method chaining
+     */
     cat(fileName) {
         this.append(`cat ${fileName}`);
         return this;
     }
+    /**
+     * Echoes text with optional escape sequences and file output.
+     *
+     * **Escape Sequences**: When `escape` is true, enables interpretation
+     * of backslash escapes (e.g., `\n`, `\t`).
+     *
+     * **File Output**: Can append or overwrite to a file.
+     *
+     * **Escaping**: Automatically escapes backslashes, newlines, and tabs
+     * in the log string for safe shell execution.
+     *
+     * @param log - Text to echo
+     * @param options - Optional echo configuration
+     * @returns This instance for method chaining
+     */
     echo(log, options) {
         const _escape = options?.escape ? '-e' : '';
         const _toFile = options?.toFile ? `>${options.toFile.append ? '>' : ''} ${options.toFile.name}` : '';
@@ -86,10 +164,13 @@ export class Commando_Basic extends BaseCommando {
         return this;
     }
     /**
-     * Assigns a value to a variable in the script.
-     * @param {string} varName - The name of the variable.
-     * @param {string | string[]} value - The value to assign to the variable.
-     * @returns {this} - The Cli instance for method chaining.
+     * Assigns a value to a shell variable (array or scalar).
+     *
+     * Creates a bash array if value is an array, otherwise creates a scalar variable.
+     *
+     * @param varName - Variable name
+     * @param value - Value(s) to assign (string or array of strings)
+     * @returns This instance for method chaining
      */
     assignVar(varName, value) {
         this.append(`${varName}=(${Array.isArray(value) ? value : [value].join(' ')})`);

package/shell/plugins/git.d.ts

@@ -13,6 +13,23 @@ type GitPushParams = {
     tags?: boolean;
     force?: boolean;
 };
+/**
+ * Git operations plugin for Commando.
+ *
+ * Provides Git command methods via a fluent API. Extends Commando_Programming
+ * and Commando_Basic (merged via class-merger).
+ *
+ * **Usage**: Access via `git()` method which returns an object with all
+ * Git operations. Methods build commands but don't execute them until
+ * `execute()` is called.
+ *
+ * **Operations**:
+ * - Repository operations: clone, fetch, pull, push
+ * - Branch operations: checkout, create, merge, get current
+ * - Commit operations: add, commit, addAndCommit
+ * - Tag operations: create, push
+ * - Utility: status, resetHard, gsui (git status UI)
+ */
 export declare class Commando_Git extends Super {
     git(): {
         clone: (url: string, options?: GitCloneParams) => this;
@@ -33,22 +50,120 @@ export declare class Commando_Git extends Super {
         gsui: (modules?: string) => this;
         status: () => this;
     };
+    /**
+     * Clones a Git repository.
+     *
+     * @param url - Repository URL to clone
+     * @param options - Optional clone parameters (branch, recursive, output folder)
+     * @returns This instance for method chaining
+     */
     git_clone(url: string, options?: GitCloneParams): this;
+    /**
+     * Checks out a branch.
+     *
+     * @param branch - Branch name to checkout
+     * @returns This instance for method chaining
+     */
     git_checkout(branch: string): this;
+    /**
+     * Creates or updates a tag (force).
+     *
+     * @param tagName - Tag name to create/update
+     * @returns This instance for method chaining
+     */
     git_createTag(tagName: string): this;
+    /**
+     * Commits changes with a message.
+     *
+     * @param commitMessage - Commit message
+     * @returns This instance for method chaining
+     */
     git_gitCommit(commitMessage: string): this;
+    /**
+     * Stages a specific file.
+     *
+     * @param file - File path to stage
+     * @returns This instance for method chaining
+     */
     git_add(file: string): this;
+    /**
+     * Stages all files in the current directory.
+     *
+     * @returns This instance for method chaining
+     */
     git_addAll(): this;
+    /**
+     * Stages all files and commits with a message.
+     *
+     * @param commitMessage - Commit message
+     * @returns This instance for method chaining
+     */
     git_addAndCommit(commitMessage: string): this;
+    /**
+     * Pushes to a remote branch.
+     *
+     * @param options - Push parameters (remote, branch, tags, force)
+     * @returns This instance for method chaining
+     */
     git_push(options?: GitPushParams): this;
+    /**
+     * Pushes all tags to remote (force).
+     *
+     * @returns This instance for method chaining
+     */
     git_pushTags(): this;
+    /**
+     * Fetches from remote.
+     *
+     * @returns This instance for method chaining
+     */
     git_fetch(): this;
+    /**
+     * Resets repository to a specific tag/commit (hard reset).
+     *
+     * @param tag - Optional tag or commit hash (default: empty string)
+     * @returns This instance for method chaining
+     */
     git_resetHard(tag?: string): this;
+    /**
+     * Gets the current branch name.
+     *
+     * @returns This instance for method chaining
+     */
     git_getCurrentBranch(): this;
+    /**
+     * Pulls from remote with optional parameters.
+     *
+     * @param params - Optional pull parameters
+     * @returns This instance for method chaining
+     */
     git_pull(params: string): this;
+    /**
+     * Merges a branch into the current branch.
+     *
+     * @param mergeFrom - Branch to merge from
+     * @returns This instance for method chaining
+     */
     git_merge(mergeFrom: string): this;
+    /**
+     * Creates a new branch and sets upstream.
+     *
+     * @param branch - Branch name to create
+     * @returns This instance for method chaining
+     */
     git_createBranch(branch: string): this;
+    /**
+     * Updates git submodules (recursive, init if needed).
+     *
+     * @param modules - Optional module paths (default: empty string)
+     * @returns This instance for method chaining
+     */
     git_gsui(modules?: string): this;
+    /**
+     * Shows git status.
+     *
+     * @returns This instance for method chaining
+     */
     git_status(): this;
 }
 export {};

package/shell/plugins/git.js

@@ -3,6 +3,23 @@ import { Commando_Basic } from './basic.js';
 import { MergeClass } from '../core/class-merger.js';
 import { BaseCommando } from '../core/BaseCommando.js';
 const Super = MergeClass(BaseCommando, Commando_Programming, Commando_Basic);
+/**
+ * Git operations plugin for Commando.
+ *
+ * Provides Git command methods via a fluent API. Extends Commando_Programming
+ * and Commando_Basic (merged via class-merger).
+ *
+ * **Usage**: Access via `git()` method which returns an object with all
+ * Git operations. Methods build commands but don't execute them until
+ * `execute()` is called.
+ *
+ * **Operations**:
+ * - Repository operations: clone, fetch, pull, push
+ * - Branch operations: checkout, create, merge, get current
+ * - Commit operations: add, commit, addAndCommit
+ * - Tag operations: create, push
+ * - Utility: status, resetHard, gsui (git status UI)
+ */
 export class Commando_Git extends Super {
     git() {
         return {
@@ -26,6 +43,13 @@ export class Commando_Git extends Super {
         };
     }
     ;
+    /**
+     * Clones a Git repository.
+     *
+     * @param url - Repository URL to clone
+     * @param options - Optional clone parameters (branch, recursive, output folder)
+     * @returns This instance for method chaining
+     */
     git_clone(url, options) {
         const branch = `${options?.branch ? ` -b ${options?.branch}` : ''}`;
         const recursive = `${options?.recursive ? ` --recursive` : ''}`;
@@ -52,52 +76,143 @@ export class Commando_Git extends Super {
     // 			});
     // 	});
     // }
+    /**
+     * Checks out a branch.
+     *
+     * @param branch - Branch name to checkout
+     * @returns This instance for method chaining
+     */
     git_checkout(branch) {
         return this.append(`git checkout ${branch}`);
     }
+    /**
+     * Creates or updates a tag (force).
+     *
+     * @param tagName - Tag name to create/update
+     * @returns This instance for method chaining
+     */
     git_createTag(tagName) {
         return this.append(`git tag -f ${tagName}`);
     }
+    /**
+     * Commits changes with a message.
+     *
+     * @param commitMessage - Commit message
+     * @returns This instance for method chaining
+     */
     git_gitCommit(commitMessage) {
         return this.append(`git commit -m "${commitMessage}"`);
     }
+    /**
+     * Stages a specific file.
+     *
+     * @param file - File path to stage
+     * @returns This instance for method chaining
+     */
     git_add(file) {
         return this.append(`git add "${file}"`);
     }
+    /**
+     * Stages all files in the current directory.
+     *
+     * @returns This instance for method chaining
+     */
     git_addAll() {
         return this.append(`git add .`);
     }
+    /**
+     * Stages all files and commits with a message.
+     *
+     * @param commitMessage - Commit message
+     * @returns This instance for method chaining
+     */
     git_addAndCommit(commitMessage) {
         return this.append(`git commit -am "${commitMessage}"`);
     }
+    /**
+     * Pushes to a remote branch.
+     *
+     * @param options - Push parameters (remote, branch, tags, force)
+     * @returns This instance for method chaining
+     */
     git_push(options) {
         return this.append(`git push ${options?.remote ?? ''} ${options?.branch ?? ''}`);
     }
+    /**
+     * Pushes all tags to remote (force).
+     *
+     * @returns This instance for method chaining
+     */
     git_pushTags() {
         return this.append('git push --tags --force');
     }
+    /**
+     * Fetches from remote.
+     *
+     * @returns This instance for method chaining
+     */
     git_fetch() {
         return this.append('git fetch');
     }
+    /**
+     * Resets repository to a specific tag/commit (hard reset).
+     *
+     * @param tag - Optional tag or commit hash (default: empty string)
+     * @returns This instance for method chaining
+     */
     git_resetHard(tag = '') {
-        return this.append('git reset --hard ${tag}');
+        return this.append(`git reset --hard ${tag}`);
     }
+    /**
+     * Gets the current branch name.
+     *
+     * @returns This instance for method chaining
+     */
     git_getCurrentBranch() {
-        return this.append('git status | grep "On branch" | sed -E "s');
-    }
+        return this.append(`git status | grep "On branch" | sed -E "s/On branch //"`);
+    }
+    /**
+     * Pulls from remote with optional parameters.
+     *
+     * @param params - Optional pull parameters
+     * @returns This instance for method chaining
+     */
     git_pull(params) {
-        return this.append('git pull ${params}');
-    }
+        return this.append(`git pull ${params}`);
+    }
+    /**
+     * Merges a branch into the current branch.
+     *
+     * @param mergeFrom - Branch to merge from
+     * @returns This instance for method chaining
+     */
     git_merge(mergeFrom) {
         return this.append(`git merge ${mergeFrom}`);
     }
+    /**
+     * Creates a new branch and sets upstream.
+     *
+     * @param branch - Branch name to create
+     * @returns This instance for method chaining
+     */
     git_createBranch(branch) {
-        return this.append(`git checkout - b ${branch}`)
-            .append(`git push-- set -upstream origin ${branch}`);
-    }
+        return this.append(`git checkout -b ${branch}`)
+            .append(`git push --set-upstream origin ${branch}`);
+    }
+    /**
+     * Updates git submodules (recursive, init if needed).
+     *
+     * @param modules - Optional module paths (default: empty string)
+     * @returns This instance for method chaining
+     */
     git_gsui(modules = '') {
-        return this.append('git submodule update --recursive --init ${modules}');
+        return this.append(`git submodule update --recursive --init ${modules}`);
     }
+    /**
+     * Shows git status.
+     *
+     * @returns This instance for method chaining
+     */
     git_status() {
         return this.append('git status');
     }

package/shell/plugins/nvm.d.ts

@@ -2,11 +2,58 @@ 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>;
+/**
+ * NVM (Node Version Manager) plugin for Commando.
+ *
+ * Provides NVM operations for managing Node.js versions:
+ * - Install NVM
+ * - Apply NVM to shell session
+ * - Install specific Node.js versions
+ * - Get installed Node.js versions
+ *
+ * Extends Commando_Programming and Commando_Basic (merged).
+ */
 export declare class Commando_NVM extends Super {
+    /**
+     * Applies NVM to the shell session.
+     *
+     * Exports NVM_DIR, sources nvm.sh, and runs `nvm use`.
+     * Must be called before using NVM commands in an interactive shell.
+     *
+     * @returns This instance for method chaining
+     */
     applyNVM(): this;
+    /**
+     * Installs NVM by downloading and executing the install script.
+     *
+     * @param version - NVM version to install
+     * @returns This instance for method chaining
+     * @throws Exception if installation fails (non-zero exit code)
+     */
     install(version: string): Promise<this>;
+    /**
+     * Gets the installed NVM version.
+     *
+     * Only executes if NVM is available (checks with `command -v nvm`).
+     *
+     * @returns Promise resolving to NVM version string
+     */
     getVersion(): Promise<string>;
+    /**
+     * Installs a specific Node.js version via NVM.
+     *
+     * @param requiredVersion - Node.js version to install (e.g., '18.0.0')
+     * @returns This instance for method chaining
+     */
     installNodeVersion(requiredVersion: string): Promise<this>;
+    /**
+     * Gets all installed Node.js versions.
+     *
+     * Parses `nvm ls` output to extract version numbers, removing ANSI codes
+     * and filtering out invalid entries.
+     *
+     * @returns Promise resolving to array of version strings (without 'v' prefix)
+     */
     getInstalledNodeVersions: () => Promise<(string | undefined)[]>;
 }
 export {};

package/shell/plugins/nvm.js

@@ -5,13 +5,39 @@ import { Commando_Basic } from './basic.js';
 import { Exception, filterDuplicates } from '@nu-art/ts-common';
 import { removeAnsiCodes } from '../tools.js';
 const Super = MergeClass(BaseCommando, Commando_Programming, Commando_Basic);
+/**
+ * NVM (Node Version Manager) plugin for Commando.
+ *
+ * Provides NVM operations for managing Node.js versions:
+ * - Install NVM
+ * - Apply NVM to shell session
+ * - Install specific Node.js versions
+ * - Get installed Node.js versions
+ *
+ * Extends Commando_Programming and Commando_Basic (merged).
+ */
 export class Commando_NVM extends Super {
+    /**
+     * Applies NVM to the shell session.
+     *
+     * Exports NVM_DIR, sources nvm.sh, and runs `nvm use`.
+     * Must be called before using NVM commands in an interactive shell.
+     *
+     * @returns This instance for method chaining
+     */
     applyNVM() {
         this.append('export NVM_DIR="$HOME/.nvm"')
             .append('[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"  # This loads nvm')
             .append('nvm use');
         return this;
     }
+    /**
+     * Installs NVM by downloading and executing the install script.
+     *
+     * @param version - NVM version to install
+     * @returns This instance for method chaining
+     * @throws Exception if installation fails (non-zero exit code)
+     */
     async install(version) {
         this.append(`curl -o- "https://raw.githubusercontent.com/nvm-sh/nvm/v${version}/install.sh" | bash`);
         await this.execute((stdout, stderr, exitCode) => {
@@ -20,16 +46,37 @@ export class Commando_NVM extends Super {
         });
         return this;
     }
+    /**
+     * Gets the installed NVM version.
+     *
+     * Only executes if NVM is available (checks with `command -v nvm`).
+     *
+     * @returns Promise resolving to NVM version string
+     */
     async getVersion() {
         return this.if('[[ -x "$(command -v nvm)" ]]', (commando) => {
             commando.append('nvm --version');
         }).execute((stdout) => stdout);
     }
+    /**
+     * Installs a specific Node.js version via NVM.
+     *
+     * @param requiredVersion - Node.js version to install (e.g., '18.0.0')
+     * @returns This instance for method chaining
+     */
     async installNodeVersion(requiredVersion) {
         await this.append(`nvm install ${requiredVersion}`)
             .execute();
         return this;
     }
+    /**
+     * Gets all installed Node.js versions.
+     *
+     * Parses `nvm ls` output to extract version numbers, removing ANSI codes
+     * and filtering out invalid entries.
+     *
+     * @returns Promise resolving to array of version strings (without 'v' prefix)
+     */
     getInstalledNodeVersions = async () => {
         function extractInstalledVersions(rawOutput) {
             const cleanedOutput = removeAnsiCodes(rawOutput);

package/shell/plugins/pnpm.d.ts

@@ -3,9 +3,40 @@ import { Commando_Basic } from './basic.js';
 import { Commando_Programming } from './programming.js';
 import { Commando_NVM } from './nvm.js';
 declare const Super: import("@nu-art/ts-common").Constructor<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 declare 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
+     */
     installPackages(): Promise<this>;
+    /**
+     * Installs PNPM by downloading and executing the install script.
+     *
+     * @param version - PNPM version to install
+     * @returns This instance for method chaining
+     */
     install(version: string): Promise<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)
+     */
     getVersion(): Promise<string>;
 }
 export {};