Merge branch 'cli'

Author: lkrms

.github/workflows/ci.yml

@@ -27,7 +27,6 @@ jobs:
         with:
           php-version: "8.3"
           coverage: none
-          tools: phive
 
       - name: Get Composer cache directory
         id: get-composer-cache
@@ -42,9 +41,7 @@ jobs:
           restore-keys: composer-cache-${{ runner.os }}-
 
       - name: Install PHP dependencies
-        run: |
-          composer install --no-interaction --no-progress
-          phive --no-progress install --trust-gpg-keys E82B2FB314E9906E,E8CC5BC780B581F2
+        run: composer install --no-interaction --no-progress
 
       - name: Check generated files
         run: scripts/generate.php --check

.phive/phars.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <phive xmlns="https://phar.io/phive">
-  <phar name="lkrms/pretty-php" version="^0.4.48" installed="0.4.50" location="./tools/pretty-php" copy="false"/>
-  <phar name="php-cs-fixer" version="^3.46.0" installed="3.48.0" location="./tools/php-cs-fixer" copy="false"/>
-  <phar name="salient-labs/php-changelog" version="^1.0.0" installed="1.0.1" location="./tools/changelog" copy="false"/>
+  <phar name="lkrms/pretty-php" version="^0.4.48" installed="0.4.51" location="./tools/pretty-php" copy="true"/>
+  <phar name="php-cs-fixer" version="^3.46.0" installed="3.48.0" location="./tools/php-cs-fixer" copy="true"/>
+  <phar name="salient-labs/php-changelog" version="^1.0.0" installed="1.0.1" location="./tools/changelog" copy="true"/>
 </phive>

src/Cli/Catalog/CliOptionVisibility.php

@@ -53,6 +53,8 @@ final class CliOptionVisibility extends Enumeration
 
     /**
      * Show the option everywhere
+     *
+     * This is the default.
      */
     public const ALL =
         CliOptionVisibility::SYNOPSIS

src/Cli/CliApplication.php

@@ -41,6 +41,9 @@ class CliApplication extends Application implements ICliApplication
 
     private int $LastExitStatus = 0;
 
+    /**
+     * @inheritDoc
+     */
     public function __construct(
         ?string $basePath = null,
         ?string $appName = null,

src/Cli/CliCommand.php

@@ -791,6 +791,15 @@ final protected function applyOptionValues(
             $_values[$name] = $_value;
             $this->OptionValues[$option->Key] = $_value;
             if ($asArguments) {
+                // If the option has an optional value and no value was given,
+                // store null to ensure it's not expanded on export
+                if (
+                    $option->ValueOptional &&
+                    $option->ValueType !== CliOptionValueType::BOOLEAN &&
+                    $value === true
+                ) {
+                    $value = null;
+                }
                 $this->ArgumentValues[$option->Key] = $value;
             }
         }
@@ -834,21 +843,29 @@ final protected function normaliseOptionValues(
      * returned.
      * @param bool $schema If `true`, an array that maps schema option names to
      * values is returned.
+     * @param bool $unexpand If `true` and an option has an optional value not
+     * given on the command line, replace its value with `null` or `true`.
      * @return array<string,mixed>
      */
     final protected function getOptionValues(
         bool $export = false,
-        bool $schema = false
+        bool $schema = false,
+        bool $unexpand = false
     ): array {
         $this->assertHasRun()->loadOptions();
         $options = $schema ? $this->SchemaOptions : $this->Options;
         foreach ($options as $key => $option) {
-            if ($export && !array_key_exists($option->Key, $this->ArgumentValues)) {
+            $given = array_key_exists($option->Key, $this->ArgumentValues);
+            if ($export && !$given) {
+                continue;
+            }
+            if ($option->ValueOptional && !$option->Required && !$given) {
                 continue;
             }
             $name = $schema ? $key : $option->Name;
             if (
-                $export &&
+                $unexpand &&
+                $given &&
                 $option->ValueOptional &&
                 $this->ArgumentValues[$option->Key] === null
             ) {

src/Cli/CliOption.php

@@ -320,6 +320,8 @@ final class CliOption implements Buildable, HasJsonSchema, IImmutable, IReadable
      * @param array<string|int|bool>|string|int|bool|null $defaultValue
      * @param (callable(array<string|int|bool>|string|int|bool): mixed)|null $valueCallback
      * @param int-mask-of<CliOptionVisibility::*> $visibility
+     * @param bool $inSchema True if the option should be included when
+     * generating a JSON Schema.
      * @param bool $hide True if the option's visibility should be
      * {@see CliOptionVisibility::NONE}.
      * @param mixed $bindTo Bind the option's value to a variable.
@@ -344,6 +346,7 @@ public function __construct(
         ?string $delimiter = ',',
         ?callable $valueCallback = null,
         int $visibility = CliOptionVisibility::ALL,
+        bool $inSchema = false,
         bool $hide = false,
         &$bindTo = null
     ) {
@@ -377,6 +380,10 @@ public function __construct(
         $this->ValueCallback = $valueCallback;
         $this->Visibility = $hide ? CliOptionVisibility::NONE : $visibility;
 
+        if ($inSchema) {
+            $this->Visibility |= CliOptionVisibility::SCHEMA;
+        }
+
         if (func_num_args() >= 20) {
             $this->BindTo = &$bindTo;
             $this->IsBound = true;

src/Cli/CliOptionBuilder.php

@@ -43,6 +43,8 @@ class Application extends Container implements IApplication
 
     private string $BasePath;
 
+    private string $WorkingDirectory;
+
     private bool $RunningFromSource;
 
     // @phpstan-ignore-next-line
@@ -300,6 +302,8 @@ public function __construct(
 
         $this->BasePath = $basePath;
 
+        $this->WorkingDirectory = File::cwd();
+
         $this->RunningFromSource =
             !extension_loaded('Phar') ||
             Phar::running() === '';
@@ -348,6 +352,18 @@ final public function getBasePath(): string
         return $this->BasePath;
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function restoreWorkingDirectory()
+    {
+        if (File::cwd() !== $this->WorkingDirectory) {
+            chdir($this->WorkingDirectory);
+        }
+
+        return $this;
+    }
+
     /**
      * @inheritDoc
      */

src/Container/Application.php

@@ -187,6 +187,13 @@ public function syncNamespace(
         ?string $resolver = null
     );
 
+    /**
+     * Change to the directory in which the application was started
+     *
+     * @return $this
+     */
+    public function restoreWorkingDirectory();
+
     /**
      * Print a summary of the application's runtime performance metrics and
      * system resource usage when it terminates