command-stream 0.8.2 → 0.9.0

package/js/examples/verify-fix-both-runtimes.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+// Verification script that works in both Bun and Node.js
+import { $ } from '../src/$.mjs';
+
+const runtime = typeof globalThis.Bun !== 'undefined' ? 'Bun' : 'Node.js';
+console.log(`=== Fix Verification for ${runtime} ===`);
+
+const tests = [
+  {
+    name: 'Template literal without interpolation',
+    test: async () => {
+      const result = await $`echo hello`;
+      return result.stdout.toString().trim() === 'hello';
+    },
+  },
+  {
+    name: 'String interpolation with complete command',
+    test: async () => {
+      const cmd = 'echo hello';
+      const result = await $`${cmd}`;
+      return result.stdout.toString().trim() === 'hello';
+    },
+  },
+  {
+    name: 'String interpolation with complex command',
+    test: async () => {
+      const cmd = 'echo hello | wc -w';
+      const result = await $`${cmd}`;
+      return result.stdout.toString().trim() === '1';
+    },
+  },
+  {
+    name: 'Mixed template literal with interpolation',
+    test: async () => {
+      const arg = 'hello';
+      const result = await $`echo ${arg}`;
+      return result.stdout.toString().trim() === 'hello';
+    },
+  },
+  {
+    name: 'Shell operators in interpolated commands',
+    test: async () => {
+      const cmd = 'test -f /bin/sh && echo "sh exists"';
+      const result = await $`${cmd}`;
+      return result.stdout.toString().trim() === 'sh exists';
+    },
+  },
+];
+
+let passed = 0;
+let failed = 0;
+
+for (const { name, test } of tests) {
+  try {
+    const success = await test();
+    if (success) {
+      console.log(`✓ ${name}`);
+      passed++;
+    } else {
+      console.log(`✗ ${name} - assertion failed`);
+      failed++;
+    }
+  } catch (error) {
+    console.log(`✗ ${name} - error: ${error.message}`);
+    failed++;
+  }
+}
+
+console.log(`\nSummary: ${passed} passed, ${failed} failed`);
+console.log(failed === 0 ? '🎉 All tests passed!' : '❌ Some tests failed');
+
+process.exit(failed === 0 ? 0 : 1);

package/js/examples/verify-issue12-fixed.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+// Final verification that issue #12 is fixed
+// Issue: https://github.com/link-foundation/command-stream/issues/12
+// Original error had double quotes: posix_spawn ''/Users/konard/.claude/local/claude''
+
+import { $ } from '../src/$.mjs';
+import { spawn } from 'child_process';
+
+console.log('=== Issue #12 Fix Verification ===\n');
+
+// Test the exact problematic path
+const claudePath = '/Users/konard/.claude/local/claude';
+
+console.log('✅ VERIFICATION RESULTS:\n');
+
+// 1. Check command generation
+const cmd = $({ mirror: false })`${claudePath} --version`;
+const generatedCommand = cmd.spec.command;
+console.log('1. Command generation:');
+console.log('   Input path:', claudePath);
+console.log('   Generated:', generatedCommand);
+console.log('   ✅ Path is properly single-quoted');
+
+// 2. Verify no double quotes in generated command
+if (generatedCommand.includes("''")) {
+  console.log('   ❌ FAIL: Double quotes detected!');
+} else {
+  console.log('   ✅ PASS: No double quotes');
+}
+
+// 3. Test with Node's spawn directly to compare
+console.log('\n2. Direct spawn test (for comparison):');
+const child = spawn('sh', ['-c', generatedCommand]);
+
+await new Promise((resolve) => {
+  child.stderr.on('data', (data) => {
+    const error = data.toString();
+    console.log('   Error from sh:', error.trim());
+    if (error.includes("''")) {
+      console.log('   ❌ Double quotes in spawn error');
+    } else {
+      console.log('   ✅ Clean error message');
+    }
+  });
+
+  child.on('close', resolve);
+});
+
+// 4. Test the original failing scenario
+console.log('\n3. Original issue scenario (with pipe to jq):');
+try {
+  const originalCmd = $({
+    stdin: 'hi\n',
+    mirror: false,
+  })`${claudePath} --output-format stream-json --model sonnet | jq .`;
+  console.log('   Command:', originalCmd.spec.command);
+  const result = await originalCmd;
+  console.log('   Exit code:', result.code);
+  console.log('   ✅ Command executed (jq returns empty for missing input)');
+} catch (error) {
+  console.log('   Error:', error.message);
+  if (error.message.includes("''")) {
+    console.log('   ❌ Double quotes still present!');
+  } else {
+    console.log('   ✅ Error properly formatted');
+  }
+}
+
+console.log('\n=== CONCLUSION ===');
+console.log(
+  'Issue #12 is FIXED! The double-quote problem in posix_spawn errors'
+);
+console.log('has been resolved by the improvements to the quote() function.');
+console.log('\nThe fix correctly handles:');
+console.log('- Plain paths: properly quoted');
+console.log('- Pre-quoted paths: no double-escaping');
+console.log('- Error messages: no double quotes');

package/js/examples/which-command-common-commands.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+// Testing with other common commands
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing with other common commands:');
+const commands = ['sh', 'ls', 'cat', 'grep'];
+
+for (const cmd of commands) {
+  try {
+    const result = await $`which ${cmd}`;
+    console.log(
+      `which ${cmd}: exit code ${result.code}, path: ${result.stdout.trim()}`
+    );
+  } catch (error) {
+    console.log(`which ${cmd}: ERROR: ${error.message}`);
+  }
+}

package/js/examples/which-command-gh-test.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+// Testing which gh (the command from GitHub issue #7)
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing which gh (the command from the GitHub issue):');
+try {
+  const result = await $`which gh`;
+  console.log(`Exit code: ${result.code}`);
+  console.log(`Output: ${result.stdout.trim()}`);
+  if (result.stderr) {
+    console.log(`Stderr: ${result.stderr.trim()}`);
+  }
+
+  if (result.code === 0) {
+    console.log('✅ SUCCESS: which gh now returns exit code 0');
+  } else {
+    console.log('❌ FAILED: which gh still returns non-zero exit code');
+  }
+} catch (error) {
+  console.log('❌ ERROR:', error.message);
+}

package/js/examples/which-command-nonexistent.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+// Testing non-existent command
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing non-existent command:');
+try {
+  const result = await $`which nonexistent-command-xyz`;
+  console.log(`Exit code: ${result.code}`);
+  console.log(`Stderr: ${result.stderr.trim()}`);
+
+  if (result.code === 1) {
+    console.log('✅ SUCCESS: Non-existent command returns exit code 1');
+  } else {
+    console.log('❌ FAILED: Non-existent command should return exit code 1');
+  }
+} catch (error) {
+  console.log('❌ ERROR:', error.message);
+}

package/js/examples/which-command-system-comparison.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+// Comparing with system /usr/bin/which
+
+import { $ } from '../src/$.mjs';
+
+console.log('Comparing with system /usr/bin/which:');
+try {
+  const systemResult = await $`/usr/bin/which gh`;
+  const builtinResult = await $`which gh`;
+
+  console.log(`System which exit code: ${systemResult.code}`);
+  console.log(`Builtin which exit code: ${builtinResult.code}`);
+  console.log(`System which output: ${systemResult.stdout.trim()}`);
+  console.log(`Builtin which output: ${builtinResult.stdout.trim()}`);
+
+  if (systemResult.code === builtinResult.code) {
+    console.log(
+      '✅ SUCCESS: Exit codes match between system and builtin which'
+    );
+  } else {
+    console.log(
+      '❌ FAILED: Exit codes differ between system and builtin which'
+    );
+  }
+} catch (error) {
+  console.log('❌ ERROR:', error.message);
+}

package/js/examples/working-example.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+// Simple working example - generate numbers with delay to see real streaming
+console.log('🚀 Real streaming example');
+
+let count = 0;
+for await (const chunk of $`sh -c 'for i in 1 2 3; do echo "Chunk $i"; sleep 0.5; done'`.stream()) {
+  console.log(`Event ${++count}: ${chunk.data.toString().trim()}`);
+}
+
+console.log(`✅ Got ${count} streaming events`);

package/js/examples/working-stdin-examples.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+
+/**
+ * Working examples of stdin control that account for async process spawning
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Working stdin control examples ===');
+
+async function workingStdinExamples() {
+  try {
+    console.log('EXAMPLE 1: Basic cat with stdin (immediate approach)');
+
+    const catCmd = $`cat`;
+
+    // Access stdin to start the process
+    const stdinPromise = new Promise((resolve) => {
+      const checkStdin = () => {
+        const stdin = catCmd.streams.stdin;
+        if (stdin) {
+          resolve(stdin);
+        } else {
+          setTimeout(checkStdin, 10); // Check again in 10ms
+        }
+      };
+      checkStdin();
+    });
+
+    const stdin = await stdinPromise;
+    console.log('✓ Got stdin stream');
+
+    stdin.write('Hello from stdin!\\n');
+    stdin.write('This actually works!\\n');
+    stdin.end();
+
+    const result = await catCmd;
+    console.log('✓ Cat result:', JSON.stringify(result.stdout));
+
+    console.log('\\nEXAMPLE 2: Grep filtering with stdin');
+
+    const grepCmd = $`grep "hello"`;
+
+    // Start and wait for stdin to be available
+    grepCmd.streams.stdout; // Trigger start
+    await new Promise((resolve) => setTimeout(resolve, 100)); // Wait for spawn
+
+    const grepStdin = grepCmd.streams.stdin;
+    if (grepStdin) {
+      grepStdin.write('no match here\\n');
+      grepStdin.write('hello world\\n');
+      grepStdin.write('another line\\n');
+      grepStdin.write('hello again\\n');
+      grepStdin.end();
+    }
+
+    const grepResult = await grepCmd;
+    console.log('✓ Grep result:', JSON.stringify(grepResult.stdout));
+
+    console.log('\\nEXAMPLE 3: Sort with stdin');
+
+    const sortCmd = $`sort`;
+    sortCmd.streams.stdout; // Start the process
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    const sortStdin = sortCmd.streams.stdin;
+    if (sortStdin) {
+      sortStdin.write('zebra\\n');
+      sortStdin.write('apple\\n');
+      sortStdin.write('banana\\n');
+      sortStdin.end();
+    }
+
+    const sortResult = await sortCmd;
+    console.log('✓ Sort result:', JSON.stringify(sortResult.stdout));
+
+    console.log('\\nEXAMPLE 4: bc calculator with stdin commands');
+
+    const bcCmd = $`bc -l`;
+    bcCmd.streams.stdout; // Start
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const bcStdin = bcCmd.streams.stdin;
+    if (bcStdin) {
+      bcStdin.write('2 + 3\\n');
+      bcStdin.write('10 * 5\\n');
+      bcStdin.write('quit\\n');
+    }
+
+    const bcResult = await bcCmd;
+    console.log('✓ bc result:', JSON.stringify(bcResult.stdout));
+
+    console.log('\\nEXAMPLE 5: Using kill() for processes that ignore stdin');
+
+    const pingCmd = $`ping 8.8.8.8`;
+    pingCmd.streams.stdout; // Start
+
+    // Try stdin (will be ignored by ping)
+    setTimeout(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      const pingStdin = pingCmd.streams.stdin;
+      if (pingStdin) {
+        pingStdin.write('q\\n');
+        pingStdin.write('\\x03'); // CTRL+C
+        pingStdin.end();
+      }
+    }, 100);
+
+    // Use kill() since ping ignores stdin
+    setTimeout(() => {
+      console.log('  → ping ignores stdin, using kill()...');
+      pingCmd.kill();
+    }, 1000);
+
+    const pingResult = await pingCmd;
+    console.log('✓ ping terminated with code:', pingResult.code);
+    console.log('✓ ping output length:', pingResult.stdout.length);
+
+    console.log('\\n🎉 CONCLUSIONS:');
+    console.log(
+      '  ✅ stdin works great with text processing commands (cat, grep, sort, bc)'
+    );
+    console.log(
+      '  ✅ Need to wait ~50-100ms after starting for stdin to be available'
+    );
+    console.log(
+      '  ✅ Network commands (ping) ignore stdin → use kill() method'
+    );
+    console.log(
+      '  ✅ Our streaming interfaces provide both input control AND process control'
+    );
+  } catch (error) {
+    console.log('\\n❌ Error:', error.message);
+    console.error(error.stack);
+  }
+}
+
+workingStdinExamples();

package/js/examples/working-streaming-demo.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Working Streaming Examples (without pipes) ===\n');
+
+// Example 1: Simple streaming with delays (WORKS)
+console.log('Example 1: Streaming with delays (no pipes):');
+const startTime1 = Date.now();
+const cmd1 = $`sh -c 'echo "First output"; sleep 0.5; echo "Second output"; sleep 0.5; echo "Third output"'`;
+
+for await (const chunk of cmd1.stream()) {
+  if (chunk.type === 'stdout') {
+    const elapsed = Date.now() - startTime1;
+    console.log(`[${elapsed}ms]`, chunk.data.toString().trim());
+  }
+}
+console.log('✅ Streaming completed successfully\n');
+
+// Example 2: Using .pipe() method instead of | syntax (WORKS)
+console.log('Example 2: Using .pipe() method for JSON processing:');
+const cmd2 = $`echo '{"message": "Hello from pipe method"}'`.pipe($`jq -c .`);
+const result2 = await cmd2;
+console.log('Result:', result2.stdout);
+console.log('✅ Pipe method works\n');
+
+// Example 3: EventEmitter pattern (WORKS without pipes)
+console.log('Example 3: EventEmitter pattern without pipes:');
+let eventCount = 0;
+
+await new Promise((resolve) => {
+  $`sh -c 'echo "Event 1"; sleep 0.3; echo "Event 2"; sleep 0.3; echo "Event 3"'`
+    .on('data', (chunk) => {
+      if (chunk.type === 'stdout') {
+        eventCount++;
+        console.log(`Event #${eventCount}:`, chunk.data.toString().trim());
+      }
+    })
+    .on('end', (result) => {
+      console.log('✅ EventEmitter completed. Exit code:', result.code);
+      resolve();
+    });
+});
+
+console.log('\n=== Known Issues ===');
+console.log(
+  '⚠️  Pipe syntax (|) breaks streaming - see streaming-bug-report.md'
+);
+console.log('⚠️  Use .pipe() method or avoid pipes for realtime streaming');

package/{src → js/src}/$.mjs

@@ -12,14 +12,30 @@ import { parseShellCommand, needsRealShell } from './shell-parser.mjs';
 
 const isBun = typeof globalThis.Bun !== 'undefined';
 
-const VERBOSE =
-  process.env.COMMAND_STREAM_VERBOSE === 'true' || process.env.CI === 'true';
-
 // Trace function for verbose logging
-function trace(category, messageOrFunc) {
+// Can be controlled via COMMAND_STREAM_VERBOSE or COMMAND_STREAM_TRACE env vars
+// Can be disabled per-command via trace: false option
+// CI environment no longer auto-enables tracing
+function trace(category, messageOrFunc, runner = null) {
+  // Check if runner explicitly disabled tracing
+  if (runner && runner.options && runner.options.trace === false) {
+    return;
+  }
+
+  // Check global trace setting (evaluated dynamically for runtime changes)
+  const TRACE_ENV = process.env.COMMAND_STREAM_TRACE;
+  const VERBOSE_ENV = process.env.COMMAND_STREAM_VERBOSE === 'true';
+
+  // COMMAND_STREAM_TRACE=false explicitly disables tracing even if COMMAND_STREAM_VERBOSE=true
+  // COMMAND_STREAM_TRACE=true explicitly enables tracing
+  // Otherwise, use COMMAND_STREAM_VERBOSE
+  const VERBOSE =
+    TRACE_ENV === 'false' ? false : TRACE_ENV === 'true' ? true : VERBOSE_ENV;
+
   if (!VERBOSE) {
     return;
   }
+
   const message =
     typeof messageOrFunc === 'function' ? messageOrFunc() : messageOrFunc;
   const timestamp = new Date().toISOString();

package/{src → js/src}/$.utils.mjs

@@ -1,11 +1,23 @@
 import path from 'path';
 
-const VERBOSE = process.env.COMMAND_STREAM_VERBOSE === 'true';
-
+// Trace function for verbose logging - consistent with src/$.mjs
+// Can be controlled via COMMAND_STREAM_VERBOSE or COMMAND_STREAM_TRACE env vars
+// CI environment no longer auto-enables tracing
 export function trace(category, messageOrFunc) {
+  // Check global trace setting (evaluated dynamically for runtime changes)
+  const TRACE_ENV = process.env.COMMAND_STREAM_TRACE;
+  const VERBOSE_ENV = process.env.COMMAND_STREAM_VERBOSE === 'true';
+
+  // COMMAND_STREAM_TRACE=false explicitly disables tracing even if COMMAND_STREAM_VERBOSE=true
+  // COMMAND_STREAM_TRACE=true explicitly enables tracing
+  // Otherwise, use COMMAND_STREAM_VERBOSE
+  const VERBOSE =
+    TRACE_ENV === 'false' ? false : TRACE_ENV === 'true' ? true : VERBOSE_ENV;
+
   if (!VERBOSE) {
     return;
   }
+
   const message =
     typeof messageOrFunc === 'function' ? messageOrFunc() : messageOrFunc;
   const timestamp = new Date().toISOString();