@j-o-r/sh 1.1.21 → 1.1.23

package/lib/SH.js

@@ -81,10 +81,8 @@ const jsType = (fn) => {
 * @returns {boolean}
 */
 const hasProp = (o, p) => {
-	if (typeof o === 'undefined') {
-		return false;
-	}
-	return Object.prototype.hasOwnProperty.call(o, p);
+  if (o == null) return false;
+  return Object.prototype.hasOwnProperty.call(o, p);
 };
 /**
 * 4ms, 5s || 5
@@ -112,6 +110,15 @@ const parseDuration = (d) => {
 /**
 * @type {Shell & SHTag}
 */
+/**
+ * SH template tag
+ *
+ * Interpolation rules:
+ * - Arrays: each element is String(x).trim(), with newlines/carriage returns/tabs escaped; if an element contains shell metacharacters or spaces, it is wrapped in single-quotes and internal single-quotes are escaped as '\''.
+ * - Non-array values: currently coerced with String(value) and inserted as-is (NOT shell-escaped). Be careful when interpolating untrusted input.
+ *
+ * Returns an SHDispatch that can be configured via .options() and executed with .run() / .runSync().
+ */
 const SH = new Proxy(function(pieces, ...args) {
 	if (pieces.some((p) => p == undefined)) {
 		throw new Error(`Malformed command ${pieces}`);
@@ -165,6 +172,10 @@ const within = async (callback) => {
 * @example 
 * const content = await readIn();
 */
+/**
+ * Read entire stdin as UTF-8. If stdin is a TTY, resolves to an empty string.
+ * @returns {Promise<string>}
+ */
 const readIn = async () => {
 	if (process.stdin.isTTY) return '';   // nothing was piped
 	let buf = '';
@@ -345,6 +356,21 @@ function* expBackoff(max = '60s', rand = '100ms') {
 *   - The value is either the next argument or `true` if no value is provided,
 *   - The `_` property contains an array of unbound arguments.
 */
+/**
+ * Parse command-line args into an object.
+ *
+ * Supported:
+ * - --key value, -k value (no grouped short flags)
+ * - Bare values collected under `_.`
+ * - Duplicate keys throw an error; keys without a following value become true.
+ *
+ * Not supported:
+ * - --key=value syntax
+ * - Grouped short flags like -abc
+ *
+ * @param {string[]} [args]
+ * @returns {ArgsObject}
+ */
 const parseArgs = (args) => {
 	if (!args) args = process.argv.slice(2);
 	const result = { _: [] };

package/lib/SHDispatch.js

@@ -1,25 +1,25 @@
 import SHExec from './SHExecute.js';
 /**
  * @typedef {Object} SpawnSyncResponse
- * @property {number} status - The exit code of the child process. A value of `0` indicates success.
- * @property {Buffer|null} signal - The signal used to terminate the process, if any.
- * @property {Array<string|null>} output - An array containing the standard output and standard error of the child process.
- * @property {number} pid - The process ID of the child process.
- * @property {Buffer|null} stdout - The standard output of the child process.
- * @property {Buffer|null} stderr - The standard error of the child process.
+ * @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).
  */
- /**
+/**
  * @typedef {Object} SHOptions
  * @property {string} [cwd] - Current working directory of the child process.
  * @property {Object} [env] - Environment key-value pairs.
- * @property {Array|string} [argv0] - Explicitly set the value of `argv[0]` sent to the child process.
+ * @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 true, runs command inside a shell.
- * @property {number} [timeout=0] - In milliseconds, specifies when to terminate the child process.
- * @property {string|Buffer|URL} [input] - The input to write to stdin.
+ * @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
@@ -64,6 +64,21 @@ const mergeOptions = (predefined, options) => {
 }
 
 /** @type {SHOptions} */
+/**
+ * SHOptions — effective defaults and semantics used by SHDispatch/SHExecute
+ *
+ * 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.
+ *
+ * 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.
+ */
 const defaultOptions = {
 	cwd: process.cwd(),
 	env: process.env,
@@ -76,7 +91,7 @@ const defaultOptions = {
 
 class SHDispatch {
 	// #prefix =  'set -euo pipefail;/usr/bin/env'
-	#prefix = 'set -euo pipefail;/usr/bin/env -S'
+	#prefix = 'set -euo pipefail'
 	#cmd = '';
 	#options = {};
 	/** 

package/lib/SHExecute.js

@@ -1,168 +1,236 @@
-import { spawnSync, spawn, exec } from 'node:child_process';
+import { spawnSync, spawn} from 'node:child_process';
 
-/**
-* Kills a process and all child processes of a given process ID in Linux/Posix.
-* @param {number} processPid - The process ID.
-* @param {string|number} signal - Signal to send.
-* @retruns {Promise<number[]>} array with killed pid numbers
-*/
-const killProcesses = (processPid, signal) => {
-	const killed = [];
-	return new Promise((resolve, reject) => {
-		// Command to get child PIDs of the given process
-		const cmd = `pgrep -P ${processPid}`;
-		exec(cmd, (error, stdout, stderr) => {
-			if (error) {
-				reject(error);
-				return;
-			}
-			if (stderr) {
-				reject(new Error(stderr));
-				return;
-			}
-			const pids = stdout.split(/\r?\n/).filter(pid => pid) || [];
-			// Kill each child process
-			try {
-				for (const pid of pids) {
-					process.kill(parseInt(pid), signal);
-					killed.push(parseInt(pid));
-				}
-			} catch (err) {
-				reject(err);
-				return;
-			}
-			// Kill the parent process after all child processes have been killed
-			try {
-				process.kill(processPid, signal);
-				killed.push(processPid);
-			} catch (err) {
-				reject(err);
-				return;
-			}
-			resolve(killed);
-		});
-	});
-}
+// Local helpers
+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.
+const parseDuration = (d) => {
+  if (typeof d === 'number') return isFinitePosInt(d) ? d : (() => { throw new Error('Invalid duration'); })();
+  if (typeof d === 'string') {
+    const m = d.match(/^(\d+)(ms|s)?$/);
+    if (!m) throw new Error('Invalid duration string');
+    const n = Number(m[1]);
+    return m[2] === 's' ? n * 1000 : n;
+  }
+  if (d == null) return 0;
+  throw new Error('Invalid duration type');
+};
+
+// Kill a process tree using pgrep without going through a shell
+const childrenOf = (pid) => new Promise((resolve, reject) => {
+  const p = spawn('pgrep', ['-P', String(pid)], { stdio: ['ignore', 'pipe', 'ignore'] });
+  const out = [];
+  p.stdout.on('data', (b) => out.push(b));
+  p.on('close', (code) => {
+    if (code === 0) {
+      const ids = Buffer.concat(out).toString('utf8').trim().split(/\s+/).map(Number).filter(Boolean);
+      resolve(ids);
+    } else if (code === 1) {
+      resolve([]); // no children
+    } else {
+      reject(new Error(`pgrep -P ${pid} failed with code ${code}`));
+    }
+  });
+  p.on('error', reject);
+});
 
+/**
+ * SHExecute
+ * Low-level process runner used by SHDispatch.
+ *
+ * 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).".
+ */
 class SHExecute {
-	#forcedKill = false;
-	/**
-	* @type {import('child_process').ChildProcess}
-	*/
-	#proc;
-	#prefix = '';
-	#command = '';
-	/** @type {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} */
-	#options = {};
-	#stdout = '';
-	#stderr = '';
-	/**
-	* @param {string} command - linux command to be executed
-	* @param {string} prefix  - command prefix (bash, sh etc.)
-	* @param {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} options
-	*/
-	constructor(command, prefix, options = {}) {
-		this.#prefix = prefix;
-		this.#command = command;
-		this.#options = options;
-		this.#proc = null;
-		this.#stdout = '';
-		this.#stderr = '';
-	}
-	/**
-	* @param {string} [payload] - data to write
-	* @retuns {Promise<object>}
-	*/
-	runSync(payload) {
-		if (payload && typeof payload !== 'string') {
-			throw new Error('Argument is not a string');
-		}
-		/** @type {import('node:child_process').SpawnSyncOptions} */
-		const options = this.#options;
-		// pipe need to be set on stdin when posting a payload
-		// @ts-ignore
-		if (payload) options['stdio'][0] = 'pipe';
-		const input = payload || undefined;
-		if (input) {
-			options.input = input
-		}
-		return spawnSync(this.#prefix, [this.#command], options);
-	}
-	/**
-	* @param {string} [payload] - data to write
-	* @retuns {Promise<string>}
-	*/
-	run(payload) {
-		if (payload && typeof payload !== 'string') {
-			throw new Error('Argument is not a string');
-		}
-		/** @type {import('node:child_process').SpawnOptions} */
-		const options = this.#options;
-		// pipe need to be set on stdin when posting a payload
-		// @ts-ignore
-		if (payload) options.stdio[0] = 'pipe';
-		this.#proc = spawn(this.#prefix, [this.#command], options);
-		this.#proc.stdout?.on('data', (data) => {
-			this.#stdout += data;
-		});
-
-		this.#proc.stderr?.on('data', (data) => {
-			this.#stderr += data;
-		});
-		if (payload) {
-			this.#proc.stdin.end(payload);
-		}
-		return new Promise((resolve, reject) => {
-			// https://nodejs.org/docs/latest/api/child_process.html#optionsdetached
-			if (options.detached) {
-			setTimeout(() => {
-				resolve('');
-				this.#proc.unref();
-			}, 1000);
-			}
-			this.#proc.on('close', (code) => {
-				if (this.#forcedKill) {
-					// Resolve without content
-					resolve();
-					return;
-				}
-				// Detached does not closes with an exitcode
-				if (code === 0 || code === null || typeof (code) === 'undefined') {
-					resolve(this.#stdout.trim());
-				} else {
-					reject(new Error(`${code}: ${this.#command} "${this.#stderr.trim()}"`));
-				}
-			});
-
-			this.#proc.on('error', (err) => {
-				reject(err);
-			});
-		});
-	}
-	/**
-	* Kill this process and possible child processes
-	* @param {number | string} signal - kill signal
-	* @returns {Promise<number[]>}
-	*/
-	async kill(signal = 'SIGTERM') {
-		if (!this.#proc) throw new Error('Trying to kill a process without creating one.');
-		if (!this.#proc.pid) throw new Error('The process pid is undefined.');
-		this.#forcedKill = true;
-		let res = [];
-		try {
-			// Try to kill pid 'childs'
-			res = await killProcesses(this.#proc.pid, signal);
-		} catch (_e) { }
-		if (!res.includes(this.#proc.pid)) {
-			// Kill self if I am not allready killed
-			res.push(this.#proc.pid);
-			// @ts-ignore
-			this.#proc.kill(signal);
-		}
-		this.#proc = undefined;
-		return res;
-	}
+  #forcedKill = false;
+  /** @type {import('child_process').ChildProcess} */
+  #proc;
+  #prefix = '';
+  #command = '';
+  /** @type {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} */
+  #options = {};
+  #stdoutChunks = [];
+  #stderrChunks = [];
+  #stdoutLen = 0;
+  #stderrLen = 0;
+  #maxBuffer = 40 * 1024 * 1024; // 40MB 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
+   */
+  constructor(command, prefix, options = {}) {
+    this.#prefix = prefix;
+    this.#command = command;
+    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}
+   */
+  runSync(payload) {
+    this.#forcedKill = false;
+    if (payload && typeof payload !== 'string') {
+      throw new Error('Argument is not a string');
+    }
+    /** @type {import('node:child_process').SpawnSyncOptions} */
+    const options = { ...this.#options, shell: false };
+    if (payload) {
+      const stdio = Array.isArray(options.stdio) ? [...options.stdio] : ['pipe', 'pipe', 'pipe'];
+      stdio[0] = 'pipe';
+      // @ts-ignore
+      options.stdio = stdio;
+      options.input = payload;
+    }
+
+    const shellOpt = this.#options?.shell;
+    if (shellOpt) {
+      const sh = typeof shellOpt === 'string' ? shellOpt : 'bash';
+      const cmd = `${this.#prefix}; ${this.#command}`;
+      return spawnSync(sh, ['-c', cmd], options);
+    }
+    // no-shell mode
+    return spawnSync('/usr/bin/env', ['-S', this.#command], options);
+  }
+
+  /**
+   * @param {string} [payload] - data to write
+   * @returns {Promise<string>}
+   */
+  run(payload) {
+    this.#forcedKill = false;
+    if (payload && typeof payload !== 'string') {
+      throw new Error('Argument is not a string');
+    }
+    /** @type {import('node:child_process').SpawnOptions} */
+    const options = { ...this.#options, shell: false };
+    if (payload) {
+      const stdio = Array.isArray(options.stdio) ? [...options.stdio] : ['pipe', 'pipe', 'pipe'];
+      stdio[0] = 'pipe';
+      // @ts-ignore
+      options.stdio = stdio;
+    }
+
+    // reset buffers for each run
+    this.#stdoutChunks = [];
+    this.#stderrChunks = [];
+    this.#stdoutLen = 0;
+    this.#stderrLen = 0;
+    this.#truncated = { stdout: false, stderr: false };
+    this.#timedOut = false;
+
+    const shellOpt = this.#options?.shell;
+    if (shellOpt) {
+      const sh = typeof shellOpt === 'string' ? shellOpt : 'bash';
+      const cmd = `${this.#prefix}; ${this.#command}`;
+      this.#proc = spawn(sh, ['-c', cmd], options);
+    } else {
+      this.#proc = spawn('/usr/bin/env', ['-S', this.#command], options);
+    }
+
+    if (payload) this.#proc.stdin?.end(payload);
+
+    const ms = parseDuration(this.#options?.timeout ?? 0);
+    let timeoutId = null;
+    if (ms > 0) {
+      timeoutId = setTimeout(() => {
+        this.#timedOut = true;
+        this.kill('SIGTERM').catch(() => {});
+      }, ms);
+    }
+
+    this.#proc.stdout?.on('data', (chunk) => {
+      this.#stdoutLen += chunk.length;
+      if (this.#stdoutLen <= this.#maxBuffer) {
+        this.#stdoutChunks.push(chunk);
+      } else {
+        this.#truncated.stdout = true;
+      }
+    });
+
+    this.#proc.stderr?.on('data', (chunk) => {
+      this.#stderrLen += chunk.length;
+      if (this.#stderrLen <= this.#maxBuffer) {
+        this.#stderrChunks.push(chunk);
+      } else {
+        this.#truncated.stderr = true;
+      }
+    });
+
+    return new Promise((resolve, reject) => {
+      if (options.detached) {
+        setTimeout(() => {
+          resolve('');
+          this.#proc.unref();
+        }, 1000);
+      }
+
+      this.#proc.on('close', (code, signal) => {
+        if (timeoutId) clearTimeout(timeoutId);
+        if (this.#forcedKill) {
+          reject(new Error('Process killed (forced).'));
+          return;
+        }
+        if (this.#timedOut) {
+          reject(new Error(`Process timed out after ${ms}ms.`));
+          return;
+        }
+        if (code === 0) {
+          const stdoutBuf = this.#stdoutChunks.length ? Buffer.concat(this.#stdoutChunks) : Buffer.alloc(0);
+          let stdout = stdoutBuf.toString('utf8').trim();
+          if (this.#truncated.stdout) stdout += '\n[stdout truncated]\n';
+          resolve(stdout);
+        } else {
+          const stderrBuf = this.#stderrChunks.length ? Buffer.concat(this.#stderrChunks) : Buffer.alloc(0);
+          let stderr = stderrBuf.toString('utf8').trim();
+          if (this.#truncated.stderr) stderr += '\n[stderr truncated]\n';
+          reject(new Error(`Exit ${code ?? 'null'}${signal ? `, signal ${signal}` : ''}: ${this.#command}${stderr ? ` :: ${stderr}` : ''}`));
+        }
+      });
+
+      this.#proc.on('error', (err) => reject(err));
+    });
+  }
+
+  /**
+   * Kill this process and possible child processes
+   * @param {number | string} signal - kill signal
+   * @returns {Promise<number[]>}
+   */
+  async kill(signal = 'SIGTERM') {
+    if (!this.#proc) throw new Error('Trying to kill a process without creating one.');
+    if (!this.#proc.pid) throw new Error('The process pid is undefined.');
+    this.#forcedKill = true;
+    const pid = this.#proc.pid;
+    let killed = [];
+    try {
+      const kids = await childrenOf(pid).catch(() => []);
+      for (const k of kids) {
+        try { process.kill(k, signal); killed.push(k); } catch (e) { if (!e || e.code !== 'ESRCH') throw e; }
+      }
+      try { process.kill(pid, signal); killed.push(pid); } catch (e) { if (!e || e.code !== 'ESRCH') throw e; }
+    } finally {
+      this.#proc = undefined;
+    }
+    return killed;
+  }
 }
 
 export default SHExecute;
-

package/lib/Test.js

@@ -64,7 +64,7 @@ class Test {
 	*/
 	#errors = [];
 	/** verbosed **/
-	#quite = false;
+	#quiet = false;
 	/** Timeout in ms to settle async code blocks called from sync methods */
 	#TO = SETTLE_ASYNC;
 	/**
@@ -72,7 +72,7 @@ class Test {
 	*/
 	constructor(quiet = false) {
 		if (quiet) {
-			this.#quite = true;
+			this.#quiet = true;
 		}
 		// Track for unresolved promises
 		this.#promiseTracker = new AsyncTracker();
@@ -149,7 +149,7 @@ class Test {
 			this.#reports[i] = { description: cb.description, duration, executed };
 			let error;
 			try {
-				if (!this.#quite) process.stdout.write(`${i}. ${cb.description} `);
+				if (!this.#quiet) process.stdout.write(`${i}. ${cb.description} `);
 				await Promise.resolve(cb.callback());
 				executed = true;
 				if (type === 'Function') {
@@ -167,7 +167,7 @@ class Test {
 				error = e;
 			}
 			duration = getDuration(start);
-			if (!this.#quite && !error) process.stdout.write(`(duration: ${duration} ms)\n`);
+			if (!this.#quiet && !error) process.stdout.write(`(duration: ${duration} ms)\n`);
 			this.#reports[i].duration = duration;
 			this.#reports[i].executed = executed;
 			if (error) {
@@ -198,14 +198,14 @@ class Test {
 
 		}
 		const errors = this.#errors.length;
-		if (!this.#quite) {
+		if (!this.#quiet) {
 			console.log('--------------------------------------------------');
 			console.log(`Total: ${tests} tests, executed: ${executed} in ${duration} ms - errors: ${errors}`);
 			if (tests !== executed) {
-				if (!this.#quite) console.log('** Not all tests have been executed **');
+				if (!this.#quiet) console.log('** Not all tests have been executed **');
 		    return { tests, executed, duration, errors };
 			}
-			// Report on unresolved promises when NOT quite
+			// Report on unresolved promises when NOT quiet
 			// This must be on a next tick because the current Promise (where this code is in) is not resolved yet
 			nextTick(() => {
 				const count = this.#promiseTracker.report(true);
@@ -235,9 +235,9 @@ class Test {
 		// A global error is an error catched outside the callstack of the test
 		const ERR = outside ? 'GLOBAL_ERROR' : 'ERROR'
 		if (this.#currentTest > -1) {
-			if (!this.#quite) process.stdout.write(`\n`);
+			if (!this.#quiet) process.stdout.write(`\n`);
 			// Register this error
-			// Always print out errors despite #quite
+			// Always print out errors despite #quiet
 			const description = this.#reports[this.#currentTest].description;
 			const executed = this.#reports[this.#currentTest].executed;
 			if (executed) {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@j-o-r/sh",
   "author": "Jorrit Duin <j-o-r@duin.work>",
   "type": "module",
-  "version": "1.1.21",
+  "version": "1.1.23",
   "description": "Execute shell commands on Linux-based systems from javascript",
   "main": "lib/SH.js",
   "types": "types/SH.d.ts",

package/types/SH.d.ts

@@ -11,14 +11,7 @@ export type Shell = Function;
  * A template-tag that returns an SHDispatch.
  */
 export type SHTag = (pieces: TemplateStringsArray, ...args: unknown[]) => SHDispatch;
-/**
-* A template-tag that returns an SHDispatch.
-* @typedef {(pieces: TemplateStringsArray, ...args: unknown[]) => SHDispatch} SHTag
-*/
-/**
-* @type {Shell & SHTag}
-*/
-export const SH: Shell & SHTag;
+export function SH(pieces: any, ...args: any[]): SHDispatch;
 /**
 * Change working directory
 * @param {string} dir
@@ -59,6 +52,10 @@ export function retry(count: number, a: string | number | typeof expBackoff | Fu
 * @example
 * const content = await readIn();
 */
+/**
+ * Read entire stdin as UTF-8. If stdin is a TTY, resolves to an empty string.
+ * @returns {Promise<string>}
+ */
 export function readIn(): Promise<string>;
 /**
 * Get user input from the command line (stdin)
@@ -113,6 +110,21 @@ export function expBackoff(max?: string, rand?: string): Generator<number, void,
 *   - The value is either the next argument or `true` if no value is provided,
 *   - The `_` property contains an array of unbound arguments.
 */
+/**
+ * Parse command-line args into an object.
+ *
+ * Supported:
+ * - --key value, -k value (no grouped short flags)
+ * - Bare values collected under `_.`
+ * - Duplicate keys throw an error; keys without a following value become true.
+ *
+ * Not supported:
+ * - --key=value syntax
+ * - Grouped short flags like -abc
+ *
+ * @param {string[]} [args]
+ * @returns {ArgsObject}
+ */
 export function parseArgs(args?: string[]): ArgsObject;
 /**
 * @typedef {Object.<string, string>} ArgsObject

package/types/SHDispatch.d.ts

@@ -1,29 +1,29 @@
 export default SHDispatch;
 export type SpawnSyncResponse = {
     /**
-     * - The exit code of the child process. A value of `0` indicates success.
+     * - Exit code of the child process (null if terminated by signal).
      */
-    status: number;
+    status: number | null;
     /**
-     * - The signal used to terminate the process, if any.
+     * - Name of the terminating signal, if any.
      */
-    signal: Buffer | null;
+    signal: string | null;
     /**
-     * - An array containing the standard output and standard error of the child process.
+     * - [stdin, stdout, stderr] per Node's SpawnSyncReturns.
      */
-    output: Array<string | null>;
+    output: (string | Buffer | null)[];
     /**
-     * - The process ID of the child process.
+     * - PID of the spawned process.
      */
     pid: number;
     /**
-     * - The standard output of the child process.
+     * - Stdout collected (type depends on encoding option).
      */
-    stdout: Buffer | null;
+    stdout: string | Buffer | null;
     /**
-     * - The standard error of the child process.
+     * - Stderr collected (type depends on encoding option).
      */
-    stderr: Buffer | null;
+    stderr: string | Buffer | null;
 };
 export type SHOptions = {
     /**
@@ -37,7 +37,7 @@ export type SHOptions = {
     /**
      * - Explicitly set the value of `argv[0]` sent to the child process.
      */
-    argv0?: string | any[] | undefined;
+    argv0?: string | undefined;
     /**
      * - If true, the child will be a process group leader.
      */
@@ -55,17 +55,17 @@ export type SHOptions = {
      */
     stdio?: number | "pipe" | "ignore" | "inherit" | StdioOption[] | undefined;
     /**
-     * - If true, runs command inside a shell.
+     * - If string or true, runs the command via that shell ('bash' if true).
      */
     shell?: string | boolean | undefined;
     /**
-     * - In milliseconds, specifies when to terminate the child process.
+     * - Milliseconds before sending SIGTERM (0 = no timeout).
      */
     timeout?: number | undefined;
     /**
-     * - The input to write to stdin.
+     * - Optional stdin payload for spawnSync. Use .run(payload) for async.
      */
-    input?: string | Buffer<ArrayBufferLike> | URL | undefined;
+    input?: string | Uint8Array<ArrayBufferLike> | Buffer<ArrayBufferLike> | undefined;
 };
 export type StdioOption = ("pipe" | "ignore" | "inherit" | number);
 export type StdioOptions = Array<StdioOption> | StdioOption;

package/types/SHExecute.d.ts

@@ -1,26 +1,40 @@
 export default SHExecute;
+/**
+ * SHExecute
+ * Low-level process runner used by SHDispatch.
+ *
+ * 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).".
+ */
 declare class SHExecute {
     /**
-    * @param {string} command - linux command to be executed
-    * @param {string} prefix  - command prefix (bash, sh etc.)
-    * @param {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} options
-    */
-    constructor(command: string, prefix: string, options?: import("child_process").SpawnOptions | import("child_process").SpawnSyncOptions);
+     * @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
+     */
+    constructor(command: string, prefix: string, options?: import("child_process").SpawnOptions & {
+        maxBuffer?: number;
+    });
     /**
-    * @param {string} [payload] - data to write
-    * @retuns {Promise<object>}
-    */
-    runSync(payload?: string): import("child_process").SpawnSyncReturns<string | Buffer<ArrayBufferLike>>;
+     * @param {string} [payload] - data to write
+     * @returns {import('child_process').SpawnSyncReturns}
+     */
+    runSync(payload?: string): import("child_process").SpawnSyncReturns<any>;
     /**
-    * @param {string} [payload] - data to write
-    * @retuns {Promise<string>}
-    */
-    run(payload?: string): Promise<any>;
+     * @param {string} [payload] - data to write
+     * @returns {Promise<string>}
+     */
+    run(payload?: string): Promise<string>;
     /**
-    * Kill this process and possible child processes
-    * @param {number | string} signal - kill signal
-    * @returns {Promise<number[]>}
-    */
+     * Kill this process and possible child processes
+     * @param {number | string} signal - kill signal
+     * @returns {Promise<number[]>}
+     */
     kill(signal?: number | string): Promise<number[]>;
     #private;
 }