cli-kiss 0.2.4 → 0.2.6

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",
       {},
@@ -27,8 +28,8 @@ export default defineConfig({
           { text: "Commands", link: "/guide/02_commands" },
           { text: "Options", link: "/guide/03_options" },
           { text: "Positionals", link: "/guide/04_positionals" },
-          { text: "Types", link: "/guide/05_types" },
-          { text: "Running your CLI", link: "/guide/06_run" },
+          { text: "Input Types", link: "/guide/05_input_types" },
+          { text: "Running your CLI", link: "/guide/06_run_as_cli" },
         ],
       },
     ],

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

@@ -1,4 +1,8 @@
 :root {
-  --vp-home-hero-image-background-image: linear-gradient( -50deg, #ff003cff 0%, #00000000 50%, #459900ff 100% );
-  --vp-home-hero-image-filter: blur(150px);
+  /*
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: linear-gradient(-50deg, #ff003caa 30%, #459900aa 70%);
+  */
+  --vp-home-hero-image-background-image: linear-gradient( -50deg, #ff003c88 25%, #008732aa 60% );
+  --vp-home-hero-image-filter: blur(60px);
 }

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,14 +7,12 @@ 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 function (_ctx, { positionals: [name] }) {
       console.log(`Hello, ${name}!`);
@@ -28,13 +26,6 @@ const greet = command(
 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.
@@ -68,7 +59,7 @@ deploy-cli --help
 ```
 
 ```text
-Usage: deploy-cli <SUBCOMMAND>
+Usage: deploy-cli <subcommand>
 
 My deployment CLI
 
@@ -79,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
@@ -102,9 +85,9 @@ const authenticatedDeploy = commandChained(
       options: {
         token: optionSingleValue({
           long: "token",
-          type: typeString,
+          type: type("secret"),
           description: "API token",
-          default: function () {
+          defaultWhenNotDefined: function () {
             const t = process.env.API_TOKEN;
             if (!t) throw new Error("API_TOKEN env var is required");
             return t;
@@ -147,13 +130,13 @@ Each `Example` entry has:
 
 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]`     |
+| 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(

package/docs/guide/03_options.md

@@ -5,11 +5,9 @@ Named `--` arguments (or `-` for short forms). Declared in the `options` map of
 
 ## `optionFlag` — boolean toggle
 
-Present or absent. Also accepts `--flag=true` / `--flag=no` / `--no-flag`.
+Present or absent. Also accepts `--flag=true` / `--flag=no`.
 
 ```ts
-import { optionFlag } from "cli-kiss";
-
 const verbose = optionFlag({
   long: "verbose",
   short: "v",
@@ -23,7 +21,7 @@ const verbose = optionFlag({
 
 | Parameter     | Type                  | Description                          |
 | ------------- | --------------------- | ------------------------------------ |
-| `long`        | `Lowercase<string>`   | Long flag name (without `--`)        |
+| `long`        | `string`              | Long flag name (without `--`)        |
 | `short`       | `string?`             | Short flag name (without `-`)        |
 | `description` | `string?`             | Help text                            |
 | `hint`        | `string?`             | Short note in parentheses            |
@@ -41,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/"
@@ -57,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"]
@@ -88,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"]
 ```

package/docs/guide/05_input_types.md

@@ -0,0 +1,134 @@
+# Input Types
+
+A `Type<Value>` converts a raw CLI string into a typed value:
+
+- Contains a `content` label about the type of data being decoded
+- Paired with a `decoder` function that throws if the value is invalid.
+
+A `Type<Value>` can then be used as a value for an `Option` or `Positional`
+
+## Built-in types
+
+All type factories accept an optional `name` parameter that overrides the label
+shown in help/errors.
+
+| Type factory   | Content type | Accepts                                                             |
+| -------------- | ------------ | ------------------------------------------------------------------- |
+| `type`         | `string`     | Any string                                                          |
+| `typeBoolean`  | `boolean`    | `true/yes/on/y` → true, `false/no/off/n` → false (case-insensitive) |
+| `typeNumber`   | `number`     | Integers, floats, scientific notation                               |
+| `typeInteger`  | `bigint`     | Integer strings only                                                |
+| `typeDatetime` | `Date`       | Any format accepted by `Date.parse` (ISO 8601 recommended)          |
+| `typeUrl`      | `URL`        | Absolute URLs                                                       |
+| `typePath`     | `string`     | Non-empty path strings; optional sync existence check               |
+
+```ts
+type("greeting").decoder("hello"); // → "hello"
+typeBoolean("flag").decoder("yes"); // → true
+typeNumber("pi").decoder("3.14"); // → 3.14
+typeInteger("id").decoder("9007199254740993"); // → 9007199254740993n
+typeDatetime("birthday").decoder("2024-01-15"); // → Date object
+typeUrl("redirect").decoder("https://example.com/path"); // → URL object
+typePath().decoder("/usr/bin"); // → "/usr/bin"
+```
+
+`typePath` also accepts a second argument for existence checks:
+
+```ts
+typePath("config", { checkSyncExistAs: "file" }); // throws if not a file
+typePath("dir", { checkSyncExistAs: "directory" }); // throws if not a directory
+```
+
+## `typeChoice` — string enum
+
+Accepts only a fixed set of strings (case-insensitive by default):
+
+```ts
+const typeEnv = typeChoice("environment", ["dev", "staging", "prod"]);
+typeEnv.decoder("prod"); // → "prod"
+typeEnv.decoder("PROD"); // → "prod"  (case-insensitive)
+typeEnv.decoder("unknown");
+// Error: Invalid value: "unknown" (expected one of: "dev" | "staging" | "prod")
+```
+
+Pass `true` as third argument to make matching case-sensitive.
+
+## `typeTuple` — fixed-length delimited value
+
+Splits a string into a fixed-length typed tuple:
+
+```ts
+const typePoint = typeTuple([typeNumber(), typeNumber()]);
+typePoint.decoder("3.14,2.71"); // → [3.14, 2.71]
+typePoint.decoder("x,2"); // → Error: at 0: Number: Unable to parse: "x"
+```
+
+The default separator is `","`. Pass a second argument to change it:
+
+```ts
+typeTuple([type("name"), typeNumber()], ":");
+// "foo:42"  →  ["foo", 42]
+```
+
+## `typeList` — variable-length delimited value
+
+Splits a string into an array of typed values:
+
+```ts
+const typeNumbers = typeList(typeNumber());
+typeNumbers.decoder("1,2,3"); // → [1, 2, 3]
+typeNumbers.decoder("1,x,3"); // → Error: at 1: Number: Unable to parse: "x"
+```
+
+Custom separator:
+
+```ts
+const typePaths = typeList(typePath(), ":");
+typePaths.decoder("/usr/bin:/usr/local/bin"); // → ["/usr/bin", "/usr/local/bin"]
+```
+
+::: tip Prefer
+[`optionRepeatable`](/guide/03_options#optionrepeatable-collect-multiple-values)
+over `typeList` when users should pass multiple values as separate flags
+(`--file a --file b` rather than `--files a,b`).
+
+:::
+
+## `typeConverted` — transform decoded value
+
+Chains a base type with a transformation function:
+
+```ts
+const typePort = typeConverted("port", typeNumber(), (n) => {
+  if (n < 1 || n > 65535) throw new Error("Out of range");
+  return n;
+});
+// "--port 8080"   →  8080
+// "--port 99999"  →  throws
+```
+
+## `typeRenamed` — rename a type
+
+Wraps a type with a different label for clearer errors:
+
+```ts
+const typeUserId = typeRenamed(typeInteger("u64"), "user-id");
+```
+
+## Custom types
+
+Implement the `Type<Value>` interface directly:
+
+```ts
+const typeHexColor: Type<string> = {
+  content: "hex-color",
+  decoder(value) {
+    if (/^#[0-9a-fA-F]{6}$/.test(value)) {
+      return value;
+    }
+    throw new Error(`Not a valid hex color: "${value}"`);
+  },
+};
+// "#ff0000"  →  "#ff0000"
+// "red"  →  Error: HexColor: Not a valid value: "red"
+```