@j-o-r/sh 1.1.28 → 1.1.31

package/README.md

@@ -1,195 +1,189 @@
-# @j-o-r/sh
+# @j-o-r/sh   [![npm](https://img.shields.io/npm/v/@j-o-r/sh?logo=npm)](https://www.npmjs.com/package/@j-o-r/sh) [![License](https://img.shields.io/npm/license/@j-o-r/sh)](https://codeberg.org/duin/sh/src/branch/main/LICENSE) [![Codeberg](https://img.shields.io/badge/Codeberg-main-blue?logo=codeberg)](https://codeberg.org/duin/sh)
 
-Execute shell commands from JavaScript.
+Execute shell commands from JavaScript on Linux.
 
 ## Introduction
 
-`@j-o-r/sh` is a Node.js module that simplifies the execution of shell commands within JavaScript applications. It provides a range of utilities to handle shell scripts and manage their output efficiently.
+`@j-o-r/sh` is a lightweight Node.js module for running shell commands with a clean, zx-inspired API. It fixes namespace pollution, adds **rolling timeouts** (reset on stdout/stderr), **no-shell mode** (`/usr/bin/env -S`), process tree kills, buffer limits (1MB default), and a built-in **Test** framework + **AsyncTracker** for leaks.
 
-This project draws inspiration from the exceptional [zx library](https://github.com/google/zx). The core functionality of zx, particularly the shell execution method, has been extracted and forms the foundation of this project.
+**Key Features**:
+- Template tag `SH`cmd`` → `SHDispatch` for `.options().run()`.
+- Global options: `SH.timeout = '5s'; SH.cwd = '/tmp';`.
+- Sync/async `run()`/`runSync()`; stdin payload; detached mode.
+- Utils: `sleep`, `retry`, `expBackoff`, `cd`, `parseArgs`, `userIn`, `readIn`.
+- Testing: `new Test().add('name', () => assert(...)).run()`.
+- Async leak detection: `AsyncTracker` via `async_hooks`.
+- Raw-by-default interpolation with explicit `bashEscape` quoting for untrusted argument values; full JSDoc.
 
-## Installation
+No runtime deps. ESM-only (ES2020+).
 
-Install the module using npm:
+## Quick Install
 
-```sh
-npm install @j-o-r/sh
+```bash
+npm i @j-o-r/sh
 ```
 
 ## Usage
 
-### Basic Usage
+### Basics
 
-To execute a shell command, use the `SH` function:
+```js
+import { SH, cd, sleep } from '@j-o-r/sh';
 
-```javascript
-import { SH, cd, within, sleep, retry, expBackoff } from '@j-o-r/sh';
-
-SH`your_shell_command`.run()
-  .then(output => {
-    console.log('Output:', output);
-  })
-  .catch(error => {
-    console.error('Error:', error);
-  });
+cd('/tmp');
+const out = await SH`ls -la`.run();
+console.log(out); // Captured stdout (trimmed)
 ```
 
-### Advanced Usage
+### Interpolation: raw by default
 
-```javascript
-const res = await SH`ls -FLa | grep package.json | wc -l`.run();
-console.log(res);
+Interpolated values are inserted into the shell command as raw shell source. This
+is convenient for trusted shell fragments such as flags, pipes, redirects, and
+compound expressions, but it is **not safe for untrusted input**.
 
-const ar = within(async () => {
-  const res = await Promise.all([
-    SH`sleep 1; echo 1`.run(),
-    SH`sleep 2; echo 2`.run(),
-    sleep(2),
-    SH`sleep 3; echo 3`.run()
-  ]);
-});
-```
+```js
+import { SH, bashEscape } from '@j-o-r/sh';
+
+const flags = ['-l', '-a'];
+await SH`ls ${flags}`.run();       // Executes: ls -l -a
 
-```javascript
-const p = await retry(3, expBackoff(), () => SH`curl -s https://unreachable`.run());
+const fragment = 'printf ok; printf done';
+await SH`${fragment}`.run();       // Raw shell syntax is intentional
+
+const userInput = 'name; rm -rf /';
+await SH`printf '%s\n' ${bashEscape(userInput)}`.run();
+// Prints the value literally instead of executing `rm`.
 ```
 
-The `SH` method accepts a template literal string enclosed in backticks as its argument. It returns an `SHDispatch` object.
+`bashEscape(value)` returns one POSIX-shell-quoted argument. It preserves empty
+strings, whitespace, quotes, semicolons, glob characters, tabs, and newlines.
+For arrays of untrusted values, quote each element yourself:
 
-### Additional Utilities
+```js
+const args = ['two words', 'semi;colon', "quote's"];
+await SH`printf '%s\n' ${args.map(bashEscape)}`.run();
+```
 
-The module also provides additional utilities for common tasks:
-- `parseArgs(process.args)`: Transform an array of strings into an object 
-- `cd(dir)`: Change the working directory.
-- `sleep(duration)`: Pause execution for a specified duration.
-- `retry(count, interval, callback)`: Retry a command a specified number of times with an optional interval.
-- `readIn()`: Read from standard input.
-- `userIn(prompt)`: Prompt the user for input and return an object with `input` (Promise resolving to the user input) and `abort()` method to cancel.
-- `within(callback)`: Create an async context in a sync block.
-- `expBackoff(max, rand)`: Generate intervals for exponential backoff.
-- `jsType(any)`: Get the 'real' javascript variable type 
-- `hasProp(object, property)`: Safely check if an object has its own property (handles null/undefined objects).
-- `assert.`: Node assert library 
-- `new Test()`: A small sync/async minimal test framework 
-- `AsyncTracker`: A class for tracking asynchronous operations using Node.js async hooks.
+### Chaining & Options
 
-## SHDispatch
+```js
+SH`curl -s ip.js.org`
+  .options({ timeout: '2s', shell: false })  // No-shell: /usr/bin/env -S
+  .run()
+  .catch(e => console.error(e.message));     // "Command failed with code 1: ..."
+```
 
-This class is returned by the `SH` function. Here's a summary of its methods and properties:
+### Parallel & Context
 
-### Methods
+```js
+import { within } from '@j-o-r/sh';
 
-- **options(options)**: Sets options for the command execution.
-- **run(payload?)**: Executes the command and returns a promise that resolves with the command's output.
-- **runSync(payload?)**: Executes the command synchronously and returns a `SpawnSyncResponse`.
-- **kill()**: Sends a kill signal to the child process.
+const results = await within(async () => Promise.all([
+  SH`sleep 1; echo ok`.run(),
+  sleep('500ms'),
+  SH`uname`.run()
+]));
+```
 
-### Examples
+### Retry & Backoff
 
-- Elementary usages, piped:
-  ```javascript
-  const res = await SH`ls -FLa | grep package.json | wc -l`.run();
-  console.log(res);
-  ```
+```js
+import { retry, expBackoff } from '@j-o-r/sh';
 
-- Feed command with content:
-  ```javascript
-  const res = await SH`wc -l`.run(`one\ntwo\n`);
-  console.log(res);
-  ```
+try {
+  const res = await retry(3, expBackoff('10s'), () =>
+    SH`curl -s unreachable`.run()
+  );
+} catch (e) {
+  // Last error
+}
+```
 
-- Create a command from a string
-  ```javascript
-	const command = "uname -r";
-	const content = await SH`${command}`.run();
-	console.log(content);
-  ```
+### Interactive / Stdin
 
-- Async context with multiple commands and sleep:
-  ```javascript
-  within(async () => {
-    const res = await Promise.all([
-      SH`sleep 1; echo 1`.run(),
-      SH`sleep 2; echo 2`.run(),
-      sleep(2),
-      SH`sleep 3; echo 3`.run()
-    ]);
-    console.log(res);
-  });
-  ```
+```js
+import { userIn, readIn } from '@j-o-r/sh';
 
-- Retry with exponential backoff:
-  ```javascript
-  try {
-    const p = await retry(3, expBackoff(), () => SH`curl -s https://unreachable`.run());
-  } catch (e) {
-    console.error('Retry failed:', e);
-  }
-  ```
+// User prompt (abortable)
+const { input, abort } = userIn('Password: ');
+const pw = await input;
 
-- Prompt user for input:
-  ```javascript
-  const user = userIn('Enter your name: ');
-  const name = await user.input;
-  console.log('Hello,', name);
-  ```
+// Piped stdin
+const out = await SH`grep secret`.run(await readIn());
+```
 
-- Check if object has property:
-  ```javascript
-  const obj = { a: 1 };
-  console.log(hasProp(obj, 'a')); // true
-  console.log(hasProp(obj, 'b')); // false
-  console.log(hasProp(null, 'a')); // false
-  ```
+### Vim / TTY (Sync)
 
-- Method for copying data to the clipboard:
-  ```javascript
-  /**
-  * Copy text to the clipboard
-  * @param {string} text
-  * @returns {Promise<string>}
-  */
-  const copyToClipboard = async (text) => {
-  	const prams = [
-  		'-selection',
-  		'clipboard'
-  	]
-  	return SH`xclip ${prams}`.options({stdio: 'inherit'}).run(text);
-  }
-  ```
+```js
+SH`vim`.options({ stdio: 'inherit' }).runSync();
+```
 
-- Open the 'vim' editor  
-  ```javascript
-  SH`vim`.options({stdio: 'inherit'}).runSync();
-  ```
+## Testing
 
-- Create and run a test
-```javascript
-import { assert, jsType, Test} from '@j-o-r/sh';
+Full-featured tester with async support, error reporting, unresolved Promise detection.
 
-const test = new Test();
-test.add('Test is test in sync', () => {
-	assert.strictEqual(jsType(test), 'Test');
-});
-test.add('Test an Array in sync', () => {
-	assert.strictEqual(jsType([]), 'Array');
-});
-test.add('Test is test in async', async () => {
-	assert.strictEqual(jsType(test), 'Test');
-});
-test.add('Test is test in async, returning a promise', async () => {
-	return new Promise((resolve, _reject) => {
-		assert.strictEqual(jsType(test), 'Test');
-		resolve();
-	});
+```js
+import { Test, assert, jsType } from '@j-o-r/sh';
+
+const t = new Test(true);  // quiet: no console
+t.add('sync assert', () => assert.strictEqual(1 + 1, 2));
+t.add('async', async () => {
+  await sleep('100ms');
+  assert.strictEqual(jsType([]), 'Array');
 });
-const report = await test.run();
-if (report.errors > 0) {
-  process.exit(1);
-}
-// await test.run([0,3]); // only run test 0 and 3
+const report = await t.run();
+console.log(report);  // { tests: 2, executed: 2, duration: 150, errors: 0 }
+
+t.unresolved();  // Logs leaks if any
+```
+
+## Advanced
+
+- **SSH Example** (interactive; use keys/sshpass for automation):
+  ```js
+  // TTY/inherit for prompts
+  SH`ssh user@host`.options({ stdio: 'inherit' }).runSync();
+  // Or sshpass: SH`sshpass -p pw ssh user@host`.run()
+  ```
+  See `scenarios/` for full demos.
+
+- **CLI Args**: `parseArgs()` → `{ port: '8080', _: ['file'] }`.
+- **Global Defaults**: Set global options on the `SH` object to apply to all subsequent commands. These can be overridden per-command via `.options()`. Examples:
+  - `SH.timeout = '5s';` – Default timeout for all runs.
+  - `SH.cwd = '/tmp';` – Default working directory.
+  - `SH.shell = false;` – Disable shell mode (uses `/usr/bin/env -S`).
+  - `SH.maxBuffer = 1 * 1024 * 1024;` – Override default buffer limit (500kb) to 1MB per stream (stdout/stderr). Buffering captures output up to this limit; excess is truncated with markers.
+- **Kill Tree**: `dispatch.kill('SIGKILL')` → children via `pgrep -P`.
+
+## API
+
+Full JSDoc in `lib/*.js`. Key exports:
+
+| Utility | Description |
+|---------|-------------|
+| `SH`cmd`` | Template → {@link SHDispatch} |
+| `cd(dir)` | `process.chdir()` |
+| `sleep('1s')` | Promise delay |
+| `retry(3, '1s', fn)` | Retry w/ delay/gen |
+| `userIn(prompt)` | `{ input: Promise, abort() }` |
+| `Test` | Test runner |
+| `AsyncTracker` | Async leak detector |
+| `parseArgs(argv)` | CLI parser |
+| `bashEscape(value)` | Quote one value as a POSIX shell argument for safe interpolation |
+
+See [types/SH.d.ts](types/SH.d.ts) for TS defs.
+
+## Development
+
+```bash
+npm run types    # Generate types/
+npm test         # Run scenarios/sh.js
+npm run release  # Pack for publish
+npm run publish  # npm publish
 ```
 
+Repo: [Codeberg](https://codeberg.org/duin/sh) | Issues: [Codeberg Issues](https://codeberg.org/duin/sh/issues)
+
 ## License
 
-This project is licensed under the Apache License, Version 2.0.
+Apache-2.0 © [Jorrit Duin](mailto:jorrit.duin+sh@gmail.com)

package/TODO.md

@@ -0,0 +1,8 @@
+# TODOs for @j-o-r/sh project
+
+## lib/SH.js review findings (2026-06-26)
+
+## In Progress
+
+## Done
+