command-stream 0.6.0 → 0.7.1

package/package.json

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

package/src/$.mjs

@@ -7,6 +7,8 @@
 
 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';
 
@@ -21,6 +23,73 @@ function trace(category, messageOrFunc) {
   console.error(`[TRACE ${timestamp}] [${category}] ${message}`);
 }
 
+// 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;
+  }
+
+  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
@@ -211,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');
@@ -478,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, []);
     }
@@ -489,6 +678,7 @@ class StreamEmitter {
   }
 
   once(event, listener) {
+    trace('StreamEmitter', () => `once() called for event: ${event}`);
     const onceWrapper = (...args) => {
       this.off(event, onceWrapper);
       listener(...args);
@@ -514,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;
@@ -569,6 +766,20 @@ function buildShellCommand(strings, values) {
     valuesLength: values.length
   }, null, 2)}`);
 
+  // Special case: if we have a single value with empty surrounding strings,
+  // and the value looks like a complete shell command, treat it as raw
+  if (values.length === 1 && strings.length === 2 && 
+      strings[0] === '' && strings[1] === '' &&
+      typeof values[0] === 'string') {
+    const commandStr = values[0];
+    // Check if this looks like a complete shell command (contains spaces and shell-safe characters)
+    const commandPattern = /^[a-zA-Z0-9_\-./=,+@:\s"'`$(){}<>|&;*?[\]~\\]+$/;
+    if (commandPattern.test(commandStr) && commandStr.trim().length > 0) {
+      trace('Utils', () => `BRANCH: buildShellCommand => COMPLETE_COMMAND | ${JSON.stringify({ command: commandStr }, null, 2)}`);
+      return commandStr;
+    }
+  }
+
   let out = '';
   for (let i = 0; i < strings.length; i++) {
     out += strings[i];
@@ -590,16 +801,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
@@ -620,6 +843,7 @@ class ProcessRunner extends StreamEmitter {
       cwd: undefined,
       env: undefined,
       interactive: false, // Explicitly request TTY forwarding for interactive commands
+      shellOperators: true, // Enable shell operator parsing by default
       ...options
     };
 
@@ -660,14 +884,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;
   }
 
@@ -995,7 +1231,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;
     }
 
@@ -1048,6 +1290,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);
@@ -1401,6 +1644,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,
@@ -1448,7 +1734,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,
@@ -1506,6 +1793,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, 
@@ -1856,7 +2151,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);
@@ -1874,6 +2178,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
@@ -1888,8 +2197,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);
@@ -1913,6 +2230,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 = '';
@@ -2220,8 +2542,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: ''
@@ -2342,8 +2673,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, {
@@ -2505,8 +2837,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, {
@@ -2743,7 +3076,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',
@@ -3131,7 +3465,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);
 
@@ -3306,14 +3641,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
     }
 
@@ -3637,6 +4139,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();
     }
@@ -3644,6 +4152,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();
     }
@@ -3651,6 +4165,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();
     }
@@ -3687,7 +4207,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(' ');
@@ -3879,10 +4400,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',
@@ -3906,6 +4429,7 @@ function set(option) {
 }
 
 function unset(option) {
+  trace('API', () => `unset() called with option: ${option}`);
   const mapping = {
     'e': 'errexit',
     'errexit': 'errexit',
@@ -3958,15 +4482,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;
 }
@@ -3996,6 +4524,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);
@@ -4030,12 +4559,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) {
@@ -4052,15 +4583,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);
@@ -4077,7 +4616,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 $,
@@ -4090,6 +4631,7 @@ export {
   ProcessRunner,
   shell,
   set,
+  resetGlobalState,
   unset,
   register,
   unregister,

package/src/commands/$.cd.mjs

@@ -8,9 +8,10 @@ export default async function cd({ args }) {
     process.chdir(target);
     const newDir = process.cwd();
     trace('VirtualCommand', () => `cd: success | ${JSON.stringify({ newDir }, null, 2)}`);
-    return VirtualUtils.success(newDir);
+    // cd command should not output anything on success, just like real cd
+    return VirtualUtils.success('');
   } catch (error) {
     trace('VirtualCommand', () => `cd: failed | ${JSON.stringify({ error: error.message }, null, 2)}`);
-    return { stderr: `cd: ${error.message}`, code: 1 };
+    return { stderr: `cd: ${error.message}\n`, code: 1 };
   }
 }

package/src/commands/$.pwd.mjs

@@ -4,5 +4,5 @@ export default async function pwd({ args, stdin, cwd }) {
   // If cwd option is provided, return that instead of process.cwd()
   const dir = cwd || process.cwd();
   trace('VirtualCommand', () => `pwd: getting directory | ${JSON.stringify({ dir }, null, 2)}`);
-  return VirtualUtils.success(dir);
+  return VirtualUtils.success(dir + '\n');
 }

package/src/shell-parser.mjs

@@ -0,0 +1,375 @@
+/**
+ * Enhanced shell command parser that handles &&, ||, ;, and () operators
+ * This allows virtual commands to work properly with shell operators
+ */
+
+import { trace } from './$.utils.mjs';
+
+/**
+ * Token types for the parser
+ */
+const TokenType = {
+  WORD: 'word',
+  AND: '&&',
+  OR: '||',
+  SEMICOLON: ';',
+  PIPE: '|',
+  LPAREN: '(',
+  RPAREN: ')',
+  REDIRECT_OUT: '>',
+  REDIRECT_APPEND: '>>',
+  REDIRECT_IN: '<',
+  EOF: 'eof'
+};
+
+/**
+ * Tokenize a shell command string
+ */
+function tokenize(command) {
+  const tokens = [];
+  let i = 0;
+  
+  while (i < command.length) {
+    // Skip whitespace
+    while (i < command.length && /\s/.test(command[i])) {
+      i++;
+    }
+    
+    if (i >= command.length) break;
+    
+    // Check for operators
+    if (command[i] === '&' && command[i + 1] === '&') {
+      tokens.push({ type: TokenType.AND, value: '&&' });
+      i += 2;
+    } else if (command[i] === '|' && command[i + 1] === '|') {
+      tokens.push({ type: TokenType.OR, value: '||' });
+      i += 2;
+    } else if (command[i] === '|') {
+      tokens.push({ type: TokenType.PIPE, value: '|' });
+      i++;
+    } else if (command[i] === ';') {
+      tokens.push({ type: TokenType.SEMICOLON, value: ';' });
+      i++;
+    } else if (command[i] === '(') {
+      tokens.push({ type: TokenType.LPAREN, value: '(' });
+      i++;
+    } else if (command[i] === ')') {
+      tokens.push({ type: TokenType.RPAREN, value: ')' });
+      i++;
+    } else if (command[i] === '>' && command[i + 1] === '>') {
+      tokens.push({ type: TokenType.REDIRECT_APPEND, value: '>>' });
+      i += 2;
+    } else if (command[i] === '>') {
+      tokens.push({ type: TokenType.REDIRECT_OUT, value: '>' });
+      i++;
+    } else if (command[i] === '<') {
+      tokens.push({ type: TokenType.REDIRECT_IN, value: '<' });
+      i++;
+    } else {
+      // Parse word (respecting quotes)
+      let word = '';
+      let inQuote = false;
+      let quoteChar = '';
+      
+      while (i < command.length) {
+        const char = command[i];
+        
+        if (!inQuote) {
+          if (char === '"' || char === "'") {
+            inQuote = true;
+            quoteChar = char;
+            word += char;
+            i++;
+          } else if (/\s/.test(char) || 
+                     '&|;()<>'.includes(char)) {
+            break;
+          } else if (char === '\\' && i + 1 < command.length) {
+            // Handle escape sequences
+            word += char;
+            i++;
+            if (i < command.length) {
+              word += command[i];
+              i++;
+            }
+          } else {
+            word += char;
+            i++;
+          }
+        } else {
+          if (char === quoteChar && command[i - 1] !== '\\') {
+            inQuote = false;
+            quoteChar = '';
+            word += char;
+            i++;
+          } else if (char === '\\' && i + 1 < command.length && 
+                     (command[i + 1] === quoteChar || command[i + 1] === '\\')) {
+            // Handle escaped quotes and backslashes inside quotes
+            word += char;
+            i++;
+            if (i < command.length) {
+              word += command[i];
+              i++;
+            }
+          } else {
+            word += char;
+            i++;
+          }
+        }
+      }
+      
+      if (word) {
+        tokens.push({ type: TokenType.WORD, value: word });
+      }
+    }
+  }
+  
+  tokens.push({ type: TokenType.EOF, value: '' });
+  return tokens;
+}
+
+/**
+ * Parse a sequence of commands with operators
+ */
+class ShellParser {
+  constructor(command) {
+    this.tokens = tokenize(command);
+    this.pos = 0;
+  }
+  
+  current() {
+    return this.tokens[this.pos] || { type: TokenType.EOF, value: '' };
+  }
+  
+  peek() {
+    return this.tokens[this.pos + 1] || { type: TokenType.EOF, value: '' };
+  }
+  
+  consume() {
+    const token = this.current();
+    this.pos++;
+    return token;
+  }
+  
+  /**
+   * Parse the main command sequence
+   */
+  parse() {
+    return this.parseSequence();
+  }
+  
+  /**
+   * Parse a sequence of commands connected by &&, ||, ;
+   */
+  parseSequence() {
+    const commands = [];
+    const operators = [];
+    
+    // Parse first command
+    let cmd = this.parsePipeline();
+    if (cmd) {
+      commands.push(cmd);
+    }
+    
+    // Parse additional commands with operators
+    while (this.current().type !== TokenType.EOF && 
+           this.current().type !== TokenType.RPAREN) {
+      const op = this.current();
+      
+      if (op.type === TokenType.AND || 
+          op.type === TokenType.OR || 
+          op.type === TokenType.SEMICOLON) {
+        operators.push(op.type);
+        this.consume();
+        
+        cmd = this.parsePipeline();
+        if (cmd) {
+          commands.push(cmd);
+        }
+      } else {
+        break;
+      }
+    }
+    
+    if (commands.length === 1 && operators.length === 0) {
+      return commands[0];
+    }
+    
+    return {
+      type: 'sequence',
+      commands,
+      operators
+    };
+  }
+  
+  /**
+   * Parse a pipeline (commands connected by |)
+   */
+  parsePipeline() {
+    const commands = [];
+    
+    let cmd = this.parseCommand();
+    if (cmd) {
+      commands.push(cmd);
+    }
+    
+    while (this.current().type === TokenType.PIPE) {
+      this.consume();
+      cmd = this.parseCommand();
+      if (cmd) {
+        commands.push(cmd);
+      }
+    }
+    
+    if (commands.length === 1) {
+      return commands[0];
+    }
+    
+    return {
+      type: 'pipeline',
+      commands
+    };
+  }
+  
+  /**
+   * Parse a single command or subshell
+   */
+  parseCommand() {
+    // Check for subshell
+    if (this.current().type === TokenType.LPAREN) {
+      this.consume(); // consume (
+      const subshell = this.parseSequence();
+      
+      if (this.current().type === TokenType.RPAREN) {
+        this.consume(); // consume )
+      }
+      
+      return {
+        type: 'subshell',
+        command: subshell
+      };
+    }
+    
+    // Parse simple command
+    return this.parseSimpleCommand();
+  }
+  
+  /**
+   * Parse a simple command (command + args + redirections)
+   */
+  parseSimpleCommand() {
+    const words = [];
+    const redirects = [];
+    
+    while (this.current().type !== TokenType.EOF) {
+      const token = this.current();
+      
+      if (token.type === TokenType.WORD) {
+        words.push(token.value);
+        this.consume();
+      } else if (token.type === TokenType.REDIRECT_OUT || 
+                 token.type === TokenType.REDIRECT_APPEND ||
+                 token.type === TokenType.REDIRECT_IN) {
+        this.consume();
+        const target = this.current();
+        if (target.type === TokenType.WORD) {
+          redirects.push({
+            type: token.type,
+            target: target.value
+          });
+          this.consume();
+        }
+      } else {
+        break;
+      }
+    }
+    
+    if (words.length === 0) {
+      return null;
+    }
+    
+    const cmd = words[0];
+    const args = words.slice(1).map(word => {
+      // Remove quotes if present
+      if ((word.startsWith('"') && word.endsWith('"')) ||
+          (word.startsWith("'") && word.endsWith("'"))) {
+        return {
+          value: word.slice(1, -1),
+          quoted: true,
+          quoteChar: word[0]
+        };
+      }
+      return {
+        value: word,
+        quoted: false
+      };
+    });
+    
+    const result = {
+      type: 'simple',
+      cmd,
+      args
+    };
+    
+    if (redirects.length > 0) {
+      result.redirects = redirects;
+    }
+    
+    return result;
+  }
+}
+
+/**
+ * Parse a shell command with support for &&, ||, ;, and ()
+ */
+export function parseShellCommand(command) {
+  try {
+    const parser = new ShellParser(command);
+    const result = parser.parse();
+    
+    trace('ShellParser', () => `Parsed command | ${JSON.stringify({
+      input: command.slice(0, 100),
+      result
+    }, null, 2)}`);
+    
+    return result;
+  } catch (error) {
+    trace('ShellParser', () => `Parse error | ${JSON.stringify({
+      command: command.slice(0, 100),
+      error: error.message
+    }, null, 2)}`);
+    
+    // Return null to fallback to sh -c
+    return null;
+  }
+}
+
+/**
+ * Check if a command needs shell features we don't handle
+ */
+export function needsRealShell(command) {
+  // Check for features we don't handle yet
+  const unsupported = [
+    '`',     // Command substitution
+    '$(',    // Command substitution
+    '${',    // Variable expansion
+    '~',     // Home expansion (at start of word)
+    '*',     // Glob patterns
+    '?',     // Glob patterns
+    '[',     // Glob patterns
+    '2>',    // stderr redirection
+    '&>',    // Combined redirection
+    '>&',    // File descriptor duplication
+    '<<',    // Here documents
+    '<<<',   // Here strings
+  ];
+  
+  for (const feature of unsupported) {
+    if (command.includes(feature)) {
+      return true;
+    }
+  }
+  
+  return false;
+}
+
+export default { parseShellCommand, needsRealShell };