command-stream 0.8.2 → 0.9.0

package/js/examples/prove-ping-stdin-limitation.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+/**
+ * Proof that ping cannot be controlled via stdin - you need kill() method
+ */
+
+import { spawn } from 'child_process';
+import { $ } from '../src/$.mjs';
+
+console.log('=== PROOF: ping ignores stdin, needs kill() method ===');
+console.log('');
+
+async function proveStdinLimitation() {
+  console.log('DEMONSTRATION 1: Native child_process with ping');
+  console.log('→ Sending CTRL+C via stdin (will be ignored by ping)');
+
+  const child = spawn('ping', ['8.8.8.8']);
+  let output = '';
+
+  child.stdout.on('data', (data) => {
+    output += data.toString();
+    process.stdout.write(`  [ping] ${data}`);
+  });
+
+  // Try to send CTRL+C after 1.5 seconds
+  setTimeout(() => {
+    console.log('  → Sending \\x03 (CTRL+C) to stdin...');
+    child.stdin.write('\\x03');
+    child.stdin.write('quit\\n');
+    child.stdin.write('exit\\n');
+    child.stdin.end();
+    console.log('  → stdin closed, but ping continues running...');
+  }, 1500);
+
+  // Force kill after 3 seconds to prove stdin didn't work
+  setTimeout(() => {
+    console.log('  → stdin failed, using kill() to terminate...');
+    child.kill('SIGTERM');
+  }, 3000);
+
+  await new Promise((resolve) => child.on('close', resolve));
+  console.log('  ✓ Native ping required kill() signal to stop');
+  console.log('');
+
+  console.log('DEMONSTRATION 2: command-stream with proper kill() method');
+  const cmd = $`ping 8.8.8.8`;
+
+  // Start by accessing stdout
+  cmd.streams.stdout.on('data', (data) => {
+    process.stdout.write(`  [stream] ${data}`);
+  });
+
+  // Kill cleanly after 2 seconds
+  setTimeout(() => {
+    console.log('  → Using command-stream kill() method...');
+    cmd.kill();
+  }, 2000);
+
+  const result = await cmd;
+  console.log(
+    `  ✓ command-stream ping cleanly terminated with code: ${result.code}`
+  );
+  console.log('');
+
+  console.log('DEMONSTRATION 3: stdin DOES work for commands that read it');
+  console.log('→ Testing with cat command');
+
+  const catCmd = $`cat`;
+  const stdin = catCmd.streams.stdin;
+
+  if (stdin) {
+    stdin.write('This data goes to cat via stdin\\n');
+    stdin.write('And cat will output it\\n');
+    stdin.end();
+  }
+
+  const catResult = await catCmd;
+  console.log('  ✓ cat output:', JSON.stringify(catResult.stdout));
+  console.log('');
+
+  console.log('📋 SUMMARY:');
+  console.log(
+    '  • ping ignores stdin completely (network utility, not interactive)'
+  );
+  console.log('  • To interrupt ping, you MUST use kill() method or signals');
+  console.log(
+    '  • stdin works fine for commands that actually read it (cat, grep, etc.)'
+  );
+  console.log(
+    '  • command-stream provides both: streams.stdin AND kill() method'
+  );
+}
+
+proveStdinLimitation().catch(console.error);

package/js/examples/readme-example.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+import { $, register } from '../src/$.mjs';
+
+// Register a custom virtual command with the new object-based signature
+register('greet', async ({ stdin }) => ({
+  stdout: `Hello, ${stdin.trim()}!\n`,
+  code: 0,
+}));
+
+// Example usage: echo "World" | greet
+console.log('Running: echo "World" | greet');
+const result = await $`echo "World"`.pipe($`greet`);
+console.log('Result:', result.stdout.trim());
+
+// Example with args
+register('greet-formal', async ({ args, stdin }) => {
+  const title = args[0] || '';
+  return { stdout: `Hello, ${title} ${stdin.trim()}!\n`, code: 0 };
+});
+
+console.log('\nRunning: echo "Smith" | greet-formal Mr.');
+const result2 = await $`echo "Smith"`.pipe($`greet-formal Mr.`);
+console.log('Result:', result2.stdout.trim());
+
+// Example accessing other options
+register('debug', async ({ args, stdin, options }) => {
+  const info = {
+    args,
+    stdinLength: stdin ? stdin.length : 0,
+    mirror: options.mirror,
+    capture: options.capture,
+  };
+  return { stdout: `${JSON.stringify(info, null, 2)}\n`, code: 0 };
+});
+
+console.log('\nRunning: echo "test input" | debug arg1 arg2');
+const result3 = await $`echo "test input"`.pipe($`debug arg1 arg2`);
+console.log('Result:', result3.stdout.trim());

package/js/examples/realtime-json-stream.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Realtime JSON Streaming Demo ===\n');
+console.log(
+  'This demo shows that jq processes and outputs JSON objects immediately'
+);
+console.log('as they arrive, not waiting for the entire stream to complete.\n');
+console.log(
+  'Watch the timestamps - each JSON object appears immediately after being generated!\n'
+);
+console.log('---\n');
+
+// Example 1: Simple realtime streaming with visible delays
+console.log(
+  'Example 1: Streaming with 1-second delays between each JSON object:'
+);
+console.log('Starting at:', new Date().toISOString());
+console.log('');
+
+const cmd1 = $`sh -c 'echo "{\\"event\\":\\"start\\",\\"time\\":\\"$(date +%H:%M:%S)\\"}"; sleep 1; echo "{\\"event\\":\\"middle\\",\\"time\\":\\"$(date +%H:%M:%S)\\"}"; sleep 1; echo "{\\"event\\":\\"end\\",\\"time\\":\\"$(date +%H:%M:%S)\\"}"' | jq -c .`;
+
+for await (const chunk of cmd1.stream()) {
+  if (chunk.type === 'stdout') {
+    const timestamp = new Date().toISOString();
+    process.stdout.write(`[${timestamp}] Received: ${chunk.data.toString()}`);
+  }
+}
+
+console.log('\n---\n');
+
+// Example 2: Processing server logs in realtime
+console.log('Example 2: Simulating realtime server logs with filtering:');
+console.log('(Only showing ERROR and WARN levels)\n');
+
+const serverLogs = $`sh -c '
+  echo "{\\"level\\":\\"INFO\\",\\"msg\\":\\"Server starting\\",\\"time\\":\\"$(date +%H:%M:%S)\\"}";
+  sleep 0.5;
+  echo "{\\"level\\":\\"ERROR\\",\\"msg\\":\\"Database connection failed\\",\\"time\\":\\"$(date +%H:%M:%S)\\"}";
+  sleep 0.5;
+  echo "{\\"level\\":\\"INFO\\",\\"msg\\":\\"Retrying connection\\",\\"time\\":\\"$(date +%H:%M:%S)\\"}";
+  sleep 0.5;
+  echo "{\\"level\\":\\"WARN\\",\\"msg\\":\\"High memory usage\\",\\"time\\":\\"$(date +%H:%M:%S)\\"}";
+  sleep 0.5;
+  echo "{\\"level\\":\\"INFO\\",\\"msg\\":\\"Connection restored\\",\\"time\\":\\"$(date +%H:%M:%S)\\"}";
+' | jq -c 'select(.level == "ERROR" or .level == "WARN")'`;
+
+let buffer = '';
+for await (const chunk of serverLogs.stream()) {
+  if (chunk.type === 'stdout') {
+    buffer += chunk.data.toString();
+    const lines = buffer.split('\n');
+    buffer = lines.pop() || ''; // Keep incomplete line in buffer
+
+    for (const line of lines) {
+      if (line.trim()) {
+        try {
+          const timestamp = new Date().toISOString();
+          const log = JSON.parse(line.trim());
+          console.log(
+            `[${timestamp}] ${log.level}: ${log.msg} (generated at ${log.time})`
+          );
+        } catch (e) {
+          console.log('Failed to parse:', line);
+        }
+      }
+    }
+  }
+}
+
+console.log('\n---\n');
+
+// Example 3: Streaming metrics with transformation
+console.log('Example 3: Streaming metrics with realtime transformation:');
+console.log('(Adding status based on CPU value)\n');
+
+const metrics = $`sh -c '
+  for i in 1 2 3 4 5; do
+    cpu=$((45 + RANDOM % 40));
+    echo "{\\"metric\\":\\"cpu\\",\\"value\\":$cpu,\\"host\\":\\"server-$i\\",\\"time\\":\\"$(date +%H:%M:%S.%N | cut -b1-12)\\"}";
+    sleep 0.3;
+  done
+' | jq -c '{metric, value, host, time, status: (if .value > 70 then "critical" elif .value > 50 then "warning" else "normal" end)}'`;
+
+console.log('Monitoring CPU metrics (updates every 0.3 seconds):');
+let metricsBuffer = '';
+for await (const chunk of metrics.stream()) {
+  if (chunk.type === 'stdout') {
+    metricsBuffer += chunk.data.toString();
+    const lines = metricsBuffer.split('\n');
+    metricsBuffer = lines.pop() || '';
+
+    for (const line of lines) {
+      if (line.trim()) {
+        try {
+          const timestamp = new Date().toISOString();
+          const metric = JSON.parse(line.trim());
+          const statusIcon =
+            metric.status === 'critical'
+              ? '🔴'
+              : metric.status === 'warning'
+                ? '🟡'
+                : '🟢';
+          console.log(
+            `[${timestamp}] ${statusIcon} ${metric.host}: CPU ${metric.value}% - ${metric.status}`
+          );
+        } catch (e) {
+          console.log('Failed to parse metric:', line);
+        }
+      }
+    }
+  }
+}
+
+console.log('\n---\n');
+
+// Example 4: Using EventEmitter pattern for realtime processing
+console.log('Example 4: Using EventEmitter pattern for realtime JSON stream:');
+console.log('(Shows different ways to handle streaming)\n');
+
+const eventCmd = $`sh -c '
+  for i in 1 2 3; do
+    echo "{\\"id\\":$i,\\"data\\":\\"Message $i\\",\\"timestamp\\":$(date +%s)}";
+    sleep 0.7;
+  done
+' | jq -c .`;
+
+let eventCount = 0;
+eventCmd
+  .on('data', (chunk) => {
+    eventCount++;
+    const timestamp = new Date().toISOString();
+    console.log(
+      `[${timestamp}] Event #${eventCount}: ${chunk.toString().trim()}`
+    );
+  })
+  .on('end', (result) => {
+    console.log(`\nStream completed. Total events: ${eventCount}`);
+    console.log('Final result code:', result.code);
+
+    console.log('\n=== Demo Complete ===');
+  });

package/js/examples/reliable-stdin-commands.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Most reliable stdin commands ===');
+
+async function reliableStdinCommands() {
+  try {
+    console.log('\\n1️⃣ cat (classic stdin reader)');
+    const catCmd = $`cat`;
+    const catStdin = await catCmd.streams.stdin;
+    console.log(
+      '  stdin type:',
+      typeof catStdin,
+      'has write?',
+      !!(catStdin && catStdin.write)
+    );
+
+    if (catStdin && catStdin.write) {
+      catStdin.write('Hello cat!\\n');
+      catStdin.write('Second line\\n');
+      catStdin.end();
+      console.log('  ✅ Wrote data to cat');
+    } else {
+      console.log('  ❌ No writable stdin');
+    }
+
+    const catResult = await catCmd;
+    console.log('  📤 Result:', JSON.stringify(catResult.stdout));
+
+    console.log('\\n2️⃣ sort (sorts stdin lines)');
+    const sortCmd = $`sort`;
+    const sortStdin = await sortCmd.streams.stdin;
+    console.log(
+      '  stdin type:',
+      typeof sortStdin,
+      'has write?',
+      !!(sortStdin && sortStdin.write)
+    );
+
+    if (sortStdin && sortStdin.write) {
+      sortStdin.write('zebra\\n');
+      sortStdin.write('apple\\n');
+      sortStdin.write('banana\\n');
+      sortStdin.end();
+      console.log('  ✅ Wrote data to sort');
+    } else {
+      console.log('  ❌ No writable stdin');
+    }
+
+    const sortResult = await sortCmd;
+    console.log('  📤 Result:', JSON.stringify(sortResult.stdout));
+
+    console.log('\\n3️⃣ wc -l (counts lines from stdin)');
+    const wcCmd = $`wc -l`;
+    const wcStdin = await wcCmd.streams.stdin;
+    console.log(
+      '  stdin type:',
+      typeof wcStdin,
+      'has write?',
+      !!(wcStdin && wcStdin.write)
+    );
+
+    if (wcStdin && wcStdin.write) {
+      wcStdin.write('line 1\\n');
+      wcStdin.write('line 2\\n');
+      wcStdin.write('line 3\\n');
+      wcStdin.end();
+      console.log('  ✅ Wrote data to wc');
+    } else {
+      console.log('  ❌ No writable stdin');
+    }
+
+    const wcResult = await wcCmd;
+    console.log('  📤 Result:', JSON.stringify(wcResult.stdout.trim()));
+
+    console.log('\\n4️⃣ tr (transforms text from stdin)');
+    const trCmd = $`tr 'a-z' 'A-Z'`;
+    const trStdin = await trCmd.streams.stdin;
+    console.log(
+      '  stdin type:',
+      typeof trStdin,
+      'has write?',
+      !!(trStdin && trStdin.write)
+    );
+
+    if (trStdin && trStdin.write) {
+      trStdin.write('hello world\\n');
+      trStdin.write('transform this\\n');
+      trStdin.end();
+      console.log('  ✅ Wrote data to tr');
+    } else {
+      console.log('  ❌ No writable stdin');
+    }
+
+    const trResult = await trCmd;
+    console.log('  📤 Result:', JSON.stringify(trResult.stdout));
+
+    console.log('\\n5️⃣ grep (filters stdin)');
+    const grepCmd = $`grep "test"`;
+    const grepStdin = await grepCmd.streams.stdin;
+    console.log(
+      '  stdin type:',
+      typeof grepStdin,
+      'has write?',
+      !!(grepStdin && grepStdin.write)
+    );
+
+    if (grepStdin && grepStdin.write) {
+      grepStdin.write('no match here\\n');
+      grepStdin.write('this is a test line\\n');
+      grepStdin.write('skip this\\n');
+      grepStdin.write('another test\\n');
+      grepStdin.end();
+      console.log('  ✅ Wrote data to grep');
+    } else {
+      console.log('  ❌ No writable stdin');
+    }
+
+    const grepResult = await grepCmd;
+    console.log('  📤 Result:', JSON.stringify(grepResult.stdout));
+
+    console.log('\\n📊 SUMMARY:');
+    console.log('  The most reliable commands for stdin testing:');
+    console.log(
+      '  ✅ cat, sort, wc, tr, grep - all read from stdin by default'
+    );
+    console.log('  ✅ These never exit until stdin is closed');
+    console.log('  ✅ Perfect for demonstrating streams.stdin control');
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+reliableStdinCommands();

package/js/examples/reproduce-issue-135-v2.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// Reproducing issue #135: Trace logs interfere with output when CI=true
+// This test sets CI=true BEFORE importing the module
+
+process.env.CI = 'true';
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Test with CI=true set BEFORE import ===');
+const $silent = $({ mirror: false, capture: true });
+const result = await $silent`echo '{"status":"ok"}'`;
+console.log('Output:', result.stdout || result);
+console.log(
+  '\n=== Expected: Should be just {"status":"ok"} without trace logs ==='
+);

package/js/examples/reproduce-issue-135.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// Reproducing issue #135: Trace logs interfere with output when CI=true
+
+import { $ } from '../src/$.mjs';
+
+const $silent = $({ mirror: false, capture: true });
+
+console.log('=== Test 1: Without CI environment ===');
+const result1 = await $silent`echo '{"status":"ok"}'`;
+console.log('Output:', result1.stdout || result1);
+
+console.log('\n=== Test 2: With CI=true environment ===');
+process.env.CI = 'true';
+const result2 = await $silent`echo '{"status":"ok"}'`;
+console.log('Output:', result2.stdout || result2);
+
+console.log('\n=== Expected: Both outputs should be just {"status":"ok"} ===');

package/js/examples/shell-cd-behavior.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+// This file documents how cd SHOULD behave to match shell behavior
+
+import { $, shell, enableVirtualCommands } from '../src/$.mjs';
+
+enableVirtualCommands();
+shell.verbose(false);
+
+console.log('=== Expected Shell cd Behavior ===\n');
+
+async function testShellBehavior() {
+  const originalCwd = process.cwd();
+
+  console.log(
+    '1. cd should persist for subsequent commands in the same session:'
+  );
+  console.log('   $ cd /tmp');
+  console.log('   $ pwd');
+  console.log('   Expected: /tmp');
+
+  // In a real shell, this would work:
+  await $`cd /tmp`;
+  const pwd1 = await $`pwd`;
+  console.log('   Actual:', pwd1.stdout.trim());
+  console.log('   Status:', pwd1.stdout.trim() === '/tmp' ? '✓' : '✗');
+
+  console.log(
+    '\n2. cd in command chain should affect all commands in the chain:'
+  );
+  console.log('   $ cd /usr && pwd');
+  console.log('   Expected: /usr');
+
+  const result2 = await $`cd /usr && pwd`;
+  console.log('   Actual:', result2.stdout.trim());
+  console.log('   Status:', result2.stdout.trim() === '/usr' ? '✓' : '✗');
+
+  console.log('\n3. After chain, directory should still be changed:');
+  console.log('   $ pwd');
+  console.log('   Expected: /usr (from previous cd)');
+
+  const pwd3 = await $`pwd`;
+  console.log('   Actual:', pwd3.stdout.trim());
+  console.log('   Status:', pwd3.stdout.trim() === '/usr' ? '✓' : '✗');
+
+  console.log('\n4. Subshell () should NOT affect parent shell:');
+  console.log('   $ (cd /tmp && pwd)');
+  console.log('   $ pwd');
+  console.log('   Expected: still /usr');
+
+  await $`(cd /tmp && pwd)`;
+  const pwd4 = await $`pwd`;
+  console.log('   Actual after subshell:', pwd4.stdout.trim());
+  console.log('   Status:', pwd4.stdout.trim() === '/usr' ? '✓' : '✗');
+
+  console.log('\n5. Multiple cd commands should work sequentially:');
+  console.log('   $ cd /var');
+  console.log('   $ cd log');
+  console.log('   $ pwd');
+  console.log('   Expected: /var/log');
+
+  await $`cd /var`;
+  await $`cd log`;
+  const pwd5 = await $`pwd`;
+  console.log('   Actual:', pwd5.stdout.trim());
+  console.log('   Status:', pwd5.stdout.trim() === '/var/log' ? '✓' : '✗');
+
+  console.log('\n6. cd with relative paths:');
+  console.log('   $ cd ..');
+  console.log('   $ pwd');
+  console.log('   Expected: /var');
+
+  await $`cd ..`;
+  const pwd6 = await $`pwd`;
+  console.log('   Actual:', pwd6.stdout.trim());
+  console.log('   Status:', pwd6.stdout.trim() === '/var' ? '✓' : '✗');
+
+  // Return to original directory
+  process.chdir(originalCwd);
+
+  console.log('\n=== Test Complete ===');
+  console.log('Note: This shows the expected shell behavior.');
+  console.log('The virtual cd command needs to maintain directory state');
+  console.log('across commands in the same $ session, but isolate');
+  console.log('subshells created with ().');
+}
+
+testShellBehavior().catch(console.error);

package/js/examples/sigint-forwarding-test.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// Test SIGINT forwarding to child processes
+// This runs in a subprocess to avoid killing the test runner
+
+import { $ } from '../src/$.mjs';
+
+process.env.COMMAND_STREAM_VERBOSE = 'true';
+
+console.log('TEST: Starting SIGINT forwarding test');
+
+// Test that SIGINT is forwarded to child processes
+console.log('TEST: Starting long-running command');
+const runner = $`sleep 30`;
+const promise = runner.start();
+
+// Set up a handler to catch SIGINT but don't let it kill the process
+let sigintReceived = false;
+process.on('SIGINT', () => {
+  console.log('RESULT: parent_received_sigint=true');
+  sigintReceived = true;
+  // Don't exit - we want to continue the test
+});
+
+// Wait a bit for command to start
+await new Promise((resolve) => setTimeout(resolve, 100));
+
+// Send SIGINT to ourselves
+console.log('TEST: Sending SIGINT');
+process.kill(process.pid, 'SIGINT');
+
+// Wait a bit for signal handling
+await new Promise((resolve) => setTimeout(resolve, 200));
+
+// Check if process was killed
+let exitCode = null;
+try {
+  // Try to wait for the promise with a timeout
+  await Promise.race([
+    promise.then((result) => {
+      exitCode = result.code;
+    }),
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('timeout')), 500)
+    ),
+  ]);
+} catch (e) {
+  if (e.message === 'timeout') {
+    console.log('RESULT: command_still_running=true');
+  } else {
+    console.log(`RESULT: command_exit_code=${exitCode ?? 'error'}`);
+  }
+}
+
+console.log(`RESULT: sigint_received=${sigintReceived}`);
+
+// Clean up
+runner.kill();
+
+console.log('TEST: Complete');
+process.exit(0);

package/js/examples/sigint-handler-test.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// Test script to verify SIGINT handler cleanup
+// This runs in a subprocess to avoid interfering with the test runner
+
+import { $ } from '../src/$.mjs';
+
+process.env.COMMAND_STREAM_VERBOSE = 'true';
+
+console.log('TEST: Starting SIGINT handler test');
+
+// Test 1: Verify handler is installed when command starts
+console.log('TEST: Check initial state');
+const initialListeners = process.listeners('SIGINT').length;
+console.log(`RESULT: initial_listeners=${initialListeners}`);
+
+// Start a command
+console.log('TEST: Starting command');
+const runner = $`sleep 0.1`;
+const promise = runner.start();
+
+// Check handler was installed
+const duringListeners = process.listeners('SIGINT').length;
+console.log(`RESULT: during_listeners=${duringListeners}`);
+
+// Wait for completion
+await promise;
+
+// Check handler was removed
+const afterListeners = process.listeners('SIGINT').length;
+console.log(`RESULT: after_listeners=${afterListeners}`);
+
+// Test 2: Multiple concurrent commands share single handler
+console.log('TEST: Starting multiple concurrent commands');
+const promises = [$`sleep 0.05`, $`sleep 0.05`, $`sleep 0.05`];
+
+const starts = promises.map((p) => p.start());
+const concurrentListeners = process.listeners('SIGINT').length;
+console.log(`RESULT: concurrent_listeners=${concurrentListeners}`);
+
+await Promise.all(starts);
+const afterConcurrentListeners = process.listeners('SIGINT').length;
+console.log(`RESULT: after_concurrent_listeners=${afterConcurrentListeners}`);
+
+// Test 3: Handler removed on error
+console.log('TEST: Testing error handling');
+try {
+  await $`exit 1`;
+} catch (e) {
+  // Expected
+}
+
+const afterErrorListeners = process.listeners('SIGINT').length;
+console.log(`RESULT: after_error_listeners=${afterErrorListeners}`);
+
+// Test 4: Handler removed when command is killed
+console.log('TEST: Testing kill cleanup');
+const killRunner = $`sleep 10`;
+const killPromise = killRunner.start();
+
+setTimeout(() => killRunner.kill(), 10);
+
+try {
+  await killPromise;
+} catch (e) {
+  // Expected
+}
+
+const afterKillListeners = process.listeners('SIGINT').length;
+console.log(`RESULT: after_kill_listeners=${afterKillListeners}`);
+
+console.log('TEST: Complete');
+process.exit(0);