Metadata-Version: 2.4
Name: git-conflict-guardian
Version: 0.1.1
Summary: Surfaces why code changed before you build on top of it
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.40.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# PR Guardian

Know why code changed **before** you build on top of it.

PR Guardian runs as a `git` hook and alerts you immediately after `git pull` when your uncommitted work overlaps with what a teammate just merged — and explains **why** their change was made using AI.

---

## The Problem

```
Monday 9am   — You start editing auth.py (3 hours of work, not committed)
Monday 11am  — Teammate merges a PR that also changes auth.py
               You do git pull, have no idea auth.py just changed
               You keep coding on top of it
Wednesday    — You raise a PR
               Reviewer says "this conflicts with PR #847 from Monday"
               You now have to rework 2 days of code
```

## The Fix

```
⚠  PR Guardian  1 overlapping file — read before you continue

  auth.py  ←  PR #847 by @teammate  2h ago  JIRA-1234
      Your changes overlap at lines 44–91
      "Refactored token refresh to be async — any code calling
       refresh_token() synchronously will break."
```

Guardian catches this **right after `git pull`**, while you can still act on it.

---

## Installation

```bash
pip install git-conflict-guardian
```

---

## Setup

### 1. Get tokens

| Token | Where to get it |
|---|---|
| GitHub personal access token | github.com → Settings → Developer settings → Tokens (classic) → `repo` scope |
| Anthropic API key | console.anthropic.com → API Keys |

### 2. Configure

```bash
guardian setup
```

Enter when prompted:
- **GitHub token:** `ghp_...`
- **GitHub repo:** `owner/your-repo` (e.g. `acme/backend`)
- **Anthropic API key:** `sk-ant-...`

#### Using a LiteLLM proxy (company Claude)?

```bash
export ANTHROPIC_BASE_URL=https://your-company-litellm-url/
```

Add to `~/.bashrc` or `~/.zshrc` to persist.

### 3. Install the git hook

```bash
cd /path/to/your/project
guardian install
```

### 4. Done

Use `git pull` as normal. Guardian fires automatically after every pull.

---

## Commands

```bash
guardian install          # install post-merge hook into current repo
guardian setup            # configure tokens interactively
guardian run              # manually trigger a check
guardian run --no-ai      # check without AI summary (faster)
guardian run --verbose    # show output even when no overlaps found
guardian blame auth.py --line 67   # explain why a specific line exists
```

---

## How it works

```
git pull
    ↓
post-merge hook fires
    ↓
Guardian checks:
  - what files changed in this pull?      (git diff HEAD~1..HEAD)
  - what files do YOU have uncommitted?   (git diff)
  - overlap found?
    ↓
Fetches the PR via GitHub API
Calls Claude to generate a plain-English briefing:
  - Why was this change made?
  - What assumption does it invalidate?
  - What should you watch out for?
    ↓
Prints to terminal instantly
```

---

## Difference from git merge conflicts

| | git conflict | PR Guardian |
|---|---|---|
| When | After merge fails, repo is broken | Before you commit, still coding freely |
| Info | "there's a conflict" | Why it changed + what breaks |
| Action | Forced to stop and fix | Choose to fix now or keep going |

Guardian catches **soft conflicts** — same file touched, not yet a hard merge conflict. By the time `git pull` shows a conflict, you've already wasted hours.

---

## Requirements

- Python 3.10+
- Git
- GitHub personal access token (repo scope)
- Anthropic API key (or LiteLLM proxy)
