Refactor exception handler to v3, use standard shell exitcode

src/StaticPHP/Command/BaseCommand.php

@@ -14,6 +14,8 @@ use ZM\Logger\ConsoleColor;
 
 abstract class BaseCommand extends Command
 {
+    use ReturnCode;
+
     /**
      * The message of the day (MOTD) displayed when the command is run.
      * You can customize this to show your application's name and version if you are using SPC in vendor mode.
@@ -101,12 +103,10 @@ abstract class BaseCommand extends Command
             return $this->handle();
         } /* @noinspection PhpRedundantCatchClauseInspection */ catch (SPCException $e) {
             // Handle SPCException and log it
-            ExceptionHandler::handleSPCException($e);
-            return static::FAILURE;
+            return ExceptionHandler::handleSPCException($e);
         } catch (\Throwable $e) {
             // Handle any other exceptions
-            ExceptionHandler::handleDefaultException($e);
-            return static::FAILURE;
+            return ExceptionHandler::handleDefaultException($e);
         }
     }
 
@@ -129,7 +129,8 @@ abstract class BaseCommand extends Command
 
         // Don't show commit ID when running in phar
         if (\Phar::running()) {
-            return $version;
+            $stable = file_exists(ROOT_DIR . '/src/.release') ? 'stable' : 'unstable';
+            return "{$version} ({$stable})";
         }
 
         $commitId = $this->getGitCommitShortId();

src/StaticPHP/Command/Dev/EnvCommand.php

@@ -29,7 +29,7 @@ class EnvCommand extends BaseCommand
         $env = $this->getArgument('env');
         if (($val = getenv($env)) === false) {
             $this->output->writeln("<error>Environment variable '{$env}' is not set.</error>");
-            return static::FAILURE;
+            return static::USER_ERROR;
         }
         if (is_array($val)) {
             foreach ($val as $k => $v) {

src/StaticPHP/Command/Dev/IsInstalledCommand.php

@@ -29,6 +29,6 @@ class IsInstalledCommand extends BaseCommand
             return static::SUCCESS;
         }
         $this->output->writeln("<error>Package [{$package}] is not installed.</error>");
-        return static::FAILURE;
+        return static::USER_ERROR;
     }
 }

src/StaticPHP/Command/Dev/LintConfigCommand.php

@@ -34,7 +34,7 @@ class LintConfigCommand extends BaseCommand
 
         if ($checkOnly && $hasChanges) {
             $this->output->writeln('<error>Some config files need sorting. Run "bin/spc dev:lint-config" to fix them.</error>');
-            return static::FAILURE;
+            return static::VALIDATION_ERROR;
         }
 
         return static::SUCCESS;
@@ -125,7 +125,7 @@ class LintConfigCommand extends BaseCommand
             return false;
         }
         ksort($data);
-        foreach ($data as $artifact_name => &$config) {
+        foreach ($data as &$config) {
             uksort($config, $config_type === 'artifact' ? [$this, 'artifactSortKey'] : [$this, 'packageSortKey']);
         }
         unset($config);

src/StaticPHP/Command/Dev/ShellCommand.php

@@ -28,6 +28,6 @@ class ShellCommand extends BaseCommand
             return $code;
         }
         $this->output->writeln('<error>Unsupported OS for shell command.</error>');
-        return static::FAILURE;
+        return static::ENVIRONMENT_ERROR;
     }
 }

src/StaticPHP/Command/DoctorCommand.php

@@ -30,6 +30,6 @@ class DoctorCommand extends BaseCommand
             return static::SUCCESS;
         }
 
-        return static::FAILURE;
+        return static::ENVIRONMENT_ERROR;
     }
 }

src/StaticPHP/Command/DumpLicenseCommand.php

@@ -71,7 +71,7 @@ class DumpLicenseCommand extends BaseCommand
             $this->output->writeln('  - --for-extensions: <info>dump-license --for-extensions=openssl,mbstring</info>');
             $this->output->writeln('  - --for-libs: <info>dump-license --for-libs=openssl,zlib</info>');
             $this->output->writeln('  - --for-packages: <info>dump-license --for-packages=php,libssl</info>');
-            return self::FAILURE;
+            return static::USER_ERROR;
         }
 
         // Deduplicate artifacts
@@ -90,11 +90,11 @@ class DumpLicenseCommand extends BaseCommand
             InteractiveTerm::success('Licenses dumped successfully: ' . $dump_dir);
             // $this->output->writeln("<info>✓ Successfully dumped licenses to: {$dump_dir}</info>");
             // $this->output->writeln("<comment>  Total artifacts: " . count($artifacts_to_dump) . '</comment>');
-            return self::SUCCESS;
+            return static::SUCCESS;
         }
 
         $this->output->writeln('<error>Failed to dump licenses</error>');
-        return self::FAILURE;
+        return static::INTERNAL_ERROR;
     }
 
     /**

src/StaticPHP/Command/ExtractCommand.php

@@ -47,7 +47,7 @@ class ExtractCommand extends BaseCommand
                 $artifact = ArtifactLoader::getArtifactInstance($name);
                 if ($artifact === null) {
                     $this->output->writeln("<error>Artifact '{$name}' not found.</error>");
-                    return static::FAILURE;
+                    return static::USER_ERROR;
                 }
                 $artifacts[$name] = $artifact;
             }

src/StaticPHP/Command/ReturnCode.php

@@ -0,0 +1,42 @@
+<?php
+
+/** @noinspection PhpMissingClassConstantTypeInspection */
+
+declare(strict_types=1);
+
+namespace StaticPHP\Command;
+
+/**
+ * Return codes for command execution.
+ *
+ * This enum defines standard return codes that can be used by commands to indicate
+ * the result of their execution. It includes codes for success, various types of errors,
+ * and an interrupt signal.
+ */
+trait ReturnCode
+{
+    public const int OK = 0;
+
+    public const SUCCESS = 0; // alias of OK
+
+    public const int INTERNAL_ERROR = 1; // unsorted or internal error
+
+    /** @deprecated Use specified error code instead */
+    public const FAILURE = 1;
+
+    public const int USER_ERROR = 2; // wrong usage or user error
+
+    public const int ENVIRONMENT_ERROR = 3; // environment not suitable for operation
+
+    public const int VALIDATION_ERROR = 4; // validation failed
+
+    public const int FILE_SYSTEM_ERROR = 5; // file system related error
+
+    public const int DOWNLOAD_ERROR = 6; // network related error
+
+    public const int BUILD_ERROR = 7; // build process error
+
+    public const int PATCH_ERROR = 8; // patching process error
+
+    public const int INTERRUPT_SIGNAL = 130; // process interrupted by user (e.g., Ctrl+C)
+}

src/StaticPHP/Command/SPCConfigCommand.php

@@ -53,6 +53,6 @@ class SPCConfigCommand extends BaseCommand
             default => "{$config['cflags']} {$config['ldflags']} {$config['libs']}",
         });
 
-        return 0;
+        return static::SUCCESS;
     }
 }