@forwardimpact/libcli 0.1.4 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libcli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Shared CLI infrastructure for the Forward Impact monorepo",
   "license": "Apache-2.0",
   "author": "D. Olsson <hi@senzilla.io>",

package/src/cli.js

@@ -39,7 +39,23 @@ export class Cli {
 
   parse(argv) {
     const command = this.#findCommand(argv);
+    const options = this.#buildOptions(command);
+    const { values, positionals } = this.#parseArgs(argv, options);
 
+    if (values.help) {
+      this.#renderHelp(command, values.json);
+      return null;
+    }
+
+    if (values.version && this.#definition.version) {
+      this.#proc.stdout.write(this.#definition.version + "\n");
+      return null;
+    }
+
+    return { values, positionals };
+  }
+
+  #buildOptions(command) {
     const globalOpts = this.#definition.globalOptions || {};
     const commandOpts = command?.options || {};
     const merged = { ...globalOpts, ...commandOpts };
@@ -51,32 +67,46 @@ export class Cli {
       if (opt.default !== undefined) options[name].default = opt.default;
       if (opt.multiple) options[name].multiple = opt.multiple;
     }
+    return options;
+  }
 
-    const { values, positionals } = parseArgs({
-      options,
-      allowPositionals: true,
-      args: argv,
-    });
-
-    if (values.help) {
-      if (values.json) {
-        this.#helpRenderer.renderJson(
-          this.#definition,
-          this.#proc.stdout,
-          command,
-        );
-      } else {
-        this.#helpRenderer.render(this.#definition, this.#proc.stdout, command);
+  #parseArgs(argv, options) {
+    try {
+      return parseArgs({ options, allowPositionals: true, args: argv });
+    } catch (err) {
+      if (err.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
+        const commandError = this.#commandAsOptionError(err);
+        if (commandError) throw commandError;
       }
-      return null;
+      throw err;
     }
+  }
 
-    if (values.version && this.#definition.version) {
-      this.#proc.stdout.write(this.#definition.version + "\n");
-      return null;
-    }
+  #commandAsOptionError(err) {
+    const match = err.message.match(/'(--?)([^']+)'/);
+    if (!match) return null;
+    const bare = match[2];
+    const asCommand = this.#definition.commands?.find((c) => c.name === bare);
+    if (!asCommand) return null;
+    const usage = asCommand.args
+      ? `${this.#definition.name} ${bare} ${asCommand.args}`
+      : `${this.#definition.name} ${bare}`;
+    return new Error(
+      `Unknown option "${match[1]}${bare}". "${bare}" is a command, not an option. Usage: ${usage}`,
+      { cause: err },
+    );
+  }
 
-    return { values, positionals };
+  #renderHelp(command, asJson) {
+    if (asJson) {
+      this.#helpRenderer.renderJson(
+        this.#definition,
+        this.#proc.stdout,
+        command,
+      );
+    } else {
+      this.#helpRenderer.render(this.#definition, this.#proc.stdout, command);
+    }
   }
 
   #findCommand(argv) {

package/src/help.js

@@ -83,6 +83,20 @@ export class HelpRenderer {
     return this.#renderExamplesArray(definition.examples);
   }
 
+  #renderDocumentation(definition) {
+    if (!definition.documentation || definition.documentation.length === 0) {
+      return [];
+    }
+    const lines = [this.#sectionHeader("Documentation:")];
+    for (const entry of definition.documentation) {
+      lines.push(`  ${entry.title}`);
+      lines.push(`    ${entry.url}`);
+      if (entry.description) lines.push(`    ${entry.description}`);
+    }
+    lines.push("");
+    return lines;
+  }
+
   #renderHintLine(definition) {
     if (!definition.commands || definition.commands.length === 0) return [];
     return [
@@ -135,6 +149,7 @@ export class HelpRenderer {
       ...this.#renderCommands(definition),
       ...this.#renderOptionSection(definition.globalOptions, "Options:"),
       ...this.#renderExamples(definition),
+      ...this.#renderDocumentation(definition),
       ...this.#renderHintLine(definition),
     ];
     out.write(lines.join("\n"));