cli-kiss 0.0.3 → 0.0.5

package/src/lib/Command.ts

@@ -4,58 +4,58 @@ import { OptionUsage } from "./Option";
 import { ReaderTokenizer } from "./Reader";
 
 export type Command<Context, Result> = {
-  getTitle(): string | undefined;
-  prepareRunner(
+  getDescription(): string | undefined;
+  buildInterpreter(
     readerTokenizer: ReaderTokenizer,
-  ): CommandRunner<Context, Result>;
+  ): CommandInterpreter<Context, Result>;
 };
 
-export type CommandRunner<Context, Result> = {
+export type CommandMetadata = {
+  description: string;
+  details?: Array<string>;
+  // TODO - printable examples ?
+};
+
+export type CommandInterpreter<Context, Result> = {
   computeUsage(): CommandUsage;
   execute(context: Context): Promise<Result>;
 };
 
 export type CommandUsage = {
   breadcrumbs: Array<CommandUsageBreadcrumb>;
-  title: string;
-  description: Array<string> | undefined;
+  description: string;
+  details: Array<string> | undefined;
   options: Array<OptionUsage>;
   arguments: Array<ArgumentUsage>;
-  subcommands: Array<{ name: string; title: string | undefined }>;
+  subcommands: Array<{ name: string; description: string | undefined }>;
 };
 
-export type CommandUsageBreadcrumb = {
-  kind: "command" | "argument";
-  value: string;
-};
+export type CommandUsageBreadcrumb = { argument: string } | { command: string };
 
 export function command<Context, Result>(
-  metadata: {
-    title: string;
-    description?: Array<string>;
-  },
+  metadata: CommandMetadata,
   execution: Execution<Context, Result>,
 ): Command<Context, Result> {
   return {
-    getTitle() {
-      return metadata.title;
+    getDescription() {
+      return metadata.description;
     },
-    prepareRunner(readerTokenizer: ReaderTokenizer) {
+    buildInterpreter(readerTokenizer: ReaderTokenizer) {
       function computeUsage(): CommandUsage {
         const executionUsage = execution.computeUsage();
         return {
           breadcrumbs: executionUsage.arguments.map((argument) =>
             breadcrumbArgument(argument.label),
           ),
-          title: metadata.title,
           description: metadata.description,
+          details: metadata.details,
           options: executionUsage.options,
           arguments: executionUsage.arguments,
           subcommands: [],
         };
       }
       try {
-        const executionResolver = execution.prepareResolver(readerTokenizer);
+        const executionResolver = execution.createResolver(readerTokenizer);
         const lastPositional = readerTokenizer.consumePositional();
         if (lastPositional !== undefined) {
           throw Error(`Unprocessed positional: ${lastPositional}`);
@@ -80,20 +80,17 @@ export function command<Context, Result>(
 }
 
 export function commandWithSubcommands<Context, Payload, Result>(
-  metadata: {
-    title: string;
-    description?: Array<string>;
-  },
+  metadata: CommandMetadata,
   execution: Execution<Context, Payload>,
   subcommands: { [subcommand: Lowercase<string>]: Command<Payload, Result> },
 ): Command<Context, Result> {
   return {
-    getTitle() {
-      return metadata.title;
+    getDescription() {
+      return metadata.description;
     },
-    prepareRunner(readerTokenizer: ReaderTokenizer) {
+    buildInterpreter(readerTokenizer: ReaderTokenizer) {
       try {
-        const executionResolver = execution.prepareResolver(readerTokenizer);
+        const executionResolver = execution.createResolver(readerTokenizer);
         const subcommandName = readerTokenizer.consumePositional();
         if (subcommandName === undefined) {
           throw new Error("Expected a subcommand");
@@ -103,19 +100,20 @@ export function commandWithSubcommands<Context, Payload, Result>(
         if (subcommandInput === undefined) {
           throw new Error(`Unknown subcommand: ${subcommandName}`);
         }
-        const subcommandRunner = subcommandInput.prepareRunner(readerTokenizer);
+        const subcommandInterpreter =
+          subcommandInput.buildInterpreter(readerTokenizer);
         const executionCallback = executionResolver();
         return {
           computeUsage() {
             const executionUsage = execution.computeUsage();
-            const subcommandUsage = subcommandRunner.computeUsage();
+            const subcommandUsage = subcommandInterpreter.computeUsage();
             return {
               breadcrumbs: executionUsage.arguments
                 .map((argument) => breadcrumbArgument(argument.label))
                 .concat([breadcrumbCommand(subcommandName)])
                 .concat(subcommandUsage.breadcrumbs),
-              title: subcommandUsage.title,
               description: subcommandUsage.description,
+              details: subcommandUsage.details,
               options: executionUsage.options.concat(subcommandUsage.options),
               arguments: executionUsage.arguments.concat(
                 subcommandUsage.arguments,
@@ -125,7 +123,7 @@ export function commandWithSubcommands<Context, Payload, Result>(
           },
           async execute(context: Context) {
             const payload = await executionCallback(context);
-            return await subcommandRunner.execute(payload);
+            return await subcommandInterpreter.execute(payload);
           },
         };
       } catch (error) {
@@ -136,14 +134,14 @@ export function commandWithSubcommands<Context, Payload, Result>(
               breadcrumbs: executionUsage.arguments
                 .map((argument) => breadcrumbArgument(argument.label))
                 .concat([breadcrumbCommand("<SUBCOMMAND>")]),
-              title: metadata.title,
               description: metadata.description,
+              details: metadata.details,
               options: executionUsage.options,
               arguments: executionUsage.arguments,
               subcommands: Object.entries(subcommands).map(
                 ([name, subcommand]) => ({
                   name,
-                  title: subcommand.getTitle(),
+                  description: subcommand.getDescription(),
                 }),
               ),
             };
@@ -157,10 +155,10 @@ export function commandWithSubcommands<Context, Payload, Result>(
   };
 }
 
-function breadcrumbArgument(label: string): CommandUsageBreadcrumb {
-  return { kind: "argument", value: label };
+function breadcrumbArgument(value: string): CommandUsageBreadcrumb {
+  return { argument: value };
 }
 
-function breadcrumbCommand(name: string): CommandUsageBreadcrumb {
-  return { kind: "command", value: name };
+function breadcrumbCommand(value: string): CommandUsageBreadcrumb {
+  return { command: value };
 }

package/src/lib/Execution.ts

@@ -4,7 +4,7 @@ import { ReaderTokenizer } from "./Reader";
 
 export type Execution<Context, Result> = {
   computeUsage(): ExecutionUsage;
-  prepareResolver(
+  createResolver(
     readerTokenizer: ReaderTokenizer,
   ): ExecutionResolver<Context, Result>;
 };
@@ -26,21 +26,18 @@ export type ExecutionUsage = {
 export function execution<
   Context,
   Result,
-  Options extends { [option: string]: Option<any> },
-  const Arguments extends Array<Argument<any>>,
+  Options extends { [option: string]: any },
+  const Arguments extends Array<any>,
 >(
-  inputs: { options: Options; arguments: Arguments },
+  inputs: {
+    options: { [K in keyof Options]: Option<Options[K]> };
+    arguments: { [K in keyof Arguments]: Argument<Arguments[K]> };
+  },
   handler: (
     context: Context,
     inputs: {
-      options: {
-        [K in keyof Options]: ReturnType<
-          ReturnType<Options[K]["prepareConsumer"]>
-        >;
-      };
-      arguments: {
-        [K in keyof Arguments]: ReturnType<Arguments[K]["consumeValue"]>;
-      };
+      options: Options;
+      arguments: Arguments;
     },
   ) => Promise<Result>,
 ): Execution<Context, Result> {
@@ -57,7 +54,7 @@ export function execution<
       }
       return { options: optionsUsage, arguments: argumentsUsage };
     },
-    prepareResolver(readerTokenizer: ReaderTokenizer) {
+    createResolver(readerTokenizer: ReaderTokenizer) {
       const optionsConsumers: any = {};
       for (const optionKey in inputs.options) {
         const optionInput = inputs.options[optionKey]!;

package/src/lib/Grid.ts

@@ -4,7 +4,11 @@ export type Grid = Array<GridRow>;
 export type GridRow = Array<GridCell>;
 export type GridCell = Array<TypoText>;
 
-export function gridToPrintableLines(grid: Grid, typoSupport: TypoSupport) {
+export function gridToPrintableLines(
+  grid: Grid,
+  typoSupport: TypoSupport,
+  delimiter: string = "",
+): Array<string> {
   const lines = new Array<string>();
   const gridWidths = new Array<number>();
   for (const gridRow of grid) {
@@ -42,7 +46,7 @@ export function gridToPrintableLines(grid: Grid, typoSupport: TypoSupport) {
         lineColumns.push(parts.join(""));
       }
     }
-    lines.push(lineColumns.join(" "));
+    lines.push(lineColumns.join(delimiter));
   }
   return lines;
 }

package/src/lib/Option.ts

@@ -11,6 +11,7 @@ export type OptionUsage = {
   long: Lowercase<string>; // TODO - better type for long option names ?
   short: string | undefined;
   label: Uppercase<string> | undefined;
+  // TODO - default value for usage ? but it can be dynamic, so maybe not
 };
 
 export type OptionConsumer<Value> = () => Value;
@@ -65,6 +66,7 @@ export function optionRepeatable<Value>(definition: {
 }): Option<Array<Value>> {
   return {
     generateUsage() {
+      // TODO - showcase that it can be repeated ?
       return {
         description: definition.description,
         long: definition.long,

package/src/lib/Reader.ts

@@ -3,7 +3,7 @@ export type ReaderPositionals = {
 };
 
 export class ReaderTokenizer {
-  #parsedArgv: Array<string>;
+  #parsedArgs: Array<string>;
   #parsedIndex: number;
   #parsedDouble: boolean;
 
@@ -17,8 +17,8 @@ export class ReaderTokenizer {
   #optionInfoByKey: Map<string, {}>; // TODO - what dis for
   #optionResultByKey: Map<string, Array<string> | null>;
 
-  constructor(argv: Array<string>) {
-    this.#parsedArgv = argv;
+  constructor(args: Array<string>) {
+    this.#parsedArgs = args;
     this.#parsedIndex = 0;
     this.#parsedDouble = false;
 
@@ -116,7 +116,7 @@ export class ReaderTokenizer {
   }
 
   #consumeArg(): string | null {
-    const arg = this.#parsedArgv[this.#parsedIndex];
+    const arg = this.#parsedArgs[this.#parsedIndex];
     if (arg === undefined) {
       return null;
     }

package/src/lib/Run.ts

@@ -1,32 +1,38 @@
-import { Command } from "./Command";
+import { Command, CommandInterpreter } from "./Command";
 import { ReaderTokenizer } from "./Reader";
-import { typoInferSupport } from "./Typo";
+import { typoInferProcessSupport, TypoSupport } from "./Typo";
 import { usageToPrintableLines } from "./Usage";
 
-export async function runWithArgv<Context, Result>(
-  argv: string[],
+export async function runAndExit<Context>(
+  cliName: Lowercase<string>,
+  cliArgs: Array<string>,
   context: Context,
-  command: Command<Context, Result>,
-  cliInfo?: {
-    name?: Lowercase<string>;
-    version?: string;
-    helpOnError?: boolean;
+  command: Command<Context, void>,
+  application?: {
+    usageOnError?: boolean;
+    usageOnHelp?: boolean;
+    buildVersion?: string;
+    useColors?: boolean;
+    onMessage?: (message: string) => void;
+    onError?: (error: any) => void;
+    onExit?: (code: number) => never;
   },
-): Promise<Result> {
-  const cliName = cliInfo?.name ?? argv[1]!;
-  const readerTokenizer = new ReaderTokenizer(argv.slice(2));
-  if (cliInfo?.version) {
+): Promise<never> {
+  const readerTokenizer = new ReaderTokenizer(cliArgs);
+  if (application?.buildVersion) {
     readerTokenizer.registerFlag({
       key: "version",
       shorts: [],
       longs: ["version"],
     });
   }
-  readerTokenizer.registerFlag({
-    key: "help",
-    shorts: [],
-    longs: ["help"],
-  });
+  if (application?.usageOnHelp ?? true) {
+    readerTokenizer.registerFlag({
+      key: "help",
+      shorts: [],
+      longs: ["help"],
+    });
+  }
   /*
   // TODO - handle completions ?
   readerTokenizer.registerFlag({
@@ -35,41 +41,50 @@ export async function runWithArgv<Context, Result>(
     longs: ["completion"],
   });
   */
-  try {
-    const commandRunner = command.prepareRunner(readerTokenizer);
-    if (cliInfo?.version) {
-      if (readerTokenizer.consumeFlag("version")) {
-        console.log(cliName, cliInfo.version);
-        process.exit(0);
-      }
-    }
-    if (readerTokenizer.consumeFlag("help")) {
-      console.log(
-        usageToPrintableLines({
-          cliName,
-          commandUsage: commandRunner.computeUsage(),
-          typoSupport: typoInferSupport(),
-        }).join("\n"),
+  const commandInterpreter = command.buildInterpreter(readerTokenizer);
+  if (application?.buildVersion) {
+    if (readerTokenizer.consumeFlag("version")) {
+      (application?.onMessage ?? console.log)(
+        [cliName, application.buildVersion].join(" "),
       );
-      process.exit(0);
+      return (application?.onExit ?? process.exit)(0);
     }
-    try {
-      return await commandRunner.execute(context);
-    } catch (error) {
-      if (cliInfo?.helpOnError ?? true) {
-        console.log(
-          usageToPrintableLines({
-            cliName,
-            commandUsage: commandRunner.computeUsage(),
-            typoSupport: typoInferSupport(),
-          }).join("\n"),
-        );
-      }
-      console.error(error);
-      process.exit(1);
+  }
+  if (application?.usageOnHelp ?? true) {
+    if (readerTokenizer.consumeFlag("help")) {
+      logUsageMessage(cliName, commandInterpreter, application);
+      return (application?.onExit ?? process.exit)(0);
     }
+  }
+  try {
+    await commandInterpreter.execute(context);
+    return (application?.onExit ?? process.exit)(0);
   } catch (error) {
-    console.error(error);
-    process.exit(1);
+    if (application?.usageOnError ?? true) {
+      logUsageMessage(cliName, commandInterpreter, application);
+    }
+    (application?.onError ?? console.error)(error);
+    return (application?.onExit ?? process.exit)(1);
+  }
+}
+
+function logUsageMessage<Context, Result>(
+  cliName: Lowercase<string>,
+  commandInterpreter: CommandInterpreter<Context, Result>,
+  application?: { useColors?: boolean; onMessage?: (message: string) => void },
+) {
+  (application?.onMessage ?? console.log)(
+    usageToPrintableLines({
+      cliName,
+      commandUsage: commandInterpreter.computeUsage(),
+      typoSupport: chooseTypoSupport(application?.useColors),
+    }).join("\n"),
+  );
+}
+
+function chooseTypoSupport(useColors?: boolean): TypoSupport {
+  if (useColors === undefined) {
+    return typoInferProcessSupport();
   }
+  return useColors ? "tty" : "none";
 }

package/src/lib/Type.ts

@@ -48,10 +48,35 @@ export const typeBigInt: Type<bigint> = {
   },
 };
 
-export function typeCommaArray(elementType: Type<any>): Type<Array<any>> {
+export function typeCommaTuple<
+  const Elements extends Array<any>,
+>(elementTypes: {
+  [K in keyof Elements]: Type<Elements[K]>;
+}): Type<Elements> {
+  return {
+    label: elementTypes
+      .map((elementType) => elementType.label)
+      .join(",") as Uppercase<string>,
+    decoder(value: string) {
+      const parts = value.split(",", elementTypes.length);
+      if (parts.length !== elementTypes.length) {
+        throw new Error(
+          `Invalid tuple value: ${value}, expected ${elementTypes.length} parts`,
+        );
+      }
+      return parts.map((part, index) =>
+        elementTypes[index]!.decoder(part),
+      ) as Elements;
+    },
+  };
+}
+
+export function typeCommaList<Value>(
+  elementType: Type<Value>,
+): Type<Array<Value>> {
   return {
     label:
-      `${elementType.label}[${elementType.label},...]` as Uppercase<string>,
+      `${elementType.label}[,${elementType.label}...]` as Uppercase<string>,
     decoder(value: string) {
       return value.split(",").map(elementType.decoder);
     },

package/src/lib/Typo.ts

@@ -42,7 +42,10 @@ export function typoPrintableString(
   throw new Error(`Unknown typo support: ${typoSupport}`);
 }
 
-export function typoInferSupport(): TypoSupport {
+export function typoInferProcessSupport(): TypoSupport {
+  if (!process) {
+    return "none";
+  }
   if (process.env) {
     if (process.env["FORCE_COLOR"] === "0") {
       return "none";
@@ -54,7 +57,7 @@ export function typoInferSupport(): TypoSupport {
       return "none";
     }
   }
-  if (!process || !process.stdout || !process.stdout.isTTY) {
+  if (!process.stdout || !process.stdout.isTTY) {
     return "none";
   }
   return "tty";
@@ -63,11 +66,20 @@ export function typoInferSupport(): TypoSupport {
 const resetCode = "\x1b[0m";
 const boldCode = "\x1b[1m";
 const colorCodes = {
-  red: "\x1b[31m",
-  green: "\x1b[32m",
-  yellow: "\x1b[33m",
-  blue: "\x1b[34m",
-  magenta: "\x1b[35m",
-  cyan: "\x1b[36m",
-  grey: "\x1b[90m",
+  darkBlack: "\x1b[30m",
+  darkRed: "\x1b[31m",
+  darkGreen: "\x1b[32m",
+  darkYellow: "\x1b[33m",
+  darkBlue: "\x1b[34m",
+  darkMagenta: "\x1b[35m",
+  darkCyan: "\x1b[36m",
+  darkWhite: "\x1b[37m",
+  brightBlack: "\x1b[90m",
+  brightRed: "\x1b[91m",
+  brightGreen: "\x1b[92m",
+  brightYellow: "\x1b[93m",
+  brightBlue: "\x1b[94m",
+  brightMagenta: "\x1b[95m",
+  brightCyan: "\x1b[96m",
+  brightWhite: "\x1b[97m",
 };