cli-kiss 0.2.3 → 0.2.5

package/src/lib/Run.ts

@@ -1,5 +1,7 @@
 import { Command, CommandDecoder } from "./Command";
+import { optionFlag, optionSingleValue } from "./Option";
 import { ReaderArgs } from "./Reader";
+import { typeChoice } from "./Type";
 import { TypoSupport } from "./Typo";
 import { usageToStyledLines } from "./Usage";
 
@@ -7,17 +9,17 @@ import { usageToStyledLines } from "./Usage";
  * Main entry point: parses CLI arguments, executes the matched command, and exits.
  * Handles `--help`, `--version`, usage-on-error, and exit codes.
  *
- * Exit codes: `0` on success / `--help` / `--version`; `1` on parse or execution error.
+ * Exit codes:
+ *  - `0` on success / `--help` / `--version`
+ *  - `1` on parse error or execution error.
  *
- * @typeParam Context - Passed unchanged to the command handler; use to inject dependencies.
+ * @typeParam Context - Forwarded unchanged to the handler.
  *
  * @param cliName - Program name used in usage and `--version` output.
  * @param cliArgs - Raw arguments, typically `process.argv.slice(2)`.
- * @param context - Forwarded to the command handler, injected dependencies.
+ * @param context - Forwarded to the handler.
  * @param command - Root {@link Command}.
- * @param options - Optional runner configuration.
- * @param options.useTtyColors - Color mode: `true` (always), `false` (never),
- *   `"mock"` (snapshot-friendly), `undefined` (auto-detect from env).
+ * @param options.colorSetup - Configures color support; enables `--color` flag if set to `"flag"`.
  * @param options.usageOnHelp - Enables `--help` flag (default `true`).
  * @param options.usageOnError - Prints usage to stderr on parse error (default `true`).
  * @param options.buildVersion - Enables `--version`; prints `<cliName> <buildVersion>`.
@@ -28,13 +30,13 @@ import { usageToStyledLines } from "./Usage";
  *
  * @example
  * ```ts
- * import { runAndExit, command, operation, positionalRequired, typeString } from "cli-kiss";
+ * import { runAndExit, command, operation, positionalRequired, type } from "cli-kiss";
  *
  * const greetCommand = command(
  *   { description: "Greet someone" },
  *   operation(
- *     { options: {}, positionals: [positionalRequired({ type: typeString, label: "NAME" })] },
- *     async (_ctx, { positionals: [name] }) => {
+ *     { options: {}, positionals: [positionalRequired({ type: type("name") })] },
+ *     async function (_ctx, { positionals: [name] }) {
  *       console.log(`Hello, ${name}!`);
  *     },
  *   ),
@@ -46,12 +48,12 @@ import { usageToStyledLines } from "./Usage";
  * ```
  */
 export async function runAndExit<Context>(
-  cliName: Lowercase<string>,
+  cliName: string,
   cliArgs: ReadonlyArray<string>,
   context: Context,
   command: Command<Context, void>,
   options?: {
-    useTtyColors?: boolean | undefined | "mock";
+    colorSetup?: "flag" | "env" | "always" | "never" | "mock" | undefined;
     usageOnHelp?: boolean | undefined;
     usageOnError?: boolean | undefined;
     buildVersion?: string | undefined;
@@ -60,20 +62,58 @@ export async function runAndExit<Context>(
   },
 ): Promise<never> {
   const readerArgs = new ReaderArgs(cliArgs);
-  const usageOnHelp = options?.usageOnHelp ?? true;
-  if (usageOnHelp) {
-    readerArgs.registerOption({
-      shorts: [],
-      longs: ["help"],
-      valued: false,
+  const preprocessors = new Array<
+    (commandDecoder: CommandDecoder<Context, void>) => undefined | number
+  >();
+  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);
+    preprocessors.push(() => {
+      try {
+        typoSupport = computeTypoSupport(colorOption.getAndDecodeValue());
+      } catch (error) {
+        typoSupport = TypoSupport.inferFromEnv();
+        throw error;
+      }
+      return undefined;
+    });
+  } else {
+    if (colorSetup === "env") {
+      typoSupport = TypoSupport.inferFromEnv();
+    } else {
+      typoSupport = computeTypoSupport(colorSetup);
+    }
+  }
+  if (options?.usageOnHelp ?? true) {
+    const helpOption = optionFlag({ long: "help" }).registerAndMakeDecoder(
+      readerArgs,
+    );
+    preprocessors.push((commandDecoder) => {
+      if (!helpOption.getAndDecodeValue()) {
+        return undefined;
+      }
+      console.log(computeUsageString(cliName, commandDecoder, typoSupport));
+      return 0;
     });
   }
-  const buildVersion = options?.buildVersion;
-  if (buildVersion) {
-    readerArgs.registerOption({
-      shorts: [],
-      longs: ["version"],
-      valued: false,
+  if (options?.buildVersion) {
+    const versionOption = optionFlag({
+      long: "version",
+    }).registerAndMakeDecoder(readerArgs);
+    preprocessors.push(() => {
+      if (!versionOption.getAndDecodeValue()) {
+        return undefined;
+      }
+      console.log([cliName, options.buildVersion].join(" "));
+      return 0;
     });
   }
   /*
@@ -94,27 +134,13 @@ export async function runAndExit<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) {
-      console.log(computeUsageString(cliName, commandDecoder, typoSupport));
-      return onExit(0);
-    }
-  }
-  if (buildVersion) {
-    if (readerArgs.getOptionValues("--version" as any).length > 0) {
-      console.log([cliName, buildVersion].join(" "));
-      return onExit(0);
-    }
-  }
   try {
+    for (const preprocessor of preprocessors) {
+      const preprocessorResult = preprocessor(commandDecoder);
+      if (preprocessorResult !== undefined) {
+        return onExit(preprocessorResult);
+      }
+    }
     const commandInterpreter = commandDecoder.decodeAndMakeInterpreter();
     try {
       await commandInterpreter.executeWithContext(context);
@@ -145,13 +171,28 @@ function handleError(
 }
 
 function computeUsageString<Context, Result>(
-  cliName: Lowercase<string>,
+  cliName: string,
   commandDecoder: CommandDecoder<Context, Result>,
   typoSupport: TypoSupport,
 ) {
   return usageToStyledLines({
     cliName,
-    commandUsage: commandDecoder.generateUsage(),
+    usage: commandDecoder.generateUsage(),
     typoSupport,
   }).join("\n");
 }
+
+function computeTypoSupport(
+  colorMode: "auto" | "always" | "never" | "mock",
+): TypoSupport {
+  switch (colorMode) {
+    case "auto":
+      return TypoSupport.inferFromEnv();
+    case "always":
+      return TypoSupport.tty();
+    case "never":
+      return TypoSupport.none();
+    case "mock":
+      return TypoSupport.mock();
+  }
+}