command-stream 0.8.2 → 0.9.0

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

@@ -0,0 +1,266 @@
+import { test, expect, describe, beforeEach } from 'bun:test';
+import './test-helper.mjs';
+import { $, raw, shell, disableVirtualCommands } from '../src/$.mjs';
+
+// Disable virtual commands for consistent system command behavior
+beforeEach(() => {
+  shell.errexit(false);
+  disableVirtualCommands();
+});
+
+describe('raw() function - Disable auto-escape', () => {
+  describe('basic functionality', () => {
+    test('should create raw object with string', () => {
+      const result = raw('test command');
+      expect(result).toEqual({ raw: 'test command' });
+    });
+
+    test('should convert numbers to string', () => {
+      expect(raw(123)).toEqual({ raw: '123' });
+    });
+
+    test('should convert boolean to string', () => {
+      expect(raw(true)).toEqual({ raw: 'true' });
+      expect(raw(false)).toEqual({ raw: 'false' });
+    });
+
+    test('should handle empty string', () => {
+      expect(raw('')).toEqual({ raw: '' });
+    });
+  });
+
+  describe('command execution with raw()', () => {
+    test('should execute simple raw command', async () => {
+      const cmd = raw('echo "hello world"');
+      const result = await $`${cmd}`;
+      expect(result.stdout.trim()).toBe('hello world');
+      expect(result.code).toBe(0);
+    });
+
+    test('should execute command with && operator', async () => {
+      const cmd = raw('echo "step1" && echo "step2"');
+      const result = await $`${cmd}`;
+      expect(result.stdout).toContain('step1');
+      expect(result.stdout).toContain('step2');
+      expect(result.code).toBe(0);
+    });
+
+    test('should execute command with || operator', async () => {
+      const cmd = raw('false || echo "fallback"');
+      const result = await $`${cmd}`;
+      expect(result.stdout.trim()).toBe('fallback');
+    });
+
+    test('should execute command with pipe', async () => {
+      const cmd = raw('echo "hello world" | wc -w');
+      const result = await $`${cmd}`;
+      expect(result.stdout.trim()).toBe('2');
+      expect(result.code).toBe(0);
+    });
+
+    test('should execute command with semicolon', async () => {
+      const cmd = raw('echo "first"; echo "second"');
+      const result = await $`${cmd}`;
+      expect(result.stdout).toContain('first');
+      expect(result.stdout).toContain('second');
+      expect(result.code).toBe(0);
+    });
+
+    test('should handle command with subshell', async () => {
+      const cmd = raw('echo "outer: $(echo inner)"');
+      const result = await $`${cmd}`;
+      expect(result.stdout.trim()).toBe('outer: inner');
+      expect(result.code).toBe(0);
+    });
+
+    test('should handle command with wildcards', async () => {
+      const cmd = raw('echo test-*.mjs | head -c 20');
+      const result = await $`${cmd}`;
+      // Should execute wildcard expansion
+      expect(result.code).toBe(0);
+      expect(result.stdout.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('combining raw() with safe interpolation', () => {
+    test('should mix raw command with safe variable', async () => {
+      const safeInput = 'test';
+      const result = await $`${raw('echo "prefix:"')} ${safeInput}`;
+      expect(result.stdout.trim()).toBe('prefix: test');
+    });
+
+    test('should safely quote user input when mixed with raw', async () => {
+      const userInput = 'test; rm -rf /';
+      const result = await $`${raw('echo "User said:"')} ${userInput}`;
+      // User input should be safely quoted even when mixed with raw
+      expect(result.stdout).toContain('User said:');
+      expect(result.stdout).toContain('test; rm -rf /');
+      // Command should not execute the rm part
+      expect(result.code).toBe(0);
+    });
+
+    test('should handle multiple raw() calls in one command', async () => {
+      const cmd1 = raw('echo "part1"');
+      const cmd2 = raw('&& echo "part2"');
+      const result = await $`${cmd1} ${cmd2}`;
+      expect(result.stdout).toContain('part1');
+      expect(result.stdout).toContain('part2');
+    });
+  });
+
+  describe('comparison with normal interpolation', () => {
+    test('raw() executes shell operators, normal interpolation escapes them', async () => {
+      const cmdString = 'echo "test" && echo "test2"';
+
+      // With raw() - executes both commands
+      const rawResult = await $`${raw(cmdString)}`;
+      expect(rawResult.stdout).toContain('test');
+      expect(rawResult.stdout).toContain('test2');
+
+      // Without raw() - treats as literal string
+      const normalResult = await $`echo ${cmdString}`;
+      expect(normalResult.stdout.trim()).toBe(cmdString);
+      expect(normalResult.stdout).not.toMatch(/test\s+test2/); // Should be one line
+    });
+
+    test('raw() allows pipes, normal interpolation escapes them', async () => {
+      const cmdString = 'echo "hello world" | wc -w';
+
+      // With raw() - executes pipe
+      const rawResult = await $`${raw(cmdString)}`;
+      expect(rawResult.stdout.trim()).toBe('2');
+
+      // Without raw() - treats pipe as literal
+      const normalResult = await $`echo ${cmdString}`;
+      expect(normalResult.stdout).toContain('|');
+      expect(normalResult.stdout).toContain('wc');
+    });
+
+    test('raw() allows command substitution, normal interpolation escapes it', async () => {
+      const cmdString = '$(echo test)';
+
+      // With raw() - executes substitution
+      const rawResult = await $`echo ${raw(cmdString)}`;
+      expect(rawResult.stdout.trim()).toBe('test');
+
+      // Without raw() - treats as literal
+      const normalResult = await $`echo ${cmdString}`;
+      expect(normalResult.stdout.trim()).toBe('$(echo test)');
+    });
+  });
+
+  describe('edge cases', () => {
+    test('should handle raw() with quotes in command', async () => {
+      const cmd = raw('echo "single\'quote" "double\\"quote"');
+      const result = await $`${cmd}`;
+      expect(result.code).toBe(0);
+      expect(result.stdout).toContain('single');
+      expect(result.stdout).toContain('quote');
+    });
+
+    test('should handle raw() with environment variables', async () => {
+      const cmd = raw('echo $HOME');
+      const result = await $`${cmd}`;
+      expect(result.stdout.trim().length).toBeGreaterThan(0);
+      expect(result.stdout.trim()).not.toBe('$HOME');
+    });
+
+    test('should handle raw() with newlines', async () => {
+      const cmd = raw('echo "line1"\necho "line2"');
+      const result = await $`${cmd}`;
+      expect(result.stdout).toContain('line1');
+      expect(result.stdout).toContain('line2');
+    });
+
+    test('should handle raw() at different positions', async () => {
+      // At start
+      const result1 = await $`${raw('echo "start"')} end`;
+      expect(result1.stdout.trim()).toContain('start');
+
+      // In middle
+      const result2 = await $`echo start ${raw('&& echo "middle"')} end`;
+      expect(result2.stdout).toContain('middle');
+
+      // At end
+      const result3 = await $`echo start ${raw('&& echo "end"')}`;
+      expect(result3.stdout).toContain('end');
+    });
+  });
+
+  describe('practical use cases', () => {
+    test('configuration-based commands', async () => {
+      const config = {
+        buildCommand: raw('echo "Building..." && echo "Done"'),
+        testCommand: raw('echo "Testing..." && echo "Passed"'),
+      };
+
+      const buildResult = await $`${config.buildCommand}`;
+      expect(buildResult.stdout).toContain('Building');
+      expect(buildResult.stdout).toContain('Done');
+
+      const testResult = await $`${config.testCommand}`;
+      expect(testResult.stdout).toContain('Testing');
+      expect(testResult.stdout).toContain('Passed');
+    });
+
+    test('complex shell pipelines', async () => {
+      const pipeline = raw('seq 1 10 | head -n 3 | tail -n 1');
+      const result = await $`${pipeline}`;
+      expect(result.stdout.trim()).toBe('3');
+    });
+
+    test('conditional execution chains', async () => {
+      const successChain = raw('true && echo "success"');
+      const result1 = await $`${successChain}`;
+      expect(result1.stdout.trim()).toBe('success');
+
+      const failChain = raw('false && echo "should not print"');
+      const result2 = await $`${failChain}`;
+      expect(result2.stdout.trim()).toBe('');
+    });
+  });
+
+  describe('security demonstrations', () => {
+    test('normal interpolation prevents injection', async () => {
+      const malicious = '; rm -rf /tmp/test';
+      const result = await $`echo ${malicious}`;
+
+      // Should safely output the string, not execute rm
+      expect(result.stdout).toContain('; rm -rf /tmp/test');
+      expect(result.code).toBe(0);
+    });
+
+    test('raw() would execute injection (demonstration only)', async () => {
+      // We demonstrate the danger without actually running dangerous commands
+      const dangerous = raw(
+        'echo "safe" ; echo "This would be dangerous with rm -rf"'
+      );
+      const result = await $`${dangerous}`;
+
+      // Both parts execute because raw() disables escaping
+      expect(result.stdout).toContain('safe');
+      expect(result.stdout).toContain('dangerous');
+    });
+  });
+
+  describe('error handling', () => {
+    test('should handle failing commands in raw()', async () => {
+      const cmd = raw('false');
+      const result = await $`${cmd}`;
+      expect(result.code).toBe(1);
+    });
+
+    test('should handle non-existent commands in raw()', async () => {
+      const cmd = raw('nonexistent-command-12345');
+      const result = await $`${cmd}`;
+      expect(result.code).not.toBe(0);
+    });
+
+    test('should handle syntax errors in raw()', async () => {
+      // Invalid shell syntax
+      const cmd = raw('echo "unclosed quote');
+      const result = await $`${cmd}`;
+      expect(result.code).not.toBe(0);
+    });
+  });
+});

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

@@ -0,0 +1,427 @@
+import { test, expect, describe, beforeEach, afterEach } from 'bun:test';
+import { beforeTestCleanup, afterTestCleanup } from './test-cleanup.mjs';
+import {
+  $,
+  sh,
+  create,
+  shell,
+  set,
+  unset,
+  disableVirtualCommands,
+} from '../src/$.mjs';
+
+// Helper function to setup shell settings for README tests
+function setupShellForReadme() {
+  shell.errexit(false);
+  shell.verbose(false);
+  shell.xtrace(false);
+  shell.pipefail(false);
+  shell.nounset(false);
+  // Disable virtual commands for these tests to ensure system command behavior
+  disableVirtualCommands();
+}
+
+describe('README Examples and Use Cases', () => {
+  beforeEach(async () => {
+    await beforeTestCleanup();
+    setupShellForReadme();
+  });
+
+  afterEach(async () => {
+    await afterTestCleanup();
+  });
+
+  describe('1. Classic Await Pattern', () => {
+    test('should work like README example: await $`ls -la`', async () => {
+      const result = await $`echo "hello world"`;
+      expect(result.stdout.trim()).toBe('hello world');
+      expect(result.code).toBe(0);
+      expect(typeof result.stdout).toBe('string');
+    });
+  });
+
+  describe('2. Async Iteration Pattern', () => {
+    test('should work like README example: for await streaming', async () => {
+      const chunks = [];
+
+      for await (const chunk of $`echo "line1"; echo "line2"`.stream()) {
+        if (chunk.type === 'stdout') {
+          chunks.push(chunk.data.toString());
+        }
+      }
+
+      const output = chunks.join('');
+      expect(output).toContain('line1');
+      expect(output).toContain('line2');
+    });
+  });
+
+  describe('3. EventEmitter Pattern', () => {
+    test('should work like README example: .on() events', async () => {
+      const events = [];
+
+      const result = await new Promise((resolve) => {
+        const cmd = $`sh -c "echo 'stdout'; echo 'stderr' >&2"`;
+        cmd
+          .on('data', (chunk) => {
+            if (chunk.type === 'stdout') {
+              events.push('stdout-data');
+            }
+          })
+          .on('stderr', (chunk) => events.push('stderr'))
+          .on('end', (result) => {
+            events.push('end');
+            resolve(result);
+          })
+          .on('exit', (code) => events.push(`exit-${code}`));
+
+        // Start the command
+        cmd.then().catch(() => {});
+      });
+
+      expect(events).toContain('stdout-data');
+      expect(events).toContain('stderr');
+      expect(events).toContain('end');
+      expect(events).toContain('exit-0');
+      expect(result.code).toBe(0);
+    });
+  });
+
+  describe('4. Mixed Pattern', () => {
+    test('should work like README example: events + await', async () => {
+      const process = $`echo "streaming data"`;
+      const chunks = [];
+
+      // Handle real-time events
+      process.on('data', (chunk) => {
+        chunks.push(chunk);
+      });
+
+      // Still get the final result
+      const result = await process;
+
+      expect(result.stdout.trim()).toBe('streaming data');
+      expect(chunks.length).toBeGreaterThan(0);
+      expect(chunks[0]).toHaveProperty('type');
+      expect(chunks[0]).toHaveProperty('data');
+    });
+  });
+
+  describe('5. Shell Replacement (.sh → .mjs)', () => {
+    test('should work like README example: shell settings', async () => {
+      // Test the exact example from README
+      shell.errexit(true);
+
+      await $`mkdir -p /tmp/test-build`;
+
+      // This should work
+      const result1 = await $`echo "build success"`;
+      expect(result1.code).toBe(0);
+
+      // set +e equivalent: allow errors
+      shell.errexit(false);
+      const cleanup = await $`ls /nonexistent-dir-12345`; // Won't throw if fails
+      expect(cleanup.code).not.toBe(0); // Should fail but not throw
+
+      // set -e again for critical operations
+      shell.errexit(true);
+      await $`echo "critical operation"`;
+
+      // Other bash-like settings
+      shell.verbose(true);
+      shell.xtrace(true);
+
+      // Or use the bash-style API
+      set('e');
+      expect(shell.settings().errexit).toBe(true);
+
+      unset('e');
+      expect(shell.settings().errexit).toBe(false);
+
+      set('x');
+      expect(shell.settings().xtrace).toBe(true);
+
+      set('verbose');
+      expect(shell.settings().verbose).toBe(true);
+    });
+  });
+
+  describe('6. Default Behavior', () => {
+    test('should work like README example: stdout/stderr capture + mirroring', async () => {
+      // This command will:
+      // 1. Print "Hello" to your terminal (stdout→stdout)
+      // 2. Print "Error!" to your terminal (stderr→stderr)
+      // 3. Capture both outputs for programmatic access
+      const result = await $`sh -c "echo 'Hello'; echo 'Error!' >&2"`;
+
+      expect(result.stdout.trim()).toBe('Hello');
+      expect(result.stderr.trim()).toBe('Error!');
+      expect(result.code).toBe(0);
+    });
+  });
+
+  describe('7. Options Override', () => {
+    test('should work like README example: sh() with options', async () => {
+      // Disable terminal output but still capture
+      const result = await sh('echo "silent"', { mirror: false });
+      expect(result.stdout.trim()).toBe('silent');
+
+      // Custom stdin input
+      const custom = await sh('cat', { stdin: 'custom input' });
+      expect(custom.stdout.trim()).toBe('custom input');
+    });
+
+    test('should work like README example: create() with defaults', async () => {
+      // Create custom $ with different defaults
+      const quiet$ = create({ mirror: false });
+      const result = await quiet$`echo "silent"`;
+      expect(result.stdout.trim()).toBe('silent');
+
+      // Disable both mirroring and capturing for performance
+      const perfResult = await sh('echo "performance"', {
+        mirror: false,
+        capture: false,
+      });
+      expect(perfResult.stdout).toBeUndefined();
+    });
+  });
+
+  describe('8. Real-world: Session ID Extraction', () => {
+    test('should work like README example: JSON parsing from streaming', async () => {
+      let sessionId = null;
+      let logFile = null;
+      const logData = [];
+
+      // Simulate a command that outputs JSON with session_id
+      const cmd = $`sh -c 'echo "{\\"session_id\\":\\"test-123\\",\\"status\\":\\"started\\"}"; echo "{\\"data\\":\\"some log data\\"}"'`;
+
+      let chunkCount = 0;
+      for await (const chunk of cmd.stream()) {
+        chunkCount++;
+        // Handle both possible chunk formats
+        const isStdout = chunk.type === 'stdout';
+        const hasData = chunk.data !== undefined;
+
+        if (isStdout && hasData) {
+          const data = chunk.data.toString();
+
+          // Extract session ID from output
+          if (!sessionId && data.includes('session_id')) {
+            try {
+              // Split by }{  to handle concatenated JSON objects
+              const jsonStrings = data.replace(/\}\{/g, '}\n{').split('\n');
+
+              for (const jsonStr of jsonStrings) {
+                const trimmed = jsonStr.trim();
+                if (trimmed && trimmed.includes('session_id')) {
+                  const parsed = JSON.parse(trimmed);
+                  if (parsed.session_id) {
+                    sessionId = parsed.session_id;
+                    logFile = `${sessionId}.log`;
+                    break;
+                  }
+                }
+              }
+            } catch (e) {
+              // Handle JSON parse errors silently
+            }
+          }
+
+          // Write to log data (simulating file writes)
+          if (sessionId) {
+            logData.push(data);
+          }
+        }
+      }
+
+      // If no chunks were received, try to get the result directly
+      if (chunkCount === 0) {
+        const result = await cmd;
+        if (result.stdout && result.stdout.includes('session_id')) {
+          const lines = result.stdout.split('\n');
+          for (const line of lines) {
+            if (line.trim() && line.includes('session_id')) {
+              try {
+                const parsed = JSON.parse(line);
+                if (parsed.session_id) {
+                  sessionId = parsed.session_id;
+                  logFile = `${sessionId}.log`;
+                  break;
+                }
+              } catch (e) {
+                // Handle JSON parse errors
+              }
+            }
+          }
+        }
+      }
+
+      expect(sessionId).toBe('test-123');
+      expect(logFile).toBe('test-123.log');
+      // Adjust expectation based on whether streaming worked
+      if (chunkCount > 0) {
+        expect(logData.length).toBeGreaterThan(0);
+      }
+    });
+  });
+
+  describe('9. Real-world: Progress Monitoring', () => {
+    test('should work like README example: progress parsing from stdout', async () => {
+      let progress = 0;
+      let completed = false;
+
+      const parseProgress = (output) => {
+        const match = output.match(/Progress: (\d+)%/);
+        return match ? parseInt(match[1]) : 0;
+      };
+
+      const updateProgressBar = (prog) => {
+        progress = prog;
+      };
+
+      // Simulate a download command with progress output
+      await new Promise((resolve) => {
+        const cmd = $`sh -c 'echo "Starting download"; echo "Progress: 25%"; echo "Progress: 50%"; echo "Progress: 100%"; echo "Done!"'`;
+        cmd
+          .on('stdout', (chunk) => {
+            const output = chunk.toString();
+            if (output.includes('Progress:')) {
+              const newProgress = parseProgress(output);
+              if (newProgress > 0) {
+                updateProgressBar(newProgress);
+              }
+            }
+          })
+          .on('end', (result) => {
+            completed = true;
+            resolve(result);
+          });
+
+        // Start the command
+        cmd.then().catch(() => {});
+      });
+
+      expect(progress).toBeGreaterThan(0);
+      expect(completed).toBe(true);
+    });
+  });
+
+  describe('10. API Documentation Examples', () => {
+    test('should match ProcessRunner events from API docs', async () => {
+      const events = [];
+
+      const result = await new Promise((resolve) => {
+        const cmd = $`sh -c "echo 'stdout'; echo 'stderr' >&2; exit 0"`;
+        cmd
+          .on('data', (chunk) => events.push(`data-${chunk.type}`))
+          .on('stdout', (chunk) => events.push('stdout'))
+          .on('stderr', (chunk) => events.push('stderr'))
+          .on('end', (result) => {
+            events.push('end');
+            resolve(result);
+          })
+          .on('exit', (code) => events.push(`exit-${code}`));
+
+        // Start the command
+        cmd.then().catch(() => {});
+      });
+
+      expect(events).toContain('data-stdout');
+      expect(events).toContain('data-stderr');
+      expect(events).toContain('stdout');
+      expect(events).toContain('stderr');
+      expect(events).toContain('end');
+      expect(events).toContain('exit-0');
+    });
+
+    test('should match Result Object from API docs', async () => {
+      const result = await $`sh -c "echo 'output'; echo 'error' >&2; exit 0"`;
+
+      // Verify result object structure from API docs
+      expect(typeof result.code).toBe('number');
+      expect(typeof result.stdout).toBe('string');
+      expect(typeof result.stderr).toBe('string');
+      expect(typeof result.stdin).toBe('string');
+      expect(result.child).toBeDefined();
+
+      expect(result.code).toBe(0);
+      expect(result.stdout.trim()).toBe('output');
+      expect(result.stderr.trim()).toBe('error');
+    });
+
+    test('should verify default options from API docs', async () => {
+      const cmd = $`echo test`;
+
+      // Verify default options structure from API docs
+      expect(cmd.options.mirror).toBe(true);
+      expect(cmd.options.capture).toBe(true);
+      expect(cmd.options.stdin).toBe('inherit');
+    });
+  });
+
+  describe('Smart Quoting & Security (from README)', () => {
+    test('safe strings are NOT quoted', () => {
+      const name = 'hello';
+      const cmd = '/usr/bin/node';
+
+      const testCmd1 = $({ mirror: false })`echo ${name}`;
+      expect(testCmd1.spec.command).toBe('echo hello');
+
+      const testCmd2 = $({ mirror: false })`${cmd} --version`;
+      expect(testCmd2.spec.command).toBe('/usr/bin/node --version');
+    });
+
+    test('dangerous strings are automatically quoted', () => {
+      const userInput = 'test; rm -rf /';
+      const pathWithSpaces = '/my path/file';
+
+      const testCmd1 = $({ mirror: false })`echo ${userInput}`;
+      expect(testCmd1.spec.command).toBe("echo 'test; rm -rf /'");
+
+      const testCmd2 = $({ mirror: false })`echo ${pathWithSpaces}`;
+      expect(testCmd2.spec.command).toBe("echo '/my path/file'");
+    });
+
+    test('user-provided quotes are preserved', () => {
+      const quotedPath = "'/path with spaces/file'";
+      const doubleQuoted = '"/path with spaces/file"';
+
+      const testCmd1 = $({ mirror: false })`cat ${quotedPath}`;
+      expect(testCmd1.spec.command).toBe("cat '/path with spaces/file'");
+
+      const testCmd2 = $({ mirror: false })`cat ${doubleQuoted}`;
+      expect(testCmd2.spec.command).toBe('cat \'"/path with spaces/file"\'');
+    });
+
+    test('shell injection attempts are neutralized', () => {
+      const dangerous = "'; rm -rf /; echo '";
+      const cmdSubstitution = '$(whoami)';
+      const varExpansion = '$HOME';
+      const complex = '`cat /etc/passwd`';
+
+      const testCmd1 = $({ mirror: false })`echo ${dangerous}`;
+      expect(testCmd1.spec.command).toContain('rm -rf');
+      expect(testCmd1.spec.command).toMatch(/^echo '/);
+
+      const testCmd2 = $({ mirror: false })`echo ${cmdSubstitution}`;
+      expect(testCmd2.spec.command).toBe("echo '$(whoami)'");
+
+      const testCmd3 = $({ mirror: false })`echo ${varExpansion}`;
+      expect(testCmd3.spec.command).toBe("echo '$HOME'");
+
+      const testCmd4 = $({ mirror: false })`echo ${complex}`;
+      expect(testCmd4.spec.command).toBe("echo '`cat /etc/passwd`'");
+    });
+
+    test('actual execution prevents injection', async () => {
+      const varExpansion = '$HOME';
+      const cmdSubstitution = '$(echo INJECTED)';
+
+      const result1 = await $`echo ${varExpansion}`;
+      expect(result1.stdout.trim()).toBe('$HOME'); // Literal, not expanded
+
+      const result2 = await $`echo ${cmdSubstitution}`;
+      expect(result2.stdout.trim()).toBe('$(echo INJECTED)'); // Literal, not executed
+    });
+  });
+});