@j-o-r/sh 1.1.31 → 1.2.0

package/lib/SH.js

@@ -11,16 +11,16 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-// 
+//
 //
 // Original Source: zx
 // Link to Original Source: https://github.com/google/zx
-// Reason for Using This Code: 
-// The core functionality of this code is highly beneficial. However, certain parts of the original code 
-// were overwriting the global namespace with core libraries and variables. This was causing conflicts with 
+// Reason for Using This Code:
+// The core functionality of this code is highly beneficial. However, certain parts of the original code
+// were overwriting the global namespace with core libraries and variables. This was causing conflicts with
 // other packages (for instance, fetch) and introducing unexpected elements into my code base.
 // The main $/SH method is all there is left, with barebone Promises and readable code.
-// Changes Made: 
+// Changes Made:
 // - The code has been or is being reformatted to comply with ES2020 standards.
 // - Some methods were added and existing ones were modified or deleted to enhance usability.
 // - The namespace has been changed from '$' to 'SH'.
@@ -29,8 +29,9 @@
 import assert from 'node:assert';
 import readline from 'node:readline/promises';
 import SHDispatch from './SHDispatch.js';
-import Test from './Test.js'
-import AsyncTracker from './AsyncTracker.js'
+import Test from './Test.js';
+import AsyncTracker from './AsyncTracker.js';
+import { defaultOptions, defaultOptionKeys, clearCwdOverride, parseDuration, optionScope } from './internal.js';
 
 /**
  * Parsed command-line arguments.
@@ -38,21 +39,7 @@ import AsyncTracker from './AsyncTracker.js'
  * 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
- * @param {Error} error - The error object passed to the callback.
- */
-
-/**
- * @typedef {Function} ResolveCallback
- * @param {any} [param] - Optional callback any value
- */
-
-/**
- * @typedef {import('./SHDispatch.js').SHOptions} SHOptions
+ * @typedef {{_: string[]} & Object.<string, string|true>} ArgsObject
  */
 
 /**
@@ -62,64 +49,46 @@ import AsyncTracker from './AsyncTracker.js'
  */
 
 /**
- * Generator-like object that yields retry delay durations.
+ * Generator that yields retry delay durations in milliseconds.
  *
- * @typedef {Iterator<number|string>} ExpBackoffGenerator
+ * @typedef {Generator<number, void, unknown>} ExpBackoffGenerator
  */
 
 /**
  * Utility to determine the JavaScript type of a value.
  *
- * @param {any} fn - Any value to inspect.
+ * Uses `Object.prototype.toString`, so `jsType(null)` returns `'Null'`;
+ * `undefined` is special-cased to `'undefined'`. Plain objects report their
+ * constructor name, or `'Object'` when there is none (null-prototype objects).
+ *
+ * @param {unknown} value - Any value to inspect.
  * @returns {string} The "real" object type name (e.g., 'Array', 'Promise') or primitive typeof.
  * @example
  * jsType([]); // 'Array'
  * jsType(Promise.resolve()); // 'Promise'
+ * jsType(null); // 'Null'
+ * jsType(undefined); // 'undefined'
  */
-const jsType = (fn) => {
-	if (fn === undefined) return 'undefined';
-	const type = Object.prototype.toString.call(fn).slice(8, -1);
-	return type === 'Object' ? fn.constructor.name : type;
+const jsType = (value) => {
+	if (value === undefined) return 'undefined';
+	const type = Object.prototype.toString.call(value).slice(8, -1);
+	// Null-prototype objects have no constructor; fall back to 'Object'.
+	return type === 'Object' ? (/** @type {any} */ (value).constructor?.name ?? 'Object') : type;
 };
 
 /**
- * Checks if an object has a specific own property (code-safe).
+ * Checks if an object has a specific own property. Safe for null-prototype
+ * objects and objects shadowing `hasOwnProperty`.
  *
  * @param {any} o - Object to examine.
  * @param {string} p - Property name to check.
  * @returns {boolean} True if the object has the own property.
  */
 const hasProp = (o, p) => {
-  if (o == null) return false;
-  return Object.prototype.hasOwnProperty.call(o, p);
+	if (o == null) return false;
+	return Object.hasOwn(o, p);
 };
 
-/**
- * Parses a human-readable duration string or number into milliseconds.
- *
- * 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 the duration type or format is invalid.
- */
-const parseDuration = (d) => {
-	if (typeof d == 'number') {
-		if (!Number.isFinite(d) || d < 0)
-			throw new Error(`Invalid duration: "${d}".`);
-		return d;
-	}
-	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(`Invalid duration type: "${jsType(d)}".`);
-}
-
 /**
  * Quotes a value as one POSIX shell argument.
  *
@@ -136,32 +105,16 @@ const parseDuration = (d) => {
  */
 const bashEscape = (x) => `'${String(x).replace(/'/g, `'\\''`)}'`;
 
-/** Default options applied to all SH commands unless overridden. */
-const defaultOptions = {
-	cwd: process.cwd(),
-	env: process.env,
-	shell: 'bash',
-	stdio: ['inherit', 'pipe', 'pipe'],
-	timeout: 0, // when 0 there is no timeout
-};
-
-/** 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.
+ * Reads and writes are symmetric: only the known default option keys
+ * (`defaultOptionKeys`, derived from `defaultOptions` in `lib/internal.js`)
+ * are routed to the shared defaults. Assigning an unknown key throws a
+ * `TypeError` listing the known keys (decision D1) — this catches typos like
+ * `SH.timout = 1` instead of silently storing junk keys that read back as
+ * `undefined` and leak into every command's options. Reads of unknown keys
+ * keep normal function-proxy behavior (usually `undefined`).
  */
 const defaultOptionHandler = {
 	get(target, prop, receiver) {
@@ -171,10 +124,13 @@ const defaultOptionHandler = {
 		return Reflect.get(target, prop, receiver);
 	},
 	set(target, prop, value) {
+		if (!defaultOptionKeys.has(prop)) {
+			throw new TypeError(`Unknown SH option: "${String(prop)}". Known options: ${[...defaultOptionKeys].join(', ')}.`);
+		}
 		defaultOptions[prop] = value;
 		return true;
 	}
-}
+};
 
 /**
  * Template tag for building and executing shell commands.
@@ -189,10 +145,15 @@ const defaultOptionHandler = {
  * 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``
+ * SH also acts as a global options setter (see the last example). Global
+ * defaults are captured when each command is created, not when it runs — see
+ * the "defaults captured at creation time" note in {@link SHDispatch#options}.
+ * Only the known option keys (cwd, env, shell, stdio, timeout, maxBuffer,
+ * detached) may be assigned; assigning anything else throws a TypeError
+ * listing the known keys (typo guard, decision D1).
  *
  * @param {TemplateStringsArray} pieces - String literals from template.
- * @param {...unknown[]} args - Values to interpolate.
+ * @param {...unknown} args - Values to interpolate.
  * @returns {SHDispatch} Command dispatcher.
  * @throws {Error} If pieces contain undefined.
  * @example
@@ -204,6 +165,10 @@ const defaultOptionHandler = {
  *
  * // Quote untrusted values explicitly
  * SH`printf '%s\n' ${bashEscape('semi; colon')}`.run();
+ *
+ * // Set global defaults for subsequently created commands
+ * SH.timeout = 5000;
+ * await SH`cmd`.run();
  */
 const SH = new Proxy(function(pieces, ...args) {
 	if (pieces.some((p) => p == undefined)) {
@@ -212,7 +177,7 @@ const SH = new Proxy(function(pieces, ...args) {
 	let cmd = pieces[0], i = 0;
 	while (i < args.length) {
 		let s;
-		
+
 		if (Array.isArray(args[i])) {
 			s = args[i].map((x) => String(x)).join(' ');
 		} else {
@@ -224,24 +189,39 @@ const SH = new Proxy(function(pieces, ...args) {
 }, defaultOptionHandler);
 
 /**
- * Executes a callback in a new async context (fresh callstack).
+ * Awaits `callback()` and returns its result, running it in a fresh async
+ * context (decision D2).
+ *
+ * Real isolation via `AsyncLocalStorage`: the callback runs inside a new
+ * scope whose `SH.*` default-option assignments are scoped to the block. Any
+ * `SH.timeout = …`, `SH.cwd = …`, etc. made inside the callback apply only to
+ * commands created within it and are discarded when the block ends — they do
+ * not leak to the enclosing scope. Nested `within()` blocks inherit their
+ * parent's scoped defaults but never leak their own outward.
  *
- * Useful for parallel operations without nesting.
+ * Note: `cd()` is a genuine process-wide operation (`process.chdir`), so it is
+ * not scoped by `within()`; use `SH.cwd = dir` for a scoped working directory.
  *
  * @param {() => Promise<any>} callback - Async function to execute.
  * @returns {Promise<any>} Result of callback.
  * @example
  * const results = await within(async () => {
+ *   SH.timeout = 5000; // scoped to this block
  *   return Promise.all([SH`sleep 1; echo 1`.run(), sleep(2)]);
  * });
  */
 const within = async (callback) => {
-	return await callback();
-}
+	const parent = optionScope.getStore();
+	const store = { ...parent };
+	return optionScope.run(store, callback);
+};
 
 /**
  * Reads entire stdin as UTF-8 string. Resolves to empty string if TTY (no pipe).
  *
+ * Side effect: permanently sets the `process.stdin` encoding to utf8 and
+ * switches it to flowing mode.
+ *
  * @returns {Promise<string>} Stdin content, or an empty string if TTY.
  * @example
  * const input = await readIn(); // Use in piped scripts
@@ -254,12 +234,31 @@ const readIn = async () => {
 		buf += chunk;
 	}
 	return buf;
-}
+};
+
+/**
+ * Minimum stdin chunk length (containing a newline) that {@link userIn}
+ * treats as a paste instead of typed input.
+ */
+const PASTE_MIN_CHUNK = 4;
+
+/**
+ * Debounce delay after the last 'line' event or paste before {@link userIn}
+ * auto-resolves with the accumulated input.
+ */
+const SUBMIT_DEBOUNCE_MS = 50;
 
 /**
  * Prompts user for input on stdin with custom prompt.
  *
- * Supports aborting input collection.
+ * Submit heuristics (non-obvious): each 'line' event is accumulated into a
+ * multi-line buffer and (re)starts a debounce timer
+ * ({@link SUBMIT_DEBOUNCE_MS}); when the timer fires without further input,
+ * the promise auto-resolves with the accumulated text plus any partially
+ * typed readline line. A paste — a stdin chunk longer than
+ * {@link PASTE_MIN_CHUNK} chars containing a newline — (re)starts the same
+ * timer, so pasted multi-line text resolves as one input. `abort()` resolves
+ * the promise with `undefined`.
  *
  * @param {string} prompt - Prompt text to display.
  * @returns {AbortableInput} Object with input Promise and abort function.
@@ -269,51 +268,49 @@ const readIn = async () => {
  * // abort(); // Cancel anytime
  */
 const userIn = (prompt) => {
-  let resolvePromise;
-  const input = new Promise((resolve) => { resolvePromise = resolve; });
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  let buffer = '';
-  let timer;
-  /** @param {string} chunk */
-  const onData = (chunk) => {
-    if (chunk.length > 4 && chunk.includes('\n')) {
-      clearTimeout(timer);
-      timer = setTimeout(resolveFunc, 50);
-    }
-  };
-
-  const resolveFunc = () => {
-    let fullText = buffer;
-    if (rl.line) fullText += rl.line;
-    cleanup();
-    resolvePromise(fullText);
-  };
-
-  const cleanup = () => {
-    process.stdin.removeListener('data', onData);
-    // @ts-ignore
-    rl.removeAllListeners('line');
-    clearTimeout(timer);
-    rl.close();
-  };
-  // @ts-ignore
-  rl.on('line', (line) => {
-    buffer += line + '\n';
-    clearTimeout(timer);
-    timer = setTimeout(resolveFunc, 50);
-  });
-  process.stdin.on('data', onData);
-
-  rl.setPrompt(prompt);
-  rl.prompt();
-
-  return {
-    input,
-    abort: () => {
-      cleanup();
-      resolvePromise();
-    }
-  };
+	let resolvePromise;
+	const input = new Promise((resolve) => { resolvePromise = resolve; });
+	const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+	let buffer = '';
+	let timer;
+	/** @param {string} chunk */
+	const onData = (chunk) => {
+		if (chunk.length > PASTE_MIN_CHUNK && chunk.includes('\n')) {
+			clearTimeout(timer);
+			timer = setTimeout(resolveFunc, SUBMIT_DEBOUNCE_MS);
+		}
+	};
+
+	const resolveFunc = () => {
+		let fullText = buffer;
+		if (rl.line) fullText += rl.line;
+		cleanup();
+		resolvePromise(fullText);
+	};
+
+	const cleanup = () => {
+		process.stdin.removeListener('data', onData);
+		rl.removeAllListeners('line');
+		clearTimeout(timer);
+		rl.close();
+	};
+	rl.on('line', (line) => {
+		buffer += line + '\n';
+		clearTimeout(timer);
+		timer = setTimeout(resolveFunc, SUBMIT_DEBOUNCE_MS);
+	});
+	process.stdin.on('data', onData);
+
+	rl.setPrompt(prompt);
+	rl.prompt();
+
+	return {
+		input,
+		abort: () => {
+			cleanup();
+			resolvePromise();
+		}
+	};
 };
 
 /**
@@ -327,11 +324,16 @@ const isDelayGenerator = (value) => value != null && typeof value == 'object' &&
 /**
  * Retries an async function up to N times with optional delays.
  *
- * Delay can be fixed ('1s'), generator-like (expBackoff()), or none.
+ * Delay precedence: when `delayOrCallback` is a function it is the retried
+ * callback and there is no delay between attempts. Otherwise it is a static
+ * duration ('1s', 100) or a delay generator (e.g. {@link expBackoff}), and
+ * `callback` is the retried function. A generator yield of `undefined`
+ * (exhausted generator) or `0` means "no further delay" — the next attempt
+ * runs immediately.
  *
  * @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.
+ * @param {string|number|Iterator<number|string>|(() => (Promise<any>|any))} delayOrCallback - Delay, delay generator, or the callback when no separate callback is supplied.
+ * @param {() => (Promise<any>|any)} [callback] - Callback to retry when a delay is supplied.
  * @returns {Promise<any>} Successful result.
  * @throws {Error} If arguments are invalid, or the last callback error if all attempts fail.
  * @example
@@ -381,7 +383,7 @@ const retry = async (count, delayOrCallback, callback) => {
 			}
 		}
 	}
-}
+};
 
 /**
  * Sleeps for a specified duration.
@@ -395,19 +397,27 @@ const sleep = (duration) => {
 	return new Promise((resolve) => {
 		setTimeout(resolve, parseDuration(duration));
 	});
-}
+};
 
 /**
  * Changes the current working directory.
  *
+ * Affects the cwd of subsequent `SH` commands: default options capture
+ * `process.cwd()` lazily when each command is created. Also clears any
+ * `SH.cwd` override, so the most recent cwd change always wins.
+ *
+ * This is a genuine process-wide operation (`process.chdir`), so it is NOT
+ * scoped by {@link within}. Use `SH.cwd = dir` inside a `within()` block for a
+ * scoped working directory.
+ *
  * @param {string} dir - Path to new directory.
  * @example
  * cd('/tmp');
  */
 const cd = (dir) => {
-	// @ts-ignore
 	process.chdir(dir);
-}
+	clearCwdOverride();
+};
 
 /**
  * Generator for exponential backoff delays with jitter.
@@ -416,6 +426,7 @@ const cd = (dir) => {
  * @param {string} [max='60s'] - Max backoff duration.
  * @param {string} [rand='100ms'] - Max jitter.
  * @yields {number} Next backoff ms.
+ * @returns {ExpBackoffGenerator} Infinite generator of backoff delays in ms.
  * @example
  * const backoff = expBackoff();
  * await sleep(backoff.next().value);
@@ -444,12 +455,15 @@ const isNegativeNumberArg = (arg) => /^-(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i
  * 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`.
+ * `parseArgs(['--n', '-1'])` parse `-1` as the value for `--n`. A lone `-`
+ * is not an option either; it is parsed as a positional (the stdin
+ * convention). The `--` end-of-options terminator is handled separately in
+ * {@link parseArgs}.
  *
  * @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);
+const isOptionArg = (arg) => arg.length > 1 && arg.startsWith('-') && !isNegativeNumberArg(arg);
 
 /**
  * Parses CLI arguments into an object.
@@ -457,7 +471,9 @@ const isOptionArg = (arg) => arg.startsWith('-') && !isNegativeNumberArg(arg);
  * 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.
+ * positionals, not options. A lone `-` is a positional (stdin convention).
+ * `--` is the conventional end-of-options terminator: every token after it
+ * goes into `_`, even option-looking ones.
  *
  * Defaults to process.argv.slice(2).
  *
@@ -467,14 +483,23 @@ const isOptionArg = (arg) => arg.startsWith('-') && !isNegativeNumberArg(arg);
  * @example
  * parseArgs(['--port', '8080', 'file.txt']); // { port: '8080', _: ['file.txt'] }
  * parseArgs(['--n', '-1']); // { n: '-1', _: [] }
+ * parseArgs(['-', '--port', '1']); // { port: '1', _: ['-'] }
+ * parseArgs(['--', '--x']); // { _: ['--x'] }
  */
 const parseArgs = (args) => {
 	if (!args) args = process.argv.slice(2);
-	const result = { _: [] };
+	// @ts-ignore — '_: string[]' is the intended exception to the 'string|true' index signature of ArgsObject.
+	const result = /** @type {ArgsObject} */ ({ _: [] });
 	const seenKeys = new Set();
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i];
 
+		if (arg === '--') {
+			// End-of-options terminator: all remaining tokens are positionals.
+			result._.push(...args.slice(i + 1));
+			break;
+		}
+
 		if (isOptionArg(arg)) {
 			if (arg.startsWith('-') && !arg.startsWith('--') && arg.length > 2) {
 				throw new Error(`Invalid argument: ${arg}. Use '--' for long options.`);
@@ -484,6 +509,7 @@ const parseArgs = (args) => {
 				throw new Error(`Duplicate argument: ${arg}`);
 			}
 			seenKeys.add(key);
+			/** @type {string|true} */
 			let value;
 			if (i + 1 < args.length && !isOptionArg(args[i + 1])) {
 				value = args[i + 1];
@@ -496,7 +522,6 @@ const parseArgs = (args) => {
 			result._.push(arg);
 		}
 	}
-	// @ts-ignore
 	return result;
 };
 
@@ -516,4 +541,4 @@ export {
 	assert,
 	AsyncTracker,
 	bashEscape
-}
+};

package/lib/SHDispatch.js

@@ -1,14 +1,5 @@
 import SHExecute from './SHExecute.js';
-
-/**
- * @typedef {Object} SpawnSyncResponse
- * @property {number|null} status - Exit code (null if signal).
- * @property {string|null} signal - Terminating signal.
- * @property {(string|Buffer|null)[]} output - [stdin, stdout, stderr].
- * @property {number} pid - Process ID.
- * @property {string|Buffer|null} stdout - Captured stdout.
- * @property {string|Buffer|null} stderr - Captured stderr.
- */
+import { defaultOptions } from './internal.js';
 
 /**
  * @typedef {('pipe' | 'ignore' | 'inherit' | number)} StdioOption
@@ -33,8 +24,8 @@ import SHExecute from './SHExecute.js';
  * - `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)
+ * - `timeout`: `0` (no timeout; absolute wall-clock cap when set)
+ * - `maxBuffer`: `512000` (500 KiB per stream in SHExecute)
  *
  * Prefix (`.options(undefined, prefix)`) only for shell mode.
  *
@@ -43,21 +34,18 @@ import SHExecute from './SHExecute.js';
  * @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|string} timeout - Absolute wall-clock timeout in ms or
+ *   duration string; 0 disables. The process is killed after the full duration
+ *   no matter how much output it produces, in BOTH `run()` and `runSync()`.
+ *   This matches Node's native `spawn`/`spawnSync` `timeout` semantics; SH is
+ *   not meant to run long-lived services, so there is no rolling/idle reset.
  * @property {number} [maxBuffer] - Maximum buffered bytes per stdout/stderr stream.
- * @property {boolean} [detached] - Run process detached and resolve early.
+ * @property {boolean} [detached] - Run process detached and resolve early (~1s).
+ *   Unless stdio is explicitly set for the command, stdio is forced to
+ *   `'ignore'`, because open pipes would keep the parent's event loop alive.
  * @example { timeout: '5s', stdio: 'inherit', shell: false, maxBuffer: 10 * 1024}
  */
 
-/** @type {SHOptions} */
-const defaultSHOptions = {
-	cwd: process.cwd(),
-	env: process.env,
-	shell: 'bash',
-	stdio: ['inherit', 'pipe', 'pipe'],
-	timeout: 0,
-};
-
 /**
  * Merges user options into predefined defaults (non-destructive).
  *
@@ -94,9 +82,11 @@ class SHDispatch {
 	#prefix = '';
 	#cmd = '';
 	/** @type {SHOptions} */
-	#options = { ...defaultSHOptions };
+	#options = { ...defaultOptions };
 	/** @type {SHExecute | null} */
 	#proc = null;
+	/** Whether the user explicitly supplied `stdio` for this command. */
+	#stdioProvided = false;
 
 	/**
 	 * @param {string} cmd - Command string.
@@ -106,7 +96,7 @@ class SHDispatch {
 	 */
 	constructor(cmd, options = {}, prefix) {
 		if (typeof cmd !== 'string' || cmd === '') {
-			throw new Error('Undefined command');
+			throw new Error('Invalid or empty command');
 		}
 		this.#cmd = cmd;
 		this.options(options, prefix);
@@ -131,6 +121,9 @@ class SHDispatch {
 			return this;
 		}
 		const nextOptions = { ...options };
+		if (nextOptions.stdio !== undefined) {
+			this.#stdioProvided = true;
+		}
 		if (nextOptions.stdio && typeof nextOptions.stdio === 'string') {
 			// convert stdio to array
 			const io = nextOptions.stdio;
@@ -143,11 +136,21 @@ class SHDispatch {
 	/**
 	 * Async run: Captures stdout; rejects on error/timeout.
 	 *
+	 * Replaces the internal process handle: calling `run()` again while a
+	 * previous run is still active makes that first process unkillable via
+	 * `kill()`.
+	 *
 	 * @param {string} [payload] - Stdin payload.
 	 * @returns {Promise<string>} Stdout.
 	 */
 	run(payload) {
-		this.#proc = new SHExecute(this.#cmd, this.#prefix, this.#options);
+		// Detached processes must not keep piped stdio: open pipe handles hold
+		// the parent's event loop alive and defeat detachment. Force 'ignore'
+		// unless the user explicitly chose a stdio setup for this command.
+		const options = this.#options.detached && !this.#stdioProvided
+			? { ...this.#options, stdio: 'ignore' }
+			: this.#options;
+		this.#proc = new SHExecute(this.#cmd, this.#prefix, options);
 		return this.#proc.run(payload);
 	}