cli-kiss 0.2.5 → 0.2.6

package/docs/.vitepress/config.mts

@@ -28,8 +28,8 @@ export default defineConfig({
           { 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" },
+          { text: "Input Types", link: "/guide/05_input_types" },
+          { text: "Running your CLI", link: "/guide/06_run_as_cli" },
         ],
       },
     ],

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

@@ -1,4 +1,8 @@
 :root {
-  --vp-home-hero-image-background-image: linear-gradient( -50deg, #ff003cff 0%, #00000000 50%, #459900ff 100% );
-  --vp-home-hero-image-filter: blur(150px);
+  /*
+  --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-filter: blur(60px);
 }

package/docs/guide/{05_types.md → 05_input_types.md}

@@ -1,23 +1,26 @@
-# Types
+# Input Types
 
 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.
 
+A `Type<Value>` can then be used as a value for an `Option` or `Positional`
+
 ## Built-in types
 
-All type factories accept an optional `name` parameter that overrides the label shown in help/errors.
+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                        |
+| Type factory   | Content type | Accepts                                                             |
+| -------------- | ------------ | ------------------------------------------------------------------- |
+| `type`         | `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                                                |
+| `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
 type("greeting").decoder("hello"); // → "hello"
@@ -32,8 +35,8 @@ typePath().decoder("/usr/bin"); // → "/usr/bin"
 `typePath` also accepts a second argument for existence checks:
 
 ```ts
-typePath("config", { checkSyncExistAs: "file" });     // throws if not a file
-typePath("dir",    { checkSyncExistAs: "directory" }); // throws if not a directory
+typePath("config", { checkSyncExistAs: "file" }); // throws if not a file
+typePath("dir", { checkSyncExistAs: "directory" }); // throws if not a directory
 ```
 
 ## `typeChoice` — string enum
@@ -101,7 +104,7 @@ const typePort = typeConverted("port", typeNumber(), (n) => {
   return n;
 });
 // "--port 8080"   →  8080
-// "--port 99999"  →  TypoError
+// "--port 99999"  →  throws
 ```
 
 ## `typeRenamed` — rename a type
@@ -109,8 +112,7 @@ const typePort = typeConverted("port", typeNumber(), (n) => {
 Wraps a type with a different label for clearer errors:
 
 ```ts
-const typeId = typeRenamed(typeInteger(), "user-id");
-// errors show "user-id" instead of "integer"
+const typeUserId = typeRenamed(typeInteger("u64"), "user-id");
 ```
 
 ## Custom types
@@ -124,7 +126,7 @@ const typeHexColor: Type<string> = {
     if (/^#[0-9a-fA-F]{6}$/.test(value)) {
       return value;
     }
-    throw new Error(`Not a valid color: "${value}"`);
+    throw new Error(`Not a valid hex color: "${value}"`);
   },
 };
 // "#ff0000"  →  "#ff0000"

package/docs/guide/{06_run.md → 06_run_as_cli.md}

@@ -18,14 +18,14 @@ await runAndExit(cliName, cliArgs, context, command, options?);
 
 ### 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                                                   |
-| `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                                                                        |
+| 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` | `"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
 
@@ -118,17 +118,12 @@ Colors are auto-detected by default (`colorSetup: "flag"` adds a `--color`
 option). Override:
 
 ```ts
+// Read from env vars (FORCE_COLOR, NO_COLOR), same as `--color=auto`
+await runAndExit("my-cli", args, ctx, cmd, { colorSetup: "env" });
 // Force colors on
 await runAndExit("my-cli", args, ctx, cmd, { colorSetup: "always" });
-
 // Force colors off (useful in CI)
 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, { colorSetup: "mock" });
 ```
 
 ## Testing your CLI

package/docs/index.md

@@ -2,11 +2,12 @@
 layout: home
 
 hero:
-  name: CLI-kiss
+  name: CLI-Kiss
   text: CLI for TypeScript.
 
   tagline:
-    No bloat, no dependencies.<br/>Standard behavior users expect.<br/>Keep It Simple and Stupid, 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

package/package.json

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

package/src/lib/Run.ts

@@ -5,6 +5,11 @@ import { typeChoice } from "./Type";
 import { TypoSupport } from "./Typo";
 import { usageToStyledLines } from "./Usage";
 
+/**
+ * Color selection modes availables
+ */
+export type RunColorMode = "env" | "always" | "never" | "mock";
+
 /**
  * Main entry point: parses CLI arguments, executes the matched command, and exits.
  * Handles `--help`, `--version`, usage-on-error, and exit codes.
@@ -53,7 +58,7 @@ export async function runAndExit<Context>(
   context: Context,
   command: Command<Context, void>,
   options?: {
-    colorSetup?: "flag" | "env" | "always" | "never" | "mock" | undefined;
+    colorSetup?: "flag" | RunColorMode | undefined;
     usageOnHelp?: boolean | undefined;
     usageOnError?: boolean | undefined;
     buildVersion?: string | undefined;
@@ -68,14 +73,12 @@ export async function runAndExit<Context>(
   let typoSupport = TypoSupport.none();
   const colorSetup = options?.colorSetup ?? "flag";
   if (colorSetup === "flag") {
-    const colorOption = optionSingleValue<"auto" | "always" | "never" | "mock">(
-      {
-        long: "color",
-        type: typeChoice("color-mode", ["auto", "always", "never", "mock"]),
-        defaultWhenNotDefined: () => "auto",
-        defaultWhenNotInlined: () => "always",
-      },
-    ).registerAndMakeDecoder(readerArgs);
+    const colorOption = optionSingleValue<"auto" | RunColorMode>({
+      long: "color",
+      type: typeChoice("color-mode", ["auto", "always", "never", "mock"]),
+      defaultWhenNotDefined: () => "auto",
+      defaultWhenNotInlined: () => "always",
+    }).registerAndMakeDecoder(readerArgs);
     preprocessors.push(() => {
       try {
         typoSupport = computeTypoSupport(colorOption.getAndDecodeValue());
@@ -86,11 +89,7 @@ export async function runAndExit<Context>(
       return undefined;
     });
   } else {
-    if (colorSetup === "env") {
-      typoSupport = TypoSupport.inferFromEnv();
-    } else {
-      typoSupport = computeTypoSupport(colorSetup);
-    }
+    typoSupport = computeTypoSupport(colorSetup);
   }
   if (options?.usageOnHelp ?? true) {
     const helpOption = optionFlag({ long: "help" }).registerAndMakeDecoder(
@@ -182,12 +181,12 @@ function computeUsageString<Context, Result>(
   }).join("\n");
 }
 
-function computeTypoSupport(
-  colorMode: "auto" | "always" | "never" | "mock",
-): TypoSupport {
+function computeTypoSupport(colorMode: "auto" | RunColorMode): TypoSupport {
   switch (colorMode) {
     case "auto":
       return TypoSupport.inferFromEnv();
+    case "env":
+      return TypoSupport.inferFromEnv();
     case "always":
       return TypoSupport.tty();
     case "never":

package/src/lib/Type.ts

@@ -51,23 +51,19 @@ export function typeBoolean(name?: string): Type<boolean> {
     content: name ?? "boolean",
     decoder(input: string) {
       const lower = input.toLowerCase();
-      if (booleanValuesTrue.has(lower)) {
+      if (typeBooleanValuesTrue.has(lower)) {
         return true;
       }
-      if (booleanValuesFalse.has(lower)) {
+      if (typeBooleanValuesFalse.has(lower)) {
         return false;
       }
-      throw new TypoError(
-        new TypoText(
-          new TypoString(`Not a boolean: `),
-          new TypoString(`"${input}"`, typoStyleQuote),
-        ),
-      );
+      throwInvalidValue("a boolean", input);
     },
   };
 }
-const booleanValuesTrue = new Set(["true", "yes", "on", "1", "y", "t"]);
-const booleanValuesFalse = new Set(["false", "no", "off", "0", "n", "f"]);
+
+export const typeBooleanValuesTrue = new Set(["true", "yes", "on", "y"]);
+export const typeBooleanValuesFalse = new Set(["false", "no", "off", "n"]);
 
 /**
  * Parses a date/time string via `Date.parse`.
@@ -91,12 +87,7 @@ export function typeDatetime(name?: string): Type<Date> {
         }
         return new Date(timestampMs);
       } catch {
-        throw new TypoError(
-          new TypoText(
-            new TypoString(`Not a valid ISO_8601 datetime: `),
-            new TypoString(`"${input}"`, typoStyleQuote),
-          ),
-        );
+        throwInvalidValue("a valid ISO_8601 datetime", input);
       }
     },
   };
@@ -109,7 +100,7 @@ export function typeDatetime(name?: string): Type<Date> {
  * ```ts
  * typeNumber("my-number").decoder("3.14")  // → 3.14
  * typeNumber("my-number").decoder("-1")    // → -1
- * typeNumber("my-number").decoder("hello") // throws TypoError
+ * typeNumber("my-number").decoder("hello") // throws
  * ```
  */
 export function typeNumber(name?: string): Type<number> {
@@ -123,12 +114,7 @@ export function typeNumber(name?: string): Type<number> {
         }
         return parsed;
       } catch {
-        throw new TypoError(
-          new TypoText(
-            new TypoString(`Not a number: `),
-            new TypoString(`"${input}"`, typoStyleQuote),
-          ),
-        );
+        throwInvalidValue("a number", input);
       }
     },
   };
@@ -141,8 +127,8 @@ export function typeNumber(name?: string): Type<number> {
  * @example
  * ```ts
  * typeInteger("my-integer").decoder("42")   // → 42n
- * typeInteger("my-integer").decoder("3.14") // throws TypoError
- * typeInteger("my-integer").decoder("abc")  // throws TypoError
+ * typeInteger("my-integer").decoder("3.14") // throws
+ * typeInteger("my-integer").decoder("abc")  // throws
  * ```
  */
 export function typeInteger(name?: string): Type<bigint> {
@@ -152,12 +138,7 @@ export function typeInteger(name?: string): Type<bigint> {
       try {
         return BigInt(input);
       } catch {
-        throw new TypoError(
-          new TypoText(
-            new TypoString(`Not an integer: `),
-            new TypoString(`"${input}"`, typoStyleQuote),
-          ),
-        );
+        throwInvalidValue("an integer", input);
       }
     },
   };
@@ -170,7 +151,7 @@ export function typeInteger(name?: string): Type<bigint> {
  * @example
  * ```ts
  * typeUrl("my-url").decoder("https://example.com") // → URL { href: "https://example.com/", ... }
- * typeUrl("my-url").decoder("not-a-url")           // throws TypoError
+ * typeUrl("my-url").decoder("not-a-url")           // throws
  * ```
  */
 export function typeUrl(name?: string): Type<URL> {
@@ -180,12 +161,7 @@ export function typeUrl(name?: string): Type<URL> {
       try {
         return new URL(input);
       } catch {
-        throw new TypoError(
-          new TypoText(
-            new TypoString(`Not an URL: `),
-            new TypoString(`"${input}"`, typoStyleQuote),
-          ),
-        );
+        throwInvalidValue("an URL", input);
       }
     },
   };
@@ -296,7 +272,20 @@ export function typePath(
         throw new Error(`Path cannot contain null characters`);
       }
       if (checks?.checkSyncExistAs !== undefined) {
-        const stats = statSync(input);
+        function safeStatSync(path: string) {
+          try {
+            return statSync(path);
+          } catch (error) {
+            throw new TypoError(
+              new TypoText(
+                new TypoString(`Path does not exist: `),
+                new TypoString(`"${path}"`, typoStyleQuote),
+              ),
+              error,
+            );
+          }
+        }
+        const stats = safeStatSync(input);
         const preview = stats.isDirectory()
           ? "directory"
           : stats.isFile()
@@ -305,7 +294,7 @@ export function typePath(
         if (checks.checkSyncExistAs === "file" && !stats.isFile()) {
           throw new TypoError(
             new TypoText(
-              new TypoString(`Expected a 'file' but found '${preview}': `),
+              new TypoString(`Expected a file but found: ${preview}: `),
               new TypoString(`"${input}"`, typoStyleQuote),
             ),
           );
@@ -313,7 +302,7 @@ export function typePath(
         if (checks.checkSyncExistAs === "directory" && !stats.isDirectory()) {
           throw new TypoError(
             new TypoText(
-              new TypoString(`Expected a 'directory' but found '${preview}': `),
+              new TypoString(`Expected a directory but found: ${preview}: `),
               new TypoString(`"${input}"`, typoStyleQuote),
             ),
           );
@@ -474,3 +463,12 @@ export function typeList<Value>(
     },
   };
 }
+
+function throwInvalidValue(kind: string, input: string): never {
+  throw new TypoError(
+    new TypoText(
+      new TypoString(`Not ${kind}: `),
+      new TypoString(`"${input}"`, typoStyleQuote),
+    ),
+  );
+}

package/src/lib/Typo.ts

@@ -1,3 +1,5 @@
+import { typeBooleanValuesFalse } from "./Type";
+
 /**
  * Color names for terminal styling, used by {@link TypoStyle}.
  * `dark*` = standard ANSI (30–37); `bright*` = high-intensity (90–97).
@@ -358,27 +360,38 @@ export class TypoSupport {
    * Auto-detects styling mode from the process environment on best-effort basis.
    */
   static inferFromEnv(): TypoSupport {
-    if (!process || !process.env) {
+    /*
+    console.warn({
+      no: readEnvVar("NO_COLOR"),
+      force: readEnvVar("FORCE_COLOR"),
+      mock: readEnvVar("MOCK_COLOR"),
+      term: readEnvVar("TERM"),
+      tty: process.stdout.isTTY,
+    });
+    */
+    if (!process || !process.env || !process.stdout) {
       return TypoSupport.none();
     }
-    function readEnvVar(name: string) {
-      if (!(name in process.env)) {
-        return undefined;
-      }
-      return process.env[name];
+    if (readEnvVar("NO_COLOR")) {
+      return TypoSupport.none();
     }
     const envForceColor = readEnvVar("FORCE_COLOR");
     if (envForceColor === "0") {
       return TypoSupport.none();
     }
     if (envForceColor !== undefined) {
-      TypoSupport.tty();
+      if (!typeBooleanValuesFalse.has(envForceColor.toLowerCase())) {
+        return TypoSupport.tty();
+      }
+    }
+    if (readEnvVar("MOCK_COLOR")) {
+      return TypoSupport.mock();
     }
-    if (readEnvVar("NO_COLOR") !== undefined) {
+    if (!process.stdout.isTTY) {
       return TypoSupport.none();
     }
-    if (readEnvVar("MOCK_COLOR") !== undefined) {
-      return TypoSupport.mock();
+    if (readEnvVar("TERM")?.toLowerCase() === "dumb") {
+      return TypoSupport.none();
     }
     return TypoSupport.tty();
   }
@@ -496,3 +509,10 @@ const ttyCodeBgColors: Record<TypoColor, string> = {
   brightCyan: "\x1b[106m",
   brightWhite: "\x1b[107m",
 };
+
+function readEnvVar(name: string) {
+  if (!(name in process.env)) {
+    return undefined;
+  }
+  return process.env[name];
+}

package/src/lib/Usage.ts

@@ -116,16 +116,16 @@ export type UsageOption = {
  * <detail lines...>
  *
  * Positionals:
- *   <LABEL>  <description> (<hint>)
+ *   <label>  <description> (<hint>)
  *
  * Subcommands:
  *   <name>  <description> (<hint>)
  *
  * Options:
- *   -s, --long <LABEL><annotation>  <description> (<hint>)
+ *   -s, --long <label><annotation>  <description> (<hint>)
  *
  * Examples:
- *   <description>
+ *   <explanation>
  *   <command line>
  *
  * ```