dollar-shell 1.1.8 → 1.1.10

package/AGENTS.md

@@ -0,0 +1,97 @@
+# AGENTS.md — dollar-shell
+
+> `dollar-shell` is a micro-library for running 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. Zero dependencies.
+
+For detailed usage docs and API references see the [wiki](https://github.com/uhop/dollar-shell/wiki).
+
+## Setup
+
+```bash
+git clone --recursive git@github.com:uhop/dollar-shell.git
+cd dollar-shell
+npm install
+```
+
+The wiki is a git submodule in `wiki/`.
+
+## Commands
+
+- **Test (Node):** `npm test` (runs `tape6 --flags FO`)
+- **Test (Bun):** `npm run test:bun`
+- **Test (Deno):** `npm run test:deno`
+- **TypeScript check:** `npm run ts-check` (`tsc --noEmit`)
+- **Lint:** `npm run lint` (Prettier check)
+- **Lint fix:** `npm run lint:fix` (Prettier write)
+
+## Project structure
+
+```
+dollar-shell/
+├── package.json      # Package config
+├── tsconfig.json     # TypeScript config (noEmit check only)
+├── src/              # Source code
+│   ├── index.js      # Main entry point, wires everything together
+│   ├── index.d.ts    # TypeScript declarations for the full public API
+│   ├── bq-spawn.js   # Template tag factory for spawn-based functions ($, $$)
+│   ├── bq-shell.js   # Template tag factory for shell-based functions ($sh, shell)
+│   ├── utils.js      # Shared utilities (raw, isWindows, winCmdEscape, etc.)
+│   ├── spawn/        # Runtime-specific Subprocess implementations
+│   │   ├── node.js   # Node.js: uses child_process + stream.Writable/Readable
+│   │   ├── deno.js   # Deno: uses Deno.Command
+│   │   └── bun.js    # Bun: uses Bun.spawn
+│   └── shell/        # Platform-specific shell escaping and command building
+│       ├── unix.js   # Unix: single-quote escaping, $SHELL detection
+│       └── windows.js # Windows: cmd.exe and PowerShell escaping
+├── tests/            # Automated tests (tape-six)
+├── tests/manual/     # Manual verification scripts
+├── ts-check/         # TypeScript usage examples (compiled but not executed)
+└── wiki/             # GitHub wiki documentation (git submodule)
+```
+
+## 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 .`;
+```
+
+## Code style
+
+- **ES modules** throughout (`"type": "module"` in package.json).
+- **No transpilation** — code runs directly in all target runtimes.
+- **Prettier** for formatting — run `npm run lint:fix` before committing.
+- Imports at the top of files, using `import` syntax.
+
+## Architecture
+
+- `src/index.js` is the main entry point. It dynamically imports the correct `spawn` implementation (Node/Deno/Bun) and the correct `shell` implementation (Unix/Windows) at import time.
+- All tag functions (`$`, `$$`, `$sh`, `shell`) are built by factory functions in `bq-spawn.js` and `bq-shell.js`.
+- **Tag function + options pattern**: calling a tag function with an options object returns a new tag function with updated defaults while preserving `.from`, `.to`, `.io`, `.through` properties.
+- **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.
+
+## Key conventions
+
+- Do not add dependencies — the library is intentionally zero-dependency.
+- All public API is exported from `src/index.js` and typed in `src/index.d.ts`. Keep them in sync.
+- Wiki documentation lives in the `wiki/` submodule — update it alongside code changes.
+- Tests are in `tests/` (automated, tape-six) and `tests/manual/` (manual verification scripts).
+- TypeScript usage examples are in `ts-check/` — they are compiled but not executed during `npm run ts-check`.

package/CLAUDE.md

@@ -0,0 +1,3 @@
+<!-- Claude Code project instructions — canonical source is AGENTS.md -->
+
+See [AGENTS.md](./AGENTS.md) for all AI agent rules and project conventions.

package/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing to dollar-shell
+
+Thank you for your interest in contributing!
+
+## Getting started
+
+This project uses git submodules. Clone and set up:
+
+```bash
+git clone --recursive git@github.com:uhop/dollar-shell.git
+cd dollar-shell
+npm install
+```
+
+See the [wiki](https://github.com/uhop/dollar-shell/wiki) for API documentation.
+
+## Development workflow
+
+1. Make your changes.
+2. Format: `npm run lint:fix`
+3. Test: `npm test`
+4. Type-check: `npm run ts-check`
+
+## Code style
+
+- ES modules (`import`/`export`), no CommonJS in source.
+- Formatted with Prettier — run `npm run lint:fix` before committing.
+- No dependencies — the library is intentionally zero-dependency.
+- Keep `src/index.js` and `src/index.d.ts` in sync.
+- Update wiki documentation alongside code changes.
+
+## AI agents
+
+If you are an AI coding agent, see [AGENTS.md](./AGENTS.md) for detailed project conventions, commands, and architecture.

package/README.md

@@ -3,7 +3,7 @@
 [npm-image]: https://img.shields.io/npm/v/dollar-shell.svg
 [npm-url]: https://npmjs.org/package/dollar-shell
 
-`dollar-shell` is a micro-library for running shell commands and using them in streams with ease in Node, Deno, Bun. It is a tiny, simple, no dependency package with TypeScript typings.
+`dollar-shell` is a micro-library for running OS and shell commands from JavaScript/TypeScript using template tag functions. It works in [Node](https://nodejs.org/), [Deno](https://deno.land/), [Bun](https://bun.sh/) with the same API. **Web streams, TypeScript typings, zero dependencies.**
 
 The idea is to run OS/shell commands and/or use them in stream pipelines as sources, sinks,
 and transformation steps using [web streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API).
@@ -85,10 +85,32 @@ chain([
 npm i --save dollar-shell
 ```
 
+## Project structure
+
+```
+dollar-shell/
+├── src/              # Source code
+│   ├── index.js      # Main entry point, wires everything together
+│   ├── index.d.ts    # TypeScript declarations for the full public API
+│   ├── bq-spawn.js   # Template tag factory for spawn-based functions ($, $$)
+│   ├── bq-shell.js   # Template tag factory for shell-based functions ($sh, shell)
+│   ├── utils.js      # Shared utilities (raw, isWindows, winCmdEscape, etc.)
+│   ├── spawn/        # Runtime-specific Subprocess implementations
+│   └── shell/        # Platform-specific shell escaping and command building
+├── tests/            # Automated tests (tape-six)
+├── tests/manual/     # Manual verification scripts
+├── ts-check/         # TypeScript usage examples (compiled but not executed)
+└── wiki/             # GitHub wiki documentation (git submodule)
+```
+
 ## Documentation
 
+The documentation can be found in the [wiki](https://github.com/uhop/dollar-shell/wiki).
+See how it can be used in [tests/](https://github.com/uhop/dollar-shell/tree/main/tests).
+
+For AI assistants: see [llms.txt](https://github.com/uhop/dollar-shell/blob/main/llms.txt) and [llms-full.txt](https://github.com/uhop/dollar-shell/blob/main/llms-full.txt) for LLM-optimized documentation.
+
 Below is the documentation for the main components: `spawn()`, `$$`, `$` and `$sh`.
-Additional information can be found in the [wiki](https://github.com/uhop/dollar-shell/wiki).
 
 ### `spawn()`
 
@@ -194,16 +216,30 @@ 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 find, understand, and use it:
+
+- **[AGENTS.md](./AGENTS.md)** — Project conventions, architecture, commands, and coding guidelines for AI agents.
+- **[CLAUDE.md](./CLAUDE.md)** — Claude Code specific instructions (redirects to AGENTS.md).
+- **[CONTRIBUTING.md](./CONTRIBUTING.md)** — Contribution guidelines for humans and AI agents.
+- **[llms.txt](./llms.txt)** — Concise project overview following the [llms.txt standard](https://llmstxt.org/).
+- **[llms-full.txt](./llms-full.txt)** — Self-contained complete API reference (no external links needed).
+
+All files are included in the npm package.
+
 ## License
 
 BSD-3-Clause
 
 ## Release History
 
+- 1.1.10 _Fixed a bug with options chaining for attached functions, fixed Bun spawn on invalid commands, Windows-compatible tests, updated dev dependencies._
+- 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._

package/llms-full.txt

@@ -0,0 +1,317 @@
+# dollar-shell
+
+> A micro-library for running OS and shell commands from JavaScript/TypeScript using template tag functions. Works in Node, Deno, and Bun with the same API. Web streams, TypeScript typings, zero dependencies.
+
+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
+
+```bash
+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,79 @@
+# dollar-shell
+
+> A micro-library for running OS and shell commands from JavaScript/TypeScript using template tag functions. Works in Node, Deno, and Bun with the same API. Web streams, TypeScript typings, zero dependencies.
+
+## Install
+
+npm i --save dollar-shell
+
+## Quick start
+
+```js
+import $ from 'dollar-shell';
+
+const result = await $`echo hello`;
+// result: {code: 0, signal: null, killed: false}
+```
+
+Run: `node my-script.js`
+
+## API
+
+- `$` — run a command, returns `Promise<{code, signal, killed}>`. Default export.
+- `$$` — run a command, returns a `Subprocess` object (full control: kill, streams, exit code).
+- `$sh` — run a shell command, returns `Promise<{code, signal, killed}>`.
+- `shell` / `sh` — run a shell command, returns a `Subprocess` object.
+- `spawn()` — low-level process spawning with full configuration.
+
+Stream pipeline helpers (available on `$` and `$sh`):
+- `.from` — stdout as a ReadableStream (source).
+- `.to` — stdin as a WritableStream (sink).
+- `.io` / `.through` — {readable, writable} duplex pair (transform step).
+
+All tag functions accept an options object to return a new tag function with updated defaults.
+
+Utilities: `raw()`, `winCmdEscape()`, `isWindows`, `cwd()`, `currentExecPath()`, `runFileArgs`, `shellEscape()`, `currentShellPath()`, `buildShellCommand()`.
+
+## Common patterns
+
+```js
+import $, {$$, $sh, raw} from 'dollar-shell';
+
+// Simple command
+const result = await $`echo hello`;
+
+// Shell command (pipes, aliases, globbing)
+await $sh({stdout: 'inherit'})`ls -l . | grep LICENSE | wc`;
+
+// Full Subprocess control
+const sp = $$`sleep 5`;
+sp.kill();
+await sp.exited;
+
+// Custom options (returns new tag function)
+const $verbose = $({stdout: 'inherit', stderr: 'inherit'});
+await $verbose`ls -l .`;
+
+// Web stream pipeline
+$.from`ls -l .`
+  .pipeThrough($.io`grep LIC`)
+  .pipeTo($.to({stdout: 'inherit'})`wc`);
+
+// Bypass escaping with raw()
+await $sh({stdout: 'inherit'})`echo ${raw('"hello"')}`;
+```
+
+## 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()
+
+## Links
+
+- Docs: https://github.com/uhop/dollar-shell/wiki
+- npm: https://www.npmjs.com/package/dollar-shell
+- Full LLM reference: https://github.com/uhop/dollar-shell/blob/main/llms-full.txt

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.8",
+  "description": "Run shell commands and use them in stream pipelines with ease in Node, Deno, Bun. Template tag API, web streams, TypeScript typings, zero dependencies.",
+  "version": "1.1.10",
   "type": "module",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
@@ -26,7 +26,12 @@
   "files": [
     "/src",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "CONTRIBUTING.md",
+    "llms.txt",
+    "llms-full.txt"
   ],
   "repository": {
     "type": "git",
@@ -36,12 +41,28 @@
     "url": "https://github.com/uhop/dollar-shell/issues"
   },
   "homepage": "https://github.com/uhop/dollar-shell#readme",
+  "llms": "https://raw.githubusercontent.com/uhop/dollar-shell/main/llms.txt",
+  "llmsFull": "https://raw.githubusercontent.com/uhop/dollar-shell/main/llms-full.txt",
   "keywords": [
     "shell",
     "spawn",
     "$",
     "dollar",
-    "stream"
+    "stream",
+    "process",
+    "exec",
+    "command",
+    "web-streams",
+    "template-tag",
+    "pipeline",
+    "typescript",
+    "esm",
+    "es-modules",
+    "cross-runtime",
+    "zero-dependency",
+    "nodejs",
+    "deno",
+    "bun"
   ],
   "author": "Eugene Lazutkin <eugene.lazutkin@gmail.com> (http://www.lazutkin.com/)",
   "funding": {
@@ -50,7 +71,8 @@
   },
   "license": "BSD-3-Clause",
   "devDependencies": {
-    "tape-six": "^1.7.0",
+    "prettier": "^3.8.1",
+    "tape-six": "^1.7.4",
     "typescript": "^5.9.3"
   },
   "tape6": {

package/src/bq-shell.js

@@ -1,5 +1,3 @@
-'use strict';
-
 import {isRawValue, getRawValue, verifyStrings} from './utils.js';
 
 const impl =
@@ -28,7 +26,11 @@ const impl =
 const bqShell = (shellEscape, shell, options = {}) => {
   const bq = (strings, ...args) => {
     if (verifyStrings(strings)) return impl(shellEscape, shell, options)(strings, ...args);
-    return Object.assign(bqShell(shellEscape, shell, {...options, ...strings}), bq);
+    const derived = bqShell(shellEscape, shell, {...options, ...strings});
+    for (const [key, value] of Object.entries(bq)) {
+      derived[key] = typeof value === 'function' ? value(strings) : value;
+    }
+    return derived;
   };
   return bq;
 };

package/src/bq-spawn.js

@@ -1,5 +1,3 @@
-'use strict';
-
 import {verifyStrings, isRawValue, getRawValue} from './utils.js';
 
 const appendString = (s, previousSpace, result) => {
@@ -69,7 +67,11 @@ const impl =
 const bqSpawn = (spawn, options = {}) => {
   const bq = (strings, ...args) => {
     if (verifyStrings(strings)) return impl(spawn, options)(strings, ...args);
-    return Object.assign(bqSpawn(spawn, {...options, ...strings}), bq);
+    const derived = bqSpawn(spawn, {...options, ...strings});
+    for (const [key, value] of Object.entries(bq)) {
+      derived[key] = typeof value === 'function' ? value(strings) : value;
+    }
+    return derived;
   };
   return bq;
 };

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.

package/src/index.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./index.d.ts"
 
-'use strict';
-
 // load dependencies
 
 import {isWindows, raw, winCmdEscape} from './utils.js';
@@ -39,17 +37,17 @@ export const $ = bqSpawn((command, options) => {
 });
 
 const fromProcess = bqSpawn((command, options) => {
-  const sp = spawn(command, Object.assign({}, options, {stdout: 'pipe'}));
+  const sp = spawn(command, {...options, stdout: 'pipe'});
   return sp.stdout;
 });
 
 const toProcess = bqSpawn((command, options) => {
-  const sp = spawn(command, Object.assign({}, options, {stdin: 'pipe'}));
+  const sp = spawn(command, {...options, stdin: 'pipe'});
   return sp.stdin;
 });
 
 const throughProcess = bqSpawn((command, options) => {
-  const sp = spawn(command, Object.assign({}, options, {stdin: 'pipe', stdout: 'pipe'}));
+  const sp = spawn(command, {...options, stdin: 'pipe', stdout: 'pipe'});
   return sp.asDuplex;
 });
 
@@ -60,36 +58,46 @@ $.through = $.io = throughProcess;
 // define shell functions
 
 export const shell = bqShell(shellEscape, (command, options) =>
-  spawn(buildShellCommand(options?.shellPath, options?.shellArgs, command), options)
+  spawn(buildShellCommand(options?.shellPath, options?.shellArgs, command), {
+    ...options,
+    windowsVerbatimArguments: true
+  })
 );
 export {shell as sh};
 
 export const $sh = bqShell(shellEscape, (command, options) => {
-  const sp = spawn(buildShellCommand(options?.shellPath, options?.shellArgs, command), options);
+  const sp = spawn(buildShellCommand(options?.shellPath, options?.shellArgs, command), {
+    ...options,
+    windowsVerbatimArguments: true
+  });
   return sp.exited.then(() => ({code: sp.exitCode, signal: sp.signalCode, killed: sp.killed}));
 });
 
 const fromShell = bqShell(shellEscape, (command, options) => {
-  const sp = spawn(
-    buildShellCommand(options?.shellPath, options?.shellArgs, command),
-    Object.assign({}, options, {stdout: 'pipe'})
-  );
+  const sp = spawn(buildShellCommand(options?.shellPath, options?.shellArgs, command), {
+    ...options,
+    stdout: 'pipe',
+    windowsVerbatimArguments: true
+  });
   return sp.stdout;
 });
 
 const toShell = bqShell(shellEscape, (command, options) => {
-  const sp = spawn(
-    buildShellCommand(options?.shellPath, options?.shellArgs, command),
-    Object.assign({}, options, {stdin: 'pipe'})
-  );
+  const sp = spawn(buildShellCommand(options?.shellPath, options?.shellArgs, command), {
+    ...options,
+    stdin: 'pipe',
+    windowsVerbatimArguments: true
+  });
   return sp.stdin;
 });
 
 const throughShell = bqShell(shellEscape, (command, options) => {
-  const sp = spawn(
-    buildShellCommand(options?.shellPath, options?.shellArgs, command),
-    Object.assign({}, options, {stdin: 'pipe', stdout: 'pipe'})
-  );
+  const sp = spawn(buildShellCommand(options?.shellPath, options?.shellArgs, command), {
+    ...options,
+    stdin: 'pipe',
+    stdout: 'pipe',
+    windowsVerbatimArguments: true
+  });
   return sp.asDuplex;
 });
 

package/src/shell/unix.js

@@ -1,5 +1,3 @@
-'use strict';
-
 import {getEnv, isAndroid} from '../utils.js';
 
 export const shellEscape = s => "'" + String(s).replace(/'/g, "'\\''") + "'";

package/src/shell/windows.js

@@ -1,5 +1,3 @@
-'use strict';
-
 import {getEnv, toBase64} from '../utils.js';
 
 export const currentShellPath = () => getEnv('ComSpec') || 'cmd.exe';

package/src/spawn/bun.js

@@ -1,5 +1,3 @@
-'use strict';
-
 const sanitize = (value, defaultValue = 'ignore') => {
   switch (value) {
     case 'pipe':
@@ -20,8 +18,10 @@ class Subprocess {
     this.options = options;
 
     this.killed = false;
+    this.finished = false;
 
-    const spawnOptions = {windowsVerbatimArguments: true};
+    const spawnOptions = {};
+    if (options.windowsVerbatimArguments) spawnOptions.windowsVerbatimArguments = true;
     options.cwd && (spawnOptions.cwd = options.cwd);
     options.env && (spawnOptions.env = options.env);
 
@@ -31,27 +31,33 @@ class Subprocess {
 
     this.spawnOptions = spawnOptions;
 
-    this.childProcess = Bun.spawn(command, spawnOptions);
+    try {
+      this.childProcess = Bun.spawn(command, spawnOptions);
+    } catch (error) {
+      this.childProcess = null;
+      this.finished = true;
+      this.exited = Promise.reject(error);
+      this.stdin = null;
+      this.stdout = null;
+      this.stderr = null;
+      return;
+    }
+    this.exited = this.childProcess.exited.then(code => {
+      this.finished = true;
+      return code;
+    });
 
     this.stdin = this.childProcess.stdin ? new WritableStream(this.childProcess.stdin) : null;
     this.stdout = this.childProcess.stdout || null;
     this.stderr = this.childProcess.stderr || null;
   }
 
-  get exited() {
-    return this.childProcess.exited;
-  }
-
-  get finished() {
-    return this.childProcess.killed;
-  }
-
   get exitCode() {
-    return this.childProcess.exitCode;
+    return this.childProcess ? this.childProcess.exitCode : null;
   }
 
   get signalCode() {
-    return this.childProcess.signalCode;
+    return this.childProcess ? this.childProcess.signalCode : null;
   }
 
   get asDuplex() {

package/src/spawn/deno.js

@@ -1,5 +1,3 @@
-'use strict';
-
 const sanitize = (value, defaultValue = 'null') => {
   switch (value) {
     case 'pipe':
@@ -28,9 +26,9 @@ class Subprocess {
 
     const spawnOptions = {
       signal: this.controller.signal,
-      args: command.slice(1),
-      windowsRawArguments: true
+      args: command.slice(1)
     };
+    if (options.windowsVerbatimArguments) spawnOptions.windowsRawArguments = true;
     options.cwd && (spawnOptions.cwd = options.cwd);
     options.env && (spawnOptions.env = options.env);
 
@@ -40,7 +38,14 @@ class Subprocess {
 
     this.spawnOptions = spawnOptions;
 
-    this.childProcess = new Deno.Command(command[0], spawnOptions).spawn();
+    try {
+      this.childProcess = new Deno.Command(command[0], spawnOptions).spawn();
+    } catch (error) {
+      this.childProcess = null;
+      this.finished = true;
+      this.exited = Promise.reject(error);
+      return;
+    }
 
     this.exited = this.childProcess.status
       .then(status => {
@@ -56,15 +61,21 @@ class Subprocess {
   }
 
   get stdin() {
-    return this.spawnOptions.stdin === 'piped' ? this.childProcess.stdin : null;
+    return this.childProcess && this.spawnOptions.stdin === 'piped'
+      ? this.childProcess.stdin
+      : null;
   }
 
   get stdout() {
-    return this.spawnOptions.stdout === 'piped' ? this.childProcess.stdout : null;
+    return this.childProcess && this.spawnOptions.stdout === 'piped'
+      ? this.childProcess.stdout
+      : null;
   }
 
   get stderr() {
-    return this.spawnOptions.stderr === 'piped' ? this.childProcess.stderr : null;
+    return this.childProcess && this.spawnOptions.stderr === 'piped'
+      ? this.childProcess.stderr
+      : null;
   }
 
   get asDuplex() {

package/src/spawn/node.js

@@ -1,5 +1,3 @@
-'use strict';
-
 import {spawn} from 'node:child_process';
 import {Readable, Writable} from 'node:stream';
 
@@ -29,7 +27,8 @@ class Subprocess {
     this.killed = false;
     this.finished = false;
 
-    const spawnOptions = {stdio: ['ignore', 'ignore', 'ignore'], windowsVerbatimArguments: true};
+    const spawnOptions = {stdio: ['ignore', 'ignore', 'ignore']};
+    if (options.windowsVerbatimArguments) spawnOptions.windowsVerbatimArguments = true;
     options.cwd && (spawnOptions.cwd = options.cwd);
     options.env && (spawnOptions.env = options.env);
 
@@ -39,6 +38,22 @@ class Subprocess {
 
     this.spawnOptions = spawnOptions;
 
+    let settled = false;
+    this.exited = new Promise((resolve, reject) => {
+      this.resolve = value => {
+        if (!settled) {
+          settled = true;
+          resolve(value);
+        }
+      };
+      this.reject = value => {
+        if (!settled) {
+          settled = true;
+          reject(value);
+        }
+      };
+    });
+
     this.childProcess = spawn(command[0], command.slice(1), spawnOptions);
     this.childProcess.on('exit', (code, signal) => {
       this.finished = true;
@@ -51,11 +66,6 @@ class Subprocess {
       this.reject(error);
     });
 
-    this.exited = new Promise((resolve, reject) => {
-      this.resolve = resolve;
-      this.reject = reject;
-    });
-
     this.stdin = this.childProcess.stdin && Writable.toWeb(this.childProcess.stdin);
     this.stdout = this.childProcess.stdout && Readable.toWeb(this.childProcess.stdout);
     this.stderr = this.childProcess.stderr && Readable.toWeb(this.childProcess.stderr);

package/src/utils.js

@@ -1,5 +1,3 @@
-'use strict';
-
 let getEnv, isWindows, isAndroid;
 if (typeof Deno !== 'undefined') {
   getEnv = name => Deno.env.get(name);
@@ -16,8 +14,7 @@ if (typeof Deno !== 'undefined') {
 }
 export {getEnv, isWindows, isAndroid};
 
-export const verifyStrings = strings =>
-  Array.isArray(strings) && strings.every(s => typeof s === 'string');
+export const verifyStrings = strings => Array.isArray(strings) && Array.isArray(strings.raw);
 
 export const toBase64 = s => {
   // const buf = new TextEncoder().encode(s),