@versatiles/release-tool 2.6.0 → 2.7.0

package/dist/lib/shell.d.ts

@@ -1,23 +1,138 @@
+/**
+ * Result of a shell command execution.
+ */
+export interface ShellResult {
+    /** Exit code of the process, or null if terminated by signal. */
+    code: number | null;
+    /** Signal that terminated the process, or null if exited normally. */
+    signal: string | null;
+    /** Captured standard output. */
+    stdout: string;
+    /** Captured standard error. */
+    stderr: string;
+}
+/**
+ * Result of an interactive shell command execution.
+ */
+export interface ShellInteractiveResult {
+    /** Exit code of the process, or null if terminated by signal. */
+    code: number | null;
+    /** Signal that terminated the process, or null if exited normally. */
+    signal: string | null;
+}
+/**
+ * A utility class for executing shell commands in a specified working directory.
+ * Provides methods for running commands with captured output, interactive commands,
+ * and convenience methods for common patterns.
+ *
+ * @example
+ * ```ts
+ * const shell = new Shell('/path/to/project');
+ * const output = await shell.stdout('git status');
+ * const success = await shell.ok('npm test');
+ * ```
+ */
 export declare class Shell {
+    /** The working directory for all commands. */
     private cwd;
+    /**
+     * Creates a new Shell instance.
+     *
+     * @param cwd - The working directory for executing commands.
+     */
     constructor(cwd: string);
-    run(command: string, errorOnCodeNonZero?: boolean): Promise<{
-        code: number | null;
-        signal: string | null;
-        stdout: string;
-        stderr: string;
-    }>;
-    exec(command: string, args: string[], errorOnCodeNonZero?: boolean, skipLog?: boolean): Promise<{
-        code: number | null;
-        signal: string | null;
-        stdout: string;
-        stderr: string;
-    }>;
-    runInteractive(command: string, errorOnCodeNonZero?: boolean): Promise<{
-        code: number | null;
-        signal: string | null;
-    }>;
+    /**
+     * Runs a shell command through bash and captures its output.
+     *
+     * @remarks
+     * **⚠️ SECURITY WARNING: Command Injection Risk**
+     *
+     * This method passes the command string directly to `bash -c`, which means
+     * shell metacharacters (`;`, `|`, `$()`, `` ` ``, etc.) are interpreted.
+     *
+     * **NEVER** pass unsanitized user input to this method:
+     * ```ts
+     * // DANGEROUS - command injection vulnerability!
+     * shell.run(`git checkout ${userInput}`);  // userInput could be "; rm -rf /"
+     *
+     * // SAFE - use exec() with array arguments instead
+     * shell.exec('git', ['checkout', userInput]);
+     * ```
+     *
+     * Only use this method with:
+     * - Hardcoded command strings
+     * - Values that have been strictly validated (e.g., version numbers matching `/^\d+\.\d+\.\d+$/`)
+     *
+     * For commands with dynamic arguments, prefer {@link Shell.exec} which passes
+     * arguments directly without shell interpretation.
+     *
+     * @param command - The shell command to execute. Must be a trusted string.
+     * @param errorOnCodeNonZero - If true (default), rejects the promise on non-zero exit code.
+     * @returns A promise resolving to the command result with exit code, signal, stdout, and stderr.
+     * @throws Rejects with the result object if errorOnCodeNonZero is true and exit code is non-zero.
+     */
+    run(command: string, errorOnCodeNonZero?: boolean): Promise<ShellResult>;
+    /**
+     * Executes a command with arguments directly, avoiding shell escaping issues.
+     * Preferred over `run()` when dealing with arguments that may contain special characters.
+     *
+     * @param command - The command executable to run.
+     * @param args - Array of arguments to pass to the command.
+     * @param errorOnCodeNonZero - If true (default), rejects the promise on non-zero exit code.
+     * @param skipLog - If true, suppresses debug logging of the command.
+     * @returns A promise resolving to the command result with exit code, signal, stdout, and stderr.
+     * @throws Rejects with the result object if errorOnCodeNonZero is true and exit code is non-zero.
+     */
+    exec(command: string, args: string[], errorOnCodeNonZero?: boolean, skipLog?: boolean): Promise<ShellResult>;
+    /**
+     * Runs a command interactively with full TTY passthrough.
+     * The user can interact with the command's stdin/stdout/stderr directly.
+     * Useful for commands that require user input (e.g., npm publish with OTP).
+     *
+     * @remarks
+     * **⚠️ SECURITY WARNING:** Same command injection risks as {@link Shell.run}.
+     * Never pass unsanitized user input. See {@link Shell.run} for details.
+     *
+     * @param command - The shell command to execute. Must be a trusted string.
+     * @param errorOnCodeNonZero - If true (default), rejects the promise on non-zero exit code.
+     * @returns A promise resolving to the exit code and signal (no captured output).
+     * @throws Rejects with the result object if errorOnCodeNonZero is true and exit code is non-zero.
+     */
+    runInteractive(command: string, errorOnCodeNonZero?: boolean): Promise<ShellInteractiveResult>;
+    /**
+     * Runs a command and returns only the trimmed stderr output.
+     *
+     * @remarks
+     * **⚠️ SECURITY WARNING:** Uses {@link Shell.run} internally.
+     * Never pass unsanitized user input. See {@link Shell.run} for details.
+     *
+     * @param command - The shell command to execute. Must be a trusted string.
+     * @param errorOnCodeZero - If true (default), rejects on non-zero exit code.
+     * @returns A promise resolving to the trimmed stderr string.
+     */
     stderr(command: string, errorOnCodeZero?: boolean): Promise<string>;
+    /**
+     * Runs a command and returns only the trimmed stdout output.
+     *
+     * @remarks
+     * **⚠️ SECURITY WARNING:** Uses {@link Shell.run} internally.
+     * Never pass unsanitized user input. See {@link Shell.run} for details.
+     *
+     * @param command - The shell command to execute. Must be a trusted string.
+     * @param errorOnCodeZero - If true (default), rejects on non-zero exit code.
+     * @returns A promise resolving to the trimmed stdout string.
+     */
     stdout(command: string, errorOnCodeZero?: boolean): Promise<string>;
+    /**
+     * Runs a command and returns whether it succeeded (exit code 0).
+     * Never throws on non-zero exit codes.
+     *
+     * @remarks
+     * **⚠️ SECURITY WARNING:** Uses {@link Shell.run} internally.
+     * Never pass unsanitized user input. See {@link Shell.run} for details.
+     *
+     * @param command - The shell command to execute. Must be a trusted string.
+     * @returns A promise resolving to true if exit code is 0, false otherwise.
+     */
     ok(command: string): Promise<boolean>;
 }

package/dist/lib/shell.js

@@ -1,15 +1,73 @@
 import { spawn } from 'child_process';
 import { debug, isVerbose } from './log.js';
+/**
+ * A utility class for executing shell commands in a specified working directory.
+ * Provides methods for running commands with captured output, interactive commands,
+ * and convenience methods for common patterns.
+ *
+ * @example
+ * ```ts
+ * const shell = new Shell('/path/to/project');
+ * const output = await shell.stdout('git status');
+ * const success = await shell.ok('npm test');
+ * ```
+ */
 export class Shell {
+    /** The working directory for all commands. */
     cwd;
+    /**
+     * Creates a new Shell instance.
+     *
+     * @param cwd - The working directory for executing commands.
+     */
     constructor(cwd) {
         this.cwd = cwd;
     }
+    /**
+     * Runs a shell command through bash and captures its output.
+     *
+     * @remarks
+     * **⚠️ SECURITY WARNING: Command Injection Risk**
+     *
+     * This method passes the command string directly to `bash -c`, which means
+     * shell metacharacters (`;`, `|`, `$()`, `` ` ``, etc.) are interpreted.
+     *
+     * **NEVER** pass unsanitized user input to this method:
+     * ```ts
+     * // DANGEROUS - command injection vulnerability!
+     * shell.run(`git checkout ${userInput}`);  // userInput could be "; rm -rf /"
+     *
+     * // SAFE - use exec() with array arguments instead
+     * shell.exec('git', ['checkout', userInput]);
+     * ```
+     *
+     * Only use this method with:
+     * - Hardcoded command strings
+     * - Values that have been strictly validated (e.g., version numbers matching `/^\d+\.\d+\.\d+$/`)
+     *
+     * For commands with dynamic arguments, prefer {@link Shell.exec} which passes
+     * arguments directly without shell interpretation.
+     *
+     * @param command - The shell command to execute. Must be a trusted string.
+     * @param errorOnCodeNonZero - If true (default), rejects the promise on non-zero exit code.
+     * @returns A promise resolving to the command result with exit code, signal, stdout, and stderr.
+     * @throws Rejects with the result object if errorOnCodeNonZero is true and exit code is non-zero.
+     */
     async run(command, errorOnCodeNonZero = true) {
         debug(`$ ${command}`);
         return this.exec('bash', ['-c', command], errorOnCodeNonZero, true);
     }
-    // Execute a command with arguments directly, avoiding shell escaping issues
+    /**
+     * Executes a command with arguments directly, avoiding shell escaping issues.
+     * Preferred over `run()` when dealing with arguments that may contain special characters.
+     *
+     * @param command - The command executable to run.
+     * @param args - Array of arguments to pass to the command.
+     * @param errorOnCodeNonZero - If true (default), rejects the promise on non-zero exit code.
+     * @param skipLog - If true, suppresses debug logging of the command.
+     * @returns A promise resolving to the command result with exit code, signal, stdout, and stderr.
+     * @throws Rejects with the result object if errorOnCodeNonZero is true and exit code is non-zero.
+     */
     async exec(command, args, errorOnCodeNonZero = true, skipLog = false) {
         if (!skipLog) {
             debug(`$ ${command} ${args.join(' ')}`);
@@ -44,7 +102,20 @@ export class Shell {
             cp.stderr.on('data', (chunk) => stderr.push(chunk));
         });
     }
-    // Runs a command interactively, so the user can interact with stdin/stdout/stderr directly.
+    /**
+     * Runs a command interactively with full TTY passthrough.
+     * The user can interact with the command's stdin/stdout/stderr directly.
+     * Useful for commands that require user input (e.g., npm publish with OTP).
+     *
+     * @remarks
+     * **⚠️ SECURITY WARNING:** Same command injection risks as {@link Shell.run}.
+     * Never pass unsanitized user input. See {@link Shell.run} for details.
+     *
+     * @param command - The shell command to execute. Must be a trusted string.
+     * @param errorOnCodeNonZero - If true (default), rejects the promise on non-zero exit code.
+     * @returns A promise resolving to the exit code and signal (no captured output).
+     * @throws Rejects with the result object if errorOnCodeNonZero is true and exit code is non-zero.
+     */
     async runInteractive(command, errorOnCodeNonZero = true) {
         return await new Promise((resolve, reject) => {
             const cp = spawn('bash', ['-c', command], {
@@ -63,14 +134,47 @@ export class Shell {
             });
         });
     }
+    /**
+     * Runs a command and returns only the trimmed stderr output.
+     *
+     * @remarks
+     * **⚠️ SECURITY WARNING:** Uses {@link Shell.run} internally.
+     * Never pass unsanitized user input. See {@link Shell.run} for details.
+     *
+     * @param command - The shell command to execute. Must be a trusted string.
+     * @param errorOnCodeZero - If true (default), rejects on non-zero exit code.
+     * @returns A promise resolving to the trimmed stderr string.
+     */
     async stderr(command, errorOnCodeZero) {
         const result = await this.run(command, errorOnCodeZero);
         return result.stderr.trim();
     }
+    /**
+     * Runs a command and returns only the trimmed stdout output.
+     *
+     * @remarks
+     * **⚠️ SECURITY WARNING:** Uses {@link Shell.run} internally.
+     * Never pass unsanitized user input. See {@link Shell.run} for details.
+     *
+     * @param command - The shell command to execute. Must be a trusted string.
+     * @param errorOnCodeZero - If true (default), rejects on non-zero exit code.
+     * @returns A promise resolving to the trimmed stdout string.
+     */
     async stdout(command, errorOnCodeZero) {
         const result = await this.run(command, errorOnCodeZero);
         return result.stdout.trim();
     }
+    /**
+     * Runs a command and returns whether it succeeded (exit code 0).
+     * Never throws on non-zero exit codes.
+     *
+     * @remarks
+     * **⚠️ SECURITY WARNING:** Uses {@link Shell.run} internally.
+     * Never pass unsanitized user input. See {@link Shell.run} for details.
+     *
+     * @param command - The shell command to execute. Must be a trusted string.
+     * @returns A promise resolving to true if exit code is 0, false otherwise.
+     */
     async ok(command) {
         const result = await this.run(command, false);
         return result.code === 0;

package/dist/lib/utils.d.ts

@@ -1,2 +1,31 @@
+/**
+ * Extracts a human-readable error message from an unknown error value.
+ * Safely handles various error formats including Error objects, objects with message properties,
+ * and other unknown values.
+ *
+ * @param error - The error value to extract a message from. Can be any type.
+ * @returns The extracted error message string, or 'unknown' if no message could be extracted.
+ *
+ * @example
+ * ```ts
+ * getErrorMessage(new Error('Something went wrong')); // 'Something went wrong'
+ * getErrorMessage({ message: 'Custom error' }); // 'Custom error'
+ * getErrorMessage(null); // 'unknown'
+ * ```
+ */
 export declare function getErrorMessage(error: unknown): string;
+/**
+ * Formats JSON data with custom styling rules for map-style configurations.
+ * Applies special formatting for certain paths (like bounds, layers, filters, paint, layout)
+ * to keep them on a single line while expanding other nested structures.
+ *
+ * @param inputData - The data to format as styled JSON.
+ * @returns A formatted JSON string with custom indentation and line breaks.
+ *
+ * @example
+ * ```ts
+ * prettyStyleJSON({ name: 'test', bounds: [0, 0, 1, 1] });
+ * // Returns formatted JSON with bounds on a single line
+ * ```
+ */
 export declare function prettyStyleJSON(inputData: unknown): string;

package/dist/lib/utils.js

@@ -1,3 +1,18 @@
+/**
+ * Extracts a human-readable error message from an unknown error value.
+ * Safely handles various error formats including Error objects, objects with message properties,
+ * and other unknown values.
+ *
+ * @param error - The error value to extract a message from. Can be any type.
+ * @returns The extracted error message string, or 'unknown' if no message could be extracted.
+ *
+ * @example
+ * ```ts
+ * getErrorMessage(new Error('Something went wrong')); // 'Something went wrong'
+ * getErrorMessage({ message: 'Custom error' }); // 'Custom error'
+ * getErrorMessage(null); // 'unknown'
+ * ```
+ */
 export function getErrorMessage(error) {
     if (error == null)
         return 'unknown';
@@ -10,6 +25,20 @@ export function getErrorMessage(error) {
     }
     return 'unknown';
 }
+/**
+ * Formats JSON data with custom styling rules for map-style configurations.
+ * Applies special formatting for certain paths (like bounds, layers, filters, paint, layout)
+ * to keep them on a single line while expanding other nested structures.
+ *
+ * @param inputData - The data to format as styled JSON.
+ * @returns A formatted JSON string with custom indentation and line breaks.
+ *
+ * @example
+ * ```ts
+ * prettyStyleJSON({ name: 'test', bounds: [0, 0, 1, 1] });
+ * // Returns formatted JSON with bounds on a single line
+ * ```
+ */
 export function prettyStyleJSON(inputData) {
     return recursive(inputData);
     function recursive(data, prefix = '', path = '') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versatiles/release-tool",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "VersaTiles release and documentation tools",
   "bin": {
     "vrt": "./dist/index.js"
@@ -11,6 +11,7 @@
   ],
   "scripts": {
     "build": "npm run build-node && npm run doc",
+    "prepare": "husky",
     "build-node": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/index.js",
     "check": "npm run lint && npm run build && npm run test && npm run format:check",
     "dev": "tsx src/index.ts",
@@ -39,11 +40,13 @@
   "homepage": "https://github.com/versatiles-org/node-release-tool",
   "devDependencies": {
     "@schemastore/package": "^0.0.10",
-    "@types/node": "^25.1.0",
+    "@types/node": "^25.2.0",
     "@typescript-eslint/eslint-plugin": "^8.54.0",
     "@typescript-eslint/parser": "^8.54.0",
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^9.39.2",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
     "prettier": "^3.8.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
@@ -52,7 +55,7 @@
   },
   "dependencies": {
     "@inquirer/select": "^5.0.4",
-    "commander": "^14.0.2",
+    "commander": "^14.0.3",
     "dependency-cruiser": "^17.3.7",
     "npm-check-updates": "^19.3.2",
     "remark": "^15.0.1",
@@ -61,5 +64,9 @@
     "typedoc-github-theme": "^0.3.1",
     "typedoc-github-wiki-theme": "^2.1.0",
     "typedoc-plugin-markdown": "^4.9.0"
+  },
+  "lint-staged": {
+    "*.{ts,js,json,md,yml,yaml}": "prettier --write",
+    "*.ts": "eslint --fix"
   }
 }