dollar-shell 1.1.7 → 1.1.9

package/AGENTS.md

@@ -0,0 +1,68 @@
+# Agent Instructions for dollar-shell
+
+This file provides guidance for AI coding agents working with or on the `dollar-shell` package.
+
+## What This Package Does
+
+`dollar-shell` runs OS and shell commands from JavaScript/TypeScript using template tag functions. It works on Node, Deno, and Bun with the same API. All streams are web streams.
+
+## Quick Reference
+
+```js
+import $, {$$, $sh, shell, sh, spawn} from 'dollar-shell';
+
+// Run a command, get exit info
+const result = await $`echo hello`;
+// result: {code: 0, signal: null, killed: false}
+
+// Run a command, get full Subprocess
+const sp = $$`sleep 5`;
+sp.kill();
+await sp.exited;
+
+// Shell command (supports pipes, aliases)
+await $sh`ls -l . | grep LICENSE | wc`;
+
+// Stream pipelines
+$.from`ls -l .`
+  .pipeThrough($.io`grep LIC`)
+  .pipeTo($.to({stdout: 'inherit'})`wc`);
+
+// Custom options (returns new tag function with updated defaults)
+const $verbose = $({stdout: 'inherit', stderr: 'inherit'});
+await $verbose`ls -l .`;
+```
+
+## Architecture
+
+- `src/index.js` — Main entry point, wires everything together
+- `src/index.d.ts` — TypeScript declarations for the full public API
+- `src/bq-spawn.js` — Template tag factory for spawn-based functions (`$`, `$$`)
+- `src/bq-shell.js` — Template tag factory for shell-based functions (`$sh`, `shell`)
+- `src/utils.js` — Shared utilities (`raw`, `isWindows`, `winCmdEscape`, etc.)
+- `src/spawn/node.js`, `src/spawn/deno.js`, `src/spawn/bun.js` — Runtime-specific Subprocess implementations
+- `src/shell/unix.js`, `src/shell/windows.js` — Platform-specific shell escaping and command building
+
+## Key Patterns
+
+- **Tag function + options pattern**: All tag functions (`$`, `$$`, `$sh`, `shell`) can be called with an options object to produce a new tag function with updated defaults. The new function retains all properties (`.from`, `.to`, `.io`, `.through`).
+- **raw()**: Wraps a value to bypass escaping (shell) or argument splitting (spawn).
+- **Platform detection**: `isWindows` boolean is exported. Runtime detection (Node/Deno/Bun) happens at import via dynamic imports.
+
+## When Using This Package
+
+- Import `$` as the default export for simple command execution.
+- Use `$sh` when you need shell features (pipes, aliases, globbing).
+- Use `$$` or `shell` when you need the full `Subprocess` object (kill, streams, exit code).
+- Use `.from`, `.to`, `.io`/`.through` for stream pipelines with web streams.
+- Always `await` the result of `$` and `$sh` (they return promises).
+- `$$` and `shell` return `Subprocess` synchronously — use `await sp.exited` to wait.
+
+## When Modifying This Package
+
+- Run `npm test` to execute tests (uses tape-six).
+- Run `npm run ts-check` to verify TypeScript declarations (`tsc --noEmit`).
+- Keep `src/index.d.ts` in sync with any API changes in `src/index.js`.
+- The wiki (in the `wiki/` submodule) documents the public API — update it alongside code changes.
+- Tests are in `tests/` (automated) and `tests/manual/` (manual verification).
+- TypeScript usage examples are in `ts-check/` — they are compiled but not executed during `npm run ts-check`.

package/README.md

@@ -194,16 +194,28 @@ the spawn options with the following properties:
 - `shellArgs` — an array of strings that are passed to the shell as arguments.
   - On Unix-like systems it defaults to `['-c']`.
   - On Windows it defaults to `['/d', '/s', '/c']` for `cmd.exe`
-    or `['-e']` for `pwsh.exe` or `powershell.exe`.
+    or `['-c']` for `pwsh.exe` or `powershell.exe`.
 
 The rest is identical to `$`: `$sh`, `$sh.from`, `$sh.to` and `$sh.io`/`$sh.through`.
 
+## For AI Agents
+
+This package ships with files to help AI coding agents and LLMs understand and use it:
+
+- **[AGENTS.md](./AGENTS.md)** — Quick-start instructions, architecture overview, and key patterns for AI agents working with this package.
+- **[llms.txt](./llms.txt)** — Concise project overview with links to documentation, following the [llms.txt standard](https://llmstxt.org/).
+- **[llms-full.txt](./llms-full.txt)** — Self-contained complete API reference (no external links needed).
+
+These files are included in the npm package.
+
 ## License
 
 BSD-3-Clause
 
 ## Release History
 
+- 1.1.9 _Updated dev dependencies, cleaned up docs, added info for AI agents._
+- 1.1.8 _Updated dev dependencies._
 - 1.1.7 _Updated dev dependencies._
 - 1.1.6 _Updated dev dependencies._
 - 1.1.5 _Updated dev dependencies._

package/llms-full.txt

@@ -0,0 +1,313 @@
+# dollar-shell
+
+> A micro-library for running shell commands and using them in stream pipelines with ease in Node, Deno, Bun. Tiny, simple, zero-dependency package with TypeScript typings. Uses web streams.
+
+The package provides template-tag functions to spawn OS processes (`$`, `$$`) and shell processes (`$sh`, `shell`/`sh`). Each has variants for stream pipelines: `.from` (stdout as ReadableStream), `.to` (stdin as WritableStream), `.io`/`.through` (duplex). All tag functions accept an options object to customize spawn/shell behavior and return a new tag function with updated defaults.
+
+Install: `npm i --save dollar-shell`
+
+## Usage
+
+```js
+import $, {$$, $sh, shell, sh, spawn} from 'dollar-shell';
+```
+
+## spawn()
+
+Low-level function to spawn a process with full control.
+
+Signature: `spawn(command: string[], options?: SpawnOptions): Subprocess`
+
+### SpawnOptions
+
+```ts
+type SpawnStreamState = 'pipe' | 'ignore' | 'inherit' | 'piped' | null;
+
+interface SpawnOptions {
+  cwd?: string;    // working directory, defaults to process.cwd()
+  env?: {[key: string]: string | undefined}; // environment variables
+  stdin?: SpawnStreamState;   // default: null (ignored)
+  stdout?: SpawnStreamState;  // default: null (ignored)
+  stderr?: SpawnStreamState;  // default: null (ignored)
+}
+```
+
+Stream states: `'pipe'`/`'piped'` makes the stream available, `'inherit'` inherits from parent, `'ignore'`/`null` ignores it.
+
+### Subprocess
+
+```ts
+interface Subprocess<R = any> {
+  readonly command: string[];
+  readonly options: SpawnOptions | undefined;
+  readonly exited: Promise<number>;       // resolves to exit code
+  readonly finished: boolean;
+  readonly killed: boolean;
+  readonly exitCode: number | null;
+  readonly signalCode: string | null;
+  readonly stdin: WritableStream<R> | null;   // non-null when stdin is 'pipe'
+  readonly stdout: ReadableStream<R> | null;  // non-null when stdout is 'pipe'
+  readonly stderr: ReadableStream<R> | null;  // non-null when stderr is 'pipe'
+  readonly asDuplex: {readable: ReadableStream<R>, writable: WritableStream<R>};
+  kill(): void;
+}
+```
+
+All streams are web streams (ReadableStream/WritableStream).
+
+Example:
+```js
+import {spawn} from 'dollar-shell';
+
+const sp = spawn(['sleep', '5']);
+await new Promise(resolve => setTimeout(resolve, 1000));
+sp.kill();
+await sp.exited;
+// sp.finished === true, sp.killed === true
+```
+
+## $$ (double dollar)
+
+Template tag function wrapping `spawn()`. Parses the template string into an array of arguments (split by whitespace). Interpolated values are kept as separate arguments when surrounded by whitespace.
+
+```ts
+type Backticks<R> = (strings: TemplateStringsArray, ...args: unknown[]) => R;
+
+interface Dollar<R, O = SpawnOptions> extends Backticks<R> {
+  (options: O): Dollar<R, O>;
+}
+
+declare const $$: Dollar<Subprocess>;
+```
+
+Signatures:
+```js
+import {$$} from 'dollar-shell';
+
+const sp = $$`ls -l ${myFile}`;           // returns Subprocess
+const sp2 = $$(options)`ls -l .`;          // with custom options
+const $tag = $$(options);                  // returns reusable tag function
+const sp3 = $tag`ls -l .`;
+```
+
+## $ (dollar)
+
+Simpler interface than `$$`. Returns a promise with exit info instead of a Subprocess.
+
+```ts
+interface DollarResult {
+  code: number | null;
+  signal: string | null;
+  killed: boolean;
+}
+
+interface DollarImpl<R = any> extends Dollar<Promise<DollarResult>> {
+  from: Dollar<ReadableStream<R>>;       // stdout as source stream
+  to: Dollar<WritableStream<R>>;         // stdin as sink stream
+  through: Dollar<DuplexPair<R>>;        // {readable, writable} pair
+  io: Dollar<DuplexPair<R>>;             // alias of through
+}
+
+declare const $: DollarImpl;
+export default $;
+```
+
+`$` is the default export.
+
+Examples:
+```js
+import $ from 'dollar-shell';
+
+// Run a command
+const result = await $`echo hello`;
+console.log(result.code, result.signal, result.killed);
+
+// With custom options
+const result2 = await $({stdout: 'inherit'})`ls -l .`;
+
+// Stream pipeline
+import chain from 'stream-chain';
+
+chain([
+  $.from`ls -l .`,
+  $.io`grep LICENSE`,
+  $.io`wc`,
+  $.to({stdout: 'inherit'})`tee output.txt`
+]);
+
+// Using $.from with web streams
+$.from`ls -l .`
+  .pipeThrough($.io`grep LIC`)
+  .pipeTo($.to({stdout: 'inherit'})`wc`);
+```
+
+When `$` is called with an options object, it returns a new `$` with updated defaults while preserving `.from`, `.to`, `.through`, `.io`:
+```js
+const $custom = $({stdout: 'inherit', stderr: 'inherit'});
+typeof $custom.from === 'function';  // true
+typeof $custom.io === 'function';    // true
+```
+
+## shell / sh
+
+Like `$$` but executes the command through a shell. Supports shell-specific features like pipes, aliases, and functions.
+
+```ts
+interface ShellOptions extends SpawnOptions {
+  shellPath?: string;    // path to shell executable
+  shellArgs?: string[];  // arguments passed to the shell
+}
+
+declare const shell: Dollar<Subprocess, ShellOptions>;
+declare const sh = shell;  // alias
+```
+
+Shell defaults:
+- Unix: shell = `$SHELL` or `/bin/sh` (or `/system/bin/sh` on Android), args = `['-c']`
+- Windows cmd.exe: shell = `%ComSpec%` or `cmd.exe`, args = `['/d', '/s', '/c']`
+- Windows PowerShell: shell = `pwsh.exe`/`powershell.exe`, args = `['-c']`
+
+Example:
+```js
+import {shell, sh} from 'dollar-shell';
+
+const sp = sh`sleep 5`;
+sp.kill();
+await sp.exited;
+```
+
+## $sh (dollar shell)
+
+Mirrors `$` but runs commands through a shell. Same relationship as `shell` to `$$`.
+
+```ts
+interface ShellImpl<R = any> extends Dollar<Promise<DollarResult>, ShellOptions> {
+  from: Dollar<ReadableStream<R>, ShellOptions>;
+  to: Dollar<WritableStream<R>, ShellOptions>;
+  through: Dollar<DuplexPair<R>, ShellOptions>;
+  io: Dollar<DuplexPair<R>, ShellOptions>;
+}
+
+declare const $sh: ShellImpl;
+```
+
+Examples:
+```js
+import {$sh} from 'dollar-shell';
+
+const result = await $sh`ls .`;
+console.log(result.code, result.signal, result.killed);
+
+// Interactive shell for aliases/functions
+const $p = $sh({shellArgs: ['-ic'], stdout: 'inherit'});
+await $p`nvm ls`;
+
+// Shell pipes
+await $sh({stdout: 'inherit'})`ls -l . | grep LICENSE | wc`;
+
+// Stream pipeline
+$sh.from`ls -l .`
+  .pipeThrough($sh.io`grep LIC`)
+  .pipeTo($sh.to({stdout: 'inherit'})`wc`);
+```
+
+## Utilities
+
+```js
+import {
+  isWindows, raw, winCmdEscape,
+  cwd, currentExecPath, runFileArgs,
+  shellEscape, currentShellPath, buildShellCommand
+} from 'dollar-shell';
+```
+
+### isWindows
+
+`const isWindows: boolean` — `true` if the current platform is Windows.
+
+### raw(value)
+
+Marks a value to bypass shell escaping or spawn argument splitting. The value is passed as-is.
+
+```js
+import {$sh, raw} from 'dollar-shell';
+await $sh({stdout: 'inherit'})`echo ${raw('"hello"')}`;
+```
+
+For spawn (`$`/`$$`), `raw()` values are split by whitespace like template string literals.
+
+### winCmdEscape(value)
+
+Escapes a value for Windows `cmd.exe` using caret (`^`) escaping. On non-Windows, returns the value as a string. Returns a `raw()`-wrapped object on Windows.
+
+```js
+import {$sh, winCmdEscape} from 'dollar-shell';
+await $sh`echo ${winCmdEscape('hello "world"')}`;
+```
+
+### cwd()
+
+Returns the current working directory (platform-agnostic).
+
+### currentExecPath()
+
+Returns the path of the current JS/TS runtime executable (Node, Deno, or Bun).
+
+### runFileArgs
+
+Array of default arguments for the current runtime:
+- Node: `[]`
+- Deno: `['run']`
+- Bun: `['run']`
+
+Note: Deno may require additional permission flags (e.g., `--allow-read`).
+
+### shellEscape(value, options?)
+
+Escapes a value for the current shell. Takes an optional `{shellPath?: string}` options object.
+- Unix: wraps in single quotes
+- Windows cmd.exe: quotes and escapes per cmd.exe rules
+- Windows PowerShell: escapes control characters and non-alphanumeric characters
+
+### currentShellPath()
+
+Returns the current shell path:
+- Unix: `$SHELL` or `/bin/sh` (or `/system/bin/sh` on Android)
+- Windows: `%ComSpec%` or `cmd.exe`
+
+### buildShellCommand(shell, args, command)
+
+Builds a command array for `spawn()` from shell path, args, and command string.
+- `shell`: string or undefined (defaults to `currentShellPath()`)
+- `args`: string[] or undefined (defaults to shell-specific args)
+- `command`: the shell command string
+
+Returns `string[]` suitable for `spawn()`.
+
+## Template String Behavior
+
+### Spawn functions ($, $$)
+
+Template strings are parsed into arrays of arguments by splitting on whitespace. Interpolated values:
+- If surrounded by whitespace: added as a separate argument (preserving spaces within the value)
+- If adjacent to text: concatenated with surrounding text
+- Empty strings are skipped
+- `raw()` values are split by whitespace like literal template text
+
+```js
+$`ls -l ${'.'}`;           // command: ['ls', '-l', '.']
+$`${'l'}s -l a${'.'}b`;    // command: ['ls', '-l', 'a.b']
+$`ls ${'x y'}`;            // command: ['ls', 'x y']  (preserved as one arg)
+```
+
+### Shell functions ($sh, shell)
+
+Template strings are concatenated into a single command string. Interpolated values are escaped using `shellEscape()` unless wrapped with `raw()`.
+
+## TypeScript
+
+Full TypeScript declarations are provided in `src/index.d.ts`. The package uses `"types": "./src/index.d.ts"` in package.json.
+
+## Platform Support
+
+Works on Node.js, Deno, and Bun. The appropriate spawn implementation is selected automatically at import time. All streams use the web streams API (ReadableStream/WritableStream).

package/llms.txt

@@ -0,0 +1,28 @@
+# dollar-shell
+
+> A micro-library for running shell commands and using them in stream pipelines with ease in Node, Deno, Bun. Tiny, simple, zero-dependency package with TypeScript typings. Uses web streams.
+
+The package provides template-tag functions to spawn OS processes (`$`, `$$`) and shell processes (`$sh`, `shell`/`sh`). Each has variants for stream pipelines: `.from` (stdout as ReadableStream), `.to` (stdin as WritableStream), `.io`/`.through` (duplex). All tag functions accept an options object to customize spawn/shell behavior and return a new tag function with updated defaults.
+
+Key concepts:
+- `$` runs a command, returns `Promise<{code, signal, killed}>`
+- `$$` runs a command, returns a `Subprocess` object (full control)
+- `$sh` runs a shell command, returns `Promise<{code, signal, killed}>`
+- `shell`/`sh` runs a shell command, returns a `Subprocess` object
+- `spawn()` is the low-level function all others build on
+- Template string arguments are automatically escaped (shell) or split (spawn)
+- `raw()` bypasses escaping/splitting for a value
+- Works on Node, Deno, and Bun with the same API
+
+## Docs
+
+- [$ (dollar)](https://github.com/uhop/dollar-shell/wiki/$): Spawn processes with simple return values, includes $.from, $.to, $.io/$.through
+- [$$ (double dollar)](https://github.com/uhop/dollar-shell/wiki/$$): Spawn processes returning full Subprocess objects
+- [$sh (dollar shell)](https://github.com/uhop/dollar-shell/wiki/$sh): Run shell commands with simple return values, includes $sh.from, $sh.to, $sh.io/$sh.through
+- [shell / sh](https://github.com/uhop/dollar-shell/wiki/shell): Run shell commands returning full Subprocess objects
+- [spawn()](https://github.com/uhop/dollar-shell/wiki/spawn): Low-level process spawning with full configuration
+- [Utilities](https://github.com/uhop/dollar-shell/wiki/Utilities): Helper functions — raw(), winCmdEscape(), isWindows, cwd(), currentExecPath(), runFileArgs, shellEscape(), currentShellPath(), buildShellCommand()
+
+## Optional
+
+- [TypeScript declarations](https://github.com/uhop/dollar-shell/blob/main/src/index.d.ts): Full TypeScript type definitions

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dollar-shell",
   "description": "Run shell commands and use them in streams with ease in Node, Deno, Bun. Tiny, simple, no dependency package.",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "type": "module",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
@@ -16,6 +16,9 @@
     "test": "tape6 --flags FO",
     "test:bun": "tape6-bun --flags FO",
     "test:deno": "tape6-deno --flags FO",
+    "test:seq": "tape6-seq --flags FO",
+    "test:seq:bun": "bun run `tape6-seq --self` --flags FO",
+    "test:seq:deno": "deno run -A `tape6-seq --self` --flags FO",
     "ts-check": "tsc --noEmit",
     "lint": "prettier --check .",
     "lint:fix": "prettier --write ."
@@ -23,7 +26,10 @@
   "files": [
     "/src",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "AGENTS.md",
+    "llms.txt",
+    "llms-full.txt"
   ],
   "repository": {
     "type": "git",
@@ -38,7 +44,13 @@
     "spawn",
     "$",
     "dollar",
-    "stream"
+    "stream",
+    "process",
+    "exec",
+    "command",
+    "web-streams",
+    "deno",
+    "bun"
   ],
   "author": "Eugene Lazutkin <eugene.lazutkin@gmail.com> (http://www.lazutkin.com/)",
   "funding": {
@@ -47,7 +59,7 @@
   },
   "license": "BSD-3-Clause",
   "devDependencies": {
-    "tape-six": "^1.5.1",
+    "tape-six": "^1.7.2",
     "typescript": "^5.9.3"
   },
   "tape6": {

package/src/index.d.ts

@@ -123,6 +123,11 @@ export declare function currentExecPath(): string;
  */
 export declare const runFileArgs: string[];
 
+/**
+ * Whether the current platform is Windows.
+ */
+export declare const isWindows: boolean;
+
 /**
  * The function marks a value as raw. The value will be passed as-is to the shell.
  * It is used to bypass the default shell escaping rules.