cli-kiss 0.1.8 → 0.2.0

package/src/lib/Command.ts

@@ -10,45 +10,185 @@ import {
   TypoText,
 } 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 `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`.
+ */
 export type CommandDescriptor<Context, Result> = {
+  /** Returns the static metadata (description, hint, details) for this command. */
   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.
+   */
   createFactory(readerArgs: ReaderArgs): CommandFactory<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.
+ *
+ * @typeParam Context - Forwarded from the parent {@link CommandDescriptor}.
+ * @typeParam Result - Forwarded from the parent {@link CommandDescriptor}.
+ */
 export type CommandFactory<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.
+   */
   generateUsage(): CommandUsage;
+  /**
+   * Creates a {@link CommandInstance} that is ready to execute.
+   *
+   * @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).
+   */
   createInstance(): CommandInstance<Context, Result>;
 };
 
+/**
+ * A fully parsed, 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.
+ */
 export type CommandInstance<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.
+   */
   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}.
+ */
 export type CommandInformation = {
+  /** Short description of what the command does. Shown prominently 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"`.
+   */
   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.
+   */
   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.
+   */
   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;
 };
 
+/**
+ * Creates a leaf command — a command that has no subcommands and directly executes
+ * an {@link OperationDescriptor}.
+ *
+ * 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 - 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}.
+ *
+ * @example
+ * ```ts
+ * const greet = command(
+ *   { description: "Greet a user" },
+ *   operation(
+ *     { options: {}, positionals: [positionalRequired({ type: typeString, label: "NAME" })] },
+ *     async (_ctx, { positionals: [name] }) => console.log(`Hello, ${name}!`),
+ *   ),
+ * );
+ * ```
+ */
 export function command<Context, Result>(
   information: CommandInformation,
   operation: OperationDescriptor<Context, Result>,
@@ -104,6 +244,48 @@ 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.
+ *
+ * @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 CommandDescriptor}s. The keys are the literal tokens the user types.
+ * @returns A {@link CommandDescriptor} that dispatches to one of the provided
+ *   subcommands.
+ *
+ * @example
+ * ```ts
+ * const rootCmd = commandWithSubcommands(
+ *   { description: "My CLI" },
+ *   operation({ options: {}, positionals: [] }, async (ctx) => ctx),
+ *   {
+ *     deploy: command({ description: "Deploy" }, deployOperation),
+ *     rollback: command({ description: "Rollback" }, rollbackOperation),
+ *   },
+ * );
+ * ```
+ */
 export function commandWithSubcommands<Context, Payload, Result>(
   information: CommandInformation,
   operation: OperationDescriptor<Context, Payload>,
@@ -198,6 +380,50 @@ 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.
+ *
+ * **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 CommandDescriptor} that transparently composes 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),
+ * );
+ * ```
+ */
 export function commandChained<Context, Payload, Result>(
   information: CommandInformation,
   operation: OperationDescriptor<Context, Payload>,

package/src/lib/Operation.ts

@@ -2,24 +2,132 @@ import { Option, OptionUsage } from "./Option";
 import { Positional, PositionalUsage } from "./Positional";
 import { ReaderArgs } from "./Reader";
 
+/**
+ * Describes an operation — the combination of options, positional arguments, and an
+ * async execution handler that together form the core logic of a CLI command.
+ *
+ * An `OperationDescriptor` is created with {@link operation} and passed to
+ * {@link command}, {@link commandWithSubcommands}, or {@link commandChained} to build
+ * a full {@link CommandDescriptor}.
+ *
+ * @typeParam Input - The context value the handler receives at execution time (forwarded
+ *   from the parent command's context or from a preceding chained operation).
+ * @typeParam Output - The value the handler produces. For leaf operations this is
+ *   typically `void`; for intermediate stages it is the payload forwarded to the next
+ *   command in a chain.
+ */
 export type OperationDescriptor<Input, Output> = {
+  /**
+   * Returns usage metadata (options and positionals) without consuming any arguments.
+   * Called by the parent command factory when building the help/usage output.
+   */
   generateUsage(): OperationUsage;
+  /**
+   * Parses options and positionals from `readerArgs` and returns an
+   * {@link OperationFactory} that can create a ready-to-execute
+   * {@link OperationInstance}.
+   *
+   * Any parse error (unknown option, type mismatch, etc.) is captured and re-thrown
+   * when {@link OperationFactory.createInstance} is called.
+   *
+   * @param readerArgs - The shared argument reader. Options are registered on it and
+   *   positionals are consumed in declaration order.
+   */
   createFactory(readerArgs: ReaderArgs): OperationFactory<Input, Output>;
 };
 
+/**
+ * Produced by {@link OperationDescriptor.createFactory} after argument parsing.
+ * Instantiating it finalises value extraction and produces an {@link OperationInstance}.
+ *
+ * @typeParam Input - Forwarded from the parent {@link OperationDescriptor}.
+ * @typeParam Output - Forwarded from the parent {@link OperationDescriptor}.
+ */
 export type OperationFactory<Input, Output> = {
+  /**
+   * Extracts the final parsed values for all options and returns an
+   * {@link OperationInstance} ready for execution.
+   *
+   * @throws {@link TypoError} if any option or positional validation failed during
+   *   {@link OperationDescriptor.createFactory}.
+   */
   createInstance(): OperationInstance<Input, Output>;
 };
 
+/**
+ * A fully parsed, ready-to-execute operation.
+ *
+ * @typeParam Input - The value the caller must supply as context.
+ * @typeParam Output - The value produced on successful execution.
+ */
 export type OperationInstance<Input, Output> = {
+  /**
+   * Runs the operation handler with the provided input context and the parsed
+   * option/positional values.
+   *
+   * @param input - Context from the parent command (or the root context supplied to
+   *   {@link runAndExit}).
+   * @returns A promise resolving to the handler's return value.
+   */
   executeWithContext(input: Input): Promise<Output>;
 };
 
+/**
+ * Collected usage metadata produced by {@link OperationDescriptor.generateUsage}.
+ * Consumed by the parent command factory when building {@link CommandUsage}.
+ */
 export type OperationUsage = {
+  /** Usage descriptors for all options registered by this operation. */
   options: Array<OptionUsage>;
+  /** Usage descriptors for all positionals declared by this operation, in order. */
   positionals: Array<PositionalUsage>;
 };
 
+/**
+ * Creates an {@link OperationDescriptor} from a set of options, positionals, and an
+ * async handler function.
+ *
+ * The `handler` receives:
+ * - `context` — the value passed down from the parent command (or from
+ *   {@link runAndExit}).
+ * - `inputs.options` — an object whose keys match those declared in `inputs.options` and whose values are
+ *   the parsed option values.
+ * - `inputs.positionals` — a tuple whose elements match `inputs.positionals` and whose
+ *   values are the parsed positional values, in declaration order.
+ *
+ * @typeParam Context - The context type accepted by the handler.
+ * @typeParam Result - The return type of the handler.
+ * @typeParam Options - Object type mapping option keys to their parsed value types.
+ * @typeParam Positionals - Tuple type of parsed positional value types, in order.
+ *
+ * @param inputs - Declares the options and positionals this operation accepts.
+ * @param inputs.options - A map from arbitrary keys to {@link Option} descriptors.
+ *   The same keys appear in `handler`'s `inputs.options` argument.
+ * @param inputs.positionals - An ordered array of {@link Positional} descriptors.
+ *   Their parsed values appear in `handler`'s `inputs.positionals` argument, in the
+ *   same order.
+ * @param handler - The async function that implements the command logic. Receives the
+ *   execution context and all parsed inputs.
+ * @returns An {@link OperationDescriptor} ready to be composed into a command.
+ *
+ * @example
+ * ```ts
+ * const greetOperation = operation(
+ *   {
+ *     options: {
+ *       loud: optionFlag({ long: "loud", description: "Print in uppercase" }),
+ *     },
+ *     positionals: [
+ *       positionalRequired({ type: typeString, label: "NAME", description: "Name to greet" }),
+ *     ],
+ *   },
+ *   async (_ctx, { options: { loud }, positionals: [name] }) => {
+ *     const message = `Hello, ${name}!`;
+ *     console.log(loud ? message.toUpperCase() : message);
+ *   },
+ * );
+ * ```
+ */
 export function operation<
   Context,
   Result,

package/src/lib/Option.ts

@@ -9,23 +9,107 @@ import {
   TypoText,
 } from "./Typo";
 
+/**
+ * Describes a single CLI option (a flag or a valued option) together with its parsing
+ * and usage-generation logic.
+ *
+ * Options are created with {@link optionFlag}, {@link optionSingleValue}, or
+ * {@link optionRepeatable} and are passed via the `options` map of {@link operation}.
+ *
+ * @typeParam Value - The TypeScript type of the parsed option value.
+ *   - `boolean` for flags created with {@link optionFlag}.
+ *   - `T` for single-value options created with {@link optionSingleValue}.
+ *   - `Array<T>` for repeatable options created with {@link optionRepeatable}.
+ */
 export type Option<Value> = {
+  /** Returns human-readable metadata used to render the `Options:` section of help. */
   generateUsage(): OptionUsage;
+  /**
+   * Registers the option on `readerOptions` so the argument reader recognises it, and
+   * returns an {@link OptionGetter} that can later retrieve the parsed value(s).
+   *
+   * @param readerOptions - The shared {@link ReaderArgs} that will parse the raw
+   *   command-line tokens.
+   */
   createGetter(readerOptions: ReaderOptions): OptionGetter<Value>;
 };
 
+/**
+ * Human-readable metadata for a single CLI option, used to render the `Options:` section
+ * of the help output produced by {@link usageToStyledLines}.
+ */
 export type OptionUsage = {
+  /** Short description of what the option does. */
   description: string | undefined;
+  /**
+   * Optional supplementary note shown in parentheses next to the description.
+   * Suitable for short caveats such as `"required"` or `"defaults to 42"`.
+   */
   hint: string | undefined;
+  /**
+   * The primary long-form name of the option, without the `--` prefix (e.g. `"verbose"`).
+   * The user passes this as `--verbose` on the command line.
+   */
   long: Lowercase<string>; // TODO - better type for long option names ?
+  /**
+   * The optional short-form name of the option, without the `-` prefix (e.g. `"v"`).
+   * The user passes this as `-v` on the command line.
+   */
   short: string | undefined;
+  /**
+   * The value placeholder label shown after the long option name in the help output
+   * (e.g. `"<FILE>"`). `undefined` for flags that take no value.
+   */
   label: Uppercase<string> | undefined;
 };
 
+/**
+ * Retrieves the parsed value for a registered option after argument parsing is complete.
+ *
+ * Returned by {@link Option.createGetter} and called by {@link OperationFactory.createInstance}.
+ *
+ * @typeParam Value - The TypeScript type of the parsed value.
+ */
 export type OptionGetter<Value> = {
+  /**
+   * Returns the fully decoded and validated value for the option.
+   *
+   * @throws {@link TypoError} if the option appeared more times than allowed, the value
+   *   failed type decoding, or a required default could not be computed.
+   */
   getValue(): Value;
 };
 
+/**
+ * Creates a boolean flag option — an option that the user passes without a value (e.g.
+ * `--verbose`) to signal `true`, or can explicitly set with `--flag=true` / `--flag=no`.
+ *
+ * **Parsing rules:**
+ * - Absent → `false` (or the return value of `default()` when provided).
+ * - `--flag` / `--flag=true` / `--flag=yes` → `true`.
+ * - `--flag=false` / `--flag=no` → `false`.
+ * - Specified more than once → {@link TypoError} ("Must not be set multiple times").
+ *
+ * @param definition - Configuration for the flag.
+ * @param definition.long - Primary long-form name (without `--`). Must be lowercase.
+ * @param definition.short - Optional short-form name (without `-`).
+ * @param definition.description - Human-readable description for the help output.
+ * @param definition.hint - Optional supplementary note shown in parentheses.
+ * @param definition.aliases - Additional long/short names that the parser also
+ *   recognises as this flag.
+ * @param definition.default - Factory for the default value when the flag is absent.
+ *   Defaults to `() => false` when omitted.
+ * @returns An {@link Option}`<boolean>`.
+ *
+ * @example
+ * ```ts
+ * const verboseFlag = optionFlag({
+ *   long: "verbose",
+ *   short: "v",
+ *   description: "Enable verbose output",
+ * });
+ * ```
+ */
 export function optionFlag(definition: {
   long: Lowercase<string>;
   short?: string;
@@ -82,6 +166,47 @@ export function optionFlag(definition: {
   };
 }
 
+/**
+ * Creates an option that accepts exactly one value (e.g. `--output dist/` or
+ * `--output=dist/`).
+ *
+ * **Parsing rules:**
+ * - Absent → `definition.default()` is called. If the default factory throws, a
+ *   {@link TypoError} is produced.
+ * - Specified once → the value is decoded with `definition.type`.
+ * - Specified more than once → {@link TypoError} ("Requires a single value, but got
+ *   multiple").
+ *
+ * **Value syntax:** `--long value`, `--long=value`, or (if `short` is set) `-s value`,
+ * `-s=value`, or `-svalue`.
+ *
+ * @typeParam Value - The TypeScript type produced by the type decoder.
+ *
+ * @param definition - Configuration for the option.
+ * @param definition.long - Primary long-form name (without `--`). Must be lowercase.
+ * @param definition.short - Optional short-form name (without `-`).
+ * @param definition.description - Human-readable description for the help output.
+ * @param definition.hint - Optional supplementary note shown in parentheses.
+ * @param definition.aliases - Additional long/short names the parser also recognises.
+ * @param definition.label - Custom label shown in the help output (e.g. `"FILE"`).
+ *   Defaults to the uppercased `type.content`.
+ * @param definition.type - The {@link Type} used to decode the raw string value.
+ * @param definition.default - Factory for the default value when the option is absent.
+ *   Throw an error from this factory to make the option effectively required.
+ * @returns An {@link Option}`<Value>`.
+ *
+ * @example
+ * ```ts
+ * const outputOption = optionSingleValue({
+ *   long: "output",
+ *   short: "o",
+ *   type: typeString,
+ *   label: "PATH",
+ *   description: "Output directory",
+ *   default: () => "dist/",
+ * });
+ * ```
+ */
 export function optionSingleValue<Value>(definition: {
   long: Lowercase<string>;
   short?: string;
@@ -145,6 +270,45 @@ export function optionSingleValue<Value>(definition: {
   };
 }
 
+/**
+ * Creates an option that can be specified any number of times, collecting all provided
+ * values into an array (e.g. `--file a.ts --file b.ts`).
+ *
+ * **Parsing rules:**
+ * - Absent → empty array `[]`.
+ * - Specified N times → array of N decoded values, in the order they appear on the
+ *   command line.
+ * - Each occurrence is decoded independently with `definition.type`.
+ *
+ * **Value syntax:** `--long value`, `--long=value`, or (if `short` is set) `-s value`,
+ * `-s=value`, or `-svalue`.
+ *
+ * @typeParam Value - The TypeScript type produced by the type decoder for each
+ *   occurrence.
+ *
+ * @param definition - Configuration for the option.
+ * @param definition.long - Primary long-form name (without `--`). Must be lowercase.
+ * @param definition.short - Optional short-form name (without `-`).
+ * @param definition.description - Human-readable description for the help output.
+ * @param definition.hint - Optional supplementary note shown in parentheses.
+ * @param definition.aliases - Additional long/short names the parser also recognises.
+ * @param definition.label - Custom label shown in the help output (e.g. `"FILE"`).
+ *   Defaults to the uppercased `type.content`.
+ * @param definition.type - The {@link Type} used to decode each raw string value.
+ * @returns An {@link Option}`<Array<Value>>`.
+ *
+ * @example
+ * ```ts
+ * const filesOption = optionRepeatable({
+ *   long: "file",
+ *   short: "f",
+ *   type: typeString,
+ *   label: "PATH",
+ *   description: "Input file (may be repeated)",
+ * });
+ * // Usage: my-cli --file a.ts --file b.ts  →  ["a.ts", "b.ts"]
+ * ```
+ */
 export function optionRepeatable<Value>(definition: {
   long: Lowercase<string>;
   short?: string;