cli-kiss 0.1.9 → 0.2.0

package/package.json

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

package/src/lib/Command.ts

@@ -16,12 +16,12 @@ import {
  *
  * A `CommandDescriptor` is the central building block of a `cli-kiss` CLI. You create
  * one with {@link command}, {@link commandWithSubcommands}, or {@link commandChained},
- * and pass it to {@link runAsCliAndExit} to run your CLI.
+ * and pass it to {@link runAndExit} to run your CLI.
  *
  * @typeParam Context - The value passed into the command when it is executed. It flows
- *   from {@link runAsCliAndExit}'s `context` argument down through the command chain.
+ *   from {@link runAndExit}'s `context` argument down through the command chain.
  * @typeParam Result - The value produced by executing the command. For root commands
- *   passed to {@link runAsCliAndExit} this is always `void`.
+ *   passed to {@link runAndExit} this is always `void`.
  */
 export type CommandDescriptor<Context, Result> = {
   /** Returns the static metadata (description, hint, details) for this command. */
@@ -74,7 +74,7 @@ export type CommandInstance<Context, Result> = {
   /**
    * Executes the command with the provided context.
    *
-   * @param context - Arbitrary value injected by the caller (see {@link runAsCliAndExit}).
+   * @param context - Arbitrary value injected by the caller (see {@link runAndExit}).
    * @returns A promise that resolves to the command's result, or rejects if the
    *   command handler throws.
    */
@@ -84,8 +84,7 @@ export type CommandInstance<Context, Result> = {
 /**
  * Static, human-readable metadata attached to a command.
  *
- * This information is displayed in the usage/help output produced by
- * {@link usageToStyledLines}.
+ * This information is displayed in the usage/help output produced by {@link usageToStyledLines}.
  */
 export type CommandInformation = {
   /** Short description of what the command does. Shown prominently in the usage header. */
@@ -176,7 +175,7 @@ export type CommandUsageSubcommand = {
  * @param information - Static metadata (description, hint, details) for the command.
  * @param operation - The operation that defines options, positionals, and the execution
  *   handler for this command.
- * @returns A {@link CommandDescriptor} suitable for passing to {@link runAsCliAndExit}
+ * @returns A {@link CommandDescriptor} suitable for passing to {@link runAndExit}
  *   or composing with {@link commandWithSubcommands} / {@link commandChained}.
  *
  * @example

package/src/lib/Operation.ts

@@ -66,7 +66,7 @@ export type OperationInstance<Input, Output> = {
    * option/positional values.
    *
    * @param input - Context from the parent command (or the root context supplied to
-   *   {@link runAsCliAndExit}).
+   *   {@link runAndExit}).
    * @returns A promise resolving to the handler's return value.
    */
   executeWithContext(input: Input): Promise<Output>;
@@ -89,7 +89,7 @@ export type OperationUsage = {
  *
  * The `handler` receives:
  * - `context` — the value passed down from the parent command (or from
- *   {@link runAsCliAndExit}).
+ *   {@link runAndExit}).
  * - `inputs.options` — an object whose keys match those declared in `inputs.options` and whose values are
  *   the parsed option values.
  * - `inputs.positionals` — a tuple whose elements match `inputs.positionals` and whose

package/src/lib/Reader.ts

@@ -85,7 +85,7 @@ export type ReaderPositionals = {
  * - End-of-options separator: `--` — all subsequent tokens are treated as positionals.
  *
  * In most cases you do not need to use `ReaderArgs` directly; it is created internally
- * by {@link runAsCliAndExit}. It is exposed for advanced use cases such as building
+ * by {@link runAndExit}. It is exposed for advanced use cases such as building
  * custom runners.
  */
 export class ReaderArgs {

package/src/lib/Run.ts

@@ -44,10 +44,8 @@ import { usageToStyledLines } from "./Usage";
  *   stderr before the error message whenever argument parsing fails.
  * @param options.buildVersion - When provided, registers a `--version` flag that prints
  *   `<cliName> <buildVersion>` to stdout and exits with code `0`.
- * @param options.onExecutionError - Custom handler for errors thrown during command
- *   execution. If omitted, the error is printed to stderr via {@link TypoSupport}.
- * @param options.onLogStdOut - Overrides the standard output sink (default: `console.log`).
- * @param options.onLogStdErr - Overrides the standard error sink (default: `console.error`).
+ * @param options.onError - Custom handler for errors thrown during command execution.
+ *   If omitted, the error is printed to stderr via {@link TypoSupport}.
  * @param options.onExit - Overrides the process exit function (default: `process.exit`).
  *   Useful for testing — supply a function that throws or captures the exit code instead
  *   of actually terminating the process.
@@ -56,7 +54,7 @@ import { usageToStyledLines } from "./Usage";
  *
  * @example
  * ```ts
- * import { runAsCliAndExit, command, operation, positionalRequired, typeString } from "cli-kiss";
+ * import { runAndExit, command, operation, positionalRequired, typeString } from "cli-kiss";
  *
  * const greetCommand = command(
  *   { description: "Greet someone" },
@@ -68,12 +66,12 @@ import { usageToStyledLines } from "./Usage";
  *   ),
  * );
  *
- * await runAsCliAndExit("greet", process.argv.slice(2), undefined, greetCommand, {
+ * await runAndExit("greet", process.argv.slice(2), undefined, greetCommand, {
  *   buildVersion: "1.0.0",
  * });
  * ```
  */
-export async function runAsCliAndExit<Context>(
+export async function runAndExit<Context>(
   cliName: Lowercase<string>,
   cliArgs: ReadonlyArray<string>,
   context: Context,
@@ -83,9 +81,7 @@ export async function runAsCliAndExit<Context>(
     usageOnHelp?: boolean | undefined;
     usageOnError?: boolean | undefined;
     buildVersion?: string | undefined;
-    onExecutionError?: ((error: unknown) => void) | undefined;
-    onLogStdOut?: ((message: string) => void) | undefined;
-    onLogStdErr?: ((message: string) => void) | undefined;
+    onError?: ((error: unknown) => void) | undefined;
     onExit?: ((code: number) => never) | undefined;
   },
 ): Promise<never> {
@@ -114,17 +110,6 @@ export async function runAsCliAndExit<Context>(
     longs: ["completion"],
   });
   */
-  const typoSupport =
-    options?.useTtyColors === undefined
-      ? TypoSupport.inferFromProcess()
-      : options.useTtyColors === "mock"
-        ? TypoSupport.mock()
-        : options.useTtyColors
-          ? TypoSupport.tty()
-          : TypoSupport.none();
-  const onLogStdOut = options?.onLogStdOut ?? console.log;
-  const onLogStdErr = options?.onLogStdErr ?? console.error;
-  const onExit = options?.onExit ?? process.exit;
   const commandFactory = command.createFactory(readerArgs);
   while (true) {
     try {
@@ -134,15 +119,24 @@ export async function runAsCliAndExit<Context>(
       }
     } catch (_) {}
   }
+  const onExit = options?.onExit ?? process.exit;
+  const typoSupport =
+    options?.useTtyColors === undefined
+      ? TypoSupport.inferFromProcess()
+      : options.useTtyColors === "mock"
+        ? TypoSupport.mock()
+        : options.useTtyColors
+          ? TypoSupport.tty()
+          : TypoSupport.none();
   if (usageOnHelp) {
     if (readerArgs.getOptionValues("--help" as any).length > 0) {
-      onLogStdOut(computeUsageString(cliName, commandFactory, typoSupport));
+      console.log(computeUsageString(cliName, commandFactory, typoSupport));
       return onExit(0);
     }
   }
   if (buildVersion) {
     if (readerArgs.getOptionValues("--version" as any).length > 0) {
-      onLogStdOut([cliName, buildVersion].join(" "));
+      console.log([cliName, buildVersion].join(" "));
       return onExit(0);
     }
   }
@@ -152,18 +146,18 @@ export async function runAsCliAndExit<Context>(
       await commandInstance.executeWithContext(context);
       return onExit(0);
     } catch (executionError) {
-      if (options?.onExecutionError) {
-        options.onExecutionError(executionError);
+      if (options?.onError) {
+        options.onError(executionError);
       } else {
-        onLogStdErr(typoSupport.computeStyledErrorMessage(executionError));
+        console.error(typoSupport.computeStyledErrorMessage(executionError));
       }
       return onExit(1);
     }
   } catch (parsingError) {
     if (options?.usageOnError ?? true) {
-      onLogStdErr(computeUsageString(cliName, commandFactory, typoSupport));
+      console.error(computeUsageString(cliName, commandFactory, typoSupport));
     }
-    onLogStdErr(typoSupport.computeStyledErrorMessage(parsingError));
+    console.error(typoSupport.computeStyledErrorMessage(parsingError));
     return onExit(1);
   }
 }

package/src/lib/Typo.ts

@@ -368,9 +368,8 @@ export class TypoError extends Error {
  * - {@link TypoSupport.inferFromProcess} — auto-detects based on `process.stdout.isTTY`
  *   and the `FORCE_COLOR` / `NO_COLOR` environment variables.
  *
- * `TypoSupport` is consumed by {@link runAsCliAndExit} (via the `useTtyColors` option)
- * and can also be used directly when building custom usage renderers with
- * {@link usageToStyledLines}.
+ * `TypoSupport` is consumed by {@link runAndExit} (via the `useTtyColors` option)
+ * and can also be used directly when building custom usage renderers with {@link usageToStyledLines}.
  */
 export class TypoSupport {
   #kind: "none" | "tty" | "mock";

package/src/lib/Usage.ts

@@ -39,8 +39,7 @@ import {
  * in each column sets the width for the entire section.
  *
  * @param params.cliName - The CLI program name shown at the start of the usage line.
- * @param params.commandUsage - The usage model produced by
- *   {@link CommandFactory.generateUsage}.
+ * @param params.commandUsage - The usage model produced by {@link CommandFactory.generateUsage}.
  * @param params.typoSupport - Controls color/styling of the output.
  * @returns An ordered array of strings, one per output line (including a trailing
  *   empty string for the blank line at the end).
@@ -50,7 +49,7 @@ import {
  * const lines = usageToStyledLines({
  *   cliName: "my-cli",
  *   commandUsage: commandFactory.generateUsage(),
- *   typoSupport: TypoSupport.none(),
+ *   typoSupport: TypoSupport.tty(),
  * });
  * process.stdout.write(lines.join("\n"));
  * ```

package/tests/unit.runner.cycle.ts

@@ -9,7 +9,7 @@ import {
   positionalOptional,
   positionalRequired,
   positionalVariadics,
-  runAsCliAndExit,
+  runAndExit,
   typeConverted,
   typeOneOf,
   typeString,
@@ -324,7 +324,7 @@ async function testCase(
         ],
       },
       async () => {
-        onLogStdOut.call("Has executed root command");
+        console.log("Has executed root command");
       },
     ),
     {
@@ -359,17 +359,17 @@ async function testCase(
             ],
           },
           async () => {
-            onLogStdOut.call("Has executed subcommand");
+            console.log("Has executed subcommand");
           },
         ),
       ),
     },
   );
-  await runAsCliAndExit("my-cli", args, null, cmd, {
+  console.log = onLogStdOut.call;
+  console.error = onLogStdErr.call;
+  await runAndExit("my-cli", args, null, cmd, {
     buildVersion: "1.0.0",
     useTtyColors: false,
-    onLogStdOut: onLogStdOut.call,
-    onLogStdErr: onLogStdErr.call,
     onExit: onExit.call,
   });
   expect({

package/tests/unit.runner.errors.ts

@@ -5,7 +5,7 @@ import {
   optionFlag,
   optionRepeatable,
   optionSingleValue,
-  runAsCliAndExit,
+  runAndExit,
   typeNumber,
   typeUrl,
 } from "../src";
@@ -34,43 +34,43 @@ it("run", async () => {
 });
 
 async function testCase(args: Array<string>, error: string) {
+  const onLogStdOut = makeMocked<string, void>([]);
   const onLogStdErr = makeMocked<string, void>([null as unknown as void]);
   const onExit = makeMocked<number, never>([null as never]);
-  await runAsCliAndExit(
-    "my-cli",
-    args,
-    null,
-    command<void, void>(
-      { description: "" },
-      operation(
-        {
-          options: {
-            optionFlag: optionFlag({ long: "flag" }),
-            optionSingleValue: optionSingleValue({
-              label: "LOCATION",
-              long: "single-value",
-              type: typeUrl,
-              default: () => undefined,
-            }),
-            optionRepeatable: optionRepeatable({
-              label: "INDEX",
-              long: "repeatable",
-              type: typeNumber,
-            }),
-          },
-          positionals: [],
+  const rootCommand = command<void, void>(
+    { description: "" },
+    operation(
+      {
+        options: {
+          optionFlag: optionFlag({
+            long: "flag",
+          }),
+          optionSingleValue: optionSingleValue({
+            label: "LOCATION",
+            long: "single-value",
+            type: typeUrl,
+            default: () => undefined,
+          }),
+          optionRepeatable: optionRepeatable({
+            label: "INDEX",
+            long: "repeatable",
+            type: typeNumber,
+          }),
         },
-        async (_, _inputs) => {},
-      ),
+        positionals: [],
+      },
+      async () => {},
     ),
-    {
-      buildVersion: "1.0.0",
-      usageOnError: false,
-      useTtyColors: "mock",
-      onLogStdErr: onLogStdErr.call,
-      onExit: onExit.call,
-    },
   );
+  console.log = onLogStdOut.call;
+  console.error = onLogStdErr.call;
+  await runAndExit("my-cli", args, null, rootCommand, {
+    buildVersion: "1.0.0",
+    usageOnError: false,
+    useTtyColors: "mock",
+    onExit: onExit.call,
+  });
+  expect(onLogStdOut.history).toEqual([]);
   expect(onLogStdErr.history).toEqual([error]);
   expect(onExit.history).toEqual([1]);
 }