cli-kiss 0.2.4 → 0.2.5

package/docs/guide/06_run.md

@@ -8,24 +8,24 @@
 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` | `Command<Context, void>`           | The root command                                  |
-| `options` | `object?`                          | See below                                         |
+| Parameter | Type                     | Description                                       |
+| --------- | ------------------------ | ------------------------------------------------- |
+| `cliName` | `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` | `Command<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 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"\|"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                                                                        |
 
 ### Exit codes
 
@@ -37,18 +37,6 @@ await runAndExit(cliName, cliArgs, context, command, options?);
 ## Full example
 
 ```ts
-import {
-  command,
-  commandWithSubcommands,
-  operation,
-  optionFlag,
-  optionSingleValue,
-  positionalRequired,
-  runAndExit,
-  typeString,
-  typeUrl,
-} from "cli-kiss";
-
 type Ctx = { db: string };
 
 const deployCmd = command(
@@ -77,9 +65,9 @@ const rootCmd = commandWithSubcommands(
       options: {
         dbUrl: optionSingleValue({
           long: "db",
-          type: typeUrl,
+          type: typeUrl(),
           description: "Database URL",
-          default: () => new URL("postgres://localhost/mydb"),
+          defaultWhenNotDefined: () => new URL("postgres://localhost/mydb"),
         }),
       },
       positionals: [],
@@ -103,7 +91,7 @@ my-cli --help
 ```
 
 ```text
-Usage: my-cli <SUBCOMMAND>
+Usage: my-cli <subcommand>
 
 My deployment CLI
 
@@ -111,7 +99,7 @@ Subcommands:
   deploy  Deploy to production
 
 Options:
-  --db <URL>  Database URL
+  --db <url>  Database URL
 ```
 
 Try it
@@ -126,17 +114,21 @@ my-cli deploy --dry-run
 
 ## Color control
 
-Colors are auto-detected. Override:
+Colors are auto-detected by default (`colorSetup: "flag"` adds a `--color`
+option). Override:
 
 ```ts
 // Force colors on
-await runAndExit("my-cli", args, ctx, cmd, { useTtyColors: true });
+await runAndExit("my-cli", args, ctx, cmd, { colorSetup: "always" });
 
 // Force colors off (useful in CI)
-await runAndExit("my-cli", args, ctx, cmd, { useTtyColors: false });
+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, { useTtyColors: "mock" });
+await runAndExit("my-cli", args, ctx, cmd, { colorSetup: "mock" });
 ```
 
 ## Testing your CLI
@@ -144,17 +136,13 @@ await runAndExit("my-cli", args, ctx, cmd, { useTtyColors: "mock" });
 Override `onExit` to prevent process exit during tests:
 
 ```ts
-import { runAndExit } from "cli-kiss";
-
 const exitCodes: number[] = [];
-
 await runAndExit("my-cli", ["--help"], undefined, myCommand, {
-  useTtyColors: false,
+  colorSetup: "never",
   onExit: (code) => {
     exitCodes.push(code);
     return undefined as never;
   },
 });
-
 console.assert(exitCodes[0] === 0, "expected exit 0 for --help");
 ```

package/package.json

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

package/src/index.ts

@@ -7,5 +7,3 @@ export * from "./lib/Run";
 export * from "./lib/Type";
 export * from "./lib/Typo";
 export * from "./lib/Usage";
-
-// TODO - maybe add a parsed option recap on error

package/src/lib/Command.ts

@@ -7,7 +7,7 @@ import {
   typoStyleUserInput,
   TypoText,
 } from "./Typo";
-import { UsageCommand, UsageSegment } from "./Usage";
+import { UsageCommand } from "./Usage";
 
 /**
  * A CLI command. Created with {@link command}, {@link commandWithSubcommands}, or {@link commandChained}.
@@ -93,8 +93,8 @@ export type CommandInformation = {
       | { subcommand: string }
       | {
           option:
-            | { long: string; value?: string }
-            | { short: string; value?: string };
+            | { long: string; inlined?: string; separated?: Array<string> }
+            | { short: string; inlined?: string; separated?: Array<string> };
         }
     >;
   }>;
@@ -115,7 +115,7 @@ export type CommandInformation = {
  * const greet = command(
  *   { description: "Greet a user" },
  *   operation(
- *     { options: {}, positionals: [positionalRequired({ type: typeString, label: "NAME" })] },
+ *     { options: {}, positionals: [positionalRequired({ type: type("name") })] },
  *     async (_ctx, { positionals: [name] }) => console.log(`Hello, ${name}!`),
  *   ),
  * );
@@ -192,7 +192,7 @@ export function command<Context, Result>(
 export function commandWithSubcommands<Context, Payload, Result>(
   information: CommandInformation,
   operation: Operation<Context, Payload>,
-  subcommands: { [subcommand: Lowercase<string>]: Command<Payload, Result> },
+  subcommands: { [subcommand: string]: Command<Payload, Result> },
 ): Command<Context, Result> {
   return {
     getInformation() {
@@ -205,17 +205,16 @@ export function commandWithSubcommands<Context, Payload, Result>(
         if (subcommandName === undefined) {
           throw new TypoError(
             new TypoText(
-              new TypoString(`<SUBCOMMAND>`, typoStyleUserInput),
+              new TypoString(`<subcommand>`, typoStyleUserInput),
               new TypoString(`: Is required, but was not provided`),
             ),
           );
         }
-        const subcommandInput =
-          subcommands[subcommandName as Lowercase<string>];
+        const subcommandInput = subcommands[subcommandName];
         if (subcommandInput === undefined) {
           throw new TypoError(
             new TypoText(
-              new TypoString(`<SUBCOMMAND>`, typoStyleUserInput),
+              new TypoString(`<subcommand>`, typoStyleUserInput),
               new TypoString(`: Invalid value: `),
               new TypoString(`"${subcommandName}"`, typoStyleQuote),
             ),
@@ -227,7 +226,7 @@ export function commandWithSubcommands<Context, Payload, Result>(
           generateUsage() {
             const subcommandUsage = subcommandDecoder.generateUsage();
             const currentUsage = generateUsageLeaf(information, operation);
-            currentUsage.segments.push(segmentSubcommand(subcommandName));
+            currentUsage.segments.push({ subcommand: subcommandName });
             currentUsage.segments.push(...subcommandUsage.segments);
             currentUsage.information = subcommandUsage.information;
             currentUsage.positionals.push(...subcommandUsage.positionals);
@@ -253,7 +252,7 @@ export function commandWithSubcommands<Context, Payload, Result>(
         return {
           generateUsage() {
             const currentUsage = generateUsageLeaf(information, operation);
-            currentUsage.segments.push(segmentPositional("<SUBCOMMAND>"));
+            currentUsage.segments.push({ positional: "<subcommand>" });
             for (const [name, subcommand] of Object.entries(subcommands)) {
               const { description, hint } = subcommand.getInformation();
               currentUsage.subcommands.push({ name, description, hint });
@@ -281,18 +280,6 @@ export function commandWithSubcommands<Context, Payload, Result>(
  * @param operation - Runs first; output becomes `subcommand`'s context.
  * @param subcommand - Runs after `operation`.
  * @returns A {@link Command} composing both stages.
- *
- * @example
- * ```ts
- * const authenticatedDeploy = commandChained(
- *   { description: "Authenticate then deploy" },
- *   operation(
- *     { options: { token: optionSingleValue({ long: "token", type: typeString, default: () => "" }) }, positionals: [] },
- *     async (_ctx, { options: { token } }) => ({ token }),
- *   ),
- *   command({ description: "Deploy" }, deployOperation),
- * );
- * ```
  */
 export function commandChained<Context, Payload, Result>(
   information: CommandInformation,
@@ -336,7 +323,7 @@ export function commandChained<Context, Payload, Result>(
         return {
           generateUsage() {
             const currentUsage = generateUsageLeaf(information, operation);
-            currentUsage.segments.push(segmentPositional("[REST]..."));
+            currentUsage.segments.push({ positional: "[REST]..." });
             return currentUsage;
           },
           decodeAndMakeInterpreter() {
@@ -348,23 +335,15 @@ export function commandChained<Context, Payload, Result>(
   };
 }
 
-function segmentPositional(value: string): UsageSegment {
-  return { positional: value };
-}
-
-function segmentSubcommand(value: string): UsageSegment {
-  return { subcommand: value };
-}
-
 function generateUsageLeaf(
   information: CommandInformation,
   operation: Operation<any, any>,
 ): UsageCommand {
   const { positionals, options } = operation.generateUsage();
   return {
-    segments: positionals.map((positional) =>
-      segmentPositional(positional.label),
-    ),
+    segments: positionals.map((positional) => ({
+      positional: positional.label,
+    })),
     information,
     positionals,
     subcommands: [],

package/src/lib/Operation.ts

@@ -1,7 +1,7 @@
 import { Option, OptionDecoder } from "./Option";
 import { Positional, PositionalDecoder } from "./Positional";
 import { ReaderArgs } from "./Reader";
-import { UsageOperation, UsageOption, UsagePositional } from "./Usage";
+import { UsageOption, UsagePositional } from "./Usage";
 
 /**
  * Options, positionals, and an async handler that together form the logic of a CLI command.
@@ -16,7 +16,16 @@ export type Operation<Context, Result> = {
   /**
    * Returns usage metadata without consuming any arguments.
    */
-  generateUsage(): UsageOperation;
+  generateUsage(): {
+    /**
+     * Registered options.
+     */
+    options: Array<UsageOption>;
+    /**
+     * Declared positionals, in order.
+     */
+    positionals: Array<UsagePositional>;
+  };
   /**
    * Consumes args from `readerArgs` and returns an {@link OperationDecoder}.
    */
@@ -74,10 +83,10 @@ export type OperationInterpreter<Context, Result> = {
  * const greetOperation = operation(
  *   {
  *     options: {
- *       loud: optionFlag({ long: "loud", description: "Print in uppercase" }),
+ *       loud: optionFlag({ long: "loud", description: "Print in uppercase", default: false }),
  *     },
  *     positionals: [
- *       positionalRequired({ type: typeString, label: "NAME", description: "Name to greet" }),
+ *       positionalRequired({ type: type("name"), description: "Name to greet" }),
  *     ],
  *   },
  *   async function (_ctx, { options: { loud }, positionals: [name] }) {