@j-o-r/sh 1.1.28 → 1.1.31

package/lib/SHDispatch.js

@@ -1,56 +1,72 @@
-import SHExec from './SHExecute.js';
+import SHExecute from './SHExecute.js';
+
 /**
  * @typedef {Object} SpawnSyncResponse
- * @property {number|null} status - Exit code of the child process (null if terminated by signal).
- * @property {string|null} signal - Name of the terminating signal, if any.
- * @property {(string|Buffer|null)[]} output - [stdin, stdout, stderr] per Node's SpawnSyncReturns.
- * @property {number} pid - PID of the spawned process.
- * @property {string|Buffer|null} stdout - Stdout collected (type depends on encoding option).
- * @property {string|Buffer|null} stderr - Stderr collected (type depends on encoding option).
+ * @property {number|null} status - Exit code (null if signal).
+ * @property {string|null} signal - Terminating signal.
+ * @property {(string|Buffer|null)[]} output - [stdin, stdout, stderr].
+ * @property {number} pid - Process ID.
+ * @property {string|Buffer|null} stdout - Captured stdout.
+ * @property {string|Buffer|null} stderr - Captured stderr.
  */
+
 /**
- * @typedef {Object} SHOptions
- * @property {string} [cwd] - Current working directory of the child process.
- * @property {Object} [env] - Environment key-value pairs.
- * @property {string} [argv0] - Explicitly set the value of `argv[0]` sent to the child process.
- * @property {boolean} [detached=false] - If true, the child will be a process group leader.
- * @property {number} [uid] - Sets the user identity of the process.
- * @property {number} [gid] - Sets the group identity of the process.
- * @property {StdioOptions|StdioOption} [stdio='pipe'] - Child's stdio configuration.
- * @property {boolean|string} [shell='bash'] - If string or true, runs the command via that shell ('bash' if true).
- * @property {number} [timeout=0] - Milliseconds before sending SIGTERM (0 = no timeout).
- * @property {string|Buffer|Uint8Array} [input] - Optional stdin payload for spawnSync. Use .run(payload) for async.
+ * @typedef {('pipe' | 'ignore' | 'inherit' | number)} StdioOption
+ * @description Stdio config for a stream:
+ * - `'pipe'`: Pipe to parent.
+ * - `'ignore'`: Discard.
+ * - `'inherit'`: From/to parent.
+ * - `number`: FD.
  */
+
 /**
- * @typedef {('pipe' | 'ignore' | 'inherit' | number)} StdioOption
- * @description Defines the stdio configuration for each of the standard streams.
- * 
- * - 'pipe' creates a pipe between the child process and the parent process. 
- *   The parent end of the pipe is exposed as a property on the `ChildProcess` object.
- * - 'ignore' indicates that the child process's corresponding stdio file descriptor will be ignored.
- * - 'inherit' passes the corresponding stdio stream to/from the child process.
- * - Stream object to be used for the stdio stream.
- * - Positive integer representing a file descriptor to be used for the stdio stream.
+ * @typedef {Array<StdioOption> | StdioOption} StdioOptions
+ * @description Stdio array [stdin, stdout, stderr] or single value (applied to all).
+ * @example ['inherit', 'pipe', 'pipe'] // Default: inherit stdin, pipe out/err
  */
+
 /**
- * @typedef {Array<StdioOption>|StdioOption} StdioOptions
- * @description 
- * Configures the stdio streams for the child process. This can be an array or a single StdioOption.
- * 
- * Array Form: Specify the configuration for [stdin, stdout, stderr].
- *   - If array length is more than 3, additional positions correspond to extra streams.
- * Single Value: This value will be applied to stdin, stdout, and stderr.
- * 
- * Examples:
- * - ['pipe', 'pipe', 'ignore']: Pipe stdin and stdout, ignore stderr.
- * - 'inherit': Inherit all stdio streams from the parent.
+ * Core options for SH/SHDispatch.
+ *
+ * Defaults (merged from global SH):
+ * - `cwd`: `process.cwd()`
+ * - `env`: `process.env`
+ * - `shell`: `'bash'` (string/true → shell; false → no-shell `/usr/bin/env -S`)
+ * - `stdio`: `['inherit', 'pipe', 'pipe']`
+ * - `timeout`: `0` (no timeout; rolling on data)
+ * - `maxBuffer`: `512000` (500 kb per stream in SHExecute)
+ *
+ * Prefix (`.options(undefined, prefix)`) only for shell mode.
+ *
+ * @typedef {Object} SHOptions
+ * @property {string} cwd - Working directory for spawned commands.
+ * @property {NodeJS.ProcessEnv} env - Environment for spawned commands.
+ * @property {string|boolean} shell - Shell executable, true for bash, or false for no-shell mode.
+ * @property {StdioOptions} stdio - Stdio config passed to child_process.
+ * @property {number|string} timeout - Rolling timeout in ms or duration string; 0 disables timeout.
+ * @property {number} [maxBuffer] - Maximum buffered bytes per stdout/stderr stream.
+ * @property {boolean} [detached] - Run process detached and resolve early.
+ * @example { timeout: '5s', stdio: 'inherit', shell: false, maxBuffer: 10 * 1024}
  */
+
+/** @type {SHOptions} */
+const defaultSHOptions = {
+	cwd: process.cwd(),
+	env: process.env,
+	shell: 'bash',
+	stdio: ['inherit', 'pipe', 'pipe'],
+	timeout: 0,
+};
+
 /**
-* Merge property values while maintaining the fixed set of props from the predefined object
-* @param {SHOptions} predefined - options
-* @param {SHOptions} options
-* @returns {SHOptions}
-*/
+ * Merges user options into predefined defaults (non-destructive).
+ *
+ * Only copies defined keys.
+ *
+ * @param {SHOptions} predefined - Base options.
+ * @param {Partial<SHOptions>} options - Overrides.
+ * @returns {SHOptions} Merged options.
+ */
 const mergeOptions = (predefined, options) => {
 	const mergedObj = { ...predefined };
 
@@ -61,94 +77,106 @@ const mergeOptions = (predefined, options) => {
 	}
 
 	return mergedObj;
-}
+};
 
 /**
- * SHOptions — effective defaults and semantics used by SHDispatch/SHExecute
+ * High-level command dispatcher.
+ *
+ * Created by {@link SH`cmd`}; chain `.options()` then `.run()`.
  *
- * Defaults:
- * - cwd: process.cwd()
- * - env: process.env
- * - shell: 'bash' (string). If a string, that shell is used. If true, 'bash' is used. If false/undefined, no shell is used.
- * - stdio: ['inherit', 'pipe', 'pipe'] — inherit stdin, capture stdout/stderr
- * - timeout: 0 — no timeout
- * - maxBuffer?: number — optional (bytes per stream). Passed through to SHExecute.
+ * Delegates to {@link SHExecute} for exec/timeout/buffer/kill.
  *
- * Notes:
- * - The prefix (see options(prefix)) is only applied when a shell is used; it is ignored in no-shell mode.
- * - Each call to options() resets to the defaults and merges the provided options; it does not accumulate from prior calls.
+ * @example
+ * const dispatch = SH`ls -la`.options({ timeout: '2s' });
+ * const out = await dispatch.run();
  */
-
-
 class SHDispatch {
-	// #prefix =  'set -euo pipefail;/usr/bin/env'
-	// #prefix = 'set -euo pipefail'
 	#prefix = '';
 	#cmd = '';
-	#options = {};
-	/** 
-	* @type {SHExec} 
-	*/
-	#proc;
+	/** @type {SHOptions} */
+	#options = { ...defaultSHOptions };
+	/** @type {SHExecute | null} */
+	#proc = null;
+
 	/**
-	* @param {string} cmd - cmd to execute
-	* @param {SHOptions} options
-	* @param {string} [prefix] - command prefix e.g (default) '/usr/bin/env'
-	*/
-	constructor(cmd, options, prefix) {
+	 * @param {string} cmd - Command string.
+	 * @param {Partial<SHOptions>} [options] - Initial options.
+	 * @param {string} [prefix] - Shell prefix (e.g., 'set -euo pipefail').
+	 * @throws {Error} Invalid/empty cmd.
+	 */
+	constructor(cmd, options = {}, prefix) {
 		if (typeof cmd !== 'string' || cmd === '') {
 			throw new Error('Undefined command');
 		}
 		this.#cmd = cmd;
 		this.options(options, prefix);
 	}
+
 	/**
-	* @param {SHOptions} [options]
-	* @param {string} [prefix] - command prefix e.g (default) '/usr/bin/env'
-	* @returns {SHDispatch}
-	*/
+	 * Updates options/prefix by merging into the dispatch instance's current options.
+	 *
+	 * This preserves global `SH.*` defaults captured when the command was created
+	 * and only overrides options explicitly supplied for this command. Strings for
+	 * `stdio` are expanded to `[value, value, value]`.
+	 *
+	 * @param {Partial<SHOptions>} [options] - New options.
+	 * @param {string} [prefix] - New prefix.
+	 * @returns {SHDispatch} Self for chaining.
+	 */
 	options(options, prefix) {
-		// this.#options = defaultOptions
 		if (typeof prefix === 'string') {
 			this.#prefix = prefix;
 		}
 		if (!options) {
 			return this;
 		}
-		if (options.stdio && typeof options.stdio === 'string') {
+		const nextOptions = { ...options };
+		if (nextOptions.stdio && typeof nextOptions.stdio === 'string') {
 			// convert stdio to array
-			// This sets the default io values
-			// but can be overwritten when having a payload
-			const io = options.stdio;
-			options.stdio = Array(3).fill(io);
+			const io = nextOptions.stdio;
+			nextOptions.stdio = Array(3).fill(io);
 		}
-		this.#options = mergeOptions(this.#options, options);
+		this.#options = mergeOptions(this.#options, nextOptions);
 		return this;
 	}
 
-	/** 
-	* @param {string} [payload]
-	* @returns {Promise<string>}
-	*/
+	/**
+	 * Async run: Captures stdout; rejects on error/timeout.
+	 *
+	 * @param {string} [payload] - Stdin payload.
+	 * @returns {Promise<string>} Stdout.
+	 */
 	run(payload) {
-		this.#proc = new SHExec(this.#cmd, this.#prefix, this.#options);
+		this.#proc = new SHExecute(this.#cmd, this.#prefix, this.#options);
 		return this.#proc.run(payload);
 	}
 
-	/** 
-	* Works for terminal screen takeovers like editors
-	* @param {string} [payload]
-	* @returns {import('child_process').SpawnSyncReturns}
-	*/
+	/**
+	 * Sync run: Full Node SpawnSyncReturns.
+	 *
+	 * Good for TTY takeovers (e.g., vim).
+	 *
+	 * @param {string} [payload] - Stdin payload.
+	 * @returns {import('child_process').SpawnSyncReturns<Buffer>}
+	 */
 	runSync(payload) {
-		return new SHExec(this.#cmd, this.#prefix, this.#options).runSync(payload);
+		return new SHExecute(this.#cmd, this.#prefix, this.#options).runSync(payload);
 	}
+
+	/**
+	 * Kills running process + children.
+	 *
+	 * @param {number | string} [signal='SIGTERM'] - Signal.
+	 * @returns {Promise<number[]>} Killed PIDs.
+	 */
 	async kill(signal = 'SIGTERM') {
 		let res = [];
-		res = await this.#proc.kill(signal);
-		this.#proc = undefined;
+		if (this.#proc) {
+			res = await this.#proc.kill(signal);
+			this.#proc = null;
+		}
 		return res;
 	}
 }
 
-export default SHDispatch
+export default SHDispatch;

package/lib/SHExecute.js

@@ -1,8 +1,22 @@
 import { spawnSync, spawn } from 'node:child_process';
 
-// Local helpers
+/**
+ * Validates if a number is a finite positive integer (including 0).
+ *
+ * @param {unknown} n - Value to check.
+ * @returns {boolean} True if finite non-negative integer.
+ */
 const isFinitePosInt = (n) => Number.isFinite(n) && n >= 0;
-// Parse duration: accepts numbers (ms) or strings like "250", "250ms", or "2s". null/undefined yields 0; negatives or invalid forms throw.
+
+/**
+ * Parses a human-readable duration into milliseconds.
+ *
+ * Supports: numbers (ms), '250ms', '2s'. null/undefined → 0; invalid → throws.
+ *
+ * @param {number|string|null|undefined} d - Duration input.
+ * @returns {number} ms.
+ * @throws {Error} Invalid format/type.
+ */
 const parseDuration = (d) => {
   if (typeof d === 'number') return isFinitePosInt(d) ? d : (() => { throw new Error('Invalid duration'); })();
   if (typeof d === 'string') {
@@ -15,7 +29,12 @@ const parseDuration = (d) => {
   throw new Error('Invalid duration type');
 };
 
-// Kill a process tree using pgrep without going through a shell
+/**
+ * Retrieves child PIDs of a given parent PID using pgrep -P.
+ *
+ * @param {number} pid - Parent PID.
+ * @returns {Promise<number[]>} Array of child PIDs.
+ */
 const childrenOf = (pid) => new Promise((resolve, reject) => {
   const p = spawn('pgrep', ['-P', String(pid)], { stdio: ['ignore', 'pipe', 'ignore'] });
   const out = [];
@@ -32,21 +51,32 @@ const childrenOf = (pid) => new Promise((resolve, reject) => {
 });
 
 /**
- * SHExecute
- * Low-level process runner used by SHDispatch.
+ * @typedef {import('../SH.js').SHOptions & { maxBuffer?: number }} SHExecuteOptions
+ * @description Extended options for SHExecute: adds `maxBuffer` (bytes per stream, default 1MB).
+ */
+
+/**
+ * Low-level process executor for shell commands.
+ *
+ * Used internally by {@link SHDispatch}.
+ *
+ * Key features:
+ * - **Shell mode**: If `options.shell` is string/true, runs `${prefix}; ${command}` via shell ('bash' default).
+ * - **No-shell mode**: Uses `/usr/bin/env -S ${command}` for direct exec (ignores prefix).
+ * - **Rolling timeout**: `options.timeout` (ms/'2s'); resets on stdout/stderr data. SIGTERM on expiry.
+ * - **Buffering**: Captures stdout/stderr up to `maxBuffer` (1MB default); appends truncation markers.
+ * - **Payload**: `run(payload)` writes string to stdin (forces pipe).
+ * - **Detached**: If `options.detached`, resolves early (~1s) and unrefs.
+ * - **Kill**: Terminates process + children via pgrep.
  *
- * Features:
- * - Optional shell execution: if options.shell is a string (e.g., 'bash') or true, runs `${prefix}; ${command}` via that shell; otherwise runs without a shell using `/usr/bin/env -S`.
- * - Timeout: options.timeout may be a number (ms) or string like '1500ms' or '2s'. On timeout, run() rejects with a descriptive error.
- * - Buffering: Captures stdout/stderr up to maxBuffer bytes per stream (default 40 MiB). Appends "[stdout truncated]" / "[stderr truncated]" markers if exceeded.
- * - Payload: Passing a payload writes it to stdin and forces stdin to be a pipe.
- * - Detached mode: If options.detached is true, run() resolves to '' after ~1s and unrefs the process.
- * - Kill support: kill(signal) attempts to terminate the process (and some children) and causes run() to reject with "Process killed (forced).".
+ * @example
+ * const exec = new SHExecute('ls', 'set -euo pipefail', { timeout: '5s' });
+ * const out = await exec.run();
  */
 class SHExecute {
   #forcedKill = false;
-  /** @type {import('child_process').ChildProcess} */
-  #proc;
+  /** @type {import('child_process').ChildProcess | null} */
+  #proc = null;
   #prefix = '';
   #command = '';
   /** @type {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} */
@@ -55,14 +85,14 @@ class SHExecute {
   #stderrChunks = [];
   #stdoutLen = 0;
   #stderrLen = 0;
-  #maxBuffer = 40 * 1024 * 1024; // 40MB per stream
+  #maxBuffer = 500 * 1024; // 500KB per stream
   #truncated = { stdout: false, stderr: false };
   #timedOut = false;
 
   /**
-   * @param {string} command - linux command to be executed
-   * @param {string} prefix  - command prefix (shell prelude, e.g. 'set -euo pipefail')
-   * @param {import('child_process').SpawnOptions & { maxBuffer?: number }} options
+   * @param {string} command - Command to execute.
+   * @param {string} prefix - Shell prelude (e.g., 'set -euo pipefail'); ignored in no-shell.
+   * @param {SHExecuteOptions} [options] - Spawn options + maxBuffer/timeout.
    */
   constructor(command, prefix, options = {}) {
     this.#prefix = prefix;
@@ -70,18 +100,14 @@ class SHExecute {
     const { maxBuffer, ...spawnOpts } = options ?? {};
     this.#maxBuffer = Number.isFinite(maxBuffer) && maxBuffer > 0 ? maxBuffer : this.#maxBuffer;
     this.#options = spawnOpts;
-    this.#proc = null;
-    this.#stdoutChunks = [];
-    this.#stderrChunks = [];
-    this.#stdoutLen = 0;
-    this.#stderrLen = 0;
-    this.#truncated = { stdout: false, stderr: false };
-    this.#timedOut = false;
   }
 
   /**
-   * @param {string} [payload] - data to write
-   * @returns {import('child_process').SpawnSyncReturns}
+   * Synchronous execution.
+   *
+   * @param {string} [payload] - Stdin data (forces pipe).
+   * @returns {import('child_process').SpawnSyncReturns<Buffer>}
+   * @throws {Error} Invalid payload type.
    */
   runSync(payload) {
     this.#forcedKill = false;
@@ -109,15 +135,20 @@ class SHExecute {
   }
 
   /**
-   * @param {string} [payload] - data to write
-   * @returns {Promise<string>}
+   * Asynchronous execution with buffering/timeout/kill.
+   *
+   * Resolves stdout (trimmed) on success; rejects on error/timeout/kill.
+   *
+   * @param {string} [payload] - Stdin data (forces pipe).
+   * @returns {Promise<string>} Trimmed UTF-8 stdout (+ truncation marker if exceeded).
+   * @throws {Error} Command failure (incl. code, stderr), timeout, kill, spawn error.
    */
   run(payload) {
     this.#forcedKill = false;
     if (payload && typeof payload !== 'string') {
       throw new Error('Argument is not a string');
     }
-    /** @type {import('node:child_process').SpawnOptions} */
+    /** @type {import('child_process').SpawnOptions} */
     const options = { ...this.#options, shell: false };
     if (payload) {
       const stdio = Array.isArray(options.stdio) ? [...options.stdio] : ['pipe', 'pipe', 'pipe'];
@@ -147,20 +178,27 @@ class SHExecute {
 
     const ms = parseDuration(this.#options?.timeout ?? 0);
     let timeoutId = null;
-    if (ms > 0) {
-      timeoutId = setTimeout(() => {
-        this.#timedOut = true;
-        this.kill('SIGTERM').catch(() => {});
-      }, ms);
-    }
+    const resetTimeout = () => {
+      if (timeoutId !== null) clearTimeout(timeoutId);
+      if (ms > 0) {
+        timeoutId = setTimeout(() => {
+          this.#timedOut = true;
+          this.kill('SIGTERM').catch(() => {});
+        }, ms);
+      }
+    };
+
+    if (ms > 0) resetTimeout();
 
     this.#proc.stdout?.on('data', (chunk) => {
       this.#stdoutLen += chunk.length;
+      // prevent TOKEN bombs
       if (this.#stdoutLen <= this.#maxBuffer) {
         this.#stdoutChunks.push(chunk);
       } else {
         this.#truncated.stdout = true;
       }
+      resetTimeout();
     });
 
     this.#proc.stderr?.on('data', (chunk) => {
@@ -170,18 +208,20 @@ class SHExecute {
       } else {
         this.#truncated.stderr = true;
       }
+      resetTimeout();
     });
 
     return new Promise((resolve, reject) => {
       if (options.detached) {
         setTimeout(() => {
+          if (timeoutId !== null) clearTimeout(timeoutId);
           resolve('');
           this.#proc.unref();
         }, 1000);
       }
 
       this.#proc.on('close', (code, signal) => {
-        if (timeoutId) clearTimeout(timeoutId);
+        if (timeoutId !== null) clearTimeout(timeoutId);
         if (this.#forcedKill) {
           reject(new Error('Process killed (forced).'));
           return;
@@ -208,9 +248,11 @@ class SHExecute {
   }
 
   /**
-   * Kill this process and possible child processes
-   * @param {number | string} signal - kill signal
-   * @returns {Promise<number[]>}
+   * Terminates process and its children (via pgrep).
+   *
+   * @param {number | string} [signal='SIGTERM'] - Signal to send.
+   * @returns {Promise<number[]>} Killed PIDs.
+   * @throws {Error} No process/PID.
    */
   async kill(signal = 'SIGTERM') {
     if (!this.#proc) throw new Error('Trying to kill a process without creating one.');
@@ -225,7 +267,7 @@ class SHExecute {
       }
       try { process.kill(pid, signal); killed.push(pid); } catch (e) { if (!e || e.code !== 'ESRCH') throw e; }
     } finally {
-      this.#proc = undefined;
+      this.#proc = null;
     }
     return killed;
   }