cli-kiss 0.1.9 → 0.2.1

package/docs/.vitepress/config.mts

@@ -0,0 +1,41 @@
+import { defineConfig } from "vitepress";
+
+export default defineConfig({
+  description: "Full-featured TypeScript CLI builder. No bloat, no dependency.",
+  title: "cli-kiss 💋",
+  base: "/cli-kiss/",
+  head: [
+    [
+      "style",
+      {},
+      `
+      .VPDoc div[class*="language-"] code { font-size: 0.8em; line-height: 1.6; }
+      `,
+    ],
+  ],
+  themeConfig: {
+    nav: [
+      { text: "Guide", link: "/guide/01_getting_started" },
+      { text: "npm", link: "https://www.npmjs.com/package/cli-kiss" },
+    ],
+    sidebar: [
+      {
+        text: "Guide",
+        items: [
+          { text: "Getting Started", link: "/guide/01_getting_started" },
+          { 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" },
+        ],
+      },
+    ],
+    socialLinks: [
+      { icon: "github", link: "https://github.com/crypto-vincent/cli-kiss" },
+    ],
+    footer: {
+      message: "CLI: Keep It Simple, Stupid. (KISS)",
+    },
+  },
+});

package/docs/guide/01_getting_started.md

@@ -0,0 +1,116 @@
+# Getting Started
+
+## Installation
+
+```sh
+npm install cli-kiss
+```
+
+## Your first CLI
+
+Here is a minimal "greet" CLI that takes:
+
+- a required `NAME` positional
+- optional `--loud` flag:
+
+```ts
+import {
+  command,
+  operation,
+  optionFlag,
+  positionalRequired,
+  runAndExit,
+  typeString,
+} from "cli-kiss";
+
+const greetCommand = command(
+  { description: "Greet someone" },
+  operation(
+    {
+      options: {
+        loud: optionFlag({ long: "loud", description: "Print in uppercase" }),
+      },
+      positionals: [
+        positionalRequired({
+          type: typeString,
+          label: "NAME",
+          description: "The name to greet",
+        }),
+      ],
+    },
+    async (_ctx, { options: { loud }, positionals: [name] }) => {
+      const message = `Hello, ${name}!`;
+      console.log(loud ? message.toUpperCase() : message);
+    },
+  ),
+);
+
+await runAndExit("greet", process.argv.slice(2), undefined, greetCommand, {
+  buildVersion: "1.0.0",
+});
+```
+
+Run it:
+
+```sh
+$ greet Alice
+```
+
+```text
+Hello, Alice!
+```
+
+Pass some flags:
+
+```sh
+$ greet --loud Alice
+```
+
+```text
+HELLO, ALICE!
+```
+
+Get some help (built-in)
+
+```sh
+$ greet --help
+```
+
+```text
+Usage: greet <NAME>
+
+Greet someone
+
+Positionals:
+  <NAME>  The name to greet
+
+Options:
+  --loud[=no]  Print in uppercase
+```
+
+Get the version (built-in)
+
+```sh
+$ greet --version
+```
+
+```text
+greet 1.0.0
+```
+
+## Project structure
+
+A typical `cli-kiss` project looks like this:
+
+```
+my-cli/
+├── src/
+│   ├── index.ts        ← entry point: calls runAndExit
+│   └── commands/
+│       ├── deploy.ts   ← command(...) definitions
+│       └── rollback.ts
+└── package.json
+```
+
+Each command lives in its own file and is composed together in the entry point.
+See the [Commands](./02_commands) guide to learn how.

package/docs/guide/02_commands.md

@@ -0,0 +1,157 @@
+# 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.
+
+```ts
+import { command, operation, positionalRequired, typeString } from "cli-kiss";
+
+const greet = command(
+  { description: "Greet a user" },
+  operation(
+    {
+      options: {},
+      positionals: [positionalRequired({ type: typeString, label: "NAME" })],
+    },
+    async (_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.
+
+```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",
+  })),
+  {
+    deploy: command(
+      { description: "Deploy the latest build" },
+      operation({ options: {}, positionals: [] }, async (ctx) => {
+        console.log(`Deploying with DB: ${ctx.db}`);
+      }),
+    ),
+    rollback: command(
+      { description: "Rollback to the previous release" },
+      operation({ options: {}, positionals: [] }, async (ctx) => {
+        console.log(`Rolling back, DB: ${ctx.db}`);
+      }),
+    ),
+  },
+);
+
+await runAndExit("deploy-cli", process.argv.slice(2), undefined, rootCmd);
+```
+
+Check it:
+
+```sh
+$ deploy-cli --help
+```
+
+```text
+Usage: deploy-cli <SUBCOMMAND>
+
+My deployment CLI
+
+Subcommands:
+  deploy    Deploy the latest build
+  rollback  Rollback to the previous release
+```
+
+### Subcommand names
+
+The keys of the subcommand map are the literal tokens users type. They must be
+lowercase strings.
+
+## `commandChained` — sequential stages
+
+Use this to split a command into reusable steps without introducing a
+user-visible subcommand 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
+  operation(
+    {
+      options: {
+        token: optionSingleValue({
+          long: "token",
+          type: typeString,
+          description: "API token",
+          default: () => {
+            const t = process.env.API_TOKEN;
+            if (!t) throw new Error("API_TOKEN env var is required");
+            return t;
+          },
+        }),
+      },
+      positionals: [],
+    },
+    async (_ctx, { options: { token } }) => ({ token }),
+  ),
+  // Stage 2: receives { token } as context
+  command(
+    { description: "Deploy with auth token" },
+    operation({ options: {}, positionals: [] }, async ({ token }) => {
+      console.log(`Deploying with token: ${token}`);
+    }),
+  ),
+);
+```
+
+The two stages' options and positionals are merged into a single flat usage
+output — the user sees one combined command.

package/docs/guide/03_options.md

@@ -0,0 +1,111 @@
+# Options
+
+Options are named arguments prefixed with `--` (or `-` for short forms). Declare
+them 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`.
+
+```ts
+import { optionFlag } from "cli-kiss";
+
+const verbose = optionFlag({
+  long: "verbose",
+  short: "v",
+  description: "Enable verbose output",
+});
+// --verbose       →  true
+// --verbose=yes   →  true
+// --verbose=no    →  false
+// (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                |
+
+::: tip A flag specified more than once triggers a parse error. Use
+[`optionRepeatable`](#optionrepeatable-collect-multiple-values) if you need
+multiple values.
+
+:::
+
+## `optionSingleValue` — one typed value
+
+Accepts exactly one value. Use any [`Type`](/guide/05_types) to decode it.
+
+```ts
+import { optionSingleValue, typeString } from "cli-kiss";
+
+const output = optionSingleValue({
+  long: "output",
+  short: "o",
+  type: typeString,
+  label: "PATH",
+  description: "Output directory",
+  default: () => "dist/",
+});
+// --output dist/   →  "dist/"
+// --output=dist/   →  "dist/"
+// -o dist/         →  "dist/"
+// (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                                            |
+
+## `optionRepeatable` — collect multiple values
+
+Collects every occurrence into an array. Safe to specify zero or many times.
+
+```ts
+import { optionRepeatable, typeString } from "cli-kiss";
+
+const files = optionRepeatable({
+  long: "file",
+  short: "f",
+  type: typeString,
+  label: "PATH",
+  description: "Input file (may be repeated)",
+});
+// --file a.ts --file b.ts   →  ["a.ts", "b.ts"]
+// (absent)                  →  []
+```
+
+| Parameter     | Type                  | Description                        |
+| ------------- | --------------------- | ---------------------------------- |
+| `long`        | `Lowercase<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                   |
+
+## Aliases
+
+All three option creators accept an `aliases` field for alternative names:
+
+```ts
+optionFlag({
+  long: "dry-run",
+  aliases: { longs: ["dryrun"], shorts: ["n"] },
+  description: "Print actions without executing them",
+});
+// --dry-run, --dryrun, and -n all work
+```

package/docs/guide/04_positionals.md

@@ -0,0 +1,118 @@
+# Positionals
+
+Positionals are bare (non-option) arguments passed by position. Declare them in
+order in the `positionals` array of [`operation`](/guide/02_commands).
+
+## `positionalRequired` — must be present
+
+Fails with a parse error if the argument is missing.
+
+```ts
+import { positionalRequired, typeString } from "cli-kiss";
+
+const name = positionalRequired({
+  type: typeString,
+  label: "NAME",
+  description: "The name to greet",
+});
+// my-cli Alice   →  "Alice"
+// my-cli         →  Error: <NAME>: 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                                 |
+
+## `positionalOptional` — may be absent
+
+Falls back to a default value when the argument is not provided.
+
+```ts
+import { positionalOptional, typeString } from "cli-kiss";
+
+const greeting = positionalOptional({
+  type: typeString,
+  label: "GREETING",
+  description: "Custom greeting (default: Hello)",
+  default: () => "Hello",
+});
+// 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 |
+
+## `positionalVariadics` — zero or more
+
+Greedily consumes all remaining positional tokens into an array.
+
+```ts
+import { positionalVariadics, typeString } from "cli-kiss";
+
+const files = positionalVariadics({
+  type: typeString,
+  label: "FILE",
+  description: "Files to process",
+});
+// my-cli a.ts b.ts c.ts   →  ["a.ts", "b.ts", "c.ts"]
+// my-cli                  →  []
+```
+
+### End delimiter
+
+Optionally stop collecting at a specific sentinel token:
+
+```ts
+const args = positionalVariadics({
+  type: typeString,
+  label: "ARG",
+  endDelimiter: "STOP",
+  description: "Arguments (end with STOP)",
+});
+// my-cli foo bar STOP ignored   →  ["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 |
+
+## Ordering rules
+
+Positionals are consumed **in declaration order**. Required positionals should
+come first; variadics should be last.
+
+```ts
+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" }),
+    ],
+  },
+  async (_ctx, { positionals: [source, dest, 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"]
+```

package/docs/guide/05_types.md

@@ -0,0 +1,134 @@
+# 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.
+
+## 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                                              |
+
+```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
+```
+
+## `typeOneOf` — string enum
+
+Accept only a fixed set of strings:
+
+```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")
+```
+
+## `typeConverted` — transform an existing type
+
+Chain a `before` type with an `after` transformation:
+
+```ts
+import { typeConverted, typeNumber } from "cli-kiss";
+
+const typePort = typeConverted(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
+```
+
+Errors from the `before` decoder are automatically prefixed with
+`from: <content>` for easy debugging.
+
+## `typeTuple` — fixed-length delimited value
+
+Split a single string into a fixed-length typed tuple:
+
+```ts
+import { typeTuple, typeNumber } from "cli-kiss";
+
+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([typeString, typeNumber], ":");
+// "foo:42"  →  ["foo", 42]
+```
+
+## `typeList` — variable-length delimited value
+
+Split a single string into an array of homogeneous values:
+
+```ts
+import { typeList, typeNumber } from "cli-kiss";
+
+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(typeString, ":");
+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`).
+
+:::
+
+## Custom types
+
+Implement the `Type<Value>` interface directly:
+
+```ts
+import type { Type } from "cli-kiss";
+
+const typeHexColor: Type<string> = {
+  content: "HexColor",
+  decoder(value) {
+    if (/^#[0-9a-fA-F]{6}$/.test(value)) return value;
+    throw new Error(`Not a valid value: "${value}"`);
+  },
+};
+
+// "--color #ff0000"  →  "#ff0000"
+// "--color red"      →  Error: --color: <HEXCOLOR>: HexColor: Not a valid value: "red"
+```