command-stream 0.8.2 → 0.9.0

package/js/tests/examples.test.mjs

@@ -0,0 +1,252 @@
+import { test, expect, describe } from 'bun:test';
+import { isWindows } from './test-helper.mjs'; // Automatically sets up beforeEach/afterEach cleanup
+import { $ } from '../src/$.mjs';
+import { trace } from '../src/$.utils.mjs';
+import { readdirSync, statSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+// Get all .mjs examples
+const examplesDir = join(process.cwd(), 'js/examples');
+const allExamples = readdirSync(examplesDir)
+  .filter(
+    (file) =>
+      file.endsWith('.mjs') && statSync(join(examplesDir, file)).isFile()
+  )
+  .sort();
+
+// Filter examples based on their content to avoid Bun-specific features
+const nodeCompatibleExamples = allExamples.filter((exampleFile) => {
+  const content = readFileSync(join(examplesDir, exampleFile), 'utf8');
+  return !content.includes('Bun.spawn') && !content.includes('Bun.file');
+});
+
+describe('Examples Execution Tests', () => {
+  // Core functionality test - our main example should work
+  // SKIP: May hang when run with full suite
+  test.skip('readme-example.mjs should execute and demonstrate new API signature', async () => {
+    const result = await $`node js/examples/readme-example.mjs`;
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('Hello, World!');
+    expect(result.stdout).toContain('Hello, Mr. Smith!');
+    expect(result.stdout).toContain('"stdinLength": 11');
+    expect(result.stdout).toContain('"mirror": true');
+    expect(result.stdout).toContain('"capture": true');
+  });
+
+  // JSON streaming test - key feature
+  // SKIP: This test hangs when run with full test suite due to sleep commands
+  test.skip('simple-jq-streaming.mjs should complete successfully', async () => {
+    const result = await $`node js/examples/simple-jq-streaming.mjs`;
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('✅ Streaming completed successfully!');
+    expect(result.stdout).toContain('🎉 All tests passed!');
+    expect(result.stdout).toContain('JSON streaming with jq works');
+  });
+
+  // Summary test to report on examples
+  test('should have examples available for manual testing', () => {
+    trace('ExampleTest', '📊 Examples Summary:');
+    trace('ExampleTest', () => `Total examples: ${allExamples.length}`);
+    trace(
+      'ExampleTest',
+      () => `Node-compatible: ${nodeCompatibleExamples.length}`
+    );
+    trace(
+      'ExampleTest',
+      () =>
+        `Bun-specific: ${allExamples.length - nodeCompatibleExamples.length}`
+    );
+
+    // Show a few example files for manual testing
+    const manualTestExamples = [
+      'debug-streaming.mjs',
+      'working-streaming-demo.mjs',
+      'test-simple-pipe.mjs',
+    ].filter((ex) => nodeCompatibleExamples.includes(ex));
+
+    if (manualTestExamples.length > 0) {
+      trace('ExampleTest', 'Recommended for manual testing:');
+      manualTestExamples.forEach((ex) =>
+        trace('ExampleTest', () => `node js/examples/${ex}`)
+      );
+    }
+
+    expect(allExamples.length).toBeGreaterThan(0);
+    expect(nodeCompatibleExamples.length).toBeGreaterThan(0);
+  });
+
+  // Test sleep example with external CTRL+C handling (CI-safe)
+  test(
+    'external process can be interrupted with SIGINT',
+    async () => {
+      const { spawn } = await import('child_process');
+
+      // Use a simple inline script instead of external file
+      const child = spawn(
+        'node',
+        ['-e', 'await new Promise(resolve => setTimeout(resolve, 10000))'],
+        {
+          stdio: ['pipe', 'pipe', 'pipe'],
+          detached: false, // Don't detach to ensure proper signal forwarding
+        }
+      );
+
+      // Give the process time to start
+      await new Promise((resolve) => setTimeout(resolve, 500));
+
+      // Send SIGINT to the process
+      child.kill('SIGINT');
+
+      // Wait for the process to exit with both close and exit handlers
+      const exitCode = await new Promise((resolve) => {
+        let resolved = false;
+
+        child.on('close', (code, signal) => {
+          if (!resolved) {
+            resolved = true;
+            resolve(code !== null ? code : signal ? 128 + 2 : 1);
+          }
+        });
+
+        child.on('exit', (code, signal) => {
+          if (!resolved) {
+            resolved = true;
+            resolve(code !== null ? code : signal ? 128 + 2 : 1);
+          }
+        });
+
+        // Fallback timeout in case the process doesn't respond
+        setTimeout(() => {
+          if (!resolved) {
+            resolved = true;
+            child.kill('SIGKILL');
+            resolve(137); // SIGKILL exit code
+          }
+        }, 2000);
+      });
+
+      // Should be interrupted (non-zero exit code)
+      expect(exitCode).not.toBe(0);
+      // Different platforms may return different codes, be flexible
+      trace('ExampleTest', () => `Actual exit code: ${exitCode}`);
+      expect(exitCode).toBeGreaterThan(0);
+    },
+    { timeout: 5000 }
+  );
+
+  // Test that verifies $.mjs can interrupt processes correctly
+  test(
+    '$.mjs should properly handle process interruption',
+    async () => {
+      // Start long-running sleep command
+      const runner = $`sleep 5`;
+
+      // Start the process
+      const promise = runner.start();
+
+      // Give it a moment to start
+      await new Promise((resolve) => setTimeout(resolve, 200));
+
+      // Kill the process directly
+      runner.kill();
+
+      // Wait for the process to complete
+      const result = await promise;
+
+      // Process should have been killed with SIGTERM exit code
+      expect(result.code).toBe(143);
+      expect(result.code).not.toBe(0);
+    },
+    { timeout: 5000 }
+  );
+
+  // Test that we don't interfere with user's SIGINT handling when no children are active
+  // Skip on Windows - uses SIGINT signal handling which works differently on Windows
+  test.skipIf(isWindows)(
+    'should not interfere with user SIGINT handling when no children active',
+    async () => {
+      const { spawn } = await import('child_process');
+
+      // Start our debug script that imports $ but doesn't run commands
+      const child = spawn('node', ['js/examples/debug-user-sigint.mjs'], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        detached: true,
+      });
+
+      let stdout = '';
+      let stderr = '';
+
+      child.stdout.on('data', (data) => {
+        stdout += data.toString();
+      });
+
+      child.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+
+      // Give the process time to set up its signal handler
+      await new Promise((resolve) => setTimeout(resolve, 500));
+
+      // Send SIGINT to the process
+      child.kill('SIGINT');
+
+      // Wait for the process to exit
+      const exitCode = await new Promise((resolve) => {
+        child.on('close', (code) => {
+          resolve(code);
+        });
+      });
+
+      // The user's SIGINT handler should have been called with exit code 42
+      expect(exitCode).toBe(42);
+      expect(stdout).toContain('USER_SIGINT_HANDLER_CALLED');
+      expect(stdout).not.toContain('TIMEOUT_REACHED');
+    },
+    { timeout: 5000 }
+  );
+
+  // REGRESSION TEST: Virtual commands must be interruptible by SIGINT
+  test(
+    'virtual commands should be properly cancelled by SIGINT (regression test)',
+    async () => {
+      // This prevents regression where virtual sleep command wasn't cancelled by SIGINT
+
+      // Start long-running sleep command
+      const runner = $`sleep 10`;
+      const promise = runner.start();
+
+      // Give it a moment to start
+      await new Promise((resolve) => setTimeout(resolve, 200));
+
+      // Kill it with SIGINT
+      runner.kill('SIGINT');
+
+      // Wait for the process to complete
+      const result = await promise;
+
+      // Virtual command should be properly cancelled (non-zero exit code)
+      // Note: In isolated tests, this should be 130 (SIGINT), but when running with other tests
+      // there might be race conditions that affect the exact exit code
+      expect(result.code).not.toBe(0); // Should not complete successfully
+      expect(result.code > 0).toBe(true); // Should have error exit code
+
+      // Log the actual exit code for debugging
+      trace(
+        'ExampleTest',
+        () =>
+          `✓ Virtual sleep command properly cancelled with exit code: ${result.code}`
+      );
+
+      // In ideal conditions (isolated test), it should be SIGINT exit code
+      if (result.code === 130) {
+        trace('ExampleTest', 'Perfect! Got expected SIGINT exit code (130)');
+      } else {
+        trace(
+          'ExampleTest',
+          'Got alternative exit code (may be due to test interference)'
+        );
+      }
+    },
+    { timeout: 5000 }
+  );
+});

package/js/tests/execa.features.test.mjs

@@ -0,0 +1,198 @@
+import { test, expect, describe } from 'bun:test';
+import './test-helper.mjs'; // Automatically sets up beforeEach/afterEach cleanup
+
+// Note: This file tests execa features conceptually since execa is not installed
+// In a real project, you would: npm install execa
+// import { execa, $ } from 'execa';
+
+describe('execa Feature Validation (Conceptual)', () => {
+  describe('Runtime Support', () => {
+    test('should work in Node.js runtime', () => {
+      // execa is designed for Node.js
+      // Would work in Node.js with: import { execa } from 'execa';
+      expect(typeof process).toBe('object'); // Node.js globals available
+    });
+
+    test('should NOT work natively in Bun without compatibility', () => {
+      // execa requires Node.js modules and may need compatibility layer for Bun
+      // This test documents the Node.js dependency
+      expect(typeof Bun).toBe('object'); // We're in Bun, but execa expects Node.js
+    });
+  });
+
+  describe('Template Literals', () => {
+    test('should support $`cmd` syntax with execa', () => {
+      // execa v8+ supports template literal syntax: $`command`
+      // const result = await $`echo "execa template literal"`;
+      // expect(result.stdout).toBe('execa template literal');
+
+      // Conceptual test - execa does support this syntax
+      expect(true).toBe(true); // Placeholder for actual execa test
+    });
+
+    test('should support variable interpolation', () => {
+      // const message = 'interpolation';
+      // const result = await $`echo ${message}`;
+      // expect(result.stdout).toContain('interpolation');
+
+      expect(true).toBe(true); // Placeholder
+    });
+  });
+
+  describe('Real-time Streaming', () => {
+    test('should have LIMITED streaming capabilities', () => {
+      // execa provides some streaming via result.stdout/stderr streams
+      // but not as comprehensive as command-stream's real-time iteration
+      // const subprocess = execa('echo', ['streaming test']);
+      // subprocess.stdout.on('data', chunk => { /* handle chunk */ });
+
+      expect(true).toBe(true); // Placeholder - execa has basic streaming
+    });
+
+    test('should buffer output by default', () => {
+      // execa buffers output and returns complete result
+      // const result = await execa('echo', ['buffered']);
+      // expect(result.stdout).toBe('buffered');
+
+      expect(true).toBe(true); // Placeholder
+    });
+  });
+
+  describe('Async Iteration', () => {
+    test('should NOT support for await iteration on result', () => {
+      // execa results are not async iterable
+      // The subprocess object might have some iteration capabilities
+      // but not the same as command-stream's chunk iteration
+
+      expect(true).toBe(true); // Placeholder - execa doesn't have this
+    });
+  });
+
+  describe('EventEmitter Pattern', () => {
+    test('should have LIMITED event support on subprocess', () => {
+      // execa subprocess extends Node.js ChildProcess with events:
+      // subprocess.on('exit', code => {});
+      // subprocess.stdout.on('data', chunk => {});
+      // But not the same comprehensive event interface as command-stream
+
+      expect(true).toBe(true); // Placeholder - limited events available
+    });
+  });
+
+  describe('Mixed Patterns', () => {
+    test('should NOT support events + await on same object', () => {
+      // execa subprocess is separate from result object
+      // You can listen to subprocess events OR await result, but not both on same object
+
+      expect(true).toBe(true); // Placeholder - no mixed patterns
+    });
+  });
+
+  describe('Shell Injection Protection', () => {
+    test('should be safe by default', () => {
+      // execa is safe by default - doesn't use shell unless explicitly requested
+      // const result = await execa('echo', [dangerousInput]); // Safe
+      // vs const result = await execa('echo ' + dangerousInput, {shell: true}); // Unsafe
+
+      expect(true).toBe(true); // Placeholder - execa is safe by default
+    });
+  });
+
+  describe('Cross-platform Support', () => {
+    test('should work cross-platform', () => {
+      // execa has excellent cross-platform support
+      // Handles Windows vs Unix differences automatically
+
+      expect(true).toBe(true); // Placeholder - execa is cross-platform
+    });
+  });
+
+  describe('Performance', () => {
+    test('should have moderate performance', () => {
+      // execa has good performance but not as fast as native Bun.$ or command-stream
+      // Optimized for reliability and features over raw speed
+
+      expect(true).toBe(true); // Placeholder - moderate performance
+    });
+  });
+
+  describe('Memory Efficiency', () => {
+    test('should buffer in memory by default', () => {
+      // execa buffers stdout/stderr in memory by default
+      // Can stream to avoid memory issues with large outputs
+      // const subprocess = execa('command', {stdout: 'pipe'});
+
+      expect(true).toBe(true); // Placeholder - buffers by default
+    });
+  });
+
+  describe('Error Handling', () => {
+    test('should reject promise on error', () => {
+      // execa rejects promise on non-zero exit codes by default
+      // try { await execa('exit', ['1']); } catch (error) { /* handle */ }
+      // Can disable with {reject: false}
+
+      expect(true).toBe(true); // Placeholder - promise rejection on error
+    });
+  });
+
+  describe('Stdin Support', () => {
+    test('should support input/output streams', () => {
+      // execa has comprehensive stdin/stdout/stderr stream support
+      // const result = await execa('cat', {input: 'stdin data'});
+      // subprocess.stdin.write('data');
+
+      expect(true).toBe(true); // Placeholder - good stream support
+    });
+  });
+
+  describe('Built-in Commands', () => {
+    test('should NOT have built-in commands', () => {
+      // execa uses system commands only, no built-ins
+      // All commands go through the operating system
+
+      expect(true).toBe(true); // Placeholder - no built-ins
+    });
+  });
+
+  describe('Bundle Size', () => {
+    test('should have ~25KB bundle size', () => {
+      // execa is a moderate-sized package
+      // Includes comprehensive features which add to bundle size
+
+      expect(true).toBe(true); // Placeholder - ~25KB estimated
+    });
+  });
+
+  describe('TypeScript Support', () => {
+    test('should have full TypeScript support', () => {
+      // execa has excellent TypeScript definitions
+      // Strong typing for all options and return types
+
+      expect(true).toBe(true); // Placeholder - full TS support
+    });
+  });
+
+  describe('Advanced Features', () => {
+    test('should support timeout settings', () => {
+      // execa supports timeout option to prevent hanging commands
+      // const result = await execa('sleep', ['10'], {timeout: 1000});
+
+      expect(true).toBe(true); // Placeholder - timeout support
+    });
+
+    test('should support detailed error information', () => {
+      // execa provides detailed error objects with context
+      // error.command, error.exitCode, error.stderr, etc.
+
+      expect(true).toBe(true); // Placeholder - detailed errors
+    });
+
+    test('should support verbose and debugging modes', () => {
+      // execa has built-in debugging and verbose output options
+      // Helpful for development and troubleshooting
+
+      expect(true).toBe(true); // Placeholder - debugging features
+    });
+  });
+});

package/js/tests/gh-commands.test.mjs

@@ -0,0 +1,164 @@
+import { test, expect, describe, beforeEach, afterEach } from 'bun:test';
+import { beforeTestCleanup, afterTestCleanup } from './test-cleanup.mjs';
+import { $ } from '../src/$.mjs';
+
+// Platform detection - tests use Unix shell redirection 2>&1 and sh -c
+const isWindows = process.platform === 'win32';
+
+// Skip on Windows - tests use 2>&1 shell redirection, pipes with head, and sh -c
+describe.skipIf(isWindows)('GitHub CLI (gh) commands', () => {
+  beforeEach(async () => {
+    await beforeTestCleanup();
+  });
+
+  afterEach(async () => {
+    await afterTestCleanup();
+  });
+  test('gh auth status returns correct exit code and output structure', async () => {
+    // Test with capture to check output
+    const result = await $`gh auth status 2>&1`.run({
+      capture: true,
+      mirror: false,
+    });
+
+    // Should have an exit code property
+    expect(result.code).toBeDefined();
+    expect(typeof result.code).toBe('number');
+
+    // Exit code should be 0 if authenticated, 1 if not - both are OK
+    // We're testing $.mjs command execution, not gh auth itself
+    expect([0, 1]).toContain(result.code);
+
+    // Should have stdout
+    expect(result.stdout).toBeDefined();
+    expect(typeof result.stdout).toBe('string');
+
+    // If authenticated (exit code 0), output should contain success indicators
+    // If not authenticated (exit code 1), that's also fine - we're testing $.mjs works
+    if (result.code === 0) {
+      const output = result.stdout;
+      const isAuthenticated =
+        output.includes('Logged in to') ||
+        output.includes('✓') ||
+        output.includes('github.com');
+      // Don't fail if indicators aren't found - different gh versions may have different output
+      expect(output.length).toBeGreaterThan(0);
+    } else {
+      // Exit code 1 means not authenticated, which is OK for our test purposes
+      expect(result.stdout.length).toBeGreaterThanOrEqual(0);
+    }
+  });
+
+  test('gh command with invalid subcommand returns non-zero exit code', async () => {
+    try {
+      const result = await $`gh invalid-command 2>&1`.run({
+        capture: true,
+        mirror: false,
+      });
+      // If it doesn't throw, check the exit code
+      expect(result.code).toBeGreaterThan(0);
+    } catch (error) {
+      // Some configurations might throw on non-zero exit
+      expect(error.code).toBeGreaterThan(0);
+    }
+  });
+
+  test('gh api can be called with parameters', async () => {
+    // Check authentication first
+    const authCheck = await $`gh auth status 2>&1`.run({
+      capture: true,
+      mirror: false,
+    });
+    if (authCheck.code !== 0) {
+      console.log(
+        'Skipping gh api test - not authenticated (this is OK - we are testing $.mjs, not gh auth)'
+      );
+      return;
+    }
+
+    // Try to run the API command
+    const result = await $`gh api user --jq .login 2>&1`.run({
+      capture: true,
+      mirror: false,
+    });
+
+    // If we get "Resource not accessible by integration" it means we're in CI with limited token
+    // This is OK - we're testing that $.mjs can execute the command, not that we have full API access
+    if (
+      result.code !== 0 &&
+      result.stdout.includes('Resource not accessible by integration')
+    ) {
+      console.log(
+        'Skipping gh api test - limited GitHub Actions token (this is OK - we are testing $.mjs, not gh permissions)'
+      );
+      return;
+    }
+
+    expect(result.code).toBe(0);
+    expect(result.stdout).toBeDefined();
+    expect(result.stdout.trim().length).toBeGreaterThan(0);
+  });
+
+  test('gh gist list works with parameters', async () => {
+    // Check authentication first
+    const authCheck = await $`gh auth status 2>&1`.run({
+      capture: true,
+      mirror: false,
+    });
+    if (authCheck.code !== 0) {
+      console.log(
+        'Skipping gh gist test - not authenticated (this is OK - we are testing $.mjs, not gh auth)'
+      );
+      return;
+    }
+
+    // Try to run the gist command
+    const result = await $`gh gist list --limit 1 2>&1`.run({
+      capture: true,
+      mirror: false,
+    });
+
+    // If we get "Resource not accessible by integration" it means we're in CI with limited token
+    // This is OK - we're testing that $.mjs can execute the command, not that we have full API access
+    if (
+      result.code !== 0 &&
+      result.stdout.includes('Resource not accessible by integration')
+    ) {
+      console.log(
+        'Skipping gh gist test - limited GitHub Actions token (this is OK - we are testing $.mjs, not gh permissions)'
+      );
+      return;
+    }
+
+    expect(result.code).toBe(0);
+    expect(result.stdout).toBeDefined();
+    // Output could be empty if user has no gists
+    expect(typeof result.stdout).toBe('string');
+  });
+
+  test('complex gh command with pipes and jq', async () => {
+    // Check authentication first
+    const authCheck = await $`gh auth status 2>&1`.run({
+      capture: true,
+      mirror: false,
+    });
+    if (authCheck.code !== 0) {
+      console.log(
+        'Skipping complex gh test - not authenticated (this is OK - we are testing $.mjs, not gh auth)'
+      );
+      return;
+    }
+
+    // Try to run the API command with graceful fallback
+    const result =
+      await $`sh -c 'gh api user --jq .login 2>/dev/null || echo "limited-token"' | head -1`.run(
+        { capture: true, mirror: false }
+      );
+
+    // This version uses || echo to handle the limited token case gracefully
+    // We're testing that $.mjs can pipe commands, not that we have full API access
+    expect(result.code).toBe(0);
+    expect(result.stdout).toBeDefined();
+    expect(result.stdout.split('\n').length).toBeLessThanOrEqual(2); // Should be one line plus possible newline
+  });
+});