cli-kiss 0.2.1 → 0.2.3

package/src/lib/Command.ts

@@ -1,4 +1,4 @@
-import { OperationDescriptor } from "./Operation";
+import { Operation } from "./Operation";
 import { OptionUsage } from "./Option";
 import { PositionalUsage } from "./Positional";
 import { ReaderArgs } from "./Reader";
@@ -11,172 +11,160 @@ import {
 } from "./Typo";
 
 /**
- * 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 — parses arguments and executes within a given context.
+ * Created with {@link command}, {@link commandWithSubcommands}, or {@link commandChained}.
+ * Usually passed through {@link runAndExit} to run.
  *
- * A `CommandDescriptor` 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 time; forwarded to handlers. Use to inject dependencies.
+ * @typeParam Result - Value produced on execution; typically `void` for leaf commands.
  */
-export type CommandDescriptor<Context, Result> = {
-  /** Returns the static metadata (description, hint, details) for this command. */
+export type Command<Context, Result> = {
+  /**
+   * Returns the command's 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.
+   * Consumes args in a `readerArgs` and returns a {@link CommandDecoder}.
    */
-  createFactory(readerArgs: ReaderArgs): CommandFactory<Context, Result>;
+  consumeAndMakeDecoder(
+    readerArgs: ReaderArgs,
+  ): CommandDecoder<Context, Result>;
 };
 
 /**
- * Produced by {@link CommandDescriptor.createFactory} after the raw CLI arguments have
- * been parsed. Provides two capabilities:
- *
- * 1. **Usage generation** — always available, even when parsing failed.
- * 2. **Instance creation** — throws a {@link TypoError} if parsing failed.
+ * Produced by {@link Command.consumeAndMakeDecoder}.
  *
- * @typeParam Context - Forwarded from the parent {@link CommandDescriptor}.
- * @typeParam Result - Forwarded from the parent {@link CommandDescriptor}.
+ * @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.
+   * Builds the {@link CommandUsage} for the current command path.
+   * Used for `--help` and `usageOnError`.
    */
   generateUsage(): CommandUsage;
   /**
-   * 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 CommandDescriptor.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 - Caller-supplied context.
+ * @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}.
+ * Static metadata for a command, shown in `--help` output via {@link usageToStyledLines}.
  */
 export type CommandInformation = {
-  /** Short description of what the command does. Shown prominently in the usage header. */
+  /**
+   * Short description 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"`.
+   * Short note 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 ?
+  /**
+   * Examples shown in the `Examples:` section of the usage output.
+   */
+  examples?: Array<{
+    /**
+     * Explanation shown above the example.
+     */
+    explanation: string;
+    /**
+     * Command line args to show as an example of usage.
+     */
+    commandArgs: Array<
+      | string
+      | { positional: string }
+      | { subcommand: string }
+      | {
+          option:
+            | { long: string; value?: string }
+            | { short: string; value?: string };
+        }
+    >;
+  }>;
 };
 
 /**
- * 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.
+ * Full usage/help model.
+ * Produced by {@link CommandDecoder.generateUsage},
+ * Consumed by {@link usageToStyledLines}.
  */
 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.
+   * Segments forming the usage line
+   * (e.g. `my-cli <POSITIONAL> subcommand <ANOTHER_POSITIONAL>`).
+   */
+  segments: Array<CommandUsageSegment>;
+  /**
+   * Command's static metadata.
    */
-  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 in declaration order.
    */
   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`).
+   * Available subcommands. Non-empty when subcommand was not specified.
    */
   subcommands: Array<CommandUsageSubcommand>;
   /**
-   * Options (flags and valued options) accepted by the current command path,
-   * in the order they were registered.
+   * Options in registration order.
    */
   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`.
+ * One element in the usage segment trail.
  */
-export type CommandUsageBreadcrumb =
-  | { positional: string }
-  | { command: string };
+export type CommandUsageSegment = { positional: string } | { command: string };
 
 /**
- * Summary information about a single subcommand shown in the `Subcommands:` section
- * of the usage output.
+ * Subcommand entry 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"`). */
+  /**
+   * Literal token the user types (e.g. `"deploy"`).
+   */
   name: string;
-  /** Short description forwarded from the subcommand's {@link CommandInformation}. */
+  /**
+   * Short description from the subcommand's {@link CommandInformation}.
+   */
   description: string | undefined;
-  /** Optional hint forwarded from the subcommand's {@link CommandInformation}. */
+  /**
+   * Hint from the subcommand's {@link CommandInformation}.
+   */
   hint: string | undefined;
 };
 
 /**
- * Creates a leaf command — a command that has no subcommands and directly executes
- * an {@link OperationDescriptor}.
+ * Creates a leaf command that 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}.
+ * @typeParam Context - Context forwarded to the handler.
+ * @typeParam Result - Value returned by the handler.
  *
- * @typeParam Context - The context value forwarded to the operation handler at
- *   execution time.
- * @typeParam Result - The value returned by the operation 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 CommandDescriptor} suitable for passing to {@link runAndExit}
- *   or composing with {@link commandWithSubcommands} / {@link commandChained}.
+ * @param information - Command metadata (description, hint, details).
+ * @param operation - Defines: options, positionals, and the handler.
+ * @returns A {@link Command}.
  *
  * @example
  * ```ts
@@ -191,27 +179,15 @@ export type CommandUsageSubcommand = {
  */
 export function command<Context, Result>(
   information: CommandInformation,
-  operation: OperationDescriptor<Context, Result>,
-): CommandDescriptor<Context, Result> {
+  operation: Operation<Context, Result>,
+): Command<Context, Result> {
   return {
     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(
@@ -222,20 +198,21 @@ export function command<Context, Result>(
           );
         }
         return {
-          generateUsage,
-          createInstance() {
-            const operationInstance = operationFactory.createInstance();
+          generateUsage: () => generateUsageShallow(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: () => generateUsageShallow(information, operation),
+          decodeAndMakeInterpreter() {
             throw error;
           },
         };
@@ -245,34 +222,17 @@ export function command<Context, Result>(
 }
 
 /**
- * Creates a command that first runs an {@link OperationDescriptor} to produce an
- * intermediate `Payload`, then dispatches execution to one of several named subcommands
- * based on the next positional argument.
- *
- * **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`.
- *
- * **Usage on error / `--help`:** when the subcommand cannot be determined, the usage
- * output lists all available subcommands under a `Subcommands:` section.
+ * Creates a command that runs an {@link Operation} to produce a `Payload`,
+ * then dispatches to a named subcommand based on the next positional token.
  *
- * @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.
+ * @typeParam Context - Context accepted by `operation`.
+ * @typeParam Payload - Output of `operation`; becomes the subcommand's context.
+ * @typeParam Result - 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 CommandDescriptor}s. The keys are the literal tokens the user types.
- * @returns A {@link CommandDescriptor} that dispatches to one of the provided
- *   subcommands.
+ * @param information - Command metadata (description, hint, details).
+ * @param operation - Always runs first; its output becomes the subcommand's context.
+ * @param subcommands - Map of subcommand names to their {@link Command}s.
+ * @returns A {@link Command} that dispatches to one of the provided subcommands.
  *
  * @example
  * ```ts
@@ -288,18 +248,16 @@ export function command<Context, Result>(
  */
 export function commandWithSubcommands<Context, Payload, Result>(
   information: CommandInformation,
-  operation: OperationDescriptor<Context, Payload>,
-  subcommands: {
-    [subcommand: Lowercase<string>]: CommandDescriptor<Payload, Result>;
-  },
-): CommandDescriptor<Context, Result> {
+  operation: Operation<Context, Payload>,
+  subcommands: { [subcommand: Lowercase<string>]: Command<Payload, Result> },
+): Command<Context, Result> {
   return {
     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 +278,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 = generateUsageShallow(information, operation);
+            currentUsage.segments.push(segmentCommand(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 +309,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 = generateUsageShallow(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 +327,17 @@ export function commandWithSubcommands<Context, Payload, Result>(
 }
 
 /**
- * Creates a command that chains two command stages by piping the output of an
- * {@link OperationDescriptor} directly into a {@link CommandDescriptor} as its context.
- *
- * 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.
+ * Chains an {@link Operation} and a {@link Command}: `operation` runs first, its
+ * output becomes `subcommand`'s context. No token is consumed for routing.
  *
- * **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`.
+ * @typeParam Context - Context accepted by `operation`.
+ * @typeParam Payload - Output of `operation`; becomes `subcommand`'s context.
+ * @typeParam Result - Value produced by `subcommand`.
  *
- * **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 CommandDescriptor} that transparently composes the two stages.
+ * @param information - Command metadata (description, hint, details).
+ * @param operation - First stage; its output is passed as `subcommand`'s context.
+ * @param subcommand - Second stage, executed after `operation`.
+ * @returns A {@link Command} transparently composing the two stages.
  *
  * @example
  * ```ts
@@ -426,40 +353,37 @@ export function commandWithSubcommands<Context, Payload, Result>(
  */
 export function commandChained<Context, Payload, Result>(
   information: CommandInformation,
-  operation: OperationDescriptor<Context, Payload>,
-  nextCommand: CommandDescriptor<Payload, Result>,
-): CommandDescriptor<Context, Result> {
+  operation: Operation<Context, Payload>,
+  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 = generateUsageShallow(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 +392,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 = generateUsageShallow(information, operation);
+            currentUsage.segments.push(segmentPositional("[REST]..."));
+            return currentUsage;
           },
-          createInstance() {
+          decodeAndMakeInterpreter() {
             throw error;
           },
         };
@@ -488,10 +405,26 @@ export function commandChained<Context, Payload, Result>(
   };
 }
 
-function breadcrumbPositional(value: string): CommandUsageBreadcrumb {
+function segmentPositional(value: string): CommandUsageSegment {
   return { positional: value };
 }
 
-function breadcrumbCommand(value: string): CommandUsageBreadcrumb {
+function segmentCommand(value: string): CommandUsageSegment {
   return { command: value };
 }
+
+function generateUsageShallow(
+  information: CommandInformation,
+  operation: Operation<any, any>,
+): CommandUsage {
+  const { positionals, options } = operation.generateUsage();
+  return {
+    segments: positionals.map((positional) =>
+      segmentPositional(positional.label),
+    ),
+    information,
+    positionals,
+    subcommands: [],
+    options,
+  };
+}