cli-kiss 0.2.4 → 0.2.6

package/dist/index.d.ts

@@ -11,7 +11,7 @@ type ReaderOptionKey = (string | {
  */
 type ReaderOptionParsing = {
     consumeShortGroup: boolean;
-    consumeNextArg: (inlined: string | null, separated: Array<string>, next: string | undefined) => boolean;
+    consumeNextArg: (inlined: string | null, separated: Array<string>, nextArg: string | undefined) => boolean;
 };
 /**
  * Result of parsing an option, including its inlined value and any following separated values.
@@ -105,17 +105,17 @@ declare class ReaderArgs {
 
 /**
  * Decodes a raw CLI string into a typed value.
- * A pair of a human-readable `content` name (e.g. `"Number"`) and a `decoder` function.
+ * A pair of a human-readable `content` name and a `decoder` function.
  *
- * Built-in: {@link typeString}, {@link typeBoolean}, {@link typeNumber},
- * {@link typeInteger}, {@link typeDate}, {@link typeUrl}.
- * Composite: {@link typeOneOf}, {@link typeMapped}, {@link typeTuple}, {@link typeList}.
+ * Built-in: {@link type}, {@link typeBoolean}, {@link typeNumber},
+ * {@link typeInteger}, {@link typeDatetime}, {@link typeUrl}.
+ * Composite: {@link typeChoice}, {@link typeConverted}, {@link typeTuple}, {@link typeList}.
  *
  * @typeParam Value - Type produced by the decoder.
  */
 type Type<Value> = {
     /**
-     * Human-readable name shown in help and errors (e.g. `"String"`, `"Number"`).
+     * Human-readable name shown in help and errors (e.g. `"name"`, `"number"`).
      */
     content: string;
     /**
@@ -133,71 +133,73 @@ type Type<Value> = {
  *
  * @example
  * ```ts
- * typeBoolean.decoder("true")  // → true
- * typeBoolean.decoder("yes")   // → true
- * typeBoolean.decoder("y")     // → true
- * typeBoolean.decoder("false") // → false
- * typeBoolean.decoder("no")    // → false
- * typeBoolean.decoder("n")     // → false
+ * typeBoolean("flag").decoder("true")  // → true
+ * typeBoolean("flag").decoder("yes")   // → true
+ * typeBoolean("flag").decoder("y")     // → true
+ * typeBoolean("flag").decoder("false") // → false
+ * typeBoolean("flag").decoder("no")    // → false
+ * typeBoolean("flag").decoder("n")     // → false
  * ```
  */
-declare const typeBoolean: Type<boolean>;
+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.
  *
  * @example
  * ```ts
- * typeDate.decoder("2024-01-15") // → Date object for 2024-01-15
- * typeDate.decoder("2024-01-15T13:45:30Z") // → Date object for 2024-01-15 13:45:30 UTC
- * typeDate.decoder("not a date") // throws TypoError
+ * typeDatetime("my-datetime").decoder("2024-01-15") // → Date object for 2024-01-15
+ * typeDatetime("my-datetime").decoder("2024-01-15T13:45:30Z") // → Date object for 2024-01-15 13:45:30 UTC
+ * typeDatetime("my-datetime").decoder("not a date") // throws TypoError
  * ```
  */
-declare const typeDate: Type<Date>;
+declare function typeDatetime(name?: string): Type<Date>;
 /**
  * Parses a string to `number` via `Number()`; `NaN` throws {@link TypoError}.
  *
  * @example
  * ```ts
- * typeNumber.decoder("3.14")  // → 3.14
- * typeNumber.decoder("-1")    // → -1
- * typeNumber.decoder("hello") // throws TypoError
+ * typeNumber("my-number").decoder("3.14")  // → 3.14
+ * typeNumber("my-number").decoder("-1")    // → -1
+ * typeNumber("my-number").decoder("hello") // throws
  * ```
  */
-declare const typeNumber: Type<number>;
+declare function typeNumber(name?: string): Type<number>;
 /**
  * Parses an integer string to `bigint` via `BigInt()`.
  * Floats and non-numeric strings throw {@link TypoError}.
  *
  * @example
  * ```ts
- * typeInteger.decoder("42")   // → 42n
- * typeInteger.decoder("3.14") // throws TypoError
- * typeInteger.decoder("abc")  // throws TypoError
+ * typeInteger("my-integer").decoder("42")   // → 42n
+ * typeInteger("my-integer").decoder("3.14") // throws
+ * typeInteger("my-integer").decoder("abc")  // throws
  * ```
  */
-declare const typeInteger: Type<bigint>;
+declare function typeInteger(name?: string): Type<bigint>;
 /**
  * Parses an absolute URL string to a `URL` object.
  * Relative or malformed URLs throw {@link TypoError}.
  *
  * @example
  * ```ts
- * typeUrl.decoder("https://example.com") // → URL { href: "https://example.com/", ... }
- * typeUrl.decoder("not-a-url")           // throws TypoError
+ * typeUrl("my-url").decoder("https://example.com") // → URL { href: "https://example.com/", ... }
+ * typeUrl("my-url").decoder("not-a-url")           // throws
  * ```
  */
-declare const typeUrl: Type<URL>;
+declare function typeUrl(name?: string): Type<URL>;
 /**
- * Identity decoder — passes the raw string through unchanged.
- *
+ * A named type that accepts any string as input.
+ * @param name - Name shown in help and errors (e.g. `"my-value"`).
  * @example
  * ```ts
- * typeString.decoder("hello") // → "hello"
- * typeString.decoder("")      // → ""
+ * type("greeting").decoder("hello") // → "hello"
+ * type("greeting").decoder("")      // → ""
  * ```
  */
-declare const typeString: Type<string>;
+declare function type(name?: string): Type<string>;
 /**
  * Chains `before`'s decoder with an `after` transformation.
  * `before` errors are prefixed with `"from: <content>"` for traceability.
@@ -205,45 +207,54 @@ declare const typeString: Type<string>;
  * @typeParam Before - Intermediate type from `before.decoder`.
  * @typeParam After - Final type from `after.decoder`.
  *
- * @param before - Base decoder for the raw string.
- * @param after - Transformation applied to the decoded value.
- * @param after.content - Name for the resulting type (shown in errors).
- * @param after.decoder - Converts a `Before` value to `After`.
+ * @param name - Name shown in help and errors (e.g. `"my-value"`).
+ * @param before - Base type to decode the raw string.
+ * @param mapper - Transforms `before`'s output to the final value; errors are wrapped with context.
  * @returns A {@link Type}`<After>`.
  *
  * @example
  * ```ts
- * const typePort = typeMapped(typeNumber, {
- *   content: "Port",
- *   decoder: (n) => {
- *     if (n < 1 || n > 65535) throw new Error("Out of range");
- *     return n;
- *   },
+ * const typePort = typeConverted("port", typeNumber(), (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 typeMapped<Before, After>(before: Type<Before>, after: {
-    content: string;
-    decoder: (value: Before) => After;
-}): Type<After>;
+declare function typeConverted<Before, After>(name: string, before: Type<Before>, mapper: (value: Before) => After): Type<After>;
+/**
+ * Adds a name to a {@link Type} for clearer error messages and help text.
+ *
+ * @param name - Name to use for the type.
+ * @param type - Base type to name.
+ * @returns A {@link Type} with the given name.
+ */
+declare function typeRenamed<Value>(type: Type<Value>, name: string): Type<Value>;
+/**
+ * Creates a {@link Type} for filesystem paths with optional existence checks.
+ * @param checks - Optional checks for path existence and type (file/directory).
+ * @returns A {@link Type}`<string>` representing the path.
+ */
+declare function typePath(name?: string, checks?: {
+    checkSyncExistAs?: "file" | "directory" | "anything";
+}): 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 content - Name shown in help and errors (e.g. `"Environment"`).
+ * @param name - Name shown in help and errors.
  * @param values - Ordered list of accepted values.
  * @returns A {@link Type}`<string>`.
  *
  * @example
  * ```ts
- * const typeEnv = typeOneOf("Environment", ["dev", "staging", "prod"]);
+ * 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")
  * ```
  */
-declare function typeOneOf<const Value extends string>(content: string, values: Array<Value>): Type<Value>;
+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}.
@@ -256,7 +267,7 @@ declare function typeOneOf<const Value extends string>(content: string, values:
  *
  * @example
  * ```ts
- * const typePoint = typeTuple([typeNumber, typeNumber]);
+ * 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"
@@ -282,7 +293,7 @@ declare function typeTuple<const Elements extends Array<any>>(elementTypes: {
  * 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, ":");
+ * const typePaths = typeList(typePath(), ":");
  * typePaths.decoder("/usr/bin:/usr/local/bin") // → ["/usr/bin", "/usr/local/bin"]
  * ```
  */
@@ -298,6 +309,10 @@ type TypoColor = "darkBlack" | "darkRed" | "darkGreen" | "darkYellow" | "darkBlu
  * All fields are optional; ignored entirely in `"none"` mode.
  */
 type TypoStyle = {
+    /**
+     * Letter case.
+     */
+    case?: "upper" | "lower";
     /**
      * Foreground (text) color.
      */
@@ -428,7 +443,7 @@ declare class TypoGrid {
      * Renders as an array of styled, column-padded strings.
      *
      * @param typoSupport - Rendering mode.
-     * @returns 2-D array of styled strings.
+     * @returns Array of styled strings.
      */
     computeStyledLines(typoSupport: TypoSupport): Array<string>;
 }
@@ -477,16 +492,12 @@ declare class TypoSupport {
     static tty(): TypoSupport;
     /**
      * Deterministic textual styling for snapshot tests.
-     * Style flags appear as suffixes: `{text}@color`, `{text}+` (bold), `{text}-` (dim),
-     * `{text}*` (italic), `{text}_` (underline), `{text}~` (strikethrough).
      */
     static mock(): TypoSupport;
     /**
-     * Auto-detects styling mode from the process environment.
-     * `FORCE_COLOR=0` / `NO_COLOR` → none; `FORCE_COLOR` (truthy) / `isTTY` → tty; else → none.
-     * Falls back to none if `process` is unavailable.
+     * Auto-detects styling mode from the process environment on best-effort basis.
      */
-    static inferFromProcess(): TypoSupport;
+    static inferFromEnv(): TypoSupport;
     /**
      * Applies `typoStyle` to `value` according to the current mode.
      *
@@ -510,9 +521,12 @@ declare class TypoSupport {
 type UsageCommand = {
     /**
      * Segments of the usage line
-     * (e.g. `my-cli <POSITIONAL> subcommand <ANOTHER_POSITIONAL>`).
      */
-    segments: Array<UsageSegment>;
+    segments: Array<{
+        positional: string;
+    } | {
+        subcommand: string;
+    }>;
     /**
      * Command metadata.
      */
@@ -530,27 +544,6 @@ type UsageCommand = {
      */
     options: Array<UsageOption>;
 };
-/**
- * One segment of the usage line.
- */
-type UsageSegment = {
-    positional: string;
-} | {
-    subcommand: string;
-};
-/**
- * Usage metadata. Produced by {@link Operation.generateUsage}, consumed when building {@link UsageCommand}.
- */
-type UsageOperation = {
-    /**
-     * Registered options.
-     */
-    options: Array<UsageOption>;
-    /**
-     * Declared positionals, in order.
-     */
-    positionals: Array<UsagePositional>;
-};
 /**
  * Positional metadata for the `Positionals:` section of help.
  */
@@ -558,16 +551,15 @@ type UsagePositional = {
     /**
      * Help text.
      */
-    description: string | undefined;
+    description?: string | undefined;
     /**
      * Short note shown in parentheses.
      */
-    hint: string | undefined;
+    hint?: string | undefined;
     /**
      * Placeholder label shown in the usage line and the `Positionals:` section.
-     * Required: `<NAME>`, optional: `[NAME]`, variadic: `[NAME]...`.
      */
-    label: Uppercase<string>;
+    label: string;
 };
 /**
  * Entry in the `Subcommands:` section.
@@ -580,11 +572,11 @@ type UsageSubcommand = {
     /**
      * From {@link CommandInformation.description}.
      */
-    description: string | undefined;
+    description?: string | undefined;
     /**
      * From {@link CommandInformation.hint}.
      */
-    hint: string | undefined;
+    hint?: string | undefined;
 };
 /**
  * Option metadata for the `Options:` section of help.
@@ -593,27 +585,27 @@ type UsageOption = {
     /**
      * Short-form name without `-` (e.g. `"v"`).
      */
-    short: string | undefined;
+    short?: string | undefined;
     /**
      * Long-form name without `--` (e.g. `"verbose"`).
      */
-    long: Lowercase<string>;
+    long: string;
     /**
-     * Extra annotation appended to the option label in help (e.g. `[=no]`, ` [*]`).
+     * Value placeholder in help (e.g. `"<FILE>"`).
      */
-    annotation: string | undefined;
+    label?: string | undefined;
     /**
-     * Help text.
+     * Extra annotation appended to the option label in help.
      */
-    description: string | undefined;
+    annotation?: string | undefined;
     /**
-     * Short note shown in parentheses.
+     * Help text.
      */
-    hint: string | undefined;
+    description?: string | undefined;
     /**
-     * Value placeholder in help (e.g. `"<FILE>"`). `undefined` for flags.
+     * Short note shown in parentheses.
      */
-    label: Uppercase<string> | undefined;
+    hint?: string | undefined;
 };
 /**
  * Converts a {@link UsageCommand} model into an array of styled lines ready to be
@@ -627,16 +619,16 @@ type UsageOption = {
  * <detail lines...>
  *
  * Positionals:
- *   <LABEL>  <description> (<hint>)
+ *   <label>  <description> (<hint>)
  *
  * Subcommands:
  *   <name>  <description> (<hint>)
  *
  * Options:
- *   -s, --long <LABEL><annotation>  <description> (<hint>)
+ *   -s, --long <label><annotation>  <description> (<hint>)
  *
  * Examples:
- *   <description>
+ *   <explanation>
  *   <command line>
  *
  * ```
@@ -660,7 +652,7 @@ type UsageOption = {
  * ```
  */
 declare function usageToStyledLines(params: {
-    cliName: Lowercase<string>;
+    cliName: string;
     usage: UsageCommand;
     typoSupport: TypoSupport;
 }): string[];
@@ -697,15 +689,15 @@ type OptionDecoder<Value> = {
 /**
  * Creates a boolean flag option (`--verbose`, optionally `--flag=no`).
  *
- * Parsing: absent → `false`; `--flag` / `--flag=yes` → `true`; `--flag=no` → `false`;
- * specified more than once → {@link TypoError}.
+ * Parsing: absent → default value; `--flag` / `--flag=yes` → `true`; `--flag=no` → `false`;
+ * specified more than once → throws {@link TypoError}.
  *
  * @param definition.long - Long-form name (without `--`).
  * @param definition.short - Short-form name (without `-`).
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
  * @param definition.aliases - Additional names.
- * @param definition.default - Default when absent. Defaults to `false`.
+ * @param definition.default - Default value when absent.
  * @returns An {@link Option}`<boolean>`.
  *
  * @example
@@ -715,15 +707,20 @@ 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: {
-    long: Lowercase<string>;
+    long: string;
     short?: string;
     description?: string;
     hint?: string;
     aliases?: {
-        longs?: Array<Lowercase<string>>;
+        longs?: Array<string>;
         shorts?: Array<string>;
     };
     default?: boolean;
@@ -731,7 +728,7 @@ declare function optionFlag(definition: {
 /**
  * Creates an option that accepts exactly one value (e.g. `--output dist/`).
  *
- * Parsing: absent → `default()`; once → decoded with `type`; more than once → {@link TypoError}.
+ * Parsing: absent → `defaultValue()`; once → decoded with `type`; more than once → {@link TypoError}.
  * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
  *
  * @typeParam Value - Type produced by the decoder.
@@ -741,9 +738,9 @@ declare function optionFlag(definition: {
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
  * @param definition.aliases - Additional names.
- * @param definition.label - Value placeholder in help. Defaults to uppercased `type.content`.
  * @param definition.type - Decoder for the raw string value.
- * @param definition.default - Default when absent. Throw to make the option required.
+ * @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`).
  * @returns An {@link Option}`<Value>`.
  *
  * @example
@@ -751,25 +748,28 @@ declare function optionFlag(definition: {
  * const outputOption = optionSingleValue({
  *   long: "output",
  *   short: "o",
- *   type: typeString,
- *   label: "PATH",
+ *   type: typePath(),
  *   description: "Output directory",
- *   default: () => "dist/",
+ *   valueWhenNotDefined: () => "dist",
  * });
+ * // Usage:
+ * //   my-cli  →  "dist"
+ * //   my-cli --output folder  →  "folder"
+ * //   my-cli -o folder  →  "folder"
  * ```
  */
 declare function optionSingleValue<Value>(definition: {
-    long: Lowercase<string>;
+    long: string;
     short?: string;
     description?: string;
     hint?: string;
     aliases?: {
-        longs?: Array<Lowercase<string>>;
+        longs?: Array<string>;
         shorts?: Array<string>;
     };
-    label?: Uppercase<string>;
     type: Type<Value>;
-    default: () => Value;
+    defaultWhenNotDefined: () => Value;
+    defaultWhenNotInlined?: () => Value;
 }): Option<Value>;
 /**
  * Creates an option that collects every occurrence into an array (e.g. `--file a.ts --file b.ts`).
@@ -784,7 +784,6 @@ declare function optionSingleValue<Value>(definition: {
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
  * @param definition.aliases - Additional names.
- * @param definition.label - Value placeholder in help. Defaults to uppercased `type.content`.
  * @param definition.type - Decoder applied to each raw string value.
  * @returns An {@link Option}`<Array<Value>>`.
  *
@@ -801,15 +800,14 @@ declare function optionSingleValue<Value>(definition: {
  * ```
  */
 declare function optionRepeatable<Value>(definition: {
-    long: Lowercase<string>;
+    long: string;
     short?: string;
     description?: string;
     hint?: string;
     aliases?: {
-        longs?: Array<Lowercase<string>>;
+        longs?: Array<string>;
         shorts?: Array<string>;
     };
-    label?: Uppercase<string>;
     type: Type<Value>;
 }): Option<Array<Value>>;
 
@@ -845,41 +843,36 @@ type PositionalDecoder<Value> = {
 };
 /**
  * Creates a required positional — missing token throws {@link TypoError}.
- * Label defaults to uppercased `type.content` in angle brackets (e.g. `<STRING>`).
  *
  * @typeParam Value - Type produced by the decoder.
  *
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
- * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
  * @param definition.type - Decoder for the raw token.
  * @returns A {@link Positional}`<Value>`.
  *
  * @example
  * ```ts
  * const namePositional = positionalRequired({
- *   type: typeString,
- *   label: "NAME",
+ *   type: type("name"),
  *   description: "The name to greet",
  * });
- * // Parses: my-cli Alice  →  "Alice"
+ * // Usage:
+ * //   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 — absent token falls back to `default()`.
- * Label defaults to uppercased `type.content` in square brackets (e.g. `[STRING]`).
  *
  * @typeParam Value - Type produced by the decoder (or the default).
  *
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
- * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
  * @param definition.type - Decoder for the raw token.
  * @param definition.default - Value when absent. Throw to make it required.
  * @returns A {@link Positional}`<Value>`.
@@ -887,51 +880,48 @@ declare function positionalRequired<Value>(definition: {
  * @example
  * ```ts
  * const greeteePositional = positionalOptional({
- *   type: typeString,
- *   label: "NAME",
+ *   type: type("name"),
  *   description: "Name to greet (default: world)",
  *   default: () => "world",
  * });
- * // my-cli         →  "world"
- * // my-cli Alice   →  "Alice"
+ * // Usage:
+ * //   my-cli  →  "world"
+ * //   my-cli Alice  →  "Alice"
  * ```
  */
 declare function positionalOptional<Value>(definition: {
     description?: string;
     hint?: string;
-    label?: Uppercase<string>;
     type: Type<Value>;
     default: () => Value;
 }): Positional<Value>;
 /**
  * Creates a variadic positional that collects zero or more remaining tokens into an array.
- * Stops at `endDelimiter` (consumed, not included). Label: `[TYPE]...` notation.
+ * Optionally stops at `endDelimiter` (consumed, not included).
  *
  * @typeParam Value - Type produced by the decoder for each token.
  *
  * @param definition.endDelimiter - Sentinel token that stops collection (consumed, not included).
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
- * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
  * @param definition.type - Decoder applied to each token.
  * @returns A {@link Positional}`<Array<Value>>`.
  *
  * @example
  * ```ts
  * const filesPositional = positionalVariadics({
- *   type: typeString,
- *   label: "FILE",
+ *   type: typePath(),
  *   description: "Files to process",
  * });
- * // my-cli a.ts b.ts c.ts  →  ["a.ts", "b.ts", "c.ts"]
- * // my-cli                  →  []
+ * // Usage:
+ * //   my-cli  →  []
+ * //   my-cli a.ts b.ts c.ts  →  ["a.ts", "b.ts", "c.ts"]
  * ```
  */
 declare function positionalVariadics<Value>(definition: {
     endDelimiter?: string;
     description?: string;
     hint?: string;
-    label?: Uppercase<string>;
     type: Type<Value>;
 }): Positional<Array<Value>>;
 
@@ -948,7 +938,16 @@ type Operation<Context, Result> = {
     /**
      * Returns usage metadata without consuming any arguments.
      */
-    generateUsage(): UsageOperation;
+    generateUsage(): {
+        /**
+         * Registered options.
+         */
+        options: Array<UsageOption>;
+        /**
+         * Declared positionals, in order.
+         */
+        positionals: Array<UsagePositional>;
+    };
     /**
      * Consumes args from `readerArgs` and returns an {@link OperationDecoder}.
      */
@@ -1001,10 +1000,10 @@ type OperationInterpreter<Context, Result> = {
  * const greetOperation = operation(
  *   {
  *     options: {
- *       loud: optionFlag({ long: "loud", description: "Print in uppercase" }),
+ *       loud: optionFlag({ long: "loud", description: "Print in uppercase", default: false }),
  *     },
  *     positionals: [
- *       positionalRequired({ type: typeString, label: "NAME", description: "Name to greet" }),
+ *       positionalRequired({ type: type("name"), description: "Name to greet" }),
  *     ],
  *   },
  *   async function (_ctx, { options: { loud }, positionals: [name] }) {
@@ -1108,10 +1107,12 @@ type CommandInformation = {
         } | {
             option: {
                 long: string;
-                value?: string;
+                inlined?: string;
+                separated?: Array<string>;
             } | {
                 short: string;
-                value?: string;
+                inlined?: string;
+                separated?: Array<string>;
             };
         }>;
     }>;
@@ -1131,7 +1132,7 @@ type CommandInformation = {
  * const greet = command(
  *   { description: "Greet a user" },
  *   operation(
- *     { options: {}, positionals: [positionalRequired({ type: typeString, label: "NAME" })] },
+ *     { options: {}, positionals: [positionalRequired({ type: type("name") })] },
  *     async (_ctx, { positionals: [name] }) => console.log(`Hello, ${name}!`),
  *   ),
  * );
@@ -1163,7 +1164,7 @@ declare function command<Context, Result>(information: CommandInformation, opera
  * ```
  */
 declare function commandWithSubcommands<Context, Payload, Result>(information: CommandInformation, operation: Operation<Context, Payload>, subcommands: {
-    [subcommand: Lowercase<string>]: Command<Payload, Result>;
+    [subcommand: string]: Command<Payload, Result>;
 }): Command<Context, Result>;
 /**
  * Chains an {@link Operation} and a {@link Command}: `operation` runs first, its
@@ -1177,21 +1178,13 @@ declare function commandWithSubcommands<Context, Payload, Result>(information: C
  * @param operation - Runs first; output becomes `subcommand`'s context.
  * @param subcommand - Runs after `operation`.
  * @returns A {@link Command} composing both 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: Operation<Context, Payload>, subcommand: Command<Payload, Result>): Command<Context, Result>;
 
+/**
+ * Color selection modes availables
+ */
+type RunColorMode = "env" | "always" | "never" | "mock";
 /**
  * Main entry point: parses CLI arguments, executes the matched command, and exits.
  * Handles `--help`, `--version`, usage-on-error, and exit codes.
@@ -1206,8 +1199,7 @@ declare function commandChained<Context, Payload, Result>(information: CommandIn
  * @param cliArgs - Raw arguments, typically `process.argv.slice(2)`.
  * @param context - Forwarded to the handler.
  * @param command - Root {@link Command}.
- * @param options.useTtyColors - Color mode: `true` (always), `false` (never),
- *   `"mock"` (snapshot-friendly), `undefined` (auto-detect from env).
+ * @param options.colorSetup - Configures color support; enables `--color` flag if set to `"flag"`.
  * @param options.usageOnHelp - Enables `--help` flag (default `true`).
  * @param options.usageOnError - Prints usage to stderr on parse error (default `true`).
  * @param options.buildVersion - Enables `--version`; prints `<cliName> <buildVersion>`.
@@ -1218,12 +1210,12 @@ declare function commandChained<Context, Payload, Result>(information: CommandIn
  *
  * @example
  * ```ts
- * import { runAndExit, command, operation, positionalRequired, typeString } from "cli-kiss";
+ * import { runAndExit, command, operation, positionalRequired, type } from "cli-kiss";
  *
  * const greetCommand = command(
  *   { description: "Greet someone" },
  *   operation(
- *     { options: {}, positionals: [positionalRequired({ type: typeString, label: "NAME" })] },
+ *     { options: {}, positionals: [positionalRequired({ type: type("name") })] },
  *     async function (_ctx, { positionals: [name] }) {
  *       console.log(`Hello, ${name}!`);
  *     },
@@ -1235,8 +1227,8 @@ declare function commandChained<Context, Payload, Result>(information: CommandIn
  * });
  * ```
  */
-declare function runAndExit<Context>(cliName: Lowercase<string>, cliArgs: ReadonlyArray<string>, context: Context, command: Command<Context, void>, options?: {
-    useTtyColors?: boolean | undefined | "mock";
+declare function runAndExit<Context>(cliName: string, cliArgs: ReadonlyArray<string>, context: Context, command: Command<Context, void>, options?: {
+    colorSetup?: "flag" | RunColorMode | undefined;
     usageOnHelp?: boolean | undefined;
     usageOnError?: boolean | undefined;
     buildVersion?: string | undefined;
@@ -1244,4 +1236,4 @@ declare function runAndExit<Context>(cliName: Lowercase<string>, cliArgs: Readon
     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 Type, type TypoColor, TypoError, TypoGrid, TypoString, type TypoStyle, TypoSupport, TypoText, type UsageCommand, type UsageOperation, type UsageOption, type UsagePositional, type UsageSegment, type UsageSubcommand, command, commandChained, commandWithSubcommands, operation, optionFlag, optionRepeatable, optionSingleValue, positionalOptional, positionalRequired, positionalVariadics, runAndExit, typeBoolean, typeDate, typeInteger, typeList, typeMapped, typeNumber, typeOneOf, typeString, typeTuple, typeUrl, typoStyleConstants, typoStyleFailure, typoStyleLogic, typoStyleQuote, typoStyleRegularStrong, typoStyleRegularWeaker, typoStyleTitle, typoStyleUserInput, usageToStyledLines };
+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 };