@j-o-r/sh 1.1.29 → 1.1.31

package/README.md

@@ -13,7 +13,7 @@ Execute shell commands from JavaScript on Linux.
 - Utils: `sleep`, `retry`, `expBackoff`, `cd`, `parseArgs`, `userIn`, `readIn`.
 - Testing: `new Test().add('name', () => assert(...)).run()`.
 - Async leak detection: `AsyncTracker` via `async_hooks`.
-- Safe interpolation; `bashEscape`; full JSDoc.
+- Raw-by-default interpolation with explicit `bashEscape` quoting for untrusted argument values; full JSDoc.
 
 No runtime deps. ESM-only (ES2020+).
 
@@ -35,6 +35,35 @@ const out = await SH`ls -la`.run();
 console.log(out); // Captured stdout (trimmed)
 ```
 
+### Interpolation: raw by default
+
+Interpolated values are inserted into the shell command as raw shell source. This
+is convenient for trusted shell fragments such as flags, pipes, redirects, and
+compound expressions, but it is **not safe for untrusted input**.
+
+```js
+import { SH, bashEscape } from '@j-o-r/sh';
+
+const flags = ['-l', '-a'];
+await SH`ls ${flags}`.run();       // Executes: ls -l -a
+
+const fragment = 'printf ok; printf done';
+await SH`${fragment}`.run();       // Raw shell syntax is intentional
+
+const userInput = 'name; rm -rf /';
+await SH`printf '%s\n' ${bashEscape(userInput)}`.run();
+// Prints the value literally instead of executing `rm`.
+```
+
+`bashEscape(value)` returns one POSIX-shell-quoted argument. It preserves empty
+strings, whitespace, quotes, semicolons, glob characters, tabs, and newlines.
+For arrays of untrusted values, quote each element yourself:
+
+```js
+const args = ['two words', 'semi;colon', "quote's"];
+await SH`printf '%s\n' ${args.map(bashEscape)}`.run();
+```
+
 ### Chaining & Options
 
 ```js
@@ -140,9 +169,9 @@ Full JSDoc in `lib/*.js`. Key exports:
 | `Test` | Test runner |
 | `AsyncTracker` | Async leak detector |
 | `parseArgs(argv)` | CLI parser |
-| `bashEscape(str)` | Shell-safe string |
+| `bashEscape(value)` | Quote one value as a POSIX shell argument for safe interpolation |
 
-See [types/index.d.ts](types/index.d.ts) for TS defs.
+See [types/SH.d.ts](types/SH.d.ts) for TS defs.
 
 ## Development
 

package/TODO.md

@@ -1,18 +1,8 @@
 # TODOs for @j-o-r/sh project
 
-## High Priority (pending)
-- [ ] Review and commit recent changes to lib/ files and types/ (from git status: modified AsyncTracker.js, SH.js, etc.)
-- [*] Generate or improve API documentation using types/*.d.ts files
+## lib/SH.js review findings (2026-06-26)
 
 ## In Progress
-- [ ]
-
-## Later (future tasks)
-- [ ] Create separate docs folder with full API reference
 
 ## Done
-- [x] Initial project setup from package.json and README.md inspection (2026-04-15)
-- [x] Update README.md to include documentation for recent changes in AsyncTracker and Test features (2026-04-15)
-- [x] Add more examples to README.md for SHDispatch methods and utilities like retry and expBackoff (2026-04-15)
-- [x] Reference general SSH example in README.md (demo-interactive-ssh.js not found in scenarios/) (2026-04-15)
-- [x] Reduce SHExecute maxBuffer default from 40MB to 1MB, update all docs/JSDoc mentioning it. Make sure global SH.maxBuffer works. (2026-04-15)
+

package/lib/SH.js

@@ -33,10 +33,12 @@ import Test from './Test.js'
 import AsyncTracker from './AsyncTracker.js'
 
 /**
- * @typedef {Object.<string, string>} ArgsObject
- * @property {string[]} _ - Array of strings, unnamed parameters
- * @property {string} [key: string] - Any string key maps to a string value
- * @description Parsed parameters result.
+ * Parsed command-line arguments.
+ *
+ * Named options map to their string value, or `true` when no value is supplied.
+ * Bare positional arguments are collected in `_`.
+ *
+ * @typedef {{_: string[]} & Object.<string, string|true|string[]>} ArgsObject
  */
 
 /**
@@ -60,9 +62,9 @@ import AsyncTracker from './AsyncTracker.js'
  */
 
 /**
- * @typedef {Object} ExpBackoffGenerator
- * @generator
- * @yields {number} Backoff time in ms.
+ * Generator-like object that yields retry delay durations.
+ *
+ * @typedef {Iterator<number|string>} ExpBackoffGenerator
  */
 
 /**
@@ -95,50 +97,44 @@ const hasProp = (o, p) => {
 /**
  * Parses a human-readable duration string or number into milliseconds.
  *
- * Supports: '5s' (5000ms), '100ms' (100ms), plain numbers (ms).
+ * Supports finite non-negative numbers as milliseconds, plus exact string forms
+ * with units: '5s' (5000ms) and '100ms' (100ms).
  *
  * @param {number|string} d - Duration as number (ms) or string ('5s', '100ms').
  * @returns {number} Duration in milliseconds.
- * @throws {Error} If invalid duration format.
+ * @throws {Error} If the duration type or format is invalid.
  */
 const parseDuration = (d) => {
 	if (typeof d == 'number') {
-		if (isNaN(d) || d < 0)
+		if (!Number.isFinite(d) || d < 0)
 			throw new Error(`Invalid duration: "${d}".`);
 		return d;
 	}
-	else if (/\d+s/.test(d)) {
-		return +d.slice(0, -1) * 1000;
-	}
-	else if (/\d+ms/.test(d)) {
-		return +d.slice(0, -2);
+	if (typeof d == 'string') {
+		const match = d.match(/^(\d+)(ms|s)$/);
+		if (!match)
+			throw new Error(`Unknown duration: "${d}".`);
+		const amount = Number(match[1]);
+		return match[2] == 's' ? amount * 1000 : amount;
 	}
-	throw new Error(`Unknown duration: "${d}".`);
+	throw new Error(`Invalid duration type: "${jsType(d)}".`);
 }
 
 /**
- * Escapes a string for safe use as a bash command-line argument.
+ * Quotes a value as one POSIX shell argument.
  *
- * Handles quotes, backticks, $, newlines, etc.
+ * The `SH` template tag interpolates values as raw shell source by default. Use
+ * this helper when a JavaScript value must be passed as data instead of shell
+ * syntax. The returned string is single-quoted and preserves the exact string
+ * value, including leading/trailing whitespace, empty strings, quotes,
+ * semicolons, glob characters, tabs, and newlines.
  *
- * @param {string} x - Input string to escape.
- * @returns {string} Bash-escaped string.
+ * @param {unknown} x - Value to quote as a single shell argument.
+ * @returns {string} POSIX-shell-quoted argument string.
+ * @example
+ * await SH`printf '%s\n' ${bashEscape(userInput)}`.run();
  */
-const bashEscape = (x) => {
-	let str = String(x).trim();
-	// the trick is to double escape escape vars first
-	str = str.replace(/\\/g, '\\\\');
-	// then add escaping for oddities
-	// Replace literal escape sequences like \n, \t, \r in quoted strings
-	str = str.replace(/(['"])\\(.)\1/g, '$1\\\\$2$1');
-	// escape $ (is a BASH var)
-	str = str.replace(/\$/g, '\\$');
-	// Escape backticks
-	str = str.replace(/`/g, '\\`');
-	// Escape quotes
-	str = str.replace(/"/g, '\\"');
-	return str;
-}
+const bashEscape = (x) => `'${String(x).replace(/'/g, `'\\''`)}'`;
 
 /** Default options applied to all SH commands unless overridden. */
 const defaultOptions = {
@@ -149,12 +145,35 @@ const defaultOptions = {
 	timeout: 0, // when 0 there is no timeout
 };
 
-/** Proxy set trap for dynamically updating defaultOptions via SH.prop = value */
-const setHandler = {
-  set(target, prop, value) {
-    defaultOptions[prop] = value;
-    return true;
-  }
+/** Known global option properties exposed for `SH.option` readback. */
+const defaultOptionKeys = new Set([
+	'cwd',
+	'env',
+	'shell',
+	'stdio',
+	'timeout',
+	'maxBuffer',
+	'detached',
+]);
+
+/**
+ * Proxy traps for the SH template tag and global option defaults.
+ *
+ * Assignments keep the existing compatibility behavior by storing every property
+ * in defaultOptions. Reads only expose known default option keys, so unknown
+ * property access continues to behave like a normal function proxy read.
+ */
+const defaultOptionHandler = {
+	get(target, prop, receiver) {
+		if (defaultOptionKeys.has(prop)) {
+			return defaultOptions[prop];
+		}
+		return Reflect.get(target, prop, receiver);
+	},
+	set(target, prop, value) {
+		defaultOptions[prop] = value;
+		return true;
+	}
 }
 
 /**
@@ -162,9 +181,13 @@ const setHandler = {
  *
  * Returns an {@link SHDispatch} instance for configuration (.options()) and execution (.run(), .runSync()).
  *
- * Interpolation rules:
- * - Arrays: Elements trimmed, newlines/tabs escaped, shell-special chars single-quoted with '\'' escape.
- * - Other values: String(value) inserted as-is (NOT auto-escaped; use {@link bashEscape} for safety).
+ * Interpolation rules are raw-by-default:
+ * - Arrays: Each element is converted with `String(value)` and joined with one space.
+ * - Other values: `String(value)` is inserted directly into the shell source.
+ *
+ * Raw interpolation allows trusted shell fragments such as pipes, redirects, and
+ * command separators. It is not safe for untrusted input. Wrap untrusted values
+ * with {@link bashEscape} before interpolating them.
  *
  * SH acts as both template tag and options setter: `SH.timeout = 5000; SH`cmd``
  *
@@ -176,8 +199,11 @@ const setHandler = {
  * const cmd = SH`echo ${'Hello'}`;
  * await cmd.run(); // Executes: echo Hello
  *
- * // Array interpolation
- * SH`ls ${['-la', '/']}`.run(); // ls '-la' '/'
+ * // Array interpolation is raw and joins with spaces
+ * SH`ls ${['-la', '/']}`.run(); // Executes: ls -la /
+ *
+ * // Quote untrusted values explicitly
+ * SH`printf '%s\n' ${bashEscape('semi; colon')}`.run();
  */
 const SH = new Proxy(function(pieces, ...args) {
 	if (pieces.some((p) => p == undefined)) {
@@ -188,25 +214,14 @@ const SH = new Proxy(function(pieces, ...args) {
 		let s;
 		
 		if (Array.isArray(args[i])) {
-			// @ts-ignore
-			s = args[i].map(/** @param {string} x */(x) => {
-				// Trim every element
-				let str = String(x).trim();
-        str = str.replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t');
-				// If the string contains special characters, wrap in single quotes
-				if (str.match(/[ "'$`(){}[\]]/)) {
-					// Escape single quotes within the string
-					return `'${str.replace(/'/g, `'\\''`)}'`;
-				}
-				return str;
-			}).join(' ');
+			s = args[i].map((x) => String(x)).join(' ');
 		} else {
 			s = String(args[i]);
 		}
 		cmd += s + pieces[++i];
 	}
 	return new SHDispatch(cmd, defaultOptions);
-}, setHandler);
+}, defaultOptionHandler);
 
 /**
  * Executes a callback in a new async context (fresh callstack).
@@ -227,12 +242,12 @@ const within = async (callback) => {
 /**
  * Reads entire stdin as UTF-8 string. Resolves to empty string if TTY (no pipe).
  *
- * @returns {Promise<string|undefined>} Stdin content or undefined if TTY.
+ * @returns {Promise<string>} Stdin content, or an empty string if TTY.
  * @example
  * const input = await readIn(); // Use in piped scripts
  */
 const readIn = async () => {
-	if (process.stdin.isTTY) return;
+	if (process.stdin.isTTY) return '';
 	let buf = '';
 	process.stdin.setEncoding('utf8');
 	for await (const chunk of process.stdin) {
@@ -301,59 +316,71 @@ const userIn = (prompt) => {
   };
 };
 
+/**
+ * Checks whether a value is a generator-like retry delay source.
+ *
+ * @param {unknown} value - Value to inspect.
+ * @returns {boolean} True when value has a callable `next()` method.
+ */
+const isDelayGenerator = (value) => value != null && typeof value == 'object' && typeof value.next == 'function';
+
 /**
  * Retries an async function up to N times with optional delays.
  *
- * Delay can be fixed ('1s'), generator (expBackoff()), or none.
+ * Delay can be fixed ('1s'), generator-like (expBackoff()), or none.
  *
- * @param {number} count - Number of attempts.
- * @param {string|number|ExpBackoffGenerator|Function} delayOrFn - Delay or callback if no separate fn.
- * @param {Function} [fn] - Callback to retry (if delayOrFn not function).
+ * @param {number} count - Positive integer number of attempts.
+ * @param {string|number|ExpBackoffGenerator|Function} delayOrCallback - Delay, delay generator, or callback if no separate callback is supplied.
+ * @param {Function} [callback] - Callback to retry when a delay is supplied.
  * @returns {Promise<any>} Successful result.
- * @throws {Error} Last error if all attempts fail.
+ * @throws {Error} If arguments are invalid, or the last callback error if all attempts fail.
  * @example
  * await retry(3, '1s', () => SH`curl http://unreliable`.run());
  * await retry(3, expBackoff(), () => flakyOp());
  */
-const retry = async (count, a, b) => {
-	let callback;
+const retry = async (count, delayOrCallback, callback) => {
+	if (!Number.isInteger(count) || count < 1) {
+		throw new Error(`Invalid retry count: "${count}". Expected a positive integer.`);
+	}
+
+	let retryCallback;
 	let delayStatic = 0;
 	let delayGen;
-	// @ts-ignore
-	if (typeof a == 'function') {
-		callback = a;
+
+	if (typeof delayOrCallback == 'function') {
+		retryCallback = delayOrCallback;
 	}
 	else {
-		if (typeof a == 'object') {
-			delayGen = a;
+		if (typeof callback != 'function') {
+			throw new Error(`Invalid retry callback: expected a function.`);
+		}
+		retryCallback = callback;
+
+		if (isDelayGenerator(delayOrCallback)) {
+			delayGen = delayOrCallback;
+		}
+		else if (delayOrCallback != null && typeof delayOrCallback == 'object') {
+			throw new Error(`Invalid retry delay generator: expected an object with next().`);
 		}
 		else {
-			delayStatic = parseDuration(a);
+			delayStatic = parseDuration(delayOrCallback);
 		}
-		assert(b);
-		callback = b;
 	}
-	let lastErr;
-	let attempt = 0;
-	while (count-- > 0) {
-		attempt++;
+
+	for (let attempt = 1; attempt <= count; attempt++) {
 		try {
-			return await callback();
+			return await retryCallback();
 		}
 		catch (err) {
-			let delay = 0;
-			if (delayStatic > 0)
-				delay = delayStatic;
-			// @ts-ignore
-			if (delayGen) delay = delayGen.next().value;
-			lastErr = err;
-			if (count == 0)
-				break;
-			if (delay)
+			if (attempt == count) {
+				throw err;
+			}
+			const delay = delayGen ? delayGen.next().value : delayStatic;
+			if (delay) {
 				await sleep(delay);
+			}
 		}
 	}
-	throw lastErr;
 }
 
 /**
@@ -403,11 +430,34 @@ function* expBackoff(max = '60s', rand = '100ms') {
 	}
 }
 
+/**
+ * Matches negative number tokens that should be parsed as values, not options.
+ *
+ * Supports decimal and exponent forms such as `-1`, `-0.5`, `-.5`, and `-1e3`.
+ *
+ * @param {string} arg - CLI argument token.
+ * @returns {boolean} True when the token is a negative numeric value.
+ */
+const isNegativeNumberArg = (arg) => /^-(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(arg);
+
+/**
+ * Checks whether a token should be parsed as an option.
+ *
+ * Negative numeric values are intentionally excluded so calls like
+ * `parseArgs(['--n', '-1'])` parse `-1` as the value for `--n`.
+ *
+ * @param {string} arg - CLI argument token.
+ * @returns {boolean} True when the token should be parsed as an option.
+ */
+const isOptionArg = (arg) => arg.startsWith('-') && !isNegativeNumberArg(arg);
+
 /**
  * Parses CLI arguments into an object.
  *
  * Supports --key value, -k value (no shorts grouped).
  * Bares go to _[]. Duplicates error. No = syntax.
+ * Negative number tokens such as -1, -0.5, and -1e3 are parsed as values or
+ * positionals, not options.
  *
  * Defaults to process.argv.slice(2).
  *
@@ -416,23 +466,26 @@ function* expBackoff(max = '60s', rand = '100ms') {
  * @throws {Error} On invalid/dupe args.
  * @example
  * parseArgs(['--port', '8080', 'file.txt']); // { port: '8080', _: ['file.txt'] }
+ * parseArgs(['--n', '-1']); // { n: '-1', _: [] }
  */
 const parseArgs = (args) => {
 	if (!args) args = process.argv.slice(2);
 	const result = { _: [] };
 	const seenKeys = new Set();
 	for (let i = 0; i < args.length; i++) {
-		if (args[i].startsWith('--') || args[i].startsWith('-')) {
-			if (args[i].startsWith('-') && !args[i].startsWith('--') && args[i].length > 2) {
-				throw new Error(`Invalid argument: ${args[i]}. Use '--' for long options.`);
+		const arg = args[i];
+
+		if (isOptionArg(arg)) {
+			if (arg.startsWith('-') && !arg.startsWith('--') && arg.length > 2) {
+				throw new Error(`Invalid argument: ${arg}. Use '--' for long options.`);
 			}
-			const key = args[i].startsWith('--') ? args[i].substring(2) : args[i].substring(1);
+			const key = arg.startsWith('--') ? arg.substring(2) : arg.substring(1);
 			if (seenKeys.has(key)) {
-				throw new Error(`Duplicate argument: ${args[i]}`);
+				throw new Error(`Duplicate argument: ${arg}`);
 			}
 			seenKeys.add(key);
 			let value;
-			if (args[i + 1] && !args[i + 1].startsWith('-')) {
+			if (i + 1 < args.length && !isOptionArg(args[i + 1])) {
 				value = args[i + 1];
 				i++; // Skip next element as it is a value
 			} else {
@@ -440,7 +493,7 @@ const parseArgs = (args) => {
 			}
 			result[key] = value;
 		} else {
-			result._.push(args[i]);
+			result._.push(arg);
 		}
 	}
 	// @ts-ignore

package/lib/SHDispatch.js

@@ -34,13 +34,23 @@ import SHExecute from './SHExecute.js';
  * - `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))
+ * - `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}
  */
-const SHOptions = {
+
+/** @type {SHOptions} */
+const defaultSHOptions = {
 	cwd: process.cwd(),
 	env: process.env,
 	shell: 'bash',
@@ -53,9 +63,9 @@ const SHOptions = {
  *
  * Only copies defined keys.
  *
- * @param {typeof SHOptions} predefined - Base options.
- * @param {Partial<typeof SHOptions>} options - Overrides.
- * @returns {typeof SHOptions} Merged options.
+ * @param {SHOptions} predefined - Base options.
+ * @param {Partial<SHOptions>} options - Overrides.
+ * @returns {SHOptions} Merged options.
  */
 const mergeOptions = (predefined, options) => {
 	const mergedObj = { ...predefined };
@@ -83,13 +93,14 @@ const mergeOptions = (predefined, options) => {
 class SHDispatch {
 	#prefix = '';
 	#cmd = '';
-	#options = SHOptions;
+	/** @type {SHOptions} */
+	#options = { ...defaultSHOptions };
 	/** @type {SHExecute | null} */
 	#proc = null;
 
 	/**
 	 * @param {string} cmd - Command string.
-	 * @param {Partial<typeof SHOptions>} [options] - Initial options.
+	 * @param {Partial<SHOptions>} [options] - Initial options.
 	 * @param {string} [prefix] - Shell prefix (e.g., 'set -euo pipefail').
 	 * @throws {Error} Invalid/empty cmd.
 	 */
@@ -102,11 +113,13 @@ class SHDispatch {
 	}
 
 	/**
-	 * Updates options/prefix; resets to defaults + user overrides (non-cumulative).
+	 * Updates options/prefix by merging into the dispatch instance's current options.
 	 *
-	 * Strings for `stdio` → array fill.
+	 * 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<typeof SHOptions>} [options] - New options.
+	 * @param {Partial<SHOptions>} [options] - New options.
 	 * @param {string} [prefix] - New prefix.
 	 * @returns {SHDispatch} Self for chaining.
 	 */
@@ -117,12 +130,13 @@ class SHDispatch {
 		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
-			const io = options.stdio;
-			options.stdio = Array(3).fill(io);
+			const io = nextOptions.stdio;
+			nextOptions.stdio = Array(3).fill(io);
 		}
-		this.#options = mergeOptions(SHOptions, options);
+		this.#options = mergeOptions(this.#options, nextOptions);
 		return this;
 	}
 

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.29",
+  "version": "1.1.31",
   "description": "Execute shell commands on Linux-based systems from javascript",
   "main": "lib/SH.js",
   "types": "types/SH.d.ts",
@@ -49,4 +49,4 @@
     "process-promise",
     "process-output"
   ]
-}
+}

package/types/SH.d.ts

@@ -1,5 +1,13 @@
+/**
+ * Parsed command-line arguments.
+ *
+ * Named options map to their string value, or `true` when no value is supplied.
+ * Bare positional arguments are collected in `_`.
+ */
 export type ArgsObject = {
-    [x: string]: string;
+    _: string[];
+} & {
+    [x: string]: string | true | string[];
 };
 export type RejectCallback = Function;
 export type ResolveCallback = Function;
@@ -14,15 +22,22 @@ export type AbortableInput = {
      */
     abort: () => void;
 };
-export type ExpBackoffGenerator = Object;
+/**
+ * Generator-like object that yields retry delay durations.
+ */
+export type ExpBackoffGenerator = Iterator<number | string>;
 /**
  * Template tag for building and executing shell commands.
  *
  * Returns an {@link SHDispatch} instance for configuration (.options()) and execution (.run(), .runSync()).
  *
- * Interpolation rules:
- * - Arrays: Elements trimmed, newlines/tabs escaped, shell-special chars single-quoted with '\'' escape.
- * - Other values: String(value) inserted as-is (NOT auto-escaped; use {@link bashEscape} for safety).
+ * Interpolation rules are raw-by-default:
+ * - Arrays: Each element is converted with `String(value)` and joined with one space.
+ * - Other values: `String(value)` is inserted directly into the shell source.
+ *
+ * Raw interpolation allows trusted shell fragments such as pipes, redirects, and
+ * command separators. It is not safe for untrusted input. Wrap untrusted values
+ * with {@link bashEscape} before interpolating them.
  *
  * SH acts as both template tag and options setter: `SH.timeout = 5000; SH`cmd``
  *
@@ -34,8 +49,11 @@ export type ExpBackoffGenerator = Object;
  * const cmd = SH`echo ${'Hello'}`;
  * await cmd.run(); // Executes: echo Hello
  *
- * // Array interpolation
- * SH`ls ${['-la', '/']}`.run(); // ls '-la' '/'
+ * // Array interpolation is raw and joins with spaces
+ * SH`ls ${['-la', '/']}`.run(); // Executes: ls -la /
+ *
+ * // Quote untrusted values explicitly
+ * SH`printf '%s\n' ${bashEscape('semi; colon')}`.run();
  */
 export const SH: any;
 /**
@@ -58,26 +76,26 @@ export function sleep(duration: string | number): Promise<void>;
 /**
  * Retries an async function up to N times with optional delays.
  *
- * Delay can be fixed ('1s'), generator (expBackoff()), or none.
+ * Delay can be fixed ('1s'), generator-like (expBackoff()), or none.
  *
- * @param {number} count - Number of attempts.
- * @param {string|number|ExpBackoffGenerator|Function} delayOrFn - Delay or callback if no separate fn.
- * @param {Function} [fn] - Callback to retry (if delayOrFn not function).
+ * @param {number} count - Positive integer number of attempts.
+ * @param {string|number|ExpBackoffGenerator|Function} delayOrCallback - Delay, delay generator, or callback if no separate callback is supplied.
+ * @param {Function} [callback] - Callback to retry when a delay is supplied.
  * @returns {Promise<any>} Successful result.
- * @throws {Error} Last error if all attempts fail.
+ * @throws {Error} If arguments are invalid, or the last callback error if all attempts fail.
  * @example
  * await retry(3, '1s', () => SH`curl http://unreliable`.run());
  * await retry(3, expBackoff(), () => flakyOp());
  */
-export function retry(count: number, a: any, b: any): Promise<any>;
+export function retry(count: number, delayOrCallback: string | number | ExpBackoffGenerator | Function, callback?: Function): Promise<any>;
 /**
  * Reads entire stdin as UTF-8 string. Resolves to empty string if TTY (no pipe).
  *
- * @returns {Promise<string|undefined>} Stdin content or undefined if TTY.
+ * @returns {Promise<string>} Stdin content, or an empty string if TTY.
  * @example
  * const input = await readIn(); // Use in piped scripts
  */
-export function readIn(): Promise<string | undefined>;
+export function readIn(): Promise<string>;
 /**
  * Prompts user for input on stdin with custom prompt.
  *
@@ -121,6 +139,8 @@ export function expBackoff(max?: string, rand?: string): Generator<number, void,
  *
  * Supports --key value, -k value (no shorts grouped).
  * Bares go to _[]. Duplicates error. No = syntax.
+ * Negative number tokens such as -1, -0.5, and -1e3 are parsed as values or
+ * positionals, not options.
  *
  * Defaults to process.argv.slice(2).
  *
@@ -129,13 +149,16 @@ export function expBackoff(max?: string, rand?: string): Generator<number, void,
  * @throws {Error} On invalid/dupe args.
  * @example
  * parseArgs(['--port', '8080', 'file.txt']); // { port: '8080', _: ['file.txt'] }
+ * parseArgs(['--n', '-1']); // { n: '-1', _: [] }
  */
 export function parseArgs(args?: string[]): ArgsObject;
 /**
- * @typedef {Object.<string, string>} ArgsObject
- * @property {string[]} _ - Array of strings, unnamed parameters
- * @property {string} [key: string] - Any string key maps to a string value
- * @description Parsed parameters result.
+ * Parsed command-line arguments.
+ *
+ * Named options map to their string value, or `true` when no value is supplied.
+ * Bare positional arguments are collected in `_`.
+ *
+ * @typedef {{_: string[]} & Object.<string, string|true|string[]>} ArgsObject
  */
 /**
  * @typedef {Function} RejectCallback
@@ -154,9 +177,9 @@ export function parseArgs(args?: string[]): ArgsObject;
  * @property {() => void} abort - Function to abort input collection.
  */
 /**
- * @typedef {Object} ExpBackoffGenerator
- * @generator
- * @yields {number} Backoff time in ms.
+ * Generator-like object that yields retry delay durations.
+ *
+ * @typedef {Iterator<number|string>} ExpBackoffGenerator
  */
 /**
  * Utility to determine the JavaScript type of a value.
@@ -180,12 +203,18 @@ import Test from './Test.js';
 import assert from 'node:assert';
 import AsyncTracker from './AsyncTracker.js';
 /**
- * Escapes a string for safe use as a bash command-line argument.
+ * Quotes a value as one POSIX shell argument.
  *
- * Handles quotes, backticks, $, newlines, etc.
+ * The `SH` template tag interpolates values as raw shell source by default. Use
+ * this helper when a JavaScript value must be passed as data instead of shell
+ * syntax. The returned string is single-quoted and preserves the exact string
+ * value, including leading/trailing whitespace, empty strings, quotes,
+ * semicolons, glob characters, tabs, and newlines.
  *
- * @param {string} x - Input string to escape.
- * @returns {string} Bash-escaped string.
+ * @param {unknown} x - Value to quote as a single shell argument.
+ * @returns {string} POSIX-shell-quoted argument string.
+ * @example
+ * await SH`printf '%s\n' ${bashEscape(userInput)}`.run();
  */
-export function bashEscape(x: string): string;
+export function bashEscape(x: unknown): string;
 export { Test, assert, AsyncTracker };

package/types/SHDispatch.d.ts

@@ -27,6 +27,49 @@ export type SpawnSyncResponse = {
 };
 export type StdioOption = ("pipe" | "ignore" | "inherit" | number);
 export type StdioOptions = Array<StdioOption> | StdioOption;
+/**
+ * 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.
+ */
+export type SHOptions = {
+    /**
+     * - Working directory for spawned commands.
+     */
+    cwd: string;
+    /**
+     * - Environment for spawned commands.
+     */
+    env: NodeJS.ProcessEnv;
+    /**
+     * - Shell executable, true for bash, or false for no-shell mode.
+     */
+    shell: string | boolean;
+    /**
+     * - Stdio config passed to child_process.
+     */
+    stdio: StdioOptions;
+    /**
+     * - Rolling timeout in ms or duration string; 0 disables timeout.
+     */
+    timeout: number | string;
+    /**
+     * - Maximum buffered bytes per stdout/stderr stream.
+     */
+    maxBuffer?: number | undefined;
+    /**
+     * - Run process detached and resolve early.
+     */
+    detached?: boolean | undefined;
+};
 /**
  * High-level command dispatcher.
  *
@@ -41,21 +84,23 @@ export type StdioOptions = Array<StdioOption> | StdioOption;
 declare class SHDispatch {
     /**
      * @param {string} cmd - Command string.
-     * @param {Partial<typeof SHOptions>} [options] - Initial options.
+     * @param {Partial<SHOptions>} [options] - Initial options.
      * @param {string} [prefix] - Shell prefix (e.g., 'set -euo pipefail').
      * @throws {Error} Invalid/empty cmd.
      */
-    constructor(cmd: string, options?: Partial<typeof SHOptions>, prefix?: string);
+    constructor(cmd: string, options?: Partial<SHOptions>, prefix?: string);
     /**
-     * Updates options/prefix; resets to defaults + user overrides (non-cumulative).
+     * Updates options/prefix by merging into the dispatch instance's current options.
      *
-     * Strings for `stdio` → array fill.
+     * 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<typeof SHOptions>} [options] - New options.
+     * @param {Partial<SHOptions>} [options] - New options.
      * @param {string} [prefix] - New prefix.
      * @returns {SHDispatch} Self for chaining.
      */
-    options(options?: Partial<typeof SHOptions>, prefix?: string): SHDispatch;
+    options(options?: Partial<SHOptions>, prefix?: string): SHDispatch;
     /**
      * Async run: Captures stdout; rejects on error/timeout.
      *
@@ -81,10 +126,3 @@ declare class SHDispatch {
     kill(signal?: number | string): Promise<number[]>;
     #private;
 }
-declare namespace SHOptions {
-    let cwd: string;
-    let env: NodeJS.ProcessEnv;
-    let shell: string;
-    let stdio: string[];
-    let timeout: number;
-}