cli-kiss 0.2.3 → 0.2.5

package/docs/.vitepress/config.mts

@@ -5,6 +5,7 @@ export default defineConfig({
   title: "cli-kiss 💋",
   base: "/cli-kiss/",
   head: [
+    ["link", { rel: "icon", href: "/cli-kiss/favicon.ico" }],
     [
       "style",
       {},
@@ -14,9 +15,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/01_getting_started.md

@@ -8,10 +8,10 @@ npm install cli-kiss
 
 ## Your first CLI
 
-Minimal "greet" CLI with:
+Example minimal "greet" CLI with:
 
-- a required `NAME` positional
-- optional `--loud` flag:
+- a required `name` positional argument
+- optional `--loud` boolean flag
 
 ```ts
 import {
@@ -20,7 +20,7 @@ import {
   optionFlag,
   positionalRequired,
   runAndExit,
-  typeString,
+  type,
 } from "cli-kiss";
 
 const greetCommand = command(
@@ -32,20 +32,19 @@ const greetCommand = command(
       },
       positionals: [
         positionalRequired({
-          type: typeString,
-          label: "NAME",
-          description: "The name to greet",
+          type: type("name"),
+          description: "The name of the person to greet",
         }),
       ],
     },
-    async (_ctx, { options: { loud }, positionals: [name] }) => {
+    async (_context, { options: { loud }, positionals: [name] }) => {
       const message = `Hello, ${name}!`;
       console.log(loud ? message.toUpperCase() : message);
     },
   ),
 );
 
-await runAndExit("greet", process.argv.slice(2), undefined, greetCommand, {
+await runAndExit("greet", process.argv.slice(2), {}, greetCommand, {
   buildVersion: "1.0.0",
 });
 ```
@@ -70,19 +69,19 @@ greet --loud Alice
 HELLO, ALICE!
 ```
 
-Help (built-in):
+Help and color (built-in):
 
 ```sh
-greet --help
+greet --help --color
 ```
 
 ```text
-Usage: greet <NAME>
+Usage: greet <name>
 
 Greet someone
 
 Positionals:
-  <NAME>  The name to greet
+  <name>  The name of the person to greet
 
 Options:
   --loud[=no]  Print in uppercase

package/docs/guide/02_commands.md

@@ -7,75 +7,42 @@ Three factory functions cover every use-case.
 No subcommands — directly runs an operation.
 
 ```ts
-import { command, operation, positionalRequired, typeString } from "cli-kiss";
-
 const greet = command(
   { description: "Greet a user" },
   operation(
     {
       options: {},
-      positionals: [positionalRequired({ type: typeString, label: "NAME" })],
+      positionals: [positionalRequired({ type: type("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.
 
 ```ts
-import {
-  command,
-  commandWithSubcommands,
-  operation,
-  runAndExit,
-} from "cli-kiss";
-
 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}`);
       }),
     ),
@@ -92,7 +59,7 @@ deploy-cli --help
 ```
 
 ```text
-Usage: deploy-cli <SUBCOMMAND>
+Usage: deploy-cli <subcommand>
 
 My deployment CLI
 
@@ -103,21 +70,13 @@ Subcommands:
 
 ### Subcommand names
 
-Keys are the tokens users type — must be lowercase strings.
+Keys are the tokens users must type.
 
 ## `commandChained` — sequential stages
 
 Splits a command into reusable steps with no extra user-visible token.
 
 ```ts
-import {
-  command,
-  commandChained,
-  operation,
-  optionSingleValue,
-  typeString,
-} from "cli-kiss";
-
 const authenticatedDeploy = commandChained(
   { description: "Authenticate then deploy" },
   // Stage 1: parse a --token option and forward the token as context
@@ -126,9 +85,9 @@ const authenticatedDeploy = commandChained(
       options: {
         token: optionSingleValue({
           long: "token",
-          type: typeString,
+          type: type("secret"),
           description: "API token",
-          default: () => {
+          defaultWhenNotDefined: function () {
             const t = process.env.API_TOKEN;
             if (!t) throw new Error("API_TOKEN env var is required");
             return t;
@@ -150,3 +109,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; inlined?: string; separated?: string[] } }`  | `--long[=val] [args]` |
+| `{ option: { short: string; inlined?: string; separated?: string[] } }` | `-s[=val] [args]`     |
+
+```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,14 +1,13 @@
 # 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`.
 
 ```ts
-import { optionFlag } from "cli-kiss";
-
 const verbose = optionFlag({
   long: "verbose",
   short: "v",
@@ -20,14 +19,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`        | `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
@@ -40,15 +39,12 @@ multiple values.
 Exactly one typed value.
 
 ```ts
-import { optionSingleValue, typeString } from "cli-kiss";
-
 const output = optionSingleValue({
   long: "output",
   short: "o",
-  type: typeString,
-  label: "PATH",
+  type: typePath(),
   description: "Output directory",
-  default: () => "dist/",
+  defaultWhenNotDefined: () => "dist/",
 });
 // --output dist/   →  "dist/"
 // --output=dist/   →  "dist/"
@@ -56,29 +52,26 @@ const output = optionSingleValue({
 // (absent)         →  "dist/"
 ```
 
-| Parameter     | Type                  | Description                                                 |
-| ------------- | --------------------- | ----------------------------------------------------------- |
-| `long`        | `Lowercase<string>`   | Long option name                                            |
-| `short`       | `string?`             | Short option name                                           |
-| `type`        | `Type<Value>`         | Decoder for the value                                       |
-| `label`       | `Uppercase<string>?`  | Placeholder in help (defaults to uppercased type content)   |
-| `description` | `string?`             | Help text                                                   |
-| `hint`        | `string?`             | Short note in parentheses                                   |
-| `default`     | `() => Value`         | Default when absent — **throw** to make the option required |
-| `aliases`     | `{ longs?, shorts? }` | Additional names                                            |
+| Parameter               | Type                  | Description                                                                  |
+| ----------------------- | --------------------- | ---------------------------------------------------------------------------- |
+| `long`                  | `string`              | Long option name                                                             |
+| `short`                 | `string?`             | Short option name                                                            |
+| `type`                  | `Type<Value>`         | Decoder for the value                                                        |
+| `description`           | `string?`             | Help text                                                                    |
+| `hint`                  | `string?`             | Short note in parentheses                                                    |
+| `defaultWhenNotDefined` | `() => Value`         | Value when option is absent — **throw** to make it required                  |
+| `defaultWhenNotInlined` | `() => Value?`        | Value when option is present but has no inline value (e.g. `--output` alone) |
+| `aliases`               | `{ longs?, shorts? }` | Additional names                                                             |
 
 ## `optionRepeatable` — collect multiple values
 
 Collects every occurrence into an array.
 
 ```ts
-import { optionRepeatable, typeString } from "cli-kiss";
-
 const files = optionRepeatable({
   long: "file",
   short: "f",
-  type: typeString,
-  label: "PATH",
+  type: typePath("FILE_PATH"),
   description: "Input file (may be repeated)",
 });
 // --file a.ts --file b.ts   →  ["a.ts", "b.ts"]
@@ -87,10 +80,9 @@ const files = optionRepeatable({
 
 | Parameter     | Type                  | Description                        |
 | ------------- | --------------------- | ---------------------------------- |
-| `long`        | `Lowercase<string>`   | Long option name                   |
+| `long`        | `string`              | Long option name                   |
 | `short`       | `string?`             | Short option name                  |
 | `type`        | `Type<Value>`         | Decoder applied to each occurrence |
-| `label`       | `Uppercase<string>?`  | Placeholder in help                |
 | `description` | `string?`             | Help text                          |
 | `hint`        | `string?`             | Short note in parentheses          |
 | `aliases`     | `{ longs?, shorts? }` | Additional names                   |

package/docs/guide/04_positionals.md

@@ -1,69 +1,63 @@
 # Positionals
 
-Bare (non-`--`) arguments, consumed in order. Declared 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 if missing.
 
 ```ts
-import { positionalRequired, typeString } from "cli-kiss";
-
 const name = positionalRequired({
-  type: typeString,
-  label: "NAME",
-  description: "The name to greet",
+  type: type("person"),
+  description: "The name of the person to greet",
 });
-// my-cli Alice   →  "Alice"
-// my-cli         →  Error: <NAME>: Is required, but was not provided
+// Usage:
+//   my-cli Alice   →  "Alice"
+//   my-cli  →  Error: <person>: Is required, but was not provided
 ```
 
-| Parameter     | Type                 | Description                                               |
-| ------------- | -------------------- | --------------------------------------------------------- |
-| `type`        | `Type<Value>`        | Decoder for the raw string token                          |
-| `label`       | `Uppercase<string>?` | Placeholder in help (defaults to uppercased type content) |
-| `description` | `string?`            | Help text                                                 |
-| `hint`        | `string?`            | Short note in parentheses                                 |
+| Parameter     | Type          | Description                      |
+| ------------- | ------------- | -------------------------------- |
+| `type`        | `Type<Value>` | Decoder for the raw string token |
+| `description` | `string?`     | Help text                        |
+| `hint`        | `string?`     | Short note in parentheses        |
 
 ## `positionalOptional` — may be absent
 
 Falls back to a default when absent.
 
 ```ts
-import { positionalOptional, typeString } from "cli-kiss";
-
 const greeting = positionalOptional({
-  type: typeString,
-  label: "GREETING",
-  description: "Custom greeting (default: Hello)",
+  type: type("greeting"),
+  description: "Custom greeting",
+  hint: "default to 'Hello'",
   default: () => "Hello",
 });
-// my-cli          →  "Hello"
-// my-cli Howdy    →  "Howdy"
+// Usage:
+//   my-cli          →  "Hello"
+//.  my-cli Howdy    →  "Howdy"
 ```
 
-| Parameter     | Type                 | Description                                       |
-| ------------- | -------------------- | ------------------------------------------------- |
-| `type`        | `Type<Value>`        | Decoder for the raw string token                  |
-| `label`       | `Uppercase<string>?` | Placeholder in help                               |
-| `description` | `string?`            | Help text                                         |
-| `hint`        | `string?`            | Short note in parentheses                         |
-| `default`     | `() => Value`        | Value when absent — **throw** to make it required |
+| Parameter     | Type          | Description                                       |
+| ------------- | ------------- | ------------------------------------------------- |
+| `type`        | `Type<Value>` | Decoder for the raw string token                  |
+| `description` | `string?`     | Help text                                         |
+| `hint`        | `string?`     | Short note in parentheses                         |
+| `default`     | `() => Value` | Value when absent — **throw** to make it required |
 
 ## `positionalVariadics` — zero or more
 
 Consumes all remaining tokens into an array.
 
 ```ts
-import { positionalVariadics, typeString } from "cli-kiss";
-
 const files = 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 a.ts b.ts c.ts   →  ["a.ts", "b.ts", "c.ts"]
+//   my-cli  →  []
 ```
 
 ### End delimiter
@@ -72,21 +66,20 @@ Optionally stop collecting at a specific sentinel token:
 
 ```ts
 const args = positionalVariadics({
-  type: typeString,
-  label: "ARG",
+  type: type("argument"),
   endDelimiter: "STOP",
   description: "Arguments (end with STOP)",
 });
-// my-cli foo bar STOP   →  ["foo", "bar"]
+// Usage:
+//   my-cli foo bar STOP   →  ["foo", "bar"]
 ```
 
-| Parameter      | Type                 | Description                          |
-| -------------- | -------------------- | ------------------------------------ |
-| `type`         | `Type<Value>`        | Decoder applied to each token        |
-| `label`        | `Uppercase<string>?` | Placeholder in help                  |
-| `description`  | `string?`            | Help text                            |
-| `hint`         | `string?`            | Short note in parentheses            |
-| `endDelimiter` | `string?`            | Sentinel token that stops collection |
+| Parameter      | Type          | Description                          |
+| -------------- | ------------- | ------------------------------------ |
+| `type`         | `Type<Value>` | Decoder applied to each token        |
+| `description`  | `string?`     | Help text                            |
+| `hint`         | `string?`     | Short note in parentheses            |
+| `endDelimiter` | `string?`     | Sentinel token that stops collection |
 
 ## Ordering rules
 
@@ -97,20 +90,17 @@ operation(
   {
     options: {},
     positionals: [
-      positionalRequired({ type: typeString, label: "SOURCE" }),
-      positionalRequired({ type: typeString, label: "DEST" }),
-      positionalOptional({
-        type: typeString,
-        label: "TAG",
-        default: () => "latest",
-      }),
-      positionalVariadics({ type: typeString, label: "EXTRA" }),
+      positionalRequired({ type: type("src") }),
+      positionalRequired({ type: type("dst") }),
+      positionalOptional({ type: type("tag"), default: () => "latest" }),
+      positionalVariadics({ type: type("extra") }),
     ],
   },
-  async (_ctx, { positionals: [source, dest, tag, extras] }) => {
+  async function (_ctx, { positionals: [src, dst, tag, extras] }) {
     /* ... */
   },
 );
-// my-cli src/ dst/                →  source="src/", dest="dst/", tag="latest", extras=[]
-// my-cli src/ dst/ v2 a b c       →  source="src/", dest="dst/", tag="v2", extras=["a","b","c"]
+// Usage:
+//   my-cli in out  →  src="in", src="out", tag="latest", extras=[]
+//   my-cli in out v2 a b c  →  src="in", src="out", tag="v2", extras=["a","b","c"]
 ```