command-stream 0.8.2 → 0.9.0

package/js/examples/test-cd-behavior.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import { $, shell, enableVirtualCommands } from '../src/$.mjs';
+
+enableVirtualCommands();
+shell.verbose(false);
+
+console.log('Testing cd command behavior:\n');
+
+// Test 1: Basic cd should persist within chain
+console.log('Test 1: cd should persist within chain');
+const originalCwd = process.cwd();
+console.log('Original cwd:', originalCwd);
+
+const result1 = await $`cd /tmp && pwd`;
+console.log('After "cd /tmp && pwd":', result1.stdout.trim());
+
+const result2 = await $`pwd`;
+console.log('Next pwd (should be back to original):', result2.stdout.trim());
+
+console.log('\nTest 2: Multiple cd in chain');
+const result3 = await $`cd /tmp && pwd && cd /usr && pwd`;
+console.log('Result of "cd /tmp && pwd && cd /usr && pwd":');
+console.log(result3.stdout);
+
+console.log('\nTest 3: cd in subshell should not affect parent');
+await $`(cd /tmp && pwd)`;
+const result4 = await $`pwd`;
+console.log('pwd after subshell cd:', result4.stdout.trim());
+
+console.log('\nTest 4: Separate cd commands');
+await $`cd /tmp`;
+const result5 = await $`pwd`;
+console.log('After separate "cd /tmp":', result5.stdout.trim());
+
+await $`cd /usr`;
+const result6 = await $`pwd`;
+console.log('After separate "cd /usr":', result6.stdout.trim());
+
+// Return to original
+process.chdir(originalCwd);
+console.log('\nFinal cwd:', process.cwd());

package/js/examples/test-child-process-timing.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Debug child process timing ===');
+
+async function debugChildProcessTiming() {
+  const cmd = $`sleep 2`; // Use sleep to keep process alive
+
+  console.log('Initial state:');
+  console.log('- started:', cmd.started);
+  console.log('- finished:', cmd.finished);
+  console.log('- child:', !!cmd.child);
+
+  console.log('\\nAccessing streams.stdin to trigger auto-start...');
+  const stdin = cmd.streams.stdin;
+
+  console.log('After accessing streams.stdin:');
+  console.log('- stdin result:', !!stdin);
+  console.log('- started:', cmd.started);
+  console.log('- finished:', cmd.finished);
+  console.log('- child:', !!cmd.child);
+
+  if (cmd.child) {
+    console.log('- child.stdin:', !!cmd.child.stdin);
+    console.log('- child.stdout:', !!cmd.child.stdout);
+    console.log('- child.stderr:', !!cmd.child.stderr);
+  }
+
+  // Wait a bit to see if child appears
+  await new Promise((resolve) => setTimeout(resolve, 100));
+
+  console.log('\\nAfter 100ms wait:');
+  console.log('- started:', cmd.started);
+  console.log('- finished:', cmd.finished);
+  console.log('- child:', !!cmd.child);
+
+  if (cmd.child) {
+    console.log('- child.stdin:', !!cmd.child.stdin);
+    console.log('- child.pid:', cmd.child.pid);
+  }
+
+  // Try accessing again
+  const stdin2 = cmd.streams.stdin;
+  console.log('\\nSecond access to streams.stdin:');
+  console.log('- stdin result:', !!stdin2);
+
+  // Let the sleep finish
+  const result = await cmd;
+  console.log('\\nFinal result:', result.code);
+}
+
+debugChildProcessTiming().catch(console.error);

package/js/examples/test-child-sigint-handler.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import { spawn } from 'child_process';
+
+console.log('Testing child SIGINT handler');
+
+const nodeCode = `
+  let cleanupDone = false;
+  process.on('SIGINT', () => {
+    console.log('CHILD_CLEANUP_START');
+    // Simulate cleanup work
+    setTimeout(() => {
+      cleanupDone = true;
+      console.log('CHILD_CLEANUP_DONE');
+      process.exit(0); // Exit cleanly after cleanup
+    }, 100);
+  });
+  
+  console.log('CHILD_READY');
+  
+  // Keep process alive
+  setTimeout(() => {
+    console.log('TIMEOUT_REACHED');
+    process.exit(1);
+  }, 5000);
+`;
+
+const child = spawn('node', ['-e', nodeCode], {
+  stdio: ['pipe', 'pipe', 'pipe'],
+  detached: true,
+});
+
+console.log('Child spawned with PID:', child.pid);
+
+let stdout = '';
+child.stdout.on('data', (data) => {
+  stdout += data.toString();
+  console.log('Stdout:', data.toString().trim());
+});
+
+child.stderr.on('data', (data) => {
+  console.log('Stderr:', data.toString().trim());
+});
+
+// Wait for child to be ready
+setTimeout(() => {
+  console.log('Sending SIGINT to child...');
+  const result = child.kill('SIGINT');
+  console.log('Kill result:', result);
+}, 500);
+
+child.on('exit', (code, signal) => {
+  console.log('Child exited with code:', code, 'signal:', signal);
+  console.log('Total stdout:', stdout);
+  process.exit(0);
+});
+
+// Timeout safety
+setTimeout(() => {
+  console.log('Timeout reached, force killing...');
+  child.kill('SIGKILL');
+}, 4000);

package/js/examples/test-cleanup-simple.mjs

@@ -0,0 +1,21 @@
+import { $ } from '../src/$.mjs';
+
+console.log('Testing stream cleanup...');
+
+let count = 0;
+for await (const chunk of $`yes x`.stream()) {
+  count++;
+  console.log(`Chunk ${count}`);
+  if (count >= 3) {
+    console.log('Breaking...');
+    break;
+  }
+}
+
+console.log('After break');
+
+// Small delay to see if output continues
+await new Promise((r) => setTimeout(r, 100));
+
+console.log('Done');
+process.exit(0);

package/js/examples/test-comprehensive-tracing.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+/**
+ * Tracing System Overview
+ *
+ * The command-stream library includes comprehensive tracing for CI debugging.
+ * Instead of one large test, each aspect is tested in separate focused examples:
+ *
+ * Individual Tracing Examples:
+ * - trace-simple-command.mjs     - Basic command execution
+ * - trace-signal-handling.mjs    - Process killing and SIGINT handling
+ * - trace-abort-controller.mjs   - AbortController integration
+ * - trace-stderr-output.mjs      - Stdout/stderr stream handling
+ * - trace-pipeline-command.mjs   - Pipeline command execution
+ * - trace-error-handling.mjs     - Error conditions and cleanup
+ *
+ * Usage for any example:
+ *   COMMAND_STREAM_TRACE=ProcessRunner node js/examples/trace-[example-name].mjs
+ *
+ * For CI debugging, enable tracing in your test runs:
+ *   COMMAND_STREAM_TRACE=ProcessRunner bun test
+ */
+
+console.log('Tracing System Overview');
+console.log('='.repeat(50));
+console.log('');
+console.log('The tracing system provides detailed logs for:');
+console.log('• Process creation and spawning');
+console.log('• Signal handling and process killing');
+console.log('• Stdin/stdout/stderr handling');
+console.log('• Virtual command execution');
+console.log('• Cleanup operations');
+console.log('• Error conditions');
+console.log('• Platform-specific behavior differences');
+console.log('');
+console.log('Run individual examples to test specific areas:');
+console.log('');
+console.log(
+  'COMMAND_STREAM_TRACE=ProcessRunner node js/examples/trace-simple-command.mjs'
+);
+console.log(
+  'COMMAND_STREAM_TRACE=ProcessRunner node js/examples/trace-signal-handling.mjs'
+);
+console.log(
+  'COMMAND_STREAM_TRACE=ProcessRunner node js/examples/trace-abort-controller.mjs'
+);
+console.log(
+  'COMMAND_STREAM_TRACE=ProcessRunner node js/examples/trace-stderr-output.mjs'
+);
+console.log(
+  'COMMAND_STREAM_TRACE=ProcessRunner node js/examples/trace-pipeline-command.mjs'
+);
+console.log(
+  'COMMAND_STREAM_TRACE=ProcessRunner node js/examples/trace-error-handling.mjs'
+);
+console.log('');
+console.log('💡 Use COMMAND_STREAM_TRACE=* to see all tracing categories');
+console.log('💡 Add COMMAND_STREAM_VERBOSE=true for even more detail');

package/js/examples/test-correct-space-handling.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+import { $, shell, enableVirtualCommands } from '../src/$.mjs';
+import { mkdtempSync, rmSync, mkdirSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+enableVirtualCommands();
+shell.verbose(true);
+
+console.log('=== Correct handling of paths with spaces ===\n');
+
+const baseDir = mkdtempSync(join(tmpdir(), 'space-test-'));
+const dirWithSpaces = join(baseDir, 'my test directory');
+mkdirSync(dirWithSpaces);
+const originalCwd = process.cwd();
+
+console.log('Directory created:', dirWithSpaces);
+
+try {
+  console.log('\nCorrect way: Let $ handle the quoting');
+  // This is the correct way - let the template literal handle quoting
+  const result1 = await $`cd ${dirWithSpaces}`;
+  console.log('Exit code:', result1.code);
+
+  const pwd1 = await $`pwd`;
+  console.log('Current dir:', pwd1.stdout.trim());
+  console.log('Expected:', dirWithSpaces);
+  console.log('Match:', pwd1.stdout.trim() === dirWithSpaces);
+
+  await $`cd ${originalCwd}`;
+
+  console.log('\nAlso works: cd with && chain');
+  const result2 = await $`cd ${dirWithSpaces} && pwd`;
+  console.log('Output:', result2.stdout.trim());
+  console.log('Expected:', dirWithSpaces);
+  console.log('Match:', result2.stdout.trim() === dirWithSpaces);
+} catch (error) {
+  console.error('Error:', error.message);
+  console.error('Stack:', error.stack);
+} finally {
+  process.chdir(originalCwd);
+  rmSync(baseDir, { recursive: true, force: true });
+}
+
+console.log('\n=== Test Complete ===');

package/js/examples/test-ctrl-c-debug.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing CTRL+C signal propagation');
+console.log('Press CTRL+C to interrupt...');
+console.log('---');
+
+// Set up comprehensive signal handlers
+let parentSigintCount = 0;
+process.on('SIGINT', () => {
+  parentSigintCount++;
+  console.log(`\n[Parent] Received SIGINT (count: ${parentSigintCount})`);
+
+  // Don't exit on first SIGINT to see what happens
+  if (parentSigintCount >= 2) {
+    console.log('[Parent] Exiting after 2 SIGINTs');
+    process.exit(130);
+  }
+});
+
+process.on('SIGTERM', () => {
+  console.log('\n[Parent] Received SIGTERM');
+});
+
+process.on('exit', (code) => {
+  console.log(`[Parent] Exiting with code: ${code}`);
+});
+
+// Test the command
+try {
+  console.log('Starting sleep 30...');
+  console.log('Process info:', {
+    pid: process.pid,
+    ppid: process.ppid,
+  });
+
+  const result = await $`sleep 30`;
+  console.log('Command completed normally');
+} catch (error) {
+  console.log('\n[Parent] Command failed/interrupted');
+  console.log('Error message:', error.message);
+  console.log('Exit code:', error.code);
+}

package/js/examples/test-ctrl-c-inherit.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing CTRL+C with explicit stdio inherit');
+console.log('Press CTRL+C to interrupt the ping command...');
+console.log('---');
+
+// Set up SIGINT handler to see if parent process receives it
+process.on('SIGINT', () => {
+  console.log('\n[Parent process received SIGINT]');
+  process.exit(130); // Standard exit code for SIGINT
+});
+
+try {
+  // Test with different configurations
+  console.log(
+    'Running with default settings (should inherit stdin/stdout/stderr)...'
+  );
+  const result = await $({
+    stdin: 'inherit',
+    capture: false,
+    mirror: true,
+  })`ping 8.8.8.8`;
+  console.log('Command completed normally:', result);
+} catch (error) {
+  console.log('Command was interrupted or failed');
+  console.log('Error:', error.message);
+  console.log('Exit code:', error.code);
+}

package/js/examples/test-ctrl-c-sleep.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing CTRL+C with sleep command');
+console.log('Press CTRL+C to interrupt the sleep...');
+console.log('---');
+
+// Set up SIGINT handler to see if parent process receives it
+let signalReceived = false;
+process.on('SIGINT', () => {
+  console.log('\n[Parent process received SIGINT]');
+  signalReceived = true;
+});
+
+try {
+  console.log('Starting 30 second sleep...');
+  const result = await $`sleep 30`;
+  console.log('Sleep completed normally:', result);
+} catch (error) {
+  console.log('\nCommand was interrupted or failed');
+  console.log('Error:', error.message);
+  console.log('Exit code:', error.code);
+  console.log('Parent received SIGINT:', signalReceived);
+}
+
+// Give a moment for any pending signals
+setTimeout(() => {
+  console.log('Final state - Parent received SIGINT:', signalReceived);
+  process.exit(signalReceived ? 130 : 0);
+}, 100);

package/js/examples/test-ctrl-c.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing CTRL+C handling with ping command');
+console.log('Press CTRL+C to interrupt the ping command...');
+console.log('---');
+
+try {
+  // Test with ping command that runs indefinitely
+  const result = await $`ping 8.8.8.8`;
+  console.log('Command completed normally:', result);
+} catch (error) {
+  console.log('Command was interrupted or failed');
+  console.log('Error:', error.message);
+  console.log('Exit code:', error.code);
+}

package/js/examples/test-debug-new-options.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+async function debug() {
+  console.log('=== Debugging how new options work ===');
+
+  // First let's see what happens with await directly
+  console.log('\n1. Direct await $`echo test`:');
+  const result1 = await $`echo "direct await"`;
+  console.log('Result stdout:', JSON.stringify(result1.stdout));
+
+  // Now let's check the runner before starting
+  console.log('\n2. Inspecting runner before start:');
+  const runner = $`echo "before start"`;
+  console.log('Runner options before start:', runner.options);
+  console.log(
+    'Runner outChunks before start:',
+    runner.outChunks ? 'array' : 'null'
+  );
+
+  // Now call start with capture: false
+  console.log('\n3. Calling start with capture: false:');
+  const result2 = await runner.start({ capture: false });
+  console.log('Runner options after start:', runner.options);
+  console.log('Result stdout:', JSON.stringify(result2.stdout));
+
+  // Test with .run() method
+  console.log('\n4. Testing .run() method:');
+  const result3 = await $`echo "run method test"`.run({
+    capture: false,
+    mirror: false,
+  });
+  console.log('Result stdout:', JSON.stringify(result3.stdout));
+  console.log('Result code:', result3.code);
+
+  // Test runner state inspection
+  console.log('\n5. Runner state inspection:');
+  const runner2 = $`echo "state test"`;
+  console.log('Initial state:');
+  console.log('  started:', runner2.started);
+  console.log('  options.capture:', runner2.options.capture);
+  console.log('  outChunks:', runner2.outChunks ? 'array' : 'null');
+
+  console.log('\nCalling start with capture: false...');
+  const result4 = await runner2.start({ capture: false });
+
+  console.log('\nAfter start:');
+  console.log('  started:', runner2.started);
+  console.log('  options.capture:', runner2.options.capture);
+  console.log('  outChunks:', runner2.outChunks);
+  console.log('  result.stdout:', JSON.stringify(result4.stdout));
+}
+
+debug().catch(console.error);

package/js/examples/test-debug-pty.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env bun
+
+import { $ } from '../src/$.mjs';
+
+// Add debug logging
+const original_runPipeline = $.prototype._runPipeline;
+$.prototype._runPipeline = async function (commands) {
+  console.log(
+    'Pipeline commands:',
+    commands.map((c) => c.cmd)
+  );
+  const result = await original_runPipeline.call(this, commands);
+  return result;
+};
+
+const original_runStreamingPipelineBun = $.prototype._runStreamingPipelineBun;
+$.prototype._runStreamingPipelineBun = async function (commands) {
+  const hasJq = commands.some((c) => c.cmd === 'jq');
+  const hasVirtual = commands.some((c) => c.isVirtual);
+  console.log(
+    `Streaming pipeline: hasJq=${hasJq}, hasVirtual=${hasVirtual}, platform=${process.platform}`
+  );
+
+  const result = await original_runStreamingPipelineBun.call(this, commands);
+  return result;
+};
+
+console.log('Testing pipeline routing:\n');
+
+// Test with actual file to avoid shell wrapper
+console.log('Test 1: Using actual file command:');
+const start = Date.now();
+for await (const chunk of $`./js/examples/emulate-claude-stream.mjs | jq .`.stream()) {
+  if (chunk.type === 'stdout') {
+    const elapsed = Date.now() - start;
+    const lines = chunk.data.toString().trim().split('\n').slice(0, 2);
+    console.log(`[${elapsed}ms] First lines:`, lines);
+  }
+}
+
+console.log('\nTest 2: Using bun run:');
+const start2 = Date.now();
+for await (const chunk of $`bun run js/examples/emulate-claude-stream.mjs | jq .`.stream()) {
+  if (chunk.type === 'stdout') {
+    const elapsed = Date.now() - start2;
+    const lines = chunk.data.toString().trim().split('\n').slice(0, 2);
+    console.log(`[${elapsed}ms] First lines:`, lines);
+  }
+}

package/js/examples/test-debug-tee.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env bun
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Debug Tee Streaming ===\n');
+
+// Patch the emit function to trace calls
+const cmd = $`bun run js/examples/emulate-claude-stream.mjs | cat | jq .`;
+const originalEmit = cmd.emit.bind(cmd);
+let emitCount = 0;
+
+cmd.emit = function (event, data) {
+  if (event === 'stdout' || event === 'data') {
+    emitCount++;
+    const preview = data.toString
+      ? data.toString().substring(0, 40)
+      : JSON.stringify(data).substring(0, 40);
+    console.log(`EMIT #${emitCount} [${event}]: ${preview}...`);
+  }
+  return originalEmit(event, data);
+};
+
+console.log('Running command...\n');
+const start = Date.now();
+
+const result = await cmd;
+
+console.log(`\nTotal emits: ${emitCount}`);
+console.log(`Time taken: ${Date.now() - start}ms`);
+console.log(`Result length: ${result.stdout.length} chars`);
+
+if (emitCount >= 8) {
+  console.log('✅ Multiple emissions detected - streaming is working!');
+} else if (emitCount === 2) {
+  console.log('⚠️  Only 2 emissions (stdout + data) - likely buffered');
+} else {
+  console.log(`❌ Unexpected emit count: ${emitCount}`);
+}

package/js/examples/test-debug.mjs

@@ -0,0 +1,25 @@
+import { $ } from '../src/$.mjs';
+
+console.log('Starting test...');
+
+const cmd = $`yes x`;
+let count = 0;
+
+// Track when we start iterating
+console.log('Starting iteration...');
+
+for await (const chunk of cmd.stream()) {
+  count++;
+  console.log(`Got chunk ${count}`);
+
+  if (count >= 2) {
+    console.log('Breaking now...');
+    break;
+  }
+}
+
+console.log('After break');
+console.log('Finished:', cmd.finished);
+console.log('Cancelled:', cmd._cancelled);
+
+process.exit(0);

package/js/examples/test-direct-jq.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env bun
+
+// Test spawning jq directly without sh -c
+
+console.log('Test: Spawn processes directly and pipe them\n');
+
+// First process: emulator
+const proc1 = Bun.spawn(['./js/examples/emulate-claude-stream.mjs'], {
+  stdout: 'pipe',
+  stderr: 'pipe',
+});
+
+// Second process: jq with stdin from first process
+const proc2 = Bun.spawn(['jq', '.'], {
+  stdin: proc1.stdout,
+  stdout: 'pipe',
+  stderr: 'pipe',
+});
+
+const start = Date.now();
+let chunkCount = 0;
+
+for await (const chunk of proc2.stdout) {
+  chunkCount++;
+  const elapsed = Date.now() - start;
+  const text = Buffer.from(chunk).toString();
+  const lines = text.split('\n').filter((l) => l.trim());
+
+  if (chunkCount === 1) {
+    console.log(
+      `[${elapsed}ms] First chunk arrived with ${lines.length} lines`
+    );
+    console.log('First few lines:', lines.slice(0, 3));
+  } else {
+    console.log(
+      `[${elapsed}ms] Chunk ${chunkCount} with ${lines.length} lines`
+    );
+  }
+}
+
+console.log(`\nTotal chunks received: ${chunkCount}`);
+console.log(
+  'If streaming worked, we should see multiple chunks at different times'
+);
+
+await proc1.exited;
+await proc2.exited;