fix: psalm errors

.gitignore

@@ -1 +1,4 @@
+.phpunit.cache/
+.phpunit.result.cache
+docs/coverage/
 vendor/

Makefile

@@ -0,0 +1,18 @@
+.PHONY: all
+all: ./vendor
+
+.PHONY: test
+test: ./vendor
+	./vendor/bin/phpunit tests
+
+.PHONY: lint
+lint: ./vendor
+	./vendor/bin/psalm --show-info=true
+
+docs/coverage: ./vendor $(wildcard src/**.php) $(wildcard tests/**.php)
+	XDEBUG_MODE=coverage ./vendor/bin/phpunit --coverage-html docs/coverage tests
+	@touch $@
+
+./vendor: composer.json composer.lock
+	composer install
+	@touch $@

composer.json

@@ -14,5 +14,12 @@
             "email": "kattendick@bde-software.com"
         }
     ],
-    "require": {}
+    "require": {
+        "php": "^8.4"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^13.0",
+        "vimeo/psalm": "^6.15",
+        "psalm/plugin-phpunit": "^0.19.5"
+    }
 }

phpunit.xml

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         cacheDirectory=".phpunit.cache"
+         executionOrder="depends,defects"
+         requireCoverageMetadata="true"
+         beStrictAboutCoverageMetadata="true"
+         beStrictAboutOutputDuringTests="true"
+         displayDetailsOnPhpunitDeprecations="true"
+         failOnPhpunitDeprecation="true"
+         failOnRisky="true"
+         failOnWarning="true">
+    <testsuites>
+        <testsuite name="unit">
+            <directory>tests/unit</directory>
+        </testsuite>
+        <testsuite name="integration">
+            <directory>tests/integration</directory>
+        </testsuite>
+    </testsuites>
+
+    <source ignoreIndirectDeprecations="true" restrictNotices="true" restrictWarnings="true">
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
+</phpunit>

psalm.xml

@@ -0,0 +1,25 @@
+<?xml version="1.0"?>
+<psalm
+    errorLevel="2"
+    resolveFromConfigFile="true"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xmlns="https://getpsalm.org/schema/config"
+    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
+    findUnusedBaselineEntry="true"
+    findUnusedCode="true"
+>
+    <projectFiles>
+        <directory name="src"/>
+        <directory name="tests"/>
+        <ignoreFiles>
+            <directory name="vendor"/>
+        </ignoreFiles>
+    </projectFiles>
+
+    <issueHandlers>
+    </issueHandlers>
+
+    <plugins>
+        <pluginClass class="Psalm\PhpUnitPlugin\Plugin"/>
+    </plugins>
+</psalm>

src/Child.php

@@ -4,6 +4,8 @@ declare(strict_types=1);
 
 namespace Nih\CommandBuilder;
 
+use InvalidArgumentException;
+
 /**
  * Representation of a running or exited child process.
  */
@@ -26,6 +28,11 @@ final class Child
      */
     private ?ExitStatus $status = null;
 
+    /**
+     * The child's output.
+     */
+    private ?Output $output = null;
+
     /**
      * The handle for writing to the child’s standard input (stdin), if it has
      * been captured.
@@ -45,13 +52,17 @@ final class Child
     public readonly ?ChildStderr $stderr;
 
     /**
-     * @param resource $process The child's process handle.
-     * @param array<int, resource> $pipes File pointers.
+     * @param resource $process The child's process resource handle.
+     * @param array<array-key, resource> $pipes
+     * The indexed array of file pointers that set by {@see \proc_open()}.
+     *
+     * @throws InvalidArgumentException
+     * When the given process is not a process resource.
      */
     public function __construct(mixed $process, array $pipes)
     {
         if (get_resource_type($process) !== 'process') {
-            throw new ChildException('invalid resource type: not a process');
+            throw new InvalidArgumentException('resource is not a process');
         }
 
         $this->process = $process;
@@ -89,8 +100,6 @@ final class Child
      * waiting. This helps avoid deadlock: it ensures that the child does not
      * block waiting for input from the parent, while the parent waits for the
      * child to exit.
-     *
-     * @throws ChildException If the resource was already closed
      */
     public function wait(): ExitStatus
     {
@@ -111,7 +120,7 @@ final class Child
         proc_close($this->process);
 
         return $this->status = new ExitStatus(
-            $status['exitcode'],
+            $status['exitcode'] < 0 ? null : $status['exitcode'],
             $status['signaled'] ? $status['termsig'] : null,
             $status['stopped'] ? $status['stopsig'] : null,
         );
@@ -120,6 +129,8 @@ final class Child
     /**
      * Simultaneously waits for the child to exit and collect all remaining
      * output on the stdout/stderr handles, returning an {@see Output} instance.
+     * This function will continue to have the same return value after it has
+     * been called at least once.
      *
      * The stdin handle to the child process, if any, will be closed before
      * waiting. This helps avoid deadlock: it ensures that the child does not
@@ -131,12 +142,13 @@ final class Child
      * parent and child. Use the `stdout` and `stderr` functions of {@see
      * Command}, respectively.
      *
-     * @throws ChildException If the resource was already closed
+     * @throws ChildException
+     * @throws StreamException
      */
     public function waitWithOutput(): Output
     {
-        if (!is_resource($this->process)) {
-            throw new ChildException('Resource was already closed');
+        if ($this->output) {
+            return $this->output;
         }
 
         // Avoid possible deadlock before waiting.
@@ -146,21 +158,29 @@ final class Child
         $stderr = $this->stderr?->getContents();
         $status = $this->wait();
 
-        return new Output($stdout, $stderr, $status);
+        return $this->output = new Output($stdout, $stderr, $status);
     }
 
     /**
      * Forces the child process to exit.
      *
      * This is equivalent to sending a SIGKILL.
+     *
+     * @throws ChildException
      */
-    public function kill(): bool
+    public function kill(): void
     {
-        if (!is_resource($this->process)) {
-            return true;
+        if ($this->status) {
+            return;
         }
 
-        return proc_terminate($this->process, 9);
+        try {
+            set_error_handler(ChildException::handleError(...));
+            $success = proc_terminate($this->process, 9);
+            assert($success);
+        } finally {
+            restore_error_handler();
+        }
     }
 
     public function __destruct()

src/ChildException.php

@@ -4,5 +4,23 @@ declare(strict_types=1);
 
 namespace Nih\CommandBuilder;
 
-class ChildException extends CommandException
-{}
+/**
+ * A PHP error occured during an operation on a process resource.
+ */
+final class ChildException extends CommandException
+{
+    public static function handleError(
+        int $severity,
+        string $message,
+        string $filename,
+        int $line,
+    ): never {
+        throw new self(
+            message: $message,
+            code: 0,
+            severity: $severity,
+            filename: $filename,
+            line: $line,
+        );
+    }
+}

src/ChildStderr.php

@@ -6,12 +6,18 @@ namespace Nih\CommandBuilder;
 
 use Override;
 
+/**
+ *
+ */
 final class ChildStderr implements StdioInterface
 {
     use StreamReadTrait;
 
+    /**
+     * @return resource
+     */
     #[Override]
-    public function getDescriptionSpec(int $fd): mixed
+    public function getDescriptiorSpec(int $fd): mixed
     {
         return $this->stream;
     }

src/ChildStdin.php

@@ -10,8 +10,11 @@ final class ChildStdin implements StdioInterface
 {
     use StreamWriteTrait;
 
+    /**
+     * @return resource
+     */
     #[Override]
-    public function getDescriptionSpec(int $fd): mixed
+    public function getDescriptiorSpec(int $fd): mixed
     {
         return $this->stream;
     }

src/ChildStdout.php

@@ -10,8 +10,11 @@ final class ChildStdout implements StdioInterface
 {
     use StreamReadTrait;
 
+    /**
+     * @return resource
+     */
     #[Override]
-    public function getDescriptionSpec(int $fd): mixed
+    public function getDescriptiorSpec(int $fd): mixed
     {
         return $this->stream;
     }

src/Command.php

@@ -17,9 +17,18 @@ final class Command implements Stringable
 {
     public readonly string $program;
 
+    /**
+     * @var list<string>
+     */
     private array $args = [];
+
+    /**
+     * @var array<string, string|null>
+     */
     private ?array $environment = null;
+
     private bool $environmentInherit = true;
+
     private ?string $cwd = null;
 
     private ?StdioInterface $stdin = null;
@@ -90,7 +99,7 @@ final class Command implements Stringable
      * escaped characters, word splitting, glob patterns, variable substitution,
      * etc. have no effect.
      *
-     * @param iterable<string|Stringable> $args
+     * @param iterable<mixed, string|Stringable> $args
      */
     public function args(iterable $args): static
     {
@@ -118,7 +127,7 @@ final class Command implements Stringable
      */
     public function env(string $key, string|Stringable $val): static
     {
-        $this->environment[$key] = $val;
+        $this->environment[$key] = (string) $val;
         return $this;
     }
 
@@ -278,18 +287,20 @@ final class Command implements Stringable
      * Executes the command as a child process, returning a handle to it.
      *
      * By default, stdin, stdout and stderr are inherited from the parent.
+     *
+     * @throws ChildException
      */
     public function spawn(): Child
     {
         return $this->spawnWithDescriptorSpec([
             $this->stdin instanceof StdioInterface
-                ? $this->stdin->getDescriptionSpec(0)
+                ? $this->stdin->getDescriptiorSpec(0)
                 : STDIN,
             $this->stdout instanceof StdioInterface
-                ? $this->stdout->getDescriptionSpec(1)
+                ? $this->stdout->getDescriptiorSpec(1)
                 : STDOUT,
             $this->stderr instanceof StdioInterface
-                ? $this->stderr->getDescriptionSpec(2)
+                ? $this->stderr->getDescriptiorSpec(2)
                 : STDERR,
         ]);
     }
@@ -299,6 +310,8 @@ final class Command implements Stringable
      * collecting its status.
      *
      * By default, stdin, stdout and stderr are inherited from the parent.
+     *
+     * @throws ChildException
      */
     public function status(): ExitStatus
     {
@@ -311,18 +324,20 @@ final class Command implements Stringable
      *
      * By default, stdout and stderr are captured (and used to provide the
      * resulting output). Stdin is not inherited from the parent.
+     *
+     * @throws ChildException
      */
     public function output(): Output
     {
         return $this->spawnWithDescriptorSpec([
             $this->stdin instanceof StdioInterface
-                ? $this->stdin->getDescriptionSpec(0)
+                ? $this->stdin->getDescriptiorSpec(0)
                 : ['pipe', 'r'],
             $this->stdout instanceof StdioInterface
-                ? $this->stdout->getDescriptionSpec(1)
+                ? $this->stdout->getDescriptiorSpec(1)
                 : ['pipe', 'w'],
             $this->stderr instanceof StdioInterface
-                ? $this->stderr->getDescriptionSpec(2)
+                ? $this->stderr->getDescriptiorSpec(2)
                 : ['pipe', 'w'],
         ])->waitWithOutput();
     }
@@ -339,6 +354,8 @@ final class Command implements Stringable
      * Returns the arguments that will be passed to the program.
      *
      * This does not include the path to the program as the first argument.
+     *
+     * @return list<string>
      */
     public function getArgs(): array
     {
@@ -354,6 +371,8 @@ final class Command implements Stringable
      *
      * Note that this output does not include environment variables inherited
      * from the parent process.
+     *
+     * @return array<string, string|null>
      */
     public function getEnvs(): array
     {
@@ -379,6 +398,9 @@ final class Command implements Stringable
         ]);
     }
 
+    /**
+     * @param array<int, resource|list<string>> $descriptorSpec
+     */
     private function spawnWithDescriptorSpec(array $descriptorSpec): Child
     {
         // Find executable if path is not absolute.
@@ -387,7 +409,7 @@ final class Command implements Stringable
             $path = getenv('PATH');
             if (is_string($path)) {
                 foreach (explode(':', $path) as $path) {
-                    $path = $path . '/' . $program;
+                    $path = $path . DIRECTORY_SEPARATOR . $program;
                     if (is_executable($path)) {
                         $program = $path;
                         break;
@@ -396,13 +418,6 @@ final class Command implements Stringable
             }
         }
 
-        if (!is_executable($program)) {
-            throw new CommandException(sprintf(
-                'Program "%s" is not executable',
-                $program,
-            ));
-        }
-
         // Handle environment inheritance.
         $environment = $this->environment;
         if (is_array($environment) && $this->environmentInherit) {
@@ -413,10 +428,15 @@ final class Command implements Stringable
             }
         }
 
+        $command = [$program];
+        foreach ($this->args as $arg) {
+            $command[] = $arg;
+        }
+
         try {
-            set_error_handler(CommandException::handleError(...));
+            set_error_handler(ChildException::handleError(...));
             $proc = proc_open(
-                [$program, ...$this->args],
+                $command,
                 $descriptorSpec,
                 $pipes,
                 $this->cwd,

src/CommandException.php

@@ -4,16 +4,9 @@ declare(strict_types=1);
 
 namespace Nih\CommandBuilder;
 
-use RuntimeException;
+use ErrorException;
 
-class CommandException extends RuntimeException
-{
-    public static function handleError(int $errno, string $errstr, string $file, int $line): never
-    {
-        $exception = new self($errstr);
-        $exception->file = $file;
-        $exception->line = $line;
-
-        throw $exception;
-    }
-}
+/**
+ *
+ */
+abstract class CommandException extends ErrorException {}

src/ExitStatus.php

@@ -11,6 +11,8 @@ namespace Nih\CommandBuilder;
  * child process. Child processes are created via the {@see Command} class and
  * their exit status is exposed through the status method, or the wait method of
  * a Child process.
+ *
+ * @api
  */
 final readonly class ExitStatus
 {
@@ -24,14 +26,20 @@ final readonly class ExitStatus
     /**
      * Was termination successful? Signal termination is not considered a
      * success, and success is defined as a zero exit status.
+     *
+     * @api
      */
     public function success(): bool
     {
-        return $this->code === 0;
+        return $this->code === 0
+            && $this->signal === null
+            && $this->stoppedSignal === null;
     }
 
     /**
      * The exit code of the process, if any.
+     *
+     * @api
      */
     public function code(): ?int
     {
@@ -40,6 +48,8 @@ final readonly class ExitStatus
 
     /**
      * If the process was terminated by a signal, returns that signal.
+     *
+     * @api
      */
     public function signal(): ?int
     {
@@ -48,6 +58,8 @@ final readonly class ExitStatus
 
     /**
      * If the process was stopped by a signal, returns that signal.
+     *
+     * @api
      */
     public function stoppedSignal(): ?int
     {

src/Stdio.php

@@ -23,13 +23,13 @@ abstract class Stdio
     {
         return new class implements StdioInterface {
             #[Override]
-            public function getDescriptionSpec(int $fd): mixed
+            public function getDescriptiorSpec(int $fd): mixed
             {
                 return match ($fd) {
                     0 => STDIN,
                     1 => STDOUT,
                     2 => STDERR,
-                    default => ['php://fd/' . $fd, 'w+'],
+                    default => ['file', 'php://fd/' . $fd, 'w+'],
                 };
             }
         };
@@ -41,8 +41,11 @@ abstract class Stdio
     public static function piped(): StdioInterface
     {
         return new class implements StdioInterface {
+            /**
+             * @return list<string>
+             */
             #[Override]
-            public function getDescriptionSpec(int $fd): mixed
+            public function getDescriptiorSpec(int $fd): mixed
             {
                 return match ($fd) {
                     0 => ['pipe', 'r'],
@@ -60,8 +63,11 @@ abstract class Stdio
     public static function null(): StdioInterface
     {
         return new class implements StdioInterface {
+            /**
+             * @return list<string>
+             */
             #[Override]
-            public function getDescriptionSpec(int $fd): mixed
+            public function getDescriptiorSpec(int $fd): mixed
             {
                 // TODO: Support windows (I think you just write to `nul` in any
                 //       directory?)
@@ -86,8 +92,11 @@ abstract class Stdio
                 private string $mode,
             ) {}
 
+            /**
+             * @return list<string>
+             */
             #[Override]
-            public function getDescriptionSpec(int $fd): mixed
+            public function getDescriptiorSpec(int $fd): mixed
             {
                 return ['file', $this->filename, $this->mode];
             }
@@ -109,10 +118,17 @@ abstract class Stdio
         }
 
         return new class($stream) implements StdioInterface {
-            public function __construct(private mixed $stream) {}
+            /**
+             * @param resource $stream
+             */
+            public function __construct(private mixed $stream)
+            {}
 
+            /**
+             * @return resource
+             */
             #[Override]
-            public function getDescriptionSpec(int $fd): mixed
+            public function getDescriptiorSpec(int $fd): mixed
             {
                 return $this->stream;
             }

src/StdioInterface.php

@@ -4,9 +4,6 @@ declare(strict_types=1);
 
 namespace Nih\CommandBuilder;
 
-use InvalidArgumentException;
-use Stringable;
-
 /**
  * Describes what to do with a standard I/O stream for a child process when
  * passed to the stdin, stdout, and stderr methods of {@see Command}.
@@ -14,7 +11,7 @@ use Stringable;
 interface StdioInterface
 {
     /**
-     * @return resource|array{0: 'file', 1: string, 2: string}|array{0: 'pipe', 1: string}
+     * @return resource|list<string>
      */
-    public function getDescriptionSpec(int $fd): mixed;
+    public function getDescriptiorSpec(int $fd): mixed;
 }

src/StreamException.php

@@ -5,6 +5,38 @@ declare(strict_types=1);
 namespace Nih\CommandBuilder;
 
 /**
- * An error prevented reading from or writing to a stream resource.
+ * A PHP error occured during an operation on a stream resource.
  */
-class StreamException extends CommandException {}
+final class StreamException extends CommandException
+{
+    /**
+     * A note on handling IO errors by setting an error handler before each
+     * operation: Yes, this is slower, but not by much (1.5x).
+     *
+     * However, it is even slower if wrapped with another function, so it is better
+     * to do this inline every time before the function (e.g. fopen) is called.
+     *
+     * ```php
+     * try {
+     *     set_error_handler(CommandException::handleError(...));
+     *     $handle = fopen('foo', 'r');
+     * } finally {
+     *     restore_error_handler();
+     * }
+     * ```
+     */
+    public static function handleError(
+        int $severity,
+        string $message,
+        string $filename,
+        int $line,
+    ): never {
+        throw new self(
+            message: $message,
+            code: 0,
+            severity: $severity,
+            filename: $filename,
+            line: $line,
+        );
+    }
+}

src/StreamReadTrait.php

@@ -9,6 +9,8 @@ trait StreamReadTrait
     use StreamTrait;
 
     /**
+     * @param int<1, max> $length
+     *
      * @throws StreamException
      */
     public function read(int $length): ?string
@@ -30,6 +32,8 @@ trait StreamReadTrait
     }
 
     /**
+     * @param int<1, max>|null $length
+     *
      * @throws StreamException
      */
     public function getContents(?int $length = null, int $offset = -1): string

src/StreamTrait.php

@@ -13,7 +13,7 @@ trait StreamTrait
      *
      * @throws InvalidArgumentException When stream is not a stream
      */
-    public function __construct(private readonly mixed $stream)
+    public function __construct(private mixed $stream)
     {
         if (get_resource_type($stream) !== 'stream') {
             throw new InvalidArgumentException('resource is not a stream');
@@ -33,6 +33,13 @@ trait StreamTrait
             return;
         }
 
+        /**
+         * Psalm is not happy that we close the resource, but I could not
+         * find any way to annotate it so psalm understands what we do
+         * here...
+         *
+         * @psalm-suppress InvalidPropertyAssignmentValue
+         */
         try {
             set_error_handler(StreamException::handleError(...));
             $success = fclose($this->stream);

src/StreamWriteTrait.php

@@ -9,6 +9,8 @@ trait StreamWriteTrait
     use StreamTrait;
 
     /**
+     * @param int<0, max>|null $length
+     *
      * @throws StreamException
      */
     public function write(string $data, ?int $length = null): int

tests/integration/CommandIntegrationTest.php

@@ -0,0 +1,188 @@
+<?php
+
+namespace Nih\CommandBuilder;
+
+use InvalidArgumentException;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\Attributes\CoversTrait;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(Child::class)]
+#[CoversClass(ChildException::class)]
+#[CoversClass(ChildStdout::class)]
+#[CoversClass(Command::class)]
+#[CoversClass(ExitStatus::class)]
+#[CoversClass(Output::class)]
+#[CoversClass(Stdio::class)]
+#[CoversTrait(StreamReadTrait::class)]
+#[CoversTrait(StreamWriteTrait::class)]
+final class CommandIntegrationTest extends TestCase
+{
+    public function testStatus(): void
+    {
+        $this->assertTrue(new Command('true')->status()->success());
+    }
+
+    /**
+     * Test that the stdin, stdout, and stderr handles are captured.
+     */
+    public function testOutput(): void
+    {
+        $output = new Command('true')
+            ->stdin(Stdio::null())
+            ->stdout(Stdio::null())
+            ->stderr(Stdio::null())
+            ->output();
+
+        $this->assertTrue($output->status->success());
+    }
+
+    public function testChildOnlyAcceptsProcesses(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $handle = fopen('php://memory', 'w');
+        $this->assertNotFalse($handle);
+        new Child($handle, []);
+    }
+
+    /**
+     * Test that the stdin, stdout, and stderr handles are captured.
+     */
+    public function testChild(): void
+    {
+        $child = new Command('/usr/bin/sleep')
+            ->stdin(Stdio::null())
+            ->stdout(Stdio::null())
+            ->stderr(Stdio::null())
+            ->arg('1000')
+            ->spawn();
+
+        $this->assertGreaterThan(1, $child->id());
+
+        $child->kill();
+
+        $status = $child->wait();
+
+        $this->assertEquals(null, $status->code());
+        $this->assertEquals(9, $status->signal());
+        $this->assertEquals(null, $status->stoppedSignal());
+
+        // Killing and waiting after the child exited does nothing.
+        $child->kill();
+        $this->assertSame($child->wait(), $status);
+        $output = $child->waitWithOutput();
+        $this->assertSame($output->status, $status);
+        $this->assertSame($child->waitWithOutput(), $output);
+    }
+
+    public function testChildDestructor(): void
+    {
+        $process = proc_open(
+            ['true'],
+            [
+                0 => ['pipe', 'w'],
+                1 => ['pipe', 'r'],
+                2 => ['pipe', 'r'],
+            ],
+            $pipes,
+        );
+
+        $this->assertNotFalse($process);
+
+        $child = new Child($process, $pipes);
+
+        $this->assertEquals('process', get_resource_type($process));
+        $this->assertEquals('stream', get_resource_type($pipes[0]));
+        $this->assertEquals('stream', get_resource_type($pipes[1]));
+        $this->assertEquals('stream', get_resource_type($pipes[2]));
+
+        unset($child);
+        gc_collect_cycles();
+
+        $this->assertEquals('Unknown', get_resource_type($process));
+        $this->assertEquals('Unknown', get_resource_type($pipes[0]));
+        $this->assertEquals('Unknown', get_resource_type($pipes[1]));
+        $this->assertEquals('Unknown', get_resource_type($pipes[2]));
+    }
+
+    public function testStdio(): void
+    {
+        if (PHP_OS_FAMILY === 'Windows') {
+            $this->markTestSkipped();
+        }
+
+        $cat = new Command('cat')
+            ->stdin(Stdio::piped())
+            ->stdout(Stdio::piped())
+            ->stderr(Stdio::piped())
+            ->spawn();
+
+        $cat->stdin?->write('Hello, World!');
+        $cat->stdin?->close();
+
+        $this->assertNotNull($cat->stdout);
+
+        $output = new Command('cat')
+            ->stdin($cat->stdout)
+            ->output();
+
+        $this->assertTrue($cat->wait()->success());
+        $this->assertTrue($output->status->success());
+
+        $this->assertEquals('Hello, World!', $output->stdout);
+        $this->assertEquals('', $output->stderr);
+    }
+
+    public function testThrowsOnNotExecutable(): void
+    {
+        $this->expectException(ChildException::class);
+        new Command(uniqid())->spawn();
+    }
+
+    public function testEnv(): void
+    {
+        if (PHP_OS_FAMILY === 'Windows') {
+            $this->markTestSkipped();
+        }
+
+        $output = new Command('env')
+            ->envClear()
+            ->envs([
+                'FOO' => 'foo',
+                'BAR' => 'bar',
+                'BAZ' => 'baz',
+            ])
+            ->envRemove('FOO')
+            ->output();
+
+        $this->assertTrue($output->status->success());
+        $this->assertEquals("BAR=bar\nBAZ=baz\n", $output->stdout);
+    }
+
+    public function testEnvInherit(): void
+    {
+        if (PHP_OS_FAMILY === 'Windows') {
+            $this->markTestSkipped();
+        }
+
+        $home = getenv('HOME');
+        $this->assertIsString($home, 'Congratulations! You have a weird system');
+
+        $child = new Command('env')
+            ->stdout(Stdio::piped())
+            ->env('FOO', 'foo')
+            ->spawn();
+
+        $this->assertNotNull($child->stdout);
+
+        $envs = [];
+        foreach (explode(PHP_EOL, $child->stdout->getContents()) as $line) {
+            [$var, $val] = explode('=', $line);
+            $envs[$var] = $val;
+        }
+
+        $this->assertEquals($home, $envs['HOME']);
+        $this->assertEquals('foo', $envs['FOO']);
+    }
+}

tests/unit/CommandTest.php

@@ -0,0 +1,116 @@
+<?php
+
+namespace Nih\CommandBuilder;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use ValueError;
+
+#[CoversClass(Command::class)]
+#[CoversClass(Stdio::class)]
+#[CoversClass(StreamException::class)]
+#[CoversClass(ChildException::class)]
+final class CommandTest extends TestCase
+{
+    public function testChildErrorHandling(): void
+    {
+        $this->expectException(ChildException::class);
+
+        try {
+            set_error_handler(ChildException::handleError(...));
+            trigger_error('Oh no!');
+        } finally {
+            restore_error_handler();
+        }
+    }
+
+    public function test(): void
+    {
+        $command = new Command('echo');
+
+        $this->assertEquals(
+            'echo',
+            $command->getProgram(),
+        );
+
+        $this->assertNull($command->getCurrentDir());
+
+        $command->currentDir('/tmp');
+
+        $this->assertEquals(
+            '/tmp',
+            $command->getCurrentDir(),
+        );
+
+        $command->arg('foo')->args(['bar', 'baz']);
+
+        $this->assertEquals(
+            ['foo', 'bar', 'baz'],
+            $command->getArgs(),
+        );
+
+        $command->env('FOO', 'foo');
+
+        $this->assertEquals(
+            ['FOO' => 'foo'],
+            $command->getEnvs(),
+        );
+
+        $command->envs([
+            'BAR' => 'bar',
+            'BAZ' => 'baz',
+        ]);
+
+        $this->assertEquals(
+            [
+                'FOO' => 'foo',
+                'BAR' => 'bar',
+                'BAZ' => 'baz',
+            ],
+            $command->getEnvs(),
+        );
+
+        $command->envRemove('BAR');
+
+        $this->assertEquals(
+            [
+                'FOO' => 'foo',
+                'BAR' => null,
+                'BAZ' => 'baz',
+            ],
+            $command->getEnvs(),
+        );
+
+        $command->envClear();
+
+        $this->assertEquals(
+            [],
+            $command->getEnvs(),
+        );
+    }
+
+    public function testStdioFromStream(): void
+    {
+        // Only verifies its okay to pass valid stream resources.
+        $this->expectNotToPerformAssertions();
+
+        new Command('echo')
+            ->stdin(STDIN)
+            ->stdout(STDOUT)
+            ->stderr(STDERR);
+    }
+
+    public function testThrowsOnEmptyProgram(): void
+    {
+        $this->expectException(ValueError::class);
+        new Command('');
+    }
+
+    public function testToString(): void
+    {
+        $this->assertEquals(
+            "'ls' '*' 'foo bar'",
+            (string) new Command('ls')->arg('*')->arg('foo bar'),
+        );
+    }
+}

tests/unit/StdioTest.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace Nih\CommandBuilder;
+
+use InvalidArgumentException;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(Stdio::class)]
+final class StdioTest extends TestCase
+{
+    public function testNull(): void
+    {
+        $null = match (PHP_OS_FAMILY) {
+            'Windows' => 'nul',
+            default => '/dev/null',
+        };
+
+        $this->assertEquals(
+            ['file', $null, 'r'],
+            Stdio::null()->getDescriptiorSpec(0),
+        );
+
+        $this->assertEquals(
+            ['file', $null, 'w'],
+            Stdio::null()->getDescriptiorSpec(1),
+        );
+
+        $this->assertEquals(
+            ['file', $null, 'w'],
+            Stdio::null()->getDescriptiorSpec(2),
+        );
+    }
+
+    public function testInherit(): void
+    {
+        $this->assertEquals(
+            STDIN,
+            Stdio::inherit()->getDescriptiorSpec(0),
+        );
+
+        $this->assertEquals(
+            STDOUT,
+            Stdio::inherit()->getDescriptiorSpec(1),
+        );
+
+        $this->assertEquals(
+            STDERR,
+            Stdio::inherit()->getDescriptiorSpec(2),
+        );
+    }
+
+    public function testFile(): void
+    {
+        $this->assertEquals(
+            ['file', '/foo/bar/baz', 'r'],
+            Stdio::file('/foo/bar/baz', 'r')->getDescriptiorSpec(0),
+        );
+    }
+
+    public function testStream(): void
+    {
+        $this->assertEquals(
+            STDOUT,
+            Stdio::stream(STDOUT)->getDescriptiorSpec(0),
+        );
+    }
+
+    public function testThrowsOnInvalidStream(): void
+    {
+        $handle = fopen('php://memory', 'w');
+        $this->assertNotFalse($handle);
+
+        fclose($handle);
+
+        $this->expectException(InvalidArgumentException::class);
+
+        /** @psalm-suppress InvalidArgument */
+        Stdio::stream($handle);
+    }
+}

tests/unit/StreamTest.php

@@ -0,0 +1,154 @@
+<?php
+
+namespace Nih\CommandBuilder;
+
+use InvalidArgumentException;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\CoversTrait;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(ChildStdin::class)]
+#[CoversClass(ChildStdout::class)]
+#[CoversClass(ChildStderr::class)]
+#[CoversClass(ChildException::class)]
+#[CoversClass(StreamException::class)]
+#[CoversTrait(StreamTrait::class)]
+#[CoversTrait(StreamReadTrait::class)]
+#[CoversTrait(StreamWriteTrait::class)]
+final class StreamTest extends TestCase
+{
+    public function testErrorHandler(): void
+    {
+        $this->expectException(StreamException::class);
+
+        try {
+            set_error_handler(StreamException::handleError(...));
+            trigger_error('Oh no!');
+        } finally {
+            restore_error_handler();
+        }
+    }
+
+
+    public function testOnlyAcceptsStreamResource(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $handle = fopen('php://memory', 'w+');
+        $this->assertNotFalse($handle);
+
+        fwrite($handle, 'test');
+        fclose($handle);
+
+        /** @psalm-suppress InvalidArgument */
+        new class($handle) {
+            use StreamTrait;
+        };
+    }
+
+    public function testReadRead(): void
+    {
+        $handle = fopen('php://memory', 'w+');
+        $this->assertNotFalse($handle);
+
+        fwrite($handle, 'test');
+        fseek($handle, 0);
+
+        $r = new class($handle) {
+            use StreamReadTrait;
+        };
+
+        $this->assertEquals('test', $r->read(4));
+        $this->assertEmpty($r->read(4));
+        $r->close();
+        $this->expectException(StreamException::class);
+        $r->read(4);
+    }
+
+    public function testReadGetContents(): void
+    {
+        $handle = fopen('php://memory', 'w+');
+        $this->assertNotFalse($handle);
+
+        fwrite($handle, 'test');
+        fseek($handle, 0);
+
+        $r = new class($handle) {
+            use StreamReadTrait;
+        };
+
+        $this->assertEquals('test', $r->getContents());
+        $this->assertEmpty($r->getContents());
+        $r->close();
+        $this->expectException(StreamException::class);
+        $r->getContents();
+    }
+
+    public function testWriteWrite(): void
+    {
+        $handle = fopen('php://memory', 'w');
+        $this->assertNotFalse($handle);
+
+        $w = new class($handle) {
+            use StreamWriteTrait;
+        };
+
+        $this->assertEquals(4, $w->write('test'));
+        $w->close();
+        $this->expectException(StreamException::class);
+        $w->write('test');
+    }
+
+    public function testWriteFlush(): void
+    {
+        $handle = fopen('php://memory', 'w');
+        $this->assertNotFalse($handle);
+
+        $w = new class($handle) {
+            use StreamWriteTrait;
+        };
+
+        $w->flush();
+        $w->close();
+        $this->expectException(StreamException::class);
+        $w->flush();
+    }
+
+    public function testChildStdin(): void
+    {
+        $handle = fopen('php://memory', 'w');
+        $this->assertNotFalse($handle);
+
+        $stdin = new ChildStdin($handle);
+
+        $this->assertEquals(
+            $handle,
+            $stdin->getDescriptiorSpec(0),
+        );
+    }
+
+    public function testChildStdout(): void
+    {
+        $handle = fopen('php://memory', 'r');
+        $this->assertNotFalse($handle);
+
+        $stdout = new ChildStdout($handle);
+
+        $this->assertEquals(
+            $handle,
+            $stdout->getDescriptiorSpec(1),
+        );
+    }
+
+    public function testChildStderr(): void
+    {
+        $handle = fopen('php://memory', 'r');
+        $this->assertNotFalse($handle);
+
+        $stderr = new ChildStderr($handle);
+
+        $this->assertEquals(
+            $handle,
+            $stderr->getDescriptiorSpec(2),
+        );
+    }
+}