cli-kiss 0.2.3 → 0.2.4

package/docs/.vitepress/config.mts

@@ -14,9 +14,7 @@ export default defineConfig({
     ],
   ],
   themeConfig: {
-    search: {
-      provider: "local",
-    },
+    search: { provider: "local", options: { detailedView: true } },
     nav: [
       { text: "Guide", link: "/guide/01_getting_started" },
       { text: "npm", link: "https://www.npmjs.com/package/cli-kiss" },

package/docs/.vitepress/theme/index.ts

@@ -0,0 +1,4 @@
+import DefaultTheme from "vitepress/theme";
+import "./style.css";
+
+export default DefaultTheme;

package/docs/.vitepress/theme/style.css

@@ -0,0 +1,4 @@
+:root {
+  --vp-home-hero-image-background-image: linear-gradient( -50deg, #ff003cff 0%, #00000000 50%, #459900ff 100% );
+  --vp-home-hero-image-filter: blur(150px);
+}

package/docs/guide/02_commands.md

@@ -16,37 +16,13 @@ const greet = command(
       options: {},
       positionals: [positionalRequired({ type: typeString, label: "NAME" })],
     },
-    async (_ctx, { positionals: [name] }) => {
+    async function (_ctx, { positionals: [name] }) {
       console.log(`Hello, ${name}!`);
     },
   ),
 );
 ```
 
-### `CommandInformation`
-
-Every command accepts a metadata object:
-
-| Field         | Type        | Description                                       |
-| ------------- | ----------- | ------------------------------------------------- |
-| `description` | `string`    | Short description shown in help output            |
-| `hint`        | `string?`   | Note shown in parentheses next to the description |
-| `details`     | `string[]?` | Extra lines printed below the description         |
-
-```ts
-command(
-  {
-    description: "Deploy the application",
-    hint: "experimental",
-    details: [
-      "Pushes to the configured remote.",
-      "Runs migrations after push.",
-    ],
-  },
-  deployOperation,
-);
-```
-
 ## `commandWithSubcommands` — dispatch to a subcommand
 
 User must pick one of several sub-actions.
@@ -63,19 +39,19 @@ const rootCmd = commandWithSubcommands(
   { description: "My deployment CLI" },
   // This operation runs before the subcommand is selected.
   // Its return value becomes the subcommand's context.
-  operation({ options: {}, positionals: [] }, async (_ctx) => ({
-    db: "postgres://localhost/mydb",
-  })),
+  operation({ options: {}, positionals: [] }, async function (_ctx) {
+    return { db: "postgres://localhost/mydb" };
+  }),
   {
     deploy: command(
       { description: "Deploy the latest build" },
-      operation({ options: {}, positionals: [] }, async (ctx) => {
+      operation({ options: {}, positionals: [] }, async function (ctx) {
         console.log(`Deploying with DB: ${ctx.db}`);
       }),
     ),
     rollback: command(
       { description: "Rollback to the previous release" },
-      operation({ options: {}, positionals: [] }, async (ctx) => {
+      operation({ options: {}, positionals: [] }, async function (ctx) {
         console.log(`Rolling back, DB: ${ctx.db}`);
       }),
     ),
@@ -128,7 +104,7 @@ const authenticatedDeploy = commandChained(
           long: "token",
           type: typeString,
           description: "API token",
-          default: () => {
+          default: function () {
             const t = process.env.API_TOKEN;
             if (!t) throw new Error("API_TOKEN env var is required");
             return t;
@@ -150,3 +126,63 @@ const authenticatedDeploy = commandChained(
 ```
 
 All stages share a single flat usage — users see one combined command.
+
+## `CommandInformation`
+
+Every command accepts a metadata object:
+
+| Field         | Type         | Description                                       |
+| ------------- | ------------ | ------------------------------------------------- |
+| `description` | `string`     | Short description shown in help output            |
+| `hint`        | `string?`    | Note shown in parentheses next to the description |
+| `details`     | `string[]?`  | Extra lines printed below the description         |
+| `examples`    | `Example[]?` | Usage examples shown in the `Examples:` section   |
+
+Each `Example` entry has:
+
+| Field         | Type           | Description                                             |
+| ------------- | -------------- | ------------------------------------------------------- |
+| `explanation` | `string`       | Comment line shown above the example command            |
+| `commandArgs` | `CommandArg[]` | Ordered list of arguments to render on the command line |
+
+Each `CommandArg` is one of:
+
+| Shape                                           | Renders as       |
+| ----------------------------------------------- | ---------------- |
+| `string`                                        | literal text     |
+| `{ positional: string }`                        | positional label |
+| `{ subcommand: string }`                        | subcommand name  |
+| `{ option: { long: string; value?: string } }`  | `--long[=value]` |
+| `{ option: { short: string; value?: string } }` | `-s[=value]`     |
+
+```ts
+command(
+  {
+    description: "Deploy the application",
+    hint: "experimental",
+    details: [
+      "Pushes to the configured remote.",
+      "Runs migrations after push.",
+    ],
+    examples: [
+      {
+        explanation: "Deploy with a specific tag",
+        commandArgs: [
+          { positional: "v1.2.3" },
+          { option: { long: "dry-run" } },
+        ],
+      },
+    ],
+  },
+  deployOperation,
+);
+```
+
+The `Examples:` section in `--help` output renders each entry as a comment
+followed by the reconstructed command line:
+
+```text
+Examples:
+ # Deploy with a specific tag
+ deploy v1.2.3 --dry-run
+```

package/docs/guide/03_options.md

@@ -1,10 +1,11 @@
 # Options
 
-Named `--` arguments (or `-` for short forms). Declared in the `options` map of [`operation`](/guide/02_commands).
+Named `--` arguments (or `-` for short forms). Declared in the `options` map of
+[`operation`](/guide/02_commands).
 
 ## `optionFlag` — boolean toggle
 
-Present or absent. Also accepts `--flag=yes` / `--flag=no`.
+Present or absent. Also accepts `--flag=true` / `--flag=no` / `--no-flag`.
 
 ```ts
 import { optionFlag } from "cli-kiss";
@@ -20,14 +21,14 @@ const verbose = optionFlag({
 // (absent)        →  false
 ```
 
-| Parameter     | Type                  | Description                                  |
-| ------------- | --------------------- | -------------------------------------------- |
-| `long`        | `Lowercase<string>`   | Long flag name (without `--`)                |
-| `short`       | `string?`             | Short flag name (without `-`)                |
-| `description` | `string?`             | Help text                                    |
-| `hint`        | `string?`             | Short note in parentheses                    |
-| `default`     | `() => boolean`       | Default when absent (default: `() => false`) |
-| `aliases`     | `{ longs?, shorts? }` | Additional names for the flag                |
+| Parameter     | Type                  | Description                          |
+| ------------- | --------------------- | ------------------------------------ |
+| `long`        | `Lowercase<string>`   | Long flag name (without `--`)        |
+| `short`       | `string?`             | Short flag name (without `-`)        |
+| `description` | `string?`             | Help text                            |
+| `hint`        | `string?`             | Short note in parentheses            |
+| `default`     | `boolean? `           | Value when absent (default: `false`) |
+| `aliases`     | `{ longs?, shorts? }` | Additional names for the flag        |
 
 ::: tip A flag specified more than once triggers a parse error. Use
 [`optionRepeatable`](#optionrepeatable-collect-multiple-values) if you need

package/docs/guide/05_types.md

@@ -7,7 +7,7 @@ A `Type<Value>` converts a raw CLI string into a typed value: a `content` label
 | Export        | TypeScript type | Accepts                                                    |
 | ------------- | --------------- | ---------------------------------------------------------- |
 | `typeString`  | `string`        | Any string                                                 |
-| `typeBoolean` | `boolean`       | `true`, `yes`, `false`, `no` (case-insensitive)            |
+| `typeBoolean` | `boolean`       | `true/yes/on/1/y/t` → true, `false/no/off/0/n/f` → false (case-insensitive) |
 | `typeNumber`  | `number`        | Integers, floats, scientific notation                      |
 | `typeInteger` | `bigint`        | Integer strings only                                       |
 | `typeDate`    | `Date`          | Any format accepted by `Date.parse` (ISO 8601 recommended) |

package/docs/guide/06_run.md

@@ -24,7 +24,7 @@ await runAndExit(cliName, cliArgs, context, command, options?);
 | `usageOnHelp`  | `boolean?`                 | `true`         | Enables `--help` flag                                       |
 | `usageOnError` | `boolean?`                 | `true`         | Prints usage to stderr when parsing fails                   |
 | `useTtyColors` | `boolean \| "mock"?`       | auto           | Controls ANSI color output                                  |
-| `onError`      | `(error: unknown) => void` | —              | Custom handler for execution errors                         |
+| `onError`      | `(error: unknown) => void` | —              | Custom handler for parse and execution errors               |
 | `onExit`       | `(code: number) => never`  | `process.exit` | Override for testing                                        |
 
 ### Exit codes

package/docs/index.md

@@ -4,10 +4,12 @@ layout: home
 hero:
   name: CLI-kiss
   text: CLI for TypeScript.
+
   tagline:
-    No bloat, no dependencies.<br/>Standard behavior users expect.<br/><span>K</span>eep
-    <span>I</span>t <span>S</span>imple and <span>S</span>tupid, it just does the
-    job.
+    No bloat, no dependencies.<br/>Standard behavior users expect.<br/>Keep It Simple and Stupid, it just does the job.
+
+  image:
+    src: /hero.png
 
   actions:
     - theme: brand
@@ -19,12 +21,15 @@ hero:
 
 features:
   - title: Zero dependencies
+    icon: 📦
     details:
       Ships with no runtime dependencies.<br/>Pure TypeScript, 5kb bundled.
   - title: Fully typed
+    icon: 🧠
     details:
       TypeScript first.<br/>Options and positionals inputs strongly typed.
   - title: Composable
+    icon: 🧩
     details:
       Easily create nested subcommands.<br/>Build complex CLIs by nesting logic.
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli-kiss",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "devDependencies": {

package/src/lib/Command.ts

@@ -1,6 +1,4 @@
 import { Operation } from "./Operation";
-import { OptionUsage } from "./Option";
-import { PositionalUsage } from "./Positional";
 import { ReaderArgs } from "./Reader";
 import {
   TypoError,
@@ -9,22 +7,21 @@ import {
   typoStyleUserInput,
   TypoText,
 } from "./Typo";
+import { UsageCommand, UsageSegment } from "./Usage";
 
 /**
- * A CLI command — parses arguments and executes within a given context.
- * Created with {@link command}, {@link commandWithSubcommands}, or {@link commandChained}.
- * Usually passed through {@link runAndExit} to run.
+ * A CLI command. Created with {@link command}, {@link commandWithSubcommands}, or {@link commandChained}.
  *
- * @typeParam Context - Injected at execution time; forwarded to handlers. Use to inject dependencies.
- * @typeParam Result - Value produced on execution; typically `void` for leaf commands.
+ * @typeParam Context - Injected at execution; forwarded to handlers.
+ * @typeParam Result - Produced on execution; typically `void`.
  */
 export type Command<Context, Result> = {
   /**
-   * Returns the command's static metadata.
+   * Returns static metadata.
    */
   getInformation(): CommandInformation;
   /**
-   * Consumes args in a `readerArgs` and returns a {@link CommandDecoder}.
+   * Registers options/positionals on `readerArgs`; returns a {@link CommandDecoder}.
    */
   consumeAndMakeDecoder(
     readerArgs: ReaderArgs,
@@ -39,10 +36,9 @@ export type Command<Context, Result> = {
  */
 export type CommandDecoder<Context, Result> = {
   /**
-   * Builds the {@link CommandUsage} for the current command path.
-   * Used for `--help` and `usageOnError`.
+   * Returns {@link UsageCommand} for the current command path.
    */
-  generateUsage(): CommandUsage;
+  generateUsage(): UsageCommand;
   /**
    * Creates a ready-to-execute {@link CommandInterpreter}.
    *
@@ -54,7 +50,7 @@ export type CommandDecoder<Context, Result> = {
 /**
  * A fully parsed, decoded and ready-to-execute command.
  *
- * @typeParam Context - Caller-supplied context.
+ * @typeParam Context - Context passed to the handler.
  * @typeParam Result - Value produced on success.
  */
 export type CommandInterpreter<Context, Result> = {
@@ -65,15 +61,15 @@ export type CommandInterpreter<Context, Result> = {
 };
 
 /**
- * Static metadata for a command, shown in `--help` output via {@link usageToStyledLines}.
+ * Command metadata shown in `--help` output.
  */
 export type CommandInformation = {
   /**
-   * Short description shown in the usage header.
+   * Shown in the usage header.
    */
   description: string;
   /**
-   * Short note shown in parentheses (e.g. `"deprecated"`, `"experimental"`).
+   * Shown in parentheses, e.g. `"deprecated"`, `"experimental"`.
    */
   hint?: string;
   /**
@@ -81,7 +77,7 @@ export type CommandInformation = {
    */
   details?: Array<string>;
   /**
-   * Examples shown in the `Examples:` section of the usage output.
+   * Shown in the `Examples:` section.
    */
   examples?: Array<{
     /**
@@ -89,7 +85,7 @@ export type CommandInformation = {
      */
     explanation: string;
     /**
-     * Command line args to show as an example of usage.
+     * Example command args.
      */
     commandArgs: Array<
       | string
@@ -104,66 +100,14 @@ export type CommandInformation = {
   }>;
 };
 
-/**
- * Full usage/help model.
- * Produced by {@link CommandDecoder.generateUsage},
- * Consumed by {@link usageToStyledLines}.
- */
-export type CommandUsage = {
-  /**
-   * Segments forming the usage line
-   * (e.g. `my-cli <POSITIONAL> subcommand <ANOTHER_POSITIONAL>`).
-   */
-  segments: Array<CommandUsageSegment>;
-  /**
-   * Command's static metadata.
-   */
-  information: CommandInformation;
-  /**
-   * Positionals in declaration order.
-   */
-  positionals: Array<PositionalUsage>;
-  /**
-   * Available subcommands. Non-empty when subcommand was not specified.
-   */
-  subcommands: Array<CommandUsageSubcommand>;
-  /**
-   * Options in registration order.
-   */
-  options: Array<OptionUsage>;
-};
-
-/**
- * One element in the usage segment trail.
- */
-export type CommandUsageSegment = { positional: string } | { command: string };
-
-/**
- * Subcommand entry shown in the `Subcommands:` section of the usage output.
- */
-export type CommandUsageSubcommand = {
-  /**
-   * Literal token the user types (e.g. `"deploy"`).
-   */
-  name: string;
-  /**
-   * Short description from the subcommand's {@link CommandInformation}.
-   */
-  description: string | undefined;
-  /**
-   * Hint from the subcommand's {@link CommandInformation}.
-   */
-  hint: string | undefined;
-};
-
 /**
  * Creates a leaf command that directly executes an {@link Operation}.
  *
  * @typeParam Context - Context forwarded to the handler.
  * @typeParam Result - Value returned by the handler.
  *
- * @param information - Command metadata (description, hint, details).
- * @param operation - Defines: options, positionals, and the handler.
+ * @param information - Command metadata.
+ * @param operation - Options, positionals, and handler.
  * @returns A {@link Command}.
  *
  * @example
@@ -198,7 +142,7 @@ export function command<Context, Result>(
           );
         }
         return {
-          generateUsage: () => generateUsageShallow(information, operation),
+          generateUsage: () => generateUsageLeaf(information, operation),
           decodeAndMakeInterpreter() {
             const operationInterpreter =
               operationDecoder.decodeAndMakeInterpreter();
@@ -211,7 +155,7 @@ export function command<Context, Result>(
         };
       } catch (error) {
         return {
-          generateUsage: () => generateUsageShallow(information, operation),
+          generateUsage: () => generateUsageLeaf(information, operation),
           decodeAndMakeInterpreter() {
             throw error;
           },
@@ -222,17 +166,16 @@ export function command<Context, Result>(
 }
 
 /**
- * Creates a command that runs an {@link Operation} to produce a `Payload`,
- * then dispatches to a named subcommand based on the next positional token.
+ * Creates a command that runs `operation` first, then dispatches to a named subcommand.
  *
  * @typeParam Context - Context accepted by `operation`.
  * @typeParam Payload - Output of `operation`; becomes the subcommand's context.
  * @typeParam Result - Value produced by the selected subcommand.
  *
- * @param information - Command metadata (description, hint, details).
- * @param operation - Always runs first; its output becomes the subcommand's context.
+ * @param information - Command metadata.
+ * @param operation - Runs first; output becomes the subcommand's context.
  * @param subcommands - Map of subcommand names to their {@link Command}s.
- * @returns A {@link Command} that dispatches to one of the provided subcommands.
+ * @returns A dispatching {@link Command}.
  *
  * @example
  * ```ts
@@ -283,8 +226,8 @@ export function commandWithSubcommands<Context, Payload, Result>(
         return {
           generateUsage() {
             const subcommandUsage = subcommandDecoder.generateUsage();
-            const currentUsage = generateUsageShallow(information, operation);
-            currentUsage.segments.push(segmentCommand(subcommandName));
+            const currentUsage = generateUsageLeaf(information, operation);
+            currentUsage.segments.push(segmentSubcommand(subcommandName));
             currentUsage.segments.push(...subcommandUsage.segments);
             currentUsage.information = subcommandUsage.information;
             currentUsage.positionals.push(...subcommandUsage.positionals);
@@ -309,7 +252,7 @@ export function commandWithSubcommands<Context, Payload, Result>(
       } catch (error) {
         return {
           generateUsage() {
-            const currentUsage = generateUsageShallow(information, operation);
+            const currentUsage = generateUsageLeaf(information, operation);
             currentUsage.segments.push(segmentPositional("<SUBCOMMAND>"));
             for (const [name, subcommand] of Object.entries(subcommands)) {
               const { description, hint } = subcommand.getInformation();
@@ -334,10 +277,10 @@ export function commandWithSubcommands<Context, Payload, Result>(
  * @typeParam Payload - Output of `operation`; becomes `subcommand`'s context.
  * @typeParam Result - Value produced by `subcommand`.
  *
- * @param information - Command metadata (description, hint, details).
- * @param operation - First stage; its output is passed as `subcommand`'s context.
- * @param subcommand - Second stage, executed after `operation`.
- * @returns A {@link Command} transparently composing the two stages.
+ * @param information - Command metadata.
+ * @param operation - Runs first; output becomes `subcommand`'s context.
+ * @param subcommand - Runs after `operation`.
+ * @returns A {@link Command} composing both stages.
  *
  * @example
  * ```ts
@@ -367,7 +310,7 @@ export function commandChained<Context, Payload, Result>(
         return {
           generateUsage() {
             const subcommandUsage = subcommandDecoder.generateUsage();
-            const currentUsage = generateUsageShallow(information, operation);
+            const currentUsage = generateUsageLeaf(information, operation);
             currentUsage.segments.push(...subcommandUsage.segments);
             currentUsage.information = subcommandUsage.information;
             currentUsage.positionals.push(...subcommandUsage.positionals);
@@ -392,7 +335,7 @@ export function commandChained<Context, Payload, Result>(
       } catch (error) {
         return {
           generateUsage() {
-            const currentUsage = generateUsageShallow(information, operation);
+            const currentUsage = generateUsageLeaf(information, operation);
             currentUsage.segments.push(segmentPositional("[REST]..."));
             return currentUsage;
           },
@@ -405,18 +348,18 @@ export function commandChained<Context, Payload, Result>(
   };
 }
 
-function segmentPositional(value: string): CommandUsageSegment {
+function segmentPositional(value: string): UsageSegment {
   return { positional: value };
 }
 
-function segmentCommand(value: string): CommandUsageSegment {
-  return { command: value };
+function segmentSubcommand(value: string): UsageSegment {
+  return { subcommand: value };
 }
 
-function generateUsageShallow(
+function generateUsageLeaf(
   information: CommandInformation,
   operation: Operation<any, any>,
-): CommandUsage {
+): UsageCommand {
   const { positionals, options } = operation.generateUsage();
   return {
     segments: positionals.map((positional) =>

package/src/lib/Operation.ts

@@ -1,6 +1,7 @@
-import { Option, OptionDecoder, OptionUsage } from "./Option";
-import { Positional, PositionalDecoder, PositionalUsage } from "./Positional";
+import { Option, OptionDecoder } from "./Option";
+import { Positional, PositionalDecoder } from "./Positional";
 import { ReaderArgs } from "./Reader";
+import { UsageOperation, UsageOption, UsagePositional } from "./Usage";
 
 /**
  * Options, positionals, and an async handler that together form the logic of a CLI command.
@@ -8,14 +9,14 @@ import { ReaderArgs } from "./Reader";
  * Created with {@link operation} and passed to {@link command},
  * {@link commandWithSubcommands}, or {@link commandChained}.
  *
- * @typeParam Context - Injected at execution time; forwarded to handlers. Use to inject dependencies.
- * @typeParam Result - Value produced on execution; typically `void` for leaf commands.
+ * @typeParam Context - Injected at execution; forwarded to handlers.
+ * @typeParam Result - Value produced on execution; typically `void`.
  */
 export type Operation<Context, Result> = {
   /**
    * Returns usage metadata without consuming any arguments.
    */
-  generateUsage(): OperationUsage;
+  generateUsage(): UsageOperation;
   /**
    * Consumes args from `readerArgs` and returns an {@link OperationDecoder}.
    */
@@ -52,27 +53,10 @@ export type OperationInterpreter<Context, Result> = {
   executeWithContext(context: Context): Promise<Result>;
 };
 
-/**
- * Usage metadata produced by {@link Operation.generateUsage}.
- * Consumed when building {@link CommandUsage}.
- */
-export type OperationUsage = {
-  /**
-   * Usage descriptors for all registered options.
-   */
-  options: Array<OptionUsage>;
-  /**
-   * Usage descriptors for all declared positionals, in order.
-   */
-  positionals: Array<PositionalUsage>;
-};
-
 /**
  * Creates an {@link Operation} from options, positionals, and an async handler.
  *
- * The `handler` receives the parent `context` and an `inputs` object with
- * `options` (keyed by the same names declared in `inputs.options`) and
- * `positionals` (a tuple in declaration order).
+ * The `handler` receives `context` and `inputs` with decoded `options` and `positionals`.
  *
  * @typeParam Context - Context type accepted by the handler.
  * @typeParam Result - Return type of the handler.
@@ -83,7 +67,7 @@ export type OperationUsage = {
  * @param inputs.options - Map of keys to {@link Option} descriptors.
  * @param inputs.positionals - Ordered array of {@link Positional} descriptors.
  * @param handler - Async function implementing the command logic.
- * @returns An {@link Operation} ready to be composed into a command.
+ * @returns An {@link Operation}.
  *
  * @example
  * ```ts
@@ -96,7 +80,7 @@ export type OperationUsage = {
  *       positionalRequired({ type: typeString, label: "NAME", description: "Name to greet" }),
  *     ],
  *   },
- *   async (_ctx, { options: { loud }, positionals: [name] }) => {
+ *   async function (_ctx, { options: { loud }, positionals: [name] }) {
  *     const message = `Hello, ${name}!`;
  *     console.log(loud ? message.toUpperCase() : message);
  *   },
@@ -123,14 +107,12 @@ export function operation<
 ): Operation<Context, Result> {
   return {
     generateUsage() {
-      const optionsUsage = new Array<OptionUsage>();
+      const optionsUsage = new Array<UsageOption>();
       for (const optionKey in inputs.options) {
         const optionInput = inputs.options[optionKey]!;
-        if (optionInput) {
-          optionsUsage.push(optionInput.generateUsage());
-        }
+        optionsUsage.push(optionInput.generateUsage());
       }
-      const positionalsUsage = new Array<PositionalUsage>();
+      const positionalsUsage = new Array<UsagePositional>();
       for (const positionalInput of inputs.positionals) {
         positionalsUsage.push(positionalInput.generateUsage());
       }