cli-kiss 0.1.9 → 0.2.1

package/docs/guide/06_run.md

@@ -0,0 +1,161 @@
+# Running your CLI
+
+## `runAndExit`
+
+`runAndExit` is the entry point for every `cli-kiss` CLI. It parses arguments,
+runs the matched command, and exits the process.
+
+```ts
+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` | `CommandDescriptor<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                                        |
+
+### Exit codes
+
+| Code | Reason                                  |
+| ---- | --------------------------------------- |
+| `0`  | Success, `--help`, or `--version`       |
+| `1`  | Parse error or uncaught execution error |
+
+## Full example
+
+```ts
+import {
+  command,
+  commandWithSubcommands,
+  operation,
+  optionFlag,
+  optionSingleValue,
+  positionalRequired,
+  runAndExit,
+  typeString,
+  typeUrl,
+} from "cli-kiss";
+
+type Ctx = { db: string };
+
+const deployCmd = command(
+  { description: "Deploy to production" },
+  operation(
+    {
+      options: {
+        dryRun: optionFlag({ long: "dry-run", description: "Simulate only" }),
+      },
+      positionals: [],
+    },
+    async ({ db }, { options: { dryRun } }) => {
+      if (dryRun) {
+        console.log(`[dry-run] would deploy with DB: ${db}`);
+      } else {
+        console.log(`Deploying with DB: ${db}`);
+      }
+    },
+  ),
+);
+
+const rootCmd = commandWithSubcommands(
+  { description: "My deployment CLI" },
+  operation(
+    {
+      options: {
+        dbUrl: optionSingleValue({
+          long: "db",
+          type: typeUrl,
+          description: "Database URL",
+          default: () => new URL("postgres://localhost/mydb"),
+        }),
+      },
+      positionals: [],
+    },
+    async (_ctx, { options: { dbUrl } }): Promise<Ctx> => ({
+      db: dbUrl.toString(),
+    }),
+  ),
+  { deploy: deployCmd },
+);
+
+await runAndExit("my-cli", process.argv.slice(2), undefined, rootCmd, {
+  buildVersion: "2.0.0",
+});
+```
+
+Check it
+
+```sh
+$ my-cli --help
+```
+
+```text
+Usage: my-cli <SUBCOMMAND>
+
+My deployment CLI
+
+Subcommands:
+  deploy  Deploy to production
+
+Options:
+  --db <URL>  Database URL
+```
+
+Try it
+
+```sh
+$ my-cli deploy --dry-run
+```
+
+```text
+[dry-run] would deploy with DB: postgres://localhost/mydb
+```
+
+## Color control
+
+By default colors are auto-detected from the terminal. You can override:
+
+```ts
+// Force colors on
+await runAndExit("my-cli", args, ctx, cmd, { useTtyColors: true });
+
+// Force colors off (useful in CI)
+await runAndExit("my-cli", args, ctx, cmd, { useTtyColors: false });
+
+// Deterministic mock output (useful in snapshot tests)
+await runAndExit("my-cli", args, ctx, cmd, { useTtyColors: "mock" });
+```
+
+## Testing your CLI
+
+Override `onExit` so that `runAndExit` does not terminate your test process:
+
+```ts
+import { runAndExit } from "cli-kiss";
+
+const exitCodes: number[] = [];
+
+await runAndExit("my-cli", ["--help"], undefined, myCommand, {
+  useTtyColors: false,
+  onExit: (code) => {
+    exitCodes.push(code);
+    return undefined as never;
+  },
+});
+
+console.assert(exitCodes[0] === 0, "expected exit 0 for --help");
+```

package/docs/index.md

@@ -0,0 +1,30 @@
+---
+layout: home
+
+hero:
+  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.
+
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /guide/01_getting_started
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/crypto-vincent/cli-kiss
+
+features:
+  - title: Zero dependencies
+    details:
+      Ships with no runtime dependencies.<br/>Pure TypeScript, 5kb bundled.
+  - title: Fully typed
+    details:
+      TypeScript first.<br/>Options and positionals inputs strongly typed.
+  - title: Composable
+    details:
+      Easily create nested subcommands.<br/>Build complex CLIs by nesting logic.
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli-kiss",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "devDependencies": {
@@ -12,12 +12,15 @@
     "ts-jest": "^29.4.4",
     "ts-node": "^10.9.2",
     "tsup": "^8.5.0",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "vitepress": "^1.6.4"
   },
   "scripts": {
     "format": "prettier --write src && prettier --write tests",
     "checks": "tsc --noEmit --skipLibCheck && prettier --check src && prettier --check tests",
     "tests": "jest --config jest.config.ts",
-    "build": "tsup src/index.ts --dts --clean --minify --sourcemap --out-dir dist"
+    "build": "tsup src/index.ts --dts --clean --minify --sourcemap --out-dir dist",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs"
   }
 }

package/src/index.ts

@@ -8,5 +8,4 @@ export * from "./lib/Type";
 export * from "./lib/Typo";
 export * from "./lib/Usage";
 
-// TODO - add documentation and examples
 // TODO - maybe add a parsed option recap on error

package/src/lib/Command.ts

@@ -16,12 +16,12 @@ import {
  *
  * A `CommandDescriptor` is the central building block of a `cli-kiss` CLI. You create
  * one with {@link command}, {@link commandWithSubcommands}, or {@link commandChained},
- * and pass it to {@link runAsCliAndExit} to run your CLI.
+ * and pass it to {@link runAndExit} to run your CLI.
  *
  * @typeParam Context - The value passed into the command when it is executed. It flows
- *   from {@link runAsCliAndExit}'s `context` argument down through the command chain.
+ *   from {@link runAndExit}'s `context` argument down through the command chain.
  * @typeParam Result - The value produced by executing the command. For root commands
- *   passed to {@link runAsCliAndExit} this is always `void`.
+ *   passed to {@link runAndExit} this is always `void`.
  */
 export type CommandDescriptor<Context, Result> = {
   /** Returns the static metadata (description, hint, details) for this command. */
@@ -74,7 +74,7 @@ export type CommandInstance<Context, Result> = {
   /**
    * Executes the command with the provided context.
    *
-   * @param context - Arbitrary value injected by the caller (see {@link runAsCliAndExit}).
+   * @param context - Arbitrary value injected by the caller (see {@link runAndExit}).
    * @returns A promise that resolves to the command's result, or rejects if the
    *   command handler throws.
    */
@@ -84,8 +84,7 @@ export type CommandInstance<Context, Result> = {
 /**
  * Static, human-readable metadata attached to a command.
  *
- * This information is displayed in the usage/help output produced by
- * {@link usageToStyledLines}.
+ * This information is displayed in the usage/help output produced by {@link usageToStyledLines}.
  */
 export type CommandInformation = {
   /** Short description of what the command does. Shown prominently in the usage header. */
@@ -176,7 +175,7 @@ export type CommandUsageSubcommand = {
  * @param information - Static metadata (description, hint, details) for the command.
  * @param operation - The operation that defines options, positionals, and the execution
  *   handler for this command.
- * @returns A {@link CommandDescriptor} suitable for passing to {@link runAsCliAndExit}
+ * @returns A {@link CommandDescriptor} suitable for passing to {@link runAndExit}
  *   or composing with {@link commandWithSubcommands} / {@link commandChained}.
  *
  * @example

package/src/lib/Operation.ts

@@ -66,7 +66,7 @@ export type OperationInstance<Input, Output> = {
    * option/positional values.
    *
    * @param input - Context from the parent command (or the root context supplied to
-   *   {@link runAsCliAndExit}).
+   *   {@link runAndExit}).
    * @returns A promise resolving to the handler's return value.
    */
   executeWithContext(input: Input): Promise<Output>;
@@ -89,7 +89,7 @@ export type OperationUsage = {
  *
  * The `handler` receives:
  * - `context` — the value passed down from the parent command (or from
- *   {@link runAsCliAndExit}).
+ *   {@link runAndExit}).
  * - `inputs.options` — an object whose keys match those declared in `inputs.options` and whose values are
  *   the parsed option values.
  * - `inputs.positionals` — a tuple whose elements match `inputs.positionals` and whose

package/src/lib/Reader.ts

@@ -85,7 +85,7 @@ export type ReaderPositionals = {
  * - End-of-options separator: `--` — all subsequent tokens are treated as positionals.
  *
  * In most cases you do not need to use `ReaderArgs` directly; it is created internally
- * by {@link runAsCliAndExit}. It is exposed for advanced use cases such as building
+ * by {@link runAndExit}. It is exposed for advanced use cases such as building
  * custom runners.
  */
 export class ReaderArgs {

package/src/lib/Run.ts

@@ -16,7 +16,7 @@ import { usageToStyledLines } from "./Usage";
  * - `1` — Argument parsing failed (a usage summary is also printed to stderr), or the
  *   command threw an unhandled execution error.
  *
- * **Built-in flags (opt-out):**
+ * **Built-in flags:**
  * - `--help` — Enabled by default (`usageOnHelp: true`). Prints the usage summary to
  *   stdout and exits with code `0`. This flag takes precedence over `--version`.
  * - `--version` — Enabled when `buildVersion` is provided. Prints `<cliName> <version>`
@@ -44,10 +44,8 @@ import { usageToStyledLines } from "./Usage";
  *   stderr before the error message whenever argument parsing fails.
  * @param options.buildVersion - When provided, registers a `--version` flag that prints
  *   `<cliName> <buildVersion>` to stdout and exits with code `0`.
- * @param options.onExecutionError - Custom handler for errors thrown during command
- *   execution. If omitted, the error is printed to stderr via {@link TypoSupport}.
- * @param options.onLogStdOut - Overrides the standard output sink (default: `console.log`).
- * @param options.onLogStdErr - Overrides the standard error sink (default: `console.error`).
+ * @param options.onError - Custom handler for errors thrown during command execution.
+ *   If omitted, the error is printed to stderr via {@link TypoSupport}.
  * @param options.onExit - Overrides the process exit function (default: `process.exit`).
  *   Useful for testing — supply a function that throws or captures the exit code instead
  *   of actually terminating the process.
@@ -56,7 +54,7 @@ import { usageToStyledLines } from "./Usage";
  *
  * @example
  * ```ts
- * import { runAsCliAndExit, command, operation, positionalRequired, typeString } from "cli-kiss";
+ * import { runAndExit, command, operation, positionalRequired, typeString } from "cli-kiss";
  *
  * const greetCommand = command(
  *   { description: "Greet someone" },
@@ -68,12 +66,12 @@ import { usageToStyledLines } from "./Usage";
  *   ),
  * );
  *
- * await runAsCliAndExit("greet", process.argv.slice(2), undefined, greetCommand, {
+ * await runAndExit("greet", process.argv.slice(2), undefined, greetCommand, {
  *   buildVersion: "1.0.0",
  * });
  * ```
  */
-export async function runAsCliAndExit<Context>(
+export async function runAndExit<Context>(
   cliName: Lowercase<string>,
   cliArgs: ReadonlyArray<string>,
   context: Context,
@@ -83,9 +81,7 @@ export async function runAsCliAndExit<Context>(
     usageOnHelp?: boolean | undefined;
     usageOnError?: boolean | undefined;
     buildVersion?: string | undefined;
-    onExecutionError?: ((error: unknown) => void) | undefined;
-    onLogStdOut?: ((message: string) => void) | undefined;
-    onLogStdErr?: ((message: string) => void) | undefined;
+    onError?: ((error: unknown) => void) | undefined;
     onExit?: ((code: number) => never) | undefined;
   },
 ): Promise<never> {
@@ -114,17 +110,6 @@ export async function runAsCliAndExit<Context>(
     longs: ["completion"],
   });
   */
-  const typoSupport =
-    options?.useTtyColors === undefined
-      ? TypoSupport.inferFromProcess()
-      : options.useTtyColors === "mock"
-        ? TypoSupport.mock()
-        : options.useTtyColors
-          ? TypoSupport.tty()
-          : TypoSupport.none();
-  const onLogStdOut = options?.onLogStdOut ?? console.log;
-  const onLogStdErr = options?.onLogStdErr ?? console.error;
-  const onExit = options?.onExit ?? process.exit;
   const commandFactory = command.createFactory(readerArgs);
   while (true) {
     try {
@@ -134,15 +119,24 @@ export async function runAsCliAndExit<Context>(
       }
     } catch (_) {}
   }
+  const onExit = options?.onExit ?? process.exit;
+  const typoSupport =
+    options?.useTtyColors === undefined
+      ? TypoSupport.inferFromProcess()
+      : options.useTtyColors === "mock"
+        ? TypoSupport.mock()
+        : options.useTtyColors
+          ? TypoSupport.tty()
+          : TypoSupport.none();
   if (usageOnHelp) {
     if (readerArgs.getOptionValues("--help" as any).length > 0) {
-      onLogStdOut(computeUsageString(cliName, commandFactory, typoSupport));
+      console.log(computeUsageString(cliName, commandFactory, typoSupport));
       return onExit(0);
     }
   }
   if (buildVersion) {
     if (readerArgs.getOptionValues("--version" as any).length > 0) {
-      onLogStdOut([cliName, buildVersion].join(" "));
+      console.log([cliName, buildVersion].join(" "));
       return onExit(0);
     }
   }
@@ -152,18 +146,18 @@ export async function runAsCliAndExit<Context>(
       await commandInstance.executeWithContext(context);
       return onExit(0);
     } catch (executionError) {
-      if (options?.onExecutionError) {
-        options.onExecutionError(executionError);
+      if (options?.onError) {
+        options.onError(executionError);
       } else {
-        onLogStdErr(typoSupport.computeStyledErrorMessage(executionError));
+        console.error(typoSupport.computeStyledErrorMessage(executionError));
       }
       return onExit(1);
     }
   } catch (parsingError) {
     if (options?.usageOnError ?? true) {
-      onLogStdErr(computeUsageString(cliName, commandFactory, typoSupport));
+      console.error(computeUsageString(cliName, commandFactory, typoSupport));
     }
-    onLogStdErr(typoSupport.computeStyledErrorMessage(parsingError));
+    console.error(typoSupport.computeStyledErrorMessage(parsingError));
     return onExit(1);
   }
 }

package/src/lib/Type.ts

@@ -84,6 +84,7 @@ export const typeBoolean: Type<boolean> = {
  * @example
  * ```ts
  * typeDate.decoder("2024-01-15") // → Date object for 2024-01-15
+ * typeDate.decoder("2024-01-15T13:45:30Z") // → Date object for 2024-01-15 13:45:30 UTC
  * typeDate.decoder("not a date") // throws TypoError
  * ```
  */

package/src/lib/Typo.ts

@@ -368,9 +368,8 @@ export class TypoError extends Error {
  * - {@link TypoSupport.inferFromProcess} — auto-detects based on `process.stdout.isTTY`
  *   and the `FORCE_COLOR` / `NO_COLOR` environment variables.
  *
- * `TypoSupport` is consumed by {@link runAsCliAndExit} (via the `useTtyColors` option)
- * and can also be used directly when building custom usage renderers with
- * {@link usageToStyledLines}.
+ * `TypoSupport` is consumed by {@link runAndExit} (via the `useTtyColors` option)
+ * and can also be used directly when building custom usage renderers with {@link usageToStyledLines}.
  */
 export class TypoSupport {
   #kind: "none" | "tty" | "mock";

package/src/lib/Usage.ts

@@ -39,8 +39,7 @@ import {
  * in each column sets the width for the entire section.
  *
  * @param params.cliName - The CLI program name shown at the start of the usage line.
- * @param params.commandUsage - The usage model produced by
- *   {@link CommandFactory.generateUsage}.
+ * @param params.commandUsage - The usage model produced by {@link CommandFactory.generateUsage}.
  * @param params.typoSupport - Controls color/styling of the output.
  * @returns An ordered array of strings, one per output line (including a trailing
  *   empty string for the blank line at the end).
@@ -50,7 +49,7 @@ import {
  * const lines = usageToStyledLines({
  *   cliName: "my-cli",
  *   commandUsage: commandFactory.generateUsage(),
- *   typoSupport: TypoSupport.none(),
+ *   typoSupport: TypoSupport.tty(),
  * });
  * process.stdout.write(lines.join("\n"));
  * ```

package/tests/unit.runner.cycle.ts

@@ -9,7 +9,7 @@ import {
   positionalOptional,
   positionalRequired,
   positionalVariadics,
-  runAsCliAndExit,
+  runAndExit,
   typeConverted,
   typeOneOf,
   typeString,
@@ -324,7 +324,7 @@ async function testCase(
         ],
       },
       async () => {
-        onLogStdOut.call("Has executed root command");
+        console.log("Has executed root command");
       },
     ),
     {
@@ -359,17 +359,17 @@ async function testCase(
             ],
           },
           async () => {
-            onLogStdOut.call("Has executed subcommand");
+            console.log("Has executed subcommand");
           },
         ),
       ),
     },
   );
-  await runAsCliAndExit("my-cli", args, null, cmd, {
+  console.log = onLogStdOut.call;
+  console.error = onLogStdErr.call;
+  await runAndExit("my-cli", args, null, cmd, {
     buildVersion: "1.0.0",
     useTtyColors: false,
-    onLogStdOut: onLogStdOut.call,
-    onLogStdErr: onLogStdErr.call,
     onExit: onExit.call,
   });
   expect({

package/tests/unit.runner.errors.ts

@@ -5,7 +5,7 @@ import {
   optionFlag,
   optionRepeatable,
   optionSingleValue,
-  runAsCliAndExit,
+  runAndExit,
   typeNumber,
   typeUrl,
 } from "../src";
@@ -34,43 +34,43 @@ it("run", async () => {
 });
 
 async function testCase(args: Array<string>, error: string) {
+  const onLogStdOut = makeMocked<string, void>([]);
   const onLogStdErr = makeMocked<string, void>([null as unknown as void]);
   const onExit = makeMocked<number, never>([null as never]);
-  await runAsCliAndExit(
-    "my-cli",
-    args,
-    null,
-    command<void, void>(
-      { description: "" },
-      operation(
-        {
-          options: {
-            optionFlag: optionFlag({ long: "flag" }),
-            optionSingleValue: optionSingleValue({
-              label: "LOCATION",
-              long: "single-value",
-              type: typeUrl,
-              default: () => undefined,
-            }),
-            optionRepeatable: optionRepeatable({
-              label: "INDEX",
-              long: "repeatable",
-              type: typeNumber,
-            }),
-          },
-          positionals: [],
+  const rootCommand = command<void, void>(
+    { description: "" },
+    operation(
+      {
+        options: {
+          optionFlag: optionFlag({
+            long: "flag",
+          }),
+          optionSingleValue: optionSingleValue({
+            label: "LOCATION",
+            long: "single-value",
+            type: typeUrl,
+            default: () => undefined,
+          }),
+          optionRepeatable: optionRepeatable({
+            label: "INDEX",
+            long: "repeatable",
+            type: typeNumber,
+          }),
         },
-        async (_, _inputs) => {},
-      ),
+        positionals: [],
+      },
+      async () => {},
     ),
-    {
-      buildVersion: "1.0.0",
-      usageOnError: false,
-      useTtyColors: "mock",
-      onLogStdErr: onLogStdErr.call,
-      onExit: onExit.call,
-    },
   );
+  console.log = onLogStdOut.call;
+  console.error = onLogStdErr.call;
+  await runAndExit("my-cli", args, null, rootCommand, {
+    buildVersion: "1.0.0",
+    usageOnError: false,
+    useTtyColors: "mock",
+    onExit: onExit.call,
+  });
+  expect(onLogStdOut.history).toEqual([]);
   expect(onLogStdErr.history).toEqual([error]);
   expect(onExit.history).toEqual([1]);
 }