command-stream 0.5.0 → 0.7.0

package/src/$.mjs

@@ -7,18 +7,13 @@
 
 import cp from 'child_process';
 import path from 'path';
+import fs from 'fs';
+import { parseShellCommand, needsRealShell } from './shell-parser.mjs';
 
 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,26 +23,75 @@ 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;
+// Shell detection cache
+let cachedShell = null;
+
+// Save initial working directory for restoration
+const initialWorkingDirectory = process.cwd();
+
+/**
+ * Find an available shell by checking multiple options in order
+ * Returns the shell command and arguments to use
+ */
+function findAvailableShell() {
+  if (cachedShell) {
+    trace('ShellDetection', () => `Using cached shell: ${cachedShell.cmd}`);
+    return cachedShell;
   }
-  
-  return INTERACTIVE_COMMANDS.has(baseName);
+
+  const shellsToTry = [
+    // Try absolute paths first (most reliable)
+    { cmd: '/bin/sh', args: ['-l', '-c'], checkPath: true },
+    { cmd: '/usr/bin/sh', args: ['-l', '-c'], checkPath: true },
+    { cmd: '/bin/bash', args: ['-l', '-c'], checkPath: true },
+    { cmd: '/usr/bin/bash', args: ['-l', '-c'], checkPath: true },
+    { cmd: '/bin/zsh', args: ['-l', '-c'], checkPath: true },
+    { cmd: '/usr/bin/zsh', args: ['-l', '-c'], checkPath: true },
+    // macOS specific paths
+    { cmd: '/usr/local/bin/bash', args: ['-l', '-c'], checkPath: true },
+    { cmd: '/usr/local/bin/zsh', args: ['-l', '-c'], checkPath: true },
+    // Linux brew paths
+    { cmd: '/home/linuxbrew/.linuxbrew/bin/bash', args: ['-l', '-c'], checkPath: true },
+    { cmd: '/home/linuxbrew/.linuxbrew/bin/zsh', args: ['-l', '-c'], checkPath: true },
+    // Try shells in PATH as fallback (which might not work in all environments)
+    // Using separate -l and -c flags for better compatibility
+    { cmd: 'sh', args: ['-l', '-c'], checkPath: false },
+    { cmd: 'bash', args: ['-l', '-c'], checkPath: false },
+    { cmd: 'zsh', args: ['-l', '-c'], checkPath: false }
+  ];
+
+  for (const shell of shellsToTry) {
+    try {
+      if (shell.checkPath) {
+        // Check if the absolute path exists
+        if (fs.existsSync(shell.cmd)) {
+          trace('ShellDetection', () => `Found shell at absolute path: ${shell.cmd}`);
+          cachedShell = { cmd: shell.cmd, args: shell.args };
+          return cachedShell;
+        }
+      } else {
+        // Try to execute 'which' to check if command is in PATH
+        const result = cp.spawnSync('which', [shell.cmd], { encoding: 'utf-8' });
+        if (result.status === 0 && result.stdout) {
+          const shellPath = result.stdout.trim();
+          trace('ShellDetection', () => `Found shell in PATH: ${shell.cmd} => ${shellPath}`);
+          cachedShell = { cmd: shell.cmd, args: shell.args };
+          return cachedShell;
+        }
+      }
+    } catch (e) {
+      // Continue to next shell option
+    }
+  }
+
+  // Final fallback - use absolute path to sh
+  trace('ShellDetection', () => 'WARNING: No shell found, using /bin/sh as fallback');
+  cachedShell = { cmd: '/bin/sh', args: ['-l', '-c'] };
+  return cachedShell;
 }
 
 
+
 // Track parent stream state for graceful shutdown
 let parentStreamsMonitored = false;
 const activeProcessRunners = new Set();
@@ -236,13 +280,127 @@ function forceCleanupAll() {
   // Clear activeProcessRunners
   activeProcessRunners.clear();
   
-  // Reset flags
+  // Reset signal handler flags
   sigintHandlerInstalled = false;
   sigintHandler = null;
   
   trace('SignalHandler', () => `Force cleanup completed - removed ${commandStreamListeners.length} handlers`);
 }
 
+// Complete global state reset for testing - clears all library state
+function resetGlobalState() {
+  // CRITICAL: Restore working directory first before anything else
+  // This MUST succeed or tests will fail with spawn errors
+  try {
+    // Try to get current directory - this might fail if we're in a deleted directory
+    let currentDir;
+    try {
+      currentDir = process.cwd();
+    } catch (e) {
+      // Can't even get cwd, we're in a deleted directory
+      currentDir = null;
+    }
+    
+    // Always try to restore to initial directory
+    if (!currentDir || currentDir !== initialWorkingDirectory) {
+      // Check if initial directory still exists
+      if (fs.existsSync(initialWorkingDirectory)) {
+        process.chdir(initialWorkingDirectory);
+        trace('GlobalState', () => `Restored working directory from ${currentDir} to ${initialWorkingDirectory}`);
+      } else {
+        // Initial directory is gone, use fallback
+        const fallback = process.env.HOME || '/workspace/command-stream' || '/';
+        if (fs.existsSync(fallback)) {
+          process.chdir(fallback);
+          trace('GlobalState', () => `Initial directory gone, changed to fallback: ${fallback}`);
+        } else {
+          // Last resort - try root
+          process.chdir('/');
+          trace('GlobalState', () => `Emergency fallback to root directory`);
+        }
+      }
+    }
+  } catch (e) {
+    trace('GlobalState', () => `Critical error restoring working directory: ${e.message}`);
+    // This is critical - we MUST have a valid working directory
+    try {
+      // Try home directory
+      if (process.env.HOME && fs.existsSync(process.env.HOME)) {
+        process.chdir(process.env.HOME);
+      } else {
+        // Last resort - root
+        process.chdir('/');
+      }
+    } catch (e2) {
+      console.error('FATAL: Cannot set any working directory!', e2);
+    }
+  }
+  
+  // First, properly clean up all active ProcessRunners
+  for (const runner of activeProcessRunners) {
+    if (runner) {
+      try {
+        // If the runner was never started, clean it up
+        if (!runner.started) {
+          trace('resetGlobalState', () => `Cleaning up unstarted ProcessRunner: ${runner.spec?.command?.slice(0, 50)}`);
+          // Call the cleanup method to properly release resources
+          if (runner._cleanup) {
+            runner._cleanup();
+          }
+        } else if (runner.kill) {
+          // For started runners, kill them
+          runner.kill();
+        }
+      } catch (e) {
+        // Ignore errors
+        trace('resetGlobalState', () => `Error during cleanup: ${e.message}`);
+      }
+    }
+  }
+  
+  // Call existing cleanup
+  forceCleanupAll();
+  
+  // Clear shell cache to force re-detection with our fixed logic
+  cachedShell = null;
+  
+  // Reset parent stream monitoring
+  parentStreamsMonitored = false;
+  
+  // Reset shell settings to defaults
+  globalShellSettings = {
+    xtrace: false,
+    errexit: false,
+    pipefail: false,
+    verbose: false,
+    noglob: false,
+    allexport: false
+  };
+  
+  // Don't clear virtual commands - they should persist across tests
+  // Just make sure they're enabled
+  virtualCommandsEnabled = true;
+  
+  // Reset ANSI config to defaults
+  globalAnsiConfig = {
+    forceColor: false,
+    noColor: false
+  };
+  
+  // Make sure built-in virtual commands are registered
+  if (virtualCommands.size === 0) {
+    // Re-import to re-register commands (synchronously if possible)
+    trace('GlobalState', () => 'Re-registering virtual commands');
+    import('./commands/index.mjs').then(() => {
+      trace('GlobalState', () => `Virtual commands re-registered, count: ${virtualCommands.size}`);
+    }).catch((e) => {
+      trace('GlobalState', () => `Error re-registering virtual commands: ${e.message}`);
+    });
+  }
+  
+  trace('GlobalState', () => 'Global state reset completed');
+}
+
 function monitorParentStreams() {
   if (parentStreamsMonitored) {
     trace('StreamMonitor', () => 'Parent streams already monitored, skipping');
@@ -503,6 +661,12 @@ class StreamEmitter {
   }
 
   on(event, listener) {
+    trace('StreamEmitter', () => `on() called | ${JSON.stringify({ 
+      event,
+      hasExistingListeners: this.listeners.has(event),
+      listenerCount: this.listeners.get(event)?.length || 0
+    })}`);
+    
     if (!this.listeners.has(event)) {
       this.listeners.set(event, []);
     }
@@ -514,6 +678,7 @@ class StreamEmitter {
   }
 
   once(event, listener) {
+    trace('StreamEmitter', () => `once() called for event: ${event}`);
     const onceWrapper = (...args) => {
       this.off(event, onceWrapper);
       listener(...args);
@@ -539,11 +704,18 @@ class StreamEmitter {
   }
 
   off(event, listener) {
+    trace('StreamEmitter', () => `off() called | ${JSON.stringify({ 
+      event,
+      hasListeners: !!this.listeners.get(event),
+      listenerCount: this.listeners.get(event)?.length || 0
+    })}`);
+    
     const eventListeners = this.listeners.get(event);
     if (eventListeners) {
       const index = eventListeners.indexOf(listener);
       if (index !== -1) {
         eventListeners.splice(index, 1);
+        trace('StreamEmitter', () => `Removed listener at index ${index}`);
       }
     }
     return this;
@@ -555,6 +727,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, "'\\''")}'`;
 }
 
@@ -585,16 +787,28 @@ function buildShellCommand(strings, values) {
 }
 
 function asBuffer(chunk) {
-  if (Buffer.isBuffer(chunk)) return chunk;
-  if (typeof chunk === 'string') return Buffer.from(chunk);
+  if (Buffer.isBuffer(chunk)) {
+    trace('Utils', () => `asBuffer: Already a buffer, length: ${chunk.length}`);
+    return chunk;
+  }
+  if (typeof chunk === 'string') {
+    trace('Utils', () => `asBuffer: Converting string to buffer, length: ${chunk.length}`);
+    return Buffer.from(chunk);
+  }
+  trace('Utils', () => 'asBuffer: Converting unknown type to buffer');
   return Buffer.from(chunk);
 }
 
 async function pumpReadable(readable, onChunk) {
-  if (!readable) return;
+  if (!readable) {
+    trace('Utils', () => 'pumpReadable: No readable stream provided');
+    return;
+  }
+  trace('Utils', () => 'pumpReadable: Starting to pump readable stream');
   for await (const chunk of readable) {
     await onChunk(asBuffer(chunk));
   }
+  trace('Utils', () => 'pumpReadable: Finished pumping readable stream');
 }
 
 // Enhanced process runner with streaming capabilities
@@ -614,6 +828,8 @@ class ProcessRunner extends StreamEmitter {
       stdin: 'inherit',
       cwd: undefined,
       env: undefined,
+      interactive: false, // Explicitly request TTY forwarding for interactive commands
+      shellOperators: true, // Enable shell operator parsing by default
       ...options
     };
 
@@ -654,14 +870,26 @@ class ProcessRunner extends StreamEmitter {
 
   // Stream property getters for child process streams (null for virtual commands)
   get stdout() {
+    trace('ProcessRunner', () => `stdout getter accessed | ${JSON.stringify({
+      hasChild: !!this.child,
+      hasStdout: !!(this.child && this.child.stdout)
+    }, null, 2)}`);
     return this.child ? this.child.stdout : null;
   }
 
   get stderr() {
+    trace('ProcessRunner', () => `stderr getter accessed | ${JSON.stringify({
+      hasChild: !!this.child,
+      hasStderr: !!(this.child && this.child.stderr)
+    }, null, 2)}`);
     return this.child ? this.child.stderr : null;
   }
 
   get stdin() {
+    trace('ProcessRunner', () => `stdin getter accessed | ${JSON.stringify({
+      hasChild: !!this.child,
+      hasStdin: !!(this.child && this.child.stdin)
+    }, null, 2)}`);
     return this.child ? this.child.stdin : null;
   }
 
@@ -989,7 +1217,13 @@ class ProcessRunner extends StreamEmitter {
   }
 
   async _forwardTTYStdin() {
+    trace('ProcessRunner', () => `_forwardTTYStdin ENTER | ${JSON.stringify({
+      isTTY: process.stdin.isTTY,
+      hasChildStdin: !!this.child?.stdin
+    }, null, 2)}`);
+    
     if (!process.stdin.isTTY || !this.child.stdin) {
+      trace('ProcessRunner', () => 'TTY forwarding skipped - no TTY or no child stdin');
       return;
     }
 
@@ -1042,6 +1276,7 @@ class ProcessRunner extends StreamEmitter {
       };
 
       const cleanup = () => {
+        trace('ProcessRunner', () => 'TTY stdin cleanup - restoring terminal mode');
         process.stdin.removeListener('data', onData);
         if (process.stdin.setRawMode) {
           process.stdin.setRawMode(false);
@@ -1395,6 +1630,49 @@ class ProcessRunner extends StreamEmitter {
     if (this.spec.mode === 'shell') {
       trace('ProcessRunner', () => `BRANCH: spec.mode => shell | ${JSON.stringify({}, null, 2)}`);
 
+      // Check if shell operator parsing is enabled and command contains operators
+      const hasShellOperators = this.spec.command.includes('&&') || 
+                                this.spec.command.includes('||') || 
+                                this.spec.command.includes('(') ||
+                                this.spec.command.includes(';') ||
+                                (this.spec.command.includes('cd ') && this.spec.command.includes('&&'));
+      
+      // Intelligent detection: disable shell operators for streaming patterns
+      const isStreamingPattern = this.spec.command.includes('sleep') && this.spec.command.includes(';') && 
+                                 (this.spec.command.includes('echo') || this.spec.command.includes('printf'));
+      
+      // Also check if we're in streaming mode (via .stream() method)
+      const shouldUseShellOperators = this.options.shellOperators && hasShellOperators && !isStreamingPattern && !this._isStreaming;
+      
+      trace('ProcessRunner', () => `Shell operator detection | ${JSON.stringify({
+        hasShellOperators,
+        shellOperatorsEnabled: this.options.shellOperators,
+        isStreamingPattern,
+        isStreaming: this._isStreaming,
+        shouldUseShellOperators,
+        command: this.spec.command.slice(0, 100)
+      }, null, 2)}`);
+      
+      // Only use enhanced parser when appropriate
+      if (!this.options._bypassVirtual && shouldUseShellOperators && !needsRealShell(this.spec.command)) {
+        const enhancedParsed = parseShellCommand(this.spec.command);
+        if (enhancedParsed && enhancedParsed.type !== 'simple') {
+          trace('ProcessRunner', () => `Using enhanced parser for shell operators | ${JSON.stringify({
+            type: enhancedParsed.type,
+            command: this.spec.command.slice(0, 50)
+          }, null, 2)}`);
+          
+          if (enhancedParsed.type === 'sequence') {
+            return await this._runSequence(enhancedParsed);
+          } else if (enhancedParsed.type === 'subshell') {
+            return await this._runSubshell(enhancedParsed);
+          } else if (enhancedParsed.type === 'pipeline') {
+            return await this._runPipeline(enhancedParsed.commands);
+          }
+        }
+      }
+
+      // Fallback to original simple parser
       const parsed = this._parseCommand(this.spec.command);
       trace('ProcessRunner', () => `Parsed command | ${JSON.stringify({
         type: parsed?.type,
@@ -1442,7 +1720,8 @@ class ProcessRunner extends StreamEmitter {
       }
     }
 
-    const argv = this.spec.mode === 'shell' ? ['sh', '-lc', this.spec.command] : [this.spec.file, ...this.spec.args];
+    const shell = findAvailableShell();
+    const argv = this.spec.mode === 'shell' ? [shell.cmd, ...shell.args, this.spec.command] : [this.spec.file, ...this.spec.args];
     trace('ProcessRunner', () => `Constructed argv | ${JSON.stringify({
       mode: this.spec.mode,
       argv: argv,
@@ -1462,12 +1741,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 +1754,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) => {
@@ -1500,6 +1779,14 @@ class ProcessRunner extends StreamEmitter {
       // For non-interactive commands, spawn with detached to create process group (for proper signal handling)
       // This allows us to send signals to the entire process group, killing shell and all its children
       trace('ProcessRunner', () => `spawnBun: Using non-interactive mode with pipes and detached=${process.platform !== 'win32'}`);
+      trace('ProcessRunner', () => `spawnBun: About to spawn | ${JSON.stringify({
+        argv,
+        cwd,
+        shellCmd: argv[0],
+        shellArgs: argv.slice(1, -1),
+        command: argv[argv.length - 1]?.slice(0, 50)
+      }, null, 2)}`);
+      
       const child = Bun.spawn(argv, { 
         cwd, 
         env, 
@@ -1850,7 +2137,16 @@ class ProcessRunner extends StreamEmitter {
   }
 
   async _pumpStdinTo(child, captureChunks) {
-    if (!child.stdin) return;
+    trace('ProcessRunner', () => `_pumpStdinTo ENTER | ${JSON.stringify({
+      hasChildStdin: !!child?.stdin,
+      willCapture: !!captureChunks,
+      isBun
+    }, null, 2)}`);
+    
+    if (!child.stdin) {
+      trace('ProcessRunner', () => 'No child stdin to pump to');
+      return;
+    }
     const bunWriter = isBun && child.stdin && typeof child.stdin.getWriter === 'function' ? child.stdin.getWriter() : null;
     for await (const chunk of process.stdin) {
       const buf = asBuffer(chunk);
@@ -1868,6 +2164,11 @@ class ProcessRunner extends StreamEmitter {
   }
 
   async _writeToStdin(buf) {
+    trace('ProcessRunner', () => `_writeToStdin ENTER | ${JSON.stringify({
+      bufferLength: buf?.length || 0,
+      hasChildStdin: !!this.child?.stdin
+    }, null, 2)}`);
+    
     const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf.buffer, buf.byteOffset ?? 0, buf.byteLength);
     if (await StreamUtils.writeToStream(this.child.stdin, bytes, 'stdin')) {
       // Successfully wrote to stream
@@ -1882,8 +2183,16 @@ class ProcessRunner extends StreamEmitter {
   }
 
   _parseCommand(command) {
+    trace('ProcessRunner', () => `_parseCommand ENTER | ${JSON.stringify({
+      commandLength: command?.length || 0,
+      preview: command?.slice(0, 50)
+    }, null, 2)}`);
+    
     const trimmed = command.trim();
-    if (!trimmed) return null;
+    if (!trimmed) {
+      trace('ProcessRunner', () => 'Empty command after trimming');
+      return null;
+    }
 
     if (trimmed.includes('|')) {
       return this._parsePipeline(trimmed);
@@ -1907,6 +2216,11 @@ class ProcessRunner extends StreamEmitter {
   }
 
   _parsePipeline(command) {
+    trace('ProcessRunner', () => `_parsePipeline ENTER | ${JSON.stringify({
+      commandLength: command?.length || 0,
+      hasPipe: command?.includes('|')
+    }, null, 2)}`);
+    
     // Split by pipe, respecting quotes
     const segments = [];
     let current = '';
@@ -2214,8 +2528,17 @@ class ProcessRunner extends StreamEmitter {
 
       return result;
     } catch (error) {
+      // Check if this is a cancellation error
+      let exitCode = error.code ?? 1;
+      if (this._cancelled && this._cancellationSignal) {
+        // Use appropriate exit code based on the signal
+        exitCode = this._cancellationSignal === 'SIGINT' ? 130 : 
+                   this._cancellationSignal === 'SIGTERM' ? 143 : 1;
+        trace('ProcessRunner', () => `Virtual command error during cancellation, using signal-based exit code: ${exitCode}`);
+      }
+      
       const result = {
-        code: error.code ?? 1,
+        code: exitCode,
         stdout: error.stdout ?? '',
         stderr: error.stderr ?? error.message,
         stdin: ''
@@ -2336,8 +2659,9 @@ class ProcessRunner extends StreamEmitter {
         commandStr.includes('&&') || commandStr.includes('||') ||
         commandStr.includes(';') || commandStr.includes('`');
 
+      const shell = findAvailableShell();
       const spawnArgs = needsShell
-        ? ['sh', '-c', commandStr]
+        ? [shell.cmd, ...shell.args.filter(arg => arg !== '-l'), commandStr]
         : [cmd, ...args.map(a => a.value !== undefined ? a.value : a)];
 
       const proc = Bun.spawn(spawnArgs, {
@@ -2499,8 +2823,9 @@ class ProcessRunner extends StreamEmitter {
         commandStr.includes('&&') || commandStr.includes('||') ||
         commandStr.includes(';') || commandStr.includes('`');
 
+      const shell = findAvailableShell();
       const spawnArgs = needsShell
-        ? ['sh', '-c', commandStr]
+        ? [shell.cmd, ...shell.args.filter(arg => arg !== '-l'), commandStr]
         : [cmd, ...args.map(a => a.value !== undefined ? a.value : a)];
 
       const proc = Bun.spawn(spawnArgs, {
@@ -2737,7 +3062,8 @@ class ProcessRunner extends StreamEmitter {
         }
         const commandStr = commandParts.join(' ');
 
-        const proc = Bun.spawn(['sh', '-c', commandStr], {
+        const shell = findAvailableShell();
+        const proc = Bun.spawn([shell.cmd, ...shell.args.filter(arg => arg !== '-l'), commandStr], {
           cwd: this.options.cwd,
           env: this.options.env,
           stdin: currentInputStream ? 'pipe' : 'ignore',
@@ -3125,7 +3451,8 @@ class ProcessRunner extends StreamEmitter {
           };
 
           // Execute using shell to handle complex commands
-          const argv = ['sh', '-c', commandStr];
+          const shell = findAvailableShell();
+          const argv = [shell.cmd, ...shell.args.filter(arg => arg !== '-l'), commandStr];
           const isLastCommand = (i === commands.length - 1);
           const proc = await spawnNodeAsync(argv, currentInput, isLastCommand);
 
@@ -3300,14 +3627,181 @@ class ProcessRunner extends StreamEmitter {
     }
   }
 
+  async _runSequence(sequence) {
+    trace('ProcessRunner', () => `_runSequence ENTER | ${JSON.stringify({
+      commandCount: sequence.commands.length,
+      operators: sequence.operators
+    }, null, 2)}`);
+
+    let lastResult = { code: 0, stdout: '', stderr: '' };
+    let combinedStdout = '';
+    let combinedStderr = '';
+    
+    for (let i = 0; i < sequence.commands.length; i++) {
+      const command = sequence.commands[i];
+      const operator = i > 0 ? sequence.operators[i - 1] : null;
+      
+      trace('ProcessRunner', () => `Executing command ${i} | ${JSON.stringify({
+        command: command.type,
+        operator,
+        lastCode: lastResult.code
+      }, null, 2)}`);
+      
+      // Check operator conditions
+      if (operator === '&&' && lastResult.code !== 0) {
+        trace('ProcessRunner', () => `Skipping due to && with exit code ${lastResult.code}`);
+        continue;
+      }
+      if (operator === '||' && lastResult.code === 0) {
+        trace('ProcessRunner', () => `Skipping due to || with exit code ${lastResult.code}`);
+        continue;
+      }
+      
+      // Execute command based on type
+      if (command.type === 'subshell') {
+        lastResult = await this._runSubshell(command);
+      } else if (command.type === 'pipeline') {
+        lastResult = await this._runPipeline(command.commands);
+      } else if (command.type === 'sequence') {
+        lastResult = await this._runSequence(command);
+      } else if (command.type === 'simple') {
+        lastResult = await this._runSimpleCommand(command);
+      }
+      
+      // Accumulate output
+      combinedStdout += lastResult.stdout;
+      combinedStderr += lastResult.stderr;
+    }
+    
+    return {
+      code: lastResult.code,
+      stdout: combinedStdout,
+      stderr: combinedStderr,
+      async text() {
+        return combinedStdout;
+      }
+    };
+  }
+
+  async _runSubshell(subshell) {
+    trace('ProcessRunner', () => `_runSubshell ENTER | ${JSON.stringify({
+      commandType: subshell.command.type
+    }, null, 2)}`);
+    
+    // Save current directory
+    const savedCwd = process.cwd();
+    
+    try {
+      // Execute subshell command
+      let result;
+      if (subshell.command.type === 'sequence') {
+        result = await this._runSequence(subshell.command);
+      } else if (subshell.command.type === 'pipeline') {
+        result = await this._runPipeline(subshell.command.commands);
+      } else if (subshell.command.type === 'simple') {
+        result = await this._runSimpleCommand(subshell.command);
+      } else {
+        result = { code: 0, stdout: '', stderr: '' };
+      }
+      
+      return result;
+    } finally {
+      // Restore directory - check if it still exists first
+      trace('ProcessRunner', () => `Restoring cwd from ${process.cwd()} to ${savedCwd}`);
+      const fs = await import('fs');
+      if (fs.existsSync(savedCwd)) {
+        process.chdir(savedCwd);
+      } else {
+        // If the saved directory was deleted, try to go to a safe location
+        const fallbackDir = process.env.HOME || process.env.USERPROFILE || '/';
+        trace('ProcessRunner', () => `Saved directory ${savedCwd} no longer exists, falling back to ${fallbackDir}`);
+        try {
+          process.chdir(fallbackDir);
+        } catch (e) {
+          // If even fallback fails, just stay where we are
+          trace('ProcessRunner', () => `Failed to restore directory: ${e.message}`);
+        }
+      }
+    }
+  }
+
+  async _runSimpleCommand(command) {
+    trace('ProcessRunner', () => `_runSimpleCommand ENTER | ${JSON.stringify({
+      cmd: command.cmd,
+      argsCount: command.args?.length || 0,
+      hasRedirects: !!command.redirects
+    }, null, 2)}`);
+    
+    const { cmd, args, redirects } = command;
+    
+    // Check for virtual command
+    if (virtualCommandsEnabled && virtualCommands.has(cmd)) {
+      trace('ProcessRunner', () => `Using virtual command: ${cmd}`);
+      const argValues = args.map(a => a.value || a);
+      const result = await this._runVirtual(cmd, argValues);
+      
+      // Handle output redirection for virtual commands
+      if (redirects && redirects.length > 0) {
+        for (const redirect of redirects) {
+          if (redirect.type === '>' || redirect.type === '>>') {
+            const fs = await import('fs');
+            if (redirect.type === '>') {
+              fs.writeFileSync(redirect.target, result.stdout);
+            } else {
+              fs.appendFileSync(redirect.target, result.stdout);
+            }
+            // Clear stdout since it was redirected
+            result.stdout = '';
+          }
+        }
+      }
+      
+      return result;
+    }
+    
+    // Build command string for real execution
+    let commandStr = cmd;
+    for (const arg of args) {
+      if (arg.quoted && arg.quoteChar) {
+        commandStr += ` ${arg.quoteChar}${arg.value}${arg.quoteChar}`;
+      } else if (arg.value !== undefined) {
+        commandStr += ` ${arg.value}`;
+      } else {
+        commandStr += ` ${arg}`;
+      }
+    }
+    
+    // Add redirections
+    if (redirects) {
+      for (const redirect of redirects) {
+        commandStr += ` ${redirect.type} ${redirect.target}`;
+      }
+    }
+    
+    trace('ProcessRunner', () => `Executing real command: ${commandStr}`);
+    
+    // Create a new ProcessRunner for the real command
+    // Use current working directory since cd virtual command may have changed it
+    const runner = new ProcessRunner(
+      { mode: 'shell', command: commandStr },
+      { ...this.options, cwd: process.cwd(), _bypassVirtual: true }
+    );
+    
+    return await runner;
+  }
+
   async* stream() {
     trace('ProcessRunner', () => `stream ENTER | ${JSON.stringify({
       started: this.started,
-      finished: this.finished
+      finished: this.finished,
+      command: this.spec?.command?.slice(0, 100)
     }, null, 2)}`);
 
+    // Mark that we're in streaming mode to bypass shell operator interception
+    this._isStreaming = true;
+
     if (!this.started) {
-      trace('ProcessRunner', () => 'Auto-starting async process from stream()');
+      trace('ProcessRunner', () => 'Auto-starting async process from stream() with streaming mode');
       this._startAsync(); // Start but don't await
     }
 
@@ -3631,6 +4125,12 @@ class ProcessRunner extends StreamEmitter {
 
   // Promise interface (for await)
   then(onFulfilled, onRejected) {
+    trace('ProcessRunner', () => `then() called | ${JSON.stringify({
+      hasPromise: !!this.promise,
+      started: this.started,
+      finished: this.finished
+    }, null, 2)}`);
+    
     if (!this.promise) {
       this.promise = this._startAsync();
     }
@@ -3638,6 +4138,12 @@ class ProcessRunner extends StreamEmitter {
   }
 
   catch(onRejected) {
+    trace('ProcessRunner', () => `catch() called | ${JSON.stringify({
+      hasPromise: !!this.promise,
+      started: this.started,
+      finished: this.finished
+    }, null, 2)}`);
+    
     if (!this.promise) {
       this.promise = this._startAsync();
     }
@@ -3645,6 +4151,12 @@ class ProcessRunner extends StreamEmitter {
   }
 
   finally(onFinally) {
+    trace('ProcessRunner', () => `finally() called | ${JSON.stringify({
+      hasPromise: !!this.promise,
+      started: this.started,
+      finished: this.finished
+    }, null, 2)}`);
+    
     if (!this.promise) {
       this.promise = this._startAsync();
     }
@@ -3681,7 +4193,8 @@ class ProcessRunner extends StreamEmitter {
     trace('ProcessRunner', () => `Starting sync execution | ${JSON.stringify({ mode: this._mode }, null, 2)}`);
 
     const { cwd, env, stdin } = this.options;
-    const argv = this.spec.mode === 'shell' ? ['sh', '-lc', this.spec.command] : [this.spec.file, ...this.spec.args];
+    const shell = findAvailableShell();
+    const argv = this.spec.mode === 'shell' ? [shell.cmd, ...shell.args, this.spec.command] : [this.spec.file, ...this.spec.args];
 
     if (globalShellSettings.xtrace) {
       const traceCmd = this.spec.mode === 'shell' ? this.spec.command : argv.join(' ');
@@ -3873,10 +4386,12 @@ function create(defaultOptions = {}) {
 }
 
 function raw(value) {
+  trace('API', () => `raw() called with value: ${String(value).slice(0, 50)}`);
   return { raw: String(value) };
 }
 
 function set(option) {
+  trace('API', () => `set() called with option: ${option}`);
   const mapping = {
     'e': 'errexit',     // set -e: exit on error
     'errexit': 'errexit',
@@ -3900,6 +4415,7 @@ function set(option) {
 }
 
 function unset(option) {
+  trace('API', () => `unset() called with option: ${option}`);
   const mapping = {
     'e': 'errexit',
     'errexit': 'errexit',
@@ -3952,15 +4468,19 @@ function unregister(name) {
 }
 
 function listCommands() {
-  return Array.from(virtualCommands.keys());
+  const commands = Array.from(virtualCommands.keys());
+  trace('VirtualCommands', () => `listCommands() returning ${commands.length} commands`);
+  return commands;
 }
 
 function enableVirtualCommands() {
+  trace('VirtualCommands', () => 'Enabling virtual commands');
   virtualCommandsEnabled = true;
   return virtualCommandsEnabled;
 }
 
 function disableVirtualCommands() {
+  trace('VirtualCommands', () => 'Disabling virtual commands');
   virtualCommandsEnabled = false;
   return virtualCommandsEnabled;
 }
@@ -3990,6 +4510,7 @@ import testCommand from './commands/$.test.mjs';
 
 // Built-in commands that match Bun.$ functionality
 function registerBuiltins() {
+  trace('VirtualCommands', () => 'registerBuiltins() called - registering all built-in commands');
   // Register all imported commands
   register('cd', cdCommand);
   register('pwd', pwdCommand);
@@ -4024,12 +4545,14 @@ const AnsiUtils = {
 
   stripControlChars(text) {
     if (typeof text !== 'string') return text;
-    return text.replace(/[\x00-\x1F\x7F]/g, '');
+    // Preserve newlines (\n = \x0A), carriage returns (\r = \x0D), and tabs (\t = \x09)
+    return text.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '');
   },
 
   stripAll(text) {
     if (typeof text !== 'string') return text;
-    return text.replace(/[\x00-\x1F\x7F]|\x1b\[[0-9;]*[mGKHFJ]/g, '');
+    // Preserve newlines (\n = \x0A), carriage returns (\r = \x0D), and tabs (\t = \x09)
+    return text.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]|\x1b\[[0-9;]*[mGKHFJ]/g, '');
   },
 
   cleanForProcessing(data) {
@@ -4046,15 +4569,23 @@ let globalAnsiConfig = {
 };
 
 function configureAnsi(options = {}) {
+  trace('AnsiUtils', () => `configureAnsi() called | ${JSON.stringify({ options }, null, 2)}`);
   globalAnsiConfig = { ...globalAnsiConfig, ...options };
+  trace('AnsiUtils', () => `New ANSI config | ${JSON.stringify({ globalAnsiConfig }, null, 2)}`);
   return globalAnsiConfig;
 }
 
 function getAnsiConfig() {
+  trace('AnsiUtils', () => `getAnsiConfig() returning | ${JSON.stringify({ globalAnsiConfig }, null, 2)}`);
   return { ...globalAnsiConfig };
 }
 
 function processOutput(data, options = {}) {
+  trace('AnsiUtils', () => `processOutput() called | ${JSON.stringify({ 
+    dataType: typeof data,
+    dataLength: Buffer.isBuffer(data) ? data.length : data?.length,
+    options 
+  }, null, 2)}`);
   const config = { ...globalAnsiConfig, ...options };
   if (!config.preserveAnsi && !config.preserveControlChars) {
     return AnsiUtils.cleanForProcessing(data);
@@ -4071,7 +4602,9 @@ function processOutput(data, options = {}) {
 }
 
 // Initialize built-in commands
+trace('Initialization', () => 'Registering built-in virtual commands');
 registerBuiltins();
+trace('Initialization', () => `Built-in commands registered: ${listCommands().join(', ')}`);
 
 export {
   $tagged as $,
@@ -4084,6 +4617,7 @@ export {
   ProcessRunner,
   shell,
   set,
+  resetGlobalState,
   unset,
   register,
   unregister,