command-stream 0.8.2 → 0.9.0

package/js/examples/test-raw-function.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+
+// Example: Using raw() to disable auto-escape for trusted command strings
+// This demonstrates the solution to issue #139
+
+import { $, raw } from '../src/$.mjs';
+
+console.log('=== raw() Function Examples ===\n');
+
+async function demonstrateRaw() {
+  console.log('1. Basic raw() usage with trusted commands:');
+  console.log('----------------------------------------------');
+
+  // Example 1: Simple command with shell operators
+  console.log('\nExample 1: Command with && operator');
+  const cmd1 = 'echo "Step 1" && echo "Step 2"';
+  console.log('Input:', cmd1);
+  const result1 = await $`${raw(cmd1)}`;
+  console.log('Output:', result1.stdout.trim());
+  console.log('Expected: Both steps executed\n');
+
+  // Example 2: Command with pipes
+  console.log('Example 2: Command with pipe operator');
+  const cmd2 = 'echo "hello world" | wc -w';
+  console.log('Input:', cmd2);
+  const result2 = await $`${raw(cmd2)}`;
+  console.log('Output:', result2.stdout.trim());
+  console.log('Expected: Word count = 2\n');
+
+  // Example 3: Complex command with multiple operators
+  console.log('Example 3: Complex command with redirects and pipes');
+  const cmd3 = 'seq 1 5 | head -n 3';
+  console.log('Input:', cmd3);
+  const result3 = await $`${raw(cmd3)}`;
+  console.log('Output:', result3.stdout.trim());
+  console.log('Expected: Numbers 1, 2, 3\n');
+
+  console.log('2. Combining raw() with safe interpolation:');
+  console.log('----------------------------------------------');
+
+  // Example 4: Mix raw command with safe user input
+  console.log('\nExample 4: Raw command + safe variable');
+  const safeInput = 'test file.txt'; // This will be auto-quoted
+  const cmd4 = raw('echo "Processing:"');
+  const result4 = await $`${cmd4} ${safeInput}`;
+  console.log('Command:', `${cmd4.raw} [auto-quoted: ${safeInput}]`);
+  console.log('Output:', result4.stdout.trim());
+  console.log('Note: File name was safely quoted\n');
+
+  console.log('3. Configuration-based commands (safe use case):');
+  console.log('--------------------------------------------------');
+
+  // Example 5: Pre-defined commands from configuration
+  const config = {
+    listHidden: 'ls -la | grep "^\\."',
+    countFiles: 'ls -1 | wc -l',
+    diskUsage: 'du -sh . 2>/dev/null || echo "N/A"',
+  };
+
+  console.log('\nExample 5: Commands from trusted configuration');
+  for (const [name, command] of Object.entries(config)) {
+    console.log(`\n${name}:`, command);
+    try {
+      const result = await $({ mirror: false })`${raw(command)}`;
+      console.log(
+        'Output:',
+        result.stdout.trim() || result.stderr.trim() || '(no output)'
+      );
+      console.log('Exit code:', result.code);
+    } catch (error) {
+      console.log('Error:', error.message);
+    }
+  }
+
+  console.log('\n4. Comparison: raw() vs normal interpolation:');
+  console.log('-----------------------------------------------');
+
+  const testString = 'echo "test" && ls';
+
+  console.log('\nWith raw() - executes as shell command:');
+  console.log('Input:', testString);
+  const rawResult = await $({ mirror: false })`${raw(testString)}`;
+  console.log('Executed:', testString);
+  console.log(
+    'Output lines:',
+    rawResult.stdout.split('\n').filter((l) => l.trim()).length
+  );
+
+  console.log('\nWithout raw() - treated as literal string:');
+  console.log('Input:', testString);
+  const normalResult = await $({ mirror: false })`echo ${testString}`;
+  console.log('Executed: echo with quoted string');
+  console.log('Output:', normalResult.stdout.trim());
+  console.log('Note: Special characters were escaped\n');
+
+  console.log('5. Security demonstration:');
+  console.log('---------------------------');
+
+  console.log('\n⚠️  WARNING: Never use raw() with untrusted input!');
+
+  // Demonstrate the danger
+  const dangerousInput = 'hello; rm -rf /tmp/test-*';
+
+  console.log('\nDangerous string:', dangerousInput);
+  console.log('\n❌ With raw() (DANGEROUS - would execute malicious code):');
+  console.log('   Would execute:', dangerousInput);
+  console.log('   Status: SKIPPED for safety\n');
+
+  console.log('✅ Without raw() (SAFE - auto-escaped):');
+  const safeResult = await $({ mirror: false })`echo ${dangerousInput}`;
+  console.log('   Executed: echo with safely quoted string');
+  console.log('   Output:', safeResult.stdout.trim());
+  console.log('   Note: Malicious code was neutralized by auto-quoting\n');
+
+  console.log('6. Practical use cases for raw():');
+  console.log('-----------------------------------');
+
+  console.log('\n✅ GOOD use case: Build scripts');
+  const buildSteps = raw('npm run lint && npm run test && npm run build');
+  console.log('Build command:', buildSteps.raw);
+  console.log('Note: Trusted command from your codebase\n');
+
+  console.log('✅ GOOD use case: Deployment commands');
+  const deployCmd = raw('git pull && npm install && pm2 reload app');
+  console.log('Deploy command:', deployCmd.raw);
+  console.log('Note: Hardcoded deployment sequence\n');
+
+  console.log('✅ GOOD use case: Complex shell pipelines');
+  const analyzeCmd = raw('cat log.txt | grep ERROR | wc -l');
+  console.log('Analysis command:', analyzeCmd.raw);
+  console.log('Note: Pre-defined analysis pipeline\n');
+
+  console.log('❌ BAD use case: User input');
+  console.log('const userCmd = getUserInput();');
+  console.log('await $`${raw(userCmd)}`; // ❌ DANGEROUS!');
+  console.log(
+    'Note: NEVER use raw() with user input - use normal interpolation\n'
+  );
+
+  console.log('Summary:');
+  console.log('--------');
+  console.log(
+    '✅ Use raw() for: Trusted commands, config files, hardcoded strings'
+  );
+  console.log(
+    '❌ Never use raw() for: User input, external data, untrusted sources'
+  );
+  console.log(
+    '💡 Default behavior (auto-escape) is safe and should be used for all user input'
+  );
+}
+
+demonstrateRaw().catch(console.error);

package/js/examples/test-raw-streaming.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env bun
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Testing Raw Streaming (no jq) ===\n');
+
+// Test 1: Simple pipe with cat (should not buffer)
+console.log('Test 1: Streaming through cat (unbuffered):');
+const start = Date.now();
+
+const cmd = $`sh -c 'echo "line1"; sleep 0.5; echo "line2"; sleep 0.5; echo "line3"' | cat`;
+
+for await (const chunk of cmd.stream()) {
+  if (chunk.type === 'stdout') {
+    const elapsed = Date.now() - start;
+    const data = chunk.data.toString().trim();
+    if (data) {
+      const lines = data.split('\n').filter((l) => l);
+      for (const line of lines) {
+        console.log(`[${elapsed}ms] ${line}`);
+      }
+    }
+  }
+}
+
+console.log('\n✅ Test complete');
+
+// Test 2: grep (line-buffered by default)
+console.log('\nTest 2: Streaming through grep:');
+const start2 = Date.now();
+
+const cmd2 = $`sh -c 'echo "match1"; sleep 0.5; echo "skip"; sleep 0.5; echo "match2"' | grep match`;
+
+for await (const chunk of cmd2.stream()) {
+  if (chunk.type === 'stdout') {
+    const elapsed = Date.now() - start2;
+    const data = chunk.data.toString().trim();
+    if (data) {
+      const lines = data.split('\n').filter((l) => l);
+      for (const line of lines) {
+        console.log(`[${elapsed}ms] ${line}`);
+      }
+    }
+  }
+}
+
+console.log('\n✅ Test complete');

package/js/examples/test-readme-examples.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+/**
+ * Test the README examples to ensure they work correctly
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('🧪 Testing README Examples');
+console.log('='.repeat(40));
+
+async function testReadmeExamples() {
+  try {
+    console.log('\n📝 EXAMPLE 1: Send data via streams.stdin with cat');
+    console.log('─'.repeat(30));
+
+    const catCmd = $`cat`;
+    const stdin = await catCmd.streams.stdin;
+
+    if (stdin && stdin.write) {
+      console.log('✅ Got writable stdin stream');
+      stdin.write('Hello from stdin!\n');
+      stdin.write('Multiple lines work!\n');
+      stdin.end();
+
+      const result = await catCmd;
+      console.log('✅ Cat output:', JSON.stringify(result.stdout));
+    } else {
+      console.log('❌ No writable stdin available');
+    }
+
+    console.log('\n🔧 EXAMPLE 2: Filter data with grep');
+    console.log('─'.repeat(30));
+
+    const grepCmd = $`grep "important"`;
+    const grepStdin = await grepCmd.streams.stdin;
+
+    if (grepStdin && grepStdin.write) {
+      console.log('✅ Got writable grep stdin stream');
+      grepStdin.write('ignore this line\n');
+      grepStdin.write('important message 1\n');
+      grepStdin.write('skip this too\n');
+      grepStdin.write('another important note\n');
+      grepStdin.end();
+
+      const grepResult = await grepCmd;
+      console.log(
+        '✅ Grep filtered output:',
+        JSON.stringify(grepResult.stdout)
+      );
+    } else {
+      console.log('❌ No writable grep stdin available');
+    }
+
+    console.log('\n📊 EXAMPLE 3: Sort data via stdin');
+    console.log('─'.repeat(30));
+
+    const sortCmd = $`sort`;
+    const sortStdin = await sortCmd.streams.stdin;
+
+    if (sortStdin && sortStdin.write) {
+      console.log('✅ Got writable sort stdin stream');
+      sortStdin.write('zebra\n');
+      sortStdin.write('apple\n');
+      sortStdin.write('banana\n');
+      sortStdin.write('cherry\n');
+      sortStdin.end();
+
+      const sortResult = await sortCmd;
+      console.log('✅ Sort result:', JSON.stringify(sortResult.stdout));
+    } else {
+      console.log('❌ No writable sort stdin available');
+    }
+
+    console.log('\n🧮 EXAMPLE 4: Calculator with bc (if available)');
+    console.log('─'.repeat(30));
+
+    try {
+      const calcCmd = $`bc -l`;
+      const calcStdin = await calcCmd.streams.stdin;
+
+      if (calcStdin && calcStdin.write) {
+        console.log('✅ Got writable bc stdin stream');
+        calcStdin.write('scale=2\n');
+        calcStdin.write('10 / 3\n');
+        calcStdin.write('sqrt(16)\n');
+        calcStdin.write('quit\n');
+
+        const calcResult = await calcCmd;
+        console.log(
+          '✅ BC calculation results:',
+          JSON.stringify(calcResult.stdout.trim())
+        );
+      } else {
+        console.log('❌ No writable bc stdin available');
+      }
+    } catch (error) {
+      console.log('⚠️ BC not available or failed:', error.message);
+    }
+
+    console.log('\n🔄 EXAMPLE 5: Text transformation with tr');
+    console.log('─'.repeat(30));
+
+    const trCmd = $`tr 'a-z' 'A-Z'`;
+    const trStdin = await trCmd.streams.stdin;
+
+    if (trStdin && trStdin.write) {
+      console.log('✅ Got writable tr stdin stream');
+      trStdin.write('hello world\n');
+      trStdin.write('this is lowercase text\n');
+      trStdin.end();
+
+      const trResult = await trCmd;
+      console.log('✅ TR transformed text:', JSON.stringify(trResult.stdout));
+    } else {
+      console.log('❌ No writable tr stdin available');
+    }
+
+    console.log('\n⚡ EXAMPLE 6: Process control with kill()');
+    console.log('─'.repeat(30));
+
+    const sleepCmd = $`sleep 5`;
+
+    // Kill after 1 second
+    setTimeout(() => {
+      console.log('🔪 Using kill() to stop sleep command...');
+      sleepCmd.kill();
+    }, 1000);
+
+    const sleepResult = await sleepCmd;
+    console.log('✅ Sleep killed with exit code:', sleepResult.code);
+
+    console.log(`\n${'='.repeat(40)}`);
+    console.log('🎉 README EXAMPLES TEST COMPLETED!');
+  } catch (error) {
+    console.log('\n❌ ERROR:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+testReadmeExamples();

package/js/examples/test-real-cat.mjs

@@ -0,0 +1,28 @@
+import { $ } from '../src/$.mjs';
+
+async function testRealCat() {
+  console.log('Testing real cat (not virtual) with streams.stdin...');
+
+  // Force bypass of virtual command by using /bin/cat
+  const catCmd = $`/bin/cat`;
+  const stdin = await catCmd.streams.stdin;
+
+  console.log('stdin available:', !!stdin);
+  console.log('stdin writable:', stdin ? stdin.writable : 'N/A');
+
+  if (stdin) {
+    stdin.write('Hello from streams.stdin!\n');
+    stdin.write('Multiple lines work\n');
+    stdin.end();
+  }
+
+  const result = await catCmd;
+  console.log('Result code:', result.code);
+  console.log('Result stdout:', JSON.stringify(result.stdout));
+  console.log(
+    'Expected content present:',
+    result.stdout.includes('Hello from streams.stdin!')
+  );
+}
+
+testRealCat().catch(console.error);

package/js/examples/test-real-commands.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env bun
+
+import { $ } from '../src/$.mjs';
+
+console.log('Test with real commands only (no virtual echo):\n');
+
+// Use printf instead of echo to avoid virtual command
+const result = await $`printf '{"test":1}\\n' | jq .`;
+console.log('Result:', result.stdout);
+
+console.log('\nTest streaming:');
+const start = Date.now();
+for await (const chunk of $`bun run js/examples/emulate-claude-stream.mjs | jq .`.stream()) {
+  if (chunk.type === 'stdout') {
+    const elapsed = Date.now() - start;
+    const lines = chunk.data.toString().trim().split('\n').slice(0, 2);
+    if (lines[0]) {
+      console.log(`[${elapsed}ms] ${lines[0]}`);
+    }
+  }
+}

package/js/examples/test-real-shell.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+async function testRealShellCommands() {
+  console.log('Testing with real shell commands...');
+
+  // Test with a real shell command (ls should exist on most systems)
+  console.log('\n1. Testing real shell command with capture: false:');
+  const result1 = await $`ls /tmp`.start({ capture: false });
+  console.log('Result stdout:', JSON.stringify(result1.stdout)); // Should be undefined
+  console.log('Result code:', result1.code);
+
+  // Test with a real shell command with capture: true
+  console.log('\n2. Testing real shell command with capture: true:');
+  const result2 = await $`ls /tmp`.start({ capture: true });
+  console.log('Result stdout type:', typeof result2.stdout); // Should be string
+  console.log('Result stdout length:', result2.stdout?.length || 0);
+  console.log('Result code:', result2.code);
+
+  // Test with mirror: false to capture but not show output
+  console.log('\n3. Testing real shell command with mirror: false:');
+  const result3 = await $`ls -la /tmp`.start({ mirror: false, capture: true });
+  console.log('Result stdout type:', typeof result3.stdout);
+  console.log('Result stdout lines:', result3.stdout?.split('\n').length || 0);
+  console.log('Result code:', result3.code);
+
+  console.log('\nAll tests completed!');
+}
+
+testRealShellCommands().catch(console.error);

package/js/examples/test-real-stdin-commands.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+
+/**
+ * Test commands that actually read and respond to stdin
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Testing commands that ACTUALLY read stdin ===');
+console.log('');
+
+async function testRealStdinCommands() {
+  try {
+    console.log('TEST 1: cat - classic stdin reader');
+
+    const catCmd = $`cat`;
+    const stdin1 = catCmd.streams.stdin;
+
+    if (stdin1) {
+      stdin1.write('Hello from stdin!\\n');
+      stdin1.write('Second line\\n');
+      stdin1.end();
+    }
+
+    const result1 = await catCmd;
+    console.log('✓ cat result:', JSON.stringify(result1.stdout));
+    console.log('  Exit code:', result1.code);
+
+    console.log('\\nTEST 2: grep - filter input from stdin');
+
+    const grepCmd = $`grep "hello"`;
+    const stdin2 = grepCmd.streams.stdin;
+
+    if (stdin2) {
+      stdin2.write('this line has no match\\n');
+      stdin2.write('hello world\\n');
+      stdin2.write('another non-match\\n');
+      stdin2.write('hello again\\n');
+      stdin2.end();
+    }
+
+    const result2 = await grepCmd;
+    console.log('✓ grep result:', JSON.stringify(result2.stdout));
+    console.log('  Exit code:', result2.code);
+
+    console.log('\\nTEST 3: sort - sort input from stdin');
+
+    const sortCmd = $`sort`;
+    const stdin3 = sortCmd.streams.stdin;
+
+    if (stdin3) {
+      stdin3.write('zebra\\n');
+      stdin3.write('apple\\n');
+      stdin3.write('banana\\n');
+      stdin3.end();
+    }
+
+    const result3 = await sortCmd;
+    console.log('✓ sort result:', JSON.stringify(result3.stdout));
+    console.log('  Exit code:', result3.code);
+
+    console.log('\\nTEST 4: wc - count lines from stdin');
+
+    const wcCmd = $`wc -l`;
+    const stdin4 = wcCmd.streams.stdin;
+
+    if (stdin4) {
+      stdin4.write('line 1\\n');
+      stdin4.write('line 2\\n');
+      stdin4.write('line 3\\n');
+      stdin4.end();
+    }
+
+    const result4 = await wcCmd;
+    console.log('✓ wc result:', JSON.stringify(result4.stdout.trim()));
+    console.log('  Exit code:', result4.code);
+
+    console.log('\\nTEST 5: tr - transform text from stdin');
+
+    const trCmd = $`tr 'a-z' 'A-Z'`; // Convert lowercase to uppercase
+    const stdin5 = trCmd.streams.stdin;
+
+    if (stdin5) {
+      stdin5.write('hello world\\n');
+      stdin5.write('this is lowercase\\n');
+      stdin5.end();
+    }
+
+    const result5 = await trCmd;
+    console.log('✓ tr result:', JSON.stringify(result5.stdout));
+    console.log('  Exit code:', result5.code);
+
+    console.log('\\nTEST 6: awk - process stdin with awk');
+
+    const awkCmd = $`awk '{print NR ": " $0}'`; // Add line numbers
+    const stdin6 = awkCmd.streams.stdin;
+
+    if (stdin6) {
+      stdin6.write('first line\\n');
+      stdin6.write('second line\\n');
+      stdin6.write('third line\\n');
+      stdin6.end();
+    }
+
+    const result6 = await awkCmd;
+    console.log('✓ awk result:', JSON.stringify(result6.stdout));
+    console.log('  Exit code:', result6.code);
+
+    console.log('\\nTEST 7: head - limit lines from stdin');
+
+    const headCmd = $`head -n 2`;
+    const stdin7 = headCmd.streams.stdin;
+
+    if (stdin7) {
+      stdin7.write('line 1\\n');
+      stdin7.write('line 2\\n');
+      stdin7.write('line 3\\n');
+      stdin7.write('line 4\\n');
+      stdin7.end();
+    }
+
+    const result7 = await headCmd;
+    console.log('✓ head result:', JSON.stringify(result7.stdout));
+    console.log('  Exit code:', result7.code);
+
+    console.log('\\nTEST 8: Interactive command - bc calculator');
+
+    const bcCmd = $`bc -l`;
+    const stdin8 = bcCmd.streams.stdin;
+
+    if (stdin8) {
+      stdin8.write('2 + 3\\n');
+      stdin8.write('10 * 5\\n');
+      stdin8.write('sqrt(16)\\n');
+      stdin8.write('quit\\n'); // Important: quit to exit bc
+    }
+
+    const result8 = await bcCmd;
+    console.log('✓ bc result:', JSON.stringify(result8.stdout));
+    console.log('  Exit code:', result8.code);
+
+    console.log('\\n✅ SUMMARY:');
+    console.log('  • All these commands actually READ and PROCESS stdin input');
+    console.log(
+      '  • They demonstrate real stdin control, not just timing coincidences'
+    );
+    console.log(
+      '  • These are the types of commands where streams.stdin is genuinely useful'
+    );
+    console.log(
+      '  • Commands like ping, top (without quit) ignore stdin - use kill() for those'
+    );
+  } catch (error) {
+    console.log('\\n❌ TEST FAILED:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+testRealStdinCommands();

package/js/examples/test-runner-batched.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+/**
+ * Batched test runner that runs tests in smaller groups to avoid interference
+ */
+
+import { execSync } from 'child_process';
+import { readdirSync } from 'fs';
+import { join } from 'path';
+
+const testsDir = join(process.cwd(), 'tests');
+const testFiles = readdirSync(testsDir)
+  .filter((f) => f.endsWith('.test.mjs'))
+  .sort();
+
+// Group tests into batches
+const batchSize = 5;
+const batches = [];
+for (let i = 0; i < testFiles.length; i += batchSize) {
+  batches.push(testFiles.slice(i, i + batchSize));
+}
+
+console.log(
+  `🧪 Running ${testFiles.length} test files in ${batches.length} batches...\n`
+);
+
+let totalPass = 0;
+let totalFail = 0;
+const failedFiles = [];
+
+batches.forEach((batch, index) => {
+  console.log(`\n📦 Batch ${index + 1}/${batches.length}: ${batch.join(', ')}`);
+
+  const files = batch.map((f) => join(testsDir, f)).join(' ');
+
+  try {
+    // Run batch synchronously and capture output
+    const output = execSync(`bun test ${files} 2>&1`, { encoding: 'utf-8' });
+
+    // Parse the output to find pass/fail counts
+    const passMatch = output.match(/(\d+)\s+pass/);
+    const failMatch = output.match(/(\d+)\s+fail/);
+
+    const pass = passMatch ? parseInt(passMatch[1]) : 0;
+    const fail = failMatch ? parseInt(failMatch[1]) : 0;
+
+    totalPass += pass;
+    totalFail += fail;
+
+    if (fail > 0) {
+      console.log(`   ❌ ${pass} pass, ${fail} fail`);
+      failedFiles.push(
+        ...batch.filter((f) =>
+          // Try to identify which files had failures
+          output.includes(f)
+        )
+      );
+    } else {
+      console.log(`   ✅ ${pass} pass`);
+    }
+  } catch (error) {
+    // Test failed to run or had non-zero exit
+    const output = error.stdout || '';
+    const passMatch = output.match(/(\d+)\s+pass/);
+    const failMatch = output.match(/(\d+)\s+fail/);
+
+    const pass = passMatch ? parseInt(passMatch[1]) : 0;
+    const fail = failMatch ? parseInt(failMatch[1]) : 0;
+
+    totalPass += pass;
+    totalFail += fail;
+
+    if (fail > 0) {
+      console.log(`   ❌ ${pass} pass, ${fail} fail`);
+      failedFiles.push(...batch);
+    } else {
+      console.log(`   ⚠️  Error running batch`);
+      failedFiles.push(...batch);
+    }
+  }
+});
+
+console.log(`\n${'='.repeat(60)}`);
+console.log('📊 Summary:');
+console.log(`   Total tests passed: ${totalPass}`);
+console.log(`   Total tests failed: ${totalFail}`);
+console.log(
+  `   Batches with issues: ${failedFiles.length > 0 ? failedFiles.length : 0}`
+);
+
+if (failedFiles.length > 0) {
+  console.log('\n❌ Files with potential issues:');
+  [...new Set(failedFiles)].forEach((f) => console.log(`   - ${f}`));
+  process.exit(1);
+} else {
+  console.log('\n✅ All batches completed successfully!');
+  process.exit(0);
+}