cli-kiss 0.0.1 → 0.0.3

package/src/lib/Command.ts

@@ -1,10 +1,10 @@
 import { ArgumentUsage } from "./Argument";
+import { Execution } from "./Execution";
 import { OptionUsage } from "./Option";
-import { Processor } from "./Processor";
 import { ReaderTokenizer } from "./Reader";
 
 export type Command<Context, Result> = {
-  getDescription(): string | undefined;
+  getTitle(): string | undefined;
   prepareRunner(
     readerTokenizer: ReaderTokenizer,
   ): CommandRunner<Context, Result>;
@@ -16,48 +16,55 @@ export type CommandRunner<Context, Result> = {
 };
 
 export type CommandUsage = {
-  breadcrumbs: Array<string>;
-  description: string | undefined;
+  breadcrumbs: Array<CommandUsageBreadcrumb>;
+  title: string;
+  description: Array<string> | undefined;
   options: Array<OptionUsage>;
   arguments: Array<ArgumentUsage>;
-  subcommands: Array<{
-    name: string;
-    description: string | undefined;
-  }>;
+  subcommands: Array<{ name: string; title: string | undefined }>;
+};
+
+export type CommandUsageBreadcrumb = {
+  kind: "command" | "argument";
+  value: string;
 };
 
 export function command<Context, Result>(
-  description: string,
-  processor: Processor<Context, Result>,
+  metadata: {
+    title: string;
+    description?: Array<string>;
+  },
+  execution: Execution<Context, Result>,
 ): Command<Context, Result> {
   return {
-    getDescription() {
-      return description;
+    getTitle() {
+      return metadata.title;
     },
     prepareRunner(readerTokenizer: ReaderTokenizer) {
       function computeUsage(): CommandUsage {
-        const processorUsage = processor.computeUsage();
+        const executionUsage = execution.computeUsage();
         return {
-          breadcrumbs: processorUsage.arguments.map(
-            (argument) => argument.label,
+          breadcrumbs: executionUsage.arguments.map((argument) =>
+            breadcrumbArgument(argument.label),
           ),
-          description,
-          options: processorUsage.options,
-          arguments: processorUsage.arguments,
+          title: metadata.title,
+          description: metadata.description,
+          options: executionUsage.options,
+          arguments: executionUsage.arguments,
           subcommands: [],
         };
       }
       try {
-        const processorResolver = processor.prepareResolver(readerTokenizer);
+        const executionResolver = execution.prepareResolver(readerTokenizer);
         const lastPositional = readerTokenizer.consumePositional();
         if (lastPositional !== undefined) {
           throw Error(`Unprocessed positional: ${lastPositional}`);
         }
-        const processorRunner = processorResolver();
+        const executionCallback = executionResolver();
         return {
           computeUsage,
           async execute(context: Context) {
-            return await processorRunner.execute(context);
+            return await executionCallback(context);
           },
         };
       } catch (error) {
@@ -73,17 +80,20 @@ export function command<Context, Result>(
 }
 
 export function commandWithSubcommands<Context, Payload, Result>(
-  description: string,
-  processor: Processor<Context, Payload>,
+  metadata: {
+    title: string;
+    description?: Array<string>;
+  },
+  execution: Execution<Context, Payload>,
   subcommands: { [subcommand: Lowercase<string>]: Command<Payload, Result> },
 ): Command<Context, Result> {
   return {
-    getDescription() {
-      return description;
+    getTitle() {
+      return metadata.title;
     },
     prepareRunner(readerTokenizer: ReaderTokenizer) {
       try {
-        const processorResolver = processor.prepareResolver(readerTokenizer);
+        const executionResolver = execution.prepareResolver(readerTokenizer);
         const subcommandName = readerTokenizer.consumePositional();
         if (subcommandName === undefined) {
           throw new Error("Expected a subcommand");
@@ -94,44 +104,46 @@ export function commandWithSubcommands<Context, Payload, Result>(
           throw new Error(`Unknown subcommand: ${subcommandName}`);
         }
         const subcommandRunner = subcommandInput.prepareRunner(readerTokenizer);
-        const processorRunner = processorResolver();
+        const executionCallback = executionResolver();
         return {
           computeUsage() {
-            const processorUsage = processor.computeUsage();
+            const executionUsage = execution.computeUsage();
             const subcommandUsage = subcommandRunner.computeUsage();
             return {
-              breadcrumbs: processorUsage.arguments
-                .map((argument) => argument.label)
-                .concat([subcommandName])
+              breadcrumbs: executionUsage.arguments
+                .map((argument) => breadcrumbArgument(argument.label))
+                .concat([breadcrumbCommand(subcommandName)])
                 .concat(subcommandUsage.breadcrumbs),
+              title: subcommandUsage.title,
               description: subcommandUsage.description,
-              options: processorUsage.options.concat(subcommandUsage.options),
-              arguments: processorUsage.arguments.concat(
+              options: executionUsage.options.concat(subcommandUsage.options),
+              arguments: executionUsage.arguments.concat(
                 subcommandUsage.arguments,
               ),
               subcommands: subcommandUsage.subcommands,
             };
           },
           async execute(context: Context) {
-            const payload = await processorRunner.execute(context);
+            const payload = await executionCallback(context);
             return await subcommandRunner.execute(payload);
           },
         };
       } catch (error) {
         return {
           computeUsage() {
-            const processorUsage = processor.computeUsage();
+            const executionUsage = execution.computeUsage();
             return {
-              breadcrumbs: processorUsage.arguments
-                .map((argument) => argument.label)
-                .concat(["<SUBCOMMAND>"]),
-              description,
-              options: processorUsage.options,
-              arguments: processorUsage.arguments,
+              breadcrumbs: executionUsage.arguments
+                .map((argument) => breadcrumbArgument(argument.label))
+                .concat([breadcrumbCommand("<SUBCOMMAND>")]),
+              title: metadata.title,
+              description: metadata.description,
+              options: executionUsage.options,
+              arguments: executionUsage.arguments,
               subcommands: Object.entries(subcommands).map(
                 ([name, subcommand]) => ({
                   name,
-                  description: subcommand.getDescription(),
+                  title: subcommand.getTitle(),
                 }),
               ),
             };
@@ -144,3 +156,11 @@ export function commandWithSubcommands<Context, Payload, Result>(
     },
   };
 }
+
+function breadcrumbArgument(label: string): CommandUsageBreadcrumb {
+  return { kind: "argument", value: label };
+}
+
+function breadcrumbCommand(name: string): CommandUsageBreadcrumb {
+  return { kind: "command", value: name };
+}

package/src/lib/{Processor.ts → Execution.ts}

@@ -2,28 +2,28 @@ import { Argument, ArgumentUsage } from "./Argument";
 import { Option, OptionUsage } from "./Option";
 import { ReaderTokenizer } from "./Reader";
 
-export type Processor<Context, Result> = {
-  computeUsage(): ProcessorUsage;
+export type Execution<Context, Result> = {
+  computeUsage(): ExecutionUsage;
   prepareResolver(
     readerTokenizer: ReaderTokenizer,
-  ): ProcessorResolver<Context, Result>;
+  ): ExecutionResolver<Context, Result>;
 };
 
-export type ProcessorResolver<Context, Result> = () => ProcessorRunner<
+export type ExecutionResolver<Context, Result> = () => ExecutionCallback<
   Context,
   Result
 >;
 
-export type ProcessorRunner<Context, Result> = {
-  execute(context: Context): Promise<Result>;
-};
+export type ExecutionCallback<Context, Result> = (
+  context: Context,
+) => Promise<Result>;
 
-export type ProcessorUsage = {
+export type ExecutionUsage = {
   options: Array<OptionUsage>;
   arguments: Array<ArgumentUsage>;
 };
 
-export function processor<
+export function execution<
   Context,
   Result,
   Options extends { [option: string]: Option<any> },
@@ -43,7 +43,7 @@ export function processor<
       };
     },
   ) => Promise<Result>,
-): Processor<Context, Result> {
+): Execution<Context, Result> {
   return {
     computeUsage() {
       const optionsUsage = new Array<OptionUsage>();
@@ -73,13 +73,11 @@ export function processor<
         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

@@ -0,0 +1,56 @@
+import { TypoSupport, TypoText, typoPrintableString } from "./Typo";
+
+export type Grid = Array<GridRow>;
+export type GridRow = Array<GridCell>;
+export type GridCell = Array<TypoText>;
+
+export function gridToPrintableLines(grid: Grid, typoSupport: TypoSupport) {
+  const lines = new Array<string>();
+  const gridWidths = new Array<number>();
+  for (const gridRow of grid) {
+    for (
+      let gridColumnIndex = 0;
+      gridColumnIndex < gridRow.length;
+      gridColumnIndex++
+    ) {
+      const gridCell = gridRow[gridColumnIndex]!;
+      const length = gridCellLength(gridCell);
+      if (
+        gridWidths[gridColumnIndex] === undefined ||
+        length > gridWidths[gridColumnIndex]!
+      ) {
+        gridWidths[gridColumnIndex] = length;
+      }
+    }
+  }
+  for (const gridRow of grid) {
+    const lineColumns = new Array<string>();
+    for (
+      let gridColumnIndex = 0;
+      gridColumnIndex < gridRow.length;
+      gridColumnIndex++
+    ) {
+      const gridCell = gridRow[gridColumnIndex]!;
+      const parts = gridCell.map((text) =>
+        typoPrintableString(typoSupport, text),
+      );
+      if (gridColumnIndex < gridRow.length - 1) {
+        const length = gridCellLength(gridCell);
+        const padding = " ".repeat(gridWidths[gridColumnIndex]! - length);
+        lineColumns.push(parts.join("") + padding);
+      } else {
+        lineColumns.push(parts.join(""));
+      }
+    }
+    lines.push(lineColumns.join(" "));
+  }
+  return lines;
+}
+
+function gridCellLength(cell: GridCell): number {
+  let length = 0;
+  for (const text of cell) {
+    length += text.value.length;
+  }
+  return length;
+}

package/src/lib/Option.ts

@@ -122,7 +122,7 @@ export function optionSingleValue<Value>(definition: {
       }
       readerTokenizer.registerOption({ key, longs, shorts });
       return () => {
-        // TODO - error handling
+        // TODO - smooth and beautiful error handling
         const values = readerTokenizer.consumeOption(definition.long);
         if (values.length > 1) {
           throw new Error(

package/src/lib/Reader.ts

@@ -187,11 +187,9 @@ export class ReaderTokenizer {
     const flagKey = this.#flagKeyByLong.get(long);
     if (flagKey !== undefined) {
       if (direct !== null) {
-        if (direct === "true") {
-          return this.#acknowledgeFlag(flagKey, true);
-        }
-        if (direct === "false") {
-          return this.#acknowledgeFlag(flagKey, false);
+        const value = asBoolean(direct);
+        if (value !== undefined) {
+          return this.#acknowledgeFlag(flagKey, value);
         }
         throw new Error(
           `Invalid parameter for long flag: ${flagKey}, value: ${direct}`,
@@ -213,12 +211,9 @@ export class ReaderTokenizer {
     const flagKey = this.#flagKeyByShort.get(short);
     if (flagKey !== undefined) {
       if (rest.startsWith("=")) {
-        if (rest === "=true") {
-          this.#acknowledgeFlag(flagKey, true);
-          return true;
-        }
-        if (rest === "=false") {
-          this.#acknowledgeFlag(flagKey, false);
+        const value = asBoolean(rest.slice(1));
+        if (value !== undefined) {
+          this.#acknowledgeFlag(flagKey, value);
           return true;
         }
         throw new Error(
@@ -283,3 +278,14 @@ export class ReaderTokenizer {
     }
   }
 }
+
+function asBoolean(value: string): boolean | undefined {
+  const lower = value.toLowerCase();
+  if (lower === "true" || lower === "t" || lower === "y" || lower === "yes") {
+    return true;
+  }
+  if (lower === "false" || lower === "f" || lower === "n" || lower === "no") {
+    return false;
+  }
+  return undefined;
+}

package/src/lib/Run.ts

@@ -1,20 +1,20 @@
 import { Command } from "./Command";
 import { ReaderTokenizer } from "./Reader";
-import { usageFormatter } from "./Usage";
+import { typoInferSupport } from "./Typo";
+import { usageToPrintableLines } from "./Usage";
 
 export async function runWithArgv<Context, Result>(
   argv: string[],
   context: Context,
   command: Command<Context, Result>,
-  cliInfo?: { name?: string; version?: string; helpOnError?: boolean },
+  cliInfo?: {
+    name?: Lowercase<string>;
+    version?: string;
+    helpOnError?: boolean;
+  },
 ): Promise<Result> {
   const cliName = cliInfo?.name ?? argv[1]!;
   const readerTokenizer = new ReaderTokenizer(argv.slice(2));
-  readerTokenizer.registerFlag({
-    key: "help",
-    shorts: [],
-    longs: ["help"],
-  });
   if (cliInfo?.version) {
     readerTokenizer.registerFlag({
       key: "version",
@@ -22,6 +22,11 @@ export async function runWithArgv<Context, Result>(
       longs: ["version"],
     });
   }
+  readerTokenizer.registerFlag({
+    key: "help",
+    shorts: [],
+    longs: ["help"],
+  });
   /*
   // TODO - handle completions ?
   readerTokenizer.registerFlag({
@@ -39,14 +44,26 @@ export async function runWithArgv<Context, Result>(
       }
     }
     if (readerTokenizer.consumeFlag("help")) {
-      console.log(usageFormatter(cliName, commandRunner.computeUsage()));
+      console.log(
+        usageToPrintableLines({
+          cliName,
+          commandUsage: commandRunner.computeUsage(),
+          typoSupport: typoInferSupport(),
+        }).join("\n"),
+      );
       process.exit(0);
     }
     try {
       return await commandRunner.execute(context);
     } catch (error) {
       if (cliInfo?.helpOnError ?? true) {
-        console.log(usageFormatter(cliName, commandRunner.computeUsage()));
+        console.log(
+          usageToPrintableLines({
+            cliName,
+            commandUsage: commandRunner.computeUsage(),
+            typoSupport: typoInferSupport(),
+          }).join("\n"),
+        );
       }
       console.error(error);
       process.exit(1);

package/src/lib/Typo.ts

@@ -0,0 +1,73 @@
+export type TypoSupport = "none" | "tty" | "html" | "mock";
+
+export type TypoText = {
+  value: string;
+  color?: keyof typeof colorCodes;
+  bold?: boolean;
+};
+
+export function typoPrintableString(
+  typoSupport: TypoSupport,
+  typoText: TypoText,
+): string {
+  if (typoSupport === "none") {
+    return typoText.value;
+  }
+  if (typoSupport === "tty") {
+    const colorStartCode = typoText.color ? colorCodes[typoText.color] : "";
+    const colorBoldCode = typoText.bold ? boldCode : "";
+    return `${colorStartCode}${colorBoldCode}${typoText.value}${resetCode}`;
+  }
+  if (typoSupport === "html") {
+    const colorStartTag = typoText.color
+      ? `<span style="color: ${typoText.color}">`
+      : "";
+    const colorEndTag = typoText.color ? "</span>" : "";
+    const boldStartTag = typoText.bold ? "<b>" : "";
+    const boldEndTag = typoText.bold ? "</b>" : "";
+    return `${colorStartTag}${boldStartTag}${typoText.value}${boldEndTag}${colorEndTag}`;
+  }
+  if (typoSupport === "mock") {
+    if (typoText.color && typoText.bold) {
+      return `{${typoText.value}}@${typoText.color}+`;
+    }
+    if (typoText.color) {
+      return `{${typoText.value}}@${typoText.color}`;
+    }
+    if (typoText.bold) {
+      return `{${typoText.value}}+`;
+    }
+    return `{${typoText.value}}`;
+  }
+  throw new Error(`Unknown typo support: ${typoSupport}`);
+}
+
+export function typoInferSupport(): TypoSupport {
+  if (process.env) {
+    if (process.env["FORCE_COLOR"] === "0") {
+      return "none";
+    }
+    if (process.env["FORCE_COLOR"]) {
+      return "tty";
+    }
+    if ("NO_COLOR" in process.env) {
+      return "none";
+    }
+  }
+  if (!process || !process.stdout || !process.stdout.isTTY) {
+    return "none";
+  }
+  return "tty";
+}
+
+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",
+};