cli-kiss 0.2.2 → 0.2.4

package/docs/.vitepress/config.mts

@@ -14,6 +14,7 @@ export default defineConfig({
     ],
   ],
   themeConfig: {
+    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/01_getting_started.md

@@ -8,7 +8,7 @@ npm install cli-kiss
 
 ## Your first CLI
 
-Here is a minimal "greet" CLI that takes:
+Minimal "greet" CLI with:
 
 - a required `NAME` positional
 - optional `--loud` flag:
@@ -60,7 +60,7 @@ greet Alice
 Hello, Alice!
 ```
 
-Pass some flags:
+Pass a flag:
 
 ```sh
 greet --loud Alice
@@ -70,7 +70,7 @@ greet --loud Alice
 HELLO, ALICE!
 ```
 
-Get some help (built-in)
+Help (built-in):
 
 ```sh
 greet --help
@@ -88,7 +88,7 @@ Options:
   --loud[=no]  Print in uppercase
 ```
 
-Get the version (built-in)
+Version (built-in):
 
 ```sh
 greet --version

package/docs/guide/02_commands.md

@@ -1,12 +1,10 @@
 # Commands
 
-Commands are the building blocks of a `cli-kiss` CLI.
-
 Three factory functions cover every use-case.
 
 ## `command` — leaf command
 
-A leaf command has no subcommands. It directly runs an operation.
+No subcommands — directly runs an operation.
 
 ```ts
 import { command, operation, positionalRequired, typeString } from "cli-kiss";
@@ -18,40 +16,16 @@ 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
 
-Use this when the user must pick one of several sub-actions.
+User must pick one of several sub-actions.
 
 ```ts
 import {
@@ -65,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}`);
       }),
     ),
@@ -105,13 +79,11 @@ Subcommands:
 
 ### Subcommand names
 
-The keys of the subcommand map are the literal tokens users type. They must be
-lowercase strings.
+Keys are the tokens users type — must be lowercase strings.
 
 ## `commandChained` — sequential stages
 
-Use this to split a command into reusable steps without introducing a
-user-visible subcommand token.
+Splits a command into reusable steps with no extra user-visible token.
 
 ```ts
 import {
@@ -132,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;
@@ -153,5 +125,64 @@ const authenticatedDeploy = commandChained(
 );
 ```
 
-The two stages' options and positionals are merged into a single flat usage
-output — the user sees one combined command.
+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,12 +1,11 @@
 # Options
 
-Options are named arguments prefixed with `--` (or `-` for short forms). Declare
-them 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
 
-A flag that is either present or absent. The user can also pass `--flag=yes` /
-`--flag=no`.
+Present or absent. Also accepts `--flag=true` / `--flag=no` / `--no-flag`.
 
 ```ts
 import { optionFlag } from "cli-kiss";
@@ -22,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
@@ -39,7 +38,7 @@ multiple values.
 
 ## `optionSingleValue` — one typed value
 
-Accepts exactly one value. Use any [`Type`](/guide/05_types) to decode it.
+Exactly one typed value.
 
 ```ts
 import { optionSingleValue, typeString } from "cli-kiss";
@@ -71,7 +70,7 @@ const output = optionSingleValue({
 
 ## `optionRepeatable` — collect multiple values
 
-Collects every occurrence into an array. Safe to specify zero or many times.
+Collects every occurrence into an array.
 
 ```ts
 import { optionRepeatable, typeString } from "cli-kiss";

package/docs/guide/04_positionals.md

@@ -1,11 +1,10 @@
 # Positionals
 
-Positionals are bare (non-option) arguments passed by position. Declare them in
-order in the `positionals` array of [`operation`](/guide/02_commands).
+Bare (non-`--`) arguments, consumed in order. Declared in the `positionals` array of [`operation`](/guide/02_commands).
 
 ## `positionalRequired` — must be present
 
-Fails with a parse error if the argument is missing.
+Fails if missing.
 
 ```ts
 import { positionalRequired, typeString } from "cli-kiss";
@@ -28,7 +27,7 @@ const name = positionalRequired({
 
 ## `positionalOptional` — may be absent
 
-Falls back to a default value when the argument is not provided.
+Falls back to a default when absent.
 
 ```ts
 import { positionalOptional, typeString } from "cli-kiss";
@@ -53,7 +52,7 @@ const greeting = positionalOptional({
 
 ## `positionalVariadics` — zero or more
 
-Greedily consumes all remaining positional tokens into an array.
+Consumes all remaining tokens into an array.
 
 ```ts
 import { positionalVariadics, typeString } from "cli-kiss";
@@ -78,7 +77,7 @@ const args = positionalVariadics({
   endDelimiter: "STOP",
   description: "Arguments (end with STOP)",
 });
-// my-cli foo bar STOP ignored   →  ["foo", "bar"]
+// my-cli foo bar STOP   →  ["foo", "bar"]
 ```
 
 | Parameter      | Type                 | Description                          |
@@ -91,8 +90,7 @@ const args = positionalVariadics({
 
 ## Ordering rules
 
-Positionals are consumed **in declaration order**. Required positionals should
-come first; variadics should be last.
+Consumed **in declaration order** — required first, variadics last.
 
 ```ts
 operation(

package/docs/guide/05_types.md

@@ -1,14 +1,13 @@
 # Types
 
-A `Type<Value>` is a pair of a human-readable `content` string and a `decoder`
-function. It tells cli-kiss how to convert a raw CLI string into a typed value.
+A `Type<Value>` converts a raw CLI string into a typed value: a `content` label paired with a `decoder`.
 
 ## Built-in types
 
 | 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) |
@@ -34,7 +33,7 @@ typeUrl.decoder("https://example.com/path"); // → URL object
 
 ## `typeOneOf` — string enum
 
-Accept only a fixed set of strings:
+Accepts only a fixed set of strings:
 
 ```ts
 import { typeOneOf } from "cli-kiss";
@@ -46,14 +45,14 @@ typeEnv.decoder("unknown");
 // Error: Invalid value: "unknown" (expected one of: "dev" | "staging" | "prod")
 ```
 
-## `typeConverted` — transform an existing type
+## `typeMapped` — transform an existing type
 
 Chain a `before` type with an `after` transformation:
 
 ```ts
-import { typeConverted, typeNumber } from "cli-kiss";
+import { typeMapped, typeNumber } from "cli-kiss";
 
-const typePort = typeConverted(typeNumber, {
+const typePort = typeMapped(typeNumber, {
   content: "Port",
   decoder: (n) => {
     if (n < 1 || n > 65535) throw new Error("Out of range");
@@ -64,12 +63,11 @@ const typePort = typeConverted(typeNumber, {
 // "--port 99999"  →  Error: --port: <PORT>: Port: Out of range
 ```
 
-Errors from the `before` decoder are automatically prefixed with
-`from: <content>` for easy debugging.
+Errors from the `before` decoder are prefixed with `from: <content>`.
 
 ## `typeTuple` — fixed-length delimited value
 
-Split a single string into a fixed-length typed tuple:
+Splits a string into a fixed-length typed tuple:
 
 ```ts
 import { typeTuple, typeNumber } from "cli-kiss";
@@ -89,7 +87,7 @@ typeTuple([typeString, typeNumber], ":");
 
 ## `typeList` — variable-length delimited value
 
-Split a single string into an array of homogeneous values:
+Splits a string into an array of typed values:
 
 ```ts
 import { typeList, typeNumber } from "cli-kiss";

package/docs/guide/06_run.md

@@ -2,8 +2,7 @@
 
 ## `runAndExit`
 
-`runAndExit` is the entry point for every `cli-kiss` CLI. It parses arguments,
-runs the matched command, and exits the process.
+`runAndExit` parses arguments, runs the matched command, and exits.
 
 ```ts
 await runAndExit(cliName, cliArgs, context, command, options?);
@@ -25,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
@@ -127,7 +126,7 @@ my-cli deploy --dry-run
 
 ## Color control
 
-By default colors are auto-detected from the terminal. You can override:
+Colors are auto-detected. Override:
 
 ```ts
 // Force colors on
@@ -142,7 +141,7 @@ await runAndExit("my-cli", args, ctx, cmd, { useTtyColors: "mock" });
 
 ## Testing your CLI
 
-Override `onExit` so that `runAndExit` does not terminate your test process:
+Override `onExit` to prevent process exit during tests:
 
 ```ts
 import { runAndExit } from "cli-kiss";

package/docs/index.md

@@ -4,10 +4,12 @@ layout: home
 hero:
   name: CLI-kiss
   text: CLI for TypeScript.
+
   tagline:
-    No bloat, no dependency. Only what you need.</br>Standard expected behaviour
-    that users are used to.</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.2",
+  "version": "0.2.4",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "devDependencies": {