@j-o-r/sh 1.1.28 → 1.1.29

package/README.md

@@ -1,195 +1,160 @@
-# @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`.
+- Safe interpolation; `bashEscape`; 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
-
-```javascript
-const res = await SH`ls -FLa | grep package.json | wc -l`.run();
-console.log(res);
+### Chaining & Options
 
-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
+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: ..."
 ```
 
-```javascript
-const p = await retry(3, expBackoff(), () => SH`curl -s https://unreachable`.run());
-```
+### Parallel & Context
 
-The `SH` method accepts a template literal string enclosed in backticks as its argument. It returns an `SHDispatch` object.
+```js
+import { within } from '@j-o-r/sh';
 
-### Additional Utilities
-
-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.
+const results = await within(async () => Promise.all([
+  SH`sleep 1; echo ok`.run(),
+  sleep('500ms'),
+  SH`uname`.run()
+]));
+```
 
-## SHDispatch
+### Retry & Backoff
 
-This class is returned by the `SH` function. Here's a summary of its methods and properties:
+```js
+import { retry, expBackoff } from '@j-o-r/sh';
 
-### Methods
+try {
+  const res = await retry(3, expBackoff('10s'), () =>
+    SH`curl -s unreachable`.run()
+  );
+} catch (e) {
+  // Last error
+}
+```
 
-- **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.
+### Interactive / Stdin
 
-### Examples
+```js
+import { userIn, readIn } from '@j-o-r/sh';
 
-- Elementary usages, piped:
-  ```javascript
-  const res = await SH`ls -FLa | grep package.json | wc -l`.run();
-  console.log(res);
-  ```
+// User prompt (abortable)
+const { input, abort } = userIn('Password: ');
+const pw = await input;
 
-- Feed command with content:
-  ```javascript
-  const res = await SH`wc -l`.run(`one\ntwo\n`);
-  console.log(res);
-  ```
+// Piped stdin
+const out = await SH`grep secret`.run(await readIn());
+```
 
-- Create a command from a string
-  ```javascript
-	const command = "uname -r";
-	const content = await SH`${command}`.run();
-	console.log(content);
-  ```
+### Vim / TTY (Sync)
 
-- 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
+SH`vim`.options({ stdio: 'inherit' }).runSync();
+```
 
-- 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);
-  }
-  ```
+## Testing
 
-- Prompt user for input:
-  ```javascript
-  const user = userIn('Enter your name: ');
-  const name = await user.input;
-  console.log('Hello,', name);
-  ```
+Full-featured tester with async support, error reporting, unresolved Promise detection.
 
-- 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
-  ```
+```js
+import { Test, assert, jsType } from '@j-o-r/sh';
 
-- 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);
-  }
-  ```
+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 t.run();
+console.log(report);  // { tests: 2, executed: 2, duration: 150, errors: 0 }
 
-- Open the 'vim' editor  
-  ```javascript
-  SH`vim`.options({stdio: 'inherit'}).runSync();
-  ```
+t.unresolved();  // Logs leaks if any
+```
 
-- Create and run a test
-```javascript
-import { assert, jsType, Test} from '@j-o-r/sh';
+## Advanced
 
-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();
-	});
-});
-const report = await test.run();
-if (report.errors > 0) {
-  process.exit(1);
-}
-// await test.run([0,3]); // only run test 0 and 3
+- **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(str)` | Shell-safe string |
+
+See [types/index.d.ts](types/index.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,18 @@
+# TODOs for @j-o-r/sh project
+
+## High Priority (pending)
+- [ ] Review and commit recent changes to lib/ files and types/ (from git status: modified AsyncTracker.js, SH.js, etc.)
+- [*] Generate or improve API documentation using types/*.d.ts files
+
+## In Progress
+- [ ]
+
+## Later (future tasks)
+- [ ] Create separate docs folder with full API reference
+
+## Done
+- [x] Initial project setup from package.json and README.md inspection (2026-04-15)
+- [x] Update README.md to include documentation for recent changes in AsyncTracker and Test features (2026-04-15)
+- [x] Add more examples to README.md for SHDispatch methods and utilities like retry and expBackoff (2026-04-15)
+- [x] Reference general SSH example in README.md (demo-interactive-ssh.js not found in scenarios/) (2026-04-15)
+- [x] Reduce SHExecute maxBuffer default from 40MB to 1MB, update all docs/JSDoc mentioning it. Make sure global SH.maxBuffer works. (2026-04-15)