exitzero 0.1.0__py3-none-any.whl

exitzero/__init__.py

@@ -0,0 +1,3 @@
+"""Policy-driven verification for AI-assisted coding teams."""
+
+__version__ = "0.1.0"

exitzero/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

exitzero/api.py

@@ -0,0 +1,69 @@
+"""Small, versioned contracts shared by core and plugins."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Any
+
+API_VERSION = 1
+HOOK_SLOTS = frozenset({"PreToolUse", "PostToolUse", "pre-commit", "CI"})
+
+
+@dataclass(frozen=True)
+class Finding:
+    rule: str
+    message: str
+    path: str | None = None
+    line: int | None = None
+    severity: str = "error"
+
+
+@dataclass(frozen=True)
+class CheckSpec:
+    id: str
+    kind: str
+    paths: tuple[str, ...] = ()
+    options: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Context:
+    root: Path
+    policy: dict[str, Any]
+    policy_path: Path
+
+
+CheckHandler = Callable[[Context, CheckSpec], list[Finding]]
+LintHandler = Callable[[Context], list[Finding]]
+HookHandler = Callable[[Context, str], list[Finding]]
+
+
+@dataclass
+class Registry:
+    """Plugins call register(); duplicate names and unsupported slots fail closed."""
+
+    checks: dict[str, CheckHandler] = field(default_factory=dict)
+    linters: dict[str, LintHandler] = field(default_factory=dict)
+    hooks: dict[str, list[HookHandler]] = field(default_factory=dict)
+    commands: dict[str, Callable[[Context, list[str]], int]] = field(default_factory=dict)
+
+    def add_check(self, name: str, handler: CheckHandler) -> None:
+        self._add(self.checks, name, handler)
+
+    def add_linter(self, name: str, handler: LintHandler) -> None:
+        self._add(self.linters, name, handler)
+
+    def add_hook(self, slot: str, handler: HookHandler) -> None:
+        if slot not in HOOK_SLOTS:
+            raise ValueError("Unsupported hook slot")
+        self.hooks.setdefault(slot, []).append(handler)
+
+    def add_command(self, name: str, handler: Callable[[Context, list[str]], int]) -> None:
+        if name in {"init", "check", "lint-config", "hooks", "report", "plugin"}:
+            raise ValueError("Reserved CLI command")
+        self._add(self.commands, name, handler)
+
+    @staticmethod
+    def _add(target: dict, name: str, handler: Callable) -> None:
+        if not name or name in target or not callable(handler):
+            raise ValueError("Invalid or duplicate plugin registration")
+        target[name] = handler

exitzero/cli.py

@@ -0,0 +1,208 @@
+"""Public command-line interface; check outcomes always come from the runner."""
+import argparse
+import json
+from pathlib import Path
+import shlex
+import sys
+
+from . import __version__
+from .api import Context, HOOK_SLOTS
+from .files import safe_path, select_files, validate_relative
+from .hooks import CURSOR_EVENTS, cursor_response, install
+from .loader import discover
+from .policy import DEFAULT_POLICY, load_policy, python_profile_policy, sync_agents
+from .runner import run
+
+
+def parser() -> argparse.ArgumentParser:
+    cli = argparse.ArgumentParser(prog="exitzero")
+    cli.add_argument("--version", action="version", version=__version__)
+    cli.add_argument("--root", default=".", help="Repository directory")
+    cli.add_argument("--policy", default="exitzero.toml", help="Policy path relative to root")
+    commands = cli.add_subparsers(dest="command", required=True)
+    init = commands.add_parser("init", help="Create policy and managed AGENTS section")
+    init.add_argument("--sync", action="store_true", help="Regenerate only the managed AGENTS section")
+    init.add_argument("--profile", choices=("default", "python"), default="default",
+                      help="Policy starter profile (python adds static checks and command slots)")
+    init.add_argument("--source-root", action="append", default=[], metavar="PATH",
+                      help="Python source root; repeat for multiple roots")
+    init.add_argument("--allow-module", action="append", default=[], metavar="MODULE",
+                      help="External Python module trusted by the imports check")
+    init.add_argument("--test-command", metavar="COMMAND",
+                      help="Shell-free test command to store as argv")
+    init.add_argument("--review-command", action="append", default=[], metavar="COMMAND",
+                      help="Shell-free review command; repeatable")
+    for name in ("check", "lint-config"):
+        child = commands.add_parser(name)
+        child.add_argument("--format", choices=("human", "json"), default="human")
+    hooks = commands.add_parser("hooks").add_subparsers(dest="hook_command", required=True)
+    installer = hooks.add_parser("install")
+    installer.add_argument("--adapter", choices=("cursor", "pre-commit"), default="cursor")
+    hook_run = hooks.add_parser("run")
+    hook_run.add_argument("--adapter", choices=("generic", "cursor"), default="generic")
+    hook_run.add_argument("--slot", choices=sorted(HOOK_SLOTS), default="CI")
+    hook_run.add_argument("--event", choices=sorted(CURSOR_EVENTS), default="stop")
+    hook_run.add_argument("--format", choices=("human", "json"), default="human")
+    report = commands.add_parser("report")
+    report.add_argument("--format", choices=("human", "json"), default="human")
+    plugin = commands.add_parser("plugin")
+    plugin.add_argument("name")
+    plugin.add_argument("args", nargs=argparse.REMAINDER)
+    return cli
+
+
+def emit(receipt: dict, output: str) -> None:
+    if output == "json":
+        print(json.dumps(receipt, ensure_ascii=False, sort_keys=True))
+        return
+    print(f"exitzero: {receipt['status']} (exit {receipt['exit_code']})")
+    for finding in receipt["findings"]:
+        location = f" {finding['path']}" if finding.get("path") else ""
+        if finding.get("line"):
+            location += f":{finding['line']}"
+        print(f"  {finding['rule']}{location}: {finding['message']}")
+    print(f"Receipt: {receipt['receipt'] or 'NOT WRITTEN'}")
+
+
+_COMMAND_OPERATORS = frozenset("|&;<>()")
+
+
+def _parse_init_command(value: str | None) -> list[str] | None:
+    """Parse a user command without invoking a shell or accepting operators."""
+
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value.strip() or "\x00" in value:
+        raise ValueError("command must be a non-empty string")
+    quote: str | None = None
+    escaped = False
+    for character in value:
+        if escaped:
+            escaped = False
+            continue
+        if quote is not None:
+            if character == quote:
+                quote = None
+            elif character == "\\" and quote == '"':
+                escaped = True
+            continue
+        if character in "'\"":
+            quote = character
+        elif character == "\\":
+            escaped = True
+        elif character in _COMMAND_OPERATORS or character in "\r\n":
+            raise ValueError("commands cannot contain shell operators or control characters")
+    if quote is not None or escaped:
+        raise ValueError("command has an unterminated quote or escape")
+    try:
+        argv = shlex.split(value, posix=True)
+    except ValueError as error:
+        raise ValueError("command has invalid shell-style quoting") from error
+    if not argv or any(not isinstance(item, str) or not item for item in argv):
+        raise ValueError("command must contain at least one argument")
+    return argv
+
+
+def _init_generation(args: argparse.Namespace) -> str:
+    generation_requested = bool(
+        args.profile != "default" or args.source_root or args.allow_module
+        or args.test_command is not None or args.review_command
+    )
+    if args.sync and generation_requested:
+        raise ValueError("init --sync cannot be combined with policy generation options")
+    if args.profile == "default" and generation_requested:
+        raise ValueError("--profile python is required with generation options")
+    if args.profile != "python":
+        return DEFAULT_POLICY
+    roots = args.source_root or ["."]
+    for root in roots:
+        validate_relative(root)
+        if any(character in root for character in "*?[]"):
+            raise ValueError("source roots must be directories, not glob patterns")
+    for module in args.allow_module:
+        if not module or any(not part.isidentifier() for part in module.split(".")):
+            raise ValueError("allow modules must contain dotted module names")
+    test_argv = _parse_init_command(args.test_command)
+    review_argvs: list[list[str]] = []
+    for value in args.review_command:
+        argv = _parse_init_command(value)
+        if argv is None:
+            raise ValueError("review commands must be non-empty strings")
+        review_argvs.append(argv)
+    return python_profile_policy(roots, args.allow_module, test_argv, review_argvs)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    root = Path(args.root).resolve()
+    if args.command in {"check", "lint-config"}:
+        receipt = run(root, args.policy, args.command)
+        emit(receipt, args.format)
+        return receipt["exit_code"]
+    if args.command == "hooks" and args.hook_command == "run":
+        if args.adapter == "cursor":
+            try:
+                payload = json.loads(sys.stdin.read(1024 * 1024))
+                if not isinstance(payload, dict) or type(payload.get("loop_count", 0)) is not int or payload.get("loop_count", 0) < 0:
+                    raise ValueError("Invalid Cursor payload")
+            except (ValueError, OSError):
+                # Still execute and persist the actual gate outcome for every invocation.
+                receipt = run(root, args.policy, "check", CURSOR_EVENTS[args.event], input_error=True)
+                print(json.dumps({"error": "Invalid Cursor JSON input", "receipt": receipt["receipt"]}))
+                return 2
+            receipt = run(root, args.policy, "check", CURSOR_EVENTS[args.event])
+            print(json.dumps(cursor_response(receipt, args.event, payload)))
+            # Cursor reads the JSON protocol; generic adapters expose unchanged gate codes.
+            return 0 if receipt["exit_code"] != 2 else 2
+        receipt = run(root, args.policy, "check", args.slot)
+        emit(receipt, args.format)
+        return receipt["exit_code"]
+    try:
+        path = safe_path(root, args.policy)
+        if args.command == "init":
+            if not root.is_dir():
+                raise ValueError("Root directory must exist")
+            generated_policy = _init_generation(args)
+            if not args.sync:
+                if path.exists():
+                    raise ValueError("Policy already exists; use init --sync")
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text(generated_policy, encoding="utf-8")
+                ignore = safe_path(root, ".gitignore")
+                existing = ignore.read_text(encoding="utf-8") if ignore.exists() else ""
+                additions = [item for item in ("/.exitzero/", "__pycache__/") if item not in existing.splitlines()]
+                if additions:
+                    ignore.write_text(existing.rstrip() + ("\n" if existing else "") + "\n".join(additions) + "\n", encoding="utf-8")
+                if not select_files(root, ["**/*.py"]):
+                    example = safe_path(root, "exitzero_sample.py")
+                    example.write_text('"""Replace this sample with your project checks."""\n\ndef add(left: int, right: int) -> int:\n    return left + right\n', encoding="utf-8")
+            policy = load_policy(path)
+            sync_agents(root, policy)
+            print("Policy and AGENTS.md synchronized. Run exitzero check to verify.")
+            return 0
+        if args.command == "report":
+            directory = safe_path(root, ".exitzero/runs")
+            files = sorted(directory.glob("*.json"), key=lambda p: p.stat().st_mtime_ns)
+            if not files:
+                raise ValueError("No receipt exists; run check first")
+            latest = safe_path(root, files[-1].relative_to(root).as_posix())
+            emit(json.loads(latest.read_text(encoding="utf-8")), args.format)
+            return 0
+        policy = load_policy(path)
+        if args.command == "hooks":
+            print("Installed " + install(root, path, args.adapter) + ". Run lint-config to verify configuration.")
+            return 0
+        registry = discover(policy["plugins"])
+        if args.name not in registry.commands:
+            raise ValueError("No such plugin command")
+        result = registry.commands[args.name](Context(root, policy, path), args.args)
+        if type(result) is not int or result not in (0, 1, 2):
+            raise ValueError("Plugin command must return exit code 0, 1 or 2")
+        return result
+    except Exception as error:
+        print(f"exitzero: unable to complete command ({type(error).__name__}); check policy, paths and existing files.", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

exitzero/files.py

@@ -0,0 +1,51 @@
+"""Repository-scoped reads that avoid credentials and generated directories."""
+from pathlib import Path, PurePosixPath
+
+EXCLUDED = frozenset({".git", ".venv", "venv", "node_modules", "__pycache__", ".exitzero", "build", "dist"})
+SENSITIVE_DIRS = frozenset({".ssh", ".aws", ".gnupg"})
+SENSITIVE_NAMES = frozenset({"auth.json", "credentials", "credentials.json", "tokens.json", "token.json", "id_rsa", "id_ed25519"})
+
+
+def validate_relative(value: str) -> None:
+    if (not isinstance(value, str) or not value or "\\" in value or "\x00" in value
+            or PurePosixPath(value).is_absolute() or ".." in PurePosixPath(value).parts
+            or ":" in value):
+        raise ValueError("Expected a relative repository path without traversal")
+
+
+def is_sensitive(path: Path) -> bool:
+    name = path.name.lower()
+    return (name == ".env" or name.startswith(".env.") or name in SENSITIVE_NAMES
+            or path.suffix.lower() in {".pem", ".key", ".p12", ".pfx", ".keystore"}
+            or any(part.lower() in SENSITIVE_DIRS for part in path.parts))
+
+
+def safe_path(root: Path, relative: str) -> Path:
+    validate_relative(relative)
+    candidate = root / relative
+    if is_sensitive(Path(relative)):
+        raise ValueError("Credential-like paths are not valid inspection targets")
+    cursor = root
+    for part in Path(relative).parts:
+        cursor = cursor / part
+        if cursor.is_symlink():
+            raise ValueError("Symlinks are not valid inspection targets")
+    if not candidate.resolve().is_relative_to(root.resolve()):
+        raise ValueError("Path escapes repository")
+    return candidate
+
+
+def select_files(root: Path, patterns: tuple[str, ...] | list[str]) -> list[Path]:
+    selected: set[Path] = set()
+    for pattern in patterns:
+        validate_relative(pattern)
+        if is_sensitive(Path(pattern)):
+            raise ValueError("Credential-like paths are not valid inspection targets")
+        for candidate in root.glob(pattern):
+            relative = candidate.relative_to(root)
+            if any(part in EXCLUDED for part in relative.parts) or is_sensitive(relative):
+                continue
+            safe_path(root, relative.as_posix())
+            if candidate.is_file():
+                selected.add(candidate)
+    return sorted(selected)

exitzero/hooks.py

@@ -0,0 +1,130 @@
+"""IDE adapters delegate to the shared runner and preserve existing hooks."""
+import hashlib
+import json
+from pathlib import Path
+import shlex
+import subprocess
+import sys
+
+from .api import Context, Finding
+from .files import safe_path
+
+CURSOR_EVENTS = {
+    "preToolUse": "PreToolUse",
+    "postToolUse": "PostToolUse",
+    "beforeShellExecution": "PreToolUse",
+    "beforeMCPExecution": "PreToolUse",
+    "afterFileEdit": "PostToolUse",
+    "stop": "PostToolUse",
+}
+
+
+def _launcher() -> list[str]:
+    checkout = Path(__file__).resolve().parents[4] / "bin" / "exitzero"
+    return [sys.executable, str(checkout)] if checkout.is_file() else [sys.executable, "-m", "exitzero"]
+
+
+def expected_cursor_command(root: Path, policy_path: Path, slot: str = "PostToolUse") -> str:
+    event = "stop" if slot == "PostToolUse" else "preToolUse"
+    return shlex.join([*_launcher(), "--root", str(root), "--policy", str(policy_path.relative_to(root)),
+                       "hooks", "run", "--adapter", "cursor", "--event", event])
+
+
+def _manifest(root: Path) -> dict:
+    path = safe_path(root, ".exitzero/hooks.json")
+    if path.exists():
+        value = json.loads(path.read_text(encoding="utf-8"))
+        if (not isinstance(value, dict) or type(value.get("version")) is not int
+                or value["version"] != 1 or not isinstance(value.get("files"), dict)
+                or any(not isinstance(digest, str) or len(digest) != 64 for digest in value["files"].values())):
+            raise ValueError("Invalid hook installation manifest")
+        return value
+    return {"version": 1, "files": {}}
+
+
+def installed_inputs(root: Path) -> list[str]:
+    """Include exactly the hook files inspected by the configuration linter."""
+    return [".exitzero/hooks.json", *_manifest(root)["files"]]
+
+
+def cursor_hook_error(entry: object) -> str | None:
+    """Validate execution fields shared by Cursor installation and config lint."""
+    if not isinstance(entry, dict):
+        return "Cursor hook entries must be objects"
+    kind = entry.get("type", "command")
+    if kind not in ("command", "prompt"):
+        return "Cursor hook type must be command or prompt"
+    field = "prompt" if kind == "prompt" else "command"
+    if not isinstance(entry.get(field), str) or not entry[field].strip():
+        return f"Cursor hook entries require a non-empty {field}"
+    return None
+
+
+def install(root: Path, policy_path: Path, adapter: str) -> str:
+    manifest = _manifest(root)
+    if adapter == "cursor":
+        relative = ".cursor/hooks.json"
+        path = safe_path(root, relative)
+        data = json.loads(path.read_text(encoding="utf-8")) if path.exists() else {"version": 1, "hooks": {}}
+        if (not isinstance(data, dict) or type(data.get("version")) is not int
+                or data["version"] != 1 or not isinstance(data.get("hooks"), dict)):
+            raise ValueError("Invalid existing Cursor hook configuration")
+        hooks = data["hooks"].setdefault("stop", [])
+        if not isinstance(hooks, list) or any(cursor_hook_error(h) for h in hooks):
+            raise ValueError("Invalid existing Cursor stop hooks")
+        command = expected_cursor_command(root, policy_path)
+        owned = next((h for h in hooks if h.get("type", "command") == "command" and h.get("command") == command), None)
+        if owned is None:
+            hooks.append({"command": command, "loop_limit": 1})
+        else:
+            owned.setdefault("loop_limit", 1)
+        content = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
+    else:
+        # Git executes hooks relative to the worktree root. Respect custom hook paths.
+        result = subprocess.run(["git", "-C", str(root), "rev-parse", "--git-path", "hooks/pre-commit"],
+                                capture_output=True, text=True, check=False)
+        if result.returncode != 0:
+            raise ValueError("pre-commit adapter requires a Git repository")
+        candidate = Path(result.stdout.strip())
+        candidate = candidate if candidate.is_absolute() else root / candidate
+        try:
+            relative = candidate.relative_to(root).as_posix()
+        except ValueError:
+            raise ValueError("External Git hook directories require manual CLI installation") from None
+        path = safe_path(root, relative)
+        command = shlex.join([*_launcher(), "--root", str(root), "--policy", policy_path.relative_to(root).as_posix(),
+                              "hooks", "run", "--slot", "pre-commit"])
+        content = "#!/bin/sh\n# exitzero managed hook\nexec " + command + "\n"
+        if path.exists() and path.read_text(encoding="utf-8") != content:
+            raise ValueError("Existing pre-commit hook preserved; chain the CLI manually")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    if adapter == "pre-commit":
+        path.chmod(path.stat().st_mode | 0o111)
+    manifest["files"][relative] = hashlib.sha256(path.read_bytes()).hexdigest()
+    target = safe_path(root, ".exitzero/hooks.json")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(manifest, sort_keys=True, indent=2) + "\n", encoding="utf-8")
+    return relative
+
+
+def lint_installed(context: Context) -> list[Finding]:
+    manifest = _manifest(context.root)
+    findings = []
+    for relative, digest in manifest["files"].items():
+        path = safe_path(context.root, relative)
+        if not path.is_file() or hashlib.sha256(path.read_bytes()).hexdigest() != digest:
+            findings.append(Finding("harness.hooks-drift", "Installed hook changed or disappeared; review and reinstall it.", relative))
+    return findings
+
+
+def cursor_response(receipt: dict, event: str, payload: dict) -> dict:
+    passed = receipt["exit_code"] == 0
+    if event in {"preToolUse", "beforeShellExecution", "beforeMCPExecution"}:
+        return {"permission": "allow" if passed else "deny", "user_message": "exitzero: " + receipt["status"],
+                "agent_message": "Review the exitzero run receipt." if not passed else ""}
+    if event == "postToolUse" and not passed:
+        return {"additional_context": "exitzero failed. Inspect the run receipt and fix the reported checks."}
+    if event == "stop" and not passed and payload.get("status") != "aborted" and payload.get("loop_count", 0) < 1:
+        return {"followup_message": "exitzero failed. Run exitzero check, inspect the receipt, and fix the reported checks."}
+    return {}

exitzero/ledger.py

@@ -0,0 +1,25 @@
+"""Append-only per-run receipts; no source, environment or command output."""
+import json
+from pathlib import Path
+import tempfile
+
+from .files import safe_path
+
+
+def persist(root: Path, receipt: dict) -> str:
+    directory = safe_path(root, ".exitzero/runs")
+    directory.mkdir(parents=True, exist_ok=True)
+    relative = f".exitzero/runs/{receipt['run_id']}.json"
+    destination = safe_path(root, relative)
+    receipt["receipt"] = relative
+    temporary: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(mode="w", dir=directory, prefix=".pending-", encoding="utf-8", delete=False) as handle:
+            temporary = Path(handle.name)
+            json.dump(receipt, handle, ensure_ascii=False, sort_keys=True, indent=2)
+            handle.write("\n")
+        temporary.replace(destination)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+    return relative

exitzero/loader.py

@@ -0,0 +1,19 @@
+"""Load only policy-selected plugins, by entry point or explicit module name."""
+import importlib
+from importlib.metadata import entry_points
+
+from .api import API_VERSION, Registry
+
+
+def discover(names: list[str]) -> Registry:
+    registry = Registry()
+    available = entry_points(group="exitzero.plugins")
+    for name in names:
+        matches = [entry for entry in available if entry.name == name]
+        if len(matches) > 1:
+            raise ValueError("Ambiguous plugin entry point")
+        plugin = matches[0].load() if matches else importlib.import_module(name)
+        if getattr(plugin, "API_VERSION", None) != API_VERSION:
+            raise ValueError("Unsupported plugin API version")
+        plugin.register(registry)
+    return registry