@kaynooo/guard-tools 0.2.1 → 0.3.0

package/README.md

@@ -14,10 +14,11 @@ guard check --json --cwd "$PWD" - < command.txt
 | --- | --- | --- |
 | `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` |
-| `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 | `src/commit.ts`, the validator in `@kaynooo/git-tools` |
+| `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-manager` | an install with another manager than the nearest lockfile pins, when it cannot be translated | `@kaynooo/pkg-tools` (`src/pin.ts`) |
+| `edit` | when `sub` is installed, a `sed -i` and a python, bun or node script replacing text in a file (`-c`, `-e` or a heredoc), handing over the `sub` command doing the same where its `s` commands or `.replace(...)` calls take literals | `src/replace.ts` |
 
 Every rule reads the command with one shell parser (`packages/kit/src/shell.ts`): quotes, heredoc bodies (text, never commands), `env`/`sudo`/`command` wrappers and subshells.
 

package/dist/cli.js

@@ -343,10 +343,15 @@ var USAGE_PREFIX = /^usage:\s*/i;
 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)) {
-  return [usageLine(usage, colors), "", colors.bold("Options:"), ...optionRows(options, colors)].join(`
+function helpText(usage, options, colors = paint(process3.stdout), examples = []) {
+  return [usageLine(usage, colors), "", colors.bold("Options:"), ...optionRows(options, colors), ...exampleRows(examples, colors)].join(`
 `);
 }
+function exampleRows(examples, colors = paint(process3.stdout)) {
+  if (examples.length === 0)
+    return [];
+  return ["", colors.bold("Examples:"), ...examples.map((example) => typeof example === "string" ? `  ${example}` : `  ${example[0]}  ${colors.dim(`# ${example[1]}`)}`)];
+}
 function optionRows(options, colors = paint(process3.stdout)) {
   const rows = Object.entries(options).map(([name, option]) => {
     const short = option.short === undefined ? "    " : `${colors.cyan(`-${option.short}`)}, `;
@@ -356,8 +361,27 @@ function optionRows(options, colors = paint(process3.stdout)) {
   const width = Math.max(0, ...rows.map((row) => row.width));
   return rows.map((row) => `  ${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" },
+  plain: { type: "boolean", description: "plain text, no colour or spinner: --color never" }
+};
+function applyOutput(color, plain, env = process3.env) {
+  const when = plain === true ? "never" : color ?? "auto";
+  if (when === "auto")
+    return;
+  if (when !== "always" && when !== "never")
+    badUsage(`--color takes auto, always or never, not ${when}`);
+  if (when === "always") {
+    env.FORCE_COLOR = "1";
+    delete env.NO_COLOR;
+  } else {
+    env.NO_COLOR = "1";
+    delete env.FORCE_COLOR;
+  }
+}
 function parse(args, usage, options, settings = {}) {
-  const all = { ...options, help: { type: "boolean", short: "h", description: "show this help" } };
+  const output = Object.fromEntries(Object.entries(OUTPUT_OPTIONS).filter(([name]) => !(name in options)));
+  const all = { ...options, ...output, help: { type: "boolean", short: "h", description: "show this help" } };
   if (completion.active)
     throw new Completing(all);
   const separator = settings.rest === true ? args.indexOf("--") : -1;
@@ -369,8 +393,10 @@ function parse(args, usage, options, settings = {}) {
   } catch (error) {
     badUsage(parseError(error));
   }
-  if (parsed.values.help === true) {
-    console.log(helpText(usage, all));
+  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));
     throw new HelpShown;
   }
   if (settings.positionals !== undefined)
@@ -417,6 +443,37 @@ function distance(a, b) {
 }
 
 // ../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) {
+  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 heading = group === undefined ? "Commands:" : `${group}:`;
+    const rows = groups.get(heading) ?? [];
+    rows.push(`  ${colors.cyan(name.padEnd(width))}  ${colors.dim(summary)}`);
+    groups.set(heading, rows);
+  }
+  return [...groups].filter(([, rows]) => rows.length > 0).flatMap(([heading, rows], index) => [...index === 0 ? [] : [""], colors.bold(heading), ...rows]);
+}
+function takeOutputFlags(argv) {
+  let index = 0;
+  for (;index < argv.length; index++) {
+    const word = argv[index];
+    if (word === "--plain")
+      applyOutput(undefined, true);
+    else if (word.startsWith("--color="))
+      applyOutput(word.slice("--color=".length), undefined);
+    else if (word === "--color" && argv[index + 1] !== undefined)
+      applyOutput(argv[++index], undefined);
+    else
+      break;
+  }
+  return argv.slice(index);
+}
 function closest(name, names) {
   const started = names.find((known) => known.startsWith(name));
   if (started !== undefined)
@@ -424,20 +481,23 @@ 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 }, stream) {
+async function help({ path, header, commands, defaultCommand, examples }, stream) {
   const colors = paint(stream);
-  const width = Math.max(...Object.keys(commands).map((name) => name.length));
   const prefix = path.join(" ");
   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),
     "",
     usageLine(`${prefix} ${defaultCommand === undefined ? colors.cyan("<command>") : `[${colors.cyan("<command>")}]`} [options]`, colors),
     "",
-    colors.bold("Commands:"),
-    ...Object.entries(commands).map(([name, { summary }]) => `  ${colors.cyan(name.padEnd(width))}  ${colors.dim(summary)}`),
-    ...options === undefined || Object.keys(options).length === 0 ? [] : ["", `${colors.bold(`Options of ${defaultCommand}:`)} ${colors.dim("the command run when none is named")}`, ...optionRows(options, 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)],
+    "",
+    colors.bold("Options:"),
+    ...optionRows(path.length === 1 ? TOP_OPTIONS : LEVEL_OPTIONS, colors),
+    ...exampleRows(examples ?? [], colors),
     "",
     `${colors.dim("Run")} ${prefix} ${colors.cyan("<command>")} --help ${colors.dim("for its options.")}`
   ].join(`
@@ -460,9 +520,15 @@ function reportThrown(prefix, error, redact = (text) => text) {
   printError(prefix, 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, argv, { version, redact }) {
-  const [name, ...args] = argv;
+async function dispatch(level, typed, { version, redact }) {
   const prefix = level.path.join(" ");
+  let argv;
+  try {
+    argv = takeOutputFlags(typed);
+  } catch (error) {
+    return reportThrown(prefix, error);
+  }
+  const [name, ...args] = argv;
   if (name === undefined && level.path.length > 1) {
     console.error(await help(level, process4.stderr));
     return 2;
@@ -488,7 +554,7 @@ async function dispatch(level, argv, { 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 }, rest, { version, redact });
+    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 });
   }
   try {
     return await command.run(rest);
@@ -534,7 +600,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 }, argv, { version: cli.version, redact: cli.redact });
+  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 });
 }
 // ../kit/src/process.ts
 import { constants } from "os";
@@ -558,7 +624,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.2.1";
+var version = "0.3.0";
 
 // ../kit/src/shell.ts
 var SEPARATORS = new Set([`
@@ -571,6 +637,7 @@ var LEADING_TILDE = /^~(?=\/|$)/;
 var LEADING_TABS = /^\t+/;
 var OPENERS = /^[({]+/;
 var CLOSERS = /[)}]+$/;
+var DOUBLE_QUOTED_ESCAPES = new Set(["$", "`", '"', "\\"]);
 var HEREDOC = /^<<(-?)[ \t]*(?:'([^']*)'|"([^"]*)"|([^\s;&|<>()-][^\s;&|<>()]*))/;
 var WRAPPERS = new Set(["command", "env", "sudo", "exec", "nohup", "time"]);
 function separatorWidth(command, i) {
@@ -758,7 +825,9 @@ function words(text) {
     if (isContinuation)
       continue;
     isStarted = true;
-    if (char === "\\" && quote !== "'")
+    if (char === "\\" && quote === '"' && !DOUBLE_QUOTED_ESCAPES.has(text[i + 1] ?? ""))
+      current += char;
+    else if (char === "\\" && quote !== "'")
       current += text[++i] ?? "";
     else if (quote !== null && char === quote)
       quote = null;
@@ -799,7 +868,10 @@ function parseCommand(text) {
       break;
     }
   }
-  const last = (tokens.at(-1) ?? "").replace(CLOSERS, "");
+  const closers = CLOSERS.exec(text.trimEnd())?.[0].length ?? 0;
+  const word = tokens.at(-1) ?? "";
+  const trimmed = word.length - (CLOSERS.exec(word)?.[0].length ?? 0);
+  const last = word.slice(0, Math.max(trimmed, word.length - closers));
   if (tokens.length > 0)
     tokens.splice(-1, 1, ...last === "" ? [] : [last]);
   const [program = "", ...args] = tokens;
@@ -1129,13 +1201,14 @@ var TRAILER = /^(?:co-authored-by|signed-off-by|reviewed-by|acked-by|tested-by|r
 var BULLET = /^\s*(?:[-*+]|\d+[.)])\s/;
 var SENTENCE_END = /[.!?:;)\]`'"]$/;
 var LOWER_START = /^\p{Ll}/u;
-var FORMAT = "A commit message is a `type(scope): title` line, then optionally a blank line, one or two lines on what changed and one `#<n> - <title>` line per ticket.";
-var TITLE = `The title is no Conventional Commit, its type and scope taken from the repository's history. ${FORMAT}`;
-var TITLE_LINE = `The title takes one line and a blank line follows it. ${FORMAT}`;
-var TRAILERS = `No trailers, ever: no Co-Authored-By, Signed-off-by or "Generated with" line, no --signoff or --trailer. ${FORMAT}`;
-var BULLETS = `The body names what changed in a line or two, never a bullet list narrating the diff. ${FORMAT}`;
-var TOO_LONG = `The body holds at most two lines besides the ticket lines; what goes beyond belongs in the reply. ${FORMAT}`;
-var WRAPPED = `A body sentence stays on one line however long it runs: never hard-wrap it. ${FORMAT}`;
+var RULE = 'The rule: a `type(scope): title` line, `!` after the scope for a breaking change, type and scope taken from the repository\'s history; then optionally a blank line and one or two lines on what changed, never a bullet list or a hard-wrapped sentence; then a blank line and one line per ticket, its title copied verbatim, `#<n> - <title>` (`owner/repo#<n> - <title>` for another repository). The message ends there: no Co-Authored-By, Signed-off-by or "Generated with" trailer. Only a breaking change gives full details.';
+var TITLE = `The title is no Conventional Commit. ${RULE}`;
+var TITLE_LINE = `The title takes one line and a blank line follows it. ${RULE}`;
+var TRAILERS = `No trailers, ever: no Co-Authored-By, Signed-off-by or "Generated with" line, no --signoff or --trailer. ${RULE}`;
+var BULLETS = `The body names what changed in a line or two, never a bullet list narrating the diff. ${RULE}`;
+var TOO_LONG = `The body holds at most two lines besides the ticket lines; what goes beyond belongs in the reply. ${RULE}`;
+var WRAPPED = `A body sentence stays on one line however long it runs: never hard-wrap it. ${RULE}`;
+var USE_GC = "Commit with `gc`, which stages exactly the paths given once the message keeps the rule: `gc 'fix(api): retry a timed-out fetch' -m 'A 502 is retried once before failing.' --ticket '#12 - [UC3] Retry failed fetches' -- src/api.ts`.";
 function isDescription(line) {
   return line !== undefined && line !== "" && !TICKET.test(line);
 }
@@ -1449,7 +1522,7 @@ var COMMIT_VALUE_LONGS = new Set(["--message", "--file", "--reuse-message", "--r
 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 (`git add <path>...`, then `git status`): the tree carries unrelated work and peer sessions edit it live.";
+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 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}`;
@@ -1617,6 +1690,330 @@ function remoteViolation(command) {
   return splitCommand(command).some((piece) => isRemote(piece.command)) ? REMOTE : null;
 }
 
+// src/replace.ts
+var PYTHON = /^python[\d.]*$/;
+var SCRIPT_RUNNERS = new Set(["bun", "node"]);
+var EVAL_FLAGS = new Set(["-e", "--eval", "-p", "--print"]);
+var WRITES = /\bwrite_text\(|\bBun\.write\(|\bwriteFileSync\(|\bwriteFile\(|\bopen\([^)\n]*,\s*['"](?:w|a|r\+)/;
+var REPLACE_CALL = /\.(replace|replaceAll)\(/g;
+var FILE_CALL = /\b(?:Path|open|Bun\.file|Bun\.write|readFileSync|writeFileSync|readFile|writeFile)\(\s*/g;
+var IDENTIFIER = /^[A-Z_$][\w$]*/i;
+var COUNT_CHECK = /\.count\(/g;
+var COUNT_EQUALS = /^\s*\)\s*==\s*(\d+)/;
+var PYTHON_COUNT = /^\s*,\s*(\d+)\s*\)/;
+var SPACE2 = /^\s*/;
+var COMMA = /^\s*,\s*/;
+var REGEX_FLAGS = /^[gm]*$/;
+var PLAIN_WORD2 = /^[\w@%+=:,./*?-]+$/;
+var SED_SEPARATORS = /^[\s;]*/;
+var SED_SEPARATOR = /[\s;]/;
+var BRE_ESCAPED = new Map([["(", "("], [")", ")"], ["{", "{"], ["}", "}"], ["+", "+"], ["?", "?"], ["|", "|"]]);
+var POSIX_CLASSES = new Map([["[:space:]", String.raw`\s`], ["[:digit:]", String.raw`\d`], ["[:alpha:]", "a-zA-Z"], ["[:alnum:]", "a-zA-Z0-9"], ["[:upper:]", "A-Z"], ["[:lower:]", "a-z"], ["[:blank:]", String.raw` \t`]]);
+var ESCAPES = new Map([["n", `
+`], ["t", "\t"]]);
+var BRE_METAS = new Set([".", "[", "]", "*", "^", "$"]);
+var ERE_METAS = new Set([...BRE_METAS, "+", "?", "(", ")", "{", "}", "|"]);
+var JS_SPECIALS = /[.*+?^${}()|[\]\\]/g;
+var WHY = "writes nothing unless each file matches as often as expected, where it rewrites files whatever it matched";
+var GENERIC = "Run `sub --from <text> --to <text> <file>...` instead (`--regex`, `--all`, `-n N`, `--pairs -` for several in order, `--dry-run --diff` to look first).";
+function literalAt(text, at, regex = false) {
+  let start = at;
+  const isRaw = text[start] === "r" || text[start] === "R";
+  if (isRaw || text[start] === "b")
+    start++;
+  const quote = text[start] ?? "";
+  if (regex && quote === "/")
+    return regexAt(text, start);
+  if (quote !== "'" && quote !== '"' && quote !== "`")
+    return;
+  const fence = text.startsWith(quote.repeat(3), start) ? quote.repeat(3) : quote;
+  let value = "";
+  for (let i = start + fence.length;i < text.length; i++) {
+    const char = text[i] ?? "";
+    if (text.startsWith(fence, i))
+      return { value, end: i + fence.length };
+    if (quote === "`" && text.startsWith("${", i))
+      return;
+    if (char === "\\" && !isRaw) {
+      const next = text[++i] ?? "";
+      value += ESCAPES.get(next) ?? (next === `
+` ? "" : next);
+    } else {
+      value += char;
+    }
+  }
+  return;
+}
+function regexAt(text, start) {
+  let source = "";
+  let inClass = false;
+  for (let i = start + 1;i < text.length; i++) {
+    const char = text[i] ?? "";
+    if (char === `
+`)
+      return;
+    if (char === "\\") {
+      source += char + (text[++i] ?? "");
+      continue;
+    }
+    if (char === "/" && !inClass) {
+      const flags = IDENTIFIER.exec(text.slice(i + 1))?.[0] ?? "";
+      return { value: source, end: i + 1 + flags.length, flags };
+    }
+    if (char === "[" || char === "]")
+      inClass = char === "[";
+    source += char;
+  }
+  return;
+}
+function skip(text, at, pattern) {
+  const found = pattern.exec(text.slice(at));
+  return found === null ? undefined : at + found[0].length;
+}
+function valueAt(script, at, regex = false) {
+  const literal = literalAt(script, at, regex);
+  const name = literal === undefined ? IDENTIFIER.exec(script.slice(at))?.[0] : undefined;
+  if (literal !== undefined || name === undefined)
+    return literal;
+  const assignments = [...script.slice(0, at).matchAll(new RegExp(String.raw`(?<![\w.$])${name.replaceAll("$", String.raw`\$`)}\s*=(?!=)\s*`, "g"))];
+  const last = assignments.at(-1);
+  const assigned = last === undefined ? undefined : literalAt(script, last.index + last[0].length, regex);
+  return assigned === undefined ? undefined : { ...assigned, end: at + name.length };
+}
+function scriptPaths(script) {
+  const paths = new Set;
+  for (const call of script.matchAll(FILE_CALL)) {
+    const path = valueAt(script, call.index + call[0].length)?.value;
+    if (path !== undefined && path !== "")
+      paths.add(path);
+  }
+  return [...paths];
+}
+function assertedCounts(script) {
+  const counts = new Map;
+  for (const call of script.matchAll(COUNT_CHECK)) {
+    const text = valueAt(script, call.index + call[0].length);
+    const equals = text === undefined ? null : COUNT_EQUALS.exec(script.slice(text.end));
+    if (text !== undefined && equals !== null)
+      counts.set(text.value, Number(equals[1]));
+  }
+  return counts;
+}
+function scriptPairs(script, isPython) {
+  const pairs = [];
+  const counts = isPython ? assertedCounts(script) : new Map;
+  for (const call of script.matchAll(REPLACE_CALL)) {
+    const from = valueAt(script, skip(script, call.index + call[0].length, SPACE2) ?? 0, !isPython);
+    const comma = from === undefined ? undefined : skip(script, from.end, COMMA);
+    const to = comma === undefined ? undefined : valueAt(script, comma);
+    if (from === undefined || to === undefined)
+      return;
+    if (from.flags !== undefined) {
+      if (!REGEX_FLAGS.test(from.flags))
+        return;
+      pairs.push({ from: from.value, to: to.value, regex: true, ...from.flags.includes("g") ? { all: true } : {} });
+      continue;
+    }
+    const limit = isPython ? PYTHON_COUNT.exec(script.slice(to.end)) : null;
+    const count = limit === null ? counts.get(from.value) : Number(limit[1]);
+    const all = call[1] === "replaceAll" || isPython && count === undefined;
+    const pair = { from: from.value, to: to.value };
+    if (all)
+      pair.all = true;
+    else if (count !== undefined && count !== 1)
+      pair.count = count;
+    pairs.push(pair);
+  }
+  return pairs.length === 0 ? undefined : pairs;
+}
+function sedArgs(args) {
+  const sed = { scripts: [], files: [], isExtended: false, isInPlace: false, isPlain: true };
+  const operands = [];
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i] ?? "";
+    if (arg === "--in-place" || arg.startsWith("--in-place="))
+      sed.isInPlace = true;
+    else if (arg === "--regexp-extended")
+      sed.isExtended = true;
+    else if (arg === "--expression")
+      sed.scripts.push(args[++i] ?? "");
+    else if (arg.startsWith("--expression="))
+      sed.scripts.push(arg.slice("--expression=".length));
+    else if (arg.startsWith("--"))
+      sed.isPlain = false;
+    else if (arg.startsWith("-") && arg.length > 1)
+      i += sedCluster(arg, args[i + 1], sed);
+    else
+      operands.push(arg);
+  }
+  if (sed.scripts.length === 0)
+    sed.scripts.push(operands.shift() ?? "");
+  sed.files = operands;
+  return sed;
+}
+function sedCluster(arg, next, sed) {
+  for (const [index, flag] of [...arg.slice(1)].entries()) {
+    if (flag === "i") {
+      sed.isInPlace = true;
+      return 0;
+    }
+    if (flag === "E" || flag === "r") {
+      sed.isExtended = true;
+    } else if (flag === "e") {
+      const value = index === arg.length - 2 ? next : arg.slice(index + 2);
+      sed.scripts.push(value ?? "");
+      return index === arg.length - 2 ? 1 : 0;
+    } else if (flag !== "s" && flag !== "u") {
+      sed.isPlain = false;
+    }
+  }
+  return 0;
+}
+function sedPart(script, at, delimiter) {
+  for (let i = at;i < script.length; i++) {
+    if (script[i] === "\\")
+      i++;
+    else if (script[i] === delimiter)
+      return { part: script.slice(at, i), end: i + 1 };
+  }
+  return;
+}
+function sedLiteral(pattern, delimiter, metas) {
+  let text = "";
+  for (let i = 0;i < pattern.length; i++) {
+    const char = pattern[i] ?? "";
+    if (char !== "\\") {
+      if (metas.has(char))
+        return;
+      text += char;
+      continue;
+    }
+    const next = pattern[++i] ?? "";
+    if (ESCAPES.has(next))
+      text += ESCAPES.get(next);
+    else if (next === delimiter || next === "\\" || BRE_METAS.has(next) || metas === ERE_METAS && ERE_METAS.has(next))
+      text += next;
+    else
+      return;
+  }
+  return text;
+}
+function sedRegex(pattern, delimiter, isExtended) {
+  let source = "";
+  for (let i = 0;i < pattern.length; i++) {
+    const char = pattern[i] ?? "";
+    const posix = [...POSIX_CLASSES].find(([name]) => pattern.startsWith(name, i));
+    if (posix !== undefined) {
+      source += posix[1];
+      i += posix[0].length - 1;
+    } else if (char === "\\") {
+      const next = pattern[++i] ?? "";
+      if (next === delimiter)
+        source += next.replaceAll(JS_SPECIALS, String.raw`\$&`);
+      else
+        source += !isExtended && BRE_ESCAPED.has(next) ? next : `\\${next}`;
+    } else {
+      source += !isExtended && BRE_ESCAPED.has(char) ? `\\${char}` : char;
+    }
+  }
+  return source;
+}
+function sedReplacement(replacement, literal) {
+  let text = "";
+  for (let i = 0;i < replacement.length; i++) {
+    const char = replacement[i] ?? "";
+    if (char === "&") {
+      text += literal ?? "$&";
+    } else if (char === "$" && literal === undefined) {
+      text += "$$";
+    } else if (char === "\\") {
+      const next = replacement[++i] ?? "";
+      if (next >= "1" && next <= "9" && literal === undefined)
+        text += `$${next}`;
+      else if (next >= "0" && next <= "9")
+        return;
+      else
+        text += ESCAPES.get(next) ?? (next === "$" && literal === undefined ? "$$" : next);
+    } else {
+      text += char;
+    }
+  }
+  return text;
+}
+function sedPairs(script, isExtended) {
+  const pairs = [];
+  for (let at = 0;at < script.length; ) {
+    at = skip(script, at, SED_SEPARATORS) ?? at;
+    if (at >= script.length)
+      break;
+    const delimiter = script[at + 1] ?? "";
+    if (script[at] !== "s" || delimiter === "" || delimiter === "\\" || delimiter === `
+`)
+      return;
+    const pattern = sedPart(script, at + 2, delimiter);
+    const replacement = pattern === undefined ? undefined : sedPart(script, pattern.end, delimiter);
+    if (pattern === undefined || replacement === undefined)
+      return;
+    const isGlobal = script[replacement.end] === "g";
+    at = replacement.end + (isGlobal ? 1 : 0);
+    if (at < script.length && !SED_SEPARATOR.test(script[at] ?? ""))
+      return;
+    const literal = sedLiteral(pattern.part, delimiter, isExtended ? ERE_METAS : BRE_METAS);
+    const to = sedReplacement(replacement.part, literal);
+    if (to === undefined)
+      return;
+    pairs.push({ from: literal ?? sedRegex(pattern.part, delimiter, isExtended), to, ...literal === undefined ? { regex: true } : {}, ...isGlobal ? { all: true } : {} });
+  }
+  return pairs.length === 0 ? undefined : pairs;
+}
+function quote(text) {
+  return `'${text.replaceAll("'", String.raw`'\''`)}'`;
+}
+function fileWord(path) {
+  return PLAIN_WORD2.test(path) ? path : quote(path);
+}
+function subCommand(pairs, files) {
+  const targets = files.length === 0 ? "<file>" : files.map(fileWord).join(" ");
+  const [pair] = pairs;
+  if (pairs.length > 1 || pair === undefined)
+    return `sub --pairs - ${targets} <<'PAIRS'
+${JSON.stringify(pairs)}
+PAIRS`;
+  const flags = [pair.regex === true ? " --regex" : "", pair.all === true ? " --all" : "", pair.count === undefined ? "" : ` -n ${pair.count}`].join("");
+  return `sub --from ${quote(pair.from)} --to ${quote(pair.to)}${flags} ${targets}`;
+}
+function route(what, pairs, files) {
+  return pairs === undefined ? `${what} ${GENERIC}` : `${what} Run this instead, which ${WHY}:
+${subCommand(pairs, files)}`;
+}
+function inlineScript(program, args, text) {
+  const flags = PYTHON.test(program) ? new Set(["-c"]) : EVAL_FLAGS;
+  const flag = args.findIndex((arg) => flags.has(arg));
+  if (flag !== -1)
+    return args[flag + 1] ?? null;
+  const reads = args.every((arg) => arg === "-" || arg.startsWith("<<") || program === "bun" && arg === "run");
+  return reads ? heredocBody(text, HEREDOC_OPENER)?.body ?? null : null;
+}
+function replaceViolation(command) {
+  for (const piece of splitCommand(command)) {
+    const { program, args } = parseCommand(piece.command);
+    if (program === "sed") {
+      const sed = sedArgs(args);
+      if (sed.isInPlace)
+        return route("`sed -i` rewrites files without checking what it matched.", sed.isPlain && sed.scripts.length > 0 ? sedPairs(sed.scripts.join(`
+`), sed.isExtended) : undefined, sed.files);
+      continue;
+    }
+    const isPython = PYTHON.test(program);
+    const script = isPython || SCRIPT_RUNNERS.has(program) ? inlineScript(program, args, piece.text) : null;
+    if (script === null || !WRITES.test(script) || script.search(REPLACE_CALL) === -1)
+      continue;
+    const pairs = scriptPairs(script, isPython);
+    return route(`A ${isPython ? "python" : program} script replacing text in a file is what \`sub\` does with a match-count check.`, pairs, scriptPaths(script));
+  }
+  return null;
+}
+
 // src/check.ts
 function absolute(path, cwd) {
   return path.startsWith("/") ? path : `${cwd}/${path}`;
@@ -1668,9 +2065,11 @@ async function checkCommand(command, context) {
   const first = (messages) => messages.find((message) => message !== null) ?? null;
   add("remote", first(run.map(remoteViolation)));
   add("git", first(run.map((each) => gitViolation(each, context.isPushAsked))));
-  add("commit", commitViolation(command, context));
+  const commit = commitViolation(command, context);
+  add("commit", commit === null ? null : `${commit} ${USE_GC}`);
   add("sql", first(await Promise.all(run.map(async (each) => sqlViolation(each, async (path) => Promise.resolve(context.read(absolute(path, context.cwd))))))));
   add("env", touchesEnv(command) ? USE_EV : null);
+  add("edit", context.canSub ? first(run.map(replaceViolation)) : null);
   const found = mismatches(command, context);
   const refused = found.find((mismatch) => mismatch.rewrite === null || !context.canRewrite);
   const rewrite = refused?.rewrite ?? null;
@@ -1696,14 +2095,14 @@ var BINS = {
   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: "`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.",
   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).",
   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>` (`-t 5m`): waits until the line shows, the port listens or the URL answers 2xx, exits 1 on a --fail line with the lines around it, 2 on a timeout with the last lines; use it instead of sleep and tail or polling loops.",
+  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.",
   out: "`out -- <cmd>`: folds long output, keeping the errors and saving the full log; run noisy builds, installs, tests and linters through it."
 };
@@ -1740,12 +2139,13 @@ async function bashCall(command, input, machine) {
     isPushAsked: file !== null && machine.exists(file),
     canRewrite: false,
     canWrap: false,
+    canSub: machine.has("sub"),
     read: machine.read,
     exists: machine.exists
   });
   if (verdict.violations.length > 0 || verdict.packages.length === 0 || !machine.has("pkg"))
     return deny(verdict.violations);
-  const checked = await machine.run(["pkg", ...verdict.packages], cwd);
+  const checked = await machine.run(["pkg", "check", ...verdict.packages], cwd);
   return checked.code === 1 ? deny([{ rule: "pkg", message: `pkg refused what this adds, so it was not run:
 ${checked.text.trim()}` }]) : null;
 }
@@ -1778,7 +2178,7 @@ async function hook(event, input, machine) {
 // src/cli.ts
 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 and package managers.
+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>\`.`;
 var checkOptions = {
@@ -1824,6 +2224,7 @@ ${checkUsage}`);
     isPushAsked: values["push-asked"] === true,
     canRewrite: true,
     canWrap: values["no-wrap"] !== true && Bun.which("out") !== null,
+    canSub: Bun.which("sub") !== null,
     read: readText,
     exists: existsSync
   };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kaynooo/guard-tools",
   "type": "module",
-  "version": "0.2.1",
+  "version": "0.3.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>",
   "license": "MIT",
@@ -38,6 +38,7 @@
   "devDependencies": {
     "@kaynooo/cli-kit": "workspace:*",
     "@kaynooo/db-tools": "workspace:*",
+    "@kaynooo/edit-tools": "workspace:*",
     "@kaynooo/env-tools": "workspace:*",
     "@kaynooo/git-tools": "workspace:*",
     "@kaynooo/out-tools": "workspace:*",