cli-kiss 0.1.8 → 0.1.9

package/dist/index.d.ts

@@ -1,65 +1,482 @@
+/**
+ * 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.
+ */
 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.
+ */
 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`.
+ */
 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 runAsCliAndExit}. It is exposed for advanced use cases such as building
+ * custom runners.
+ */
 declare class ReaderArgs {
     #private;
+    /**
+     * @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>);
+    /**
+     * 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>;
         valued: boolean;
     }): ReaderOptionKey;
+    /**
+     * 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>;
+    /**
+     * 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;
 }
 
+/**
+ * Describes how to decode a raw CLI string token into a typed TypeScript value.
+ *
+ * A `Type` is a pair of:
+ * - a `content` string — a human-readable name shown in help/error messages (e.g.
+ *   `"String"`, `"Number"`, `"Url"`).
+ * - a `decoder` function — converts the raw string or throws a {@link TypoError} on
+ *   invalid input.
+ *
+ * Built-in types: {@link typeString}, {@link typeBoolean}, {@link typeNumber},
+ * {@link typeInteger}, {@link typeDate}, {@link typeUrl}.
+ *
+ * Composite types: {@link typeOneOf}, {@link typeConverted}, {@link typeTuple},
+ * {@link typeList}.
+ *
+ * @typeParam Value - The TypeScript type that the decoder produces.
+ */
 type Type<Value> = {
+    /**
+     * Human-readable name for this type, used in help text and error messages.
+     * Examples: `"String"`, `"Number"`, `"Url"`.
+     */
     content: string;
+    /**
+     * Decodes a raw string token into a `Value`.
+     *
+     * @param value - The raw string from the command line.
+     * @returns The decoded value.
+     * @throws {@link TypoError} if the value cannot be decoded.
+     */
     decoder(value: string): Value;
 };
+/**
+ * A {@link Type} that decodes `"true"` / `"yes"` to `true` and `"false"` / `"no"` to
+ * `false` (case-insensitive). Any other value throws a {@link TypoError}.
+ *
+ * Primarily used internally by {@link optionFlag} for the `--flag=<value>` syntax, but
+ * can also be used in positionals or valued options.
+ *
+ * @example
+ * ```ts
+ * typeBoolean.decoder("yes")   // → true
+ * typeBoolean.decoder("false") // → false
+ * typeBoolean.decoder("1")     // throws TypoError
+ * ```
+ */
 declare const typeBoolean: Type<boolean>;
+/**
+ * A {@link Type} that parses a date/time string using `Date.parse`.
+ *
+ * Accepts any format supported by the JavaScript `Date.parse` API, including ISO 8601
+ * strings (e.g. `"2024-01-15"`, `"2024-01-15T10:30:00Z"`). Non-parseable values throw
+ * a {@link TypoError}.
+ *
+ * Produces a `Date` object. The decoded value is the result of `new Date(Date.parse(value))`.
+ *
+ * @example
+ * ```ts
+ * typeDate.decoder("2024-01-15") // → Date object for 2024-01-15
+ * typeDate.decoder("not a date") // throws TypoError
+ * ```
+ */
 declare const typeDate: Type<Date>;
+/**
+ * A {@link Type} that parses a string into a JavaScript `number` using the `Number()`
+ * constructor.
+ *
+ * Accepts integers, floating-point values, and scientific notation (e.g. `"3.14"`,
+ * `"-1"`, `"1e10"`). Values that produce `NaN` throw a {@link TypoError}.
+ *
+ * @example
+ * ```ts
+ * typeNumber.decoder("3.14")  // → 3.14
+ * typeNumber.decoder("-1")    // → -1
+ * typeNumber.decoder("hello") // throws TypoError
+ * ```
+ */
 declare const typeNumber: Type<number>;
+/**
+ * A {@link Type} that parses a string into a JavaScript `bigint` using the `BigInt()`
+ * constructor.
+ *
+ * Only accepts valid integer strings (e.g. `"42"`, `"-100"`, `"9007199254740993"`).
+ * Floating-point strings or non-numeric values throw a {@link TypoError}.
+ *
+ * @example
+ * ```ts
+ * typeInteger.decoder("42")   // → 42n
+ * typeInteger.decoder("3.14") // throws TypoError
+ * typeInteger.decoder("abc")  // throws TypoError
+ * ```
+ */
 declare const typeInteger: Type<bigint>;
+/**
+ * A {@link Type} that parses a string into a `URL` object using the `URL` constructor.
+ *
+ * The string must be a valid absolute URL (e.g. `"https://example.com/path?q=1"`).
+ * Relative URLs and malformed strings throw a {@link TypoError}.
+ *
+ * @example
+ * ```ts
+ * typeUrl.decoder("https://example.com") // → URL { href: "https://example.com/", ... }
+ * typeUrl.decoder("not-a-url")           // throws TypoError
+ * ```
+ */
 declare const typeUrl: Type<URL>;
+/**
+ * A {@link Type} that passes the raw string through unchanged (identity decoder).
+ *
+ * This is the simplest type and accepts any string value without validation.
+ *
+ * @example
+ * ```ts
+ * typeString.decoder("hello") // → "hello"
+ * typeString.decoder("")      // → ""
+ * ```
+ */
 declare const typeString: Type<string>;
+/**
+ * Creates a new {@link Type} by chaining a `before` type decoder with an `after`
+ * transformation.
+ *
+ * The raw string is first decoded by `before.decoder`; its result is then passed to
+ * `after.decoder`. Errors from `before` are wrapped with a "from: <content>" context
+ * prefix so that the full decoding path is visible in error messages.
+ *
+ * Use this when an existing type (e.g. {@link typeString}, {@link typeOneOf}) produces
+ * an intermediate value that needs a further transformation (e.g. parsing a
+ * string-keyed enum into a number).
+ *
+ * @typeParam Before - The intermediate type produced by `before.decoder`.
+ * @typeParam After - The final type produced by `after.decoder`.
+ *
+ * @param before - The base type that decodes the raw CLI string.
+ * @param after - The transformation applied to the `Before` value.
+ * @param after.content - Human-readable name for the resulting type (shown in errors).
+ * @param after.decoder - Function that converts a `Before` value into `After`.
+ * @returns A new {@link Type}`<After>` whose `content` is `after.content`.
+ *
+ * @example
+ * ```ts
+ * const typePort = typeConverted(typeNumber, {
+ *   content: "Port",
+ *   decoder: (n) => {
+ *     if (n < 1 || n > 65535) throw new Error("Out of range");
+ *     return n;
+ *   },
+ * });
+ * // "--port 8080"   →  8080
+ * // "--port 99999"  →  TypoError: --port: <PORT>: Port: Out of range
+ * ```
+ */
 declare function typeConverted<Before, After>(before: Type<Before>, after: {
     content: string;
     decoder: (value: Before) => After;
 }): Type<After>;
+/**
+ * Creates a {@link Type}`<string>` that only accepts a fixed set of string values.
+ *
+ * The decoder performs an exact (case-sensitive) lookup in `values`. If the input is
+ * not in the set, a {@link TypoError} is thrown listing up to 5 of the valid options.
+ *
+ * Combine with {@link typeConverted} to map the accepted strings to a richer type.
+ *
+ * @param content - Human-readable name for this type shown in help text and error
+ *   messages (e.g. `"Environment"`, `"LogLevel"`).
+ * @param values - The ordered list of accepted string values. The order is preserved in
+ *   the error message preview.
+ * @returns A {@link Type}`<string>` that validates membership in `values`.
+ *
+ * @example
+ * ```ts
+ * const typeEnv = typeOneOf("Environment", ["dev", "staging", "prod"]);
+ * typeEnv.decoder("prod")    // → "prod"
+ * typeEnv.decoder("unknown") // throws TypoError: Invalid value: "unknown" (expected one of: "dev" | "staging" | "prod")
+ * ```
+ */
 declare function typeOneOf(content: string, values: Array<string>): Type<string>;
+/**
+ * Creates a {@link Type} that decodes a single delimited string into a fixed-length
+ * tuple of typed elements.
+ *
+ * The raw string is split on `separator` into exactly `elementTypes.length` parts.
+ * Each part is decoded by its corresponding element type. If the number of splits does
+ * not match, or if any element's decoder fails, a {@link TypoError} is thrown with the
+ * index and element type context.
+ *
+ * The resulting `content` is the element types' `content` values joined by `separator`
+ * (e.g. `"Number,String"` for a `[number, string]` tuple with `","` separator).
+ *
+ * @typeParam Elements - The tuple type of decoded element values (inferred from
+ *   `elementTypes`).
+ *
+ * @param elementTypes - An ordered array of {@link Type}s, one per tuple element.
+ * @param separator - The string used to split the raw value (default: `","`).
+ * @returns A {@link Type}`<Elements>` tuple type.
+ *
+ * @example
+ * ```ts
+ * const typePoint = typeTuple([typeNumber, typeNumber]);
+ * typePoint.decoder("3.14,2.71") // → [3.14, 2.71]
+ * typePoint.decoder("1,2,3")     // → [1, 2]
+ * typePoint.decoder("x,2")       // throws TypoError: at 0: Number: Unable to parse: "x"
+ * ```
+ */
 declare function typeTuple<const Elements extends Array<any>>(elementTypes: {
     [K in keyof Elements]: Type<Elements[K]>;
 }, separator?: string): Type<Elements>;
+/**
+ * Creates a {@link Type} that decodes a single delimited string into an array of
+ * homogeneous typed elements.
+ *
+ * The raw string is split on `separator` and each part is decoded by `elementType`.
+ * If any element's decoder fails, a {@link TypoError} is thrown with the index and
+ * element type context.
+ *
+ * Unlike {@link typeTuple}, the number of elements is not fixed; the result array
+ * length equals the number of `separator`-delimited parts in the input string. To pass
+ * an empty array, the user must pass an empty string (`""`), which splits into one
+ * empty-string element — consider using {@link optionRepeatable} instead if you want a
+ * naturally empty default.
+ *
+ * The `content` is formatted as `"<elementContent>[<sep><elementContent>]..."` to
+ * signal repeatability.
+ *
+ * @typeParam Value - The TypeScript element type produced by `elementType.decoder`.
+ *
+ * @param elementType - The {@link Type} used to decode each element.
+ * @param separator - The string used to split the raw value (default: `","`).
+ * @returns A {@link Type}`<Array<Value>>`.
+ *
+ * @example
+ * ```ts
+ * const typeNumbers = typeList(typeNumber);
+ * typeNumbers.decoder("1,2,3")  // → [1, 2, 3]
+ * typeNumbers.decoder("1,x,3")  // throws TypoError: at 1: Number: Unable to parse: "x"
+ *
+ * const typePaths = typeList(typeString, ":");
+ * typePaths.decoder("/usr/bin:/usr/local/bin") // → ["/usr/bin", "/usr/local/bin"]
+ * ```
+ */
 declare function typeList<Value>(elementType: Type<Value>, separator?: string): Type<Array<Value>>;
 
+/**
+ * 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}.
+ */
 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: ReaderArgs): OptionGetter<Value>;
 };
+/**
+ * Human-readable metadata for a single CLI option, used to render the `Options:` section
+ * of the help output produced by {@link usageToStyledLines}.
+ */
 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>;
+    /**
+     * 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.
+ */
 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",
+ * });
+ * ```
+ */
 declare function optionFlag(definition: {
     long: Lowercase<string>;
     short?: string;
@@ -71,6 +488,47 @@ declare function optionFlag(definition: {
     };
     default?: () => boolean;
 }): Option<boolean>;
+/**
+ * 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/",
+ * });
+ * ```
+ */
 declare function optionSingleValue<Value>(definition: {
     long: Lowercase<string>;
     short?: string;
@@ -84,6 +542,45 @@ declare function optionSingleValue<Value>(definition: {
     type: Type<Value>;
     default: () => Value;
 }): Option<Value>;
+/**
+ * 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"]
+ * ```
+ */
 declare function optionRepeatable<Value>(definition: {
     long: Lowercase<string>;
     short?: string;
@@ -97,21 +594,121 @@ declare function optionRepeatable<Value>(definition: {
     type: Type<Value>;
 }): Option<Array<Value>>;
 
+/**
+ * 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.
+ */
 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}.
+ */
 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"
+ * ```
+ */
 declare function positionalRequired<Value>(definition: {
     description?: string;
     hint?: string;
     label?: Uppercase<string>;
     type: Type<Value>;
 }): Positional<Value>;
+/**
+ * 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"
+ * ```
+ */
 declare function positionalOptional<Value>(definition: {
     description?: string;
     hint?: string;
@@ -119,6 +716,45 @@ declare function positionalOptional<Value>(definition: {
     type: Type<Value>;
     default: () => Value;
 }): Positional<Value>;
+/**
+ * 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                  →  []
+ * ```
+ */
 declare function positionalVariadics<Value>(definition: {
     endDelimiter?: string;
     description?: string;
@@ -127,20 +763,128 @@ declare function positionalVariadics<Value>(definition: {
     type: Type<Value>;
 }): Positional<Array<Value>>;
 
+/**
+ * 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.
+ */
 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}.
+ */
 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.
+ */
 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 runAsCliAndExit}).
+     * @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}.
+ */
 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 runAsCliAndExit}).
+ * - `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);
+ *   },
+ * );
+ * ```
+ */
 declare function operation<Context, Result, Options extends {
     [option: string]: any;
 }, const Positionals extends Array<any>>(inputs: {
@@ -155,45 +899,342 @@ declare function operation<Context, Result, Options extends {
     positionals: Positionals;
 }) => Promise<Result>): OperationDescriptor<Context, Result>;
 
+/**
+ * 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 runAsCliAndExit} to run your CLI.
+ *
+ * @typeParam Context - The value passed into the command when it is executed. It flows
+ *   from {@link runAsCliAndExit}'s `context` argument down through the command chain.
+ * @typeParam Result - The value produced by executing the command. For root commands
+ *   passed to {@link runAsCliAndExit} this is always `void`.
+ */
 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}.
+ */
 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.
+ */
 type CommandInstance<Context, Result> = {
+    /**
+     * Executes the command with the provided context.
+     *
+     * @param context - Arbitrary value injected by the caller (see {@link runAsCliAndExit}).
+     * @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}.
+ */
 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>;
 };
+/**
+ * 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.
+ */
 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`.
+ */
 type CommandUsageBreadcrumb = {
     positional: string;
 } | {
     command: string;
 };
+/**
+ * Summary information about a single subcommand shown in the `Subcommands:` section
+ * of the usage output.
+ */
 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 runAsCliAndExit}
+ *   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}!`),
+ *   ),
+ * );
+ * ```
+ */
 declare function command<Context, Result>(information: CommandInformation, operation: OperationDescriptor<Context, Result>): CommandDescriptor<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),
+ *   },
+ * );
+ * ```
+ */
 declare function commandWithSubcommands<Context, Payload, Result>(information: CommandInformation, operation: OperationDescriptor<Context, Payload>, subcommands: {
     [subcommand: Lowercase<string>]: CommandDescriptor<Payload, Result>;
 }): CommandDescriptor<Context, 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),
+ * );
+ * ```
+ */
 declare function commandChained<Context, Payload, Result>(information: CommandInformation, operation: OperationDescriptor<Context, Payload>, nextCommand: CommandDescriptor<Payload, Result>): CommandDescriptor<Context, Result>;
 
+/**
+ * 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.onExecutionError - Custom handler for errors thrown during command
+ *   execution. If omitted, the error is printed to stderr via {@link TypoSupport}.
+ * @param options.onLogStdOut - Overrides the standard output sink (default: `console.log`).
+ * @param options.onLogStdErr - Overrides the standard error sink (default: `console.error`).
+ * @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 { runAsCliAndExit, 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 runAsCliAndExit("greet", process.argv.slice(2), undefined, greetCommand, {
+ *   buildVersion: "1.0.0",
+ * });
+ * ```
+ */
 declare function runAsCliAndExit<Context>(cliName: Lowercase<string>, cliArgs: ReadonlyArray<string>, context: Context, command: CommandDescriptor<Context, void>, options?: {
     useTtyColors?: boolean | undefined | "mock";
     usageOnHelp?: boolean | undefined;
@@ -205,62 +1246,331 @@ declare function runAsCliAndExit<Context>(cliName: Lowercase<string>, cliArgs: R
     onExit?: ((code: number) => never) | undefined;
 }): Promise<never>;
 
+/**
+ * Available foreground and background color names for terminal styling.
+ *
+ * Colors are divided into two groups:
+ * - **dark** variants correspond to standard ANSI colors (codes 30–37 / 40–47).
+ * - **bright** variants correspond to high-intensity ANSI colors (codes 90–97 / 100–107).
+ *
+ * Used by {@link TypoStyle}'s `fgColor` and `bgColor` fields.
+ */
 type TypoColor = "darkBlack" | "darkRed" | "darkGreen" | "darkYellow" | "darkBlue" | "darkMagenta" | "darkCyan" | "darkWhite" | "brightBlack" | "brightRed" | "brightGreen" | "brightYellow" | "brightBlue" | "brightMagenta" | "brightCyan" | "brightWhite";
+/**
+ * Describes the visual styling to apply to a text segment when rendered by a
+ * {@link TypoSupport} instance.
+ *
+ * All fields are optional. When `TypoSupport` is in `"none"` mode, no styling is
+ * applied and the raw text is returned unchanged. In `"tty"` mode the corresponding
+ * ANSI escape codes are emitted. In `"mock"` mode a deterministic textual representation
+ * is produced (useful for snapshot tests).
+ */
 type TypoStyle = {
+    /** Foreground (text) color. */
     fgColor?: TypoColor;
+    /** Background color. */
     bgColor?: TypoColor;
+    /** Render the text with reduced intensity. */
     dim?: boolean;
+    /** Render the text in bold. */
     bold?: boolean;
+    /** Render the text in italic. */
     italic?: boolean;
+    /** Render the text with an underline. */
     underline?: boolean;
+    /** Render the text with a strikethrough. */
     strikethrough?: boolean;
 };
+/**
+ * Pre-defined {@link TypoStyle} for section titles in the usage output (e.g.
+ * `"Positionals:"`, `"Options:"`).
+ * Rendered in bold dark-green.
+ */
 declare const typoStyleTitle: TypoStyle;
+/** Pre-defined {@link TypoStyle} for logic/type identifiers in error messages. Rendered in bold dark-magenta. */
 declare const typoStyleLogic: TypoStyle;
+/** Pre-defined {@link TypoStyle} for quoted user-supplied values in error messages. Rendered in bold dark-yellow. */
 declare const typoStyleQuote: TypoStyle;
+/** Pre-defined {@link TypoStyle} for failure/error labels (e.g. `"Error:"`). Rendered in bold dark-red. */
 declare const typoStyleFailure: TypoStyle;
+/** Pre-defined {@link TypoStyle} for CLI flag/option/command constant names. Rendered in bold dark-cyan. */
 declare const typoStyleConstants: TypoStyle;
+/** Pre-defined {@link TypoStyle} for positional placeholders and user-input labels. Rendered in bold dark-blue. */
 declare const typoStyleUserInput: TypoStyle;
+/** Pre-defined {@link TypoStyle} for strong regular text (e.g. command descriptions). Rendered in bold. */
 declare const typoStyleRegularStrong: TypoStyle;
+/** Pre-defined {@link TypoStyle} for subtle supplementary text (e.g. hints). Rendered in italic and dim. */
 declare const typoStyleRegularWeaker: TypoStyle;
+/**
+ * An immutable styled string segment consisting of a raw text value and an associated
+ * {@link TypoStyle}.
+ *
+ * Multiple `TypoString`s are composed into a {@link TypoText} for multi-part messages.
+ * Rendering is deferred until {@link TypoString.computeStyledString} is called with a
+ * {@link TypoSupport} instance.
+ */
 declare class TypoString {
     #private;
+    /**
+     * @param value - The raw text content.
+     * @param typoStyle - The style to apply when rendering. Defaults to `{}` (no style).
+     */
     constructor(value: string, typoStyle?: TypoStyle);
+    /** Returns the unstyled raw text content. */
     getRawString(): string;
+    /**
+     * Returns the text with ANSI escape codes (or mock markers) applied by `typoSupport`.
+     *
+     * @param typoSupport - Controls how styles are rendered (tty colors, mock, or none).
+     */
     computeStyledString(typoSupport: TypoSupport): string;
 }
+/**
+ * A mutable sequence of {@link TypoString} segments that together form a styled
+ * multi-part message.
+ *
+ * `TypoText` is used throughout the library to build error messages and usage output
+ * that carry styling information without being coupled to a specific output mode.
+ * Rendering is deferred to {@link TypoText.computeStyledString}.
+ */
 declare class TypoText {
     #private;
+    /**
+     * Creates a `TypoText` pre-populated with the provided parts. Each part can be a
+     * `TypoText` (flattened by value), a `TypoString`, or a plain `string` (wrapped in an
+     * unstyled `TypoString`).
+     *
+     * @param typoParts - Initial parts to append. Can be any mix of `TypoText`,
+     *   `TypoString`, and `string`.
+     */
     constructor(...typoParts: Array<TypoText | TypoString | string>);
+    /**
+     * Appends a single {@link TypoString} segment to the end of this text.
+     *
+     * @param typoString - The segment to append.
+     */
     pushString(typoString: TypoString): void;
+    /**
+     * Appends all segments from another {@link TypoText} to the end of this text
+     * (shallow copy of segments).
+     *
+     * @param typoText - The text whose segments are appended.
+     */
     pushText(typoText: TypoText): void;
+    /**
+     * Renders all segments into a single string, applying styles via `typoSupport`.
+     *
+     * @param typoSupport - Controls how styles are rendered.
+     * @returns The concatenated, optionally styled string.
+     */
     computeStyledString(typoSupport: TypoSupport): string;
+    /**
+     * Returns the concatenation of all segments' raw (unstyled) text.
+     * Equivalent to calling {@link TypoText.computeStyledString} with
+     * {@link TypoSupport.none}.
+     */
     computeRawString(): string;
+    /**
+     * Returns the total character length of the raw (unstyled) text.
+     * Used by {@link TypoGrid} to compute column widths for alignment.
+     */
     computeRawLength(): number;
 }
+/**
+ * A grid of {@link TypoText} cells that renders with column-aligned padding.
+ *
+ * Each row is an array of `TypoText` cells. When {@link TypoGrid.computeStyledGrid} is
+ * called, each column is padded to the width of its widest cell (measured in raw
+ * characters). The last column in each row is **not** padded.
+ *
+ * Used internally by {@link usageToStyledLines} to render the `Positionals:`,
+ * `Subcommands:`, and `Options:` sections with neat alignment.
+ */
 declare class TypoGrid {
     #private;
     constructor();
+    /**
+     * Appends a row of cells to the grid.
+     *
+     * @param cells - An ordered array of {@link TypoText} cells for this row. All rows
+     *   should have the same number of cells for alignment to be meaningful.
+     */
     pushRow(cells: Array<TypoText>): void;
+    /**
+     * Renders the grid into a 2-D array of styled strings, with space padding added
+     * between columns (except after the last column).
+     *
+     * @param typoSupport - Controls how styles are rendered.
+     * @returns A 2-D array where each inner array is the styled (and padded) cells of
+     *   one row. Join the inner arrays with `""` to get a single line string.
+     */
     computeStyledGrid(typoSupport: TypoSupport): Array<Array<string>>;
 }
+/**
+ * An `Error` subclass that carries a {@link TypoText} styled message in addition to
+ * the plain-text `Error.message` used by the standard JS error chain.
+ *
+ * `TypoError` is used throughout `cli-kiss` to report parsing failures (unknown option,
+ * type decoding error, missing required argument, etc.). Its styled representation is
+ * rendered by {@link TypoSupport.computeStyledErrorMessage} when outputting errors to
+ * the terminal.
+ *
+ * Errors can be chained: if `source` is a `TypoError`, its styled text is appended
+ * after `": "` to form the full message context chain.
+ */
 declare class TypoError extends Error {
     #private;
+    /**
+     * @param currentTypoText - The styled message for this error level.
+     * @param source - An optional cause. If it is a `TypoError`, its styled text is
+     *   appended (chained context). If it is a plain `Error`, its `.message` is appended
+     *   as a plain string. Any other value is stringified with `String()`.
+     */
     constructor(currentTypoText: TypoText, source?: unknown);
+    /**
+     * Renders this error's styled message as a string.
+     *
+     * @param typoSupport - Controls how ANSI styles are applied.
+     * @returns The full styled error message (without a leading `"Error:"` prefix).
+     */
     computeStyledString(typoSupport: TypoSupport): string;
+    /**
+     * Executes `thrower` and returns its result. If `thrower` throws any error, the error
+     * is re-thrown as a new `TypoError` whose message is `context()` with the original
+     * error chained as the source.
+     *
+     * This is a convenience helper for adding contextual information to errors that arise
+     * deep in a call chain (e.g. "at 0: Number: Unable to parse: ...").
+     *
+     * @typeParam Value - The return type of `thrower`.
+     * @param thrower - A zero-argument function whose return value is passed through on
+     *   success.
+     * @param context - A zero-argument factory that produces the {@link TypoText} context
+     *   prepended to the caught error. Called only when `thrower` throws.
+     * @returns The value returned by `thrower`.
+     * @throws `TypoError` wrapping the original error with the provided context prepended.
+     */
     static tryWithContext<Value>(thrower: () => Value, context: () => TypoText): Value;
 }
+/**
+ * Controls whether and how ANSI terminal styling is applied when rendering
+ * {@link TypoString}, {@link TypoText}, and error messages.
+ *
+ * Instances are created via the static factory methods:
+ * - {@link TypoSupport.none} — strips all styling (plain text).
+ * - {@link TypoSupport.tty} — applies ANSI escape codes for color terminals.
+ * - {@link TypoSupport.mock} — applies a deterministic textual representation useful
+ *   for snapshot tests.
+ * - {@link TypoSupport.inferFromProcess} — auto-detects based on `process.stdout.isTTY`
+ *   and the `FORCE_COLOR` / `NO_COLOR` environment variables.
+ *
+ * `TypoSupport` is consumed by {@link runAsCliAndExit} (via the `useTtyColors` option)
+ * and can also be used directly when building custom usage renderers with
+ * {@link usageToStyledLines}.
+ */
 declare class TypoSupport {
     #private;
     private constructor();
+    /**
+     * Returns a `TypoSupport` that strips all styling — every styled string is returned
+     * as-is (plain text, no ANSI codes).
+     */
     static none(): TypoSupport;
+    /**
+     * Returns a `TypoSupport` that applies ANSI escape codes.
+     * Use this when writing to a color-capable terminal (`stdout.isTTY === true`).
+     */
     static tty(): TypoSupport;
+    /**
+     * Returns a `TypoSupport` that applies a deterministic mock styling representation.
+     *
+     * Instead of real ANSI codes, each style flag is expressed as a readable suffix:
+     * `{text}@color`, `{text}+` (bold), `{text}-` (dim), `{text}*` (italic),
+     * `{text}_` (underline), `{text}~` (strikethrough). Useful for snapshot testing.
+     */
     static mock(): TypoSupport;
+    /**
+     * Selects a `TypoSupport` mode automatically based on the current process environment:
+     *
+     * 1. `FORCE_COLOR=0` or `NO_COLOR` env var set → {@link TypoSupport.none}.
+     * 2. `FORCE_COLOR` env var set (any truthy value) → {@link TypoSupport.tty}.
+     * 3. `process.stdout.isTTY === true` → {@link TypoSupport.tty}.
+     * 4. Otherwise → {@link TypoSupport.none}.
+     *
+     * Falls back to {@link TypoSupport.none} if `process` is not available (e.g. in a
+     * non-Node environment).
+     */
     static inferFromProcess(): TypoSupport;
+    /**
+     * Applies the given {@link TypoStyle} to `value` and returns the styled string.
+     *
+     * - In `"none"` mode: returns `value` unchanged.
+     * - In `"tty"` mode: wraps `value` in ANSI escape codes and appends a reset code.
+     * - In `"mock"` mode: wraps `value` in a deterministic textual representation.
+     *
+     * @param value - The raw text to style.
+     * @param typoStyle - The style to apply.
+     * @returns The styled string.
+     */
     computeStyledString(value: string, typoStyle: TypoStyle): string;
+    /**
+     * Formats an error value as a styled `"Error: <message>"` string.
+     *
+     * - If `error` is a {@link TypoError}, its styled text is used for the message part.
+     * - If `error` is a plain `Error`, its `.message` property is used.
+     * - Otherwise `String(error)` is used.
+     *
+     * The `"Error:"` prefix is always styled with {@link typoStyleFailure}.
+     *
+     * @param error - The error to format (any value thrown by a handler).
+     * @returns A styled error string ready to print to stderr.
+     */
     computeStyledErrorMessage(error: unknown): string;
 }
 
+/**
+ * Converts a {@link CommandUsage} model into an array of styled lines ready to be
+ * joined with `"\n"` and printed to the terminal.
+ *
+ * The output format is:
+ * ```
+ * Usage: <cliName> [breadcrumbs...]
+ *
+ * <description> (<hint>)
+ * <detail lines...>
+ *
+ * Positionals:
+ *   <LABEL>  <description> (<hint>)
+ *
+ * Subcommands:
+ *   <name>  <description> (<hint>)
+ *
+ * Options:
+ *   -s, --long <LABEL>  <description> (<hint>)
+ *
+ * ```
+ * Sections that have no entries are omitted. The trailing empty line is always included.
+ *
+ * Column alignment within each section is handled by {@link TypoGrid}: the widest entry
+ * in each column sets the width for the entire section.
+ *
+ * @param params.cliName - The CLI program name shown at the start of the usage line.
+ * @param params.commandUsage - The usage model produced by
+ *   {@link CommandFactory.generateUsage}.
+ * @param params.typoSupport - Controls color/styling of the output.
+ * @returns An ordered array of strings, one per output line (including a trailing
+ *   empty string for the blank line at the end).
+ *
+ * @example
+ * ```ts
+ * const lines = usageToStyledLines({
+ *   cliName: "my-cli",
+ *   commandUsage: commandFactory.generateUsage(),
+ *   typoSupport: TypoSupport.none(),
+ * });
+ * process.stdout.write(lines.join("\n"));
+ * ```
+ */
 declare function usageToStyledLines(params: {
     cliName: Lowercase<string>;
     commandUsage: CommandUsage;