command-stream 0.3.2 → 0.5.0

package/README.md

@@ -1,3 +1,7 @@
+[![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)
 
@@ -23,31 +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) |
-|---------|----------------|-------|-------|-----|
-| **Runtime Support** | ✅ Bun + Node.js | 🟡 Bun only | ✅ Node.js | ✅ Node.js |
-| **Template Literals** | ✅ `` $`cmd` `` | ✅ `` $`cmd` `` | ✅ `` $`cmd` `` | ✅ `` $`cmd` `` |
-| **Real-time Streaming** | ✅ Live output | ❌ Buffer only | 🟡 Limited | ❌ Buffer only |
-| **Synchronous Execution** | ✅ `.sync()` with events | ❌ No | ✅ `execaSync` | ❌ No |
-| **Async Iteration** | ✅ `for await (chunk of $.stream())` | ❌ No | ❌ No | ❌ No |
-| **EventEmitter Pattern** | ✅ `.on('data', ...)` | ❌ No | 🟡 Limited events | ❌ No |
-| **Mixed Patterns** | ✅ Events + await/sync | ❌ No | ❌ No | ❌ No |
-| **Bun.$ Compatibility** | ✅ `.text()` method support | ✅ Native API | ❌ No | ❌ No |
-| **Shell Injection Protection** | ✅ Auto-quoting | ✅ Built-in | ✅ Safe by default | ✅ Safe by default |
-| **Cross-platform** | ✅ macOS/Linux/Windows | ✅ Yes | ✅ Yes | ✅ Yes |
-| **Performance** | ⚡ Fast (Bun optimized) | ⚡ Very fast | 🐌 Moderate | 🐌 Slow |
-| **Memory Efficiency** | ✅ Streaming prevents buildup | 🟡 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 |
-| **Shell Settings** | ✅ `set -e`/`set +e` equivalent | ❌ No | ❌ No | ❌ No |
-| **Stdout Support** | ✅ Real-time streaming + events | ✅ Shell redirection + buffered | ✅ Node.js streams + interleaved | ✅ Readable streams + `.pipe.stdout` |
-| **Stderr Support** | ✅ Real-time streaming + events | ✅ Redirection + `.quiet()` access | ✅ Streams + interleaved output | ✅ Readable streams + `.pipe.stderr` |
-| **Stdin Support** | ✅ string/Buffer/inherit/ignore | ✅ Pipe operations | ✅ Input/output streams | ✅ Basic stdin |
-| **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 |
-| **Virtual Commands Engine** | ✅ **Revolutionary**: Register JavaScript functions as shell commands with full pipeline support | ❌ No extensibility | ❌ 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 |
-| **Bundle Size** | 📦 ~15KB | 🎯 0KB (built-in) | 📦 ~25KB | 📦 ~50KB |
-| **TypeScript** | 🔄 Coming soon | ✅ Built-in | ✅ Full support | ✅ Full support |
-| **License** | ✅ **Unlicense (Public Domain)** | 🟡 MIT (+ LGPL dependencies) | 🟡 MIT | 🟡 Apache 2.0 |
+| 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) |
+|---------|----------------|-------|-------|-----|-------|-------|
+| **📦 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', ...)` | 🟡 Limited events | 🟡 Child process events | ❌ No | ❌ No | ❌ No |
+| **Mixed Patterns** | ✅ Events + await/sync | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No |
+| **Bun.$ Compatibility** | ✅ `.text()` method support | ❌ No | ❌ No | ✅ Native API | ❌ No | ❌ No |
+| **Shell Injection Protection** | ✅ 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 | ❌ 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 | ✅ 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** | ✅ **410 tests, 909 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?
 
@@ -60,7 +81,9 @@ 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**: 266+ tests with comprehensive coverage
+- **🛡️ Production Ready**: **410 tests, 909 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
 
 ## Built-in Commands (🚀 NEW!)
 
@@ -140,6 +163,42 @@ console.log(result.stdout);
 console.log(result.code); // exit code
 ```
 
+### Custom Options with $({ options }) Syntax (NEW!)
+
+```javascript
+import { $ } from 'command-stream';
+
+// Create a $ with custom options
+const $silent = $({ mirror: false, capture: true });
+const result = await $silent`echo "quiet operation"`;
+
+// Options for stdin handling
+const $withInput = $({ stdin: 'input data\n' });
+await $withInput`cat`; // Pipes the input to cat
+
+// Custom environment variables
+const $withEnv = $({ env: { ...process.env, MY_VAR: 'value' } });
+await $withEnv`printenv MY_VAR`; // Prints: value
+
+// Custom working directory
+const $inTmp = $({ cwd: '/tmp' });
+await $inTmp`pwd`; // Prints: /tmp
+
+// Combine multiple options
+const $custom = $({
+  stdin: 'test data',
+  mirror: false,
+  capture: true,
+  cwd: '/tmp'
+});
+await $custom`cat > output.txt`; // Writes to /tmp/output.txt silently
+
+// Reusable configurations
+const $prod = $({ env: { NODE_ENV: 'production' }, capture: true });
+await $prod`npm start`;
+await $prod`npm test`;
+```
+
 ### Execution Control (NEW!)
 
 ```javascript
@@ -242,6 +301,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:
@@ -318,7 +454,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 };
 });
@@ -328,7 +464,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`;
@@ -365,7 +501,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 };
@@ -401,11 +537,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 };
 });
 
@@ -433,12 +569,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 };
 });
@@ -463,7 +599,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 };
@@ -472,7 +608,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);
@@ -660,7 +796,8 @@ The enhanced `$` function returns a `ProcessRunner` instance that extends `Event
 - `env: object` - Environment variables
 
 **Override defaults:**
-- Use `sh(command, options)` for one-off overrides
+- Use `$({ options })` syntax for one-off configurations with template literals
+- Use `sh(command, options)` for one-off overrides with string commands
 - Use `create(defaultOptions)` to create custom `$` with different defaults
 
 ### Shell Settings API
@@ -676,6 +813,38 @@ Control shell behavior like bash `set`/`unset` commands:
 - `unset(option)`: Disable shell option
 - `shell.settings()`: Get current settings object
 
+#### Error Handling Modes
+
+```javascript
+import { $, shell } from 'command-stream';
+
+// ✅ Default behavior: Commands don't throw on non-zero exit
+const result = await $`ls nonexistent-file`; // Won't throw
+console.log(result.code); // → 2 (non-zero, but no exception)
+
+// ✅ Enable errexit: Commands throw on non-zero exit
+shell.errexit(true);
+try {
+  await $`ls nonexistent-file`; // Throws error
+} catch (error) {
+  console.log('Command failed:', error.code); // → 2
+}
+
+// ✅ Disable errexit: Back to non-throwing behavior
+shell.errexit(false);
+await $`ls nonexistent-file`; // Won't throw, returns result with code 2
+
+// ✅ One-time override without changing global settings
+try {
+  const result = await $`ls nonexistent-file`;
+  if (result.code !== 0) {
+    throw new Error(`Command failed with code ${result.code}`);
+  }
+} catch (error) {
+  console.log('Manual error handling');
+}
+```
+
 ### Virtual Commands API
 
 Control and extend the command system with custom JavaScript functions:
@@ -690,11 +859,79 @@ Control and extend the command system with custom JavaScript functions:
 - `enableVirtualCommands()`: Enable virtual command processing
 - `disableVirtualCommands()`: Disable virtual commands (use system commands only)
 
+#### Advanced Virtual Command Features
+
+```javascript
+import { $, register } from 'command-stream';
+
+// ✅ Cancellation support with AbortController
+register('cancellable', async function* ({ args, stdin, abortSignal }) {
+  for (let i = 0; i < 10; i++) {
+    if (abortSignal?.aborted) {
+      break; // Proper cancellation handling
+    }
+    yield `Count: ${i}\n`;
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  }
+});
+
+// ✅ Access to all process 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,  // 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 }) => {
+  if (Math.random() > 0.5) {
+    return {
+      stdout: 'Success!\n',
+      code: 0
+    };
+  } else {
+    return {
+      stdout: '',
+      stderr: 'Random failure occurred\n',
+      code: 1
+    };
+  }
+});
+
+// ✅ 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)
@@ -703,10 +940,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
 }
 ```
 
@@ -771,10 +1011,172 @@ const result4 = await $`echo "pipe test"`.pipe($`cat`);
 const text4 = await result4.text(); // "pipe test\n"
 ```
 
+## Signal Handling (CTRL+C Support)
+
+The library provides **advanced CTRL+C handling** that properly manages signals across different scenarios:
+
+### How It Works
+
+1. **Smart Signal Forwarding**: CTRL+C is forwarded **only when child processes are active**
+2. **User Handler Preservation**: When no children are running, your custom SIGINT handlers work normally
+3. **Process Groups**: Child processes use detached spawning for proper signal isolation
+4. **TTY Mode Support**: Raw TTY mode is properly managed and restored on interruption
+5. **Graceful Termination**: Uses SIGTERM → SIGKILL escalation for robust process cleanup
+6. **Exit Code Standards**: Proper signal exit codes (130 for SIGINT, 143 for SIGTERM)
+
+### Advanced Signal Behavior
+
+```javascript
+// ✅ Smart signal handling - only interferes when necessary
+import { $ } from 'command-stream';
+
+// Case 1: No children active - your handlers work normally  
+process.on('SIGINT', () => {
+  console.log('My custom handler runs!');
+  process.exit(42); // Custom exit code
+});
+// Press CTRL+C → Your handler runs, exits with code 42
+
+// Case 2: Children active - automatic forwarding
+await $`ping 8.8.8.8`; // Press CTRL+C → Forwards to ping, exits with code 130
+
+// Case 3: Multiple processes - all interrupted
+await Promise.all([
+  $`sleep 100`,
+  $`ping google.com`  
+]); // Press CTRL+C → All processes terminated, exits with code 130
+```
+
+### Examples
+
+```javascript
+// Long-running command that can be interrupted with CTRL+C
+try {
+  await $`ping 8.8.8.8`;  // Press CTRL+C to stop
+} catch (error) {
+  console.log('Command interrupted:', error.code); // Exit code 130 (SIGINT)
+}
+
+// Multiple concurrent processes - CTRL+C stops all
+try {
+  await Promise.all([
+    $`sleep 100`,
+    $`ping google.com`,
+    $`tail -f /var/log/system.log`
+  ]);
+} catch (error) {
+  // All processes are terminated when you press CTRL+C
+}
+
+// Works with streaming patterns too
+try {
+  for await (const chunk of $`ping 8.8.8.8`.stream()) {
+    console.log(chunk);
+    // Press CTRL+C to break the loop and stop the process
+  }
+} catch (error) {
+  console.log('Streaming interrupted');
+}
+```
+
+### Signal Handling Behavior
+
+- **🎯 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
+- **🔄 Process Groups**: Detached spawning ensures proper signal isolation
+- **🧹 TTY Cleanup**: Raw terminal mode properly restored on interruption
+- **📊 Standard Exit Codes**: 
+  - `130` - SIGINT interruption (CTRL+C)
+  - `143` - SIGTERM termination (programmatic kill)
+  - `137` - SIGKILL force termination
+
+### Command Resolution Priority
+
+```javascript
+// Understanding how commands are resolved:
+
+// 1. Virtual Commands (highest priority)
+register('echo', () => ({ stdout: 'virtual!\n', code: 0 }));
+await $`echo test`; // → "virtual!"
+
+// 2. Built-in Commands (if no virtual match)  
+unregister('echo');
+await $`echo test`; // → Uses built-in echo
+
+// 3. System Commands (if no built-in/virtual match)
+await $`unknown-command`; // → Uses system PATH lookup
+
+// 4. Virtual Bypass (special case)
+await $({ stdin: 'data' })`sleep 1`; // Bypasses virtual sleep, uses system sleep
+```
+
+## Execution Patterns Deep Dive
+
+### When to Use Different Patterns
+
+```javascript
+import { $ } from 'command-stream';
+
+// ✅ Use await for simple command execution
+const result = await $`ls -la`;
+
+// ✅ Use .sync() when you need blocking execution with events
+const syncCmd = $`build-script`
+  .on('stdout', chunk => updateProgress(chunk))
+  .sync(); // Events fire after completion
+
+// ✅ Use .start() for non-blocking execution with real-time events  
+const asyncCmd = $`long-running-server`
+  .on('stdout', chunk => logOutput(chunk))
+  .start(); // Events fire in real-time
+
+// ✅ Use .stream() for processing large outputs efficiently
+for await (const chunk of $`generate-big-file`.stream()) {
+  processChunkInRealTime(chunk);
+} // Memory efficient - processes chunks as they arrive
+
+// ✅ Use EventEmitter pattern for complex workflows
+$`deployment-script`
+  .on('stdout', chunk => {
+    if (chunk.toString().includes('ERROR')) {
+      handleError(chunk);
+    }
+  })
+  .on('stderr', chunk => logError(chunk))
+  .on('end', result => {
+    if (result.code === 0) {
+      notifySuccess();
+    }
+  })
+  .start();
+```
+
+### Performance Considerations
+
+```javascript
+// 🚀 Memory Efficient: For large outputs, use streaming
+for await (const chunk of $`cat huge-file.log`.stream()) {
+  processChunk(chunk); // Processes incrementally
+}
+
+// 🐌 Memory Inefficient: Buffers entire output in memory
+const result = await $`cat huge-file.log`;
+processFile(result.stdout); // Loads everything into memory
+
+// ⚡ Fastest: Sync execution for small, quick commands
+const quickResult = $`pwd`.sync();
+
+// 🔄 Best for UX: Async with events for long-running commands
+$`npm install`
+  .on('stdout', showProgress)
+  .start();
+```
+
 ## Testing
 
 ```bash
-# Run comprehensive test suite (266 tests)
+# Run comprehensive test suite (270+ tests)
 bun test
 
 # Run tests with coverage report
@@ -782,9 +1184,10 @@ bun test --coverage
 
 # Run specific test categories
 npm run test:features    # Feature comparison tests
-npm run test:builtin     # Built-in commands tests
+npm run test:builtin     # Built-in commands tests  
 npm run test:pipe        # .pipe() method tests
 npm run test:sync        # Synchronous execution tests
+npm run test:signal      # CTRL+C signal handling tests
 ```
 
 ## Requirements

package/package.json

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