cli-kiss 0.2.7 → 0.2.9

package/docs/.vitepress/config.mts

@@ -2,7 +2,7 @@ import { defineConfig } from "vitepress";
 
 export default defineConfig({
   description: "Full-featured TypeScript CLI builder. No bloat, no dependency.",
-  title: "cli-kiss 💋",
+  title: "cli-kiss",
   base: "/cli-kiss/",
   head: [
     ["link", { rel: "icon", href: "/cli-kiss/favicon.ico" }],

package/docs/.vitepress/theme/Layout.vue

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+import DefaultTheme from 'vitepress/theme'
+const { Layout } = DefaultTheme
+</script>
+
+<template>
+  <Layout>
+    <template #nav-bar-title-before>
+      <img
+        src="/logo.png"
+        alt="logo"
+        style="width:32px;height:32px;margin-right:8px;display:block;"
+      >
+    </template>
+  </Layout>
+</template>

package/docs/.vitepress/theme/index.ts

@@ -1,4 +1,8 @@
 import DefaultTheme from "vitepress/theme";
+import MyLayout from "./Layout.vue";
 import "./style.css";
 
-export default DefaultTheme;
+export default {
+  extends: DefaultTheme,
+  Layout: MyLayout,
+};

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

@@ -3,6 +3,10 @@
   --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-background-image: linear-gradient(
+    -50deg,
+    #ff003c88 25%,
+    #008732aa 60%
+  );
   --vp-home-hero-image-filter: blur(60px);
 }

package/docs/guide/01_getting_started.md

@@ -20,7 +20,7 @@ import {
   optionFlag,
   positionalRequired,
   runAndExit,
-  type,
+  typeString,
 } from "cli-kiss";
 
 const greetCommand = command(
@@ -32,7 +32,7 @@ const greetCommand = command(
       },
       positionals: [
         positionalRequired({
-          type: type("name"),
+          type: typeString("name"),
           description: "The name of the person to greet",
         }),
       ],

package/docs/guide/02_commands.md

@@ -12,7 +12,7 @@ const greet = command(
   operation(
     {
       options: {},
-      positionals: [positionalRequired({ type: type("name") })],
+      positionals: [positionalRequired({ type: typeString("name") })],
     },
     async function (_ctx, { positionals: [name] }) {
       console.log(`Hello, ${name}!`);
@@ -85,9 +85,9 @@ const authenticatedDeploy = commandChained(
       options: {
         token: optionSingleValue({
           long: "token",
-          type: type("secret"),
+          type: typeString("secret"),
           description: "API token",
-          defaultIfNotSpecified: function () {
+          fallbackValueIfAbsent: function () {
             const t = process.env.API_TOKEN;
             if (!t) throw new Error("API_TOKEN env var is required");
             return t;

package/docs/guide/03_options.md

@@ -44,7 +44,7 @@ const output = optionSingleValue({
   short: "o",
   type: typePath(),
   description: "Output directory",
-  defaultIfNotSpecified: () => "dist/",
+  fallbackValueIfAbsent: () => "dist/",
 });
 // --output dist/   →  "dist/"
 // --output=dist/   →  "dist/"
@@ -52,16 +52,16 @@ const output = optionSingleValue({
 // (absent)         →  "dist/"
 ```
 
-| 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                                                    |
-| `defaultIfNotSpecified` | `() => Value`         | Value when option is absent — **throw** to make it required                  |
-| `valueIfNothingInlined` | `() => Value?`        | Value when option is present but has no inline value (e.g. `--output` alone) |
-| `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                                                    |
+| `fallbackValueIfAbsent`    | `() => Value`         | Value when option is absent — **throw** to make it required                  |
+| `impliedValueIfNotInlined` | `() => Value?`        | Value when option is present but has no inline value (e.g. `--output` alone) |
+| `aliases`                  | `{ longs?, shorts? }` | Additional names                                                             |
 
 ## `optionRepeatable` — collect multiple values
 

package/docs/guide/04_positionals.md

@@ -9,7 +9,7 @@ Fails if missing.
 
 ```ts
 const name = positionalRequired({
-  type: type("person"),
+  type: typeString("person"),
   description: "The name of the person to greet",
 });
 // Usage:
@@ -29,7 +29,7 @@ Falls back to a default when absent.
 
 ```ts
 const greeting = positionalOptional({
-  type: type("greeting"),
+  type: typeString("greeting"),
   description: "Custom greeting",
   hint: "default to 'Hello'",
   default: () => "Hello",
@@ -66,7 +66,7 @@ Optionally stop collecting at a specific sentinel token:
 
 ```ts
 const args = positionalVariadics({
-  type: type("argument"),
+  type: typeString("argument"),
   endDelimiter: "STOP",
   description: "Arguments (end with STOP)",
 });
@@ -90,10 +90,10 @@ operation(
   {
     options: {},
     positionals: [
-      positionalRequired({ type: type("src") }),
-      positionalRequired({ type: type("dst") }),
-      positionalOptional({ type: type("tag"), default: () => "latest" }),
-      positionalVariadics({ type: type("extra") }),
+      positionalRequired({ type: typeString("src") }),
+      positionalRequired({ type: typeString("dst") }),
+      positionalOptional({ type: typeString("tag"), default: () => "latest" }),
+      positionalVariadics({ type: typeString("extra") }),
     ],
   },
   async function (_ctx, { positionals: [src, dst, tag, extras] }) {
@@ -101,6 +101,6 @@ operation(
   },
 );
 // 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"]
+//   my-cli in out  →  src="in", dst="out", tag="latest", extras=[]
+//   my-cli in out v2 a b c  →  src="in", dst="out", tag="v2", extras=["a","b","c"]
 ```

package/docs/guide/05_input_types.md

@@ -14,7 +14,7 @@ shown in help/errors.
 
 | Type factory   | Content type | Accepts                                                             |
 | -------------- | ------------ | ------------------------------------------------------------------- |
-| `type`         | `string`     | Any string                                                          |
+| `typeString`   | `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                                                |
@@ -23,7 +23,7 @@ shown in help/errors.
 | `typePath`     | `string`     | Non-empty path strings; optional sync existence check               |
 
 ```ts
-type("greeting").decoder("hello"); // → "hello"
+typeString("greeting").decoder("hello"); // → "hello"
 typeBoolean("flag").decoder("yes"); // → true
 typeNumber("pi").decoder("3.14"); // → 3.14
 typeInteger("id").decoder("9007199254740993"); // → 9007199254740993n
@@ -47,8 +47,7 @@ Accepts only a fixed set of strings (case-insensitive by default):
 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")
+typeEnv.decoder("unknown"); // Error: Invalid value: "unknown"
 ```
 
 Pass `true` as third argument to make matching case-sensitive.
@@ -58,15 +57,15 @@ Pass `true` as third argument to make matching case-sensitive.
 Splits a string into a fixed-length typed tuple:
 
 ```ts
-const typePoint = typeTuple([typeNumber(), typeNumber()]);
+const typePoint = typeTuple([typeNumber("a"), typeNumber("b")]);
 typePoint.decoder("3.14,2.71"); // → [3.14, 2.71]
-typePoint.decoder("x,2"); // → Error: at 0: Number: Unable to parse: "x"
+typePoint.decoder("x,2"); // → Error: at 0: a: Unable to parse: "x"
 ```
 
 The default separator is `","`. Pass a second argument to change it:
 
 ```ts
-typeTuple([type("name"), typeNumber()], ":");
+typeTuple([typeString("name"), typeNumber()], ":");
 // "foo:42"  →  ["foo", 42]
 ```
 
@@ -75,9 +74,9 @@ typeTuple([type("name"), typeNumber()], ":");
 Splits a string into an array of typed values:
 
 ```ts
-const typeNumbers = typeList(typeNumber());
+const typeNumbers = typeList(typeNumber("v"));
 typeNumbers.decoder("1,2,3"); // → [1, 2, 3]
-typeNumbers.decoder("1,x,3"); // → Error: at 1: Number: Unable to parse: "x"
+typeNumbers.decoder("1,x,3"); // → Error: at 1: v: Unable to parse: "x"
 ```
 
 Custom separator:
@@ -94,17 +93,19 @@ over `typeList` when users should pass multiple values as separate flags
 
 :::
 
-## `typeConverted` — transform decoded value
+## `typeMapped` — transformed 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");
+const typePort = typeMapped("port", typeNumber(), (n) => {
+  if (n < 1 || n > 65535) {
+    throw new Error("Out of range");
+  }
   return n;
 });
-// "--port 8080"   →  8080
-// "--port 99999"  →  throws
+typePort.decoder("8080"); // → 8080
+typePort.decoder("99999"); // → Error: Out of range
 ```
 
 ## `typeRenamed` — rename a type
@@ -129,6 +130,6 @@ const typeHexColor: Type<string> = {
     throw new Error(`Not a valid hex color: "${value}"`);
   },
 };
-// "#ff0000"  →  "#ff0000"
-// "red"  →  Error: HexColor: Not a valid value: "red"
+typeHexColor.decoder("#ff0000"); // → "#ff0000"
+typeHexColor.decoder("red"); // → Error: Not a valid hex color: "red"
 ```

package/docs/guide/06_run_as_cli.md

@@ -67,7 +67,7 @@ const rootCmd = commandWithSubcommands(
           long: "db",
           type: typeUrl(),
           description: "Database URL",
-          defaultIfNotSpecified: () => new URL("postgres://localhost/mydb"),
+          fallbackValueIfAbsent: () => new URL("postgres://localhost/mydb"),
         }),
       },
       positionals: [],

package/docs/index.md

@@ -2,7 +2,7 @@
 layout: home
 
 hero:
-  name: CLI-Kiss
+  name: CLI-kiss
   text: CLI for TypeScript.
 
   tagline:
@@ -10,7 +10,7 @@ hero:
     Simple and Stupid, it just does the job.
 
   image:
-    src: /hero.png
+    src: /logo.png
 
   actions:
     - theme: brand

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli-kiss",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "devDependencies": {

package/src/index.ts

@@ -4,7 +4,7 @@ export * from "./lib/Option";
 export * from "./lib/Positional";
 export * from "./lib/Reader";
 export * from "./lib/Run";
-export * from "./lib/Similarity";
+export * from "./lib/Suggest";
 export * from "./lib/Type";
 export * from "./lib/Typo";
 export * from "./lib/Usage";

package/src/lib/Command.ts

@@ -1,6 +1,6 @@
 import { Operation } from "./Operation";
 import { ReaderArgs } from "./Reader";
-import { similaritySort } from "./Similarity";
+import { suggestTextPushMessage } from "./Suggest";
 import {
   TypoError,
   TypoString,
@@ -17,7 +17,7 @@ import { UsageCommand } from "./Usage";
  * @typeParam Context - Injected at execution; forwarded to handlers.
  * @typeParam Result - Produced on execution; typically `void`.
  */
-export type Command<Context, Result> = {
+export type Command<Context, Result = void> = {
   /**
    * Returns static metadata.
    */
@@ -44,7 +44,7 @@ export type CommandDecoder<Context, Result> = {
   /**
    * Creates a ready-to-execute {@link CommandInterpreter}.
    *
-   * @throws {@link TypoError} if parsing or decoding failed.
+   * @throws if parsing or decoding failed.
    */
   decodeAndMakeInterpreter(): CommandInterpreter<Context, Result>;
 };
@@ -82,6 +82,7 @@ export type CommandInformation = {
    * Shown in the `Examples:` section.
    */
   examples?: Array<{
+    // TODO - a nicer example system, maybe with --help=example support
     /**
      * Explanation shown above the example.
      */
@@ -117,13 +118,13 @@ export type CommandInformation = {
  * const greet = command(
  *   { description: "Greet a user" },
  *   operation(
- *     { options: {}, positionals: [positionalRequired({ type: type("name") })] },
+ *     { positionals: [positionalRequired({ type: type("name") })] },
  *     async (_ctx, { positionals: [name] }) => console.log(`Hello, ${name}!`),
  *   ),
  * );
  * ```
  */
-export function command<Context, Result>(
+export function command<Context, Result = void>(
   information: CommandInformation,
   operation: Operation<Context, Result>,
 ): Command<Context, Result> {
@@ -136,12 +137,11 @@ export function command<Context, Result>(
         const operationDecoder = operation.consumeAndMakeDecoder(readerArgs);
         const endPositional = readerArgs.consumePositional();
         if (endPositional !== undefined) {
-          throw new TypoError(
-            new TypoText(
-              new TypoString(`Unexpected argument: `),
-              new TypoString(`"${endPositional}"`, typoStyleQuote),
-            ),
-          );
+          const errorText = new TypoText();
+          errorText.push(new TypoString(`Unexpected argument: `));
+          errorText.push(new TypoString(`"${endPositional}"`, typoStyleQuote));
+          errorText.push(new TypoString(`.`));
+          throw new TypoError(errorText);
         }
         return {
           generateUsage: () => generateUsageLeaf(information, operation),
@@ -168,7 +168,8 @@ export function command<Context, Result>(
 }
 
 /**
- * Creates a command that runs `operation` first, then dispatches to a named subcommand.
+ * Creates a command that runs `operation` first,
+ * then dispatches result to a named subcommand.
  *
  * @typeParam Context - Context accepted by `operation`.
  * @typeParam Payload - Output of `operation`; becomes the subcommand's context.
@@ -191,7 +192,7 @@ export function command<Context, Result>(
  * );
  * ```
  */
-export function commandWithSubcommands<Context, Payload, Result>(
+export function commandWithSubcommands<Context, Payload, Result = void>(
   information: CommandInformation,
   operation: Operation<Context, Payload>,
   subcommands: { [subcommand: string]: Command<Payload, Result> },
@@ -200,6 +201,11 @@ export function commandWithSubcommands<Context, Payload, Result>(
   if (subcommandNames.length === 0) {
     throw new Error("At least one subcommand is required");
   }
+  for (const name of subcommandNames) {
+    if (name.startsWith("-")) {
+      throw new Error(`Subcommand name "${name}" cannot start with "-".`);
+    }
+  }
   return {
     getInformation() {
       return information;
@@ -209,30 +215,22 @@ export function commandWithSubcommands<Context, Payload, Result>(
         const operationDecoder = operation.consumeAndMakeDecoder(readerArgs);
         const subcommandName = readerArgs.consumePositional();
         if (subcommandName === undefined) {
-          throw new TypoError(
-            new TypoText(
-              new TypoString(`<subcommand>`, typoStyleUserInput),
-              new TypoString(`: Is required, but was not provided`),
-            ),
-          );
+          const errorText = new TypoText();
+          errorText.push(new TypoString(`Missing argument: `));
+          errorText.push(new TypoString(`<subcommand>`, typoStyleUserInput));
+          errorText.push(new TypoString(`.`));
+          suggestSubcommandNames(errorText, "", subcommandNames);
+          throw new TypoError(errorText);
         }
         const subcommandInput = subcommands[subcommandName];
         if (subcommandInput === undefined) {
-          const text = new TypoText();
-          text.push(new TypoString(`<subcommand>`, typoStyleUserInput));
-          text.push(new TypoString(`: Unknown name: `));
-          text.push(new TypoString(`"${subcommandName}"`, typoStyleQuote));
-          const suggestions = similaritySort(
-            subcommandName,
-            subcommandNames.map((subcommandName) => ({
-              key: subcommandName,
-              value: new TypoString(subcommandName, typoStyleConstants),
-            })),
-          ).slice(0, 3);
-          text.push(new TypoString(`: did you mean: `));
-          text.push(TypoText.join(suggestions, new TypoString(`, `)));
-          text.push(new TypoString(` ?`));
-          throw new TypoError(text);
+          const errorText = new TypoText();
+          errorText.push(new TypoString(`<subcommand>`, typoStyleUserInput));
+          errorText.push(new TypoString(`: Unknown name: `));
+          errorText.push(new TypoString(`"${subcommandName}"`, typoStyleQuote));
+          errorText.push(new TypoString(`.`));
+          suggestSubcommandNames(errorText, subcommandName, subcommandNames);
+          throw new TypoError(errorText);
         }
         const subcommandDecoder =
           subcommandInput.consumeAndMakeDecoder(readerArgs);
@@ -283,8 +281,8 @@ export function commandWithSubcommands<Context, Payload, Result>(
 }
 
 /**
- * Chains an {@link Operation} and a {@link Command}: `operation` runs first, its
- * output becomes `subcommand`'s context. No token is consumed for routing.
+ * Chains an {@link Operation} and a {@link Command}: `operation` runs first,
+ * its output becomes `subcommand`'s context. No token is consumed for routing.
  *
  * @typeParam Context - Context accepted by `operation`.
  * @typeParam Payload - Output of `operation`; becomes `subcommand`'s context.
@@ -295,7 +293,7 @@ export function commandWithSubcommands<Context, Payload, Result>(
  * @param subcommand - Runs after `operation`.
  * @returns A {@link Command} composing both stages.
  */
-export function commandChained<Context, Payload, Result>(
+export function commandChained<Context, Payload, Result = void>(
   information: CommandInformation,
   operation: Operation<Context, Payload>,
   subcommand: Command<Payload, Result>,
@@ -355,12 +353,25 @@ function generateUsageLeaf(
 ): UsageCommand {
   const { positionals, options } = operation.generateUsage();
   return {
-    segments: positionals.map((positional) => ({
-      positional: positional.label,
-    })),
+    segments: positionals.map((p) => ({ positional: p.label })),
     information,
     positionals,
     subcommands: [],
     options,
   };
 }
+
+function suggestSubcommandNames(
+  errorText: TypoText,
+  input: string,
+  subcommandNames: Array<string> = [],
+) {
+  suggestTextPushMessage(
+    errorText,
+    input,
+    subcommandNames.map((subcommandName) => ({
+      reference: subcommandName,
+      hint: new TypoString(subcommandName, typoStyleConstants),
+    })),
+  );
+}

package/src/lib/Operation.ts

@@ -12,7 +12,7 @@ import { UsageOption, UsagePositional } from "./Usage";
  * @typeParam Context - Injected at execution; forwarded to handlers.
  * @typeParam Result - Value produced on execution; typically `void`.
  */
-export type Operation<Context, Result> = {
+export type Operation<Context, Result = void> = {
   /**
    * Returns usage metadata without consuming any arguments.
    */
@@ -44,7 +44,7 @@ export type OperationDecoder<Context, Result> = {
   /**
    * Creates a ready-to-execute {@link OperationInterpreter}.
    *
-   * @throws {@link TypoError} if parsing or decoding failed.
+   * @throws if parsing or decoding failed.
    */
   decodeAndMakeInterpreter(): OperationInterpreter<Context, Result>;
 };
@@ -99,55 +99,71 @@ export type OperationInterpreter<Context, Result> = {
 export function operation<
   Context,
   Result,
-  Options extends { [option: string]: any },
-  const Positionals extends Array<any>,
+  const Options extends { [option: string]: any } = {},
+  const Positionals extends Array<any> = [],
 >(
   inputs: {
-    options: { [K in keyof Options]: Option<Options[K]> };
-    positionals: { [K in keyof Positionals]: Positional<Positionals[K]> };
+    options?: { [K in keyof Options]: Option<Options[K]> };
+    positionals?: { [K in keyof Positionals]: Positional<Positionals[K]> };
   },
   handler: (
     context: Context,
     inputs: {
-      options: Options;
-      positionals: Positionals;
+      options: { [K in keyof Options]: Options[K] };
+      positionals: { [K in keyof Positionals]: Positionals[K] };
     },
   ) => Promise<Result>,
 ): Operation<Context, Result> {
   return {
     generateUsage() {
       const optionsUsage = new Array<UsageOption>();
-      for (const optionKey in inputs.options) {
-        const optionInput = inputs.options[optionKey]!;
-        optionsUsage.push(optionInput.generateUsage());
+      if (inputs.options !== undefined) {
+        for (const optionKey in inputs.options) {
+          const optionInput = inputs.options[optionKey]!;
+          optionsUsage.push(optionInput.generateUsage());
+        }
       }
       const positionalsUsage = new Array<UsagePositional>();
-      for (const positionalInput of inputs.positionals) {
-        positionalsUsage.push(positionalInput.generateUsage());
+      if (inputs.positionals !== undefined) {
+        for (const positionalInput of inputs.positionals) {
+          positionalsUsage.push(positionalInput.generateUsage());
+        }
       }
       return { options: optionsUsage, positionals: positionalsUsage };
     },
     consumeAndMakeDecoder(readerArgs: ReaderArgs) {
-      const optionsDecoders: Record<string, OptionDecoder<any>> = {};
-      for (const optionKey in inputs.options) {
-        const optionInput = inputs.options[optionKey]!;
-        optionsDecoders[optionKey] =
-          optionInput.registerAndMakeDecoder(readerArgs);
+      const optionsDecoders = {} as {
+        [K in keyof Options]: OptionDecoder<Options[K]>;
+      };
+      if (inputs.options !== undefined) {
+        for (const optionKey in inputs.options) {
+          const optionInput = inputs.options[optionKey]!;
+          optionsDecoders[optionKey] =
+            optionInput.registerAndMakeDecoder(readerArgs);
+        }
       }
-      const positionalsDecoders: Array<PositionalDecoder<any>> = [];
-      for (const positionalInput of inputs.positionals) {
-        positionalsDecoders.push(
-          positionalInput.consumeAndMakeDecoder(readerArgs),
-        );
+      const positionalsDecoders = [] as {
+        [K in keyof Positionals]: PositionalDecoder<Positionals[K]>;
+      };
+      if (inputs.positionals !== undefined) {
+        for (const positionalInput of inputs.positionals) {
+          positionalsDecoders.push(
+            positionalInput.consumeAndMakeDecoder(readerArgs),
+          );
+        }
       }
       return {
         decodeAndMakeInterpreter() {
-          const optionsValues: any = {};
+          const optionsValues = {} as {
+            [K in keyof Options]: Options[K];
+          };
           for (const optionKey in optionsDecoders) {
             optionsValues[optionKey] =
               optionsDecoders[optionKey]!.getAndDecodeValue();
           }
-          const positionalsValues: any = [];
+          const positionalsValues = [] as {
+            [K in keyof Positionals]: Positionals[K];
+          };
           for (const positionalDecoder of positionalsDecoders) {
             positionalsValues.push(positionalDecoder.decodeValue());
           }