command-stream 0.8.2 → 0.9.0

package/js/examples/cleanup-verification-test.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// Test comprehensive resource cleanup
+// This runs in a subprocess for isolation
+
+import { $ } from '../src/$.mjs';
+
+process.env.COMMAND_STREAM_VERBOSE = 'true';
+
+console.log('TEST: Starting cleanup verification');
+
+// Test 1: Virtual command cleanup
+console.log('TEST: Virtual command cleanup');
+const v1 = $`echo "test1"`;
+await v1;
+console.log(`RESULT: virtual_finished=${v1.finished}`);
+
+// Test 2: Real process cleanup
+console.log('TEST: Real process cleanup');
+const r1 = $`/bin/echo "test2"`;
+await r1;
+console.log(`RESULT: real_finished=${r1.finished}`);
+
+// Test 3: Error cleanup
+console.log('TEST: Error cleanup');
+const e1 = $`exit 1`;
+try {
+  await e1;
+} catch (e) {
+  // Expected
+}
+console.log(`RESULT: error_finished=${e1.finished}`);
+
+// Test 4: Kill cleanup
+console.log('TEST: Kill cleanup');
+const k1 = $`sleep 10`;
+const kp = k1.start();
+setTimeout(() => k1.kill(), 10);
+try {
+  await kp;
+} catch (e) {
+  // Expected
+}
+console.log(`RESULT: kill_finished=${k1.finished}`);
+
+// Test 5: Pipeline cleanup
+console.log('TEST: Pipeline cleanup');
+const p1 = await $`echo "test" | /bin/cat | /bin/cat`;
+console.log(
+  `RESULT: pipeline_output=${p1.stdout ? p1.stdout.trim() : 'no_output'}`
+);
+
+// Test 6: Event listener cleanup
+console.log('TEST: Event listener cleanup');
+const ev1 = $`echo "test"`;
+ev1.on('data', () => {});
+ev1.on('end', () => {});
+await ev1;
+console.log(`RESULT: event_listeners_size=${ev1.listeners.size}`);
+
+// Test 7: Concurrent command cleanup
+console.log('TEST: Concurrent command cleanup');
+const concurrent = [$`echo "c1"`, $`echo "c2"`, $`echo "c3"`];
+await Promise.all(concurrent);
+console.log(
+  `RESULT: concurrent_finished=${concurrent.every((c) => c.finished)}`
+);
+
+// Test 8: Not awaited cleanup
+console.log('TEST: Not awaited cleanup');
+const na1 = $`echo "not awaited"`;
+na1.start(); // Start but don't await
+await new Promise((resolve) => setTimeout(resolve, 100));
+console.log(`RESULT: not_awaited_finished=${na1.finished}`);
+
+// Test 9: Stream iterator break cleanup
+console.log('TEST: Stream iterator break cleanup');
+const si1 = $`for i in 1 2 3; do echo $i; sleep 0.01; done`;
+let iterations = 0;
+for await (const chunk of si1.stream()) {
+  iterations++;
+  if (iterations >= 2) {
+    break;
+  }
+}
+console.log(`RESULT: stream_iterator_finished=${si1.finished}`);
+
+// Test 10: AbortController cleanup
+console.log('TEST: AbortController cleanup');
+const ac1 = $`sleep 10`;
+const acp = ac1.start();
+const hadController = ac1._abortController !== null;
+ac1.kill();
+try {
+  await acp;
+} catch (e) {
+  // Expected
+}
+console.log(`RESULT: had_abort_controller=${hadController}`);
+console.log(
+  `RESULT: abort_controller_cleaned=${ac1._abortController === null}`
+);
+
+// Final check: No lingering SIGINT handlers
+const finalListeners = process.listeners('SIGINT').filter((l) => {
+  const str = l.toString();
+  return (
+    str.includes('activeProcessRunners') ||
+    str.includes('ProcessRunner') ||
+    str.includes('activeChildren')
+  );
+});
+console.log(`RESULT: final_sigint_handlers=${finalListeners.length}`);
+
+console.log('TEST: Complete');
+process.exit(0);

package/js/examples/colors-buffer-processing.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+// Using AnsiUtils.cleanForProcessing() for Buffer data
+
+import { $, AnsiUtils } from '../src/$.mjs';
+
+console.log('Using AnsiUtils.cleanForProcessing() for Buffer data:');
+const colorCommand =
+  'printf "\\033[31mRed text\\033[0m \\033[32mGreen text\\033[0m \\033[34mBlue text\\033[0m\\n"';
+
+const result = await $`sh -c ${colorCommand}`;
+const buffer = Buffer.from(result.stdout);
+const cleanBuffer = AnsiUtils.cleanForProcessing(buffer);
+console.log(`Clean buffer: "${cleanBuffer.toString().trim()}"`);

package/js/examples/colors-default-preserved.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+// Default behavior (ANSI colors preserved)
+
+import { $ } from '../src/$.mjs';
+
+console.log('Default behavior (ANSI colors preserved):');
+const colorCommand =
+  'printf "\\033[31mRed text\\033[0m \\033[32mGreen text\\033[0m \\033[34mBlue text\\033[0m\\n"';
+
+const result = await $`sh -c ${colorCommand}`;
+console.log('Visual output:');
+process.stdout.write(result.stdout); // Show actual colors
+console.log('Raw string representation:');
+console.log(`"${result.stdout.replace(/\x1b/g, '\\x1b')}"`);

package/js/examples/colors-per-command-config.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+// Per-command ANSI configuration
+
+import { $ } from '../src/$.mjs';
+
+console.log('Per-command ANSI configuration:');
+const colorCommand =
+  'printf "\\033[31mRed text\\033[0m \\033[32mGreen text\\033[0m \\033[34mBlue text\\033[0m\\n"';
+
+// Test with the process runner's ansi option
+const proc = $`sh -c ${colorCommand}`;
+proc.options.ansi = { preserveAnsi: false };
+const result = await proc;
+console.log(`Output with ANSI disabled: "${result.stdout.trim()}"`);

package/js/examples/colors-strip-ansi.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+// Using AnsiUtils.stripAnsi() for clean data processing
+
+import { $, AnsiUtils } from '../src/$.mjs';
+
+console.log('Using AnsiUtils.stripAnsi() for clean data processing:');
+const colorCommand =
+  'printf "\\033[31mRed text\\033[0m \\033[32mGreen text\\033[0m \\033[34mBlue text\\033[0m\\n"';
+
+const result = await $`sh -c ${colorCommand}`;
+const stripped = AnsiUtils.stripAnsi(result.stdout);
+console.log(`Stripped: "${stripped.trim()}"`);

package/js/examples/commandstream-jq.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+import { appendFileSync } from 'fs';
+
+console.log('🤖 Command-stream: Claude → jq pipeline');
+
+let chunkCount = 0;
+const logFile = 'claude-jq-output.log';
+
+const command = $({
+  stdin: 'hi\n',
+})`claude --output-format stream-json --verbose --model sonnet | jq -r '.type'`;
+
+command
+  .on('data', (chunk) => {
+    chunkCount++;
+    const data = chunk.data.toString();
+    console.log(`📦 CHUNK ${chunkCount}: ${data.trim()}`);
+
+    // Write to file simultaneously
+    appendFileSync(logFile, `Chunk ${chunkCount}: ${data}`);
+  })
+  .on('end', (result) => {
+    console.log(
+      `✅ Got ${chunkCount} chunks, saved to ${logFile}, exit: ${result.code}`
+    );
+  })
+  .start();

package/js/examples/commandstream-working.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('🤖 Command-stream: Claude with stdin');
+
+let chunkCount = 0;
+
+const command = $({
+  stdin: 'hi\n',
+})`claude --output-format stream-json --verbose --model sonnet`;
+
+command
+  .on('data', (chunk) => {
+    chunkCount++;
+    console.log(`📦 CHUNK ${chunkCount}:`);
+    console.log(chunk.data.toString());
+    console.log('---');
+  })
+  .on('end', (result) => {
+    console.log(`✅ Got ${chunkCount} chunks, exit: ${result.code}`);
+  })
+  .start();

package/js/examples/comprehensive-streams-demo.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+/**
+ * Comprehensive demonstration of command-stream streaming interfaces (Issue #33)
+ * Shows: streams.stdin, streams.stdout, streams.stderr, buffers, strings, kill()
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('🚀 command-stream: Comprehensive Streaming Demo');
+console.log('='.repeat(50));
+
+async function comprehensiveDemo() {
+  console.log('\\n1️⃣ STREAMS.STDIN: Send data to commands that read stdin');
+
+  const echoCmd = $`cat`; // cat reads from stdin and outputs to stdout
+  const stdin = echoCmd.streams.stdin;
+  console.log(`   Auto-started? ${echoCmd.started}`);
+
+  if (stdin) {
+    stdin.write('Hello from streams.stdin!\\n');
+    stdin.write('Multiple lines work perfectly\\n');
+    stdin.end();
+  }
+
+  const echoResult = await echoCmd;
+  console.log(`   ✅ Output: ${JSON.stringify(echoResult.stdout)}`);
+
+  console.log('\\n2️⃣ KILL() METHOD: Interrupt processes that ignore stdin');
+
+  const pingCmd = $`ping -c 100 8.8.8.8`; // Long ping, will be interrupted
+
+  // Access stdout to start and monitor
+  const pingOut = pingCmd.streams.stdout;
+  let pingData = '';
+  if (pingOut) {
+    pingOut.on('data', (chunk) => {
+      pingData += chunk.toString();
+    });
+  }
+
+  // Kill after 1.5 seconds
+  setTimeout(() => {
+    console.log('   🔪 Killing ping with kill() method...');
+    pingCmd.kill();
+  }, 1500);
+
+  const pingResult = await pingCmd;
+  console.log(`   ✅ Ping terminated, exit code: ${pingResult.code}`);
+  console.log(`   📊 Captured ${pingResult.stdout.length} bytes of output`);
+
+  console.log('\\n3️⃣ BUFFERS INTERFACE: Get binary data');
+
+  const bufferCmd = $`echo -n "Binary data test"`;
+  const stdoutBuffer = await bufferCmd.buffers.stdout;
+  console.log(`   ✅ Buffer length: ${stdoutBuffer.length} bytes`);
+  console.log(
+    `   ✅ Buffer content: ${JSON.stringify(stdoutBuffer.toString())}`
+  );
+
+  console.log('\\n4️⃣ STRINGS INTERFACE: Get text data');
+
+  const stringCmd = $`echo "String data test"`;
+  const stdoutString = await stringCmd.strings.stdout;
+  console.log(`   ✅ String result: ${JSON.stringify(stdoutString.trim())}`);
+
+  console.log('\\n5️⃣ MIXED STDOUT/STDERR CAPTURE');
+
+  const mixedCmd = $`sh -c 'echo "stdout line" && echo "stderr line" >&2'`;
+  const [stdout, stderr] = await Promise.all([
+    mixedCmd.strings.stdout,
+    mixedCmd.strings.stderr,
+  ]);
+  console.log(`   ✅ stdout: ${JSON.stringify(stdout.trim())}`);
+  console.log(`   ✅ stderr: ${JSON.stringify(stderr.trim())}`);
+
+  console.log('\\n6️⃣ NO AUTO-START UNTIL PROPERTY ACCESS');
+
+  const lazyCmd = $`echo "lazy loading test"`;
+  console.log(`   Created command, started? ${lazyCmd.started}`);
+
+  const lazyStreams = lazyCmd.streams;
+  console.log(`   Accessed .streams, started? ${lazyCmd.started}`);
+
+  const lazyStdout = lazyStreams.stdout; // This triggers auto-start
+  console.log(`   Accessed .streams.stdout, started? ${lazyCmd.started}`);
+
+  const lazyResult = await lazyCmd;
+  console.log(`   ✅ Result: ${JSON.stringify(lazyResult.stdout.trim())}`);
+
+  console.log('\\n7️⃣ BACKWARD COMPATIBILITY');
+
+  const oldStyleCmd = $`echo "backward compatible"`;
+  const oldResult = await oldStyleCmd; // Traditional await syntax
+  console.log(
+    `   ✅ Old style works: ${JSON.stringify(oldResult.stdout.trim())}`
+  );
+
+  console.log(`\\n${'='.repeat(50)}`);
+  console.log('🎉 SUMMARY: Issue #33 Implementation Complete!');
+  console.log('');
+  console.log(
+    '✅ command.streams.stdin/stdout/stderr - immediate stream access'
+  );
+  console.log('✅ command.buffers.stdin/stdout/stderr - binary data interface');
+  console.log('✅ command.strings.stdin/stdout/stderr - text data interface');
+  console.log(
+    '✅ Auto-start only on actual property access, not parent object'
+  );
+  console.log('✅ kill() method for interrupting processes');
+  console.log('✅ Full backward compatibility with await command');
+  console.log('✅ All 484 tests passing');
+  console.log('');
+  console.log('📖 Use cases:');
+  console.log('  • streams.stdin  → Send data to interactive commands');
+  console.log('  • kill()         → Interrupt network/long-running commands');
+  console.log('  • buffers        → Binary data processing');
+  console.log('  • strings        → Text processing and filtering');
+}
+
+comprehensiveDemo().catch(console.error);

package/js/examples/ctrl-c-concurrent-processes.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+// Multiple concurrent processes CTRL+C handling
+
+import { $ } from '../src/$.mjs';
+
+console.log('Multiple concurrent processes');
+console.log('Starting 3 processes - press CTRL+C to interrupt all...\n');
+
+try {
+  await Promise.all([
+    $`/bin/sleep 20`,
+    $`/sbin/ping -c 50 google.com`,
+    $`/usr/bin/yes > /dev/null`,
+  ]);
+  console.log('All processes completed');
+} catch (error) {
+  console.log('\n✓ All processes were interrupted');
+  console.log(`Exit code: ${error.code}`);
+}

package/js/examples/ctrl-c-long-running-command.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+// Long-running command that can be interrupted with CTRL+C
+
+import { $ } from '../src/$.mjs';
+
+console.log('Long-running command (ping)');
+console.log('Press CTRL+C to interrupt...\n');
+
+try {
+  // This will inherit stdin and properly handle CTRL+C
+  await $`ping -c 100 8.8.8.8`;
+  console.log('Ping completed successfully');
+} catch (error) {
+  console.log('\n✓ Command interrupted by CTRL+C');
+  console.log(`Exit code: ${error.code}`);
+  if (error.code === 130 || error.code === -2) {
+    console.log('(This is the expected exit code for SIGINT)');
+  }
+}

package/js/examples/ctrl-c-real-system-command.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+// Real system command CTRL+C handling
+
+import { $ } from '../src/$.mjs';
+
+console.log('Real system command (ping)');
+console.log('Starting ping command - press CTRL+C to interrupt...\n');
+
+try {
+  // Use a real system command that runs indefinitely
+  await $`/sbin/ping -c 100 8.8.8.8`;
+  console.log('Ping completed successfully');
+} catch (error) {
+  console.log('\n✓ Ping was interrupted');
+  console.log(`Exit code: ${error.code}`);
+}

package/js/examples/ctrl-c-sleep-command.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+// Sleep command with signal handling
+
+import { $ } from '../src/$.mjs';
+
+console.log('Sleep command');
+console.log('Press CTRL+C to interrupt the 10-second sleep...\n');
+
+try {
+  console.log('Sleeping for 10 seconds...');
+  await $`sleep 10`;
+  console.log('Sleep completed successfully');
+} catch (error) {
+  console.log('\n✓ Sleep interrupted by CTRL+C');
+  console.log(`Exit code: ${error.code}`);
+}

package/js/examples/ctrl-c-stdin-forwarding.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+// Command with stdin forwarding and CTRL+C handling
+
+import { $ } from '../src/$.mjs';
+
+console.log('Command with stdin forwarding');
+console.log(
+  'This example shows that stdin is properly forwarded while still handling CTRL+C\n'
+);
+
+try {
+  // Create a simple script that reads input
+  await $`echo "Type some text and press Enter, or press CTRL+C to exit:"`;
+  await $`head -n 3`; // Read up to 3 lines
+  console.log('Input reading completed');
+} catch (error) {
+  console.log('\n✓ Command interrupted by CTRL+C');
+  console.log(`Exit code: ${error.code}`);
+}

package/js/examples/ctrl-c-virtual-command.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+// Virtual sleep command CTRL+C handling
+
+import { $ } from '../src/$.mjs';
+
+console.log('Virtual sleep command');
+console.log('Sleeping for 30 seconds - press CTRL+C to interrupt...\n');
+
+const result = await $`sleep 30`;
+
+if (result.code === 0) {
+  console.log('Sleep completed successfully');
+} else {
+  console.log('✓ Sleep was interrupted');
+  console.log(`Exit code: ${result.code}`);
+}

package/js/examples/debug-already-started.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+// Testing already started behavior
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing already started behavior:');
+const runner = $`echo "already started"`;
+
+// First start
+const firstResult = await runner.start({ capture: true });
+console.log('First start result:', JSON.stringify(firstResult.stdout));
+
+// Try to start again with different options
+const secondResult = await runner.start({ capture: false });
+console.log(
+  'Second start result (should ignore new options):',
+  JSON.stringify(secondResult.stdout)
+);
+console.log('Same result reference?', firstResult === secondResult);

package/js/examples/debug-ansi-processing.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import { $, processOutput, getAnsiConfig } from '../src/$.mjs';
+
+console.log('=== Debug ANSI Processing ===\n');
+
+console.log('1. Current global ANSI config:');
+console.log(getAnsiConfig());
+
+console.log('\n2. Testing processOutput function directly:');
+const testData = '\x1b[31mRed text\x1b[0m normal text';
+console.log('Input:', JSON.stringify(testData));
+const processed = processOutput(testData);
+console.log('Processed:', JSON.stringify(processed));
+console.log('Are they equal?', testData === processed);
+
+console.log('\n3. Testing with jq command and manual event handling:');
+const proc = $`echo '{"test": "value"}' | jq --color-output .`;
+
+const rawChunks = [];
+const processedChunks = [];
+
+// Capture raw stdout before processing
+proc.child.stdout.on('data', (chunk) => {
+  rawChunks.push(chunk);
+  console.log('RAW CHUNK:', JSON.stringify(chunk.toString()));
+});
+
+// Capture processed output from events
+proc.on('stdout', (chunk) => {
+  processedChunks.push(chunk);
+  console.log('PROCESSED CHUNK:', JSON.stringify(chunk.toString()));
+});
+
+await proc;
+
+console.log('\n4. Final comparison:');
+const rawResult = Buffer.concat(rawChunks).toString();
+const processedResult = Buffer.concat(processedChunks).toString();
+console.log('Raw result:', JSON.stringify(rawResult));
+console.log('Processed result:', JSON.stringify(processedResult));
+console.log('Results identical?', rawResult === processedResult);

package/js/examples/debug-basic-streaming.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Basic Streaming Debug ===');
+
+console.log('1. Testing await pattern:');
+const result1 = await $`echo "test1"`;
+console.log('Await result:', result1.stdout.trim());
+
+console.log('2. Testing stream pattern:');
+const chunks = [];
+const cmd = $`echo "test2"`;
+try {
+  for await (const chunk of cmd.stream()) {
+    chunks.push(chunk);
+    console.log(
+      'Stream chunk:',
+      chunk.type,
+      JSON.stringify(chunk.data.toString().trim())
+    );
+  }
+  console.log('Stream completed, chunks:', chunks.length);
+} catch (e) {
+  console.log('Stream error:', e.message);
+}
+
+console.log('3. Testing stream with command that produces multiple lines:');
+const cmd2 = $`sh -c 'echo "line1"; echo "line2"'`;
+let count = 0;
+for await (const chunk of cmd2.stream()) {
+  count++;
+  console.log(
+    `Chunk ${count}:`,
+    chunk.type,
+    JSON.stringify(chunk.data.toString().trim())
+  );
+  if (count >= 10) {
+    console.log('Breaking after 10 chunks to prevent infinite loop');
+    break;
+  }
+}
+
+console.log('Debug script completed successfully!');

package/js/examples/debug-buildshellcommand.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+// Debug buildShellCommand function to see exactly what it produces
+import fs from 'fs';
+
+// Recreate buildShellCommand logic
+function quote(value) {
+  if (value === null || value === undefined) {
+    return '""';
+  }
+
+  const str = String(value);
+  if (str === '') {
+    return '""';
+  }
+
+  // Check if value needs quoting (contains spaces or special characters)
+  if (/^[a-zA-Z0-9._/:-]+$/.test(str)) {
+    return str; // Safe to use unquoted
+  }
+
+  return `'${str.replace(/'/g, "'\\''")}'`;
+}
+
+function buildShellCommand(strings, values) {
+  console.log('buildShellCommand input:', { strings, values });
+
+  let out = '';
+  for (let i = 0; i < strings.length; i++) {
+    out += strings[i];
+    if (i < values.length) {
+      const v = values[i];
+      if (
+        v &&
+        typeof v === 'object' &&
+        Object.prototype.hasOwnProperty.call(v, 'raw')
+      ) {
+        console.log(`Using raw value: ${String(v.raw)}`);
+        out += String(v.raw);
+      } else {
+        const quoted = quote(v);
+        console.log(`Quoting value: "${v}" -> "${quoted}"`);
+        out += quoted;
+      }
+    }
+  }
+
+  console.log('buildShellCommand output:', out);
+  return out;
+}
+
+console.log('=== buildShellCommand Debug ===');
+
+console.log('\n--- Case 1: Template literal $`echo hello` ---');
+const strings1 = ['echo hello'];
+const values1 = [];
+const result1 = buildShellCommand(strings1, values1);
+
+console.log(
+  '\n--- Case 2: String interpolation $`${cmd}` where cmd="echo hello" ---'
+);
+const strings2 = ['', ''];
+const values2 = ['echo hello'];
+const result2 = buildShellCommand(strings2, values2);
+
+console.log(
+  '\n--- Case 3: String interpolation $`echo ${arg}` where arg="hello" ---'
+);
+const strings3 = ['echo ', ''];
+const values3 = ['hello'];
+const result3 = buildShellCommand(strings3, values3);
+
+console.log('\n--- Case 4: Multiple args $`echo ${arg1} ${arg2}` ---');
+const strings4 = ['echo ', ' ', ''];
+const values4 = ['hello', 'world'];
+const result4 = buildShellCommand(strings4, values4);
+
+console.log('\n=== Summary ===');
+console.log(`Case 1 (template): "${result1}"`);
+console.log(`Case 2 (interpolation): "${result2}"`);
+console.log(`Case 3 (mixed): "${result3}"`);
+console.log(`Case 4 (multiple): "${result4}"`);