@kaynooo/cli-doctor 0.2.0 → 0.4.0

package/dist/cli-bin.js

@@ -2,16 +2,19 @@
 // @bun
 
 // src/cli-bin.ts
-import process7 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";
 
-// ../../node_modules/.bun/@kaynooo+utils@2.31.0+d0769e28dc4dad16/node_modules/@kaynooo/utils/dist/chunk-mtetydvc.js
+// ../../node_modules/.bun/@kaynooo+utils@2.31.2+d0769e28dc4dad16/node_modules/@kaynooo/utils/dist/chunk-mtetydvc.js
 function x(s) {
   let r = s.startsWith("#") ? s.slice(1).toLowerCase() : s.toLowerCase();
   if (!/^[a-f0-9]+$/.test(r))
@@ -231,7 +234,7 @@ class e {
   }
 }
 
-// ../../node_modules/.bun/@kaynooo+utils@2.31.0+d0769e28dc4dad16/node_modules/@kaynooo/utils/dist/chunk-y1msbssb.js
+// ../../node_modules/.bun/@kaynooo+utils@2.31.2+d0769e28dc4dad16/node_modules/@kaynooo/utils/dist/chunk-y1msbssb.js
 var r = 39;
 var o = 49;
 var f2 = "\x1B[";
@@ -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}` };
 }
@@ -349,61 +456,20 @@ class HelpShown extends Exit {
 
 class Completing {
   options;
-  constructor(options) {
+  positionals;
+  candidates;
+  constructor(options, positionals = [], candidates = {}) {
     this.options = options;
+    this.positionals = positionals;
+    this.candidates = candidates;
   }
 }
 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 value = option.type === "string" ? ` ${colors.dim("<value>")}` : "";
-    return { flag: `${short}${colors.cyan(`--${name}`)}${value}`, width: `-x, --${name}`.length + (option.type === "string" ? " <value>".length : 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;
@@ -420,14 +486,13 @@ function applyOutput(color, plain, env = process2.env) {
 function parse(args, usage, options, settings = {}) {
   const output = Object.fromEntries(Object.entries(OUTPUT_OPTIONS).filter(([name]) => !(name in options)));
   const all = { ...options, ...output, help: { type: "boolean", short: "h", description: "show this help" } };
+  const listing = listed(all, settings.allowNegative === true);
   if (completion.active)
-    throw new Completing(all);
-  const separator = settings.rest === true ? args.indexOf("--") : -1;
-  const own = separator === -1 ? args : args.slice(0, separator);
-  const rest = separator === -1 ? undefined : args.slice(separator + 1);
+    throw new Completing(listing, settings.positionals, settings.candidates);
+  const { own, rest } = settings.trailing === true ? splitTrailing(args, all, settings.positionals?.length ?? 0) : splitRest(args, settings.rest === true);
   let parsed;
   try {
-    parsed = parseArgs({ args: joinDashValues(own, all), options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true });
+    parsed = parseArgs({ args: joinDashValues(withBare(own, all), all), options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true });
   } catch (error) {
     const message = parseError(error);
     throw new UsageError(message, nearestOption(message, all, settings.allowNegative === true));
@@ -435,12 +500,84 @@ function parse(args, usage, options, settings = {}) {
   const values = parsed.values;
   applyOutput("color" in output ? values.color : undefined, "plain" in output ? values.plain : undefined);
   if (values.help === true) {
-    console.log(wantsHelpJson() ? JSON.stringify(description(usage, settings)) : helpText(usage, all, undefined, settings));
+    console.log(wantsHelpJson() ? JSON.stringify(description(usage, settings)) : helpText(usage, listing, undefined, settings));
     throw new HelpShown;
   }
+  checkChoices(parsed.values, all);
+  checkConflicts(parsed.values, all);
   if (settings.positionals !== undefined)
     checkPositionals(parsed.positionals, settings.positionals);
-  return { ...parsed, positionals: parsed.positionals, rest };
+  return { ...parsed, values: parsed.values, positionals: parsed.positionals, rest };
+}
+function splitRest(args, passes) {
+  const separator = passes ? args.indexOf("--") : -1;
+  return { own: separator === -1 ? args : args.slice(0, separator), rest: separator === -1 ? undefined : args.slice(separator + 1) };
+}
+function splitTrailing(args, options, count) {
+  const takesValue = (word) => !word.includes("=") && Object.entries(options).some(([name, { short, type }]) => type === "string" && (word === `--${name}` || word === `-${short}`));
+  let seen = 0;
+  if (count === 0)
+    return { own: args, rest: undefined };
+  for (let at = 0;at < args.length; at++) {
+    const word = args[at];
+    if (word === "--")
+      break;
+    if (word.startsWith("-")) {
+      if (takesValue(word))
+        at++;
+      continue;
+    }
+    seen++;
+    if (seen === count)
+      return { own: args.slice(0, at + 1), rest: args.slice(at + 1) };
+  }
+  return { own: args, rest: undefined };
+}
+function listed(options, allowNegative) {
+  if (!allowNegative)
+    return options;
+  return Object.fromEntries(Object.entries(options).flatMap(([name, option]) => {
+    if (option.type !== "boolean" || option.negative === undefined)
+      return [[name, option]];
+    return [...option.description === undefined ? [] : [[name, option]], [`no-${name}`, { type: "boolean", description: option.negative }]];
+  }));
+}
+function withBare(args, options) {
+  const bare = new Map(Object.entries(options).flatMap(([name, { short, optional }]) => optional === undefined ? [] : [[`--${name}`, optional], ...short === undefined ? [] : [[`-${short}`, optional]]]));
+  if (bare.size === 0)
+    return args;
+  const separator = args.indexOf("--");
+  const own = separator === -1 ? args : args.slice(0, separator);
+  return [...own.flatMap((arg, index) => {
+    const optional = bare.get(arg);
+    const next = own[index + 1];
+    const value = next !== undefined && (optional?.accepts === undefined ? !next.startsWith("-") : optional.accepts.test(next));
+    return optional === undefined || value ? [arg] : [arg, optional.bare];
+  }), ...separator === -1 ? [] : args.slice(separator)];
+}
+function checkConflicts(values, options) {
+  const given = (name) => values[name] !== undefined && values[name] !== false;
+  for (const [name, { conflicts = [] }] of Object.entries(options)) {
+    const other = given(name) ? conflicts.find(given) : undefined;
+    if (other !== undefined)
+      badUsage(`--${name} cannot be used with --${other}`);
+  }
+}
+function checkChoices(values, options) {
+  for (const [name, option] of Object.entries(options)) {
+    if (option.choices === undefined)
+      continue;
+    const given = values[name];
+    for (const value of Array.isArray(given) ? given : [given]) {
+      if (typeof value === "string")
+        oneOf(value, name, option.choices);
+    }
+  }
+}
+function oneOf(value, name, choices) {
+  if (!choices.includes(value))
+    badUsage(`${name.startsWith("<") ? name : `--${name}`} takes one of ${choices.join(", ")}, not ${value}`);
+  return value;
 }
 function checkPositionals(given, names) {
   const variadic = names.at(-1)?.replace("]", "").endsWith("...") === true;
@@ -491,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)
@@ -511,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 {}
@@ -585,14 +722,103 @@ 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" }
 };
 var TOP_OPTIONS = { ...LEVEL_OPTIONS, version: { type: "boolean", short: "v", description: "print the version" } };
-async function commandRows(commands, colors) {
-  const width = Math.max(...Object.keys(commands).map((name) => name.length));
+async function commandRows(all, colors) {
+  const commands = shown(all);
+  const width = Math.max(0, ...Object.keys(commands).map((name) => name.length));
   const groups = new Map([["Commands:", []]]);
   const summaries = await Promise.all(Object.values(commands).map(async ({ summary }) => resolveSummary(summary)));
   for (const [index, [name, { group }]] of Object.entries(commands).entries()) {
@@ -603,6 +829,9 @@ async function commandRows(commands, colors) {
   }
   return [...groups].filter(([, rows]) => rows.length > 0).flatMap(([heading, rows], index) => [...index === 0 ? [] : [""], colors.bold(heading), ...rows]);
 }
+function shown(commands) {
+  return Object.fromEntries(Object.entries(commands).filter(([, { hidden }]) => hidden !== true));
+}
 function takeOutputFlags(argv) {
   let index = 0;
   for (;index < argv.length; index++) {
@@ -634,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);
@@ -661,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}`;
@@ -681,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;
@@ -694,12 +925,20 @@ async function dispatch(level, typed, { version, redact }) {
     return reportThrown(prefix, error);
   }
   const [name, ...args] = argv;
+  const fallback = level.defaultCommand === undefined ? undefined : level.commands[level.defaultCommand];
+  if (name === undefined && level.runBare && fallback !== undefined && "run" in fallback) {
+    try {
+      return await fallback.run([]);
+    } catch (error) {
+      return reportThrown(`${prefix} ${level.defaultCommand}`, error, redact, false);
+    }
+  }
   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")) {
@@ -708,6 +947,7 @@ async function dispatch(level, typed, { version, redact }) {
   }
   let command = level.commands[level.aliases?.[name] ?? name];
   let rest = args;
+  let ran = name;
   if (command === undefined && level.lazy.length > 0) {
     level = await expand(level, [...level.path.slice(1), ...argv]);
     command = level.commands[level.aliases?.[name] ?? name];
@@ -715,40 +955,77 @@ async function dispatch(level, typed, { version, redact }) {
   if (command === undefined && level.defaultCommand !== undefined) {
     command = level.commands[level.defaultCommand];
     rest = argv;
+    ran = level.defaultCommand;
   }
   if (command === undefined) {
-    const meant = closest(name, Object.keys(level.commands));
+    const meant = closest(name, Object.keys(shown(level.commands)));
     printError(prefix, `no command ${name}`, meant === undefined ? `run ${prefix} --help for its commands` : `did you mean ${meant}?`);
     return 2;
   }
   if ("commands" in command) {
     const { summary } = command;
-    return dispatch({ path: [...level.path, name], header: (colors, text) => `${colors.bold(`${prefix} ${name}`)}  ${text}`, summary, ...scopeOf(command.commands, command.extraCommands, command.aliases), defaultCommand: undefined, examples: command.examples, replaces: undefined }, rest, { version, redact });
+    return dispatch({ path: [...level.path, name], header: (colors, text) => `${colors.bold(`${prefix} ${name}`)}  ${text}`, summary, ...scopeOf(command.commands, command.extraCommands, command.aliases), defaultCommand: undefined, runBare: false, examples: command.examples, replaces: undefined }, rest, { version, redact });
   }
   try {
     return await command.run(rest);
   } catch (error) {
-    return reportThrown(`${prefix} ${name}`, error, redact, wantsJson(rest));
+    return reportThrown(`${prefix} ${ran}`, error, redact, wantsJson(rest));
   }
 }
 var COMPLETE = "__complete";
 var FILES = "__files__";
-async function optionsOf(run) {
+async function completingOf(run) {
   completion.active = true;
   try {
     await run([]);
   } catch (error) {
     if (error instanceof Completing)
-      return error.options;
+      return error;
   } finally {
     completion.active = false;
   }
-  return {};
+  return new Completing({});
+}
+async function optionsOf(run) {
+  return (await completingOf(run)).options;
+}
+function candidateLine(candidate) {
+  return typeof candidate === "string" ? candidate : candidate.join("\t");
+}
+function positionalBeingTyped(before, { options, positionals }) {
+  const takesValue = (word) => !word.includes("=") && Object.entries(options).some(([name, { short, type }]) => type === "string" && (word === `--${name}` || word === `-${short}`));
+  let index = 0;
+  let at = 0;
+  while (at < before.length) {
+    const word = before[at];
+    if (word === "--") {
+      index += before.length - at - 1;
+      break;
+    }
+    if (!word.startsWith("-"))
+      index++;
+    else if (takesValue(word))
+      at++;
+    at++;
+  }
+  const last = positionals.at(-1);
+  if (index < positionals.length)
+    return positionals[index];
+  return last?.replace("]", "").endsWith("...") === true ? last : undefined;
 }
 async function leafCandidates(run, words) {
-  if (!(words.at(-1) ?? "").startsWith("-"))
-    return [FILES];
-  return Object.entries(await optionsOf(run)).map(([name, option]) => option.description === undefined ? `--${name}` : `--${name}	${option.description}`);
+  const completing = await completingOf(run);
+  if ((words.at(-1) ?? "").startsWith("-"))
+    return Object.entries(completing.options).map(([name, option]) => option.description === undefined ? `--${name}` : `--${name}	${option.description}`);
+  const flag = words.at(-2);
+  const option = flag?.startsWith("-") === true ? Object.entries(completing.options).find(([name, { short }]) => flag === `--${name}` || flag === `-${short}`)?.[1] : undefined;
+  if (option?.type === "string") {
+    const values = option.choices === undefined ? await option.candidates?.() : option.choices;
+    return values === undefined ? [FILES] : values.map(candidateLine);
+  }
+  const name = positionalBeingTyped(words.slice(0, -1), completing);
+  const values = name === undefined ? undefined : await completing.candidates[name]?.();
+  return values === undefined ? [FILES] : values.map(candidateLine);
 }
 async function candidates(scope, defaultCommand, words, before = []) {
   const [word = "", ...rest] = words;
@@ -759,8 +1036,13 @@ async function candidates(scope, defaultCommand, words, before = []) {
     ({ commands, aliases } = await expand(scope, [...before, ...words]));
     command = commands[aliases?.[word] ?? word];
   }
-  if (listing)
-    return Promise.all(Object.entries(commands).map(async ([name, { summary }]) => `${name}	${await resolveSummary(summary)}`));
+  if (listing) {
+    const own = await Promise.all(Object.entries(shown(commands)).map(async ([name, { summary }]) => `${name}	${await resolveSummary(summary)}`));
+    const fallback = defaultCommand === undefined ? undefined : commands[defaultCommand];
+    const values = fallback !== undefined && "run" in fallback ? await leafCandidates(fallback.run, [word]) : [];
+    const valueOf = (line) => line.slice(0, line.includes("\t") ? line.indexOf("\t") : undefined);
+    return [...own, ...values.filter((line) => line !== FILES && !(valueOf(line) in commands))];
+  }
   if (command === undefined) {
     const fallback = defaultCommand === undefined ? undefined : commands[defaultCommand];
     return fallback !== undefined && "run" in fallback ? leafCandidates(fallback.run, words) : [];
@@ -772,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, 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
@@ -799,29 +1104,12 @@ var {Glob } = globalThis.Bun;
 var SESSION_FILES = new Glob("*.json");
 var ACCOUNT_DIRS = new Glob("*/sessions");
 // package.json
-var version = "0.2.0";
+var version = "0.4.0";
 
-// src/host.ts
-import { homedir } from "os";
-import { join } from "path";
-import process6 from "process";
-var RUN_TIMEOUT_MS = 20000;
-function hostHere() {
-  const home = homedir();
-  return {
-    home,
-    globalModules: join(process6.env.BUN_INSTALL ?? join(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: { ...process6.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();
-      return { code: ran.code, stdout: of("stdout"), stderr: of("stderr") };
-    }
-  };
-}
+// src/completions.ts
+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";
@@ -840,8 +1128,14 @@ 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"]
 };
 var FORGE = "git.kaynooo.fr";
@@ -927,12 +1221,82 @@ function checkBun(host) {
     return { check: "bun", ok: false, detail: `${host.bunVersion}, the tools ask for ${[...new Set(unmet)].join(" and ")}`, fix: "bun upgrade" };
   return { check: "bun", ok: true, detail: floors.length === 0 ? host.bunVersion : `${host.bunVersion}, the tools ask for ${[...new Set(floors)].join(" and ")}` };
 }
+function checkCompletions(host) {
+  if (host.which("fish") === null)
+    return { check: "completions", ok: true, detail: "fish is not installed" };
+  const dir = completionDir(host.home);
+  const missing = missingCompletions(host, dir);
+  if (missing.length > 0)
+    return { check: "completions", ok: false, detail: `no fish completion in ${dir} for ${missing.join(", ")}`, fix: "cli completions fish --install" };
+  return { check: "completions", ok: true, detail: dir };
+}
 async function runChecks(host) {
   const entries = Object.entries(TOOLS);
   const tools = [];
   for (let at = 0;at < entries.length; at += INFO_AT_ONCE)
     tools.push(...await Promise.all(entries.slice(at, at + INFO_AT_ONCE).map(async ([name, bins]) => checkTool(host, name, bins))));
-  return [...tools, await checkTea(host), checkHooks(host), checkBun(host)];
+  return [...tools, await checkTea(host), checkHooks(host), checkBun(host), checkCompletions(host)];
+}
+
+// src/completions.ts
+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'
+    set -l tokens (commandline -xpc 2>/dev/null; or commandline -opc)
+    set -l current (commandline -ct)
+    for line in ($bin __complete $tokens[2..-1] $current 2>/dev/null)
+        if test "$line" = __files__
+            __fish_complete_path $current
+        else
+            echo $line
+        end
+    end
+end`;
+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);
+}
+function completionFile(bin) {
+  return `${MARKER}
+${FUNCTION}
+complete -c ${bin} -f -a '(__kaynooo_cli_complete ${bin})'
+`;
+}
+async function installCompletions(host, dir) {
+  const bins = installedBins(host);
+  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(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(join3(dir, `${bin}.fish`)));
+}
+
+// src/host.ts
+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 = homedir2();
+  return {
+    home,
+    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: { ...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();
+      return { code: ran.code, stdout: of("stdout"), stderr: of("stderr") };
+    }
+  };
 }
 
 // src/list.ts
@@ -960,7 +1324,7 @@ var LIST_OPTIONS = {
   json: jsonOption("[{bin, package, installed, synopsis?, summary?, replaces?, examples?}]")
 };
 function print(listed) {
-  const { cyan, dim } = paint(process7.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}`)}`;
@@ -976,18 +1340,73 @@ async function list(args, host = hostHere()) {
     print(listed);
   return 0;
 }
+var COMPLETIONS_USAGE = `cli completions fish [--install] [--dir <folder>]: fish completions for every installed bin of the @kaynooo/cli-* packages
+
+Each bin completes itself through \`<bin> __complete\`; this writes the one line fish needs per bin. Without --install the files print on stdout, with it they go to ~/.cache/fish/kaynooo-cli (or $XDG_CACHE_HOME), one <bin>.fish each, the stale ones this command wrote taken out. That folder has to be in fish_complete_path, first so a completion fish ships for the same name does not win: \`set -p fish_complete_path ~/.cache/fish/kaynooo-cli\`.
+Exits 0 when it printed or wrote them, 2 on a usage error.`;
+var COMPLETIONS_OPTIONS = {
+  install: { type: "boolean", description: "write the files to the folder instead of printing them" },
+  dir: { type: "string", short: "d", description: "the folder to write to, instead of ~/.cache/fish/kaynooo-cli" }
+};
+async function completions(args, host = hostHere()) {
+  const { values, positionals } = parse(args, COMPLETIONS_USAGE, COMPLETIONS_OPTIONS, { positionals: ["<shell>"], candidates: { "<shell>": () => ["fish"] }, examples: ["cli completions fish", ["cli completions fish --install", "write one file per bin"]] });
+  if (positionals[0] !== "fish")
+    badUsage("only fish is supported: cli completions fish");
+  if (values.install !== true) {
+    console.log(installedBins(host).map(completionFile).join(`
+`));
+    return 0;
+  }
+  const dir = values.dir ?? completionDir(host.home);
+  const { written, removed } = await installCompletions(host, dir);
+  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) {
-  process7.exitCode = await runCli({
+  process11.exitCode = await runCli({
     name: "cli",
     version,
     about: "the bins of the @kaynooo/cli-* packages, described by their own help",
     replaces: "running each bin's --help to find the one that fits",
     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) }
+      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 {
-  list
+  completions,
+  list,
+  stats
 };