@hasna/hooks 0.12.2 → 0.12.3

package/hooks/hook-workspace-repos-guard/README.md

@@ -61,6 +61,26 @@ other than `$HOME`, `$( )`, backticks, a glob) fails closed to the directory
 the command runs in, so `rm -rf "$TMPDIR/x"` run from a protected checkout is
 refused. Use a literal absolute path for deletes outside the roots.
 
+A here-document body is data, not commands, when nothing in the command can
+run it: its delimiter is quoted (or it holds no `$( )` or backticks), and
+every command word of the command, including those in command substitutions
+at any depth and inside double quotes, is a command that never runs its input
+or arguments as code (`cat`, `tee`,
+`head`, `grep`, `jq`, `echo`, `cd`, `mkdir`, `cp`, `mv`, `rm`, `trash`, the
+Hasna record CLIs such as `todos` and `conversations`, `git` with a data
+subcommand such as `commit` and no `-c`, and `gh pr|issue|api|release|gist`).
+No command word may be a path, an expansion, or the bare name of a file the
+command writes, and the command may hold no variable assignment, process
+substitution, or shell, interpreter or runner word (`bash`, `python3`,
+`ssh`, `sudo`, `xargs`, `chmod`, ...). Any other command word (`rbash`,
+`newgrp`, `tclsh8.6`, an unknown tool) keeps the line-by-line analysis,
+because a list of runners can never be complete. A `<<` inside `${...}` or
+`$[...]` is not taken for a here-document. Such a body is analysed on
+its own, away from the session cwd: a protected path it names, or reaches
+with its own `cd`, still counts, but a word in it (`rm`, `>`, a trailing name)
+is never resolved against the cwd, and its `cd` never moves the outer shell.
+Every other body keeps the line-by-line analysis.
+
 ## Configuration
 
 Allowed orgs default to `hasna,hasnaxyz,hasna-products`. Private workspace

package/hooks/hook-workspace-repos-guard/src/hook.ts

@@ -36,7 +36,9 @@
  * off, so a later read-only stage never supplies an earlier stage's target.
  * apply_patch tools are inspected through their `*** Add File:` /
  * `*** Update File:` / `*** Delete File:` markers. Parenthesized command
- * groups are unwrapped.
+ * groups are unwrapped. A here-document body is data unless something in the
+ * command can run it (see dataHeredocs): its words are then never resolved
+ * against the cwd, and only protected paths it names explicitly count.
  *
  * Allowed orgs default to hasna,hasnaxyz,hasna-products and are overridable
  * with the WORKSPACE_REPOS_GUARD_ORGS env var (comma-separated) or, where
@@ -52,7 +54,16 @@
 import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, statSync } from "fs";
 import { homedir } from "os";
 import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "path";
-import { commandWordIndex, decodeWord, envSplitCommandText, gitSubcommand, lexCommand, mentionsDeleteVerb } from "../../hook-trash-guard/src/hook";
+import {
+  commandWordIndex,
+  decodeWord,
+  envSplitCommandText,
+  gitSubcommand,
+  heredocMarkerAt,
+  lexCommand,
+  mentionsDeleteVerb,
+  type HeredocMarker,
+} from "../../hook-trash-guard/src/hook";
 import {
   getCommand,
   readInput,
@@ -352,6 +363,20 @@ function shellWords(command: string): ShellWord[] {
   return words;
 }
 
+/**
+ * Whether the word at `at`, the first one after a delete verb or subcommand,
+ * asks for help or a version: such a call prints and exits, acting on
+ * nothing. Only that first position counts. Any earlier option may take the
+ * request as its value (`git clean -f -e --help` excludes the pattern
+ * `--help` and still deletes), so a request after another option stays a
+ * delete. `-h`/`-V` count only where `short` (Trash and git subcommands,
+ * whose `-h` is help).
+ */
+function asksForHelp(words: string[], at: number, short: boolean): boolean {
+  const word = words[at];
+  return word === "--help" || word === "--version" || (short && (word === "-h" || word === "-V"));
+}
+
 /**
  * Classify the operation of one command segment (a `&&`/`||`/`;`-delimited
  * unit). Git is handled by its subcommand: clean|rm delete, clone|init write,
@@ -373,7 +398,10 @@ function segmentOperation(segment: string): Operation {
     if (index < 0) return "read";
     const words = part.words.filter((_, at) => at >= index && !part.redirects.has(at)).map((word) => decodeWord(word.text));
     const tool = words[0].split("/").pop();
-    if (["rm", "rmdir", "unlink", "shred", "rmtree", "del"].includes(tool ?? "")) return "delete";
+    if (["rm", "rmdir", "shred"].includes(tool ?? "")) return asksForHelp(words, 1, false) ? "read" : "delete";
+    // POSIX/BSD unlink takes no options, so `unlink --help` removes a file
+    // named `--help`; rmtree and del are not modelled. Always deletes.
+    if (["unlink", "rmtree", "del"].includes(tool ?? "")) return "delete";
     if (tool === "trash") {
       // Hasna metadata/setup verbs take identifiers, not paths to remove.
       // Keep legacy positional Trash clients and capture verbs guarded.
@@ -386,11 +414,14 @@ function segmentOperation(segment: string): Operation {
       }
       if (at === words.length || ["status", "doctor", "list", "info", "get", "pending", "station", "setup", "backup", "storage", "retrieval", "backup-storage", "backup-inspect", "backup-refresh", "help"].includes(words[at])) return "read";
       if (["restore", "restore-capsule"].includes(words[at])) return "write";
+      if (["put", "rm", "delete", "remove"].includes(words[at]) && asksForHelp(words, at + 1, true)) return "read";
       return "delete";
     }
     if (tool === "git") {
       const sub = gitSubcommand(part, index);
-      if (sub === "clean" || sub === "rm") return "delete";
+      // Honoured only for `git rm|clean <request>`: a global option before the
+      // subcommand is not modelled here, so it keeps the delete.
+      if (sub === "clean" || sub === "rm") return words[1] === sub && asksForHelp(words, 2, true) ? "read" : "delete";
       return sub === "clone" || sub === "init" ? "write" : "read";
     }
     if (tool === "env" && mentionsDeleteVerb(envSplitCommandText(words))) return "delete";
@@ -499,6 +530,384 @@ function cdDestinations(operand: string | undefined, bases: string[], home: stri
 
 const REL_OPERAND = /(?:^|\s)(\.\.?|[^\s"';&|<>()\x60/]+(?:\/[^\s"';&|<>()\x60]*)?)\s*$/;
 
+interface HeredocSpan {
+  /** Line of the `<<` operator, and the operator's columns on it. */
+  line: number;
+  from: number;
+  to: number;
+  /** First body line, and the terminator line just past the last. */
+  start: number;
+  end: number;
+  quoted: boolean;
+}
+
+/**
+ * Here-document bodies in a command, located line by line. Bash reads a body
+ * from the line after the one holding its `<<` operator, whatever quoting or
+ * `$( )` that operator sits in, so each line is scanned with a stack of open
+ * contexts (a `"..."` string, a `$( )` with its unclosed `(` count) carried
+ * across lines. Returns null when the scan cannot be followed to the end: a
+ * `'...'`, backtick or arithmetic `(( ))` spanning lines, an operator with no
+ * word, a body with no exact terminator line (bash's `DELIM)` form included),
+ * or a quote or substitution still open at the end.
+ */
+export function heredocSpans(command: string): HeredocSpan[] | null {
+  const lines = command.split("\n");
+  const spans: HeredocSpan[] = [];
+  const stack: Array<'"' | number> = [];
+  let n = 0;
+  while (n < lines.length) {
+    const lineIndex = n;
+    const line = lines[n++].replace(/\r$/, "");
+    const pending: Array<{ marker: HeredocMarker; from: number }> = [];
+    for (let i = 0; i < line.length; i++) {
+      const ch = line[i];
+      const top = stack[stack.length - 1];
+      if (ch === "\\") {
+        i++;
+        continue;
+      }
+      if (ch === "$" && line[i + 1] === "(" && line[i + 2] === "(") {
+        const close = line.indexOf("))", i + 3);
+        if (close < 0) return null;
+        i = close + 1;
+        continue;
+      }
+      if (ch === "$" && line[i + 1] === "(") {
+        stack.push(0);
+        i++;
+        continue;
+      }
+      // `$[ ]` is arithmetic, so a `<<` in it is a shift, not an operator.
+      if (ch === "$" && line[i + 1] === "[") return null;
+      // Inside `${...}` a `<<` is not an operator either (`${x:-<<EOF}` starts
+      // no body), so a parameter expansion is skipped only when it holds no
+      // quote, substitution, nested expansion or `<<`; otherwise the scan
+      // gives up and the command keeps the line-by-line analysis.
+      if (ch === "$" && line[i + 1] === "{") {
+        const close = line.indexOf("}", i + 2);
+        if (close < 0 || /['"\x60$]|<</.test(line.slice(i + 2, close))) return null;
+        i = close;
+        continue;
+      }
+      if (ch === "\x60") {
+        const close = line.indexOf("\x60", i + 1);
+        if (close < 0) return null;
+        i = close;
+        continue;
+      }
+      if (top === '"') {
+        if (ch === '"') stack.pop();
+        continue;
+      }
+      // Command text, at the top level or inside `$( )`.
+      if (ch === "'") {
+        const close = line.indexOf("'", i + 1);
+        if (close < 0) return null;
+        i = close;
+        continue;
+      }
+      if (ch === '"') {
+        stack.push('"');
+        continue;
+      }
+      if (ch === "#" && (i === 0 || /[\s;&|()]/.test(line[i - 1]))) break;
+      if (ch === "(" && line[i + 1] === "(" && (i === 0 || /[\s;&|(]/.test(line[i - 1]))) {
+        const close = line.indexOf("))", i + 2);
+        if (close < 0) return null;
+        i = close + 1;
+        continue;
+      }
+      if (typeof top === "number" && (ch === "(" || ch === ")")) {
+        if (ch === "(") stack[stack.length - 1] = top + 1;
+        else if (top === 0) stack.pop();
+        else stack[stack.length - 1] = top - 1;
+        continue;
+      }
+      if (ch === "<" && line[i + 1] === "<") {
+        if (line[i + 2] === "<") {
+          i += 2;
+          continue;
+        }
+        const marker = heredocMarkerAt(line, i);
+        if (!marker) return null;
+        pending.push({ marker, from: i });
+        i = marker.end - 1;
+      }
+    }
+    for (const { marker, from } of pending) {
+      const start = n;
+      for (;;) {
+        if (n >= lines.length) return null;
+        let text = lines[n++].replace(/\r$/, "");
+        if (marker.stripTabs) text = text.replace(/^\t+/, "");
+        if (text === marker.delimiter) break;
+      }
+      spans.push({ line: lineIndex, from, to: marker.end, start, end: n - 1, quoted: marker.quoted });
+    }
+  }
+  return stack.length === 0 ? spans : null;
+}
+
+/**
+ * Words that can run a here-document body as code, or run something that
+ * may: shells, interpreters, remote, privileged and deferred runners, and
+ * tools with a shell escape. Matched as any word of the command, because
+ * wrappers (`sudo -u x bash`, `timeout 9 sh`, `xargs rm`) put the runner after
+ * the command word.
+ */
+const BODY_RUNNERS = new Set([
+  "sh", "bash", "zsh", "dash", "ksh", "mksh", "ash", "fish", "csh", "tcsh", "nu", "xonsh", "elvish", "busybox", "toybox",
+  "ssh", "su", "runuser", "sudo", "doas", "pkexec", "xargs", "parallel", "expect", "script", "at", "batch", "crontab",
+  "watch", "flock", "chroot", "nsenter", "unshare", "docker", "podman", "kubectl", "lxc",
+  "python", "pypy", "node", "nodejs", "bun", "deno", "tsx", "ts-node", "zx", "npx", "bunx", "pnpx", "perl", "ruby", "irb",
+  "php", "lua", "luajit", "osascript", "pwsh", "powershell", "Rscript", "R", "julia", "tclsh", "wish",
+  "awk", "gawk", "mawk", "nawk", "sed", "make", "gmake", "gdb", "lldb", "sqlite3", "psql", "mysql", "sftp", "ftp", "lftp",
+  "vim", "vi", "nvim", "ex", "ed", "emacs",
+  // Making a file executable is how a written body becomes a runnable script.
+  "chmod",
+]);
+
+/** Builtins that run a file or string as shell code, or rename a command, in command position. */
+const BODY_RUNNER_COMMANDS = new Set([".", "source", "eval", "env", "alias", "hash"]);
+
+/** Commands whose operands name files they write. */
+const FILE_WRITERS = new Set(["tee", "cp", "mv", "install", "ln"]);
+
+/**
+ * The only command words a command holding a data body may use: commands that
+ * read, write, move or delete files but never run their input or arguments as
+ * code, plus the Hasna record CLIs a body is usually filed through. The rest
+ * of the command is still analysed, so a delete here still counts. A list of
+ * runners can never be complete (`rbash`, `newgrp`, `sg`, `tclsh8.6`, any
+ * installed interpreter), so any other command word keeps the line-by-line
+ * analysis. `git` and `gh` are checked by subcommand (dataCommand).
+ */
+const DATA_COMMANDS = new Set([
+  "cat", "tac", "tee", "head", "tail", "wc", "cut", "tr", "nl", "rev", "fold", "fmt", "paste", "uniq",
+  "grep", "egrep", "fgrep", "jq", "diff", "cmp", "comm", "iconv", "od", "xxd", "hexdump",
+  "base64", "base32", "md5sum", "sha1sum", "sha224sum", "sha256sum", "sha384sum", "sha512sum", "b2sum", "cksum",
+  "echo", "printf", "true", "false", ":", "test", "[", "read", "cd", "pwd", "ls", "mkdir", "touch", "stat", "sleep",
+  "cp", "mv", "ln", "rm", "rmdir", "unlink", "shred", "trash",
+  "todos", "conversations", "mementos", "knowledge", "files", "asks",
+]);
+
+/** git subcommands that take a body only as a message, patch or blob. */
+const GIT_DATA_SUBCOMMANDS = new Set([
+  "add", "commit", "tag", "notes", "status", "diff", "log", "show", "rev-parse", "branch", "switch", "push", "fetch",
+  "hash-object", "apply",
+]);
+
+/** gh commands that take a body only as text or a request payload. */
+const GH_DATA_COMMANDS = new Set(["pr", "issue", "api", "release", "gist"]);
+
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*\+?=/;
+
+/**
+ * Whether the command word at `index` of `words` is a data command. git is
+ * accepted only with `-C <dir>`, `--no-pager` or `-P` before a data
+ * subcommand (`-c` can define an alias that runs a shell on stdin), and gh
+ * only for its built-in commands (an extension or shell alias can run
+ * anything).
+ */
+function dataCommand(words: string[], index: number): boolean {
+  const name = words[index];
+  if (name === "gh") return GH_DATA_COMMANDS.has(words[index + 1] ?? "");
+  if (name !== "git") return DATA_COMMANDS.has(name);
+  for (let at = index + 1; at < words.length; at++) {
+    const word = words[at];
+    if (word === "-C") at++;
+    else if (word === "--no-pager" || word === "-P") continue;
+    else return !word.startsWith("-") && GIT_DATA_SUBCOMMANDS.has(word);
+  }
+  return false;
+}
+
+const baseName = (word: string): string => word.split("/").pop() ?? "";
+
+/**
+ * Index of the `"` closing the one at `open`, past escapes and the
+ * substitutions inside it; -1 when there is none.
+ */
+function closingDoubleQuote(text: string, open: number): number {
+  for (let i = open + 1; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "\\") i++;
+    else if (ch === '"') return i;
+    else if (ch === "$" && text[i + 1] === "(") {
+      i = closingParen(text, i + 1);
+      if (i < 0) return -1;
+    } else if (ch === "\x60") {
+      i = text.indexOf("\x60", i + 1);
+      if (i < 0) return -1;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Index of the `)` closing the `(` at `open`, skipping quoted text and
+ * backtick substitutions; -1 when there is none.
+ */
+function closingParen(text: string, open: number): number {
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "\\") i++;
+    else if (ch === "'" || ch === "\x60") {
+      i = text.indexOf(ch, i + 1);
+      if (i < 0) return -1;
+    } else if (ch === '"') {
+      i = closingDoubleQuote(text, i);
+      if (i < 0) return -1;
+    } else if (ch === "(") depth++;
+    else if (ch === ")" && --depth === 0) return i;
+  }
+  return -1;
+}
+
+/**
+ * The text of every `$( )` and backtick command substitution in `text` at
+ * this level, inside double quotes or not (single quotes run nothing). Their
+ * own substitutions are found when each is scanned in turn. Null when the
+ * text cannot be followed, or an arithmetic `$(( ))` holds a substitution.
+ */
+function commandSubstitutions(text: string): string[] | null {
+  const found: string[] = [];
+  let inDouble = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "\\") i++;
+    else if (ch === "'" && !inDouble) {
+      const close = text.indexOf("'", i + 1);
+      if (close < 0) return null;
+      i = close;
+    } else if (ch === '"') inDouble = !inDouble;
+    else if (ch === "$" && text[i + 1] === "(") {
+      const close = closingParen(text, i + 1);
+      if (close < 0) return null;
+      const inner = text.slice(i + 2, close);
+      if (text[i + 2] === "(") {
+        if (/\$\(|\x60/.test(inner)) return null;
+      } else found.push(inner);
+      i = close;
+    } else if (ch === "\x60") {
+      const close = text.indexOf("\x60", i + 1);
+      if (close < 0) return null;
+      found.push(text.slice(i + 1, close));
+      i = close;
+    }
+  }
+  return inDouble ? null : found;
+}
+
+/**
+ * Whether anything in `command` (here-document bodies, terminators and
+ * operators already blanked) could execute a body, here or in a command
+ * substitution: a runner word anywhere; a process substitution; a variable
+ * assignment (`PATH=...` changes what a command word runs); or a command word
+ * that is not a data command (DATA_COMMANDS, dataCommand), is a path or an
+ * expansion, or is the bare name of a file the command writes. Text that
+ * cannot be parsed counts as yes.
+ */
+function mayRunBodies(command: string): boolean {
+  if (/[<>]\(/.test(command)) return true;
+  const segments: ReturnType<typeof lexCommand>["segments"] = [];
+  const queue = [command];
+  for (let parsed = 0; queue.length > 0; parsed++) {
+    if (parsed > 64) return true;
+    const text = queue.shift()!;
+    const lexed = lexCommand(text);
+    // lexCommand reports only top-level substitutions; one inside double
+    // quotes (`"$(sh <<'EOF' … )"`) runs just the same.
+    const nested = commandSubstitutions(text);
+    if (!lexed.trustworthy || !nested) return true;
+    segments.push(...lexed.segments);
+    queue.push(...new Set([...lexed.substitutions, ...nested]));
+  }
+  // Every file the command writes: redirect targets, writer operands, dd of=.
+  const written = new Set<string>();
+  for (const segment of segments) {
+    const words = segment.words.map((word) => decodeWord(word.text));
+    for (const at of segment.redirects) written.add(baseName(words[at] ?? ""));
+    const index = commandWordIndex(segment);
+    if (index < 0) continue;
+    const tool = baseName(words[index]);
+    if (FILE_WRITERS.has(tool)) {
+      for (const word of words.slice(index + 1)) if (!word.startsWith("-")) written.add(baseName(word));
+    }
+    if (tool === "dd") {
+      for (const word of words) if (word.startsWith("of=")) written.add(baseName(word.slice(3)));
+    }
+  }
+  written.delete("");
+  for (const segment of segments) {
+    for (const word of segment.words) {
+      const name = baseName(decodeWord(word.text));
+      if (BODY_RUNNERS.has(name) || /^(?:python|pypy|node|perl|ruby|php|lua)[0-9.]+$/.test(name)) return true;
+    }
+    const index = commandWordIndex(segment);
+    const words = segment.words
+      .map((word, at) => ({ text: decodeWord(word.text), at }))
+      .filter(({ at }) => !segment.redirects.has(at));
+    if (words.some(({ text, at }) => (index < 0 || at < index) && ASSIGNMENT.test(text))) return true;
+    if (index < 0) continue;
+    const raw = segment.words[index].text;
+    const name = decodeWord(raw);
+    if (/[$\x60]/.test(raw) || name.includes("/") || BODY_RUNNER_COMMANDS.has(name) || written.has(name)) return true;
+    if (!dataCommand(words.filter(({ at }) => at >= index).map(({ text }) => text), 0)) return true;
+  }
+  return false;
+}
+
+/**
+ * When every here-document body in `command` is data, the command with the
+ * bodies and their terminator lines blanked, and the bodies. A body is data
+ * when its delimiter is quoted, or it holds no `$( )` or backtick (expansion
+ * alone runs nothing), and nothing in the command can run it (mayRunBodies:
+ * every command word is a data command).
+ * Otherwise null: the command is analysed line by line as it stands.
+ */
+function dataHeredocs(command: string): { outer: string; bodies: string[] } | null {
+  if (!command.includes("<<")) return null;
+  const spans = heredocSpans(command);
+  if (!spans || spans.length === 0) return null;
+  const lines = command.split("\n");
+  const outer = [...lines];
+  const bodies: string[] = [];
+  for (const span of spans) {
+    const body = lines.slice(span.start, span.end);
+    if (!span.quoted && body.some((line) => /\$\(|\x60/.test(line))) return null;
+    bodies.push(body.join("\n"));
+    for (let k = span.start; k <= span.end; k++) outer[k] = "";
+  }
+  const lexed = [...outer];
+  for (const span of [...spans].reverse()) {
+    const line = lexed[span.line];
+    lexed[span.line] = line.slice(0, span.from) + " ".repeat(span.to - span.from) + line.slice(span.to);
+  }
+  return mayRunBodies(lexed.join("\n")) ? null : { outer: outer.join("\n"), bodies };
+}
+
+/**
+ * A directory outside every protected root. A data body is analysed as if run
+ * from here, so only a protected path it names, or reaches with its own `cd`,
+ * can count; its other words never resolve against the real cwd.
+ */
+const DETACHED_CWD = "/";
+
+/**
+ * Extract protected-repo-checkout targets from a Bash command. Here-document
+ * bodies that are data (dataHeredocs) are analysed on their own from
+ * DETACHED_CWD; the rest of the command is analysed by segmentTargets.
+ */
+export function bashTargets(command: string, home: string, cwd: string): PathTarget[] {
+  if (!command) return [];
+  const data = dataHeredocs(command);
+  if (!data) return segmentTargets(command, home, cwd);
+  return [...segmentTargets(data.outer, home, cwd), ...data.bodies.flatMap((body) => bashTargets(body, home, DETACHED_CWD))];
+}
+
 /**
  * Extract protected-repo-checkout targets from a Bash command. Recognises
  * explicit `~/...`, `$HOME/...`, `${HOME}/...` and literal-home references
@@ -519,7 +928,7 @@ const REL_OPERAND = /(?:^|\s)(\.\.?|[^\s"';&|<>()\x60/]+(?:\/[^\s"';&|<>()\x60]*
  * pipeline or the background does not change the outer cwd, and a cd that
  * cannot be resolved statically never narrows it.
  */
-export function bashTargets(command: string, home: string, cwd: string): PathTarget[] {
+function segmentTargets(command: string, home: string, cwd: string): PathTarget[] {
   if (!command) return [];
   const roots = protectedRoots(home);
   const underRoot = (path: string) => roots.some((root) => path === root || path.startsWith(`${root}${sep}`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {