@mmerterden/multi-agent-pipeline 20.27.2 → 20.29.0

package/pipeline/scripts/_guard_rules.py

@@ -0,0 +1,605 @@
+"""Command rules agent-guard.py applies attended and unattended alike.
+
+None of these executes anything. The only side effects are reading a commit or
+PR message file the command names (bounded by MAX_FILE_BYTES), because a
+message given with `-F file` is invisible to a rule that reads argv alone, and
+consuming a confirmation record (confirm-command.mjs) the user's answer left.
+
+A rule judges a program only where it is the segment's command word: after
+any VAR=value assignments and the wrappers in WRAPPERS. Text that merely
+mentions `git push --no-verify` (an echo, a printf, a heredoc commit message)
+is not that program. Heredoc bodies are removed before these rules see the
+line (strip_heredoc_bodies); the attribution rules read them separately, since
+a body is where a commit message usually is.
+
+  command_segments(cmd)    the simple commands of a line, heredoc bodies out
+  command_word(toks)       (assignments, argv) with wrappers stripped
+  no_verify(toks)          a git commit / push / merge that skips the repo's
+                           git hooks (--no-verify and its prefixes, commit -n,
+                           -c core.hooksPath, HUSKY=0, GIT_CONFIG_* hooksPath),
+                           or a `git config core.hooksPath` write
+  message_text(cmd, cwd)   the commit message text a line carries
+  ask_reason(toks, seg)    a write a person should confirm: closing a GitHub
+                           issue, a PR body that closes one, a Jira transition
+  confirmed(cmd)           a fresh confirmation of exactly this command
+  read_only_*              a commit, push or file write into a repository
+                           listed in prefs.global.readOnlyRepos
+"""
+import hashlib
+import json
+import os
+import re
+import shlex
+import time
+
+MAX_FILE_BYTES = 256 * 1024
+CONFIRM_TTL_SECONDS = 600
+
+# Closing keywords GitHub acts on, followed by an issue reference.
+CLOSING = re.compile(
+    r"\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\b\s*:?\s+(?:[\w.-]+/[\w.-]+)?#\d+",
+    re.IGNORECASE,
+)
+# "Generated by AI", "generated with an AI assistant"; never "ai-sdk".
+AI_GENERATED = re.compile(
+    r"generated\s+(?:by|with)\s+(?:an?\s+)?(?:[\w-]+\s+){0,3}?ai\b(?![-\w])",
+    re.IGNORECASE,
+)
+JIRA_TRANSITION = re.compile(r"/rest/api/(?:\d+|latest)/issue/[^/\s'\"]+/transitions\b", re.IGNORECASE)
+POST_METHOD = re.compile(r"(?:^|\s)(?:-X|--request)\s*=?\s*['\"]?post\b", re.IGNORECASE)
+BODY_FLAG = re.compile(r"(?:^|\s)(?:-d|--data[\w-]*|--json|-F|--form)(?:\s|=|$)")
+HEREDOC_OPEN = re.compile(r"<<(-?)\s*(['\"]?)([A-Za-z_][A-Za-z0-9_]*)\2")
+ASSIGN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
+
+GIT_VALUE_OPTIONS = {"-C", "-c", "--git-dir", "--work-tree", "--exec-path", "--namespace"}
+COMMIT_VALUE_LETTERS = set("mFCct")
+COMMIT_VALUE_LONG = {
+    "--message", "--file", "--reuse-message", "--reedit-message", "--template", "--author",
+    "--date", "--fixup", "--squash", "--trailer", "--cleanup", "--pathspec-from-file",
+}
+HOOK_SKIPPING_SUBS = {"commit", "push", "merge"}
+NO_VERIFY_MIN = "--no-veri"
+GH_ALIASES = {"i": "issue", "pr": "pr", "co": "pr"}
+WRITE_SUBS = {"commit", "push", "merge", "cherry-pick", "revert", "am", "rebase", "tag"}
+HTTP_CLIENTS = {"curl", "wget", "http", "https", "xh"}
+# Wrappers that run the rest of the line as the command, with the options
+# that take a value.
+WRAPPERS = {
+    "sudo": {"-u", "-g", "-h", "-p", "-C", "-D", "-r", "-t", "-U"},
+    "doas": {"-u", "-C"},
+    "command": set(),
+    "builtin": set(),
+    "exec": {"-a"},
+    "env": {"-u", "--unset", "-C", "--chdir", "-S", "--split-string"},
+    "xargs": {"-I", "-L", "-n", "-P", "-s", "-d", "-E", "-a"},
+    "nice": {"-n"},
+    "nohup": set(),
+    "time": set(),
+    "timeout": {"-s", "-k", "--signal", "--kill-after"},
+}
+
+
+def strip_heredoc_bodies(cmd):
+    """(cmd without heredoc bodies, [bodies]). Line-based and lenient: a body
+    runs from the line after `<<DELIM` to the line that is DELIM (tabs allowed
+    before it for `<<-`); an unterminated one runs to the end."""
+    lines = cmd.split("\n")
+    out, bodies, pending, i = [], [], [], 0
+    while i < len(lines):
+        line = lines[i]
+        out.append(line)
+        pending.extend((m.group(1) == "-", m.group(3)) for m in HEREDOC_OPEN.finditer(line))
+        i += 1
+        while pending and i <= len(lines):
+            dash, delim = pending.pop(0)
+            body = []
+            while i < len(lines):
+                cand = lines[i].lstrip("\t") if dash else lines[i]
+                i += 1
+                if cand.strip() == delim:
+                    break
+                body.append(lines[i - 1])
+            bodies.append("\n".join(body))
+    return "\n".join(out), bodies
+
+
+def split_simple(cmd):
+    """Simple-command segments, split on `;`, `&&`, `||`, `|`, newlines and
+    unquoted `(`, `)` and backticks. Quote-aware, so an operator inside a quoted
+    commit message is text."""
+    segs, cur, q, i = [], [], None, 0
+    while i < len(cmd):
+        c = cmd[i]
+        if q == "'":
+            cur.append(c)
+            q = None if c == "'" else q
+            i += 1
+            continue
+        if c == "\\" and i + 1 < len(cmd):
+            cur.append(cmd[i:i + 2])
+            i += 2
+            continue
+        if q == '"':
+            if c == '"':
+                q = None
+                cur.append(c)
+            elif cmd.startswith("$(", i):
+                segs.append("".join(cur))
+                cur = []
+                i += 2
+                continue
+            else:
+                cur.append(c)
+            i += 1
+            continue
+        if c in ("'", '"'):
+            q = c
+            cur.append(c)
+            i += 1
+            continue
+        two = cmd[i:i + 2]
+        if two in ("&&", "||", "|&"):
+            segs.append("".join(cur))
+            cur = []
+            i += 2
+            continue
+        if c in (";", "|", "\n", "(", ")", "`"):
+            segs.append("".join(cur))
+            cur = []
+            i += 1
+            continue
+        cur.append(c)
+        i += 1
+    segs.append("".join(cur))
+    return [s for s in segs if s.strip()]
+
+
+# shlex grows a token one character at a time, so a megabyte argument takes
+# longer than the guard's deadline. Past this length a segment is split on
+# whitespace with quotes and backslashes removed, as agent-guard.tokenize does.
+SHLEX_MAX_CHARS = 16384
+
+
+def tokens(seg):
+    if len(seg) > SHLEX_MAX_CHARS:
+        return [re.sub(r"[\"'\\]", "", t) for t in seg.split()]
+    try:
+        return shlex.split(seg)
+    except ValueError:
+        return seg.split()
+
+
+def command_segments(cmd):
+    """[(segment, tokens)] for the simple commands of a line, bodies removed."""
+    stripped, _ = strip_heredoc_bodies(cmd)
+    return [(s, tokens(s)) for s in split_simple(stripped)]
+
+
+def command_word(toks):
+    """(assignments, argv): leading VAR=value assignments (and those `env`
+    sets), then the command with the WRAPPERS in front of it consumed."""
+    assigns, i = [], 0
+    while i < len(toks):
+        t = toks[i]
+        if ASSIGN.match(t):
+            assigns.append(t)
+            i += 1
+            continue
+        base = os.path.basename(t)
+        if base not in WRAPPERS:
+            break
+        value_opts = WRAPPERS[base]
+        i += 1
+        while i < len(toks) and (toks[i].startswith("-") or (base == "env" and ASSIGN.match(toks[i]))):
+            if ASSIGN.match(toks[i]):
+                assigns.append(toks[i])
+            elif toks[i] in value_opts:
+                i += 1
+            i += 1
+        if base == "timeout" and i < len(toks) and re.match(r"^[0-9]", toks[i]):
+            i += 1
+    return assigns, toks[i:]
+
+
+def _git_split(toks):
+    """(assignments, global_options, subcommand, args) when the segment's
+    command word is git, else None."""
+    assigns, argv = command_word(toks)
+    if not argv or os.path.basename(argv[0]).lower() != "git":
+        return None
+    opts, j = [], 1
+    while j < len(argv):
+        o = argv[j]
+        if o in GIT_VALUE_OPTIONS:
+            opts.append((o, argv[j + 1] if j + 1 < len(argv) else ""))
+            j += 2
+        elif o.startswith("-"):
+            key, _, val = o.partition("=")
+            opts.append((key, val))
+            j += 1
+        else:
+            return assigns, opts, o.lower(), argv[j + 1:]
+    return None
+
+
+def _hookspath_assign(assigns):
+    for a in assigns:
+        name, _, val = a.partition("=")
+        low = val.lower().replace(" ", "")
+        if name == "HUSKY" and low in ("0", "false"):
+            return "HUSKY=0 switches the repository's git hooks off"
+        if (name == "GIT_CONFIG_PARAMETERS" or name.startswith("GIT_CONFIG_KEY_")) and "hookspath" in low:
+            return f"{name} overrides core.hooksPath and skips the repository's git hooks"
+    return None
+
+
+def no_verify(toks):
+    """A reason when the segment skips the repository's own git hooks."""
+    assigns, argv = command_word(toks)
+    if argv and argv[0] == "export":
+        reason = _hookspath_assign([a for a in argv[1:] if ASSIGN.match(a)])
+        if reason:
+            return reason
+    split = _git_split(toks)
+    if not split:
+        return None
+    assigns, opts, sub, args = split
+    if sub == "config":
+        reading = {"--get", "--get-all", "--get-regexp", "--list", "-l", "--unset", "--unset-all", "--show-origin"}
+        keys = [a for a in args if not a.startswith("-")]
+        if keys and keys[0].lower() == "core.hookspath" and len(keys) > 1 and not reading & set(args):
+            return "git config core.hooksPath points git away from the repository's hooks"
+        return None
+    if sub not in HOOK_SKIPPING_SUBS:
+        return None
+    reason = _hookspath_assign(assigns)
+    if reason:
+        return reason
+    for key, val in opts:
+        if key == "-c" and val.lower().replace(" ", "").startswith("core.hookspath="):
+            return f"git {sub} with core.hooksPath overridden skips the repository's git hooks"
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a == "--":
+            break
+        if len(a) >= len(NO_VERIFY_MIN) and "--no-verify".startswith(a):
+            return f"git {sub} {a} skips the repository's git hooks"
+        if sub == "commit":
+            if a in COMMIT_VALUE_LONG:
+                i += 2
+                continue
+            if a.startswith("-") and not a.startswith("--") and len(a) > 1:
+                for ch in a[1:]:
+                    if ch == "n":
+                        return "git commit -n skips the repository's git hooks"
+                    if ch in COMMIT_VALUE_LETTERS:
+                        if ch == a[-1]:
+                            i += 1  # the value is the next token
+                        break
+        i += 1
+    return None
+
+
+def message_files(toks):
+    """Paths a `git commit` reads its message from (`-F`, `--file`)."""
+    split = _git_split(toks)
+    if not split or split[2] != "commit":
+        return []
+    out, args, i = [], split[3], 0
+    while i < len(args):
+        a = args[i]
+        if a in ("-F", "--file"):
+            if i + 1 < len(args):
+                out.append(args[i + 1])
+            i += 2
+            continue
+        if a.startswith("--file="):
+            out.append(a.split("=", 1)[1])
+        elif a.startswith("-") and not a.startswith("--") and "F" in a[1:]:
+            rest = a[a.index("F") + 1:]
+            if rest:
+                out.append(rest)
+            elif i + 1 < len(args):
+                out.append(args[i + 1])
+                i += 1
+        i += 1
+    return [p for p in out if p and p != "-"]
+
+
+def _message_args(toks):
+    split = _git_split(toks)
+    if not split or split[2] != "commit":
+        return []
+    out, args, i = [], split[3], 0
+    while i < len(args):
+        a = args[i]
+        if a in ("-m", "--message"):
+            if i + 1 < len(args):
+                out.append(args[i + 1])
+            i += 2
+            continue
+        if a.startswith("--message="):
+            out.append(a.split("=", 1)[1])
+        elif a.startswith("-m") and len(a) > 2:
+            out.append(a[2:])
+        i += 1
+    return out
+
+
+def message_text(cmd, cwd):
+    """The commit message text a line carries: -m values, -F files and, when
+    the line commits, its heredoc bodies (the `-F -` and `$(cat <<EOF)` forms)."""
+    stripped, bodies = strip_heredoc_bodies(cmd)
+    parts, commits = [], False
+    for seg in split_simple(stripped):
+        toks = tokens(seg)
+        split = _git_split(toks)
+        if not split or split[2] != "commit":
+            continue
+        commits = True
+        parts.extend(_message_args(toks))
+        parts.extend(read_bounded(p, cwd) for p in message_files(toks))
+    if commits:
+        parts.extend(bodies)
+    return "\n".join(parts)
+
+
+def commit_text(cmd, cwd):
+    """What a commit on this line records: every word of each git commit
+    segment (its -m, --author, --trailer and -c values), the -F files it
+    names, the line's heredoc bodies, and the values assigned to variables
+    on the line, which a message can expand. The other commands on the line
+    are left out, so an echo beside a commit is not its message, unless the
+    commit reads a message file the hook cannot judge from disk: one that does
+    not exist yet, or one the same line writes. Then the whole line counts,
+    since the text the file will hold is on it."""
+    stripped, bodies = strip_heredoc_bodies(cmd)
+    parts, assigned, others, files, commits = [], [], [], [], False
+    for seg in split_simple(stripped):
+        toks = tokens(seg)
+        assigned.extend(t.partition("=")[2] for t in toks if ASSIGN.match(t))
+        split = _git_split(toks)
+        if not split or split[2] != "commit":
+            others.append(seg)
+            continue
+        commits = True
+        parts.extend(toks)
+        for path in message_files(toks):
+            files.append(path)
+            parts.append(read_bounded(path, cwd))
+    if not commits:
+        return ""
+    if any(_unjudged_message_file(f, cwd, others) for f in files):
+        parts.append(stripped)
+    return "\n".join(parts + bodies + assigned)
+
+
+def _unjudged_message_file(path, cwd, others):
+    """True when a -F file's text on disk is not what the commit will read:
+    it is missing, or another command on the line names it (a redirect or
+    tee writing it before the commit runs)."""
+    if path == "-":
+        return False
+    p = os.path.expanduser(path)
+    if not os.path.isabs(p):
+        p = os.path.join(cwd or os.getcwd(), p)
+    if not os.path.isfile(p):
+        return True
+    names = {path, os.path.basename(path)}
+    return any(n and n in seg for seg in others for n in names)
+
+
+def ai_generated(cmd, cwd):
+    """True when the commit message says it was generated by an AI."""
+    return bool(AI_GENERATED.search(message_text(cmd, cwd)))
+
+
+def read_bounded(path, cwd):
+    """The text of a message file, or "" when it cannot be read."""
+    p = os.path.expanduser(path)
+    if not os.path.isabs(p):
+        p = os.path.join(cwd or os.getcwd(), p)
+    try:
+        if not os.path.isfile(p):
+            return ""
+        with open(p, "rb") as fh:
+            return fh.read(MAX_FILE_BYTES).decode("utf-8", "replace")
+    except OSError:
+        return ""
+
+
+def _flag_values(args, names, short=None):
+    vals, i = [], 0
+    while i < len(args):
+        a = args[i]
+        if a in names or (short and a == short):
+            if i + 1 < len(args):
+                vals.append(args[i + 1])
+            i += 2
+            continue
+        for n in names:
+            if a.startswith(n + "="):
+                vals.append(a.split("=", 1)[1])
+        i += 1
+    return vals
+
+
+def _gh_ask(argv, cwd):
+    if not argv or os.path.basename(argv[0]) != "gh":
+        return None
+    args = argv[1:]
+    cleaned, i = [], 0
+    while i < len(args):
+        if args[i] in ("-R", "--repo"):
+            i += 2
+            continue
+        cleaned.append(args[i])
+        i += 1
+    plains = [a for a in cleaned if not a.startswith("-")]
+    if not plains:
+        return None
+    group = GH_ALIASES.get(plains[0], plains[0])
+    sub = plains[1] if len(plains) > 1 else ""
+    if group == "issue" and sub == "close":
+        return "gh issue close closes a tracked issue; the user confirms every issue closure"
+    if group == "pr" and sub in ("create", "edit"):
+        bodies = _flag_values(cleaned, {"--body"}, "-b")
+        bodies += [read_bounded(p, cwd) for p in _flag_values(cleaned, {"--body-file"}, "-F")]
+        if any(CLOSING.search(b or "") for b in bodies):
+            return (
+                f"gh pr {sub} with a closing keyword (Closes/Fixes/Resolves #N) closes the issue on merge; "
+                "use Ref: #N or Related: #N, or confirm the closure"
+            )
+    if group == "api":
+        joined = " ".join(cleaned)
+        if re.search(r"issues/\d+\b", joined) and re.search(r"\bstate=closed\b", joined):
+            return "gh api closing an issue (state=closed); the user confirms every issue closure"
+    return None
+
+
+def _jira_ask(argv, seg):
+    if not argv or os.path.basename(argv[0]) not in HTTP_CLIENTS:
+        return None
+    if not JIRA_TRANSITION.search(seg):
+        return None
+    if POST_METHOD.search(seg) or BODY_FLAG.search(seg):
+        return "a Jira transition POST moves the issue through its workflow; the user confirms each transition"
+    return None
+
+
+def ask_reason(toks, seg, cwd=None):
+    """Why a person should confirm this segment, or None."""
+    _, argv = command_word(toks)
+    return _gh_ask(argv, cwd) or _jira_ask(argv, seg)
+
+
+# --- confirmations ---------------------------------------------------------------
+
+
+def confirmations_dir(env=None):
+    env = os.environ if env is None else env
+    root = env.get("LOGS_ROOT") or os.path.join(os.path.expanduser("~"), ".claude", "logs", "multi-agent")
+    return os.path.join(root, "confirmations")
+
+
+def command_digest(cmd):
+    return hashlib.sha256(cmd.encode("utf-8")).hexdigest()
+
+
+def confirmed(cmd, env=None):
+    """True, and the record consumed, when confirm-command.mjs recorded the
+    user's yes for exactly this command less than CONFIRM_TTL_SECONDS ago."""
+    if not isinstance(cmd, str) or not cmd:
+        return False
+    path = os.path.join(confirmations_dir(env), command_digest(cmd) + ".json")
+    try:
+        fresh = time.time() - os.stat(path).st_mtime < CONFIRM_TTL_SECONDS
+    except OSError:
+        return False
+    try:
+        os.remove(path)
+    except OSError:
+        return False
+    return fresh
+
+
+# --- read-only repositories ----------------------------------------------------
+
+
+def prefs_candidates(env=None):
+    env = os.environ if env is None else env
+    home = env.get("HOME") or os.path.expanduser("~")
+    return [
+        p
+        for p in (
+            env.get("MULTI_AGENT_PREFS"),
+            os.path.join(home, ".claude", "multi-agent-preferences.json"),
+            os.path.join(home, ".config", "multi-agent-pipeline", "multi-agent-preferences.json"),
+        )
+        if p
+    ]
+
+
+def read_only_roots(env=None):
+    """prefs.global.readOnlyRepos[], expanded and real-pathed."""
+    for p in prefs_candidates(env):
+        if not os.path.isfile(p):
+            continue
+        try:
+            with open(p, encoding="utf-8") as fh:
+                roots = (json.load(fh).get("global") or {}).get("readOnlyRepos") or []
+        except (OSError, ValueError, AttributeError):
+            return []
+        out = []
+        for r in roots if isinstance(roots, list) else []:
+            if isinstance(r, str) and r.strip():
+                out.append(os.path.realpath(os.path.expanduser(r.strip())))
+        return out
+    return []
+
+
+def _under(path, root):
+    a = os.path.normcase(path)
+    b = os.path.normcase(root)
+    return a == b or a.startswith(b.rstrip(os.sep) + os.sep)
+
+
+def read_only_root_of(path, roots):
+    """The read-only root that contains `path`, or None."""
+    if not path or not roots:
+        return None
+    real = os.path.realpath(os.path.expanduser(path))
+    for r in roots:
+        if _under(real, r):
+            return r
+    return None
+
+
+def git_write_dir(toks, cwd):
+    """(subcommand, directory) for a git call that writes history or a remote."""
+    split = _git_split(toks)
+    if not split or split[2] not in WRITE_SUBS:
+        return None
+    _, opts, sub, _ = split
+    base = cwd or os.getcwd()
+    for key, val in opts:
+        if key in ("-C", "--work-tree") and val:
+            base = val if os.path.isabs(val) else os.path.join(base, val)
+        elif key == "--git-dir" and val:
+            base = os.path.dirname(val.rstrip("/")) if os.path.isabs(val) else os.path.join(base, val, "..")
+    return sub, os.path.normpath(base)
+
+
+_ROOTS = {"loaded": False, "roots": []}
+
+
+def cached_read_only_roots():
+    if not _ROOTS["loaded"]:
+        _ROOTS["roots"], _ROOTS["loaded"] = read_only_roots(), True
+    return _ROOTS["roots"]
+
+
+def read_only_file_reason(path, cwd):
+    """Why an Edit / Write to `path` is refused, or None."""
+    if not isinstance(path, str) or not path:
+        return None
+    p = os.path.expanduser(path)
+    if not os.path.isabs(p):
+        p = os.path.join(cwd or os.getcwd(), p)
+    root = read_only_root_of(p, cached_read_only_roots())
+    if root:
+        return f"{path} is inside {root}, which prefs.global.readOnlyRepos lists as read-only"
+    return None
+
+
+def read_only_git_reason(toks, cwd):
+    """Why a git commit / push (or another history write) is refused, or None."""
+    hit = git_write_dir(toks, cwd)
+    if not hit:
+        return None
+    sub, directory = hit
+    root = read_only_root_of(directory, cached_read_only_roots())
+    if root:
+        return f"git {sub} in {root}, which prefs.global.readOnlyRepos lists as read-only"
+    return None