cli-kiss 0.2.6 → 0.2.8

package/README.md

@@ -1,6 +1,14 @@
-# CLI - Keep It Simple, Stupid
+# cli-kiss
 
-Full-featured CLI builder for TypeScript. No bloat, no dependency.
+Type-safe CLI builder for TypeScript. No dependencies, no supply-chain attacks.
+
+Small API, standard compliance, polished help output, zero runtime dependencies.
+
+## Why
+
+- Compose commands, subcommands, options, and positionals with strong types
+- Get built-in `--help`, `--version`, and color-aware error messages
+- Ship a real CLI parser without pulling in a dependency tree
 
 ## Install
 
@@ -8,6 +16,56 @@ Full-featured CLI builder for TypeScript. No bloat, no dependency.
 npm install cli-kiss
 ```
 
-## Cookbook
+## Example
+
+```ts
+import {
+  command,
+  operation,
+  optionFlag,
+  positionalRequired,
+  runAndExit,
+  type,
+} from "cli-kiss";
+
+const greet = command(
+  { description: "Greet someone" },
+  operation(
+    {
+      options: {
+        loud: optionFlag({ long: "loud", description: "Print in uppercase" }),
+      },
+      positionals: [positionalRequired({ type: type("name") })],
+    },
+    async (_ctx, { options: { loud }, positionals: [name] }) => {
+      const text = `Hello, ${name}!`;
+      console.log(loud ? text.toUpperCase() : text);
+    },
+  ),
+);
+
+await runAndExit("greet", process.argv.slice(2), {}, greet, {
+  buildVersion: "1.0.0",
+});
+```
+
+```sh
+greet --help
+```
+
+```text
+Usage: greet <name>
+
+Greet someone
+
+Positionals:
+  <name>
+
+Options:
+  --loud[=no]  Print in uppercase
+```
+
+## Docs
 
-Documentation and examples: **<https://crypto-vincent.github.io/cli-kiss/>** 💋
+Guides, examples, and API usage:
+[crypto-vincent.github.io/cli-kiss](https://crypto-vincent.github.io/cli-kiss/)

package/dist/index.d.ts

@@ -1,47 +1,43 @@
 /**
- * Opaque key returned by {@link ReaderArgs.registerOption}.
  */
-type ReaderOptionKey = (string | {
-    __brand: "ReaderOptionKey";
-}) & {
-    __brand: "ReaderOptionKey";
+type ReaderOptionLongSpec = {
+    key: string;
+    nextGuard: ReaderOptionNextGuard;
 };
 /**
- * Parsing behaviour for a registered option, passed to {@link ReaderArgs.registerOption}.
  */
-type ReaderOptionParsing = {
-    consumeShortGroup: boolean;
-    consumeNextArg: (inlined: string | null, separated: Array<string>, nextArg: string | undefined) => boolean;
+type ReaderOptionShortSpec = {
+    key: string;
+    restGuard: ReaderOptionRestGuard;
+    nextGuard: ReaderOptionNextGuard;
+};
+/**
+ */
+type ReaderOptionRestGuard = (rest: string) => boolean;
+/**
+ */
+type ReaderOptionNextGuard = (value: ReaderOptionValue, next: string | undefined) => boolean;
+/**
+ */
+type ReaderOptionResult = {
+    identifier: string;
+    values: ReadonlyArray<ReaderOptionValue>;
 };
 /**
- * Result of parsing an option, including its inlined value and any following separated values.
  */
 type ReaderOptionValue = {
     inlined: string | null;
-    separated: Array<string>;
+    separated: ReadonlyArray<string>;
 };
+/**
+ */
+type ReaderOptionGetter = () => ReaderOptionResult;
 /**
  * Option registration/query interface. Subset of {@link ReaderArgs}.
  */
 type ReaderOptions = {
-    /**
-     * Registers an option; all `longs` and `shorts` share the same key.
-     *
-     * @param definition.longs - Long-form names (without `--`).
-     * @param definition.shorts - Short-form names (without `-`).
-     * @param definition.parsing - Parsing behaviour.
-     * @returns A {@link ReaderOptionKey} for later retrieval.
-     * @throws `Error` if a name is already registered or short names overlap.
-     */
-    registerOption(definition: {
-        longs: Array<string>;
-        shorts: Array<string>;
-        parsing: ReaderOptionParsing;
-    }): ReaderOptionKey;
-    /**
-     * Returns all values collected for `key`.
-     */
-    getOptionValues(key: ReaderOptionKey): Array<ReaderOptionValue>;
+    registerOptionLong(longSpec: ReaderOptionLongSpec): ReaderOptionGetter;
+    registerOptionShort(shortSpec: ReaderOptionShortSpec): ReaderOptionGetter;
 };
 /**
  * Positional consumption interface. Subset of {@link ReaderArgs}.
@@ -51,7 +47,7 @@ type ReaderPositionals = {
      * Returns the next positional token, parsing intervening options as side-effects.
      *
      * @returns The next positional, or `undefined` when exhausted.
-     * @throws {@link TypoError} on an unrecognised option.
+     * @throws on an unrecognised option.
      */
     consumePositional(): string | undefined;
 };
@@ -67,38 +63,21 @@ type ReaderPositionals = {
 declare class ReaderArgs {
     #private;
     /**
-     * @param args - Raw CLI tokens (e.g. `process.argv.slice(2)`). Not mutated.
+     * @param tokens - Raw CLI tokens (e.g. `process.argv.slice(2)`).
      */
-    constructor(args: ReadonlyArray<string>);
+    constructor(tokens: ReadonlyArray<string>);
+    /**
+     */
+    registerOptionLong(longSpec: ReaderOptionLongSpec): ReaderOptionGetter;
     /**
-     * Registers an option; all `longs` and `shorts` share the same key.
-     * Short names must not be prefixes of one another.
-     *
-     * @param definition.longs - Long-form names (without `--`).
-     * @param definition.shorts - Short-form names (without `-`).
-     * @param definition.parsing - Parsing behaviour.
-     * @returns A {@link ReaderOptionKey} for {@link ReaderArgs.getOptionValues}.
-     * @throws `Error` if any name is already registered or short names overlap.
-     */
-    registerOption(definition: {
-        longs: Array<string>;
-        shorts: Array<string>;
-        parsing: ReaderOptionParsing;
-    }): ReaderOptionKey;
-    /**
-     * Returns all values collected for `key`.
-     *
-     * @param key - Key from {@link ReaderArgs.registerOption}.
-     * @returns One entry per occurrence.
-     * @throws `Error` if `key` was not registered.
      */
-    getOptionValues(key: ReaderOptionKey): Array<ReaderOptionValue>;
+    registerOptionShort(shortSpec: ReaderOptionShortSpec): ReaderOptionGetter;
     /**
      * Returns the next positional token; parses intervening options as a side-effect.
      * All tokens after `--` are treated as positionals.
      *
      * @returns The next positional, or `undefined` when exhausted.
-     * @throws {@link TypoError} on an unrecognised option.
+     * @throws on an unrecognised option.
      */
     consumePositional(): string | undefined;
 }
@@ -115,7 +94,7 @@ declare class ReaderArgs {
  */
 type Type<Value> = {
     /**
-     * Human-readable name shown in help and errors (e.g. `"name"`, `"number"`).
+     * Human-readable name shown in help and errors (e.g. `"name"`, `"context"`).
      */
     content: string;
     /**
@@ -123,7 +102,7 @@ type Type<Value> = {
      *
      * @param input - Raw string from the command line.
      * @returns The decoded value.
-     * @throws {@link TypoError} on invalid input.
+     * @throws on invalid input.
      */
     decoder(input: string): Value;
 };
@@ -142,8 +121,6 @@ type Type<Value> = {
  * ```
  */
 declare function typeBoolean(name?: string): Type<boolean>;
-declare const typeBooleanValuesTrue: Set<string>;
-declare const typeBooleanValuesFalse: Set<string>;
 /**
  * Parses a date/time string via `Date.parse`.
  * Accepts any format supported by `Date.parse`, including ISO 8601.
@@ -157,7 +134,7 @@ declare const typeBooleanValuesFalse: Set<string>;
  */
 declare function typeDatetime(name?: string): Type<Date>;
 /**
- * Parses a string to `number` via `Number()`; `NaN` throws {@link TypoError}.
+ * Parses a string to `number` via `Number()`; `NaN` throws.
  *
  * @example
  * ```ts
@@ -169,7 +146,7 @@ declare function typeDatetime(name?: string): Type<Date>;
 declare function typeNumber(name?: string): Type<number>;
 /**
  * Parses an integer string to `bigint` via `BigInt()`.
- * Floats and non-numeric strings throw {@link TypoError}.
+ * Floats and non-numeric strings throws.
  *
  * @example
  * ```ts
@@ -181,7 +158,7 @@ declare function typeNumber(name?: string): Type<number>;
 declare function typeInteger(name?: string): Type<bigint>;
 /**
  * Parses an absolute URL string to a `URL` object.
- * Relative or malformed URLs throw {@link TypoError}.
+ * Relative or malformed URLs throws.
  *
  * @example
  * ```ts
@@ -241,7 +218,6 @@ declare function typePath(name?: string, checks?: {
 }): Type<string>;
 /**
  * Creates a {@link Type}`<string>` that only accepts a fixed set of values.
- * Out-of-set inputs throw {@link TypoError} listing up to 5 valid options.
  *
  * @param name - Name shown in help and errors.
  * @param values - Ordered list of accepted values.
@@ -251,13 +227,13 @@ declare function typePath(name?: string, checks?: {
  * ```ts
  * const typeEnv = typeChoice("environment", ["dev", "staging", "prod"]);
  * typeEnv.decoder("prod")    // → "prod"
- * typeEnv.decoder("unknown") // throws TypoError: Invalid value: "unknown" (expected one of: "dev" | "staging" | "prod")
+ * typeEnv.decoder("unknown") // throws
  * ```
  */
 declare function typeChoice<const Value extends string>(name: string, values: Array<Value>, caseSensitive?: boolean): Type<Value>;
 /**
  * Splits a delimited string into a typed tuple.
- * Each part is decoded by the corresponding element type; wrong count or decode failure throws {@link TypoError}.
+ * Each part is decoded by the corresponding element type; wrong count or decode failure throws.
  *
  * @typeParam Elements - Tuple of decoded value types (inferred from `elementTypes`).
  *
@@ -269,8 +245,9 @@ declare function typeChoice<const Value extends string>(name: string, values: Ar
  * ```ts
  * const typePoint = typeTuple([typeNumber("x"), typeNumber("y")]);
  * 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"
+ * typePoint.decoder("1")         // throws
+ * typePoint.decoder("1,2,3")     // throws
+ * typePoint.decoder("x,2")       // throws
  * ```
  */
 declare function typeTuple<const Elements extends Array<any>>(elementTypes: {
@@ -278,7 +255,7 @@ declare function typeTuple<const Elements extends Array<any>>(elementTypes: {
 }, separator?: string): Type<Elements>;
 /**
  * Splits a delimited string into a typed array.
- * Each part is decoded by `elementType`; failed decodes throw {@link TypoError}.
+ * Each part is decoded by `elementType`; failed decodes throws.
  * Note: splitting an empty string yields one empty element — prefer {@link optionRepeatable} for a zero-default.
  *
  * @typeParam Value - Element type produced by `elementType.decoder`.
@@ -289,10 +266,9 @@ declare function typeTuple<const Elements extends Array<any>>(elementTypes: {
  *
  * @example
  * ```ts
- * const typeNumbers = typeList(typeNumber);
+ * const typeNumbers = typeList(typeNumber("v"));
  * typeNumbers.decoder("1,2,3")  // → [1, 2, 3]
- * typeNumbers.decoder("1,x,3")  // throws TypoError: at 1: Number: Unable to parse: "x"
- *
+ * typeNumbers.decoder("1,x,3")  // throws
  * const typePaths = typeList(typePath(), ":");
  * typePaths.decoder("/usr/bin:/usr/local/bin") // → ["/usr/bin", "/usr/local/bin"]
  * ```
@@ -381,9 +357,9 @@ declare class TypoString {
     #private;
     /**
      * @param value - Raw text content.
-     * @param typoStyle - Style to apply when rendering. Defaults to `{}` (no style).
+     * @param style - Style to apply when rendering.
      */
-    constructor(value: string, typoStyle?: TypoStyle);
+    constructor(value: string, style?: TypoStyle);
     /**
      * Returns the text styled by `typoSupport`.
      *
@@ -394,7 +370,15 @@ declare class TypoString {
      * Returns the raw text.
      */
     getRawString(): string;
+    /**
+     * Predefined ellipsis segment with subtle styling.
+     */
+    static elipsis: TypoString;
 }
+/**
+ * A segment of styled text, a string, or an array of segments.
+ */
+type TypoSegment = TypoText | TypoString | Array<TypoSegment>;
 /**
  * Mutable sequence of {@link TypoString} segments.
  */
@@ -403,13 +387,15 @@ declare class TypoText {
     /**
      * @param segments - Initial text segments
      */
-    constructor(...segments: Array<TypoText | Array<TypoString> | TypoString | string>);
+    constructor(...segments: Array<TypoSegment>);
     /**
      * Appends new text segment(s).
-     *
-     * @param segment - Text segment(s) to append.
      */
-    push(segment: TypoText | Array<TypoString> | TypoString | string): void;
+    push(...segments: Array<TypoSegment>): void;
+    /**
+     * Appends separated segments, optionally truncating with an ellipsis.
+     */
+    pushJoined(segments: Array<TypoSegment>, separator: TypoSegment, ellipsisLimit: number): void;
     /**
      * Renders all segments into a single styled string.
      *
@@ -505,7 +491,7 @@ declare class TypoSupport {
      * @param typoStyle - Style to apply.
      * @returns Styled string.
      */
-    computeStyledString(value: string, typoStyle: TypoStyle): string;
+    computeStyledString(value: string, typoStyle: TypoStyle | undefined): string;
     /**
      * Formats any thrown value as `"Error: <message>"` with {@link typoStyleFailure} on the prefix.
      *
@@ -671,7 +657,7 @@ type Option<Value> = {
     /**
      * Registers the option on `readerOptions` and returns an {@link OptionDecoder}.
      */
-    registerAndMakeDecoder(readerOptions: ReaderArgs): OptionDecoder<Value>;
+    registerAndMakeDecoder(readerOptions: ReaderOptions): OptionDecoder<Value>;
 };
 /**
  * Produced by {@link Option.registerAndMakeDecoder}.
@@ -682,15 +668,19 @@ type OptionDecoder<Value> = {
     /**
      * Returns the decoded option value.
      *
-     * @throws {@link TypoError} if decoding failed.
+     * @throws if decoding failed.
      */
     getAndDecodeValue(): Value;
 };
 /**
  * Creates a boolean flag option (`--verbose`, optionally `--flag=no`).
  *
- * Parsing: absent → default value; `--flag` / `--flag=yes` → `true`; `--flag=no` → `false`;
- * specified more than once → throws {@link TypoError}.
+ * Syntax: `--long`, `--long=no`, `-s`, `-s=no`.
+ * Parsing logic:
+ * - absent → default value
+ * - `--flag` / `--flag=yes` → `true`
+ * - `--flag=no` → `false`
+ * - specified more than once → throws.
  *
  * @param definition.long - Long-form name (without `--`).
  * @param definition.short - Short-form name (without `-`).
@@ -707,11 +697,6 @@ type OptionDecoder<Value> = {
  *   short: "v",
  *   description: "Enable verbose output",
  * });
- * // Usage:
- * //   my-cli  →  false
- * //   my-cli --verbose  →  true
- * //   my-cli --verbose=yes  →  true
- * //   my-cli -v=no  →  false
  * ```
  */
 declare function optionFlag(definition: {
@@ -728,8 +713,13 @@ declare function optionFlag(definition: {
 /**
  * Creates an option that accepts exactly one value (e.g. `--output dist/`).
  *
- * Parsing: absent → `defaultValue()`; once → decoded with `type`; more than once → {@link TypoError}.
- * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
+ * Syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
+ * Parsing logic:
+ * - absent → `fallbackValueIfAbsent()`
+ * - `--long value` → decoded with `type.decoder("value")`
+ * - more than once → throws
+ * - if `impliedValueIfNotInlined` is not provided, then: `--long` / `-s` without a value → throws
+ * - if `impliedValueIfNotInlined` is provided, then: `--long` / `-s` without an inline value → `impliedValueIfNotInlined()`
  *
  * @typeParam Value - Type produced by the decoder.
  *
@@ -739,8 +729,8 @@ declare function optionFlag(definition: {
  * @param definition.hint - Short note shown in parentheses.
  * @param definition.aliases - Additional names.
  * @param definition.type - Decoder for the raw string value.
- * @param definition.valueWhenNotDefined - Default value when the option is not specified at all.
- * @param definition.valueWhenNotInlined - Default value when the option is specified without an inline value (e.g. `--option` or `-o`).
+ * @param definition.fallbackValueIfAbsent - Default value when the option is not specified at all.
+ * @param definition.impliedValueIfNotInlined - Default value when the option is specified without an inline value (e.g. `--option` or `-o`).
  * @returns An {@link Option}`<Value>`.
  *
  * @example
@@ -750,12 +740,8 @@ declare function optionFlag(definition: {
  *   short: "o",
  *   type: typePath(),
  *   description: "Output directory",
- *   valueWhenNotDefined: () => "dist",
+ *   fallbackValueIfAbsent: () => "dist",
  * });
- * // Usage:
- * //   my-cli  →  "dist"
- * //   my-cli --output folder  →  "folder"
- * //   my-cli -o folder  →  "folder"
  * ```
  */
 declare function optionSingleValue<Value>(definition: {
@@ -768,14 +754,16 @@ declare function optionSingleValue<Value>(definition: {
         shorts?: Array<string>;
     };
     type: Type<Value>;
-    defaultWhenNotDefined: () => Value;
-    defaultWhenNotInlined?: () => Value;
+    fallbackValueIfAbsent?: () => Value;
+    impliedValueIfNotInlined?: () => Value;
 }): Option<Value>;
 /**
  * Creates an option that collects every occurrence into an array (e.g. `--file a.ts --file b.ts`).
  *
- * Parsing: absent → `[]`; N occurrences → array of N decoded values in order.
- * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
+ * Syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
+ * Parsing logic:
+ * - absent → `[]`
+ * - N occurrences → array of N decoded values in order.
  *
  * @typeParam Value - Type produced by the decoder for each occurrence.
  *
@@ -796,7 +784,6 @@ declare function optionSingleValue<Value>(definition: {
  *   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: {
@@ -837,18 +824,24 @@ type PositionalDecoder<Value> = {
     /**
      * Returns the decoded positional value.
      *
-     * @throws {@link TypoError} if decoding failed.
+     * @throws if decoding failed.
      */
     decodeValue(): Value;
 };
 /**
- * Creates a required positional — missing token throws {@link TypoError}.
+ * Creates a required positional — missing token throws.
+ *
+ * Syntax: `<type>`, e.g. `<NAME>`.
+ * Parsing logic:
+ * - "token" → decoded with `type.decoder("token")`
+ * - token missing → throws
  *
  * @typeParam Value - Type produced by the decoder.
  *
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
  * @param definition.type - Decoder for the raw token.
+ * @param definition.missing - Message shown when the token is missing.
  * @returns A {@link Positional}`<Value>`.
  *
  * @example
@@ -857,8 +850,6 @@ type PositionalDecoder<Value> = {
  *   type: type("name"),
  *   description: "The name to greet",
  * });
- * // Usage:
- * //   my-cli Alice  →  "Alice"
  * ```
  */
 declare function positionalRequired<Value>(definition: {
@@ -869,6 +860,11 @@ declare function positionalRequired<Value>(definition: {
 /**
  * Creates an optional positional — absent token falls back to `default()`.
  *
+ * Syntax: `[type]`, e.g. `[NAME]`.
+ * Parsing logic:
+ * - "token" → decoded with `type.decoder("token")`
+ * - token missing → `default()`
+ *
  * @typeParam Value - Type produced by the decoder (or the default).
  *
  * @param definition.description - Help text.
@@ -881,12 +877,10 @@ declare function positionalRequired<Value>(definition: {
  * ```ts
  * const greeteePositional = positionalOptional({
  *   type: type("name"),
- *   description: "Name to greet (default: world)",
+ *   description: "Name to greet",
+ *   hint: "Defaults to \"world\"",
  *   default: () => "world",
  * });
- * // Usage:
- * //   my-cli  →  "world"
- * //   my-cli Alice  →  "Alice"
  * ```
  */
 declare function positionalOptional<Value>(definition: {
@@ -899,6 +893,12 @@ declare function positionalOptional<Value>(definition: {
  * Creates a variadic positional that collects zero or more remaining tokens into an array.
  * Optionally stops at `endDelimiter` (consumed, not included).
  *
+ * Syntax: `[type]...`, e.g. `[NAME]...`.
+ * Parsing logic:
+ * - "a b ..." → decoded with `[type.decoder("a")`, `type.decoder("b"), ...]``
+ * - token missing → stops collection
+ * - endDelimiter encountered → stops collection
+ *
  * @typeParam Value - Type produced by the decoder for each token.
  *
  * @param definition.endDelimiter - Sentinel token that stops collection (consumed, not included).
@@ -913,9 +913,6 @@ declare function positionalOptional<Value>(definition: {
  *   type: typePath(),
  *   description: "Files to process",
  * });
- * // Usage:
- * //   my-cli  →  []
- * //   my-cli a.ts b.ts c.ts  →  ["a.ts", "b.ts", "c.ts"]
  * ```
  */
 declare function positionalVariadics<Value>(definition: {
@@ -963,7 +960,7 @@ type OperationDecoder<Context, Result> = {
     /**
      * Creates a ready-to-execute {@link OperationInterpreter}.
      *
-     * @throws {@link TypoError} if parsing or decoding failed.
+     * @throws if parsing or decoding failed.
      */
     decodeAndMakeInterpreter(): OperationInterpreter<Context, Result>;
 };
@@ -1000,7 +997,7 @@ type OperationInterpreter<Context, Result> = {
  * const greetOperation = operation(
  *   {
  *     options: {
- *       loud: optionFlag({ long: "loud", description: "Print in uppercase", default: false }),
+ *       loud: optionFlag({ long: "loud", description: "Print in uppercase" }),
  *     },
  *     positionals: [
  *       positionalRequired({ type: type("name"), description: "Name to greet" }),
@@ -1013,18 +1010,22 @@ type OperationInterpreter<Context, Result> = {
  * );
  * ```
  */
-declare function operation<Context, Result, Options extends {
+declare function operation<Context, Result, const Options extends {
     [option: string]: any;
-}, const Positionals extends Array<any>>(inputs: {
-    options: {
+} = {}, const Positionals extends Array<any> = []>(inputs: {
+    options?: {
         [K in keyof Options]: Option<Options[K]>;
     };
-    positionals: {
+    positionals?: {
         [K in keyof Positionals]: Positional<Positionals[K]>;
     };
 }, handler: (context: Context, inputs: {
-    options: Options;
-    positionals: Positionals;
+    options: {
+        [K in keyof Options]: Options[K];
+    };
+    positionals: {
+        [K in keyof Positionals]: Positionals[K];
+    };
 }) => Promise<Result>): Operation<Context, Result>;
 
 /**
@@ -1057,7 +1058,7 @@ type CommandDecoder<Context, Result> = {
     /**
      * Creates a ready-to-execute {@link CommandInterpreter}.
      *
-     * @throws {@link TypoError} if parsing or decoding failed.
+     * @throws if parsing or decoding failed.
      */
     decodeAndMakeInterpreter(): CommandInterpreter<Context, Result>;
 };
@@ -1132,15 +1133,16 @@ type CommandInformation = {
  * const greet = command(
  *   { description: "Greet a user" },
  *   operation(
- *     { options: {}, positionals: [positionalRequired({ type: type("name") })] },
+ *     { positionals: [positionalRequired({ type: type("name") })] },
  *     async (_ctx, { positionals: [name] }) => console.log(`Hello, ${name}!`),
  *   ),
  * );
  * ```
  */
-declare function command<Context, Result>(information: CommandInformation, operation: Operation<Context, Result>): Command<Context, Result>;
+declare function command<Context, Result = void>(information: CommandInformation, operation: Operation<Context, Result>): Command<Context, Result>;
 /**
- * Creates a command that runs `operation` first, then dispatches to a named subcommand.
+ * Creates a command that runs `operation` first,
+ * then dispatches result to a named subcommand.
  *
  * @typeParam Context - Context accepted by `operation`.
  * @typeParam Payload - Output of `operation`; becomes the subcommand's context.
@@ -1163,12 +1165,12 @@ declare function command<Context, Result>(information: CommandInformation, opera
  * );
  * ```
  */
-declare function commandWithSubcommands<Context, Payload, Result>(information: CommandInformation, operation: Operation<Context, Payload>, subcommands: {
+declare function commandWithSubcommands<Context, Payload, Result = void>(information: CommandInformation, operation: Operation<Context, Payload>, subcommands: {
     [subcommand: string]: Command<Payload, Result>;
 }): Command<Context, Result>;
 /**
- * Chains an {@link Operation} and a {@link Command}: `operation` runs first, its
- * output becomes `subcommand`'s context. No token is consumed for routing.
+ * Chains an {@link Operation} and a {@link Command}: `operation` runs first,
+ * its output becomes `subcommand`'s context. No token is consumed for routing.
  *
  * @typeParam Context - Context accepted by `operation`.
  * @typeParam Payload - Output of `operation`; becomes `subcommand`'s context.
@@ -1179,7 +1181,7 @@ declare function commandWithSubcommands<Context, Payload, Result>(information: C
  * @param subcommand - Runs after `operation`.
  * @returns A {@link Command} composing both stages.
  */
-declare function commandChained<Context, Payload, Result>(information: CommandInformation, operation: Operation<Context, Payload>, subcommand: Command<Payload, Result>): Command<Context, Result>;
+declare function commandChained<Context, Payload, Result = void>(information: CommandInformation, operation: Operation<Context, Payload>, subcommand: Command<Payload, Result>): Command<Context, Result>;
 
 /**
  * Color selection modes availables
@@ -1236,4 +1238,9 @@ declare function runAndExit<Context>(cliName: string, cliArgs: ReadonlyArray<str
     onExit?: ((code: number) => never) | undefined;
 }): Promise<never>;
 
-export { type Command, type CommandDecoder, type CommandInformation, type CommandInterpreter, type Operation, type OperationDecoder, type OperationInterpreter, type Option, type OptionDecoder, type Positional, type PositionalDecoder, ReaderArgs, type ReaderOptionKey, type ReaderOptionParsing, type ReaderOptionValue, type ReaderOptions, type ReaderPositionals, type RunColorMode, type Type, type TypoColor, TypoError, TypoGrid, TypoString, type TypoStyle, TypoSupport, TypoText, type UsageCommand, type UsageOption, type UsagePositional, type UsageSubcommand, command, commandChained, commandWithSubcommands, operation, optionFlag, optionRepeatable, optionSingleValue, positionalOptional, positionalRequired, positionalVariadics, runAndExit, type, typeBoolean, typeBooleanValuesFalse, typeBooleanValuesTrue, typeChoice, typeConverted, typeDatetime, typeInteger, typeList, typeNumber, typePath, typeRenamed, typeTuple, typeUrl, typoStyleConstants, typoStyleFailure, typoStyleLogic, typoStyleQuote, typoStyleRegularStrong, typoStyleRegularWeaker, typoStyleTitle, typoStyleUserInput, usageToStyledLines };
+declare function suggestTextPushMessage(text: TypoText, query: string, candidates: Array<{
+    reference: string;
+    hint: TypoSegment;
+}>): void;
+
+export { type Command, type CommandDecoder, type CommandInformation, type CommandInterpreter, type Operation, type OperationDecoder, type OperationInterpreter, type Option, type OptionDecoder, type Positional, type PositionalDecoder, ReaderArgs, type ReaderOptionGetter, type ReaderOptionLongSpec, type ReaderOptionNextGuard, type ReaderOptionRestGuard, type ReaderOptionResult, type ReaderOptionShortSpec, type ReaderOptionValue, type ReaderOptions, type ReaderPositionals, type RunColorMode, type Type, type TypoColor, TypoError, TypoGrid, type TypoSegment, TypoString, type TypoStyle, TypoSupport, TypoText, type UsageCommand, type UsageOption, type UsagePositional, type UsageSubcommand, command, commandChained, commandWithSubcommands, operation, optionFlag, optionRepeatable, optionSingleValue, positionalOptional, positionalRequired, positionalVariadics, runAndExit, suggestTextPushMessage, type, typeBoolean, typeChoice, typeConverted, typeDatetime, typeInteger, typeList, typeNumber, typePath, typeRenamed, typeTuple, typeUrl, typoStyleConstants, typoStyleFailure, typoStyleLogic, typoStyleQuote, typoStyleRegularStrong, typoStyleRegularWeaker, typoStyleTitle, typoStyleUserInput, usageToStyledLines };