cli-kiss 0.2.3 → 0.2.5

package/docs/guide/05_types.md

@@ -1,79 +1,61 @@
 # Types
 
-A `Type<Value>` converts a raw CLI string into a typed value: a `content` label paired with a `decoder`.
+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.
 
 ## Built-in types
 
-| Export        | TypeScript type | Accepts                                                    |
-| ------------- | --------------- | ---------------------------------------------------------- |
-| `typeString`  | `string`        | Any string                                                 |
-| `typeBoolean` | `boolean`       | `true`, `yes`, `false`, `no` (case-insensitive)            |
-| `typeNumber`  | `number`        | Integers, floats, scientific notation                      |
-| `typeInteger` | `bigint`        | Integer strings only                                       |
-| `typeDate`    | `Date`          | Any format accepted by `Date.parse` (ISO 8601 recommended) |
-| `typeUrl`     | `URL`           | Absolute URLs                                              |
+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/1/y/t` → true, `false/no/off/0/n/f` → 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
-import {
-  typeBoolean,
-  typeDate,
-  typeInteger,
-  typeNumber,
-  typeString,
-  typeUrl,
-} from "cli-kiss";
-
-typeString.decoder("hello"); // → "hello"
-typeBoolean.decoder("yes"); // → true
-typeNumber.decoder("3.14"); // → 3.14
-typeInteger.decoder("9007199254740993"); // → 9007199254740993n
-typeDate.decoder("2024-01-15"); // → Date object
-typeUrl.decoder("https://example.com/path"); // → URL object
+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"
 ```
 
-## `typeOneOf` — string enum
-
-Accepts only a fixed set of strings:
+`typePath` also accepts a second argument for existence checks:
 
 ```ts
-import { typeOneOf } from "cli-kiss";
-
-const typeEnv = typeOneOf("Environment", ["dev", "staging", "prod"]);
-
-typeEnv.decoder("prod"); // → "prod"
-typeEnv.decoder("unknown");
-// Error: Invalid value: "unknown" (expected one of: "dev" | "staging" | "prod")
+typePath("config", { checkSyncExistAs: "file" });     // throws if not a file
+typePath("dir",    { checkSyncExistAs: "directory" }); // throws if not a directory
 ```
 
-## `typeMapped` — transform an existing type
+## `typeChoice` — string enum
 
-Chain a `before` type with an `after` transformation:
+Accepts only a fixed set of strings (case-insensitive by default):
 
 ```ts
-import { typeMapped, typeNumber } from "cli-kiss";
-
-const typePort = typeMapped(typeNumber, {
-  content: "Port",
-  decoder: (n) => {
-    if (n < 1 || n > 65535) throw new Error("Out of range");
-    return n;
-  },
-});
-// "--port 8080"   →  8080
-// "--port 99999"  →  Error: --port: <PORT>: Port: Out of range
+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")
 ```
 
-Errors from the `before` decoder are prefixed with `from: <content>`.
+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
-import { typeTuple, typeNumber } from "cli-kiss";
-
-const typePoint = typeTuple([typeNumber, typeNumber]);
-
+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"
 ```
@@ -81,7 +63,7 @@ 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([typeString, typeNumber], ":");
+typeTuple([type("name"), typeNumber()], ":");
 // "foo:42"  →  ["foo", 42]
 ```
 
@@ -90,10 +72,7 @@ typeTuple([typeString, typeNumber], ":");
 Splits a string into an array of typed values:
 
 ```ts
-import { typeList, typeNumber } from "cli-kiss";
-
-const typeNumbers = typeList(typeNumber);
-
+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"
 ```
@@ -101,7 +80,7 @@ typeNumbers.decoder("1,x,3"); // → Error: at 1: Number: Unable to parse: "x"
 Custom separator:
 
 ```ts
-const typePaths = typeList(typeString, ":");
+const typePaths = typeList(typePath(), ":");
 typePaths.decoder("/usr/bin:/usr/local/bin"); // → ["/usr/bin", "/usr/local/bin"]
 ```
 
@@ -112,21 +91,42 @@ over `typeList` when users should pass multiple values as separate flags
 
 :::
 
+## `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"  →  TypoError
+```
+
+## `typeRenamed` — rename a type
+
+Wraps a type with a different label for clearer errors:
+
+```ts
+const typeId = typeRenamed(typeInteger(), "user-id");
+// errors show "user-id" instead of "integer"
+```
+
 ## Custom types
 
 Implement the `Type<Value>` interface directly:
 
 ```ts
-import type { Type } from "cli-kiss";
-
 const typeHexColor: Type<string> = {
-  content: "HexColor",
+  content: "hex-color",
   decoder(value) {
-    if (/^#[0-9a-fA-F]{6}$/.test(value)) return value;
-    throw new Error(`Not a valid value: "${value}"`);
+    if (/^#[0-9a-fA-F]{6}$/.test(value)) {
+      return value;
+    }
+    throw new Error(`Not a valid color: "${value}"`);
   },
 };
-
-// "--color #ff0000"  →  "#ff0000"
-// "--color red"      →  Error: --color: <HEXCOLOR>: HexColor: Not a valid value: "red"
+// "#ff0000"  →  "#ff0000"
+// "red"  →  Error: HexColor: Not a valid value: "red"
 ```

package/docs/guide/06_run.md

@@ -8,24 +8,24 @@
 await runAndExit(cliName, cliArgs, context, command, options?);
 ```
 
-| Parameter | Type                               | Description                                       |
-| --------- | ---------------------------------- | ------------------------------------------------- |
-| `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` | `Command<Context, void>`           | The root command                                  |
-| `options` | `object?`                          | See below                                         |
+| Parameter | Type                     | Description                                       |
+| --------- | ------------------------ | ------------------------------------------------- |
+| `cliName` | `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` | `Command<Context, void>` | The root command                                  |
+| `options` | `object?`                | See below                                         |
 
 ### Options
 
-| Option         | Type                       | Default        | Description                                                 |
-| -------------- | -------------------------- | -------------- | ----------------------------------------------------------- |
-| `buildVersion` | `string?`                  | —              | Enables `--version` flag; prints `<cliName> <buildVersion>` |
-| `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                         |
-| `onExit`       | `(code: number) => never`  | `process.exit` | Override for testing                                        |
+| Option         | Type                                        | Default        | Description                                                                                 |
+| -------------- | ------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------- |
+| `buildVersion` | `string?`                                   | —              | Enables `--version` flag; prints `<cliName> <buildVersion>`                                 |
+| `usageOnHelp`  | `boolean?`                                  | `true`         | Enables `--help` flag                                                                       |
+| `usageOnError` | `boolean?`                                  | `true`         | Prints usage to stderr when parsing fails                                                   |
+| `colorSetup`   | `"flag"\|"env"\|"always"\|"never"\|"mock"?` | `"flag"`       | Color mode: `"flag"` adds a `--color` option; `"env"` reads env vars; others force the mode |
+| `onError`      | `(error: unknown) => void`                  | —              | Custom handler for parse and execution errors                                               |
+| `onExit`       | `(code: number) => never`                   | `process.exit` | Override for testing                                                                        |
 
 ### Exit codes
 
@@ -37,18 +37,6 @@ await runAndExit(cliName, cliArgs, context, command, options?);
 ## Full example
 
 ```ts
-import {
-  command,
-  commandWithSubcommands,
-  operation,
-  optionFlag,
-  optionSingleValue,
-  positionalRequired,
-  runAndExit,
-  typeString,
-  typeUrl,
-} from "cli-kiss";
-
 type Ctx = { db: string };
 
 const deployCmd = command(
@@ -77,9 +65,9 @@ const rootCmd = commandWithSubcommands(
       options: {
         dbUrl: optionSingleValue({
           long: "db",
-          type: typeUrl,
+          type: typeUrl(),
           description: "Database URL",
-          default: () => new URL("postgres://localhost/mydb"),
+          defaultWhenNotDefined: () => new URL("postgres://localhost/mydb"),
         }),
       },
       positionals: [],
@@ -103,7 +91,7 @@ my-cli --help
 ```
 
 ```text
-Usage: my-cli <SUBCOMMAND>
+Usage: my-cli <subcommand>
 
 My deployment CLI
 
@@ -111,7 +99,7 @@ Subcommands:
   deploy  Deploy to production
 
 Options:
-  --db <URL>  Database URL
+  --db <url>  Database URL
 ```
 
 Try it
@@ -126,17 +114,21 @@ my-cli deploy --dry-run
 
 ## Color control
 
-Colors are auto-detected. Override:
+Colors are auto-detected by default (`colorSetup: "flag"` adds a `--color`
+option). Override:
 
 ```ts
 // Force colors on
-await runAndExit("my-cli", args, ctx, cmd, { useTtyColors: true });
+await runAndExit("my-cli", args, ctx, cmd, { colorSetup: "always" });
 
 // Force colors off (useful in CI)
-await runAndExit("my-cli", args, ctx, cmd, { useTtyColors: false });
+await runAndExit("my-cli", args, ctx, cmd, { colorSetup: "never" });
+
+// Read from env vars (FORCE_COLOR, NO_COLOR, MOCK_COLOR)
+await runAndExit("my-cli", args, ctx, cmd, { colorSetup: "env" });
 
 // Deterministic mock output (useful in snapshot tests)
-await runAndExit("my-cli", args, ctx, cmd, { useTtyColors: "mock" });
+await runAndExit("my-cli", args, ctx, cmd, { colorSetup: "mock" });
 ```
 
 ## Testing your CLI
@@ -144,17 +136,13 @@ await runAndExit("my-cli", args, ctx, cmd, { useTtyColors: "mock" });
 Override `onExit` to prevent process exit during tests:
 
 ```ts
-import { runAndExit } from "cli-kiss";
-
 const exitCodes: number[] = [];
-
 await runAndExit("my-cli", ["--help"], undefined, myCommand, {
-  useTtyColors: false,
+  colorSetup: "never",
   onExit: (code) => {
     exitCodes.push(code);
     return undefined as never;
   },
 });
-
 console.assert(exitCodes[0] === 0, "expected exit 0 for --help");
 ```

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.5",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "devDependencies": {

package/src/index.ts

@@ -7,5 +7,3 @@ export * from "./lib/Run";
 export * from "./lib/Type";
 export * from "./lib/Typo";
 export * from "./lib/Usage";
-
-// TODO - maybe add a parsed option recap on error