cli-kiss 0.1.0 → 0.1.2

package/src/lib/Run.ts

@@ -1,4 +1,4 @@
-import { Command, CommandRunner } from "./Command";
+import { Command, CommandFactory } from "./Command";
 import { ReaderArgs } from "./Reader";
 import { TypoSupport } from "./Typo";
 import { usageToStyledLines } from "./Usage";
@@ -9,31 +9,29 @@ export async function runAsCliAndExit<Context>(
   context: Context,
   command: Command<Context, void>,
   application?: {
-    usageOnError?: boolean | undefined;
     usageOnHelp?: boolean | undefined;
     buildVersion?: string | undefined;
     useColors?: boolean | undefined;
+    onExecutionError?: ((error: unknown) => void) | undefined;
     onLogStdOut?: ((message: string) => void) | undefined; // TODO - this is a problem, deep commands use console
     onLogStdErr?: ((message: string) => void) | undefined;
     onExit?: ((code: number) => never) | undefined;
-    onError?: ((error: unknown) => void) | undefined;
   },
 ): Promise<never> {
-  // TODO - can those flags could be implemented as a chained command ??
   const readerArgs = new ReaderArgs(cliArgs);
-  const buildVersion = application?.buildVersion;
-  if (buildVersion) {
+  const usageOnHelp = application?.usageOnHelp ?? true;
+  if (usageOnHelp) {
     readerArgs.registerOption({
       shorts: [],
-      longs: ["version"],
+      longs: ["help"],
       valued: false,
     });
   }
-  const usageOnHelp = application?.usageOnHelp ?? true;
-  if (usageOnHelp) {
+  const buildVersion = application?.buildVersion;
+  if (buildVersion) {
     readerArgs.registerOption({
       shorts: [],
-      longs: ["help"],
+      longs: ["version"],
       valued: false,
     });
   }
@@ -45,54 +43,57 @@ export async function runAsCliAndExit<Context>(
     longs: ["completion"],
   });
   */
-  const commandRunner = command.createRunnerFromArgs(readerArgs);
+  const commandFactory = command.createFactory(readerArgs);
   while (true) {
     const positional = readerArgs.consumePositional();
     if (positional === undefined) {
       break;
     }
   }
+  const typoSupport = chooseTypoSupport(application?.useColors);
   const onLogStdOut = application?.onLogStdOut ?? console.log;
+  const onLogStdErr = application?.onLogStdErr ?? console.error;
   const onExit = application?.onExit ?? process.exit;
-  if (buildVersion) {
-    if (readerArgs.getOptionValues("--version" as any).length > 0) {
-      onLogStdOut([cliName, buildVersion].join(" "));
+  if (usageOnHelp) {
+    if (readerArgs.getOptionValues("--help" as any).length > 0) {
+      onLogStdOut(computeUsageString(cliName, commandFactory, typoSupport));
       return onExit(0);
     }
   }
-  if (usageOnHelp) {
-    if (readerArgs.getOptionValues("--help" as any).length > 0) {
-      const typoSupport = chooseTypoSupport(application?.useColors);
-      onLogStdOut(computeUsageString(cliName, commandRunner, typoSupport));
+  if (buildVersion) {
+    if (readerArgs.getOptionValues("--version" as any).length > 0) {
+      onLogStdOut([cliName, buildVersion].join(" "));
       return onExit(0);
     }
   }
   try {
-    await commandRunner.executeWithContext(context);
-    return onExit(0);
-  } catch (error) {
-    if (application?.onError) {
-      application.onError(error);
-    } else {
-      const onLogStdErr = application?.onLogStdErr ?? console.error;
-      const typoSupport = chooseTypoSupport(application?.useColors);
-      if (application?.usageOnError ?? true) {
-        onLogStdErr(computeUsageString(cliName, commandRunner, typoSupport));
+    const commandInstance = commandFactory.createInstance();
+    try {
+      await commandInstance.executeWithContext(context);
+      return onExit(0);
+    } catch (error) {
+      if (application?.onExecutionError) {
+        application.onExecutionError(error);
+      } else {
+        onLogStdErr(typoSupport.computeStyledErrorMessage(error));
       }
-      onLogStdErr(typoSupport.computeStyledErrorMessage(error));
+      return onExit(1);
     }
+  } catch (error) {
+    onLogStdErr(computeUsageString(cliName, commandFactory, typoSupport));
+    onLogStdErr(typoSupport.computeStyledErrorMessage(error));
     return onExit(1);
   }
 }
 
 function computeUsageString<Context, Result>(
   cliName: Lowercase<string>,
-  commandRunner: CommandRunner<Context, Result>,
+  commandFactory: CommandFactory<Context, Result>,
   typoSupport: TypoSupport,
 ) {
   return usageToStyledLines({
     cliName,
-    commandUsage: commandRunner.generateUsage(),
+    commandUsage: commandFactory.generateUsage(),
     typoSupport,
   }).join("\n");
 }

package/src/lib/Type.ts

@@ -122,7 +122,7 @@ export function typeTuple<const Elements extends Array<any>>(
           () =>
             new TypoText(
               new TypoString(elementTypes[index]!.label, typoStyleUserInput),
-              new TypoString(` at position ${index}`),
+              new TypoString(`@${index}`),
             ),
         ),
       ) as Elements;
@@ -147,7 +147,7 @@ export function typeList<Value>(
             () =>
               new TypoText(
                 new TypoString(elementType.label, typoStyleUserInput),
-                new TypoString(` at position ${index}`),
+                new TypoString(`@${index}`),
               ),
           ),
         );

package/src/lib/Usage.ts

@@ -17,21 +17,6 @@ export function usageToStyledLines(params: {
 
   const lines = new Array<string>();
 
-  // TODO - description stacking for subcommands ?
-  lines.push(
-    textOverview(commandUsage.metadata.description).computeStyledString(
-      typoSupport,
-    ),
-  );
-  if (commandUsage.metadata.details) {
-    lines.push(
-      textSubtleInfo(commandUsage.metadata.details).computeStyledString(
-        typoSupport,
-      ),
-    );
-  }
-
-  lines.push("");
   const breadcrumbs = [
     textUsageTitle("Usage:").computeStyledString(typoSupport),
     textConstants(cliName).computeStyledString(typoSupport),
@@ -52,20 +37,28 @@ export function usageToStyledLines(params: {
   );
   lines.push(breadcrumbs.join(" "));
 
+  lines.push("");
+  const infoText = new TypoText();
+  infoText.pushString(textUsageIntro(commandUsage.information.description));
+  if (commandUsage.information.hint) {
+    infoText.pushString(textDelimiter(" "));
+    infoText.pushString(textSubtleInfo(`(${commandUsage.information.hint})`));
+  }
+  lines.push(infoText.computeStyledString(typoSupport));
+  if (commandUsage.information.details) {
+    const detailsString = textSubtleInfo(commandUsage.information.details);
+    lines.push(detailsString.computeStyledString(typoSupport));
+  }
+
   if (commandUsage.positionals.length > 0) {
     lines.push("");
     lines.push(textBlockTitle("Positionals:").computeStyledString(typoSupport));
     const typoGrid = new TypoGrid();
     for (const positionalUsage of commandUsage.positionals) {
       const typoGridRow = new Array<TypoText>();
-      typoGridRow.push(new TypoText(textDelimiter()));
+      typoGridRow.push(new TypoText(textDelimiter("  ")));
       typoGridRow.push(new TypoText(textUserInput(positionalUsage.label)));
-      if (positionalUsage.description) {
-        typoGridRow.push(new TypoText(textDelimiter()));
-        typoGridRow.push(
-          new TypoText(textUsefulInfo(positionalUsage.description)),
-        );
-      }
+      typoGridRow.push(...createInformationals(positionalUsage));
       typoGrid.pushRow(typoGridRow);
     }
     lines.push(
@@ -77,14 +70,11 @@ export function usageToStyledLines(params: {
     lines.push("");
     lines.push(textBlockTitle("Subcommands:").computeStyledString(typoSupport));
     const typoGrid = new TypoGrid();
-    for (const subcommand of commandUsage.subcommands) {
+    for (const subcommandUsage of commandUsage.subcommands) {
       const typoGridRow = new Array<TypoText>();
-      typoGridRow.push(new TypoText(textDelimiter()));
-      typoGridRow.push(new TypoText(textConstants(subcommand.name)));
-      if (subcommand.description) {
-        typoGridRow.push(new TypoText(textDelimiter()));
-        typoGridRow.push(new TypoText(textUsefulInfo(subcommand.description)));
-      }
+      typoGridRow.push(new TypoText(textDelimiter("  ")));
+      typoGridRow.push(new TypoText(textConstants(subcommandUsage.name)));
+      typoGridRow.push(...createInformationals(subcommandUsage));
       typoGrid.pushRow(typoGridRow);
     }
     lines.push(
@@ -98,7 +88,7 @@ export function usageToStyledLines(params: {
     const typoGrid = new TypoGrid();
     for (const optionUsage of commandUsage.options) {
       const typoGridRow = new Array<TypoText>();
-      typoGridRow.push(new TypoText(textDelimiter()));
+      typoGridRow.push(new TypoText(textDelimiter("  ")));
       if (optionUsage.short) {
         typoGridRow.push(
           new TypoText(
@@ -125,10 +115,7 @@ export function usageToStyledLines(params: {
           ),
         );
       }
-      if (optionUsage.description) {
-        typoGridRow.push(new TypoText(textDelimiter()));
-        typoGridRow.push(new TypoText(textUsefulInfo(optionUsage.description)));
-      }
+      typoGridRow.push(...createInformationals(optionUsage));
       typoGrid.pushRow(typoGridRow);
     }
     lines.push(
@@ -140,10 +127,33 @@ export function usageToStyledLines(params: {
   return lines;
 }
 
-function textOverview(value: string): TypoString {
+function createInformationals(usage: {
+  description: string | undefined;
+  hint: string | undefined;
+}): Array<TypoText> {
+  const informationals = [];
+  if (usage.description) {
+    informationals.push(textDelimiter(" "));
+    informationals.push(textUsefulInfo(usage.description));
+  }
+  if (usage.hint) {
+    informationals.push(textDelimiter(" "));
+    informationals.push(textSubtleInfo(`(${usage.hint})`));
+  }
+  if (informationals.length > 0) {
+    return [new TypoText(textDelimiter(" "), ...informationals)];
+  }
+  return [];
+}
+
+function textUsageIntro(value: string): TypoString {
   return new TypoString(value, { bold: true });
 }
 
+function textUsageTitle(value: string): TypoString {
+  return new TypoString(value, { fgColor: "darkMagenta", bold: true });
+}
+
 function textUsefulInfo(value: string): TypoString {
   return new TypoString(value);
 }
@@ -152,10 +162,6 @@ function textSubtleInfo(value: string): TypoString {
   return new TypoString(value, { italic: true, dim: true });
 }
 
-function textUsageTitle(value: string): TypoString {
-  return new TypoString(value, { fgColor: "darkMagenta", bold: true });
-}
-
 function textBlockTitle(value: string): TypoString {
   return new TypoString(value, { fgColor: "darkGreen", bold: true });
 }
@@ -168,6 +174,6 @@ function textUserInput(value: string): TypoString {
   return new TypoString(value, typoStyleUserInput);
 }
 
-function textDelimiter(value?: string): TypoString {
-  return new TypoString(value ?? "  ");
+function textDelimiter(value: string): TypoString {
+  return new TypoString(value);
 }

package/tests/unit.command.execute.ts

@@ -147,6 +147,7 @@ async function executeInterpreted<Context, Result>(
   command: Command<Context, Result>,
 ) {
   const readerArgs = new ReaderArgs(positionals);
-  const commandRunner = command.createRunnerFromArgs(readerArgs);
-  return await commandRunner.executeWithContext(context);
+  const commandFactory = command.createFactory(readerArgs);
+  const commandInstance = commandFactory.createInstance();
+  return await commandInstance.executeWithContext(context);
 }

package/tests/unit.command.usage.ts

@@ -94,6 +94,7 @@ const cmd = commandWithSubcommands<string, any, any>(
     sub2: command(
       {
         description: "Subcommand 2 description",
+        hint: "Subcommand 2 hint",
         details: [
           "Subcommand 2 details.",
           "Second line of subcommand 2 details.",
@@ -106,6 +107,7 @@ const cmd = commandWithSubcommands<string, any, any>(
               long: "dudu",
               type: typeString,
               default: () => "duduDefault",
+              hint: "Dudu option hint",
               description: "Dudu option description",
             }),
           },
@@ -118,6 +120,7 @@ const cmd = commandWithSubcommands<string, any, any>(
             positionalOptional({
               label: "OPT-POS",
               description: "Optional positional string",
+              hint: "Optional positional hint",
               type: typeString,
               default: () => "42",
             }),
@@ -148,18 +151,18 @@ it("run", async () => {
    */
 
   expect(usage1).toStrictEqual([
+    "{{Usage:}@darkMagenta}+ {{my-cli}@darkCyan}+ {{<POS-1>}@darkBlue}+ {{<POS-2>}@darkBlue}+ {{<SUBCOMMAND>}@darkCyan}+",
+    "",
     "{Root command description}+",
     "{{Root command details. Second line of root command details.}-}*",
     "",
-    "{{Usage:}@darkMagenta}+ {{my-cli}@darkCyan}+ {{<POS-1>}@darkBlue}+ {{<POS-2>}@darkBlue}+ {{<SUBCOMMAND>}@darkCyan}+",
-    "",
     "{{Positionals:}@darkGreen}+",
     "  {{<POS-1>}@darkBlue}+  Required positional number 1",
     "  {{<POS-2>}@darkBlue}+  Required positional number 2",
     "",
     "{{Subcommands:}@darkGreen}+",
     "  {{sub1}@darkCyan}+  Subcommand 1 description",
-    "  {{sub2}@darkCyan}+  Subcommand 2 description",
+    "  {{sub2}@darkCyan}+  Subcommand 2 description {{(Subcommand 2 hint)}-}*",
     "",
     "{{Options:}@darkGreen}+",
     "  {{-b}@darkCyan}+, {{--boolean-flag}@darkCyan}+{{[=no]}-}*                           Root boolean-flag description",
@@ -168,11 +171,11 @@ it("run", async () => {
     "",
   ]);
   expect(usage2).toStrictEqual([
+    "{{Usage:}@darkMagenta}+ {{my-cli}@darkCyan}+ {{<POS-1>}@darkBlue}+ {{<POS-2>}@darkBlue}+ {{sub1}@darkCyan}+ {{<POS-STRING>}@darkBlue}+",
+    "",
     "{Subcommand 1 description}+",
     "{{Subcommand 1 details. Second line of subcommand 1 details.}-}*",
     "",
-    "{{Usage:}@darkMagenta}+ {{my-cli}@darkCyan}+ {{<POS-1>}@darkBlue}+ {{<POS-2>}@darkBlue}+ {{sub1}@darkCyan}+ {{<POS-STRING>}@darkBlue}+",
-    "",
     "{{Positionals:}@darkGreen}+",
     "  {{<POS-1>}@darkBlue}+       Required positional number 1",
     "  {{<POS-2>}@darkBlue}+       Required positional number 2",
@@ -185,23 +188,23 @@ it("run", async () => {
     "",
   ]);
   expect(usage3).toStrictEqual([
-    "{Subcommand 2 description}+",
-    "{{Subcommand 2 details. Second line of subcommand 2 details.}-}*",
-    "",
     "{{Usage:}@darkMagenta}+ {{my-cli}@darkCyan}+ {{<POS-1>}@darkBlue}+ {{<POS-2>}@darkBlue}+ {{sub2}@darkCyan}+ {{<POS-NUMBER>}@darkBlue}+ {{[OPT-POS]}@darkBlue}+ {{[VARIADIC]...}@darkBlue}+",
     "",
+    "{Subcommand 2 description}+ {{(Subcommand 2 hint)}-}*",
+    "{{Subcommand 2 details. Second line of subcommand 2 details.}-}*",
+    "",
     "{{Positionals:}@darkGreen}+",
     "  {{<POS-1>}@darkBlue}+        Required positional number 1",
     "  {{<POS-2>}@darkBlue}+        Required positional number 2",
     "  {{<POS-NUMBER>}@darkBlue}+   Required positional number",
-    "  {{[OPT-POS]}@darkBlue}+      Optional positional string",
+    "  {{[OPT-POS]}@darkBlue}+      Optional positional string {{(Optional positional hint)}-}*",
     "  {{[VARIADIC]...}@darkBlue}+  Variadic positionals strings",
     "",
     "{{Options:}@darkGreen}+",
     "  {{-b}@darkCyan}+, {{--boolean-flag}@darkCyan}+{{[=no]}-}*                           Root boolean-flag description",
     "  {{-s}@darkCyan}+, {{--string-option}@darkCyan}+ {{<COOL-STUFF>}@darkBlue}+                  Root string-option description",
     "      {{--complex-option}@darkCyan}+ {{<NUMBER,STRING[,STRING]...>}@darkBlue}+  Root complex-option description",
-    "      {{--dudu}@darkCyan}+ {{<STRING>}@darkBlue}+                               Dudu option description",
+    "      {{--dudu}@darkCyan}+ {{<STRING>}@darkBlue}+                               Dudu option description {{(Dudu option hint)}-}*",
     "",
   ]);
 });
@@ -211,18 +214,10 @@ async function getUsage<Context, Result>(
   command: Command<Context, Result>,
 ) {
   const readerArgs = new ReaderArgs(args);
-  const commandRunner = command.createRunnerFromArgs(readerArgs);
-  /*
-  try {
-    const interpreterInstance = interpreterFactory.createInterpreterInstance();
-    console.log(await interpreterInstance.executeWithContext({} as Context));
-  } catch (error) {
-    console.error("Error during execution:", error);
-  }
-  */
+  const commandFactory = command.createFactory(readerArgs);
   return usageToStyledLines({
     cliName: "my-cli",
-    commandUsage: commandRunner.generateUsage(),
+    commandUsage: commandFactory.generateUsage(),
     typoSupport: TypoSupport.mock(),
   });
 }