command-stream 0.8.2 → 0.9.0

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

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== JQ Streaming Debug ===');
+
+console.log('Testing the exact command that was failing...');
+
+const cmd = $`sh -c 'echo "{\\"id\\":1}"; sleep 0.5; echo "{\\"id\\":2}"; sleep 0.5; echo "{\\"id\\":3}"' | jq -c .`;
+
+console.log('Getting stream...');
+
+// Set a timeout to prevent infinite hang
+const timeout = setTimeout(() => {
+  console.log('TIMEOUT: JQ stream took too long');
+  process.exit(1);
+}, 10000);
+
+try {
+  let chunkCount = 0;
+  let buffer = '';
+
+  console.log('Starting stream iteration...');
+  for await (const chunk of cmd.stream()) {
+    if (chunk.type === 'stdout') {
+      chunkCount++;
+      buffer += chunk.data.toString();
+
+      console.log(
+        `Chunk ${chunkCount}:`,
+        JSON.stringify(chunk.data.toString())
+      );
+
+      // Process complete lines
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || '';
+
+      for (const line of lines) {
+        if (line.trim()) {
+          console.log('Complete line:', JSON.stringify(line.trim()));
+        }
+      }
+
+      // Safety break after getting some output
+      if (chunkCount >= 5) {
+        console.log('Safety break after 5 chunks');
+        break;
+      }
+    }
+  }
+
+  clearTimeout(timeout);
+  console.log('JQ streaming completed with', chunkCount, 'chunks');
+} catch (error) {
+  clearTimeout(timeout);
+  console.log('JQ streaming error:', error.message);
+}

package/js/examples/debug-jq-tty-colors.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+/**
+ * Debug script to understand jq TTY and color behavior
+ * This helps diagnose why the test behaves differently in different environments
+ */
+
+import { $ } from '../src/$.mjs';
+import { spawn } from 'child_process';
+
+const testJson =
+  '{"message": "hello", "number": 42, "active": true, "data": null}';
+
+console.log('='.repeat(60));
+console.log('JQ TTY AND COLOR BEHAVIOR DIAGNOSTIC');
+console.log('='.repeat(60));
+
+// 1. Check current environment
+console.log('\n1. ENVIRONMENT INFORMATION:');
+console.log('-'.repeat(40));
+console.log('Node version:', process.version);
+console.log('Platform:', process.platform);
+console.log('TTY Status:');
+console.log('  - process.stdout.isTTY:', process.stdout.isTTY);
+console.log('  - process.stderr.isTTY:', process.stderr.isTTY);
+console.log('  - process.stdin.isTTY:', process.stdin.isTTY);
+console.log('Environment variables:');
+console.log('  - TERM:', process.env.TERM || '(not set)');
+console.log('  - COLORTERM:', process.env.COLORTERM || '(not set)');
+console.log('  - NO_COLOR:', process.env.NO_COLOR || '(not set)');
+console.log('  - FORCE_COLOR:', process.env.FORCE_COLOR || '(not set)');
+console.log('  - CI:', process.env.CI || '(not set)');
+
+// 2. Test jq version and capabilities
+console.log('\n2. JQ VERSION AND CAPABILITIES:');
+console.log('-'.repeat(40));
+try {
+  const jqVersion = await $`jq --version`;
+  console.log('jq version:', jqVersion.stdout.trim());
+} catch (e) {
+  console.log('Error getting jq version:', e.message);
+}
+
+// 3. Test default jq behavior through command-stream
+console.log('\n3. JQ THROUGH COMMAND-STREAM (default):');
+console.log('-'.repeat(40));
+const defaultResult = await $`echo ${testJson} | jq .`;
+const hasDefaultColors = /\u001b\[\d+/.test(defaultResult.stdout);
+console.log('Exit code:', defaultResult.code);
+console.log('Has ANSI color codes:', hasDefaultColors);
+console.log('Output length:', defaultResult.stdout.length);
+console.log(
+  'First 150 chars (raw):',
+  JSON.stringify(defaultResult.stdout.substring(0, 150))
+);
+
+// 4. Test with explicit color flag
+console.log('\n4. JQ WITH EXPLICIT COLOR FLAG (-C):');
+console.log('-'.repeat(40));
+const colorResult = await $`echo ${testJson} | jq -C .`;
+const hasExplicitColors = /\u001b\[\d+/.test(colorResult.stdout);
+console.log('Has ANSI color codes:', hasExplicitColors);
+console.log('Output length:', colorResult.stdout.length);
+console.log(
+  'First 150 chars (raw):',
+  JSON.stringify(colorResult.stdout.substring(0, 150))
+);
+
+// 5. Test with explicit no-color flag
+console.log('\n5. JQ WITH EXPLICIT NO-COLOR FLAG (-M):');
+console.log('-'.repeat(40));
+const noColorResult = await $`echo ${testJson} | jq -M .`;
+const hasNoColors = /\u001b\[\d+/.test(noColorResult.stdout);
+console.log('Has ANSI color codes:', hasNoColors);
+console.log('Output length:', noColorResult.stdout.length);
+console.log(
+  'First 150 chars (raw):',
+  JSON.stringify(noColorResult.stdout.substring(0, 150))
+);
+
+// 6. Test jq directly with Node's spawn (bypassing command-stream)
+console.log('\n6. JQ DIRECTLY VIA NODE SPAWN:');
+console.log('-'.repeat(40));
+await new Promise((resolve) => {
+  const echo = spawn('echo', [testJson]);
+  const jq = spawn('jq', ['.']);
+
+  let output = '';
+  echo.stdout.pipe(jq.stdin);
+
+  jq.stdout.on('data', (data) => {
+    output += data.toString();
+  });
+
+  jq.on('close', () => {
+    const hasSpawnColors = /\u001b\[\d+/.test(output);
+    console.log('Has ANSI color codes:', hasSpawnColors);
+    console.log('Output length:', output.length);
+    console.log(
+      'First 150 chars (raw):',
+      JSON.stringify(output.substring(0, 150))
+    );
+    resolve();
+  });
+});
+
+// 7. Test with environment variable manipulation
+console.log('\n7. JQ WITH ENVIRONMENT VARIABLES:');
+console.log('-'.repeat(40));
+
+// Test with NO_COLOR
+process.env.NO_COLOR = '1';
+const noColorEnvResult = await $`echo ${testJson} | jq .`;
+const hasNoColorEnv = /\u001b\[\d+/.test(noColorEnvResult.stdout);
+console.log('With NO_COLOR=1, has colors:', hasNoColorEnv);
+delete process.env.NO_COLOR;
+
+// Test with FORCE_COLOR
+process.env.FORCE_COLOR = '1';
+const forceColorEnvResult = await $`echo ${testJson} | jq .`;
+const hasForceColorEnv = /\u001b\[\d+/.test(forceColorEnvResult.stdout);
+console.log('With FORCE_COLOR=1, has colors:', hasForceColorEnv);
+delete process.env.FORCE_COLOR;
+
+// 8. Summary and test recommendation
+console.log('\n8. ANALYSIS AND RECOMMENDATION:');
+console.log('-'.repeat(40));
+console.log('Default behavior has colors:', hasDefaultColors);
+console.log('Explicit -C has colors:', hasExplicitColors);
+console.log('Explicit -M has colors:', hasNoColors);
+console.log('Direct spawn has colors:', /\u001b\[\d+/.test(''));
+
+if (hasDefaultColors && !process.stdout.isTTY) {
+  console.log(
+    '\n⚠️  UNEXPECTED: jq is outputting colors in non-TTY environment by default'
+  );
+  console.log('This might be due to:');
+  console.log('  - jq configuration or alias');
+  console.log('  - Environment variables affecting color output');
+  console.log('  - Different jq version behavior');
+} else if (!hasDefaultColors && process.stdout.isTTY) {
+  console.log(
+    '\n⚠️  UNEXPECTED: jq is NOT outputting colors in TTY environment by default'
+  );
+  console.log('This might be due to:');
+  console.log("  - Pipe detection (jq sees it's in a pipe)");
+  console.log('  - Environment variables suppressing colors');
+} else {
+  console.log('\n✅ jq behavior matches expected TTY detection');
+}
+
+console.log('\n9. RECOMMENDED TEST FIX:');
+console.log('-'.repeat(40));
+console.log('The test should handle both scenarios:');
+console.log('  1. When jq auto-detects TTY and colors accordingly');
+console.log('  2. When jq is affected by environment variables or config');
+console.log('\nSuggested approach:');
+console.log('  - Test explicit -C and -M flags (predictable behavior)');
+console.log(
+  '  - For default behavior, accept both colored and non-colored output'
+);
+console.log(
+  '  - Focus on testing that output is valid JSON regardless of colors'
+);
+
+console.log(`\n${'='.repeat(60)}`);
+console.log('DIAGNOSTIC COMPLETE');
+console.log('='.repeat(60));

package/js/examples/debug-kill-cleanup.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+function getSigintHandlerCount() {
+  const sigintListeners = process.listeners('SIGINT');
+  const commandStreamListeners = sigintListeners.filter((l) => {
+    const str = l.toString();
+    return (
+      str.includes('activeProcessRunners') ||
+      str.includes('ProcessRunner') ||
+      str.includes('activeChildren')
+    );
+  });
+  return commandStreamListeners.length;
+}
+
+console.log('=== Kill Cleanup Debug ===');
+
+console.log('Initial SIGINT handlers:', getSigintHandlerCount());
+
+// Test killing like the failing test does
+const runner = $`seq 1 100`;
+const promise = runner.start();
+
+console.log('After starting command:', getSigintHandlerCount(), 'handlers');
+
+// Let it start generating
+await new Promise((resolve) => setTimeout(resolve, 10));
+
+console.log('Before killing:', getSigintHandlerCount(), 'handlers');
+
+// Kill it before it completes
+runner.kill();
+
+console.log('Immediately after kill:', getSigintHandlerCount(), 'handlers');
+
+try {
+  await promise;
+} catch (e) {
+  console.log('Expected error after kill:', e.message);
+}
+
+console.log(
+  'After awaiting killed promise:',
+  getSigintHandlerCount(),
+  'handlers'
+);
+console.log('runner.finished:', runner.finished);
+
+// Wait a bit more
+await new Promise((resolve) => setTimeout(resolve, 50));
+
+console.log('After 50ms wait:', getSigintHandlerCount(), 'handlers');
+
+console.log('Test completed.');

package/js/examples/debug-kill-method.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing kill() method');
+
+try {
+  const runner = $`sleep 5`;
+  console.log('Created runner');
+
+  // Give it time to start
+  setTimeout(async () => {
+    console.log('Killing the command');
+    try {
+      runner.kill('SIGINT');
+      console.log('Kill method called successfully');
+    } catch (error) {
+      console.error('Error in kill():', error.message);
+      console.error('Error stack:', error.stack);
+    }
+  }, 500);
+
+  console.log('Awaiting runner');
+  const result = await runner.catch((error) => {
+    console.log('Runner caught error:', error.message);
+    return { code: error.code || 130 };
+  });
+
+  console.log('Final result:', result);
+} catch (error) {
+  console.error('Outer error:', error.message);
+  console.error('Stack:', error.stack);
+}

package/js/examples/debug-listener-interference.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Listener Interference Debug ===');
+
+async function testWithoutStream() {
+  console.log('\n1. Test without calling stream():');
+  const cmd = $`echo "test1"`;
+
+  cmd.on('end', () => console.log('END listener called'));
+  cmd.on('exit', () => console.log('EXIT listener called'));
+
+  console.log('Listeners before await:', cmd.listeners);
+  await cmd;
+  console.log('Listeners after await:', cmd.listeners);
+}
+
+async function testWithStream() {
+  console.log('\n2. Test after calling stream():');
+  const cmd = $`echo "test2"`;
+
+  cmd.on('end', () => console.log('END listener called'));
+  cmd.on('exit', () => console.log('EXIT listener called'));
+
+  console.log('Listeners before stream():', cmd.listeners);
+
+  // Just call stream() to get the generator, but don't iterate
+  const streamGen = cmd.stream();
+
+  console.log('Listeners after stream():', cmd.listeners);
+
+  await cmd;
+  console.log('Listeners after await:', cmd.listeners);
+}
+
+await testWithoutStream();
+await testWithStream();

package/js/examples/debug-listener-lifecycle.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Listener Lifecycle Debug ===');
+
+const cmd = $`echo "test"`;
+
+// Track the instance identity
+console.log('Command instance ID:', cmd.toString());
+
+// Add listeners
+cmd.on('data', () => console.log('DATA listener called'));
+cmd.on('end', () => console.log('END listener called'));
+cmd.on('exit', () => console.log('EXIT listener called'));
+
+console.log('After adding listeners:', cmd.listeners.size, 'listeners');
+
+// Override _runVirtual to track listeners during execution
+const original_runVirtual = cmd._runVirtual;
+if (original_runVirtual) {
+  cmd._runVirtual = function (...args) {
+    console.log('At start of _runVirtual:', this.listeners.size, 'listeners');
+    console.log('Instance check:', this === cmd ? 'SAME' : 'DIFFERENT');
+
+    const result = original_runVirtual.apply(this, args);
+
+    console.log('At end of _runVirtual:', this.listeners.size, 'listeners');
+    return result;
+  };
+}
+
+// Also override emit to see the context
+const originalEmit = cmd.emit;
+cmd.emit = function (event, ...args) {
+  console.log(
+    `Emitting ${event}: instance check:`,
+    this === cmd ? 'SAME' : 'DIFFERENT'
+  );
+  console.log(`Emitting ${event}: listeners map size:`, this.listeners.size);
+  console.log(
+    `Emitting ${event}: has listener for event:`,
+    this.listeners.has(event)
+  );
+  return originalEmit.call(this, event, ...args);
+};
+
+console.log('Starting await...');
+await cmd;
+console.log('After await:', cmd.listeners.size, 'listeners');

package/js/examples/debug-listener-timing.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Listener Timing Debug ===');
+
+async function testEarlyListeners() {
+  console.log('\n1. Attaching listeners BEFORE await:');
+  const cmd = $`echo "test1"`;
+
+  // Attach listeners immediately after creating command
+  const events = [];
+  cmd.on('data', () => events.push('data'));
+  cmd.on('end', () => events.push('end'));
+  cmd.on('exit', () => events.push('exit'));
+
+  console.log('Events before await:', events);
+  await cmd;
+  console.log('Events after await:', events);
+}
+
+async function testLateListeners() {
+  console.log('\n2. Attaching listeners AFTER await:');
+  const cmd = $`echo "test2"`;
+
+  // First await the command
+  await cmd;
+
+  // THEN attach listeners (too late!)
+  const events = [];
+  cmd.on('data', () => events.push('data'));
+  cmd.on('end', () => events.push('end'));
+  cmd.on('exit', () => events.push('exit'));
+
+  console.log('Events after await (should be empty):', events);
+}
+
+async function testStreamWithEarlyListeners() {
+  console.log('\n3. Testing stream with early listeners:');
+  const cmd = $`echo "test3"`;
+
+  const events = [];
+  cmd.on('data', () => events.push('data'));
+  cmd.on('end', () => events.push('end'));
+  cmd.on('exit', () => events.push('exit'));
+
+  console.log('Events before stream:', events);
+
+  // Use stream instead of await
+  for await (const chunk of cmd.stream()) {
+    console.log('Stream chunk received');
+    break; // Just get first chunk
+  }
+
+  console.log('Events after stream:', events);
+}
+
+await testEarlyListeners();
+await testLateListeners();
+await testStreamWithEarlyListeners();
+
+console.log('\nDebug completed!');

package/js/examples/debug-listeners-property.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Listeners Property Debug ===');
+
+const cmd = $`echo "test"`;
+
+// Override the listeners property to track modifications
+let _listeners = cmd.listeners;
+Object.defineProperty(cmd, 'listeners', {
+  get() {
+    return _listeners;
+  },
+  set(newValue) {
+    console.log('LISTENERS PROPERTY SET!');
+    console.log('Old value size:', _listeners ? _listeners.size : 'undefined');
+    console.log('New value size:', newValue ? newValue.size : 'undefined');
+
+    // Get stack trace to see who's setting the property
+    const stack = new Error().stack;
+    console.log('Stack trace:', stack.split('\n').slice(1, 5).join('\n'));
+
+    _listeners = newValue;
+  },
+});
+
+cmd.on('data', () => console.log('DATA listener called'));
+cmd.on('end', () => console.log('END listener called'));
+cmd.on('exit', () => console.log('EXIT listener called'));
+
+console.log('Starting await...');
+await cmd;
+console.log('Completed await');

package/js/examples/debug-map-methods.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Map Methods Debug ===');
+
+const cmd = $`echo "test"`;
+
+// Override Map methods to track modifications
+const originalClear = cmd.listeners.clear.bind(cmd.listeners);
+const originalDelete = cmd.listeners.delete.bind(cmd.listeners);
+const originalSet = cmd.listeners.set.bind(cmd.listeners);
+
+cmd.listeners.clear = function () {
+  console.log('LISTENERS MAP CLEARED!');
+  const stack = new Error().stack;
+  console.log('Stack trace:', stack.split('\n').slice(1, 5).join('\n'));
+  return originalClear();
+};
+
+cmd.listeners.delete = function (key) {
+  console.log('LISTENERS MAP DELETE:', key);
+  const stack = new Error().stack;
+  console.log('Stack trace:', stack.split('\n').slice(1, 3).join('\n'));
+  return originalDelete(key);
+};
+
+cmd.listeners.set = function (key, value) {
+  console.log('LISTENERS MAP SET:', key, 'with', value.length, 'listeners');
+  return originalSet(key, value);
+};
+
+cmd.on('data', () => console.log('DATA listener called'));
+cmd.on('end', () => console.log('END listener called'));
+cmd.on('exit', () => console.log('EXIT listener called'));
+
+console.log('Starting await...');
+await cmd;
+console.log('Completed await');

package/js/examples/debug-not-awaited-cleanup.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env bun
+// Debug script to test the non-awaited command cleanup issue
+
+import { $ } from '../src/$.mjs';
+
+// Enable verbose mode
+process.env.COMMAND_STREAM_VERBOSE = 'true';
+
+async function testNotAwaitedCleanup() {
+  console.log('=== Not Awaited Cleanup Debug ===');
+
+  console.log('\n1. Initial state:');
+  const initialListeners = process.listeners('SIGINT').length;
+  console.log('Initial SIGINT listeners:', initialListeners);
+
+  console.log('\n2. Creating and starting commands without awaiting...');
+  const runner1 = $`sleep 0.05`;
+  const runner2 = $`echo "not awaited"`;
+  const runner3 = $`pwd`;
+
+  console.log(
+    'After creating runners, SIGINT listeners:',
+    process.listeners('SIGINT').length
+  );
+
+  // Start them
+  const promise1 = runner1.start();
+  console.log(
+    'After starting runner1, SIGINT listeners:',
+    process.listeners('SIGINT').length
+  );
+
+  const promise2 = runner2.start();
+  console.log(
+    'After starting runner2, SIGINT listeners:',
+    process.listeners('SIGINT').length
+  );
+
+  const promise3 = runner3.start();
+  console.log(
+    'After starting runner3, SIGINT listeners:',
+    process.listeners('SIGINT').length
+  );
+
+  console.log('\n3. Checking after 50ms...');
+  await new Promise((resolve) => setTimeout(resolve, 50));
+  console.log(
+    'After 50ms, SIGINT listeners:',
+    process.listeners('SIGINT').length
+  );
+
+  console.log('\n4. Checking after 100ms total...');
+  await new Promise((resolve) => setTimeout(resolve, 50));
+  console.log(
+    'After 100ms total, SIGINT listeners:',
+    process.listeners('SIGINT').length
+  );
+
+  console.log('\n5. Checking after 200ms total...');
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  console.log(
+    'After 200ms total, SIGINT listeners:',
+    process.listeners('SIGINT').length
+  );
+
+  console.log('\n6. Checking individual promise statuses...');
+  console.log(
+    'Promise 1 resolved?',
+    await Promise.race([
+      promise1.then(() => true),
+      new Promise((r) => setTimeout(() => r(false), 0)),
+    ])
+  );
+  console.log(
+    'Promise 2 resolved?',
+    await Promise.race([
+      promise2.then(() => true),
+      new Promise((r) => setTimeout(() => r(false), 0)),
+    ])
+  );
+  console.log(
+    'Promise 3 resolved?',
+    await Promise.race([
+      promise3.then(() => true),
+      new Promise((r) => setTimeout(() => r(false), 0)),
+    ])
+  );
+
+  console.log('\n7. Forcing resolution by awaiting all...');
+  try {
+    const results = await Promise.all([promise1, promise2, promise3]);
+    console.log('All promises resolved');
+  } catch (e) {
+    console.log('Error waiting for promises:', e.message);
+  }
+
+  console.log('\n8. Final state:');
+  console.log('Final SIGINT listeners:', process.listeners('SIGINT').length);
+  console.log('Expected:', initialListeners);
+  console.log(
+    'Match?',
+    process.listeners('SIGINT').length === initialListeners
+  );
+}
+
+testNotAwaitedCleanup().catch(console.error);

package/js/examples/debug-off-method.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Off Method Debug ===');
+
+const cmd = $`echo "test"`;
+
+// Override the off method to track when listeners are removed
+const originalOff = cmd.off.bind(cmd);
+cmd.off = function (event, listener) {
+  console.log(`OFF called for event: ${event}`);
+  console.log(`Listeners before off:`, this.listeners.size);
+
+  // Get stack trace to see who's calling off
+  const stack = new Error().stack;
+  console.log('Stack trace:', stack.split('\n').slice(1, 4).join('\n'));
+
+  const result = originalOff(event, listener);
+  console.log(`Listeners after off:`, this.listeners.size);
+  return result;
+};
+
+cmd.on('data', () => console.log('DATA listener called'));
+cmd.on('end', () => console.log('END listener called'));
+cmd.on('exit', () => console.log('EXIT listener called'));
+
+await cmd;