command-stream 0.5.0 → 0.6.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.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
@@ -555,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, "'\\''")}'`;
 }
 
@@ -614,6 +619,7 @@ class ProcessRunner extends StreamEmitter {
       stdin: 'inherit',
       cwd: undefined,
       env: undefined,
+      interactive: false, // Explicitly request TTY forwarding for interactive commands
       ...options
     };
 
@@ -1462,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,
@@ -1475,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) => {