@j-o-r/sh 1.1.22 → 1.1.24

package/README.md

@@ -64,11 +64,14 @@ The module also provides additional utilities for common tasks:
 - `sleep(duration)`: Pause execution for a specified duration.
 - `retry(count, interval, callback)`: Retry a command a specified number of times with an optional interval.
 - `readIn()`: Read from standard input.
+- `userIn(prompt)`: Prompt the user for input and return an object with `input` (Promise resolving to the user input) and `abort()` method to cancel.
 - `within(callback)`: Create an async context in a sync block.
 - `expBackoff(max, rand)`: Generate intervals for exponential backoff.
 - `jsType(any)`: Get the 'real' javascript variable type 
+- `hasProp(object, property)`: Safely check if an object has its own property (handles null/undefined objects).
 - `assert.`: Node assert library 
 - `new Test()`: A small sync/async minimal test framework 
+- `AsyncTracker`: A class for tracking asynchronous operations using Node.js async hooks.
 
 ## SHDispatch
 
@@ -118,11 +121,27 @@ This class is returned by the `SH` function. Here's a summary of its methods and
 - Retry with exponential backoff:
   ```javascript
   try {
-    const p = await retry(3, expBackoff(), () => SH`curl -s https://flipwrsi`.run());
+    const p = await retry(3, expBackoff(), () => SH`curl -s https://unreachable`.run());
   } catch (e) {
     console.error('Retry failed:', e);
   }
   ```
+
+- Prompt user for input:
+  ```javascript
+  const user = userIn('Enter your name: ');
+  const name = await user.input;
+  console.log('Hello,', name);
+  ```
+
+- Check if object has property:
+  ```javascript
+  const obj = { a: 1 };
+  console.log(hasProp(obj, 'a')); // true
+  console.log(hasProp(obj, 'b')); // false
+  console.log(hasProp(null, 'a')); // false
+  ```
+
 - Method for copying data to the clipboard:
   ```javascript
   /**

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,210 +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 = {};
-	#stdoutChunks = [];
-	#stderrChunks = [];
-	// Track sizes to avoid unbounded memory growth and RangeError on join/toString
-	#stdoutLen = 0;
-	#stderrLen = 0;
-	// Max bytes to buffer in memory (per stream). Remaining data is ignored.
-	#maxBuffer = 40 * 1024 * 1024; // default 40MB
-	#truncated = { stdout: false, stderr: false };
-	/**
-	* @param {string} command - linux command to be executed
-	* @param {string} prefix  - command prefix (bash, sh etc.)
-	* @param {import('child_process').SpawnOptions & { maxBuffer?: number }} options
-	*/
-	constructor(command, prefix, options = {}) {
-		this.#prefix = prefix;
-		this.#command = command;
-		// Extract our custom option to avoid passing unknown keys to spawn/spawnSync
-		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 };
-	}
-	/**
-	* @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) {
-			// clone/ensure stdio array exists
-			const stdio = Array.isArray(options.stdio) ? [...options.stdio] : ['pipe', 'pipe', 'pipe'];
-			stdio[0] = 'pipe';
-			options.stdio = stdio;
-		}
-		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';
-
-		// reset buffers for each run
-		this.#stdoutChunks = [];
-		this.#stderrChunks = [];
-		this.#stdoutLen = 0;
-		this.#stderrLen = 0;
-		this.#truncated = { stdout: false, stderr: false };
-
-		this.#proc = spawn(this.#prefix, [this.#command], options);
-		this.#proc.stdout?.on('data', (chunk) => {
-			this.#stdoutLen += chunk.length;
-			if (this.#stdoutLen <= this.#maxBuffer) {
-				this.#stdoutChunks.push(chunk);
-			} else {
-				this.#truncated.stdout = true;
-				// ignore further data to cap memory; alternatively implement a ring buffer
-			}
-		});
-
-		this.#proc.stderr?.on('data', (chunk) => {
-			this.#stderrLen += chunk.length;
-			if (this.#stderrLen <= this.#maxBuffer) {
-				this.#stderrChunks.push(chunk);
-			} else {
-				this.#truncated.stderr = true;
-			}
-		});
-		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') {
-					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(`${code}: ${this.#command} "${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;
-		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/module.md

@@ -0,0 +1,154 @@
+# @j-o-r/sh Module Documentation
+
+## Overview
+
+**Name:** @j-o-r/sh  
+**Version:** 1.1.23  
+**Description:** Execute shell commands on Linux-based systems from javascript.  
+
+This module simplifies the execution of shell commands within JavaScript applications, providing utilities to handle shell scripts and manage their output efficiently. It is inspired by the zx library and supports features like command execution, retries, user input, and more.
+
+**Repository:** https://codeberg.org/duin/sh  
+**License:** Apache License, Version 2.0  
+
+Key features include:
+- Execute shell commands synchronously or asynchronously.
+- Utilities for changing directory, sleeping, retrying commands with backoff.
+- Parsing command-line arguments.
+- User input prompts.
+- A minimal test framework.
+- Async operation tracking.
+
+## Installation Notes
+
+The module is already installed in the current environment. For new installations, use:
+
+```sh
+npm install @j-o-r/sh
+```
+
+Requires Node.js >= 20.0.0.
+
+## API Usage Examples
+
+### Basic Usage
+
+To execute a shell command, use the `SH` function:
+
+```javascript
+import { SH } from '@j-o-r/sh';
+
+SH`your_shell_command`.run()
+  .then(output => {
+    console.log('Output:', output);
+  })
+  .catch(error => {
+    console.error('Error:', error);
+  });
+```
+
+### Advanced Usage
+
+```javascript
+import { SH, cd, within, sleep, retry, expBackoff } from '@j-o-r/sh';
+
+const res = await SH`ls -FLa | grep package.json | wc -l`.run();
+console.log(res);
+
+const ar = within(async () => {
+  const res = await Promise.all([
+    SH`sleep 1; echo 1`.run(),
+    SH`sleep 2; echo 2`.run(),
+    sleep(2),
+    SH`sleep 3; echo 3`.run()
+  ]);
+});
+
+const p = await retry(3, expBackoff(), () => SH`curl -s https://unreachable`.run());
+```
+
+### Additional Examples
+
+- Prompt user for input:
+  ```javascript
+  const user = userIn('Enter your name: ');
+  const name = await user.input;
+  console.log('Hello,', name);
+  ```
+
+- Create and run a test:
+  ```javascript
+  import { assert, jsType, Test } from '@j-o-r/sh';
+
+  const test = new Test();
+  test.add('Test is test in sync', () => {
+    assert.strictEqual(jsType(test), 'Test');
+  });
+  const report = await test.run();
+  ```
+
+## Full API Reference
+
+### Main Exports
+
+- **SH**: A template tag function that returns an `SHDispatch` object for executing shell commands.
+- **cd(dir: string)**: Changes the working directory.
+- **sleep(duration: string | number)**: Pauses execution for the specified duration (e.g., '5s').
+- **retry(count: number, a: string | number | expBackoff | Function, b?: Function)**: Retries a function with optional intervals.
+- **readIn()**: Reads from stdin as a promise.
+- **userIn(prompt: string)**: Prompts for user input, returns object with `input` promise and `abort` method.
+- **within(callback: Function)**: Creates an async context.
+- **expBackoff(max?: string, rand?: string)**: Generator for exponential backoff intervals.
+- **parseArgs(args?: string[])**: Parses command-line arguments into an object.
+- **jsType(any)**: Returns the 'real' JavaScript type.
+- **hasProp(o: any, p: string)**: Safely checks if an object has a property.
+- **Test**: Class for a minimal test framework.
+- **assert**: Node.js assert library.
+- **AsyncTracker**: Class for tracking async operations.
+
+### SHDispatch Class
+
+Returned by the `SH` template tag. Methods:
+
+- **options(options: SpawnOptions | SpawnSyncOptions, prefix?: string)**: Sets execution options.
+- **run(payload?: string)**: Executes the command asynchronously, returns Promise<string>.
+- **runSync(payload?: string)**: Executes synchronously, returns SpawnSyncReturns.
+- **kill(signal?: string)**: Kills the process.
+
+### Test Class
+
+For running tests:
+
+- **constructor(quiet?: boolean)**: Creates a test suite.
+- **syncTimeout(timeout: number)**: Sets timeout for sync tests.
+- **add(description: string, callback: Function | AsyncFunction)**: Adds a test.
+- **run(execute?: number[])**: Runs tests, returns Promise<Report>.
+- **reset()**: Clears tests.
+
+### AsyncTracker Class
+
+Tracks async operations:
+
+- **enable(type?: SystemTypes)**: Enables tracking.
+- **disable()**: Disables tracking.
+- **reset()**: Clears tracked items.
+- **report(verbose?: boolean)**: Reports unresolved async operations.
+- **getUnresolved(type?: SystemTypes)**: Gets unresolved items.
+- **getTypeDescription(type: SystemTypes)**: Gets type description.
+- **addCustomType(type: string, description: string)**: Adds custom type.
+
+### Types
+
+- **ArgsObject**: Object for parsed args, with `_` for unnamed.
+- **SpawnSyncResponse**: Result of sync spawn.
+- **SHOptions**: Options for SH execution.
+- **AsyncHookItem**: Item in async tracking.
+- **testDefinition, testReport, Report**: Types for test framework.
+
+## Dependencies
+
+**Runtime Dependencies:** None  
+
+**Dev Dependencies:**  
+- @types/node: ^22.10.10
+

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.22",
+  "version": "1.1.24",
   "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,28 +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 & { maxBuffer?: number }} options
-    */
+     * @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;
 }

package/tmp.js

@@ -1,169 +0,0 @@
-import { spawnSync, spawn, exec } 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);
-		});
-	});
-}
-
-class SHExecute {
-	#forcedKill = false;
-	/**
-	* @type {import('child_process').ChildProcess}
-	*/
-	#proc;
-	#prefix = '';
-	#command = '';
-	/** @type {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} */
-	#options = {};
-	#stdoutChunks = [];
-	#stderrChunks = [];
-	/**
-	* @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.#stdoutChunks = [];
-		this.#stderrChunks = [];
-	}
-	/**
-	* @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.#stdoutChunks.push(data);
-		});
-
-		this.#proc.stderr?.on('data', (data) => {
-			this.#stderrChunks.push(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') {
-					const stdout = this.#stdoutChunks.map(chunk => chunk.toString()).join('').trim();
-					resolve(stdout);
-				} else {
-					const stderr = this.#stderrChunks.map(chunk => chunk.toString()).join('').trim();
-					reject(new Error(`${code}: \${this.#command} "${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;
-		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;
-	}
-}
-
-export default SHExecute;