cli-kiss 0.1.8 → 0.2.0

package/src/lib/Positional.ts

@@ -8,17 +8,82 @@ import {
   TypoText,
 } from "./Typo";
 
+/**
+ * Describes a single positional argument — a bare (non-option) token on the command
+ * line — together with its parsing and usage-generation logic.
+ *
+ * Positionals are created with {@link positionalRequired}, {@link positionalOptional}, or
+ * {@link positionalVariadics} and are passed via the `positionals` array of
+ * {@link operation}, where they are consumed in declaration order.
+ *
+ * @typeParam Value - The TypeScript type of the parsed positional value.
+ */
 export type Positional<Value> = {
+  /** Returns human-readable metadata used to render the `Positionals:` section of help. */
   generateUsage(): PositionalUsage;
+  /**
+   * Consumes the next positional token(s) from `readerPositionals` and returns the
+   * decoded value.
+   *
+   * @param readerPositionals - The shared {@link ReaderArgs} that manages the queue of
+   *   remaining positional tokens.
+   * @throws {@link TypoError} if the positional is required but absent, or if the raw
+   *   value fails type decoding.
+   */
   consumePositionals(readerPositionals: ReaderPositionals): Value;
 };
 
+/**
+ * Human-readable metadata for a single positional argument, used to render the
+ * `Positionals:` section of the help output produced by {@link usageToStyledLines}.
+ */
 export type PositionalUsage = {
+  /** Short description of what the positional represents. */
   description: string | undefined;
+  /**
+   * Optional supplementary note shown in parentheses next to the description.
+   * Suitable for short caveats such as `"defaults to 'world'"`.
+   */
   hint: string | undefined;
+  /**
+   * The placeholder label shown in the usage line and the `Positionals:` section.
+   * Required positionals use angle-bracket notation (e.g. `"<NAME>"`); optional ones
+   * use square-bracket notation (e.g. `"[FILE]"`); variadic ones append `...`
+   * (e.g. `"[ITEM]..."`).
+   */
   label: Uppercase<string>;
 };
 
+/**
+ * Creates a required positional argument — one that must be present on the command line.
+ *
+ * The parser consumes the next available positional token and decodes it with
+ * `definition.type`. If no token is available, a {@link TypoError} is thrown immediately
+ * during parsing (i.e. inside {@link OperationDescriptor.createFactory}).
+ *
+ * The label displayed in the usage line defaults to the uppercased `type.content`
+ * wrapped in angle brackets (e.g. `<STRING>`). Supply `label` to override.
+ *
+ * @typeParam Value - The TypeScript type produced by the type decoder.
+ *
+ * @param definition - Configuration for the positional.
+ * @param definition.description - Human-readable description for the help output.
+ * @param definition.hint - Optional supplementary note shown in parentheses.
+ * @param definition.label - Custom label shown in the usage line (without angle brackets).
+ *   Defaults to the uppercased `type.content`.
+ * @param definition.type - The {@link Type} used to decode the raw string token.
+ * @returns A {@link Positional}`<Value>`.
+ *
+ * @example
+ * ```ts
+ * const namePositional = positionalRequired({
+ *   type: typeString,
+ *   label: "NAME",
+ *   description: "The name to greet",
+ * });
+ * // Parses: my-cli Alice  →  "Alice"
+ * ```
+ */
 export function positionalRequired<Value>(definition: {
   description?: string;
   hint?: string;
@@ -49,6 +114,41 @@ export function positionalRequired<Value>(definition: {
   };
 }
 
+/**
+ * Creates an optional positional argument — one that may or may not appear on the
+ * command line.
+ *
+ * The parser consumes the next available positional token. If no token is available,
+ * `definition.default()` is called to supply the fallback value. If the default factory
+ * throws, a {@link TypoError} is produced.
+ *
+ * The label displayed in the usage line defaults to the uppercased `type.content`
+ * wrapped in square brackets (e.g. `[STRING]`). Supply `label` to override.
+ *
+ * @typeParam Value - The TypeScript type produced by the type decoder (or the default).
+ *
+ * @param definition - Configuration for the positional.
+ * @param definition.description - Human-readable description for the help output.
+ * @param definition.hint - Optional supplementary note shown in parentheses.
+ * @param definition.label - Custom label shown in the usage line (without square brackets).
+ *   Defaults to the uppercased `type.content`.
+ * @param definition.type - The {@link Type} used to decode the raw string token.
+ * @param definition.default - Factory called when the positional is absent to supply the
+ *   default value. Throw from this factory to make omission an error.
+ * @returns A {@link Positional}`<Value>`.
+ *
+ * @example
+ * ```ts
+ * const greeteePositional = positionalOptional({
+ *   type: typeString,
+ *   label: "NAME",
+ *   description: "Name to greet (default: world)",
+ *   default: () => "world",
+ * });
+ * // my-cli         →  "world"
+ * // my-cli Alice   →  "Alice"
+ * ```
+ */
 export function positionalOptional<Value>(definition: {
   description?: string;
   hint?: string;
@@ -85,6 +185,45 @@ export function positionalOptional<Value>(definition: {
   };
 }
 
+/**
+ * Creates a variadic positional argument — one that collects zero or more remaining
+ * positional tokens into an array.
+ *
+ * The parser greedily consumes tokens until either there are no more tokens or it
+ * encounters the optional `endDelimiter` sentinel string, which is consumed but not
+ * included in the result. Each token is decoded independently with `definition.type`.
+ *
+ * If absent entirely, the result is an empty array `[]`.
+ *
+ * The label displayed in the usage line defaults to the uppercased `type.content`
+ * wrapped in square brackets followed by `...` (e.g. `[STRING]...`). When an
+ * `endDelimiter` is configured, the delimiter is also shown (e.g. `[STRING]...["--"]`).
+ * Supply `label` to override the base label.
+ *
+ * @typeParam Value - The TypeScript type produced by the type decoder for each token.
+ *
+ * @param definition - Configuration for the variadic positional.
+ * @param definition.endDelimiter - Optional sentinel string that signals the end of
+ *   the variadic sequence (e.g. `"--"`). When encountered it is consumed but not
+ *   included in the result array.
+ * @param definition.description - Human-readable description for the help output.
+ * @param definition.hint - Optional supplementary note shown in parentheses.
+ * @param definition.label - Custom label shown in the usage line (without brackets).
+ *   Defaults to the uppercased `type.content`.
+ * @param definition.type - The {@link Type} used to decode each raw string token.
+ * @returns A {@link Positional}`<Array<Value>>`.
+ *
+ * @example
+ * ```ts
+ * const filesPositional = positionalVariadics({
+ *   type: typeString,
+ *   label: "FILE",
+ *   description: "Files to process",
+ * });
+ * // my-cli a.ts b.ts c.ts  →  ["a.ts", "b.ts", "c.ts"]
+ * // my-cli                  →  []
+ * ```
+ */
 export function positionalVariadics<Value>(definition: {
   endDelimiter?: string;
   description?: string;

package/src/lib/Reader.ts

@@ -6,23 +6,88 @@ import {
   TypoText,
 } from "./Typo";
 
+/**
+ * An opaque key that uniquely identifies a registered CLI option within a
+ * {@link ReaderArgs} instance.
+ *
+ * Keys are returned by {@link ReaderArgs.registerOption} and passed back to
+ * {@link ReaderArgs.getOptionValues} to retrieve the parsed values. The internal
+ * representation is intentionally opaque — treat it as a handle, not a string.
+ */
 export type ReaderOptionKey = (string | { __brand: "ReaderOptionKey" }) & {
   __brand: "ReaderOptionKey";
 };
 
+/**
+ * Interface for registering and querying CLI options during argument parsing.
+ *
+ * {@link ReaderArgs} implements both `ReaderOptions` and {@link ReaderPositionals}.
+ * The two interfaces are exposed separately so that option and positional parsing logic
+ * can depend only on the capability they need.
+ */
 export type ReaderOptions = {
+  /**
+   * Registers a new option so the parser can recognise it when scanning argument tokens.
+   *
+   * @param definition.longs - The long-form names (without `--`) for this option.
+   * @param definition.shorts - The short-form names (without `-`) for this option.
+   * @param definition.valued - When `true`, the option consumes the following token as
+   *   its value. When `false`, the option is a boolean flag.
+   * @returns An opaque {@link ReaderOptionKey} used to retrieve parsed values later.
+   * @throws `Error` if any of the given names has already been registered, or if a
+   *   short name overlaps (is a prefix of, or has as a prefix, another registered short).
+   */
   registerOption(definition: {
     longs: Array<string>;
     shorts: Array<string>;
     valued: boolean;
   }): ReaderOptionKey;
+  /**
+   * Returns all values collected for the option identified by `key`.
+   *
+   * @param key - The key returned by a prior {@link ReaderOptions.registerOption} call.
+   * @returns An array of raw string values, one per occurrence of the option on the
+   *   command line. Empty if the option was never provided.
+   * @throws `Error` if `key` was not previously registered on this instance.
+   */
   getOptionValues(key: ReaderOptionKey): Array<string>;
 };
 
+/**
+ * Interface for consuming positional (non-option) argument tokens during parsing.
+ *
+ * {@link ReaderArgs} implements both {@link ReaderOptions} and `ReaderPositionals`.
+ */
 export type ReaderPositionals = {
+  /**
+   * Consumes and returns the next positional token from the argument list, skipping
+   * any option tokens (which are parsed as side-effects).
+   *
+   * @returns The next positional string value, or `undefined` if no more positionals
+   *   are available.
+   * @throws {@link TypoError} if an unrecognised option token is encountered while
+   *   scanning for the next positional.
+   */
   consumePositional(): string | undefined;
 };
 
+/**
+ * The core argument parser for `cli-kiss`. Parses a flat array of raw CLI tokens into
+ * named options and positional values.
+ *
+ * Options must be registered with {@link ReaderArgs.registerOption} **before**
+ * {@link ReaderArgs.consumePositional} is called, because the parser needs to know
+ * whether each token is an option name, an option value, or a bare positional.
+ *
+ * **Supported argument syntax:**
+ * - Long options: `--name`, `--name value`, `--name=value`
+ * - Short options: `-n`, `-n value`, `-n=value`, `-nvalue`, `-abc` (stacked flags)
+ * - End-of-options separator: `--` — all subsequent tokens are treated as positionals.
+ *
+ * In most cases you do not need to use `ReaderArgs` directly; it is created internally
+ * by {@link runAndExit}. It is exposed for advanced use cases such as building
+ * custom runners.
+ */
 export class ReaderArgs {
   #args: ReadonlyArray<string>;
   #parsedIndex: number;
@@ -32,6 +97,10 @@ export class ReaderArgs {
   #valuedByKey: Map<ReaderOptionKey, boolean>;
   #resultByKey: Map<ReaderOptionKey, Array<string>>;
 
+  /**
+   * @param args - The raw command-line tokens to parse. Typically `process.argv.slice(2)`.
+   *   The array is not modified; a read cursor is maintained internally.
+   */
   constructor(args: ReadonlyArray<string>) {
     this.#args = args;
     this.#parsedIndex = 0;
@@ -42,6 +111,24 @@ export class ReaderArgs {
     this.#resultByKey = new Map();
   }
 
+  /**
+   * Registers a CLI option so the parser can recognise it.
+   *
+   * All `longs` and `shorts` are associated with the same returned key. Calling
+   * `getOptionValues(key)` after parsing will return values collected under any of the
+   * registered names.
+   *
+   * Short names support stacking (e.g. `-abc` is parsed as `-a -b -c`) and inline
+   * values (e.g. `-nvalue`). Short names must not be a prefix of, nor have as a prefix,
+   * any other registered short name — the parser uses prefix matching to parse stacked
+   * shorts, so overlapping prefixes would be ambiguous.
+   *
+   * @param definition.longs - Long-form names (without `--`).
+   * @param definition.shorts - Short-form names (without `-`).
+   * @param definition.valued - `true` if the option consumes a value; `false` for flags.
+   * @returns An opaque {@link ReaderOptionKey} to pass to {@link ReaderArgs.getOptionValues}.
+   * @throws `Error` if any name is already registered or if two short names overlap.
+   */
   registerOption(definition: {
     longs: Array<string>;
     shorts: Array<string>;
@@ -83,6 +170,15 @@ export class ReaderArgs {
     return key;
   }
 
+  /**
+   * Returns all raw string values collected for the given option key.
+   *
+   * @param key - A key previously returned by {@link ReaderArgs.registerOption}.
+   * @returns An array of string values, one per occurrence on the command line. For
+   *   flags this will be `["true"]` per occurrence; for valued options it will be the
+   *   literal value strings.
+   * @throws `Error` if `key` was not registered on this instance.
+   */
   getOptionValues(key: ReaderOptionKey): Array<string> {
     const optionResult = this.#resultByKey.get(key);
     if (optionResult === undefined) {
@@ -91,6 +187,20 @@ export class ReaderArgs {
     return optionResult;
   }
 
+  /**
+   * Scans forward through the argument list and returns the next bare positional token,
+   * consuming and parsing any intervening option tokens as side-effects.
+   *
+   * Option tokens encountered during the scan are recorded in the internal results map
+   * (equivalent to recording their values against their key). Any unrecognised option token
+   * causes a {@link TypoError} to be thrown immediately.
+   *
+   * After `--` is encountered, all remaining tokens are treated as positionals.
+   *
+   * @returns The next positional string, or `undefined` when the argument list is
+   *   exhausted.
+   * @throws {@link TypoError} if an unrecognised option (long or short) is encountered.
+   */
   consumePositional(): string | undefined {
     while (true) {
       const arg = this.#consumeArg();

package/src/lib/Run.ts

@@ -3,7 +3,75 @@ import { ReaderArgs } from "./Reader";
 import { TypoSupport } from "./Typo";
 import { usageToStyledLines } from "./Usage";
 
-export async function runAsCliAndExit<Context>(
+/**
+ * Parses the provided CLI arguments against the given command descriptor, executes
+ * the matched command, and exits the process with an appropriate exit code.
+ *
+ * This is the primary entry point for running a `cli-kiss`-based CLI application.
+ * It handles argument parsing, `--help` / `--version` flags, usage printing on errors,
+ * and exit code management.
+ *
+ * **Exit codes:**
+ * - `0` — Command executed successfully, or `--help` / `--version` was handled.
+ * - `1` — Argument parsing failed (a usage summary is also printed to stderr), or the
+ *   command threw an unhandled execution error.
+ *
+ * **Built-in flags (opt-out):**
+ * - `--help` — Enabled by default (`usageOnHelp: true`). Prints the usage summary to
+ *   stdout and exits with code `0`. This flag takes precedence over `--version`.
+ * - `--version` — Enabled when `buildVersion` is provided. Prints `<cliName> <version>`
+ *   to stdout and exits with code `0`.
+ *
+ * @typeParam Context - Arbitrary value passed unchanged to the command's execution handler.
+ *   Use this to inject dependencies (e.g. a database connection, a logger) into your commands.
+ *
+ * @param cliName - The name of the CLI program (e.g. `"my-cli"`). Used in the usage
+ *   summary header and in the `--version` output.
+ * @param cliArgs - The raw command-line arguments to parse, typically `process.argv.slice(2)`.
+ * @param context - The context value forwarded to the command's execution handler.
+ * @param command - The root {@link CommandDescriptor} that describes how to parse and execute
+ *   the CLI.
+ * @param options - Optional configuration for the runner.
+ * @param options.useTtyColors - Controls terminal color output in styled messages.
+ *   - `true` — Always apply ANSI color codes.
+ *   - `false` — Never apply color codes (plain text).
+ *   - `"mock"` — Use a deterministic mock style useful for snapshot testing.
+ *   - `undefined` (default) — Auto-detect based on `process.stdout.isTTY` and the
+ *     `FORCE_COLOR` / `NO_COLOR` environment variables.
+ * @param options.usageOnHelp - When `true` (default), registers a `--help` flag that
+ *   prints the usage summary and exits with code `0`.
+ * @param options.usageOnError - When `true` (default), prints the usage summary to
+ *   stderr before the error message whenever argument parsing fails.
+ * @param options.buildVersion - When provided, registers a `--version` flag that prints
+ *   `<cliName> <buildVersion>` to stdout and exits with code `0`.
+ * @param options.onError - Custom handler for errors thrown during command execution.
+ *   If omitted, the error is printed to stderr via {@link TypoSupport}.
+ * @param options.onExit - Overrides the process exit function (default: `process.exit`).
+ *   Useful for testing — supply a function that throws or captures the exit code instead
+ *   of actually terminating the process.
+ *
+ * @returns A `Promise<never>` because the function always terminates by calling `onExit`.
+ *
+ * @example
+ * ```ts
+ * import { runAndExit, command, operation, positionalRequired, typeString } from "cli-kiss";
+ *
+ * const greetCommand = command(
+ *   { description: "Greet someone" },
+ *   operation(
+ *     { options: {}, positionals: [positionalRequired({ type: typeString, label: "NAME" })] },
+ *     async (_ctx, { positionals: [name] }) => {
+ *       console.log(`Hello, ${name}!`);
+ *     },
+ *   ),
+ * );
+ *
+ * await runAndExit("greet", process.argv.slice(2), undefined, greetCommand, {
+ *   buildVersion: "1.0.0",
+ * });
+ * ```
+ */
+export async function runAndExit<Context>(
   cliName: Lowercase<string>,
   cliArgs: ReadonlyArray<string>,
   context: Context,
@@ -13,9 +81,7 @@ export async function runAsCliAndExit<Context>(
     usageOnHelp?: boolean | undefined;
     usageOnError?: boolean | undefined;
     buildVersion?: string | undefined;
-    onExecutionError?: ((error: unknown) => void) | undefined;
-    onLogStdOut?: ((message: string) => void) | undefined;
-    onLogStdErr?: ((message: string) => void) | undefined;
+    onError?: ((error: unknown) => void) | undefined;
     onExit?: ((code: number) => never) | undefined;
   },
 ): Promise<never> {
@@ -44,17 +110,6 @@ export async function runAsCliAndExit<Context>(
     longs: ["completion"],
   });
   */
-  const typoSupport =
-    options?.useTtyColors === undefined
-      ? TypoSupport.inferFromProcess()
-      : options.useTtyColors === "mock"
-        ? TypoSupport.mock()
-        : options.useTtyColors
-          ? TypoSupport.tty()
-          : TypoSupport.none();
-  const onLogStdOut = options?.onLogStdOut ?? console.log;
-  const onLogStdErr = options?.onLogStdErr ?? console.error;
-  const onExit = options?.onExit ?? process.exit;
   const commandFactory = command.createFactory(readerArgs);
   while (true) {
     try {
@@ -64,15 +119,24 @@ export async function runAsCliAndExit<Context>(
       }
     } catch (_) {}
   }
+  const onExit = options?.onExit ?? process.exit;
+  const typoSupport =
+    options?.useTtyColors === undefined
+      ? TypoSupport.inferFromProcess()
+      : options.useTtyColors === "mock"
+        ? TypoSupport.mock()
+        : options.useTtyColors
+          ? TypoSupport.tty()
+          : TypoSupport.none();
   if (usageOnHelp) {
     if (readerArgs.getOptionValues("--help" as any).length > 0) {
-      onLogStdOut(computeUsageString(cliName, commandFactory, typoSupport));
+      console.log(computeUsageString(cliName, commandFactory, typoSupport));
       return onExit(0);
     }
   }
   if (buildVersion) {
     if (readerArgs.getOptionValues("--version" as any).length > 0) {
-      onLogStdOut([cliName, buildVersion].join(" "));
+      console.log([cliName, buildVersion].join(" "));
       return onExit(0);
     }
   }
@@ -82,18 +146,18 @@ export async function runAsCliAndExit<Context>(
       await commandInstance.executeWithContext(context);
       return onExit(0);
     } catch (executionError) {
-      if (options?.onExecutionError) {
-        options.onExecutionError(executionError);
+      if (options?.onError) {
+        options.onError(executionError);
       } else {
-        onLogStdErr(typoSupport.computeStyledErrorMessage(executionError));
+        console.error(typoSupport.computeStyledErrorMessage(executionError));
       }
       return onExit(1);
     }
   } catch (parsingError) {
     if (options?.usageOnError ?? true) {
-      onLogStdErr(computeUsageString(cliName, commandFactory, typoSupport));
+      console.error(computeUsageString(cliName, commandFactory, typoSupport));
     }
-    onLogStdErr(typoSupport.computeStyledErrorMessage(parsingError));
+    console.error(typoSupport.computeStyledErrorMessage(parsingError));
     return onExit(1);
   }
 }