cli-kiss 0.2.2 → 0.2.4

package/src/lib/Command.ts

@@ -1,6 +1,4 @@
 import { Operation } from "./Operation";
-import { OptionUsage } from "./Option";
-import { PositionalUsage } from "./Positional";
 import { ReaderArgs } from "./Reader";
 import {
   TypoError,
@@ -9,176 +7,108 @@ import {
   typoStyleUserInput,
   TypoText,
 } from "./Typo";
+import { UsageCommand, UsageSegment } from "./Usage";
 
 /**
- * Describes a CLI command: how to parse its arguments from raw CLI input and how to
- * execute it within a given context.
+ * A CLI command. Created with {@link command}, {@link commandWithSubcommands}, or {@link commandChained}.
  *
- * A `Command` is the central building block of a `cli-kiss` CLI.
- * You create one with {@link command}, {@link commandWithSubcommands},
- * or {@link commandChained}, and pass it to {@link runAndExit} to run your CLI.
- *
- * @typeParam Context - The value passed into the command when it is executed. It flows
- *   from {@link runAndExit}'s `context` argument down through the command chain.
- * @typeParam Result - The value produced by executing the command. For root commands
- *   passed to {@link runAndExit} this is always `void`.
+ * @typeParam Context - Injected at execution; forwarded to handlers.
+ * @typeParam Result - Produced on execution; typically `void`.
  */
 export type Command<Context, Result> = {
   /**
-   * Returns the static metadata information about this command.
+   * Returns static metadata.
    */
   getInformation(): CommandInformation;
   /**
-   * Parses `readerArgs` and returns a {@link CommandFactory} that can generate usage
-   * information or create a ready-to-run {@link CommandInstance}.
-   *
-   * Parsing errors are captured and deferred: `createFactory` never throws; instead
-   * the error surfaces when {@link CommandFactory.createInstance} is called on the
-   * returned factory.
+   * Registers options/positionals on `readerArgs`; returns a {@link CommandDecoder}.
    */
-  createFactory(readerArgs: ReaderArgs): CommandFactory<Context, Result>;
+  consumeAndMakeDecoder(
+    readerArgs: ReaderArgs,
+  ): CommandDecoder<Context, Result>;
 };
 
 /**
- * Produced by {@link Command.createFactory} after the raw CLI arguments have
- * been parsed. Provides two capabilities:
+ * Produced by {@link Command.consumeAndMakeDecoder}.
  *
- * 1. **Usage generation** — always available, even when parsing failed.
- * 2. **Instance creation** — throws a {@link TypoError} if parsing failed.
- *
- * @typeParam Context - Input passed to the command {@link Command}.
- * @typeParam Result - Result of the command's logic {@link Command}.
+ * @typeParam Context - See {@link Command}.
+ * @typeParam Result - See {@link Command}.
  */
-export type CommandFactory<Context, Result> = {
+export type CommandDecoder<Context, Result> = {
   /**
-   * Builds the complete {@link CommandUsage} for the currently parsed command path.
-   * This is called to render the `--help` output and on error when `usageOnError`
-   * is enabled.
+   * Returns {@link UsageCommand} for the current command path.
    */
-  generateUsage(): CommandUsage;
+  generateUsage(): UsageCommand;
   /**
-   * Creates a {@link CommandInstance} that is ready to execute.
+   * Creates a ready-to-execute {@link CommandInterpreter}.
    *
-   * @throws {@link TypoError} if the argument parsing that occurred during
-   *   {@link Command.createFactory} encountered an error (e.g. unknown
-   *   option, missing required positional, invalid type).
+   * @throws {@link TypoError} if parsing or decoding failed.
    */
-  createInstance(): CommandInstance<Context, Result>;
+  decodeAndMakeInterpreter(): CommandInterpreter<Context, Result>;
 };
 
 /**
- * A fully parsed, ready-to-execute command.
+ * A fully parsed, decoded and ready-to-execute command.
  *
- * @typeParam Context - The value the caller must provide when executing the command.
- * @typeParam Result - The value the command produces on successful execution.
+ * @typeParam Context - Context passed to the handler.
+ * @typeParam Result - Value produced on success.
  */
-export type CommandInstance<Context, Result> = {
+export type CommandInterpreter<Context, Result> = {
   /**
-   * Executes the command with the provided context.
-   *
-   * @param context - Arbitrary value injected by the caller (see {@link runAndExit}).
-   * @returns A promise that resolves to the command's result, or rejects if the
-   *   command handler throws.
+   * Executes with the provided context.
    */
   executeWithContext(context: Context): Promise<Result>;
 };
 
 /**
- * Static, human-readable metadata attached to a command.
- *
- * This information is displayed in the usage/help output produced by {@link usageToStyledLines}.
+ * Command metadata shown in `--help` output.
  */
 export type CommandInformation = {
-  /** Short description of what the command does. Shown prominently in the usage header. */
+  /**
+   * Shown in the usage header.
+   */
   description: string;
   /**
-   * Optional supplementary note shown in parentheses next to the description.
-   * Suitable for short caveats such as `"deprecated"` or `"experimental"`.
+   * Shown in parentheses, e.g. `"deprecated"`, `"experimental"`.
    */
   hint?: string;
   /**
-   * Optional list of additional detail lines printed below the description.
-   * Useful for multi-line explanations, examples, or caveats that don't fit in
-   * a single sentence.
+   * Extra lines printed below the description.
    */
   details?: Array<string>;
-  // TODO - printable examples ?
-};
-
-/**
- * The full usage/help model for a command as it appears after argument parsing.
- *
- * This is produced by {@link CommandFactory.generateUsage} and consumed by
- * {@link usageToStyledLines} to render the `--help` output.
- */
-export type CommandUsage = {
   /**
-   * Ordered list of breadcrumb segments that form the command's usage line, e.g.:
-   * `Usage: my-cli <POSITIONAL> subcommand <ANOTHER_POSITIONAL>`.
-   *
-   * Each element is either a positional placeholder or a literal subcommand name.
+   * Shown in the `Examples:` section.
    */
-  breadcrumbs: Array<CommandUsageBreadcrumb>;
-  /** The command's static metadata (description, hint, details). */
-  information: CommandInformation;
-  /**
-   * Positional arguments that belong to the current command path,
-   * in the order they must appear on the command line.
-   */
-  positionals: Array<PositionalUsage>;
-  /**
-   * Subcommands available at the current level of the command hierarchy.
-   * Non-empty only when the command is a {@link commandWithSubcommands} and the
-   * subcommand selection could not be resolved (i.e. on error or `--help`).
-   */
-  subcommands: Array<CommandUsageSubcommand>;
-  /**
-   * Options (flags and valued options) accepted by the current command path,
-   * in the order they were registered.
-   */
-  options: Array<OptionUsage>;
-};
-
-/**
- * A single element in the usage breadcrumb trail shown at the top of the help output.
- *
- * - `{ positional: string }` — A positional placeholder such as `<NAME>` or `[FILE]`.
- * - `{ command: string }` — A literal subcommand token such as `deploy`.
- */
-export type CommandUsageBreadcrumb =
-  | { positional: string }
-  | { command: string };
-
-/**
- * Summary information about a single subcommand shown in the `Subcommands:` section
- * of the usage output.
- */
-export type CommandUsageSubcommand = {
-  /** The literal token the user types to select this subcommand (e.g. `"deploy"`). */
-  name: string;
-  /** Short description forwarded from the subcommand's {@link CommandInformation}. */
-  description: string | undefined;
-  /** Optional hint forwarded from the subcommand's {@link CommandInformation}. */
-  hint: string | undefined;
+  examples?: Array<{
+    /**
+     * Explanation shown above the example.
+     */
+    explanation: string;
+    /**
+     * Example command args.
+     */
+    commandArgs: Array<
+      | string
+      | { positional: string }
+      | { subcommand: string }
+      | {
+          option:
+            | { long: string; value?: string }
+            | { short: string; value?: string };
+        }
+    >;
+  }>;
 };
 
 /**
- * Creates a leaf command — a command that has no subcommands and directly executes
- * an {@link Operation}.
- *
- * During parsing, `command` reads all positionals and options consumed by `operation`,
- * then asserts that no extra positionals remain. Any unexpected trailing positional
- * causes a {@link TypoError} deferred to {@link CommandFactory.createInstance}.
+ * Creates a leaf command that directly executes an {@link Operation}.
  *
- * @typeParam Context - The context value forwarded to the operation handler at
- *   execution time.
- * @typeParam Result - The value returned by the operation handler.
+ * @typeParam Context - Context forwarded to the handler.
+ * @typeParam Result - Value returned by the handler.
  *
- * @param information - Static metadata (description, hint, details) for the command.
- * @param operation - The operation that defines options, positionals, and the execution
- *   handler for this command.
- * @returns A {@link Command} suitable for passing to {@link runAndExit}
- *   or composing with {@link commandWithSubcommands} / {@link commandChained}.
+ * @param information - Command metadata.
+ * @param operation - Options, positionals, and handler.
+ * @returns A {@link Command}.
  *
  * @example
  * ```ts
@@ -199,21 +129,9 @@ export function command<Context, Result>(
     getInformation() {
       return information;
     },
-    createFactory(readerArgs: ReaderArgs) {
-      function generateUsage(): CommandUsage {
-        const operationUsage = operation.generateUsage();
-        return {
-          breadcrumbs: operationUsage.positionals.map((positional) =>
-            breadcrumbPositional(positional.label),
-          ),
-          information: information,
-          positionals: operationUsage.positionals,
-          subcommands: [],
-          options: operationUsage.options,
-        };
-      }
+    consumeAndMakeDecoder(readerArgs: ReaderArgs) {
       try {
-        const operationFactory = operation.createFactory(readerArgs);
+        const operationDecoder = operation.consumeAndMakeDecoder(readerArgs);
         const endPositional = readerArgs.consumePositional();
         if (endPositional !== undefined) {
           throw new TypoError(
@@ -224,20 +142,21 @@ export function command<Context, Result>(
           );
         }
         return {
-          generateUsage,
-          createInstance() {
-            const operationInstance = operationFactory.createInstance();
+          generateUsage: () => generateUsageLeaf(information, operation),
+          decodeAndMakeInterpreter() {
+            const operationInterpreter =
+              operationDecoder.decodeAndMakeInterpreter();
             return {
               async executeWithContext(context: Context) {
-                return await operationInstance.executeWithContext(context);
+                return await operationInterpreter.executeWithContext(context);
               },
             };
           },
         };
       } catch (error) {
         return {
-          generateUsage,
-          createInstance() {
+          generateUsage: () => generateUsageLeaf(information, operation),
+          decodeAndMakeInterpreter() {
             throw error;
           },
         };
@@ -247,34 +166,16 @@ export function command<Context, Result>(
 }
 
 /**
- * Creates a command that first runs an {@link Operation} to produce an
- * intermediate `Payload`, then dispatches execution to one of several named subcommands
- * based on the next positional argument.
+ * Creates a command that runs `operation` first, then dispatches to a named subcommand.
  *
- * **Parsing behaviour:**
- * 1. The `operation`'s positionals and options are parsed from `readerArgs`.
- * 2. The next positional token is consumed as the subcommand name.
- *    - If no token is present, a {@link TypoError} is deferred.
- *    - If the token does not match any key in `subcommands`, a {@link TypoError} is
- *      deferred.
- * 3. The matched subcommand's factory is created with the remaining `readerArgs`.
+ * @typeParam Context - Context accepted by `operation`.
+ * @typeParam Payload - Output of `operation`; becomes the subcommand's context.
+ * @typeParam Result - Value produced by the selected subcommand.
  *
- * **Usage on error / `--help`:** when the subcommand cannot be determined, the usage
- * output lists all available subcommands under a `Subcommands:` section.
- *
- * @typeParam Context - The context value accepted by the root operation handler.
- * @typeParam Payload - The value produced by the root operation and forwarded as the
- *   context to the selected subcommand.
- * @typeParam Result - The value produced by the selected subcommand.
- *
- * @param information - Static metadata shown in the top-level usage when no valid
- *   subcommand has been selected.
- * @param operation - The operation that is always executed first, before the
- *   subcommand. Its output becomes the subcommand's context.
- * @param subcommands - A map of lowercase subcommand names to their
- *   {@link Command}s. The keys are the literal tokens the user types.
- * @returns A {@link Command} that dispatches to one of the provided
- *   subcommands.
+ * @param information - Command metadata.
+ * @param operation - Runs first; output becomes the subcommand's context.
+ * @param subcommands - Map of subcommand names to their {@link Command}s.
+ * @returns A dispatching {@link Command}.
  *
  * @example
  * ```ts
@@ -297,9 +198,9 @@ export function commandWithSubcommands<Context, Payload, Result>(
     getInformation() {
       return information;
     },
-    createFactory(readerArgs: ReaderArgs) {
+    consumeAndMakeDecoder(readerArgs: ReaderArgs) {
       try {
-        const operationFactory = operation.createFactory(readerArgs);
+        const operationDecoder = operation.consumeAndMakeDecoder(readerArgs);
         const subcommandName = readerArgs.consumePositional();
         if (subcommandName === undefined) {
           throw new TypoError(
@@ -320,31 +221,29 @@ export function commandWithSubcommands<Context, Payload, Result>(
             ),
           );
         }
-        const subcommandFactory = subcommandInput.createFactory(readerArgs);
+        const subcommandDecoder =
+          subcommandInput.consumeAndMakeDecoder(readerArgs);
         return {
           generateUsage() {
-            const operationUsage = operation.generateUsage();
-            const subcommandUsage = subcommandFactory.generateUsage();
-            return {
-              breadcrumbs: operationUsage.positionals
-                .map((positional) => breadcrumbPositional(positional.label))
-                .concat([breadcrumbCommand(subcommandName)])
-                .concat(subcommandUsage.breadcrumbs),
-              information: subcommandUsage.information,
-              positionals: operationUsage.positionals.concat(
-                subcommandUsage.positionals,
-              ),
-              subcommands: subcommandUsage.subcommands,
-              options: operationUsage.options.concat(subcommandUsage.options),
-            };
+            const subcommandUsage = subcommandDecoder.generateUsage();
+            const currentUsage = generateUsageLeaf(information, operation);
+            currentUsage.segments.push(segmentSubcommand(subcommandName));
+            currentUsage.segments.push(...subcommandUsage.segments);
+            currentUsage.information = subcommandUsage.information;
+            currentUsage.positionals.push(...subcommandUsage.positionals);
+            currentUsage.subcommands = subcommandUsage.subcommands;
+            currentUsage.options.push(...subcommandUsage.options);
+            return currentUsage;
           },
-          createInstance() {
-            const operationInstance = operationFactory.createInstance();
-            const subcommandInstance = subcommandFactory.createInstance();
+          decodeAndMakeInterpreter() {
+            const operationInterpreter =
+              operationDecoder.decodeAndMakeInterpreter();
+            const subcommandInterpreter =
+              subcommandDecoder.decodeAndMakeInterpreter();
             return {
               async executeWithContext(context: Context) {
-                return await subcommandInstance.executeWithContext(
-                  await operationInstance.executeWithContext(context),
+                return await subcommandInterpreter.executeWithContext(
+                  await operationInterpreter.executeWithContext(context),
                 );
               },
             };
@@ -353,25 +252,15 @@ export function commandWithSubcommands<Context, Payload, Result>(
       } catch (error) {
         return {
           generateUsage() {
-            const operationUsage = operation.generateUsage();
-            return {
-              breadcrumbs: operationUsage.positionals
-                .map((positional) => breadcrumbPositional(positional.label))
-                .concat([breadcrumbPositional("<SUBCOMMAND>")]),
-              information: information,
-              positionals: operationUsage.positionals,
-              subcommands: Object.entries(subcommands).map((subcommand) => {
-                const metadata = subcommand[1].getInformation();
-                return {
-                  name: subcommand[0],
-                  description: metadata.description,
-                  hint: metadata.hint,
-                };
-              }),
-              options: operationUsage.options,
-            };
+            const currentUsage = generateUsageLeaf(information, operation);
+            currentUsage.segments.push(segmentPositional("<SUBCOMMAND>"));
+            for (const [name, subcommand] of Object.entries(subcommands)) {
+              const { description, hint } = subcommand.getInformation();
+              currentUsage.subcommands.push({ name, description, hint });
+            }
+            return currentUsage;
           },
-          createInstance() {
+          decodeAndMakeInterpreter() {
             throw error;
           },
         };
@@ -381,36 +270,17 @@ export function commandWithSubcommands<Context, Payload, Result>(
 }
 
 /**
- * Creates a command that chains two command stages by piping the output of an
- * {@link Operation} directly into a {@link Command} as its context.
+ * Chains an {@link Operation} and a {@link Command}: `operation` runs first, its
+ * output becomes `subcommand`'s context. No token is consumed for routing.
  *
- * Unlike {@link commandWithSubcommands}, there is no runtime token consumed for routing;
- * the `nextCommand` is always the continuation. This is useful for splitting a complex
- * command into reusable pieces, such as a shared authentication step followed by
- * different sub-actions.
+ * @typeParam Context - Context accepted by `operation`.
+ * @typeParam Payload - Output of `operation`; becomes `subcommand`'s context.
+ * @typeParam Result - Value produced by `subcommand`.
  *
- * **Parsing behaviour:**
- * 1. `operation`'s positionals and options are parsed.
- * 2. `nextCommand`'s factory is immediately created from the same `readerArgs` (the
- *    remaining unparsed tokens).
- * 3. At execution time, `operation` runs first; its result is passed as the context to
- *    `nextCommand`.
- *
- * **Usage:** breadcrumbs, positionals, and options from both stages are merged into a
- * single flat usage description. The `information` of `nextCommand` takes precedence in
- * the generated usage output.
- *
- * @typeParam Context - The context value accepted by `operation`.
- * @typeParam Payload - The value produced by `operation` and used as the context for
- *   `nextCommand`.
- * @typeParam Result - The value produced by `nextCommand`.
- *
- * @param information - Fallback metadata used in the usage output when `nextCommand`'s
- *   factory cannot be created (i.e. on parse error in the next stage).
- * @param operation - The first stage operation. Its output becomes `nextCommand`'s
- *   context.
- * @param nextCommand - The second stage command, executed after `operation` succeeds.
- * @returns A {@link Command} that transparently composes the two stages.
+ * @param information - Command metadata.
+ * @param operation - Runs first; output becomes `subcommand`'s context.
+ * @param subcommand - Runs after `operation`.
+ * @returns A {@link Command} composing both stages.
  *
  * @example
  * ```ts
@@ -427,39 +297,36 @@ export function commandWithSubcommands<Context, Payload, Result>(
 export function commandChained<Context, Payload, Result>(
   information: CommandInformation,
   operation: Operation<Context, Payload>,
-  nextCommand: Command<Payload, Result>,
+  subcommand: Command<Payload, Result>,
 ): Command<Context, Result> {
   return {
     getInformation() {
       return information;
     },
-    createFactory(readerArgs: ReaderArgs) {
+    consumeAndMakeDecoder(readerArgs: ReaderArgs) {
       try {
-        const operationFactory = operation.createFactory(readerArgs);
-        const nextCommandFactory = nextCommand.createFactory(readerArgs);
+        const operationDecoder = operation.consumeAndMakeDecoder(readerArgs);
+        const subcommandDecoder = subcommand.consumeAndMakeDecoder(readerArgs);
         return {
           generateUsage() {
-            const operationUsage = operation.generateUsage();
-            const nextCommandUsage = nextCommandFactory.generateUsage();
-            return {
-              breadcrumbs: operationUsage.positionals
-                .map((positional) => breadcrumbPositional(positional.label))
-                .concat(nextCommandUsage.breadcrumbs),
-              information: nextCommandUsage.information,
-              positionals: operationUsage.positionals.concat(
-                nextCommandUsage.positionals,
-              ),
-              subcommands: nextCommandUsage.subcommands,
-              options: operationUsage.options.concat(nextCommandUsage.options),
-            };
+            const subcommandUsage = subcommandDecoder.generateUsage();
+            const currentUsage = generateUsageLeaf(information, operation);
+            currentUsage.segments.push(...subcommandUsage.segments);
+            currentUsage.information = subcommandUsage.information;
+            currentUsage.positionals.push(...subcommandUsage.positionals);
+            currentUsage.subcommands = subcommandUsage.subcommands;
+            currentUsage.options.push(...subcommandUsage.options);
+            return currentUsage;
           },
-          createInstance() {
-            const operationInstance = operationFactory.createInstance();
-            const nextCommandInstance = nextCommandFactory.createInstance();
+          decodeAndMakeInterpreter() {
+            const operationInterpreter =
+              operationDecoder.decodeAndMakeInterpreter();
+            const subcommandInterpreter =
+              subcommandDecoder.decodeAndMakeInterpreter();
             return {
               async executeWithContext(context: Context) {
-                return await nextCommandInstance.executeWithContext(
-                  await operationInstance.executeWithContext(context),
+                return await subcommandInterpreter.executeWithContext(
+                  await operationInterpreter.executeWithContext(context),
                 );
               },
             };
@@ -468,18 +335,11 @@ export function commandChained<Context, Payload, Result>(
       } catch (error) {
         return {
           generateUsage() {
-            const operationUsage = operation.generateUsage();
-            return {
-              breadcrumbs: operationUsage.positionals
-                .map((positional) => breadcrumbPositional(positional.label))
-                .concat([breadcrumbPositional("[REST]...")]),
-              information: information,
-              positionals: operationUsage.positionals,
-              subcommands: [],
-              options: operationUsage.options,
-            };
+            const currentUsage = generateUsageLeaf(information, operation);
+            currentUsage.segments.push(segmentPositional("[REST]..."));
+            return currentUsage;
           },
-          createInstance() {
+          decodeAndMakeInterpreter() {
             throw error;
           },
         };
@@ -488,10 +348,26 @@ export function commandChained<Context, Payload, Result>(
   };
 }
 
-function breadcrumbPositional(value: string): CommandUsageBreadcrumb {
+function segmentPositional(value: string): UsageSegment {
   return { positional: value };
 }
 
-function breadcrumbCommand(value: string): CommandUsageBreadcrumb {
-  return { command: value };
+function segmentSubcommand(value: string): UsageSegment {
+  return { subcommand: value };
+}
+
+function generateUsageLeaf(
+  information: CommandInformation,
+  operation: Operation<any, any>,
+): UsageCommand {
+  const { positionals, options } = operation.generateUsage();
+  return {
+    segments: positionals.map((positional) =>
+      segmentPositional(positional.label),
+    ),
+    information,
+    positionals,
+    subcommands: [],
+    options,
+  };
 }