@kaynooo/cli-doctor 0.3.0 → 0.4.0

package/README.md

@@ -17,6 +17,14 @@ doctor --json    # [{check, ok, detail, fix?}]
 
 A registry that does not answer leaves a package passing, with a note. Exit codes: 0 every check passed, 1 one failed, 2 a usage error.
 
+## cli stats
+
+```sh
+cli stats [--since 7d] [--json]   # runs per bin, failures, and the options usage errors did not know
+```
+
+Every bin records each run in `~/.local/state/kaynooo-cli/usage.jsonl`: the bin, its command, the flag names it saw (never values or arguments), the exit code and, on a usage error, the unknown option. `KAYNOOO_CLI_NO_USAGE=1` turns it off; `guard` never records.
+
 ## cli list
 
 ```sh

package/dist/cli-bin.js

@@ -2,12 +2,15 @@
 // @bun
 
 // src/cli-bin.ts
-import process8 from "process";
+import process11 from "process";
 
 // ../kit/src/args.ts
-import process2 from "process";
+import process4 from "process";
 import { parseArgs } from "util";
 
+// ../kit/src/format.ts
+import process2 from "process";
+
 // ../kit/src/style.ts
 import process from "process";
 
@@ -293,11 +296,102 @@ function upTo(text, separator) {
   const end = text.indexOf(separator);
   return end === -1 ? text : text.slice(0, end);
 }
+function truncate(text, width) {
+  return text.length <= width ? text : `${text.slice(0, Math.max(0, width - 1))}\u2026`;
+}
+var LINE_BREAKS = /\s*\n\s*/g;
 var ESCAPE = String.fromCharCode(27);
+function textWidth(text) {
+  return Bun.stringWidth(text);
+}
+function table(rows, { cellWidth, header = false, align = [], fit } = {}) {
+  const cells = cellWidth === undefined ? rows : rows.map((row) => row.map((cell) => truncate(cell.replaceAll(LINE_BREAKS, " "), cellWidth)));
+  const widths = [];
+  for (const row of cells) {
+    for (const [index, cell] of row.entries())
+      widths[index] = Math.max(widths[index] ?? 0, textWidth(cell));
+  }
+  const shown = fit === undefined ? cells : narrow(cells, widths, fit);
+  const colors = paint(process2.stdout);
+  const lines = shown.map((row) => row.map((cell, index) => {
+    const width = widths[index] ?? 0;
+    const gap = " ".repeat(Math.max(0, width - textWidth(cell)));
+    if (align[index] === "right")
+      return `${gap}${cell}`;
+    return index === row.length - 1 ? cell : `${cell}${gap}`;
+  }).join("  ").trimEnd());
+  return lines.map((line, index) => header && index === 0 ? colors.bold(line) : line).join(`
+`);
+}
+function narrow(rows, widths, limit) {
+  const used = () => widths.reduce((sum, width) => sum + width, 0) + 2 * Math.max(0, widths.length - 1);
+  const cuttable = (index) => rows.every((row) => !(row[index] ?? "").includes(ESCAPE));
+  const floor = 8;
+  while (used() > limit) {
+    let widest = -1;
+    for (const [index, width] of widths.entries()) {
+      if (cuttable(index) && width > floor && width > (widths[widest] ?? 0))
+        widest = index;
+    }
+    if (widest === -1)
+      break;
+    widths[widest] = Math.max(floor, (widths[widest] ?? 0) - (used() - limit));
+  }
+  return rows.map((row) => row.map((cell, index) => textWidth(cell) > (widths[index] ?? 0) ? truncate(cell, widths[index] ?? 0) : cell));
+}
 function printJson(value) {
   console.log(JSON.stringify(value, undefined, 2));
 }
 
+// ../kit/src/help.ts
+import process3 from "process";
+var OPTIONAL = /\[[^\]]+\]/g;
+var USAGE_PREFIX = /^usage:\s*/i;
+var FULL_STOP = /\.$/;
+function usageLine(usage, colors = paint(process3.stdout)) {
+  return `${colors.bold("Usage:")} ${usage.replace(USAGE_PREFIX, "").replaceAll(OPTIONAL, (part) => colors.dim(part))}`;
+}
+function helpText(usage, options, colors = paint(process3.stdout), { examples = [], replaces } = {}) {
+  return [usageLine(usage, colors), ...replacesRows(replaces, colors), "", colors.bold("Options:"), ...optionRows(options, colors), ...exampleRows(examples, colors)].join(`
+`);
+}
+function replacesRows(replaces, colors = paint(process3.stdout)) {
+  return replaces === undefined ? [] : ["", `${colors.bold("Instead of:")} ${replaces}`];
+}
+function wantsHelpJson(env = process3.env) {
+  return env.KIT_HELP === "json";
+}
+function description(usage, { examples = [], replaces } = {}) {
+  const lines = usage.replace(USAGE_PREFIX, "").split(`
+`);
+  const first = lines[0];
+  const colon = first.indexOf(": ");
+  const prose = lines[lines.indexOf("") + 1] ?? "";
+  const fallback = lines.includes("") ? `${prose.charAt(0).toLowerCase()}${prose.slice(1)}`.replace(FULL_STOP, "") : "";
+  return {
+    synopsis: colon === -1 ? first : first.slice(0, colon),
+    summary: colon === -1 ? fallback : first.slice(colon + 2),
+    ...replaces === undefined ? {} : { replaces },
+    examples: examples.map((example) => typeof example === "string" ? { line: example } : { line: example[0], note: example[1] })
+  };
+}
+function exampleRows(examples, colors = paint(process3.stdout)) {
+  if (examples.length === 0)
+    return [];
+  return ["", colors.bold("Examples:"), ...examples.map((example) => typeof example === "string" ? `  ${example}` : `  ${example[0]}  ${colors.dim(`# ${example[1]}`)}`)];
+}
+function optionRows(options, colors = paint(process3.stdout)) {
+  const rows = Object.entries(options).map(([name, option]) => {
+    const short = option.short === undefined ? "    " : `${colors.cyan(`-${option.short}`)}, `;
+    const named = option.choices === undefined ? "<value>" : `<${option.choices.join("|")}>`;
+    const placeholder = option.optional === undefined ? named : `[${named}]`;
+    const value = option.type === "string" ? ` ${colors.dim(placeholder)}` : "";
+    return { flag: `${short}${colors.cyan(`--${name}`)}${value}`, width: `-x, --${name}`.length + (option.type === "string" ? placeholder.length + 1 : 0), description: option.description ?? "" };
+  });
+  const width = Math.max(0, ...rows.map((row) => row.width));
+  return rows.map((row) => row.description === "" ? `  ${row.flag}` : `  ${row.flag}${" ".repeat(width - row.width)}  ${colors.dim(row.description)}`);
+}
+
 // ../kit/src/text.ts
 var ANSI = new RegExp(`${String.fromCharCode(27)}\\[[\\d;?]*[a-z]`, "gi");
 function distance(a, b) {
@@ -317,8 +411,21 @@ function closest(name, names) {
   const [best] = names.map((known) => ({ known, far: distance(name, known) })).sort((a, b) => a.far - b.far);
   return best !== undefined && best.far <= (name.length < 4 ? 1 : 2) ? best.known : undefined;
 }
+// ../kit/src/input.ts
+var DURATION = /^(\d+(?:\.\d+)?)(ms|[smhd])?$/;
+var UNIT_MS = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
+function duration(value, name, fallback, unit = "s") {
+  if (value === undefined)
+    return fallback;
+  const match = DURATION.exec(value.trim());
+  const ms = match === null ? 0 : Number(match[1]) * UNIT_MS[match[2] ?? unit];
+  if (ms < 1)
+    badUsage(`--${name} takes a duration such as 30s, 5m, 1h or 7d, not ${value}`);
+  return ms;
+}
 
 // ../kit/src/args.ts
+var DASHES = /^-+/;
 function jsonOption(holds) {
   return { type: "boolean", description: holds === undefined ? "print JSON" : `print JSON: ${holds}` };
 }
@@ -358,58 +465,11 @@ class Completing {
   }
 }
 var completion = { active: false };
-var OPTIONAL = /\[[^\]]+\]/g;
-var USAGE_PREFIX = /^usage:\s*/i;
-var FULL_STOP = /\.$/;
-var DASHES = /^-+/;
-function usageLine(usage, colors = paint(process2.stdout)) {
-  return `${colors.bold("Usage:")} ${usage.replace(USAGE_PREFIX, "").replaceAll(OPTIONAL, (part) => colors.dim(part))}`;
-}
-function helpText(usage, options, colors = paint(process2.stdout), { examples = [], replaces } = {}) {
-  return [usageLine(usage, colors), ...replacesRows(replaces, colors), "", colors.bold("Options:"), ...optionRows(options, colors), ...exampleRows(examples, colors)].join(`
-`);
-}
-function replacesRows(replaces, colors = paint(process2.stdout)) {
-  return replaces === undefined ? [] : ["", `${colors.bold("Instead of:")} ${replaces}`];
-}
-function wantsHelpJson(env = process2.env) {
-  return env.KIT_HELP === "json";
-}
-function description(usage, { examples = [], replaces } = {}) {
-  const lines = usage.replace(USAGE_PREFIX, "").split(`
-`);
-  const first = lines[0];
-  const colon = first.indexOf(": ");
-  const prose = lines[lines.indexOf("") + 1] ?? "";
-  const fallback = lines.includes("") ? `${prose.charAt(0).toLowerCase()}${prose.slice(1)}`.replace(FULL_STOP, "") : "";
-  return {
-    synopsis: colon === -1 ? first : first.slice(0, colon),
-    summary: colon === -1 ? fallback : first.slice(colon + 2),
-    ...replaces === undefined ? {} : { replaces },
-    examples: examples.map((example) => typeof example === "string" ? { line: example } : { line: example[0], note: example[1] })
-  };
-}
-function exampleRows(examples, colors = paint(process2.stdout)) {
-  if (examples.length === 0)
-    return [];
-  return ["", colors.bold("Examples:"), ...examples.map((example) => typeof example === "string" ? `  ${example}` : `  ${example[0]}  ${colors.dim(`# ${example[1]}`)}`)];
-}
-function optionRows(options, colors = paint(process2.stdout)) {
-  const rows = Object.entries(options).map(([name, option]) => {
-    const short = option.short === undefined ? "    " : `${colors.cyan(`-${option.short}`)}, `;
-    const named = option.choices === undefined ? "<value>" : `<${option.choices.join("|")}>`;
-    const placeholder = option.optional === undefined ? named : `[${named}]`;
-    const value = option.type === "string" ? ` ${colors.dim(placeholder)}` : "";
-    return { flag: `${short}${colors.cyan(`--${name}`)}${value}`, width: `-x, --${name}`.length + (option.type === "string" ? placeholder.length + 1 : 0), description: option.description ?? "" };
-  });
-  const width = Math.max(0, ...rows.map((row) => row.width));
-  return rows.map((row) => row.description === "" ? `  ${row.flag}` : `  ${row.flag}${" ".repeat(width - row.width)}  ${colors.dim(row.description)}`);
-}
 var OUTPUT_OPTIONS = {
   color: { type: "string", description: "auto (on a terminal alone), always or never" },
   plain: { type: "boolean", description: "plain text, no colour or spinner: --color never" }
 };
-function applyOutput(color, plain, env = process2.env) {
+function applyOutput(color, plain, env = process4.env) {
   const when = plain === true ? "never" : color ?? "auto";
   if (when === "auto")
     return;
@@ -568,7 +628,7 @@ function nearestOption(message, options, allowNegative) {
 }
 // ../kit/src/process.ts
 import { constants } from "os";
-import process3 from "process";
+import process5 from "process";
 var KILL_GRACE_MS = 2000;
 function exitCodeOf(code, signal) {
   if (code !== null)
@@ -588,7 +648,7 @@ async function runCommand(argv, { cwd, env, stdin = "ignore", timeoutMs, signal,
       return;
     try {
       if (grouped)
-        process3.kill(-proc.pid, killing);
+        process5.kill(-proc.pid, killing);
       else
         proc.kill(killing);
     } catch {}
@@ -662,7 +722,95 @@ var ESCAPE_CODE = new RegExp(`${ESC}(?:\\[[\\x30-\\x3F]*[\\x20-\\x2F]*[\\x40-\\x
 var RESET_STYLE = `${ESC}[0m`;
 var CLOSE_LINK = `${ESC}]8;;${ESC}\\`;
 // ../kit/src/cli.ts
-import process4 from "process";
+import process7 from "process";
+
+// ../kit/src/usage.ts
+import { appendFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { dirname, isAbsolute, join } from "path";
+import process6 from "process";
+
+// ../kit/src/logs.ts
+var DAY_MS = 24 * 60 * 60 * 1000;
+var CLI_FOLDER = "kaynooo-cli";
+
+// ../kit/src/usage.ts
+var UNKNOWN_OPTION2 = /unknown option '(--[a-z][a-z0-9-]*)[=']/;
+var FLAG_NAME = /^(?:--[a-z][a-z0-9-]*|-[a-zA-Z])$/;
+var LONGEST_NAME = 40;
+var usageError;
+function noteUsageError(message) {
+  usageError = message;
+}
+function stateHome(env = process6.env) {
+  const dir = env.XDG_STATE_HOME;
+  return dir !== undefined && isAbsolute(dir) ? dir : join(homedir(), ".local", "state");
+}
+function usagePath(env = process6.env) {
+  return join(stateHome(env), CLI_FOLDER, "usage.jsonl");
+}
+function usageRecorded(env = process6.env) {
+  const off = env.KAYNOOO_CLI_NO_USAGE;
+  return env.NODE_ENV !== "test" && (off === undefined || off === "" || off === "0");
+}
+function flagNames(argv) {
+  const end = argv.indexOf("--");
+  const names = (end === -1 ? argv : argv.slice(0, end)).filter((word) => word.startsWith("-") && word !== "-").map((word) => word.includes("=") ? word.slice(0, word.indexOf("=")) : word);
+  return [...new Set(names)].filter((name) => name.length <= LONGEST_NAME && FLAG_NAME.test(name));
+}
+function usageEntry(bin, command, argv, code, now = new Date) {
+  const unknown = code === 2 && usageError !== undefined ? UNKNOWN_OPTION2.exec(usageError)?.[1] : undefined;
+  usageError = undefined;
+  return { at: now.toISOString(), bin, ...command === undefined ? {} : { command }, flags: flagNames(argv), code, ...unknown === undefined ? {} : { unknown } };
+}
+function recordUsage(entry, env = process6.env) {
+  if (!usageRecorded(env))
+    return;
+  try {
+    const path = usagePath(env);
+    mkdirSync(dirname(path), { recursive: true, mode: 448 });
+    appendFileSync(path, `${JSON.stringify(entry)}
+`, { mode: 384 });
+  } catch {}
+}
+async function readUsage(path = usagePath(), since = 0) {
+  const file = Bun.file(path);
+  if (!await file.exists())
+    return [];
+  return (await file.text()).split(`
+`).flatMap((line) => {
+    try {
+      const entry = JSON.parse(line);
+      return Date.parse(entry.at) >= since ? [entry] : [];
+    } catch {
+      return [];
+    }
+  });
+}
+function summarizeUsage(entries) {
+  const bins = new Map;
+  const errors = new Map;
+  for (const entry of entries) {
+    const bin = bins.get(entry.bin) ?? { runs: 0, failed: 0, usageErrors: 0 };
+    bin.runs++;
+    bin.failed += entry.code === 0 ? 0 : 1;
+    bin.usageErrors += entry.code === 2 ? 1 : 0;
+    bins.set(entry.bin, bin);
+    if (entry.code === 2 && entry.unknown !== undefined) {
+      const key = `${entry.bin} ${entry.command ?? ""} ${entry.unknown}`;
+      const error = errors.get(key) ?? { bin: entry.bin, ...entry.command === undefined ? {} : { command: entry.command }, unknown: entry.unknown, count: 0 };
+      error.count++;
+      errors.set(key, error);
+    }
+  }
+  return {
+    runs: entries.length,
+    bins: [...bins].map(([bin, counts]) => ({ bin, ...counts })).toSorted((a, b) => b.runs - a.runs),
+    usageErrors: [...errors.values()].toSorted((a, b) => b.count - a.count)
+  };
+}
+
+// ../kit/src/cli.ts
 var LEVEL_OPTIONS = {
   ...OUTPUT_OPTIONS,
   help: { type: "boolean", short: "h", description: "show this help" }
@@ -715,7 +863,7 @@ async function expand(scope, words) {
   }
   return { ...scope, commands, lazy: [] };
 }
-async function help({ path, header, summary: lazySummary, commands, defaultCommand, examples, replaces }, stream) {
+async function help2({ path, header, summary: lazySummary, commands, defaultCommand, examples, replaces }, stream) {
   const colors = paint(stream);
   const prefix = path.join(" ");
   const summary = await resolveSummary(lazySummary);
@@ -742,8 +890,8 @@ async function help({ path, header, summary: lazySummary, commands, defaultComma
 `);
 }
 function printError(prefix, message, hint, cause) {
-  const colors = paint(process4.stderr);
-  const styled = takesControlCodes(process4.stderr);
+  const colors = paint(process7.stderr);
+  const styled = takesControlCodes(process7.stderr);
   const head = styled ? `${colors.red.bold("error")} ${colors.dim(`${prefix}:`)}` : `error: ${prefix}:`;
   const under = (label, text, tint) => text === undefined ? "" : `
   ${styled ? tint(label) : `${label}:`} ${text}`;
@@ -762,6 +910,8 @@ function reportThrown(prefix, error, redact = (text) => text, json = false) {
   const help = error instanceof UsageError ? `run ${prefix} --help for its options` : undefined;
   const named = error instanceof Error && !(error instanceof Exit) && error.name !== "Error" ? `${error.name}: ${error.message}` : undefined;
   const cause = error instanceof Error && error.cause instanceof Error ? redact(error.cause.message) : undefined;
+  if (error instanceof UsageError)
+    noteUsageError(error.message);
   const report = json ? printJsonError : (message, hint, causeText) => printError(prefix, message, hint, causeText);
   report(redact(named ?? (error instanceof Error ? error.message : String(error))), error instanceof Exit ? error.hint ?? help : undefined, cause);
   return error instanceof Exit ? error.code : 1;
@@ -784,11 +934,11 @@ async function dispatch(level, typed, { version, redact }) {
     }
   }
   if (name === undefined && level.path.length > 1) {
-    console.error(await help(await expand(level, [...level.path.slice(1), ...argv]), process4.stderr));
+    console.error(await help2(await expand(level, [...level.path.slice(1), ...argv]), process7.stderr));
     return 2;
   }
   if (name === undefined || name === "help" || name === "--help" || name === "-h") {
-    console.log(await help(await expand(level, [...level.path.slice(1), ...argv]), process4.stdout));
+    console.log(await help2(await expand(level, [...level.path.slice(1), ...argv]), process7.stdout));
     return 0;
   }
   if (level.path.length === 1 && (name === "--version" || name === "-v")) {
@@ -904,26 +1054,49 @@ async function printCandidates(found) {
     console.log(line);
   return 0;
 }
-async function runCli(cli, argv = process4.argv.slice(2)) {
+async function runCli(cli, argv = process7.argv.slice(2)) {
   if (argv[0] === COMPLETE)
     return printCandidates(candidates(scopeOf(cli.commands, cli.extraCommands, cli.aliases), cli.defaultCommand, argv.slice(1)));
-  return dispatch({ path: [cli.name], header: (colors, about) => `${colors.bold(cli.name)} ${colors.dim(cli.version)}  ${about}`, summary: cli.about, ...scopeOf(cli.commands, cli.extraCommands, cli.aliases), defaultCommand: cli.defaultCommand, runBare: cli.runBare === true, examples: cli.examples, replaces: cli.replaces }, argv, { version: cli.version, redact: cli.redact });
+  const code = await dispatch({ path: [cli.name], header: (colors, about) => `${colors.bold(cli.name)} ${colors.dim(cli.version)}  ${about}`, summary: cli.about, ...scopeOf(cli.commands, cli.extraCommands, cli.aliases), defaultCommand: cli.defaultCommand, runBare: cli.runBare === true, examples: cli.examples, replaces: cli.replaces }, argv, { version: cli.version, redact: cli.redact });
+  if (cli.usage !== false) {
+    try {
+      recordUsage(usageEntry(cli.name, commandPath(scopeOf(cli.commands, cli.extraCommands, cli.aliases), argv), argv, code));
+    } catch {}
+  }
+  return code;
+}
+function commandPath(scope, argv) {
+  const path = [];
+  let level = scope;
+  for (const word of argv.filter((each) => !each.startsWith("-"))) {
+    const name = level.aliases !== undefined && Object.hasOwn(level.aliases, word) ? level.aliases[word] ?? word : word;
+    const command = Object.hasOwn(level.commands, name) ? level.commands[name] : undefined;
+    if (command === undefined)
+      break;
+    path.push(word);
+    if (!("commands" in command))
+      break;
+    level = scopeOf(command.commands, command.extraCommands, command.aliases);
+  }
+  return path.length === 0 ? undefined : path.join(" ");
 }
-async function runMain({ name, version, run, redact }, argv = process4.argv.slice(2)) {
+async function runMain({ name, version, run, redact, usage }, argv = process7.argv.slice(2)) {
   if (argv[0] === COMPLETE)
     return printCandidates(leafCandidates(run, argv.slice(1)));
   if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v")) {
     console.log(version);
     return 0;
   }
+  let code;
   try {
-    return await run(argv);
+    code = await run(argv);
   } catch (error) {
-    return reportThrown(name, error, redact, wantsJson(argv));
+    code = reportThrown(name, error, redact, wantsJson(argv));
   }
+  if (usage !== false)
+    recordUsage(usageEntry(name, undefined, argv, code));
+  return code;
 }
-// ../kit/src/logs.ts
-var DAY_MS = 24 * 60 * 60 * 1000;
 // ../kit/src/secrets.ts
 var SECRET_WORDS = new Set(["key", "pass", "pwd", "auth", "salt", "cookie", "session", "jwt", "ssn", "iban", "card", "cvv", "otp"]);
 // ../kit/src/sessions.ts
@@ -931,16 +1104,16 @@ var {Glob } = globalThis.Bun;
 var SESSION_FILES = new Glob("*.json");
 var ACCOUNT_DIRS = new Glob("*/sessions");
 // package.json
-var version = "0.3.0";
+var version = "0.4.0";
 
 // src/completions.ts
-import { existsSync as existsSync2, mkdirSync, readdirSync, readFileSync as readFileSync2, rmSync } from "fs";
-import { join as join2 } from "path";
-import process6 from "process";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync2, rmSync } from "fs";
+import { join as join3 } from "path";
+import process9 from "process";
 
 // src/checks.ts
 import { existsSync, readFileSync } from "fs";
-import { basename, join } from "path";
+import { basename, join as join2 } from "path";
 var TOOLS = {
   "@kaynooo/cli-base": ["base", "proof"],
   "@kaynooo/cli-changelog": ["changelog"],
@@ -955,8 +1128,13 @@ var TOOLS = {
   "@kaynooo/cli-gitlab": ["gl"],
   "@kaynooo/cli-guard": ["guard"],
   "@kaynooo/cli-out": ["out"],
+  "@kaynooo/cli-dev": ["dev"],
+  "@kaynooo/cli-pick": ["pick"],
   "@kaynooo/cli-pkg": ["pkg"],
+  "@kaynooo/cli-probe": ["probe"],
+  "@kaynooo/cli-repos": ["repos"],
   "@kaynooo/cli-stack": ["stack"],
+  "@kaynooo/cli-sweep": ["sweep"],
   "@kaynooo/cli-view": ["view"],
   "@kaynooo/cli-wait": ["waitfor", "slot"]
 };
@@ -984,12 +1162,12 @@ function firstLine(text) {
   return end === -1 ? trimmed : trimmed.slice(0, end);
 }
 function installed(host, name) {
-  return readJson(join(host.globalModules, name, "package.json"));
+  return readJson(join2(host.globalModules, name, "package.json"));
 }
 function ownBin(host, name, bin) {
   const declared = installed(host, name)?.bin;
   const file = typeof declared === "string" ? declared : declared?.[bin];
-  return file === undefined ? undefined : join(host.globalModules, name, file);
+  return file === undefined ? undefined : join2(host.globalModules, name, file);
 }
 async function checkTool(host, name, bins) {
   const check = name.slice(name.indexOf("/") + 1);
@@ -998,7 +1176,7 @@ async function checkTool(host, name, bins) {
     return { check, ok: false, detail: "not installed", fix: `bun install -g ${name}` };
   const off = bins.filter((bin) => host.which(bin) === null);
   if (off.length > 0)
-    return { check, ok: false, detail: `${version}, ${off.join(", ")} not on the PATH`, fix: `add ${join(host.globalModules, "..", "..", "..", "bin")} to the PATH` };
+    return { check, ok: false, detail: `${version}, ${off.join(", ")} not on the PATH`, fix: `add ${join2(host.globalModules, "..", "..", "..", "bin")} to the PATH` };
   const info = await host.run(["bun", "info", name, "version", "--no-cache"]);
   const answered = info.code === 0 ? firstLine(info.stdout.trim().split(`
 `).at(-1) ?? "") : "";
@@ -1025,9 +1203,9 @@ async function checkTea(host) {
   return { check: "tea", ok: true, detail: `logged in to ${forge} as ${login.name}, Forgejo ${served}` };
 }
 function checkHooks(host) {
-  const settings = readJson(join(host.home, ".claude", "settings.json")) ?? {};
+  const settings = readJson(join2(host.home, ".claude", "settings.json")) ?? {};
   const plugin = settings.enabledPlugins?.[PLUGIN] === true;
-  const mod = (settings.env?.CLAUDE_CODE_PLUGIN_DIRS ?? "").split(":").map((dir) => dir.replace(LEADING_TILDE, host.home)).find((dir) => basename(dir) === "cli" && existsSync(join(dir, "hooks", "hooks.json")));
+  const mod = (settings.env?.CLAUDE_CODE_PLUGIN_DIRS ?? "").split(":").map((dir) => dir.replace(LEADING_TILDE, host.home)).find((dir) => basename(dir) === "cli" && existsSync(join2(dir, "hooks", "hooks.json")));
   if (plugin && mod !== undefined)
     return { check: "hooks", ok: false, detail: `both the ${PLUGIN} plugin and the mod in ${mod} run guard, so every call is checked twice`, fix: `claude plugin disable ${PLUGIN}` };
   if (plugin)
@@ -1074,8 +1252,8 @@ var FUNCTION = `functions -q __kaynooo_cli_complete; or function __kaynooo_cli_c
         end
     end
 end`;
-function completionDir(home, env = process6.env) {
-  return join2(env.XDG_CACHE_HOME ?? join2(home, ".cache"), "fish", "kaynooo-cli");
+function completionDir(home, env = process9.env) {
+  return join3(env.XDG_CACHE_HOME ?? join3(home, ".cache"), "fish", "kaynooo-cli");
 }
 function installedBins(host) {
   return Object.values(TOOLS).flat().filter((bin) => host.which(bin) !== null);
@@ -1088,31 +1266,31 @@ complete -c ${bin} -f -a '(__kaynooo_cli_complete ${bin})'
 }
 async function installCompletions(host, dir) {
   const bins = installedBins(host);
-  mkdirSync(dir, { recursive: true });
-  const removed = readdirSync(dir).filter((name) => FISH_FILE.test(name) && !bins.includes(name.replace(FISH_FILE, "")) && readFileSync2(join2(dir, name), "utf8").startsWith(MARKER));
+  mkdirSync2(dir, { recursive: true });
+  const removed = readdirSync(dir).filter((name) => FISH_FILE.test(name) && !bins.includes(name.replace(FISH_FILE, "")) && readFileSync2(join3(dir, name), "utf8").startsWith(MARKER));
   for (const name of removed)
-    rmSync(join2(dir, name));
-  await Promise.all(bins.map(async (bin) => Bun.write(join2(dir, `${bin}.fish`), completionFile(bin))));
+    rmSync(join3(dir, name));
+  await Promise.all(bins.map(async (bin) => Bun.write(join3(dir, `${bin}.fish`), completionFile(bin))));
   return { written: bins, removed: removed.map((name) => name.replace(FISH_FILE, "")) };
 }
 function missingCompletions(host, dir) {
-  return installedBins(host).filter((bin) => !existsSync2(join2(dir, `${bin}.fish`)));
+  return installedBins(host).filter((bin) => !existsSync2(join3(dir, `${bin}.fish`)));
 }
 
 // src/host.ts
-import { homedir } from "os";
-import { join as join3 } from "path";
-import process7 from "process";
+import { homedir as homedir2 } from "os";
+import { join as join4 } from "path";
+import process10 from "process";
 var RUN_TIMEOUT_MS = 20000;
 function hostHere() {
-  const home = homedir();
+  const home = homedir2();
   return {
     home,
-    globalModules: join3(process7.env.BUN_INSTALL ?? join3(home, ".bun"), "install", "global", "node_modules"),
+    globalModules: join4(process10.env.BUN_INSTALL ?? join4(home, ".bun"), "install", "global", "node_modules"),
     bunVersion: Bun.version,
     which: (bin) => Bun.which(bin),
     run: async (argv, env) => {
-      const ran = await runCommand(argv, { timeoutMs: RUN_TIMEOUT_MS, ...env === undefined ? {} : { env: { ...process7.env, ...env } } });
+      const ran = await runCommand(argv, { timeoutMs: RUN_TIMEOUT_MS, ...env === undefined ? {} : { env: { ...process10.env, ...env } } });
       if (ran.timedOut)
         return { code: 1, stdout: "", stderr: `timed out after ${RUN_TIMEOUT_MS / 1000}s` };
       const of = (stream) => Buffer.concat(ran.chunks.filter((chunk) => chunk.stream === stream).map((chunk) => chunk.data)).toString();
@@ -1146,7 +1324,7 @@ var LIST_OPTIONS = {
   json: jsonOption("[{bin, package, installed, synopsis?, summary?, replaces?, examples?}]")
 };
 function print(listed) {
-  const { cyan, dim } = paint(process8.stdout);
+  const { cyan, dim } = paint(process11.stdout);
   const width = Math.max(...listed.map((each) => each.bin.length));
   for (const each of listed) {
     const what = !each.installed ? dim(`not installed: bun install -g ${each.package}`) : `${each.summary ?? ""}${each.replaces === undefined ? "" : dim(`; instead of ${each.replaces}`)}`;
@@ -1184,8 +1362,37 @@ async function completions(args, host = hostHere()) {
   console.log(`wrote ${written.length} completions to ${dir}${removed.length === 0 ? "" : `, took out ${removed.join(", ")}`}`);
   return 0;
 }
+var STATS_USAGE = `cli stats [--since 7d] [--json]: how often each bin ran, and the usage errors by the option it did not know
+
+Every bin records each run in ~/.local/state/kaynooo-cli/usage.jsonl (or $XDG_STATE_HOME): the bin, its command, the names of the flags it saw (never a value or an argument), the exit code and, on a usage error, the unknown option. Set KAYNOOO_CLI_NO_USAGE=1 to stop recording; \`guard\` never records.
+Exits 0 when it printed the summary, 2 on a usage error.`;
+var STATS_OPTIONS = {
+  since: { type: "string", description: "only the runs this recent (7d, 12h)" },
+  json: jsonOption("{runs, bins: [{bin, runs, failed, usageErrors}], usageErrors: [{bin, command?, unknown, count}]}")
+};
+async function stats(args, path = usagePath()) {
+  const { values } = parse(args, STATS_USAGE, STATS_OPTIONS, { positionals: [], examples: ["cli stats", ["cli stats --since 7d", "the last week"]] });
+  const window = values.since === undefined ? undefined : duration(values.since, "since", 0, "h");
+  const summary = summarizeUsage(await readUsage(path, window === undefined ? 0 : Date.now() - window));
+  if (values.json === true) {
+    printJson(summary);
+    return 0;
+  }
+  if (summary.runs === 0) {
+    console.log("no run recorded");
+    return 0;
+  }
+  console.log(`${summary.runs} runs
+
+${table(summary.bins.map((each) => [each.bin, String(each.runs), `${each.failed} failed`, `${each.usageErrors} usage errors`]))}`);
+  if (summary.usageErrors.length > 0)
+    console.log(`
+unknown options
+${table(summary.usageErrors.map((each) => [`${each.bin}${each.command === undefined ? "" : ` ${each.command}`}`, each.unknown, `${each.count}x`]))}`);
+  return 0;
+}
 if (import.meta.main) {
-  process8.exitCode = await runCli({
+  process11.exitCode = await runCli({
     name: "cli",
     version,
     about: "the bins of the @kaynooo/cli-* packages, described by their own help",
@@ -1193,11 +1400,13 @@ if (import.meta.main) {
     examples: ["cli list", ["cli list --json", "with each bin's synopsis and examples"]],
     commands: {
       list: { summary: "every bin in one line: what it does and what it is reached for instead of", run: async (args) => list(args) },
+      stats: { summary: "how often each bin ran and the options usage errors did not know", run: async (args) => stats(args) },
       completions: { summary: "fish completions for every installed bin, printed or written to the folder fish reads", run: async (args) => completions(args) }
     }
   });
 }
 export {
   completions,
-  list
+  list,
+  stats
 };

package/dist/cli.js

@@ -2,12 +2,15 @@
 // @bun
 
 // src/cli.ts
-import process8 from "process";
+import process11 from "process";
 
 // ../kit/src/args.ts
-import process2 from "process";
+import process4 from "process";
 import { parseArgs } from "util";
 
+// ../kit/src/format.ts
+import process2 from "process";
+
 // ../kit/src/style.ts
 import process from "process";
 
@@ -293,11 +296,102 @@ function upTo(text, separator) {
   const end = text.indexOf(separator);
   return end === -1 ? text : text.slice(0, end);
 }
+function truncate(text, width) {
+  return text.length <= width ? text : `${text.slice(0, Math.max(0, width - 1))}\u2026`;
+}
+var LINE_BREAKS = /\s*\n\s*/g;
 var ESCAPE = String.fromCharCode(27);
+function textWidth(text) {
+  return Bun.stringWidth(text);
+}
+function table(rows, { cellWidth, header = false, align = [], fit } = {}) {
+  const cells = cellWidth === undefined ? rows : rows.map((row) => row.map((cell) => truncate(cell.replaceAll(LINE_BREAKS, " "), cellWidth)));
+  const widths = [];
+  for (const row of cells) {
+    for (const [index, cell] of row.entries())
+      widths[index] = Math.max(widths[index] ?? 0, textWidth(cell));
+  }
+  const shown = fit === undefined ? cells : narrow(cells, widths, fit);
+  const colors = paint(process2.stdout);
+  const lines = shown.map((row) => row.map((cell, index) => {
+    const width = widths[index] ?? 0;
+    const gap = " ".repeat(Math.max(0, width - textWidth(cell)));
+    if (align[index] === "right")
+      return `${gap}${cell}`;
+    return index === row.length - 1 ? cell : `${cell}${gap}`;
+  }).join("  ").trimEnd());
+  return lines.map((line, index) => header && index === 0 ? colors.bold(line) : line).join(`
+`);
+}
+function narrow(rows, widths, limit) {
+  const used = () => widths.reduce((sum, width) => sum + width, 0) + 2 * Math.max(0, widths.length - 1);
+  const cuttable = (index) => rows.every((row) => !(row[index] ?? "").includes(ESCAPE));
+  const floor = 8;
+  while (used() > limit) {
+    let widest = -1;
+    for (const [index, width] of widths.entries()) {
+      if (cuttable(index) && width > floor && width > (widths[widest] ?? 0))
+        widest = index;
+    }
+    if (widest === -1)
+      break;
+    widths[widest] = Math.max(floor, (widths[widest] ?? 0) - (used() - limit));
+  }
+  return rows.map((row) => row.map((cell, index) => textWidth(cell) > (widths[index] ?? 0) ? truncate(cell, widths[index] ?? 0) : cell));
+}
 function printJson(value) {
   console.log(JSON.stringify(value, undefined, 2));
 }
 
+// ../kit/src/help.ts
+import process3 from "process";
+var OPTIONAL = /\[[^\]]+\]/g;
+var USAGE_PREFIX = /^usage:\s*/i;
+var FULL_STOP = /\.$/;
+function usageLine(usage, colors = paint(process3.stdout)) {
+  return `${colors.bold("Usage:")} ${usage.replace(USAGE_PREFIX, "").replaceAll(OPTIONAL, (part) => colors.dim(part))}`;
+}
+function helpText(usage, options, colors = paint(process3.stdout), { examples = [], replaces } = {}) {
+  return [usageLine(usage, colors), ...replacesRows(replaces, colors), "", colors.bold("Options:"), ...optionRows(options, colors), ...exampleRows(examples, colors)].join(`
+`);
+}
+function replacesRows(replaces, colors = paint(process3.stdout)) {
+  return replaces === undefined ? [] : ["", `${colors.bold("Instead of:")} ${replaces}`];
+}
+function wantsHelpJson(env = process3.env) {
+  return env.KIT_HELP === "json";
+}
+function description(usage, { examples = [], replaces } = {}) {
+  const lines = usage.replace(USAGE_PREFIX, "").split(`
+`);
+  const first = lines[0];
+  const colon = first.indexOf(": ");
+  const prose = lines[lines.indexOf("") + 1] ?? "";
+  const fallback = lines.includes("") ? `${prose.charAt(0).toLowerCase()}${prose.slice(1)}`.replace(FULL_STOP, "") : "";
+  return {
+    synopsis: colon === -1 ? first : first.slice(0, colon),
+    summary: colon === -1 ? fallback : first.slice(colon + 2),
+    ...replaces === undefined ? {} : { replaces },
+    examples: examples.map((example) => typeof example === "string" ? { line: example } : { line: example[0], note: example[1] })
+  };
+}
+function exampleRows(examples, colors = paint(process3.stdout)) {
+  if (examples.length === 0)
+    return [];
+  return ["", colors.bold("Examples:"), ...examples.map((example) => typeof example === "string" ? `  ${example}` : `  ${example[0]}  ${colors.dim(`# ${example[1]}`)}`)];
+}
+function optionRows(options, colors = paint(process3.stdout)) {
+  const rows = Object.entries(options).map(([name, option]) => {
+    const short = option.short === undefined ? "    " : `${colors.cyan(`-${option.short}`)}, `;
+    const named = option.choices === undefined ? "<value>" : `<${option.choices.join("|")}>`;
+    const placeholder = option.optional === undefined ? named : `[${named}]`;
+    const value = option.type === "string" ? ` ${colors.dim(placeholder)}` : "";
+    return { flag: `${short}${colors.cyan(`--${name}`)}${value}`, width: `-x, --${name}`.length + (option.type === "string" ? placeholder.length + 1 : 0), description: option.description ?? "" };
+  });
+  const width = Math.max(0, ...rows.map((row) => row.width));
+  return rows.map((row) => row.description === "" ? `  ${row.flag}` : `  ${row.flag}${" ".repeat(width - row.width)}  ${colors.dim(row.description)}`);
+}
+
 // ../kit/src/text.ts
 var ANSI = new RegExp(`${String.fromCharCode(27)}\\[[\\d;?]*[a-z]`, "gi");
 function distance(a, b) {
@@ -317,8 +411,21 @@ function closest(name, names) {
   const [best] = names.map((known) => ({ known, far: distance(name, known) })).sort((a, b) => a.far - b.far);
   return best !== undefined && best.far <= (name.length < 4 ? 1 : 2) ? best.known : undefined;
 }
+// ../kit/src/input.ts
+var DURATION = /^(\d+(?:\.\d+)?)(ms|[smhd])?$/;
+var UNIT_MS = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
+function duration(value, name, fallback, unit = "s") {
+  if (value === undefined)
+    return fallback;
+  const match = DURATION.exec(value.trim());
+  const ms = match === null ? 0 : Number(match[1]) * UNIT_MS[match[2] ?? unit];
+  if (ms < 1)
+    badUsage(`--${name} takes a duration such as 30s, 5m, 1h or 7d, not ${value}`);
+  return ms;
+}
 
 // ../kit/src/args.ts
+var DASHES = /^-+/;
 function jsonOption(holds) {
   return { type: "boolean", description: holds === undefined ? "print JSON" : `print JSON: ${holds}` };
 }
@@ -358,58 +465,11 @@ class Completing {
   }
 }
 var completion = { active: false };
-var OPTIONAL = /\[[^\]]+\]/g;
-var USAGE_PREFIX = /^usage:\s*/i;
-var FULL_STOP = /\.$/;
-var DASHES = /^-+/;
-function usageLine(usage, colors = paint(process2.stdout)) {
-  return `${colors.bold("Usage:")} ${usage.replace(USAGE_PREFIX, "").replaceAll(OPTIONAL, (part) => colors.dim(part))}`;
-}
-function helpText(usage, options, colors = paint(process2.stdout), { examples = [], replaces } = {}) {
-  return [usageLine(usage, colors), ...replacesRows(replaces, colors), "", colors.bold("Options:"), ...optionRows(options, colors), ...exampleRows(examples, colors)].join(`
-`);
-}
-function replacesRows(replaces, colors = paint(process2.stdout)) {
-  return replaces === undefined ? [] : ["", `${colors.bold("Instead of:")} ${replaces}`];
-}
-function wantsHelpJson(env = process2.env) {
-  return env.KIT_HELP === "json";
-}
-function description(usage, { examples = [], replaces } = {}) {
-  const lines = usage.replace(USAGE_PREFIX, "").split(`
-`);
-  const first = lines[0];
-  const colon = first.indexOf(": ");
-  const prose = lines[lines.indexOf("") + 1] ?? "";
-  const fallback = lines.includes("") ? `${prose.charAt(0).toLowerCase()}${prose.slice(1)}`.replace(FULL_STOP, "") : "";
-  return {
-    synopsis: colon === -1 ? first : first.slice(0, colon),
-    summary: colon === -1 ? fallback : first.slice(colon + 2),
-    ...replaces === undefined ? {} : { replaces },
-    examples: examples.map((example) => typeof example === "string" ? { line: example } : { line: example[0], note: example[1] })
-  };
-}
-function exampleRows(examples, colors = paint(process2.stdout)) {
-  if (examples.length === 0)
-    return [];
-  return ["", colors.bold("Examples:"), ...examples.map((example) => typeof example === "string" ? `  ${example}` : `  ${example[0]}  ${colors.dim(`# ${example[1]}`)}`)];
-}
-function optionRows(options, colors = paint(process2.stdout)) {
-  const rows = Object.entries(options).map(([name, option]) => {
-    const short = option.short === undefined ? "    " : `${colors.cyan(`-${option.short}`)}, `;
-    const named = option.choices === undefined ? "<value>" : `<${option.choices.join("|")}>`;
-    const placeholder = option.optional === undefined ? named : `[${named}]`;
-    const value = option.type === "string" ? ` ${colors.dim(placeholder)}` : "";
-    return { flag: `${short}${colors.cyan(`--${name}`)}${value}`, width: `-x, --${name}`.length + (option.type === "string" ? placeholder.length + 1 : 0), description: option.description ?? "" };
-  });
-  const width = Math.max(0, ...rows.map((row) => row.width));
-  return rows.map((row) => row.description === "" ? `  ${row.flag}` : `  ${row.flag}${" ".repeat(width - row.width)}  ${colors.dim(row.description)}`);
-}
 var OUTPUT_OPTIONS = {
   color: { type: "string", description: "auto (on a terminal alone), always or never" },
   plain: { type: "boolean", description: "plain text, no colour or spinner: --color never" }
 };
-function applyOutput(color, plain, env = process2.env) {
+function applyOutput(color, plain, env = process4.env) {
   const when = plain === true ? "never" : color ?? "auto";
   if (when === "auto")
     return;
@@ -568,7 +628,7 @@ function nearestOption(message, options, allowNegative) {
 }
 // ../kit/src/process.ts
 import { constants } from "os";
-import process3 from "process";
+import process5 from "process";
 var KILL_GRACE_MS = 2000;
 function exitCodeOf(code, signal) {
   if (code !== null)
@@ -588,7 +648,7 @@ async function runCommand(argv, { cwd, env, stdin = "ignore", timeoutMs, signal,
       return;
     try {
       if (grouped)
-        process3.kill(-proc.pid, killing);
+        process5.kill(-proc.pid, killing);
       else
         proc.kill(killing);
     } catch {}
@@ -662,7 +722,95 @@ var ESCAPE_CODE = new RegExp(`${ESC}(?:\\[[\\x30-\\x3F]*[\\x20-\\x2F]*[\\x40-\\x
 var RESET_STYLE = `${ESC}[0m`;
 var CLOSE_LINK = `${ESC}]8;;${ESC}\\`;
 // ../kit/src/cli.ts
-import process4 from "process";
+import process7 from "process";
+
+// ../kit/src/usage.ts
+import { appendFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { dirname, isAbsolute, join } from "path";
+import process6 from "process";
+
+// ../kit/src/logs.ts
+var DAY_MS = 24 * 60 * 60 * 1000;
+var CLI_FOLDER = "kaynooo-cli";
+
+// ../kit/src/usage.ts
+var UNKNOWN_OPTION2 = /unknown option '(--[a-z][a-z0-9-]*)[=']/;
+var FLAG_NAME = /^(?:--[a-z][a-z0-9-]*|-[a-zA-Z])$/;
+var LONGEST_NAME = 40;
+var usageError;
+function noteUsageError(message) {
+  usageError = message;
+}
+function stateHome(env = process6.env) {
+  const dir = env.XDG_STATE_HOME;
+  return dir !== undefined && isAbsolute(dir) ? dir : join(homedir(), ".local", "state");
+}
+function usagePath(env = process6.env) {
+  return join(stateHome(env), CLI_FOLDER, "usage.jsonl");
+}
+function usageRecorded(env = process6.env) {
+  const off = env.KAYNOOO_CLI_NO_USAGE;
+  return env.NODE_ENV !== "test" && (off === undefined || off === "" || off === "0");
+}
+function flagNames(argv) {
+  const end = argv.indexOf("--");
+  const names = (end === -1 ? argv : argv.slice(0, end)).filter((word) => word.startsWith("-") && word !== "-").map((word) => word.includes("=") ? word.slice(0, word.indexOf("=")) : word);
+  return [...new Set(names)].filter((name) => name.length <= LONGEST_NAME && FLAG_NAME.test(name));
+}
+function usageEntry(bin, command, argv, code, now = new Date) {
+  const unknown = code === 2 && usageError !== undefined ? UNKNOWN_OPTION2.exec(usageError)?.[1] : undefined;
+  usageError = undefined;
+  return { at: now.toISOString(), bin, ...command === undefined ? {} : { command }, flags: flagNames(argv), code, ...unknown === undefined ? {} : { unknown } };
+}
+function recordUsage(entry, env = process6.env) {
+  if (!usageRecorded(env))
+    return;
+  try {
+    const path = usagePath(env);
+    mkdirSync(dirname(path), { recursive: true, mode: 448 });
+    appendFileSync(path, `${JSON.stringify(entry)}
+`, { mode: 384 });
+  } catch {}
+}
+async function readUsage(path = usagePath(), since = 0) {
+  const file = Bun.file(path);
+  if (!await file.exists())
+    return [];
+  return (await file.text()).split(`
+`).flatMap((line) => {
+    try {
+      const entry = JSON.parse(line);
+      return Date.parse(entry.at) >= since ? [entry] : [];
+    } catch {
+      return [];
+    }
+  });
+}
+function summarizeUsage(entries) {
+  const bins = new Map;
+  const errors = new Map;
+  for (const entry of entries) {
+    const bin = bins.get(entry.bin) ?? { runs: 0, failed: 0, usageErrors: 0 };
+    bin.runs++;
+    bin.failed += entry.code === 0 ? 0 : 1;
+    bin.usageErrors += entry.code === 2 ? 1 : 0;
+    bins.set(entry.bin, bin);
+    if (entry.code === 2 && entry.unknown !== undefined) {
+      const key = `${entry.bin} ${entry.command ?? ""} ${entry.unknown}`;
+      const error = errors.get(key) ?? { bin: entry.bin, ...entry.command === undefined ? {} : { command: entry.command }, unknown: entry.unknown, count: 0 };
+      error.count++;
+      errors.set(key, error);
+    }
+  }
+  return {
+    runs: entries.length,
+    bins: [...bins].map(([bin, counts]) => ({ bin, ...counts })).toSorted((a, b) => b.runs - a.runs),
+    usageErrors: [...errors.values()].toSorted((a, b) => b.count - a.count)
+  };
+}
+
+// ../kit/src/cli.ts
 var LEVEL_OPTIONS = {
   ...OUTPUT_OPTIONS,
   help: { type: "boolean", short: "h", description: "show this help" }
@@ -715,7 +863,7 @@ async function expand(scope, words) {
   }
   return { ...scope, commands, lazy: [] };
 }
-async function help({ path, header, summary: lazySummary, commands, defaultCommand, examples, replaces }, stream) {
+async function help2({ path, header, summary: lazySummary, commands, defaultCommand, examples, replaces }, stream) {
   const colors = paint(stream);
   const prefix = path.join(" ");
   const summary = await resolveSummary(lazySummary);
@@ -742,8 +890,8 @@ async function help({ path, header, summary: lazySummary, commands, defaultComma
 `);
 }
 function printError(prefix, message, hint, cause) {
-  const colors = paint(process4.stderr);
-  const styled = takesControlCodes(process4.stderr);
+  const colors = paint(process7.stderr);
+  const styled = takesControlCodes(process7.stderr);
   const head = styled ? `${colors.red.bold("error")} ${colors.dim(`${prefix}:`)}` : `error: ${prefix}:`;
   const under = (label, text, tint) => text === undefined ? "" : `
   ${styled ? tint(label) : `${label}:`} ${text}`;
@@ -762,6 +910,8 @@ function reportThrown(prefix, error, redact = (text) => text, json = false) {
   const help = error instanceof UsageError ? `run ${prefix} --help for its options` : undefined;
   const named = error instanceof Error && !(error instanceof Exit) && error.name !== "Error" ? `${error.name}: ${error.message}` : undefined;
   const cause = error instanceof Error && error.cause instanceof Error ? redact(error.cause.message) : undefined;
+  if (error instanceof UsageError)
+    noteUsageError(error.message);
   const report = json ? printJsonError : (message, hint, causeText) => printError(prefix, message, hint, causeText);
   report(redact(named ?? (error instanceof Error ? error.message : String(error))), error instanceof Exit ? error.hint ?? help : undefined, cause);
   return error instanceof Exit ? error.code : 1;
@@ -784,11 +934,11 @@ async function dispatch(level, typed, { version, redact }) {
     }
   }
   if (name === undefined && level.path.length > 1) {
-    console.error(await help(await expand(level, [...level.path.slice(1), ...argv]), process4.stderr));
+    console.error(await help2(await expand(level, [...level.path.slice(1), ...argv]), process7.stderr));
     return 2;
   }
   if (name === undefined || name === "help" || name === "--help" || name === "-h") {
-    console.log(await help(await expand(level, [...level.path.slice(1), ...argv]), process4.stdout));
+    console.log(await help2(await expand(level, [...level.path.slice(1), ...argv]), process7.stdout));
     return 0;
   }
   if (level.path.length === 1 && (name === "--version" || name === "-v")) {
@@ -904,26 +1054,49 @@ async function printCandidates(found) {
     console.log(line);
   return 0;
 }
-async function runCli(cli, argv = process4.argv.slice(2)) {
+async function runCli(cli, argv = process7.argv.slice(2)) {
   if (argv[0] === COMPLETE)
     return printCandidates(candidates(scopeOf(cli.commands, cli.extraCommands, cli.aliases), cli.defaultCommand, argv.slice(1)));
-  return dispatch({ path: [cli.name], header: (colors, about) => `${colors.bold(cli.name)} ${colors.dim(cli.version)}  ${about}`, summary: cli.about, ...scopeOf(cli.commands, cli.extraCommands, cli.aliases), defaultCommand: cli.defaultCommand, runBare: cli.runBare === true, examples: cli.examples, replaces: cli.replaces }, argv, { version: cli.version, redact: cli.redact });
+  const code = await dispatch({ path: [cli.name], header: (colors, about) => `${colors.bold(cli.name)} ${colors.dim(cli.version)}  ${about}`, summary: cli.about, ...scopeOf(cli.commands, cli.extraCommands, cli.aliases), defaultCommand: cli.defaultCommand, runBare: cli.runBare === true, examples: cli.examples, replaces: cli.replaces }, argv, { version: cli.version, redact: cli.redact });
+  if (cli.usage !== false) {
+    try {
+      recordUsage(usageEntry(cli.name, commandPath(scopeOf(cli.commands, cli.extraCommands, cli.aliases), argv), argv, code));
+    } catch {}
+  }
+  return code;
+}
+function commandPath(scope, argv) {
+  const path = [];
+  let level = scope;
+  for (const word of argv.filter((each) => !each.startsWith("-"))) {
+    const name = level.aliases !== undefined && Object.hasOwn(level.aliases, word) ? level.aliases[word] ?? word : word;
+    const command = Object.hasOwn(level.commands, name) ? level.commands[name] : undefined;
+    if (command === undefined)
+      break;
+    path.push(word);
+    if (!("commands" in command))
+      break;
+    level = scopeOf(command.commands, command.extraCommands, command.aliases);
+  }
+  return path.length === 0 ? undefined : path.join(" ");
 }
-async function runMain({ name, version, run, redact }, argv = process4.argv.slice(2)) {
+async function runMain({ name, version, run, redact, usage }, argv = process7.argv.slice(2)) {
   if (argv[0] === COMPLETE)
     return printCandidates(leafCandidates(run, argv.slice(1)));
   if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v")) {
     console.log(version);
     return 0;
   }
+  let code;
   try {
-    return await run(argv);
+    code = await run(argv);
   } catch (error) {
-    return reportThrown(name, error, redact, wantsJson(argv));
+    code = reportThrown(name, error, redact, wantsJson(argv));
   }
+  if (usage !== false)
+    recordUsage(usageEntry(name, undefined, argv, code));
+  return code;
 }
-// ../kit/src/logs.ts
-var DAY_MS = 24 * 60 * 60 * 1000;
 // ../kit/src/secrets.ts
 var SECRET_WORDS = new Set(["key", "pass", "pwd", "auth", "salt", "cookie", "session", "jwt", "ssn", "iban", "card", "cvv", "otp"]);
 // ../kit/src/sessions.ts
@@ -931,16 +1104,16 @@ var {Glob } = globalThis.Bun;
 var SESSION_FILES = new Glob("*.json");
 var ACCOUNT_DIRS = new Glob("*/sessions");
 // package.json
-var version = "0.3.0";
+var version = "0.4.0";
 
 // src/checks.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { basename, join as join2 } from "path";
+import { basename, join as join3 } from "path";
 
 // src/completions.ts
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "fs";
-import { join } from "path";
-import process6 from "process";
+import { existsSync, mkdirSync as mkdirSync2, readdirSync, readFileSync, rmSync } from "fs";
+import { join as join2 } from "path";
+import process9 from "process";
 var MARKER = "# Generated by `cli completions fish`";
 var FISH_FILE = /\.fish$/;
 var FUNCTION = `functions -q __kaynooo_cli_complete; or function __kaynooo_cli_complete --argument-names bin --description 'what a @kaynooo/cli-* bin offers for the word being typed'
@@ -954,8 +1127,8 @@ var FUNCTION = `functions -q __kaynooo_cli_complete; or function __kaynooo_cli_c
         end
     end
 end`;
-function completionDir(home, env = process6.env) {
-  return join(env.XDG_CACHE_HOME ?? join(home, ".cache"), "fish", "kaynooo-cli");
+function completionDir(home, env = process9.env) {
+  return join2(env.XDG_CACHE_HOME ?? join2(home, ".cache"), "fish", "kaynooo-cli");
 }
 function installedBins(host) {
   return Object.values(TOOLS).flat().filter((bin) => host.which(bin) !== null);
@@ -968,15 +1141,15 @@ complete -c ${bin} -f -a '(__kaynooo_cli_complete ${bin})'
 }
 async function installCompletions(host, dir) {
   const bins = installedBins(host);
-  mkdirSync(dir, { recursive: true });
-  const removed = readdirSync(dir).filter((name) => FISH_FILE.test(name) && !bins.includes(name.replace(FISH_FILE, "")) && readFileSync(join(dir, name), "utf8").startsWith(MARKER));
+  mkdirSync2(dir, { recursive: true });
+  const removed = readdirSync(dir).filter((name) => FISH_FILE.test(name) && !bins.includes(name.replace(FISH_FILE, "")) && readFileSync(join2(dir, name), "utf8").startsWith(MARKER));
   for (const name of removed)
-    rmSync(join(dir, name));
-  await Promise.all(bins.map(async (bin) => Bun.write(join(dir, `${bin}.fish`), completionFile(bin))));
+    rmSync(join2(dir, name));
+  await Promise.all(bins.map(async (bin) => Bun.write(join2(dir, `${bin}.fish`), completionFile(bin))));
   return { written: bins, removed: removed.map((name) => name.replace(FISH_FILE, "")) };
 }
 function missingCompletions(host, dir) {
-  return installedBins(host).filter((bin) => !existsSync(join(dir, `${bin}.fish`)));
+  return installedBins(host).filter((bin) => !existsSync(join2(dir, `${bin}.fish`)));
 }
 
 // src/checks.ts
@@ -994,8 +1167,13 @@ var TOOLS = {
   "@kaynooo/cli-gitlab": ["gl"],
   "@kaynooo/cli-guard": ["guard"],
   "@kaynooo/cli-out": ["out"],
+  "@kaynooo/cli-dev": ["dev"],
+  "@kaynooo/cli-pick": ["pick"],
   "@kaynooo/cli-pkg": ["pkg"],
+  "@kaynooo/cli-probe": ["probe"],
+  "@kaynooo/cli-repos": ["repos"],
   "@kaynooo/cli-stack": ["stack"],
+  "@kaynooo/cli-sweep": ["sweep"],
   "@kaynooo/cli-view": ["view"],
   "@kaynooo/cli-wait": ["waitfor", "slot"]
 };
@@ -1023,12 +1201,12 @@ function firstLine(text) {
   return end === -1 ? trimmed : trimmed.slice(0, end);
 }
 function installed(host, name) {
-  return readJson(join2(host.globalModules, name, "package.json"));
+  return readJson(join3(host.globalModules, name, "package.json"));
 }
 function ownBin(host, name, bin) {
   const declared = installed(host, name)?.bin;
   const file = typeof declared === "string" ? declared : declared?.[bin];
-  return file === undefined ? undefined : join2(host.globalModules, name, file);
+  return file === undefined ? undefined : join3(host.globalModules, name, file);
 }
 async function checkTool(host, name, bins) {
   const check = name.slice(name.indexOf("/") + 1);
@@ -1037,7 +1215,7 @@ async function checkTool(host, name, bins) {
     return { check, ok: false, detail: "not installed", fix: `bun install -g ${name}` };
   const off = bins.filter((bin) => host.which(bin) === null);
   if (off.length > 0)
-    return { check, ok: false, detail: `${version}, ${off.join(", ")} not on the PATH`, fix: `add ${join2(host.globalModules, "..", "..", "..", "bin")} to the PATH` };
+    return { check, ok: false, detail: `${version}, ${off.join(", ")} not on the PATH`, fix: `add ${join3(host.globalModules, "..", "..", "..", "bin")} to the PATH` };
   const info = await host.run(["bun", "info", name, "version", "--no-cache"]);
   const answered = info.code === 0 ? firstLine(info.stdout.trim().split(`
 `).at(-1) ?? "") : "";
@@ -1064,9 +1242,9 @@ async function checkTea(host) {
   return { check: "tea", ok: true, detail: `logged in to ${forge} as ${login.name}, Forgejo ${served}` };
 }
 function checkHooks(host) {
-  const settings = readJson(join2(host.home, ".claude", "settings.json")) ?? {};
+  const settings = readJson(join3(host.home, ".claude", "settings.json")) ?? {};
   const plugin = settings.enabledPlugins?.[PLUGIN] === true;
-  const mod = (settings.env?.CLAUDE_CODE_PLUGIN_DIRS ?? "").split(":").map((dir) => dir.replace(LEADING_TILDE, host.home)).find((dir) => basename(dir) === "cli" && existsSync2(join2(dir, "hooks", "hooks.json")));
+  const mod = (settings.env?.CLAUDE_CODE_PLUGIN_DIRS ?? "").split(":").map((dir) => dir.replace(LEADING_TILDE, host.home)).find((dir) => basename(dir) === "cli" && existsSync2(join3(dir, "hooks", "hooks.json")));
   if (plugin && mod !== undefined)
     return { check: "hooks", ok: false, detail: `both the ${PLUGIN} plugin and the mod in ${mod} run guard, so every call is checked twice`, fix: `claude plugin disable ${PLUGIN}` };
   if (plugin)
@@ -1100,19 +1278,19 @@ async function runChecks(host) {
 }
 
 // src/host.ts
-import { homedir } from "os";
-import { join as join3 } from "path";
-import process7 from "process";
+import { homedir as homedir2 } from "os";
+import { join as join4 } from "path";
+import process10 from "process";
 var RUN_TIMEOUT_MS = 20000;
 function hostHere() {
-  const home = homedir();
+  const home = homedir2();
   return {
     home,
-    globalModules: join3(process7.env.BUN_INSTALL ?? join3(home, ".bun"), "install", "global", "node_modules"),
+    globalModules: join4(process10.env.BUN_INSTALL ?? join4(home, ".bun"), "install", "global", "node_modules"),
     bunVersion: Bun.version,
     which: (bin) => Bun.which(bin),
     run: async (argv, env) => {
-      const ran = await runCommand(argv, { timeoutMs: RUN_TIMEOUT_MS, ...env === undefined ? {} : { env: { ...process7.env, ...env } } });
+      const ran = await runCommand(argv, { timeoutMs: RUN_TIMEOUT_MS, ...env === undefined ? {} : { env: { ...process10.env, ...env } } });
       if (ran.timedOut)
         return { code: 1, stdout: "", stderr: `timed out after ${RUN_TIMEOUT_MS / 1000}s` };
       const of = (stream) => Buffer.concat(ran.chunks.filter((chunk) => chunk.stream === stream).map((chunk) => chunk.data)).toString();
@@ -1131,7 +1309,7 @@ var OPTIONS = {
   json: jsonOption("[{check, ok, detail, fix?}]")
 };
 function print(results) {
-  const { green, red, dim } = paint(process8.stdout);
+  const { green, red, dim } = paint(process11.stdout);
   const width = Math.max(...results.map((result) => result.check.length));
   for (const { check, ok, detail, fix } of results)
     console.log(`${ok ? green("ok  ") : red("FAIL")}  ${check.padEnd(width)}  ${detail}${fix === undefined ? "" : `  ${dim("fix:")} ${fix}`}`);
@@ -1150,7 +1328,7 @@ async function main(args, host = hostHere()) {
   return results.every((result) => result.ok) ? 0 : 1;
 }
 if (import.meta.main)
-  process8.exitCode = await runMain({ name: "doctor", version, run: async (args) => main(args) });
+  process11.exitCode = await runMain({ name: "doctor", version, run: async (args) => main(args) });
 export {
   main
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kaynooo/cli-doctor",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "doctor: checks the @kaynooo/cli-* install of a host: each bin's version against the registry, tea's login to Forgejo, the Claude Code hooks and the Bun floor; cli list: every bin in one line, read from its own help.",
   "author": "Kaynooo <contact@kaynooo.fr>",
   "license": "MIT",
@@ -36,6 +36,6 @@
     "doctor": "$npm_execpath src/cli.ts"
   },
   "devDependencies": {
-    "@kaynooo/cli-kit": "0.19.0"
+    "@kaynooo/cli-kit": "0.20.0"
   }
 }