command-stream 0.8.2 → 0.9.0

package/js/examples/ci-debug-stdout-buffering.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+/**
+ * Example: Debugging stdout buffering issues in CI environments
+ *
+ * Problem: In CI environments (non-TTY), stdout is often buffered, causing
+ * output to not appear immediately. This can make tests fail when they expect
+ * immediate output.
+ *
+ * Solution: Force stdout flush in non-TTY environments.
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing stdout buffering in CI environment');
+console.log('Is TTY?', process.stdout.isTTY);
+
+// Example 1: Force flush in non-TTY environment
+async function testWithFlush() {
+  console.log('TEST 1: With stdout flush');
+
+  // Write and immediately flush
+  process.stdout.write('IMMEDIATE_OUTPUT\n');
+
+  // Force flush if not TTY (CI environment)
+  if (!process.stdout.isTTY && process.stdout.write('', () => {})) {
+    // This forces a flush
+  }
+
+  // Small delay to demonstrate the difference
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  console.log('After delay');
+}
+
+// Example 2: Using command-stream with proper output handling
+async function testCommandStream() {
+  console.log('\nTEST 2: Using command-stream');
+
+  // This should handle output correctly in CI
+  const result = await $`echo "COMMAND_OUTPUT"`;
+  console.log('Result:', result.stdout);
+
+  // For streaming output in CI
+  const runner = $`echo "STREAMING_START" && sleep 0.1 && echo "STREAMING_END"`;
+
+  for await (const chunk of runner.stream()) {
+    process.stdout.write(`Chunk: ${chunk.data}`);
+    // Force flush in CI
+    if (!process.stdout.isTTY) {
+      process.stdout.write('', () => {});
+    }
+  }
+}
+
+// Example 3: Debugging missing output in CI
+async function debugMissingOutput() {
+  console.log('\nTEST 3: Debugging missing output');
+
+  // Add timestamps to understand timing
+  const log = (msg) => {
+    const timestamp = new Date().toISOString();
+    const message = `[${timestamp}] ${msg}\n`;
+    process.stderr.write(message); // stderr is often unbuffered
+    process.stdout.write(message);
+
+    // Force flush
+    if (!process.stdout.isTTY) {
+      process.stdout.write('', () => {});
+    }
+  };
+
+  log('Starting test');
+  log('Running command...');
+
+  const result = await $`echo "TEST_OUTPUT"`;
+  log(`Command completed with code ${result.code}`);
+  log(`Output: ${result.stdout}`);
+}
+
+// Run tests
+async function main() {
+  try {
+    await testWithFlush();
+    await testCommandStream();
+    await debugMissingOutput();
+
+    console.log('\nAll tests completed successfully');
+  } catch (error) {
+    console.error('Test failed:', error);
+    process.exit(1);
+  }
+}
+
+main();

package/js/examples/ci-debug-test-timeouts.mjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+
+/**
+ * Example: Debugging test timeout issues in CI
+ *
+ * Problem: Tests hang indefinitely in CI without proper timeout configuration,
+ * causing the entire CI job to timeout after hours.
+ *
+ * Solution: Add proper timeouts to all tests and handle stuck processes.
+ */
+
+import { spawn } from 'child_process';
+import { $ } from '../src/$.mjs';
+
+console.log('Testing timeout handling strategies');
+
+// Example 1: Test with no timeout (problematic)
+async function testNoTimeout() {
+  console.log('\nTEST 1: Command with no timeout (problematic)');
+  console.log('This would hang forever in CI...');
+
+  // DON'T DO THIS - example of what to avoid
+  // const result = await $`sleep 999999`;
+
+  console.log('Skipping actual execution to prevent hang');
+}
+
+// Example 2: Test with promise race timeout
+async function testPromiseRaceTimeout() {
+  console.log('\nTEST 2: Using Promise.race for timeout');
+
+  const command = $`sleep 30`;
+  const timeout = new Promise((_, reject) => {
+    setTimeout(() => reject(new Error('Command timeout')), 2000);
+  });
+
+  try {
+    const result = await Promise.race([command, timeout]);
+    console.log('Command completed:', result.stdout);
+  } catch (error) {
+    console.log('✓ Command timed out as expected:', error.message);
+    // Clean up the command
+    command.kill();
+  }
+}
+
+// Example 3: Test with AbortController
+async function testAbortController() {
+  console.log('\nTEST 3: Using AbortController for timeout');
+
+  const controller = new AbortController();
+
+  // Set timeout
+  const timeoutId = setTimeout(() => {
+    console.log('Timeout reached, aborting...');
+    controller.abort();
+  }, 2000);
+
+  try {
+    const result = await $`sleep 30`.start({ signal: controller.signal });
+    clearTimeout(timeoutId);
+    console.log('Command completed:', result.stdout);
+  } catch (error) {
+    console.log('✓ Command aborted:', error.message);
+  }
+}
+
+// Example 4: Custom timeout wrapper
+async function withTimeout(promise, ms, message = 'Operation timed out') {
+  const timeout = new Promise((_, reject) => {
+    setTimeout(() => reject(new Error(message)), ms);
+  });
+
+  return Promise.race([promise, timeout]);
+}
+
+async function testCustomTimeoutWrapper() {
+  console.log('\nTEST 4: Custom timeout wrapper');
+
+  try {
+    const result = await withTimeout(
+      $`sleep 30`,
+      2000,
+      'Command exceeded 2 second timeout'
+    );
+    console.log('Command completed:', result.stdout);
+  } catch (error) {
+    console.log('✓ Timeout wrapper worked:', error.message);
+  }
+}
+
+// Example 5: Bun test timeout pattern
+async function testBunTestPattern() {
+  console.log('\nTEST 5: Bun test timeout pattern');
+
+  // This shows how to add timeouts in Bun tests
+  const exampleTest = `
+    import { test, expect } from 'bun:test';
+    
+    // WITHOUT TIMEOUT - Can hang forever
+    test('problematic test', async () => {
+      await $\`sleep 999999\`;
+    });
+    
+    // WITH TIMEOUT - Will fail after 5 seconds
+    test('properly configured test', async () => {
+      await $\`sleep 999999\`;
+    }, 5000); // <-- Timeout in milliseconds
+    
+    // WITH CUSTOM TIMEOUT for long operations
+    test('long running test', async () => {
+      // Some operation that legitimately takes time
+      await $\`npm install\`;
+    }, 60000); // 60 second timeout
+  `;
+
+  console.log('Example Bun test with timeout:');
+  console.log(exampleTest);
+}
+
+// Example 6: Detecting stuck processes
+async function testStuckProcessDetection() {
+  console.log('\nTEST 6: Detecting stuck processes');
+
+  const child = spawn('sleep', ['30'], {
+    stdio: 'pipe',
+  });
+
+  console.log(`Started process with PID ${child.pid}`);
+
+  // Monitor for inactivity
+  let lastActivity = Date.now();
+  const inactivityTimeout = 2000; // 2 seconds
+
+  const monitor = setInterval(() => {
+    const idle = Date.now() - lastActivity;
+    if (idle > inactivityTimeout) {
+      console.log(`Process ${child.pid} appears stuck (idle for ${idle}ms)`);
+      console.log('Killing stuck process...');
+      child.kill('SIGKILL');
+      clearInterval(monitor);
+    }
+  }, 500);
+
+  // Update activity on any output
+  child.stdout.on('data', () => {
+    lastActivity = Date.now();
+  });
+  child.stderr.on('data', () => {
+    lastActivity = Date.now();
+  });
+
+  await new Promise((resolve) => {
+    child.on('exit', (code, signal) => {
+      clearInterval(monitor);
+      console.log(`Process exited with code ${code}, signal ${signal}`);
+      resolve();
+    });
+  });
+}
+
+// Example 7: CI-specific timeout configuration
+async function testCITimeoutConfig() {
+  console.log('\nTEST 7: CI-specific timeout configuration');
+
+  const isCI = process.env.CI === 'true';
+
+  // Use different timeouts for CI vs local
+  const timeouts = {
+    default: isCI ? 30000 : 5000, // 30s in CI, 5s local
+    long: isCI ? 120000 : 30000, // 2min in CI, 30s local
+    network: isCI ? 60000 : 10000, // 1min in CI, 10s local
+  };
+
+  console.log('Timeout configuration:');
+  console.log(`- Environment: ${isCI ? 'CI' : 'Local'}`);
+  console.log(`- Default timeout: ${timeouts.default}ms`);
+  console.log(`- Long operation timeout: ${timeouts.long}ms`);
+  console.log(`- Network operation timeout: ${timeouts.network}ms`);
+
+  // Example usage
+  try {
+    await withTimeout(
+      $`sleep 30`,
+      timeouts.default,
+      `Command exceeded ${isCI ? 'CI' : 'local'} timeout`
+    );
+  } catch (error) {
+    console.log('✓ CI-aware timeout worked:', error.message);
+  }
+}
+
+// Example 8: Cleanup after timeout
+async function testTimeoutCleanup() {
+  console.log('\nTEST 8: Cleanup after timeout');
+
+  const runners = [];
+  const startRunner = (name) => {
+    const runner = $`sleep 30`;
+    runners.push({ name, runner });
+    return runner.start();
+  };
+
+  // Start multiple commands
+  const promises = [
+    startRunner('command1'),
+    startRunner('command2'),
+    startRunner('command3'),
+  ];
+
+  // Set global timeout
+  setTimeout(() => {
+    console.log('Global timeout reached, cleaning up all runners...');
+    runners.forEach(({ name, runner }) => {
+      if (!runner.finished) {
+        console.log(`Killing ${name}`);
+        runner.kill();
+      }
+    });
+  }, 2000);
+
+  // Wait for all to finish (either naturally or by timeout)
+  const results = await Promise.allSettled(promises);
+
+  results.forEach((result, i) => {
+    const status = result.status === 'fulfilled' ? 'completed' : 'failed';
+    console.log(`${runners[i].name}: ${status}`);
+  });
+
+  // Verify cleanup
+  const unfinished = runners.filter((r) => !r.runner.finished);
+  console.log(`Unfinished runners: ${unfinished.length}`);
+}
+
+// Run tests
+async function main() {
+  try {
+    console.log('Environment:');
+    console.log(`- CI: ${process.env.CI || 'false'}`);
+    console.log(`- Node: ${process.version}`);
+    console.log(`- Platform: ${process.platform}`);
+
+    await testNoTimeout();
+    await testPromiseRaceTimeout();
+    await testAbortController();
+    await testCustomTimeoutWrapper();
+    await testBunTestPattern();
+    await testStuckProcessDetection();
+    await testCITimeoutConfig();
+    await testTimeoutCleanup();
+
+    console.log('\nAll timeout tests completed successfully');
+  } catch (error) {
+    console.error('Test failed:', error);
+    process.exit(1);
+  }
+}
+
+main();

package/js/examples/claude-exact-file-output.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+import { appendFileSync } from 'fs';
+
+const claude = 'claude';
+const logFile = 'claude-output.log';
+
+console.log('🤖 Claude streaming to console and file');
+
+let events = 0;
+for await (const chunk of $`${claude} -p "hi" --output-format stream-json --verbose --model sonnet`.stream()) {
+  const data = chunk.data.toString();
+  console.log(`📦 Event ${++events}: ${data.trim()}`);
+
+  // Write to file simultaneously
+  appendFileSync(logFile, `Event ${events}: ${data}`);
+}
+
+console.log(`✅ ${events} events streamed to console and saved to ${logFile}`);

package/js/examples/claude-exact-jq.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+const claude = 'claude';
+console.log('🤖 Claude → jq streaming pipeline');
+
+let events = 0;
+for await (const chunk of $`${claude} -p "hi" --output-format stream-json --verbose --model sonnet | jq`.stream()) {
+  console.log(`📦 Event ${++events}: ${chunk.data.toString().trim()}`);
+}
+
+console.log(`✅ Pipeline completed with ${events} events`);

package/js/examples/claude-exact-streaming.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+const claude = 'claude';
+console.log('🤖 Claude exact streaming example');
+
+let events = 0;
+for await (const chunk of $`${claude} -p "hi" --output-format stream-json --verbose --model sonnet`.stream()) {
+  console.log(`📦 Event ${++events}: ${chunk.data.toString().trim()}`);
+}
+
+console.log(`✅ Received ${events} streaming events`);

package/js/examples/claude-jq-pipeline.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('🤖 Claude → jq streaming pipeline');
+
+// Claude with JSON output piped to jq
+let events = 0;
+for await (const chunk of $`claude "say hi" --output-format stream-json | jq -r '.type // empty'`.stream()) {
+  console.log(`📦 Event ${++events}: ${chunk.data.toString().trim()}`);
+}
+
+console.log(`✅ Pipeline completed with ${events} events`);

package/js/examples/claude-json-stream.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// Test Claude in JSON streaming mode
+import { spawn } from 'child_process';
+
+console.log('=== Claude JSON streaming test ===');
+
+let chunkCount = 0;
+const child = spawn('claude', ['hi', '--output-format', 'stream-json'], {
+  stdio: 'pipe',
+});
+
+child.stdout.on('data', (data) => {
+  chunkCount++;
+  const str = data.toString();
+  console.log(`JSON chunk ${chunkCount}:`, str);
+
+  // Try to parse each line as JSON
+  str
+    .split('\n')
+    .filter((line) => line.trim())
+    .forEach((line, i) => {
+      try {
+        const json = JSON.parse(line);
+        console.log(`  Parsed line ${i + 1}:`, json);
+      } catch (e) {
+        console.log(`  Raw line ${i + 1}:`, line);
+      }
+    });
+});
+
+child.stderr.on('data', (data) => {
+  console.log('stderr:', data.toString());
+});
+
+child.on('close', (code) => {
+  console.log(
+    `Process closed with code ${code}, received ${chunkCount} chunks`
+  );
+});

package/js/examples/claude-streaming-basic.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+/**
+ * Basic Claude streaming example with command-stream
+ *
+ * This example demonstrates:
+ * 1. Real-time streaming output from Claude
+ * 2. Multiple chunks/events being captured
+ * 3. Both console display and file writing simultaneously
+ */
+
+import { $ } from '../src/$.mjs';
+import { writeFileSync, appendFileSync, existsSync } from 'fs';
+
+// Claude command - using a prompt that should generate multiple chunks
+const claudeCommand = 'claude';
+const prompt =
+  'Count from 1 to 5, explaining each number briefly. Use --output-format stream-json if available.';
+
+console.log('🚀 Starting Claude streaming example...\n');
+
+// Clean up any existing log file
+const logFile = 'claude-streaming.log';
+if (existsSync(logFile)) {
+  writeFileSync(logFile, '');
+}
+
+console.log('📝 Command being executed:');
+console.log(`${claudeCommand} "${prompt}"`);
+console.log('\n🌊 Streaming output:\n');
+
+let chunkCount = 0;
+let totalOutput = '';
+
+try {
+  // Create the command but don't start it yet
+  const command = $`${claudeCommand} "${prompt}"`;
+
+  // Attach event handlers
+  command
+    .on('data', (chunk) => {
+      chunkCount++;
+      const data = chunk.data.toString();
+
+      console.log(`📦 Chunk ${chunkCount} (${chunk.type}):`);
+      console.log(data);
+      console.log('---');
+
+      // Write to log file in real-time
+      appendFileSync(
+        logFile,
+        `=== Chunk ${chunkCount} (${chunk.type}) ===\n${data}\n`
+      );
+
+      totalOutput += data;
+    })
+    .on('stderr', (chunk) => {
+      const data = chunk.toString();
+      console.log('⚠️ stderr:', data);
+      appendFileSync(logFile, `=== STDERR ===\n${data}\n`);
+    })
+    .on('end', (result) => {
+      console.log('\n✅ Streaming completed!');
+      console.log(`📊 Total chunks received: ${chunkCount}`);
+      console.log(`📁 Log saved to: ${logFile}`);
+      console.log(`🎯 Exit code: ${result.code}`);
+      console.log(`📏 Total output length: ${totalOutput.length} characters`);
+
+      // Write final summary
+      appendFileSync(
+        logFile,
+        `\n=== SUMMARY ===\nTotal chunks: ${chunkCount}\nExit code: ${result.code}\nTotal length: ${totalOutput.length}\n`
+      );
+    })
+    .on('error', (error) => {
+      console.error('❌ Error:', error);
+      appendFileSync(logFile, `=== ERROR ===\n${error}\n`);
+    });
+
+  // Start the command
+  await command.start();
+} catch (error) {
+  console.error('💥 Failed to execute command:', error.message);
+
+  // Check if claude command is available
+  try {
+    const checkResult = await $`which ${claudeCommand}`;
+    if (checkResult.code !== 0) {
+      console.log(
+        '\n💡 Tip: Make sure Claude CLI is installed and in your PATH'
+      );
+      console.log(
+        '   You can install it from: https://github.com/anthropics/claude-cli'
+      );
+    }
+  } catch (checkError) {
+    console.log('\n💡 Claude CLI not found in PATH. Please install it first.');
+  }
+}

package/js/examples/claude-streaming-demo.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+/**
+ * Claude streaming demo with command-stream
+ *
+ * This demonstrates:
+ * 1. Real-time streaming output
+ * 2. Multiple chunks/events being captured
+ * 3. Simultaneous console display and file writing
+ * 4. Handling of both stdout and stderr
+ */
+
+import { $ } from '../src/$.mjs';
+import { writeFileSync, appendFileSync, existsSync } from 'fs';
+
+// We'll use a command that produces output over time to simulate streaming
+// If claude is not available, we'll fall back to a simulation
+const claudeCommand = 'claude';
+const fallbackCommand =
+  'sh -c \'for i in $(seq 1 5); do echo "Response chunk $i: This is simulated streaming output from Claude."; sleep 0.5; done\'';
+
+console.log('🚀 Starting Claude streaming demo...\n');
+
+// Clean up any existing log file
+const logFile = 'claude-streaming-demo.log';
+if (existsSync(logFile)) {
+  writeFileSync(logFile, '');
+}
+
+let chunkCount = 0;
+let totalOutput = '';
+
+async function runClaudeDemo() {
+  console.log('📝 Attempting to run Claude command...\n');
+
+  try {
+    // First check if claude is available
+    const claudeCheck = await $`which ${claudeCommand}`;
+
+    if (claudeCheck.code !== 0) {
+      console.log('⚠️ Claude CLI not found, using fallback simulation\n');
+      return runFallbackDemo();
+    }
+
+    // Try to run Claude with streaming output
+    const prompt =
+      'Count from 1 to 5, explaining each number briefly. Make each response a separate chunk if possible.';
+    console.log(`🎯 Command: ${claudeCommand} "${prompt}"`);
+    console.log('\n🌊 Streaming output:\n');
+
+    const command = $`${claudeCommand} "${prompt}"`;
+
+    command
+      .on('data', handleChunk)
+      .on('stderr', handleStderr)
+      .on('end', handleEnd)
+      .on('error', handleError);
+
+    await command.start();
+  } catch (error) {
+    console.log('⚠️ Claude command failed, using fallback simulation\n');
+    return runFallbackDemo();
+  }
+}
+
+async function runFallbackDemo() {
+  console.log('🎯 Running fallback streaming simulation');
+  console.log('🌊 Streaming output:\n');
+
+  const command = $`${fallbackCommand}`;
+
+  command
+    .on('data', handleChunk)
+    .on('stderr', handleStderr)
+    .on('end', handleEnd)
+    .on('error', handleError);
+
+  await command.start();
+}
+
+function handleChunk(chunk) {
+  chunkCount++;
+  const data = chunk.data.toString();
+
+  console.log(`📦 Chunk ${chunkCount} (${chunk.type}):`);
+  console.log(data);
+  console.log('---');
+
+  // Write to log file in real-time
+  appendFileSync(
+    logFile,
+    `=== Chunk ${chunkCount} (${chunk.type}) ===\n${data}\n`
+  );
+
+  totalOutput += data;
+}
+
+function handleStderr(chunk) {
+  const data = chunk.toString();
+  console.log('⚠️ stderr:', data);
+  appendFileSync(logFile, `=== STDERR ===\n${data}\n`);
+}
+
+function handleEnd(result) {
+  console.log('\n✅ Streaming completed!');
+  console.log(`📊 Total chunks received: ${chunkCount}`);
+  console.log(`📁 Log saved to: ${logFile}`);
+  console.log(`🎯 Exit code: ${result.code}`);
+  console.log(`📏 Total output length: ${totalOutput.length} characters`);
+
+  // Write final summary
+  appendFileSync(
+    logFile,
+    `\n=== SUMMARY ===\nTotal chunks: ${chunkCount}\nExit code: ${result.code}\nTotal length: ${totalOutput.length}\n`
+  );
+
+  console.log('\n💡 Pro tip: Check the log file to see all captured output!');
+}
+
+function handleError(error) {
+  console.error('❌ Error:', error);
+  appendFileSync(logFile, `=== ERROR ===\n${error}\n`);
+}
+
+// Run the demo
+runClaudeDemo().catch(console.error);

package/js/examples/claude-streaming-final.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+import { appendFileSync } from 'fs';
+
+console.log('🤖 Claude streaming example');
+
+// Simple prompt that should stream
+let events = 0;
+const logFile = 'claude-stream.log';
+
+for await (const chunk of $`claude hi`.stream()) {
+  const data = chunk.data.toString();
+  console.log(`📦 Event ${++events}: ${data.trim()}`);
+
+  // Write to file simultaneously
+  appendFileSync(logFile, `Event ${events}: ${data}`);
+}
+
+console.log(`✅ Received ${events} streaming events, logged to ${logFile}`);