@kaynooo/cli-guard 0.13.0 → 0.14.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +2 -2
  2. package/dist/cli.js +103 -18
  3. package/package.json +11 -11
package/README.md CHANGED
@@ -13,8 +13,8 @@ guard check --json --cwd "$PWD" - < command.txt
13
13
  | Rule | Refuses | Lives in |
14
14
  | --- | --- | --- |
15
15
  | `remote` | `ssh`, `scp`, `sftp`, `mosh`, `rsync` to a host, `DOCKER_HOST=ssh://`, `docker -H ssh://` | `src/remote.ts` |
16
- | `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` |
17
- | `destructive` | `git reset --hard`, discarding the whole tree (`checkout -- .`, `checkout -f`, `restore .`, `switch -f`), `git clean -f`, a force push (`--force`, `-f`, `--mirror`, `+refspec`; `--force-with-lease` passes), `git branch -D`, a `git rebase` (`--continue` and `--abort` pass), `filter-branch`, `rm -r` on `/`, `~`, `$HOME`, `.`, `..`, `*` or a top-level directory, a download piped into a shell (`curl ... \| sh`, `bash <(curl ...)`); each refusal names the safe route: a commit with `gc` first, `base`, `git worktree add`, `--force-with-lease` | `src/destructive.ts` |
16
+ | `git` | `git stash` (pointing at `base 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` |
17
+ | `destructive` | `git reset --hard`, discarding the whole tree (`checkout -- .`, `checkout -f`, `restore .`, `switch -f`), `git clean -f`, a force push (`--force`, `-f`, `--mirror`, `+refspec`; `--force-with-lease` passes), `git branch -D`, a `git rebase` (`--continue` and `--abort` pass), `filter-branch`, `rm -r` on `/`, `~`, `$HOME`, `.`, `..`, `*` or a top-level directory, a download piped into a shell (`curl ... \| sh`, `bash <(curl ...)`), `dl --exec --yes` on a script no `--sha256` or `--sums` pins; each refusal names the safe route: a commit with `gc` first, `base`, `git worktree add`, `--force-with-lease`, `dl <url>` then `dl <url> --exec --sha256 <sha>` | `src/destructive.ts` |
18
18
  | `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/cli-git` |
19
19
  | `sql` | a SQL client, console or dump tool fed a write (INSERT, UPDATE, DELETE, DDL, migrations, fixtures) outside a test database | `@kaynooo/cli-db` (`src/clients.ts`, `src/guard.ts`) |
20
20
  | `env` | a command reading, writing or printing an env file or the whole environment; `guard path` refuses a file tool opening one | `@kaynooo/cli-env` (`src/guard.ts`) |
package/dist/cli.js CHANGED
@@ -509,7 +509,7 @@ class Completing {
509
509
  }
510
510
  var completion = { active: false };
511
511
  var OUTPUT_OPTIONS = {
512
- color: { type: "string", description: "auto (on a terminal alone), always or never" },
512
+ color: { type: "string", choices: ["auto", "always", "never"], description: "auto (the default) colours on a terminal alone" },
513
513
  plain: { type: "boolean", description: "plain text, no colour or spinner: --color never" }
514
514
  };
515
515
  function applyOutput(color, plain, env = process9.env) {
@@ -805,6 +805,66 @@ import { readFileSync as readFileSync4, realpathSync as realpathSync2 } from "fs
805
805
  import { dirname as dirname3, join as join5 } from "path";
806
806
  import process14 from "process";
807
807
 
808
+ // ../kit/src/completions.ts
809
+ var COMPLETION_SHELLS = ["fish", "bash", "zsh"];
810
+ var FISH_FUNCTION = `functions -q __kaynooo_cli_complete; or function __kaynooo_cli_complete --argument-names bin --description 'what a @kaynooo/cli-kit bin offers for the word being typed'
811
+ set -l tokens (commandline -xpc 2>/dev/null; or commandline -opc)
812
+ set -l current (commandline -ct)
813
+ for line in ($bin __complete $tokens[2..-1] $current 2>/dev/null)
814
+ if test "$line" = __files__
815
+ __fish_complete_path $current
816
+ else
817
+ echo $line
818
+ end
819
+ end
820
+ end`;
821
+ var BASH_FUNCTION = `__kaynooo_cli_complete() {
822
+ local IFS=$'\\n' cur=\${COMP_WORDS[COMP_CWORD]} line words=
823
+ local -a lines
824
+ COMPREPLY=()
825
+ lines=($("\${COMP_WORDS[0]}" __complete "\${COMP_WORDS[@]:1:COMP_CWORD}" 2>/dev/null))
826
+ for line in "\${lines[@]}"; do
827
+ if [[ $line == __files__ ]]; then
828
+ COMPREPLY+=($(compgen -f -- "$cur"))
829
+ else
830
+ words+="\${line%%$'\\t'*}"$'\\n'
831
+ fi
832
+ done
833
+ COMPREPLY+=($(compgen -W "$words" -- "$cur"))
834
+ }`;
835
+ var ZSH_FUNCTION = `__kaynooo_cli_complete() {
836
+ local line
837
+ local -a described plain
838
+ for line in \${(f)"$("\${words[1]}" __complete "\${(@)words[2,CURRENT]}" 2>/dev/null)"}; do
839
+ if [[ $line == __files__ ]]; then
840
+ _files
841
+ elif [[ $line == *$'\\t'* ]]; then
842
+ described+=("\${\${line%%$'\\t'*}//:/\\\\:}:\${line#*$'\\t'}")
843
+ else
844
+ plain+=("$line")
845
+ fi
846
+ done
847
+ (( \${#described} )) && _describe -V value described
848
+ (( \${#plain} )) && compadd -- "\${plain[@]}"
849
+ return 0
850
+ }`;
851
+ function completionScript(shell, bins, header = `# Generated by \`${bins[0]} --completions ${shell}\``) {
852
+ if (shell === "fish")
853
+ return `${header}
854
+ ${FISH_FUNCTION}
855
+ ${bins.map((bin) => `complete -c ${bin} -f -a '(__kaynooo_cli_complete ${bin})'
856
+ `).join("")}`;
857
+ if (shell === "bash")
858
+ return `${header}
859
+ ${BASH_FUNCTION}
860
+ complete -F __kaynooo_cli_complete ${bins.join(" ")}
861
+ `;
862
+ return `${header}
863
+ ${ZSH_FUNCTION}
864
+ compdef __kaynooo_cli_complete ${bins.join(" ")}
865
+ `;
866
+ }
867
+
808
868
  // ../kit/src/notify.ts
809
869
  import process12 from "process";
810
870
  var NOTIFY_AFTER_MS = 1e4;
@@ -878,7 +938,11 @@ var LEVEL_OPTIONS = {
878
938
  ...OUTPUT_OPTIONS,
879
939
  help: { type: "boolean", short: "h", description: "show this help" }
880
940
  };
881
- var TOP_OPTIONS = { ...LEVEL_OPTIONS, version: { type: "boolean", short: "v", description: "print the version" } };
941
+ var TOP_OPTIONS = {
942
+ ...LEVEL_OPTIONS,
943
+ version: { type: "boolean", short: "v", description: "print the version" },
944
+ completions: { type: "string", choices: COMPLETION_SHELLS, description: "print the shell completion script" }
945
+ };
882
946
  async function commandRows(all, colors) {
883
947
  const commands = shown(all);
884
948
  const width = Math.max(0, ...Object.keys(commands).map((name) => name.length));
@@ -1111,6 +1175,19 @@ async function candidates(scope, defaultCommand, words, before = []) {
1111
1175
  }
1112
1176
  return "commands" in command ? candidates(scopeOf(command.commands, command.extraCommands, command.aliases), undefined, rest, [...before, word]) : leafCandidates(command.run, rest);
1113
1177
  }
1178
+ var COMPLETIONS = "--completions";
1179
+ function flagValue([flag = "", ...rest]) {
1180
+ return flag.includes("=") ? [flag.slice(flag.indexOf("=") + 1), ...rest] : rest;
1181
+ }
1182
+ function printCompletionScript(name, args) {
1183
+ const shell = COMPLETION_SHELLS.find((each) => each === args[0]);
1184
+ if (shell === undefined || args.length !== 1) {
1185
+ printError(name, `${COMPLETIONS} takes one of ${COMPLETION_SHELLS.join(", ")}`, `${name} ${COMPLETIONS} fish`);
1186
+ return 2;
1187
+ }
1188
+ console.log(completionScript(shell, [name]).trimEnd());
1189
+ return 0;
1190
+ }
1114
1191
  async function printCandidates(found) {
1115
1192
  for (const line of await found)
1116
1193
  console.log(line);
@@ -1135,6 +1212,8 @@ async function runCli(cli, argv = scriptArgs()) {
1135
1212
  const version = cli.version ?? packageVersion();
1136
1213
  if (argv[0] === COMPLETE)
1137
1214
  return printCandidates(candidates(scopeOf(cli.commands, cli.extraCommands, cli.aliases), cli.defaultCommand, argv.slice(1)));
1215
+ if (argv[0] === COMPLETIONS || argv[0]?.startsWith(`${COMPLETIONS}=`) === true)
1216
+ return printCompletionScript(cli.name, flagValue(argv));
1138
1217
  const started = performance.now();
1139
1218
  const code = await dispatch({ path: [cli.name], header: (colors, about) => `${colors.bold(cli.name)} ${colors.dim(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, redact: cli.redact });
1140
1219
  const command = commandPath(scopeOf(cli.commands, cli.extraCommands, cli.aliases), argv);
@@ -2467,7 +2546,7 @@ var INTERPRETERS = new Set(["bun", "deno", "node", "python", "python3", "ruby",
2467
2546
  var CODE_OPTIONS = new Set(["-e", "-c", "-p", "-E", "-pe", "-r", "--eval", "--print", "--command"]);
2468
2547
  var CAN_REACH_FILES = /read|write|open|exec|spawn|system|popen|import|require|eval|load|fetch|glob|stream|source|getline|constructor|file(?!s\b)|\bcat\b|\b(?:Bun|Deno|fs|os|io|sh|bash|process|globalThis|window|Function|qx)\b|\$\s*[`({]|`/i;
2469
2548
  var DECLARERS = new Set(["export", "declare", "local", "readonly", "typeset"]);
2470
- var HARMLESS = new Set(["ev", "redact", "ls", "stat", "test", "[", "[[", "touch"]);
2549
+ var HARMLESS = new Set(["ev", "ls", "stat", "test", "[", "[[", "touch"]);
2471
2550
  var GIT_HARMLESS = new Set(["check-ignore", "ls-files", "status"]);
2472
2551
  function variablesOf(command) {
2473
2552
  const variables = new Map;
@@ -2528,7 +2607,7 @@ function namesEnv(piece, variables) {
2528
2607
  }
2529
2608
 
2530
2609
  // ../env/src/guard-pipes.ts
2531
- var XARGS_SAFE = new Set(["ls", "stat", "wc", "test", "[", "touch", "echo", "printf", "basename", "dirname", "ev", "redact", ""]);
2610
+ var XARGS_SAFE = new Set(["ls", "stat", "wc", "test", "[", "touch", "echo", "printf", "basename", "dirname", "ev", ""]);
2532
2611
  var PARALLEL_VALUE_OPTIONS = new Set(["-j", "--jobs", "-P", "--max-procs", "-S", "--sshlogin", "-C", "--colsep", "-n", "--max-args", "-N", "-d", "--delimiter", "-E", "-I", "--timeout", "--delay", "--joblog", "--results", "--tmpdir", "-a", "--arg-file", "--halt", "--retries", "--tag-string"]);
2533
2612
  var IDENTIFIER = /^[A-Z_]\w*$/i;
2534
2613
  var READ_VALUE_OPTIONS = new Set(["-a", "-d", "-i", "-n", "-N", "-p", "-t", "-u"]);
@@ -2575,7 +2654,7 @@ function loopReadsListedEnv(pieces, index, variables) {
2575
2654
 
2576
2655
  // ../env/src/guard.ts
2577
2656
  var ENV_DUMP = /(?:console\.\w+|JSON\.stringify|Object\.(?:entries|keys|values)|print)\(\s*process\.env\s*[,)]/;
2578
- 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/cli-env`.';
2657
+ 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 `ev redact`, as `docker compose exec <svc> printenv | ev redact` or `docker compose config | ev redact`. If `ev` is missing: `bun install -g @kaynooo/cli-env`.';
2579
2658
  var USE_EV_SEARCH = "To search them, `ev grep <regex>` prints the matching keys, masked. `grep -l`, `-L` and `-c` (file names and counts) are allowed, and a tree-wide search can run as `rg <regex>`, which skips gitignored files, or `grep -r --exclude='.env*' <regex> .`.";
2580
2659
  function touchingPieces(command, options = {}) {
2581
2660
  const pieces = splitCommand(command);
@@ -2590,7 +2669,8 @@ function touchingPieces(command, options = {}) {
2590
2669
  if (!isDump)
2591
2670
  return false;
2592
2671
  for (let at = index;pieces[at]?.separator === "|"; at++) {
2593
- if (parseCommand(pieces[at + 1]?.command ?? "").program === "redact")
2672
+ const next = parseCommand(pieces[at + 1]?.command ?? "");
2673
+ if (next.program === "ev" && next.args[0] === "redact")
2594
2674
  return false;
2595
2675
  }
2596
2676
  return true;
@@ -3021,7 +3101,7 @@ var RISKY_CONFIG = /^(?:alias\.|core\.(?:sshcommand|hookspath|pager|editor|fsmon
3021
3101
  var RISKY_ENV = /^GIT_(?:CONFIG_(?:COUNT|PARAMETERS)|EXTERNAL_DIFF|ASKPASS|PROXY_COMMAND|PAGER)=/;
3022
3102
  var READS_CONFIG = new Set(["--get", "--get-all", "--get-regexp", "--list", "-l", "--unset", "--unset-all", "--show-origin", "--show-scope"]);
3023
3103
  var STAGE_BY_PATH = `Stage by path: the tree carries unrelated work and peer sessions edit it live. ${USE_GC}`;
3024
- 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`.";
3104
+ var STASH = "Never `git stash`: a pop with nothing saved applies someone else's old stash. To prove a test fails without your change, `base 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`.";
3025
3105
  var ADD_ALL = `\`git add\` over the whole tree is refused. ${STAGE_BY_PATH}`;
3026
3106
  var COMMIT_ALL = `\`git commit -a\` stages the whole tree and is refused. ${STAGE_BY_PATH}`;
3027
3107
  var PUSH = "`git push` and `gp` run only when the user asked for a push in their latest prompt: say the commit is ready and let them ask.";
@@ -3297,7 +3377,9 @@ var PROTECTED_RM = "Never `rm -r` on a `.git` directory, on `~/Workspace` itself
3297
3377
  var FIND_DELETE_HOME = 'Never `find ~ -delete` or `find / -exec rm` (also `$HOME`): it deletes matches across the whole home or disk. Start `find` in the project folder or `.` and name the pattern, such as `find . -name "*.tmp" -delete`.';
3298
3378
  var REFLOG_EXPIRE = "Never `git reflog expire`, `git gc --prune=now` or `git update-ref -d`: they drop the reflog, unreachable commits or a ref, the only way back from a bad reset or rebase. Let git prune on its own schedule, and ask the user to run one when it is really wanted.";
3299
3379
  var DOCKER_PRUNE_ALL = "Never `docker system prune -a` (`--all`): it removes every image not used by a running container, volumes of other projects' stacks included with --volumes. `docker system prune` without -a drops only dangling data; remove named images with `docker rmi`.";
3300
- var PIPE_TO_SHELL = 'Never run what `curl`/`wget` fetches straight in a shell (`| sh`, `bash <(curl ...)`, `eval "$(curl ...)"`): it runs code nobody read. Download it to a file, read it, then run it, or hand the command to the user.';
3380
+ var PINNED_RUN = "`dl <url>` downloads it and prints its path and sha256; read that file, then `dl <url> --exec --sha256 <sha>` runs exactly what was read.";
3381
+ var PIPE_TO_SHELL = `Never run what \`curl\`/\`wget\` fetches straight in a shell (\`| sh\`, \`bash <(curl ...)\`, \`eval "$(curl ...)"\`): it runs code nobody read. ${PINNED_RUN} Or hand the command to the user.`;
3382
+ var UNPINNED_EXEC = `Never \`dl --exec --yes\` a script no \`--sha256\` or \`--sums\` pins: it runs code nobody read. ${PINNED_RUN}`;
3301
3383
  function hasOption(args, long, shorts) {
3302
3384
  for (const arg of args) {
3303
3385
  if (arg === "--")
@@ -3414,11 +3496,18 @@ function runsDownload(command) {
3414
3496
  return (SHELLS.has(program) || EVALUATORS.has(program)) && FETCH_SUBSTITUTION.test(piece.command);
3415
3497
  });
3416
3498
  }
3499
+ function runsUnpinned(args) {
3500
+ const own = args.includes("--") ? args.slice(0, args.indexOf("--")) : args;
3501
+ const given = (name) => own.some((arg) => arg === name || arg.startsWith(`${name}=`));
3502
+ return given("--exec") && given("--yes") && !given("--sha256") && !given("--sums");
3503
+ }
3417
3504
  function destructiveViolation(command) {
3418
3505
  if (runsDownload(command))
3419
3506
  return PIPE_TO_SHELL;
3420
3507
  for (const piece of splitCommand(command)) {
3421
3508
  const { program, args } = parseCommand(piece.command);
3509
+ if (program === "dl" && runsUnpinned(args))
3510
+ return UNPINNED_EXEC;
3422
3511
  if (program === "rm" && removesBroadly(args))
3423
3512
  return BROAD_RM;
3424
3513
  if (program === "rm" && recursiveTargets(args).some(isProtectedPath))
@@ -4047,18 +4136,15 @@ function checkPath(path) {
4047
4136
 
4048
4137
  // src/bins.ts
4049
4138
  var BINS = {
4050
- check: "`check`: runs the repo's check, typecheck, lint and test steps (package.json, composer.json and PHP tool configs, a Justfile, a Makefile) and prints only what failed, each full log saved to a file; a step runs inside the running compose service that mounts its folder (`--in <service>`, `--host`), never starting one; validate a change with it rather than chaining the scripts or `docker compose exec` by hand (`--only lint,test`, `--list`, `--slot`, `--failed` to re-run what failed last, `--fix` for the fixers).",
4051
- fix: "`fix` (the alias of `check --fix`): runs the repo's fixers and formatters (its fix, lint:fix and format scripts, php-cs-fixer, just fmt, go fmt, cargo fmt, ruff), in the compose service like `check`, and lists the files they changed.",
4139
+ check: "`check`: runs the repo's check, typecheck, lint and test steps (package.json, composer.json and PHP tool configs, a Justfile, a Makefile) and prints only what failed, each full log saved to a file; a step runs inside the running compose service that mounts its folder (`--in <service>`, `--host`), never starting one; validate a change with it rather than chaining the scripts or `docker compose exec` by hand (`--only lint,test`, `--list`, `--slot`, `--failed` to re-run what failed last); `check --fix` runs its fixers and formatters instead (its fix, lint:fix and format scripts, php-cs-fixer, just fmt, go fmt, cargo fmt, ruff) and lists the files they changed.",
4052
4140
  errs: "`errs [log]`, `errs -- <cmd>`: turns tsc, tsgo, eslint, bun check, bun test, vitest, playwright, phpunit, phpstan and php-cs-fixer 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.",
4053
4141
  db: '`db "<sql>"`: one read-only statement against the Postgres, MySQL or MariaDB in DATABASE_URL (`-e KEY` for another) or, without one, the compose project\'s running database service (`-s <service>`, `-c <container>` for any container, `-d <database>`), credentials never shown; a write runs on a database whose name ends in `_test` and is printed for the user to run otherwise; `db tables`, `db describe <table>`, `db dbs`; use it instead of `docker exec <container> psql` or `mysql`.',
4054
- 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; `ev pins [dir]` lists the env vars reaching outside that the tests of an app leave unpinned.",
4055
- redact: "`redact`: masks secrets in piped output, `<cmd> | redact`.",
4142
+ 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; `ev pins [dir]` lists the env vars reaching outside that the tests of an app leave unpinned; `ev redact` masks secrets in piped output, `<cmd> | ev redact`.",
4056
4143
  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.",
4057
4144
  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.",
4058
4145
  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.",
4059
4146
  sub: "`sub --from <text> --to <text> <file>...`: replaces text, writing nothing unless each match count is as expected (1, `-n N`, `--all`), `--regex`, `--dry-run --diff`; multi-line text goes as SEARCH/REPLACE blocks on stdin from a quoted heredoc (`sub <file> <<'EOF'`, see `sub --help`), no escaping; use it instead of sed -i, a bun -e or python editor.",
4060
- 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).",
4061
- 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).",
4147
+ 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; `base proof` runs it at HEAD (or a ref), 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).",
4062
4148
  gst: "`gst [--log N]`: branch, upstream, changed counts and HEAD in one line, then the changed paths by staged, unstaged and untracked, `gst --repos` one line per repository nested below; use it instead of `git status --short` and `git log --oneline`.",
4063
4149
  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.",
4064
4150
  gp: "`gp [--repos] [dir]...`: pushes the current branch when it is ahead of its upstream, with `-u` to origin when it has none, `--repos` every repository nested below too, `--dry-run` saying what would go, flags for git push after `--`; only when the user asked for a push, like `git push`.",
@@ -4071,11 +4157,10 @@ var BINS = {
4071
4157
  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.",
4072
4158
  slot: "`slot [-l <lock>] -- <cmd>`: waits for one of the machine-wide slots shared by every session (half the CPUs), then runs the command; `--lock <name>` also holds a named lock for what must not run twice (a shared test database), `slot ls` lists holders and waiters; run heavy jobs (phpunit, playwright, vue-tsc, a full test suite) through it instead of a flock wrapper.",
4073
4159
  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.",
4074
- 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.",
4075
- "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.",
4160
+ src: "`src peek <file:from-to>...` prints several spans with line numbers in one call, `src 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; `src 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; `src 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.",
4076
4161
  doctor: "`doctor`: checks this host's @kaynooo/cli-* 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.",
4077
4162
  cli: "`cli list`: every @kaynooo/cli-* 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.",
4078
- 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.",
4163
+ dl: "`dl <url>`: downloads into a new folder and prints the path, size, final URL and sha256, with the diff of a text file since its last download; `--sha256 <hex>` or `--sums <url>` checks it, `-x` extracts, `--bin [name]` installs into ~/.local/bin, `--exec --sha256 <sha>` runs a script exactly as read, `dl ls` lists what it installed or ran; use it instead of `curl | sh`, `curl -LO` and `sha256sum -c`.",
4079
4164
  out: "`out -- <cmd>`: folds long output, keeping the errors and saving the full log; run noisy builds, installs, tests and linters through it.",
4080
4165
  changelog: "`changelog --dry`: the release notes since the last tag, grouped from the conventional commits, without publishing them; `changelog` publishes them as the Forgejo release of the tag at HEAD, `changelog undo [tag]` takes a release back."
4081
4166
  };
@@ -4182,7 +4267,7 @@ async function hook(event, input, machine) {
4182
4267
  var LISTED = [
4183
4268
  { name: "remote", refuses: "ssh, scp, rsync and deploys to a remote machine", route: "hand the command to the user" },
4184
4269
  { name: "git", refuses: "stash, whole-tree add and commit, push without being asked, tags", route: "stage by path with `gc`, push only when asked" },
4185
- { name: "destructive", refuses: "reset --hard, discarding the tree, clean -f, force push, branch -D, rebase, filter-branch, rm -r on a broad path, curl piped to a shell", route: "commit with `gc` first, `base`, `git worktree add`, `--force-with-lease` only when asked" },
4270
+ { name: "destructive", refuses: "reset --hard, discarding the tree, clean -f, force push, branch -D, rebase, filter-branch, rm -r on a broad path, curl piped to a shell, dl --exec --yes on an unpinned script", route: "commit with `gc` first, `base`, `git worktree add`, `--force-with-lease` only when asked, `dl <url>` then `dl <url> --exec --sha256 <sha>`" },
4186
4271
  { name: "commit", refuses: "a commit message breaking the format, an unreadable one, trailers", route: "`gc <title> -m <line> -- <path>...`" },
4187
4272
  { name: "sql", refuses: "SQL writes and DDL, a file the client cannot read", route: '`db "<sql>"`, writes on a `*_test` database or handed over' },
4188
4273
  { name: "env", refuses: "reading or printing an env file, a diff of a tracked one", route: "`ev`, and `rg` for a tree-wide search" },
package/package.json CHANGED
@@ -1,17 +1,17 @@
1
1
  {
2
2
  "name": "@kaynooo/cli-guard",
3
3
  "type": "module",
4
- "version": "0.13.0",
4
+ "version": "0.14.1",
5
5
  "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.",
6
6
  "author": "Kaynooo <contact@kaynooo.fr>",
7
7
  "license": "MIT",
8
- "homepage": "https://git.kaynooo.fr/kaynooo/cli/src/branch/main/packages/guard#readme",
8
+ "homepage": "https://github.com/Kayno0o/cli/tree/main/packages/guard#readme",
9
9
  "repository": {
10
10
  "type": "git",
11
- "url": "git+https://git.kaynooo.fr/kaynooo/cli.git",
11
+ "url": "git+https://github.com/Kayno0o/cli.git",
12
12
  "directory": "packages/guard"
13
13
  },
14
- "bugs": "https://git.kaynooo.fr/kaynooo/cli/issues",
14
+ "bugs": "https://github.com/Kayno0o/cli/issues",
15
15
  "keywords": [
16
16
  "claude-code",
17
17
  "cli",
@@ -36,12 +36,12 @@
36
36
  "guard": "$npm_execpath src/cli.ts"
37
37
  },
38
38
  "devDependencies": {
39
- "@kaynooo/cli-db": "0.13.0",
40
- "@kaynooo/cli-edit": "0.11.0",
41
- "@kaynooo/cli-env": "0.13.3",
42
- "@kaynooo/cli-git": "0.16.0",
43
- "@kaynooo/cli-kit": "0.39.0",
44
- "@kaynooo/cli-out": "0.14.4",
45
- "@kaynooo/cli-pkg": "0.15.2"
39
+ "@kaynooo/cli-db": "0.13.2",
40
+ "@kaynooo/cli-edit": "0.11.2",
41
+ "@kaynooo/cli-env": "0.15.0",
42
+ "@kaynooo/cli-git": "0.17.0",
43
+ "@kaynooo/cli-kit": "0.41.0",
44
+ "@kaynooo/cli-out": "0.14.5",
45
+ "@kaynooo/cli-pkg": "0.16.1"
46
46
  }
47
47
  }