cli-kiss 0.2.3 → 0.2.5

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,22 +7,21 @@ import {
   typoStyleUserInput,
   TypoText,
 } from "./Typo";
+import { UsageCommand } from "./Usage";
 
 /**
- * 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 CLI command. Created with {@link command}, {@link commandWithSubcommands}, or {@link commandChained}.
  *
- * @typeParam Context - Injected at execution time; forwarded to handlers. Use to inject dependencies.
- * @typeParam Result - Value produced on execution; typically `void` for leaf commands.
+ * @typeParam Context - Injected at execution; forwarded to handlers.
+ * @typeParam Result - Produced on execution; typically `void`.
  */
 export type Command<Context, Result> = {
   /**
-   * Returns the command's static metadata.
+   * Returns static metadata.
    */
   getInformation(): CommandInformation;
   /**
-   * Consumes args in a `readerArgs` and returns a {@link CommandDecoder}.
+   * Registers options/positionals on `readerArgs`; returns a {@link CommandDecoder}.
    */
   consumeAndMakeDecoder(
     readerArgs: ReaderArgs,
@@ -39,10 +36,9 @@ export type Command<Context, Result> = {
  */
 export type CommandDecoder<Context, Result> = {
   /**
-   * Builds the {@link CommandUsage} for the current command path.
-   * Used for `--help` and `usageOnError`.
+   * Returns {@link UsageCommand} for the current command path.
    */
-  generateUsage(): CommandUsage;
+  generateUsage(): UsageCommand;
   /**
    * Creates a ready-to-execute {@link CommandInterpreter}.
    *
@@ -54,7 +50,7 @@ export type CommandDecoder<Context, Result> = {
 /**
  * A fully parsed, decoded and ready-to-execute command.
  *
- * @typeParam Context - Caller-supplied context.
+ * @typeParam Context - Context passed to the handler.
  * @typeParam Result - Value produced on success.
  */
 export type CommandInterpreter<Context, Result> = {
@@ -65,15 +61,15 @@ export type CommandInterpreter<Context, Result> = {
 };
 
 /**
- * Static metadata for a command, shown in `--help` output via {@link usageToStyledLines}.
+ * Command metadata shown in `--help` output.
  */
 export type CommandInformation = {
   /**
-   * Short description shown in the usage header.
+   * Shown in the usage header.
    */
   description: string;
   /**
-   * Short note shown in parentheses (e.g. `"deprecated"`, `"experimental"`).
+   * Shown in parentheses, e.g. `"deprecated"`, `"experimental"`.
    */
   hint?: string;
   /**
@@ -81,7 +77,7 @@ export type CommandInformation = {
    */
   details?: Array<string>;
   /**
-   * Examples shown in the `Examples:` section of the usage output.
+   * Shown in the `Examples:` section.
    */
   examples?: Array<{
     /**
@@ -89,7 +85,7 @@ export type CommandInformation = {
      */
     explanation: string;
     /**
-     * Command line args to show as an example of usage.
+     * Example command args.
      */
     commandArgs: Array<
       | string
@@ -97,73 +93,21 @@ export type CommandInformation = {
       | { subcommand: string }
       | {
           option:
-            | { long: string; value?: string }
-            | { short: string; value?: string };
+            | { long: string; inlined?: string; separated?: Array<string> }
+            | { short: string; inlined?: string; separated?: Array<string> };
         }
     >;
   }>;
 };
 
-/**
- * Full usage/help model.
- * Produced by {@link CommandDecoder.generateUsage},
- * Consumed by {@link usageToStyledLines}.
- */
-export type CommandUsage = {
-  /**
-   * Segments forming the usage line
-   * (e.g. `my-cli <POSITIONAL> subcommand <ANOTHER_POSITIONAL>`).
-   */
-  segments: Array<CommandUsageSegment>;
-  /**
-   * Command's static metadata.
-   */
-  information: CommandInformation;
-  /**
-   * Positionals in declaration order.
-   */
-  positionals: Array<PositionalUsage>;
-  /**
-   * Available subcommands. Non-empty when subcommand was not specified.
-   */
-  subcommands: Array<CommandUsageSubcommand>;
-  /**
-   * Options in registration order.
-   */
-  options: Array<OptionUsage>;
-};
-
-/**
- * One element in the usage segment trail.
- */
-export type CommandUsageSegment = { positional: string } | { command: string };
-
-/**
- * Subcommand entry shown in the `Subcommands:` section of the usage output.
- */
-export type CommandUsageSubcommand = {
-  /**
-   * Literal token the user types (e.g. `"deploy"`).
-   */
-  name: string;
-  /**
-   * Short description from the subcommand's {@link CommandInformation}.
-   */
-  description: string | undefined;
-  /**
-   * Hint from the subcommand's {@link CommandInformation}.
-   */
-  hint: string | undefined;
-};
-
 /**
  * Creates a leaf command that directly executes an {@link Operation}.
  *
  * @typeParam Context - Context forwarded to the handler.
  * @typeParam Result - Value returned by the handler.
  *
- * @param information - Command metadata (description, hint, details).
- * @param operation - Defines: options, positionals, and the handler.
+ * @param information - Command metadata.
+ * @param operation - Options, positionals, and handler.
  * @returns A {@link Command}.
  *
  * @example
@@ -171,7 +115,7 @@ export type CommandUsageSubcommand = {
  * const greet = command(
  *   { description: "Greet a user" },
  *   operation(
- *     { options: {}, positionals: [positionalRequired({ type: typeString, label: "NAME" })] },
+ *     { options: {}, positionals: [positionalRequired({ type: type("name") })] },
  *     async (_ctx, { positionals: [name] }) => console.log(`Hello, ${name}!`),
  *   ),
  * );
@@ -198,7 +142,7 @@ export function command<Context, Result>(
           );
         }
         return {
-          generateUsage: () => generateUsageShallow(information, operation),
+          generateUsage: () => generateUsageLeaf(information, operation),
           decodeAndMakeInterpreter() {
             const operationInterpreter =
               operationDecoder.decodeAndMakeInterpreter();
@@ -211,7 +155,7 @@ export function command<Context, Result>(
         };
       } catch (error) {
         return {
-          generateUsage: () => generateUsageShallow(information, operation),
+          generateUsage: () => generateUsageLeaf(information, operation),
           decodeAndMakeInterpreter() {
             throw error;
           },
@@ -222,17 +166,16 @@ export function command<Context, Result>(
 }
 
 /**
- * Creates a command that runs an {@link Operation} to produce a `Payload`,
- * then dispatches to a named subcommand based on the next positional token.
+ * Creates a command that runs `operation` first, then dispatches to a named 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 - Command metadata (description, hint, details).
- * @param operation - Always runs first; its output becomes the subcommand's context.
+ * @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 {@link Command} that dispatches to one of the provided subcommands.
+ * @returns A dispatching {@link Command}.
  *
  * @example
  * ```ts
@@ -249,7 +192,7 @@ export function command<Context, Result>(
 export function commandWithSubcommands<Context, Payload, Result>(
   information: CommandInformation,
   operation: Operation<Context, Payload>,
-  subcommands: { [subcommand: Lowercase<string>]: Command<Payload, Result> },
+  subcommands: { [subcommand: string]: Command<Payload, Result> },
 ): Command<Context, Result> {
   return {
     getInformation() {
@@ -262,17 +205,16 @@ export function commandWithSubcommands<Context, Payload, Result>(
         if (subcommandName === undefined) {
           throw new TypoError(
             new TypoText(
-              new TypoString(`<SUBCOMMAND>`, typoStyleUserInput),
+              new TypoString(`<subcommand>`, typoStyleUserInput),
               new TypoString(`: Is required, but was not provided`),
             ),
           );
         }
-        const subcommandInput =
-          subcommands[subcommandName as Lowercase<string>];
+        const subcommandInput = subcommands[subcommandName];
         if (subcommandInput === undefined) {
           throw new TypoError(
             new TypoText(
-              new TypoString(`<SUBCOMMAND>`, typoStyleUserInput),
+              new TypoString(`<subcommand>`, typoStyleUserInput),
               new TypoString(`: Invalid value: `),
               new TypoString(`"${subcommandName}"`, typoStyleQuote),
             ),
@@ -283,8 +225,8 @@ export function commandWithSubcommands<Context, Payload, Result>(
         return {
           generateUsage() {
             const subcommandUsage = subcommandDecoder.generateUsage();
-            const currentUsage = generateUsageShallow(information, operation);
-            currentUsage.segments.push(segmentCommand(subcommandName));
+            const currentUsage = generateUsageLeaf(information, operation);
+            currentUsage.segments.push({ subcommand: subcommandName });
             currentUsage.segments.push(...subcommandUsage.segments);
             currentUsage.information = subcommandUsage.information;
             currentUsage.positionals.push(...subcommandUsage.positionals);
@@ -309,8 +251,8 @@ export function commandWithSubcommands<Context, Payload, Result>(
       } catch (error) {
         return {
           generateUsage() {
-            const currentUsage = generateUsageShallow(information, operation);
-            currentUsage.segments.push(segmentPositional("<SUBCOMMAND>"));
+            const currentUsage = generateUsageLeaf(information, operation);
+            currentUsage.segments.push({ positional: "<subcommand>" });
             for (const [name, subcommand] of Object.entries(subcommands)) {
               const { description, hint } = subcommand.getInformation();
               currentUsage.subcommands.push({ name, description, hint });
@@ -334,22 +276,10 @@ export function commandWithSubcommands<Context, Payload, Result>(
  * @typeParam Payload - Output of `operation`; becomes `subcommand`'s context.
  * @typeParam Result - Value produced by `subcommand`.
  *
- * @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
- * const authenticatedDeploy = commandChained(
- *   { description: "Authenticate then deploy" },
- *   operation(
- *     { options: { token: optionSingleValue({ long: "token", type: typeString, default: () => "" }) }, positionals: [] },
- *     async (_ctx, { options: { token } }) => ({ token }),
- *   ),
- *   command({ description: "Deploy" }, deployOperation),
- * );
- * ```
+ * @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.
  */
 export function commandChained<Context, Payload, Result>(
   information: CommandInformation,
@@ -367,7 +297,7 @@ export function commandChained<Context, Payload, Result>(
         return {
           generateUsage() {
             const subcommandUsage = subcommandDecoder.generateUsage();
-            const currentUsage = generateUsageShallow(information, operation);
+            const currentUsage = generateUsageLeaf(information, operation);
             currentUsage.segments.push(...subcommandUsage.segments);
             currentUsage.information = subcommandUsage.information;
             currentUsage.positionals.push(...subcommandUsage.positionals);
@@ -392,8 +322,8 @@ export function commandChained<Context, Payload, Result>(
       } catch (error) {
         return {
           generateUsage() {
-            const currentUsage = generateUsageShallow(information, operation);
-            currentUsage.segments.push(segmentPositional("[REST]..."));
+            const currentUsage = generateUsageLeaf(information, operation);
+            currentUsage.segments.push({ positional: "[REST]..." });
             return currentUsage;
           },
           decodeAndMakeInterpreter() {
@@ -405,23 +335,15 @@ export function commandChained<Context, Payload, Result>(
   };
 }
 
-function segmentPositional(value: string): CommandUsageSegment {
-  return { positional: value };
-}
-
-function segmentCommand(value: string): CommandUsageSegment {
-  return { command: value };
-}
-
-function generateUsageShallow(
+function generateUsageLeaf(
   information: CommandInformation,
   operation: Operation<any, any>,
-): CommandUsage {
+): UsageCommand {
   const { positionals, options } = operation.generateUsage();
   return {
-    segments: positionals.map((positional) =>
-      segmentPositional(positional.label),
-    ),
+    segments: positionals.map((positional) => ({
+      positional: positional.label,
+    })),
     information,
     positionals,
     subcommands: [],

package/src/lib/Operation.ts

@@ -1,6 +1,7 @@
-import { Option, OptionDecoder, OptionUsage } from "./Option";
-import { Positional, PositionalDecoder, PositionalUsage } from "./Positional";
+import { Option, OptionDecoder } from "./Option";
+import { Positional, PositionalDecoder } from "./Positional";
 import { ReaderArgs } from "./Reader";
+import { UsageOption, UsagePositional } from "./Usage";
 
 /**
  * Options, positionals, and an async handler that together form the logic of a CLI command.
@@ -8,14 +9,23 @@ import { ReaderArgs } from "./Reader";
  * Created with {@link operation} and passed to {@link command},
  * {@link commandWithSubcommands}, or {@link commandChained}.
  *
- * @typeParam Context - Injected at execution time; forwarded to handlers. Use to inject dependencies.
- * @typeParam Result - Value produced on execution; typically `void` for leaf commands.
+ * @typeParam Context - Injected at execution; forwarded to handlers.
+ * @typeParam Result - Value produced on execution; typically `void`.
  */
 export type Operation<Context, Result> = {
   /**
    * Returns usage metadata without consuming any arguments.
    */
-  generateUsage(): OperationUsage;
+  generateUsage(): {
+    /**
+     * Registered options.
+     */
+    options: Array<UsageOption>;
+    /**
+     * Declared positionals, in order.
+     */
+    positionals: Array<UsagePositional>;
+  };
   /**
    * Consumes args from `readerArgs` and returns an {@link OperationDecoder}.
    */
@@ -52,27 +62,10 @@ export type OperationInterpreter<Context, Result> = {
   executeWithContext(context: Context): Promise<Result>;
 };
 
-/**
- * Usage metadata produced by {@link Operation.generateUsage}.
- * Consumed when building {@link CommandUsage}.
- */
-export type OperationUsage = {
-  /**
-   * Usage descriptors for all registered options.
-   */
-  options: Array<OptionUsage>;
-  /**
-   * Usage descriptors for all declared positionals, in order.
-   */
-  positionals: Array<PositionalUsage>;
-};
-
 /**
  * Creates an {@link Operation} from options, positionals, and an async handler.
  *
- * The `handler` receives the parent `context` and an `inputs` object with
- * `options` (keyed by the same names declared in `inputs.options`) and
- * `positionals` (a tuple in declaration order).
+ * The `handler` receives `context` and `inputs` with decoded `options` and `positionals`.
  *
  * @typeParam Context - Context type accepted by the handler.
  * @typeParam Result - Return type of the handler.
@@ -83,20 +76,20 @@ export type OperationUsage = {
  * @param inputs.options - Map of keys to {@link Option} descriptors.
  * @param inputs.positionals - Ordered array of {@link Positional} descriptors.
  * @param handler - Async function implementing the command logic.
- * @returns An {@link Operation} ready to be composed into a command.
+ * @returns An {@link Operation}.
  *
  * @example
  * ```ts
  * const greetOperation = operation(
  *   {
  *     options: {
- *       loud: optionFlag({ long: "loud", description: "Print in uppercase" }),
+ *       loud: optionFlag({ long: "loud", description: "Print in uppercase", default: false }),
  *     },
  *     positionals: [
- *       positionalRequired({ type: typeString, label: "NAME", description: "Name to greet" }),
+ *       positionalRequired({ type: type("name"), description: "Name to greet" }),
  *     ],
  *   },
- *   async (_ctx, { options: { loud }, positionals: [name] }) => {
+ *   async function (_ctx, { options: { loud }, positionals: [name] }) {
  *     const message = `Hello, ${name}!`;
  *     console.log(loud ? message.toUpperCase() : message);
  *   },
@@ -123,14 +116,12 @@ export function operation<
 ): Operation<Context, Result> {
   return {
     generateUsage() {
-      const optionsUsage = new Array<OptionUsage>();
+      const optionsUsage = new Array<UsageOption>();
       for (const optionKey in inputs.options) {
         const optionInput = inputs.options[optionKey]!;
-        if (optionInput) {
-          optionsUsage.push(optionInput.generateUsage());
-        }
+        optionsUsage.push(optionInput.generateUsage());
       }
-      const positionalsUsage = new Array<PositionalUsage>();
+      const positionalsUsage = new Array<UsagePositional>();
       for (const positionalInput of inputs.positionals) {
         positionalsUsage.push(positionalInput.generateUsage());
       }