cli-kiss 0.2.1 → 0.2.3

package/docs/.vitepress/config.mts

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

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:
@@ -53,27 +53,27 @@ await runAndExit("greet", process.argv.slice(2), undefined, greetCommand, {
 Run it:
 
 ```sh
-$ greet Alice
+greet Alice
 ```
 
 ```text
 Hello, Alice!
 ```
 
-Pass some flags:
+Pass a flag:
 
 ```sh
-$ greet --loud Alice
+greet --loud Alice
 ```
 
 ```text
 HELLO, ALICE!
 ```
 
-Get some help (built-in)
+Help (built-in):
 
 ```sh
-$ greet --help
+greet --help
 ```
 
 ```text
@@ -88,10 +88,10 @@ Options:
   --loud[=no]  Print in uppercase
 ```
 
-Get the version (built-in)
+Version (built-in):
 
 ```sh
-$ greet --version
+greet --version
 ```
 
 ```text
@@ -102,7 +102,7 @@ greet 1.0.0
 
 A typical `cli-kiss` project looks like this:
 
-```
+```text
 my-cli/
 ├── src/
 │   ├── index.ts        ← entry point: calls runAndExit

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";
@@ -51,7 +49,7 @@ command(
 
 ## `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 {
@@ -90,7 +88,7 @@ await runAndExit("deploy-cli", process.argv.slice(2), undefined, rootCmd);
 Check it:
 
 ```sh
-$ deploy-cli --help
+deploy-cli --help
 ```
 
 ```text
@@ -105,13 +103,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 {
@@ -153,5 +149,4 @@ 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.

package/docs/guide/03_options.md

@@ -1,12 +1,10 @@
 # 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=yes` / `--flag=no`.
 
 ```ts
 import { optionFlag } from "cli-kiss";
@@ -39,7 +37,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 +69,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,7 +1,6 @@
 # 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
 
@@ -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?);
@@ -14,7 +13,7 @@ await runAndExit(cliName, cliArgs, context, command, options?);
 | `cliName` | `Lowercase<string>`                | Program name used in help and `--version` output  |
 | `cliArgs` | `ReadonlyArray<string>`            | Raw arguments — typically `process.argv.slice(2)` |
 | `context` | `Context`                          | Value forwarded to every command handler          |
-| `command` | `CommandDescriptor<Context, void>` | The root command                                  |
+| `command` | `Command<Context, void>`           | The root command                                  |
 | `options` | `object?`                          | See below                                         |
 
 ### Options
@@ -100,7 +99,7 @@ await runAndExit("my-cli", process.argv.slice(2), undefined, rootCmd, {
 Check it
 
 ```sh
-$ my-cli --help
+my-cli --help
 ```
 
 ```text
@@ -118,7 +117,7 @@ Options:
 Try it
 
 ```sh
-$ my-cli deploy --dry-run
+my-cli deploy --dry-run
 ```
 
 ```text
@@ -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

@@ -2,12 +2,12 @@
 layout: home
 
 hero:
-  name: cli-kiss 💋
+  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/><span>K</span>eep
+    <span>I</span>t <span>S</span>imple and <span>S</span>tupid, it just does the
+    job.
 
   actions:
     - theme: brand

package/package.json

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