@nu-art/commando 0.401.0 → 0.401.2

package/plugins/git.d.ts

@@ -0,0 +1,169 @@
+import { Commando_Programming } from './programming.js';
+import { Commando_Basic } from './basic.js';
+import { BaseCommando } from '../core/BaseCommando.js';
+declare const Super: import("@nu-art/ts-common").Constructor<BaseCommando & Commando_Programming & Commando_Basic>;
+type GitCloneParams = {
+    outputFolder?: string;
+    branch?: string;
+    recursive?: boolean;
+};
+type GitPushParams = {
+    remote: string;
+    branch: string;
+    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;
+        checkout: (branch: string) => this;
+        createTag: (tagName: string) => this;
+        gitCommit: (commitMessage: string) => this;
+        add: (file: string) => this;
+        addAll: () => this;
+        addAndCommit: (commitMessage: string) => this;
+        push: (options?: GitPushParams) => this;
+        pushTags: () => this;
+        fetch: () => this;
+        resetHard: (tag?: string) => this;
+        getCurrentBranch: () => this;
+        pull: (params: string) => this;
+        merge: (mergeFrom: string) => this;
+        createBranch: (branch: string) => this;
+        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/plugins/git.js

@@ -0,0 +1,219 @@
+import { Commando_Programming } from './programming.js';
+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 {
+            clone: this.git_clone,
+            checkout: this.git_checkout,
+            createTag: this.git_createTag,
+            gitCommit: this.git_gitCommit,
+            add: this.git_add,
+            addAll: this.git_addAll,
+            addAndCommit: this.git_addAndCommit,
+            push: this.git_push,
+            pushTags: this.git_pushTags,
+            fetch: this.git_fetch,
+            resetHard: this.git_resetHard,
+            getCurrentBranch: this.git_getCurrentBranch,
+            pull: this.git_pull,
+            merge: this.git_merge,
+            createBranch: this.git_createBranch,
+            gsui: this.git_gsui,
+            status: this.git_status,
+        };
+    }
+    ;
+    /**
+     * 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` : ''}`;
+        const outputFolder = `${options?.outputFolder ? ` ${options.outputFolder}` : ''}`;
+        const command = `git clone${recursive}${branch} ${url}${outputFolder}`;
+        return this.append(command);
+    }
+    // git_cloneAssert(url: string, options?: GitCloneParams) {
+    // 	return new Promise<void>((resolve, reject) => {
+    // 		const branch = `${options?.branch ? ` -b ${options?.branch}` : ''}`;
+    // 		const recursive = `${options?.recursive ? ` --recursive` : ''}`;
+    // 		const outputFolder = `${options?.outputFolder ? ` ${options.outputFolder}` : ''}`;
+    // 		const command = `git clone${recursive}${branch} ${url}${outputFolder}`;
+    // 		this.echo(command);
+    // 		this.append(command)
+    // 			.execute((stdout: string, stderr: string, exitCode: number) => {
+    // 				if (exitCode === 0)
+    // 					return resolve();
+    //
+    // 				if (exitCode === 128)
+    // 					return reject(new Error(`No access to repo: ${url}`));
+    //
+    // 				return reject(new Error(`Got unexpected exit code(${exitCode}) while cloning: ${url}`));
+    // 			});
+    // 	});
+    // }
+    /**
+     * 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}`);
+    }
+    /**
+     * Gets the current branch name.
+     *
+     * @returns This instance for method chaining
+     */
+    git_getCurrentBranch() {
+        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}`);
+    }
+    /**
+     * 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}`);
+    }
+    /**
+     * 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}`);
+    }
+    /**
+     * Shows git status.
+     *
+     * @returns This instance for method chaining
+     */
+    git_status() {
+        return this.append('git status');
+    }
+}

package/plugins/nvm.d.ts

@@ -0,0 +1,59 @@
+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 → 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/plugins/pnpm.d.ts

@@ -0,0 +1,42 @@
+import { BaseCommando } from '../core/BaseCommando.js';
+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 {};

package/{shell/plugins → 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 → 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;
 }