obey-cli 0.1.0__py3-none-any.whl

obey_cli/enforce/templates/obey_hook.py

@@ -0,0 +1,452 @@
+#!/usr/bin/env python3
+"""obey hook: blocks agent actions that break a rule in .obey/hooks/rules.json.
+
+Generated by obey (https://github.com/B0yko/obey); remove with `obey enforce --remove`. Standard library only,
+Python 3.9+. Usage, as the agents' hook configs call it:
+
+    python3 .obey/hooks/obey_hook.py <claude|codex|cursor|gemini|copilot|opencode> [stop]
+
+The payload arrives on stdin. A violation produces the agent's own deny format. Any internal error allows the
+action and prints a warning (fail open), so a bug here can never lock you out of your agent.
+
+Paths are taken relative to the project this script is installed in; a relative path is resolved against the
+payload's cwd, and symlinks are followed. The stop event checks only what the agent itself changed in the session
+(from a Claude Code transcript), and gives up after MAX_STOP_BLOCKS blocked stops in a row.
+"""
+
+import hashlib
+import json
+import os
+import shlex
+import subprocess
+import sys
+import tempfile
+import time
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+
+# Blocked Stop events in a row that end the blocking, so a rule that cannot be met never traps an agent.
+MAX_STOP_BLOCKS = 3
+
+
+def _project_root():
+    """The project this hook was installed into (<root>/.obey/hooks/obey_hook.py), wherever the agent's cwd is."""
+    return os.path.dirname(os.path.dirname(HERE))
+
+
+def _payload_cwd(payload, root):
+    cwd = payload.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR") or os.environ.get("GEMINI_PROJECT_DIR")
+    if not isinstance(cwd, str) or not cwd:
+        return root
+    return cwd if os.path.isabs(cwd) else os.path.join(root, cwd)
+
+
+def _under(path, root):
+    try:
+        rel = os.path.relpath(path, root)
+    except ValueError:
+        return None
+    if rel == ".." or rel.startswith(".." + os.sep):
+        return None
+    return rel.replace(os.sep, "/")
+
+
+def _rel_forms(path, root, cwd, follow=True):
+    """Repo-relative spellings of a path: as written (lexically normalised), then with symlinks resolved.
+
+    A relative path is taken against `cwd`. Both spellings are checked against the rules, so a link into a protected
+    directory (src/link -> ../secrets) and a repo reached through an alias are both seen. `follow=False` keeps the
+    last component as it is (rm and mv act on the link itself).
+    """
+    if not path:
+        return [""]
+    full = path if os.path.isabs(path) else os.path.join(cwd or root, path)
+    if follow:
+        resolved = os.path.realpath(full)
+    else:
+        resolved = os.path.join(os.path.realpath(os.path.dirname(full)), os.path.basename(full))
+    real_root = os.path.realpath(root)
+    forms = []
+    for cand in (os.path.normpath(full), resolved):
+        for base in (root, real_root):
+            rel = _under(cand, base)
+            if rel is not None and rel not in forms:
+                forms.append(rel)
+    return forms or [os.path.relpath(resolved, real_root).replace(os.sep, "/")]
+
+
+def _read(path):
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            return fh.read()
+    except OSError:
+        return None
+
+
+def _args(value):
+    if isinstance(value, str):
+        try:
+            value = json.loads(value)
+        except ValueError:
+            return {"command": value}
+    return value if isinstance(value, dict) else {}
+
+
+def _file_actions(kind, path, root, cwd, old=None, new=None, content=None):
+    """Actions for a file edit or write: one per spelling of the path (see _rel_forms)."""
+    actions = []
+    for rel in _rel_forms(path, root, cwd):
+        current = _read(os.path.join(os.path.realpath(root), rel))
+        action = {"kind": kind, "path": rel, "exists": current is not None}
+        if kind == "edit":
+            action.update({"old": old or "", "new": new or ""})
+            if current is not None and old and old in current:
+                action["new_content"] = current.replace(old, new or "", 1)
+            action["current"] = current
+        elif kind == "write":
+            action["content"] = content or ""
+            action["current"] = current
+        actions.append(action)
+    return actions
+
+
+def _delete_actions(path, root, cwd):
+    return [{"kind": "delete", "path": rel, "exists": True} for rel in _rel_forms(path, root, cwd, follow=False)]
+
+
+def _shell_action(command, root, cwd):
+    """A shell action with the files it writes, resolved against the working directory and symlinks.
+
+    Writes to files that exist are what an existing_only rule forbids, so the action also lists the targets that
+    exist on disk.
+    """
+    import obey_engine
+
+    action = {"kind": "shell", "command": command}
+    targets = obey_engine.shell_write_targets(command)
+    if targets:
+        real_root = os.path.realpath(root)
+        resolved, existing = [], []
+        for target in targets:
+            if target["path"] == "*":
+                resolved.append(target)
+                continue
+            for rel in _rel_forms(target["path"], root, cwd, follow=target["op"] == "write"):
+                resolved.append({"path": rel, "op": target["op"]})
+                if os.path.lexists(os.path.join(real_root, rel)):
+                    existing.append(rel)
+        action["targets"] = resolved
+        action["existing_paths"] = existing
+    return action
+
+
+def _patch_actions(patch, root, cwd):
+    """Actions from an apply_patch envelope (*** Begin Patch / *** Update File: path / +line / -line)."""
+    actions, current, kind, added, removed = [], None, None, [], []
+
+    def flush():
+        if current is not None:
+            if kind == "delete":
+                actions.extend(_delete_actions(current, root, cwd))
+            elif kind == "add":
+                actions.extend(_file_actions("write", current, root, cwd, content="\n".join(added)))
+            else:
+                actions.extend(_file_actions("edit", current, root, cwd, old="\n".join(removed), new="\n".join(added)))
+
+    for line in patch.splitlines():
+        for marker, k in (("*** Add File: ", "add"), ("*** Update File: ", "update"), ("*** Delete File: ", "delete")):
+            if line.startswith(marker):
+                flush()
+                current, kind, added, removed = line[len(marker) :].strip(), k, [], []
+                break
+        else:
+            if line.startswith("*** Move to: ") and current is not None:
+                actions.extend(_delete_actions(current, root, cwd))
+                current = line[len("*** Move to: ") :].strip()
+            elif line.startswith("+") and not line.startswith("+++"):
+                added.append(line[1:])
+            elif line.startswith("-") and not line.startswith("---"):
+                removed.append(line[1:])
+    flush()
+    return actions
+
+
+def actions_from(agent, payload, root, cwd=None):
+    """Normalise one agent's pre-tool payload into engine actions."""
+    cwd = cwd or root
+    if agent in ("claude", "codex", "gemini") or (agent == "copilot" and "tool_name" in payload):
+        tool = payload.get("tool_name", "")
+        data = _args(payload.get("tool_input"))
+    elif agent == "copilot":
+        tool, data = payload.get("toolName", ""), _args(payload.get("toolArgs"))
+    elif agent == "cursor":
+        if "command" in payload and "tool_name" not in payload:
+            return [_shell_action(_command_text(payload.get("command", "")), root, cwd)]
+        tool, data = payload.get("tool_name", ""), _args(payload.get("tool_input"))
+    elif agent == "opencode":
+        tool, data = payload.get("tool", ""), _args(payload.get("args"))
+    else:
+        return []
+    name = str(tool)
+    low = name.lower()
+    command = data.get("command")
+    if low in ("bash", "shell", "run_shell_command", "powershell") or (low == "" and command):
+        return [_shell_action(_command_text(command), root, cwd)]
+    if low == "apply_patch":
+        patch = data.get("command") or data.get("patch") or data.get("input") or data.get("patchText") or ""
+        if isinstance(patch, list):
+            patch = "\n".join(str(p) for p in patch)
+        return _patch_actions(str(patch), root, cwd)
+    path = (
+        data.get("file_path")
+        or data.get("filePath")
+        or data.get("path")
+        or data.get("notebook_path")
+        or data.get("target_file")
+        or ""
+    )
+    if low in ("write", "write_file", "create"):
+        content = data.get("content") or data.get("file_text") or data.get("fileText") or data.get("contents") or ""
+        return _file_actions("write", path, root, cwd, content=str(content))
+    if low in ("edit", "replace", "str_replace_editor", "notebookedit", "multiedit"):
+        if isinstance(data.get("edits"), list):
+            old = "\n".join(str(e.get("old_string", "")) for e in data["edits"] if isinstance(e, dict))
+            new = "\n".join(str(e.get("new_string", "")) for e in data["edits"] if isinstance(e, dict))
+        else:
+            old = data.get("old_string") or data.get("oldString") or data.get("old_str") or ""
+            new = data.get("new_string") or data.get("newString") or data.get("new_str") or data.get("new_source") or ""
+        return _file_actions("edit", path, root, cwd, old=str(old), new=str(new))
+    if low in ("delete", "delete_file"):
+        return _delete_actions(path, root, cwd)
+    return []
+
+
+def _command_text(command):
+    """The command line: a string, or an argv list (a Codex shell call) joined the way a shell would read it."""
+    if isinstance(command, (list, tuple)):
+        return shlex.join(str(c) for c in command)
+    return str(command or "")
+
+
+def deny_output(agent, reason):
+    if agent in ("claude", "codex"):
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": reason,
+            }
+        }
+    if agent == "copilot":
+        return {"permissionDecision": "deny", "permissionDecisionReason": reason}
+    if agent == "gemini":
+        return {"decision": "deny", "reason": reason}
+    if agent == "cursor":
+        return {"permission": "deny", "user_message": reason, "agent_message": reason}
+    if agent == "opencode":
+        return {"deny": reason}
+    return {"deny": reason}
+
+
+def stop_output(agent, reason):
+    if agent in ("claude", "codex", "copilot"):
+        return {"decision": "block", "reason": reason}
+    if agent == "gemini":
+        return {"decision": "deny", "reason": reason}
+    if agent == "cursor":
+        return {"followup_message": reason}
+    return {}
+
+
+def warn_output(agent, message):
+    if agent in ("claude", "codex"):
+        return {"systemMessage": message}
+    return None
+
+
+def _git(root, *args):
+    try:
+        out = subprocess.run(["git", *args], cwd=root, capture_output=True, timeout=20, check=False)
+        return out.stdout.decode("utf-8", "replace") if out.returncode == 0 else ""
+    except (OSError, subprocess.SubprocessError):
+        return ""
+
+
+def _working_tree_diff(root, paths=None):
+    """The uncommitted changes as a git diff, untracked files as new-file diffs; only those in `paths` when given."""
+    import obey_engine
+
+    if paths is not None and not paths:
+        return ""
+    spec = ["--", *sorted(paths)] if paths is not None else []
+    diff = _git(root, "--literal-pathspecs", "diff", "HEAD", "--relative", "--no-color", "--no-ext-diff", *spec)
+    for path in _git(root, "ls-files", "--others", "--exclude-standard", "-z").split("\0"):
+        if path and not path.startswith(".obey/") and (paths is None or path in paths):
+            text = _read(os.path.join(root, path))
+            if text is not None:
+                diff += obey_engine.new_file_diff(path, text)
+    return diff
+
+
+def _agent_changes(events, root):
+    """Repo-relative paths that the agent's edits and shell commands wrote; None when a command's targets are unknown.
+
+    Event paths are rewritten to repo-relative ones, so the rules' globs match them.
+    """
+    import obey_engine
+
+    paths = set()
+    for ev in events:
+        if ev.get("denied"):
+            continue
+        kind = ev.get("type")
+        if kind in ("edit", "write", "delete") and ev.get("path"):
+            forms = _rel_forms(ev["path"], root, root)
+            ev["path"] = forms[0]
+            paths.update(forms)
+        elif kind == "shell":
+            for target in obey_engine.shell_write_targets(ev.get("command") or ""):
+                if target["path"] == "*":
+                    return None
+                paths.update(_rel_forms(target["path"], root, root, follow=target["op"] == "write"))
+    return paths
+
+
+def _stop_run(root, payload):
+    """(run record for the stop-time checks, whether the agent's commands are known).
+
+    With a Claude Code transcript the record holds the agent's own edits and commands, and only the files they
+    touched count as changed, so the user's uncommitted work never triggers a block. Without one (other agents) it
+    is the whole working tree and the commands are unknown.
+    """
+    import obey_engine
+
+    events, known, paths = [], False, None
+    transcript = payload.get("transcript_path") or payload.get("transcriptPath")
+    if isinstance(transcript, str) and os.path.exists(transcript):
+        text = _read(transcript) or ""
+        if obey_engine.transcript_recognized(text):
+            events, known = obey_engine.events_from_transcript(text, root), True
+            paths = _agent_changes(events, root)
+    final = payload.get("last_assistant_message") or payload.get("prompt_response") or ""
+    run = {
+        "events": events,
+        "diff": _working_tree_diff(root, paths),
+        "base_files": [p for p in _git(root, "ls-files", "-z").split("\0") if p],
+        "commits": [],
+        "pushed_refs": [],
+        "final_message": final if isinstance(final, str) else "",
+    }
+    return run, known
+
+
+def _log(entry):
+    path = os.environ.get("OBEY_HOOK_LOG")
+    if not path:
+        return
+    try:
+        with open(path, "a", encoding="utf-8") as fh:
+            fh.write(json.dumps(dict(entry, ts=round(time.time(), 3))) + "\n")
+    except OSError:
+        pass
+
+
+def _stop_state(payload, root):
+    """The file that counts a session's consecutive blocked Stop events (in the temp dir)."""
+    key = str(payload.get("session_id") or payload.get("sessionId") or payload.get("conversation_id") or "")
+    if not key:
+        key = "default-" + hashlib.sha256(root.encode("utf-8", "replace")).hexdigest()[:12]
+    safe = "".join(c for c in key if c.isalnum() or c in "-_")[:80]
+    return os.path.join(tempfile.gettempdir(), "obey-stop-" + safe)
+
+
+def _blocked_stops(path):
+    try:
+        with open(path) as fh:
+            return int(fh.read().strip() or 0)
+    except (OSError, ValueError):
+        return 0
+
+
+def _set_blocked_stops(path, count):
+    try:
+        if count:
+            with open(path, "w") as fh:
+                fh.write(str(count))
+        elif os.path.exists(path):
+            os.remove(path)
+    except OSError:
+        pass
+
+
+def main(argv):
+    agent = argv[1] if len(argv) > 1 else "claude"
+    event = argv[2] if len(argv) > 2 else "pre"
+    started = time.monotonic()
+    try:
+        raw = sys.stdin.read()
+        payload = json.loads(raw) if raw.strip() else {}
+        if not isinstance(payload, dict):
+            payload = {}
+        import obey_engine
+
+        with open(os.path.join(HERE, "rules.json"), encoding="utf-8") as fh:
+            rules = json.load(fh)["rules"]
+        root = _project_root()
+        cwd = _payload_cwd(payload, root)
+        if event == "stop":
+            state = _stop_state(payload, root)
+            blocked = _blocked_stops(state)
+            if blocked >= MAX_STOP_BLOCKS:
+                _set_blocked_stops(state, 0)  # a fresh start for the next turn
+                return 0  # do not keep an agent in a loop; the run report still shows the violation
+            run, known = _stop_run(root, payload)
+            for rule in rules:
+                kind = rule["checker"]["type"]
+                if kind not in obey_engine.STOP_TYPES or (kind == "command_required" and not known):
+                    continue  # without a transcript the agent's commands are unknown, so none can be required
+                verdict = obey_engine.check(rule, run)
+                if verdict["verdict"] != "violated":
+                    continue
+                if kind == "path_required_with" and known:
+                    # The agent's changes lack the paired change; one the user made earlier may supply it.
+                    whole = obey_engine.check(rule, dict(run, diff=_working_tree_diff(root)))
+                    if whole["verdict"] != "violated":
+                        continue
+                reason = obey_engine.reason(rule, verdict)
+                _set_blocked_stops(state, blocked + 1)
+                _log({"agent": agent, "event": "stop", "decision": "block", "rule_id": rule["id"]})
+                print(json.dumps(stop_output(agent, reason)))
+                return 0
+            _set_blocked_stops(state, 0)  # this Stop passes
+            return 0
+        for action in actions_from(agent, payload, root, cwd):
+            decision = obey_engine.evaluate_action(rules, action)
+            if decision:
+                _log(
+                    {
+                        "agent": agent,
+                        "event": "pre",
+                        "decision": "deny",
+                        "rule_id": decision["rule_id"],
+                        "tool": payload.get("tool_name") or payload.get("toolName") or payload.get("tool"),
+                        "ms": round((time.monotonic() - started) * 1000, 1),
+                    }
+                )
+                print(json.dumps(deny_output(agent, decision["reason"])))
+                return 0
+        _log({"agent": agent, "event": event, "decision": "allow"})
+        return 0
+    except Exception as exc:
+        message = "obey hook error, action allowed: {}: {}".format(type(exc).__name__, exc)
+        sys.stderr.write(message + "\n")
+        out = warn_output(agent, message)
+        if out:
+            print(json.dumps(out))
+        _log({"agent": agent, "event": event, "decision": "error", "error": message})
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

obey_cli/enforce/templates/pre_commit.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""obey pre-commit check: the staged diff and the commit message against .obey/hooks/rules.json.
+
+Generated by obey (https://github.com/B0yko/obey). Standard library only, Python 3.9+. Works with any agent and
+with people. Install as git hooks:
+
+    ln -s ../../.obey/pre-commit .git/hooks/pre-commit
+    ln -s ../../.obey/pre-commit .git/hooks/commit-msg
+
+or through the pre-commit framework (see the obey README). With a commit-message file argument it checks the
+message; without one it checks the staged changes. Exit code 1 blocks the commit. An internal error (the engine
+cannot be loaded, a crash) allows the commit and says so on stderr, so a bug here can never lock you out of git.
+"""
+
+import os
+import subprocess
+import sys
+
+
+def _find_root():
+    """The project root: git's top level when it holds obey's files, else where this script really lives.
+
+    Through the symlink install, __file__ is .git/hooks/pre-commit; its real path is <root>/.obey/pre-commit.
+    """
+    real = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
+    try:
+        out = subprocess.run(["git", "rev-parse", "--show-toplevel"], capture_output=True, timeout=10, check=False)
+        top = out.stdout.decode("utf-8", "replace").strip() if out.returncode == 0 else ""
+    except (OSError, subprocess.SubprocessError):
+        top = ""
+    for candidate in (top, real):
+        if candidate and os.path.isfile(os.path.join(candidate, ".obey", "hooks", "rules.json")):
+            return candidate
+    return real
+
+
+ROOT = _find_root()
+sys.path.insert(0, os.path.join(ROOT, ".obey", "hooks"))
+
+STAGED_TYPES = {
+    "path_forbidden",
+    "dependency_unchanged",
+    "content_forbidden_added",
+    "content_required_added",
+    "file_naming",
+    "path_required_with",
+    "command_forbidden",
+}
+
+
+# Files `obey enforce` writes: they quote the rules and the engine's own code, so they are not checked against them.
+OWN = (
+    ".obey",
+    ".claude/settings.json",
+    ".codex/hooks.json",
+    ".cursor/hooks.json",
+    ".gemini/settings.json",
+    ".github/hooks/obey.json",
+    ".opencode/plugins/obey.ts",
+)
+
+
+def _git(*args):
+    out = subprocess.run(["git", *args], cwd=ROOT, capture_output=True, timeout=30, check=False)
+    return out.stdout.decode("utf-8", "replace")
+
+
+def main(argv):
+    try:
+        import json
+
+        import obey_engine
+
+        with open(os.path.join(ROOT, ".obey", "hooks", "rules.json"), encoding="utf-8") as fh:
+            rules = json.load(fh)["rules"]
+        message_file = next((a for a in argv[1:] if not a.startswith("-")), None)
+        problems = []
+        if message_file:
+            with open(message_file, encoding="utf-8", errors="replace") as fh:
+                message = "\n".join(line for line in fh.read().splitlines() if not line.startswith("#")).strip()
+            run = {
+                "events": [],
+                "diff": "",
+                "base_files": [],
+                "commits": [{"sha": "staged", "message": message, "files": []}],
+                "pushed_refs": [],
+                "final_message": "",
+            }
+            selected = [r for r in rules if r["checker"]["type"] == "commit_message"]
+        else:
+            run = {
+                "events": [],
+                "diff": _git(
+                    "diff", "--cached", "--no-color", "--no-ext-diff", "--", ".", *[":(exclude)" + p for p in OWN]
+                ),
+                "base_files": [p for p in _git("ls-files", "-z").split("\0") if p],
+                "commits": [],
+                "pushed_refs": [],
+                "final_message": "",
+            }
+            selected = [r for r in rules if r["checker"]["type"] in STAGED_TYPES]
+        for rule in selected:
+            verdict = obey_engine.check(rule, run)
+            if verdict["verdict"] == "violated":
+                problems.append(obey_engine.reason(rule, verdict))
+        if problems:
+            sys.stderr.write("obey: commit blocked\n" + "".join("  - " + p + "\n" for p in problems))
+            return 1
+        return 0
+    except Exception as exc:
+        sys.stderr.write("obey pre-commit error, commit allowed: {}: {}\n".format(type(exc).__name__, exc))
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))