@kaynooo/guard-tools 0.3.0 → 0.4.0

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

@@ -340,13 +340,34 @@ class Completing {
 var completion = { active: false };
 var OPTIONAL = /\[[^\]]+\]/g;
 var USAGE_PREFIX = /^usage:\s*/i;
+var FULL_STOP = /\.$/;
 function usageLine(usage, colors = paint(process3.stdout)) {
   return `${colors.bold("Usage:")} ${usage.replace(USAGE_PREFIX, "").replaceAll(OPTIONAL, (part) => colors.dim(part))}`;
 }
-function helpText(usage, options, colors = paint(process3.stdout), examples = []) {
-  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 [];
@@ -389,14 +410,14 @@ 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 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,6 +432,25 @@ 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)}`;
@@ -481,9 +521,11 @@ function closest(name, names) {
   const [best] = names.map((known) => ({ known, far: distance(name, known) })).sort((a, b) => a.far - b.far);
   return best !== undefined && best.far <= (name.length < 4 ? 1 : 2) ? best.known : undefined;
 }
-async function help({ path, header, commands, defaultCommand, examples }, stream) {
+async function help({ path, header, summary, commands, defaultCommand, examples, replaces }, stream) {
   const colors = paint(stream);
   const prefix = path.join(" ");
+  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));
@@ -491,6 +533,7 @@ async function help({ path, header, commands, defaultCommand, examples }, stream
     header(colors),
     "",
     usageLine(`${prefix} ${defaultCommand === undefined ? colors.cyan("<command>") : `[${colors.cyan("<command>")}]`} [options]`, colors),
+    ...replacesRows(replaces, colors),
     "",
     ...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)],
@@ -511,13 +554,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 }) {
@@ -554,12 +605,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) => `${colors.bold(`${prefix} ${name}`)}  ${summary}`, summary, commands: command.commands, aliases: 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";
@@ -600,7 +651,7 @@ 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 dispatch({ path: [cli.name], header: (colors) => `${colors.bold(cli.name)} ${colors.dim(cli.version)}  ${cli.about}`, summary: cli.about, commands: cli.commands, aliases: 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 +675,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.0";
 
 // ../kit/src/shell.ts
 var SEPARATORS = new Set([`
@@ -1523,7 +1574,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 +2143,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 +2238,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 +2249,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 +2259,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 +2347,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.0",
   "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",