feat(Shared): add isDebug() method for robust debug mode check

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: Vitexus

src/Ease/Exception.php

@@ -48,7 +48,7 @@ class Exception extends \Exception
      */
     public function __construct(string $message, int $code = 0, ?self $previous = null)
     {
-        if (\Ease\Shared::cfg('DEBUG', false)) {
+        if (\Ease\Shared::isDebug()) {
             $trace = $this->getTrace();
             $caller = new Molecule();
             $where = $trace[0]['class'].'::'.$trace[0]['function'];

src/Ease/Functions.php

@@ -600,7 +600,7 @@ public static function guidv4($data = null): string
      */
     public static function writeResult(array $result, string $destination = 'php://stdout', ?\Ease\Sand $engine = null)
     {
-        $written = file_put_contents($destination, json_encode($result, Shared::cfg('DEBUG') ? \JSON_PRETTY_PRINT | \JSON_UNESCAPED_UNICODE | \JSON_UNESCAPED_SLASHES : 0));
+        $written = file_put_contents($destination, json_encode($result, Shared::isDebug() ? \JSON_PRETTY_PRINT | \JSON_UNESCAPED_UNICODE | \JSON_UNESCAPED_SLASHES : 0));
 
         if ($engine instanceof \Ease\Sand) {
             $engine->addStatusMessage(sprintf(_('Saving result to %s'), $destination), $written ? 'success' : 'error');

src/Ease/Logger/Logging.php

@@ -94,7 +94,7 @@ public function getLogger(?array $options = null)
      */
     public function logBanner($prefix = '', $suffix = ''): void
     {
-        if (\Ease\Shared::cfg('DEBUG') === true) {
+        if (\Ease\Shared::isDebug()) {
             $suffix .= ' Loggers: '.\Ease\Shared::cfg('EASE_LOGGER');
         }
 

src/Ease/Logger/Regent.php

@@ -163,7 +163,7 @@ public function addStatusObject(Message $message)
         foreach ($this->loggers as $logger) {
             switch ($message->type) {
                 case 'debug':
-                    if ((bool) \Ease\Shared::cfg('DEBUG', false) === false) {
+                    if (\Ease\Shared::isDebug() === false) {
                         break;
                     }
 

src/Ease/Shared.php

@@ -148,6 +148,20 @@ public static function cfg(/* string */ $constant, $cfg = null)
         return $cfg;
     }
 
+    /**
+     * Whether debug mode is on.
+     *
+     * cfg() reads constants/env vars, both of which surface as strings —
+     * PHP's (bool) cast treats any non-empty string (including "false" or
+     * "0") as true, so callers comparing cfg('DEBUG') truthiness directly
+     * flip on debug output for a literal `DEBUG=false` in the environment.
+     * Compare the normalized string instead.
+     */
+    public static function isDebug(): bool
+    {
+        return strtolower((string) self::cfg('DEBUG', 'false')) === 'true';
+    }
+
     /**
      * Application name or "Composer project Name" fallback.
      *

tests/src/Ease/SharedTest.php

@@ -169,4 +169,27 @@ public function testUser(): void
     {
         $this->assertInstanceOf('\Ease\User', \Ease\Shared::user(null, '\Ease\User'));
     }
+
+    /**
+     * Regression test: cfg('DEBUG') always surfaces env vars as strings, so a
+     * literal DEBUG=false in the environment must NOT be treated as enabled —
+     * PHP's (bool) cast on a non-empty string like "false" is true, which is
+     * the bug isDebug() exists to avoid.
+     *
+     * @covers \Ease\Shared::isDebug
+     */
+    public function testIsDebug(): void
+    {
+        putenv('DEBUG=false');
+        $this->assertFalse(\Ease\Shared::isDebug(), 'DEBUG=false (string) must not enable debug mode');
+
+        putenv('DEBUG=true');
+        $this->assertTrue(\Ease\Shared::isDebug(), 'DEBUG=true (string) must enable debug mode');
+
+        putenv('DEBUG=TRUE');
+        $this->assertTrue(\Ease\Shared::isDebug(), 'DEBUG value must be compared case-insensitively');
+
+        putenv('DEBUG');
+        $this->assertFalse(\Ease\Shared::isDebug(), 'Unset DEBUG must default to disabled');
+    }
 }