command-stream 0.8.2 → 0.9.0

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

@@ -0,0 +1,125 @@
+#!/usr/bin/env bun
+
+import { $, register } from '../src/$.mjs';
+
+console.log('=== Testing Virtual Command Streaming ===\n');
+
+// Register a streaming virtual command that generates data incrementally
+register('stream-numbers', async function* ({ args, stdin }) {
+  const count = parseInt(args[0] || '3');
+  const delay = parseInt(args[1] || '500');
+
+  for (let i = 1; i <= count; i++) {
+    yield `{"number": ${i}}\n`;
+    if (i < count) {
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+});
+
+// Register a virtual filter command
+register('filter-even', async function* ({ args, stdin }) {
+  const lines = stdin.trim().split('\n');
+  for (const line of lines) {
+    try {
+      const obj = JSON.parse(line);
+      if (obj.number && obj.number % 2 === 0) {
+        yield `${line}\n`;
+      }
+    } catch (e) {
+      // Skip invalid JSON
+    }
+  }
+});
+
+// Test 1: Virtual command alone with streaming
+console.log('Test 1: Virtual streaming command alone:');
+console.log('Should output 3 numbers with 300ms delays:\n');
+const start1 = Date.now();
+
+for await (const chunk of $`stream-numbers 3 300`.stream()) {
+  if (chunk.type === 'stdout') {
+    const elapsed = Date.now() - start1;
+    const data = chunk.data.toString().trim();
+    if (data) {
+      console.log(`[${elapsed}ms] ${data}`);
+    }
+  }
+}
+
+console.log('\n✅ Test 1 complete\n');
+
+// Test 2: Virtual command piped to real command
+console.log('Test 2: Virtual -> Real command pipeline:');
+console.log('Stream numbers through jq:\n');
+const start2 = Date.now();
+
+for await (const chunk of $`stream-numbers 3 200 | jq -c '.number *= 2'`.stream()) {
+  if (chunk.type === 'stdout') {
+    const elapsed = Date.now() - start2;
+    const data = chunk.data.toString().trim();
+    if (data) {
+      console.log(`[${elapsed}ms] ${data}`);
+    }
+  }
+}
+
+console.log('\n✅ Test 2 complete\n');
+
+// Test 3: Real command piped to virtual command
+console.log('Test 3: Real -> Virtual command pipeline:');
+console.log('Generate numbers with shell, filter with virtual command:\n');
+const start3 = Date.now();
+
+const cmd3 = $`sh -c 'for i in 1 2 3 4 5; do echo "{\\"number\\": $i}"; done' | filter-even`;
+
+for await (const chunk of cmd3.stream()) {
+  if (chunk.type === 'stdout') {
+    const elapsed = Date.now() - start3;
+    const data = chunk.data.toString().trim();
+    if (data) {
+      console.log(`[${elapsed}ms] ${data}`);
+    }
+  }
+}
+
+console.log('\n✅ Test 3 complete\n');
+
+// Test 4: Mixed pipeline with multiple stages
+console.log('Test 4: Virtual -> Real -> Virtual pipeline:');
+console.log('Stream numbers, transform with jq, filter with virtual:\n');
+const start4 = Date.now();
+
+const cmd4 = $`stream-numbers 5 150 | jq -c '{value: .number, double: (.number * 2)}' | filter-even`;
+
+// Note: filter-even will only work on objects with 'number' field,
+// so let's create a better filter
+register('filter-double-even', async function* ({ args, stdin }) {
+  const lines = stdin.trim().split('\n');
+  for (const line of lines) {
+    try {
+      const obj = JSON.parse(line);
+      if (obj.double && obj.double % 4 === 0) {
+        yield `${line}\n`;
+      }
+    } catch (e) {
+      // Skip invalid JSON
+    }
+  }
+});
+
+const cmd4Fixed = $`stream-numbers 5 150 | jq -c '{value: .number, double: (.number * 2)}' | filter-double-even`;
+
+for await (const chunk of cmd4Fixed.stream()) {
+  if (chunk.type === 'stdout') {
+    const elapsed = Date.now() - start4;
+    const data = chunk.data.toString().trim();
+    if (data) {
+      console.log(`[${elapsed}ms] ${data}`);
+    }
+  }
+}
+
+console.log('\n✅ Test 4 complete\n');
+
+console.log('🎉 All virtual streaming tests passed!');

package/js/examples/test-waiting-command.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+async function testWaitingCommand() {
+  console.log('🧪 Testing with command that truly waits');
+
+  // Use a command that definitely waits for input
+  const nodeCmd = $`node -e "process.stdin.on('data', d => process.stdout.write('Got: ' + d)); process.stdin.on('end', () => process.exit(0));"`;
+  console.log('1. Created node stdin reader command');
+
+  await nodeCmd.start({
+    mode: 'async',
+    stdin: 'pipe',
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  console.log('2. Started command');
+
+  // Wait a bit for process to start
+  await new Promise((resolve) => setTimeout(resolve, 100));
+
+  console.log('3. After start:');
+  console.log('   started:', nodeCmd.started);
+  console.log('   child exists:', !!nodeCmd.child);
+  console.log('   finished:', nodeCmd.finished);
+
+  if (nodeCmd.child) {
+    console.log('   child.pid:', nodeCmd.child.pid);
+    console.log('   child.stdin exists:', !!nodeCmd.child.stdin);
+  }
+
+  // Try to access via streams
+  const stdin = await nodeCmd.streams.stdin;
+  console.log('4. Got stdin via streams:');
+  console.log('   type:', typeof stdin);
+  console.log('   has write:', !!(stdin && stdin.write));
+
+  if (stdin && stdin.write) {
+    console.log('5. Writing to stdin...');
+    stdin.write('Hello World\n');
+    stdin.end();
+
+    const result = await nodeCmd;
+    console.log('   Result:', JSON.stringify(result.stdout));
+  } else {
+    console.log('5. No writable stdin');
+    nodeCmd.kill();
+  }
+}
+
+testWaitingCommand();

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

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Commands that definitely wait for stdin ===');
+
+async function testWaitingCommands() {
+  try {
+    console.log('\\n1️⃣ cat with no arguments - waits for stdin');
+    const cmd1 = $`timeout 2 cat`; // Timeout as safety
+    const stdin1 = await cmd1.streams.stdin;
+    console.log('cat stdin type:', typeof stdin1);
+
+    if (stdin1 && stdin1.write) {
+      stdin1.write('Hello cat!\\n');
+      stdin1.end();
+    }
+
+    const result1 = await cmd1;
+    console.log('cat result:', JSON.stringify(result1.stdout));
+
+    console.log('\\n2️⃣ sort with no arguments - waits for stdin');
+    const cmd2 = $`timeout 2 sort`;
+    const stdin2 = await cmd2.streams.stdin;
+    console.log('sort stdin type:', typeof stdin2);
+
+    if (stdin2 && stdin2.write) {
+      stdin2.write('zebra\\n');
+      stdin2.write('apple\\n');
+      stdin2.end();
+    }
+
+    const result2 = await cmd2;
+    console.log('sort result:', JSON.stringify(result2.stdout));
+
+    console.log('\\n3️⃣ wc (word count) - waits for stdin');
+    const cmd3 = $`timeout 2 wc -l`;
+    const stdin3 = await cmd3.streams.stdin;
+    console.log('wc stdin type:', typeof stdin3);
+
+    if (stdin3 && stdin3.write) {
+      stdin3.write('line 1\\n');
+      stdin3.write('line 2\\n');
+      stdin3.end();
+    }
+
+    const result3 = await cmd3;
+    console.log('wc result:', JSON.stringify(result3.stdout));
+
+    console.log('\\n4️⃣ head -n 1 - waits for stdin, takes first line');
+    const cmd4 = $`timeout 2 head -n 1`;
+    const stdin4 = await cmd4.streams.stdin;
+    console.log('head stdin type:', typeof stdin4);
+
+    if (stdin4 && stdin4.write) {
+      stdin4.write('first line\\n');
+      stdin4.write('second line\\n');
+      stdin4.end();
+    }
+
+    const result4 = await cmd4;
+    console.log('head result:', JSON.stringify(result4.stdout));
+
+    console.log('\\n5️⃣ Node.js process.stdin - definitely waits');
+    const cmd5 = $`node -e "process.stdin.setEncoding('utf8'); process.stdin.on('data', d => process.stdout.write('Got: ' + d)); process.stdin.on('end', () => process.exit(0));"`;
+
+    const stdin5 = await cmd5.streams.stdin;
+    console.log('node stdin type:', typeof stdin5);
+
+    if (stdin5 && stdin5.write) {
+      stdin5.write('Node test\\n');
+      stdin5.end();
+    }
+
+    const result5 = await cmd5;
+    console.log('node result:', JSON.stringify(result5.stdout));
+  } catch (error) {
+    console.error('Error:', error.message);
+    console.error(error.stack);
+  }
+}
+
+testWaitingCommands();

package/js/examples/test-watch-mode.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+import { promises as fs } from 'fs';
+import { spawn } from 'child_process';
+import os from 'os';
+import path from 'path';
+
+console.log('=== Testing watch mode ===\n');
+
+// Start the watch process in background
+console.log('Starting watch process...');
+const watchProcess = spawn(
+  'node',
+  ['claude-profiles.mjs', '--watch', 'test-watch', '--verbose'],
+  {
+    stdio: 'pipe',
+    env: process.env,
+  }
+);
+
+let output = '';
+watchProcess.stdout.on('data', (data) => {
+  const text = data.toString();
+  output += text;
+  process.stdout.write(text);
+});
+
+watchProcess.stderr.on('data', (data) => {
+  const text = data.toString();
+  output += text;
+  process.stderr.write(text);
+});
+
+// Wait for initial save
+console.log('\nWaiting for initial state...');
+await new Promise((resolve) => setTimeout(resolve, 3000));
+
+// Make a change to trigger save
+console.log('\nMaking a change to .claude.json...');
+const claudeJsonPath = path.join(os.homedir(), '.claude.json');
+try {
+  const content = await fs.readFile(claudeJsonPath, 'utf8');
+  const json = JSON.parse(content);
+  json.test_timestamp = new Date().toISOString();
+  await fs.writeFile(claudeJsonPath, JSON.stringify(json, null, 2));
+  console.log('✅ Modified .claude.json');
+} catch (error) {
+  console.error('Failed to modify .claude.json:', error.message);
+}
+
+// Wait for save detection
+console.log('\nWaiting for change detection...');
+await new Promise((resolve) => setTimeout(resolve, 8000));
+
+// Check if save was detected
+if (output.includes('Profile auto-saved')) {
+  console.log('\n✅ Auto-save detected and completed');
+} else {
+  console.log('\n⚠️ Auto-save not detected in output');
+}
+
+// Make another change within throttle window
+console.log('\nMaking another change (within 30s throttle)...');
+try {
+  const content = await fs.readFile(claudeJsonPath, 'utf8');
+  const json = JSON.parse(content);
+  json.test_timestamp2 = new Date().toISOString();
+  await fs.writeFile(claudeJsonPath, JSON.stringify(json, null, 2));
+  console.log('✅ Modified .claude.json again');
+} catch (error) {
+  console.error('Failed to modify .claude.json:', error.message);
+}
+
+// Wait to see throttling
+console.log('\nWaiting to observe throttling...');
+await new Promise((resolve) => setTimeout(resolve, 5000));
+
+// Send SIGINT to test graceful shutdown
+console.log('\nSending SIGINT for graceful shutdown...');
+watchProcess.kill('SIGINT');
+
+// Wait for process to exit
+await new Promise((resolve) => {
+  watchProcess.on('exit', (code) => {
+    console.log(`\nWatch process exited with code: ${code}`);
+    resolve();
+  });
+});
+
+// Clean up test changes
+console.log('\nCleaning up test changes...');
+try {
+  const content = await fs.readFile(claudeJsonPath, 'utf8');
+  const json = JSON.parse(content);
+  delete json.test_timestamp;
+  delete json.test_timestamp2;
+  await fs.writeFile(claudeJsonPath, JSON.stringify(json, null, 2));
+  console.log('✅ Cleaned up .claude.json');
+} catch (error) {
+  console.error('Failed to clean up:', error.message);
+}
+
+console.log('\n=== Watch mode test complete ===');

package/js/examples/test-yes-cancellation.mjs

@@ -0,0 +1,26 @@
+import { $ } from '../src/$.mjs';
+
+console.log('Testing yes command cancellation...');
+
+const runner = $`yes "test output"`;
+let iterations = 0;
+const maxIterations = 5;
+
+console.log('Starting async iteration...');
+for await (const chunk of runner.stream()) {
+  iterations++;
+  console.log(`Iteration ${iterations}: received chunk`);
+  if (iterations >= maxIterations) {
+    console.log('Breaking from loop...');
+    break; // This MUST stop the yes command
+  }
+}
+
+console.log(`Finished: ${runner.finished}`);
+console.log(`Total iterations: ${iterations}`);
+
+// Wait a bit to ensure no more output
+await new Promise((resolve) => setTimeout(resolve, 100));
+
+console.log('Test complete');
+process.exit(0);

package/js/examples/test-yes-detailed.mjs

@@ -0,0 +1,58 @@
+import { $ } from '../src/$.mjs';
+
+console.log('Testing yes command cancellation in detail...');
+
+// Test 1: Direct generator usage
+console.log('\n=== Test 1: Direct generator test ===');
+import yesCommand from '../src/commands/$.yes.mjs';
+
+let cancelled = false;
+const abortController = new AbortController();
+const generator = yesCommand({
+  args: ['test'],
+  stdin: '',
+  isCancelled: () => cancelled,
+  signal: abortController.signal,
+});
+
+let count = 0;
+for await (const chunk of generator) {
+  count++;
+  console.log(`Direct iteration ${count}: ${chunk.trim()}`);
+  if (count >= 3) {
+    console.log('Setting cancelled=true and aborting...');
+    cancelled = true;
+    abortController.abort();
+    // Try to return the generator
+    if (generator.return) {
+      await generator.return();
+    }
+    break;
+  }
+}
+console.log(`Direct test finished, count=${count}`);
+
+// Test 2: Through command-stream
+console.log('\n=== Test 2: Through command-stream ===');
+const runner = $`yes "stream test"`;
+let iterations = 0;
+
+for await (const chunk of runner.stream()) {
+  iterations++;
+  console.log(`Stream iteration ${iterations}: got chunk`);
+  if (iterations >= 3) {
+    console.log('Breaking from stream...');
+    break;
+  }
+}
+
+console.log(
+  `Stream test finished: runner.finished=${runner.finished}, iterations=${iterations}`
+);
+
+// Wait to see if any more output comes
+console.log('\nWaiting 500ms to check for spurious output...');
+await new Promise((resolve) => setTimeout(resolve, 500));
+
+console.log('All tests complete');
+process.exit(0);

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

@@ -0,0 +1,28 @@
+import { $ } from '../src/$.mjs';
+
+console.log('Testing yes command stopping...');
+
+const runner = $({ mirror: false })`yes "test"`;
+let iterations = 0;
+
+console.log('Starting iteration...');
+for await (const chunk of runner.stream()) {
+  iterations++;
+  console.log(`Iteration ${iterations}`);
+
+  if (iterations >= 3) {
+    console.log('Breaking...');
+    break;
+  }
+}
+
+console.log(`Finished: ${runner.finished}`);
+console.log(`Total iterations: ${iterations}`);
+
+// Check if the runner is actually stopped
+console.log('\nWaiting 100ms...');
+await new Promise((resolve) => setTimeout(resolve, 100));
+
+console.log('Still finished:', runner.finished);
+
+process.exit(0);

package/js/examples/trace-abort-controller.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+/**
+ * AbortController Tracing Test
+ *
+ * Tests AbortController integration with tracing to debug external
+ * signal handling and virtual command cancellation.
+ *
+ * Usage:
+ *   COMMAND_STREAM_TRACE=ProcessRunner node js/examples/trace-abort-controller.mjs
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing AbortController with tracing...');
+
+const controller = new AbortController();
+const promise = $({ signal: controller.signal })`sleep 2`;
+
+setTimeout(() => {
+  console.log('🛑 Aborting with AbortController...');
+  controller.abort();
+}, 300);
+
+try {
+  const result = await promise;
+  console.log('✓ Virtual sleep result:', result.code);
+} catch (error) {
+  console.log('✓ Virtual sleep was aborted (expected):', error.message);
+}

package/js/examples/trace-error-handling.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+/**
+ * Error Handling Tracing Test
+ *
+ * Tests error conditions with tracing to debug error propagation,
+ * cleanup on failure, and exception handling.
+ *
+ * Usage:
+ *   COMMAND_STREAM_TRACE=ProcessRunner node js/examples/trace-error-handling.mjs
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing error handling with tracing...');
+
+try {
+  const result = await $`/nonexistent/command`;
+  console.log('✗ Should have failed');
+} catch (error) {
+  console.log('✓ Error caught (expected):', error.message);
+}

package/js/examples/trace-pipeline-command.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+/**
+ * Pipeline Command Tracing Test
+ *
+ * Tests pipeline command execution with tracing to debug command
+ * parsing, pipeline creation, and multi-process coordination.
+ *
+ * Usage:
+ *   COMMAND_STREAM_TRACE=ProcessRunner node js/examples/trace-pipeline-command.mjs
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing pipeline command with tracing...');
+
+const result = await $`echo "test data" | grep "test"`;
+console.log(
+  '✓ Pipeline result:',
+  result.code,
+  JSON.stringify(result.stdout.trim())
+);

package/js/examples/trace-signal-handling.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+/**
+ * Signal Handling Tracing Test
+ *
+ * Tests process killing and signal handling with tracing to debug
+ * SIGINT forwarding and cleanup operations.
+ *
+ * Usage:
+ *   COMMAND_STREAM_TRACE=ProcessRunner node js/examples/trace-signal-handling.mjs
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing signal handling with tracing...');
+
+const runner = $`sleep 3`;
+const promise = runner.start();
+
+setTimeout(() => {
+  console.log('🔪 Killing process with SIGINT...');
+  runner.kill('SIGINT');
+}, 500);
+
+try {
+  const result = await promise;
+  console.log('✓ Sleep result (killed):', result.code);
+} catch (error) {
+  console.log(
+    '✓ Sleep was interrupted (expected):',
+    error.message,
+    'code:',
+    error.code
+  );
+}

package/js/examples/trace-simple-command.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+/**
+ * Simple Command Tracing Test
+ *
+ * Tests basic command execution with tracing to debug process creation,
+ * stdout/stderr handling, and completion.
+ *
+ * Usage:
+ *   COMMAND_STREAM_TRACE=ProcessRunner node js/examples/trace-simple-command.mjs
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing simple command execution with tracing...');
+
+const result = await $`echo "Hello tracing"`;
+console.log('✓ Result:', result.code, JSON.stringify(result.stdout.trim()));

package/js/examples/trace-stderr-output.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+/**
+ * Stderr Output Tracing Test
+ *
+ * Tests stdout/stderr handling with tracing to debug stream pumping,
+ * data capture, and I/O operations.
+ *
+ * Usage:
+ *   COMMAND_STREAM_TRACE=ProcessRunner node js/examples/trace-stderr-output.mjs
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing stderr output with tracing...');
+
+const result =
+  await $`sh -c 'echo "stdout message" && echo "stderr message" >&2'`;
+
+console.log('✓ Command result:', result.code);
+console.log('  stdout:', JSON.stringify(result.stdout.trim()));
+console.log('  stderr:', JSON.stringify(result.stderr.trim()));