fix: preserve empty-string sentinel in coerce()

Optional params with `--flag=` (or default `''`) bypass `validate()`
entirely, so they reach `coerce()` un-validated. The previous version
ran them through `filter_var($value, FILTER_VALIDATE_BOOLEAN)`, which
silently returns `false` for empty strings -- a behaviour change for
callers (e.g. Cloud's `Patch.php`) that use `''` as a three-state
"not set" sentinel before resolving to `null`.

Now coerce returns early for empty strings, and uses
`FILTER_NULL_ON_FAILURE` for everything else so any unrecognised
input falls back to the original value rather than getting
silently downgraded to `false`.

Spotted by Greptile review on PR #52.

Author: Chirag Aggarwal

src/CLI/CLI.php

@@ -424,15 +424,18 @@ protected function validate(string $key, array $param, $value): void
      * to happen here at the dispatch boundary.
      *
      * Only string inputs are coerced; bool defaults are passed through
-     * untouched.
+     * untouched. Strings that `filter_var` doesn't recognise (including the
+     * empty string, which bypasses `validate()` for optional params) are
+     * passed through unchanged so callers that use `''` as a sentinel for
+     * "not set" keep working.
      *
      * @param  Validator|callable  $validator
      * @param  mixed  $value
      * @return mixed
      */
     protected function coerce(Validator|callable $validator, mixed $value): mixed
     {
-        if (! is_string($value)) {
+        if (! is_string($value) || $value === '') {
             return $value;
         }
 
@@ -444,11 +447,13 @@ protected function coerce(Validator|callable $validator, mixed $value): mixed
             $validator = $validator->getValidator();
         }
 
-        if ($validator instanceof Boolean) {
-            return \filter_var($value, FILTER_VALIDATE_BOOLEAN);
+        if (! ($validator instanceof Boolean)) {
+            return $value;
         }
 
-        return $value;
+        $coerced = \filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);
+
+        return $coerced === null ? $value : $coerced;
     }
 
     public function setContainer(Container $container): self

tests/CLI/CLITest.php

@@ -364,6 +364,30 @@ public function testBooleanParamCoercionUnwrapsNullable(): void
         $this->assertFalse($captured);
     }
 
+    /**
+     * Empty-string params bypass `validate()` when optional, so they reach
+     * `coerce()` un-validated. We must NOT silently turn them into `false`
+     * (callers like Cloud's `Patch.php` use `''` as a "not set" sentinel and
+     * later resolve it to `null`/three-state).
+     */
+    public function testBooleanParamPreservesEmptyStringSentinel(): void
+    {
+        $captured = 'untouched';
+
+        $cli = new CLI(new Generic(), ['test.php', 'build']);
+
+        $cli
+            ->task('build')
+            ->param('commit', '', new Boolean(true), 'Commit changes', true)
+            ->action(function ($commit) use (&$captured) {
+                $captured = $commit;
+            });
+
+        $cli->run();
+
+        $this->assertSame('', $captured);
+    }
+
     public function testNonBooleanValidatorPassesValueThroughUnchanged(): void
     {
         $captured = null;