command-stream 0.1.0 → 0.2.0

package/$.mjs

@@ -36,6 +36,75 @@ function traceFunc(category, funcName, phase, data = {}) {
   trace(category, `${funcName} ${phase}`, data);
 }
 
+// Track parent stream state for graceful shutdown
+let parentStreamsMonitored = false;
+const activeProcessRunners = new Set();
+
+function monitorParentStreams() {
+  if (parentStreamsMonitored) return;
+  parentStreamsMonitored = true;
+  
+  // Monitor parent stdout/stderr for closure
+  const checkParentStream = (stream, name) => {
+    if (stream && typeof stream.on === 'function') {
+      stream.on('close', () => {
+        trace('ProcessRunner', `Parent ${name} closed - triggering graceful shutdown`, {
+          activeProcesses: activeProcessRunners.size
+        });
+        // Signal all active ProcessRunners to gracefully shutdown
+        for (const runner of activeProcessRunners) {
+          runner._handleParentStreamClosure();
+        }
+      });
+    }
+  };
+  
+  checkParentStream(process.stdout, 'stdout');
+  checkParentStream(process.stderr, 'stderr');
+}
+
+// Safe write function that checks stream state and handles parent closure
+function safeWrite(stream, data, processRunner = null) {
+  // Ensure parent stream monitoring is active
+  monitorParentStreams();
+  
+  // Check if stream is writable and not destroyed/closed
+  if (!stream || !stream.writable || stream.destroyed || stream.closed) {
+    trace('ProcessRunner', 'safeWrite skipped - stream not writable', { 
+      hasStream: !!stream,
+      writable: stream?.writable,
+      destroyed: stream?.destroyed,
+      closed: stream?.closed
+    });
+    
+    // If this is a parent stream closure, signal graceful shutdown
+    if (processRunner && (stream === process.stdout || stream === process.stderr)) {
+      processRunner._handleParentStreamClosure();
+    }
+    
+    return false;
+  }
+  
+  try {
+    return stream.write(data);
+  } catch (error) {
+    trace('ProcessRunner', 'safeWrite error', { 
+      error: error.message, 
+      code: error.code,
+      writable: stream.writable,
+      destroyed: stream.destroyed
+    });
+    
+    // If this is an EPIPE on parent streams, signal graceful shutdown
+    if (error.code === 'EPIPE' && processRunner && 
+        (stream === process.stdout || stream === process.stderr)) {
+      processRunner._handleParentStreamClosure();
+    }
+    
+    return false;
+  }
+}
+
 // Global shell settings (like bash set -e / set +e)
 let globalShellSettings = {
   errexit: false,    // set -e equivalent: exit on error
@@ -192,6 +261,79 @@ class ProcessRunner extends StreamEmitter {
     this._cancelled = false;
     this._virtualGenerator = null;
     this._abortController = new AbortController();
+    
+    // Register this ProcessRunner for parent stream monitoring
+    activeProcessRunners.add(this);
+    
+    // Track finished state changes to trigger cleanup
+    this._finished = false;
+  }
+  
+  // Override finished property to trigger cleanup when set to true
+  get finished() {
+    return this._finished;
+  }
+  
+  set finished(value) {
+    if (value === true && this._finished === false) {
+      this._finished = true;
+      this._cleanup(); // Trigger cleanup when process finishes
+    } else {
+      this._finished = value;
+    }
+  }
+
+  // Handle parent stream closure by gracefully shutting down child processes
+  _handleParentStreamClosure() {
+    if (this.finished || this._cancelled) return;
+    
+    trace('ProcessRunner', 'Handling parent stream closure', {
+      started: this.started,
+      hasChild: !!this.child,
+      command: this.spec.command?.slice(0, 50) || this.spec.file
+    });
+    
+    // Mark as cancelled to prevent further operations
+    this._cancelled = true;
+    
+    // Cancel abort controller for virtual commands
+    if (this._abortController) {
+      this._abortController.abort();
+    }
+    
+    // Gracefully close child process if it exists
+    if (this.child) {
+      try {
+        // Close stdin first to signal completion
+        if (this.child.stdin && typeof this.child.stdin.end === 'function') {
+          this.child.stdin.end();
+        } else if (isBun && this.child.stdin && typeof this.child.stdin.getWriter === 'function') {
+          const writer = this.child.stdin.getWriter();
+          writer.close().catch(() => {}); // Ignore close errors
+        }
+        
+        // Give the process a moment to exit gracefully, then terminate
+        setTimeout(() => {
+          if (this.child && !this.finished) {
+            trace('ProcessRunner', 'Terminating child process after parent stream closure', {});
+            if (typeof this.child.kill === 'function') {
+              this.child.kill('SIGTERM');
+            }
+          }
+        }, 100);
+        
+      } catch (error) {
+        trace('ProcessRunner', 'Error during graceful shutdown', { error: error.message });
+      }
+    }
+    
+    // Remove from active set
+    activeProcessRunners.delete(this);
+  }
+
+  // Cleanup method to remove from active set when process completes normally
+  _cleanup() {
+    activeProcessRunners.delete(this);
   }
 
   // Unified start method that can work in both async and sync modes
@@ -304,7 +446,7 @@ class ProcessRunner extends StreamEmitter {
     // Setup stdout streaming
     const outPump = pumpReadable(this.child.stdout, async (buf) => {
       if (this.options.capture) this.outChunks.push(buf);
-      if (this.options.mirror) process.stdout.write(buf);
+      if (this.options.mirror) safeWrite(process.stdout, buf);
       
       // Emit chunk events
       this.emit('stdout', buf);
@@ -314,7 +456,7 @@ class ProcessRunner extends StreamEmitter {
     // Setup stderr streaming  
     const errPump = pumpReadable(this.child.stderr, async (buf) => {
       if (this.options.capture) this.errChunks.push(buf);
-      if (this.options.mirror) process.stderr.write(buf);
+      if (this.options.mirror) safeWrite(process.stderr, buf);
       
       // Emit chunk events
       this.emit('stderr', buf);
@@ -394,7 +536,27 @@ class ProcessRunner extends StreamEmitter {
       const buf = asBuffer(chunk);
       captureChunks && captureChunks.push(buf);
       if (bunWriter) await bunWriter.write(buf);
-      else if (typeof child.stdin.write === 'function') child.stdin.write(buf);
+      else if (typeof child.stdin.write === 'function') {
+        // Add error handler to prevent unhandled error events
+        if (child.stdin && typeof child.stdin.on === 'function') {
+          child.stdin.on('error', (error) => {
+            if (error.code !== 'EPIPE') {
+              trace('ProcessRunner', 'child stdin buffer error event', { error: error.message, code: error.code });
+            }
+          });
+        }
+        
+        // Safe write to handle EPIPE errors
+        if (child.stdin && child.stdin.writable && !child.stdin.destroyed && !child.stdin.closed) {
+          try {
+            child.stdin.write(buf);
+          } catch (error) {
+            if (error.code !== 'EPIPE') {
+              trace('ProcessRunner', 'Error writing stdin buffer', { error: error.message, code: error.code });
+            }
+          }
+        }
+      }
       else if (isBun && typeof Bun.write === 'function') await Bun.write(child.stdin, buf);
     }
     if (bunWriter) await bunWriter.close();
@@ -405,8 +567,14 @@ class ProcessRunner extends StreamEmitter {
     if (isBun && this.child.stdin && typeof this.child.stdin.getWriter === 'function') {
       const w = this.child.stdin.getWriter();
       const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf.buffer, buf.byteOffset ?? 0, buf.byteLength);
-      await w.write(bytes);
-      await w.close();
+      try {
+        await w.write(bytes);
+        await w.close();
+      } catch (error) {
+        if (error.code !== 'EPIPE') {
+          trace('ProcessRunner', 'Error writing to Bun writer', { error: error.message, code: error.code });
+        }
+      }
     } else if (this.child.stdin && typeof this.child.stdin.write === 'function') {
       this.child.stdin.end(buf);
     } else if (isBun && typeof Bun.write === 'function') {
@@ -541,7 +709,7 @@ class ProcessRunner extends StreamEmitter {
           signal: this._abortController.signal
         };
         
-        const generator = handler(argValues, stdinData, commandOptions);
+        const generator = handler({ args: argValues, stdin: stdinData, ...commandOptions });
         this._virtualGenerator = generator;
         
         // Create a promise that resolves when cancelled
@@ -578,7 +746,7 @@ class ProcessRunner extends StreamEmitter {
               // Only output if not cancelled
               if (!this._cancelled) {
                 if (this.options.mirror) {
-                  process.stdout.write(buf);
+                  safeWrite(process.stdout, buf);
                 }
                 
                 this.emit('stdout', buf);
@@ -600,7 +768,7 @@ class ProcessRunner extends StreamEmitter {
         };
       } else {
         // Regular async function
-        result = await handler(argValues, stdinData, this.options);
+        result = await handler({ args: argValues, stdin: stdinData, ...this.options });
         
         // Ensure result has required fields, respecting capture option
         result = {
@@ -615,7 +783,7 @@ class ProcessRunner extends StreamEmitter {
         if (result.stdout) {
           const buf = Buffer.from(result.stdout);
           if (this.options.mirror) {
-            process.stdout.write(buf);
+            safeWrite(process.stdout, buf);
           }
           this.emit('stdout', buf);
           this.emit('data', { type: 'stdout', data: buf });
@@ -624,7 +792,7 @@ class ProcessRunner extends StreamEmitter {
         if (result.stderr) {
           const buf = Buffer.from(result.stderr);
           if (this.options.mirror) {
-            process.stderr.write(buf);
+            safeWrite(process.stderr, buf);
           }
           this.emit('stderr', buf);
           this.emit('data', { type: 'stderr', data: buf });
@@ -665,7 +833,7 @@ class ProcessRunner extends StreamEmitter {
       if (result.stderr) {
         const buf = Buffer.from(result.stderr);
         if (this.options.mirror) {
-          process.stderr.write(buf);
+          safeWrite(process.stderr, buf);
         }
         this.emit('stderr', buf);
         this.emit('data', { type: 'stderr', data: buf });
@@ -794,13 +962,26 @@ class ProcessRunner extends StreamEmitter {
       
       // Write stdin data if needed for first process
       if (needsManualStdin && stdinData && proc.stdin) {
+        // Add error handler for Bun stdin
+        if (proc.stdin && typeof proc.stdin.on === 'function') {
+          proc.stdin.on('error', (error) => {
+            if (error.code !== 'EPIPE') {
+              trace('ProcessRunner', 'Bun stdin error event', { error: error.message, code: error.code });
+            }
+          });
+        }
+        
         (async () => {
           try {
             // Bun's FileSink has write and end methods
-            await proc.stdin.write(stdinData);
-            await proc.stdin.end();
+            if (proc.stdin && proc.stdin.writable && !proc.stdin.destroyed && !proc.stdin.closed) {
+              await proc.stdin.write(stdinData);
+              await proc.stdin.end();
+            }
           } catch (e) {
-            console.error('Error writing stdin:', e);
+            if (e.code !== 'EPIPE') {
+              trace('ProcessRunner', 'Error writing stdin (Bun)', { error: e.message, code: e.code });
+            }
           }
         })();
       }
@@ -815,7 +996,7 @@ class ProcessRunner extends StreamEmitter {
           // Only emit stderr for the last command
           if (i === commands.length - 1) {
             if (this.options.mirror) {
-              process.stderr.write(buf);
+              safeWrite(process.stderr, buf);
             }
             this.emit('stderr', buf);
             this.emit('data', { type: 'stderr', data: buf });
@@ -833,7 +1014,7 @@ class ProcessRunner extends StreamEmitter {
       const buf = Buffer.from(chunk);
       finalOutput += buf.toString();
       if (this.options.mirror) {
-        process.stdout.write(buf);
+        safeWrite(process.stdout, buf);
       }
       this.emit('stdout', buf);
       this.emit('data', { type: 'stdout', data: buf });
@@ -959,11 +1140,24 @@ class ProcessRunner extends StreamEmitter {
       
       // Write stdin data if needed for first process
       if (needsManualStdin && stdinData && proc.stdin) {
+        // Add error handler for Node stdin
+        if (proc.stdin && typeof proc.stdin.on === 'function') {
+          proc.stdin.on('error', (error) => {
+            if (error.code !== 'EPIPE') {
+              trace('ProcessRunner', 'Node stdin error event', { error: error.message, code: error.code });
+            }
+          });
+        }
+        
         try {
-          await proc.stdin.write(stdinData);
-          await proc.stdin.end();
+          if (proc.stdin && proc.stdin.writable && !proc.stdin.destroyed && !proc.stdin.closed) {
+            await proc.stdin.write(stdinData);
+            await proc.stdin.end();
+          }
         } catch (e) {
-          // Ignore stdin errors
+          if (e.code !== 'EPIPE') {
+            trace('ProcessRunner', 'Error writing stdin (Node stream)', { error: e.message, code: e.code });
+          }
         }
       }
       
@@ -982,7 +1176,7 @@ class ProcessRunner extends StreamEmitter {
               // Emit from the first process for real-time updates
               const buf = Buffer.from(chunk);
               if (this.options.mirror) {
-                process.stdout.write(buf);
+                safeWrite(process.stdout, buf);
               }
               this.emit('stdout', buf);
               this.emit('data', { type: 'stdout', data: buf });
@@ -1007,7 +1201,7 @@ class ProcessRunner extends StreamEmitter {
           allStderr += buf.toString();
           if (i === commands.length - 1) {
             if (this.options.mirror) {
-              process.stderr.write(buf);
+              safeWrite(process.stderr, buf);
             }
             this.emit('stderr', buf);
             this.emit('data', { type: 'stderr', data: buf });
@@ -1028,7 +1222,7 @@ class ProcessRunner extends StreamEmitter {
       finalOutput += buf.toString();
       if (shouldEmitFromLast) {
         if (this.options.mirror) {
-          process.stdout.write(buf);
+          safeWrite(process.stdout, buf);
         }
         this.emit('stdout', buf);
         this.emit('data', { type: 'stdout', data: buf });
@@ -1139,7 +1333,8 @@ class ProcessRunner extends StreamEmitter {
           const self = this; // Capture this context
           currentInputStream = new ReadableStream({
             async start(controller) {
-              for await (const chunk of handler(argValues, inputData, {})) {
+              const { stdin: _, ...optionsWithoutStdin } = self.options;
+              for await (const chunk of handler({ args: argValues, stdin: inputData, ...optionsWithoutStdin })) {
                 const data = Buffer.from(chunk);
                 controller.enqueue(data);
                 
@@ -1147,7 +1342,7 @@ class ProcessRunner extends StreamEmitter {
                 if (isLastCommand) {
                   chunks.push(data);
                   if (self.options.mirror) {
-                    process.stdout.write(data);
+                    safeWrite(process.stdout, data);
                   }
                   self.emit('stdout', data);
                   self.emit('data', { type: 'stdout', data });
@@ -1162,14 +1357,15 @@ class ProcessRunner extends StreamEmitter {
           });
         } else {
           // Regular async function
-          const result = await handler(argValues, inputData, {});
+          const { stdin: _, ...optionsWithoutStdin } = this.options;
+          const result = await handler({ args: argValues, stdin: inputData, ...optionsWithoutStdin });
           const outputData = result.stdout || '';
           
           if (isLastCommand) {
             finalOutput = outputData;
             const buf = Buffer.from(outputData);
             if (this.options.mirror) {
-              process.stdout.write(buf);
+              safeWrite(process.stdout, buf);
             }
             this.emit('stdout', buf);
             this.emit('data', { type: 'stdout', data: buf });
@@ -1229,11 +1425,25 @@ class ProcessRunner extends StreamEmitter {
                 const { done, value } = await reader.read();
                 if (done) break;
                 if (writer.write) {
-                  await writer.write(value);
+                  try {
+                    await writer.write(value);
+                  } catch (error) {
+                    if (error.code !== 'EPIPE') {
+                      trace('ProcessRunner', 'Error writing to stream writer', { error: error.message, code: error.code });
+                    }
+                    break; // Stop streaming if write fails
+                  }
                 } else if (writer.getWriter) {
-                  const w = writer.getWriter();
-                  await w.write(value);
-                  w.releaseLock();
+                  try {
+                    const w = writer.getWriter();
+                    await w.write(value);
+                    w.releaseLock();
+                  } catch (error) {
+                    if (error.code !== 'EPIPE') {
+                      trace('ProcessRunner', 'Error writing to stream writer (getWriter)', { error: error.message, code: error.code });
+                    }
+                    break; // Stop streaming if write fails
+                  }
                 }
               }
             } finally {
@@ -1254,7 +1464,7 @@ class ProcessRunner extends StreamEmitter {
             allStderr += buf.toString();
             if (isLastCommand) {
               if (this.options.mirror) {
-                process.stderr.write(buf);
+                safeWrite(process.stderr, buf);
               }
               this.emit('stderr', buf);
               this.emit('data', { type: 'stderr', data: buf });
@@ -1269,7 +1479,7 @@ class ProcessRunner extends StreamEmitter {
             const buf = Buffer.from(chunk);
             chunks.push(buf);
             if (this.options.mirror) {
-              process.stdout.write(buf);
+              safeWrite(process.stdout, buf);
             }
             this.emit('stdout', buf);
             this.emit('data', { type: 'stdout', data: buf });
@@ -1346,7 +1556,7 @@ class ProcessRunner extends StreamEmitter {
           if (handler.constructor.name === 'AsyncGeneratorFunction') {
             traceBranch('ProcessRunner', '_runPipelineNonStreaming', 'ASYNC_GENERATOR', { cmd });
             const chunks = [];
-            for await (const chunk of handler(argValues, currentInput, this.options)) {
+            for await (const chunk of handler({ args: argValues, stdin: currentInput, ...this.options })) {
               chunks.push(Buffer.from(chunk));
             }
             result = {
@@ -1357,7 +1567,7 @@ class ProcessRunner extends StreamEmitter {
             };
           } else {
             // Regular async function
-            result = await handler(argValues, currentInput, this.options);
+            result = await handler({ args: argValues, stdin: currentInput, ...this.options });
             result = {
               code: result.code ?? 0,
               stdout: this.options.capture ? (result.stdout ?? '') : undefined,
@@ -1378,7 +1588,7 @@ class ProcessRunner extends StreamEmitter {
             if (result.stdout) {
               const buf = Buffer.from(result.stdout);
               if (this.options.mirror) {
-                process.stdout.write(buf);
+                safeWrite(process.stdout, buf);
               }
               this.emit('stdout', buf);
               this.emit('data', { type: 'stdout', data: buf });
@@ -1387,7 +1597,7 @@ class ProcessRunner extends StreamEmitter {
             if (result.stderr) {
               const buf = Buffer.from(result.stderr);
               if (this.options.mirror) {
-                process.stderr.write(buf);
+                safeWrite(process.stderr, buf);
               }
               this.emit('stderr', buf);
               this.emit('data', { type: 'stderr', data: buf });
@@ -1447,7 +1657,7 @@ class ProcessRunner extends StreamEmitter {
           if (result.stderr) {
             const buf = Buffer.from(result.stderr);
             if (this.options.mirror) {
-              process.stderr.write(buf);
+              safeWrite(process.stderr, buf);
             }
             this.emit('stderr', buf);
             this.emit('data', { type: 'stderr', data: buf });
@@ -1518,7 +1728,7 @@ class ProcessRunner extends StreamEmitter {
                 // If this is the last command, emit streaming data
                 if (isLastCommand) {
                   if (this.options.mirror) {
-                    process.stdout.write(chunk);
+                    safeWrite(process.stdout, chunk);
                   }
                   this.emit('stdout', chunk);
                   this.emit('data', { type: 'stdout', data: chunk });
@@ -1530,7 +1740,7 @@ class ProcessRunner extends StreamEmitter {
                 // If this is the last command, emit streaming data
                 if (isLastCommand) {
                   if (this.options.mirror) {
-                    process.stderr.write(chunk);
+                    safeWrite(process.stderr, chunk);
                   }
                   this.emit('stderr', chunk);
                   this.emit('data', { type: 'stderr', data: chunk });
@@ -1547,10 +1757,68 @@ class ProcessRunner extends StreamEmitter {
               
               proc.on('error', reject);
               
+              // Add error handler to stdin to prevent unhandled error events
+              if (proc.stdin) {
+                proc.stdin.on('error', (error) => {
+                  trace('ProcessRunner', 'stdin error event', { 
+                    error: error.message, 
+                    code: error.code,
+                    isEPIPE: error.code === 'EPIPE'
+                  });
+                  
+                  // Only reject on non-EPIPE errors
+                  if (error.code !== 'EPIPE') {
+                    reject(error);
+                  }
+                  // EPIPE errors are expected when pipe is closed, so we ignore them
+                });
+              }
+              
               if (stdin) {
-                proc.stdin.write(stdin);
+                // Use safe write to handle potential EPIPE errors
+                trace('ProcessRunner', 'Attempting to write stdin', { 
+                  hasStdin: !!proc.stdin,
+                  writable: proc.stdin?.writable,
+                  destroyed: proc.stdin?.destroyed,
+                  closed: proc.stdin?.closed,
+                  stdinLength: stdin.length
+                });
+                
+                if (proc.stdin && proc.stdin.writable && !proc.stdin.destroyed && !proc.stdin.closed) {
+                  try {
+                    proc.stdin.write(stdin);
+                    trace('ProcessRunner', 'Successfully wrote to stdin', { stdinLength: stdin.length });
+                  } catch (error) {
+                    trace('ProcessRunner', 'Error writing to stdin', { 
+                      error: error.message, 
+                      code: error.code,
+                      isEPIPE: error.code === 'EPIPE'
+                    });
+                    if (error.code !== 'EPIPE') {
+                      throw error; // Re-throw non-EPIPE errors
+                    }
+                  }
+                } else {
+                  trace('ProcessRunner', 'Skipped writing to stdin - stream not writable', {
+                    hasStdin: !!proc.stdin,
+                    writable: proc.stdin?.writable,
+                    destroyed: proc.stdin?.destroyed,
+                    closed: proc.stdin?.closed
+                  });
+                }
+              }
+              
+              // Safely end the stdin stream
+              if (proc.stdin && typeof proc.stdin.end === 'function' && 
+                  proc.stdin.writable && !proc.stdin.destroyed && !proc.stdin.closed) {
+                try {
+                  proc.stdin.end();
+                } catch (error) {
+                  if (error.code !== 'EPIPE') {
+                    trace('ProcessRunner', 'Error ending stdin', { error: error.message });
+                  }
+                }
               }
-              proc.stdin.end();
             });
           };
           
@@ -1641,7 +1909,7 @@ class ProcessRunner extends StreamEmitter {
           if (result.stderr) {
             const buf = Buffer.from(result.stderr);
             if (this.options.mirror) {
-              process.stderr.write(buf);
+              safeWrite(process.stderr, buf);
             }
             this.emit('stderr', buf);
             this.emit('data', { type: 'stderr', data: buf });
@@ -1741,7 +2009,7 @@ class ProcessRunner extends StreamEmitter {
       
       const buf = Buffer.from(result.stderr);
       if (this.options.mirror) {
-        process.stderr.write(buf);
+        safeWrite(process.stderr, buf);
       }
       this.emit('stderr', buf);
       this.emit('data', { type: 'stderr', data: buf });
@@ -2016,8 +2284,8 @@ class ProcessRunner extends StreamEmitter {
     
     // Mirror output if requested (but always capture for result)
     if (this.options.mirror) {
-      if (result.stdout) process.stdout.write(result.stdout);
-      if (result.stderr) process.stderr.write(result.stderr);
+      if (result.stdout) safeWrite(process.stdout, result.stdout);
+      if (result.stderr) safeWrite(process.stderr, result.stderr);
     }
     
     // Store chunks for events (batched after completion)
@@ -2249,7 +2517,7 @@ function disableVirtualCommands() {
 // Built-in commands that match Bun.$ functionality
 function registerBuiltins() {
   // cd - change directory
-  register('cd', async (args) => {
+  register('cd', async ({ args }) => {
     const target = args[0] || process.env.HOME || process.env.USERPROFILE || '/';
     trace('VirtualCommand', 'cd: changing directory', { target });
     
@@ -2265,15 +2533,15 @@ function registerBuiltins() {
   });
 
   // pwd - print working directory
-  register('pwd', async (args, stdin, options) => {
+  register('pwd', async ({ args, stdin, cwd }) => {
     // If cwd option is provided, return that instead of process.cwd()
-    const dir = options?.cwd || process.cwd();
+    const dir = cwd || process.cwd();
     trace('VirtualCommand', 'pwd: getting directory', { dir });
     return { stdout: dir, code: 0 };
   });
 
   // echo - print arguments
-  register('echo', async (args) => {
+  register('echo', async ({ args }) => {
     trace('VirtualCommand', 'echo: processing', { argsCount: args.length });
     
     let output = args.join(' ');
@@ -2288,7 +2556,7 @@ function registerBuiltins() {
   });
 
   // sleep - wait for specified time
-  register('sleep', async (args) => {
+  register('sleep', async ({ args }) => {
     const seconds = parseFloat(args[0] || 0);
     trace('VirtualCommand', 'sleep: starting', { seconds });
     
@@ -2313,7 +2581,7 @@ function registerBuiltins() {
   });
 
   // which - locate command
-  register('which', async (args) => {
+  register('which', async ({ args }) => {
     if (args.length === 0) {
       return { stderr: 'which: missing operand', code: 1 };
     }
@@ -2344,7 +2612,7 @@ function registerBuiltins() {
   });
 
   // exit - exit with code
-  register('exit', async (args) => {
+  register('exit', async ({ args }) => {
     const code = parseInt(args[0] || 0);
     if (globalShellSettings.errexit || code !== 0) {
       // For virtual commands, we simulate exit by returning the code
@@ -2354,11 +2622,11 @@ function registerBuiltins() {
   });
 
   // env - print environment variables
-  register('env', async (args, stdin, options) => {
+  register('env', async ({ args, stdin, env }) => {
     if (args.length === 0) {
       // Use custom env if provided, otherwise use process.env
-      const env = options?.env || process.env;
-      const output = Object.entries(env)
+      const envVars = env || process.env;
+      const output = Object.entries(envVars)
         .map(([key, value]) => `${key}=${value}`)
         .join('\n') + '\n';
       return { stdout: output, code: 0 };
@@ -2369,7 +2637,7 @@ function registerBuiltins() {
   });
 
   // cat - read and display file contents
-  register('cat', async (args, stdin, options) => {
+  register('cat', async ({ args, stdin, cwd }) => {
     if (args.length === 0) {
       // Read from stdin if no files specified
       return { stdout: stdin || '', code: 0 };
@@ -2386,7 +2654,7 @@ function registerBuiltins() {
         
         try {
           // Resolve path relative to cwd if provided
-          const basePath = options?.cwd || process.cwd();
+          const basePath = cwd || process.cwd();
           const fullPath = path.isAbsolute(filename) ? filename : path.join(basePath, filename);
           
           const content = fs.readFileSync(fullPath, 'utf8');
@@ -2409,7 +2677,7 @@ function registerBuiltins() {
   });
 
   // ls - list directory contents
-  register('ls', async (args, stdin, options) => {
+  register('ls', async ({ args, stdin, cwd }) => {
     try {
       const fs = await import('fs');
       const path = await import('path');
@@ -2428,7 +2696,7 @@ function registerBuiltins() {
       
       for (const targetPath of targetPaths) {
         // Resolve path relative to cwd if provided
-        const basePath = options?.cwd || process.cwd();
+        const basePath = cwd || process.cwd();
         const fullPath = path.isAbsolute(targetPath) ? targetPath : path.join(basePath, targetPath);
         
         try {
@@ -2483,7 +2751,7 @@ function registerBuiltins() {
   });
 
   // mkdir - create directories
-  register('mkdir', async (args, stdin, options) => {
+  register('mkdir', async ({ args, stdin, cwd }) => {
     if (args.length === 0) {
       return { stderr: 'mkdir: missing operand', code: 1 };
     }
@@ -2498,7 +2766,7 @@ function registerBuiltins() {
       
       for (const dir of dirs) {
         try {
-          const basePath = options?.cwd || process.cwd();
+          const basePath = cwd || process.cwd();
           const fullPath = path.isAbsolute(dir) ? dir : path.join(basePath, dir);
           
           if (recursive) {
@@ -2521,7 +2789,7 @@ function registerBuiltins() {
   });
 
   // rm - remove files and directories
-  register('rm', async (args, stdin, options) => {
+  register('rm', async ({ args, stdin, cwd }) => {
     if (args.length === 0) {
       return { stderr: 'rm: missing operand', code: 1 };
     }
@@ -2537,7 +2805,7 @@ function registerBuiltins() {
       
       for (const target of targets) {
         try {
-          const basePath = options?.cwd || process.cwd();
+          const basePath = cwd || process.cwd();
           const fullPath = path.isAbsolute(target) ? target : path.join(basePath, target);
           
           const stat = fs.statSync(fullPath);
@@ -2570,7 +2838,7 @@ function registerBuiltins() {
   });
 
   // mv - move/rename files and directories
-  register('mv', async (args, stdin, options) => {
+  register('mv', async ({ args, stdin, cwd }) => {
     if (args.length < 2) {
       return { stderr: 'mv: missing destination file operand', code: 1 };
     }
@@ -2579,7 +2847,7 @@ function registerBuiltins() {
       const fs = await import('fs');
       const path = await import('path');
       
-      const basePath = options?.cwd || process.cwd();
+      const basePath = cwd || process.cwd();
       
       if (args.length === 2) {
         // Simple rename/move
@@ -2651,7 +2919,7 @@ function registerBuiltins() {
   });
 
   // cp - copy files and directories
-  register('cp', async (args, stdin, options) => {
+  register('cp', async ({ args, stdin, cwd }) => {
     if (args.length < 2) {
       return { stderr: 'cp: missing destination file operand', code: 1 };
     }
@@ -2664,7 +2932,7 @@ function registerBuiltins() {
       const paths = args.filter(arg => !arg.startsWith('-'));
       const recursive = flags.includes('-r') || flags.includes('-R');
       
-      const basePath = options?.cwd || process.cwd();
+      const basePath = cwd || process.cwd();
       
       if (paths.length === 2) {
         // Simple copy
@@ -2748,7 +3016,7 @@ function registerBuiltins() {
   });
 
   // touch - create or update file timestamps
-  register('touch', async (args, stdin, options) => {
+  register('touch', async ({ args, stdin, cwd }) => {
     if (args.length === 0) {
       return { stderr: 'touch: missing file operand', code: 1 };
     }
@@ -2757,7 +3025,7 @@ function registerBuiltins() {
       const fs = await import('fs');
       const path = await import('path');
       
-      const basePath = options?.cwd || process.cwd();
+      const basePath = cwd || process.cwd();
       
       for (const file of args) {
         try {
@@ -2786,7 +3054,7 @@ function registerBuiltins() {
   });
 
   // basename - extract filename from path
-  register('basename', async (args) => {
+  register('basename', async ({ args }) => {
     if (args.length === 0) {
       return { stderr: 'basename: missing operand', code: 1 };
     }
@@ -2811,7 +3079,7 @@ function registerBuiltins() {
   });
 
   // dirname - extract directory from path
-  register('dirname', async (args) => {
+  register('dirname', async ({ args }) => {
     if (args.length === 0) {
       return { stderr: 'dirname: missing operand', code: 1 };
     }
@@ -2829,22 +3097,20 @@ function registerBuiltins() {
   });
 
   // yes - output a string repeatedly
-  register('yes', async function* (args, stdin, options) {
+  register('yes', async function* ({ args, stdin, isCancelled, signal, ...rest }) {
     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;
-        }
+      if (isCancelled && isCancelled()) {
+        trace('VirtualCommand', 'yes: cancelled via function', {});
+        return;
+      }
+      if (signal && signal.aborted) {
+        trace('VirtualCommand', 'yes: cancelled via abort signal', {});
+        return;
       }
       
       yield output + '\n';
@@ -2855,16 +3121,16 @@ function registerBuiltins() {
           const timeout = setTimeout(resolve, 0);
           
           // Listen for abort signal if available
-          if (options && options.signal) {
+          if (signal) {
             const abortHandler = () => {
               clearTimeout(timeout);
               reject(new Error('Aborted'));
             };
             
-            if (options.signal.aborted) {
+            if (signal.aborted) {
               abortHandler();
             } else {
-              options.signal.addEventListener('abort', abortHandler, { once: true });
+              signal.addEventListener('abort', abortHandler, { once: true });
             }
           }
         });
@@ -2876,7 +3142,7 @@ function registerBuiltins() {
   });
 
   // seq - generate sequence of numbers
-  register('seq', async (args) => {
+  register('seq', async ({ args }) => {
     if (args.length === 0) {
       return { stderr: 'seq: missing operand', code: 1 };
     }
@@ -2924,7 +3190,7 @@ function registerBuiltins() {
   });
 
   // test - test file conditions (basic implementation)
-  register('test', async (args) => {
+  register('test', async ({ args }) => {
     if (args.length === 0) {
       return { stdout: '', code: 1 };
     }

package/package.json

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