@kaynooo/cli-doctor 0.5.2 → 0.7.0

package/README.md

@@ -38,10 +38,10 @@ Each bin completes itself through `<bin> __complete`. fish gets a file per bin (
 ## cli stats
 
 ```sh
-cli stats [--since 7d] [--json]   # runs per bin, failures, and the options usage errors did not know
+cli stats [--since 7d] [--json]   # runs per bin and per command, failures (exit 1) apart from usage errors (exit 2), and the options usage errors did not know
 ```
 
-Every bin records each run in `~/.local/state/kaynooo-cli/usage.jsonl`: the bin, its command, the flag names it saw (never values or arguments), the exit code and, on a usage error, the unknown option. `KAYNOOO_CLI_NO_USAGE=1` turns it off; `guard` never records.
+Every bin records each run in `~/.local/state/kaynooo-cli/usage.jsonl`: the bin, its command, the flag names it saw (never values or arguments), the exit code and, on a usage error, the unknown option (never its message). `KAYNOOO_CLI_NO_USAGE=1` turns it off; `guard` never records.
 
 ## cli list
 

package/dist/cli-bin.js

@@ -2,7 +2,7 @@
 // @bun
 
 // src/cli-bin.ts
-import process12 from "process";
+import process13 from "process";
 // ../kit/src/args.ts
 import process5 from "process";
 import { parseArgs } from "util";
@@ -808,26 +808,38 @@ async function readUsage(path = usagePath(), since = 0) {
     }
   });
 }
+function tally(counts, code) {
+  counts.runs++;
+  counts.failed += code === 0 || code === 2 ? 0 : 1;
+  counts.usageErrors += code === 2 ? 1 : 0;
+}
 function summarizeUsage(entries) {
   const bins = new Map;
-  const errors = new Map;
+  const commands = new Map;
+  const unknowns = 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;
+    tally(bin, entry.code);
     bins.set(entry.bin, bin);
-    if (entry.code === 2 && entry.unknown !== undefined) {
+    if (entry.command !== undefined) {
+      const command = commands.get(`${entry.bin} ${entry.command}`) ?? { bin: entry.bin, command: entry.command, runs: 0, failed: 0, usageErrors: 0 };
+      tally(command, entry.code);
+      commands.set(`${entry.bin} ${entry.command}`, command);
+    }
+    if (entry.code !== 2)
+      continue;
+    if (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);
+      const unknown = unknowns.get(key) ?? { bin: entry.bin, ...entry.command === undefined ? {} : { command: entry.command }, unknown: entry.unknown, count: 0 };
+      unknown.count++;
+      unknowns.set(key, unknown);
     }
   }
   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)
+    commands: [...commands.values()].toSorted((a, b) => b.runs - a.runs),
+    usageErrors: [...unknowns.values()].toSorted((a, b) => b.count - a.count)
   };
 }
 
@@ -931,7 +943,7 @@ 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)
+  if (error instanceof Exit && error.code === 2)
     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);
@@ -1148,11 +1160,10 @@ import process10 from "process";
 import { existsSync, readFileSync as readFileSync2 } from "fs";
 import { basename, join as join3 } from "path";
 var TOOLS = {
-  "@kaynooo/cli-audit": ["audit"],
   "@kaynooo/cli-base": ["base", "proof"],
   "@kaynooo/cli-changelog": ["changelog"],
   "@kaynooo/cli-check": ["check", "fix", "errs", "j"],
-  "@kaynooo/cli-code": ["peek", "todo-scan", "hotspots"],
+  "@kaynooo/cli-code": ["src", "peek", "todo-scan", "hotspots"],
   "@kaynooo/cli-db": ["db"],
   "@kaynooo/cli-docker": ["dc", "dlog", "dx", "sf"],
   "@kaynooo/cli-doctor": ["doctor", "cli"],
@@ -1167,12 +1178,11 @@ var TOOLS = {
   "@kaynooo/cli-pick": ["pick"],
   "@kaynooo/cli-pkg": ["pkg"],
   "@kaynooo/cli-probe": ["probe"],
-  "@kaynooo/cli-proc": ["pid", "ports", "procs"],
-  "@kaynooo/cli-repos": ["repos"],
+  "@kaynooo/cli-proc": ["proc", "pid", "ports", "procs"],
   "@kaynooo/cli-stack": ["stack"],
-  "@kaynooo/cli-sweep": ["sweep"],
   "@kaynooo/cli-view": ["view"],
-  "@kaynooo/cli-wait": ["waitfor", "slot"]
+  "@kaynooo/cli-wait": ["waitfor", "slot"],
+  "@kaynooo/cli-workspace": ["ws", "repos", "sweep", "audit"]
 };
 var FORGE = "git.kaynooo.fr";
 var FORGE_HOSTS = new Set([FORGE, "git.kevyn.fr"]);
@@ -1343,6 +1353,46 @@ function missingCompletions(host, dir) {
   return installedBins(host).filter((bin) => !existsSync2(join4(dir, `${bin}.fish`)));
 }
 
+// src/doctor.ts
+import process12 from "process";
+
+// src/fix.ts
+var INSTALL = /^bun install -g (\S+)$/;
+var RUNNABLE = /^(?:cli completions fish --install|claude plugin (?:install \S+ --marketplace \S+|disable \S+))$/;
+function planFixes(results) {
+  const steps = [];
+  const installs = [];
+  for (const { ok, fix } of results) {
+    if (ok || fix === undefined)
+      continue;
+    const install = INSTALL.exec(fix);
+    if (install !== null)
+      installs.push(install[1] ?? "");
+    else
+      steps.push({ command: fix, argv: RUNNABLE.test(fix) ? fix.split(" ") : undefined });
+  }
+  if (installs.length === 0)
+    return steps;
+  const command = `bun install -g ${installs.join(" ")}`;
+  return [{ command, argv: command.split(" ") }, ...steps];
+}
+async function applyFixes(host, steps, dry) {
+  const outcomes = [];
+  for (const { command, argv } of steps) {
+    if (argv === undefined) {
+      outcomes.push({ command, status: "not run", detail: "not a command doctor runs: do it by hand" });
+      continue;
+    }
+    if (dry) {
+      outcomes.push({ command, status: "dry-run" });
+      continue;
+    }
+    const ran = await host.run(argv);
+    outcomes.push(ran.code === 0 ? { command, status: "ran" } : { command, status: "failed", detail: `exit ${ran.code}: ${firstLine(ran.stderr || ran.stdout)}` });
+  }
+  return outcomes;
+}
+
 // src/host.ts
 import { homedir as homedir2 } from "os";
 import { join as join5 } from "path";
@@ -1365,6 +1415,67 @@ function hostHere() {
   };
 }
 
+// src/doctor.ts
+var USAGE = `doctor [--only <check>] [--quiet] [--fix [--dry-run]] [--json]: checks this host's @kaynooo/cli-* install, one line per check, the command that fixes a failing one beside it
+
+Each @kaynooo/cli-* package installed globally with its bins on the PATH and no older than the registry's latest; tea logged in to git.kaynooo.fr and reaching it; the Claude Code hooks wired through the cli-hooks plugin or the cli mod, not both; Bun at least the version the tools ask for; fish completions for every bin.
+--fix runs the printed fix: lines it may (global installs of the packages, the completions, the hooks plugin), the installs in one call, then checks again; a line that installs a system package or only describes a step is printed as not run. --dry-run shows what --fix would run.
+--quiet prints only the failing checks, nothing when all pass. --only limits the run to the checks named, e.g. --only tea --only bun.`;
+var EXITS = [[0, "every check passes (after --fix, the ones it fixed too)"], [1, "a check fails"], [2, "a usage error"]];
+var INSTALL2 = "bun install -g ";
+var OPTIONS = {
+  json: jsonOption("[{check, ok, detail, fix?}], as the checks stand after --fix; the fixes it ran go to stderr"),
+  only: { type: "string", multiple: true, choices: CHECK_NAMES, description: "run only this check (a package such as cli-forgejo, tea, hooks, bun or completions), repeatable" },
+  quiet: { type: "boolean", short: "q", description: "print only the failing checks" },
+  fix: { type: "boolean", description: "run the fix: lines doctor may run, then check again" },
+  "dry-run": { type: "boolean", description: "with --fix, show what would run without running it (alone, it implies --fix)" }
+};
+function print(results) {
+  if (results.length === 0)
+    return;
+  const { green, red, dim } = paint(process12.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}`}`);
+  const installs = results.flatMap((result) => result.fix?.startsWith(INSTALL2) === true ? [result.fix.slice(INSTALL2.length)] : []);
+  if (installs.length > 1)
+    console.log(`
+${dim("fix them all:")} ${INSTALL2}${installs.join(" ")}`);
+}
+function printOutcomes(outcomes, log) {
+  const { green, red, dim } = paint(process12.stdout);
+  const marks = { ran: green("ran    "), failed: red("failed "), "dry-run": dim("would  "), "not run": dim("not run") };
+  for (const { command, status, detail } of outcomes)
+    log(`${marks[status]}  ${command}${detail === undefined ? "" : `  ${dim(detail)}`}`);
+}
+async function main(args, host = hostHere()) {
+  const { values } = parse(args, USAGE, OPTIONS, { positionals: [], exits: EXITS, replaces: "checking each bin's version, tea's login and the hooks by hand", examples: ["doctor", ["doctor --json", "the checks for a script"], ["doctor -q", "silent unless something fails"], ["doctor --fix --dry-run", "what --fix would run"]] });
+  const only = values.only ?? [];
+  const dry = values["dry-run"] === true;
+  const json = values.json === true;
+  let results = await runChecks(host, only);
+  let fixed = false;
+  if ((values.fix === true || dry) && results.some((result) => !result.ok)) {
+    if (!json)
+      print(values.quiet === true ? results.filter((result) => !result.ok) : results);
+    const steps = planFixes(results);
+    printOutcomes(await applyFixes(host, steps, dry), json ? console.error : console.log);
+    if (dry)
+      return 1;
+    results = await runChecks(host, only);
+    fixed = true;
+  }
+  const shown = values.quiet === true ? results.filter((result) => !result.ok) : results;
+  if (fixed && !json && shown.length > 0)
+    console.log(`
+after the fixes:`);
+  if (json)
+    printJson(shown);
+  else
+    print(shown);
+  return results.every((result) => result.ok) ? 0 : 1;
+}
+
 // src/list.ts
 var USAGE_WORD = /^Usage:\s*/;
 async function describeBin(host, bin, name) {
@@ -1389,8 +1500,8 @@ Exits 0 when it printed the list, 2 on a usage error.`;
 var LIST_OPTIONS = {
   json: jsonOption("[{bin, package, installed, synopsis?, summary?, replaces?, examples?}]")
 };
-function print(listed) {
-  const { cyan, dim } = paint(process12.stdout);
+function print2(listed) {
+  const { cyan, dim } = paint(process13.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}`)}`;
@@ -1403,7 +1514,7 @@ async function list(args, host = hostHere()) {
   if (values.json === true)
     printJson(listed);
   else
-    print(listed);
+    print2(listed);
   return 0;
 }
 var COMPLETIONS_USAGE = `cli completions <fish|bash> [--install] [--dir <folder>]: shell completions for every installed bin of the @kaynooo/cli-* packages
@@ -1440,11 +1551,11 @@ async function completions(args, host = hostHere()) {
 }
 var STATS_USAGE = `cli stats [--since 7d] [--json]: how often each bin ran, and the usage errors by the option it did not know
 
-Every bin records each run in ~/.local/state/kaynooo-cli/usage.jsonl (or $XDG_STATE_HOME): the bin, its command, the names of the flags it saw (never a value or an argument), the exit code and, on a usage error, the unknown option. Set KAYNOOO_CLI_NO_USAGE=1 to stop recording; \`guard\` never records.
+Every bin records each run in ~/.local/state/kaynooo-cli/usage.jsonl (or $XDG_STATE_HOME): the bin, its command, the names of the flags it saw (never a value or an argument), the exit code and and, on a usage error, the unknown option (never the message, which carries the values it refused). failed counts exits other than 0 and 2, usage errors are exit 2 (misuse, or a check that could not be made). Set KAYNOOO_CLI_NO_USAGE=1 to stop recording; \`guard\` never records.
 Exits 0 when it printed the summary, 2 on a usage error.`;
 var STATS_OPTIONS = {
   since: { type: "string", description: "only the runs this recent (7d, 12h)" },
-  json: jsonOption("{runs, bins: [{bin, runs, failed, usageErrors}], usageErrors: [{bin, command?, unknown, count}]}")
+  json: jsonOption("{runs, bins: [{bin, runs, failed, usageErrors}], commands: [{bin, command, runs, failed, usageErrors}], usageErrors: [{bin, command?, unknown, count}]}")
 };
 async function stats(args, path = usagePath()) {
   const { values } = parse(args, STATS_USAGE, STATS_OPTIONS, { positionals: [], examples: ["cli stats", ["cli stats --since 7d", "the last week"]] });
@@ -1461,6 +1572,11 @@ async function stats(args, path = usagePath()) {
   console.log(`${summary.runs} runs
 
 ${table(summary.bins.map((each) => [each.bin, String(each.runs), `${each.failed} failed`, `${each.usageErrors} usage errors`]))}`);
+  const busy = summary.commands.filter((each) => each.failed + each.usageErrors > 0).toSorted((a, b) => b.failed + b.usageErrors - (a.failed + a.usageErrors)).slice(0, 15);
+  if (busy.length > 0)
+    console.log(`
+commands with failures or usage errors
+${table(busy.map((each) => [`${each.bin} ${each.command}`, String(each.runs), `${each.failed} failed`, `${each.usageErrors} usage errors`]))}`);
   if (summary.usageErrors.length > 0)
     console.log(`
 unknown options
@@ -1468,12 +1584,13 @@ ${table(summary.usageErrors.map((each) => [`${each.bin}${each.command === undefi
   return 0;
 }
 if (import.meta.main) {
-  process12.exitCode = await runCli({
+  process13.exitCode = await runCli({
     name: "cli",
     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: {
+      doctor: { summary: "checks this host's install of the bins, one line per check, the command that fixes a failing one beside it", run: async (args) => main(args) },
       list: { summary: "every bin in one line: what it does and what it is reached for instead of", run: async (args) => list(args) },
       stats: { summary: "how often each bin ran and the options usage errors did not know", run: async (args) => stats(args) },
       completions: { summary: "fish completions for every installed bin, printed or written to the folder fish reads", run: async (args) => completions(args) }

package/dist/cli.js

@@ -2,7 +2,7 @@
 // @bun
 
 // src/cli.ts
-import process12 from "process";
+import process13 from "process";
 // ../kit/src/args.ts
 import process5 from "process";
 import { parseArgs } from "util";
@@ -808,26 +808,38 @@ async function readUsage(path = usagePath(), since = 0) {
     }
   });
 }
+function tally(counts, code) {
+  counts.runs++;
+  counts.failed += code === 0 || code === 2 ? 0 : 1;
+  counts.usageErrors += code === 2 ? 1 : 0;
+}
 function summarizeUsage(entries) {
   const bins = new Map;
-  const errors = new Map;
+  const commands = new Map;
+  const unknowns = 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;
+    tally(bin, entry.code);
     bins.set(entry.bin, bin);
-    if (entry.code === 2 && entry.unknown !== undefined) {
+    if (entry.command !== undefined) {
+      const command = commands.get(`${entry.bin} ${entry.command}`) ?? { bin: entry.bin, command: entry.command, runs: 0, failed: 0, usageErrors: 0 };
+      tally(command, entry.code);
+      commands.set(`${entry.bin} ${entry.command}`, command);
+    }
+    if (entry.code !== 2)
+      continue;
+    if (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);
+      const unknown = unknowns.get(key) ?? { bin: entry.bin, ...entry.command === undefined ? {} : { command: entry.command }, unknown: entry.unknown, count: 0 };
+      unknown.count++;
+      unknowns.set(key, unknown);
     }
   }
   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)
+    commands: [...commands.values()].toSorted((a, b) => b.runs - a.runs),
+    usageErrors: [...unknowns.values()].toSorted((a, b) => b.count - a.count)
   };
 }
 
@@ -931,7 +943,7 @@ 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)
+  if (error instanceof Exit && error.code === 2)
     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);
@@ -1139,6 +1151,9 @@ var SECRET_WORDS = new Set(["key", "pass", "pwd", "auth", "salt", "cookie", "ses
 var {Glob } = globalThis.Bun;
 var SESSION_FILES = new Glob("*.json");
 var ACCOUNT_DIRS = new Glob("*/sessions");
+// src/doctor.ts
+import process12 from "process";
+
 // src/checks.ts
 import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
 import { basename, join as join4 } from "path";
@@ -1207,11 +1222,10 @@ function missingCompletions(host, dir) {
 
 // src/checks.ts
 var TOOLS = {
-  "@kaynooo/cli-audit": ["audit"],
   "@kaynooo/cli-base": ["base", "proof"],
   "@kaynooo/cli-changelog": ["changelog"],
   "@kaynooo/cli-check": ["check", "fix", "errs", "j"],
-  "@kaynooo/cli-code": ["peek", "todo-scan", "hotspots"],
+  "@kaynooo/cli-code": ["src", "peek", "todo-scan", "hotspots"],
   "@kaynooo/cli-db": ["db"],
   "@kaynooo/cli-docker": ["dc", "dlog", "dx", "sf"],
   "@kaynooo/cli-doctor": ["doctor", "cli"],
@@ -1226,12 +1240,11 @@ var TOOLS = {
   "@kaynooo/cli-pick": ["pick"],
   "@kaynooo/cli-pkg": ["pkg"],
   "@kaynooo/cli-probe": ["probe"],
-  "@kaynooo/cli-proc": ["pid", "ports", "procs"],
-  "@kaynooo/cli-repos": ["repos"],
+  "@kaynooo/cli-proc": ["proc", "pid", "ports", "procs"],
   "@kaynooo/cli-stack": ["stack"],
-  "@kaynooo/cli-sweep": ["sweep"],
   "@kaynooo/cli-view": ["view"],
-  "@kaynooo/cli-wait": ["waitfor", "slot"]
+  "@kaynooo/cli-wait": ["waitfor", "slot"],
+  "@kaynooo/cli-workspace": ["ws", "repos", "sweep", "audit"]
 };
 var FORGE = "git.kaynooo.fr";
 var FORGE_HOSTS = new Set([FORGE, "git.kevyn.fr"]);
@@ -1402,7 +1415,7 @@ function hostHere() {
   };
 }
 
-// src/cli.ts
+// src/doctor.ts
 var USAGE = `doctor [--only <check>] [--quiet] [--fix [--dry-run]] [--json]: checks this host's @kaynooo/cli-* install, one line per check, the command that fixes a failing one beside it
 
 Each @kaynooo/cli-* package installed globally with its bins on the PATH and no older than the registry's latest; tea logged in to git.kaynooo.fr and reaching it; the Claude Code hooks wired through the cli-hooks plugin or the cli mod, not both; Bun at least the version the tools ask for; fish completions for every bin.
@@ -1462,8 +1475,6 @@ after the fixes:`);
     print(shown);
   return results.every((result) => result.ok) ? 0 : 1;
 }
-if (import.meta.main)
-  process12.exitCode = await runMain({ name: "doctor", run: async (args) => main(args) });
-export {
-  main
-};
+
+// src/cli.ts
+process13.exitCode = await runMain({ name: "doctor", run: async (args) => main(args) });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kaynooo/cli-doctor",
   "type": "module",
-  "version": "0.5.2",
+  "version": "0.7.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",
@@ -33,9 +33,10 @@
   },
   "scripts": {
     "build": "$npm_execpath build src/cli.ts src/cli-bin.ts --target bun --outdir dist",
+    "cli": "$npm_execpath src/cli-bin.ts",
     "doctor": "$npm_execpath src/cli.ts"
   },
   "devDependencies": {
-    "@kaynooo/cli-kit": "0.21.0"
+    "@kaynooo/cli-kit": "0.21.1"
   }
 }