@kaynooo/cli-doctor 0.2.0 → 0.4.0

package/dist/cli.js

@@ -2,16 +2,19 @@
 // @bun
 
 // src/cli.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,11 +1104,55 @@ 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/checks.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { basename, join as join3 } from "path";
+
+// src/completions.ts
+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'
+    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 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);
+}
+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, "")) && readFileSync(join2(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))));
+  return { written: bins, removed: removed.map((name) => name.replace(FISH_FILE, "")) };
+}
+function missingCompletions(host, dir) {
+  return installedBins(host).filter((bin) => !existsSync(join2(dir, `${bin}.fish`)));
+}
 
 // src/checks.ts
-import { existsSync, readFileSync } from "fs";
-import { basename, join } from "path";
 var TOOLS = {
   "@kaynooo/cli-base": ["base", "proof"],
   "@kaynooo/cli-changelog": ["changelog"],
@@ -818,8 +1167,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";
@@ -837,7 +1192,7 @@ function readJsonText(text) {
   }
 }
 function readJson(path) {
-  return existsSync(path) ? readJsonText(readFileSync(path, "utf8")) : undefined;
+  return existsSync2(path) ? readJsonText(readFileSync2(path, "utf8")) : undefined;
 }
 function firstLine(text) {
   const trimmed = text.trim();
@@ -846,12 +1201,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(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 : join(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);
@@ -860,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 ${join(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) ?? "") : "";
@@ -887,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(join(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" && 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" && 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)
@@ -905,28 +1260,37 @@ 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/host.ts
-import { homedir } from "os";
-import { join as join2 } from "path";
-import process6 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: join2(process6.env.BUN_INSTALL ?? join2(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: { ...process6.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();
@@ -945,7 +1309,7 @@ var OPTIONS = {
   json: jsonOption("[{check, ok, detail, fix?}]")
 };
 function print(results) {
-  const { green, red, dim } = paint(process7.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}`}`);
@@ -964,7 +1328,7 @@ async function main(args, host = hostHere()) {
   return results.every((result) => result.ok) ? 0 : 1;
 }
 if (import.meta.main)
-  process7.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
 };