cli-kiss 0.0.2 → 0.0.4

package/src/lib/Command.ts

@@ -1,10 +1,10 @@
 import { ArgumentUsage } from "./Argument";
+import { Execution } from "./Execution";
 import { OptionUsage } from "./Option";
-import { Process } from "./Process";
 import { ReaderTokenizer } from "./Reader";
 
 export type Command<Context, Result> = {
-  getTitle(): string | undefined;
+  getDescription(): string | undefined;
   prepareRunner(
     readerTokenizer: ReaderTokenizer,
   ): CommandRunner<Context, Result>;
@@ -17,54 +17,52 @@ export type CommandRunner<Context, 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>;
+    description: string;
+    details?: Array<string>;
+    // TODO - examples ?
   },
-  process: Process<Context, Result>,
+  execution: Execution<Context, Result>,
 ): Command<Context, Result> {
   return {
-    getTitle() {
-      return metadata.title;
+    getDescription() {
+      return metadata.description;
     },
     prepareRunner(readerTokenizer: ReaderTokenizer) {
       function computeUsage(): CommandUsage {
-        const processUsage = process.computeUsage();
+        const executionUsage = execution.computeUsage();
         return {
-          breadcrumbs: processUsage.arguments.map((argument) =>
+          breadcrumbs: executionUsage.arguments.map((argument) =>
             breadcrumbArgument(argument.label),
           ),
-          title: metadata.title,
           description: metadata.description,
-          options: processUsage.options,
-          arguments: processUsage.arguments,
+          details: metadata.details,
+          options: executionUsage.options,
+          arguments: executionUsage.arguments,
           subcommands: [],
         };
       }
       try {
-        const processResolver = process.prepareResolver(readerTokenizer);
+        const executionResolver = execution.prepareResolver(readerTokenizer);
         const lastPositional = readerTokenizer.consumePositional();
         if (lastPositional !== undefined) {
           throw Error(`Unprocessed positional: ${lastPositional}`);
         }
-        const processRunner = processResolver();
+        const executionCallback = executionResolver();
         return {
           computeUsage,
           async execute(context: Context) {
-            return await processRunner.execute(context);
+            return await executionCallback(context);
           },
         };
       } catch (error) {
@@ -81,19 +79,19 @@ export function command<Context, Result>(
 
 export function commandWithSubcommands<Context, Payload, Result>(
   metadata: {
-    title: string;
-    description?: Array<string>;
+    description: string;
+    details?: Array<string>;
   },
-  process: Process<Context, Payload>,
+  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) {
       try {
-        const processResolver = process.prepareResolver(readerTokenizer);
+        const executionResolver = execution.prepareResolver(readerTokenizer);
         const subcommandName = readerTokenizer.consumePositional();
         if (subcommandName === undefined) {
           throw new Error("Expected a subcommand");
@@ -104,46 +102,46 @@ export function commandWithSubcommands<Context, Payload, Result>(
           throw new Error(`Unknown subcommand: ${subcommandName}`);
         }
         const subcommandRunner = subcommandInput.prepareRunner(readerTokenizer);
-        const processRunner = processResolver();
+        const executionCallback = executionResolver();
         return {
           computeUsage() {
-            const processUsage = process.computeUsage();
+            const executionUsage = execution.computeUsage();
             const subcommandUsage = subcommandRunner.computeUsage();
             return {
-              breadcrumbs: processUsage.arguments
+              breadcrumbs: executionUsage.arguments
                 .map((argument) => breadcrumbArgument(argument.label))
                 .concat([breadcrumbCommand(subcommandName)])
                 .concat(subcommandUsage.breadcrumbs),
-              title: subcommandUsage.title,
               description: subcommandUsage.description,
-              options: processUsage.options.concat(subcommandUsage.options),
-              arguments: processUsage.arguments.concat(
+              details: subcommandUsage.details,
+              options: executionUsage.options.concat(subcommandUsage.options),
+              arguments: executionUsage.arguments.concat(
                 subcommandUsage.arguments,
               ),
               subcommands: subcommandUsage.subcommands,
             };
           },
           async execute(context: Context) {
-            const payload = await processRunner.execute(context);
+            const payload = await executionCallback(context);
             return await subcommandRunner.execute(payload);
           },
         };
       } catch (error) {
         return {
           computeUsage() {
-            const processUsage = process.computeUsage();
+            const executionUsage = execution.computeUsage();
             return {
-              breadcrumbs: processUsage.arguments
+              breadcrumbs: executionUsage.arguments
                 .map((argument) => breadcrumbArgument(argument.label))
                 .concat([breadcrumbCommand("<SUBCOMMAND>")]),
-              title: metadata.title,
               description: metadata.description,
-              options: processUsage.options,
-              arguments: processUsage.arguments,
+              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/{Process.ts → Execution.ts}

@@ -2,48 +2,45 @@ import { Argument, ArgumentUsage } from "./Argument";
 import { Option, OptionUsage } from "./Option";
 import { ReaderTokenizer } from "./Reader";
 
-export type Process<Context, Result> = {
-  computeUsage(): ProcessUsage;
+export type Execution<Context, Result> = {
+  computeUsage(): ExecutionUsage;
   prepareResolver(
     readerTokenizer: ReaderTokenizer,
-  ): ProcessResolver<Context, Result>;
+  ): ExecutionResolver<Context, Result>;
 };
 
-export type ProcessResolver<Context, Result> = () => ProcessRunner<
+export type ExecutionResolver<Context, Result> = () => ExecutionCallback<
   Context,
   Result
 >;
 
-export type ProcessRunner<Context, Result> = {
-  execute(context: Context): Promise<Result>;
-};
+export type ExecutionCallback<Context, Result> = (
+  context: Context,
+) => Promise<Result>;
 
-export type ProcessUsage = {
+export type ExecutionUsage = {
   options: Array<OptionUsage>;
   arguments: Array<ArgumentUsage>;
 };
 
-export function process<
+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>,
-): Process<Context, Result> {
+): Execution<Context, Result> {
   return {
     computeUsage() {
       const optionsUsage = new Array<OptionUsage>();
@@ -73,13 +70,11 @@ export function process<
         for (const optionKey in optionsConsumers) {
           optionsValues[optionKey] = optionsConsumers[optionKey]!();
         }
-        return {
-          async execute(context: Context) {
-            return await handler(context, {
-              options: optionsValues,
-              arguments: argumentsValues,
-            });
-          },
+        return async (context: Context) => {
+          return await handler(context, {
+            options: optionsValues,
+            arguments: argumentsValues,
+          });
         };
       };
     },

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/Run.ts

@@ -3,18 +3,17 @@ import { ReaderTokenizer } from "./Reader";
 import { typoInferSupport } from "./Typo";
 import { usageToPrintableLines } from "./Usage";
 
-export async function runWithArgv<Context, Result>(
-  argv: string[],
+export async function runCommand<Context, Result>(
+  cliName: Lowercase<string>,
+  cliArgs: Array<string>,
   context: Context,
   command: Command<Context, Result>,
   cliInfo?: {
-    name?: Lowercase<string>;
     version?: string;
     helpOnError?: boolean;
   },
 ): Promise<Result> {
-  const cliName = cliInfo?.name ?? argv[1]!;
-  const readerTokenizer = new ReaderTokenizer(argv.slice(2));
+  const readerTokenizer = new ReaderTokenizer(cliArgs);
   if (cliInfo?.version) {
     readerTokenizer.registerFlag({
       key: "version",
@@ -65,7 +64,7 @@ export async function runWithArgv<Context, Result>(
           }).join("\n"),
         );
       }
-      console.error(error);
+      console.error(error); // TODO - better, prettier errors
       process.exit(1);
     }
   } catch (error) {

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

@@ -63,11 +63,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",
 };

package/src/lib/Usage.ts

@@ -3,7 +3,7 @@ import { GridCell, GridRow, gridToPrintableLines } from "./Grid";
 import { TypoSupport, TypoText, typoPrintableString } from "./Typo";
 
 export function usageToPrintableLines(params: {
-  cliName: string;
+  cliName: Lowercase<string>;
   commandUsage: CommandUsage;
   typoSupport: TypoSupport;
 }) {
@@ -11,42 +11,61 @@ export function usageToPrintableLines(params: {
 
   const lines = new Array<string>();
 
-  lines.push("");
-  lines.push(typoPrintableString(typoSupport, textDesc(commandUsage.title)));
-  if (commandUsage.description) {
-    for (const descriptionLine of commandUsage.description) {
-      lines.push(typoPrintableString(typoSupport, textSubs(descriptionLine)));
+  lines.push(
+    typoPrintableString(typoSupport, textDescription(commandUsage.description)),
+  );
+  if (commandUsage.details) {
+    for (const detailLine of commandUsage.details) {
+      lines.push(typoPrintableString(typoSupport, textDetails(detailLine)));
     }
   }
 
-  const breadcrumbPrefix = typoPrintableString(
-    typoSupport,
-    textTitle("Usage:"),
-  );
-  const breadcrumbsItems = [
-    typoPrintableString(typoSupport, textName(cliName)),
+  lines.push("");
+  lines.push(typoPrintableString(typoSupport, textCategory("Usage:")));
+  const breadcrumbs = [
+    " ",
+    typoPrintableString(typoSupport, textFixed(cliName)),
   ].concat(
     commandUsage.breadcrumbs.map((breadcrumb) => {
-      if (breadcrumb.kind === "argument") {
-        return typoPrintableString(typoSupport, textValue(breadcrumb.value));
+      if ("argument" in breadcrumb) {
+        return typoPrintableString(typoSupport, textInput(breadcrumb.argument));
+      }
+      if ("command" in breadcrumb) {
+        return typoPrintableString(typoSupport, textFixed(breadcrumb.command));
       }
-      return typoPrintableString(typoSupport, textName(breadcrumb.value));
+      throw new Error(`Unknown breadcrumb: ${JSON.stringify(breadcrumb)}`);
     }),
   );
-  lines.push("");
-  lines.push(`${breadcrumbPrefix} ${breadcrumbsItems.join(" ")}`);
+  lines.push(breadcrumbs.join(" "));
 
   if (commandUsage.arguments.length > 0) {
     lines.push("");
-    lines.push(typoPrintableString(typoSupport, textTitle("Arguments:")));
+    lines.push(typoPrintableString(typoSupport, textCategory("Arguments:")));
     const grid = new Array<GridRow>();
     for (const argumentUsage of commandUsage.arguments) {
       const gridRow = new Array<GridCell>();
-      gridRow.push([]);
-      gridRow.push([textValue(argumentUsage.label)]);
-      gridRow.push([]);
+      gridRow.push([textDelimiter()]);
+      gridRow.push([textInput(argumentUsage.label)]);
       if (argumentUsage.description) {
-        gridRow.push([textDesc(argumentUsage.description)]);
+        gridRow.push([textDelimiter()]);
+        gridRow.push([textDescription(argumentUsage.description)]);
+      }
+      grid.push(gridRow);
+    }
+    lines.push(...gridToPrintableLines(grid, typoSupport));
+  }
+
+  if (commandUsage.subcommands.length > 0) {
+    lines.push("");
+    lines.push(typoPrintableString(typoSupport, textCategory("Subcommands:")));
+    const grid = new Array<GridRow>();
+    for (const subcommand of commandUsage.subcommands) {
+      const gridRow = new Array<GridCell>();
+      gridRow.push([textDelimiter()]);
+      gridRow.push([textFixed(subcommand.name)]);
+      if (subcommand.description) {
+        gridRow.push([textDelimiter()]);
+        gridRow.push([textDescription(subcommand.description)]);
       }
       grid.push(gridRow);
     }
@@ -55,72 +74,57 @@ export function usageToPrintableLines(params: {
 
   if (commandUsage.options.length > 0) {
     lines.push("");
-    lines.push(typoPrintableString(typoSupport, textTitle("Options:")));
+    lines.push(typoPrintableString(typoSupport, textCategory("Options:")));
     const grid = new Array<GridRow>();
     for (const optionUsage of commandUsage.options) {
       const gridRow = new Array<GridCell>();
-      gridRow.push([]);
+      gridRow.push([textDelimiter()]);
       if (optionUsage.short) {
-        gridRow.push([textName(`-${optionUsage.short}`), { value: "," }]);
+        gridRow.push([textFixed(`-${optionUsage.short}`), { value: ", " }]);
       } else {
         gridRow.push([]);
       }
       if (optionUsage.label) {
         gridRow.push([
-          textName(`--${optionUsage.long} `),
-          textValue(optionUsage.label),
+          textFixed(`--${optionUsage.long} `),
+          textInput(optionUsage.label),
         ]);
       } else {
-        gridRow.push([
-          textName(`--${optionUsage.long}`),
-          { value: "[=yes|no]", color: "grey" },
-        ]);
+        gridRow.push([textFixed(`--${optionUsage.long}`)]);
       }
-      gridRow.push([]);
       if (optionUsage.description) {
-        gridRow.push([textDesc(optionUsage.description)]);
+        gridRow.push([textDelimiter()]);
+        gridRow.push([textDescription(optionUsage.description)]);
       }
       grid.push(gridRow);
     }
     lines.push(...gridToPrintableLines(grid, typoSupport));
   }
 
-  if (commandUsage.subcommands.length > 0) {
-    lines.push("");
-    lines.push(typoPrintableString(typoSupport, textTitle("Subcommands:")));
-    const grid = new Array<GridRow>();
-    for (const subcommand of commandUsage.subcommands) {
-      const gridRow = new Array<GridCell>();
-      gridRow.push([]);
-      gridRow.push([textName(subcommand.name)]);
-      gridRow.push([]);
-      if (subcommand.title) {
-        gridRow.push([textDesc(subcommand.title)]);
-      }
-      grid.push(gridRow);
-    }
-    lines.push(...gridToPrintableLines(grid, typoSupport));
-  }
   lines.push("");
   return lines;
 }
 
-function textTitle(text: string): TypoText {
-  return { value: text, color: "green", bold: true };
+function textCategory(text: string): TypoText {
+  return { value: text, color: "brightGreen", bold: true };
 }
 
-function textSubs(text: string): TypoText {
-  return { value: text, color: "grey" };
+function textDescription(text: string): TypoText {
+  return { value: text, bold: true };
 }
 
-function textDesc(text: string): TypoText {
-  return { value: text, bold: true };
+function textDetails(text: string): TypoText {
+  return { value: text, color: "brightBlack" };
+}
+
+function textFixed(text: string): TypoText {
+  return { value: text, color: "brightCyan", bold: true };
 }
 
-function textName(text: string): TypoText {
-  return { value: text, color: "cyan", bold: true };
+function textInput(text: string): TypoText {
+  return { value: text, color: "brightBlue" };
 }
 
-function textValue(text: string): TypoText {
-  return { value: text, color: "cyan" };
+function textDelimiter(): TypoText {
+  return { value: "  " };
 }

package/tests/{unit.command.run.ts → unit.command.runArgv.ts}

@@ -5,18 +5,19 @@ import {
   argumentVariadics,
   command,
   commandWithSubcommands,
+  execution,
   optionFlag,
   optionRepeatable,
   optionSingleValue,
-  process,
-  runWithArgv,
+  runCommand,
+  typeCommaList,
   typeNumber,
   typeString,
 } from "../src";
 
 const cmd = commandWithSubcommands<string, any, any>(
-  { title: "Root command title" },
-  process(
+  { description: "Root command description" },
+  execution(
     {
       options: {
         booleanFlag: optionFlag({ long: "boolean-flag", default: () => false }),
@@ -27,7 +28,7 @@ const cmd = commandWithSubcommands<string, any, any>(
         }),
         numberOption: optionRepeatable({
           long: "number-option",
-          type: typeNumber,
+          type: typeCommaList(typeNumber),
         }),
       },
       arguments: [
@@ -41,8 +42,8 @@ const cmd = commandWithSubcommands<string, any, any>(
   ),
   {
     sub1: command(
-      { title: "Subcommand 1 title" },
-      process(
+      { description: "Subcommand 1 description" },
+      execution(
         {
           options: {},
           arguments: [argumentRequired({ type: typeString })],
@@ -53,8 +54,8 @@ const cmd = commandWithSubcommands<string, any, any>(
       ),
     ),
     sub2: command(
-      { title: "Subcommand 2 title" },
-      process(
+      { description: "Subcommand 2 description" },
+      execution(
         {
           options: {},
           arguments: [
@@ -72,8 +73,9 @@ const cmd = commandWithSubcommands<string, any, any>(
 );
 
 it("run", async () => {
-  const res1 = await runWithArgv(
-    ["node", "script", "50", "51", "sub1", "final"],
+  const res1 = await runCommand(
+    "script",
+    ["50", "51", "sub1", "final"],
     "Run Context Input",
     cmd,
   );
@@ -97,18 +99,17 @@ it("run", async () => {
     at: "sub1",
   });
 
-  const res2 = await runWithArgv(
+  const res2 = await runCommand(
+    "script",
     [
-      "node",
-      "script",
       "40",
       "41",
       "sub2",
       "--string-option=hello",
       "--number-option",
-      "123",
+      "123.1,123.2",
       "--number-option",
-      "1234",
+      "123.3",
       "88.88",
       "a,b",
       "final",
@@ -124,7 +125,7 @@ it("run", async () => {
         options: {
           booleanFlag: true,
           stringOption: "hello",
-          numberOption: [123, 1234],
+          numberOption: [[123.1, 123.2], [123.3]],
         },
         arguments: [40, 41],
       },