@forwardimpact/libcli 0.1.8 → 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.8",
-  "description": "Agent-friendly CLIs: argument parsing, handler dispatch, grep-friendly help, JSON mode, and skill-doc links 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",
@@ -17,14 +17,16 @@
   },
   "license": "Apache-2.0",
   "author": "D. Olsson <hi@senzilla.io>",
-  "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"
-    ]
-  },
+  "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": {

package/src/cli.js

@@ -2,11 +2,13 @@ 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(
@@ -37,10 +39,12 @@ export class Cli {
     }
   }
 
+  /** 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);
@@ -130,6 +134,7 @@ 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) {
@@ -155,21 +160,25 @@ export class Cli {
     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;
   }
@@ -145,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) {
@@ -163,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) {

package/src/summary.js

@@ -5,10 +5,12 @@
 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();