@kaynooo/cli-doctor 0.2.0 → 0.3.0

package/dist/cli-bin.js

@@ -2,7 +2,7 @@
 // @bun
 
 // src/cli-bin.ts
-import process7 from "process";
+import process8 from "process";
 
 // ../kit/src/args.ts
 import process2 from "process";
@@ -11,7 +11,7 @@ import { parseArgs } from "util";
 // ../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 +231,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[";
@@ -349,8 +349,12 @@ 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 };
@@ -393,8 +397,10 @@ function exampleRows(examples, colors = paint(process2.stdout)) {
 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 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)}`);
@@ -420,14 +426,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 +440,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;
@@ -591,8 +668,9 @@ var LEVEL_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 +681,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++) {
@@ -694,6 +775,14 @@ 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));
     return 2;
@@ -708,6 +797,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 +805,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 +886,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) : [];
@@ -775,7 +907,7 @@ async function printCandidates(found) {
 async function runCli(cli, argv = process4.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 });
+  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 });
 }
 async function runMain({ name, version, run, redact }, argv = process4.argv.slice(2)) {
   if (argv[0] === COMPLETE)
@@ -799,33 +931,16 @@ 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.3.0";
 
-// src/host.ts
-import { homedir } from "os";
-import { join } from "path";
+// 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";
-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/checks.ts
 import { existsSync, readFileSync } from "fs";
-import { basename, join as join2 } from "path";
+import { basename, join } from "path";
 var TOOLS = {
   "@kaynooo/cli-base": ["base", "proof"],
   "@kaynooo/cli-changelog": ["changelog"],
@@ -842,6 +957,7 @@ var TOOLS = {
   "@kaynooo/cli-out": ["out"],
   "@kaynooo/cli-pkg": ["pkg"],
   "@kaynooo/cli-stack": ["stack"],
+  "@kaynooo/cli-view": ["view"],
   "@kaynooo/cli-wait": ["waitfor", "slot"]
 };
 var FORGE = "git.kaynooo.fr";
@@ -868,12 +984,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(join(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 : join(host.globalModules, name, file);
 }
 async function checkTool(host, name, bins) {
   const check = name.slice(name.indexOf("/") + 1);
@@ -882,7 +998,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 ${join(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) ?? "") : "";
@@ -909,9 +1025,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(join(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(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" && existsSync(join(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)
@@ -927,12 +1043,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 = process6.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);
+  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));
+  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) => !existsSync2(join2(dir, `${bin}.fish`)));
+}
+
+// src/host.ts
+import { homedir } from "os";
+import { join as join3 } from "path";
+import process7 from "process";
+var RUN_TIMEOUT_MS = 20000;
+function hostHere() {
+  const home = homedir();
+  return {
+    home,
+    globalModules: join3(process7.env.BUN_INSTALL ?? join3(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 } } });
+      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 +1146,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(process8.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 +1162,42 @@ 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;
+}
 if (import.meta.main) {
-  process7.exitCode = await runCli({
+  process8.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) },
+      completions: { summary: "fish completions for every installed bin, printed or written to the folder fish reads", run: async (args) => completions(args) }
     }
   });
 }
 export {
+  completions,
   list
 };

package/dist/cli.js

@@ -2,7 +2,7 @@
 // @bun
 
 // src/cli.ts
-import process7 from "process";
+import process8 from "process";
 
 // ../kit/src/args.ts
 import process2 from "process";
@@ -11,7 +11,7 @@ import { parseArgs } from "util";
 // ../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 +231,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[";
@@ -349,8 +349,12 @@ 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 };
@@ -393,8 +397,10 @@ function exampleRows(examples, colors = paint(process2.stdout)) {
 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 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)}`);
@@ -420,14 +426,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 +440,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;
@@ -591,8 +668,9 @@ var LEVEL_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 +681,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++) {
@@ -694,6 +775,14 @@ 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));
     return 2;
@@ -708,6 +797,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 +805,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 +886,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) : [];
@@ -775,7 +907,7 @@ async function printCandidates(found) {
 async function runCli(cli, argv = process4.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 });
+  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 });
 }
 async function runMain({ name, version, run, redact }, argv = process4.argv.slice(2)) {
   if (argv[0] === COMPLETE)
@@ -799,11 +931,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.3.0";
+
+// src/checks.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { basename, join as join2 } from "path";
+
+// src/completions.ts
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "fs";
+import { join } from "path";
+import process6 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 = process6.env) {
+  return join(env.XDG_CACHE_HOME ?? join(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);
+  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));
+  for (const name of removed)
+    rmSync(join(dir, name));
+  await Promise.all(bins.map(async (bin) => Bun.write(join(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`)));
+}
 
 // src/checks.ts
-import { existsSync, readFileSync } from "fs";
-import { basename, join } from "path";
 var TOOLS = {
   "@kaynooo/cli-base": ["base", "proof"],
   "@kaynooo/cli-changelog": ["changelog"],
@@ -820,6 +996,7 @@ var TOOLS = {
   "@kaynooo/cli-out": ["out"],
   "@kaynooo/cli-pkg": ["pkg"],
   "@kaynooo/cli-stack": ["stack"],
+  "@kaynooo/cli-view": ["view"],
   "@kaynooo/cli-wait": ["waitfor", "slot"]
 };
 var FORGE = "git.kaynooo.fr";
@@ -837,7 +1014,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 +1023,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);
@@ -860,7 +1037,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) ?? "") : "";
@@ -887,9 +1064,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" && existsSync2(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)
@@ -905,28 +1082,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 { join as join3 } from "path";
+import process7 from "process";
 var RUN_TIMEOUT_MS = 20000;
 function hostHere() {
   const home = homedir();
   return {
     home,
-    globalModules: join2(process6.env.BUN_INSTALL ?? join2(home, ".bun"), "install", "global", "node_modules"),
+    globalModules: join3(process7.env.BUN_INSTALL ?? join3(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: { ...process7.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 +1131,7 @@ var OPTIONS = {
   json: jsonOption("[{check, ok, detail, fix?}]")
 };
 function print(results) {
-  const { green, red, dim } = paint(process7.stdout);
+  const { green, red, dim } = paint(process8.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 +1150,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) });
+  process8.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.2.0",
+  "version": "0.3.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.15.0"
+    "@kaynooo/cli-kit": "0.19.0"
   }
 }