command-stream 0.0.4 → 0.1.0

package/$.mjs

@@ -10,6 +10,32 @@ import { fileURLToPath } from 'url';
 
 const isBun = typeof globalThis.Bun !== 'undefined';
 
+// Verbose tracing for debugging (enabled in CI or when COMMAND_STREAM_VERBOSE is set)
+const VERBOSE = process.env.COMMAND_STREAM_VERBOSE === 'true' || process.env.CI === 'true';
+
+// Trace function for verbose logging
+function trace(category, message, data = {}) {
+  if (!VERBOSE) return;
+  
+  const timestamp = new Date().toISOString();
+  const dataStr = Object.keys(data).length > 0 ? ' | ' + JSON.stringify(data) : '';
+  console.error(`[TRACE ${timestamp}] [${category}] ${message}${dataStr}`);
+}
+
+// Trace decision branches
+function traceBranch(category, condition, branch, data = {}) {
+  if (!VERBOSE) return;
+  
+  trace(category, `BRANCH: ${condition} => ${branch}`, data);
+}
+
+// Trace function entry/exit
+function traceFunc(category, funcName, phase, data = {}) {
+  if (!VERBOSE) return;
+  
+  trace(category, `${funcName} ${phase}`, data);
+}
+
 // Global shell settings (like bash set -e / set +e)
 let globalShellSettings = {
   errexit: false,    // set -e equivalent: exit on error
@@ -50,6 +76,9 @@ class StreamEmitter {
       this.listeners.set(event, []);
     }
     this.listeners.get(event).push(listener);
+    
+    // No auto-start - explicit start() or await will start the process
+    
     return this;
   }
 
@@ -84,18 +113,28 @@ function quote(value) {
 }
 
 function buildShellCommand(strings, values) {
+  traceFunc('Utils', 'buildShellCommand', 'ENTER', { 
+    stringsLength: strings.length,
+    valuesLength: values.length
+  });
+  
   let out = '';
   for (let i = 0; i < strings.length; i++) {
     out += strings[i];
     if (i < values.length) {
       const v = values[i];
       if (v && typeof v === 'object' && Object.prototype.hasOwnProperty.call(v, 'raw')) {
+        traceBranch('Utils', 'buildShellCommand', 'RAW_VALUE', { value: String(v.raw) });
         out += String(v.raw);
       } else {
-        out += quote(v);
+        const quoted = quote(v);
+        traceBranch('Utils', 'buildShellCommand', 'QUOTED_VALUE', { original: v, quoted });
+        out += quoted;
       }
     }
   }
+  
+  traceFunc('Utils', 'buildShellCommand', 'EXIT', { command: out });
   return out;
 }
 
@@ -116,6 +155,12 @@ async function pumpReadable(readable, onChunk) {
 class ProcessRunner extends StreamEmitter {
   constructor(spec, options = {}) {
     super();
+    
+    traceFunc('ProcessRunner', 'constructor', 'ENTER', { 
+      spec: typeof spec === 'object' ? { ...spec, command: spec.command?.slice(0, 100) } : spec,
+      options 
+    });
+    
     this.spec = spec;
     this.options = {
       mirror: true,
@@ -139,27 +184,92 @@ class ProcessRunner extends StreamEmitter {
     
     // Promise for awaiting final result
     this.promise = null;
+    
+    // Track the execution mode
+    this._mode = null; // 'async' or 'sync'
+    
+    // Cancellation support for virtual commands
+    this._cancelled = false;
+    this._virtualGenerator = null;
+    this._abortController = new AbortController();
   }
 
-  async _start() {
-    if (this.started) return;
+  // Unified start method that can work in both async and sync modes
+  start(options = {}) {
+    const mode = options.mode || 'async';
+    
+    traceFunc('ProcessRunner', 'start', 'ENTER', { mode, options });
+    
+    if (mode === 'sync') {
+      traceBranch('ProcessRunner', 'mode', 'sync', {});
+      return this._startSync();
+    } else {
+      traceBranch('ProcessRunner', 'mode', 'async', {});
+      return this._startAsync();
+    }
+  }
+  
+  // Shortcut for sync mode
+  sync() {
+    return this.start({ mode: 'sync' });
+  }
+  
+  // Shortcut for async mode
+  async() {
+    return this.start({ mode: 'async' });
+  }
+  
+  async _startAsync() {
+    if (this.started) return this.promise;
+    if (this.promise) return this.promise;
+    
+    this.promise = this._doStartAsync();
+    return this.promise;
+  }
+  
+  async _doStartAsync() {
+    traceFunc('ProcessRunner', '_doStartAsync', 'ENTER', { 
+      mode: this.spec.mode,
+      command: this.spec.command?.slice(0, 100)
+    });
+    
     this.started = true;
+    this._mode = 'async';
 
     const { cwd, env, stdin } = this.options;
     
     // Handle programmatic pipeline mode
     if (this.spec.mode === 'pipeline') {
+      traceBranch('ProcessRunner', 'spec.mode', 'pipeline', { 
+        hasSource: !!this.spec.source,
+        hasDestination: !!this.spec.destination
+      });
       return await this._runProgrammaticPipeline(this.spec.source, this.spec.destination);
     }
     
     // Check if this is a virtual command first
     if (this.spec.mode === 'shell') {
+      traceBranch('ProcessRunner', 'spec.mode', 'shell', {});
+      
       // Parse the command to check for virtual commands or pipelines
       const parsed = this._parseCommand(this.spec.command);
+      trace('ProcessRunner', 'Parsed command', { 
+        type: parsed?.type,
+        cmd: parsed?.cmd,
+        argsCount: parsed?.args?.length
+      });
+      
       if (parsed) {
         if (parsed.type === 'pipeline') {
+          traceBranch('ProcessRunner', 'parsed.type', 'pipeline', { 
+            commandCount: parsed.commands?.length 
+          });
           return await this._runPipeline(parsed.commands);
         } else if (parsed.type === 'simple' && virtualCommandsEnabled && virtualCommands.has(parsed.cmd)) {
+          traceBranch('ProcessRunner', 'virtualCommand', parsed.cmd, { 
+            isVirtual: true,
+            args: parsed.args 
+          });
           return await this._runVirtual(parsed.cmd, parsed.args);
         }
       }
@@ -236,8 +346,16 @@ class ProcessRunner extends StreamEmitter {
     const code = await exited;
     await Promise.all([outPump, errPump, stdinPumpPromise]);
 
-    const resultData = {
+    // Debug: Check the raw exit code
+    trace('ProcessRunner', 'Raw exit code from child', { 
       code,
+      codeType: typeof code,
+      childExitCode: this.child?.exitCode,
+      isBun
+    });
+
+    const resultData = {
+      code: code ?? 0,  // Default to 0 if exit code is null/undefined
       stdout: this.options.capture ? Buffer.concat(this.outChunks).toString('utf8') : undefined,
       stderr: this.options.capture ? Buffer.concat(this.errChunks).toString('utf8') : undefined,
       stdin: this.options.capture && this.inChunks ? Buffer.concat(this.inChunks).toString('utf8') : undefined,
@@ -311,12 +429,12 @@ class ProcessRunner extends StreamEmitter {
     
     const cmd = parts[0];
     const args = parts.slice(1).map(arg => {
-      // Remove quotes if present
+      // Keep track of whether the arg was quoted
       if ((arg.startsWith('"') && arg.endsWith('"')) || 
           (arg.startsWith("'") && arg.endsWith("'"))) {
-        return arg.slice(1, -1);
+        return { value: arg.slice(1, -1), quoted: true, quoteChar: arg[0] };
       }
-      return arg;
+      return { value: arg, quoted: false };
     });
     
     return { cmd, args, type: 'simple' };
@@ -359,11 +477,13 @@ class ProcessRunner extends StreamEmitter {
       
       const cmd = parts[0];
       const args = parts.slice(1).map(arg => {
+        // Keep track of whether the arg was quoted
         if ((arg.startsWith('"') && arg.endsWith('"')) || 
             (arg.startsWith("'") && arg.endsWith("'"))) {
-          return arg.slice(1, -1);
+          // Store the original with quotes for system commands
+          return { value: arg.slice(1, -1), quoted: true, quoteChar: arg[0] };
         }
-        return arg;
+        return { value: arg, quoted: false };
       });
       
       return { cmd, args };
@@ -373,11 +493,19 @@ class ProcessRunner extends StreamEmitter {
   }
 
   async _runVirtual(cmd, args) {
+    traceFunc('ProcessRunner', '_runVirtual', 'ENTER', { cmd, args });
+    
     const handler = virtualCommands.get(cmd);
     if (!handler) {
+      trace('ProcessRunner', 'Virtual command not found', { cmd });
       throw new Error(`Virtual command not found: ${cmd}`);
     }
 
+    trace('ProcessRunner', 'Found virtual command handler', { 
+      cmd,
+      isGenerator: handler.constructor.name === 'AsyncGeneratorFunction'
+    });
+
     try {
       // Prepare stdin
       let stdinData = '';
@@ -387,12 +515,15 @@ class ProcessRunner extends StreamEmitter {
         stdinData = this.options.stdin.toString('utf8');
       }
 
+      // Extract actual values for virtual command
+      const argValues = args.map(arg => arg.value !== undefined ? arg.value : arg);
+
       // Shell tracing for virtual commands
       if (globalShellSettings.xtrace) {
-        console.log(`+ ${cmd} ${args.join(' ')}`);
+        console.log(`+ ${cmd} ${argValues.join(' ')}`);
       }
       if (globalShellSettings.verbose) {
-        console.log(`${cmd} ${args.join(' ')}`);
+        console.log(`${cmd} ${argValues.join(' ')}`);
       }
 
       // Execute the virtual command
@@ -400,18 +531,65 @@ class ProcessRunner extends StreamEmitter {
       
       // Check if handler is async generator (streaming)
       if (handler.constructor.name === 'AsyncGeneratorFunction') {
-        // Handle streaming virtual command
+        // Handle streaming virtual command with cancellation support
         const chunks = [];
-        for await (const chunk of handler(args, stdinData, this.options)) {
-          const buf = Buffer.from(chunk);
-          chunks.push(buf);
+        
+        // Create options with cancellation check and abort signal
+        const commandOptions = {
+          ...this.options,
+          isCancelled: () => this._cancelled,
+          signal: this._abortController.signal
+        };
+        
+        const generator = handler(argValues, stdinData, commandOptions);
+        this._virtualGenerator = generator;
+        
+        // Create a promise that resolves when cancelled
+        const cancelPromise = new Promise(resolve => {
+          this._cancelResolve = resolve;
+        });
+        
+        try {
+          const iterator = generator[Symbol.asyncIterator]();
+          let done = false;
           
-          if (this.options.mirror) {
-            process.stdout.write(buf);
+          while (!done && !this._cancelled) {
+            // Race between getting next value and cancellation
+            const result = await Promise.race([
+              iterator.next(),
+              cancelPromise.then(() => ({ done: true, cancelled: true }))
+            ]);
+            
+            if (result.cancelled || this._cancelled) {
+              // Cancelled - close the generator
+              if (iterator.return) {
+                await iterator.return();
+              }
+              break;
+            }
+            
+            done = result.done;
+            
+            if (!done) {
+              const chunk = result.value;
+              const buf = Buffer.from(chunk);
+              chunks.push(buf);
+              
+              // Only output if not cancelled
+              if (!this._cancelled) {
+                if (this.options.mirror) {
+                  process.stdout.write(buf);
+                }
+                
+                this.emit('stdout', buf);
+                this.emit('data', { type: 'stdout', data: buf });
+              }
+            }
           }
-          
-          this.emit('stdout', buf);
-          this.emit('data', { type: 'stdout', data: buf });
+        } finally {
+          // Clean up
+          this._virtualGenerator = null;
+          this._cancelResolve = null;
         }
         
         result = {
@@ -422,7 +600,7 @@ class ProcessRunner extends StreamEmitter {
         };
       } else {
         // Regular async function
-        result = await handler(args, stdinData, this.options);
+        result = await handler(argValues, stdinData, this.options);
         
         // Ensure result has required fields, respecting capture option
         result = {
@@ -489,26 +667,642 @@ class ProcessRunner extends StreamEmitter {
         if (this.options.mirror) {
           process.stderr.write(buf);
         }
-        this.emit('stderr', buf);
-        this.emit('data', { type: 'stderr', data: buf });
-      }
-      
-      this.emit('end', result);
-      this.emit('exit', result.code);
-      
-      if (globalShellSettings.errexit) {
-        throw error;
+        this.emit('stderr', buf);
+        this.emit('data', { type: 'stderr', data: buf });
+      }
+      
+      this.emit('end', result);
+      this.emit('exit', result.code);
+      
+      if (globalShellSettings.errexit) {
+        throw error;
+      }
+      
+      return result;
+    }
+  }
+
+  async _runStreamingPipelineBun(commands) {
+    traceFunc('ProcessRunner', '_runStreamingPipelineBun', 'ENTER', { 
+      commandsCount: commands.length 
+    });
+    
+    // For true streaming, we need to handle virtual and real commands differently
+    // but make them work together seamlessly
+    
+    // First, analyze the pipeline to identify virtual vs real commands
+    const pipelineInfo = commands.map(command => {
+      const { cmd, args } = command;
+      const isVirtual = virtualCommandsEnabled && virtualCommands.has(cmd);
+      return { ...command, isVirtual };
+    });
+    
+    trace('ProcessRunner', 'Pipeline analysis', { 
+      virtualCount: pipelineInfo.filter(p => p.isVirtual).length,
+      realCount: pipelineInfo.filter(p => !p.isVirtual).length 
+    });
+    
+    // If pipeline contains virtual commands, use advanced streaming
+    if (pipelineInfo.some(info => info.isVirtual)) {
+      traceBranch('ProcessRunner', '_runStreamingPipelineBun', 'MIXED_PIPELINE', {});
+      return this._runMixedStreamingPipeline(commands);
+    }
+    
+    // For pipelines with commands that buffer (like jq), use tee streaming
+    const needsStreamingWorkaround = commands.some(c => 
+      c.cmd === 'jq' || c.cmd === 'grep' || c.cmd === 'sed' || c.cmd === 'cat' || c.cmd === 'awk'
+    );
+    if (needsStreamingWorkaround) {
+      traceBranch('ProcessRunner', '_runStreamingPipelineBun', 'TEE_STREAMING', { 
+        bufferedCommands: commands.filter(c => 
+          ['jq', 'grep', 'sed', 'cat', 'awk'].includes(c.cmd)
+        ).map(c => c.cmd)
+      });
+      return this._runTeeStreamingPipeline(commands);
+    }
+    
+    // All real commands - use native pipe connections
+    const processes = [];
+    let allStderr = '';
+    
+    for (let i = 0; i < commands.length; i++) {
+      const command = commands[i];
+      const { cmd, args } = command;
+      
+      // Build command string
+      const commandParts = [cmd];
+      for (const arg of args) {
+        if (arg.value !== undefined) {
+          if (arg.quoted) {
+            commandParts.push(`${arg.quoteChar}${arg.value}${arg.quoteChar}`);
+          } else if (arg.value.includes(' ')) {
+            commandParts.push(`"${arg.value}"`);
+          } else {
+            commandParts.push(arg.value);
+          }
+        } else {
+          if (typeof arg === 'string' && arg.includes(' ') && !arg.startsWith('"') && !arg.startsWith("'")) {
+            commandParts.push(`"${arg}"`);
+          } else {
+            commandParts.push(arg);
+          }
+        }
+      }
+      const commandStr = commandParts.join(' ');
+      
+      // Determine stdin for this process
+      let stdin;
+      let needsManualStdin = false;
+      let stdinData;
+      
+      if (i === 0) {
+        // First command - use provided stdin or pipe
+        if (this.options.stdin && typeof this.options.stdin === 'string') {
+          stdin = 'pipe';
+          needsManualStdin = true;
+          stdinData = Buffer.from(this.options.stdin);
+        } else if (this.options.stdin && Buffer.isBuffer(this.options.stdin)) {
+          stdin = 'pipe';
+          needsManualStdin = true;
+          stdinData = this.options.stdin;
+        } else {
+          stdin = 'ignore';
+        }
+      } else {
+        // Connect to previous process stdout
+        stdin = processes[i - 1].stdout;
+      }
+      
+      // Spawn the process directly (not through sh) for better streaming
+      // Only use sh -c for complex commands that need shell features
+      const needsShell = commandStr.includes('*') || commandStr.includes('$') || 
+                         commandStr.includes('>') || commandStr.includes('<') ||
+                         commandStr.includes('&&') || commandStr.includes('||') ||
+                         commandStr.includes(';') || commandStr.includes('`');
+      
+      const spawnArgs = needsShell 
+        ? ['sh', '-c', commandStr]
+        : [cmd, ...args.map(a => a.value !== undefined ? a.value : a)];
+      
+      const proc = Bun.spawn(spawnArgs, {
+        cwd: this.options.cwd,
+        env: this.options.env,
+        stdin: stdin,
+        stdout: 'pipe',
+        stderr: 'pipe'
+      });
+      
+      // Write stdin data if needed for first process
+      if (needsManualStdin && stdinData && proc.stdin) {
+        (async () => {
+          try {
+            // Bun's FileSink has write and end methods
+            await proc.stdin.write(stdinData);
+            await proc.stdin.end();
+          } catch (e) {
+            console.error('Error writing stdin:', e);
+          }
+        })();
+      }
+      
+      processes.push(proc);
+      
+      // Collect stderr from all processes
+      (async () => {
+        for await (const chunk of proc.stderr) {
+          const buf = Buffer.from(chunk);
+          allStderr += buf.toString();
+          // Only emit stderr for the last command
+          if (i === commands.length - 1) {
+            if (this.options.mirror) {
+              process.stderr.write(buf);
+            }
+            this.emit('stderr', buf);
+            this.emit('data', { type: 'stderr', data: buf });
+          }
+        }
+      })();
+    }
+    
+    // Stream output from the last process
+    const lastProc = processes[processes.length - 1];
+    let finalOutput = '';
+    
+    // Stream stdout from last process
+    for await (const chunk of lastProc.stdout) {
+      const buf = Buffer.from(chunk);
+      finalOutput += buf.toString();
+      if (this.options.mirror) {
+        process.stdout.write(buf);
+      }
+      this.emit('stdout', buf);
+      this.emit('data', { type: 'stdout', data: buf });
+    }
+    
+    // Wait for all processes to complete
+    const exitCodes = await Promise.all(processes.map(p => p.exited));
+    const lastExitCode = exitCodes[exitCodes.length - 1];
+    
+    // Check for pipeline failures if pipefail is set
+    if (globalShellSettings.pipefail) {
+      const failedIndex = exitCodes.findIndex(code => code !== 0);
+      if (failedIndex !== -1) {
+        const error = new Error(`Pipeline command at index ${failedIndex} failed with exit code ${exitCodes[failedIndex]}`);
+        error.code = exitCodes[failedIndex];
+        throw error;
+      }
+    }
+    
+    const result = createResult({
+      code: lastExitCode || 0,
+      stdout: finalOutput,
+      stderr: allStderr,
+      stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
+             this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
+    });
+    
+    this.result = result;
+    this.finished = true;
+    
+    this.emit('end', result);
+    this.emit('exit', result.code);
+    
+    if (globalShellSettings.errexit && result.code !== 0) {
+      const error = new Error(`Pipeline failed with exit code ${result.code}`);
+      error.code = result.code;
+      error.stdout = result.stdout;
+      error.stderr = result.stderr;
+      error.result = result;
+      throw error;
+    }
+    
+    return result;
+  }
+
+  async _runTeeStreamingPipeline(commands) {
+    traceFunc('ProcessRunner', '_runTeeStreamingPipeline', 'ENTER', { 
+      commandsCount: commands.length 
+    });
+    
+    // Use tee() to split streams for real-time reading
+    // This works around jq and similar commands that buffer when piped
+    
+    const processes = [];
+    let allStderr = '';
+    let currentStream = null;
+    
+    for (let i = 0; i < commands.length; i++) {
+      const command = commands[i];
+      const { cmd, args } = command;
+      
+      // Build command string
+      const commandParts = [cmd];
+      for (const arg of args) {
+        if (arg.value !== undefined) {
+          if (arg.quoted) {
+            commandParts.push(`${arg.quoteChar}${arg.value}${arg.quoteChar}`);
+          } else if (arg.value.includes(' ')) {
+            commandParts.push(`"${arg.value}"`);
+          } else {
+            commandParts.push(arg.value);
+          }
+        } else {
+          if (typeof arg === 'string' && arg.includes(' ') && !arg.startsWith('"') && !arg.startsWith("'")) {
+            commandParts.push(`"${arg}"`);
+          } else {
+            commandParts.push(arg);
+          }
+        }
+      }
+      const commandStr = commandParts.join(' ');
+      
+      // Determine stdin for this process
+      let stdin;
+      let needsManualStdin = false;
+      let stdinData;
+      
+      if (i === 0) {
+        // First command - use provided stdin or ignore
+        if (this.options.stdin && typeof this.options.stdin === 'string') {
+          stdin = 'pipe';
+          needsManualStdin = true;
+          stdinData = Buffer.from(this.options.stdin);
+        } else if (this.options.stdin && Buffer.isBuffer(this.options.stdin)) {
+          stdin = 'pipe';
+          needsManualStdin = true;
+          stdinData = this.options.stdin;
+        } else {
+          stdin = 'ignore';
+        }
+      } else {
+        // Use the stream from previous process
+        stdin = currentStream;
+      }
+      
+      // Spawn the process directly (not through sh) for better control
+      const needsShell = commandStr.includes('*') || commandStr.includes('$') || 
+                         commandStr.includes('>') || commandStr.includes('<') ||
+                         commandStr.includes('&&') || commandStr.includes('||') ||
+                         commandStr.includes(';') || commandStr.includes('`');
+      
+      const spawnArgs = needsShell 
+        ? ['sh', '-c', commandStr]
+        : [cmd, ...args.map(a => a.value !== undefined ? a.value : a)];
+      
+      const proc = Bun.spawn(spawnArgs, {
+        cwd: this.options.cwd,
+        env: this.options.env,
+        stdin: stdin,
+        stdout: 'pipe',
+        stderr: 'pipe'
+      });
+      
+      // Write stdin data if needed for first process
+      if (needsManualStdin && stdinData && proc.stdin) {
+        try {
+          await proc.stdin.write(stdinData);
+          await proc.stdin.end();
+        } catch (e) {
+          // Ignore stdin errors
+        }
+      }
+      
+      processes.push(proc);
+      
+      // For non-last processes, tee the output so we can both pipe and read
+      if (i < commands.length - 1) {
+        const [readStream, pipeStream] = proc.stdout.tee();
+        currentStream = pipeStream;
+        
+        // Read from the tee'd stream for real-time updates
+        // Always read from the first process for best streaming
+        if (i === 0) {
+          (async () => {
+            for await (const chunk of readStream) {
+              // Emit from the first process for real-time updates
+              const buf = Buffer.from(chunk);
+              if (this.options.mirror) {
+                process.stdout.write(buf);
+              }
+              this.emit('stdout', buf);
+              this.emit('data', { type: 'stdout', data: buf });
+            }
+          })();
+        } else {
+          // Consume other tee'd streams to prevent blocking
+          (async () => {
+            for await (const chunk of readStream) {
+              // Just consume to keep flowing
+            }
+          })();
+        }
+      } else {
+        currentStream = proc.stdout;
+      }
+      
+      // Collect stderr from all processes
+      (async () => {
+        for await (const chunk of proc.stderr) {
+          const buf = Buffer.from(chunk);
+          allStderr += buf.toString();
+          if (i === commands.length - 1) {
+            if (this.options.mirror) {
+              process.stderr.write(buf);
+            }
+            this.emit('stderr', buf);
+            this.emit('data', { type: 'stderr', data: buf });
+          }
+        }
+      })();
+    }
+    
+    // Read final output from the last process
+    const lastProc = processes[processes.length - 1];
+    let finalOutput = '';
+    
+    // If we haven't emitted stdout yet (no tee), emit from last process
+    const shouldEmitFromLast = commands.length === 1;
+    
+    for await (const chunk of lastProc.stdout) {
+      const buf = Buffer.from(chunk);
+      finalOutput += buf.toString();
+      if (shouldEmitFromLast) {
+        if (this.options.mirror) {
+          process.stdout.write(buf);
+        }
+        this.emit('stdout', buf);
+        this.emit('data', { type: 'stdout', data: buf });
+      }
+    }
+    
+    // Wait for all processes to complete
+    const exitCodes = await Promise.all(processes.map(p => p.exited));
+    const lastExitCode = exitCodes[exitCodes.length - 1];
+    
+    // Check for pipeline failures if pipefail is set
+    if (globalShellSettings.pipefail) {
+      const failedIndex = exitCodes.findIndex(code => code !== 0);
+      if (failedIndex !== -1) {
+        const error = new Error(`Pipeline command at index ${failedIndex} failed with exit code ${exitCodes[failedIndex]}`);
+        error.code = exitCodes[failedIndex];
+        throw error;
+      }
+    }
+    
+    const result = createResult({
+      code: lastExitCode || 0,
+      stdout: finalOutput,
+      stderr: allStderr,
+      stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
+             this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
+    });
+    
+    this.result = result;
+    this.finished = true;
+    
+    this.emit('end', result);
+    this.emit('exit', result.code);
+    
+    if (globalShellSettings.errexit && result.code !== 0) {
+      const error = new Error(`Pipeline failed with exit code ${result.code}`);
+      error.code = result.code;
+      error.stdout = result.stdout;
+      error.stderr = result.stderr;
+      error.result = result;
+      throw error;
+    }
+    
+    return result;
+  }
+
+
+  async _runMixedStreamingPipeline(commands) {
+    traceFunc('ProcessRunner', '_runMixedStreamingPipeline', 'ENTER', { 
+      commandsCount: commands.length 
+    });
+    
+    // Handle pipelines with both virtual and real commands
+    // Each stage reads from previous stage's output stream
+    
+    let currentInputStream = null;
+    let finalOutput = '';
+    let allStderr = '';
+    
+    // Set up initial input stream if provided
+    if (this.options.stdin) {
+      const inputData = typeof this.options.stdin === 'string' 
+        ? this.options.stdin 
+        : this.options.stdin.toString('utf8');
+      
+      // Create a readable stream from the input
+      currentInputStream = new ReadableStream({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode(inputData));
+          controller.close();
+        }
+      });
+    }
+    
+    for (let i = 0; i < commands.length; i++) {
+      const command = commands[i];
+      const { cmd, args } = command;
+      const isLastCommand = i === commands.length - 1;
+      
+      if (virtualCommandsEnabled && virtualCommands.has(cmd)) {
+        // Handle virtual command with streaming
+        traceBranch('ProcessRunner', '_runMixedStreamingPipeline', 'VIRTUAL_COMMAND', { 
+          cmd,
+          commandIndex: i 
+        });
+        const handler = virtualCommands.get(cmd);
+        const argValues = args.map(arg => arg.value !== undefined ? arg.value : arg);
+        
+        // Read input from stream if available
+        let inputData = '';
+        if (currentInputStream) {
+          const reader = currentInputStream.getReader();
+          try {
+            while (true) {
+              const { done, value } = await reader.read();
+              if (done) break;
+              inputData += new TextDecoder().decode(value);
+            }
+          } finally {
+            reader.releaseLock();
+          }
+        }
+        
+        // Check if handler is async generator (streaming)
+        if (handler.constructor.name === 'AsyncGeneratorFunction') {
+          // Create output stream from generator
+          const chunks = [];
+          const self = this; // Capture this context
+          currentInputStream = new ReadableStream({
+            async start(controller) {
+              for await (const chunk of handler(argValues, inputData, {})) {
+                const data = Buffer.from(chunk);
+                controller.enqueue(data);
+                
+                // Emit for last command
+                if (isLastCommand) {
+                  chunks.push(data);
+                  if (self.options.mirror) {
+                    process.stdout.write(data);
+                  }
+                  self.emit('stdout', data);
+                  self.emit('data', { type: 'stdout', data });
+                }
+              }
+              controller.close();
+              
+              if (isLastCommand) {
+                finalOutput = Buffer.concat(chunks).toString('utf8');
+              }
+            }
+          });
+        } else {
+          // Regular async function
+          const result = await handler(argValues, inputData, {});
+          const outputData = result.stdout || '';
+          
+          if (isLastCommand) {
+            finalOutput = outputData;
+            const buf = Buffer.from(outputData);
+            if (this.options.mirror) {
+              process.stdout.write(buf);
+            }
+            this.emit('stdout', buf);
+            this.emit('data', { type: 'stdout', data: buf });
+          }
+          
+          // Create stream from output
+          currentInputStream = new ReadableStream({
+            start(controller) {
+              controller.enqueue(new TextEncoder().encode(outputData));
+              controller.close();
+            }
+          });
+          
+          if (result.stderr) {
+            allStderr += result.stderr;
+          }
+        }
+      } else {
+        // Handle real command - spawn with streaming
+        const commandParts = [cmd];
+        for (const arg of args) {
+          if (arg.value !== undefined) {
+            if (arg.quoted) {
+              commandParts.push(`${arg.quoteChar}${arg.value}${arg.quoteChar}`);
+            } else if (arg.value.includes(' ')) {
+              commandParts.push(`"${arg.value}"`);
+            } else {
+              commandParts.push(arg.value);
+            }
+          } else {
+            if (typeof arg === 'string' && arg.includes(' ') && !arg.startsWith('"') && !arg.startsWith("'")) {
+              commandParts.push(`"${arg}"`);
+            } else {
+              commandParts.push(arg);
+            }
+          }
+        }
+        const commandStr = commandParts.join(' ');
+        
+        // Spawn the process
+        const proc = Bun.spawn(['sh', '-c', commandStr], {
+          cwd: this.options.cwd,
+          env: this.options.env,
+          stdin: currentInputStream ? 'pipe' : 'ignore',
+          stdout: 'pipe',
+          stderr: 'pipe'
+        });
+        
+        // Write input stream to process stdin if needed
+        if (currentInputStream && proc.stdin) {
+          const reader = currentInputStream.getReader();
+          const writer = proc.stdin.getWriter ? proc.stdin.getWriter() : proc.stdin;
+          
+          (async () => {
+            try {
+              while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+                if (writer.write) {
+                  await writer.write(value);
+                } else if (writer.getWriter) {
+                  const w = writer.getWriter();
+                  await w.write(value);
+                  w.releaseLock();
+                }
+              }
+            } finally {
+              reader.releaseLock();
+              if (writer.close) await writer.close();
+              else if (writer.end) writer.end();
+            }
+          })();
+        }
+        
+        // Set up output stream
+        currentInputStream = proc.stdout;
+        
+        // Handle stderr
+        (async () => {
+          for await (const chunk of proc.stderr) {
+            const buf = Buffer.from(chunk);
+            allStderr += buf.toString();
+            if (isLastCommand) {
+              if (this.options.mirror) {
+                process.stderr.write(buf);
+              }
+              this.emit('stderr', buf);
+              this.emit('data', { type: 'stderr', data: buf });
+            }
+          }
+        })();
+        
+        // For last command, stream output
+        if (isLastCommand) {
+          const chunks = [];
+          for await (const chunk of proc.stdout) {
+            const buf = Buffer.from(chunk);
+            chunks.push(buf);
+            if (this.options.mirror) {
+              process.stdout.write(buf);
+            }
+            this.emit('stdout', buf);
+            this.emit('data', { type: 'stdout', data: buf });
+          }
+          finalOutput = Buffer.concat(chunks).toString('utf8');
+          await proc.exited;
+        }
       }
-      
-      return result;
     }
+    
+    const result = createResult({
+      code: 0, // TODO: Track exit codes properly
+      stdout: finalOutput,
+      stderr: allStderr,
+      stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
+             this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
+    });
+    
+    this.result = result;
+    this.finished = true;
+    
+    this.emit('end', result);
+    this.emit('exit', result.code);
+    
+    return result;
   }
 
-  async _runPipeline(commands) {
-    if (commands.length === 0) {
-      return createResult({ code: 1, stdout: '', stderr: 'No commands in pipeline', stdin: '' });
-    }
-
+  async _runPipelineNonStreaming(commands) {
+    traceFunc('ProcessRunner', '_runPipelineNonStreaming', 'ENTER', { 
+      commandsCount: commands.length 
+    });
+    
+    // Original non-streaming implementation for fallback (e.g., virtual commands)
     let currentOutput = '';
     let currentInput = '';
     
@@ -524,26 +1318,35 @@ class ProcessRunner extends StreamEmitter {
       const command = commands[i];
       const { cmd, args } = command;
       
-      // Check if this is a virtual command
+      // Check if this is a virtual command (only if virtual commands are enabled)
       if (virtualCommandsEnabled && virtualCommands.has(cmd)) {
+        traceBranch('ProcessRunner', '_runPipelineNonStreaming', 'VIRTUAL_COMMAND', { 
+          cmd,
+          argsCount: args.length 
+        });
+        
         // Run virtual command with current input
         const handler = virtualCommands.get(cmd);
         
         try {
+          // Extract actual values for virtual command
+          const argValues = args.map(arg => arg.value !== undefined ? arg.value : arg);
+          
           // Shell tracing for virtual commands
           if (globalShellSettings.xtrace) {
-            console.log(`+ ${cmd} ${args.join(' ')}`);
+            console.log(`+ ${cmd} ${argValues.join(' ')}`);
           }
           if (globalShellSettings.verbose) {
-            console.log(`${cmd} ${args.join(' ')}`);
+            console.log(`${cmd} ${argValues.join(' ')}`);
           }
 
           let result;
           
           // Check if handler is async generator (streaming)
           if (handler.constructor.name === 'AsyncGeneratorFunction') {
+            traceBranch('ProcessRunner', '_runPipelineNonStreaming', 'ASYNC_GENERATOR', { cmd });
             const chunks = [];
-            for await (const chunk of handler(args, currentInput, this.options)) {
+            for await (const chunk of handler(argValues, currentInput, this.options)) {
               chunks.push(Buffer.from(chunk));
             }
             result = {
@@ -554,7 +1357,7 @@ class ProcessRunner extends StreamEmitter {
             };
           } else {
             // Regular async function
-            result = await handler(args, currentInput, this.options);
+            result = await handler(argValues, currentInput, this.options);
             result = {
               code: result.code ?? 0,
               stdout: this.options.capture ? (result.stdout ?? '') : undefined,
@@ -660,54 +1463,262 @@ class ProcessRunner extends StreamEmitter {
           return result;
         }
       } else {
-        // For system commands in pipeline, we would need to spawn processes
-        // For now, return an error indicating this isn't supported
-        const result = createResult({
-          code: 1,
-          stdout: currentOutput,
-          stderr: `Pipeline with system command '${cmd}' not yet supported`,
-          stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
-                 this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
-        });
-        
-        this.result = result;
-        this.finished = true;
-        
-        const buf = Buffer.from(result.stderr);
-        if (this.options.mirror) {
-          process.stderr.write(buf);
+        // Execute system command in pipeline
+        try {
+          // Build command string for this part of the pipeline
+          const commandParts = [cmd];
+          for (const arg of args) {
+            if (arg.value !== undefined) {
+              // Handle our parsed arg structure
+              if (arg.quoted) {
+                // Preserve original quotes
+                commandParts.push(`${arg.quoteChar}${arg.value}${arg.quoteChar}`);
+              } else if (arg.value.includes(' ')) {
+                // Quote if contains spaces
+                commandParts.push(`"${arg.value}"`);
+              } else {
+                commandParts.push(arg.value);
+              }
+            } else {
+              // Handle plain string args (backward compatibility)
+              if (typeof arg === 'string' && arg.includes(' ') && !arg.startsWith('"') && !arg.startsWith("'")) {
+                commandParts.push(`"${arg}"`);
+              } else {
+                commandParts.push(arg);
+              }
+            }
+          }
+          const commandStr = commandParts.join(' ');
+          
+          // Shell tracing for system commands
+          if (globalShellSettings.xtrace) {
+            console.log(`+ ${commandStr}`);
+          }
+          if (globalShellSettings.verbose) {
+            console.log(commandStr);
+          }
+          
+          // Execute the system command with current input as stdin (ASYNC VERSION)
+          const spawnNodeAsync = async (argv, stdin, isLastCommand = false) => {
+            const require = createRequire(import.meta.url);
+            const cp = require('child_process');
+            
+            return new Promise((resolve, reject) => {
+              const proc = cp.spawn(argv[0], argv.slice(1), {
+                cwd: this.options.cwd,
+                env: this.options.env,
+                stdio: ['pipe', 'pipe', 'pipe']
+              });
+              
+              let stdout = '';
+              let stderr = '';
+              
+              proc.stdout.on('data', (chunk) => {
+                stdout += chunk.toString();
+                // If this is the last command, emit streaming data
+                if (isLastCommand) {
+                  if (this.options.mirror) {
+                    process.stdout.write(chunk);
+                  }
+                  this.emit('stdout', chunk);
+                  this.emit('data', { type: 'stdout', data: chunk });
+                }
+              });
+              
+              proc.stderr.on('data', (chunk) => {
+                stderr += chunk.toString();
+                // If this is the last command, emit streaming data
+                if (isLastCommand) {
+                  if (this.options.mirror) {
+                    process.stderr.write(chunk);
+                  }
+                  this.emit('stderr', chunk);
+                  this.emit('data', { type: 'stderr', data: chunk });
+                }
+              });
+              
+              proc.on('close', (code) => {
+                resolve({
+                  status: code,
+                  stdout,
+                  stderr
+                });
+              });
+              
+              proc.on('error', reject);
+              
+              if (stdin) {
+                proc.stdin.write(stdin);
+              }
+              proc.stdin.end();
+            });
+          };
+          
+          // Execute using shell to handle complex commands
+          const argv = ['sh', '-c', commandStr];
+          const isLastCommand = (i === commands.length - 1);
+          const proc = await spawnNodeAsync(argv, currentInput, isLastCommand);
+          
+          let result = {
+            code: proc.status || 0,
+            stdout: proc.stdout || '',
+            stderr: proc.stderr || '',
+            stdin: currentInput
+          };
+          
+          // If command failed and pipefail is set, fail the entire pipeline
+          if (globalShellSettings.pipefail && result.code !== 0) {
+            const error = new Error(`Pipeline command '${commandStr}' failed with exit code ${result.code}`);
+            error.code = result.code;
+            error.stdout = result.stdout;
+            error.stderr = result.stderr;
+            throw error;
+          }
+          
+          // If this isn't the last command, pass stdout as stdin to next command
+          if (i < commands.length - 1) {
+            currentInput = result.stdout;
+            // Accumulate stderr from all commands
+            if (result.stderr && this.options.capture) {
+              this.errChunks = this.errChunks || [];
+              this.errChunks.push(Buffer.from(result.stderr));
+            }
+          } else {
+            // This is the last command - store final result (streaming already handled during execution)
+            currentOutput = result.stdout;
+            
+            // Collect all accumulated stderr
+            let allStderr = '';
+            if (this.errChunks && this.errChunks.length > 0) {
+              allStderr = Buffer.concat(this.errChunks).toString('utf8');
+            }
+            if (result.stderr) {
+              allStderr += result.stderr;
+            }
+            
+            // Store final result using createResult helper for .text() method compatibility
+            const finalResult = createResult({
+              code: result.code,
+              stdout: currentOutput,
+              stderr: allStderr,
+              stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
+                     this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
+            });
+            
+            this.result = finalResult;
+            this.finished = true;
+            
+            // Emit completion events
+            this.emit('end', finalResult);
+            this.emit('exit', finalResult.code);
+            
+            // Handle shell settings
+            if (globalShellSettings.errexit && finalResult.code !== 0) {
+              const error = new Error(`Pipeline failed with exit code ${finalResult.code}`);
+              error.code = finalResult.code;
+              error.stdout = finalResult.stdout;
+              error.stderr = finalResult.stderr;
+              error.result = finalResult;
+              throw error;
+            }
+            
+            return finalResult;
+          }
+          
+        } catch (error) {
+          // Handle errors from system commands in pipeline
+          const result = createResult({
+            code: error.code ?? 1,
+            stdout: currentOutput,
+            stderr: error.stderr ?? error.message,
+            stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
+                   this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
+          });
+          
+          this.result = result;
+          this.finished = true;
+          
+          if (result.stderr) {
+            const buf = Buffer.from(result.stderr);
+            if (this.options.mirror) {
+              process.stderr.write(buf);
+            }
+            this.emit('stderr', buf);
+            this.emit('data', { type: 'stderr', data: buf });
+          }
+          
+          this.emit('end', result);
+          this.emit('exit', result.code);
+          
+          if (globalShellSettings.errexit) {
+            throw error;
+          }
+          
+          return result;
         }
-        this.emit('stderr', buf);
-        this.emit('data', { type: 'stderr', data: buf });
-        
-        this.emit('end', result);
-        this.emit('exit', result.code);
-        
-        return result;
       }
     }
   }
 
+  async _runPipeline(commands) {
+    traceFunc('ProcessRunner', '_runPipeline', 'ENTER', { 
+      commandsCount: commands.length 
+    });
+    
+    if (commands.length === 0) {
+      traceBranch('ProcessRunner', '_runPipeline', 'NO_COMMANDS', {});
+      return createResult({ code: 1, stdout: '', stderr: 'No commands in pipeline', stdin: '' });
+    }
+
+
+    // For true streaming, we need to connect processes via pipes
+    if (isBun) {
+      traceBranch('ProcessRunner', '_runPipeline', 'BUN_STREAMING', {});
+      return this._runStreamingPipelineBun(commands);
+    }
+    
+    // For Node.js, fall back to non-streaming implementation for now
+    traceBranch('ProcessRunner', '_runPipeline', 'NODE_NON_STREAMING', {});
+    return this._runPipelineNonStreaming(commands);
+  }
+
   // Run programmatic pipeline (.pipe() method)
   async _runProgrammaticPipeline(source, destination) {
+    traceFunc('ProcessRunner', '_runProgrammaticPipeline', 'ENTER', {});
+    
     try {
       // Execute the source command first
+      trace('ProcessRunner', 'Executing source command', {});
       const sourceResult = await source;
       
       if (sourceResult.code !== 0) {
         // If source failed, return its result
+        traceBranch('ProcessRunner', '_runProgrammaticPipeline', 'SOURCE_FAILED', { 
+          code: sourceResult.code,
+          stderr: sourceResult.stderr 
+        });
         return sourceResult;
       }
       
-      // Set the destination's stdin to the source's stdout
-      destination.options = {
+      // Create a new ProcessRunner with the correct stdin for the destination
+      const destWithStdin = new ProcessRunner(destination.spec, {
         ...destination.options,
         stdin: sourceResult.stdout
-      };
+      });
       
       // Execute the destination command
-      const destResult = await destination;
+      const destResult = await destWithStdin;
       
+      // Debug: Log what destResult looks like
+      trace('ProcessRunner', 'destResult debug', { 
+        code: destResult.code, 
+        codeType: typeof destResult.code,
+        hasCode: 'code' in destResult,
+        keys: Object.keys(destResult),
+        resultType: typeof destResult,
+        fullResult: JSON.stringify(destResult, null, 2).slice(0, 200)
+      });
+
       // Return the final result with combined information
       return createResult({
         code: destResult.code,
@@ -744,13 +1755,20 @@ class ProcessRunner extends StreamEmitter {
 
   // Async iteration support
   async* stream() {
+    traceFunc('ProcessRunner', 'stream', 'ENTER', { 
+      started: this.started,
+      finished: this.finished 
+    });
+    
     if (!this.started) {
-      this._start(); // Start but don't await
+      trace('ProcessRunner', 'Auto-starting async process from stream()', {});
+      this._startAsync(); // Start but don't await
     }
     
     let buffer = [];
     let resolve, reject;
     let ended = false;
+    let cleanedUp = false;
 
     const onData = (chunk) => {
       buffer.push(chunk);
@@ -783,15 +1801,94 @@ class ProcessRunner extends StreamEmitter {
         }
       }
     } finally {
+      cleanedUp = true;
       this.off('data', onData);
       this.off('end', onEnd);
+      
+      // Kill the process if it's still running when iteration is stopped
+      // This happens when breaking from a for-await loop
+      if (!this.finished) {
+        this.kill();
+      }
+    }
+  }
+  
+  // Kill the running process or cancel virtual command
+  kill() {
+    traceFunc('ProcessRunner', 'kill', 'ENTER', { 
+      cancelled: this._cancelled,
+      finished: this.finished,
+      hasChild: !!this.child,
+      hasVirtualGenerator: !!this._virtualGenerator
+    });
+    
+    // Mark as cancelled for virtual commands
+    this._cancelled = true;
+    
+    // Resolve the cancel promise to break the race in virtual command execution
+    if (this._cancelResolve) {
+      trace('ProcessRunner', 'Resolving cancel promise', {});
+      this._cancelResolve();
+    }
+    
+    // Abort any async operations
+    if (this._abortController) {
+      trace('ProcessRunner', 'Aborting controller', {});
+      this._abortController.abort();
+    }
+    
+    // If it's a virtual generator, try to close it
+    if (this._virtualGenerator && this._virtualGenerator.return) {
+      trace('ProcessRunner', 'Closing virtual generator', {});
+      try {
+        this._virtualGenerator.return();
+      } catch (err) {
+        trace('ProcessRunner', 'Error closing generator', { error: err.message });
+      }
+    }
+    
+    // Kill child process if it exists
+    if (this.child && !this.finished) {
+      traceBranch('ProcessRunner', 'hasChild', 'killing', { pid: this.child.pid });
+      try {
+        // Kill the process group to ensure all child processes are terminated
+        if (this.child.pid) {
+          if (isBun) {
+            trace('ProcessRunner', 'Killing Bun process', { pid: this.child.pid });
+            this.child.kill();
+          } else {
+            // In Node.js, kill the process group
+            trace('ProcessRunner', 'Killing Node process group', { pid: this.child.pid });
+            process.kill(-this.child.pid, 'SIGTERM');
+          }
+        }
+        this.finished = true;
+      } catch (err) {
+        // Process might already be dead
+        trace('ProcessRunner', 'Error killing process', { error: err.message });
+        console.error('Error killing process:', err.message);
+      }
     }
+    
+    // Mark as finished
+    this.finished = true;
+    
+    traceFunc('ProcessRunner', 'kill', 'EXIT', { 
+      cancelled: this._cancelled,
+      finished: this.finished 
+    });
   }
 
   // Programmatic piping support
   pipe(destination) {
+    traceFunc('ProcessRunner', 'pipe', 'ENTER', { 
+      hasDestination: !!destination,
+      destinationType: destination?.constructor?.name 
+    });
+    
     // If destination is a ProcessRunner, create a pipeline
     if (destination instanceof ProcessRunner) {
+      traceBranch('ProcessRunner', 'pipe', 'PROCESS_RUNNER_DEST', {});
       // Create a new ProcessRunner that represents the piped operation
       const pipeSpec = {
         mode: 'pipeline',
@@ -799,49 +1896,64 @@ class ProcessRunner extends StreamEmitter {
         destination: destination
       };
       
-      return new ProcessRunner(pipeSpec, {
+      const pipeRunner = new ProcessRunner(pipeSpec, {
         ...this.options,
         capture: destination.options.capture ?? true
       });
+      
+      traceFunc('ProcessRunner', 'pipe', 'EXIT', { mode: 'pipeline' });
+      return pipeRunner;
     }
     
     // If destination is a template literal result (from $`command`), use its spec
     if (destination && destination.spec) {
+      traceBranch('ProcessRunner', 'pipe', 'TEMPLATE_LITERAL_DEST', {});
       const destRunner = new ProcessRunner(destination.spec, destination.options);
       return this.pipe(destRunner);
     }
     
+    traceBranch('ProcessRunner', 'pipe', 'INVALID_DEST', {});
     throw new Error('pipe() destination must be a ProcessRunner or $`command` result');
   }
 
   // Promise interface (for await)
   then(onFulfilled, onRejected) {
     if (!this.promise) {
-      this.promise = this._start();
+      this.promise = this._startAsync();
     }
     return this.promise.then(onFulfilled, onRejected);
   }
 
   catch(onRejected) {
     if (!this.promise) {
-      this.promise = this._start();
+      this.promise = this._startAsync();
     }
     return this.promise.catch(onRejected);
   }
 
   finally(onFinally) {
     if (!this.promise) {
-      this.promise = this._start();
+      this.promise = this._startAsync();
     }
     return this.promise.finally(onFinally);
   }
 
-  // Synchronous execution
-  sync() {
+  // Internal sync execution
+  _startSync() {
+    traceFunc('ProcessRunner', '_startSync', 'ENTER', { 
+      started: this.started,
+      spec: this.spec 
+    });
+    
     if (this.started) {
+      traceBranch('ProcessRunner', '_startSync', 'ALREADY_STARTED', {});
       throw new Error('Command already started - cannot run sync after async start');
     }
     
+    this.started = true;
+    this._mode = 'sync';
+    trace('ProcessRunner', 'Starting sync execution', { mode: this._mode });
+    
     const { cwd, env, stdin } = this.options;
     const argv = this.spec.mode === 'shell' ? ['sh', '-lc', this.spec.command] : [this.spec.file, ...this.spec.args];
     
@@ -960,34 +2072,79 @@ class ProcessRunner extends StreamEmitter {
 
 // Public APIs
 async function sh(commandString, options = {}) {
+  traceFunc('API', 'sh', 'ENTER', { 
+    command: commandString,
+    options 
+  });
+  
   const runner = new ProcessRunner({ mode: 'shell', command: commandString }, options);
-  return runner._start();
+  const result = await runner._startAsync();
+  
+  traceFunc('API', 'sh', 'EXIT', { code: result.code });
+  return result;
 }
 
 async function exec(file, args = [], options = {}) {
+  traceFunc('API', 'exec', 'ENTER', { 
+    file,
+    argsCount: args.length,
+    options 
+  });
+  
   const runner = new ProcessRunner({ mode: 'exec', file, args }, options);
-  return runner._start();
+  const result = await runner._startAsync();
+  
+  traceFunc('API', 'exec', 'EXIT', { code: result.code });
+  return result;
 }
 
 async function run(commandOrTokens, options = {}) {
+  traceFunc('API', 'run', 'ENTER', { 
+    type: typeof commandOrTokens,
+    options 
+  });
+  
   if (typeof commandOrTokens === 'string') {
+    traceBranch('API', 'run', 'STRING_COMMAND', { command: commandOrTokens });
     return sh(commandOrTokens, { ...options, mirror: false, capture: true });
   }
+  
   const [file, ...args] = commandOrTokens;
+  traceBranch('API', 'run', 'TOKEN_ARRAY', { file, argsCount: args.length });
   return exec(file, args, { ...options, mirror: false, capture: true });
 }
 
 // Enhanced tagged template that returns ProcessRunner
 function $tagged(strings, ...values) {
+  traceFunc('API', '$tagged', 'ENTER', { 
+    stringsLength: strings.length,
+    valuesLength: values.length 
+  });
+  
   const cmd = buildShellCommand(strings, values);
-  return new ProcessRunner({ mode: 'shell', command: cmd }, { mirror: true, capture: true });
+  const runner = new ProcessRunner({ mode: 'shell', command: cmd }, { mirror: true, capture: true });
+  
+  traceFunc('API', '$tagged', 'EXIT', { command: cmd });
+  return runner;
 }
 
 function create(defaultOptions = {}) {
+  traceFunc('API', 'create', 'ENTER', { defaultOptions });
+  
   const tagged = (strings, ...values) => {
+    traceFunc('API', 'create.tagged', 'ENTER', { 
+      stringsLength: strings.length,
+      valuesLength: values.length 
+    });
+    
     const cmd = buildShellCommand(strings, values);
-    return new ProcessRunner({ mode: 'shell', command: cmd }, { mirror: true, capture: true, ...defaultOptions });
+    const runner = new ProcessRunner({ mode: 'shell', command: cmd }, { mirror: true, capture: true, ...defaultOptions });
+    
+    traceFunc('API', 'create.tagged', 'EXIT', { command: cmd });
+    return runner;
   };
+  
+  traceFunc('API', 'create', 'EXIT', {});
   return tagged;
 }
 
@@ -1058,12 +2215,21 @@ const shell = {
 
 // Virtual command registration API
 function register(name, handler) {
+  traceFunc('VirtualCommands', 'register', 'ENTER', { name });
+  
   virtualCommands.set(name, handler);
+  
+  traceFunc('VirtualCommands', 'register', 'EXIT', { registered: true });
   return virtualCommands;
 }
 
 function unregister(name) {
-  return virtualCommands.delete(name);
+  traceFunc('VirtualCommands', 'unregister', 'ENTER', { name });
+  
+  const deleted = virtualCommands.delete(name);
+  
+  traceFunc('VirtualCommands', 'unregister', 'EXIT', { deleted });
+  return deleted;
 }
 
 function listCommands() {
@@ -1085,10 +2251,15 @@ function registerBuiltins() {
   // cd - change directory
   register('cd', async (args) => {
     const target = args[0] || process.env.HOME || process.env.USERPROFILE || '/';
+    trace('VirtualCommand', 'cd: changing directory', { target });
+    
     try {
       process.chdir(target);
-      return { stdout: process.cwd(), code: 0 };
+      const newDir = process.cwd();
+      trace('VirtualCommand', 'cd: success', { newDir });
+      return { stdout: newDir, code: 0 };
     } catch (error) {
+      trace('VirtualCommand', 'cd: failed', { error: error.message });
       return { stderr: `cd: ${error.message}`, code: 1 };
     }
   });
@@ -1097,14 +2268,18 @@ function registerBuiltins() {
   register('pwd', async (args, stdin, options) => {
     // If cwd option is provided, return that instead of process.cwd()
     const dir = options?.cwd || process.cwd();
+    trace('VirtualCommand', 'pwd: getting directory', { dir });
     return { stdout: dir, code: 0 };
   });
 
   // echo - print arguments
   register('echo', async (args) => {
+    trace('VirtualCommand', 'echo: processing', { argsCount: args.length });
+    
     let output = args.join(' ');
     if (args.includes('-n')) {
       // Don't add newline
+      traceBranch('VirtualCommand', 'echo', 'NO_NEWLINE', {});
       output = args.filter(arg => arg !== '-n').join(' ');
     } else {
       output += '\n';
@@ -1115,10 +2290,15 @@ function registerBuiltins() {
   // sleep - wait for specified time
   register('sleep', async (args) => {
     const seconds = parseFloat(args[0] || 0);
+    trace('VirtualCommand', 'sleep: starting', { seconds });
+    
     if (isNaN(seconds) || seconds < 0) {
+      trace('VirtualCommand', 'sleep: invalid interval', { input: args[0] });
       return { stderr: 'sleep: invalid time interval', code: 1 };
     }
+    
     await new Promise(resolve => setTimeout(resolve, seconds * 1000));
+    trace('VirtualCommand', 'sleep: completed', { seconds });
     return { stdout: '', code: 0 };
   });
 
@@ -1649,14 +2829,49 @@ function registerBuiltins() {
   });
 
   // yes - output a string repeatedly
-  register('yes', async function* (args) {
+  register('yes', async function* (args, stdin, options) {
     const output = args.length > 0 ? args.join(' ') : 'y';
+    trace('VirtualCommand', 'yes: starting infinite generator', { output });
     
     // Generate infinite stream of the output
     while (true) {
+      // Check if cancelled via function or abort signal
+      if (options) {
+        if (options.isCancelled && options.isCancelled()) {
+          trace('VirtualCommand', 'yes: cancelled via function', {});
+          return;
+        }
+        if (options.signal && options.signal.aborted) {
+          trace('VirtualCommand', 'yes: cancelled via abort signal', {});
+          return;
+        }
+      }
+      
       yield output + '\n';
-      // Small delay to prevent overwhelming the system
-      await new Promise(resolve => setTimeout(resolve, 0));
+      
+      // Small delay with abort signal support
+      try {
+        await new Promise((resolve, reject) => {
+          const timeout = setTimeout(resolve, 0);
+          
+          // Listen for abort signal if available
+          if (options && options.signal) {
+            const abortHandler = () => {
+              clearTimeout(timeout);
+              reject(new Error('Aborted'));
+            };
+            
+            if (options.signal.aborted) {
+              abortHandler();
+            } else {
+              options.signal.addEventListener('abort', abortHandler, { once: true });
+            }
+          }
+        });
+      } catch (err) {
+        // Aborted
+        return;
+      }
     }
   });