@divergeai/cli 0.1.22 → 0.1.23

package/README.md

@@ -13,6 +13,12 @@ diverge tools list --organization-id <id>
 
 Node 22 or later. Linux and macOS are supported; Windows is best-effort.
 
+`diverge --help`, `diverge <command> --help` and `diverge <command> <verb>
+--help` print the usage, and that usage is the CLI's command table: a
+command, verb or option that does not exist is answered with the closest ones
+it lists, by spelling or by what their description says (`diverge whoami` →
+`diverge status`, `tools search` → `tools list --filter`), and exits 1.
+
 ## Sign in
 
 `diverge login` runs the browser sign-in (authorization code with PKCE on a

package/dist/diverge.mjs

@@ -7423,7 +7423,7 @@ function tokenSource(env, baseUrl) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.1.22" : "dev";
+var VERSION = true ? "0.1.23" : "dev";
 var USER_AGENT = `diverge/${VERSION}`;
 
 // src/http.ts
@@ -7849,6 +7849,146 @@ async function revokeRefreshToken(baseUrl, clientId2, refreshToken) {
   if (!response.ok) throw new CliError(`Revoke endpoint returned HTTP ${response.status}`);
 }
 
+// src/usage.ts
+function usageEntries(usage2) {
+  const entries = [];
+  let current = null;
+  for (const line of usage2.split("\n")) {
+    if (/^ {2}\S/.test(line)) {
+      const label = line.trim().split(/ {2,}/)[0];
+      const verbs = [];
+      for (const word of label.split(" ")) {
+        if (!/^[a-z][a-z-]*$/.test(word)) break;
+        verbs.push(word);
+      }
+      current = { verbs, summary: line.trim().slice(label.length).trim(), lines: [line] };
+      entries.push(current);
+    } else if (current && /^ {3,}\S/.test(line)) {
+      current.lines.push(line);
+    } else {
+      current = null;
+    }
+  }
+  return entries;
+}
+function startsWith(words, prefix) {
+  return prefix.every((word, index) => words[index] === word);
+}
+function verbPath(usage2, args) {
+  let best = [];
+  for (const entry of usageEntries(usage2)) {
+    let shared = 0;
+    while (shared < entry.verbs.length && args[shared] === entry.verbs[shared]) shared++;
+    if (shared > best.length) best = entry.verbs.slice(0, shared);
+  }
+  return best;
+}
+function groupOptions(usage2) {
+  return usage2.split("\n", 1)[0].match(/\[--[^\]]+\]/g) ?? [];
+}
+function verbUsage(command, usage2, path15) {
+  const lines = usageEntries(usage2).filter((entry) => startsWith(entry.verbs, path15)).flatMap((entry) => entry.lines);
+  if (path15.length === 0 || lines.length === 0) return usage2;
+  const shared = groupOptions(usage2);
+  return [`diverge ${command} ${path15.join(" ")} ...`, "", ...lines, ...shared.length ? ["", `Every ${command} command also takes ${shared.join(" ")}.`] : []].join("\n");
+}
+var COMMON_WORDS = /* @__PURE__ */ new Set(["the", "and", "you", "for", "its", "with", "not", "one", "are", "all", "any", "from", "that", "this", "own", "per", "into", "out", "else", "each", "what", "when", "your"]);
+function distance(a, b) {
+  const d = Array.from({ length: a.length + 1 }, (_, i) => Array.from({ length: b.length + 1 }, (_2, j) => i === 0 ? j : j === 0 ? i : 0));
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+    }
+  }
+  return d[a.length][b.length];
+}
+function namesIt(word, guess) {
+  if (word.length < 3 || COMMON_WORDS.has(word)) return false;
+  return word === guess || guess.length >= 3 && word.startsWith(guess) || guess.startsWith(word) || guess.endsWith(word);
+}
+function prose(line) {
+  return line.toLowerCase().replace(/\[[^\]]*\]|--?[a-z][a-z-]*/g, " ");
+}
+function closest(guess, candidates, rest = [], limit = 3) {
+  const target = guess.toLowerCase().replace(/^-+/, "");
+  const threshold = Math.max(1, Math.floor(target.length / 3));
+  const matches = [];
+  for (const candidate of candidates) {
+    const first = candidate.summary ?? "";
+    const name = candidate.name.toLowerCase();
+    if (name && rest.includes(candidate.name)) {
+      matches.push({ candidate, score: 0, hint: first });
+      continue;
+    }
+    const edits = name ? distance(target, name) : Infinity;
+    if (edits <= threshold || name && target.length >= 2 && name.startsWith(target)) {
+      matches.push({ candidate, score: Math.min(edits, threshold), hint: first });
+      continue;
+    }
+    const line = candidate.lines.find((text) => (prose(text).match(/[a-z]+/g) ?? []).some((word) => namesIt(word, target)));
+    if (line) matches.push({ candidate, score: threshold + 1, hint: line });
+  }
+  return matches.sort((a, b) => a.score - b.score).slice(0, limit);
+}
+function didYouMean(matches) {
+  if (matches.length === 0) return "";
+  const shown = (match) => {
+    const hint = match.hint.trim();
+    return hint && hint !== match.candidate.invocation ? `${match.candidate.invocation} (${hint})` : match.candidate.invocation;
+  };
+  if (matches.length === 1) return ` Did you mean: ${shown(matches[0])}?`;
+  return ` Did you mean one of:
+${matches.map((match) => `  ${shown(match)}`).join("\n")}`;
+}
+function verbCandidates(command, usage2, path15) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const entry of usageEntries(usage2)) {
+    if (!startsWith(entry.verbs, path15)) continue;
+    const name = entry.verbs[path15.length] ?? "";
+    const invocation = ["diverge", command, ...path15, ...name ? [name] : []].join(" ");
+    const lines = [entry.summary, ...entry.lines.slice(1).map((line) => line.trim())].filter(Boolean);
+    const known = byName.get(name);
+    if (known) known.lines.push(...lines);
+    else byName.set(name, { invocation, name, summary: entry.summary, lines });
+  }
+  return [...byName.values()];
+}
+function unknownVerb(command, usage2, path15, verb, rest = []) {
+  const candidates = verbCandidates(command, usage2, path15);
+  const where = [command, ...path15].join(" ");
+  if (!verb) return new CliError(`${where} needs one of: ${candidates.map((candidate) => candidate.name).filter(Boolean).join(", ")}
+
+${usage2}`);
+  return new CliError(`Unknown ${where} verb: ${verb}.${didYouMean(closest(verb, candidates, rest))}
+
+${usage2}`);
+}
+function optionCandidates(usage2, path15) {
+  const entries = usageEntries(usage2);
+  const [header = "", ...body] = usage2.split("\n");
+  const described = entries.length === 0 || path15.length === 0 ? body : entries.filter((entry) => startsWith(entry.verbs, path15)).flatMap((entry) => entry.lines);
+  const byName = /* @__PURE__ */ new Map();
+  const add = (line, describes) => {
+    for (const [flag] of line.matchAll(/--[a-z][a-z-]*/g)) {
+      const candidate = byName.get(flag) ?? { invocation: flag, name: flag.slice(2), lines: [] };
+      byName.set(flag, candidate);
+      if (describes && !candidate.lines.includes(line.trim())) candidate.lines.push(line.trim());
+    }
+  };
+  add(header, false);
+  for (const line of described) add(line, true);
+  return [...byName.values()];
+}
+function unknownOption(error, usage2, args) {
+  if (!(error instanceof Error) || error.name !== "TypeError") return null;
+  const option = /^Unknown option '([^']+)'/.exec(error.message)?.[1];
+  if (!option) return null;
+  const path15 = verbPath(usage2, args);
+  return `Unknown option: ${option}.${didYouMean(closest(option, optionCandidates(usage2, path15)))}`;
+}
+
 // src/commands/login.ts
 import { parseArgs } from "node:util";
 
@@ -8647,9 +8787,7 @@ async function runSkills(args, io) {
       return ExitCode.Ok;
     }
     default:
-      throw new CliError(`skills needs one of: list, install, status
-
-${skillsUsage}`);
+      throw unknownVerb("skills", skillsUsage, [], verb, rest);
   }
 }
 
@@ -8829,16 +8967,12 @@ async function setup(args, io) {
       return ExitCode.Ok;
     }
     default:
-      throw new CliError(`agents setup needs one of: claude, opencode, codex, dsh
-
-${agentsUsage}`);
+      throw unknownVerb("agents", agentsUsage, ["setup"], agent, rest);
   }
 }
 async function run(args, io) {
   const [agent, ...rest] = args;
-  if (agent !== "dsh") throw new CliError(`agents run supports: dsh
-
-${agentsUsage}`);
+  if (agent !== "dsh") throw unknownVerb("agents", agentsUsage, ["run"], agent, rest);
   const terminator = rest.indexOf("--");
   const flags = terminator === -1 ? rest : rest.slice(0, terminator);
   const passthrough = terminator === -1 ? [] : rest.slice(terminator + 1);
@@ -8915,18 +9049,8 @@ async function rotate(args, io) {
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
   });
 }
-function agentsVerbUsage(verb) {
-  const lines = agentsUsage.split("\n").filter((line) => line.trimStart().startsWith(`${verb} `) || line.trimStart().startsWith(`${verb}	`));
-  return lines.length ? `diverge agents ${verb} ...
-
-${lines.join("\n")}` : agentsUsage;
-}
 async function runAgents(args, io) {
   const [verb, ...rest] = args;
-  if (verb && (rest.includes("--help") || rest.includes("-h")) && !rest.includes("--")) {
-    io.stdout(agentsVerbUsage(verb));
-    return ExitCode.Ok;
-  }
   switch (verb) {
     case "setup":
       return setup(rest, io);
@@ -8937,9 +9061,7 @@ async function runAgents(args, io) {
     case "status":
       return status(rest, io);
     default:
-      throw new CliError(`agents needs one of: setup, run, rotate, status
-
-${agentsUsage}`);
+      throw unknownVerb("agents", agentsUsage, [], verb, rest);
   }
 }
 
@@ -8947,20 +9069,22 @@ ${agentsUsage}`);
 import { parseArgs as parseArgs4 } from "node:util";
 var orgUsage = `diverge org [use <id|name>]
 
-Without a verb: the organizations you may act in, the default marked.
-use <id|name>: make it the default \u2014 where every command that names no
-organization acts, in every shell on this machine that shares the login. It
-is a local preference: the platform is asked only for a token there, which
-proves you may act in it. For one command, pass --organization-id <id> (or
-set DIVERGENT_ORG_ID) instead. A platform actor may act in, and so sees, every
-organization.`;
+  (no verb)      list the organizations you may act in, the default marked
+  use <id|name>  make it the default: where every command that names no organization acts,
+                 in every shell on this machine that shares the login
+
+The default is a local preference: the platform is asked only for a token
+there, which proves you may act in it. For one command, pass
+--organization-id <id> (or set DIVERGENT_ORG_ID) instead. A platform actor may
+act in, and so sees, every organization.`;
 async function runOrg(args, io) {
   const { positionals } = parseArgs4({ args, options: {}, strict: true, allowPositionals: true });
+  const verb = positionals[0];
+  if (verb && verb !== "use") throw unknownVerb("org", orgUsage, [], verb, positionals.slice(1));
   const source = tokenSource(io.env, resolveApiUrl(void 0, io.env));
   const info = await fetchUserInfo(source.baseUrl, (await getUserToken(source)).access_token);
   const organizations = info.organizations ?? [];
   const current = requireLogin(source).organization;
-  const verb = positionals[0];
   if (!verb) {
     if (organizations.length === 0) {
       io.stdout("You are not a member of any organization.");
@@ -8969,9 +9093,6 @@ async function runOrg(args, io) {
     for (const organization of organizations) io.stdout(`${organization.id === current ? "*" : " "} ${organization.name} (${organization.id})`);
     return 0;
   }
-  if (verb !== "use") throw new CliError(`Unknown verb: ${verb}
-
-${orgUsage}`);
   const target = positionals[1];
   if (!target) throw new CliError("org use needs an organization id or name");
   const choice = chooseOrganization({ flag: target, organizations });
@@ -9659,7 +9780,7 @@ function formatPending(result, apiUrl, organizationId) {
 var toolsUsage = `diverge tools <list|capabilities|describe|call|run|invocation|bridge> [--organization-id <id>] [--project-id <id>] ...
 
   list         [--filter <text>] [--capability <selector>] [--json]
-               --filter matches tool names and descriptions, ignoring case
+               --filter searches tool names and descriptions, ignoring case
   capabilities [--json]
   describe <name> [--json]
   call <name> [--args-json '{...}' | --args-json - | --args-file <path>] [--wait] [--timeout <seconds>] [--json]
@@ -9718,7 +9839,7 @@ async function call(rest, io) {
     });
   } catch (error) {
     if (!json) throw error;
-    outcome = { tool, status: "failed", error: error instanceof Error ? error.message : String(error) };
+    outcome = { tool, status: "failed", error: unknownOption(error, toolsUsage, ["call"]) ?? (error instanceof Error ? error.message : String(error)) };
   }
   if (json) io.stdout(JSON.stringify(outcome, null, 2));
   else printOutcome(outcome, waited, io);
@@ -9742,26 +9863,8 @@ function printOutcome(outcome, waited, io) {
       throw new CliError(outcome.invocationId ? `Approved, but execution failed: ${outcome.error}` : outcome.error || "Tool execution failed");
   }
 }
-function toolsVerbUsage(verb) {
-  const lines = [];
-  let inVerb = false;
-  for (const line of toolsUsage.split("\n")) {
-    if (/^ {2}\S/.test(line)) inVerb = line.trimStart().startsWith(`${verb} `);
-    else if (!/^ {3,}\S/.test(line)) inVerb = false;
-    if (inVerb) lines.push(line);
-  }
-  return lines.length ? `diverge tools ${verb} ...
-
-${lines.join("\n")}
-
-Every tools command takes --organization-id <id> (or DIVERGENT_ORG_ID, else the signed-in login's organization) and --project-id <id> (or DIVERGENT_PROJECT_ID).` : toolsUsage;
-}
 async function runTools(args, io) {
   const [verb, ...rest] = args;
-  if (verb && (rest.includes("--help") || rest.includes("-h"))) {
-    io.stdout(toolsVerbUsage(verb));
-    return ExitCode.Ok;
-  }
   switch (verb) {
     case "list": {
       const { values } = parseArgs6({ args: rest, options: { ...SCOPE_OPTIONS, filter: { type: "string" }, capability: { type: "string" }, json: { type: "boolean", default: false } }, strict: true });
@@ -9844,9 +9947,7 @@ async function runTools(args, io) {
       return serveBridge(new BridgeServer(tools, { tools: allow }), process.stdin, process.stdout);
     }
     default:
-      throw new CliError(`tools needs one of: list, capabilities, describe, call, run, invocation, bridge
-
-${toolsUsage}`);
+      throw unknownVerb("tools", toolsUsage, [], verb, rest);
   }
 }
 
@@ -9900,20 +10001,8 @@ function formatPlugin(plugin) {
     ...plugin.refusals?.length ? ["  NOT SERVED: the platform refuses this version; publish a fixed one:", ...plugin.refusals.map((reason) => `    - ${reason}`)] : []
   ];
 }
-function pluginsVerbUsage(verb) {
-  const lines = pluginsUsage.split("\n").filter((line) => line.trimStart().startsWith(`${verb} `));
-  return lines.length ? `diverge plugins ${verb} ...
-
-${lines.join("\n")}
-
-Every plugins command takes --organization-id <id> (or DIVERGENT_ORG_ID, else the signed-in login's organization).` : pluginsUsage;
-}
 async function runPlugins(args, io) {
   const [verb, ...rest] = args;
-  if (verb && (rest.includes("--help") || rest.includes("-h"))) {
-    io.stdout(pluginsVerbUsage(verb));
-    return ExitCode.Ok;
-  }
   switch (verb) {
     case "validate": {
       const { values, positionals } = parseArgs7({ args: rest, options: { ...SCOPE_OPTIONS2, json: { type: "boolean", default: false } }, allowPositionals: true, strict: true });
@@ -9971,9 +10060,7 @@ ${pluginsUsage}`);
       return ExitCode.Ok;
     }
     default:
-      throw new CliError(`plugins needs one of: validate, publish, list, retire
-
-${pluginsUsage}`);
+      throw unknownVerb("plugins", pluginsUsage, [], verb, rest);
   }
 }
 
@@ -10084,9 +10171,9 @@ function installLatest(version) {
 
 // src/cli.ts
 var COMMANDS = [
-  { name: "login", summary: "Sign in through the browser", usage: loginUsage, run: runLogin },
+  { name: "login", summary: "Sign in (authenticate) through the browser", usage: loginUsage, run: runLogin },
   { name: "logout", summary: "Revoke the login and forget it", usage: logoutUsage, run: runLogout },
-  { name: "status", summary: "Show the deployment and the cached login", usage: statusUsage, run: runStatus },
+  { name: "status", summary: "Show who you are signed in as: the deployment, the account and what the login carries", usage: statusUsage, run: runStatus },
   { name: "org", summary: "Show or switch the organization the login acts in", usage: orgUsage, run: runOrg },
   { name: "token", summary: "Print a fresh access token", usage: tokenUsage, run: runToken },
   { name: "agents", summary: "Point a coding agent at the model gateway (setup, run, status)", usage: agentsUsage, run: runAgents },
@@ -10122,15 +10209,19 @@ async function run2(argv, io) {
   }
   const command = COMMANDS.find((candidate) => candidate.name === name);
   if (!command) {
-    io.stderr(`Unknown command: ${name}
+    const candidates = COMMANDS.map((known) => ({ invocation: `diverge ${known.name}`, name: known.name, summary: known.summary, lines: [known.summary] }));
+    io.stderr(`Unknown command: ${name}.${didYouMean(closest(name, candidates, rest))}
 
 ${usage()}`);
     return ExitCode.Failure;
   }
   const own = rest.includes("--") ? rest.slice(0, rest.indexOf("--")) : rest;
-  if ((own.includes("--help") || own.includes("-h")) && (own.length === 1 || own[0].startsWith("-"))) {
-    io.stdout(command.usage);
-    return ExitCode.Ok;
+  if (own.includes("--help") || own.includes("-h")) {
+    const path15 = verbPath(command.usage, own);
+    if (path15.length > 0 || own[0].startsWith("-")) {
+      io.stdout(verbUsage(command.name, command.usage, path15));
+      return ExitCode.Ok;
+    }
   }
   const code2 = await runCommand(command, rest, io);
   updateNotice(argv, io);
@@ -10145,9 +10236,9 @@ async function runCommand(command, rest, io) {
       return error.exitCode;
     }
     if (error instanceof Error && error.name === "TypeError" && /Unknown option|Option .* argument|Unexpected argument/.test(error.message)) {
-      io.stderr(`Error: ${error.message}
+      io.stderr(`Error: ${unknownOption(error, command.usage, rest) ?? error.message}
 
-${command.usage}`);
+${verbUsage(command.name, command.usage, verbPath(command.usage, rest))}`);
       return ExitCode.Failure;
     }
     io.stderr(`Error: ${error instanceof Error ? error.message : String(error)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@divergeai/cli",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "Divergent platform CLI: sign in, wire coding agents to the inference gateway, call platform tools",
   "license": "UNLICENSED",
   "type": "module",