Add failing tests for subprocess API

Test fixtures for 10 subprocess scenarios:
- spawn-basic.ts: Basic spawn and exit code
- spawn-stdout.ts: Capture stdout output
- spawn-stderr.ts: Capture stderr output
- spawn-stdin.ts: Write to process stdin
- spawn-cwd.ts: Set working directory
- spawn-env.ts: Set environment variables
- spawn-kill.ts: Kill a running process
- spawn-error.ts: Handle errors gracefully
- spawn-args.ts: Pass arguments to command
- spawn-exit-code.ts: Get non-zero exit codes

All tests currently fail (subprocess not implemented yet).

Author: nev-offload

tests/cli.test.ts

@@ -3435,4 +3435,170 @@ export default async () => {
       expect(stdout).toContain('headers-object test complete');
     });
   });
+
+  // ==================== SUBPROCESS API ====================
+
+  describe('subprocess', () => {
+    /**
+     * Subprocess API test suite
+     * 
+     * These tests verify funee's subprocess spawning and management API.
+     * The API provides:
+     * - spawn() for running commands
+     * - Process object for managing running processes
+     * - Streaming stdin/stdout/stderr
+     * - Signal handling and process control
+     */
+
+    it('spawns a basic command and gets exit code', async () => {
+      /**
+       * Tests basic subprocess spawning:
+       * - spawn(command, args) runs a command
+       * - Returns status with exit code
+       * - success is true for exit code 0
+       */
+      const { stdout, stderr, exitCode } = await runFunee(['process/spawn-basic.ts']);
+      
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('exit code: 0');
+      expect(stdout).toContain('success: true');
+      expect(stdout).toContain('spawn-basic: pass');
+    });
+
+    it('captures stdout output from subprocess', async () => {
+      /**
+       * Tests stdout capture:
+       * - stdout is available as Uint8Array
+       * - stdoutText() returns decoded string
+       * - Output matches command output
+       */
+      const { stdout, stderr, exitCode } = await runFunee(['process/spawn-stdout.ts']);
+      
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('stdout text: "hello world"');
+      expect(stdout).toContain('spawn-stdout: pass');
+    });
+
+    it('captures stderr output from subprocess', async () => {
+      /**
+       * Tests stderr capture:
+       * - stderr is captured separately
+       * - stderrText() returns decoded string
+       * - Errors appear in stderr, not stdout
+       */
+      const { stdout, stderr, exitCode } = await runFunee(['process/spawn-stderr.ts']);
+      
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('stderr contains error: true');
+      expect(stdout).toContain('stdout is empty: true');
+      expect(stdout).toContain('success: false');
+      expect(stdout).toContain('spawn-stderr: pass');
+    });
+
+    it('writes to subprocess stdin', async () => {
+      /**
+       * Tests stdin writing:
+       * - stdin: "piped" enables writing
+       * - writeInput() sends data
+       * - Process receives input
+       */
+      const { stdout, stderr, exitCode } = await runFunee(['process/spawn-stdin.ts']);
+      
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('output: "hello from stdin"');
+      expect(stdout).toContain('matches input: true');
+      expect(stdout).toContain('spawn-stdin: pass');
+    });
+
+    it('sets working directory for subprocess', async () => {
+      /**
+       * Tests cwd option:
+       * - cwd sets process working directory
+       * - Commands run in specified directory
+       */
+      const { stdout, stderr, exitCode } = await runFunee(['process/spawn-cwd.ts']);
+      
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('is /tmp: true');
+      expect(stdout).toContain('spawn-cwd: pass');
+    });
+
+    it('sets environment variables for subprocess', async () => {
+      /**
+       * Tests env options:
+       * - env sets custom environment variables
+       * - inheritEnv controls parent env inheritance
+       */
+      const { stdout, stderr, exitCode } = await runFunee(['process/spawn-env.ts']);
+      
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('custom env var: custom_value');
+      expect(stdout).toContain('inheritEnv true, has PATH: true');
+      expect(stdout).toContain('spawn-env: pass');
+    });
+
+    it('kills a running subprocess', async () => {
+      /**
+       * Tests process killing:
+       * - kill(signal) sends signal to process
+       * - Process terminates
+       * - status.signal contains termination signal
+       */
+      const { stdout, stderr, exitCode } = await runFunee(['process/spawn-kill.ts']);
+      
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('pid is number: true');
+      expect(stdout).toContain('success: false');
+      expect(stdout).toContain('signal: SIGTERM');
+      expect(stdout).toContain('spawn-kill: pass');
+    });
+
+    it('handles subprocess errors gracefully', async () => {
+      /**
+       * Tests error handling:
+       * - Command not found throws error
+       * - Invalid cwd throws error
+       * - Errors have descriptive messages
+       */
+      const { stdout, stderr, exitCode } = await runFunee(['process/spawn-error.ts']);
+      
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('command not found error caught: true');
+      expect(stdout).toContain('spawn-error: pass');
+    });
+
+    it('passes arguments to subprocess correctly', async () => {
+      /**
+       * Tests argument handling:
+       * - Multiple arguments work
+       * - Arguments with spaces handled
+       * - cmd array form works
+       */
+      const { stdout, stderr, exitCode } = await runFunee(['process/spawn-args.ts']);
+      
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('multiple args: "one two three"');
+      expect(stdout).toContain('cmd array args: "from cmd array"');
+      expect(stdout).toContain('spawn-args: pass');
+    });
+
+    it('captures non-zero exit codes', async () => {
+      /**
+       * Tests exit code handling:
+       * - Non-zero codes captured correctly
+       * - success is false for non-zero
+       * - Different codes are distinguishable
+       */
+      const { stdout, stderr, exitCode } = await runFunee(['process/spawn-exit-code.ts']);
+      
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('exit 1 - code: 1');
+      expect(stdout).toContain('exit 1 - success: false');
+      expect(stdout).toContain('exit 42 - code: 42');
+      expect(stdout).toContain('exit 0 - code: 0');
+      expect(stdout).toContain('exit 0 - success: true');
+      expect(stdout).toContain('exit 255 - code: 255');
+      expect(stdout).toContain('spawn-exit-code: pass');
+    });
+  });
 });

tests/fixtures/process/spawn-args.ts

@@ -0,0 +1,42 @@
+/**
+ * Test: Pass arguments to subprocess
+ * 
+ * Verifies that:
+ * 1. Arguments are passed correctly to the command
+ * 2. Arguments with spaces are handled properly
+ * 3. Multiple arguments work correctly
+ */
+import { spawn, log } from "funee";
+
+export default async function main() {
+  // Test 1: Multiple arguments
+  const result1 = await spawn("echo", ["one", "two", "three"]);
+  const text1 = result1.stdoutText().trim();
+  log(`multiple args: "${text1}"`);
+  
+  // Test 2: Argument with spaces (should be treated as single arg)
+  const result2 = await spawn("echo", ["hello world"]);
+  const text2 = result2.stdoutText().trim();
+  log(`arg with space: "${text2}"`);
+  
+  // Test 3: Arguments in cmd array (full options form)
+  const proc = spawn({
+    cmd: ["echo", "from", "cmd", "array"],
+    stdout: "piped",
+  });
+  const output = await proc.output();
+  const text3 = output.stdoutText().trim();
+  log(`cmd array args: "${text3}"`);
+  
+  // Test 4: Special characters in arguments
+  const result4 = await spawn("echo", ["$HOME", "&&", "test"]);
+  const text4 = result4.stdoutText().trim();
+  // echo should output the literal strings since not going through shell
+  log(`special chars: "${text4}"`);
+  
+  if (text1 === "one two three" && text3 === "from cmd array") {
+    log("spawn-args: pass");
+  } else {
+    log("spawn-args: FAIL");
+  }
+}

tests/fixtures/process/spawn-basic.ts

@@ -0,0 +1,26 @@
+/**
+ * Test: Basic subprocess spawn and exit code
+ * 
+ * Verifies that:
+ * 1. spawn() can run a simple command
+ * 2. The process exits with code 0 for successful commands
+ * 3. status.success is true for exit code 0
+ */
+import { spawn, log } from "funee";
+
+export default async function main() {
+  // Simple command that exits successfully
+  const result = await spawn("echo", ["hello"]);
+  
+  // Check exit code
+  const exitCode = result.status.code;
+  log(`exit code: ${exitCode}`);
+  log(`success: ${result.status.success}`);
+  
+  // Verify success
+  if (exitCode === 0 && result.status.success) {
+    log("spawn-basic: pass");
+  } else {
+    log("spawn-basic: FAIL");
+  }
+}

tests/fixtures/process/spawn-cwd.ts

@@ -0,0 +1,30 @@
+/**
+ * Test: Set working directory for subprocess
+ * 
+ * Verifies that:
+ * 1. cwd option changes the process working directory
+ * 2. Commands run in the specified directory
+ */
+import { spawn, log } from "funee";
+
+export default async function main() {
+  // Run pwd in /tmp directory
+  const result = await spawn({
+    cmd: ["pwd"],
+    cwd: "/tmp",
+    stdout: "piped",
+  });
+  
+  const output = await result.output();
+  const cwd = output.stdoutText().trim();
+  
+  log(`cwd: ${cwd}`);
+  log(`is /tmp: ${cwd === "/tmp" || cwd === "/private/tmp"}`);
+  
+  // macOS resolves /tmp to /private/tmp
+  if (cwd === "/tmp" || cwd === "/private/tmp") {
+    log("spawn-cwd: pass");
+  } else {
+    log("spawn-cwd: FAIL");
+  }
+}

tests/fixtures/process/spawn-env.ts

@@ -0,0 +1,53 @@
+/**
+ * Test: Set environment variables for subprocess
+ * 
+ * Verifies that:
+ * 1. env option sets custom environment variables
+ * 2. Process can access the environment variables
+ * 3. inheritEnv controls whether parent env is included
+ */
+import { spawn, log } from "funee";
+
+export default async function main() {
+  // Test 1: Set custom env var
+  const result1 = await spawn({
+    cmd: ["sh", "-c", "echo $MY_VAR"],
+    env: { MY_VAR: "custom_value" },
+    stdout: "piped",
+  });
+  
+  const output1 = await result1.output();
+  const value1 = output1.stdoutText().trim();
+  log(`custom env var: ${value1}`);
+  
+  // Test 2: inheritEnv: false should not have PATH
+  const result2 = await spawn({
+    cmd: ["sh", "-c", "echo PATH=$PATH"],
+    env: { MY_VAR: "test" },
+    inheritEnv: false,
+    stdout: "piped",
+  });
+  
+  const output2 = await result2.output();
+  const value2 = output2.stdoutText().trim();
+  log(`inheritEnv false, PATH: ${value2}`);
+  
+  // Test 3: inheritEnv: true (default) should have PATH
+  const result3 = await spawn({
+    cmd: ["sh", "-c", "echo PATH_EXISTS=$PATH"],
+    env: { MY_VAR: "test" },
+    inheritEnv: true,
+    stdout: "piped",
+  });
+  
+  const output3 = await result3.output();
+  const value3 = output3.stdoutText().trim();
+  const hasPath = value3.includes("/usr") || value3.includes("/bin");
+  log(`inheritEnv true, has PATH: ${hasPath}`);
+  
+  if (value1 === "custom_value" && hasPath) {
+    log("spawn-env: pass");
+  } else {
+    log("spawn-env: FAIL");
+  }
+}

tests/fixtures/process/spawn-error.ts

@@ -0,0 +1,46 @@
+/**
+ * Test: Handle subprocess errors gracefully
+ * 
+ * Verifies that:
+ * 1. Command not found throws an error
+ * 2. Error message is descriptive
+ * 3. Does not crash the runtime
+ */
+import { spawn, log } from "funee";
+
+export default async function main() {
+  // Test 1: Non-existent command
+  let errorCaught = false;
+  let errorMessage = "";
+  
+  try {
+    await spawn("nonexistent_command_xyz123", ["arg"]);
+  } catch (e: unknown) {
+    errorCaught = true;
+    errorMessage = e instanceof Error ? e.message : String(e);
+  }
+  
+  log(`command not found error caught: ${errorCaught}`);
+  log(`error message contains useful info: ${errorMessage.includes("not found") || errorMessage.includes("No such file") || errorMessage.includes("ENOENT")}`);
+  
+  // Test 2: Invalid cwd
+  let cwdErrorCaught = false;
+  
+  try {
+    const proc = spawn({
+      cmd: ["echo", "hello"],
+      cwd: "/nonexistent/directory/xyz123",
+    });
+    await proc.status;
+  } catch (e: unknown) {
+    cwdErrorCaught = true;
+  }
+  
+  log(`invalid cwd error caught: ${cwdErrorCaught}`);
+  
+  if (errorCaught) {
+    log("spawn-error: pass");
+  } else {
+    log("spawn-error: FAIL");
+  }
+}