hermes-gate 0.1.2__py3-none-any.whl

hermes_gate/__init__.py

@@ -0,0 +1,3 @@
+"""Hermes Gate public package surface."""
+
+__version__ = "0.1.2"

hermes_gate/adapters.py

@@ -0,0 +1,299 @@
+from __future__ import annotations
+
+import json
+import hashlib
+import os
+import re
+import shutil
+import stat
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .config import AdapterSpec
+from .execution import run_argv
+from .gate_result import validate_gate_result
+from .gitstate import git_dir
+
+_MINIMUMS = {
+    "pygate": (0, 2, 0),
+    "quick-gate": (0, 2, 3),
+}
+_SNAPSHOT_SKIP_DIRS = {".git", ".pygate", "__pycache__", ".venv", "venv", "node_modules"}
+
+
+@dataclass(frozen=True)
+class ResolvedAdapter:
+    name: str
+    argv: tuple[str, ...]
+    version: str
+
+
+def resolve_adapter(
+    spec: AdapterSpec, root: Path, *, timeout_seconds: float = 5
+) -> tuple[ResolvedAdapter | None, str]:
+    if not spec.enabled:
+        return None, "native repository commands"
+    floor = _MINIMUMS.get(spec.name)
+    if floor is None:
+        return None, f"unsupported adapter: {spec.name}"
+    if not spec.argv:
+        return None, f"{spec.name} adapter argv is empty"
+    executable = spec.argv[0]
+    executable_path = Path(executable)
+    if not executable_path.is_absolute():
+        executable_path = root / executable_path
+    if shutil.which(executable) is None and not (
+        executable_path.is_file() and os.access(executable_path, os.X_OK)
+    ):
+        return None, f"{spec.name} adapter executable is unavailable"
+    version_run = run_argv(
+        [*spec.argv, "--version"],
+        cwd=root,
+        timeout_seconds=max(timeout_seconds, 0.001),
+    )
+    if version_run.unavailable:
+        return None, f"{spec.name} adapter executable is unavailable"
+    if version_run.timed_out:
+        return None, f"{spec.name} adapter version probe timed out"
+    version_text = (version_run.stdout or version_run.stderr).strip().splitlines()
+    version = version_text[0] if version_text else ""
+    parsed = _version_tuple(version)
+    configured = _version_tuple(spec.minimum_version) if spec.minimum_version else floor
+    if configured is None:
+        return None, f"{spec.name} adapter minimum_version is invalid: {spec.minimum_version}"
+    minimum = max(floor, configured)
+    if parsed is None or parsed < minimum:
+        required = ".".join(str(item) for item in minimum)
+        return None, f"{spec.name} {required}+ required; found {version or 'unknown'}"
+    return ResolvedAdapter(spec.name, spec.argv, version), ""
+
+
+def run_adapter(
+    spec: AdapterSpec,
+    *,
+    root: Path,
+    mode: str,
+    checked_paths: list[str],
+    timeout_seconds: float,
+) -> dict[str, Any]:
+    started = time.monotonic()
+    adapter, reason = resolve_adapter(spec, root, timeout_seconds=timeout_seconds)
+    if adapter is None:
+        return {"status": "ERROR", "reason": reason, "checks": [], "command_versions": {}}
+    remaining = timeout_seconds - (time.monotonic() - started)
+    if remaining <= 0:
+        return {
+            "status": "ERROR",
+            "reason": f"{adapter.name} adapter budget exhausted during version probe",
+            "checks": [],
+            "command_versions": {adapter.name: adapter.version},
+        }
+    state_dir = git_dir(root) / "hermes-gate" / "adapters" / adapter.name / mode
+    state_dir.mkdir(parents=True, exist_ok=True)
+    expected_digest, expected_paths = canonical_snapshot_digest(root, checked_paths)
+    changed_file = state_dir / "changed-files.txt"
+    changed_file.write_text(
+        "".join(f"{item}\n" for item in checked_paths),
+        encoding="utf-8",
+    )
+    primitive_mode = "canary" if adapter.name == "pygate" and mode == "fast" else mode
+    if adapter.name == "quick-gate" and mode == "fast":
+        primitive_mode = "quick"
+    argv = [
+        *adapter.argv,
+        "run",
+        "--mode",
+        primitive_mode,
+        "--changed-files",
+        str(changed_file),
+        "--output-dir",
+        str(state_dir),
+    ]
+    result_path = state_dir / "gate-result.json"
+    result_path.unlink(missing_ok=True)
+    execution = run_argv(argv, cwd=root, timeout_seconds=remaining)
+    if execution.unavailable or execution.timed_out:
+        detail = "executable unavailable" if execution.unavailable else "timed out"
+        return {
+            "status": "ERROR",
+            "reason": f"{adapter.name} adapter {detail}",
+            "checks": [],
+            "command_versions": {adapter.name: adapter.version},
+        }
+    try:
+        payload = json.loads(result_path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError) as exc:
+        return {
+            "status": "ERROR",
+            "reason": f"{adapter.name} did not produce a readable gate-result/v1: {exc}",
+            "checks": [],
+            "command_versions": {adapter.name: adapter.version},
+        }
+    errors = validate_gate_result(payload)
+    if errors:
+        return {
+            "status": "ERROR",
+            "reason": f"{adapter.name} emitted invalid gate-result/v1: {'; '.join(errors)}",
+            "checks": [],
+            "command_versions": {adapter.name: adapter.version},
+        }
+    missing_paths = sorted(set(expected_paths) - set(payload["checked_paths"]))
+    if missing_paths:
+        return {
+            "status": "ERROR",
+            "reason": f"{adapter.name} omitted checked paths: {', '.join(missing_paths)}",
+            "checks": [],
+            "command_versions": {adapter.name: adapter.version},
+        }
+    current_digest, _ = canonical_snapshot_digest(root, checked_paths)
+    if current_digest != expected_digest:
+        return {
+            "status": "ERROR",
+            "reason": f"{adapter.name} checked inputs changed during execution",
+            "checks": [],
+            "command_versions": {adapter.name: adapter.version},
+        }
+    if payload["snapshot_digest"] != expected_digest:
+        return {
+            "status": "ERROR",
+            "reason": f"{adapter.name} snapshot digest does not match checked inputs",
+            "checks": [],
+            "command_versions": {adapter.name: adapter.version},
+        }
+    if payload["status"] == "pass" and execution.returncode != 0:
+        return {
+            "status": "ERROR",
+            "reason": f"{adapter.name} emitted pass but exited with {execution.returncode}",
+            "checks": [],
+            "command_versions": {adapter.name: adapter.version},
+        }
+    blocking_checks = [
+        str(check.get("name", "unknown"))
+        for check in payload["checks"]
+        if check.get("status") not in {"pass", "skipped"}
+    ]
+    if payload["status"] == "pass" and (
+        blocking_checks or payload.get("errors") or payload.get("findings")
+    ):
+        detail = ", ".join(blocking_checks) if blocking_checks else "errors or findings"
+        return {
+            "status": "ERROR",
+            "reason": f"{adapter.name} emitted pass with blocking evidence: {detail}",
+            "checks": list(payload["checks"]),
+            "command_versions": {adapter.name: adapter.version},
+        }
+    status = "PASS" if payload["status"] == "pass" else "FAIL"
+    if payload["status"] == "error":
+        status = "ERROR"
+    reason = "" if status == "PASS" else f"{adapter.name} returned {payload['status']}"
+    versions = {adapter.name: adapter.version}
+    for name, value in payload.get("command_versions", {}).items():
+        versions[str(name)] = value if isinstance(value, str) else json.dumps(value, sort_keys=True)
+    return {
+        "status": status,
+        "reason": reason,
+        "checks": list(payload["checks"]),
+        "command_versions": versions,
+        "adapter": adapter.name,
+        "adapter_exit_code": execution.returncode,
+        "gate_result": payload,
+    }
+
+
+def _version_tuple(value: str) -> tuple[int, int, int] | None:
+    match = re.search(r"(?<!\d)(\d+)\.(\d+)\.(\d+)(?!\d)", value)
+    if not match:
+        return None
+    return tuple(int(item) for item in match.groups())
+
+
+def canonical_snapshot_digest(root: Path, checked_paths: list[str]) -> tuple[str, list[str]]:
+    records: list[dict[str, Any]] = []
+    normalized: set[str] = set()
+    for raw_path in checked_paths:
+        path = Path(raw_path)
+        if not path.is_absolute():
+            path = root / path
+        files = _files_for_snapshot(path)
+        if not files and not path.is_dir():
+            files = [path]
+        for file_path in files:
+            relative = _relative_snapshot_path(file_path, root)
+            if relative in normalized:
+                continue
+            normalized.add(relative)
+            if file_path.is_symlink():
+                record: dict[str, Any] = {
+                    "path": relative,
+                    "exists": True,
+                    "symlink": os.readlink(file_path),
+                }
+                try:
+                    target_stat = file_path.stat()
+                except FileNotFoundError:
+                    record["target_type"] = "missing"
+                except OSError:
+                    record["target_type"] = "unreadable"
+                else:
+                    record["target_type"] = (
+                        "file"
+                        if stat.S_ISREG(target_stat.st_mode)
+                        else "directory"
+                        if stat.S_ISDIR(target_stat.st_mode)
+                        else "other"
+                    )
+                if record.get("target_type") == "file":
+                    try:
+                        content = file_path.read_bytes()
+                    except OSError:
+                        record["target_type"] = "unreadable"
+                    else:
+                        record.update(
+                            {"size": len(content), "sha256": hashlib.sha256(content).hexdigest()}
+                        )
+                records.append(record)
+                continue
+            if not file_path.exists() or not file_path.is_file():
+                records.append({"path": relative, "exists": False})
+                continue
+            try:
+                data = file_path.read_bytes()
+            except OSError as exc:
+                records.append({"path": relative, "exists": False, "error": type(exc).__name__})
+                continue
+            records.append(
+                {
+                    "path": relative,
+                    "exists": True,
+                    "size": len(data),
+                    "sha256": hashlib.sha256(data).hexdigest(),
+                }
+            )
+    records.sort(key=lambda record: record["path"])
+    encoded = json.dumps(records, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest(), [str(record["path"]) for record in records]
+
+
+def _files_for_snapshot(path: Path) -> list[Path]:
+    if path.is_file() or path.is_symlink():
+        return [path]
+    if not path.is_dir():
+        return [path]
+    files: list[Path] = []
+    for current, directories, names in os.walk(path, followlinks=False):
+        directories[:] = sorted(
+            item
+            for item in directories
+            if item not in _SNAPSHOT_SKIP_DIRS and not item.startswith(".")
+        )
+        files.extend(Path(current) / name for name in sorted(names))
+    return files
+
+
+def _relative_snapshot_path(path: Path, root: Path) -> str:
+    try:
+        return path.absolute().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return path.absolute().as_posix()

hermes_gate/classification.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+CODE_EXTENSIONS = {
+    ".c",
+    ".cc",
+    ".cpp",
+    ".cs",
+    ".go",
+    ".h",
+    ".hpp",
+    ".java",
+    ".js",
+    ".jsx",
+    ".kt",
+    ".kts",
+    ".php",
+    ".py",
+    ".rb",
+    ".rs",
+    ".sh",
+    ".swift",
+    ".ts",
+    ".tsx",
+    ".vue",
+    ".yaml",
+    ".yml",
+    ".toml",
+}
+CODE_NAMES = {"Dockerfile", "Makefile", "Justfile", "AGENTS.md", "CLAUDE.md"}
+
+
+def is_code_path(path: str) -> bool:
+    item = Path(path)
+    return item.suffix.lower() in CODE_EXTENSIONS or item.name in CODE_NAMES

hermes_gate/cli.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+from typing import Any, Callable
+
+from .codex_install import install as install_codex
+from .codex_install import uninstall as uninstall_codex
+from .doctor import diagnose
+from .engine import boundary, fast, full, repair, review
+from .gitstate import repo_root
+from .hooks import read_stdin_payload, run_hook
+from .init_repo import initialize, uninstall
+from .status import EXIT_CODES, Status
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(
+        prog="hermes-gate", description="Bounded session-wide completion rail"
+    )
+    root.add_argument("--version", action="version", version="hermes-gate 0.1.2")
+    sub = root.add_subparsers(dest="command", required=True)
+    init = sub.add_parser(
+        "init", help="install a repository profile, runner, workflow, and baseline"
+    )
+    init.add_argument("--force", action="store_true")
+    sub.add_parser("fast", help="run the cached session-scoped deterministic gate")
+    sub.add_parser("repair", help="run one configured deterministic repair")
+    sub.add_parser("review", help="run one bounded independent review")
+    sub.add_parser("full", help="run the complete declared repository contract")
+    bound = sub.add_parser("boundary", help="validate exact receipts for a Git or PR boundary")
+    bound.add_argument("action", choices=("commit", "push", "pr-create", "pr-ready"))
+    sub.add_parser("doctor", help="read-only installation and receipt diagnostics")
+    sub.add_parser("install-codex", help=argparse.SUPPRESS)
+    sub.add_parser("uninstall-codex", help=argparse.SUPPRESS)
+    sub.add_parser("uninstall-repo", help=argparse.SUPPRESS)
+    hook = sub.add_parser("hook", help=argparse.SUPPRESS)
+    hook.add_argument("event", choices=("session-start", "stop", "pre-tool-use"))
+    return root
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    if args.command == "hook":
+        output = run_hook(args.event, read_stdin_payload())
+        print(json.dumps(output, sort_keys=True))
+        return 0
+    if args.command == "doctor":
+        output = diagnose(Path.cwd())
+        return _emit(output)
+    if args.command == "install-codex":
+        executable = Path(sys.argv[0])
+        output = install_codex(executable)
+        return _emit(output)
+    if args.command == "uninstall-codex":
+        return _emit(uninstall_codex())
+    root = repo_root(Path.cwd())
+    if root is None:
+        return _emit(
+            {
+                "schema": "hermes-gate/result-v1",
+                "command": args.command,
+                "status": Status.NOT_APPLICABLE.value,
+                "reason": "not a Git repository",
+                "elapsed_ms": 0,
+            }
+        )
+    routes: dict[str, Callable[[], dict[str, Any]]] = {
+        "init": lambda: _wrap_init(root, args.force),
+        "fast": lambda: fast(root),
+        "repair": lambda: repair(root),
+        "review": lambda: review(root),
+        "full": lambda: full(root),
+        "boundary": lambda: boundary(root, args.action),
+        "uninstall-repo": lambda: _wrap_uninstall(root),
+    }
+    return _emit(routes[args.command]())
+
+
+def _wrap_init(root: Path, force: bool) -> dict[str, Any]:
+    started = time.monotonic()
+    value = initialize(root, force=force)
+    return {
+        "schema": "hermes-gate/result-v1",
+        "command": "init",
+        "elapsed_ms": round((time.monotonic() - started) * 1000),
+        **value,
+    }
+
+
+def _wrap_uninstall(root: Path) -> dict[str, Any]:
+    started = time.monotonic()
+    value = uninstall(root)
+    return {
+        "schema": "hermes-gate/result-v1",
+        "command": "uninstall-repo",
+        "elapsed_ms": round((time.monotonic() - started) * 1000),
+        **value,
+    }
+
+
+def _emit(output: dict[str, Any]) -> int:
+    print(json.dumps(output, indent=2, sort_keys=True))
+    try:
+        status = Status(str(output.get("status", Status.ERROR.value)))
+    except ValueError:
+        status = Status.ERROR
+    return EXIT_CODES[status]
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hermes_gate/codex_install.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shlex
+import shutil
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+
+MARKER_START = "<!-- hermes-gate:v0.1:start -->"
+MARKER_END = "<!-- hermes-gate:v0.1:end -->"
+CONTRACT = f"""
+{MARKER_START}
+## Hermes Gate completion rail
+
+For code changes, run `hermes-gate fast` before declaring completion and one `hermes-gate review`
+for a completed diff. Run `hermes-gate full` for PR or release readiness when the profile requires
+it. Matching receipts are mandatory at commit, push, and PR boundaries. Read-only, non-Git,
+unchanged, and non-code work is exempt. Hooks never repair files or authorize public actions.
+{MARKER_END}
+""".strip()
+
+
+def install(executable: Path, *, codex_home: Path | None = None) -> dict[str, Any]:
+    home = (codex_home or Path.home() / ".codex").resolve()
+    home.mkdir(parents=True, exist_ok=True)
+    hooks_path = home / "hooks.json"
+    agents_path = home / "AGENTS.md"
+    backup_dir = (
+        Path.home()
+        / ".local"
+        / "state"
+        / "hermes-gate"
+        / "codex-backups"
+        / datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
+    )
+    backup_dir.mkdir(parents=True, exist_ok=True)
+    for path in (hooks_path, agents_path):
+        if path.exists():
+            shutil.copy2(path, backup_dir / path.name)
+
+    hooks = _read_hooks(hooks_path)
+    command = str(executable.resolve())
+    for event in ("SessionStart", "Stop", "PreToolUse"):
+        groups = hooks["hooks"].setdefault(event, [])
+        hooks["hooks"][event] = [group for group in groups if not _is_ours(event, group)]
+    hooks["hooks"]["SessionStart"].append(
+        {
+            "matcher": "startup|resume|clear|compact",
+            "hooks": [
+                {
+                    "type": "command",
+                    "command": f'"{command}" hook session-start',
+                    "timeout": 3,
+                    "additionalContextLimit": 500,
+                }
+            ],
+        }
+    )
+    hooks["hooks"]["Stop"].append(
+        {"hooks": [{"type": "command", "command": f'"{command}" hook stop', "timeout": 10}]}
+    )
+    hooks["hooks"]["PreToolUse"].append(
+        {
+            "matcher": "^Bash$",
+            "hooks": [
+                {
+                    "type": "command",
+                    "command": f'"{command}" hook pre-tool-use',
+                    "timeout": 5,
+                    "statusMessage": "Checking Hermes Gate receipts",
+                }
+            ],
+        }
+    )
+    _atomic_json(hooks_path, hooks)
+    original = agents_path.read_text(encoding="utf-8") if agents_path.exists() else ""
+    agents_path.write_text(_replace_contract(original), encoding="utf-8")
+    manifest = {
+        "schema": "hermes-gate/codex-install-v1",
+        "executable": command,
+        "hooks_path": str(hooks_path),
+        "hooks_sha256": hashlib.sha256(hooks_path.read_bytes()).hexdigest(),
+        "agents_path": str(agents_path),
+        "backup_dir": str(backup_dir),
+        "rollback": f'"{command}" uninstall-codex',
+        "trust_action": "Open /hooks in Codex and trust the three exact Hermes Gate command definitions.",
+    }
+    manifest_path = Path.home() / ".local" / "state" / "hermes-gate" / "codex-install.json"
+    _atomic_json(manifest_path, manifest)
+    return {"status": "PASS", **manifest}
+
+
+def uninstall(*, codex_home: Path | None = None) -> dict[str, Any]:
+    home = (codex_home or Path.home() / ".codex").resolve()
+    hooks_path = home / "hooks.json"
+    agents_path = home / "AGENTS.md"
+    hooks = _read_hooks(hooks_path)
+    removed = 0
+    for event, groups in list(hooks.get("hooks", {}).items()):
+        kept = [group for group in groups if not _is_ours(event, group)]
+        removed += len(groups) - len(kept)
+        hooks["hooks"][event] = kept
+    _atomic_json(hooks_path, hooks)
+    if agents_path.exists():
+        agents_path.write_text(
+            _replace_contract(agents_path.read_text(encoding="utf-8"), remove=True),
+            encoding="utf-8",
+        )
+    return {"status": "PASS", "removed_hook_groups": removed, "preserved_unrelated_hooks": True}
+
+
+def installed(*, codex_home: Path | None = None) -> dict[str, Any]:
+    home = (codex_home or Path.home() / ".codex").resolve()
+    hooks = _read_hooks(home / "hooks.json")
+    counts = {
+        event: sum(1 for group in hooks.get("hooks", {}).get(event, []) if _is_ours(event, group))
+        for event in ("SessionStart", "Stop", "PreToolUse")
+    }
+    agents = (
+        (home / "AGENTS.md").read_text(encoding="utf-8") if (home / "AGENTS.md").exists() else ""
+    )
+    return {
+        "hook_groups": counts,
+        "instruction": MARKER_START in agents,
+        "status": "PASS"
+        if all(value == 1 for value in counts.values()) and MARKER_START in agents
+        else "NOT_CONFIGURED",
+    }
+
+
+def _read_hooks(path: Path) -> dict[str, Any]:
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return {"description": "User lifecycle hooks", "hooks": {}}
+    if not isinstance(raw, dict) or not isinstance(raw.get("hooks", {}), dict):
+        raise ValueError(f"malformed Codex hook file: {path}")
+    raw.setdefault("hooks", {})
+    return raw
+
+
+def _is_ours(event: str, group: Any) -> bool:
+    """Recognize only the complete v0.1 hook definitions we install.
+
+    Command text is user-owned configuration, so a substring such as
+    ``hermes-gate`` is not an ownership marker: it can describe an unrelated
+    hook like ``hermes-gate-notify``.  The complete event, matcher, hook shape,
+    and parsed command argv must match instead.
+    """
+    expected = {
+        "SessionStart": (
+            "startup|resume|clear|compact",
+            "session-start",
+            3,
+            {"additionalContextLimit": 500},
+        ),
+        "Stop": (None, "stop", 10, {}),
+        "PreToolUse": (
+            "^Bash$",
+            "pre-tool-use",
+            5,
+            {"statusMessage": "Checking Hermes Gate receipts"},
+        ),
+    }.get(event)
+    if expected is None or not isinstance(group, dict):
+        return False
+    matcher, action, timeout, extra = expected
+    if group.get("matcher") != matcher or set(group) != (
+        {"hooks"} if matcher is None else {"matcher", "hooks"}
+    ):
+        return False
+    hook_items = group.get("hooks")
+    if not isinstance(hook_items, list) or len(hook_items) != 1:
+        return False
+    hook = hook_items[0]
+    if (
+        not isinstance(hook, dict)
+        or hook.get("type") != "command"
+        or hook.get("timeout") != timeout
+    ):
+        return False
+    allowed_keys = {"type", "command", "timeout", *extra}
+    if set(hook) != allowed_keys or any(hook.get(key) != value for key, value in extra.items()):
+        return False
+    try:
+        argv = shlex.split(str(hook["command"]))
+    except (KeyError, TypeError, ValueError):
+        return False
+    return len(argv) == 3 and Path(argv[0]).name == "hermes-gate" and argv[1:] == ["hook", action]
+
+
+def _replace_contract(text: str, *, remove: bool = False) -> str:
+    start = text.find(MARKER_START)
+    end = text.find(MARKER_END)
+    if start >= 0 and end >= start:
+        end += len(MARKER_END)
+        text = (text[:start].rstrip() + "\n" + text[end:].lstrip()).rstrip()
+    if remove:
+        return text + ("\n" if text else "")
+    return text.rstrip() + ("\n\n" if text.strip() else "") + CONTRACT + "\n"
+
+
+def _atomic_json(path: Path, value: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    temporary.write_text(json.dumps(value, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    os.chmod(temporary, 0o600)
+    os.replace(temporary, path)