@forwardimpact/libcli 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,9 @@
+# libcli
+
+Shared CLI infrastructure for Forward Impact products.
+
+## Getting Started
+
+```js
+import { createCli, HelpRenderer, SummaryRenderer } from '@forwardimpact/libcli';
+```

package/package.json

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

package/src/cli.js

@@ -7,6 +7,27 @@ export class Cli {
   #helpRenderer;
 
   constructor(definition, { process, helpRenderer }) {
+    if (definition.options) {
+      throw new Error(
+        `${definition.name}: "options" is no longer supported. ` +
+          `Use "globalOptions" for shared options and per-command "options" ` +
+          `for command-specific options.`,
+      );
+    }
+    if (definition.commands && definition.globalOptions) {
+      const globalNames = new Set(Object.keys(definition.globalOptions));
+      for (const cmd of definition.commands) {
+        if (!cmd.options) continue;
+        for (const name of Object.keys(cmd.options)) {
+          if (globalNames.has(name)) {
+            throw new Error(
+              `${definition.name}: option "${name}" in command ` +
+                `"${cmd.name}" collides with a global option`,
+            );
+          }
+        }
+      }
+    }
     this.#definition = definition;
     this.#proc = process;
     this.#helpRenderer = helpRenderer;
@@ -17,8 +38,14 @@ export class Cli {
   }
 
   parse(argv) {
+    const command = this.#findCommand(argv);
+
+    const globalOpts = this.#definition.globalOptions || {};
+    const commandOpts = command?.options || {};
+    const merged = { ...globalOpts, ...commandOpts };
+
     const options = {};
-    for (const [name, opt] of Object.entries(this.#definition.options || {})) {
+    for (const [name, opt] of Object.entries(merged)) {
       options[name] = { type: opt.type };
       if (opt.short) options[name].short = opt.short;
       if (opt.default !== undefined) options[name].default = opt.default;
@@ -33,9 +60,13 @@ export class Cli {
 
     if (values.help) {
       if (values.json) {
-        this.#helpRenderer.renderJson(this.#definition, this.#proc.stdout);
+        this.#helpRenderer.renderJson(
+          this.#definition,
+          this.#proc.stdout,
+          command,
+        );
       } else {
-        this.#helpRenderer.render(this.#definition, this.#proc.stdout);
+        this.#helpRenderer.render(this.#definition, this.#proc.stdout, command);
       }
       return null;
     }
@@ -48,6 +79,20 @@ export class Cli {
     return { values, positionals };
   }
 
+  #findCommand(argv) {
+    const commands = this.#definition.commands;
+    if (!commands || commands.length === 0) return null;
+
+    const positionals = argv.filter((a) => !a.startsWith("-"));
+
+    for (let len = Math.min(positionals.length, 3); len > 0; len--) {
+      const candidate = positionals.slice(0, len).join(" ");
+      const found = commands.find((c) => c.name === candidate);
+      if (found) return found;
+    }
+    return null;
+  }
+
   showHelp() {
     this.#helpRenderer.render(this.#definition, this.#proc.stdout);
   }

package/src/help.js

@@ -48,11 +48,11 @@ export class HelpRenderer {
     return lines;
   }
 
-  #renderOptions(definition) {
-    if (!definition.options) return [];
-    const entries = Object.entries(definition.options);
+  #renderOptionSection(options, title) {
+    if (!options) return [];
+    const entries = Object.entries(options);
     if (entries.length === 0) return [];
-    const lines = [this.#sectionHeader("Options:")];
+    const lines = [this.#sectionHeader(title)];
     const optStrings = entries.map(([name, opt]) => {
       let s = `--${name}`;
       if (opt.type === "string") s += `=<${opt.type}>`;
@@ -69,30 +69,99 @@ export class HelpRenderer {
     return lines;
   }
 
-  #renderExamples(definition) {
-    if (!definition.examples || definition.examples.length === 0) return [];
+  #renderExamplesArray(examples) {
+    if (!examples || examples.length === 0) return [];
     const lines = [this.#sectionHeader("Examples:")];
-    for (const ex of definition.examples) {
+    for (const ex of examples) {
       lines.push(`  ${ex}`);
     }
     lines.push("");
     return lines;
   }
 
-  render(definition, stream) {
+  #renderExamples(definition) {
+    return this.#renderExamplesArray(definition.examples);
+  }
+
+  #renderHintLine(definition) {
+    if (!definition.commands || definition.commands.length === 0) return [];
+    return [
+      `Use ${definition.name} <command> --help for command-specific options.`,
+      "",
+    ];
+  }
+
+  #renderCommand(definition, stream, command) {
+    let header = `${definition.name} ${command.name}`;
+    if (command.args) header += ` ${command.args}`;
+    if (command.description) header += ` \u2014 ${command.description}`;
+    const formatted = supportsColor(this.#proc)
+      ? formatHeader(header, this.#proc)
+      : header;
+
+    let usage = `Usage: ${definition.name} ${command.name}`;
+    if (command.args) usage += ` ${command.args}`;
+    usage += " [options]";
+
+    const globalWithoutVersion = definition.globalOptions
+      ? Object.fromEntries(
+          Object.entries(definition.globalOptions).filter(
+            ([name]) => name !== "version",
+          ),
+        )
+      : null;
+
+    const lines = [
+      formatted,
+      "",
+      usage,
+      "",
+      ...this.#renderOptionSection(command.options, "Options:"),
+      ...this.#renderOptionSection(globalWithoutVersion, "Global options:"),
+      ...this.#renderExamplesArray(command.examples),
+    ];
+    stream.write(lines.join("\n"));
+  }
+
+  render(definition, stream, command) {
     const out = stream || this.#proc.stdout;
+    if (command) {
+      this.#renderCommand(definition, out, command);
+      return;
+    }
     const lines = [
       ...this.#renderHeader(definition),
       ...this.#renderUsage(definition),
       ...this.#renderCommands(definition),
-      ...this.#renderOptions(definition),
+      ...this.#renderOptionSection(definition.globalOptions, "Options:"),
       ...this.#renderExamples(definition),
+      ...this.#renderHintLine(definition),
     ];
     out.write(lines.join("\n"));
   }
 
-  renderJson(definition, stream) {
+  renderJson(definition, stream, command) {
     const out = stream || this.#proc.stdout;
-    out.write(JSON.stringify(definition, null, 2) + "\n");
+    if (command) {
+      const globalWithoutVersion = definition.globalOptions
+        ? Object.fromEntries(
+            Object.entries(definition.globalOptions).filter(
+              ([name]) => name !== "version",
+            ),
+          )
+        : undefined;
+      const obj = {
+        name: command.name,
+        args: command.args,
+        description: command.description,
+        parent: definition.name,
+        options: command.options,
+        globalOptions: globalWithoutVersion,
+        examples: command.examples,
+      };
+      out.write(JSON.stringify(obj, null, 2) + "\n");
+    } else {
+      out.write(JSON.stringify(definition, null, 2) + "\n");
+    }
   }
 }