command-stream 0.8.2 → 0.9.0

package/js/examples/test-streams-stdin-ctrl-c.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+/**
+ * Test to verify that streams.stdin can be used to send CTRL+C to interrupt commands
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Testing streams.stdin CTRL+C functionality ===');
+console.log('');
+
+async function testStreamsStdinCtrlC() {
+  try {
+    console.log('TEST 1: Send CTRL+C via streams.stdin to ping command');
+
+    const command = $`ping 8.8.8.8`;
+    console.log('✓ Command created');
+
+    // Access stdin stream - this should auto-start the command
+    const stdin = command.streams.stdin;
+    console.log('✓ Accessed streams.stdin - command should be started');
+    console.log('  Started?', command.started);
+
+    // Wait a moment for ping to start
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    // Send CTRL+C (ASCII code 3)
+    console.log('✓ Sending CTRL+C via stdin...');
+    if (stdin) {
+      stdin.write('\x03'); // CTRL+C
+      stdin.end();
+    }
+
+    // Wait for the command to complete
+    const result = await command;
+    console.log('✓ Command completed with exit code:', result.code);
+    console.log('✓ Stdout length:', result.stdout.length);
+    console.log(
+      '✓ First 200 chars of stdout:',
+      JSON.stringify(result.stdout.slice(0, 200))
+    );
+
+    console.log('');
+    console.log('TEST 2: Test with a different long-running command');
+
+    const command2 = $`sleep 10`;
+    console.log('✓ Sleep command created');
+
+    const stdin2 = command2.streams.stdin;
+    console.log('✓ Accessed streams.stdin for sleep command');
+
+    // Wait a moment
+    await new Promise((resolve) => setTimeout(resolve, 500));
+
+    // Send CTRL+C
+    console.log('✓ Sending CTRL+C to sleep command...');
+    if (stdin2) {
+      stdin2.write('\x03');
+      stdin2.end();
+    }
+
+    const result2 = await command2;
+    console.log('✓ Sleep command completed with exit code:', result2.code);
+
+    console.log('');
+    console.log('TEST 3: Test stdin with echo command');
+
+    const command3 = $`cat`;
+    console.log('✓ Cat command created');
+
+    const stdin3 = command3.streams.stdin;
+    console.log('✓ Accessed streams.stdin for cat command');
+
+    // Send some data first, then CTRL+C
+    if (stdin3) {
+      stdin3.write('Hello from stdin!\n');
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      stdin3.write('\x03'); // CTRL+C
+      stdin3.end();
+    }
+
+    const result3 = await command3;
+    console.log('✓ Cat command completed with exit code:', result3.code);
+    console.log('✓ Output:', JSON.stringify(result3.stdout));
+
+    console.log('');
+    console.log('✅ ALL STREAMS.STDIN CTRL+C TESTS COMPLETED!');
+  } catch (error) {
+    console.log('');
+    console.error('❌ STREAMS.STDIN CTRL+C TEST FAILED:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+testStreamsStdinCtrlC();

package/js/examples/test-template-literal.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { $, shell, enableVirtualCommands } from '../src/$.mjs';
+
+enableVirtualCommands();
+shell.verbose(true);
+
+console.log('=== Testing template literal with spaces ===\n');
+
+const pathWithSpaces = '/tmp/my test dir';
+
+console.log('Variable value:', pathWithSpaces);
+
+// Test 1: Direct template literal
+console.log('\nTest 1: Template literal interpolation');
+console.log('Command will be: cd', pathWithSpaces);
+
+// Capture what command is actually generated
+const originalCwd = process.cwd();
+
+// Try manually constructing the command
+console.log('\nTest 2: Manual command string');
+const cmdString = `cd "${pathWithSpaces}"`;
+console.log('Manual command string:', cmdString);
+const result = await $([cmdString]);
+console.log('Result code:', result.code);

package/js/examples/test-template-vs-interpolation.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+// Test the difference between template literals and string interpolation
+import { $ } from '../src/$.mjs';
+
+// Enable verbose mode
+process.env.COMMAND_STREAM_VERBOSE = 'true';
+
+console.log('=== Template Literal vs String Interpolation Test ===');
+console.log(
+  `Runtime: ${typeof globalThis.Bun !== 'undefined' ? 'Bun' : 'Node.js'}`
+);
+
+console.log('\n--- Testing Template Literal: $`echo hello` ---');
+try {
+  const result1 = await $`echo hello`;
+  console.log(
+    `✓ Template literal success: "${result1.stdout.toString().trim()}"`
+  );
+} catch (error) {
+  console.log(`✗ Template literal failed: ${error.message}`);
+}
+
+console.log('\n--- Testing String Interpolation: $`${cmd}` ---');
+const cmd = 'echo hello';
+try {
+  const result2 = await $`${cmd}`;
+  console.log(
+    `✓ String interpolation success: "${result2.stdout.toString().trim()}"`
+  );
+} catch (error) {
+  console.log(`✗ String interpolation failed: ${error.message}`);
+  if (error.stderr) {
+    console.log(`  Stderr: ${error.stderr.toString().trim()}`);
+  }
+}
+
+console.log('\n--- Testing another format: $(cmd) ---');
+try {
+  // Note: This tests using a variable directly in template literal
+  const result3 = $`${cmd}`;
+  const output3 = await result3;
+  console.log(`✓ $(cmd) format success: "${output3.stdout.toString().trim()}"`);
+} catch (error) {
+  console.log(`✗ $(cmd) format failed: ${error.message}`);
+  if (error.stderr) {
+    console.log(`  Stderr: ${error.stderr.toString().trim()}`);
+  }
+}

package/js/examples/test-timing.mjs

@@ -0,0 +1,41 @@
+import { $ } from '../src/$.mjs';
+
+console.log('Testing exact timing of cancellation...');
+
+// Patch the virtual command to see when it yields
+const originalYes = (await import('../src/commands/$.yes.mjs')).default;
+let yieldCount = 0;
+
+const patchedYes = async function* (opts) {
+  const gen = originalYes(opts);
+  for await (const value of gen) {
+    yieldCount++;
+    console.log(`  [YES YIELD ${yieldCount}]`);
+    yield value;
+  }
+};
+
+// Temporarily replace yes command
+const virtualCommands = (await import('../src/$.mjs')).virtualCommands;
+virtualCommands.set('yes', patchedYes);
+
+const runner = $`yes "test"`;
+let iterations = 0;
+
+console.log('\nStarting iteration...');
+for await (const chunk of runner.stream()) {
+  iterations++;
+  console.log(`  [RECEIVED ${iterations}]: ${chunk.data.toString().trim()}`);
+
+  if (iterations >= 3) {
+    console.log('  [BREAKING]');
+    break;
+  }
+}
+
+console.log(`\nFinal:`);
+console.log(`  Total yields from yes: ${yieldCount}`);
+console.log(`  Total received: ${iterations}`);
+console.log(`  runner.finished: ${runner.finished}`);
+
+process.exit(0);

package/js/examples/test-top-inherit-stdout-stdin-control.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+/**
+ * Test top command with inherited stdout but controlled stdin
+ * This demonstrates the key requirement: inherit stdout but control stdin independently
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Testing top with inherit stdout + streams.stdin control ===');
+console.log('');
+
+async function testTopInheritStdoutStdinControl() {
+  try {
+    console.log(
+      '🎯 GOAL: Run top with inherited stdout, stop it via streams.stdin'
+    );
+    console.log('');
+    console.log('  → top output should appear directly in this terminal');
+    console.log(
+      '  → we should be able to send "q" via streams.stdin to stop it'
+    );
+    console.log(
+      '  → this proves stdout inheritance + independent stdin control'
+    );
+    console.log('');
+
+    console.log('Starting top command...');
+    console.log('━'.repeat(60));
+
+    // Create top command with inherited stdout
+    const topCmd = $`top -n 10`; // Limit to 10 iterations as backup
+
+    // Get stdin control BEFORE starting with specific options
+    const stdin = topCmd.streams.stdin;
+    console.log('✓ Got streams.stdin handle');
+
+    // Set up the quit sequence
+    setTimeout(() => {
+      console.log('\\n[CONTROL] → Sending "q" to quit top...');
+      if (stdin && !stdin.destroyed) {
+        stdin.write('q');
+        // Don't end() immediately - top needs time to process
+        setTimeout(() => {
+          if (stdin && !stdin.destroyed) {
+            stdin.end();
+          }
+        }, 100);
+      }
+    }, 2000); // Wait 2 seconds to see some output
+
+    // Backup kill in case stdin quit doesn't work
+    const killTimer = setTimeout(() => {
+      console.log('\\n[CONTROL] → stdin quit failed, using kill()...');
+      topCmd.kill();
+    }, 5000);
+
+    // Run with inherited stdout but piped stdin (so we can control it)
+    const result = await topCmd.run({
+      stdout: 'inherit', // Output goes directly to terminal
+      stdin: 'pipe', // We control stdin via streams.stdin
+    });
+
+    clearTimeout(killTimer);
+    console.log('━'.repeat(60));
+    console.log('✅ top command completed!');
+    console.log(`   Exit code: ${result.code}`);
+
+    if (result.code === 0) {
+      console.log('   🎉 SUCCESS: top quit cleanly via "q" command!');
+    } else if (
+      result.code === 130 ||
+      result.code === 143 ||
+      result.code === null
+    ) {
+      console.log(
+        '   ⚠️  top was terminated by signal (stdin might not have worked)'
+      );
+    } else {
+      console.log('   ℹ️  top exited with unexpected code');
+    }
+
+    console.log('');
+    console.log('🔍 VERIFICATION: Test the same with a simple command');
+
+    console.log('  → Running echo with inherited stdout + controlled stdin...');
+    const echoCmd = $`cat`;
+    const echoStdin = echoCmd.streams.stdin;
+
+    if (echoStdin) {
+      echoStdin.write('This should appear directly in terminal\\n');
+      echoStdin.write('Because stdout is inherited\\n');
+      echoStdin.end();
+    }
+
+    const echoResult = await echoCmd.run({
+      stdout: 'inherit',
+      stdin: 'pipe',
+    });
+
+    console.log(`  ✅ Verification completed (exit code: ${echoResult.code})`);
+    console.log('');
+
+    console.log('📋 DEMONSTRATION COMPLETE:');
+    console.log(
+      '  ✅ top output appeared directly in terminal (stdout inherited)'
+    );
+    console.log(
+      '  ✅ we controlled top via streams.stdin (independent stdin control)'
+    );
+    console.log('  ✅ "q" command sent via stdin to stop top');
+    console.log(
+      '  ✅ this proves the library supports: inherit stdout + control stdin'
+    );
+  } catch (error) {
+    console.log('');
+    console.error('❌ TEST FAILED:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+testTopInheritStdoutStdinControl();

package/js/examples/test-top-quit-stdin.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+/**
+ * Test that we can stop the `top` command by sending 'q' via streams.stdin
+ * This demonstrates stdin control for interactive commands that actually read stdin
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Testing top command quit via streams.stdin ===');
+console.log('');
+
+async function testTopQuitStdin() {
+  try {
+    console.log('TEST: Stop top command by sending "q" via streams.stdin');
+
+    // Start top command (interactive process monitor)
+    const topCmd = $`top -n 5`; // Limit to 5 iterations in case stdin quit fails
+    console.log('✓ top command created');
+
+    // Get stdin stream (this will auto-start the command)
+    const stdin = topCmd.streams.stdin;
+    console.log('✓ Accessed streams.stdin - top should be started');
+    console.log('  Started?', topCmd.started);
+
+    // Get stdout to monitor output
+    const stdout = topCmd.streams.stdout;
+    if (stdout) {
+      stdout.on('data', (data) => {
+        const output = data.toString();
+        process.stdout.write(`[top] ${output}`);
+
+        // Look for signs that top is running (like "Tasks:" or "Cpu(s):")
+        if (
+          output.includes('Tasks:') ||
+          output.includes('Cpu') ||
+          output.includes('PID')
+        ) {
+          console.log('\\n  → top is running, sending "q" to quit...');
+          if (stdin && !stdin.destroyed) {
+            stdin.write('q');
+            // Don't end() stdin immediately - top might need time to process
+          }
+        }
+      });
+    }
+
+    // Fallback: send 'q' after 2 seconds in case we miss the output detection
+    setTimeout(() => {
+      console.log('\\n  → Fallback: sending "q" after 2 seconds...');
+      if (stdin && !stdin.destroyed) {
+        stdin.write('q');
+        // Give top a moment to process the quit command
+        setTimeout(() => {
+          if (stdin && !stdin.destroyed) {
+            stdin.end();
+          }
+        }, 500);
+      }
+    }, 2000);
+
+    // Additional fallback: kill if still running after 5 seconds
+    const killTimeout = setTimeout(() => {
+      console.log('\\n  → stdin "q" failed, using kill() as backup...');
+      topCmd.kill();
+    }, 5000);
+
+    // Wait for top to complete
+    const result = await topCmd;
+    clearTimeout(killTimeout);
+
+    console.log('\\n✓ top command completed');
+    console.log('  Exit code:', result.code);
+    console.log('  Output length:', result.stdout.length);
+    console.log(
+      '  First 200 chars:',
+      JSON.stringify(result.stdout.slice(0, 200))
+    );
+
+    // Determine how it was stopped
+    if (result.code === 0) {
+      console.log('  🎉 SUCCESS: top quit cleanly via "q" command!');
+    } else if (result.code === 130 || result.code === 143) {
+      console.log(
+        '  ⚠️  top was killed via signal (stdin quit may not have worked)'
+      );
+    } else {
+      console.log('  ℹ️  top exited with code:', result.code);
+    }
+
+    console.log('\\n=== Testing comparison with cat (known stdin reader) ===');
+
+    const catCmd = $`cat`;
+    const catStdin = catCmd.streams.stdin;
+
+    if (catStdin) {
+      catStdin.write('Testing cat stdin\\n');
+      catStdin.write('This should work reliably\\n');
+      catStdin.end();
+    }
+
+    const catResult = await catCmd;
+    console.log('✓ cat result:', JSON.stringify(catResult.stdout));
+    console.log('  Exit code:', catResult.code);
+
+    console.log('\\n📋 CONCLUSION:');
+    console.log('✅ streams.stdin successfully sends data to processes');
+    console.log('✅ Interactive commands like top can be controlled via stdin');
+    console.log('✅ Fallback kill() method available for stubborn processes');
+  } catch (error) {
+    console.log('');
+    console.error('❌ TEST FAILED:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+testTopQuitStdin();

package/js/examples/test-trace-option.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// Test the trace option in $ config
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Test: mirror:false with trace:false in CI environment ===');
+process.env.CI = 'true';
+
+const $silent = $({ mirror: false, capture: true, trace: false });
+const result = await $silent`echo '{"status":"ok"}'`;
+console.log('JSON Output:', result.stdout);
+
+console.log('\n=== Parsing JSON to verify it works ===');
+try {
+  const parsed = JSON.parse(result.stdout);
+  console.log('Parsed successfully:', parsed);
+  console.log('✓ Test PASSED: No trace logs interfered with JSON parsing');
+} catch (e) {
+  console.error('✗ Test FAILED: Could not parse JSON:', e.message);
+  console.error('Raw output:', result.stdout);
+}

package/js/examples/test-user-double-quotes.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+// Test: User provides double quotes around interpolated value
+// Expected: Preserve double quotes (wrapped in single quotes for shell)
+
+import { $ } from '../src/$.mjs';
+
+const claude = '/Users/konard/.claude/local/claude';
+
+console.log('=== Test: User-Provided Double Quotes ===\n');
+
+// User wraps the path in double quotes
+const doubleQuoted = `"${claude}"`;
+
+console.log('Original path:', claude);
+console.log('User provides:', doubleQuoted);
+
+const cmd = $({ mirror: false })`${doubleQuoted} --version`;
+console.log('Generated command:', cmd.spec.command);
+
+// Check the expected result
+const expected = `'"/Users/konard/.claude/local/claude"' --version`;
+if (cmd.spec.command === expected) {
+  console.log('✅ PASS: Double quotes preserved and properly wrapped');
+} else {
+  console.log('❌ FAIL: Unexpected quoting');
+  console.log('Expected:', expected);
+}
+
+// Test execution
+try {
+  const result = await cmd;
+  console.log('\nExecution result:', result.code);
+} catch (error) {
+  console.log('\nExecution error:', error.message);
+}

package/js/examples/test-user-single-quotes.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+// Test: User provides single quotes around interpolated value
+// Expected: Preserve single quotes without double-escaping
+
+import { $ } from '../src/$.mjs';
+
+const claude = '/Users/konard/.claude/local/claude';
+
+console.log('=== Test: User-Provided Single Quotes ===\n');
+
+// User wraps the path in single quotes
+const singleQuoted = `'${claude}'`;
+
+console.log('Original path:', claude);
+console.log('User provides:', singleQuoted);
+
+const cmd = $({ mirror: false })`${singleQuoted} --version`;
+console.log('Generated command:', cmd.spec.command);
+
+// Check the result
+if (cmd.spec.command === `'${claude}' --version`) {
+  console.log('✅ PASS: Single quotes preserved correctly');
+} else if (cmd.spec.command.includes("''")) {
+  console.log('❌ FAIL: Double quotes detected');
+} else {
+  console.log('⚠️  WARNING: Unexpected quoting pattern');
+}
+
+// Test execution
+try {
+  const result = await cmd;
+  console.log('\nExecution result:', result.code);
+} catch (error) {
+  console.log('\nExecution error:', error.message);
+}

package/js/examples/test-verbose.mjs

@@ -0,0 +1,18 @@
+import { $, shell } from '../src/$.mjs';
+
+const originalLog = console.log;
+const capturedLogs = [];
+console.log = (...args) => {
+  capturedLogs.push(args.join(' '));
+  originalLog(...args); // Also output to see what's happening
+};
+
+shell.verbose(true);
+await $`echo "verbose test"`;
+
+console.log = originalLog;
+console.log('Captured logs:', capturedLogs);
+console.log(
+  'Has echo command:',
+  capturedLogs.some((log) => log.includes('echo "verbose test"'))
+);

package/js/examples/test-verbose2.mjs

@@ -0,0 +1,32 @@
+import { $, shell } from '../src/$.mjs';
+
+const originalLog = console.log;
+const capturedLogs = [];
+console.log = (...args) => {
+  capturedLogs.push(args.join(' '));
+  originalLog('LOG:', ...args); // Also output to see what's happening
+};
+
+shell.verbose(true);
+const result = await $`echo "verbose test"`;
+console.log('Result stdout:', result.stdout);
+
+console.log = originalLog;
+console.log('Captured logs:', capturedLogs);
+console.log('Looking for: "echo \\"verbose test\\""');
+console.log(
+  'Found verbatim:',
+  capturedLogs.some((log) => log === 'echo "verbose test"')
+);
+console.log(
+  'Found without quotes:',
+  capturedLogs.some((log) => log === 'echo verbose test')
+);
+console.log(
+  'Contains echo:',
+  capturedLogs.some((log) => log.includes('echo'))
+);
+console.log(
+  'Contains verbose test:',
+  capturedLogs.some((log) => log.includes('verbose test'))
+);