tripwire-git 0.1.0__tar.gz

tripwire_git-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codelock contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tripwire_git-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: tripwire-git
+Version: 0.1.0
+Summary: Protect blocks of code in Git: changes need approval from an owner, an approver or a leader.
+License: MIT
+Keywords: git,code-owners,approval,pre-receive,ci
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# tripwire
+
+Protect blocks of code in Git. A protected block can only be changed by its
+owner or a leader, or by someone whose change an authorized person approved.
+Works from a local pre-commit check, a self-hosted `pre-receive` hook, or as a
+required check on GitHub, GitLab and Gitea / Forgejo.
+
+## Quick start
+
+1. Mark a block in any language, inside a comment:
+
+   ```python
+   # @lock-begin billing
+   RATE = 5
+   # @lock-end billing
+   ```
+
+2. Create `.tripwire/locks.json` (see `locks.example.json`):
+
+   ```json
+   {
+     "leaders": ["alice"],
+     "locks": [
+       {"id": "billing", "owners": ["bob"], "approvers": ["carol"]},
+       {"id": "prod-config", "owners": ["bob"], "paths": ["config/prod/", "*.pem"]}
+     ]
+   }
+   ```
+
+3. Check a change:
+
+   ```bash
+   pip install tripwire-git
+   tripwire preflight --actor dave        # uncommitted changes vs HEAD
+   ```
+
+   Output: `tripwire: BLOCKED` with `block 'billing' in app.py is locked; ask:
+   alice, bob, carol`, exit code 1.
+
+## Concepts
+
+- Blocks are marked with `@lock-begin <id>` / `@lock-end <id>`; files and
+  folders are locked with path patterns (`dir/` prefix or glob).
+- Owners and leaders may edit freely. Anyone else needs an approval from an
+  owner, an approver or a leader. You cannot approve your own change.
+- Approvals are bound to the exact before/after content of the protected
+  block (a SHA-256 digest). Edit the code again and the approval is void.
+- Rules are always read from the **base** revision (the target branch), so a
+  change cannot rewrite the rules that judge it. Changing the rules file is
+  leaders-only and cannot be approved.
+- Whitespace-only edits are ignored. Deleting markers counts as a change.
+  Unclosed blocks extend to end of file. A marker whose id is missing from the
+  rules is leaders-only.
+
+## Commands
+
+```bash
+tripwire preflight --actor alice                              # uncommitted changes vs HEAD
+tripwire check --base origin/main --head HEAD --actor alice   # a commit range
+tripwire approve --base origin/main --head HEAD --approver carol  # local approvals file
+tripwire preflight --staged                                   # staged changes only
+tripwire install-hook                                         # local pre-commit hook
+tripwire pre-receive                                          # server hook, reads stdin
+tripwire github-check | gitlab-check | gitea-check            # pull / merge requests
+```
+
+Exit codes: 0 allowed, 1 blocked, 2 error (fails closed).
+
+## Local early warning
+
+`tripwire install-hook` installs a `pre-commit` hook that checks staged changes
+and refuses the commit when a protected block is touched without permission
+(or use `.pre-commit-hooks.yaml` with the pre-commit framework). Your Git
+identity (`git config user.email`, or `TRIPWIRE_ACTOR`) must match a name in
+`locks.json`. This is a convenience: `git commit --no-verify` skips it, so the
+server-side or CI check below remains the real gate. Nothing can stop someone
+from editing files in their own clone; tripwire stops unapproved changes from
+landing on protected branches.
+
+## Platforms
+
+| Platform | Enforce with | Approvals from | Verified |
+|---|---|---|---|
+| Self-hosted Git | `hooks/pre-receive` | `.tripwire/approvals.json` | real git repos |
+| GitHub | required check, `templates/github-actions.yml` | PR reviews | real GitHub |
+| GitLab | required pipeline, `templates/gitlab-ci.yml` | MR approvals | simulated API only |
+| Gitea / Forgejo | required check, `templates/gitea-actions.yml` | PR reviews | simulated API only |
+
+On hosted services, also forbid direct pushes to the protected branch and add a
+path lock for the CI configuration, otherwise a PR can delete the check.
+
+**Self-hosted Git.** Copy `hooks/pre-receive` into the bare repo and set
+`TRIPWIRE_ACTOR` from your server's authenticated user.
+
+**GitHub.** Only a reviewer's latest review counts; it must be `APPROVED` on
+the PR's current head commit, so a new push voids it. Reviewer logins are
+matched to names in `locks.json` case-insensitively; teams are not supported.
+
+**GitLab.** Store a `read_api` project access token as `GITLAB_TOKEN`. GitLab's
+approvals endpoint is not bound to a commit, so enable "Remove all approvals
+when commits are added to the source branch"; tripwire cannot verify it.
+
+**Gitea / Forgejo.** Enable "Dismiss stale approvals". Stale and dismissed
+reviews are ignored. The API base comes from `--gitea-url`, `GITEA_API_URL`,
+`GITHUB_API_URL` or `GITHUB_SERVER_URL`.
+
+## Architecture
+
+- `engine.py`: platform-neutral core (diff + actor + rules + approvals -> decision)
+- `review.py`: shared pull / merge request check used by the platform adapters
+- `github.py`, `gitlab.py`, `gitea.py`: API clients and approval mapping
+- `approvals.py`: local approvals file
+- `gitio.py`, `cli.py`: Git access and command line
+
+## Limits
+
+- Identity comes from `--actor` / `TRIPWIRE_ACTOR` locally; it is only as
+  trustworthy as whatever sets it. On hosted platforms it is the PR author.
+- The local approvals file is trust-based: anyone able to commit could write an
+  entry naming an approver. Use platform approvals for real deployments.
+- On every platform, people who can edit branch protection or CI settings are
+  trusted; tripwire cannot stop an admin from switching the rule off.
+- Pushes with several authors are checked as one cumulative diff by the pusher.
+- Whitespace-insensitive comparison also ignores indentation changes.
+- Not yet: platform teams, Bitbucket, Azure DevOps, Gerrit, CODEOWNERS import.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+## License
+
+MIT

tripwire_git-0.1.0/README.md

@@ -0,0 +1,136 @@
+# tripwire
+
+Protect blocks of code in Git. A protected block can only be changed by its
+owner or a leader, or by someone whose change an authorized person approved.
+Works from a local pre-commit check, a self-hosted `pre-receive` hook, or as a
+required check on GitHub, GitLab and Gitea / Forgejo.
+
+## Quick start
+
+1. Mark a block in any language, inside a comment:
+
+   ```python
+   # @lock-begin billing
+   RATE = 5
+   # @lock-end billing
+   ```
+
+2. Create `.tripwire/locks.json` (see `locks.example.json`):
+
+   ```json
+   {
+     "leaders": ["alice"],
+     "locks": [
+       {"id": "billing", "owners": ["bob"], "approvers": ["carol"]},
+       {"id": "prod-config", "owners": ["bob"], "paths": ["config/prod/", "*.pem"]}
+     ]
+   }
+   ```
+
+3. Check a change:
+
+   ```bash
+   pip install tripwire-git
+   tripwire preflight --actor dave        # uncommitted changes vs HEAD
+   ```
+
+   Output: `tripwire: BLOCKED` with `block 'billing' in app.py is locked; ask:
+   alice, bob, carol`, exit code 1.
+
+## Concepts
+
+- Blocks are marked with `@lock-begin <id>` / `@lock-end <id>`; files and
+  folders are locked with path patterns (`dir/` prefix or glob).
+- Owners and leaders may edit freely. Anyone else needs an approval from an
+  owner, an approver or a leader. You cannot approve your own change.
+- Approvals are bound to the exact before/after content of the protected
+  block (a SHA-256 digest). Edit the code again and the approval is void.
+- Rules are always read from the **base** revision (the target branch), so a
+  change cannot rewrite the rules that judge it. Changing the rules file is
+  leaders-only and cannot be approved.
+- Whitespace-only edits are ignored. Deleting markers counts as a change.
+  Unclosed blocks extend to end of file. A marker whose id is missing from the
+  rules is leaders-only.
+
+## Commands
+
+```bash
+tripwire preflight --actor alice                              # uncommitted changes vs HEAD
+tripwire check --base origin/main --head HEAD --actor alice   # a commit range
+tripwire approve --base origin/main --head HEAD --approver carol  # local approvals file
+tripwire preflight --staged                                   # staged changes only
+tripwire install-hook                                         # local pre-commit hook
+tripwire pre-receive                                          # server hook, reads stdin
+tripwire github-check | gitlab-check | gitea-check            # pull / merge requests
+```
+
+Exit codes: 0 allowed, 1 blocked, 2 error (fails closed).
+
+## Local early warning
+
+`tripwire install-hook` installs a `pre-commit` hook that checks staged changes
+and refuses the commit when a protected block is touched without permission
+(or use `.pre-commit-hooks.yaml` with the pre-commit framework). Your Git
+identity (`git config user.email`, or `TRIPWIRE_ACTOR`) must match a name in
+`locks.json`. This is a convenience: `git commit --no-verify` skips it, so the
+server-side or CI check below remains the real gate. Nothing can stop someone
+from editing files in their own clone; tripwire stops unapproved changes from
+landing on protected branches.
+
+## Platforms
+
+| Platform | Enforce with | Approvals from | Verified |
+|---|---|---|---|
+| Self-hosted Git | `hooks/pre-receive` | `.tripwire/approvals.json` | real git repos |
+| GitHub | required check, `templates/github-actions.yml` | PR reviews | real GitHub |
+| GitLab | required pipeline, `templates/gitlab-ci.yml` | MR approvals | simulated API only |
+| Gitea / Forgejo | required check, `templates/gitea-actions.yml` | PR reviews | simulated API only |
+
+On hosted services, also forbid direct pushes to the protected branch and add a
+path lock for the CI configuration, otherwise a PR can delete the check.
+
+**Self-hosted Git.** Copy `hooks/pre-receive` into the bare repo and set
+`TRIPWIRE_ACTOR` from your server's authenticated user.
+
+**GitHub.** Only a reviewer's latest review counts; it must be `APPROVED` on
+the PR's current head commit, so a new push voids it. Reviewer logins are
+matched to names in `locks.json` case-insensitively; teams are not supported.
+
+**GitLab.** Store a `read_api` project access token as `GITLAB_TOKEN`. GitLab's
+approvals endpoint is not bound to a commit, so enable "Remove all approvals
+when commits are added to the source branch"; tripwire cannot verify it.
+
+**Gitea / Forgejo.** Enable "Dismiss stale approvals". Stale and dismissed
+reviews are ignored. The API base comes from `--gitea-url`, `GITEA_API_URL`,
+`GITHUB_API_URL` or `GITHUB_SERVER_URL`.
+
+## Architecture
+
+- `engine.py`: platform-neutral core (diff + actor + rules + approvals -> decision)
+- `review.py`: shared pull / merge request check used by the platform adapters
+- `github.py`, `gitlab.py`, `gitea.py`: API clients and approval mapping
+- `approvals.py`: local approvals file
+- `gitio.py`, `cli.py`: Git access and command line
+
+## Limits
+
+- Identity comes from `--actor` / `TRIPWIRE_ACTOR` locally; it is only as
+  trustworthy as whatever sets it. On hosted platforms it is the PR author.
+- The local approvals file is trust-based: anyone able to commit could write an
+  entry naming an approver. Use platform approvals for real deployments.
+- On every platform, people who can edit branch protection or CI settings are
+  trusted; tripwire cannot stop an admin from switching the rule off.
+- Pushes with several authors are checked as one cumulative diff by the pusher.
+- Whitespace-insensitive comparison also ignores indentation changes.
+- Not yet: platform teams, Bitbucket, Azure DevOps, Gerrit, CODEOWNERS import.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+## License
+
+MIT

tripwire_git-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tripwire-git"
+version = "0.1.0"
+description = "Protect blocks of code in Git: changes need approval from an owner, an approver or a leader."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["git", "code-owners", "approval", "pre-receive", "ci"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.scripts]
+tripwire = "tripwire.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

tripwire_git-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tripwire_git-0.1.0/src/tripwire/__init__.py

@@ -0,0 +1,3 @@
+"""tripwire: approval-gated protection for blocks of code in Git."""
+
+__version__ = "0.1.0"

tripwire_git-0.1.0/src/tripwire/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

tripwire_git-0.1.0/src/tripwire/approvals.py

@@ -0,0 +1,30 @@
+"""Approval providers. Local provider reads .tripwire/approvals.json.
+
+Platform providers (GitHub, GitLab, ...) will implement the same shape:
+return a list of Approval for the change being checked.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import List, Optional
+
+from .config import ConfigError
+from .models import Approval
+
+
+def parse_local(text: Optional[str]) -> List[Approval]:
+    if not text or not text.strip():
+        return []
+    try:
+        raw = json.loads(text)
+        return [Approval(i["lock"], i["approver"], i["digest"]) for i in raw]
+    except (ValueError, KeyError, TypeError) as exc:
+        raise ConfigError("invalid approvals file: %s" % exc)
+
+
+def dump_local(approvals: List[Approval]) -> str:
+    return json.dumps(
+        [{"lock": a.lock_id, "approver": a.approver, "digest": a.digest} for a in approvals],
+        indent=2,
+    ) + "\n"

tripwire_git-0.1.0/src/tripwire/blocks.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import re
+from typing import Dict, List, Tuple
+
+BEGIN = re.compile(r"@lock-begin\s+([A-Za-z0-9_.\-]+)")
+END = re.compile(r"@lock-end\s+([A-Za-z0-9_.\-]+)")
+
+Norm = Tuple[str, ...]
+
+
+def normalize(text: str) -> Norm:
+    """Strip each line and drop blank lines, so whitespace-only edits don't count."""
+    return tuple(line.strip() for line in text.splitlines() if line.strip())
+
+
+def extract_blocks(text: str) -> Dict[str, Norm]:
+    """Map block id -> normalized content between its markers.
+
+    An unclosed block extends to the end of the file (fail closed).
+    """
+    content: Dict[str, List[str]] = {}
+    open_ids: List[str] = []
+    for line in text.splitlines():
+        begin = BEGIN.search(line)
+        if begin:
+            open_ids.append(begin.group(1))
+            content.setdefault(begin.group(1), [])
+            continue
+        end = END.search(line)
+        if end:
+            if end.group(1) in open_ids:
+                open_ids.reverse()
+                open_ids.remove(end.group(1))
+                open_ids.reverse()
+            continue
+        stripped = line.strip()
+        if stripped:
+            for block_id in open_ids:
+                content[block_id].append(stripped)
+    return {k: tuple(v) for k, v in content.items()}

tripwire_git-0.1.0/src/tripwire/cli.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import List, Optional, Tuple
+
+from .approvals import dump_local, parse_local
+from .config import APPROVALS_PATH, RULES_PATH, Config, ConfigError, parse_config
+from .engine import evaluate
+from .gitio import (
+    EMPTY_TREE,
+    ZERO,
+    GitError,
+    RevSource,
+    WorktreeSource,
+    collect_changes,
+    git,
+    new_branch_base,
+    toplevel,
+)
+from .models import Approval, Decision
+
+
+def resolve_actor(explicit: Optional[str], root: str) -> str:
+    for candidate in (
+        explicit,
+        os.environ.get("TRIPWIRE_ACTOR"),
+        os.environ.get("GL_USERNAME"),
+        os.environ.get("REMOTE_USER"),
+    ):
+        if candidate:
+            return candidate
+    for key in ("tripwire.actor", "user.email"):
+        value = git(root, "config", key, check=False).decode().strip()
+        if value:
+            return value
+    raise ConfigError("cannot determine the acting user; pass --actor or set TRIPWIRE_ACTOR")
+
+
+def run_check(root: str, base: str, head: Optional[str], actor: str) -> Tuple[Optional[Config], Decision]:
+    """Rules are read from `base`, so a change cannot rewrite the rules that judge it."""
+    rules = RevSource(root, base).read(RULES_PATH)
+    if rules is None:
+        return None, Decision()
+    config = parse_config(rules)
+    head_src = RevSource(root, head) if head is not None else WorktreeSource(root)
+    approvals = parse_local(head_src.read(APPROVALS_PATH))
+    return config, evaluate(config, collect_changes(root, base, head), actor, approvals)
+
+
+def report(decision: Decision) -> int:
+    if decision.allowed:
+        print("tripwire: OK")
+        return 0
+    print("tripwire: BLOCKED", file=sys.stderr)
+    for v in decision.violations:
+        print("  - " + v.message, file=sys.stderr)
+    return 1
+
+
+def cmd_check(args, root: str) -> int:
+    actor = resolve_actor(args.actor, root)
+    _, decision = run_check(root, args.base, args.head, actor)
+    return report(decision)
+
+
+def cmd_preflight(args, root: str) -> int:
+    actor = resolve_actor(args.actor, root)
+    has_head = git(root, "rev-parse", "--verify", "-q", "HEAD", check=False).strip()
+    _, decision = run_check(root, "HEAD" if has_head else EMPTY_TREE, "" if args.staged else None, actor)
+    return report(decision)
+
+
+HOOK_MARK = "# installed by tripwire"
+HOOK = """#!/bin/sh
+%s
+# Local early warning. Bypassable with --no-verify: the server-side check is the real gate.
+if command -v tripwire >/dev/null 2>&1; then
+  exec tripwire preflight --staged
+else
+  exec python -m tripwire preflight --staged
+fi
+""" % HOOK_MARK
+
+
+def cmd_install_hook(args, root: str) -> int:
+    hooks = git(root, "rev-parse", "--git-path", "hooks").decode().strip()
+    path = os.path.join(root, hooks, "pre-commit") if not os.path.isabs(hooks) else os.path.join(hooks, "pre-commit")
+    if os.path.exists(path):
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            ours = HOOK_MARK in fh.read()
+        if not ours and not args.force:
+            print("tripwire: %s already exists; use --force to replace it" % path, file=sys.stderr)
+            return 1
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8", newline="\n") as fh:
+        fh.write(HOOK)
+    os.chmod(path, 0o755)
+    print("tripwire: installed %s" % path)
+    return 0
+
+
+def cmd_pre_receive(args, root: str) -> int:
+    actor = resolve_actor(args.actor, root)
+    status = 0
+    for line in sys.stdin:
+        parts = line.split()
+        if len(parts) < 3:
+            continue
+        old, new, ref = parts[:3]
+        if new == ZERO:
+            continue
+        base = old if old != ZERO else new_branch_base(root, new)
+        if base is None:
+            continue
+        _, decision = run_check(root, base, new, actor)
+        if not decision.allowed:
+            print("tripwire: push to %s rejected" % ref, file=sys.stderr)
+            status = report(decision) or status
+    return status
+
+
+def _pull_number(explicit: Optional[int]) -> int:
+    if explicit is not None:
+        return explicit
+    event = os.environ.get("GITHUB_EVENT_PATH")
+    if not event or not os.path.isfile(event):
+        raise ConfigError("pull request number unknown; pass --pr")
+    with open(event, encoding="utf-8") as fh:
+        number = json.load(fh).get("pull_request", {}).get("number")
+    if number is None:
+        raise ConfigError("not a pull_request event; pass --pr")
+    return int(number)
+
+
+def cmd_github_check(args, root: str) -> int:
+    from .github import GitHubClient, check_pull_request
+
+    return report(check_pull_request(root, GitHubClient.from_env(args.github_repo), _pull_number(args.pr)))
+
+
+def cmd_gitea_check(args, root: str) -> int:
+    from .gitea import GiteaClient, check_pull_request
+
+    client = GiteaClient.from_env(args.gitea_repo, args.gitea_url)
+    return report(check_pull_request(root, client, _pull_number(args.pr)))
+
+
+def cmd_gitlab_check(args, root: str) -> int:
+    from .gitlab import GitLabClient, check_merge_request
+
+    iid = args.mr or os.environ.get("CI_MERGE_REQUEST_IID")
+    if not iid:
+        raise ConfigError("merge request number unknown; pass --mr or run in a merge request pipeline")
+    return report(check_merge_request(root, GitLabClient.from_env(args.gitlab_project), int(iid)))
+
+
+def cmd_approve(args, root: str) -> int:
+    config, decision = run_check(root, args.base, args.head, actor="")
+    if config is None:
+        print("tripwire: no rules file at base", file=sys.stderr)
+        return 2
+    if args.approver not in config.everyone():
+        print("tripwire: %s is not an owner, approver or leader" % args.approver, file=sys.stderr)
+        return 1
+    path = os.path.join(root, APPROVALS_PATH)
+    existing: List[Approval] = []
+    if os.path.isfile(path):
+        with open(path, encoding="utf-8") as fh:
+            existing = parse_local(fh.read())
+    added = 0
+    for v in decision.violations:
+        if v.digest and (args.lock is None or v.lock_id == args.lock):
+            lock = config.get(v.lock_id)
+            allowed = set(config.leaders) | (set(lock.owners) | set(lock.approvers) if lock else set())
+            if args.approver in allowed:
+                existing.append(Approval(v.lock_id, args.approver, v.digest))
+                added += 1
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(dump_local(existing))
+    print("tripwire: recorded %d approval(s) in %s" % (added, APPROVALS_PATH))
+    return 0 if added else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="tripwire")
+    p.add_argument("--repo", default=".", help="path inside the repository")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    c = sub.add_parser("check", help="check base..head (head defaults to the working tree)")
+    c.add_argument("--base", required=True)
+    c.add_argument("--head")
+    c.add_argument("--actor")
+    c.set_defaults(func=cmd_check)
+
+    f = sub.add_parser("preflight", help="check uncommitted changes against HEAD")
+    f.add_argument("--actor")
+    f.add_argument("--staged", action="store_true", help="check only staged changes (for pre-commit)")
+    f.set_defaults(func=cmd_preflight)
+
+    h = sub.add_parser("install-hook", help="install a local pre-commit hook")
+    h.add_argument("--force", action="store_true", help="replace an existing pre-commit hook")
+    h.set_defaults(func=cmd_install_hook)
+
+    r = sub.add_parser("pre-receive", help="server hook: read ref updates from stdin")
+    r.add_argument("--actor")
+    r.set_defaults(func=cmd_pre_receive)
+
+    g = sub.add_parser("github-check", help="check a GitHub pull request using its reviews")
+    g.add_argument("--pr", type=int, help="PR number (default: from GITHUB_EVENT_PATH)")
+    g.add_argument("--github-repo", help="owner/name (default: GITHUB_REPOSITORY)")
+    g.set_defaults(func=cmd_github_check)
+
+    gt = sub.add_parser("gitea-check", help="check a Gitea/Forgejo pull request using its reviews")
+    gt.add_argument("--pr", type=int, help="PR number (default: from GITHUB_EVENT_PATH)")
+    gt.add_argument("--gitea-repo", help="owner/name (default: GITHUB_REPOSITORY)")
+    gt.add_argument("--gitea-url", help="API base, e.g. https://git.example.com/api/v1")
+    gt.set_defaults(func=cmd_gitea_check)
+
+    gl = sub.add_parser("gitlab-check", help="check a GitLab merge request using its approvals")
+    gl.add_argument("--mr", type=int, help="MR iid (default: CI_MERGE_REQUEST_IID)")
+    gl.add_argument("--gitlab-project", help="project id or path (default: CI_PROJECT_ID)")
+    gl.set_defaults(func=cmd_gitlab_check)
+
+    a = sub.add_parser("approve", help="record an approval for the pending change")
+    a.add_argument("--base", required=True)
+    a.add_argument("--head")
+    a.add_argument("--approver", required=True)
+    a.add_argument("--lock", help="only approve this lock id")
+    a.set_defaults(func=cmd_approve)
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        root = toplevel(args.repo) if args.command != "pre-receive" else os.path.abspath(args.repo)
+        return args.func(args, root)
+    except (ConfigError, GitError) as exc:
+        print("tripwire: error: %s" % exc, file=sys.stderr)
+        return 2