cli-kiss 0.1.7 → 0.1.9

package/dist/index.d.ts

@@ -1,117 +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;
 }
 
-type TypoColor = "darkBlack" | "darkRed" | "darkGreen" | "darkYellow" | "darkBlue" | "darkMagenta" | "darkCyan" | "darkWhite" | "brightBlack" | "brightRed" | "brightGreen" | "brightYellow" | "brightBlue" | "brightMagenta" | "brightCyan" | "brightWhite";
-type TypoStyle = {
-    fgColor?: TypoColor;
-    bgColor?: TypoColor;
-    dim?: boolean;
-    bold?: boolean;
-    italic?: boolean;
-    underline?: boolean;
-    strikethrough?: boolean;
-};
-declare const typoStyleFailure: TypoStyle;
-declare const typoStyleConstants: TypoStyle;
-declare const typoStyleUserInput: TypoStyle;
-declare const typoStyleQuote: TypoStyle;
-declare class TypoString {
-    #private;
-    constructor(value: string, typoStyle?: TypoStyle);
-    getRawString(): string;
-    computeStyledString(typoSupport: TypoSupport): string;
-}
-declare class TypoText {
-    #private;
-    constructor(...typoParts: Array<TypoText | TypoString | string>);
-    pushString(typoString: TypoString): void;
-    pushText(typoText: TypoText): void;
-    computeStyledString(typoSupport: TypoSupport): string;
-    computeRawString(): string;
-    computeRawLength(): number;
-}
-declare class TypoGrid {
-    #private;
-    constructor();
-    pushRow(cells: Array<TypoText>): void;
-    computeStyledGrid(typoSupport: TypoSupport): Array<Array<string>>;
-}
-declare class TypoError extends Error {
-    #private;
-    constructor(currentTypoText: TypoText, source?: unknown);
-    computeStyledString(typoSupport: TypoSupport): string;
-}
-declare class TypoSupport {
-    #private;
-    private constructor();
-    static none(): TypoSupport;
-    static tty(): TypoSupport;
-    static mock(): TypoSupport;
-    static inferFromProcess(): TypoSupport;
-    computeStyledString(value: string, typoStyle: TypoStyle): string;
-    computeStyledErrorMessage(error: unknown): string;
-}
-
+/**
+ * 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> = {
-    label: Uppercase<string>;
+    /**
+     * 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>;
-declare const typeNumber: Type<number>;
-declare const typeBigInt: Type<bigint>;
-declare function typeMapped<Before, After>(before: Type<Before>, after: {
-    label: Uppercase<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>;
-declare function typeOneOf<Value>(type: Type<Value>, values: Array<Value>): Type<Value>;
+/**
+ * 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>>;
-declare function typeDecode<Value>(type: Type<Value>, value: string, context: () => TypoText): 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;
@@ -123,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;
@@ -136,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;
@@ -149,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;
@@ -171,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;
@@ -179,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: {
@@ -207,47 +899,344 @@ 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?: {
-    useColors?: boolean | undefined;
+    useTtyColors?: boolean | undefined | "mock";
     usageOnHelp?: boolean | undefined;
     usageOnError?: boolean | undefined;
     buildVersion?: string | undefined;
@@ -257,10 +1246,335 @@ 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;
     typoSupport: TypoSupport;
 }): string[];
 
-export { type CommandDescriptor, type CommandFactory, type CommandInformation, type CommandInstance, type CommandUsage, type CommandUsageBreadcrumb, type CommandUsageSubcommand, type OperationDescriptor, type OperationFactory, type OperationInstance, type OperationUsage, type Option, type OptionGetter, type OptionUsage, type Positional, type PositionalUsage, ReaderArgs, type ReaderOptionKey, type ReaderOptions, type ReaderPositionals, type Type, type TypoColor, TypoError, TypoGrid, TypoString, type TypoStyle, TypoSupport, TypoText, command, commandChained, commandWithSubcommands, operation, optionFlag, optionRepeatable, optionSingleValue, positionalOptional, positionalRequired, positionalVariadics, runAsCliAndExit, typeBigInt, typeBoolean, typeDate, typeDecode, typeList, typeMapped, typeNumber, typeOneOf, typeString, typeTuple, typeUrl, typoStyleConstants, typoStyleFailure, typoStyleQuote, typoStyleUserInput, usageToStyledLines };
+export { type CommandDescriptor, type CommandFactory, type CommandInformation, type CommandInstance, type CommandUsage, type CommandUsageBreadcrumb, type CommandUsageSubcommand, type OperationDescriptor, type OperationFactory, type OperationInstance, type OperationUsage, type Option, type OptionGetter, type OptionUsage, type Positional, type PositionalUsage, ReaderArgs, type ReaderOptionKey, type ReaderOptions, type ReaderPositionals, type Type, type TypoColor, TypoError, TypoGrid, TypoString, type TypoStyle, TypoSupport, TypoText, command, commandChained, commandWithSubcommands, operation, optionFlag, optionRepeatable, optionSingleValue, positionalOptional, positionalRequired, positionalVariadics, runAsCliAndExit, typeBoolean, typeConverted, typeDate, typeInteger, typeList, typeNumber, typeOneOf, typeString, typeTuple, typeUrl, typoStyleConstants, typoStyleFailure, typoStyleLogic, typoStyleQuote, typoStyleRegularStrong, typoStyleRegularWeaker, typoStyleTitle, typoStyleUserInput, usageToStyledLines };