refactor(console): exit codes as enum + int (#741)

Author: brendt

src/Tempest/Console/src/Actions/ExecuteConsoleCommand.php

@@ -21,7 +21,7 @@ public function __construct(
     ) {
     }
 
-    public function __invoke(string $commandName): ExitCode
+    public function __invoke(string $commandName): ExitCode|int
     {
         $callable = $this->getCallable($this->resolveCommandMiddleware($commandName));
 

src/Tempest/Console/src/Console.php

@@ -9,7 +9,7 @@
 
 interface Console
 {
-    public function call(string $command): ExitCode;
+    public function call(string $command): ExitCode|int;
 
     public function readln(): string;
 

src/Tempest/Console/src/ConsoleApplication.php

@@ -57,7 +57,13 @@ public function run(): void
         try {
             $exitCode = ($this->container->get(ExecuteConsoleCommand::class))($this->argumentBag->getCommandName());
 
-            $this->container->get(Kernel::class)->shutdown($exitCode->value);
+            $exitCode = is_int($exitCode) ? $exitCode : $exitCode->value;
+
+            if ($exitCode < 0 || $exitCode > 255) {
+                throw new InvalidExitCode($exitCode);
+            }
+
+            $this->container->get(Kernel::class)->shutdown($exitCode);
         } catch (Throwable $throwable) {
             foreach ($this->appConfig->errorHandlers as $exceptionHandler) {
                 $exceptionHandler->handleException($throwable);

src/Tempest/Console/src/ConsoleMiddleware.php

@@ -8,5 +8,5 @@
 
 interface ConsoleMiddleware
 {
-    public function __invoke(Invocation $invocation, ConsoleMiddlewareCallable $next): ExitCode;
+    public function __invoke(Invocation $invocation, ConsoleMiddlewareCallable $next): ExitCode|int;
 }

src/Tempest/Console/src/ConsoleMiddlewareCallable.php

@@ -14,7 +14,7 @@ public function __construct(
     ) {
     }
 
-    public function __invoke(Invocation $invocation): ExitCode
+    public function __invoke(Invocation $invocation): ExitCode|int
     {
         return ($this->closure)($invocation);
     }

src/Tempest/Console/src/Exceptions/ConsoleErrorHandler.php

@@ -5,16 +5,20 @@
 namespace Tempest\Console\Exceptions;
 
 use Tempest\Console\Console;
+use Tempest\Console\ExitCode;
+use Tempest\Console\HasExitCode;
 use Tempest\Console\Input\ConsoleArgumentBag;
 use Tempest\Container\Tag;
 use Tempest\Core\ErrorHandler;
+use Tempest\Core\Kernel;
 use Tempest\Highlight\Escape;
 use Tempest\Highlight\Highlighter;
 use Throwable;
 
 final readonly class ConsoleErrorHandler implements ErrorHandler
 {
     public function __construct(
+        private Kernel $kernel,
         #[Tag('console')]
         private Highlighter $highlighter,
         private Console $console,
@@ -53,6 +57,10 @@ public function handleException(Throwable $throwable): void
                 ->writeln('<em>-v</em> show more')
                 ->writeln();
         }
+
+        $exitCode = $throwable instanceof HasExitCode ? $throwable->getExitCode() : ExitCode::ERROR;
+
+        $this->kernel->shutdown($exitCode->value);
     }
 
     public function handleError(int $errNo, string $errstr, string $errFile, int $errLine): void

src/Tempest/Console/src/ExitCode.php

@@ -4,10 +4,20 @@
 
 namespace Tempest\Console;
 
+/**
+ * You're free to return any int between 0 and 255 from a console command as exit code.
+ * The meaning of these integer values will be determined by your application.
+ * Alternatively, Tempest provides a closed set of predefined exit codes via this enum.
+ * The exit codes listed here are used by Tempest and assigned a fixed meaning.
+ */
 enum ExitCode: int
 {
     case SUCCESS = 0;
     case ERROR = 1;
     case INVALID = 2;
     case CANCELLED = 25;
+    case CANNOT_EXECUTE = 126;
+    case COMMAND_NOT_FOUND = 127;
+    case INVALID_EXIT_CODE = 128;
+    case TERMINATED = 130;
 }

src/Tempest/Console/src/GenericConsole.php

@@ -43,7 +43,7 @@ public function __construct(
     ) {
     }
 
-    public function call(string $command): ExitCode
+    public function call(string $command): ExitCode|int
     {
         return ($this->executeConsoleCommand)($command);
     }

src/Tempest/Console/src/HasExitCode.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Console;
+
+interface HasExitCode
+{
+    public function getExitCode(): ExitCode;
+}

src/Tempest/Console/src/InvalidExitCode.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Console;
+
+use Exception;
+
+final class InvalidExitCode extends Exception implements HasExitCode
+{
+    public function __construct(int $original)
+    {
+        parent::__construct("An exit code should be between 0 and 255. Instead got {$original}");
+    }
+
+    public function getExitCode(): ExitCode
+    {
+        return ExitCode::INVALID_EXIT_CODE;
+    }
+}