cli-kiss 0.2.4 → 0.2.6

package/docs/guide/06_run_as_cli.md

@@ -0,0 +1,143 @@
+# Running your CLI
+
+## `runAndExit`
+
+`runAndExit` parses arguments, runs the matched command, and exits.
+
+```ts
+await runAndExit(cliName, cliArgs, context, command, options?);
+```
+
+| 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                                                   |
+| `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
+
+| Code | Reason                                  |
+| ---- | --------------------------------------- |
+| `0`  | Success, `--help`, or `--version`       |
+| `1`  | Parse error or uncaught execution error |
+
+## Full example
+
+```ts
+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",
+          defaultWhenNotDefined: () => 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
+
+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" });
+```
+
+## Testing your CLI
+
+Override `onExit` to prevent process exit during tests:
+
+```ts
+const exitCodes: number[] = [];
+await runAndExit("my-cli", ["--help"], undefined, myCommand, {
+  colorSetup: "never",
+  onExit: (code) => {
+    exitCodes.push(code);
+    return undefined as never;
+  },
+});
+console.assert(exitCodes[0] === 0, "expected exit 0 for --help");
+```

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.4",
+  "version": "0.2.6",
   "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] }) {