command-stream 0.8.2 → 0.9.0

package/js/tests/start-run-options.test.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+
+import { test, expect, describe } from 'bun:test';
+import { isWindows } from './test-helper.mjs'; // Automatically sets up beforeEach/afterEach cleanup
+import { $ } from '../src/$.mjs';
+
+describe('Start/Run Options Passing', () => {
+  describe('.start() method with options', () => {
+    test('should pass capture: false option correctly', async () => {
+      const result = await $`echo "test with capture false"`.start({
+        capture: false,
+      });
+      expect(result.stdout).toBeUndefined();
+      expect(result.code).toBe(0);
+    });
+
+    test('should pass capture: true option correctly', async () => {
+      const result = await $`echo "test with capture true"`.start({
+        capture: true,
+      });
+      expect(result.stdout).toBe('test with capture true\n');
+      expect(result.code).toBe(0);
+    });
+
+    test('should pass mirror: false option correctly', async () => {
+      // mirror: false should still capture but not show output to console
+      const result = await $`echo "test with mirror false"`.start({
+        mirror: false,
+      });
+      expect(result.stdout).toBe('test with mirror false\n');
+      expect(result.code).toBe(0);
+    });
+
+    test('should pass both capture and mirror options', async () => {
+      const result = await $`echo "test both options"`.start({
+        capture: false,
+        mirror: false,
+      });
+      expect(result.stdout).toBeUndefined();
+      expect(result.code).toBe(0);
+    });
+
+    test('should pass stdin option correctly', async () => {
+      const result = await $`cat`.start({
+        stdin: 'custom input data',
+        capture: true,
+      });
+      expect(result.stdout).toBe('custom input data');
+      expect(result.code).toBe(0);
+    });
+
+    // Skip on Windows - uses 'ls /tmp' which is Unix-specific
+    test.skipIf(isWindows)('should work with real shell commands', async () => {
+      const result = await $`ls /tmp`.start({ capture: false });
+      expect(result.stdout).toBeUndefined();
+      expect(result.code).toBe(0);
+    });
+
+    test('should ignore options if process already started', async () => {
+      const runner = $`echo "already started test"`;
+
+      // Start the process
+      const firstResult = await runner.start();
+      expect(firstResult.stdout).toBe('already started test\n');
+
+      // Try to start again with different options - should be ignored
+      const secondResult = await runner.start({ capture: false });
+      expect(secondResult.stdout).toBe('already started test\n'); // Should still have stdout
+    });
+  });
+
+  describe('.run() method (alias for .start())', () => {
+    test('should work identically to .start() with capture: false', async () => {
+      const result = await $`echo "test with run alias"`.run({
+        capture: false,
+      });
+      expect(result.stdout).toBeUndefined();
+      expect(result.code).toBe(0);
+    });
+
+    test('should work identically to .start() with capture: true', async () => {
+      const result = await $`echo "test with run alias"`.run({ capture: true });
+      expect(result.stdout).toBe('test with run alias\n');
+      expect(result.code).toBe(0);
+    });
+
+    test('should work with multiple options', async () => {
+      const result = await $`echo "run with multiple options"`.run({
+        mirror: false,
+        capture: true,
+      });
+      expect(result.stdout).toBe('run with multiple options\n');
+      expect(result.code).toBe(0);
+    });
+
+    test('should work with stdin option', async () => {
+      const result = await $`cat`.run({
+        stdin: 'run method input',
+        capture: true,
+      });
+      expect(result.stdout).toBe('run method input');
+      expect(result.code).toBe(0);
+    });
+  });
+
+  describe('Backward compatibility', () => {
+    test('direct await should still work with default options', async () => {
+      const result = await $`echo "default behavior"`;
+      expect(result.stdout).toBe('default behavior\n');
+      expect(result.code).toBe(0);
+    });
+
+    test('.start() without options should work identically to direct await', async () => {
+      const directResult = await $`echo "no options test"`;
+      const startResult = await $`echo "no options test"`.start();
+
+      expect(directResult.stdout).toBe(startResult.stdout);
+      expect(directResult.code).toBe(startResult.code);
+    });
+
+    test('.run() without options should work identically to direct await', async () => {
+      const directResult = await $`echo "run no options"`;
+      const runResult = await $`echo "run no options"`.run();
+
+      expect(directResult.stdout).toBe(runResult.stdout);
+      expect(directResult.code).toBe(runResult.code);
+    });
+  });
+
+  describe('Virtual commands support', () => {
+    test('should work with virtual echo command', async () => {
+      const result = await $`echo "virtual command test"`.start({
+        capture: false,
+      });
+      expect(result.stdout).toBeUndefined();
+      expect(result.code).toBe(0);
+    });
+
+    test('should work with virtual commands using .run()', async () => {
+      const result = await $`echo "virtual run test"`.run({
+        capture: true,
+        mirror: false,
+      });
+      expect(result.stdout).toBe('virtual run test\n');
+      expect(result.code).toBe(0);
+    });
+  });
+
+  describe('Edge cases', () => {
+    test('should handle empty options object', async () => {
+      const result = await $`echo "empty options"`.start({});
+      expect(result.stdout).toBe('empty options\n');
+      expect(result.code).toBe(0);
+    });
+
+    test('should handle mode option alongside other options', async () => {
+      const result = await $`echo "with mode option"`.start({
+        mode: 'async',
+        capture: false,
+      });
+      expect(result.stdout).toBeUndefined();
+      expect(result.code).toBe(0);
+    });
+
+    test('should reinitialize chunks when capture option changes', async () => {
+      const runner = $`echo "chunk reinit test"`;
+
+      // Verify initial state
+      expect(runner.options.capture).toBe(true);
+      expect(runner.outChunks).toEqual([]);
+
+      // Change capture to false
+      const result = await runner.start({ capture: false });
+
+      // Verify chunks were reinitialized
+      expect(runner.options.capture).toBe(false);
+      expect(runner.outChunks).toBe(null);
+      expect(result.stdout).toBeUndefined();
+    });
+  });
+});

package/js/tests/stderr-output-handling.test.mjs

@@ -0,0 +1,279 @@
+import { test, expect, describe, beforeEach, afterEach } from 'bun:test';
+import { beforeTestCleanup, afterTestCleanup } from './test-cleanup.mjs';
+import { isWindows } from './test-helper.mjs';
+import { $ } from '../src/$.mjs';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+
+describe('Stderr output handling in $.mjs', () => {
+  beforeEach(async () => {
+    await beforeTestCleanup();
+  });
+
+  afterEach(async () => {
+    await afterTestCleanup();
+  });
+
+  // Skip on Windows - uses sh -c with shell redirection
+  test.skipIf(isWindows)(
+    'commands that output to stderr should not hang when captured',
+    async () => {
+      // Test with a command that writes to stderr
+      const result =
+        await $`sh -c 'echo "stdout message" && echo "stderr message" >&2'`.run(
+          {
+            capture: true,
+            mirror: false,
+            timeout: 5000, // Safety timeout
+          }
+        );
+
+      expect(result.code).toBe(0);
+      expect(result.stdout).toContain('stdout message');
+      expect(result.stderr).toContain('stderr message');
+    }
+  );
+
+  // Skip on Windows - uses 'which' command which is Unix-specific
+  test.skipIf(isWindows)(
+    'gh commands with progress output to stderr should complete',
+    async () => {
+      // Check if gh is available
+      try {
+        await $`which gh`.run({ capture: true, mirror: false });
+      } catch {
+        console.log('Skipping: gh not available');
+        return;
+      }
+
+      // gh version outputs to stderr for progress
+      const result = await $`gh version`.run({
+        capture: true,
+        mirror: false,
+        timeout: 5000,
+      });
+
+      expect(result.code).toBe(0);
+      expect(result.stdout).toBeDefined();
+      // Version info should be in stdout
+      expect(result.stdout).toContain('gh version');
+    }
+  );
+
+  // Skip on Windows - uses sh -c and 2>&1 shell redirection
+  test.skipIf(isWindows)(
+    'capturing with 2>&1 should combine stderr into stdout',
+    async () => {
+      const result =
+        await $`sh -c 'echo "stdout" && echo "stderr" >&2' 2>&1`.run({
+          capture: true,
+          mirror: false,
+        });
+
+      expect(result.code).toBe(0);
+      expect(result.stdout).toContain('stdout');
+      expect(result.stdout).toContain('stderr');
+      expect(result.stderr).toBe(''); // stderr should be empty since redirected
+    }
+  );
+
+  // Skip on Windows - uses sh scripts and chmod
+  test.skipIf(isWindows)(
+    'long-running commands with stderr output should not hang',
+    async () => {
+      // Create a script that outputs to both stdout and stderr over time
+      const scriptPath = path.join(os.tmpdir(), 'test-script.sh');
+      const scriptContent = `#!/bin/sh
+for i in 1 2 3; do
+  echo "stdout: iteration $i"
+  echo "stderr: iteration $i" >&2
+  sleep 0.1
+done
+`;
+      await fs.writeFile(scriptPath, scriptContent);
+      await $`chmod +x ${scriptPath}`.run({ capture: true, mirror: false });
+
+      try {
+        const startTime = Date.now();
+        const result = await $`${scriptPath}`.run({
+          capture: true,
+          mirror: false,
+          timeout: 5000,
+        });
+        const duration = Date.now() - startTime;
+
+        expect(result.code).toBe(0);
+        expect(result.stdout).toContain('stdout: iteration 3');
+        expect(result.stderr).toContain('stderr: iteration 3');
+        expect(duration).toBeLessThan(2000); // Should complete quickly, not hang
+      } finally {
+        await fs.unlink(scriptPath).catch(() => {});
+      }
+    }
+  );
+
+  // Skip on Windows - uses 2>&1 shell redirection which doesn't work the same way on Windows
+  test.skipIf(isWindows)(
+    'gh gist create with stderr progress should work correctly',
+    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;
+      }
+
+      // Check if we can actually create gists (not just authenticated)
+      const testAccess = await $`gh api user/gists --method HEAD 2>&1`.run({
+        capture: true,
+        mirror: false,
+      });
+      if (testAccess.code !== 0) {
+        // In CI with GitHub Actions token, we might get 404 or 403 errors
+        if (
+          testAccess.stdout.includes(
+            'Resource not accessible by integration'
+          ) ||
+          testAccess.stdout.includes('HTTP 404') ||
+          testAccess.stdout.includes('HTTP 403')
+        ) {
+          console.log(
+            'Skipping gh gist test - limited GitHub Actions token or API access (this is OK - we are testing $.mjs, not gh permissions)'
+          );
+          return;
+        }
+      }
+
+      // Create test file
+      const testFile = path.join(os.tmpdir(), 'stderr-test.txt');
+      await fs.writeFile(testFile, 'Testing stderr handling\n');
+
+      let gistId = null;
+
+      try {
+        // Without 2>&1 redirection - capture both streams separately
+        const result1 =
+          await $`gh gist create ${testFile} --desc "stderr-test-1" --public=false`.run(
+            {
+              capture: true,
+              mirror: false,
+              timeout: 10000,
+            }
+          );
+
+        expect(result1.code).toBe(0);
+        expect(result1.stdout).toBeDefined();
+
+        // The URL should be in stdout
+        const url1 = result1.stdout.trim();
+        expect(url1).toContain('gist.github.com');
+        gistId = url1.split('/').pop();
+
+        // Clean up first gist
+        await $`gh gist delete ${gistId} --yes`.run({
+          capture: true,
+          mirror: false,
+        });
+
+        // With 2>&1 redirection - all output in stdout
+        const result2 =
+          await $`gh gist create ${testFile} --desc "stderr-test-2" --public=false 2>&1`.run(
+            {
+              capture: true,
+              mirror: false,
+              timeout: 10000,
+            }
+          );
+
+        expect(result2.code).toBe(0);
+        expect(result2.stdout).toBeDefined();
+
+        // Should contain both progress messages and URL
+        expect(result2.stdout).toContain('Creating gist');
+        expect(result2.stdout).toContain('gist.github.com');
+
+        // Extract and clean up second gist
+        const lines = result2.stdout.trim().split('\n');
+        const url2 = lines.find((line) => line.includes('gist.github.com'));
+        if (url2) {
+          gistId = url2.split('/').pop();
+          await $`gh gist delete ${gistId} --yes`.run({
+            capture: true,
+            mirror: false,
+          });
+        }
+      } finally {
+        // Clean up
+        await fs.unlink(testFile).catch(() => {});
+        if (gistId) {
+          await $`gh gist delete ${gistId} --yes`
+            .run({ capture: true, mirror: false })
+            .catch(() => {});
+        }
+      }
+    }
+  );
+
+  // Skip on Windows - uses sh -c with shell redirection
+  test.skipIf(isWindows)(
+    'streaming mode should handle stderr correctly',
+    async () => {
+      const cmd = $`sh -c 'echo "line1" && echo "err1" >&2 && sleep 0.1 && echo "line2" && echo "err2" >&2'`;
+
+      const collected = {
+        stdout: [],
+        stderr: [],
+      };
+
+      for await (const chunk of cmd.stream()) {
+        if (chunk.type === 'stdout') {
+          collected.stdout.push(chunk.data.toString());
+        } else if (chunk.type === 'stderr') {
+          collected.stderr.push(chunk.data.toString());
+        }
+      }
+
+      const result = await cmd;
+
+      expect(result.code).toBe(0);
+      expect(collected.stdout.join('')).toContain('line1');
+      expect(collected.stdout.join('')).toContain('line2');
+      expect(collected.stderr.join('')).toContain('err1');
+      expect(collected.stderr.join('')).toContain('err2');
+    }
+  );
+
+  // Skip on Windows - uses sh -c with shell redirection; also already skipped
+  test.skip('timeout should work even with pending stderr', async () => {
+    // Command that continuously outputs to stderr
+    const startTime = Date.now();
+
+    try {
+      await $`sh -c 'while true; do echo "stderr output" >&2; sleep 0.1; done'`.run(
+        {
+          capture: true,
+          mirror: false,
+          timeout: 1000, // 1 second timeout
+        }
+      );
+
+      // Should not reach here
+      expect(true).toBe(false);
+    } catch (error) {
+      const duration = Date.now() - startTime;
+
+      // Should have timed out
+      expect(duration).toBeGreaterThanOrEqual(900);
+      expect(duration).toBeLessThan(1500);
+
+      // Error should indicate timeout/killed
+      expect(error).toBeDefined();
+    }
+  });
+});

package/js/tests/streaming-interfaces.test.mjs

@@ -0,0 +1,194 @@
+import { test, expect } from 'bun:test';
+import './test-helper.mjs'; // Automatically sets up beforeEach/afterEach cleanup
+import { $ } from '../src/$.mjs';
+
+// Platform detection - Some tests use Unix utilities (cat, grep, sort, sh)
+const isWindows = process.platform === 'win32';
+
+// Skip on Windows - uses 'cat' command
+test.skipIf(isWindows)(
+  'streaming interfaces - basic functionality',
+  async () => {
+    // Test streams.stdin with cat
+    const catCmd = $`cat`;
+    const stdin = await catCmd.streams.stdin;
+
+    if (stdin) {
+      stdin.write('Hello from streams.stdin!\n');
+      stdin.write('Multiple lines work\n');
+      stdin.end();
+    }
+
+    const result = await catCmd;
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('Hello from streams.stdin!');
+    expect(result.stdout).toContain('Multiple lines work');
+  }
+);
+
+test('streaming interfaces - auto-start behavior', async () => {
+  const cmd = $`echo "test"`;
+
+  // Accessing parent objects should not auto-start
+  const streams = cmd.streams;
+  const buffers = cmd.buffers;
+  const strings = cmd.strings;
+  expect(cmd.started).toBe(false);
+
+  // Accessing actual properties should auto-start
+  const stdout = cmd.streams.stdout;
+  expect(cmd.started).toBe(true);
+
+  await cmd;
+});
+
+// Skip on Windows - uses 'printf' command
+test.skipIf(isWindows)('streaming interfaces - buffers interface', async () => {
+  const cmd = $`printf "Binary test"`;
+  const buffer = await cmd.buffers.stdout;
+
+  expect(Buffer.isBuffer(buffer)).toBe(true);
+  expect(buffer.toString()).toBe('Binary test');
+});
+
+test('streaming interfaces - strings interface', async () => {
+  const cmd = $`echo "String test"`;
+  const str = await cmd.strings.stdout;
+
+  expect(typeof str).toBe('string');
+  expect(str.trim()).toBe('String test');
+});
+
+// Skip on Windows - uses 'sh -c' command
+test.skipIf(isWindows)(
+  'streaming interfaces - mixed stdout/stderr',
+  async () => {
+    const cmd = $`sh -c 'echo "stdout" && echo "stderr" >&2'`;
+
+    const [stdout, stderr] = await Promise.all([
+      cmd.strings.stdout,
+      cmd.strings.stderr,
+    ]);
+
+    expect(stdout.trim()).toBe('stdout');
+    expect(stderr.trim()).toBe('stderr');
+  }
+);
+
+// Skip on Windows - uses Unix signal exit codes (130, 143)
+test.skipIf(isWindows)(
+  'streaming interfaces - kill method works',
+  async () => {
+    const cmd = $`sleep 10`;
+
+    // Start the process
+    await cmd.streams.stdout;
+    expect(cmd.started).toBe(true);
+
+    // Kill after short delay
+    setTimeout(() => cmd.kill(), 100);
+
+    const result = await cmd;
+    expect([130, 143, null]).toContain(result.code); // SIGTERM/SIGINT codes
+  },
+  5000
+);
+
+// Skip on Windows - uses 'cat' command (not available on Windows)
+test.skipIf(isWindows)(
+  'streaming interfaces - stdin control with cross-platform command',
+  async () => {
+    // Use 'cat' which works identically on all platforms and waits for input
+    const catCmd = $`cat`;
+    const stdin = await catCmd.streams.stdin;
+
+    // Send some data and close stdin
+    setTimeout(() => {
+      if (stdin && !stdin.destroyed) {
+        stdin.write('Hello from stdin!\n');
+        stdin.write('Multiple lines work\n');
+        setTimeout(() => stdin.end(), 100);
+      }
+    }, 100);
+
+    // Backup kill (shouldn't be needed since we close stdin)
+    setTimeout(() => {
+      if (!catCmd.finished) {
+        catCmd.kill();
+      }
+    }, 2000);
+
+    const result = await catCmd;
+    expect(typeof result.code).toBe('number');
+    expect(result.code).toBe(0); // Should exit cleanly when stdin is closed
+    expect(result.stdout.length).toBeGreaterThan(0);
+    expect(result.stdout).toContain('Hello from stdin!');
+    expect(result.stdout).toContain('Multiple lines work');
+  },
+  5000
+);
+
+test('streaming interfaces - immediate access after completion', async () => {
+  const cmd = $`echo "immediate test"`;
+  const result = await cmd;
+
+  // After completion, should return immediate results
+  const buffer = cmd.buffers.stdout;
+  const string = cmd.strings.stdout;
+
+  expect(Buffer.isBuffer(buffer)).toBe(true);
+  expect(typeof string).toBe('string');
+  expect(buffer.toString().trim()).toBe('immediate test');
+  expect(string.trim()).toBe('immediate test');
+});
+
+test('streaming interfaces - backward compatibility', async () => {
+  // Traditional await syntax should still work
+  const result = await $`echo "backward compatible"`;
+  expect(result.code).toBe(0);
+  expect(result.stdout.trim()).toBe('backward compatible');
+});
+
+// Skip on Windows - uses 'sort' command with different behavior
+test.skipIf(isWindows)(
+  'streaming interfaces - stdin pipe mode works',
+  async () => {
+    // Test that stdin: 'pipe' is properly handled vs string data
+    const sortCmd = $`sort`;
+    const stdin = await sortCmd.streams.stdin;
+
+    expect(stdin).not.toBe(null);
+    expect(typeof stdin.write).toBe('function');
+
+    stdin.write('zebra\n');
+    stdin.write('apple\n');
+    stdin.write('banana\n');
+    stdin.end();
+
+    const result = await sortCmd;
+    expect(result.code).toBe(0);
+    expect(result.stdout).toBe('apple\nbanana\nzebra\n');
+  }
+);
+
+// Skip on Windows - uses 'grep' command
+test.skipIf(isWindows)(
+  'streaming interfaces - grep filtering via stdin',
+  async () => {
+    const grepCmd = $`grep "important"`;
+    const stdin = await grepCmd.streams.stdin;
+
+    stdin.write('ignore this line\n');
+    stdin.write('important message 1\n');
+    stdin.write('skip this too\n');
+    stdin.write('another important note\n');
+    stdin.end();
+
+    const result = await grepCmd;
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('important message 1');
+    expect(result.stdout).toContain('another important note');
+    expect(result.stdout).not.toContain('ignore this');
+    expect(result.stdout).not.toContain('skip this');
+  }
+);