command-stream 0.8.2 → 0.9.0

package/js/tests/shell-settings.test.mjs

@@ -0,0 +1,279 @@
+import { test, expect, describe, beforeEach } from 'bun:test';
+import { isWindows } from './test-helper.mjs'; // Automatically sets up beforeEach/afterEach cleanup
+import { $, shell, set, unset } from '../src/$.mjs';
+
+describe('Shell Settings (set -e / set +e equivalent)', () => {
+  beforeEach(() => {
+    // Reset all shell settings before each test
+    shell.errexit(false);
+    shell.verbose(false);
+    shell.xtrace(false);
+    shell.pipefail(false);
+    shell.nounset(false);
+  });
+
+  describe('Error Handling (set -e / set +e)', () => {
+    test('should continue execution by default (like bash without set -e)', async () => {
+      const result1 = await $`exit 1`;
+      expect(result1.code).toBe(1);
+
+      const result2 = await $`echo "continued"`;
+      expect(result2.code).toBe(0);
+      expect(result2.stdout.trim()).toBe('continued');
+    });
+
+    test('should throw on error when errexit enabled (set -e)', async () => {
+      shell.errexit(true);
+
+      try {
+        await $`exit 42`;
+        expect(true).toBe(false); // Should not reach here
+      } catch (error) {
+        expect(error.code).toBe(42);
+        expect(error.message).toContain('Command failed with exit code 42');
+        expect(error.result).toBeDefined();
+        expect(error.result.code).toBe(42);
+      }
+    });
+
+    test('should stop throwing when errexit disabled (set +e)', async () => {
+      shell.errexit(true);
+      shell.errexit(false);
+
+      const result = await $`exit 1`;
+      expect(result.code).toBe(1);
+      // Should not throw
+    });
+
+    test('should allow mid-script changes (like bash)', async () => {
+      // Start without errexit
+      const result1 = await $`exit 1`;
+      expect(result1.code).toBe(1);
+
+      // Enable errexit
+      shell.errexit(true);
+      try {
+        await $`exit 2`;
+        expect(true).toBe(false); // Should not reach here
+      } catch (error) {
+        expect(error.code).toBe(2);
+      }
+
+      // Disable errexit again
+      shell.errexit(false);
+      const result3 = await $`exit 3`;
+      expect(result3.code).toBe(3);
+      // Should not throw
+    });
+  });
+
+  describe('Verbose Mode (set -v)', () => {
+    test('should not print commands by default', async () => {
+      // Capture console output
+      const originalLog = console.log;
+      const capturedLogs = [];
+      console.log = (...args) => capturedLogs.push(args.join(' '));
+
+      try {
+        await $`echo "silent"`;
+        expect(capturedLogs).toHaveLength(0);
+      } finally {
+        console.log = originalLog;
+      }
+    });
+
+    test('should print commands when verbose enabled', async () => {
+      // Ensure clean state before intercepting console.log
+      shell.errexit(false);
+      shell.verbose(false);
+      shell.xtrace(false);
+      shell.pipefail(false);
+      shell.nounset(false);
+
+      const originalLog = console.log;
+      const capturedLogs = [];
+      console.log = (...args) => capturedLogs.push(args.join(' '));
+
+      try {
+        shell.verbose(true);
+        await $`echo "verbose test"`;
+
+        expect(capturedLogs.length).toBeGreaterThan(0);
+        expect(
+          capturedLogs.some((log) => log.includes('echo "verbose test"'))
+        ).toBe(true);
+      } finally {
+        console.log = originalLog;
+      }
+    });
+  });
+
+  describe('Trace Mode (set -x)', () => {
+    test('should not trace commands by default', async () => {
+      const originalLog = console.log;
+      const capturedLogs = [];
+      console.log = (...args) => capturedLogs.push(args.join(' '));
+
+      try {
+        await $`echo "no trace"`;
+        expect(capturedLogs).toHaveLength(0);
+      } finally {
+        console.log = originalLog;
+      }
+    });
+
+    test('should trace commands when xtrace enabled', async () => {
+      // Ensure clean state before intercepting console.log
+      shell.errexit(false);
+      shell.verbose(false);
+      shell.xtrace(false);
+      shell.pipefail(false);
+      shell.nounset(false);
+
+      const originalLog = console.log;
+      const capturedLogs = [];
+      console.log = (...args) => capturedLogs.push(args.join(' '));
+
+      try {
+        shell.xtrace(true);
+        await $`echo "trace test"`;
+
+        expect(capturedLogs.length).toBeGreaterThan(0);
+        expect(capturedLogs.some((log) => log.startsWith('+ '))).toBe(true);
+        expect(
+          capturedLogs.some((log) => log.includes('echo "trace test"'))
+        ).toBe(true);
+      } finally {
+        console.log = originalLog;
+      }
+    });
+  });
+
+  describe('Settings API', () => {
+    test('should allow setting options with set() function', () => {
+      set('e');
+      expect(shell.settings().errexit).toBe(true);
+
+      set('v');
+      expect(shell.settings().verbose).toBe(true);
+
+      set('x');
+      expect(shell.settings().xtrace).toBe(true);
+    });
+
+    test('should allow unsetting options with unset() function', () => {
+      shell.errexit(true);
+      shell.verbose(true);
+
+      unset('e');
+      expect(shell.settings().errexit).toBe(false);
+
+      unset('v');
+      expect(shell.settings().verbose).toBe(false);
+    });
+
+    test('should support long option names', () => {
+      set('errexit');
+      expect(shell.settings().errexit).toBe(true);
+
+      set('verbose');
+      expect(shell.settings().verbose).toBe(true);
+
+      unset('errexit');
+      expect(shell.settings().errexit).toBe(false);
+    });
+
+    test('should return current settings', () => {
+      shell.errexit(true);
+      shell.verbose(true);
+
+      const settings = shell.settings();
+      expect(settings.errexit).toBe(true);
+      expect(settings.verbose).toBe(true);
+      expect(settings.xtrace).toBe(false);
+      expect(settings.pipefail).toBe(false);
+      expect(settings.nounset).toBe(false);
+    });
+  });
+
+  describe('Shell Replacement Benefits', () => {
+    test('should provide better error objects than bash', async () => {
+      shell.errexit(true);
+
+      try {
+        await $`sh -c "echo 'stdout'; echo 'stderr' >&2; exit 5"`;
+        expect(true).toBe(false);
+      } catch (error) {
+        expect(error.code).toBe(5);
+        expect(error.stdout).toContain('stdout');
+        expect(error.stderr).toContain('stderr');
+        expect(error.result).toBeDefined();
+        expect(error.result.code).toBe(5);
+      }
+    });
+
+    // Skip on Windows - shell command execution differs
+    test.skipIf(isWindows)(
+      'should allow JavaScript control flow with shell semantics',
+      async () => {
+        const results = [];
+
+        // Test a list of commands with error handling
+        const commands = [
+          'echo "success1"',
+          'exit 1', // This will fail
+          'echo "success2"',
+        ];
+
+        for (const cmd of commands) {
+          try {
+            shell.errexit(true);
+            const result = await $`sh -c ${cmd}`;
+            results.push({ cmd, success: true, output: result.stdout.trim() });
+          } catch (error) {
+            results.push({ cmd, success: false, code: error.code });
+
+            // Decide whether to continue or not
+            if (error.code === 1) {
+              shell.errexit(false); // Continue on this specific error
+            }
+          }
+        }
+
+        expect(results).toHaveLength(3);
+        expect(results[0].success).toBe(true);
+        expect(results[0].output).toBe('success1');
+        expect(results[1].success).toBe(false);
+        expect(results[1].code).toBe(1);
+        expect(results[2].success).toBe(true);
+        expect(results[2].output).toBe('success2');
+      }
+    );
+  });
+
+  describe('Real-world Shell Script Pattern', () => {
+    test('should support common shell script patterns', async () => {
+      // Typical shell script pattern:
+      // set -e  # exit on error
+      // optional commands with set +e
+      // set -e  # back to strict mode
+
+      shell.errexit(true);
+
+      // Critical setup command
+      const setup = await $`echo "setup complete"`;
+      expect(setup.code).toBe(0);
+
+      // Optional command that might fail
+      shell.errexit(false);
+      const optional = await $`ls /nonexistent 2>/dev/null`;
+      expect(optional.code).not.toBe(0); // Should fail but not throw
+
+      // Back to strict mode for critical operations
+      shell.errexit(true);
+      const critical = await $`echo "critical operation"`;
+      expect(critical.code).toBe(0);
+      expect(critical.stdout.trim()).toBe('critical operation');
+    });
+  });
+});

package/js/tests/sigint-cleanup-isolated.test.mjs

@@ -0,0 +1,151 @@
+import { test, expect, describe } from 'bun:test';
+import './test-helper.mjs'; // Automatically sets up beforeEach/afterEach cleanup
+import { $ } from '../src/$.mjs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Platform detection - Windows handles signals differently than Unix
+const isWindows = process.platform === 'win32';
+
+// Skip on Windows - SIGINT handler testing requires Unix signal semantics
+describe.skipIf(isWindows)('SIGINT Cleanup Tests (Isolated)', () => {
+  test('should properly manage SIGINT handlers', async () => {
+    // Run the test in a subprocess to avoid interfering with test runner
+    const scriptPath = join(__dirname, '../examples/sigint-handler-test.mjs');
+    const result = await $`node ${scriptPath}`;
+
+    // Parse results from output
+    const output = result.stdout;
+    const results = {};
+
+    // Extract RESULT lines
+    const resultLines = output
+      .split('\n')
+      .filter((line) => line.includes('RESULT:'));
+    resultLines.forEach((line) => {
+      const match = line.match(/RESULT: (\w+)=(.+)/);
+      if (match) {
+        results[match[1]] = match[2];
+      }
+    });
+
+    // Verify handler lifecycle
+    const initial = parseInt(results.initial_listeners);
+    const during = parseInt(results.during_listeners);
+    const after = parseInt(results.after_listeners);
+
+    expect(during).toBe(initial + 1); // Handler added
+    expect(after).toBe(initial); // Handler removed
+
+    // Verify concurrent commands share handler
+    const concurrent = parseInt(results.concurrent_listeners);
+    const afterConcurrent = parseInt(results.after_concurrent_listeners);
+
+    expect(concurrent).toBe(initial + 1); // Single handler for all
+    expect(afterConcurrent).toBe(initial); // Cleaned up
+
+    // Verify cleanup on error
+    const afterError = parseInt(results.after_error_listeners);
+    expect(afterError).toBe(initial);
+
+    // Verify cleanup on kill
+    const afterKill = parseInt(results.after_kill_listeners);
+    expect(afterKill).toBe(initial);
+  });
+
+  test('should forward SIGINT to child processes', async () => {
+    // Run the forwarding test in subprocess
+    const scriptPath = join(
+      __dirname,
+      '../examples/sigint-forwarding-test.mjs'
+    );
+    const result = await $`node ${scriptPath}`;
+
+    // Parse results
+    const output = result.stdout;
+    const results = {};
+
+    const resultLines = output
+      .split('\n')
+      .filter((line) => line.includes('RESULT:'));
+    resultLines.forEach((line) => {
+      const match = line.match(/RESULT: (\w+)=(.+)/);
+      if (match) {
+        results[match[1]] = match[2];
+      }
+    });
+
+    // Verify SIGINT was received by parent
+    expect(results.sigint_received).toBe('true');
+
+    // The child process should have been forwarded the signal
+    // (exact behavior depends on implementation)
+  });
+
+  test('should cleanup all resources properly', async () => {
+    // Run comprehensive cleanup test
+    const scriptPath = join(
+      __dirname,
+      '../examples/cleanup-verification-test.mjs'
+    );
+    const result = await $`node ${scriptPath}`;
+
+    // Parse results
+    const output = result.stdout;
+    const results = {};
+
+    const resultLines = output
+      .split('\n')
+      .filter((line) => line.includes('RESULT:'));
+    resultLines.forEach((line) => {
+      const match = line.match(/RESULT: (\w+)=(.+)/);
+      if (match) {
+        results[match[1]] = match[2];
+      }
+    });
+
+    // Verify all cleanup scenarios
+    expect(results.virtual_finished).toBe('true');
+    expect(results.real_finished).toBe('true');
+    expect(results.error_finished).toBe('true');
+    expect(results.kill_finished).toBe('true');
+    expect(results.pipeline_output).toBe('test');
+    expect(results.event_listeners_size).toBe('0');
+    expect(results.concurrent_finished).toBe('true');
+    expect(results.not_awaited_finished).toBe('true');
+    expect(results.stream_iterator_finished).toBe('true');
+    expect(results.had_abort_controller).toBe('true');
+    expect(results.abort_controller_cleaned).toBe('true');
+    expect(results.final_sigint_handlers).toBe('0');
+  });
+
+  test('should not interfere with user SIGINT handlers', async () => {
+    // This test verifies that after commands finish, user handlers work
+    await $`echo test`;
+
+    // Wait to ensure cleanup
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    // User's handler should work fine now
+    let userHandlerCalled = false;
+    const userHandler = () => {
+      userHandlerCalled = true;
+    };
+
+    process.on('SIGINT', userHandler);
+
+    try {
+      // This should NOT exit the process since we're not actually sending SIGINT
+      // We're just testing that we can add handlers
+      expect(process.listeners('SIGINT').includes(userHandler)).toBe(true);
+
+      // Clean up
+      process.removeListener('SIGINT', userHandler);
+    } finally {
+      process.removeListener('SIGINT', userHandler);
+    }
+  });
+});

package/js/tests/sigint-cleanup.test.mjs

@@ -0,0 +1,118 @@
+import { test, expect, describe } from 'bun:test';
+import './test-helper.mjs'; // Automatically sets up beforeEach/afterEach cleanup
+import { $ } from '../src/$.mjs';
+
+// Platform detection - Windows handles signals differently than Unix
+const isWindows = process.platform === 'win32';
+
+// Skip on Windows - SIGINT handler testing requires Unix signal semantics
+describe.skipIf(isWindows)('SIGINT Handler Cleanup Tests', () => {
+  test('should remove SIGINT handler when all ProcessRunners finish', async () => {
+    // Check initial state
+    const initialListeners = process.listeners('SIGINT').length;
+
+    // Run a quick command that finishes immediately
+    const result = await $`echo hello`;
+    expect(result.code).toBe(0);
+
+    // After command finishes, SIGINT handler should be removed
+    const afterListeners = process.listeners('SIGINT').length;
+    expect(afterListeners).toBe(initialListeners);
+  });
+
+  test('should not interfere with user SIGINT handlers after commands finish', async () => {
+    // Run a command and let it finish
+    await $`echo test`;
+
+    // Wait a bit to ensure all cleanup is complete
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    // Add user's SIGINT handler
+    let userHandlerCalled = false;
+    const userHandler = () => {
+      userHandlerCalled = true;
+    };
+
+    // Test that we can add a handler without interference
+    process.on('SIGINT', userHandler);
+
+    try {
+      // Verify the handler was added successfully
+      const listeners = process.listeners('SIGINT');
+      expect(listeners.includes(userHandler)).toBe(true);
+
+      // NOTE: We do NOT emit SIGINT here as it would kill the test runner
+      // The isolated test in sigint-cleanup-isolated.test.mjs tests actual SIGINT behavior
+    } finally {
+      // Cleanup
+      process.removeListener('SIGINT', userHandler);
+    }
+  });
+
+  test('should maintain SIGINT handler while commands are active', async () => {
+    // Import forceCleanupAll to ensure clean state
+    const { forceCleanupAll } = await import('../src/$.mjs');
+    forceCleanupAll();
+
+    const initialListeners = process.listeners('SIGINT').length;
+
+    // Start a long-running command
+    const runner = $`sleep 2`;
+    const promise = runner.start();
+
+    // While command is running, handler should be installed
+    const duringListeners = process.listeners('SIGINT').length;
+    expect(duringListeners).toBe(initialListeners + 1);
+
+    // Kill the command
+    runner.kill();
+
+    try {
+      await promise;
+    } catch (error) {
+      // Expected error when process is killed with SIGTERM
+      expect(error.code).toBe(143);
+    }
+
+    // After command finishes, handler should be removed
+    const afterListeners = process.listeners('SIGINT').length;
+
+    // If listeners count doesn't match, force cleanup of command-stream handlers only
+    if (afterListeners !== initialListeners) {
+      const ourListeners = process.listeners('SIGINT').filter((l) => {
+        const str = l.toString();
+        return (
+          str.includes('activeProcessRunners') ||
+          str.includes('ProcessRunner') ||
+          str.includes('activeChildren')
+        );
+      });
+
+      if (ourListeners.length > 0) {
+        console.warn(
+          `Test left behind ${ourListeners.length} command-stream SIGINT handlers, forcing cleanup...`
+        );
+        ourListeners.forEach((listener) => {
+          process.removeListener('SIGINT', listener);
+        });
+      }
+    }
+
+    const finalListeners = process.listeners('SIGINT').length;
+    expect(finalListeners).toBe(initialListeners);
+  });
+
+  test('should handle multiple concurrent ProcessRunners correctly', async () => {
+    const initialListeners = process.listeners('SIGINT').length;
+
+    // Start multiple commands
+    const promises = [$`echo one`, $`echo two`, $`echo three`];
+
+    // Wait for all to finish
+    await Promise.all(promises);
+
+    // Handler should be removed after all finish
+    const afterListeners = process.listeners('SIGINT').length;
+    expect(afterListeners).toBe(initialListeners);
+  });
+});

package/js/tests/start-run-edge-cases.test.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+import { test, expect, describe, beforeEach, afterEach } from 'bun:test';
+import { isWindows } from './test-helper.mjs'; // Automatically sets up beforeEach/afterEach cleanup
+import { $, shell } from '../src/$.mjs';
+
+describe('Start/Run Edge Cases and Advanced Usage', () => {
+  beforeEach(() => {
+    shell.errexit(false);
+    shell.verbose(false);
+    shell.xtrace(false);
+    shell.pipefail(false);
+    shell.nounset(false);
+  });
+
+  afterEach(() => {
+    shell.errexit(false);
+    shell.verbose(false);
+    shell.xtrace(false);
+    shell.pipefail(false);
+    shell.nounset(false);
+  });
+  test('should handle complex option combinations', async () => {
+    const result = await $`echo "complex test"`.start({
+      capture: true,
+      mirror: false,
+      stdin: 'inherit',
+      mode: 'async',
+    });
+
+    expect(result.stdout).toBe('complex test\n');
+    expect(result.code).toBe(0);
+  });
+
+  // Skip on Windows - uses 'ls -la /tmp' which is Unix-specific
+  test.skipIf(isWindows)(
+    'should work with real shell commands that produce large output',
+    async () => {
+      const result = await $`ls -la /tmp`.start({ capture: false });
+
+      expect(result.stdout).toBeUndefined();
+      expect(result.code).toBe(0);
+    }
+  );
+
+  test('should handle stderr with capture: false', async () => {
+    const result = await $`ls /nonexistent-path-12345`.start({
+      capture: false,
+    });
+
+    expect(result.stdout).toBeUndefined();
+    expect(result.stderr).toBeUndefined();
+    expect(result.code).not.toBe(0); // ls should fail
+  });
+
+  test('should handle stderr with capture: true', async () => {
+    const result = await $`ls /nonexistent-path-98765`.start({ capture: true });
+
+    expect(result.stdout).toBe(''); // No stdout for failed ls
+    expect(typeof result.stderr).toBe('string');
+    expect(result.stderr.length).toBeGreaterThan(0);
+    expect(result.code).not.toBe(0);
+  });
+
+  test('should handle multiple consecutive start() calls correctly', async () => {
+    const runner = $`echo "multiple calls"`;
+
+    // First call should work
+    const result1 = await runner.start({ capture: true });
+    expect(result1.stdout).toBe('multiple calls\n');
+
+    // Second call should return the same result (cached)
+    const result2 = await runner.start({ capture: false }); // Options ignored
+    expect(result2.stdout).toBe('multiple calls\n'); // Still captured
+
+    // Results should be the same object reference
+    expect(result1).toBe(result2);
+  });
+
+  test('should handle mixed sync/async mode correctly', async () => {
+    const result1 = await $`echo "async mode"`.start({ mode: 'async' });
+    const result2 = $`echo "sync mode"`.start({ mode: 'sync' });
+
+    expect(result1.stdout).toBe('async mode\n');
+    expect(result2.stdout).toBe('sync mode\n');
+  });
+
+  test('should preserve original behavior when no options passed', async () => {
+    const withStart = await $`echo "with start"`.start();
+    const withRun = await $`echo "with run"`.run();
+    const directAwait = await $`echo "direct await"`;
+
+    expect(withStart.stdout).toBe('with start\n');
+    expect(withRun.stdout).toBe('with run\n');
+    expect(directAwait.stdout).toBe('direct await\n');
+
+    // All should have same structure
+    expect(Object.keys(withStart)).toEqual(Object.keys(withRun));
+    expect(Object.keys(withRun)).toEqual(Object.keys(directAwait));
+  });
+
+  test('should work with piped commands', async () => {
+    const result = await $`echo "hello world"`
+      .pipe($`cat`)
+      .start({ mirror: false });
+
+    expect(result.stdout).toBe('hello world\n');
+    expect(result.code).toBe(0);
+  });
+
+  test('should handle buffer stdin correctly with options', async () => {
+    const inputBuffer = Buffer.from('buffer test data');
+    const result = await $`cat`.start({
+      stdin: inputBuffer,
+      capture: true,
+      mirror: false,
+    });
+
+    // Result might be a buffer or string depending on the command
+    const output =
+      typeof result.stdout === 'string'
+        ? result.stdout
+        : result.stdout?.toString();
+    expect(output).toBe('buffer test data');
+    expect(result.code).toBe(0);
+  });
+
+  test('should maintain performance with capture: false', async () => {
+    // This test verifies that when capture is false, we don't waste memory
+    const startTime = Date.now();
+
+    const result = await $`echo "performance test"`.start({ capture: false });
+
+    const endTime = Date.now();
+    const duration = endTime - startTime;
+
+    expect(result.stdout).toBeUndefined();
+    expect(result.code).toBe(0);
+    expect(duration).toBeLessThan(1000); // Should complete quickly
+  });
+
+  test('should handle empty string stdin', async () => {
+    const result = await $`cat`.start({
+      stdin: '',
+      capture: true,
+      mirror: false,
+    });
+
+    expect(result.stdout).toBe('');
+    expect(result.code).toBe(0);
+  });
+});