@kaynooo/guard-tools 0.3.0 → 0.4.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Kaynooo <kaynooo@kevyn.fr>
+Copyright (c) 2026 Kaynooo <contact@kaynooo.fr>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -13,7 +13,7 @@ guard check --json --cwd "$PWD" - < command.txt
 | Rule | Refuses | Lives in |
 | --- | --- | --- |
 | `remote` | `ssh`, `scp`, `sftp`, `mosh`, `rsync` to a host, `DOCKER_HOST=ssh://`, `docker -H ssh://` | `src/remote.ts` |
-| `git` | `git stash` (pointing at `base`), `git add -A`/`.`/`-u`, `git commit -a` in any flag cluster, `git push` the user did not ask for, `git push --tags` without `--atomic` | `src/git.ts` |
+| `git` | `git stash` (pointing at `proof`, `base`, a commit first or `git worktree add`), `git add -A`/`.`/`-u`, `git commit -a` in any flag cluster, `git push` the user did not ask for, `git push --tags` without `--atomic` | `src/git.ts` |
 | `commit` | a commit message breaking the format: no Conventional Commit title, a trailer, a body over two lines, a bullet list, a hard wrap; `-m`, `-F <file>` and `-F -` with a heredoc are read; the refusal spells the rule out and points at `gc` | `src/commit.ts`, the validator in `@kaynooo/git-tools` |
 | `sql` | a SQL client, console or dump tool fed a write (INSERT, UPDATE, DELETE, DDL, migrations, fixtures) outside a test database | `@kaynooo/db-tools` (`src/clients.ts`, `src/guard.ts`) |
 | `env` | a command reading, writing or printing an env file or the whole environment; `guard path` refuses a file tool opening one | `@kaynooo/env-tools` (`src/guard.ts`) |

package/dist/cli.js

@@ -298,6 +298,26 @@ function upTo(text, separator) {
 }
 var ESCAPE = String.fromCharCode(27);
 
+// ../kit/src/text.ts
+var ANSI = new RegExp(`${String.fromCharCode(27)}\\[[\\d;?]*[a-z]`, "gi");
+function distance(a, b) {
+  let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (const [i, left] of [...a].entries()) {
+    const current = [i + 1];
+    for (const [j, right] of [...b].entries())
+      current.push(Math.min((previous[j + 1] ?? 0) + 1, (current[j] ?? 0) + 1, (previous[j] ?? 0) + (left === right ? 0 : 1)));
+    previous = current;
+  }
+  return previous[b.length] ?? 0;
+}
+function closest(name, names) {
+  const started = names.find((known) => known.startsWith(name));
+  if (started !== undefined)
+    return started;
+  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/args.ts
 function jsonOption(holds) {
   return { type: "boolean", description: holds === undefined ? "print JSON" : `print JSON: ${holds}` };
@@ -317,8 +337,8 @@ function fail(message, code = 2, hint) {
 }
 
 class UsageError extends Exit {
-  constructor(message) {
-    super(message, 2);
+  constructor(message, hint) {
+    super(message, 2, hint);
   }
 }
 function badUsage(message) {
@@ -340,13 +360,35 @@ class Completing {
 var completion = { active: false };
 var OPTIONAL = /\[[^\]]+\]/g;
 var USAGE_PREFIX = /^usage:\s*/i;
+var FULL_STOP = /\.$/;
+var DASHES = /^-+/;
 function usageLine(usage, colors = paint(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 = []) {
-  return [usageLine(usage, colors), "", colors.bold("Options:"), ...optionRows(options, colors), ...exampleRows(examples, colors)].join(`
+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 [];
@@ -356,10 +398,10 @@ 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 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 };
+    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.flag}${" ".repeat(width - row.width)}  ${colors.dim(row.description)}`);
+  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" },
@@ -389,14 +431,15 @@ function parse(args, usage, options, settings = {}) {
   const rest = separator === -1 ? undefined : args.slice(separator + 1);
   let parsed;
   try {
-    parsed = parseArgs({ args: own, options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true });
+    parsed = parseArgs({ args: joinDashValues(own, all), options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true });
   } catch (error) {
-    badUsage(parseError(error));
+    const message = parseError(error);
+    throw new UsageError(message, nearestOption(message, all, settings.allowNegative === true));
   }
   const values = parsed.values;
   applyOutput("color" in output ? values.color : undefined, "plain" in output ? values.plain : undefined);
   if (values.help === true) {
-    console.log(helpText(usage, all, undefined, settings.examples));
+    console.log(wantsHelpJson() ? JSON.stringify(description(usage, settings)) : helpText(usage, all, undefined, settings));
     throw new HelpShown;
   }
   if (settings.positionals !== undefined)
@@ -411,10 +454,45 @@ function checkPositionals(given, names) {
   if (!variadic && given.length > names.length)
     badUsage(`unexpected argument ${given[names.length]}`);
 }
+function joinDashValues(args, options) {
+  const longOf = new Map(Object.entries(options).flatMap(([name, option]) => option.short === undefined ? [[`--${name}`, name]] : [[`--${name}`, name], [`-${option.short}`, name]]));
+  const isOption = (arg) => arg === "--" || longOf.has(arg.includes("=") ? arg.slice(0, arg.indexOf("=")) : arg);
+  const joined = [];
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i] ?? "";
+    if (arg === "--")
+      return [...joined, ...args.slice(i)];
+    const name = longOf.get(arg);
+    const next = args[i + 1];
+    if (name !== undefined && options[name]?.type === "string" && next !== undefined && next.startsWith("-") && next !== "-" && !isOption(next)) {
+      joined.push(`--${name}=${next}`);
+      i++;
+    } else {
+      joined.push(arg);
+    }
+  }
+  return joined;
+}
 function parseError(error) {
   const message = upTo(error instanceof Error ? error.message : String(error), ". ");
   return `${message.charAt(0).toLowerCase()}${message.slice(1)}`;
 }
+var UNKNOWN_OPTION = /^unknown option '(-[^']+)'/;
+function nearestOption(message, options, allowNegative) {
+  const typed = UNKNOWN_OPTION.exec(message)?.[1];
+  if (typed === undefined)
+    return;
+  const word = typed.replace(DASHES, "");
+  if (word.length < 2 && !typed.startsWith("--"))
+    return;
+  const known = Object.entries(options).flatMap(([name, option]) => [
+    ...option.short === undefined ? [] : [`-${option.short}`],
+    `--${name}`,
+    ...allowNegative && option.type === "boolean" ? [`--no-${name}`] : []
+  ]);
+  const meant = closest(word, known.map((flag) => flag.replace(DASHES, "")));
+  return meant === undefined ? undefined : `did you mean ${known.find((flag) => flag.replace(DASHES, "") === meant)}?`;
+}
 async function readInput(path, { noStdin = "nothing is piped on stdin" } = {}) {
   if (path === "-") {
     if (process3.stdin.isTTY)
@@ -428,33 +506,19 @@ async function readInput(path, { noStdin = "nothing is piped on stdin" } = {}) {
 }
 // ../kit/src/cli.ts
 import process4 from "process";
-
-// ../kit/src/text.ts
-var ANSI = new RegExp(`${String.fromCharCode(27)}\\[[\\d;?]*[a-z]`, "gi");
-function distance(a, b) {
-  let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
-  for (const [i, left] of [...a].entries()) {
-    const current = [i + 1];
-    for (const [j, right] of [...b].entries())
-      current.push(Math.min((previous[j + 1] ?? 0) + 1, (current[j] ?? 0) + 1, (previous[j] ?? 0) + (left === right ? 0 : 1)));
-    previous = current;
-  }
-  return previous[b.length] ?? 0;
-}
-
-// ../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" } };
-function commandRows(commands, colors) {
+async function commandRows(commands, colors) {
   const width = Math.max(...Object.keys(commands).map((name) => name.length));
   const groups = new Map([["Commands:", []]]);
-  for (const [name, { summary, group }] of Object.entries(commands)) {
+  const summaries = await Promise.all(Object.values(commands).map(async ({ summary }) => resolveSummary(summary)));
+  for (const [index, [name, { group }]] of Object.entries(commands).entries()) {
     const heading = group === undefined ? "Commands:" : `${group}:`;
     const rows = groups.get(heading) ?? [];
-    rows.push(`  ${colors.cyan(name.padEnd(width))}  ${colors.dim(summary)}`);
+    rows.push(`  ${colors.cyan(name.padEnd(width))}  ${colors.dim(summaries[index])}`);
     groups.set(heading, rows);
   }
   return [...groups].filter(([, rows]) => rows.length > 0).flatMap(([heading, rows], index) => [...index === 0 ? [] : [""], colors.bold(heading), ...rows]);
@@ -474,25 +538,38 @@ function takeOutputFlags(argv) {
   }
   return argv.slice(index);
 }
-function closest(name, names) {
-  const started = names.find((known) => known.startsWith(name));
-  if (started !== undefined)
-    return started;
-  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;
+async function resolveSummary(summary) {
+  return typeof summary === "string" ? summary : summary();
+}
+function scopeOf(commands, extra, aliases) {
+  return { commands: typeof commands === "function" ? {} : commands, lazy: [...typeof commands === "function" ? [commands] : [], ...extra === undefined ? [] : [extra]], aliases };
 }
-async function help({ path, header, commands, defaultCommand, examples }, stream) {
+async function expand(scope, words) {
+  if (scope.lazy.length === 0)
+    return scope;
+  const commands = { ...scope.commands };
+  for (const added of await Promise.all(scope.lazy.map(async (lazy) => lazy(words)))) {
+    for (const [name, command] of Object.entries(added))
+      commands[name] ??= command;
+  }
+  return { ...scope, commands, lazy: [] };
+}
+async function help({ path, header, summary: lazySummary, commands, defaultCommand, examples, replaces }, stream) {
   const colors = paint(stream);
   const prefix = path.join(" ");
+  const summary = await resolveSummary(lazySummary);
+  if (wantsHelpJson())
+    return JSON.stringify(description(`${prefix} <command> [options]: ${summary}`, { examples, replaces }));
   const fallback = defaultCommand === undefined ? undefined : commands[defaultCommand];
   const options = fallback !== undefined && "run" in fallback ? await optionsOf(fallback.run) : undefined;
   const own = Object.entries(options ?? {}).filter(([name]) => !(name in TOP_OPTIONS));
   return [
-    header(colors),
+    header(colors, summary),
     "",
     usageLine(`${prefix} ${defaultCommand === undefined ? colors.cyan("<command>") : `[${colors.cyan("<command>")}]`} [options]`, colors),
+    ...replacesRows(replaces, colors),
     "",
-    ...commandRows(commands, colors),
+    ...await commandRows(commands, colors),
     ...own.length === 0 ? [] : ["", `${colors.bold(`Options of ${defaultCommand}:`)} ${colors.dim("the command run when none is named")}`, ...optionRows(Object.fromEntries(own), colors)],
     "",
     colors.bold("Options:"),
@@ -511,13 +588,21 @@ function printError(prefix, message, hint, cause) {
   ${styled ? tint(label) : `${label}:`} ${text}`;
   console.error(`${head} ${message}${under("cause", cause, colors.dim)}${under("hint", hint, colors.yellow)}`);
 }
-function reportThrown(prefix, error, redact = (text) => text) {
+function printJsonError(message, hint, cause) {
+  console.error(JSON.stringify({ error: message, ...hint === undefined ? {} : { hint }, ...cause === undefined ? {} : { cause } }));
+}
+function wantsJson(argv) {
+  const end = argv.indexOf("--");
+  return (end === -1 ? argv : argv.slice(0, end)).includes("--json");
+}
+function reportThrown(prefix, error, redact = (text) => text, json = false) {
   if (error instanceof HelpShown)
     return 0;
   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;
-  printError(prefix, redact(named ?? (error instanceof Error ? error.message : String(error))), error instanceof Exit ? error.hint ?? help : undefined, cause);
+  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;
 }
 async function dispatch(level, typed, { version, redact }) {
@@ -530,11 +615,11 @@ async function dispatch(level, typed, { version, redact }) {
   }
   const [name, ...args] = argv;
   if (name === undefined && level.path.length > 1) {
-    console.error(await help(level, process4.stderr));
+    console.error(await help(await expand(level, [...level.path.slice(1), ...argv]), process4.stderr));
     return 2;
   }
   if (name === undefined || name === "help" || name === "--help" || name === "-h") {
-    console.log(await help(level, process4.stdout));
+    console.log(await help(await expand(level, [...level.path.slice(1), ...argv]), process4.stdout));
     return 0;
   }
   if (level.path.length === 1 && (name === "--version" || name === "-v")) {
@@ -543,6 +628,10 @@ async function dispatch(level, typed, { version, redact }) {
   }
   let command = level.commands[level.aliases?.[name] ?? name];
   let rest = args;
+  if (command === undefined && level.lazy.length > 0) {
+    level = await expand(level, [...level.path.slice(1), ...argv]);
+    command = level.commands[level.aliases?.[name] ?? name];
+  }
   if (command === undefined && level.defaultCommand !== undefined) {
     command = level.commands[level.defaultCommand];
     rest = argv;
@@ -554,12 +643,12 @@ async function dispatch(level, typed, { version, redact }) {
   }
   if ("commands" in command) {
     const { summary } = command;
-    return dispatch({ path: [...level.path, name], header: (colors) => `${colors.bold(`${prefix} ${name}`)}  ${summary}`, commands: command.commands, aliases: command.aliases, defaultCommand: undefined, examples: command.examples }, 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, examples: command.examples, replaces: undefined }, rest, { version, redact });
   }
   try {
     return await command.run(rest);
   } catch (error) {
-    return reportThrown(`${prefix} ${name}`, error, redact);
+    return reportThrown(`${prefix} ${name}`, error, redact, wantsJson(rest));
   }
 }
 var COMPLETE = "__complete";
@@ -579,18 +668,24 @@ async function optionsOf(run) {
 async function leafCandidates(run, words) {
   if (!(words.at(-1) ?? "").startsWith("-"))
     return [FILES];
-  return Object.entries(await optionsOf(run)).map(([name, option]) => `--${name}	${option.description}`);
+  return Object.entries(await optionsOf(run)).map(([name, option]) => option.description === undefined ? `--${name}` : `--${name}	${option.description}`);
 }
-async function candidates(commands, aliases, defaultCommand, words) {
+async function candidates(scope, defaultCommand, words, before = []) {
   const [word = "", ...rest] = words;
-  const command = commands[aliases?.[word] ?? word];
-  if (rest.length === 0 && !word.startsWith("-"))
-    return Object.entries(commands).map(([name, { summary }]) => `${name}	${summary}`);
+  const listing = rest.length === 0 && !word.startsWith("-");
+  let { commands, aliases } = scope;
+  let command = commands[aliases?.[word] ?? word];
+  if (listing || command === undefined) {
+    ({ 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 (command === undefined) {
     const fallback = defaultCommand === undefined ? undefined : commands[defaultCommand];
     return fallback !== undefined && "run" in fallback ? leafCandidates(fallback.run, words) : [];
   }
-  return "commands" in command ? candidates(command.commands, command.aliases, undefined, rest) : leafCandidates(command.run, rest);
+  return "commands" in command ? candidates(scopeOf(command.commands, command.extraCommands, command.aliases), undefined, rest, [...before, word]) : leafCandidates(command.run, rest);
 }
 async function printCandidates(found) {
   for (const line of await found)
@@ -599,8 +694,8 @@ async function printCandidates(found) {
 }
 async function runCli(cli, argv = process4.argv.slice(2)) {
   if (argv[0] === COMPLETE)
-    return printCandidates(candidates(cli.commands, cli.aliases, cli.defaultCommand, argv.slice(1)));
-  return dispatch({ path: [cli.name], header: (colors) => `${colors.bold(cli.name)} ${colors.dim(cli.version)}  ${cli.about}`, commands: cli.commands, aliases: cli.aliases, defaultCommand: cli.defaultCommand, examples: cli.examples }, argv, { version: cli.version, redact: cli.redact });
+    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 });
 }
 // ../kit/src/process.ts
 import { constants } from "os";
@@ -624,7 +719,7 @@ async function runCommand(argv, { cwd, env, stdin = "ignore" } = {}) {
   return { code: exitCodeOf(proc.exitCode, proc.signalCode), chunks, output, text: output.toString() };
 }
 // package.json
-var version = "0.3.0";
+var version = "0.4.1";
 
 // ../kit/src/shell.ts
 var SEPARATORS = new Set([`
@@ -1120,7 +1215,7 @@ var EXEC_VALUE_OPTIONS = new Set(["-e", "--env", "--env-file", "-u", "--user", "
 var CONFIG_LISTS = new Set(["--services", "--volumes", "--profiles", "--images", "--networks", "--hash", "-q", "--quiet"]);
 var FORMAT_OPTIONS = new Set(["-f", "--format"]);
 var WHOLE_FORMAT = /Env|\{\{\s*json\s+\.\s*\}\}|^json$/;
-var USE_EV = '.env files hold secrets that must never reach the transcript, so they are not read, edited or printed directly. Use `ev` instead: `ev list`, `ev get KEY` (masked), `ev grep <regex>` for the keys matching it, `ev show <rev>:<file>` for one at a git revision, `printf %s "$value" | ev set KEY [file]` (`--empty` for an empty value), `ev unset KEY`, `ev mv KEY --from .env --to .env.local`, `ev diff a b`, `ev missing`; and pipe output that may carry a secret through `redact`, as `docker compose exec <svc> printenv | redact` or `docker compose config | redact`. If `ev` is missing: `bun install -g @kaynooo/env-tools`.';
+var USE_EV = '.env files hold secrets that must never reach the transcript, so they are not read, edited or printed directly. Use `ev` instead: `ev list`, `ev get KEY` (masked), `ev grep <regex>` for the keys matching it, `ev show <rev>:<file>` for one at a git revision, `printf %s "$value" | ev set KEY [file]` (`--empty` for an empty value), `ev unset KEY`, `ev cp KEY --from .env --to .env.local`, `ev mv KEY --from .env --to .env.local`, `ev diff a b`, `ev missing`; and pipe output that may carry a secret through `redact`, as `docker compose exec <svc> printenv | redact` or `docker compose config | redact`. If `ev` is missing: `bun install -g @kaynooo/env-tools`.';
 function isEnvFile(path) {
   const name = path.slice(Math.max(path.lastIndexOf("/"), path.lastIndexOf(":")) + 1);
   return (ENV_FILE.test(name) || name === ".env*") && !TEMPLATE.test(name);
@@ -1523,7 +1618,7 @@ var SHORT_CLUSTER = /^-[A-Z]+$/i;
 var STAGES_ALL = /[Au]/;
 var ALL_TAGS = new Set(["--tags", "--follow-tags"]);
 var STAGE_BY_PATH = `Stage by path: the tree carries unrelated work and peer sessions edit it live. ${USE_GC}`;
-var STASH = "Never `git stash`: a pop with nothing saved applies someone else's old stash. To see how a test behaves without your change, run it at HEAD with `base -- <cmd>` (a temporary worktree, the working tree untouched), `--keep <path>` to carry the new test over, `--ref <rev>` for another commit.";
+var STASH = "Never `git stash`: a pop with nothing saved applies someone else's old stash. To prove a test fails without your change, `proof --keep <test> -- <cmd>` runs it at HEAD in a temporary worktree and again here; `base -- <cmd>` runs any command at HEAD (`--ref <rev>` another commit), the working tree untouched. To set edits aside before a cherry-pick, a rebase or a checkout, commit them with `gc` first, or do the other work in `git worktree add`.";
 var ADD_ALL = `\`git add\` over the whole tree is refused. ${STAGE_BY_PATH}`;
 var COMMIT_ALL = `\`git commit -a\` stages the whole tree and is refused. ${STAGE_BY_PATH}`;
 var PUSH = "`git push` runs only when the user asked for a push in their latest prompt: say the commit is ready and let them ask.";
@@ -2092,18 +2187,25 @@ function checkPath(path) {
 var BINS = {
   check: "`check`: runs the repo's check, typecheck, lint and test steps and prints only what failed, each full log saved to a file; validate a change with it rather than chaining the scripts (`--only lint,test`, `--list`).",
   fix: "`fix`: runs the repo's fixers and formatters (its fix, lint:fix and format scripts, just fmt, go fmt, cargo fmt, ruff) and lists the files they changed.",
+  errs: "`errs [log]`, `errs -- <cmd>`: turns tsc, tsgo, eslint, bun check and bun test output into one `file:line:col: message (rule)` line per error, counting the lines it did not recognise (`--json`); use it instead of reading raw type, lint or test logs.",
   db: '`db "<sql>"`: one read-only statement against the Postgres in DATABASE_URL (`-e KEY` for another) or, without one, the compose project\'s running Postgres service (`-s <service>`, `-d <database>`), credentials never shown, a write printed for the user to run; `db tables`, `db describe <table>`, `db dbs`.',
   ev: "`ev`: .env files read and edited with values masked (`ev list`, `ev get KEY`, `ev grep <regex>`, `ev show <rev>:<file>`, `ev set`, `ev diff`, `ev missing`); `ev audit [dir]` finds env files others can read or git tracks, and compose files writing secrets out.",
   redact: "`redact`: masks secrets in piped output, `<cmd> | redact`.",
   pkg: "`pkg <name>[@version]`: checks an npm package before it is added: whether the name exists or is a near miss of a popular one, the newest version at least two weeks old, licence, install scripts; `bun add`, `npm install`, `pnpm add` and `yarn add` run it first and are refused on what it flags. `pkg bump <@scope/lib> [version]` waits until the registry serves a release, then `bun add --exact`s it in every consumer under ~/Workspace (`--dry-run`), `pkg consumers <name>` lists them; use it instead of a `bun info` and sleep loop and a `bun add` per repo.",
   stack: "`stack port <name>`: the port a service name always hashes to, for every host port a compose file publishes; `stack audit [dir]` cross-checks release.config.ts against its compose files.",
-  ft: "`ft`: Forgejo CI runs, logs and waits, releases, issue checklists and claims, in a repo whose origin is on Forgejo.",
+  ft: "`ft`: Forgejo CI runs, logs and waits, releases, issue checklists and claims, milestones (`ft milestones`, `ft milestone <m>`, `ft new -m`), in a repo whose origin is on Forgejo.",
   sub: "`sub --from <text> --to <text> <file>...`: replaces text, writing nothing unless each match count is as expected (1, `-n N`, `--all`), `--regex`, `--pairs <json|->` for several in order, `--dry-run --diff`; use it instead of sed -i, a bun -e or python editor.",
   base: "`base [--ref <rev>] [--keep <path>...] -- <cmd>`: runs a command at HEAD (or a ref) in a temporary worktree, removed afterwards, ignored env files and node_modules/vendor linked; use it instead of git stash to see whether a test fails without your change (`--keep` the new test).",
+  proof: "`proof [--ref <rev>] [--keep <path>...] -- <cmd>`: runs the command at HEAD (or a ref) in a temporary worktree, then in the working tree, and exits 0 only when it fails before and passes now, printing the failing side's output; use it to prove a new test fails without your change (`--keep` the test).",
   gst: "`gst [--log N]`: branch, upstream, changed counts and HEAD in one line, then the changed paths by staged, unstaged and untracked; use it instead of `git status --short` and `git log --oneline`.",
   gc: "`gc <title> [-m <line>]... [--ticket <line>]... -- <path>...`: commits exactly those paths, refusing with nothing staged when the message breaks a commit rule, a path has no change or other files are already staged; use it instead of chaining git add, status and commit.",
   waitfor: "`waitfor --file <log> --until <regex> [--fail <regex>]`, `--port <n>`, `--url <url>`, `--pid <n>` (`-t 5m`): waits until the line shows, the port listens, the URL answers 2xx or the process exits, exits 1 on a --fail line with the lines around it, 2 on a timeout with the last lines; `waitfor task <id>` waits for a background Bash task and prints its exit code, last lines and failure lines; use it instead of sleep and tail, `until ! pgrep -f` or polling loops.",
   gl: "`gl ci [ref]` waits for the GitLab pipeline covering a commit and prints each failed job's tests (exit 0/1/2), `gl runs`, `gl logs <pipeline> [-j job] [--full]`; use it instead of `glab ci` or `glab api .../pipelines/<id>/jobs` polled in a sleep loop.",
+  peek: "`peek <file:from-to>...` prints several spans with line numbers in one call, `peek --def <symbol>` a whole declaration, `--refs <symbol>` its usages by file, `--outline <file>` the declarations and members, `--around <regex> -C 3` the lines around matches; use it instead of `sed -n N,Mp`, `grep -n` chains and whole-file reads.",
+  "todo-scan": "`todo-scan [path...]` lists the TODO, FIXME and owner/repo#N comments as `<file>:<line>: <comment>`, `--stale` only those whose issue is closed (exit 1), through ft; use it to find the workarounds a shipped fix lets you drop.",
+  doctor: "`doctor`: checks this host's agent-tools install, one line per check with its fix: each bin's version against the registry, tea's login, the Claude Code hooks, the Bun floor (`--json`); run it when a bin lacks a command or a flag its docs name.",
+  "agent-tools": "`agent-tools list`: every agent-tools bin in one line, what it does and what it is reached for instead of, read from each bin's own --help (`--json` adds the synopsis and examples); run it to find the bin that fits a task.",
+  hotspots: "`hotspots [dir] [--since <date>] [-n 20]`: ranks the source files by complexity times git churn (commits touching each in the window, 6 months by default), tests and generated files left out, `--json`; use it to pick which complex files are worth splitting first.",
   out: "`out -- <cmd>`: folds long output, keeping the errors and saving the full log; run noisy builds, installs, tests and linters through it."
 };
 function binsSection(installed) {
@@ -2180,7 +2282,9 @@ var checkUsage = `guard check [options] [<command> | -]
 
 Checks a shell command against the rules: remote machines, git (stash, whole-tree add and commit, push, tags), commit messages, SQL writes, env files, package managers and in-place edits (sed -i and replace scripts, pointed at sub).
 Prints each broken rule with the route to take instead and exits 1, prints nothing and exits 0 when the command is clean.
-The command is read from stdin with - or when none is given; a rule may rewrite it instead (the pinned package manager, a noisy run through out), printed as \`runs as: <command>\`.`;
+The command is read from stdin with - or when none is given; a rule may rewrite it instead (the pinned package manager, a noisy run through out), printed as \`runs as: <command>\`.
+
+Exits 0 when the command is clean, 1 when a rule is broken, 2 on a usage error.`;
 var checkOptions = {
   json: jsonOption("{violations, command, notes, packages} for a hook"),
   cwd: { type: "string", description: "the directory the command runs in (default: here)" },
@@ -2189,7 +2293,9 @@ var checkOptions = {
 };
 var pathUsage = `guard path [--json] <path>...
 
-Checks the paths a file tool would read, edit or write: env files are refused.`;
+Checks the paths a file tool would read, edit or write: env files are refused.
+
+Exits 0 when every path is clean, 1 when one is refused, 2 on a usage error.`;
 var pathOptions = {
   json: jsonOption("{violations} for a hook")
 };
@@ -2197,7 +2303,9 @@ var hookUsage = `guard hook <${EVENTS.join("|")}>
 
 Answers a Claude Code hook: reads the event JSON on stdin and prints the reply JSON, nothing when the call goes ahead untouched.
 pre-tool-use refuses a Bash call breaking a rule, an install pkg refuses, and a Read, Edit or Write of an env file; user-prompt-submit remembers whether the prompt asked for a push; session-start lists the installed agent-tools bins.
-A failure exits 1, which Claude Code reports without blocking the call.`;
+A failure exits 1, which Claude Code reports without blocking the call.
+
+Exits 0 when it answered, 1 on a failure or an unknown event (never 2, which would block the call).`;
 function readText(path) {
   try {
     return readFileSync(path, "utf8");
@@ -2283,6 +2391,8 @@ process6.exitCode = await runCli({
   name: "guard",
   version,
   about: "the safety rules a Claude Code Bash call is held to, each refusal naming the route",
+  replaces: "a hook script per rule, each wording its own refusal",
+  examples: [['guard check "git push --force"', "the rules a command breaks, with their routes"], ["guard path .env", "whether a file tool may open a path"]],
   commands: {
     check: { run: check, summary: "check a shell command, printing each broken rule with its route" },
     path: { run: async (args) => Promise.resolve(path(args)), summary: "check a path a file tool would open" },

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@kaynooo/guard-tools",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "guard: the safety rules a Claude Code Bash call is held to (git, remote machines, SQL writes, env files, package managers, commit messages), each refusal naming the route.",
-  "author": "Kaynooo <kaynooo@kevyn.fr>",
+  "author": "Kaynooo <contact@kaynooo.fr>",
   "license": "MIT",
-  "homepage": "https://git.kevyn.fr/kaynooo/agent-tools/src/branch/main/packages/guard#readme",
+  "homepage": "https://git.kaynooo.fr/kaynooo/agent-tools/src/branch/main/packages/guard#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://git.kevyn.fr/kaynooo/agent-tools.git",
+    "url": "git+https://git.kaynooo.fr/kaynooo/agent-tools.git",
     "directory": "packages/guard"
   },
-  "bugs": "https://git.kevyn.fr/kaynooo/agent-tools/issues",
+  "bugs": "https://git.kaynooo.fr/kaynooo/agent-tools/issues",
   "keywords": [
     "claude-code",
     "cli",
@@ -29,7 +29,7 @@
     "bun": ">=1.4.3"
   },
   "publishConfig": {
-    "registry": "https://git.kevyn.fr/api/packages/kaynooo/npm/"
+    "registry": "https://git.kaynooo.fr/api/packages/kaynooo/npm/"
   },
   "scripts": {
     "build": "$npm_execpath build src/cli.ts --target bun --outdir dist",