command-stream 0.8.2 → 0.9.0

package/js/examples/test-direct-pipe-reading.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env bun
+
+// Test different ways to read from piped processes
+
+console.log('=== Testing Direct Pipe Reading Methods ===\n');
+
+// Method 1: Two separate processes with manual pipe
+console.log('Method 1: Manual pipe connection with for await:');
+{
+  const proc1 = Bun.spawn(
+    ['bun', 'run', 'js/examples/emulate-claude-stream.mjs'],
+    {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    }
+  );
+
+  const proc2 = Bun.spawn(['jq', '.'], {
+    stdin: proc1.stdout,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+
+  const start = Date.now();
+  let chunkCount = 0;
+
+  // Read using for await
+  for await (const chunk of proc2.stdout) {
+    chunkCount++;
+    const elapsed = Date.now() - start;
+    console.log(`  [${elapsed}ms] Chunk ${chunkCount}: ${chunk.length} bytes`);
+  }
+
+  await proc1.exited;
+  await proc2.exited;
+}
+
+// Method 2: Try reading proc1.stdout directly while it's also piped
+console.log('\nMethod 2: Read from first process while piped:');
+{
+  const proc1 = Bun.spawn(
+    ['bun', 'run', 'js/examples/emulate-claude-stream.mjs'],
+    {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    }
+  );
+
+  const start = Date.now();
+  let chunkCount = 0;
+
+  // Try to read proc1 stdout directly (even though it will be piped)
+  for await (const chunk of proc1.stdout) {
+    chunkCount++;
+    const elapsed = Date.now() - start;
+    const text = Buffer.from(chunk).toString().trim();
+    console.log(`  [${elapsed}ms] From proc1: ${text}`);
+  }
+
+  await proc1.exited;
+}
+
+// Method 3: Use tee to split the stream
+console.log('\nMethod 3: Using tee() to split stream:');
+{
+  const proc1 = Bun.spawn(
+    ['bun', 'run', 'js/examples/emulate-claude-stream.mjs'],
+    {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    }
+  );
+
+  // Use ReadableStream.tee() to split the stream
+  const [stream1, stream2] = proc1.stdout.tee();
+
+  const proc2 = Bun.spawn(['jq', '.'], {
+    stdin: stream2,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+
+  const start = Date.now();
+  let chunkCount = 0;
+
+  // Read from the tee'd stream
+  for await (const chunk of stream1) {
+    chunkCount++;
+    const elapsed = Date.now() - start;
+    const text = Buffer.from(chunk).toString().trim();
+    console.log(`  [${elapsed}ms] From tee: ${text}`);
+  }
+
+  await proc1.exited;
+  await proc2.exited;
+}
+
+// Method 4: What if we DON'T pipe and just run the full command?
+console.log('\nMethod 4: Full pipeline as single command:');
+{
+  const proc = Bun.spawn(
+    ['sh', '-c', 'bun run js/examples/emulate-claude-stream.mjs | jq .'],
+    {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    }
+  );
+
+  const start = Date.now();
+  let chunkCount = 0;
+
+  for await (const chunk of proc.stdout) {
+    chunkCount++;
+    const elapsed = Date.now() - start;
+    console.log(`  [${elapsed}ms] Chunk ${chunkCount}: ${chunk.length} bytes`);
+  }
+
+  await proc.exited;
+}

package/js/examples/test-direct-pipe.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+echo "Testing if jq buffers output:"
+echo ""
+
+# Create a script that outputs JSON with delays
+cat > /tmp/stream-test.sh << 'EOF'
+#!/bin/bash
+echo '{"n":1}'
+sleep 0.5
+echo '{"n":2}'
+sleep 0.5  
+echo '{"n":3}'
+EOF
+
+chmod +x /tmp/stream-test.sh
+
+echo "Running: /tmp/stream-test.sh | jq . | while read line..."
+echo "If jq doesn't buffer, we should see output every 0.5 seconds"
+echo ""
+
+start=$SECONDS
+/tmp/stream-test.sh | jq . | while IFS= read -r line; do
+    elapsed=$((SECONDS - start))
+    echo "[${elapsed}s] $line"
+done
+
+rm /tmp/stream-test.sh

package/js/examples/test-double-quoting-prevention.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+
+// Test: Prevent double-quoting when user provides quotes on strings that need quoting
+import { $ } from '../src/$.mjs';
+
+console.log('=== Double-Quoting Prevention Test ===\n');
+
+async function testDoubleQuoting() {
+  console.log('Scenario 1: User quotes a path with spaces');
+  console.log('-------------------------------------------');
+
+  // User provides quotes around a path with spaces
+  const pathWithSpaces = '/path with spaces/command';
+  const userQuoted1 = `'${pathWithSpaces}'`;
+  const userQuoted2 = `"${pathWithSpaces}"`;
+
+  console.log('Original path:', pathWithSpaces);
+  console.log('\nUser provides single quotes:', userQuoted1);
+  const cmd1 = $({ mirror: false })`${userQuoted1} --test`;
+  console.log('Generated:', cmd1.spec.command);
+  console.log('Expected: Already quoted, should not double-quote');
+
+  console.log('\nUser provides double quotes:', userQuoted2);
+  const cmd2 = $({ mirror: false })`${userQuoted2} --test`;
+  console.log('Generated:', cmd2.spec.command);
+  console.log('Expected: Preserve double quotes (wrap in single quotes)');
+
+  console.log('\n\nScenario 2: User quotes a string with special characters');
+  console.log('----------------------------------------------------------');
+
+  // User provides quotes around dangerous strings
+  const dangerous = 'test; echo HACKED';
+  const userQuotedDanger1 = `'${dangerous}'`;
+  const userQuotedDanger2 = `"${dangerous}"`;
+
+  console.log('Dangerous string:', dangerous);
+  console.log('\nUser provides single quotes:', userQuotedDanger1);
+  const cmd3 = $({ mirror: false })`echo ${userQuotedDanger1}`;
+  console.log('Generated:', cmd3.spec.command);
+  console.log('Expected: Already single-quoted, should not double-quote');
+
+  console.log('\nUser provides double quotes:', userQuotedDanger2);
+  const cmd4 = $({ mirror: false })`echo ${userQuotedDanger2}`;
+  console.log('Generated:', cmd4.spec.command);
+  console.log('Expected: Preserve double quotes (wrap in single quotes)');
+
+  console.log('\n\nScenario 3: User quotes safe strings (unnecessary)');
+  console.log('----------------------------------------------------');
+
+  const safe = 'hello';
+  const userQuotedSafe1 = `'${safe}'`;
+  const userQuotedSafe2 = `"${safe}"`;
+
+  console.log('Safe string:', safe);
+  console.log('\nUser unnecessarily single-quotes:', userQuotedSafe1);
+  const cmd5 = $({ mirror: false })`echo ${userQuotedSafe1}`;
+  console.log('Generated:', cmd5.spec.command);
+  console.log("Expected: Preserve user's quotes even if unnecessary");
+
+  console.log('\nUser unnecessarily double-quotes:', userQuotedSafe2);
+  const cmd6 = $({ mirror: false })`echo ${userQuotedSafe2}`;
+  console.log('Generated:', cmd6.spec.command);
+  console.log("Expected: Preserve user's quotes (wrap in single quotes)");
+
+  console.log('\n\nScenario 4: Complex edge cases');
+  console.log('--------------------------------');
+
+  // User quotes a string that contains quotes
+  const withQuotes = "it's a test";
+  const userQuotedComplex = `"${withQuotes}"`;
+
+  console.log('String with internal quotes:', withQuotes);
+  console.log('User wraps in double quotes:', userQuotedComplex);
+  const cmd7 = $({ mirror: false })`echo ${userQuotedComplex}`;
+  console.log('Generated:', cmd7.spec.command);
+  console.log('Expected: Preserve double quotes, wrap in single quotes');
+
+  // User provides escaped quotes
+  const alreadyEscaped = "\\'test\\'";
+  console.log('\nAlready escaped string:', alreadyEscaped);
+  const cmd8 = $({ mirror: false })`echo ${alreadyEscaped}`;
+  console.log('Generated:', cmd8.spec.command);
+  console.log('Expected: Handle escaped quotes properly');
+
+  console.log('\n\n=== Verification Tests ===\n');
+
+  // Test that the commands actually work
+  console.log('Testing actual execution:');
+
+  try {
+    // Test with user-quoted path with spaces
+    const testPath = '"/test path/cmd"';
+    const testCmd = $({ capture: true, mirror: false })`echo ${testPath}`;
+    const result = await testCmd;
+    console.log('\nInput:', testPath);
+    console.log('Command:', testCmd.spec.command);
+    console.log('Output:', (result.stdout || String(result)).trim());
+    console.log(
+      'Verification:',
+      (result.stdout || String(result)).trim() === '"/test path/cmd"'
+        ? '✅ Quotes preserved correctly'
+        : '❌ Quotes not preserved'
+    );
+
+    // Test with user-quoted dangerous string
+    const testDanger = "'test; echo BAD'";
+    const dangerCmd = $({ capture: true, mirror: false })`echo ${testDanger}`;
+    const dangerResult = await dangerCmd;
+    console.log('\nInput:', testDanger);
+    console.log('Command:', dangerCmd.spec.command);
+    console.log(
+      'Output:',
+      (dangerResult.stdout || String(dangerResult)).trim()
+    );
+    console.log(
+      'Verification:',
+      !(dangerResult.stdout || String(dangerResult)).includes('BAD')
+        ? '✅ No injection occurred'
+        : '❌ INJECTION!'
+    );
+  } catch (error) {
+    console.error('Execution error:', error.message);
+  }
+
+  console.log('\n\n=== Double-Quote Prevention Rules ===\n');
+  console.log(
+    '1. If string starts and ends with single quotes: preserve as-is (no double-quoting)'
+  );
+  console.log(
+    '2. If string starts and ends with double quotes: wrap in single quotes to preserve'
+  );
+  console.log('3. If string has no quotes but needs them: add single quotes');
+  console.log(
+    "4. If string has no quotes and doesn't need them: leave unquoted"
+  );
+}
+
+testDoubleQuoting().catch(console.error);

package/js/examples/test-edge-cases-quoting.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+// Test: Edge cases for quote handling
+// Expected: Proper handling of unusual quoting scenarios
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Test: Quote Edge Cases ===\n');
+
+const edgeCases = [
+  {
+    desc: 'Single quote character alone',
+    input: "'",
+    check: (cmd) => cmd.includes("\\'"),
+  },
+  {
+    desc: 'Double quote character alone',
+    input: '"',
+    check: (cmd) => true,
+  },
+  {
+    desc: 'Empty single quotes',
+    input: "''",
+    check: (cmd) => cmd === "echo ''",
+  },
+  {
+    desc: 'Empty double quotes',
+    input: '""',
+    check: (cmd) => cmd === 'echo \'""\'',
+  },
+  {
+    desc: 'Nested quotes (double inside single)',
+    input: '\'"test"\'',
+    check: (cmd) => true,
+  },
+  {
+    desc: 'Nested quotes (single inside double)',
+    input: '"\'test\'"',
+    check: (cmd) => true,
+  },
+  {
+    desc: 'Multiple single quotes',
+    input: "'''",
+    check: (cmd) => true,
+  },
+  {
+    desc: 'Path with internal quotes',
+    input: "/path/with'quote/in'it",
+    check: (cmd) => cmd.includes("\\'"),
+  },
+  {
+    desc: 'Already escaped quote',
+    input: "can\\'t",
+    check: (cmd) => true,
+  },
+  {
+    desc: 'Mix of quotes and spaces',
+    input: 'it\'s "a test"',
+    check: (cmd) => true,
+  },
+];
+
+async function testEdgeCases() {
+  for (const { desc, input, check } of edgeCases) {
+    console.log(`\n${desc}:`);
+    console.log('Input:', JSON.stringify(input));
+
+    const cmd = $({ mirror: false })`echo ${input}`;
+    console.log('Generated:', cmd.spec.command);
+
+    if (check && check(cmd.spec.command)) {
+      console.log('✅ PASS: Handled correctly');
+    } else {
+      console.log('⚠️  Check the quoting pattern');
+    }
+
+    // Test actual execution for some cases
+    if (!input.includes('|') && !input.includes('&') && !input.includes(';')) {
+      try {
+        const result = await $`echo ${input}`;
+        console.log('Execution output:', JSON.stringify(String(result).trim()));
+      } catch (error) {
+        console.log('Execution error:', error.message);
+      }
+    }
+  }
+}
+
+testEdgeCases().catch(console.error);

package/js/examples/test-events.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env bun
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Test Event Emissions ===\n');
+
+console.log('Test: emulate | cat | jq with event listeners');
+const cmd = $`bun run js/examples/emulate-claude-stream.mjs | cat | jq .`;
+
+const start = Date.now();
+let eventCount = 0;
+
+// Listen to raw stdout events
+cmd.on('stdout', (data) => {
+  eventCount++;
+  const elapsed = Date.now() - start;
+  const text = data.toString().trim();
+  if (eventCount <= 3 || elapsed < 700) {
+    console.log(
+      `[${elapsed}ms] Event ${eventCount}: ${text.substring(0, 50)}...`
+    );
+  }
+});
+
+// Also run the command
+const result = await cmd;
+
+console.log(`\nTotal events: ${eventCount}`);
+console.log(`Final output length: ${result.stdout.length} chars`);
+
+if (eventCount >= 5) {
+  console.log('✅ Real-time events are being emitted from source!');
+  console.log('The implementation is streaming correctly.');
+  console.log('The formatted jq output is available in result.stdout');
+} else {
+  console.log('❌ Not enough events emitted');
+}

package/js/examples/test-explicit-stdio.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Test with explicit stdio configuration ===');
+
+async function testExplicitStdio() {
+  console.log('Test 1: Use run() with explicit stdio');
+
+  const cmd1 = $`cat`;
+  const stdin1 = cmd1.streams.stdin;
+
+  console.log('Stdin before run:', !!stdin1);
+
+  // Explicitly set stdio to pipe mode
+  const runPromise = cmd1.run({
+    stdin: 'pipe',
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+
+  console.log('Command started?', cmd1.started);
+  console.log('Stdin after start:', !!cmd1.streams.stdin);
+
+  const actualStdin = cmd1.streams.stdin;
+  if (actualStdin) {
+    actualStdin.write('Hello explicit stdio\\n');
+    actualStdin.end();
+  }
+
+  const result1 = await runPromise;
+  console.log('Result:', result1);
+
+  console.log('\\nTest 2: Start manually with stdio options');
+
+  const cmd2 = $`cat`;
+  cmd2.start({ mode: 'async', stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' });
+
+  const stdin2 = cmd2.streams.stdin;
+  console.log('Manual start stdin available?', !!stdin2);
+
+  if (stdin2) {
+    stdin2.write('Manual start test\\n');
+    stdin2.end();
+  }
+
+  const result2 = await cmd2;
+  console.log('Manual result:', result2);
+}
+
+testExplicitStdio().catch(console.error);

package/js/examples/test-final-streaming.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env bun
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Final Streaming Test with PTY Workaround ===\n');
+
+console.log('Test 1: Direct emulator execution (baseline):');
+{
+  const start = Date.now();
+  for await (const chunk of $`bun run js/examples/emulate-claude-stream.mjs`.stream()) {
+    if (chunk.type === 'stdout') {
+      const elapsed = Date.now() - start;
+      const lines = chunk.data
+        .toString()
+        .trim()
+        .split('\n')
+        .filter((l) => l);
+      for (const line of lines) {
+        console.log(`  [${elapsed}ms] ${line}`);
+      }
+    }
+  }
+}
+
+console.log(
+  '\nTest 2: Emulator piped through jq (should stream in real-time):'
+);
+{
+  const start = Date.now();
+  let chunkCount = 0;
+
+  for await (const chunk of $`bun run js/examples/emulate-claude-stream.mjs | jq .`.stream()) {
+    if (chunk.type === 'stdout') {
+      chunkCount++;
+      const elapsed = Date.now() - start;
+      const text = chunk.data.toString();
+      const lines = text.split('\n').filter((l) => l.trim());
+
+      if (lines.length > 0) {
+        console.log(`  [${elapsed}ms] Chunk ${chunkCount}: ${lines[0]}`);
+        if (lines.length > 1) {
+          console.log(
+            `                    ... and ${lines.length - 1} more lines`
+          );
+        }
+      }
+    }
+  }
+  console.log(`  Total chunks: ${chunkCount}`);
+}
+
+console.log('\nTest 3: Complex pipeline with jq -c:');
+{
+  const start = Date.now();
+
+  for await (const chunk of $`bun run js/examples/emulate-claude-stream.mjs | jq -c .`.stream()) {
+    if (chunk.type === 'stdout') {
+      const elapsed = Date.now() - start;
+      const lines = chunk.data.toString().trim().split('\n');
+      for (const line of lines) {
+        if (line) {
+          console.log(`  [${elapsed}ms] ${line}`);
+        }
+      }
+    }
+  }
+}
+
+console.log(
+  '\n✅ If timestamps show incremental times (not all the same), streaming is working!'
+);

package/js/examples/test-fix.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+async function testFix() {
+  console.log('🧪 Testing the stdin pipe fix');
+
+  const sortCmd = $`sort`;
+  console.log('1. Created sort command');
+
+  // Start with pipe stdin
+  const startPromise = sortCmd.start({
+    mode: 'async',
+    stdin: 'pipe',
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+
+  // Add timeout to avoid hanging
+  const timeoutPromise = new Promise((_, reject) => {
+    setTimeout(() => reject(new Error('Start timed out')), 2000);
+  });
+
+  try {
+    await Promise.race([startPromise, timeoutPromise]);
+    console.log('2. Started successfully');
+  } catch (error) {
+    console.log('2. Start timeout (process is waiting - good!)');
+  }
+
+  console.log('3. Checking child status:');
+  console.log('   started:', sortCmd.started);
+  console.log('   child exists:', !!sortCmd.child);
+  console.log('   finished:', sortCmd.finished);
+
+  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'
+    );
+  }
+
+  // Now test streams access
+  const stdinPromise = sortCmd.streams.stdin;
+  const stdinTimeout = new Promise((resolve) => {
+    setTimeout(() => resolve('TIMEOUT'), 1000);
+  });
+
+  const stdin = await Promise.race([stdinPromise, stdinTimeout]);
+  console.log('4. Got stdin:');
+  console.log('   result:', stdin === 'TIMEOUT' ? 'TIMEOUT' : typeof stdin);
+  console.log('   has write:', stdin && stdin.write ? 'YES' : 'NO');
+
+  if (stdin && stdin.write) {
+    console.log('5. SUCCESS! Writing to stdin...');
+    stdin.write('zebra\n');
+    stdin.write('apple\n');
+    stdin.end();
+
+    const result = await sortCmd;
+    console.log('   Sorted result:', JSON.stringify(result.stdout));
+  } else {
+    console.log('5. Cleaning up...');
+    sortCmd.kill();
+  }
+
+  console.log('Test complete');
+}
+
+testFix();

package/js/examples/test-incremental-streaming.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env bun
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Testing Incremental Streaming ===\n');
+
+// Test: Does output stream incrementally?
+console.log('Each line should appear with 500ms delay between them:\n');
+const start = Date.now();
+
+const cmd = $`sh -c 'echo "line1"; sleep 0.5; echo "line2"; sleep 0.5; echo "line3"'`;
+
+for await (const chunk of cmd.stream()) {
+  if (chunk.type === 'stdout') {
+    const elapsed = Date.now() - start;
+    const lines = chunk.data
+      .toString()
+      .trim()
+      .split('\n')
+      .filter((l) => l);
+    for (const line of lines) {
+      console.log(`[${elapsed}ms] ${line}`);
+    }
+  }
+}
+
+console.log('\n--- Now testing with pipe ---\n');
+
+const start2 = Date.now();
+const cmd2 = $`sh -c 'echo "line1"; sleep 0.5; echo "line2"; sleep 0.5; echo "line3"' | cat`;
+
+for await (const chunk of cmd2.stream()) {
+  if (chunk.type === 'stdout') {
+    const elapsed = Date.now() - start2;
+    const lines = chunk.data
+      .toString()
+      .trim()
+      .split('\n')
+      .filter((l) => l);
+    for (const line of lines) {
+      console.log(`[${elapsed}ms] ${line}`);
+    }
+  }
+}
+
+console.log('\n✅ Test complete');

package/js/examples/test-individual-spawn.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env bun
+
+// Test spawning processes individually and connecting them
+
+const proc1 = Bun.spawn(
+  ['bun', 'run', 'js/examples/emulate-claude-stream.mjs'],
+  {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  }
+);
+
+const proc2 = Bun.spawn(['jq', '.'], {
+  stdin: proc1.stdout,
+  stdout: 'pipe',
+  stderr: 'pipe',
+});
+
+console.log('Testing direct process pipe connection:');
+console.log('This SHOULD stream in real-time\n');
+
+const start = Date.now();
+
+// Read from jq's output
+for await (const chunk of proc2.stdout) {
+  const elapsed = Date.now() - start;
+  const text = Buffer.from(chunk).toString();
+  const lines = text.split('\n').filter((l) => l.trim());
+  for (const line of lines) {
+    console.log(`[${elapsed}ms] ${line}`);
+  }
+}
+
+await proc1.exited;
+await proc2.exited;