@forwardimpact/libcli 0.1.7 → 0.1.9

package/README.md

@@ -1,6 +1,11 @@
 # libcli
 
-Shared CLI infrastructure for Forward Impact products.
+<!-- BEGIN:description — Do not edit. Generated from package.json. -->
+
+Agent-friendly CLIs — self-documenting entry points that humans and agents reach
+through the same interface.
+
+<!-- END:description -->
 
 ## Getting Started
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@forwardimpact/libcli",
-  "version": "0.1.7",
-  "description": "Agent-friendly CLIs: argument parsing, grep-friendly help output, JSON mode, and skill-doc links surfaced in `--help`.",
+  "version": "0.1.9",
+  "description": "Agent-friendly CLIs — self-documenting entry points that humans and agents reach through the same interface.",
   "keywords": [
     "cli",
     "agent",
@@ -9,16 +9,24 @@
     "help",
     "grep"
   ],
-  "forwardimpact": {
-    "capability": "agent-capability",
-    "needs": [
-      "Parse CLI args and render help",
-      "Render colored tables and JSON output",
-      "Surface skill-doc links in CLI --help output"
-    ]
+  "homepage": "https://www.forwardimpact.team",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forwardimpact/monorepo.git",
+    "directory": "libraries/libcli"
   },
   "license": "Apache-2.0",
   "author": "D. Olsson <hi@senzilla.io>",
+  "jobs": [
+    {
+      "user": "Platform Builders",
+      "goal": "Enable Agents on Every Surface",
+      "trigger": "Building an interface and realizing agents can't discover or navigate it the same way humans do.",
+      "bigHire": "give agents and humans the same interface so capabilities don't need separate paths.",
+      "littleHire": "add a capability and know both humans and agents can reach it without a separate integration.",
+      "competesWith": "hand-written argument parsing; separate agent and human interfaces; tolerating agents that can't self-serve"
+    }
+  ],
   "type": "module",
   "main": "./src/index.js",
   "exports": {
@@ -28,22 +36,17 @@
     "src/**/*.js",
     "README.md"
   ],
-  "engines": {
-    "bun": ">=1.2.0",
-    "node": ">=18.0.0"
-  },
   "scripts": {
     "test": "bun test test/*.test.js"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/forwardimpact/monorepo.git",
-    "directory": "libraries/libcli"
+  "devDependencies": {
+    "@forwardimpact/libharness": "^0.1.14"
+  },
+  "engines": {
+    "bun": ">=1.2.0",
+    "node": ">=18.0.0"
   },
   "publishConfig": {
     "access": "public"
-  },
-  "devDependencies": {
-    "@forwardimpact/libharness": "^0.1.14"
   }
 }

package/src/cli.js

@@ -1,11 +1,14 @@
 import { parseArgs } from "node:util";
 import { HelpRenderer } from "./help.js";
+import { freezeInvocationContext } from "./invocation-context.js";
 
+/** Command-line interface that parses argv against a definition of commands, options, and help. */
 export class Cli {
   #definition;
   #proc;
   #helpRenderer;
 
+  /** Build a CLI from a definition, wiring in the process handle and help renderer; throws if the deprecated top-level `options` key is present or if any command option name collides with a global option. */
   constructor(definition, { process, helpRenderer }) {
     if (definition.options) {
       throw new Error(
@@ -14,29 +17,34 @@ export class Cli {
           `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`,
-            );
-          }
-        }
-      }
-    }
+    Cli.#validateNoCollisions(definition);
     this.#definition = definition;
     this.#proc = process;
     this.#helpRenderer = helpRenderer;
   }
 
+  static #validateNoCollisions(definition) {
+    if (!definition.commands || !definition.globalOptions) return;
+    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`,
+          );
+        }
+      }
+    }
+  }
+
+  /** Return the CLI program name from the definition. */
   get name() {
     return this.#definition.name;
   }
 
+  /** Parse argv into values and positionals, handling --help and --version; returns null when help or version is printed. */
   parse(argv) {
     const command = this.#findCommand(argv);
     const options = this.#buildOptions(command);
@@ -88,8 +96,11 @@ export class Cli {
     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}`
+    const argsStr = Array.isArray(asCommand.args)
+      ? asCommand.argsUsage
+      : asCommand.args;
+    const usage = argsStr
+      ? `${this.#definition.name} ${bare} ${argsStr}`
       : `${this.#definition.name} ${bare}`;
     return new Error(
       `Unknown option "${match[1]}${bare}". "${bare}" is a command, not an option. Usage: ${usage}`,
@@ -123,21 +134,51 @@ export class Cli {
     return null;
   }
 
+  /** Match parsed positionals to a subcommand and invoke its handler with a frozen invocation context. */
+  dispatch(parsed, { data }) {
+    const command = this.#findCommand(parsed.positionals);
+    if (!command) {
+      throw new Error(`${this.#definition.name}: no matching subcommand`);
+    }
+    if (typeof command.handler !== "function") {
+      throw new Error(
+        `${this.#definition.name}: subcommand "${command.name}" lacks a handler — ` +
+          `dispatch() requires { args: string[], handler: (ctx) => any }`,
+      );
+    }
+    const consumed = command.name.split(" ").length;
+    const argv = parsed.positionals.slice(consumed);
+    const argNames = Array.isArray(command.args) ? command.args : [];
+    const args = Object.fromEntries(
+      argNames.map((n, i) => [n, argv[i]]).filter(([, v]) => v !== undefined),
+    );
+    const ctx = freezeInvocationContext({
+      data,
+      args,
+      options: parsed.values,
+    });
+    return command.handler(ctx);
+  }
+
+  /** Print the top-level help text to stdout. */
   showHelp() {
     this.#helpRenderer.render(this.#definition, this.#proc.stdout);
   }
 
+  /** Write an error message to stderr and set exit code 1. */
   error(message) {
     this.#proc.stderr.write(`${this.#definition.name}: error: ${message}\n`);
     this.#proc.exitCode = 1;
   }
 
+  /** Write a usage error message to stderr and set exit code 2. */
   usageError(message) {
     this.#proc.stderr.write(`${this.#definition.name}: error: ${message}\n`);
     this.#proc.exitCode = 2;
   }
 }
 
+/** Create a Cli instance wired to the real process and a default HelpRenderer. */
 export function createCli(definition) {
   const helpRenderer = new HelpRenderer({ process });
   return new Cli(definition, { process, helpRenderer });

package/src/format.js

@@ -84,7 +84,7 @@ export function formatTable(headers, rows, options = {}, proc = process) {
 }
 
 /**
- * Format an error message
+ * Prefix the message with "Error: " and colorize red.
  * @param {string} message
  * @param {object} proc
  * @returns {string}
@@ -104,7 +104,7 @@ export function formatSuccess(message, proc = process) {
 }
 
 /**
- * Format a warning message
+ * Prefix the message with "Warning: " and colorize yellow.
  * @param {string} message
  * @param {object} proc
  * @returns {string}

package/src/help.js

@@ -1,9 +1,11 @@
 import { supportsColor } from "./color.js";
 import { formatHeader, formatSubheader } from "./format.js";
 
+/** Render CLI help output as formatted text or JSON from a CLI definition. */
 export class HelpRenderer {
   #proc;
 
+  /** Store the process handle for stdout access and color detection. */
   constructor({ process }) {
     this.#proc = process;
   }
@@ -32,16 +34,23 @@ export class HelpRenderer {
     return [`Usage: ${definition.name} [options]`, ""];
   }
 
+  #argsDisplay(cmd) {
+    if (Array.isArray(cmd.args)) return cmd.argsUsage || "";
+    return cmd.args || "";
+  }
+
   #renderCommands(definition) {
     if (!definition.commands || definition.commands.length === 0) return [];
     const lines = [this.#sectionHeader("Commands:")];
     const maxWidth = Math.max(
-      ...definition.commands.map(
-        (c) => c.name.length + (c.args ? c.args.length + 1 : 0),
-      ),
+      ...definition.commands.map((c) => {
+        const argsStr = this.#argsDisplay(c);
+        return c.name.length + (argsStr ? argsStr.length + 1 : 0);
+      }),
     );
     for (const cmd of definition.commands) {
-      const left = cmd.args ? `${cmd.name} ${cmd.args}` : cmd.name;
+      const argsStr = this.#argsDisplay(cmd);
+      const left = argsStr ? `${cmd.name} ${argsStr}` : cmd.name;
       lines.push(`  ${left.padEnd(maxWidth)}  ${cmd.description}`);
     }
     lines.push("");
@@ -106,15 +115,16 @@ export class HelpRenderer {
   }
 
   #renderCommand(definition, stream, command) {
+    const argsStr = this.#argsDisplay(command);
     let header = `${definition.name} ${command.name}`;
-    if (command.args) header += ` ${command.args}`;
+    if (argsStr) header += ` ${argsStr}`;
     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}`;
+    if (argsStr) usage += ` ${argsStr}`;
     usage += " [options]";
 
     const globalWithoutVersion = definition.globalOptions
@@ -137,6 +147,7 @@ export class HelpRenderer {
     stream.write(lines.join("\n"));
   }
 
+  /** Render human-readable help text for the full CLI or a single command to the given stream. */
   render(definition, stream, command) {
     const out = stream || this.#proc.stdout;
     if (command) {
@@ -155,6 +166,7 @@ export class HelpRenderer {
     out.write(lines.join("\n"));
   }
 
+  /** Render the CLI definition or a single command as pretty-printed JSON to the given stream. */
   renderJson(definition, stream, command) {
     const out = stream || this.#proc.stdout;
     if (command) {
@@ -173,6 +185,7 @@ export class HelpRenderer {
         options: command.options,
         globalOptions: globalWithoutVersion,
         examples: command.examples,
+        documentation: definition.documentation,
       };
       out.write(JSON.stringify(obj, null, 2) + "\n");
     } else {

package/src/index.js

@@ -1,4 +1,5 @@
 export { Cli, createCli } from "./cli.js";
+export { freezeInvocationContext } from "./invocation-context.js";
 export { HelpRenderer } from "./help.js";
 export { SummaryRenderer } from "./summary.js";
 export { colors, supportsColor, colorize } from "./color.js";

package/src/invocation-context.js

@@ -0,0 +1,54 @@
+/**
+ * @typedef {Object} InvocationContext
+ *
+ * The shape libui and libcli both produce from their native inputs.
+ * Handlers consume the context and return a view; surface-specific
+ * formatters render the view. The context carries no information about
+ * which surface produced it — surface dispatch happens one level above the
+ * handler.
+ *
+ * Invariants:
+ * - No surface affordances — no DOM nodes, streams, Request/Response, or
+ *   surface tag. Anything that exists on only one surface stays out.
+ * - Uniform value shapes — args values are strings; options values are one
+ *   of string, boolean true, or string[]. No nulls, no numbers.
+ * - Frozen at all levels — the context, args, options, and any array
+ *   inside options are Object.freeze'd by the producer.
+ *
+ * @property {Object} data
+ *   Host's data dependencies, opaque to libui and libcli. Shape is the
+ *   product's responsibility. Anything a handler needs that is not a
+ *   positional or named argument lives here, including surface-specific
+ *   runtime dependencies the host folds in before invocation. The handler
+ *   treats data as immutable input.
+ *
+ * @property {Readonly<Object<string, string>>} args
+ *   Named positional arguments. On the web side: route-pattern parameters
+ *   keyed by their name. On the CLI side: the subcommand's declared
+ *   positional argument names mapped to their argv values. Values are
+ *   always strings; consumers parse if they need other types.
+ *
+ * @property {Readonly<Object<string, string | boolean | string[]>>} options
+ *   Named non-positional arguments. On the web side: the URL hash query
+ *   string parsed once. On the CLI side: parsed CLI flags. Values are one
+ *   of: a string, the boolean true (for a presence-only flag or an
+ *   empty-valued query parameter), or an array of strings (when the same
+ *   key appears more than once). Absent options are not present in the
+ *   object — 'foo' in ctx.options is the membership test.
+ */
+
+/**
+ * Deep-freeze an invocation context so handlers may assume immutability.
+ * @param {{ data: Object, args: Object<string,string>, options: Object<string,string|boolean|string[]> }} raw
+ * @returns {InvocationContext}
+ */
+export function freezeInvocationContext({ data, args, options }) {
+  for (const v of Object.values(options)) {
+    if (Array.isArray(v)) Object.freeze(v);
+  }
+  return Object.freeze({
+    data,
+    args: Object.freeze({ ...args }),
+    options: Object.freeze({ ...options }),
+  });
+}

package/src/summary.js

@@ -1,19 +1,75 @@
+/**
+ * Numeric severity per syslog ordering. Mirrors the LOG_LEVEL contract used
+ * by libtelemetry. Inlined here so libcli stays free of telemetry deps.
+ */
+const LEVELS = { error: 0, warn: 1, info: 2, debug: 3, trace: 3 };
+const DEFAULT_LEVEL = "info";
+
+/** Render post-run summary blocks to stdout; successful blocks are suppressed only when LOG_LEVEL=error is explicitly set (default level is "info", which renders all blocks). */
 export class SummaryRenderer {
   #proc;
+  #level;
 
+  /** Initialize the renderer, reading LOG_LEVEL from the environment; defaults to "info" (all blocks rendered) when LOG_LEVEL is absent or unrecognized. */
   constructor({ process }) {
     this.#proc = process;
+    const raw = (process.env?.LOG_LEVEL || "").toLowerCase().trim();
+    this.#level = LEVELS[raw] ?? LEVELS[DEFAULT_LEVEL];
   }
 
-  render({ title, items }, stream = this.#proc.stdout) {
-    stream.write(title + "\n");
-    if (!items || items.length === 0) return;
-
-    const maxLabel = Math.max(...items.map((item) => item.label.length));
-    for (const item of items) {
-      stream.write(
-        `  ${item.label.padEnd(maxLabel)}  \u2014 ${item.description}\n`,
+  /**
+   * Whether a block describing a run with the given `ok` would be rendered
+   * under the current LOG_LEVEL. Centralizes the suppression rule so callers
+   * that need to gate richer output (tables, multi-line blocks) on the same
+   * policy don't need to reimplement the level check.
+   *
+   * @param {boolean} ok
+   * @returns {boolean}
+   */
+  shouldRender(ok) {
+    if (typeof ok !== "boolean") {
+      throw new TypeError(
+        "SummaryRenderer.shouldRender requires an explicit `ok` boolean",
       );
     }
+    return !(ok && this.#level <= LEVELS.error);
+  }
+
+  /**
+   * Render a summary block. A block is **atomic, including its top margin**:
+   * `render` prepends a single blank line before the title so blocks visually
+   * separate from preceding output, and the whole unit (margin + title + items
+   * + extras) is suppressed together when LOG_LEVEL=error and the caller
+   * reports success (`ok: true`). A failing run still prints so the user sees
+   * the diagnostic context regardless of verbosity.
+   *
+   * Because the margin is owned by the block, callers MUST NOT print their own
+   * `\n` before `render`. Doing so leaks a stray blank line when the block is
+   * suppressed, and double-spaces it when the block renders.
+   *
+   * @param {object}   params
+   * @param {string}   params.title       Block title (rendered after the leading blank line).
+   * @param {Array<{label: string, description: string}>} params.items  Rows.
+   * @param {boolean}  params.ok          Whether the run this summary describes succeeded.
+   * @param {string}   [params.extras]    Free-form content rendered after items. Subject to the same suppression as the rest of the block.
+   * @param {{ write: (s: string) => void }} [stream]  Defaults to process.stdout.
+   */
+  render({ title, items, ok, extras }, stream = this.#proc.stdout) {
+    if (!this.shouldRender(ok)) return;
+
+    stream.write("\n" + title + "\n");
+
+    if (items && items.length > 0) {
+      const maxLabel = Math.max(...items.map((item) => item.label.length));
+      for (const item of items) {
+        stream.write(
+          `  ${item.label.padEnd(maxLabel)}  — ${item.description}\n`,
+        );
+      }
+    }
+
+    if (extras) {
+      stream.write(extras.endsWith("\n") ? extras : extras + "\n");
+    }
   }
 }