cli-kiss 0.2.6 → 0.2.8

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/02_commands.md

@@ -87,7 +87,7 @@ const authenticatedDeploy = commandChained(
           long: "token",
           type: type("secret"),
           description: "API token",
-          defaultWhenNotDefined: 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",
-  defaultWhenNotDefined: () => "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                                                    |
-| `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                                                             |
+| 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/05_input_types.md

@@ -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,9 +57,9 @@ 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:
@@ -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:
@@ -103,8 +102,8 @@ 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
+typePort.decoder("8080"); // → 8080
+typePort.decoder("99999"); // → Error: Out of range
 ```
 
 ## `typeRenamed` — rename a type
@@ -129,6 +128,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",
-          defaultWhenNotDefined: () => 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.6",
+  "version": "0.2.8",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "devDependencies": {

package/src/index.ts

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

package/src/lib/Command.ts

@@ -1,8 +1,10 @@
 import { Operation } from "./Operation";
 import { ReaderArgs } from "./Reader";
+import { suggestTextPushMessage } from "./Suggest";
 import {
   TypoError,
   TypoString,
+  typoStyleConstants,
   typoStyleQuote,
   typoStyleUserInput,
   TypoText,
@@ -42,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>;
 };
@@ -80,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.
      */
@@ -115,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> {
@@ -134,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),
@@ -166,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.
@@ -189,11 +192,16 @@ 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> },
 ): Command<Context, Result> {
+  // TODO - forbid subcommands that start with a "-" ?
+  const subcommandNames = Object.keys(subcommands);
+  if (subcommandNames.length === 0) {
+    throw new Error("At least one subcommand is required");
+  }
   return {
     getInformation() {
       return information;
@@ -203,22 +211,21 @@ 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(`<subcommand>`, typoStyleUserInput));
+          errorText.push(new TypoString(`: Missing argument.`));
+          suggestSubcommandNames(errorText, "", subcommandNames);
+          throw new TypoError(errorText);
         }
         const subcommandInput = subcommands[subcommandName];
         if (subcommandInput === undefined) {
-          throw new TypoError(
-            new TypoText(
-              new TypoString(`<subcommand>`, typoStyleUserInput),
-              new TypoString(`: Invalid value: `),
-              new TypoString(`"${subcommandName}"`, typoStyleQuote),
-            ),
-          );
+          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);
@@ -269,8 +276,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.
@@ -281,7 +288,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>,
@@ -341,12 +348,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

@@ -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>;
 };
@@ -83,7 +83,7 @@ export type OperationInterpreter<Context, Result> = {
  * const greetOperation = operation(
  *   {
  *     options: {
- *       loud: optionFlag({ long: "loud", description: "Print in uppercase", default: false }),
+ *       loud: optionFlag({ long: "loud", description: "Print in uppercase" }),
  *     },
  *     positionals: [
  *       positionalRequired({ type: type("name"), description: "Name to greet" }),
@@ -99,46 +99,54 @@ 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);
+      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),
-        );
+      if (inputs.positionals !== undefined) {
+        for (const positionalInput of inputs.positionals) {
+          positionalsDecoders.push(
+            positionalInput.consumeAndMakeDecoder(readerArgs),
+          );
+        }
       }
       return {
         decodeAndMakeInterpreter() {