command-stream 0.8.2 → 0.9.0

package/js/examples/ci-debug-baseline-vs-library.mjs

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+
+/**
+ * Example: Testing baseline spawn behavior vs command-stream library
+ *
+ * Problem: When tests fail in CI, it's important to determine if the issue
+ * is with the library or with the underlying Node.js spawn behavior.
+ *
+ * Solution: Test both baseline (raw spawn) and library functionality to compare.
+ */
+
+import { spawn } from 'child_process';
+import { $ } from '../src/$.mjs';
+
+console.log('Testing baseline vs library behavior');
+
+// Example 1: Baseline spawn test (no library)
+async function testBaselineSpawn() {
+  console.log('\nTEST 1: Baseline spawn (no command-stream)');
+
+  return new Promise((resolve, reject) => {
+    const child = spawn('echo', ['baseline test'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+      console.log('Baseline stdout:', data.toString().trim());
+    });
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+      console.log('Baseline stderr:', data.toString().trim());
+    });
+
+    child.on('exit', (code, signal) => {
+      console.log(`Baseline exit: code=${code}, signal=${signal}`);
+      if (code === 0) {
+        resolve({ stdout, stderr, code });
+      } else {
+        reject(new Error(`Baseline failed: ${code}/${signal}`));
+      }
+    });
+
+    child.on('error', (error) => {
+      console.log('Baseline error:', error.message);
+      reject(error);
+    });
+  });
+}
+
+// Example 2: Library test (using command-stream)
+async function testLibrary() {
+  console.log('\nTEST 2: Library test (using command-stream)');
+
+  try {
+    const result = await $`echo "library test"`;
+    console.log('Library stdout:', result.stdout.trim());
+    console.log(`Library exit: code=${result.code}`);
+    return result;
+  } catch (error) {
+    console.log('Library error:', error.message);
+    throw error;
+  }
+}
+
+// Example 3: Signal handling comparison
+async function testSignalHandlingComparison() {
+  console.log('\nTEST 3: Signal handling comparison');
+
+  // Baseline signal handling
+  console.log('3a. Baseline signal handling:');
+  const baselineChild = spawn('sleep', ['30'], {
+    stdio: 'inherit',
+  });
+
+  setTimeout(() => {
+    console.log('Sending SIGTERM to baseline child...');
+    baselineChild.kill('SIGTERM');
+  }, 1000);
+
+  await new Promise((resolve) => {
+    baselineChild.on('exit', (code, signal) => {
+      console.log(`Baseline exited: code=${code}, signal=${signal}`);
+      resolve();
+    });
+  });
+
+  // Library signal handling
+  console.log('3b. Library signal handling:');
+  const runner = $`sleep 30`;
+  const promise = runner.start();
+
+  setTimeout(() => {
+    console.log('Sending kill to library runner...');
+    runner.kill();
+  }, 1000);
+
+  try {
+    await promise;
+  } catch (error) {
+    console.log(`Library exited: ${error.message}`);
+  }
+  console.log(`Library finished: ${runner.finished}`);
+}
+
+// Example 4: Streaming comparison
+async function testStreamingComparison() {
+  console.log('\nTEST 4: Streaming output comparison');
+
+  // Baseline streaming
+  console.log('4a. Baseline streaming:');
+  await new Promise((resolve) => {
+    const child = spawn(
+      'sh',
+      ['-c', 'for i in 1 2 3; do echo "baseline $i"; sleep 0.1; done'],
+      {
+        stdio: 'pipe',
+      }
+    );
+
+    child.stdout.on('data', (chunk) => {
+      process.stdout.write(`[Baseline chunk]: ${chunk}`);
+    });
+
+    child.on('exit', resolve);
+  });
+
+  // Library streaming
+  console.log('4b. Library streaming:');
+  const runner = $`sh -c 'for i in 1 2 3; do echo "library $i"; sleep 0.1; done'`;
+
+  for await (const chunk of runner.stream()) {
+    process.stdout.write(`[Library chunk]: ${chunk.data}`);
+  }
+}
+
+// Example 5: Error handling comparison
+async function testErrorHandlingComparison() {
+  console.log('\nTEST 5: Error handling comparison');
+
+  // Baseline error handling
+  console.log('5a. Baseline error handling:');
+  try {
+    await new Promise((resolve, reject) => {
+      const child = spawn('false', [], { stdio: 'inherit' });
+      child.on('exit', (code) => {
+        if (code !== 0) {
+          reject(new Error(`Command failed with code ${code}`));
+        } else {
+          resolve();
+        }
+      });
+    });
+  } catch (error) {
+    console.log('Baseline error caught:', error.message);
+  }
+
+  // Library error handling
+  console.log('5b. Library error handling:');
+  try {
+    await $`false`;
+  } catch (error) {
+    console.log('Library error caught:', error.message);
+  }
+}
+
+// Example 6: CI-specific differences
+async function testCISpecificDifferences() {
+  console.log('\nTEST 6: CI-specific behavior differences');
+
+  const isCI = process.env.CI === 'true';
+  const isTTY = process.stdout.isTTY;
+
+  console.log(`Environment: CI=${isCI}, TTY=${isTTY}`);
+
+  // Test that might behave differently in CI
+  const testScript = `
+    if [ -t 0 ]; then
+      echo "TTY detected"
+    else
+      echo "No TTY (typical in CI)"
+    fi
+  `;
+
+  // Baseline
+  console.log('6a. Baseline TTY detection:');
+  await new Promise((resolve) => {
+    const child = spawn('sh', ['-c', testScript], {
+      stdio: 'inherit',
+    });
+    child.on('exit', resolve);
+  });
+
+  // Library
+  console.log('6b. Library TTY detection:');
+  const result = await $`sh -c ${testScript}`;
+  console.log(result.stdout.trim());
+}
+
+// Example 7: Performance comparison
+async function testPerformanceComparison() {
+  console.log('\nTEST 7: Performance comparison');
+
+  const iterations = 10;
+
+  // Baseline performance
+  console.log(`7a. Baseline performance (${iterations} iterations):`);
+  const baselineStart = Date.now();
+  for (let i = 0; i < iterations; i++) {
+    await new Promise((resolve) => {
+      const child = spawn('echo', [`test ${i}`], {
+        stdio: 'ignore',
+      });
+      child.on('exit', resolve);
+    });
+  }
+  const baselineTime = Date.now() - baselineStart;
+  console.log(`Baseline time: ${baselineTime}ms`);
+
+  // Library performance
+  console.log(`7b. Library performance (${iterations} iterations):`);
+  const libraryStart = Date.now();
+  for (let i = 0; i < iterations; i++) {
+    await $({ quiet: true })`echo "test ${i}"`;
+  }
+  const libraryTime = Date.now() - libraryStart;
+  console.log(`Library time: ${libraryTime}ms`);
+
+  console.log(`Overhead: ${libraryTime - baselineTime}ms`);
+}
+
+// Run all comparisons
+async function main() {
+  console.log('Environment info:');
+  console.log(`- Node: ${process.version}`);
+  console.log(`- Platform: ${process.platform}`);
+  console.log(`- CI: ${process.env.CI || 'false'}`);
+  console.log(`- TTY: ${process.stdout.isTTY || false}`);
+
+  try {
+    await testBaselineSpawn();
+    await testLibrary();
+    await testSignalHandlingComparison();
+    await testStreamingComparison();
+    await testErrorHandlingComparison();
+    await testCISpecificDifferences();
+    await testPerformanceComparison();
+
+    console.log('\n✅ All comparison tests completed successfully');
+    console.log('Both baseline and library are working correctly');
+  } catch (error) {
+    console.error('\n❌ Test failed:', error);
+    console.error('This helps identify if the issue is with:');
+    console.error('- The library implementation');
+    console.error('- The underlying Node.js spawn behavior');
+    console.error('- CI environment configuration');
+    process.exit(1);
+  }
+}
+
+main();

package/js/examples/ci-debug-es-module-loading.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+
+/**
+ * Example: Debugging ES module loading failures in CI
+ *
+ * Problem: In CI environments, child processes spawned with ES module imports
+ * sometimes fail immediately with SIGINT or other signals.
+ *
+ * Solution: Use different approaches for loading modules in child processes.
+ */
+
+import { spawn } from 'child_process';
+import { $ } from '../src/$.mjs';
+
+console.log('Testing ES module loading in child processes');
+
+// Example 1: Direct ES module import (may fail in CI)
+async function testDirectESModule() {
+  console.log('\nTEST 1: Direct ES module import in child process');
+
+  const script = `
+    import { $ } from '../src/$.mjs';
+    console.log('Module loaded successfully');
+    const result = await $\`echo "ES module test"\`;
+    console.log('Result:', result.stdout);
+  `;
+
+  try {
+    // This might fail in CI with immediate SIGINT
+    const child = spawn('node', ['--input-type=module', '-e', script], {
+      stdio: 'inherit',
+      cwd: process.cwd(),
+    });
+
+    await new Promise((resolve, reject) => {
+      child.on('exit', (code, signal) => {
+        if (code === 0) {
+          console.log('✓ ES module loaded successfully');
+          resolve();
+        } else {
+          console.log(`✗ Failed with code ${code}, signal ${signal}`);
+          reject(new Error(`Process failed: ${code}/${signal}`));
+        }
+      });
+    });
+  } catch (error) {
+    console.log('Expected failure in CI:', error.message);
+  }
+}
+
+// Example 2: CommonJS fallback approach
+async function testCommonJSFallback() {
+  console.log('\nTEST 2: CommonJS-style dynamic import');
+
+  const script = `
+    (async () => {
+      try {
+        const module = await import('../src/$.mjs');
+        const $ = module.$;
+        console.log('Module loaded via dynamic import');
+        const result = await $\`echo "Dynamic import test"\`;
+        console.log('Result:', result.stdout);
+      } catch (error) {
+        console.error('Import failed:', error.message);
+        process.exit(1);
+      }
+    })();
+  `;
+
+  const child = spawn('node', ['--input-type=module', '-e', script], {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+  });
+
+  await new Promise((resolve) => {
+    child.on('exit', (code, signal) => {
+      console.log(`Process exited with code ${code}, signal ${signal}`);
+      resolve();
+    });
+  });
+}
+
+// Example 3: Simple inline script without imports (most reliable in CI)
+async function testInlineScript() {
+  console.log('\nTEST 3: Inline script without ES module imports');
+
+  const child = spawn(
+    'node',
+    [
+      '-e',
+      `
+    console.log('INLINE_START');
+    setTimeout(() => {
+      console.log('INLINE_END');
+      process.exit(0);
+    }, 100);
+  `,
+    ],
+    {
+      stdio: 'inherit',
+    }
+  );
+
+  await new Promise((resolve) => {
+    child.on('exit', (code) => {
+      console.log(`✓ Inline script completed with code ${code}`);
+      resolve();
+    });
+  });
+}
+
+// Example 4: Shell command fallback (most compatible)
+async function testShellFallback() {
+  console.log('\nTEST 4: Shell command fallback');
+
+  // Use shell commands directly when ES modules fail
+  const child = spawn(
+    'sh',
+    ['-c', 'echo "SHELL_START" && sleep 0.1 && echo "SHELL_END"'],
+    {
+      stdio: 'inherit',
+    }
+  );
+
+  await new Promise((resolve) => {
+    child.on('exit', (code) => {
+      console.log(`✓ Shell command completed with code ${code}`);
+      resolve();
+    });
+  });
+}
+
+// Example 5: Error handling with detailed diagnostics
+async function testWithDiagnostics() {
+  console.log('\nTEST 5: Child process with detailed diagnostics');
+
+  const script = `
+    console.error('[DIAG] Node version:', process.version);
+    console.error('[DIAG] Platform:', process.platform);
+    console.error('[DIAG] CWD:', process.cwd());
+    console.error('[DIAG] Module paths:', module.paths);
+    
+    import('../src/$.mjs').then(
+      (module) => {
+        console.log('SUCCESS: Module loaded');
+        process.exit(0);
+      },
+      (error) => {
+        console.error('FAILURE: Cannot load module');
+        console.error('Error:', error.message);
+        console.error('Stack:', error.stack);
+        process.exit(1);
+      }
+    );
+  `;
+
+  const child = spawn('node', ['--input-type=module', '-e', script], {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+  });
+
+  await new Promise((resolve) => {
+    child.on('exit', resolve);
+  });
+}
+
+// Run all tests
+async function main() {
+  console.log('Environment info:');
+  console.log('- Node version:', process.version);
+  console.log('- Platform:', process.platform);
+  console.log('- CI:', process.env.CI || 'false');
+  console.log('- GitHub Actions:', process.env.GITHUB_ACTIONS || 'false');
+
+  await testDirectESModule();
+  await testCommonJSFallback();
+  await testInlineScript();
+  await testShellFallback();
+  await testWithDiagnostics();
+
+  console.log('\nAll tests completed');
+}
+
+main().catch(console.error);

package/js/examples/ci-debug-signal-handling.mjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+
+/**
+ * Example: Debugging signal handling issues in CI
+ *
+ * Problem: SIGINT/SIGTERM signals behave differently in CI environments,
+ * especially with process groups and detached processes.
+ *
+ * Solution: Proper signal forwarding and cleanup strategies.
+ */
+
+import { spawn } from 'child_process';
+import { $ } from '../src/$.mjs';
+
+console.log('Testing signal handling in CI environment');
+
+// Example 1: Basic signal forwarding
+async function testBasicSignalForwarding() {
+  console.log('\nTEST 1: Basic signal forwarding');
+
+  const child = spawn('sh', ['-c', 'echo "Starting sleep" && sleep 30'], {
+    stdio: 'inherit',
+    detached: false, // Not detached, stays in same process group
+  });
+
+  console.log(`Child PID: ${child.pid}`);
+
+  // Forward SIGINT to child
+  const signalHandler = () => {
+    console.log('Parent received SIGINT, forwarding to child...');
+    child.kill('SIGINT');
+  };
+  process.on('SIGINT', signalHandler);
+
+  // Simulate SIGINT after 1 second
+  setTimeout(() => {
+    console.log('Simulating SIGINT...');
+    process.kill(process.pid, 'SIGINT');
+  }, 1000);
+
+  await new Promise((resolve) => {
+    child.on('exit', (code, signal) => {
+      console.log(`Child exited with code ${code}, signal ${signal}`);
+      process.removeListener('SIGINT', signalHandler);
+      resolve();
+    });
+  });
+}
+
+// Example 2: Detached process group handling
+async function testDetachedProcessGroup() {
+  console.log('\nTEST 2: Detached process group');
+
+  const child = spawn('sh', ['-c', 'echo "Detached start" && sleep 30'], {
+    stdio: 'inherit',
+    detached: true, // Creates new process group
+  });
+
+  const pgid = -child.pid; // Negative PID targets the process group
+  console.log(`Child PID: ${child.pid}, PGID: ${pgid}`);
+
+  // Kill entire process group
+  setTimeout(() => {
+    console.log('Killing process group...');
+    try {
+      process.kill(pgid, 'SIGTERM');
+    } catch (error) {
+      console.log('Error killing process group:', error.message);
+      // Fallback to killing just the child
+      child.kill('SIGTERM');
+    }
+  }, 1000);
+
+  await new Promise((resolve) => {
+    child.on('exit', (code, signal) => {
+      console.log(`Child exited with code ${code}, signal ${signal}`);
+      resolve();
+    });
+  });
+}
+
+// Example 3: Signal handling with command-stream
+async function testCommandStreamSignals() {
+  console.log('\nTEST 3: Command-stream signal handling');
+
+  const runner = $`sleep 30`;
+  const promise = runner.start();
+
+  // Log when command starts
+  runner.on('start', () => {
+    console.log('Command started');
+  });
+
+  // Simulate interrupt after 1 second
+  setTimeout(() => {
+    console.log('Sending kill signal to runner...');
+    runner.kill();
+  }, 1000);
+
+  try {
+    await promise;
+    console.log('Command completed normally');
+  } catch (error) {
+    console.log('Command was interrupted:', error.message);
+  }
+
+  console.log('Runner finished:', runner.finished);
+}
+
+// Example 4: Cleanup on unexpected exit
+async function testCleanupOnExit() {
+  console.log('\nTEST 4: Cleanup on unexpected exit');
+
+  const children = [];
+
+  // Cleanup function
+  const cleanup = () => {
+    console.log('Cleaning up child processes...');
+    children.forEach((child) => {
+      if (!child.killed) {
+        console.log(`Killing child ${child.pid}`);
+        child.kill('SIGTERM');
+      }
+    });
+  };
+
+  // Register cleanup handlers
+  process.on('exit', cleanup);
+  process.on('SIGINT', () => {
+    console.log('Received SIGINT');
+    cleanup();
+    process.exit(130); // Standard exit code for SIGINT
+  });
+  process.on('SIGTERM', () => {
+    console.log('Received SIGTERM');
+    cleanup();
+    process.exit(143); // Standard exit code for SIGTERM
+  });
+
+  // Start some child processes
+  for (let i = 0; i < 3; i++) {
+    const child = spawn('sleep', ['30'], {
+      stdio: 'ignore',
+    });
+    children.push(child);
+    console.log(`Started child ${i + 1} with PID ${child.pid}`);
+  }
+
+  // Simulate cleanup after 1 second
+  setTimeout(() => {
+    console.log('Triggering cleanup...');
+    cleanup();
+  }, 1000);
+
+  // Wait for all children to exit
+  await Promise.all(
+    children.map((child) => new Promise((resolve) => child.on('exit', resolve)))
+  );
+
+  console.log('All children cleaned up');
+}
+
+// Example 5: Signal handling in CI vs local environment
+async function testEnvironmentDifferences() {
+  console.log('\nTEST 5: Environment-specific signal handling');
+
+  const isCI = process.env.CI === 'true';
+  const isGitHubActions = process.env.GITHUB_ACTIONS === 'true';
+  const isTTY = process.stdout.isTTY;
+
+  console.log('Environment:');
+  console.log(`- CI: ${isCI}`);
+  console.log(`- GitHub Actions: ${isGitHubActions}`);
+  console.log(`- TTY: ${isTTY}`);
+  console.log(`- Process group: ${process.pid}`);
+
+  // Different strategies based on environment
+  if (isCI) {
+    console.log('Using CI-optimized signal handling');
+    // In CI, we might need more aggressive cleanup
+    const child = spawn('sleep', ['30'], {
+      stdio: 'inherit',
+      detached: false, // Keep in same process group for CI
+    });
+
+    setTimeout(() => {
+      // Use SIGKILL as last resort in CI
+      child.kill('SIGKILL');
+    }, 1000);
+
+    await new Promise((resolve) => child.on('exit', resolve));
+  } else {
+    console.log('Using local development signal handling');
+    // In local dev, we can be more graceful
+    const child = spawn('sleep', ['30'], {
+      stdio: 'inherit',
+      detached: true, // Can detach in local environment
+    });
+
+    setTimeout(() => {
+      // Use SIGTERM for graceful shutdown
+      child.kill('SIGTERM');
+    }, 1000);
+
+    await new Promise((resolve) => child.on('exit', resolve));
+  }
+}
+
+// Run tests
+async function main() {
+  try {
+    await testBasicSignalForwarding();
+    await testDetachedProcessGroup();
+    await testCommandStreamSignals();
+    await testCleanupOnExit();
+    await testEnvironmentDifferences();
+
+    console.log('\nAll signal handling tests completed');
+  } catch (error) {
+    console.error('Test failed:', error);
+    process.exit(1);
+  }
+}
+
+main();