Merge branch 'cli-v1'

Author: lkrms

lk-util/Command/Generate/GenerateBuilder.php

@@ -168,7 +168,7 @@ protected function run(string ...$args)
         $extends = $this->getFqcnAlias(Builder::class);
 
         $desc = $this->Description === null
-            ? "Creates $classClass objects via a fluent interface"
+            ? "A fluent $classClass factory"
             : $this->Description;
 
         if ($this->IncludeProperties) {

src/Cli/Catalog/CliHelpSectionName.php

@@ -5,7 +5,9 @@
 use Lkrms\Concept\Dictionary;
 
 /**
- * Section names commonly used in help messages / manual pages
+ * Section names commonly used in help messages
+ *
+ * @api
  *
  * @extends Dictionary<string>
  */

src/Cli/Catalog/CliHelpTarget.php

@@ -7,19 +7,21 @@
 /**
  * Help message targets
  *
+ * @api
+ *
  * @extends Enumeration<int>
  */
 final class CliHelpTarget extends Enumeration
 {
     /**
-     * Help is written to a terminal with minimal formatting
+     * Help is written to the console with minimal formatting
      */
     public const PLAIN = 0;
 
     /**
-     * Help is written to a terminal
+     * Help is written to the console with normal formatting
      */
-    public const TTY = 1;
+    public const NORMAL = 1;
 
     /**
      * Help is written as Markdown

src/Cli/Catalog/CliOptionType.php

@@ -7,6 +7,8 @@
 /**
  * Command line option types
  *
+ * @api
+ *
  * @extends Enumeration<int>
  */
 final class CliOptionType extends Enumeration

src/Cli/Catalog/CliOptionValueType.php

@@ -10,6 +10,8 @@
 /**
  * Command line option value types
  *
+ * @api
+ *
  * @extends ConvertibleEnumeration<int>
  */
 final class CliOptionValueType extends ConvertibleEnumeration

src/Cli/Catalog/CliOptionValueUnknownPolicy.php

@@ -8,6 +8,8 @@
  * Unknown value policy for command line options of type ONE_OF, ONE_OF_OPTIONAL
  * and ONE_OF_POSITIONAL
  *
+ * @api
+ *
  * @extends Enumeration<int>
  */
 final class CliOptionValueUnknownPolicy extends Enumeration

src/Cli/Catalog/CliOptionVisibility.php

@@ -7,6 +7,8 @@
 /**
  * Command line option visibility flags
  *
+ * @api
+ *
  * @extends Enumeration<int>
  */
 final class CliOptionVisibility extends Enumeration

src/Cli/CliApplication.php

@@ -4,13 +4,14 @@
 
 use Lkrms\Cli\Catalog\CliHelpSectionName;
 use Lkrms\Cli\Catalog\CliHelpTarget;
-use Lkrms\Cli\Contract\ICliApplication;
+use Lkrms\Cli\Contract\CliApplicationInterface;
+use Lkrms\Cli\Contract\CliCommandInterface;
 use Lkrms\Cli\Exception\CliInvalidArgumentsException;
-use Lkrms\Cli\Support\CliHelpStyle;
 use Lkrms\Console\Support\ConsoleManPageFormat;
 use Lkrms\Console\Support\ConsoleMarkdownFormat;
 use Lkrms\Console\ConsoleFormatter as Formatter;
 use Lkrms\Container\Application;
+use Lkrms\Contract\HasJsonSchema;
 use Lkrms\Facade\Console;
 use Lkrms\Utility\Catalog\EnvFlag;
 use Lkrms\Utility\Arr;
@@ -26,18 +27,18 @@
 /**
  * A service container for CLI applications
  */
-class CliApplication extends Application implements ICliApplication
+class CliApplication extends Application implements CliApplicationInterface
 {
     private const COMMAND_REGEX = '/^[a-z][a-z0-9_-]*$/iD';
 
     /**
-     * @var array<string,class-string<CliCommand>|mixed[]>
+     * @var array<string,class-string<CliCommandInterface>|mixed[]>
      */
     private $CommandTree = [];
 
-    private ?CliCommand $RunningCommand = null;
+    private ?CliCommandInterface $RunningCommand = null;
 
-    private ?CliCommand $LastCommand = null;
+    private ?CliCommandInterface $LastCommand = null;
 
     private int $LastExitStatus = 0;
 
@@ -69,15 +70,15 @@ public function __construct(
     /**
      * @inheritDoc
      */
-    public function getRunningCommand(): ?CliCommand
+    public function getRunningCommand(): ?CliCommandInterface
     {
         return $this->RunningCommand;
     }
 
     /**
      * @inheritDoc
      */
-    public function getLastCommand(): ?CliCommand
+    public function getLastCommand(): ?CliCommandInterface
     {
         return $this->LastCommand;
     }
@@ -91,23 +92,26 @@ public function getLastExitStatus(): int
     }
 
     /**
-     * Get a CliCommand instance from the given node in the command tree
+     * Get a command instance from the given node in the command tree
      *
      * Returns `null` if no command is registered at the given node.
      *
-     * @internal
      * @param string $name The name of the node as a space-delimited list of
      * subcommands.
-     * @param array<string,class-string<CliCommand>|mixed[]>|class-string<CliCommand>|false|null $node The node as returned by {@see CliApplication::getNode()}.
+     * @param array<string,class-string<CliCommandInterface>|mixed[]>|class-string<CliCommandInterface>|false|null $node The node as returned by {@see CliApplication::getNode()}.
      */
-    protected function getNodeCommand(string $name, $node): ?CliCommand
+    protected function getNodeCommand(string $name, $node): ?CliCommandInterface
     {
         if (!is_string($node)) {
             return null;
         }
 
-        if (!(($command = $this->get($node)) instanceof CliCommand)) {
-            throw new LogicException("Not a subclass of CliCommand: $node");
+        if (!(($command = $this->get($node)) instanceof CliCommandInterface)) {
+            throw new LogicException(sprintf(
+                'Does not implement %s: %s',
+                CliCommandInterface::class,
+                $node,
+            ));
         }
         $command->setName($name ? explode(' ', $name) : []);
 
@@ -119,18 +123,17 @@ protected function getNodeCommand(string $name, $node): ?CliCommand
      *
      * Returns one of the following:
      * - `null` if nothing has been added to the tree at `$name`
-     * - the name of the {@see CliCommand} class registered at `$name`
+     * - the name of the {@see CliCommandInterface} class registered at `$name`
      * - an array that maps subcommands of `$name` to their respective nodes
-     * - `false` if a {@see CliCommand} has been registered above `$name`, e.g.
-     *   if `$name` is `["sync", "canvas", "from-sis"]` and a command has been
-     *   registered at `["sync", "canvas"]`
+     * - `false` if a {@see CliCommandInterface} has been registered above
+     *   `$name`, e.g. if `$name` is `["sync", "canvas", "from-sis"]` and a
+     *   command has been registered at `["sync", "canvas"]`
      *
      * Nodes in the command tree are either subcommand arrays (branches) or
-     * {@see CliCommand} class names (leaves).
+     * {@see CliCommandInterface} class names (leaves).
      *
-     * @internal
      * @param string[] $name
-     * @return array<string,class-string<CliCommand>|mixed[]>|class-string<CliCommand>|false|null
+     * @return array<string,class-string<CliCommandInterface>|mixed[]>|class-string<CliCommandInterface>|false|null
      */
     protected function getNode(array $name = [])
     {
@@ -199,11 +202,11 @@ public function command(array $name, string $id)
     /**
      * Get a help message for a command tree node
      *
-     * @param array<string,class-string<CliCommand>|mixed[]>|class-string<CliCommand> $node
+     * @param array<string,class-string<CliCommandInterface>|mixed[]>|class-string<CliCommandInterface> $node
      */
     private function getHelp(string $name, $node, ?CliHelpStyle $style = null): ?string
     {
-        $style ??= new CliHelpStyle(CliHelpTarget::TTY);
+        $style ??= new CliHelpStyle(CliHelpTarget::NORMAL);
 
         $command = $this->getNodeCommand($name, $node);
         if ($command) {
@@ -236,7 +239,7 @@ private function getHelp(string $name, $node, ?CliHelpStyle $style = null): ?str
     /**
      * Get usage information for a command tree node
      *
-     * @param array<string,class-string<CliCommand>|mixed[]>|class-string<CliCommand> $node
+     * @param array<string,class-string<CliCommandInterface>|mixed[]>|class-string<CliCommandInterface> $node
      */
     private function getUsage(string $name, $node): ?string
     {
@@ -378,8 +381,11 @@ public function run()
 
             if ($args && $args[0] === '_json_schema') {
                 array_shift($args);
-                $schema = $command->getJsonSchema($args[0] ?? trim($this->getProgramName() . " $name") . ' options');
-                echo Json::prettyPrint($schema) . \PHP_EOL;
+                $schema = $command->getJsonSchema();
+                echo Json::prettyPrint([
+                    '$schema' => $schema['$schema'] ?? HasJsonSchema::DRAFT_04_SCHEMA_ID,
+                    'title' => $args[0] ?? $schema['title'] ?? trim($this->getProgramName() . " $name") . ' options',
+                ] + $schema) . \PHP_EOL;
                 return $this;
             }
 
@@ -425,7 +431,7 @@ public function runAndExit()
     }
 
     /**
-     * @param array<string,class-string<CliCommand>|mixed[]>|class-string<CliCommand> $node
+     * @param array<string,class-string<CliCommandInterface>|mixed[]>|class-string<CliCommandInterface> $node
      * @param int&CliHelpTarget::* $target
      */
     private function generateHelp(string $name, $node, int $target, string ...$args): void