@j-o-r/sh 1.1.31 → 1.1.32

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;

package/lib/internal.js

@@ -0,0 +1,113 @@
+/**
+ * Shared internals for the SH library.
+ *
+ * Single source of truth for the default command options used by the `SH`
+ * template tag (`lib/SH.js`) and `SHDispatch` (`lib/SHDispatch.js`), and for
+ * the shared `parseDuration` used by `lib/SH.js` and `lib/SHExecute.js`.
+ * Not part of the public API; nothing here is re-exported from `lib/SH.js`.
+ */
+
+/**
+ * Explicit default `cwd` override, set via `SH.cwd = dir`.
+ *
+ * @type {string | undefined}
+ */
+let cwdOverride;
+
+/**
+ * Default maximum buffered bytes per stdout/stderr stream: 512000 (500 KiB).
+ * Used by `SHExecute` when `options.maxBuffer` is unset or invalid.
+ */
+const DEFAULT_MAX_BUFFER = 500 * 1024;
+
+/**
+ * Default options applied to all SH commands unless overridden.
+ *
+ * `cwd` is intentionally lazy: the getter resolves `process.cwd()` at read
+ * time, so commands created after a `cd()` run in the new directory instead of
+ * the directory the process was started in. `SHDispatch` spreads these
+ * defaults (`{ ...defaultOptions }`) per command, which invokes the getter and
+ * freezes the value for that command — "defaults captured at creation time".
+ * Do not "optimize" this into a static snapshot.
+ *
+ * An explicit `SH.cwd = dir` assignment takes precedence over `process.cwd()`
+ * (it only redirects SH commands; it does not `chdir` the process). `cd()`
+ * clears the override again, so the most recent of the two always wins.
+ *
+ * `maxBuffer` and `detached` are initialized explicitly so every key the `SH`
+ * proxy exposes ({@link defaultOptionKeys}) also has a defined value here.
+ * This is behavior-neutral: `SHExecute` already fell back to
+ * `DEFAULT_MAX_BUFFER` for unset/invalid values and truthy-checks `detached`.
+ *
+ * @type {import('./SHDispatch.js').SHOptions}
+ */
+const defaultOptions = {
+	get cwd() {
+		return cwdOverride ?? process.cwd();
+	},
+	set cwd(value) {
+		cwdOverride = value;
+	},
+	env: process.env,
+	shell: 'bash',
+	stdio: ['inherit', 'pipe', 'pipe'],
+	timeout: 0, // when 0 there is no timeout
+	maxBuffer: DEFAULT_MAX_BUFFER,
+	detached: false,
+};
+
+/**
+ * Known global option keys exposed by the `SH` proxy in `lib/SH.js`.
+ *
+ * Derived from the own keys of {@link defaultOptions}, so the key set can
+ * never drift from the defaults. (The previous hard-coded list in `lib/SH.js`
+ * readable-exposed `maxBuffer`/`detached`, which were uninitialized in the
+ * defaults.) The proxy routes reads/writes for these keys to
+ * `defaultOptions` and throws a `TypeError` on writes to any other key
+ * (decision D1).
+ *
+ * @type {Set<string>}
+ */
+const defaultOptionKeys = new Set(Object.keys(defaultOptions));
+
+/**
+ * Clears the `SH.cwd` override so the lazy `cwd` getter follows
+ * `process.cwd()` again. Called by `cd()` after a successful
+ * `process.chdir()`.
+ */
+const clearCwdOverride = () => {
+	cwdOverride = undefined;
+};
+
+/**
+ * Parses a human-readable duration into milliseconds.
+ *
+ * Accepts finite non-negative numbers (milliseconds) and strings in the exact
+ * forms `'Nms'`, `'Ns'`, or a bare `'N'`. The bare-number form is treated as
+ * milliseconds on purpose: it preserves the leniency of the former `SHExecute`
+ * parser, so e.g. `timeout: '100'` keeps working.
+ *
+ * `null`/`undefined` are not special-cased here; call sites that allow an
+ * absent duration handle it themselves (e.g. `parseDuration(timeout ?? 0)`).
+ *
+ * @param {number|string} d - Duration as number (ms) or string ('5s', '100ms', '100').
+ * @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: "${d === null ? 'Null' : typeof d}".`);
+};
+
+export { defaultOptions, defaultOptionKeys, clearCwdOverride, DEFAULT_MAX_BUFFER, parseDuration };

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.31",
+  "version": "1.1.32",
   "description": "Execute shell commands on Linux-based systems from javascript",
   "main": "lib/SH.js",
   "types": "types/SH.d.ts",
@@ -22,7 +22,7 @@
   },
   "license": "Apache License, Version 2.0",
   "devDependencies": {
-    "@types/node": "^22.10.10"
+    "@types/node": "*"
   },
   "bugs": {
     "url": "https://codeberg.org/duin/sh/issues"
@@ -49,4 +49,4 @@
     "process-promise",
     "process-output"
   ]
-}
+}