dollar-shell 1.1.14 → 1.2.1

package/README.md

@@ -219,6 +219,40 @@ the spawn options with the following properties:
 
 The rest is identical to `$`: `$sh`, `$sh.from`, `$sh.to` and `$sh.io`/`$sh.through`.
 
+## Forcing the Node backend
+
+Each runtime uses its own backend by default (`node:child_process` on Node, `Bun.spawn` on Bun,
+`Deno.Command` on Deno). Set the **`DSH_FORCE_NODE` environment variable** (e.g. `DSH_FORCE_NODE=1`) to
+make every runtime spawn through the Node backend — Bun and Deno then run `node:child_process` on
+their compatibility layer. This swaps **only the spawn mechanism**: the runtime that runs your code and how
+it's re-launched stay native, so a forced child of Bun/Deno is still `bun run …` / `deno run …`, never a
+bare `node`. Handy for sidestepping runtime-specific quirks (e.g. Bun intermittently dropping the last
+chunk of a child's piped output).
+
+Because dollar-shell spawns children with `env` defaulting to `process.env`, the variable is inherited by
+those children — so it forces the Node backend across the whole process tree. To force **only the
+current process** (no leak to spawned children), set `globalThis.DSH_FORCE_NODE = true` before importing
+instead; it's process-local, but requires a dynamic `import()` (the backend is chosen once, at import time).
+See the [Cross-runtime notes](https://github.com/uhop/dollar-shell/wiki/Cross-runtime-notes) for details.
+
+## Node streams (`dollar-shell/node`)
+
+The default entry exposes [web streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) on
+`stdin`/`stdout`/`stderr`. If you'd rather work with Node streams — to pipe straight into `fs`/`zlib`/etc.
+with no Web↔Node adapter, or to skip the conversion — import from `dollar-shell/node` instead:
+
+```js
+import {spawn} from 'dollar-shell/node';
+
+const sp = spawn(['cat', 'file.txt'], {stdout: 'pipe'});
+sp.stdout.pipe(process.stdout); // sp.stdout is a Node Readable
+```
+
+The API is identical to the main entry — same `$`, `$$`, `$sh`, `shell`, helpers, and
+`.from`/`.to`/`.through`/`.io` — only the stream types differ (`stdin` is a Node `Writable`, `stdout`/`stderr`
+are Node `Readable`s, and `asDuplex` / `.io` / `.through` return a Node `Duplex`). It always spawns through the Node backend, so it also runs on Bun and Deno through their
+`node:child_process` compatibility layer (only the spawn mechanism changes — the runtime launch stays native).
+
 ## For AI Agents
 
 This package ships with files to help AI coding agents and LLMs find, understand, and use it:
@@ -229,7 +263,7 @@ This package ships with files to help AI coding agents and LLMs find, understand
 - **[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.
+The machine-readable `llms.txt` and `llms-full.txt` ship inside the npm package, so AI tools can read them straight from `node_modules`. `AGENTS.md` and `CLAUDE.md` are authoring-side docs kept in the repository.
 
 ## License
 
@@ -237,6 +271,8 @@ BSD-3-Clause
 
 ## Release History
 
+- 1.2.1 _Bugfix: `DSH_FORCE_NODE` and `dollar-shell/node` now switch only the spawn mechanism — spawned children stay native (`bun run …` / `deno run …`)._
+- 1.2.0 _Added `dollar-shell/node` with Node streams and a `DSH_FORCE_NODE` flag to force the Node backend on any runtime._
 - 1.1.14 _Fixed Bun stdin abort path, added js-check, Bun + Deno wired into CI._
 - 1.1.13 _Updated dev dependencies._
 - 1.1.12 _Consolidated TypeScript tests into `tests/`, removed `ts-check/`, added CJS test, improved test coverage and documentation._

package/llms-full.txt

@@ -13,7 +13,7 @@ npm i --save dollar-shell
 ## Usage
 
 ```js
-import $, {$$, $sh, shell, sh, spawn} from 'dollar-shell';
+import {$, $$, $sh, shell, sh, spawn} from 'dollar-shell';
 ```
 
 ## spawn()
@@ -315,3 +315,36 @@ Full TypeScript declarations are provided in `src/index.d.ts`. The package uses
 ## 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).
+
+### Forcing the Node backend
+
+By default each runtime uses its own backend (`node:child_process` on Node, `Bun.spawn` on Bun, `Deno.Command` on Deno). Make every runtime spawn through the Node backend — so Bun and Deno run `node:child_process` on their compatibility layer — with the **`DSH_FORCE_NODE` environment variable** (any value except `''`, `0`, `false`):
+
+```bash
+DSH_FORCE_NODE=1 node app.js
+```
+
+This swaps **only the spawn mechanism**. The runtime that executes your scripts and the way dollar-shell re-launches the current runtime (`currentExecPath` / `runFileArgs` / `cwd`) stay native — a forced child of Bun or Deno is still launched as `bun run …` / `deno run …`, never a bare `node`.
+
+dollar-shell's `env` option defaults to `process.env`, so spawned children inherit the variable — the environment variable therefore forces the Node backend across the **whole process tree** (this process and every dollar-shell child it spawns), which is usually what you want for a build script or wrapper.
+
+To force **only the current process** without leaking into the children it spawns, set the process-local flag instead. It requires a dynamic `import()`, because the backend is chosen once, when the module first loads:
+
+```js
+globalThis.DSH_FORCE_NODE = true;
+const {$} = await import('dollar-shell');
+```
+
+(Or keep the environment variable and pass an explicit `env` to the children you don't want affected.)
+
+This is useful to sidestep runtime-specific quirks (e.g. Bun intermittently dropping the final chunk of a child's piped Web-Stream output; the Node backend delivers it reliably). On Deno, **reading** the env var needs `--allow-env` (the read is permission-guarded, so a plain import never prompts) and **writing** `process.env` in-process needs it too, whereas the `globalThis` flag needs no permission. Forcing the Node backend on Deno makes `stdout` a regular (non-byte) ReadableStream, so BYOB readers are unavailable there.
+
+### Node streams (`dollar-shell/node`)
+
+The package also ships a Node-streams facade at `dollar-shell/node`:
+
+```js
+import {$, $$, $sh, shell, sh, spawn} from 'dollar-shell/node';
+```
+
+The API is identical to the main entry, except the streams are Node streams (from `node:stream`) instead of Web streams: `stdin`/`stdout`/`stderr` are a Node `Writable`/`Readable`, and `.io`/`.through`/`asDuplex` return a Node `Duplex` (so a process drops straight into a `.pipe()` chain or `stream.pipeline()`). This is convenient for direct Node-ecosystem interop — pipe straight into `fs`/`zlib`/etc. with no Web↔Node adapter, and skip the conversion. It always spawns through the Node backend, so on Bun and Deno it runs `node:child_process` through their compatibility layer; like `DSH_FORCE_NODE`, this changes only the spawn mechanism — the runtime that executes your scripts and how it is re-launched stay native. Type declarations live in `src/node/index.d.ts`.

package/llms.txt

@@ -37,7 +37,7 @@ Utilities: `raw()`, `winCmdEscape()`, `isWindows`, `cwd()`, `currentExecPath()`,
 ## Common patterns
 
 ```js
-import $, {$$, $sh, raw} from 'dollar-shell';
+import {$, $$, $sh, raw} from 'dollar-shell';
 
 // Simple command
 const result = await $`echo hello`;
@@ -63,6 +63,14 @@ $.from`ls -l .`
 await $sh({stdout: 'inherit'})`echo ${raw('"hello"')}`;
 ```
 
+## Forcing the Node backend
+
+By default each runtime uses its native backend. Set the `DSH_FORCE_NODE` environment variable (e.g. `DSH_FORCE_NODE=1`) to make every runtime spawn through the Node backend (`node:child_process`; Bun and Deno run it on their Node compat). This swaps **only the spawn mechanism** — the runtime that runs your code and how dollar-shell re-launches it stay native, so a forced child of Bun/Deno is still `bun run …` / `deno run …`, never a bare `node`. Because dollar-shell's `env` option defaults to `process.env`, spawned children inherit the variable, so it forces the whole process tree; to force only the current process (no leak to children), set `globalThis.DSH_FORCE_NODE = true` before a dynamic `import()` instead (process-local). Useful to sidestep runtime-specific quirks. The backend is selected once, at import time. Treated as off: unset, `''`, `0`, `false`.
+
+## Node streams (`dollar-shell/node`)
+
+`import {$, $$, $sh, shell, spawn} from 'dollar-shell/node'` gives the identical API, but `stdin`/`stdout`/`stderr` are Node `Readable`/`Writable` (and `.io`/`.through`/`asDuplex` a Node `Duplex`) instead of Web streams — for direct Node-ecosystem piping with no adapter. Always spawns through the Node backend (`node:child_process`, run on Bun/Deno via their Node compat); only the spawn mechanism changes — the runtime launch stays native.
+
 ## Docs
 
 - [$ (dollar)](https://github.com/uhop/dollar-shell/wiki/$): Spawn processes with simple return values, includes $.from, $.to, $.io/$.through

package/package.json

@@ -1,15 +1,13 @@
 {
   "name": "dollar-shell",
   "description": "Run OS and shell commands using template tag functions. Same API in Node, Deno, and Bun. Web streams, TypeScript typings, zero dependencies.",
-  "version": "1.1.14",
+  "version": "1.2.1",
   "type": "module",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
   "exports": {
-    ".": {
-      "types": "./src/index.d.ts",
-      "default": "./src/index.js"
-    },
+    ".": "./src/index.js",
+    "./node": "./src/node/index.js",
     "./*": "./src/*"
   },
   "scripts": {
@@ -31,9 +29,6 @@
     "/src",
     "LICENSE",
     "README.md",
-    "AGENTS.md",
-    "CLAUDE.md",
-    "CONTRIBUTING.md",
     "llms.txt",
     "llms-full.txt"
   ],
@@ -57,6 +52,7 @@
     "exec",
     "command",
     "web-streams",
+    "node-streams",
     "template-tag",
     "pipeline",
     "typescript",
@@ -73,12 +69,15 @@
     "url": "https://github.com/sponsors/uhop"
   },
   "license": "BSD-3-Clause",
+  "engines": {
+    "node": ">=22"
+  },
   "devDependencies": {
-    "@types/bun": "^1.3.13",
-    "@types/deno": "^2.5.0",
-    "@types/node": "^25.6.0",
+    "@types/bun": "^1.3.14",
+    "@types/deno": "^2.7.0",
+    "@types/node": "^25.9.1",
     "prettier": "^3.8.3",
-    "tape-six": "^1.9.0",
+    "tape-six": "^1.10.1",
     "typescript": "^6.0.3"
   },
   "tape6": {

package/src/bq-shell.js

@@ -1,4 +1,4 @@
-import {isRawValue, getRawValue, verifyStrings} from './utils.js';
+import {isRawValue, getRawValue, verifyStrings, bqTagSymbol, isBqTag} from './utils.js';
 
 const impl =
   (shellEscape, shell, options) =>
@@ -28,10 +28,11 @@ const bqShell = (shellEscape, shell, options = {}) => {
     if (verifyStrings(strings)) return impl(shellEscape, shell, options)(strings, ...args);
     const derived = bqShell(shellEscape, shell, {...options, ...strings});
     for (const [key, value] of Object.entries(bq)) {
-      derived[key] = typeof value === 'function' ? value(strings) : value;
+      derived[key] = isBqTag(value) ? value(strings) : value;
     }
     return derived;
   };
+  /** @type {any} */ (bq)[bqTagSymbol] = true;
   return bq;
 };
 

package/src/bq-spawn.js

@@ -1,4 +1,4 @@
-import {verifyStrings, isRawValue, getRawValue} from './utils.js';
+import {verifyStrings, isRawValue, getRawValue, bqTagSymbol, isBqTag} from './utils.js';
 
 const appendString = (s, previousSpace, result) => {
   previousSpace ||= /^\s/.test(s);
@@ -69,10 +69,11 @@ const bqSpawn = (spawn, options = {}) => {
     if (verifyStrings(strings)) return impl(spawn, options)(strings, ...args);
     const derived = bqSpawn(spawn, {...options, ...strings});
     for (const [key, value] of Object.entries(bq)) {
-      derived[key] = typeof value === 'function' ? value(strings) : value;
+      derived[key] = isBqTag(value) ? value(strings) : value;
     }
     return derived;
   };
+  /** @type {any} */ (bq)[bqTagSymbol] = true;
   return bq;
 };
 

package/src/build.js

@@ -0,0 +1,113 @@
+// Shared API builder. Given a spawn backend (`spawn`, `cwd`, `currentExecPath`,
+// `runFileArgs`), wires up the shell helpers and all tag functions ($, $$, $sh,
+// shell, with from/to/through/io). Both entry points reuse this — `index.js`
+// passes a Web-Streams backend, `node/index.js` passes the raw-Node-streams one.
+
+import bqSpawn from './bq-spawn.js';
+import bqShell from './bq-shell.js';
+
+import {isWindows} from './utils.js';
+
+export const buildApi = async ({spawn, cwd, currentExecPath, runFileArgs}) => {
+  let modShell;
+  if (isWindows) {
+    modShell = await import('./shell/windows.js');
+  } else {
+    modShell = await import('./shell/unix.js');
+  }
+  const {shellEscape, currentShellPath, buildShellCommand} = modShell;
+
+  // spawn functions
+
+  const $$ = bqSpawn(spawn);
+
+  const $ = bqSpawn((command, options) => {
+    const sp = spawn(command, options);
+    return sp.exited.then(() => ({code: sp.exitCode, signal: sp.signalCode, killed: sp.killed}));
+  });
+
+  const fromProcess = bqSpawn((command, options) => {
+    const sp = spawn(command, {...options, stdout: 'pipe'});
+    return sp.stdout;
+  });
+
+  const toProcess = bqSpawn((command, options) => {
+    const sp = spawn(command, {...options, stdin: 'pipe'});
+    return sp.stdin;
+  });
+
+  const throughProcess = bqSpawn((command, options) => {
+    const sp = spawn(command, {...options, stdin: 'pipe', stdout: 'pipe'});
+    return sp.asDuplex;
+  });
+
+  const $impl = /** @type {import('./index.d.ts').DollarImpl} */ ($);
+  $impl.from = fromProcess;
+  $impl.to = toProcess;
+  $impl.through = $impl.io = throughProcess;
+
+  // shell functions
+
+  const shell = bqShell(shellEscape, (command, options) =>
+    spawn(buildShellCommand(options?.shellPath, options?.shellArgs, command), {
+      ...options,
+      windowsVerbatimArguments: true
+    })
+  );
+
+  const $sh = bqShell(shellEscape, (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), {
+      ...options,
+      stdout: 'pipe',
+      windowsVerbatimArguments: true
+    });
+    return sp.stdout;
+  });
+
+  const toShell = bqShell(shellEscape, (command, options) => {
+    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), {
+      ...options,
+      stdin: 'pipe',
+      stdout: 'pipe',
+      windowsVerbatimArguments: true
+    });
+    return sp.asDuplex;
+  });
+
+  const $shImpl = /** @type {import('./index.d.ts').ShellImpl} */ ($sh);
+  $shImpl.from = fromShell;
+  $shImpl.to = toShell;
+  $shImpl.through = $shImpl.io = throughShell;
+
+  return {
+    spawn,
+    cwd,
+    currentExecPath,
+    runFileArgs,
+    shellEscape,
+    currentShellPath,
+    buildShellCommand,
+    $$,
+    $,
+    shell,
+    sh: shell,
+    $sh
+  };
+};

package/src/index.d.ts

@@ -215,7 +215,7 @@ export interface DollarResult {
 /**
  * The type of the {@link $} function.
  */
-interface DollarImpl<R = any> extends Dollar<Promise<DollarResult>> {
+export interface DollarImpl<R = any> extends Dollar<Promise<DollarResult>> {
   /**
    * The tag function that can be used as a template string.
    * It can take an options object and return self with updated defaults.
@@ -297,7 +297,7 @@ export declare const sh: typeof shell;
 /**
  * The type of the $sh function.
  */
-interface ShellImpl<R = any> extends Dollar<Promise<DollarResult>, ShellOptions> {
+export interface ShellImpl<R = any> extends Dollar<Promise<DollarResult>, ShellOptions> {
   /**
    * The tag function that can be used as a template string.
    * It can take an options object and return self with updated defaults.

package/src/index.js

@@ -2,109 +2,73 @@
 
 // load dependencies
 
-import {isWindows, raw, winCmdEscape} from './utils.js';
-
-import bqSpawn from './bq-spawn.js';
-import bqShell from './bq-shell.js';
-
-export {isWindows, raw, winCmdEscape};
-
-let modSpawn;
+import {getEnv} from './utils.js';
+
+import {buildApi} from './build.js';
+
+export {isWindows, raw, winCmdEscape} from './utils.js';
+
+// Force the Node backend on every runtime with the `DSH_FORCE_NODE` environment
+// variable (e.g. DSH_FORCE_NODE=1) — Bun/Deno then run on their Node compat (e.g. to
+// sidestep Bun's Web-Stream child-pipe tail-drop). The env var is inherited by spawned
+// children; to force only this process, set `globalThis.DSH_FORCE_NODE` before a dynamic
+// import instead. Treated as off: unset, '', '0', 'false'.
+const isFlagOn = value =>
+  value != null &&
+  value !== '' &&
+  value !== '0' &&
+  value !== 0 &&
+  String(value).toLowerCase() !== 'false';
+
+const envForceNode = () => {
+  if (typeof Deno !== 'undefined') {
+    const status = Deno.permissions?.querySync?.({name: 'env', variable: 'DSH_FORCE_NODE'});
+    if (status && status.state !== 'granted') return undefined;
+  }
+  try {
+    return getEnv('DSH_FORCE_NODE');
+  } catch {
+    return undefined;
+  }
+};
+
+const forceNode =
+  isFlagOn(/** @type {any} */ (globalThis).DSH_FORCE_NODE) || isFlagOn(envForceNode());
+
+// The runtime-native backend defines how to launch *this* runtime — `currentExecPath`,
+// `runFileArgs`, `cwd`. DSH_FORCE_NODE forces only the spawn *implementation*
+// (`node:child_process`); it must not change which runtime we target or how it is
+// invoked, so a forced child of Bun/Deno is still `bun run …` / `deno run …`, never a
+// bare `node`. (`process.execPath` is already the real runtime under Bun/Deno node
+// compat; `runFileArgs` is what actually differs — `[]` for node vs `['run']`.)
+let modRuntime;
 if (typeof Deno !== 'undefined') {
-  modSpawn = await import('./spawn/deno.js');
+  modRuntime = await import('./spawn/deno.js');
 } else if (typeof Bun !== 'undefined') {
-  modSpawn = await import('./spawn/bun.js');
+  modRuntime = await import('./spawn/bun.js');
 } else {
-  modSpawn = await import('./spawn/node.js');
+  modRuntime = await import('./spawn/node.js');
 }
-export const {spawn, cwd, currentExecPath, runFileArgs} = modSpawn;
-
-let modShell;
-if (isWindows) {
-  modShell = await import('./shell/windows.js');
-} else {
-  modShell = await import('./shell/unix.js');
-}
-export const {shellEscape, currentShellPath, buildShellCommand} = modShell;
-
-// define spawn functions
-
-export const $$ = bqSpawn(spawn);
-
-export const $ = bqSpawn((command, options) => {
-  const sp = spawn(command, options);
-  return sp.exited.then(() => ({code: sp.exitCode, signal: sp.signalCode, killed: sp.killed}));
-});
-
-const fromProcess = bqSpawn((command, options) => {
-  const sp = spawn(command, {...options, stdout: 'pipe'});
-  return sp.stdout;
+const modSpawn = forceNode ? await import('./spawn/node.js') : modRuntime;
+
+export const {
+  spawn,
+  cwd,
+  currentExecPath,
+  runFileArgs,
+  shellEscape,
+  currentShellPath,
+  buildShellCommand,
+  $$,
+  $,
+  shell,
+  sh,
+  $sh
+} = await buildApi({
+  spawn: modSpawn.spawn,
+  cwd: modRuntime.cwd,
+  currentExecPath: modRuntime.currentExecPath,
+  runFileArgs: modRuntime.runFileArgs
 });
 
-const toProcess = bqSpawn((command, options) => {
-  const sp = spawn(command, {...options, stdin: 'pipe'});
-  return sp.stdin;
-});
-
-const throughProcess = bqSpawn((command, options) => {
-  const sp = spawn(command, {...options, stdin: 'pipe', stdout: 'pipe'});
-  return sp.asDuplex;
-});
-
-const $any = /** @type {any} */ ($);
-$any.from = fromProcess;
-$any.to = toProcess;
-$any.through = $any.io = throughProcess;
-
-// define shell functions
-
-export const shell = bqShell(shellEscape, (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,
-    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), {
-    ...options,
-    stdout: 'pipe',
-    windowsVerbatimArguments: true
-  });
-  return sp.stdout;
-});
-
-const toShell = bqShell(shellEscape, (command, options) => {
-  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), {
-    ...options,
-    stdin: 'pipe',
-    stdout: 'pipe',
-    windowsVerbatimArguments: true
-  });
-  return sp.asDuplex;
-});
-
-const $shAny = /** @type {any} */ ($sh);
-$shAny.from = fromShell;
-$shAny.to = toShell;
-$shAny.through = $shAny.io = throughShell;
-
 export default $;

package/src/node/index.d.ts

@@ -0,0 +1,172 @@
+/// <reference types="node" />
+import type {Readable, Writable, Duplex} from 'node:stream';
+import type {
+  SpawnStreamState,
+  SpawnOptions,
+  ShellEscapeOptions,
+  DollarResult,
+  ShellOptions
+} from '../index.js';
+
+// The stream-free half of the public API is identical to the main entry — reuse it verbatim.
+export type {SpawnStreamState, SpawnOptions, ShellEscapeOptions, DollarResult, ShellOptions};
+export {
+  cwd,
+  currentExecPath,
+  runFileArgs,
+  isWindows,
+  raw,
+  winCmdEscape,
+  shellEscape,
+  currentShellPath,
+  buildShellCommand
+} from '../index.js';
+
+/**
+ * Sub-process object. Identical to the main entry's `Subprocess`, except the standard
+ * streams are Node streams ([`Readable`]/[`Writable`]) instead of Web streams.
+ */
+export interface Subprocess {
+  /**
+   * The raw command that was run as an array of strings.
+   */
+  readonly command: string[];
+  /**
+   * The options that were passed to `spawn()`.
+   */
+  readonly options: SpawnOptions | undefined;
+  /**
+   * The promise that will be resolved with the exit code when the process exits.
+   */
+  readonly exited: Promise<number>;
+  /**
+   * Whether the process has finished running.
+   */
+  readonly finished: boolean;
+  /**
+   * Whether the process was killed when finished.
+   */
+  readonly killed: boolean;
+  /**
+   * The exit code of the process when it was finished.
+   */
+  readonly exitCode: number | null;
+  /**
+   * The signal code of the process when it was finished.
+   */
+  readonly signalCode: string | null;
+  /**
+   * The standard input stream as a Node `Writable`.
+   * It is `null` if `options.stdin` was not set to `'pipe'`.
+   */
+  readonly stdin: Writable | null;
+  /**
+   * The standard output stream as a Node `Readable`.
+   * It is `null` if `options.stdout` was not set to `'pipe'`.
+   */
+  readonly stdout: Readable | null;
+  /**
+   * The standard error stream as a Node `Readable`.
+   * It is `null` if `options.stderr` was not set to `'pipe'`.
+   */
+  readonly stderr: Readable | null;
+  /**
+   * The process as a Node `Duplex` stream: writes go to `stdin`, reads come from `stdout`.
+   * Built lazily on first access (and cached). Requires both `stdin` and `stdout` piped.
+   */
+  readonly asDuplex: Duplex;
+  /**
+   * Kill the process.
+   */
+  kill(): void;
+}
+
+/**
+ * Spawn a process with advanced ways to configure and control it.
+ */
+export declare function spawn(command: string[], options?: SpawnOptions): Subprocess;
+
+/**
+ * Backticks (tag) function.
+ */
+type Backticks<R> = (strings: TemplateStringsArray, ...args: unknown[]) => R;
+
+/**
+ * The type of the $ (tag) function. It can be used as a tag function for a template string,
+ * or it can take an options object and return self with updated defaults.
+ */
+interface Dollar<R, O = SpawnOptions> extends Backticks<R> {
+  (options: O): Dollar<R, O>;
+}
+
+/**
+ * `$$` (tag) function: spawns a process and returns a {@link Subprocess}.
+ */
+export declare const $$: Dollar<Subprocess>;
+
+/**
+ * The type of the {@link $} function.
+ */
+export interface DollarImpl extends Dollar<Promise<DollarResult>> {
+  /**
+   * Returns the `stdout` of the process as a Node `Readable`.
+   */
+  from: Dollar<Readable>;
+  /**
+   * Returns the `stdin` of the process as a Node `Writable`.
+   */
+  to: Dollar<Writable>;
+  /**
+   * Returns the process as a Node `Duplex` stream. Alias of `io`.
+   */
+  through: Dollar<Duplex>;
+  /**
+   * Returns the process as a Node `Duplex` stream. Alias of `through`.
+   */
+  io: Dollar<Duplex>;
+}
+
+/**
+ * The `$` function with custom properties (`from`, `to`, `through`, `io`). Used as a tag
+ * function it spawns a process and resolves to a simplified result. It is the default export.
+ */
+export declare const $: DollarImpl;
+
+/**
+ * The shell tag function: runs a command through a shell and returns a {@link Subprocess}.
+ */
+export declare const shell: Dollar<Subprocess, ShellOptions>;
+/**
+ * An alias of `shell`.
+ */
+export declare const sh: typeof shell;
+
+/**
+ * The type of the `$sh` function.
+ */
+export interface ShellImpl extends Dollar<Promise<DollarResult>, ShellOptions> {
+  /**
+   * Returns the `stdout` of the shell process as a Node `Readable`.
+   */
+  from: Dollar<Readable, ShellOptions>;
+  /**
+   * Returns the `stdin` of the shell process as a Node `Writable`.
+   */
+  to: Dollar<Writable, ShellOptions>;
+  /**
+   * Returns the shell process as a Node `Duplex` stream. Alias of `io`.
+   */
+  through: Dollar<Duplex, ShellOptions>;
+  /**
+   * Returns the shell process as a Node `Duplex` stream. Alias of `through`.
+   */
+  io: Dollar<Duplex, ShellOptions>;
+}
+
+/**
+ * The `$sh` function with custom properties (`from`, `to`, `through`, `io`). Used as a tag
+ * function it runs a shell command and resolves to a simplified result.
+ */
+export declare const $sh: ShellImpl;
+
+export default $;

package/src/node/index.js

@@ -0,0 +1,45 @@
+// @ts-self-types="./index.d.ts"
+
+// The Node-streams facade: identical API to the main entry, but stdin/stdout/stderr
+// (and .from/.to/.through/.io/asDuplex) are Node streams instead of Web streams.
+// Spawning always goes through node:child_process (on Bun/Deno via their node compat) —
+// that is the point of this entry. But, like DSH_FORCE_NODE on the main entry, this must
+// affect only the spawn implementation: `currentExecPath` / `runFileArgs` / `cwd` stay
+// runtime-native, so a child of Bun/Deno is still launched as `bun run …` / `deno run …`,
+// never a bare `node`.
+
+import {buildApi} from '../build.js';
+import * as backend from '../spawn/node.js';
+
+export {isWindows, raw, winCmdEscape} from '../utils.js';
+
+let modRuntime;
+if (typeof Deno !== 'undefined') {
+  modRuntime = await import('../spawn/deno.js');
+} else if (typeof Bun !== 'undefined') {
+  modRuntime = await import('../spawn/bun.js');
+} else {
+  modRuntime = backend;
+}
+
+export const {
+  spawn,
+  cwd,
+  currentExecPath,
+  runFileArgs,
+  shellEscape,
+  currentShellPath,
+  buildShellCommand,
+  $$,
+  $,
+  shell,
+  sh,
+  $sh
+} = await buildApi({
+  spawn: backend.nodeStreamSpawn,
+  cwd: modRuntime.cwd,
+  currentExecPath: modRuntime.currentExecPath,
+  runFileArgs: modRuntime.runFileArgs
+});
+
+export default $;

package/src/spawn/node.js

@@ -1,5 +1,5 @@
 import {spawn} from 'node:child_process';
-import {Readable, Writable} from 'node:stream';
+import {Readable, Writable, Duplex} from 'node:stream';
 
 const setStdio = (stdio, fd, value) => {
   switch (value) {
@@ -18,7 +18,10 @@ const setStdio = (stdio, fd, value) => {
 };
 
 class Subprocess {
-  constructor(command, options) {
+  #nodeStreams;
+  #asDuplex;
+
+  constructor(command, options, nodeStreams) {
     this.command = command;
     this.options = options;
 
@@ -67,13 +70,28 @@ class Subprocess {
       this.reject(error);
     });
 
-    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);
+    this.#nodeStreams = nodeStreams;
+    if (nodeStreams) {
+      this.stdin = this.childProcess.stdin || null;
+      this.stdout = this.childProcess.stdout || null;
+      this.stderr = this.childProcess.stderr || null;
+    } else {
+      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);
+    }
   }
 
   get asDuplex() {
-    return {readable: this.stdout, writable: this.stdin};
+    // Web-streams mode keeps the `{readable, writable}` pair (the pipeThrough shape).
+    // Node-streams mode returns a real Node `Duplex` (built lazily, once) so the process
+    // drops straight into `.pipe()` chains and `stream.pipeline()`.
+    if (!this.#nodeStreams) return {readable: this.stdout, writable: this.stdin};
+    // `@types/node` types `Duplex.from({readable, writable})` for Web streams only,
+    // but at runtime it accepts a Node readable + writable just fine.
+    return (this.#asDuplex ??= Duplex.from(
+      /** @type {any} */ ({readable: this.stdout, writable: this.stdin})
+    ));
   }
 
   kill() {
@@ -88,4 +106,7 @@ export const runFileArgs = [];
 export const cwd = () => process.cwd();
 
 const nodeSpawn = (command, options = {}) => new Subprocess(command, options);
-export {nodeSpawn as spawn};
+// Variant that keeps raw Node streams (no Web Streams conversion) — backs the
+// `dollar-shell/node` facade. Internal: reached only through that entry.
+const nodeStreamSpawn = (command, options = {}) => new Subprocess(command, options, true);
+export {nodeSpawn as spawn, nodeStreamSpawn};

package/src/utils.js

@@ -33,6 +33,9 @@ export const raw = value => ({[rawValueSymbol]: value});
 export const isRawValue = value => value && typeof value === 'object' && rawValueSymbol in value;
 export const getRawValue = value => value[rawValueSymbol];
 
+export const bqTagSymbol = Symbol.for('dollar-shell.bq-tag');
+export const isBqTag = value => typeof value === 'function' && value[bqTagSymbol] === true;
+
 export const winCmdEscape = isWindows
   ? value => raw(String(value).replace(/./g, '^$&'))
   : value => String(value);

package/AGENTS.md

@@ -1,99 +0,0 @@
-# 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`, validates the `.d.ts` sidecars)
-- **JavaScript check:** `npm run js-check` (`tsc --project tsconfig.check.json`, lints the `.js` sources for unused vars / undeclared refs)
-- **TypeScript tests:** `npm run ts-test` (run `.ts` test files with tape6)
-- **Lint:** `npm run lint` (Prettier check)
-- **Lint fix:** `npm run lint:fix` (Prettier write)
-
-## Project structure
-
-```
-dollar-shell/
-├── package.json          # Package config
-├── tsconfig.json         # Strict TS config — checks the .d.ts sidecars
-├── tsconfig.check.json   # Lint config — checkJs on .js sources, with @types/{node,bun,deno} for cross-runtime globals
-├── 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): .js, .cjs, .ts
-├── tests/manual/     # Manual verification scripts
-└── 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 runtime dependencies — the library is intentionally zero-dependency. DevDeps for tooling (`@types/node`, `@types/bun`, `@types/deno`, `prettier`, `tape-six`, `typescript`) are fine.
-- 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. Cross-runtime behavior asymmetries (e.g. BYOB readers — only Deno supports them) are documented at `wiki/Cross-runtime-notes.md`.
-- Tests are in `tests/` (automated, tape-six) and `tests/manual/` (manual verification scripts).
-- TypeScript typing tests (`.ts`) are in `tests/` and checked by `npm run ts-check`. They can also be run as tests via `npm run ts-test`.

package/CLAUDE.md

@@ -1,3 +0,0 @@
-<!-- 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

@@ -1,34 +0,0 @@
-# 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.