command-stream 0.4.0 → 0.6.0

package/README.md

@@ -1,5 +1,6 @@
 [![npm](https://img.shields.io/npm/v/command-stream.svg)](https://npmjs.com/command-stream)
 [![License](https://img.shields.io/badge/license-Unlicense-blue.svg)](https://github.com/link-foundation/command-stream/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/link-foundation/command-stream?style=social)](https://github.com/link-foundation/command-stream/stargazers)
 
 [![Open in Gitpod](https://img.shields.io/badge/Gitpod-ready--to--code-f29718?logo=gitpod)](https://gitpod.io/#https://github.com/link-foundation/command-stream)
 [![Open in GitHub Codespaces](https://img.shields.io/badge/GitHub%20Codespaces-Open-181717?logo=github)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=link-foundation/command-stream)
@@ -26,39 +27,48 @@ A modern $ shell utility library with streaming, async iteration, and EventEmitt
 
 ## Comparison with Other Libraries
 
-| Feature | [command-stream](https://github.com/link-foundation/command-stream) | [Bun.$](https://bun.sh/docs/runtime/shell) | [execa](https://github.com/sindresorhus/execa) | [zx](https://github.com/google/zx) | [ShellJS](https://github.com/shelljs/shelljs) | [cross-spawn](https://github.com/moxystudio/node-cross-spawn) |
+| Feature | [**command-stream**](https://github.com/link-foundation/command-stream) | [**execa**](https://github.com/sindresorhus/execa) | [**cross-spawn**](https://github.com/moxystudio/node-cross-spawn) | [**Bun.$**](https://github.com/oven-sh/bun) | [**ShellJS**](https://github.com/shelljs/shelljs) | [**zx**](https://github.com/google/zx) |
 |---------|----------------|-------|-------|-----|-------|-------|
-| **Runtime Support** | ✅ Bun + Node.js | 🟡 Bun only | ✅ Node.js | ✅ Node.js | ✅ Node.js | ✅ Node.js |
-| **Template Literals** | ✅ `` $`cmd` `` | ✅ `` $`cmd` `` | ✅ `` $`cmd` `` | ✅ `` $`cmd` `` | ❌ Function calls | ❌ Function calls |
-| **Real-time Streaming** | ✅ Live output | ❌ Buffer only | 🟡 Limited | ❌ Buffer only | ❌ Buffer only | ❌ Buffer only |
-| **Synchronous Execution** | ✅ `.sync()` with events | ❌ No | ✅ `execaSync` | ❌ No | ✅ Sync by default | ✅ `spawnSync` |
+| **📦 NPM Package** | [![npm](https://img.shields.io/npm/v/command-stream.svg)](https://www.npmjs.com/package/command-stream) | [![npm](https://img.shields.io/npm/v/execa.svg)](https://www.npmjs.com/package/execa) | [![npm](https://img.shields.io/npm/v/cross-spawn.svg)](https://www.npmjs.com/package/cross-spawn) | N/A (Built-in) | [![npm](https://img.shields.io/npm/v/shelljs.svg)](https://www.npmjs.com/package/shelljs) | [![npm](https://img.shields.io/npm/v/zx.svg)](https://www.npmjs.com/package/zx) |
+| **⭐ GitHub Stars** | [**⭐ 2** (Please ⭐ us!)](https://github.com/link-foundation/command-stream) | [⭐ 7,264](https://github.com/sindresorhus/execa) | [⭐ 1,149](https://github.com/moxystudio/node-cross-spawn) | [⭐ 80,169](https://github.com/oven-sh/bun) (Full Runtime) | [⭐ 14,375](https://github.com/shelljs/shelljs) | [⭐ 44,569](https://github.com/google/zx) |
+| **📊 Monthly Downloads** | **893** (New project!) | **381M** | **409M** | N/A (Built-in) | **35M** | **4.2M** |
+| **📈 Total Downloads** | **Growing** | **6B+** | **5.4B** | N/A (Built-in) | **596M** | **37M** |
+| **Runtime Support** | ✅ Bun + Node.js | ✅ Node.js | ✅ Node.js | 🟡 Bun only | ✅ Node.js | ✅ Node.js |
+| **Template Literals** | ✅ `` $`cmd` `` | ✅ `` $`cmd` `` | ❌ Function calls | ✅ `` $`cmd` `` | ❌ Function calls | ✅ `` $`cmd` `` |
+| **Real-time Streaming** | ✅ Live output | 🟡 Limited | ❌ Buffer only | ❌ Buffer only | ❌ Buffer only | ❌ Buffer only |
+| **Synchronous Execution** | ✅ `.sync()` with events | ✅ `execaSync` | ✅ `spawnSync` | ❌ No | ✅ Sync by default | ❌ No |
 | **Async Iteration** | ✅ `for await (chunk of $.stream())` | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No |
-| **EventEmitter Pattern** | ✅ `.on('data', ...)` | ❌ No | 🟡 Limited events | ❌ No | ❌ No | 🟡 Child process events |
+| **EventEmitter Pattern** | ✅ `.on('data', ...)` | 🟡 Limited events | 🟡 Child process events | ❌ No | ❌ No | ❌ No |
 | **Mixed Patterns** | ✅ Events + await/sync | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No |
-| **Bun.$ Compatibility** | ✅ `.text()` method support | ✅ Native API | ❌ No | ❌ No | ❌ No | ❌ No |
-| **Shell Injection Protection** | ✅ Auto-quoting | ✅ Built-in | ✅ Safe by default | ✅ Safe by default | 🟡 Manual escaping | ✅ Safe by default |
-| **Cross-platform** | ✅ macOS/Linux/Windows | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ✅ **Specialized** cross-platform |
-| **Performance** | ⚡ Fast (Bun optimized) | ⚡ Very fast | 🐌 Moderate | 🐌 Slow | 🐌 Moderate | ⚡ Fast |
+| **Bun.$ Compatibility** | ✅ `.text()` method support | ❌ No | ❌ No | ✅ Native API | ❌ No | ❌ No |
+| **Shell Injection Protection** | ✅ Smart auto-quoting | ✅ Safe by default | ✅ Safe by default | ✅ Built-in | 🟡 Manual escaping | ✅ Safe by default |
+| **Cross-platform** | ✅ macOS/Linux/Windows | ✅ Yes | ✅ **Specialized** cross-platform | ✅ Yes | ✅ Yes | ✅ Yes |
+| **Performance** | ⚡ Fast (Bun optimized) | 🐌 Moderate | ⚡ Fast | ⚡ Very fast | 🐌 Moderate | 🐌 Slow |
 | **Memory Efficiency** | ✅ Streaming prevents buildup | 🟡 Buffers in memory | 🟡 Buffers in memory | 🟡 Buffers in memory | 🟡 Buffers in memory | 🟡 Buffers in memory |
-| **Error Handling** | ✅ Configurable (`set -e`/`set +e`, non-zero OK by default) | ✅ Throws on error | ✅ Throws on error | ✅ Throws on error | ✅ Configurable | ❌ Basic (exit codes) |
+| **Error Handling** | ✅ Configurable (`set -e`/`set +e`, non-zero OK by default) | ✅ Throws on error | ❌ Basic (exit codes) | ✅ Throws on error | ✅ Configurable | ✅ Throws on error |
 | **Shell Settings** | ✅ `set -e`/`set +e` equivalent | ❌ No | ❌ No | ❌ No | 🟡 Limited (`set()`) | ❌ No |
-| **Stdout Support** | ✅ Real-time streaming + events | ✅ Shell redirection + buffered | ✅ Node.js streams + interleaved | ✅ Readable streams + `.pipe.stdout` | ✅ Direct output | ✅ Inherited/buffered |
-| **Stderr Support** | ✅ Real-time streaming + events | ✅ Redirection + `.quiet()` access | ✅ Streams + interleaved output | ✅ Readable streams + `.pipe.stderr` | ✅ Error output | ✅ Inherited/buffered |
-| **Stdin Support** | ✅ string/Buffer/inherit/ignore | ✅ Pipe operations | ✅ Input/output streams | ✅ Basic stdin | 🟡 Basic | ✅ Full stdio support |
-| **Built-in Commands** | ✅ **18 commands**: cat, ls, mkdir, rm, mv, cp, touch, basename, dirname, seq, yes + all Bun.$ commands | ✅ echo, cd, etc. | ❌ Uses system | ❌ Uses system | ✅ **20+ commands**: cat, ls, mkdir, rm, mv, cp, etc. | ❌ Uses system |
-| **Virtual Commands Engine** | ✅ **Revolutionary**: Register JavaScript functions as shell commands with full pipeline support | ❌ No extensibility | ❌ No custom commands | ❌ No custom commands | ❌ No custom commands | ❌ No custom commands |
-| **Pipeline/Piping Support** | ✅ **Advanced**: System + Built-ins + Virtual + Mixed + `.pipe()` method | ✅ Standard shell piping | ✅ Programmatic `.pipe()` + multi-destination | ✅ Shell piping + `.pipe()` method | ✅ Shell piping + `.to()` method | ❌ No piping |
-| **Bundle Size** | 📦 **~20KB gzipped** | 🎯 0KB (built-in) | 📦 ~400KB+ (packagephobia) | 📦 ~50KB+ (estimated) | 📦 ~15KB gzipped | 📦 ~2KB gzipped |
-| **Signal Handling** | ✅ **Advanced SIGINT/SIGTERM forwarding** with cleanup | 🟡 Basic | 🟡 Basic | 🟡 Basic | 🟡 Basic | ✅ **Excellent** cross-platform |
-| **Process Management** | ✅ **Robust child process lifecycle** with proper termination | ❌ Basic | ✅ Good | 🟡 Limited | 🟡 Limited | ✅ **Excellent** spawn wrapper |
-| **Debug Tracing** | ✅ **Comprehensive VERBOSE logging** for CI/debugging | ❌ No | 🟡 Limited | ❌ No | 🟡 Basic | ❌ No |
-| **Test Coverage** | ✅ **410 tests, 909 assertions** | 🟡 Good coverage | ✅ Excellent | 🟡 Good | ✅ Good | ✅ Good |
-| **CI Reliability** | ✅ **Platform-specific handling** (macOS/Ubuntu) | 🟡 Basic | ✅ Good | 🟡 Basic | ✅ Good | ✅ **Excellent** |
-| **Documentation** | ✅ **Comprehensive examples + guides** | ✅ Good | ✅ Excellent | 🟡 Limited | ✅ Good | 🟡 Basic |
-| **TypeScript** | 🔄 Coming soon | ✅ Built-in | ✅ Full support | ✅ Full support | 🟡 Community types | ✅ Built-in |
-| **License** | ✅ **Unlicense (Public Domain)** | 🟡 MIT (+ LGPL dependencies) | 🟡 MIT | 🟡 Apache 2.0 | 🟡 BSD-3-Clause | 🟡 MIT |
-
-**📊 Popularity (Weekly Downloads 2024):** [cross-spawn](https://www.npmjs.com/package/cross-spawn): 102M+ • [execa](https://www.npmjs.com/package/execa): 98M+ • [ShellJS](https://www.npmjs.com/package/shelljs): 9M+ • [zx](https://www.npmjs.com/package/zx): Growing fast
+| **Stdout Support** | ✅ Real-time streaming + events | ✅ Node.js streams + interleaved | ✅ Inherited/buffered | ✅ Shell redirection + buffered | ✅ Direct output | ✅ Readable streams + `.pipe.stdout` |
+| **Stderr Support** | ✅ Real-time streaming + events | ✅ Streams + interleaved output | ✅ Inherited/buffered | ✅ Redirection + `.quiet()` access | ✅ Error output | ✅ Readable streams + `.pipe.stderr` |
+| **Stdin Support** | ✅ string/Buffer/inherit/ignore | ✅ Input/output streams | ✅ Full stdio support | ✅ Pipe operations | 🟡 Basic | ✅ Basic stdin |
+| **Built-in Commands** | ✅ **18 commands**: cat, ls, mkdir, rm, mv, cp, touch, basename, dirname, seq, yes + all Bun.$ commands | ❌ Uses system | ❌ Uses system | ✅ echo, cd, etc. | ✅ **20+ commands**: cat, ls, mkdir, rm, mv, cp, etc. | ❌ Uses system |
+| **Virtual Commands Engine** | ✅ **Revolutionary**: Register JavaScript functions as shell commands with full pipeline support | ❌ No custom commands | ❌ No custom commands | ❌ No extensibility | ❌ No custom commands | ❌ No custom commands |
+| **Pipeline/Piping Support** | ✅ **Advanced**: System + Built-ins + Virtual + Mixed + `.pipe()` method | ✅ Programmatic `.pipe()` + multi-destination | ❌ No piping | ✅ Standard shell piping | ✅ Shell piping + `.to()` method | ✅ Shell piping + `.pipe()` method |
+| **Bundle Size** | 📦 **~20KB gzipped** | 📦 ~400KB+ (packagephobia) | 📦 ~2KB gzipped | 🎯 0KB (built-in) | 📦 ~15KB gzipped | 📦 ~50KB+ (estimated) |
+| **Signal Handling** | ✅ **Advanced SIGINT/SIGTERM forwarding** with cleanup | 🟡 Basic | ✅ **Excellent** cross-platform | 🟡 Basic | 🟡 Basic | 🟡 Basic |
+| **Process Management** | ✅ **Robust child process lifecycle** with proper termination | ✅ Good | ✅ **Excellent** spawn wrapper | ❌ Basic | 🟡 Limited | 🟡 Limited |
+| **Debug Tracing** | ✅ **Comprehensive VERBOSE logging** for CI/debugging | 🟡 Limited | ❌ No | ❌ No | 🟡 Basic | ❌ No |
+| **Test Coverage** | ✅ **518+ tests, 1165+ assertions** | ✅ Excellent | ✅ Good | 🟡 Good coverage | ✅ Good | 🟡 Good |
+| **CI Reliability** | ✅ **Platform-specific handling** (macOS/Ubuntu) | ✅ Good | ✅ **Excellent** | 🟡 Basic | ✅ Good | 🟡 Basic |
+| **Documentation** | ✅ **Comprehensive examples + guides** | ✅ Excellent | 🟡 Basic | ✅ Good | ✅ Good | 🟡 Limited |
+| **TypeScript** | 🔄 Coming soon | ✅ Full support | ✅ Built-in | ✅ Built-in | 🟡 Community types | ✅ Full support |
+| **License** | ✅ **Unlicense (Public Domain)** | 🟡 MIT | 🟡 MIT | 🟡 MIT (+ LGPL dependencies) | 🟡 BSD-3-Clause | 🟡 Apache 2.0 |
+
+**📊 Popularity & Adoption:** 
+- **⭐ GitHub Stars:** [Bun: 80,169](https://github.com/oven-sh/bun) • [zx: 44,569](https://github.com/google/zx) • [ShellJS: 14,375](https://github.com/shelljs/shelljs) • [execa: 7,264](https://github.com/sindresorhus/execa) • [cross-spawn: 1,149](https://github.com/moxystudio/node-cross-spawn) • [**command-stream: 2 ⭐ us!**](https://github.com/link-foundation/command-stream)
+- **📈 Total Downloads:** [execa: 6B+](https://www.npmjs.com/package/execa) • [cross-spawn: 5.4B](https://www.npmjs.com/package/cross-spawn) • [ShellJS: 596M](https://www.npmjs.com/package/shelljs) • [zx: 37M](https://www.npmjs.com/package/zx) • [command-stream: Growing](https://www.npmjs.com/package/command-stream)
+- **📊 Monthly Downloads:** [cross-spawn: 409M](https://www.npmjs.com/package/cross-spawn) • [execa: 381M](https://www.npmjs.com/package/execa) • [ShellJS: 35M](https://www.npmjs.com/package/shelljs) • [zx: 4.2M](https://www.npmjs.com/package/zx) • [command-stream: 893 (growing!)](https://www.npmjs.com/package/command-stream)
+
+**⭐ Help Us Grow!** If command-stream's **revolutionary virtual commands** and **advanced streaming capabilities** help your project, [**please star us on GitHub**](https://github.com/link-foundation/command-stream) to help the project grow!
 
 ### Why Choose command-stream?
 
@@ -71,7 +81,7 @@ A modern $ shell utility library with streaming, async iteration, and EventEmitt
 - **🐚 Shell Replacement**: Dynamic error handling with `set -e`/`set +e` equivalents for .sh file replacement
 - **⚡ Bun Optimized**: Designed for Bun with Node.js fallback compatibility  
 - **💾 Memory Efficient**: Streaming prevents large buffer accumulation
-- **🛡️ Production Ready**: **410 tests, 909 assertions** with comprehensive coverage including CI reliability
+- **🛡️ Production Ready**: **518+ tests, 1165+ assertions** with comprehensive coverage including CI reliability
 - **🎯 Advanced Signal Handling**: Robust SIGINT/SIGTERM forwarding with proper child process cleanup
 - **🔍 Debug-Friendly**: Comprehensive VERBOSE tracing for CI debugging and troubleshooting
 
@@ -141,6 +151,54 @@ npm install command-stream
 bun add command-stream
 ```
 
+## Smart Quoting & Security
+
+Command-stream provides intelligent auto-quoting to protect against shell injection while avoiding unnecessary quotes for safe strings:
+
+### Smart Quoting Behavior
+
+```javascript
+import { $ } from 'command-stream';
+
+// Safe strings are NOT quoted (performance optimization)
+await $`echo ${name}`;           // name = "hello" → echo hello
+await $`${cmd} --version`;       // cmd = "/usr/bin/node" → /usr/bin/node --version
+
+// Dangerous strings are automatically quoted for safety
+await $`echo ${userInput}`;      // userInput = "test; rm -rf /" → echo 'test; rm -rf /'
+await $`echo ${pathWithSpaces}`; // pathWithSpaces = "/my path/file" → echo '/my path/file'
+
+// Special characters that trigger auto-quoting:
+// Spaces, $, ;, |, &, >, <, `, *, ?, [, ], {, }, (, ), !, #, and others
+
+// User-provided quotes are preserved
+const quotedPath = "'/path with spaces/file'";
+await $`cat ${quotedPath}`;      // → cat '/path with spaces/file' (no double-quoting!)
+
+const doubleQuoted = '"/path with spaces/file"';
+await $`cat ${doubleQuoted}`;    // → cat '"/path with spaces/file"' (preserves intent)
+```
+
+### Shell Injection Protection
+
+All interpolated values are automatically secured:
+
+```javascript
+// ✅ SAFE - All these injection attempts are neutralized
+const dangerous = "'; rm -rf /; echo '";
+await $`echo ${dangerous}`;      // → echo ''\'' rm -rf /; echo '\'''
+
+const cmdSubstitution = "$(whoami)";
+await $`echo ${cmdSubstitution}`; // → echo '$(whoami)' (literal text, not executed)
+
+const varExpansion = "$HOME";
+await $`echo ${varExpansion}`;   // → echo '$HOME' (literal text, not expanded)
+
+// ✅ SAFE - Even complex injection attempts
+const complex = "`cat /etc/passwd`";
+await $`echo ${complex}`;        // → echo '`cat /etc/passwd`' (literal text)
+```
+
 ## Usage Patterns
 
 ### Classic Await (Backward Compatible)
@@ -174,6 +232,11 @@ await $withEnv`printenv MY_VAR`; // Prints: value
 const $inTmp = $({ cwd: '/tmp' });
 await $inTmp`pwd`; // Prints: /tmp
 
+// Interactive mode for TTY commands (requires TTY environment)
+const $interactive = $({ interactive: true });
+await $interactive`vim myfile.txt`; // Full TTY access for editor
+await $interactive`less README.md`; // Proper pager interaction
+
 // Combine multiple options
 const $custom = $({
   stdin: 'test data',
@@ -291,6 +354,83 @@ syncCmd.on('end', result => {
 const syncResult = syncCmd.sync();
 ```
 
+### Streaming Interfaces
+
+Advanced streaming interfaces for fine-grained process control:
+
+```javascript
+import { $ } from 'command-stream';
+
+// 🎯 STDIN CONTROL: Send data to interactive commands (real-time)
+const grepCmd = $`grep "important"`;
+const stdin = await grepCmd.streams.stdin; // Available immediately
+
+stdin.write('ignore this line\n');
+stdin.write('important message\n');
+stdin.write('skip this too\n');
+stdin.end();
+
+const result = await grepCmd;
+console.log(result.stdout); // "important message\n"
+
+// 🔧 BINARY DATA: Access raw buffers (after command finishes)
+const cmd = $`echo "Hello World"`;
+const buffer = await cmd.buffers.stdout; // Complete snapshot
+console.log(buffer.length); // 12
+
+// 📝 TEXT DATA: Access as strings (after command finishes)
+const textCmd = $`echo "Hello World"`;
+const text = await textCmd.strings.stdout; // Complete snapshot
+console.log(text.trim()); // "Hello World"
+
+// ⚡ PROCESS CONTROL: Kill commands that ignore stdin
+const pingCmd = $`ping google.com`;
+
+// Some commands ignore stdin input
+const pingStdin = await pingCmd.streams.stdin;
+if (pingStdin) {
+  pingStdin.write('q\n'); // ping ignores this
+}
+
+// Use kill() for forceful termination
+setTimeout(() => pingCmd.kill(), 2000);
+const pingResult = await pingCmd;
+console.log('Ping stopped with code:', pingResult.code); // 143 (SIGTERM)
+
+// 🔄 MIXED STDOUT/STDERR: Handle both streams (complete snapshots)
+const mixedCmd = $`sh -c 'echo "out" && echo "err" >&2'`;
+const [stdout, stderr] = await Promise.all([
+  mixedCmd.strings.stdout, // Available after finish
+  mixedCmd.strings.stderr  // Available after finish
+]);
+console.log('Out:', stdout.trim()); // "out"  
+console.log('Err:', stderr.trim()); // "err"
+
+// 🏃‍♂️ AUTO-START: Streams auto-start processes when accessed
+const cmd = $`echo "test"`;
+console.log('Started?', cmd.started); // false
+
+const output = await cmd.streams.stdout; // Auto-starts, immediate access
+console.log('Started?', cmd.started); // true
+
+// 🔙 BACKWARD COMPATIBLE: Traditional await still works
+const traditional = await $`echo "still works"`;
+console.log(traditional.stdout); // "still works\n"
+```
+
+**Key Features:**
+- `command.streams.stdin/stdout/stderr` - Direct access to Node.js streams  
+- `command.buffers.stdin/stdout/stderr` - Binary data as Buffer objects
+- `command.strings.stdin/stdout/stderr` - Text data as strings
+- `command.kill()` - Forceful process termination
+- **Auto-start behavior:** Process starts only when accessing stream properties
+- **Perfect for:** Interactive commands (grep, sort, bc), data processing, real-time control
+- **Network commands (ping, wget) ignore stdin** → Use `kill()` method instead
+
+**🚀 Streams vs Buffers/Strings:**
+- **`streams.*`** - Available **immediately** when command starts, for real-time interaction
+- **`buffers.*` & `strings.*`** - Complete **snapshots** available only **after** command finishes
+
 ### Shell Replacement (.sh → .mjs)
 
 Replace bash scripts with JavaScript while keeping shell semantics:
@@ -367,7 +507,7 @@ Create custom commands that work seamlessly alongside built-ins:
 import { $, register, unregister, listCommands } from 'command-stream';
 
 // Register a custom command
-register('greet', async (args, stdin) => {
+register('greet', async ({ args, stdin }) => {
   const name = args[0] || 'World';
   return { stdout: `Hello, ${name}!\n`, code: 0 };
 });
@@ -377,7 +517,7 @@ await $`greet Alice`;                    // → "Hello, Alice!"
 await $`echo "Bob" | greet`;             // → "Hello, Bob!"
 
 // Streaming virtual commands with async generators
-register('countdown', async function* (args) {
+register('countdown', async function* ({ args }) {
   const start = parseInt(args[0] || 5);
   for (let i = start; i >= 0; i--) {
     yield `${i}\n`;
@@ -414,7 +554,7 @@ await execa('node', ['script.js']);  // execa: separate processes
 await $`node script.js`;             // zx: shell commands only
 
 // ✅ command-stream: JavaScript functions AS shell commands  
-register('deploy', async (args) => {
+register('deploy', async ({ args }) => {
   const env = args[0] || 'staging';
   await deployToEnvironment(env);
   return { stdout: `Deployed to ${env}!\n`, code: 0 };
@@ -450,11 +590,11 @@ await $`seq 1 5 | cat > numbers.txt`;
 await $`git log --oneline | head -n 5`;
 
 // 🚀 UNIQUE: Virtual command piping
-register('uppercase', async (args, stdin) => {
+register('uppercase', async ({ args, stdin }) => {
   return { stdout: stdin.toUpperCase(), code: 0 };
 });
 
-register('reverse', async (args, stdin) => {
+register('reverse', async ({ args, stdin }) => {
   return { stdout: stdin.split('').reverse().join(''), code: 0 };
 });
 
@@ -482,12 +622,12 @@ import { $, register } from 'command-stream';
 const result = await $`echo "hello"`.pipe($`echo "World: $(cat)"`);
 
 // 🌟 Virtual command chaining
-register('add-prefix', async (args, stdin) => {
+register('add-prefix', async ({ args, stdin }) => {
   const prefix = args[0] || 'PREFIX:';
   return { stdout: `${prefix} ${stdin.trim()}\n`, code: 0 };
 });
 
-register('add-suffix', async (args, stdin) => {
+register('add-suffix', async ({ args, stdin }) => {
   const suffix = args[0] || 'SUFFIX';
   return { stdout: `${stdin.trim()} ${suffix}\n`, code: 0 };
 });
@@ -512,7 +652,7 @@ try {
 }
 
 // ✅ Complex data processing
-register('json-parse', async (args, stdin) => {
+register('json-parse', async ({ args, stdin }) => {
   try {
     const data = JSON.parse(stdin);
     return { stdout: JSON.stringify(data, null, 2), code: 0 };
@@ -521,7 +661,7 @@ register('json-parse', async (args, stdin) => {
   }
 });
 
-register('extract-field', async (args, stdin) => {
+register('extract-field', async ({ args, stdin }) => {
   const field = args[0];
   try {
     const data = JSON.parse(stdin);
@@ -695,9 +835,10 @@ The enhanced `$` function returns a `ProcessRunner` instance that extends `Event
 
 ```javascript
 {
-  mirror: true,    // Live output to terminal (stdout→stdout, stderr→stderr)
-  capture: true,   // Capture output for programmatic access
-  stdin: 'inherit' // Inherit stdin from parent process
+  mirror: true,        // Live output to terminal (stdout→stdout, stderr→stderr)
+  capture: true,       // Capture output for programmatic access
+  stdin: 'inherit',    // Inherit stdin from parent process
+  interactive: false   // Explicitly request TTY forwarding for interactive commands
 }
 ```
 
@@ -705,6 +846,7 @@ The enhanced `$` function returns a `ProcessRunner` instance that extends `Event
 - `mirror: boolean` - Whether to pipe output to terminal in real-time
 - `capture: boolean` - Whether to capture output in result object
 - `stdin: 'inherit' | 'ignore' | string | Buffer` - How to handle stdin
+- `interactive: boolean` - Enable TTY forwarding for interactive commands (requires `stdin: 'inherit'` and TTY environment)
 - `cwd: string` - Working directory for command
 - `env: object` - Environment variables
 
@@ -778,9 +920,9 @@ Control and extend the command system with custom JavaScript functions:
 import { $, register } from 'command-stream';
 
 // ✅ Cancellation support with AbortController
-register('cancellable', async function* (args, stdin, options) {
+register('cancellable', async function* ({ args, stdin, abortSignal }) {
   for (let i = 0; i < 10; i++) {
-    if (options.signal?.aborted) {
+    if (abortSignal?.aborted) {
       break; // Proper cancellation handling
     }
     yield `Count: ${i}\n`;
@@ -789,22 +931,28 @@ register('cancellable', async function* (args, stdin, options) {
 });
 
 // ✅ Access to all process options
-register('debug-info', async (args, stdin, options) => {
+// All original options (built-in + custom) are available in the 'options' object
+// Common options like cwd, env are also available at top level for convenience
+// Runtime additions: isCancelled function, abortSignal
+register('debug-info', async ({ args, stdin, cwd, env, options, isCancelled }) => {
   return {
     stdout: JSON.stringify({
       args,
-      cwd: options.cwd,
-      env: Object.keys(options.env || {}),
-      stdinLength: stdin.length,
-      mirror: options.mirror,
-      capture: options.capture
+      cwd,  // Available at top level for convenience
+      env: Object.keys(env || {}),  // Available at top level for convenience
+      stdinLength: stdin?.length || 0,
+      allOptions: options,  // All original options (built-in + custom)
+      mirror: options.mirror,  // Built-in option from options object
+      capture: options.capture,  // Built-in option from options object
+      customOption: options.customOption || 'not provided',  // Custom option
+      isCancelledAvailable: typeof isCancelled === 'function'
     }, null, 2),
     code: 0
   };
 });
 
 // ✅ Error handling and non-zero exit codes
-register('maybe-fail', async (args) => {
+register('maybe-fail', async ({ args }) => {
   if (Math.random() > 0.5) {
     return {
       stdout: 'Success!\n',
@@ -818,13 +966,27 @@ register('maybe-fail', async (args) => {
     };
   }
 });
+
+// ✅ Example: User options flow through to virtual commands
+register('show-options', async ({ args, stdin, options, cwd }) => {
+  return {
+    stdout: `Custom: ${options.customValue || 'none'}, CWD: ${cwd || options.cwd || 'default'}\n`,
+    code: 0
+  };
+});
+
+// Usage example showing options passed to virtual command:
+const result = await $({ customValue: 'hello world', cwd: '/tmp' })`show-options`;
+console.log(result.stdout); // Output: Custom: hello world, CWD: /tmp
 ```
 
 #### Handler Function Signature
 
 ```javascript
 // Regular async function
-async function handler(args, stdin, options) {
+async function handler({ args, stdin, abortSignal, cwd, env, options, isCancelled }) {
+  // All original options available in 'options': options.mirror, options.capture, options.customValue, etc.
+  // Common options like cwd, env also available at top level for convenience
   return {
     code: 0,           // Exit code (number)
     stdout: "output",  // Standard output (string)
@@ -833,10 +995,13 @@ async function handler(args, stdin, options) {
 }
 
 // Async generator for streaming
-async function* streamingHandler(args, stdin, options) {
+async function streamingHandler({ args, stdin, abortSignal, cwd, env, options, isCancelled }) {
+  // Access both built-in and custom options from 'options' object
+  if (options.customFlag) {
+    yield "custom behavior\n";
+  }
   yield "chunk1\n";
   yield "chunk2\n";
-  // Each yield sends a chunk in real-time
 }
 ```
 
@@ -973,7 +1138,7 @@ try {
 
 - **🎯 Smart Detection**: Only forwards CTRL+C when child processes are active
 - **🛡️ Non-Interference**: Preserves user SIGINT handlers when no children running  
-- **⚡ Interactive Commands**: Commands like `vim`, `less`, `top` work with their own signal handling
+- **⚡ Interactive Commands**: Use `interactive: true` option for commands like `vim`, `less`, `top` to enable proper TTY forwarding and signal handling
 - **🔄 Process Groups**: Detached spawning ensures proper signal isolation
 - **🧹 TTY Cleanup**: Raw terminal mode properly restored on interruption
 - **📊 Standard Exit Codes**: 
@@ -1066,7 +1231,7 @@ $`npm install`
 ## Testing
 
 ```bash
-# Run comprehensive test suite (270+ tests)
+# Run comprehensive test suite (518+ tests)
 bun test
 
 # Run tests with coverage report
@@ -1117,7 +1282,7 @@ bun test  # Run the full test suite
 
 ### 🧪 **Running Tests**
 ```bash
-bun test                    # All 266 tests
+bun test                    # All 518+ tests
 bun test tests/pipe.test.mjs # Specific test file
 npm run test:builtin        # Built-in commands only
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "command-stream",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Modern $ shell utility library with streaming, async iteration, and EventEmitter support, optimized for Bun runtime",
   "type": "module",
   "main": "src/$.mjs",

package/src/$.mjs

@@ -12,13 +12,6 @@ const isBun = typeof globalThis.Bun !== 'undefined';
 
 const VERBOSE = process.env.COMMAND_STREAM_VERBOSE === 'true' || process.env.CI === 'true';
 
-// Interactive commands that need TTY forwarding by default
-const INTERACTIVE_COMMANDS = new Set([
-  'top', 'htop', 'btop', 'less', 'more', 'vi', 'vim', 'nano', 'emacs',
-  'man', 'pager', 'watch', 'tmux', 'screen', 'ssh', 'ftp', 'sftp',
-  'mysql', 'psql', 'redis-cli', 'mongo', 'sqlite3', 'irb', 'python',
-  'node', 'repl', 'gdb', 'lldb', 'bc', 'dc', 'ed'
-]);
 
 // Trace function for verbose logging
 function trace(category, messageOrFunc) {
@@ -28,24 +21,6 @@ function trace(category, messageOrFunc) {
   console.error(`[TRACE ${timestamp}] [${category}] ${message}`);
 }
 
-// Check if a command is interactive and needs TTY forwarding
-function isInteractiveCommand(command) {
-  if (!command || typeof command !== 'string') return false;
-  
-  // Extract command and arguments from shell command string
-  const parts = command.trim().split(/\s+/);
-  const commandName = parts[0];
-  const baseName = path.basename(commandName);
-  
-  // Special handling for commands that are only interactive when run without arguments/scripts
-  if (baseName === 'node' || baseName === 'python' || baseName === 'python3') {
-    // These are only interactive when run without a script file
-    // If there are additional arguments (like a script file), they're not interactive
-    return parts.length === 1;
-  }
-  
-  return INTERACTIVE_COMMANDS.has(baseName);
-}
 
 
 // Track parent stream state for graceful shutdown
@@ -513,6 +488,14 @@ class StreamEmitter {
     return this;
   }
 
+  once(event, listener) {
+    const onceWrapper = (...args) => {
+      this.off(event, onceWrapper);
+      listener(...args);
+    };
+    return this.on(event, onceWrapper);
+  }
+
   emit(event, ...args) {
     const eventListeners = this.listeners.get(event);
     trace('StreamEmitter', () => `Emitting event | ${JSON.stringify({ 
@@ -521,7 +504,9 @@ class StreamEmitter {
       listenerCount: eventListeners?.length || 0 
     })}`);
     if (eventListeners) {
-      for (const listener of eventListeners) {
+      // Create a copy to avoid issues if listeners modify the array
+      const listenersToCall = [...eventListeners];
+      for (const listener of listenersToCall) {
         listener(...args);
       }
     }
@@ -545,6 +530,36 @@ function quote(value) {
   if (Array.isArray(value)) return value.map(quote).join(' ');
   if (typeof value !== 'string') value = String(value);
   if (value === '') return "''";
+  
+  // If the value is already properly quoted and doesn't need further escaping,
+  // check if we can use it as-is or with simpler quoting
+  if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+    // If it's already single-quoted and doesn't contain unescaped single quotes in the middle,
+    // we can potentially use it as-is
+    const inner = value.slice(1, -1);
+    if (!inner.includes("'")) {
+      // The inner content has no single quotes, so the original quoting is fine
+      return value;
+    }
+  }
+  
+  if (value.startsWith('"') && value.endsWith('"') && value.length > 2) {
+    // If it's already double-quoted, wrap it in single quotes to preserve it
+    return `'${value}'`;
+  }
+  
+  // Check if the string needs quoting at all
+  // Safe characters: alphanumeric, dash, underscore, dot, slash, colon, equals, comma, plus
+  // This regex matches strings that DON'T need quoting
+  const safePattern = /^[a-zA-Z0-9_\-./=,+@:]+$/;
+  
+  if (safePattern.test(value)) {
+    // The string is safe and doesn't need quoting
+    return value;
+  }
+  
+  // Default behavior: wrap in single quotes and escape any internal single quotes
+  // This handles spaces, special shell characters, etc.
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
 
@@ -604,6 +619,7 @@ class ProcessRunner extends StreamEmitter {
       stdin: 'inherit',
       cwd: undefined,
       env: undefined,
+      interactive: false, // Explicitly request TTY forwarding for interactive commands
       ...options
     };
 
@@ -655,6 +671,281 @@ class ProcessRunner extends StreamEmitter {
     return this.child ? this.child.stdin : null;
   }
 
+  // Issue #33: New streaming interfaces
+  _autoStartIfNeeded(reason) {
+    if (!this.started && !this.finished) {
+      trace('ProcessRunner', () => `Auto-starting process due to ${reason}`);
+      this.start({ mode: 'async', stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' });
+    }
+  }
+
+  get streams() {
+    const self = this;
+    return {
+      get stdin() {
+        trace('ProcessRunner.streams', () => `stdin access | ${JSON.stringify({
+          hasChild: !!self.child,
+          hasStdin: !!(self.child && self.child.stdin),
+          started: self.started,
+          finished: self.finished,
+          hasPromise: !!self.promise,
+          command: self.spec?.command?.slice(0, 50)
+        }, null, 2)}`);
+        
+        self._autoStartIfNeeded('streams.stdin access');
+        
+        // Streams are available immediately after spawn, or null if not piped
+        // Return the stream directly if available, otherwise ensure process starts
+        if (self.child && self.child.stdin) {
+          trace('ProcessRunner.streams', () => 'stdin: returning existing stream');
+          return self.child.stdin;
+        }
+        if (self.finished) {
+          trace('ProcessRunner.streams', () => 'stdin: process finished, returning null');
+          return null;
+        }
+        
+        // For virtual commands, there's no child process
+        // Exception: virtual commands with stdin: "pipe" will fallback to real commands
+        const isVirtualCommand = self._virtualGenerator || (self.spec && self.spec.command && virtualCommands.has(self.spec.command.split(' ')[0]));
+        const willFallbackToReal = isVirtualCommand && self.options.stdin === 'pipe';
+        
+        if (isVirtualCommand && !willFallbackToReal) {
+          trace('ProcessRunner.streams', () => 'stdin: virtual command, returning null');
+          return null;
+        }
+        
+        // If not started, start it and wait for child to be created (not for completion!)
+        if (!self.started) {
+          trace('ProcessRunner.streams', () => 'stdin: not started, starting and waiting for child');
+          // Start the process
+          self._startAsync();
+          // Wait for child to be created using async iteration
+          return new Promise((resolve) => {
+            const checkForChild = () => {
+              if (self.child && self.child.stdin) {
+                resolve(self.child.stdin);
+              } else if (self.finished || self._virtualGenerator) {
+                resolve(null);
+              } else {
+                // Use setImmediate to check again in next event loop iteration
+                setImmediate(checkForChild);
+              }
+            };
+            setImmediate(checkForChild);
+          });
+        }
+        
+        // Process is starting - wait for child to appear
+        if (self.promise && !self.child) {
+          trace('ProcessRunner.streams', () => 'stdin: process starting, waiting for child');
+          return new Promise((resolve) => {
+            const checkForChild = () => {
+              if (self.child && self.child.stdin) {
+                resolve(self.child.stdin);
+              } else if (self.finished || self._virtualGenerator) {
+                resolve(null);
+              } else {
+                setImmediate(checkForChild);
+              }
+            };
+            setImmediate(checkForChild);
+          });
+        }
+        
+        trace('ProcessRunner.streams', () => 'stdin: returning null (no conditions met)');
+        return null;
+      },
+      get stdout() {
+        trace('ProcessRunner.streams', () => `stdout access | ${JSON.stringify({
+          hasChild: !!self.child,
+          hasStdout: !!(self.child && self.child.stdout),
+          started: self.started,
+          finished: self.finished,
+          hasPromise: !!self.promise,
+          command: self.spec?.command?.slice(0, 50)
+        }, null, 2)}`);
+        
+        self._autoStartIfNeeded('streams.stdout access');
+        
+        if (self.child && self.child.stdout) {
+          trace('ProcessRunner.streams', () => 'stdout: returning existing stream');
+          return self.child.stdout;
+        }
+        if (self.finished) {
+          trace('ProcessRunner.streams', () => 'stdout: process finished, returning null');
+          return null;
+        }
+        
+        // For virtual commands, there's no child process
+        if (self._virtualGenerator || (self.spec && self.spec.command && virtualCommands.has(self.spec.command.split(' ')[0]))) {
+          trace('ProcessRunner.streams', () => 'stdout: virtual command, returning null');
+          return null;
+        }
+        
+        if (!self.started) {
+          trace('ProcessRunner.streams', () => 'stdout: not started, starting and waiting for child');
+          self._startAsync();
+          return new Promise((resolve) => {
+            const checkForChild = () => {
+              if (self.child && self.child.stdout) {
+                resolve(self.child.stdout);
+              } else if (self.finished || self._virtualGenerator) {
+                resolve(null);
+              } else {
+                setImmediate(checkForChild);
+              }
+            };
+            setImmediate(checkForChild);
+          });
+        }
+        
+        if (self.promise && !self.child) {
+          trace('ProcessRunner.streams', () => 'stdout: process starting, waiting for child');
+          return new Promise((resolve) => {
+            const checkForChild = () => {
+              if (self.child && self.child.stdout) {
+                resolve(self.child.stdout);
+              } else if (self.finished || self._virtualGenerator) {
+                resolve(null);
+              } else {
+                setImmediate(checkForChild);
+              }
+            };
+            setImmediate(checkForChild);
+          });
+        }
+        
+        trace('ProcessRunner.streams', () => 'stdout: returning null (no conditions met)');
+        return null;
+      },
+      get stderr() {
+        trace('ProcessRunner.streams', () => `stderr access | ${JSON.stringify({
+          hasChild: !!self.child,
+          hasStderr: !!(self.child && self.child.stderr),
+          started: self.started,
+          finished: self.finished,
+          hasPromise: !!self.promise,
+          command: self.spec?.command?.slice(0, 50)
+        }, null, 2)}`);
+        
+        self._autoStartIfNeeded('streams.stderr access');
+        
+        if (self.child && self.child.stderr) {
+          trace('ProcessRunner.streams', () => 'stderr: returning existing stream');
+          return self.child.stderr;
+        }
+        if (self.finished) {
+          trace('ProcessRunner.streams', () => 'stderr: process finished, returning null');
+          return null;
+        }
+        
+        // For virtual commands, there's no child process
+        if (self._virtualGenerator || (self.spec && self.spec.command && virtualCommands.has(self.spec.command.split(' ')[0]))) {
+          trace('ProcessRunner.streams', () => 'stderr: virtual command, returning null');
+          return null;
+        }
+        
+        if (!self.started) {
+          trace('ProcessRunner.streams', () => 'stderr: not started, starting and waiting for child');
+          self._startAsync();
+          return new Promise((resolve) => {
+            const checkForChild = () => {
+              if (self.child && self.child.stderr) {
+                resolve(self.child.stderr);
+              } else if (self.finished || self._virtualGenerator) {
+                resolve(null);
+              } else {
+                setImmediate(checkForChild);
+              }
+            };
+            setImmediate(checkForChild);
+          });
+        }
+        
+        if (self.promise && !self.child) {
+          trace('ProcessRunner.streams', () => 'stderr: process starting, waiting for child');
+          return new Promise((resolve) => {
+            const checkForChild = () => {
+              if (self.child && self.child.stderr) {
+                resolve(self.child.stderr);
+              } else if (self.finished || self._virtualGenerator) {
+                resolve(null);
+              } else {
+                setImmediate(checkForChild);
+              }
+            };
+            setImmediate(checkForChild);
+          });
+        }
+        
+        trace('ProcessRunner.streams', () => 'stderr: returning null (no conditions met)');
+        return null;
+      }
+    };
+  }
+
+  get buffers() {
+    const self = this;
+    return {
+      get stdin() {
+        self._autoStartIfNeeded('buffers.stdin access');
+        if (self.finished && self.result) {
+          return Buffer.from(self.result.stdin || '', 'utf8');
+        }
+        // Return promise if not finished
+        return self.then ? self.then(result => Buffer.from(result.stdin || '', 'utf8')) : Promise.resolve(Buffer.alloc(0));
+      },
+      get stdout() {
+        self._autoStartIfNeeded('buffers.stdout access');
+        if (self.finished && self.result) {
+          return Buffer.from(self.result.stdout || '', 'utf8');
+        }
+        // Return promise if not finished
+        return self.then ? self.then(result => Buffer.from(result.stdout || '', 'utf8')) : Promise.resolve(Buffer.alloc(0));
+      },
+      get stderr() {
+        self._autoStartIfNeeded('buffers.stderr access');
+        if (self.finished && self.result) {
+          return Buffer.from(self.result.stderr || '', 'utf8');
+        }
+        // Return promise if not finished
+        return self.then ? self.then(result => Buffer.from(result.stderr || '', 'utf8')) : Promise.resolve(Buffer.alloc(0));
+      }
+    };
+  }
+
+  get strings() {
+    const self = this;
+    return {
+      get stdin() {
+        self._autoStartIfNeeded('strings.stdin access');
+        if (self.finished && self.result) {
+          return self.result.stdin || '';
+        }
+        // Return promise if not finished
+        return self.then ? self.then(result => result.stdin || '') : Promise.resolve('');
+      },
+      get stdout() {
+        self._autoStartIfNeeded('strings.stdout access');
+        if (self.finished && self.result) {
+          return self.result.stdout || '';
+        }
+        // Return promise if not finished
+        return self.then ? self.then(result => result.stdout || '') : Promise.resolve('');
+      },
+      get stderr() {
+        self._autoStartIfNeeded('strings.stderr access');
+        if (self.finished && self.result) {
+          return self.result.stderr || '';
+        }
+        // Return promise if not finished  
+        return self.then ? self.then(result => result.stderr || '') : Promise.resolve('');
+      }
+    };
+  }
+
+
   // Centralized method to properly finish a process with correct event emission order
   finish(result) {
     trace('ProcessRunner', () => `finish() called | ${JSON.stringify({
@@ -814,14 +1105,15 @@ class ProcessRunner extends StreamEmitter {
           writer.close().catch(() => { }); // Ignore close errors
         }
 
-        setTimeout(() => {
+        // Use setImmediate for deferred termination instead of setTimeout
+        setImmediate(() => {
           if (this.child && !this.finished) {
             trace('ProcessRunner', () => 'Terminating child process after parent stream closure');
             if (typeof this.child.kill === 'function') {
               this.child.kill('SIGTERM');
             }
           }
-        }, 100);
+        });
 
       } catch (error) {
         trace('ProcessRunner', () => `Error during graceful shutdown | ${JSON.stringify({ error: error.message }, null, 2)}`);
@@ -939,7 +1231,14 @@ class ProcessRunner extends StreamEmitter {
   start(options = {}) {
     const mode = options.mode || 'async';
 
-    trace('ProcessRunner', () => `start ENTER | ${JSON.stringify({ mode, options, started: this.started }, null, 2)}`);
+    trace('ProcessRunner', () => `start ENTER | ${JSON.stringify({ 
+      mode, 
+      options, 
+      started: this.started,
+      hasPromise: !!this.promise,
+      hasChild: !!this.child,
+      command: this.spec?.command?.slice(0, 50)
+    }, null, 2)}`);
 
     // Merge new options with existing options before starting
     if (Object.keys(options).length > 0 && !this.started) {
@@ -1115,16 +1414,17 @@ class ProcessRunner extends StreamEmitter {
             commandCount: parsed.commands?.length
           }, null, 2)}`);
           return await this._runPipeline(parsed.commands);
-        } else if (parsed.type === 'simple' && virtualCommandsEnabled && virtualCommands.has(parsed.cmd)) {
+        } else if (parsed.type === 'simple' && virtualCommandsEnabled && virtualCommands.has(parsed.cmd) && !this.options._bypassVirtual) {
           // For built-in virtual commands that have real counterparts (like sleep),
           // skip the virtual version when custom stdin is provided to ensure proper process handling
           const hasCustomStdin = this.options.stdin && 
                                  this.options.stdin !== 'inherit' && 
                                  this.options.stdin !== 'ignore';
           
-          // List of built-in virtual commands that should fallback to real commands with custom stdin
-          const builtinCommands = ['sleep', 'echo', 'pwd', 'true', 'false', 'yes', 'cat', 'ls', 'which'];
-          const shouldBypassVirtual = hasCustomStdin && builtinCommands.includes(parsed.cmd);
+          // Only bypass for commands that truly need real process behavior with custom stdin
+          // Most commands like 'echo' work fine with virtual implementations even with stdin
+          const commandsThatNeedRealStdin = ['sleep', 'cat']; // Only these really need real processes for stdin
+          const shouldBypassVirtual = hasCustomStdin && commandsThatNeedRealStdin.includes(parsed.cmd);
           
           if (shouldBypassVirtual) {
             trace('ProcessRunner', () => `Bypassing built-in virtual command due to custom stdin | ${JSON.stringify({
@@ -1168,12 +1468,12 @@ class ProcessRunner extends StreamEmitter {
     }
 
     // Detect if this is an interactive command that needs direct TTY access
-    // Only activate for interactive commands when we have a real TTY and the command is likely to need it
+    // Only activate for interactive commands when we have a real TTY and interactive mode is explicitly requested
     const isInteractive = stdin === 'inherit' && 
       process.stdin.isTTY === true && 
       process.stdout.isTTY === true && 
       process.stderr.isTTY === true &&
-      (this.spec.mode === 'shell' ? isInteractiveCommand(this.spec.command) : isInteractiveCommand(this.spec.file));
+      this.options.interactive === true;
     
     trace('ProcessRunner', () => `Interactive command detection | ${JSON.stringify({
       isInteractive,
@@ -1181,7 +1481,7 @@ class ProcessRunner extends StreamEmitter {
       stdinTTY: process.stdin.isTTY,
       stdoutTTY: process.stdout.isTTY,
       stderrTTY: process.stderr.isTTY,
-      commandCheck: this.spec.mode === 'shell' ? isInteractiveCommand(this.spec.command) : isInteractiveCommand(this.spec.file)
+      interactiveOption: this.options.interactive
     }, null, 2)}`);
 
     const spawnBun = (argv) => {
@@ -1380,6 +1680,10 @@ class ProcessRunner extends StreamEmitter {
         this.child.stdin.end();
         trace('ProcessRunner', () => `stdin: Child stdin closed successfully`);
       }
+    } else if (stdin === 'pipe') {
+      trace('ProcessRunner', () => `stdin: Using pipe mode - leaving stdin open for manual control`);
+      // Leave stdin open for manual writing via streams.stdin
+      stdinPumpPromise = Promise.resolve();
     } else if (typeof stdin === 'string' || Buffer.isBuffer(stdin)) {
       const buf = Buffer.isBuffer(stdin) ? stdin : Buffer.from(stdin);
       trace('ProcessRunner', () => `stdin: Writing buffer to child | ${JSON.stringify({
@@ -1675,7 +1979,23 @@ class ProcessRunner extends StreamEmitter {
     try {
       // Prepare stdin
       let stdinData = '';
-      if (this.options.stdin && typeof this.options.stdin === 'string') {
+      
+      // Special handling for streaming mode (stdin: "pipe")
+      if (this.options.stdin === 'pipe') {
+        // For streaming interfaces, virtual commands should fallback to real commands
+        // because virtual commands don't support true streaming
+        trace('ProcessRunner', () => `Virtual command fallback for streaming | ${JSON.stringify({ cmd }, null, 2)}`);
+        
+        // Create a new ProcessRunner for the real command with properly merged options
+        // Preserve main options but use appropriate stdin for the real command
+        const modifiedOptions = { 
+          ...this.options, 
+          stdin: 'pipe', // Keep pipe but ensure it doesn't trigger virtual command fallback
+          _bypassVirtual: true // Flag to prevent virtual command recursion
+        };
+        const realRunner = new ProcessRunner({ mode: 'shell', command: originalCommand || cmd }, modifiedOptions);
+        return await realRunner._doStartAsync();
+      } else if (this.options.stdin && typeof this.options.stdin === 'string') {
         stdinData = this.options.stdin;
       } else if (this.options.stdin && Buffer.isBuffer(this.options.stdin)) {
         stdinData = this.options.stdin.toString('utf8');
@@ -1698,22 +2018,28 @@ class ProcessRunner extends StreamEmitter {
         const chunks = [];
 
         const commandOptions = {
-          ...this.options,
-          isCancelled: () => this._cancelled,
-          signal: this._abortController?.signal
+          // Commonly used options at top level for convenience
+          cwd: this.options.cwd,
+          env: this.options.env,
+          // All original options (built-in + custom) in options object
+          options: this.options,
+          isCancelled: () => this._cancelled
         };
         
         trace('ProcessRunner', () => `_runVirtual signal details | ${JSON.stringify({
           cmd,
           hasAbortController: !!this._abortController,
           signalAborted: this._abortController?.signal?.aborted,
-          signalExists: !!commandOptions.signal,
-          commandOptionsSignalAborted: commandOptions.signal?.aborted,
           optionsSignalExists: !!this.options.signal,
           optionsSignalAborted: this.options.signal?.aborted
         }, null, 2)}`);
 
-        const generator = handler({ args: argValues, stdin: stdinData, ...commandOptions });
+        const generator = handler({ 
+          args: argValues, 
+          stdin: stdinData, 
+          abortSignal: this._abortController?.signal,
+          ...commandOptions 
+        });
         this._virtualGenerator = generator;
 
         const cancelPromise = new Promise(resolve => {
@@ -1802,22 +2128,28 @@ class ProcessRunner extends StreamEmitter {
       } else {
         // Regular async function - race with abort signal
         const commandOptions = {
-          ...this.options,
-          isCancelled: () => this._cancelled,
-          signal: this._abortController?.signal
+          // Commonly used options at top level for convenience
+          cwd: this.options.cwd,
+          env: this.options.env,
+          // All original options (built-in + custom) in options object
+          options: this.options,
+          isCancelled: () => this._cancelled
         };
         
         trace('ProcessRunner', () => `_runVirtual signal details (non-generator) | ${JSON.stringify({
           cmd,
           hasAbortController: !!this._abortController,
           signalAborted: this._abortController?.signal?.aborted,
-          signalExists: !!commandOptions.signal,
-          commandOptionsSignalAborted: commandOptions.signal?.aborted,
           optionsSignalExists: !!this.options.signal,
           optionsSignalAborted: this.options.signal?.aborted
         }, null, 2)}`);
         
-        const handlerPromise = handler({ args: argValues, stdin: stdinData, ...commandOptions });
+        const handlerPromise = handler({ 
+          args: argValues, 
+          stdin: stdinData, 
+          abortSignal: this._abortController?.signal,
+          ...commandOptions 
+        });
         
         // Create an abort promise that rejects when cancelled
         const abortPromise = new Promise((_, reject) => {

package/src/commands/$.cat.mjs

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import { trace, VirtualUtils } from '../$.utils.mjs';
 
-export default async function cat({ args, stdin, cwd, isCancelled, signal }) {
+export default async function cat({ args, stdin, cwd, isCancelled, abortSignal }) {
   if (args.length === 0) {
     // Read from stdin if no files specified
     if (stdin !== undefined && stdin !== '') {
@@ -14,7 +14,7 @@ export default async function cat({ args, stdin, cwd, isCancelled, signal }) {
     const outputs = [];
     for (const file of args) {
       // Check for cancellation before processing each file
-      if (isCancelled?.() || signal?.aborted) {
+      if (isCancelled?.() || abortSignal?.aborted) {
         trace('VirtualCommand', () => `cat: cancelled while processing files`);
         return { code: 130, stdout: '', stderr: '' }; // SIGINT exit code
       }

package/src/commands/$.sleep.mjs

@@ -1,11 +1,11 @@
 import { trace } from '../$.utils.mjs';
 
-export default async function sleep({ args, signal, isCancelled }) {
+export default async function sleep({ args, abortSignal, isCancelled }) {
   const seconds = parseFloat(args[0] || 0);
   trace('VirtualCommand', () => `sleep: starting | ${JSON.stringify({ 
     seconds,
-    hasSignal: !!signal,
-    signalAborted: signal?.aborted,
+    hasSignal: !!abortSignal,
+    signalAborted: abortSignal?.aborted,
     hasIsCancelled: !!isCancelled
   }, null, 2)}`);
   
@@ -18,30 +18,30 @@ export default async function sleep({ args, signal, isCancelled }) {
     await new Promise((resolve, reject) => {
       const timeoutId = setTimeout(resolve, seconds * 1000);
       
-      // Handle cancellation via signal
-      if (signal) {
+      // Handle cancellation via abort signal
+      if (abortSignal) {
         trace('VirtualCommand', () => `sleep: setting up abort signal listener | ${JSON.stringify({
-          signalAborted: signal.aborted
+          signalAborted: abortSignal.aborted
         }, null, 2)}`);
         
-        signal.addEventListener('abort', () => {
+        abortSignal.addEventListener('abort', () => {
           trace('VirtualCommand', () => `sleep: abort signal received | ${JSON.stringify({
             seconds,
-            signalAborted: signal.aborted
+            signalAborted: abortSignal.aborted
           }, null, 2)}`);
           clearTimeout(timeoutId);
           reject(new Error('Sleep cancelled'));
         });
         
         // Check if already aborted
-        if (signal.aborted) {
+        if (abortSignal.aborted) {
           trace('VirtualCommand', () => `sleep: signal already aborted | ${JSON.stringify({ seconds }, null, 2)}`);
           clearTimeout(timeoutId);
           reject(new Error('Sleep cancelled'));
           return;
         }
       } else {
-        trace('VirtualCommand', () => `sleep: no signal provided | ${JSON.stringify({ seconds }, null, 2)}`);
+        trace('VirtualCommand', () => `sleep: no abort signal provided | ${JSON.stringify({ seconds }, null, 2)}`);
       }
       
       // Also check isCancelled periodically for quicker response

package/src/commands/$.yes.mjs

@@ -1,11 +1,11 @@
 import { trace } from '../$.utils.mjs';
 
-export default async function* yes({ args, stdin, isCancelled, signal, ...rest }) {
+export default async function* yes({ args, stdin, isCancelled, abortSignal, ...rest }) {
   const output = args.length > 0 ? args.join(' ') : 'y';
   trace('VirtualCommand', () => `yes: starting infinite generator | ${JSON.stringify({ 
     output,
     hasIsCancelled: !!isCancelled,
-    hasSignal: !!signal
+    hasAbortSignal: !!abortSignal
   }, null, 2)}`);
 
   let iteration = 0;
@@ -14,12 +14,12 @@ export default async function* yes({ args, stdin, isCancelled, signal, ...rest }
   while (!isCancelled?.() && iteration < MAX_ITERATIONS) {
     trace('VirtualCommand', () => `yes: iteration ${iteration} starting | ${JSON.stringify({
       isCancelled: isCancelled?.(),
-      signalAborted: signal?.aborted
+      abortSignalAborted: abortSignal?.aborted
     }, null, 2)}`);
     
     // Check for abort signal
-    if (signal?.aborted) {
-      trace('VirtualCommand', () => `yes: aborted via signal | ${JSON.stringify({ iteration }, null, 2)}`);
+    if (abortSignal?.aborted) {
+      trace('VirtualCommand', () => `yes: aborted via abort signal | ${JSON.stringify({ iteration }, null, 2)}`);
       break;
     }
 
@@ -43,6 +43,6 @@ export default async function* yes({ args, stdin, isCancelled, signal, ...rest }
   trace('VirtualCommand', () => `yes: generator completed | ${JSON.stringify({ 
     iteration,
     wasCancelled: isCancelled?.(),
-    wasAborted: signal?.aborted
+    wasAborted: abortSignal?.aborted
   }, null, 2)}`);
 }