@j-o-r/sh 1.1.31 → 1.1.32

package/types/SH.d.ts

@@ -7,11 +7,8 @@
 export type ArgsObject = {
     _: string[];
 } & {
-    [x: string]: string | true | 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.
@@ -23,9 +20,9 @@ export type AbortableInput = {
     abort: () => void;
 };
 /**
- * Generator-like object that yields retry delay durations.
+ * Generator that yields retry delay durations in milliseconds.
  */
-export type ExpBackoffGenerator = Iterator<number | string>;
+export type ExpBackoffGenerator = Generator<number, void, unknown>;
 /**
  * Template tag for building and executing shell commands.
  *
@@ -39,10 +36,15 @@ export type ExpBackoffGenerator = Iterator<number | string>;
  * 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
@@ -54,11 +56,19 @@ export type ExpBackoffGenerator = Iterator<number | string>;
  *
  * // 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');
@@ -76,21 +86,29 @@ 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-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
  * await retry(3, '1s', () => SH`curl http://unreliable`.run());
  * await retry(3, expBackoff(), () => flakyOp());
  */
-export function retry(count: number, delayOrCallback: string | number | ExpBackoffGenerator | Function, callback?: Function): 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).
  *
+ * 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
@@ -99,7 +117,14 @@ 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.
@@ -110,9 +135,13 @@ export function readIn(): Promise<string>;
  */
 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.
@@ -129,18 +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.
+ * 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).
  *
@@ -150,6 +182,8 @@ export function expBackoff(max?: string, rand?: string): Generator<number, void,
  * @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;
 /**
@@ -158,18 +192,7 @@ export function parseArgs(args?: string[]): ArgsObject;
  * 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
  */
 /**
  * @typedef {Object} AbortableInput
@@ -177,22 +200,29 @@ export function parseArgs(args?: string[]): ArgsObject;
  * @property {() => void} abort - Function to abort input collection.
  */
 /**
- * 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'
  */
-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.

package/types/SHDispatch.d.ts

@@ -1,30 +1,4 @@
 export default SHDispatch;
-export type SpawnSyncResponse = {
-    /**
-     * - Exit code (null if signal).
-     */
-    status: number | null;
-    /**
-     * - Terminating signal.
-     */
-    signal: string | null;
-    /**
-     * - [stdin, stdout, stderr].
-     */
-    output: (string | Buffer | null)[];
-    /**
-     * - Process ID.
-     */
-    pid: number;
-    /**
-     * - Captured stdout.
-     */
-    stdout: string | Buffer | null;
-    /**
-     * - Captured stderr.
-     */
-    stderr: string | Buffer | null;
-};
 export type StdioOption = ("pipe" | "ignore" | "inherit" | number);
 export type StdioOptions = Array<StdioOption> | StdioOption;
 /**
@@ -36,7 +10,7 @@ export type StdioOptions = Array<StdioOption> | StdioOption;
  * - `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.
  */
@@ -58,7 +32,10 @@ export type SHOptions = {
      */
     stdio: StdioOptions;
     /**
-     * - Rolling timeout in ms or duration string; 0 disables 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.
      */
     timeout: number | string;
     /**
@@ -66,7 +43,9 @@ export type SHOptions = {
      */
     maxBuffer?: number | undefined;
     /**
-     * - Run process detached and resolve early.
+     * - 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;
 };
@@ -104,6 +83,10 @@ declare 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.
      */

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;