cli-kiss 0.2.1 → 0.2.3

package/tests/unit.command.execute.ts

@@ -1,7 +1,8 @@
 import { expect, it } from "@jest/globals";
 import {
   command,
-  CommandDescriptor,
+  Command,
+  commandChained,
   commandWithSubcommands,
   operation,
   optionFlag,
@@ -16,64 +17,69 @@ import {
   typeString,
 } from "../src";
 
-const rootCommand = commandWithSubcommands<string, any, any>(
-  { description: "Root command description" },
+const rootCommand = commandChained(
+  { description: "?" },
   operation(
     {
-      options: {
-        booleanFlag: optionFlag({
-          long: "boolean-flag",
-          default: () => false,
-        }),
-        stringOption: optionSingleValue({
-          long: "string-option",
-          type: typeString,
-          default: () => undefined,
-        }),
-        numberOption: optionRepeatable({
-          long: "number-option",
-          type: typeList(typeNumber),
-        }),
-      },
-      positionals: [
-        positionalRequired({ type: typeNumber }),
-        positionalRequired({ type: typeNumber }),
-      ],
+      options: { flag: optionFlag({ short: "b", long: "boolean-flag" }) },
+      positionals: [positionalRequired({ label: "POS-1", type: typeNumber })],
     },
     async (context, inputs) => {
       return { at: "root", context, inputs };
     },
   ),
-  {
-    sub1: command(
-      { description: "Subcommand 1 description" },
-      operation(
-        {
-          options: {},
-          positionals: [positionalRequired({ type: typeString })],
-        },
-        async (context, inputs) => {
-          return { at: "sub1", context, inputs };
+  commandWithSubcommands<any, any, any>(
+    { description: "?" },
+    operation(
+      {
+        options: {
+          string: optionSingleValue({
+            long: "string-option",
+            type: typeString,
+            default: () => undefined,
+          }),
+          number: optionRepeatable({
+            long: "number-option",
+            type: typeList(typeNumber),
+          }),
         },
-      ),
+        positionals: [positionalRequired({ type: typeNumber })],
+      },
+      async (context, inputs) => {
+        return { at: "mid", context, inputs };
+      },
     ),
-    sub2: command(
-      { description: "Subcommand 2 description" },
-      operation(
-        {
-          options: {},
-          positionals: [
-            positionalRequired({ type: typeNumber }),
-            positionalOptional({ type: typeString, default: () => "42" }),
-            positionalVariadics({ type: typeString }),
-          ],
-        },
-        async (context, inputs) => {
-          return { at: "sub2", context, inputs };
-        },
+    {
+      sub1: command(
+        { description: "?" },
+        operation(
+          {
+            options: {},
+            positionals: [positionalRequired({ type: typeString })],
+          },
+          async (context, inputs) => {
+            return { at: "sub1", context, inputs };
+          },
+        ),
       ),
-    ),
-  },
+      sub2: command(
+        { description: "?" },
+        operation(
+          {
+            options: {},
+            positionals: [
+              positionalRequired({ type: typeNumber }),
+              positionalOptional({ type: typeString, default: () => "42" }),
+              positionalVariadics({ type: typeString }),
+            ],
+          },
+          async (context, inputs) => {
+            return { at: "sub2", context, inputs };
+          },
+        ),
+      ),
+    },
+  ),
 );
 
 it("run", async () => {
@@ -83,23 +89,26 @@ it("run", async () => {
     rootCommand,
   );
   expect(res1).toStrictEqual({
+    at: "sub1",
     context: {
-      context: "Run Context Input",
-      inputs: {
-        options: {
-          booleanFlag: false,
-          stringOption: undefined,
-          numberOption: [],
+      at: "mid",
+      context: {
+        at: "root",
+        context: "Run Context Input",
+        inputs: {
+          options: { flag: false },
+          positionals: [50],
         },
-        positionals: [50, 51],
       },
-      at: "root",
+      inputs: {
+        options: { string: undefined, number: [] },
+        positionals: [51],
+      },
     },
     inputs: {
       options: {},
       positionals: ["final"],
     },
-    at: "sub1",
   });
 
   const res2 = await executeInterpreted(
@@ -121,33 +130,36 @@ it("run", async () => {
     rootCommand,
   );
   expect(res2).toStrictEqual({
+    at: "sub2",
     context: {
-      context: "Run Context Input",
-      inputs: {
-        options: {
-          booleanFlag: true,
-          stringOption: "hello",
-          numberOption: [[123.1, 123.2], [123.3]],
+      at: "mid",
+      context: {
+        at: "root",
+        context: "Run Context Input",
+        inputs: {
+          options: { flag: true },
+          positionals: [40],
         },
-        positionals: [40, 41],
       },
-      at: "root",
+      inputs: {
+        options: { string: "hello", number: [[123.1, 123.2], [123.3]] },
+        positionals: [41],
+      },
     },
     inputs: {
       options: {},
       positionals: [88.88, "a,b", ["final"]],
     },
-    at: "sub2",
   });
 });
 
 async function executeInterpreted<Context, Result>(
   args: Array<string>,
   context: Context,
-  command: CommandDescriptor<Context, Result>,
+  command: Command<Context, Result>,
 ) {
   const readerArgs = new ReaderArgs(args);
-  const commandFactory = command.createFactory(readerArgs);
-  const commandInstance = commandFactory.createInstance();
-  return await commandInstance.executeWithContext(context);
+  const commandDecoder = command.consumeAndMakeDecoder(readerArgs);
+  const commandInterpreter = commandDecoder.decodeAndMakeInterpreter();
+  return await commandInterpreter.executeWithContext(context);
 }

package/tests/unit.command.usage.ts

@@ -1,7 +1,8 @@
 import { it } from "@jest/globals";
 import {
   command,
-  CommandDescriptor,
+  Command,
+  commandChained,
   commandWithSubcommands,
   operation,
   optionFlag,
@@ -19,10 +20,16 @@ import {
   usageToStyledLines,
 } from "../src";
 
-const cmd = commandWithSubcommands<string, any, any>(
+const rootCommand = commandChained<any, any, any>(
   {
     description: "Root command description",
-    details: ["Root command details.", "Second line of root command details."],
+    details: ["Root command details.", "Root second line of command details."],
+    examples: [
+      {
+        explanation: "Example usage of the root command",
+        commandArgs: [{ positional: "42" }, { option: { short: "b" } }],
+      },
+    ],
   },
   operation(
     {
@@ -30,20 +37,7 @@ const cmd = commandWithSubcommands<string, any, any>(
         booleanFlag: optionFlag({
           short: "b",
           long: "boolean-flag",
-          description: "Root boolean-flag description",
-        }),
-        stringOption: optionSingleValue({
-          short: "s",
-          long: "string-option",
-          type: typeString,
-          default: () => undefined,
-          label: "COOL-STUFF",
-          description: "Root string-option description",
-        }),
-        complexOption: optionRepeatable({
-          long: "complex-option",
-          type: typeTuple([typeNumber, typeList(typeString)]),
-          description: "Root complex-option description",
+          description: "boolean-flag description",
         }),
       },
       positionals: [
@@ -52,107 +46,203 @@ const cmd = commandWithSubcommands<string, any, any>(
           description: "Required positional number 1",
           type: typeNumber,
         }),
-        positionalRequired({
-          label: "POS-2",
-          description: "Required positional number 2",
-          type: typeNumber,
-        }),
       ],
     },
     async (context, inputs) => {
       return { at: "root", context, inputs };
     },
   ),
-  {
-    sub1: command(
-      {
-        description: "Subcommand 1 description",
-        details: [
-          "Subcommand 1 details.",
-          "Second line of subcommand 1 details.",
-        ],
-      },
-      operation(
+  commandWithSubcommands<any, any, any>(
+    {
+      description: "Mid command description",
+      details: ["Mid command details.", "Mid second line of command details."],
+      examples: [
         {
-          options: {},
-          positionals: [
-            positionalRequired({
-              label: "POS-STRING",
-              description: "Required positional string",
-              type: typeString,
-            }),
+          explanation: "Example usage of the mid command",
+          commandArgs: [
+            { positional: "42" },
+            { option: { short: "b" } },
+            { positional: "43" },
           ],
         },
-        async (context, inputs) => {
-          return { at: "sub1", context, inputs };
-        },
-      ),
-    ),
-    sub2: command(
+      ],
+    },
+    operation(
       {
-        description: "Subcommand 2 description",
-        hint: "Subcommand 2 hint",
-        details: [
-          "Subcommand 2 details.",
-          "Second line of subcommand 2 details.",
+        options: {
+          stringOption: optionSingleValue({
+            short: "s",
+            long: "string-option",
+            type: typeString,
+            default: () => undefined,
+            label: "COOL-STUFF",
+            description: "string-option description",
+          }),
+          complexOption: optionRepeatable({
+            long: "complex-option",
+            type: typeTuple([typeNumber, typeList(typeString)]),
+            description: "complex-option description",
+          }),
+        },
+        positionals: [
+          positionalRequired({
+            label: "POS-2",
+            description: "Required positional number 2",
+            type: typeNumber,
+          }),
         ],
       },
-      operation(
+      async (context, inputs) => {
+        return { at: "root", context, inputs };
+      },
+    ),
+    {
+      sub1: command(
         {
-          options: {
-            duduValue: optionSingleValue({
-              long: "dudu",
-              type: typeString,
-              default: () => "duduDefault",
-              hint: "Dudu option hint",
-              description: "Dudu option description",
-            }),
-          },
-          positionals: [
-            positionalRequired({
-              label: "POS-NUMBER",
-              description: "Required positional number",
-              type: typeNumber,
-            }),
-            positionalOptional({
-              label: "OPT-POS",
-              description: "Optional positional string",
-              hint: "Optional positional hint",
-              type: typeString,
-              default: () => "42",
-            }),
-            positionalVariadics({
-              label: "VARIADIC",
-              description: "Variadic positionals strings",
-              type: typeString,
-            }),
+          description: "Subcommand 1 description",
+          details: [
+            "Subcommand 1 details.",
+            "Subcommand 1 second line of details.",
+          ],
+          examples: [
+            {
+              explanation: "Example usage of subcommand 1",
+              commandArgs: [
+                { option: { short: "b" } },
+                { positional: "42" },
+                { positional: "43" },
+                { subcommand: "sub1" },
+                { positional: "valid" },
+              ],
+            },
           ],
         },
-        async (context, inputs) => {
-          return { at: "sub2", context, inputs };
+        operation(
+          {
+            options: {},
+            positionals: [
+              positionalRequired({
+                label: "POS-STRING",
+                description: "Required positional string",
+                type: typeString,
+              }),
+            ],
+          },
+          async (context, inputs) => {
+            return { at: "sub1", context, inputs };
+          },
+        ),
+      ),
+      sub2: command(
+        {
+          description: "Subcommand 2 description",
+          hint: "Subcommand 2 hint",
+          details: [
+            "Subcommand 2 details.",
+            "Subcommand 2 second line of details.",
+          ],
+          examples: [
+            {
+              explanation: "Example usage of subcommand 2",
+              commandArgs: [
+                { positional: "40" },
+                { positional: "41" },
+                { subcommand: "sub2" },
+                { option: { long: "dudu", value: "hello" } },
+                { positional: "50" },
+              ],
+            },
+          ],
         },
+        operation(
+          {
+            options: {
+              duduValue: optionSingleValue({
+                long: "dudu",
+                type: typeString,
+                default: () => "duduDefault",
+                hint: "Dudu option hint",
+                description: "Dudu option description",
+              }),
+            },
+            positionals: [
+              positionalRequired({
+                label: "POS-NUMBER",
+                description: "Required positional number",
+                type: typeNumber,
+              }),
+              positionalOptional({
+                label: "OPT-POS",
+                description: "Optional positional string",
+                hint: "Optional positional hint",
+                type: typeString,
+                default: () => "42",
+              }),
+              positionalVariadics({
+                label: "VARIADIC",
+                description: "Variadic positionals strings",
+                type: typeString,
+              }),
+            ],
+          },
+          async (context, inputs) => {
+            return { at: "sub2", context, inputs };
+          },
+        ),
       ),
-    ),
-  },
+    },
+  ),
 );
 
 it("run", async () => {
-  const usage1 = await getUsage([], cmd);
-  const usage2 = await getUsage(["50", "51", "sub1"], cmd);
-  const usage3 = await getUsage(["40", "41", "sub2", "--doesn't-exist"], cmd);
+  const usage1 = await getUsage([], rootCommand);
+  const usage2 = await getUsage(["50"], rootCommand);
+  const usage3 = await getUsage(["50", "51"], rootCommand);
+  const usage4 = await getUsage(["50", "51", "sub1"], rootCommand);
+  const usage5 = await getUsage(["50", "51", "sub1", "valid"], rootCommand);
+  const usage6 = await getUsage(
+    ["40", "41", "sub2", "--doesn't-exist"],
+    rootCommand,
+  );
+  const usage7 = await getUsage(
+    ["40", "41", "sub2", "not-a-number"],
+    rootCommand,
+  );
 
-  /*
   console.log(usage1.join("\n"));
   console.log(usage2.join("\n"));
   console.log(usage3.join("\n"));
+  console.log(usage4.join("\n"));
+  console.log(usage5.join("\n"));
+  console.log(usage6.join("\n"));
+  console.log(usage7.join("\n"));
+  /*
    */
 
-  expect(usage1).toStrictEqual([
-    "{{Usage:}@darkMagenta}+ {{my-cli}@darkCyan}+ {{<POS-1>}@darkBlue}+ {{<POS-2>}@darkBlue}+ {{<SUBCOMMAND>}@darkBlue}+",
+  const usageRoot = [
+    "{{Usage:}@darkMagenta}+ {{my-cli}@darkCyan}+ {{<POS-1>}@darkBlue}+ {{[REST]...}@darkBlue}+",
     "",
     "{Root command description}+",
     "{{Root command details.}-}*",
-    "{{Second line of root command details.}-}*",
+    "{{Root second line of command details.}-}*",
+    "",
+    "{{Positionals:}@darkGreen}+",
+    "  {{<POS-1>}@darkBlue}+  Required positional number 1",
+    "",
+    "{{Options:}@darkGreen}+",
+    "  {{-b}@darkCyan}+, {{--boolean-flag}@darkCyan}+{{[=no]}-}*  boolean-flag description",
+    "",
+    "{{Examples:}@darkGreen}+",
+    "  {{# Example usage of the root command}-}*",
+    "  {{my-cli}@darkCyan}+ {{42}@darkBlue}+ {{-b}@darkCyan}+",
+    "",
+  ];
+  const usageMid = [
+    "{{Usage:}@darkMagenta}+ {{my-cli}@darkCyan}+ {{<POS-1>}@darkBlue}+ {{<POS-2>}@darkBlue}+ {{<SUBCOMMAND>}@darkBlue}+",
+    "",
+    "{Mid command description}+",
+    "{{Mid command details.}-}*",
+    "{{Mid second line of command details.}-}*",
     "",
     "{{Positionals:}@darkGreen}+",
     "  {{<POS-1>}@darkBlue}+  Required positional number 1",
@@ -163,17 +253,21 @@ it("run", async () => {
     "  {{sub2}@darkCyan}+  Subcommand 2 description {{(Subcommand 2 hint)}-}*",
     "",
     "{{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",
+    "  {{-b}@darkCyan}+, {{--boolean-flag}@darkCyan}+{{[=no]}-}*                           boolean-flag description",
+    "  {{-s}@darkCyan}+, {{--string-option}@darkCyan}+ {{<COOL-STUFF>}@darkBlue}+                  string-option description",
+    "      {{--complex-option}@darkCyan}+ {{<NUMBER,STRING[,STRING]...>}@darkBlue}+  complex-option description",
+    "",
+    "{{Examples:}@darkGreen}+",
+    "  {{# Example usage of the mid command}-}*",
+    "  {{my-cli}@darkCyan}+ {{42}@darkBlue}+ {{-b}@darkCyan}+ {{43}@darkBlue}+",
     "",
-  ]);
-  expect(usage2).toStrictEqual([
+  ];
+  const usageSub1 = [
     "{{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.}-}*",
+    "{{Subcommand 1 second line of details.}-}*",
     "",
     "{{Positionals:}@darkGreen}+",
     "  {{<POS-1>}@darkBlue}+       Required positional number 1",
@@ -181,17 +275,21 @@ it("run", async () => {
     "  {{<POS-STRING>}@darkBlue}+  Required positional string",
     "",
     "{{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",
+    "  {{-b}@darkCyan}+, {{--boolean-flag}@darkCyan}+{{[=no]}-}*                           boolean-flag description",
+    "  {{-s}@darkCyan}+, {{--string-option}@darkCyan}+ {{<COOL-STUFF>}@darkBlue}+                  string-option description",
+    "      {{--complex-option}@darkCyan}+ {{<NUMBER,STRING[,STRING]...>}@darkBlue}+  complex-option description",
+    "",
+    "{{Examples:}@darkGreen}+",
+    "  {{# Example usage of subcommand 1}-}*",
+    "  {{my-cli}@darkCyan}+ {{-b}@darkCyan}+ {{42}@darkBlue}+ {{43}@darkBlue}+ {{sub1}@darkCyan}+ {{valid}@darkBlue}+",
     "",
-  ]);
-  expect(usage3).toStrictEqual([
+  ];
+  const usageSub2 = [
     "{{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.}-}*",
+    "{{Subcommand 2 second line of details.}-}*",
     "",
     "{{Positionals:}@darkGreen}+",
     "  {{<POS-1>}@darkBlue}+        Required positional number 1",
@@ -201,23 +299,46 @@ it("run", async () => {
     "  {{[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",
+    "  {{-b}@darkCyan}+, {{--boolean-flag}@darkCyan}+{{[=no]}-}*                           boolean-flag description",
+    "  {{-s}@darkCyan}+, {{--string-option}@darkCyan}+ {{<COOL-STUFF>}@darkBlue}+                  string-option description",
+    "      {{--complex-option}@darkCyan}+ {{<NUMBER,STRING[,STRING]...>}@darkBlue}+  complex-option description",
     "      {{--dudu}@darkCyan}+ {{<STRING>}@darkBlue}+                               Dudu option description {{(Dudu option hint)}-}*",
     "",
-  ]);
+    "{{Examples:}@darkGreen}+",
+    "  {{# Example usage of subcommand 2}-}*",
+    "  {{my-cli}@darkCyan}+ {{40}@darkBlue}+ {{41}@darkBlue}+ {{sub2}@darkCyan}+ {{--dudu}@darkCyan}+{{=}-}*{{hello}@darkBlue}+ {{50}@darkBlue}+",
+    "",
+  ];
+
+  expect(usage1).toStrictEqual(usageRoot);
+  expect(usage2).toStrictEqual(usageMid);
+  expect(usage3).toStrictEqual(usageMid);
+  expect(usage4).toStrictEqual(usageSub1);
+  expect(usage5).toStrictEqual(usageSub1);
+  expect(usage6).toStrictEqual(usageSub2);
+  expect(usage7).toStrictEqual(usageSub2);
 });
 
 async function getUsage<Context, Result>(
   args: Array<string>,
-  command: CommandDescriptor<Context, Result>,
+  command: Command<Context, Result>,
 ) {
   const readerArgs = new ReaderArgs(args);
-  const commandFactory = command.createFactory(readerArgs);
+  const commandDecoder = command.consumeAndMakeDecoder(readerArgs);
+  /*
+  try {
+    const interpreter = commandDecoder.decodeAndMakeInterpreter();
+    const result = await interpreter.executeWithContext(
+      "" as unknown as Context,
+    );
+    console.log(result);
+  } catch (error) {
+    console.log(TypoSupport.tty().computeStyledErrorMessage(error));
+  }
+    */
   return usageToStyledLines({
     cliName: "my-cli",
-    commandUsage: commandFactory.generateUsage(),
-    typoSupport: TypoSupport.mock(),
+    commandUsage: commandDecoder.generateUsage(),
+    typoSupport: TypoSupport.tty(),
   });
 }