command-stream 0.5.0 → 0.7.0

package/README.md

@@ -41,7 +41,7 @@ A modern $ shell utility library with streaming, async iteration, and EventEmitt
 | **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 |
+| **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 |
@@ -57,7 +57,7 @@ A modern $ shell utility library with streaming, async iteration, and EventEmitt
 | **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 |
+| **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 |
@@ -81,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
 
@@ -151,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)
@@ -184,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',
@@ -782,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
 }
 ```
 
@@ -792,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
 
@@ -1083,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**: 
@@ -1176,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
@@ -1227,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.5.0",
+  "version": "0.7.0",
   "description": "Modern $ shell utility library with streaming, async iteration, and EventEmitter support, optimized for Bun runtime",
   "type": "module",
   "main": "src/$.mjs",