command-stream 0.8.2 → 0.9.0

package/js/examples/test-sleep.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+// Test sleep example for CI reliability (no network dependencies)
+console.error('[test-sleep.mjs] Process started, PID:', process.pid);
+console.error('[test-sleep.mjs] Node version:', process.version);
+console.error('[test-sleep.mjs] Current directory:', process.cwd());
+console.error('[test-sleep.mjs] Script path:', import.meta.url);
+
+let $;
+try {
+  const module = await import('../src/$.mjs');
+  $ = module.$;
+  console.error('[test-sleep.mjs] Module imported successfully');
+} catch (error) {
+  console.error('[test-sleep.mjs] Failed to import module:', error.message);
+  console.error('[test-sleep.mjs] Error stack:', error.stack);
+  // Exit early if we can't import the module
+  console.log('STARTING_SLEEP'); // Still output for test
+  process.exit(1);
+}
+
+console.error('[test-sleep.mjs] Is TTY:', process.stdout.isTTY);
+console.log('STARTING_SLEEP');
+console.error('[test-sleep.mjs] Wrote STARTING_SLEEP to stdout');
+
+// Ensure stdout is flushed immediately for CI environments
+await new Promise((resolve) => {
+  if (process.stdout.isTTY === false) {
+    console.error(
+      '[test-sleep.mjs] Non-TTY environment detected, forcing flush'
+    );
+    // Force flush in non-TTY environments (CI)
+    process.stdout.write('', () => {
+      console.error('[test-sleep.mjs] Stdout flush completed');
+      resolve();
+    });
+  } else {
+    console.error('[test-sleep.mjs] TTY environment, no flush needed');
+    resolve();
+  }
+});
+
+console.error('[test-sleep.mjs] About to run sleep command');
+try {
+  const result = await $`sleep 30`; // Long enough to be interrupted, but timeout safe
+  console.log('SLEEP_COMPLETED');
+  console.error('[test-sleep.mjs] Sleep completed with code:', result.code);
+} catch (error) {
+  console.error(
+    '[test-sleep.mjs] Sleep interrupted:',
+    error.message,
+    'code:',
+    error.code
+  );
+  process.exit(error.code || 1);
+}

package/js/examples/test-smart-quoting.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+
+// Test smart quoting behavior for interpolated strings
+// We need to preserve user-provided quotes while still auto-quoting when necessary
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Smart Quoting Tests ===\n');
+
+async function testSmartQuoting() {
+  const claude = '/Users/konard/.claude/local/claude';
+
+  console.log('1. Testing user-provided quotes preservation:');
+  console.log('----------------------------------------------');
+
+  // Case 1: User provides single quotes
+  console.log('\nCase 1: User wraps in single quotes');
+  const singleQuoted = `'${claude}'`;
+  console.log('Input:', singleQuoted);
+  const cmd1 = $({ mirror: false })`${singleQuoted} --version`;
+  console.log('Generated:', cmd1.spec.command);
+  console.log(
+    'Expected: Should preserve single quotes without double-escaping'
+  );
+
+  // Case 2: User provides double quotes
+  console.log('\nCase 2: User wraps in double quotes');
+  const doubleQuoted = `"${claude}"`;
+  console.log('Input:', doubleQuoted);
+  const cmd2 = $({ mirror: false })`${doubleQuoted} --version`;
+  console.log('Generated:', cmd2.spec.command);
+  console.log(
+    'Expected: Should preserve double quotes (wrapped in single quotes for shell)'
+  );
+
+  // Case 3: No quotes from user - auto-quote
+  console.log('\nCase 3: No quotes from user');
+  console.log('Input:', claude);
+  const cmd3 = $({ mirror: false })`${claude} --version`;
+  console.log('Generated:', cmd3.spec.command);
+  console.log('Expected: Should auto-quote the path');
+
+  console.log('\n2. Testing smart auto-quoting (only when needed):');
+  console.log('--------------------------------------------------');
+
+  // Test various strings that need/don't need escaping
+  const testCases = [
+    {
+      desc: 'Simple command (no special chars)',
+      value: 'echo',
+      needsQuoting: false,
+    },
+    {
+      desc: 'Path with spaces',
+      value: '/path with spaces/command',
+      needsQuoting: true,
+    },
+    {
+      desc: 'Path with special chars',
+      value: '/path/with$special&chars',
+      needsQuoting: true,
+    },
+    {
+      desc: 'Simple path (no special chars)',
+      value: '/usr/bin/echo',
+      needsQuoting: false, // Ideally shouldn't need quotes
+    },
+    {
+      desc: 'String with single quote',
+      value: "can't",
+      needsQuoting: true,
+    },
+    {
+      desc: 'Empty string',
+      value: '',
+      needsQuoting: true, // Empty needs quotes
+    },
+  ];
+
+  for (const { desc, value, needsQuoting } of testCases) {
+    console.log(`\n${desc}:`);
+    console.log('Input:', JSON.stringify(value));
+    const cmd = $({ mirror: false })`echo ${value}`;
+    console.log('Generated:', cmd.spec.command);
+    console.log('Needs quoting:', needsQuoting);
+  }
+
+  console.log('\n3. Testing complex scenarios:');
+  console.log('------------------------------');
+
+  // Scenario 1: Mixed quoted and unquoted
+  console.log('\nScenario 1: Mixed arguments');
+  const path = '/usr/bin/env';
+  const arg1 = 'node';
+  const arg2 = '--version';
+  const mixedCmd = $({ mirror: false })`${path} ${arg1} ${arg2}`;
+  console.log('Generated:', mixedCmd.spec.command);
+
+  // Scenario 2: User pre-quotes some args
+  console.log('\nScenario 2: Some args pre-quoted by user');
+  const quotedArg = '"my file.txt"';
+  const unquotedArg = 'output.log';
+  const partialCmd = $({ mirror: false })`cat ${quotedArg} > ${unquotedArg}`;
+  console.log('Generated:', partialCmd.spec.command);
+
+  // Scenario 3: Command with already-escaped characters
+  console.log('\nScenario 3: Already-escaped characters');
+  const escaped = "can\\'t";
+  const escapedCmd = $({ mirror: false })`echo ${escaped}`;
+  console.log('Input (escaped):', escaped);
+  console.log('Generated:', escapedCmd.spec.command);
+
+  console.log('\n4. Testing actual execution with quotes:');
+  console.log('-----------------------------------------');
+
+  // Test that quotes work correctly in practice
+  try {
+    // Test with spaces in argument
+    const result1 = await $`echo ${'hello world'}`;
+    console.log('Spaces test output:', String(result1).trim());
+
+    // Test with special characters
+    const result2 = await $`echo ${'$HOME'}`;
+    console.log('Special char test output:', String(result2).trim());
+    console.log('(Should print literal $HOME, not expanded)');
+
+    // Test with single quotes in content
+    const result3 = await $`echo ${"it's working"}`;
+    console.log('Single quote test output:', String(result3).trim());
+  } catch (error) {
+    console.error('Execution error:', error.message);
+  }
+
+  console.log('\n5. Edge cases for quote handling:');
+  console.log('----------------------------------');
+
+  // Test various edge cases
+  const edgeCases = [
+    {
+      desc: 'Just single quote',
+      input: "'",
+      expected: 'Should escape properly',
+    },
+    {
+      desc: 'Just double quote',
+      input: '"',
+      expected: 'Should escape properly',
+    },
+    {
+      desc: 'Empty single quotes',
+      input: "''",
+      expected: 'Should preserve as-is',
+    },
+    {
+      desc: 'Empty double quotes',
+      input: '""',
+      expected: 'Should wrap in single quotes',
+    },
+    {
+      desc: 'Nested quotes',
+      input: '"\'nested\'"',
+      expected: 'Should handle nested quotes',
+    },
+    {
+      desc: 'Triple quotes',
+      input: "'''",
+      expected: 'Should escape all quotes',
+    },
+  ];
+
+  for (const { desc, input, expected } of edgeCases) {
+    console.log(`\n${desc}:`);
+    console.log('Input:', JSON.stringify(input));
+    const cmd = $({ mirror: false })`echo ${input}`;
+    console.log('Generated:', cmd.spec.command);
+    console.log('Expected:', expected);
+  }
+}
+
+testSmartQuoting().catch(console.error);

package/js/examples/test-spaces-in-path.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { $, shell, enableVirtualCommands } from '../src/$.mjs';
+import { mkdtempSync, rmSync, mkdirSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+enableVirtualCommands();
+shell.verbose(true);
+
+console.log('=== Testing paths with spaces ===\n');
+
+const baseDir = mkdtempSync(join(tmpdir(), 'space-test-'));
+const dirWithSpaces = join(baseDir, 'my test directory');
+mkdirSync(dirWithSpaces);
+const originalCwd = process.cwd();
+
+console.log('Directory created:', dirWithSpaces);
+
+try {
+  console.log('\nTest 1: cd with quoted path');
+  const result1 = await $`cd "${dirWithSpaces}"`;
+  console.log('Exit code:', result1.code);
+  console.log('Stdout:', result1.stdout);
+  console.log('Stderr:', result1.stderr);
+
+  const pwd1 = await $`pwd`;
+  console.log('Current dir:', pwd1.stdout.trim());
+  console.log('Expected:', dirWithSpaces);
+  console.log('Match:', pwd1.stdout.trim() === dirWithSpaces);
+
+  await $`cd ${originalCwd}`;
+
+  console.log('\nTest 2: cd with escaped spaces');
+  const escaped = dirWithSpaces.replace(/ /g, '\\ ');
+  const result2 = await $`cd ${escaped}`;
+  console.log('Exit code:', result2.code);
+
+  const pwd2 = await $`pwd`;
+  console.log('Current dir:', pwd2.stdout.trim());
+} catch (error) {
+  console.error('Error:', error.message);
+} finally {
+  process.chdir(originalCwd);
+  rmSync(baseDir, { recursive: true, force: true });
+}
+
+console.log('\n=== Test Complete ===');

package/js/examples/test-special-chars-quoting.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+// Test: Quoting strings with special characters
+// Expected: Proper escaping and quoting for shell safety
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Test: Special Characters Quoting ===\n');
+
+async function testSpecialChars() {
+  const tests = [
+    { desc: 'Single quote in string', input: "can't", testExec: true },
+    { desc: 'Double quote in string', input: 'say "hello"', testExec: true },
+    { desc: 'Dollar sign (variable)', input: '$HOME', testExec: true },
+    { desc: 'Backtick (command sub)', input: '`date`', testExec: true },
+    { desc: 'Semicolon (command sep)', input: 'first; second', testExec: true },
+    { desc: 'Ampersand (background)', input: 'cmd &', testExec: false },
+    { desc: 'Pipe character', input: 'a | b', testExec: false },
+    { desc: 'Backslash', input: 'path\\to\\file', testExec: true },
+    { desc: 'Newline', input: 'line1\nline2', testExec: true },
+    { desc: 'Tab', input: 'col1\tcol2', testExec: true },
+  ];
+
+  for (const { desc, input, testExec } of tests) {
+    console.log(`\n${desc}:`);
+    console.log('Input:', JSON.stringify(input));
+
+    const cmd = $({ mirror: false })`echo ${input}`;
+    console.log('Generated:', cmd.spec.command);
+
+    if (testExec) {
+      try {
+        const result = await $`echo ${input}`;
+        const output = String(result).trim();
+        console.log('Output:', JSON.stringify(output));
+
+        // Check if special chars were properly escaped
+        if (input === '$HOME' && output === '$HOME') {
+          console.log('✅ Variable not expanded (properly escaped)');
+        } else if (input === '`date`' && output === '`date`') {
+          console.log('✅ Command substitution prevented (properly escaped)');
+        } else if (output === input) {
+          console.log('✅ Output matches input (properly escaped)');
+        } else {
+          console.log('⚠️  Output differs from input');
+        }
+      } catch (error) {
+        console.log('Execution error:', error.message);
+      }
+    }
+  }
+}
+
+testSpecialChars().catch(console.error);

package/js/examples/test-stdin-after-start.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Test stdin access after process starts ===');
+
+async function testStdinAfterStart() {
+  const cmd = $`cat`;
+
+  // First, start the process explicitly
+  cmd.start({ mode: 'async', stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' });
+
+  // Wait a moment for the process to actually start
+  await new Promise((resolve) => setTimeout(resolve, 100));
+
+  console.log('Process started?', cmd.started);
+  console.log('Child exists?', !!cmd.child);
+  console.log('Child stdin exists?', !!(cmd.child && cmd.child.stdin));
+
+  // Now try to access stdin
+  const stdin = cmd.streams.stdin;
+  console.log('Stdin from streams?', !!stdin);
+
+  if (stdin) {
+    console.log('Writing to stdin...');
+    stdin.write('Hello after start!\\n');
+    stdin.end();
+  } else {
+    console.log('No stdin available, ending without input');
+    // End the process some other way
+    setTimeout(() => cmd.kill(), 100);
+  }
+
+  const result = await cmd;
+  console.log('Final result stdout:', JSON.stringify(result.stdout));
+  console.log('Exit code:', result.code);
+}
+
+testStdinAfterStart().catch(console.error);

package/js/examples/test-stdin-simple.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+/**
+ * Simple focused test for streams.stdin functionality
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Testing streams.stdin simple functionality ===');
+
+async function testStdinSimple() {
+  try {
+    // Test 1: Basic stdin with cat
+    console.log('TEST 1: Send data to cat via stdin');
+    const cmd1 = $`cat`;
+
+    const stdin1 = cmd1.streams.stdin;
+    console.log('  Process started?', cmd1.started);
+
+    if (stdin1) {
+      stdin1.write('Hello World\\n');
+      stdin1.end();
+    }
+
+    const result1 = await cmd1;
+    console.log('  Exit code:', result1.code);
+    console.log('  Output:', JSON.stringify(result1.stdout));
+
+    // Test 2: stdin with echo command using Node.js
+    console.log('\\nTEST 2: Node.js script reading stdin');
+    const cmd2 = $`node -e "process.stdin.on('data', d => process.stdout.write(d)); process.stdin.on('end', () => process.exit(0));"`;
+
+    const stdin2 = cmd2.streams.stdin;
+    if (stdin2) {
+      stdin2.write('Node stdin test\\n');
+      stdin2.end();
+    }
+
+    const result2 = await cmd2;
+    console.log('  Exit code:', result2.code);
+    console.log('  Output:', JSON.stringify(result2.stdout));
+
+    // Test 3: Test kill method on sleep
+    console.log('\\nTEST 3: Kill sleep command');
+    const cmd3 = $`sleep 5`;
+
+    // Start the process
+    cmd3.streams.stdout; // Access to start
+    console.log('  Process started?', cmd3.started);
+
+    // Wait a bit then kill
+    setTimeout(() => {
+      console.log('  Killing sleep...');
+      cmd3.kill();
+    }, 500);
+
+    const result3 = await cmd3;
+    console.log('  Exit code:', result3.code);
+
+    console.log('\\n✅ All stdin tests completed!');
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+    process.exit(1);
+  }
+}
+
+testStdinSimple();

package/js/examples/test-stdin-timing.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Test stdin timing with proper flow ===');
+
+async function testStdinTiming() {
+  console.log('Test 1: Access stdin immediately and write quickly');
+
+  const cmd1 = $`cat`;
+
+  // Get stdin immediately, which should auto-start the process
+  const stdin1 = cmd1.streams.stdin;
+  console.log('Stdin available immediately?', !!stdin1);
+  console.log('Command started?', cmd1.started);
+
+  if (stdin1) {
+    // Write immediately before the process might finish
+    stdin1.write('Quick input\\n');
+    stdin1.end();
+  }
+
+  const result1 = await cmd1;
+  console.log('Result 1:', JSON.stringify(result1.stdout));
+  console.log('Exit code 1:', result1.code);
+
+  console.log(
+    '\\nTest 2: Create test with Node.js script that definitely reads stdin'
+  );
+
+  const nodeScript = `
+    process.stdin.setEncoding('utf8');
+    let input = '';
+    process.stdin.on('data', (chunk) => {
+      input += chunk;
+    });
+    process.stdin.on('end', () => {
+      process.stdout.write('Received: ' + input);
+    });
+  `;
+
+  const cmd2 = $`node -e "${nodeScript}"`;
+  const stdin2 = cmd2.streams.stdin;
+
+  console.log('Node script stdin available?', !!stdin2);
+
+  if (stdin2) {
+    stdin2.write('Node.js input test\\n');
+    stdin2.end();
+  }
+
+  const result2 = await cmd2;
+  console.log('Node result:', JSON.stringify(result2.stdout));
+  console.log('Exit code 2:', result2.code);
+
+  console.log('\\nTest 3: Test with sleep to ensure process stays alive');
+
+  const cmd3 = $`sh -c 'cat && echo "Done"'`;
+  const stdin3 = cmd3.streams.stdin;
+
+  console.log('Shell cat stdin available?', !!stdin3);
+
+  if (stdin3) {
+    // Send data and then close stdin
+    stdin3.write('Shell script input\\n');
+    stdin3.end();
+  }
+
+  const result3 = await cmd3;
+  console.log('Shell result:', JSON.stringify(result3.stdout));
+  console.log('Exit code 3:', result3.code);
+}
+
+testStdinTiming().catch(console.error);

package/js/examples/test-stdio-combinations.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+
+/**
+ * Test different stdio combinations with streams interface
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Testing stdio combinations with streams interface ===');
+console.log('');
+
+async function testStdioCombinations() {
+  try {
+    console.log('TEST 1: Default behavior - streams.stdin works for input');
+
+    const cmd1 = $`cat`;
+    const stdin1 = cmd1.streams.stdin;
+
+    if (stdin1) {
+      stdin1.write('Hello from streams.stdin!\\n');
+      stdin1.write('This demonstrates stdin control\\n');
+      stdin1.end();
+    }
+
+    const result1 = await cmd1;
+    console.log('✓ Default cat result:', JSON.stringify(result1.stdout));
+    console.log('  Exit code:', result1.code);
+
+    console.log('');
+    console.log('TEST 2: Demonstrate top quit with streams.stdin');
+
+    console.log('  → Starting limited top command...');
+    const topCmd = $`top -l 2`; // Limited to 2 iterations on macOS
+    const topStdin = topCmd.streams.stdin;
+
+    // Try to quit early with 'q'
+    setTimeout(() => {
+      console.log('  → Sending "q" to quit top early...');
+      if (topStdin && !topStdin.destroyed) {
+        topStdin.write('q');
+      }
+    }, 500);
+
+    // Backup kill after reasonable time
+    setTimeout(() => {
+      if (!topCmd.finished) {
+        console.log('  → Backup kill...');
+        topCmd.kill();
+      }
+    }, 3000);
+
+    const topResult = await topCmd;
+    console.log('  ✓ Top completed with exit code:', topResult.code);
+    console.log('  ✓ Output length:', topResult.stdout.length, 'characters');
+
+    console.log('');
+    console.log('TEST 3: Compare with native behavior - ping ignores stdin');
+
+    const pingCmd = $`ping -c 3 127.0.0.1`; // Limited ping
+    const pingStdin = pingCmd.streams.stdin;
+
+    // Try to send data to ping stdin (will be ignored)
+    if (pingStdin) {
+      pingStdin.write('q\\n');
+      pingStdin.write('quit\\n');
+      pingStdin.write('\\x03'); // CTRL+C
+      pingStdin.end();
+    }
+
+    const pingResult = await pingCmd;
+    console.log('  ✓ Ping completed (stdin ignored, ran full 3 pings)');
+    console.log('  ✓ Exit code:', pingResult.code);
+    console.log(
+      '  ✓ Contains ping statistics?',
+      pingResult.stdout.includes('packets transmitted')
+    );
+
+    console.log('');
+    console.log('TEST 4: Interactive command that responds to stdin - more');
+
+    // Create a temporary file for 'more' command
+    const setupCmd = $`echo "Line 1\\nLine 2\\nLine 3\\nLine 4\\nLine 5\\nLine 6" > /tmp/test-more.txt`;
+    await setupCmd;
+
+    const moreCmd = $`more /tmp/test-more.txt`;
+    const moreStdin = moreCmd.streams.stdin;
+
+    // Send space (next page) and q (quit) to more
+    setTimeout(() => {
+      if (moreStdin && !moreStdin.destroyed) {
+        console.log('  → Sending commands to more...');
+        moreStdin.write(' '); // space for next page
+        setTimeout(() => moreStdin.write('q'), 100); // quit
+      }
+    }, 100);
+
+    const moreResult = await moreCmd;
+    console.log('  ✓ More command completed with exit code:', moreResult.code);
+
+    // Cleanup
+    await $`rm -f /tmp/test-more.txt`;
+
+    console.log('');
+    console.log('✅ SUMMARY:');
+    console.log('  • streams.stdin allows sending data to any process');
+    console.log(
+      '  • Interactive commands (cat, top, more) can be controlled via stdin'
+    );
+    console.log(
+      '  • Network commands (ping) ignore stdin input (expected behavior)'
+    );
+    console.log('  • kill() method works for forceful termination when needed');
+    console.log(
+      '  • Our library provides both input control AND process control'
+    );
+  } catch (error) {
+    console.log('');
+    console.error('❌ TEST FAILED:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+testStdioCombinations();