cli-kiss 0.2.4 → 0.2.6

package/src/lib/Run.ts

@@ -1,8 +1,15 @@
 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";
 
+/**
+ * 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.
@@ -17,8 +24,7 @@ import { usageToStyledLines } from "./Usage";
  * @param cliArgs - Raw arguments, typically `process.argv.slice(2)`.
  * @param context - Forwarded to the handler.
  * @param command - Root {@link Command}.
- * @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>`.
@@ -29,12 +35,12 @@ 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" })] },
+ *     { options: {}, positionals: [positionalRequired({ type: type("name") })] },
  *     async function (_ctx, { positionals: [name] }) {
  *       console.log(`Hello, ${name}!`);
  *     },
@@ -47,12 +53,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"; // TODO - flag setter option
+    colorSetup?: "flag" | RunColorMode | undefined;
     usageOnHelp?: boolean | undefined;
     usageOnError?: boolean | undefined;
     buildVersion?: string | undefined;
@@ -61,26 +67,52 @@ export async function runAndExit<Context>(
   },
 ): Promise<never> {
   const readerArgs = new ReaderArgs(cliArgs);
-  const usageOnHelp = options?.usageOnHelp ?? true;
-  if (usageOnHelp) {
-    readerArgs.registerOption({
-      shorts: [],
-      longs: ["help"],
-      parsing: {
-        consumeShortGroup: false,
-        consumeNextArg: () => 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" | RunColorMode>({
+      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 {
+    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"],
-      parsing: {
-        consumeShortGroup: false,
-        consumeNextArg: () => 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;
     });
   }
   /*
@@ -91,7 +123,6 @@ export async function runAndExit<Context>(
     longs: ["completion"],
   });
   */
-  // TODO - handle color flag ?
   const commandDecoder = command.consumeAndMakeDecoder(readerArgs);
   while (true) {
     try {
@@ -101,21 +132,14 @@ export async function runAndExit<Context>(
       }
     } catch (_) {}
   }
-  const typoSupport = computeTypoSupport(options?.useTtyColors);
   const onExit = options?.onExit ?? process.exit;
-  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);
@@ -146,7 +170,7 @@ function handleError(
 }
 
 function computeUsageString<Context, Result>(
-  cliName: Lowercase<string>,
+  cliName: string,
   commandDecoder: CommandDecoder<Context, Result>,
   typoSupport: TypoSupport,
 ) {
@@ -157,14 +181,17 @@ function computeUsageString<Context, Result>(
   }).join("\n");
 }
 
-function computeTypoSupport(
-  useTtyColors: boolean | undefined | "mock",
-): TypoSupport {
-  return useTtyColors === undefined
-    ? TypoSupport.inferFromProcess()
-    : useTtyColors === "mock"
-      ? TypoSupport.mock()
-      : useTtyColors
-        ? TypoSupport.tty()
-        : TypoSupport.none();
+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":
+      return TypoSupport.none();
+    case "mock":
+      return TypoSupport.mock();
+  }
 }