command-stream 0.8.2 → 0.9.0

package/js/examples/git-operations-with-cd.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+import { $, shell, enableVirtualCommands } from '../src/$.mjs';
+import { mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+// Enable virtual commands including cd
+enableVirtualCommands();
+shell.verbose(true);
+
+console.log('=== Git Operations with cd Virtual Command Examples ===\n');
+
+async function example1_BasicGitWorkflow() {
+  console.log('Example 1: Basic Git Workflow with cd\n');
+
+  const tempDir = mkdtempSync(join(tmpdir(), 'git-example-'));
+  const originalCwd = process.cwd();
+
+  try {
+    // Navigate to temp directory and initialize git
+    await $`cd ${tempDir}`;
+    await $`git init`;
+    await $`git config user.email "example@test.com"`;
+    await $`git config user.name "Example User"`;
+
+    // Create and commit a file
+    await $`echo "# My Project" > README.md`;
+    await $`git add README.md`;
+    await $`git commit -m "Initial commit"`;
+
+    // Show the log
+    await $`git log --oneline`;
+
+    // Return to original directory
+    await $`cd ${originalCwd}`;
+
+    console.log(`✓ Successfully created git repo in ${tempDir}\n`);
+  } catch (error) {
+    console.error('Error:', error.message);
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+async function example2_MultipleTempRepos() {
+  console.log('Example 2: Working with Multiple Temp Repositories\n');
+
+  const repo1 = mkdtempSync(join(tmpdir(), 'repo1-'));
+  const repo2 = mkdtempSync(join(tmpdir(), 'repo2-'));
+  const originalCwd = process.cwd();
+
+  try {
+    // Initialize first repository
+    await $`cd ${repo1} && git init && git config user.email "repo1@test.com"`;
+    await $`cd ${repo1} && echo "Repo 1 Content" > file.txt`;
+    await $`cd ${repo1} && git add . && git commit -m "Repo 1 commit"`;
+
+    // Initialize second repository
+    await $`cd ${repo2} && git init && git config user.email "repo2@test.com"`;
+    await $`cd ${repo2} && echo "Repo 2 Content" > file.txt`;
+    await $`cd ${repo2} && git add . && git commit -m "Repo 2 commit"`;
+
+    // Check both repositories
+    console.log('Repo 1 log:');
+    await $`cd ${repo1} && git log --oneline`;
+
+    console.log('\nRepo 2 log:');
+    await $`cd ${repo2} && git log --oneline`;
+
+    await $`cd ${originalCwd}`;
+
+    console.log('✓ Successfully managed multiple repositories\n');
+  } catch (error) {
+    console.error('Error:', error.message);
+  } finally {
+    rmSync(repo1, { recursive: true, force: true });
+    rmSync(repo2, { recursive: true, force: true });
+  }
+}
+
+async function example3_BranchingWorkflow() {
+  console.log('Example 3: Git Branching Workflow\n');
+
+  const tempDir = mkdtempSync(join(tmpdir(), 'branch-example-'));
+  const originalCwd = process.cwd();
+
+  try {
+    // Setup repository
+    await $`cd ${tempDir}`;
+    await $`git init`;
+    await $`git config user.email "branch@test.com"`;
+    await $`git config user.name "Branch Example"`;
+
+    // Create initial commit
+    await $`echo "Initial content" > main.txt`;
+    await $`git add .`;
+    await $`git commit -m "Initial commit"`;
+
+    // Create and switch to feature branch
+    await $`git checkout -b feature-branch`;
+    await $`echo "Feature content" > feature.txt`;
+    await $`git add .`;
+    await $`git commit -m "Add feature"`;
+
+    // Show branch info
+    const currentBranch = await $`git branch --show-current`;
+    console.log(`Current branch: ${currentBranch.stdout.trim()}`);
+
+    // List all branches
+    await $`git branch -a`;
+
+    // Switch back to main/master
+    const mainBranch =
+      await $`git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "master"`;
+    await $`git checkout ${mainBranch.stdout.trim() || 'master'}`;
+
+    await $`cd ${originalCwd}`;
+
+    console.log('✓ Branching workflow completed\n');
+  } catch (error) {
+    console.error('Error:', error.message);
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+async function example4_GitDiffWorkflow() {
+  console.log('Example 4: Git Diff and Status Workflow\n');
+
+  const tempDir = mkdtempSync(join(tmpdir(), 'diff-example-'));
+  const originalCwd = process.cwd();
+
+  try {
+    // Use cd chains for all operations
+    await $`cd ${tempDir} && git init`;
+    await $`cd ${tempDir} && git config user.email "diff@test.com"`;
+    await $`cd ${tempDir} && git config user.name "Diff Example"`;
+
+    // Create initial commit
+    await $`cd ${tempDir} && echo "Line 1" > file.txt`;
+    await $`cd ${tempDir} && git add . && git commit -m "Initial"`;
+
+    // Make changes
+    await $`cd ${tempDir} && echo "Line 2" >> file.txt`;
+
+    // Show status
+    console.log('Git status:');
+    await $`cd ${tempDir} && git status --short`;
+
+    // Show diff
+    console.log('\nGit diff:');
+    await $`cd ${tempDir} && git diff`;
+
+    // Stage and commit changes
+    await $`cd ${tempDir} && git add . && git commit -m "Add line 2"`;
+
+    // Show final log
+    await $`cd ${tempDir} && git log --oneline`;
+
+    await $`cd ${originalCwd}`;
+
+    console.log('✓ Diff workflow completed\n');
+  } catch (error) {
+    console.error('Error:', error.message);
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+// Run all examples
+async function runExamples() {
+  try {
+    await example1_BasicGitWorkflow();
+    await example2_MultipleTempRepos();
+    await example3_BranchingWorkflow();
+    await example4_GitDiffWorkflow();
+
+    console.log('=== All Git Examples Completed Successfully ===');
+  } catch (error) {
+    console.error('Failed to run examples:', error);
+    process.exit(1);
+  }
+}
+
+runExamples();

package/js/examples/interactive-math-calc.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+// Interactive math calculator for testing streaming I/O
+// Reads expressions from stdin, evaluates them, and writes results to stdout
+// Send "exit" or "\q" to quit
+
+import readline from 'readline';
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+  terminal: false, // Don't treat as TTY
+});
+
+console.log('READY'); // Signal that calculator is ready
+
+rl.on('line', (line) => {
+  const input = line.trim();
+
+  // Check for exit commands
+  if (input === 'exit' || input === '\\q' || input === 'quit') {
+    console.log('GOODBYE');
+    process.exit(0);
+  }
+
+  // Try to evaluate the math expression
+  try {
+    // Parse simple math expressions like "1+2", "3*4", "10/2", "5-3"
+    const result = eval(input); // Using eval for simplicity in test
+    console.log(`RESULT: ${result}`);
+  } catch (error) {
+    console.error(`ERROR: Invalid expression: ${input}`);
+  }
+});
+
+// Handle stdin close
+rl.on('close', () => {
+  process.exit(0);
+});
+
+// Ensure output is not buffered
+process.stdout.setDefaultEncoding('utf8');
+if (process.stdout._handle && process.stdout._handle.setBlocking) {
+  process.stdout._handle.setBlocking(true);
+}

package/js/examples/interactive-top-fixed.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Fixed Interactive top command ===');
+console.log('This version properly handles:');
+console.log('- Interactive keyboard input (q to quit)');
+console.log('- ANSI colors and formatting');
+console.log('- Terminal control sequences');
+console.log('- Proper stdin/stdout forwarding');
+console.log('\nStarting top... Press q to quit when ready.\n');
+
+// Use direct spawn with proper TTY settings for true interactivity
+const proc = $`top`.run({
+  stdin: 'inherit', // Forward stdin directly
+  mirror: false, // Don't mirror - we want direct terminal output
+});
+
+// Handle process completion
+proc.on('end', (result) => {
+  console.log(`\n=== top exited with code: ${result.code} ===`);
+});
+
+// Start the process and wait for it to complete
+await proc;

package/js/examples/interactive-top-improved.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import { ProcessRunner } from '../src/$.mjs';
+import { spawn } from 'child_process';
+
+console.log('=== Improved Interactive top with command-stream ===');
+console.log('This version fixes TTY handling while using command-stream');
+console.log('- Keyboard input works (q to quit)');
+console.log('- ANSI colors preserved');
+console.log('- Proper terminal interaction');
+console.log('\nChoose your preferred method:\n');
+
+console.log('Method 1: Direct Node.js spawn (most reliable)');
+console.log('Method 2: Enhanced ProcessRunner with TTY support');
+console.log('Method 3: Command-stream with proper stdin settings\n');
+
+const method = process.argv[2] || '1';
+
+switch (method) {
+  case '1':
+    console.log('Using Method 1: Direct spawn...\n');
+    const proc = spawn('top', [], {
+      stdio: 'inherit',
+      env: process.env,
+    });
+    proc.on('close', (code) => {
+      console.log(`\n=== top exited with code: ${code} ===`);
+    });
+    break;
+
+  case '2':
+    console.log('Using Method 2: Enhanced ProcessRunner...\n');
+    const runner = new ProcessRunner(
+      { mode: 'shell', command: 'top' },
+      {
+        stdin: 'inherit',
+        mirror: true,
+        capture: false,
+        tty: true, // Request TTY mode if supported
+      }
+    );
+
+    await runner.start();
+    break;
+
+  case '3':
+    console.log('Using Method 3: Command-stream with settings...\n');
+
+    // Set raw mode on stdin to forward keystrokes immediately
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+      process.stdin.resume();
+    }
+
+    const proc3 = spawn('top', [], {
+      stdio: [process.stdin, process.stdout, process.stderr],
+      env: process.env,
+    });
+
+    proc3.on('close', (code) => {
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(false);
+      }
+      console.log(`\n=== top exited with code: ${code} ===`);
+    });
+    break;
+
+  default:
+    console.log(
+      'Invalid method. Use: node interactive-top-improved.mjs [1|2|3]'
+    );
+}

package/js/examples/interactive-top-pty-logging.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// Get the directory where this script is located
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const logPath = path.join(__dirname, 'top-pty-session.log');
+
+console.log('=== Interactive top with PTY logging ===');
+console.log('This demonstrates interactive mode with proper output capture');
+console.log('- top runs interactively (q to quit)');
+console.log(`- All output is logged to ${logPath}`);
+console.log('- Uses pseudo-terminal for proper capture');
+console.log('\nStarting top... Press q to quit when ready.\n');
+
+const logStream = fs.createWriteStream(logPath, { flags: 'a' });
+logStream.write(
+  `\n=== Top PTY session started at ${new Date().toISOString()} ===\n`
+);
+
+// The issue: automatic interactive detection uses stdio: 'inherit' which prevents output capture
+// For now, we need to use a non-interactive command to demonstrate logging
+// Using 'top -l 3' (3 iterations) instead of interactive top
+console.log(
+  'Note: Using top -l 3 (3 iterations) to demonstrate logging capability'
+);
+console.log(
+  'Interactive top with logging requires PTY support which is not yet implemented\n'
+);
+
+const proc = $`top -l 3`;
+
+let outputSize = 0;
+
+// Log all stdout data to file
+proc.on('stdout', (chunk) => {
+  // Log raw data (with ANSI codes) to file
+  logStream.write(chunk);
+  outputSize += chunk.length;
+
+  // Log progress
+  console.log(
+    `[LOG] Captured ${chunk.length} bytes (total: ${outputSize} bytes)`
+  );
+});
+
+// Log stderr if any
+proc.on('stderr', (chunk) => {
+  logStream.write(`[STDERR] ${chunk}`);
+  console.log(`[LOG] Captured ${chunk.length} bytes of stderr`);
+});
+
+// Handle process completion
+proc.on('end', (result) => {
+  logStream.write(
+    `\n=== Top PTY session ended with code: ${result.code} at ${new Date().toISOString()} ===\n`
+  );
+  logStream.end();
+  console.log(`\n=== Session logged to ${logPath} ===`);
+  console.log(`=== Total output captured: ${outputSize} bytes ===`);
+  console.log(`=== top exited with code: ${result.code} ===`);
+});
+
+// Start the process
+await proc;

package/js/examples/interactive-top-pty.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+import { spawn } from 'child_process';
+
+console.log('=== Truly Interactive top command ===');
+console.log(
+  'This version uses direct spawn with stdio: "inherit" for full TTY support'
+);
+console.log('- Keyboard input works (q to quit, space to refresh, etc.)');
+console.log('- ANSI colors and formatting preserved');
+console.log('- Full terminal interaction');
+console.log('\nStarting top... Press q to quit when ready.\n');
+
+// Use Node.js spawn directly with stdio: 'inherit' for true TTY forwarding
+const topProcess = spawn('top', [], {
+  stdio: 'inherit', // This forwards stdin, stdout, stderr directly to/from terminal
+  cwd: process.cwd(),
+  env: process.env,
+});
+
+topProcess.on('close', (code) => {
+  console.log(`\n=== top exited with code: ${code} ===`);
+});
+
+topProcess.on('error', (error) => {
+  console.error('Error starting top:', error.message);
+});

package/js/examples/interactive-top-with-logging.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// Get the directory where this script is located
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const logPath = path.join(__dirname, 'top-session.log');
+
+console.log('=== Interactive top with logging ===');
+console.log(
+  'This demonstrates interactive mode while logging all output to files'
+);
+console.log('- top runs interactively (q to quit)');
+console.log(`- All output is logged to ${logPath}`);
+console.log('- All input can be captured too');
+console.log('\nStarting top... Press q to quit when ready.\n');
+
+const logStream = fs.createWriteStream(logPath, { flags: 'a' });
+logStream.write(
+  `\n=== Top session started at ${new Date().toISOString()} ===\n`
+);
+
+// Start top - it will run interactively
+const proc = $`top`;
+
+// Log all stdout data to file while maintaining interactivity
+proc.on('stdout', (chunk) => {
+  // Log raw data (with ANSI codes) to file
+  logStream.write(chunk);
+
+  // Also log processed data for debugging
+  console.log(`[LOG] Captured ${chunk.length} bytes of stdout`);
+});
+
+// Log stderr if any
+proc.on('stderr', (chunk) => {
+  logStream.write(`[STDERR] ${chunk}`);
+  console.log(`[LOG] Captured ${chunk.length} bytes of stderr`);
+});
+
+// Handle process completion
+proc.on('end', (result) => {
+  logStream.write(
+    `\n=== Top session ended with code: ${result.code} at ${new Date().toISOString()} ===\n`
+  );
+  logStream.end();
+  console.log(`\n=== Session logged to ${logPath} ===`);
+  console.log(`=== top exited with code: ${result.code} ===`);
+});
+
+// Start the process
+await proc;

package/js/examples/interactive-top.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log(
+  '=== Interactive top command (preserves ANSI colors and interactive controls) ==='
+);
+console.log('This will run top interactively. Press q to quit when ready.\n');
+
+// Start top in interactive mode - it should work automatically
+const proc = $`top`;
+
+// Forward all stdout to terminal (preserving colors and formatting)
+proc.on('stdout', (chunk) => {
+  process.stdout.write(chunk);
+});
+
+// Forward stderr if any
+proc.on('stderr', (chunk) => {
+  process.stderr.write(chunk);
+});
+
+// Handle process completion
+proc.on('end', (result) => {
+  console.log(`\n=== top exited with code: ${result.code} ===`);
+});
+
+// Start the process
+await proc;

package/js/examples/jq-color-demo.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== jq Color Output Demo ===\n');
+
+const testJson =
+  '{"message": "Hello World", "number": 42, "active": true, "nested": {"data": [1, 2, 3], "flag": false}}';
+
+console.log(
+  'This demo shows how to get colored jq output with command-stream.\n'
+);
+
+console.log(
+  '1. Default behavior (mirror: true means output appears automatically):'
+);
+console.log('   Code: await $`echo ${testJson} | jq .`');
+console.log('   Output:');
+await $`echo ${testJson} | jq .`;
+
+console.log('\n2. Force colors even in non-TTY environments with -C flag:');
+console.log('   Code: await $`echo ${testJson} | jq -C .`');
+console.log('   Output (with ANSI color codes):');
+await $`echo ${testJson} | jq -C .`;
+
+console.log('\n3. Extract specific field with colors:');
+console.log('   Code: await $`echo ${testJson} | jq -C .nested`');
+console.log('   Output:');
+await $`echo ${testJson} | jq -C .nested`;
+
+console.log('\n4. No need for console.log - output is automatically mirrored!');
+console.log('   The beauty of command-stream is that with default settings,');
+console.log('   you get shell-like behavior: output appears immediately.');
+
+console.log('\n5. Capture-only mode (no automatic output):');
+console.log(
+  '   Code: const result = await $({ mirror: false })`echo ${testJson} | jq -C .message`'
+);
+const result = await $({ mirror: false })`echo ${testJson} | jq -C .message`;
+console.log('   Captured result:', JSON.stringify(result.stdout.trim()));
+
+console.log('\n6. Best of both worlds (mirror + capture):');
+console.log(
+  '   Code: const result = await $`echo ${testJson} | jq -C -r .message`'
+);
+const result2 = await $`echo ${testJson} | jq -C -r .message`;
+console.log('   Also captured:', JSON.stringify(result2.stdout.trim()));
+
+console.log('\n✅ Summary:');
+console.log('- Use jq -C for forced colors (works in any environment)');
+console.log('- Default mirror:true means no manual console.log needed');
+console.log('- Colors work great with command-stream piping');
+console.log('- In real TTY environments, jq colors automatically!');

package/js/examples/jq-colors-streaming.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== jq Streaming with ANSI Colors ===\n');
+
+console.log('Test 1: JSON streaming with colors (using --color-output):');
+const coloredCmd = $`printf '{"name":"Alice","status":"active","score":95}\n{"name":"Bob","status":"inactive","score":87}\n{"name":"Carol","status":"active","score":92}\n' | jq --color-output .`;
+
+console.log('Streaming colored JSON:');
+coloredCmd.on('stdout', (chunk) => {
+  // Display raw colored output
+  process.stdout.write(chunk);
+});
+
+await coloredCmd;
+
+console.log('\nTest 2: Compact colored streaming:');
+const compactCmd = $`printf '{"user":"Alice","data":{"x":1,"y":2}}\n{"user":"Bob","data":{"x":3,"y":4}}\n' | jq --color-output -c '.user + ": " + (.data.x + .data.y | tostring)'`;
+
+compactCmd.on('stdout', (chunk) => {
+  process.stdout.write('> ');
+  process.stdout.write(chunk);
+});
+
+await compactCmd;
+
+console.log('\nTest 3: Interactive-style filtering with colors:');
+const filterCmd = $`printf '{"type":"user","name":"Alice"}\n{"type":"admin","name":"Bob"}\n{"type":"user","name":"Carol"}\n' | jq --color-output 'select(.type == "user")'`;
+
+console.log('Filtered users (colored):');
+filterCmd.on('stdout', (chunk) => {
+  process.stdout.write(chunk);
+});
+
+await filterCmd;
+
+console.log('\n=== Results ===');
+console.log('✅ ANSI colors preserved in jq pipelines');
+console.log('✅ Real-time streaming with color support');
+console.log('✅ Use --color-output to force colors in pipelines');
+console.log('✅ Colors work even when not connected to terminal');

package/js/examples/manual-ctrl-c-test.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+// Manual test for CTRL+C handling
+// Run this script and press CTRL+C to test signal propagation
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Manual CTRL+C Test ===\n');
+console.log('This script will run ping continuously.');
+console.log('Press CTRL+C to interrupt and see if it properly terminates.\n');
+console.log('Starting ping to 8.8.8.8...');
+console.log('----------------------------------------\n');
+
+// Track if we received SIGINT
+let parentGotSigint = false;
+let sigintCount = 0;
+process.on('SIGINT', () => {
+  sigintCount++;
+  console.log(`\n[PARENT] Received SIGINT signal (count: ${sigintCount})`);
+  parentGotSigint = true;
+
+  // Exit on second CTRL+C (user really wants to quit)
+  if (sigintCount >= 2) {
+    console.log('[PARENT] Exiting after second CTRL+C');
+    process.exit(130);
+  }
+});
+
+// Clean exit handler
+process.on('exit', (code) => {
+  console.log(`\n[PARENT] Exiting with code: ${code}`);
+  console.log(`Parent received SIGINT: ${parentGotSigint}`);
+});
+
+try {
+  // Run ping with default settings (stdin: 'inherit')
+  const result = await $`ping 8.8.8.8`;
+  console.log('\nPing completed normally (unexpected)');
+} catch (error) {
+  console.log('\n----------------------------------------');
+  console.log('Command was interrupted!');
+  console.log(`Exit code: ${error.code}`);
+  console.log(`Error message: ${error.message}`);
+
+  if (error.code === 130 || error.code === -2 || error.code === 2) {
+    console.log('✓ SUCCESS: Received expected SIGINT exit code');
+  } else {
+    console.log(`⚠ WARNING: Unexpected exit code ${error.code}`);
+  }
+}

package/js/examples/methods-multiple-options.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+// Both .start() and .run() support all the same options
+
+import { $ } from '../src/$.mjs';
+
+console.log('Both support all the same options:');
+
+// Test with multiple options using .start()
+console.log('.start() with multiple options:');
+const startResult = await $`cat`.start({
+  stdin: 'Input for start method',
+  capture: true,
+  mirror: false,
+});
+console.log(`Output: ${JSON.stringify(startResult.stdout)}`);
+
+// Test with multiple options using .run()
+console.log('\n.run() with multiple options:');
+const runResult = await $`cat`.run({
+  stdin: 'Input for run method',
+  capture: true,
+  mirror: false,
+});
+console.log(`Output: ${JSON.stringify(runResult.stdout)}`);