command-stream 0.8.2 → 0.9.0

package/js/examples/test-jq-colors.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Testing jq color output in pipelines ===\n');
+
+// Test 1: Direct jq with color output
+console.log('1. Direct jq command with --color-output:');
+const directResult =
+  await $`echo '{"name": "test", "value": 42, "active": true}' | jq --color-output .`;
+console.log('Raw output:');
+process.stdout.write(directResult.stdout);
+console.log('\nRaw bytes (first 100):');
+console.log(Buffer.from(directResult.stdout.slice(0, 100)));
+
+console.log('\n2. Pipeline with jq --color-output:');
+const pipeResult =
+  await $`echo '{"users": [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]}' | jq --color-output '.users[]'`;
+console.log('Raw output:');
+process.stdout.write(pipeResult.stdout);
+
+console.log('\n3. Testing if jq auto-detects color capability:');
+const autoResult = await $`echo '{"test": "data"}' | jq .`;
+console.log('Raw output (should have colors if terminal supports it):');
+process.stdout.write(autoResult.stdout);
+
+console.log('\n4. Testing streaming behavior:');
+const streamProc = $`printf '{"a":1}\\n{"b":2}\\n{"c":3}\\n' | jq --color-output -c .`;
+
+console.log('Streaming output:');
+streamProc.on('stdout', (chunk) => {
+  process.stdout.write('CHUNK: ');
+  process.stdout.write(chunk);
+});
+
+await streamProc;
+
+console.log('\n=== Analysis ===');
+console.log('- Direct jq should show colors if --color-output is used');
+console.log('- Pipeline should preserve ANSI codes in streaming');
+console.log('- Check raw bytes to see ANSI escape sequences (\\x1b[...)');

package/js/examples/test-jq-compact.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+
+// Test jq with compact output mode
+
+console.log('Test: jq with -c (compact) flag\n');
+
+const proc1 = Bun.spawn(['./js/examples/emulate-claude-stream.mjs'], {
+  stdout: 'pipe',
+  stderr: 'pipe',
+});
+
+// Use jq -c for compact output (one line per JSON object)
+const proc2 = Bun.spawn(['jq', '-c', '.'], {
+  stdin: proc1.stdout,
+  stdout: 'pipe',
+  stderr: 'pipe',
+});
+
+const start = Date.now();
+let chunkCount = 0;
+
+for await (const chunk of proc2.stdout) {
+  chunkCount++;
+  const elapsed = Date.now() - start;
+  const text = Buffer.from(chunk).toString().trim();
+
+  console.log(`[${elapsed}ms] Chunk ${chunkCount}: ${text}`);
+}
+
+console.log(`\nTotal chunks received: ${chunkCount}`);
+
+await proc1.exited;
+await proc2.exited;

package/js/examples/test-jq-native.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+echo "Testing native jq streaming (without our library):"
+echo "Each JSON object should appear immediately, not all at once"
+echo ""
+
+# Test with delays - jq should output each line as it arrives
+(echo '{"n":1}'; sleep 0.5; echo '{"n":2}'; sleep 0.5; echo '{"n":3}') | jq . | while read line; do
+    echo "[$(date +%s%3N)] $line"
+done

package/js/examples/test-jq-pipeline-behavior.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+/**
+ * Test to demonstrate jq's color behavior in different contexts
+ */
+
+import { $ } from '../src/$.mjs';
+import { execSync } from 'child_process';
+
+const testJson = '{"message": "hello", "number": 42}';
+
+console.log('='.repeat(60));
+console.log('JQ COLOR BEHAVIOR IN DIFFERENT CONTEXTS');
+console.log('='.repeat(60));
+
+console.log('\nEnvironment:', {
+  'process.stdout.isTTY': process.stdout.isTTY,
+  TERM: process.env.TERM,
+});
+
+console.log('\n1. JQ IN A PIPELINE (through command-stream):');
+console.log('-'.repeat(40));
+// When jq is part of a pipeline, it detects it's not writing to a TTY
+const pipeResult = await $`echo ${testJson} | jq .`;
+console.log('Command: echo ... | jq .');
+console.log('Has colors:', /\u001b\[\d+/.test(pipeResult.stdout));
+console.log("Reason: jq detects it's in a pipeline, not direct TTY output\n");
+
+console.log('2. JQ DIRECTLY TO TTY (if possible):');
+console.log('-'.repeat(40));
+try {
+  // Try to run jq directly without a pipe
+  const directResult = await $`jq . <<< '${testJson}'`;
+  console.log('Command: jq . <<< ...');
+  console.log('Has colors:', /\u001b\[\d+/.test(directResult.stdout));
+  console.log('Output sample:', directResult.stdout.substring(0, 50));
+} catch (e) {
+  console.log('Could not test direct jq (bash syntax not supported)');
+}
+
+console.log('\n3. JQ WITH EXPLICIT COLOR FLAGS:');
+console.log('-'.repeat(40));
+const colorResult = await $`echo ${testJson} | jq -C .`;
+console.log('Command: echo ... | jq -C .');
+console.log(
+  'Has colors:',
+  /\u001b\[\d+/.test(colorResult.stdout),
+  '(forced with -C)'
+);
+
+const noColorResult = await $`echo ${testJson} | jq -M .`;
+console.log('Command: echo ... | jq -M .');
+console.log(
+  'Has colors:',
+  /\u001b\[\d+/.test(noColorResult.stdout),
+  '(disabled with -M)'
+);
+
+console.log('\n4. DIRECT SHELL EXECUTION (for comparison):');
+console.log('-'.repeat(40));
+try {
+  // Using execSync to run directly in shell
+  const shellOutput = execSync(`echo '${testJson}' | jq .`, {
+    encoding: 'utf8',
+    shell: '/bin/sh',
+  });
+  console.log('Via execSync with shell:');
+  console.log('Has colors:', /\u001b\[\d+/.test(shellOutput));
+} catch (e) {
+  console.log('Error:', e.message);
+}
+
+console.log(`\n${'='.repeat(60)}`);
+console.log('SUMMARY:');
+console.log("- jq auto-detects when it's in a pipeline vs direct TTY");
+console.log('- In pipelines, jq disables colors by default (smart behavior)');
+console.log('- This is why the test sees no colors even with isTTY=true');
+console.log('- The -C flag forces colors even in pipelines');
+console.log('- The -M flag disables colors even with TTY');
+console.log('='.repeat(60));

package/js/examples/test-jq-realtime.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env bun
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Testing Real-Time jq Streaming ===\n');
+
+console.log('Test: Emulated Claude stream with jq formatting');
+const start = Date.now();
+let lastTime = start;
+let chunkCount = 0;
+
+for await (const chunk of $`bun run js/examples/emulate-claude-stream.mjs | jq .`.stream()) {
+  if (chunk.type === 'stdout') {
+    chunkCount++;
+    const now = Date.now();
+    const elapsed = now - start;
+    const delta = now - lastTime;
+    lastTime = now;
+
+    const text = chunk.data.toString().trim();
+    if (text) {
+      console.log(`[${elapsed}ms, +${delta}ms] Chunk ${chunkCount}:`);
+      console.log(text);
+      console.log('---');
+    }
+  }
+}
+
+console.log(`\nTotal chunks received: ${chunkCount}`);
+console.log(`Total time: ${Date.now() - start}ms`);
+
+if (chunkCount >= 5) {
+  console.log(
+    '✅ SUCCESS: Real-time streaming is working! We received multiple chunks over time.'
+  );
+} else if (chunkCount === 1) {
+  console.log('❌ FAIL: All output was buffered into a single chunk.');
+} else {
+  console.log('⚠️  WARNING: Received fewer chunks than expected.');
+}

package/js/examples/test-manual-start.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+async function testManualStart() {
+  console.log('🧪 Testing manual start with pipe stdin');
+
+  // Start manually with correct options
+  const sortCmd = $`sort`;
+  console.log('1. Created sort command');
+
+  // Manual start with correct stdio
+  await sortCmd.start({
+    mode: 'async',
+    stdin: 'pipe',
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  console.log('2. Manually started with pipe stdio');
+
+  console.log('3. After manual start:');
+  console.log('   started:', sortCmd.started);
+  console.log('   child exists:', !!sortCmd.child);
+
+  if (sortCmd.child) {
+    console.log('   child.stdin exists:', !!sortCmd.child.stdin);
+    console.log(
+      '   child.stdin writable:',
+      sortCmd.child.stdin ? sortCmd.child.stdin.writable : 'N/A'
+    );
+    console.log('   child.stdin type:', typeof sortCmd.child.stdin);
+  }
+
+  // Now try to get stdin through streams
+  const stdin = await sortCmd.streams.stdin;
+  console.log('4. Got stdin through streams:');
+  console.log('   type:', typeof stdin);
+  console.log('   has write:', !!(stdin && stdin.write));
+
+  if (stdin && stdin.write) {
+    console.log('5. Writing to stdin...');
+    stdin.write('zebra\n');
+    stdin.write('apple\n');
+    stdin.end();
+
+    const result = await sortCmd;
+    console.log('   Result:', JSON.stringify(result.stdout));
+  } else {
+    console.log('5. No writable stdin, killing...');
+    sortCmd.kill();
+  }
+}
+
+testManualStart();

package/js/examples/test-mixed-quoting.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+// Test: Mixed quoted and unquoted arguments
+// Expected: Each argument properly handled based on its content
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Test: Mixed Quoting Scenarios ===\n');
+
+async function testMixedQuoting() {
+  console.log('1. Multiple interpolations in one command:');
+  console.log('------------------------------------------');
+
+  const cmd = 'echo';
+  const arg1 = 'hello';
+  const arg2 = 'world';
+  const arg3 = '$USER';
+
+  const command = $({ mirror: false })`${cmd} ${arg1} ${arg2} ${arg3}`;
+  console.log('Inputs:', { cmd, arg1, arg2, arg3 });
+  console.log('Generated:', command.spec.command);
+
+  try {
+    const result = await command;
+    console.log('Output:', String(result).trim());
+  } catch (error) {
+    console.log('Error:', error.message);
+  }
+
+  console.log('\n2. Mix of pre-quoted and unquoted:');
+  console.log('-----------------------------------');
+
+  const quotedPath = '"/path with spaces/file.txt"';
+  const unquotedPath = 'output.log';
+
+  const mixedCmd = $({ mirror: false })`cat ${quotedPath} > ${unquotedPath}`;
+  console.log('Quoted input:', quotedPath);
+  console.log('Unquoted input:', unquotedPath);
+  console.log('Generated:', mixedCmd.spec.command);
+
+  console.log('\n3. Command construction with various types:');
+  console.log('--------------------------------------------');
+
+  const executable = '/usr/bin/env';
+  const program = 'node';
+  const flag = '--version';
+  const envVar = 'NODE_ENV=production';
+
+  const complexCmd = $({
+    mirror: false,
+  })`${envVar} ${executable} ${program} ${flag}`;
+  console.log('Components:', { envVar, executable, program, flag });
+  console.log('Generated:', complexCmd.spec.command);
+
+  console.log('\n4. User mixes single and double quotes:');
+  console.log('----------------------------------------');
+
+  const singleQuotedArg = "'my-file.txt'";
+  const doubleQuotedArg = '"another file.txt"';
+  const unquotedArg = 'regular.txt';
+
+  const userMixedCmd = $({
+    mirror: false,
+  })`ls ${singleQuotedArg} ${doubleQuotedArg} ${unquotedArg}`;
+  console.log('Single quoted:', singleQuotedArg);
+  console.log('Double quoted:', doubleQuotedArg);
+  console.log('Unquoted:', unquotedArg);
+  console.log('Generated:', userMixedCmd.spec.command);
+
+  console.log('\n5. Path interpolation positions:');
+  console.log('---------------------------------');
+
+  const testPath = '/Users/konard/.claude/local/claude';
+
+  // First position (command)
+  const firstPos = $({ mirror: false })`${testPath} --version`;
+  console.log('First position:', firstPos.spec.command);
+
+  // Middle position
+  const middlePos = $({ mirror: false })`echo ${testPath} done`;
+  console.log('Middle position:', middlePos.spec.command);
+
+  // Last position
+  const lastPos = $({ mirror: false })`file ${testPath}`;
+  console.log('Last position:', lastPos.spec.command);
+}
+
+testMixedQuoting().catch(console.error);

package/js/examples/test-multi-stream.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env bun
+
+// Test reading from multiple processes in pipeline simultaneously
+
+console.log('=== Testing Multi-Stream Pipeline Reading ===\n');
+
+const proc1 = Bun.spawn(
+  ['bun', 'run', 'js/examples/emulate-claude-stream.mjs'],
+  {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  }
+);
+
+// Use tee to split the stream so we can both pipe it and read it
+const [readStream, pipeStream] = proc1.stdout.tee();
+
+const proc2 = Bun.spawn(['jq', '.'], {
+  stdin: pipeStream,
+  stdout: 'pipe',
+  stderr: 'pipe',
+});
+
+const start = Date.now();
+
+// Read from proc1's tee'd stream for real-time updates
+console.log('Reading from source (proc1):');
+(async () => {
+  for await (const chunk of readStream) {
+    const elapsed = Date.now() - start;
+    const text = Buffer.from(chunk).toString().trim();
+    console.log(`  [${elapsed}ms] Source: ${text}`);
+  }
+})();
+
+// Also read from proc2 to get the final jq output
+console.log('\nReading from jq output (proc2):');
+let jqOutput = '';
+for await (const chunk of proc2.stdout) {
+  const elapsed = Date.now() - start;
+  const text = Buffer.from(chunk).toString();
+  jqOutput += text;
+  console.log(`  [${elapsed}ms] jq completed, ${chunk.length} bytes`);
+}
+
+console.log('\nFinal jq output:');
+console.log(jqOutput);
+
+await proc1.exited;
+await proc2.exited;

package/js/examples/test-multistage-debug.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env bun
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Debug Multi-Stage Pipeline ===\n');
+
+console.log('Testing: emulate | cat | jq');
+const start = Date.now();
+let chunkCount = 0;
+let firstChunkTime = null;
+let lastChunkTime = null;
+
+for await (const chunk of $`bun run js/examples/emulate-claude-stream.mjs | cat | jq .`.stream()) {
+  if (chunk.type === 'stdout') {
+    chunkCount++;
+    const elapsed = Date.now() - start;
+
+    if (!firstChunkTime) {
+      firstChunkTime = elapsed;
+    }
+    lastChunkTime = elapsed;
+
+    console.log(
+      `[${elapsed}ms] Chunk ${chunkCount}: ${chunk.data.length} bytes`
+    );
+  }
+}
+
+console.log(`\nSummary:`);
+console.log(`- Total chunks: ${chunkCount}`);
+console.log(`- First chunk at: ${firstChunkTime}ms`);
+console.log(`- Last chunk at: ${lastChunkTime}ms`);
+console.log(`- Time span: ${lastChunkTime - firstChunkTime}ms`);
+
+if (chunkCount === 1) {
+  console.log('\n❌ All output was buffered into a single chunk');
+  console.log('This means jq collected all input before producing output');
+} else if (lastChunkTime - firstChunkTime < 100) {
+  console.log('\n⚠️  Chunks arrived very close together (< 100ms span)');
+  console.log('This suggests partial buffering');
+} else {
+  console.log('\n✅ Real-time streaming is working!');
+  console.log('Chunks arrived over time as expected');
+}

package/js/examples/test-native-spawn-vs-command-stream.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+/**
+ * Test to prove that native spawn/child_process cannot kill ping via stdin,
+ * but our command-stream library can kill it properly with the kill() method.
+ */
+
+import { spawn } from 'child_process';
+import { $ } from '../src/$.mjs';
+
+console.log('=== Testing Native spawn vs command-stream kill capabilities ===');
+console.log('');
+
+async function testNativeSpawnVsCommandStream() {
+  try {
+    console.log(
+      'TEST 1: Native spawn - try to kill ping via stdin (will fail)'
+    );
+
+    const nativeProcess = spawn('ping', ['8.8.8.8']);
+    console.log('✓ Native ping process started, PID:', nativeProcess.pid);
+
+    // Try to send CTRL+C via stdin (this won't work for ping)
+    setTimeout(() => {
+      console.log('  Attempting to send CTRL+C via stdin to native ping...');
+      nativeProcess.stdin.write('\x03'); // CTRL+C
+      nativeProcess.stdin.end();
+    }, 2000);
+
+    // Set up a timeout to kill the process since stdin won't work
+    const killTimeout = setTimeout(() => {
+      console.log('  stdin CTRL+C failed (as expected), using SIGTERM...');
+      nativeProcess.kill('SIGTERM');
+    }, 4000);
+
+    const nativeResult = await new Promise((resolve) => {
+      let stdout = '';
+      let stderr = '';
+
+      nativeProcess.stdout.on('data', (data) => {
+        stdout += data.toString();
+        process.stdout.write(`[NATIVE] ${data}`);
+      });
+
+      nativeProcess.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+
+      nativeProcess.on('close', (code, signal) => {
+        clearTimeout(killTimeout);
+        resolve({ code, signal, stdout, stderr });
+      });
+    });
+
+    console.log(
+      '  Native ping terminated with code:',
+      nativeResult.code,
+      'signal:',
+      nativeResult.signal
+    );
+    console.log('  Output length:', nativeResult.stdout.length);
+
+    console.log('');
+    console.log(
+      'TEST 2: command-stream - kill ping using kill() method (will work)'
+    );
+
+    const streamCommand = $`ping 8.8.8.8`;
+
+    // Access stdout to start the process
+    const stdout = streamCommand.streams.stdout;
+    console.log('✓ command-stream ping started');
+
+    // Set up data listener to see output
+    if (stdout) {
+      stdout.on('data', (data) => {
+        process.stdout.write(`[STREAM] ${data}`);
+      });
+    }
+
+    // Kill after 2 seconds using our kill() method
+    setTimeout(() => {
+      console.log('  Killing command-stream ping using kill() method...');
+      streamCommand.kill();
+    }, 2000);
+
+    const streamResult = await streamCommand;
+    console.log(
+      '  command-stream ping terminated with code:',
+      streamResult.code
+    );
+    console.log('  Output length:', streamResult.stdout.length);
+
+    console.log('');
+    console.log(
+      'TEST 3: Show stdin works for commands that actually read stdin'
+    );
+
+    console.log('  Testing native spawn with cat (stdin should work)...');
+    const nativeCat = spawn('cat');
+
+    nativeCat.stdin.write('Hello from native cat\n');
+    nativeCat.stdin.end();
+
+    const catResult = await new Promise((resolve) => {
+      let output = '';
+      nativeCat.stdout.on('data', (data) => {
+        output += data.toString();
+      });
+      nativeCat.on('close', (code) => {
+        resolve({ code, output });
+      });
+    });
+
+    console.log('  Native cat result:', JSON.stringify(catResult.output));
+
+    console.log('  Testing command-stream with cat...');
+    const streamCat = $`cat`;
+    const catStdin = streamCat.streams.stdin;
+
+    if (catStdin) {
+      catStdin.write('Hello from command-stream cat\n');
+      catStdin.end();
+    }
+
+    const streamCatResult = await streamCat;
+    console.log(
+      '  command-stream cat result:',
+      JSON.stringify(streamCatResult.stdout)
+    );
+
+    console.log('');
+    console.log('✅ CONCLUSIONS:');
+    console.log(
+      '  1. Native spawn cannot kill ping via stdin CTRL+C (ping ignores stdin)'
+    );
+    console.log(
+      '  2. command-stream kill() method properly terminates ping with signals'
+    );
+    console.log(
+      '  3. Both native spawn and command-stream work fine with stdin for commands that read it (like cat)'
+    );
+    console.log(
+      '  4. For ping specifically, you need kill() method, not stdin manipulation'
+    );
+  } catch (error) {
+    console.log('');
+    console.error('❌ TEST FAILED:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+testNativeSpawnVsCommandStream();

package/js/examples/test-no-parse-pipeline.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing: Disable pipeline parsing, let sh handle it\n');
+
+// Temporarily disable pipeline parsing to test
+const originalParse = $.prototype._parseCommand;
+$.prototype._parseCommand = function (command) {
+  // Skip pipeline parsing
+  return null;
+};
+
+const start = Date.now();
+
+// This will now be executed as a single sh command
+const cmd = $`bun run js/examples/emulate-claude-stream.mjs | jq .`;
+
+for await (const chunk of cmd.stream()) {
+  if (chunk.type === 'stdout') {
+    const elapsed = Date.now() - start;
+    const lines = chunk.data
+      .toString()
+      .split('\n')
+      .filter((l) => l.trim());
+    for (const line of lines) {
+      console.log(`[${elapsed}ms] ${line}`);
+    }
+  }
+}
+
+// Restore original parsing
+$.prototype._parseCommand = originalParse;

package/js/examples/test-non-virtual.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+async function testNonVirtual() {
+  console.log('🧪 Testing with definitely non-virtual command');
+
+  // Use wc which should not be virtual
+  const wcCmd = $`wc -l`;
+  console.log('1. Created wc command');
+
+  // Check if process spawns properly with regular async execution
+  console.log('2. Testing normal execution first...');
+  const testCmd = $`wc -l`;
+  const testResult = await testCmd.start({ stdin: 'test\nline2\n' });
+  console.log('   Normal execution result:', testResult.stdout.trim());
+
+  // Now test streams
+  console.log('3. Testing streams...');
+  await wcCmd.start({
+    mode: 'async',
+    stdin: 'pipe',
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+
+  console.log('4. After start:');
+  console.log('   started:', wcCmd.started);
+  console.log('   child exists:', !!wcCmd.child);
+  console.log('   finished:', wcCmd.finished);
+
+  if (wcCmd.child) {
+    console.log('   child.pid:', wcCmd.child.pid);
+    console.log('   child.stdin:', typeof wcCmd.child.stdin);
+  }
+
+  // Try direct access to child stdin if available
+  if (wcCmd.child && wcCmd.child.stdin) {
+    console.log('5. Direct child.stdin access works!');
+    wcCmd.child.stdin.write('line1\n');
+    wcCmd.child.stdin.write('line2\n');
+    wcCmd.child.stdin.end();
+
+    const result = await wcCmd;
+    console.log('   Direct access result:', result.stdout.trim());
+  } else {
+    console.log('5. No child.stdin available');
+    wcCmd.kill();
+  }
+}
+
+testNonVirtual();