command-stream 0.8.2 → 0.9.0

package/js/examples/streaming-silent-capture.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+// Long-running command with silent capture
+
+import { $ } from '../src/$.mjs';
+
+console.log('Long-running with silent capture:');
+const $longSilent = $({ mirror: false, capture: true });
+
+try {
+  const startTime = Date.now();
+  for await (const chunk of $longSilent`sleep 2 && echo "Task completed"`.stream()) {
+    if (chunk.type === 'stdout') {
+      const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+      console.log(`⏱️  [${elapsed}s] ${chunk.data.toString().trim()}`);
+    }
+  }
+} catch (error) {
+  console.log(`Error: ${error.message}`);
+}

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

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+/**
+ * Simple streaming test to verify command-stream functionality
+ * Uses 'echo' and 'seq' commands that are guaranteed to exist
+ */
+
+import { $ } from '../src/$.mjs';
+import { writeFileSync, appendFileSync, existsSync } from 'fs';
+
+console.log('🧪 Testing streaming with simple commands...\n');
+
+// Test 1: Basic echo with streaming
+console.log('Test 1: Basic echo streaming');
+let chunkCount = 0;
+
+const echoTest = $`echo "Hello from streaming test!"`;
+echoTest
+  .on('data', (chunk) => {
+    chunkCount++;
+    console.log(`📦 Chunk ${chunkCount}: "${chunk.data.toString().trim()}"`);
+  })
+  .on('end', (result) => {
+    console.log(
+      `✅ Echo test complete. Chunks: ${chunkCount}, Exit code: ${result.code}\n`
+    );
+
+    // Test 2: seq command for multiple chunks
+    runSeqTest();
+  });
+
+await echoTest.start();
+
+function runSeqTest() {
+  console.log('Test 2: Sequence streaming (multiple chunks)');
+  let seqChunks = 0;
+
+  const seqTest = $`seq 1 5`;
+  seqTest
+    .on('data', (chunk) => {
+      seqChunks++;
+      const data = chunk.data.toString().trim();
+      console.log(`📦 Seq chunk ${seqChunks}: "${data}"`);
+    })
+    .on('end', (result) => {
+      console.log(
+        `✅ Seq test complete. Chunks: ${seqChunks}, Exit code: ${result.code}\n`
+      );
+
+      // Test 3: For-await streaming pattern
+      runAsyncIteratorTest();
+    });
+
+  seqTest.start();
+}
+
+async function runAsyncIteratorTest() {
+  console.log('Test 3: Async iterator streaming pattern');
+  let iteratorChunks = 0;
+
+  for await (const chunk of $`seq 10 13`.stream()) {
+    iteratorChunks++;
+    console.log(
+      `🔄 Iterator chunk ${iteratorChunks}: "${chunk.data.toString().trim()}" (${chunk.type})`
+    );
+  }
+
+  console.log(`✅ Async iterator test complete. Chunks: ${iteratorChunks}\n`);
+  console.log('🎉 All streaming tests completed!');
+}

package/js/examples/streaming-virtual-pipeline.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env bun
+
+// Virtual command with pipeline
+
+import { $ } from '../src/$.mjs';
+
+console.log('Virtual command with jq pipeline:');
+
+const start = Date.now();
+let chunkCount = 0;
+for await (const chunk of $`echo '{"test":1}' | jq .`.stream()) {
+  if (chunk.type === 'stdout') {
+    chunkCount++;
+    const elapsed = Date.now() - start;
+    console.log(`[${elapsed}ms] Chunk ${chunkCount}`);
+  }
+}
+console.log(`Total: ${chunkCount} chunks`);

package/js/examples/syntax-basic-comparison.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+// Basic streaming comparison: regular $ vs $({ options })
+
+import { $ } from '../src/$.mjs';
+
+console.log('Basic streaming comparison:');
+
+console.log('Regular $ syntax:');
+try {
+  for await (const chunk of $`echo "Hello from regular $"`.stream()) {
+    if (chunk.type === 'stdout') {
+      console.log(`📝 Regular: ${chunk.data.toString().trim()}`);
+    }
+  }
+} catch (error) {
+  console.log(`Error: ${error.message}`);
+}
+
+console.log('\n$({ options }) syntax with mirror: false:');
+const $configured = $({ mirror: false });
+
+try {
+  for await (const chunk of $configured`echo "Hello from configured $"`.stream()) {
+    if (chunk.type === 'stdout') {
+      console.log(`⚙️  Configured: ${chunk.data.toString().trim()}`);
+    }
+  }
+} catch (error) {
+  console.log(`Error: ${error.message}`);
+}

package/js/examples/syntax-basic-options.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+// Basic options verification
+
+import { $ } from '../src/$.mjs';
+
+console.log('Verifying basic options...');
+
+const $quiet = $({ mirror: false });
+const result = await $quiet`echo "test"`;
+console.assert(result.stdout === 'test\n', 'Basic options failed');
+console.log('✓ Basic options work');

package/js/examples/syntax-combined-options.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+// Combined multiple options using $({ options })
+
+import { $ } from '../src/$.mjs';
+
+console.log('Combined options:');
+const $combined = $({
+  stdin: 'test data for file',
+  cwd: '/tmp',
+  mirror: false,
+  capture: true,
+});
+
+const filename = `test-${Date.now()}.txt`;
+await $combined`cat > ${filename}`;
+const verify = await $({ cwd: '/tmp', mirror: false })`cat ${filename}`;
+console.log('Created file with content:', verify.stdout);
+await $({ cwd: '/tmp', mirror: false })`rm ${filename}`;

package/js/examples/syntax-command-chaining.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+// Command chaining verification
+
+import { $ } from '../src/$.mjs';
+
+console.log('Verifying command chaining...');
+
+const $chain = $({ mirror: false });
+const result = await $chain`echo "abc" | tr 'a-z' 'A-Z'`;
+console.assert(result.stdout === 'ABC\n', 'Chaining failed');
+console.log('✓ Command chaining works');

package/js/examples/syntax-custom-directory.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+// Custom working directory using $({ options })
+
+import { $ } from '../src/$.mjs';
+
+console.log('Custom working directory:');
+const $inTmp = $({ cwd: '/tmp', mirror: false });
+const result = await $inTmp`pwd`;
+console.log('Current directory:', result.stdout.trim());

package/js/examples/syntax-custom-environment.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+// Custom environment using $({ options })
+
+import { $ } from '../src/$.mjs';
+
+console.log('Custom environment:');
+const $withEnv = $({
+  env: { ...process.env, DEMO_VAR: 'custom_value' },
+  mirror: false,
+});
+const result = await $withEnv`printenv DEMO_VAR`;
+console.log('DEMO_VAR =', result.stdout.trim());

package/js/examples/syntax-custom-stdin.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+// Custom stdin using $({ options })
+
+import { $ } from '../src/$.mjs';
+
+console.log('Custom stdin:');
+const $withInput = $({ stdin: 'Hello from stdin!\n' });
+const result = await $withInput`cat`;
+console.log('Output:', result.stdout.trim());

package/js/examples/syntax-mixed-regular.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+// Mixed with regular $ verification
+
+import { $ } from '../src/$.mjs';
+
+console.log('Verifying mixed with regular $...');
+
+const result = await $`echo "normal"`;
+console.assert(result.stdout === 'normal\n', 'Regular $ failed');
+console.log('✓ Regular $ still works');

package/js/examples/syntax-mixed-usage.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+// Mix with regular $ usage
+
+import { $ } from '../src/$.mjs';
+
+console.log('Mixed usage:');
+console.log('Regular $ (with mirror):');
+await $`echo "This appears in terminal"`;
+
+console.log('With options (no mirror):');
+await $({ mirror: false })`echo "This doesn't appear"`;
+
+console.log('Regular $ again:');
+await $`echo "Back to normal"`;

package/js/examples/syntax-multiple-listeners.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+// Multiple event listeners comparison
+
+import { $ } from '../src/$.mjs';
+
+console.log('Multiple event listeners comparison:');
+
+console.log('Regular $ with multiple listeners:');
+try {
+  const multiRunner1 = $`echo -e "Event 1\\nEvent 2\\nEvent 3"`;
+
+  // First listener - counts events
+  let eventCount1 = 0;
+  multiRunner1.on('stdout', (data) => {
+    const lines = data
+      .toString()
+      .split('\n')
+      .filter((line) => line.trim());
+    eventCount1 += lines.length;
+  });
+
+  // Second listener - processes events
+  multiRunner1.on('stdout', (data) => {
+    const lines = data
+      .toString()
+      .split('\n')
+      .filter((line) => line.trim());
+    for (const line of lines) {
+      console.log(`📨 Regular listener: ${line}`);
+    }
+  });
+
+  // Third listener - logs timing
+  const start1 = Date.now();
+  multiRunner1.on('close', () => {
+    const duration = Date.now() - start1;
+    console.log(
+      `⏰ Regular $ processed ${eventCount1} events in ${duration}ms`
+    );
+  });
+
+  await multiRunner1;
+} catch (error) {
+  console.log(`Error: ${error.message}`);
+}
+
+console.log('\nConfigured $ with multiple listeners:');
+const $multiConfig = $({ mirror: false });
+
+try {
+  const multiRunner2 = $multiConfig`echo -e "Config Event 1\\nConfig Event 2\\nConfig Event 3"`;
+
+  // First listener - counts events
+  let eventCount2 = 0;
+  multiRunner2.on('stdout', (data) => {
+    const lines = data
+      .toString()
+      .split('\n')
+      .filter((line) => line.trim());
+    eventCount2 += lines.length;
+  });
+
+  // Second listener - processes events
+  multiRunner2.on('stdout', (data) => {
+    const lines = data
+      .toString()
+      .split('\n')
+      .filter((line) => line.trim());
+    for (const line of lines) {
+      console.log(`📨 Configured listener: ${line}`);
+    }
+  });
+
+  // Third listener - logs timing
+  const start2 = Date.now();
+  multiRunner2.on('close', () => {
+    const duration = Date.now() - start2;
+    console.log(
+      `⏰ Configured $ processed ${eventCount2} events in ${duration}ms`
+    );
+  });
+
+  await multiRunner2;
+} catch (error) {
+  console.log(`Error: ${error.message}`);
+}

package/js/examples/syntax-piping-comparison.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+// Command chaining with different options comparison
+
+import { $ } from '../src/$.mjs';
+
+console.log('Command chaining with different options:');
+
+console.log('Regular $ with pipes:');
+try {
+  for await (const chunk of $`echo "apple,banana,cherry" | tr ',' '\\n' | sort`.stream()) {
+    if (chunk.type === 'stdout') {
+      const lines = chunk.data.toString().trim().split('\n');
+      lines.forEach((line) => console.log(`🔗 Piped: ${line}`));
+    }
+  }
+} catch (error) {
+  console.log(`Error: ${error.message}`);
+}
+
+console.log('\nConfigured $ with pipes:');
+const $pipe = $({ mirror: false });
+try {
+  for await (const chunk of $pipe`echo "zebra,yak,xerus" | tr ',' '\\n' | sort -r`.stream()) {
+    if (chunk.type === 'stdout') {
+      const lines = chunk.data.toString().trim().split('\n');
+      lines.forEach((line) => console.log(`⚙️  Configured: ${line}`));
+    }
+  }
+} catch (error) {
+  console.log(`Error: ${error.message}`);
+}

package/js/examples/syntax-reusable-config.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+// Multiple uses of same configured $ verification
+
+import { $ } from '../src/$.mjs';
+
+console.log('Verifying reusable configurations...');
+
+const $multi = $({ capture: true, mirror: false });
+const result1 = await $multi`echo "1"`;
+const result2 = await $multi`echo "2"`;
+console.assert(
+  result1.stdout === '1\n' && result2.stdout === '2\n',
+  'Reuse failed'
+);
+console.log('✓ Reusable configurations work');

package/js/examples/syntax-reusable-configs.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+// Reusable configurations using $({ options })
+
+import { $ } from '../src/$.mjs';
+
+console.log('Reusable configurations:');
+const $debug = $({
+  env: { ...process.env, DEBUG: 'true' },
+  mirror: false,
+});
+
+// Run multiple commands with same configuration
+const result1 = await $debug`echo "Command 1"`;
+console.log('DEBUG mode result:', result1.stdout.trim());
+
+const result2 = await $debug`echo "Command 2"`;
+console.log('DEBUG mode result:', result2.stdout.trim());
+
+const result3 = await $debug`echo "Command 3"`;
+console.log('DEBUG mode result:', result3.stdout.trim());

package/js/examples/syntax-silent-operations.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+// Silent operations (no mirror to stdout) using $({ options })
+
+import { $ } from '../src/$.mjs';
+
+console.log('Silent operation:');
+const $silent = $({ mirror: false });
+const result = await $silent`echo "This won't appear in terminal"`;
+console.log('Captured output:', result.stdout.trim());

package/js/examples/syntax-stdin-option.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+// stdin option verification
+
+import { $ } from '../src/$.mjs';
+
+console.log('Verifying stdin option...');
+
+const $stdin = $({ stdin: 'input\n' });
+const result = await $stdin`cat`;
+console.assert(result.stdout === 'input\n', 'stdin option failed');
+console.log('✓ stdin option works');

package/js/examples/temp-sigint-test.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+// Temporary test file for SIGINT handling - can be used for debugging user signal handlers
+
+import { $ } from '../src/$.mjs';
+
+let sigintReceived = false;
+
+process.on('SIGINT', () => {
+  sigintReceived = true;
+  console.log('USER_SIGINT_HANDLER_CALLED');
+  process.exit(42); // Custom exit code to verify user handler was called
+});
+
+console.log('Process started, waiting for SIGINT...');
+
+// Wait for SIGINT (simulate doing some work without child processes)
+setTimeout(() => {
+  console.log('TIMEOUT_REACHED');
+  process.exit(1); // Should not reach here in test
+}, 10000);

package/js/examples/test-actual-buildshell.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+// Test the actual buildShellCommand from command-stream
+import { $ } from '../src/$.mjs';
+
+// Enable verbose to see buildShellCommand traces
+process.env.COMMAND_STREAM_VERBOSE = 'true';
+
+console.log('=== Testing Actual buildShellCommand ===');
+
+console.log('\n--- Case 1: $`echo hello` ---');
+try {
+  const result1 = await $`echo hello`;
+  console.log(`✓ Result: "${result1.stdout.toString().trim()}"`);
+} catch (error) {
+  console.log(`✗ Error: ${error.message}`);
+}
+
+console.log('\n--- Case 2: $`${cmd}` where cmd="echo hello" ---');
+const cmd = 'echo hello';
+try {
+  const result2 = await $`${cmd}`;
+  console.log(`✓ Result: "${result2.stdout.toString().trim()}"`);
+} catch (error) {
+  console.log(`✗ Error: ${error.message}`);
+}
+
+console.log('\n--- Case 3: $`echo ${arg}` where arg="hello" ---');
+const arg = 'hello';
+try {
+  const result3 = await $`echo ${arg}`;
+  console.log(`✓ Result: "${result3.stdout.toString().trim()}"`);
+} catch (error) {
+  console.log(`✗ Error: ${error.message}`);
+}
+
+console.log('\n--- Case 4: Pipeline $`${pipeline}` ---');
+const pipeline = 'echo hello | wc -w';
+try {
+  const result4 = await $`${pipeline}`;
+  console.log(`✓ Result: "${result4.stdout.toString().trim()}"`);
+} catch (error) {
+  console.log(`✗ Error: ${error.message}`);
+}

package/js/examples/test-async-streams-working.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Test async streams with commands that wait ===');
+
+async function testAsyncStreamsWorking() {
+  try {
+    console.log('TEST 1: Node.js script that waits for input');
+
+    const nodeCmd = $`node -e "process.stdin.setEncoding('utf8'); let input = ''; process.stdin.on('data', chunk => input += chunk); process.stdin.on('end', () => process.stdout.write('Got: ' + input.trim()));"`;
+
+    console.log('Awaiting stdin for Node.js script...');
+    const nodeStdin = await nodeCmd.streams.stdin;
+    console.log('✓ Node stdin available:', !!nodeStdin);
+
+    if (nodeStdin) {
+      nodeStdin.write('Node.js input test');
+      nodeStdin.end();
+    }
+
+    const nodeResult = await nodeCmd;
+    console.log('✓ Node result:', JSON.stringify(nodeResult.stdout));
+
+    console.log('\\nTEST 2: Python script that waits for input');
+
+    const pythonCmd = $`python3 -c "import sys; data = sys.stdin.read(); print('Python got:', data.strip())"`;
+
+    const pythonStdin = await pythonCmd.streams.stdin;
+    console.log('✓ Python stdin available:', !!pythonStdin);
+
+    if (pythonStdin) {
+      pythonStdin.write('Python input test\\n');
+      pythonStdin.end();
+    }
+
+    const pythonResult = await pythonCmd;
+    console.log('✓ Python result:', JSON.stringify(pythonResult.stdout));
+
+    console.log('\\nTEST 3: bc calculator (interactive)');
+
+    const bcCmd = $`bc -l`;
+    const bcStdin = await bcCmd.streams.stdin;
+    console.log('✓ bc stdin available:', !!bcStdin);
+
+    if (bcStdin) {
+      bcStdin.write('2 + 3\\n');
+      bcStdin.write('10 * 5\\n');
+      bcStdin.write('quit\\n');
+    }
+
+    const bcResult = await bcCmd;
+    console.log('✓ bc result:', JSON.stringify(bcResult.stdout));
+
+    console.log('\\nTEST 4: Demonstrate immediate vs promise behavior');
+
+    const immediateCmd = $`cat`;
+    // Start the process manually first
+    immediateCmd.start({
+      mode: 'async',
+      stdin: 'pipe',
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+
+    // Wait for it to spawn
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    // Now access should be immediate (not a promise)
+    const immediateStdin = immediateCmd.streams.stdin;
+    const isPromise = immediateStdin instanceof Promise;
+    console.log('✓ Immediate access is promise?', isPromise);
+
+    if (!isPromise && immediateStdin) {
+      immediateStdin.write('Immediate access test\\n');
+      immediateStdin.end();
+    } else if (isPromise) {
+      const stdin = await immediateStdin;
+      if (stdin) {
+        stdin.write('Promise-based access\\n');
+        stdin.end();
+      }
+    }
+
+    const immediateResult = await immediateCmd;
+    console.log(
+      '✓ Immediate test result:',
+      JSON.stringify(immediateResult.stdout)
+    );
+
+    console.log('\\n🎉 CONCLUSIONS:');
+    console.log('  ✅ await cmd.streams.stdin works for interactive commands');
+    console.log('  ✅ Returns immediate stream if process already spawned');
+    console.log('  ✅ Returns promise if process not yet spawned');
+    console.log('  ✅ Much cleaner API than manual timing');
+  } catch (error) {
+    console.log('\\n❌ Error:', error.message);
+    console.error(error.stack);
+  }
+}
+
+testAsyncStreamsWorking();