@j-o-r/sh 1.1.29 → 1.1.32

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
@@ -34,28 +25,34 @@ 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 KiB 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 - Timeout in ms or duration string; 0 disables.
+ *   Async `run()` uses a rolling timeout that resets on stdout/stderr data.
+ *   `runSync()` passes it to `spawnSync`, where it is absolute: the process is
+ *   killed after the full duration no matter how much output it produces.
+ * @property {number} [maxBuffer] - Maximum buffered bytes per stdout/stderr stream.
+ * @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}
  */
-const SHOptions = {
-	cwd: process.cwd(),
-	env: process.env,
-	shell: 'bash',
-	stdio: ['inherit', 'pipe', 'pipe'],
-	timeout: 0,
-};
 
 /**
  * Merges user options into predefined defaults (non-destructive).
  *
  * 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,30 +80,35 @@ const mergeOptions = (predefined, options) => {
 class SHDispatch {
 	#prefix = '';
 	#cmd = '';
-	#options = SHOptions;
+	/** @type {SHOptions} */
+	#options = { ...defaultOptions };
 	/** @type {SHExecute | null} */
 	#proc = null;
+	/** Whether the user explicitly supplied `stdio` for this command. */
+	#stdioProvided = false;
 
 	/**
 	 * @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, 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);
 	}
 
 	/**
-	 * 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,23 +119,37 @@ class SHDispatch {
 		if (!options) {
 			return this;
 		}
-		if (options.stdio && typeof options.stdio === 'string') {
+		const nextOptions = { ...options };
+		if (nextOptions.stdio !== undefined) {
+			this.#stdioProvided = true;
+		}
+		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;
 	}
 
 	/**
 	 * 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);
 	}
 

package/lib/SHExecute.js

@@ -1,58 +1,37 @@
 import { spawnSync, spawn } from 'node:child_process';
-
-/**
- * Validates if a number is a finite positive integer (including 0).
- *
- * @param {unknown} n - Value to check.
- * @returns {boolean} True if finite non-negative integer.
- */
-const isFinitePosInt = (n) => Number.isFinite(n) && n >= 0;
-
-/**
- * Parses a human-readable duration into milliseconds.
- *
- * Supports: numbers (ms), '250ms', '2s'. null/undefined → 0; invalid → throws.
- *
- * @param {number|string|null|undefined} d - Duration input.
- * @returns {number} ms.
- * @throws {Error} Invalid format/type.
- */
-const parseDuration = (d) => {
-  if (typeof d === 'number') return isFinitePosInt(d) ? d : (() => { throw new Error('Invalid duration'); })();
-  if (typeof d === 'string') {
-    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');
-};
+import { DEFAULT_MAX_BUFFER, parseDuration } from './internal.js';
 
 /**
  * Retrieves child PIDs of a given parent PID using pgrep -P.
  *
+ * Best-effort: any pgrep failure resolves to an empty list so callers
+ * (notably `kill()`) always settle instead of hanging.
+ *
  * @param {number} pid - Parent PID.
  * @returns {Promise<number[]>} Array of child PIDs.
  */
 const childrenOf = (pid) => new Promise((resolve, reject) => {
-  const p = spawn('pgrep', ['-P', String(pid)], { stdio: ['ignore', 'pipe', 'ignore'] });
-  const out = [];
-  p.stdout.on('data', (chunk) => out.push(chunk));
-  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 or error
-    }
-  });
-  p.on('error', reject);
+	const p = spawn('pgrep', ['-P', String(pid)], { stdio: ['ignore', 'pipe', 'ignore'] });
+	const out = [];
+	p.stdout.on('data', (chunk) => out.push(chunk));
+	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 or error
+		} else {
+			// pgrep failed (2: syntax error, 3: fatal error); kill stays best-effort.
+			resolve([]);
+		}
+	});
+	p.on('error', reject);
 });
 
 /**
- * @typedef {import('../SH.js').SHOptions & { maxBuffer?: number }} SHExecuteOptions
- * @description Extended options for SHExecute: adds `maxBuffer` (bytes per stream, default 1MB).
+ * @typedef {import('./SHDispatch.js').SHOptions} SHExecuteOptions
+ * @description Options accepted by SHExecute — the shared SHOptions; `maxBuffer`
+ * (bytes per stream) defaults to 512000 (500 KiB).
  */
 
 /**
@@ -64,213 +43,239 @@ const childrenOf = (pid) => new Promise((resolve, reject) => {
  * - **Shell mode**: If `options.shell` is string/true, runs `${prefix}; ${command}` via shell ('bash' default).
  * - **No-shell mode**: Uses `/usr/bin/env -S ${command}` for direct exec (ignores prefix).
  * - **Rolling timeout**: `options.timeout` (ms/'2s'); resets on stdout/stderr data. SIGTERM on expiry.
- * - **Buffering**: Captures stdout/stderr up to `maxBuffer` (1MB default); appends truncation markers.
+ *   Async `run()` only — the timeout is stripped from the spawn options so Node's
+ *   native absolute spawn timeout never interferes. `runSync()` instead passes the
+ *   timeout to `spawnSync`, whose semantics are absolute (kills after the full
+ *   duration, regardless of output).
+ * - **Buffering**: Captures stdout/stderr up to `maxBuffer` (512000 bytes / 500 KiB default); appends truncation markers.
  * - **Payload**: `run(payload)` writes string to stdin (forces pipe).
- * - **Detached**: If `options.detached`, resolves early (~1s) and unrefs.
- * - **Kill**: Terminates process + children via pgrep.
+ * - **Detached**: If `options.detached`, resolves early (~1s) and unrefs. Unless the
+ *   caller explicitly set `stdio`, SHDispatch forces `stdio: 'ignore'` for detached
+ *   runs, because open pipes keep the parent's event loop alive and defeat detachment.
+ * - **Kill**: Terminates process + direct children via pgrep (requires procps; grandchildren survive).
  *
  * @example
  * const exec = new SHExecute('ls', 'set -euo pipefail', { timeout: '5s' });
  * const out = await exec.run();
  */
 class SHExecute {
-  #forcedKill = false;
-  /** @type {import('child_process').ChildProcess | null} */
-  #proc = null;
-  #prefix = '';
-  #command = '';
-  /** @type {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} */
-  #options = {};
-  #stdoutChunks = [];
-  #stderrChunks = [];
-  #stdoutLen = 0;
-  #stderrLen = 0;
-  #maxBuffer = 500 * 1024; // 500KB per stream
-  #truncated = { stdout: false, stderr: false };
-  #timedOut = false;
+	#forcedKill = false;
+	/** @type {import('child_process').ChildProcess | null} */
+	#proc = null;
+	#prefix = '';
+	#command = '';
+	/** @type {import('child_process').SpawnOptions | import('child_process').SpawnSyncOptions} */
+	#options = {};
+	#stdoutChunks = [];
+	#stderrChunks = [];
+	#stdoutLen = 0;
+	#stderrLen = 0;
+	#maxBuffer = DEFAULT_MAX_BUFFER; // 512000 bytes (500 KiB) per stream
+	#truncated = { stdout: false, stderr: false };
+	#timedOut = false;
+	/** Timeout in ms; 0 disables. Rolling in `run()`, absolute in `runSync()`. */
+	#timeout = 0;
 
-  /**
-   * @param {string} command - Command to execute.
-   * @param {string} prefix - Shell prelude (e.g., 'set -euo pipefail'); ignored in no-shell.
-   * @param {SHExecuteOptions} [options] - Spawn options + maxBuffer/timeout.
-   */
-  constructor(command, prefix, options = {}) {
-    this.#prefix = prefix;
-    this.#command = command;
-    const { maxBuffer, ...spawnOpts } = options ?? {};
-    this.#maxBuffer = Number.isFinite(maxBuffer) && maxBuffer > 0 ? maxBuffer : this.#maxBuffer;
-    this.#options = spawnOpts;
-  }
+	/**
+	 * @param {string} command - Command to execute.
+	 * @param {string} prefix - Shell prelude (e.g., 'set -euo pipefail'); ignored in no-shell.
+	 * @param {SHExecuteOptions} [options] - Spawn options + maxBuffer/timeout.
+	 */
+	constructor(command, prefix, options = {}) {
+		this.#prefix = prefix;
+		this.#command = command;
+		// maxBuffer and timeout are SH-level options, not spawn options. timeout in
+		// particular must not reach spawn(): since Node 15.5 it triggers a native
+		// absolute timeout that would defeat the rolling timeout in run().
+		const { maxBuffer, timeout, ...spawnOpts } = options ?? {};
+		this.#maxBuffer = Number.isFinite(maxBuffer) && maxBuffer > 0 ? maxBuffer : this.#maxBuffer;
+		this.#timeout = parseDuration(timeout ?? 0);
+		this.#options = spawnOpts;
+	}
 
-  /**
-   * Synchronous execution.
-   *
-   * @param {string} [payload] - Stdin data (forces pipe).
-   * @returns {import('child_process').SpawnSyncReturns<Buffer>}
-   * @throws {Error} Invalid payload type.
-   */
-  runSync(payload) {
-    this.#forcedKill = false;
-    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;
-    }
+	/**
+	 * Synchronous execution.
+	 *
+	 * @param {string} [payload] - Stdin data (forces pipe).
+	 * @returns {import('child_process').SpawnSyncReturns<Buffer>}
+	 * @throws {Error} Invalid payload type.
+	 */
+	runSync(payload) {
+		this.#forcedKill = false;
+		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 (this.#timeout > 0) {
+			// spawnSync supports timeout natively; semantics are absolute (no rolling reset).
+			options.timeout = this.#timeout;
+		}
+		if (payload) {
+			const stdio = Array.isArray(options.stdio) ? [...options.stdio] : ['pipe', 'pipe', 'pipe'];
+			stdio[0] = 'pipe';
+			// @ts-ignore — stdio widens to string[] via the ['pipe', 'pipe', 'pipe'] literal; runtime values are valid StdioOptions.
+			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.#prefix}; ${this.#command}` : this.#command;
-      return spawnSync(sh, ['-c', cmd], options);
-    }
-    // no-shell mode
-    return spawnSync('/usr/bin/env', ['-S', this.#command], options);
-  }
+		const shellOpt = this.#options?.shell;
+		if (shellOpt) {
+			const sh = typeof shellOpt === 'string' ? shellOpt : 'bash';
+			const cmd = this.#prefix ? `${this.#prefix}; ${this.#command}` : this.#command;
+			return spawnSync(sh, ['-c', cmd], options);
+		}
+		// no-shell mode
+		return spawnSync('/usr/bin/env', ['-S', this.#command], options);
+	}
 
-  /**
-   * Asynchronous execution with buffering/timeout/kill.
-   *
-   * Resolves stdout (trimmed) on success; rejects on error/timeout/kill.
-   *
-   * @param {string} [payload] - Stdin data (forces pipe).
-   * @returns {Promise<string>} Trimmed UTF-8 stdout (+ truncation marker if exceeded).
-   * @throws {Error} Command failure (incl. code, stderr), timeout, kill, spawn error.
-   */
-  run(payload) {
-    this.#forcedKill = false;
-    if (payload && typeof payload !== 'string') {
-      throw new Error('Argument is not a string');
-    }
-    /** @type {import('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;
-    }
+	/**
+	 * Asynchronous execution with buffering/timeout/kill.
+	 *
+	 * Resolves stdout (trimmed) on success.
+	 *
+	 * @param {string} [payload] - Stdin data (forces pipe).
+	 * @returns {Promise<string>} Trimmed UTF-8 stdout (+ truncation marker if exceeded).
+	 *   Rejects with an Error on command failure (message includes the exit code,
+	 *   or the signal name for signal kills, plus stderr), rolling-timeout expiry,
+	 *   forced kill, or spawn failure.
+	 */
+	run(payload) {
+		this.#forcedKill = false;
+		if (payload && typeof payload !== 'string') {
+			throw new Error('Argument is not a string');
+		}
+		/** @type {import('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 — stdio widens to string[] via the ['pipe', 'pipe', 'pipe'] literal; runtime values are valid StdioOptions.
+			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;
+		// 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.#prefix}; ${this.#command}` : this.#command;
-      this.#proc = spawn(sh, ['-c', cmd], options);
-    } else {
-      this.#proc = spawn('/usr/bin/env', ['-S', this.#command], options);
-    }
+		const shellOpt = this.#options?.shell;
+		if (shellOpt) {
+			const sh = typeof shellOpt === 'string' ? shellOpt : 'bash';
+			const cmd = this.#prefix ? `${this.#prefix}; ${this.#command}` : 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);
+		if (payload) this.#proc.stdin?.end(payload);
 
-    const ms = parseDuration(this.#options?.timeout ?? 0);
-    let timeoutId = null;
-    const resetTimeout = () => {
-      if (timeoutId !== null) clearTimeout(timeoutId);
-      if (ms > 0) {
-        timeoutId = setTimeout(() => {
-          this.#timedOut = true;
-          this.kill('SIGTERM').catch(() => {});
-        }, ms);
-      }
-    };
+		const ms = this.#timeout;
+		let timeoutId = null;
+		const resetTimeout = () => {
+			if (timeoutId !== null) clearTimeout(timeoutId);
+			if (ms > 0) {
+				timeoutId = setTimeout(() => {
+					this.#timedOut = true;
+					this.kill('SIGTERM').catch(() => {});
+				}, ms);
+			}
+		};
 
-    if (ms > 0) resetTimeout();
+		if (ms > 0) resetTimeout();
 
-    this.#proc.stdout?.on('data', (chunk) => {
-      this.#stdoutLen += chunk.length;
-      // prevent TOKEN bombs
-      if (this.#stdoutLen <= this.#maxBuffer) {
-        this.#stdoutChunks.push(chunk);
-      } else {
-        this.#truncated.stdout = true;
-      }
-      resetTimeout();
-    });
+		this.#proc.stdout?.on('data', (chunk) => {
+			this.#stdoutLen += chunk.length;
+			// prevent TOKEN bombs
+			if (this.#stdoutLen <= this.#maxBuffer) {
+				this.#stdoutChunks.push(chunk);
+			} else {
+				this.#truncated.stdout = true;
+			}
+			resetTimeout();
+		});
 
-    this.#proc.stderr?.on('data', (chunk) => {
-      this.#stderrLen += chunk.length;
-      if (this.#stderrLen <= this.#maxBuffer) {
-        this.#stderrChunks.push(chunk);
-      } else {
-        this.#truncated.stderr = true;
-      }
-      resetTimeout();
-    });
+		this.#proc.stderr?.on('data', (chunk) => {
+			this.#stderrLen += chunk.length;
+			if (this.#stderrLen <= this.#maxBuffer) {
+				this.#stderrChunks.push(chunk);
+			} else {
+				this.#truncated.stderr = true;
+			}
+			resetTimeout();
+		});
 
-    return new Promise((resolve, reject) => {
-      if (options.detached) {
-        setTimeout(() => {
-          if (timeoutId !== null) clearTimeout(timeoutId);
-          resolve('');
-          this.#proc.unref();
-        }, 1000);
-      }
+		return new Promise((resolve, reject) => {
+			if (options.detached) {
+				setTimeout(() => {
+					if (timeoutId !== null) clearTimeout(timeoutId);
+					resolve('');
+					// #proc may already be null when kill() ran within the 1s window.
+					this.#proc?.unref();
+				}, 1000);
+			}
 
-      this.#proc.on('close', (code, signal) => {
-        if (timeoutId !== null) 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');
-          if (this.#truncated.stderr) stderr += '\n[stderr truncated]\n';
-          reject(new Error(`Command failed with code ${code}: ${stderr}`));
-        }
-      });
+			this.#proc.on('close', (code, signal) => {
+				if (timeoutId !== null) clearTimeout(timeoutId);
+				// Check timeout first: the timeout path kills with SIGTERM, which sets
+				// #forcedKill in the same tick; #forcedKill must not mask the timeout.
+				if (this.#timedOut) {
+					reject(new Error(`Process timed out after ${ms}ms.`));
+					return;
+				}
+				if (this.#forcedKill) {
+					reject(new Error('Process killed (forced).'));
+					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');
+					if (this.#truncated.stderr) stderr += '\n[stderr truncated]\n';
+					const reason = code === null ? `signal ${signal}` : `code ${code}`;
+					reject(new Error(`Command failed with ${reason}: ${stderr}`));
+				}
+			});
 
-      this.#proc.on('error', (err) => reject(err));
-    });
-  }
+			this.#proc.on('error', (err) => reject(err));
+		});
+	}
 
-  /**
-   * Terminates process and its children (via pgrep).
-   *
-   * @param {number | string} [signal='SIGTERM'] - Signal to send.
-   * @returns {Promise<number[]>} Killed PIDs.
-   * @throws {Error} No process/PID.
-   */
-  async kill(signal = 'SIGTERM') {
-    if (!this.#proc) throw new Error('Trying to kill a process without creating one.');
-    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 = null;
-    }
-    return killed;
-  }
+	/**
+	 * Terminates process and its children (via pgrep).
+	 *
+	 * Requires `pgrep` (procps) at runtime. Only direct children are
+	 * discovered — grandchildren and deeper descendants survive. Best-effort:
+	 * pgrep failures resolve to an empty child list instead of rejecting.
+	 *
+	 * @param {number | string} [signal='SIGTERM'] - Signal to send.
+	 * @returns {Promise<number[]>} Killed PIDs.
+	 * @throws {Error} No process/PID.
+	 */
+	async kill(signal = 'SIGTERM') {
+		if (!this.#proc) throw new Error('Trying to kill a process without creating one.');
+		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 = null;
+		}
+		return killed;
+	}
 }
 
 export default SHExecute;