@j-o-r/sh 1.1.29 → 1.1.32

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.29",
+  "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"

package/types/SH.d.ts

@@ -1,9 +1,14 @@
+/**
+ * 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;
 };
-export type RejectCallback = Function;
-export type ResolveCallback = Function;
-export type SHOptions = import("./SHDispatch.js").SHOptions;
 export type AbortableInput = {
     /**
      * - Promise that resolves to user input or void if aborted.
@@ -14,33 +19,56 @@ export type AbortableInput = {
      */
     abort: () => void;
 };
-export type ExpBackoffGenerator = Object;
+/**
+ * Generator that yields retry delay durations in milliseconds.
+ */
+export type ExpBackoffGenerator = Generator<number, void, unknown>;
 /**
  * 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``
+ * 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
  * 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();
+ *
+ * // Set global defaults for subsequently created commands
+ * SH.timeout = 5000;
+ * await SH`cmd`.run();
  */
 export const SH: any;
 /**
  * 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.
+ *
  * @param {string} dir - Path to new directory.
  * @example
  * cd('/tmp');
@@ -58,30 +86,45 @@ 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 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 - 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|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} 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 | Iterator<number | string> | (() => (Promise<any> | any)), callback?: () => (Promise<any> | any)): 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.
+ * 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
  */
-export function readIn(): Promise<string | undefined>;
+export function readIn(): Promise<string>;
 /**
  * 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.
@@ -92,9 +135,13 @@ export function readIn(): Promise<string | undefined>;
  */
 export function userIn(prompt: string): AbortableInput;
 /**
- * Executes a callback in a new async context (fresh callstack).
+ * Awaits `callback()` and returns its result.
  *
- * Useful for parallel operations without nesting.
+ * Despite the historical name, this is currently a thin wrapper: no new async
+ * context or fresh callstack is created — the callback runs in the current
+ * one. It is kept as an intent marker for grouping async work (and for API
+ * compatibility); real isolation via AsyncLocalStorage is a pending decision
+ * (see the project TODO, decision D2).
  *
  * @param {() => Promise<any>} callback - Async function to execute.
  * @returns {Promise<any>} Result of callback.
@@ -111,16 +158,21 @@ export function within(callback: () => Promise<any>): Promise<any>;
  * @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);
  */
-export function expBackoff(max?: string, rand?: string): Generator<number, void, unknown>;
+export function expBackoff(max?: string, rand?: string): ExpBackoffGenerator;
 /**
  * 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. 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).
  *
@@ -129,24 +181,18 @@ 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', _: [] }
+ * parseArgs(['-', '--port', '1']); // { port: '1', _: ['-'] }
+ * parseArgs(['--', '--x']); // { _: ['--x'] }
  */
 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.
- */
-/**
- * @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
+ * 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>} ArgsObject
  */
 /**
  * @typedef {Object} AbortableInput
@@ -154,22 +200,29 @@ 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 that yields retry delay durations in milliseconds.
+ *
+ * @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'
  */
-export function jsType(fn: any): string;
+export function jsType(value: unknown): string;
 /**
- * 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.
@@ -180,12 +233,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

@@ -1,32 +1,54 @@
 export default SHDispatch;
-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 KiB per stream in SHExecute)
+ *
+ * Prefix (`.options(undefined, prefix)`) only for shell mode.
+ */
+export type SHOptions = {
     /**
-     * - Exit code (null if signal).
+     * - Working directory for spawned commands.
      */
-    status: number | null;
+    cwd: string;
     /**
-     * - Terminating signal.
+     * - Environment for spawned commands.
      */
-    signal: string | null;
+    env: NodeJS.ProcessEnv;
     /**
-     * - [stdin, stdout, stderr].
+     * - Shell executable, true for bash, or false for no-shell mode.
      */
-    output: (string | Buffer | null)[];
+    shell: string | boolean;
     /**
-     * - Process ID.
+     * - Stdio config passed to child_process.
      */
-    pid: number;
+    stdio: StdioOptions;
     /**
-     * - Captured stdout.
+     * - 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.
      */
-    stdout: string | Buffer | null;
+    timeout: number | string;
     /**
-     * - Captured stderr.
+     * - Maximum buffered bytes per stdout/stderr stream.
      */
-    stderr: string | Buffer | null;
+    maxBuffer?: number | undefined;
+    /**
+     * - 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.
+     */
+    detached?: boolean | undefined;
 };
-export type StdioOption = ("pipe" | "ignore" | "inherit" | number);
-export type StdioOptions = Array<StdioOption> | StdioOption;
 /**
  * High-level command dispatcher.
  *
@@ -41,24 +63,30 @@ 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.
      *
+     * 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.
      */
@@ -81,10 +109,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;
-}

package/types/SHExecute.d.ts

@@ -1,10 +1,9 @@
 export default SHExecute;
-export type SHExecuteOptions = any & {
-    maxBuffer?: number;
-};
+export type SHExecuteOptions = import("./SHDispatch.js").SHOptions;
 /**
- * @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).
  */
 /**
  * Low-level process executor for shell commands.
@@ -15,10 +14,16 @@ export type SHExecuteOptions = any & {
  * - **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' });
@@ -42,16 +47,22 @@ declare class SHExecute {
     /**
      * Asynchronous execution with buffering/timeout/kill.
      *
-     * Resolves stdout (trimmed) on success; rejects on error/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).
-     * @throws {Error} Command failure (incl. code, stderr), timeout, kill, spawn error.
+     *   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?: string): Promise<string>;
     /**
      * 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.

package/types/internal.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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}
+ */
+export const defaultOptions: import("./SHDispatch.js").SHOptions;
+/**
+ * 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>}
+ */
+export const defaultOptionKeys: Set<string>;
+/**
+ * Clears the `SH.cwd` override so the lazy `cwd` getter follows
+ * `process.cwd()` again. Called by `cd()` after a successful
+ * `process.chdir()`.
+ */
+export function clearCwdOverride(): void;
+/**
+ * Default maximum buffered bytes per stdout/stderr stream: 512000 (500 KiB).
+ * Used by `SHExecute` when `options.maxBuffer` is unset or invalid.
+ */
+export const DEFAULT_MAX_BUFFER: number;
+/**
+ * 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.
+ */
+export function parseDuration(d: number | string): number;