hans-tools/tools/gh-monitor/buildspec.md

# gh-monitor — Build Spec

**Status:** Pending Andrew's review  
**Depends on:** design.md approved

---

## Directory Layout

```
gh-monitor/
├── design.md
├── buildspec.md
├── poll.py               # Main entry point
├── config/
│   └── watched.yaml      # Repos and filter rules
├── state/
│   ├── last_seen.json    # Event cursor (gitignored)
│   └── errors.log        # Error log (gitignored)
├── requirements.txt
└── .gitignore
```

---

## Build Order

### STEP 1 — .gitignore + requirements.txt

`.gitignore`:
```
state/last_seen.json
state/errors.log
__pycache__/
*.pyc
.env
```

`requirements.txt`:
```
PyYAML>=6.0
```
(All other deps: stdlib + gh CLI)

### STEP 2 — config/watched.yaml

Starter config watching the-agency repo:
```yaml
repos:
  - owner: coding-with-hans-heinemann
    repo: the-agency
    notify_on:
      - review_submitted
      - review_comment
      - issue_comment
      - pr_closed
```

### STEP 3 — poll.py: config + state loader

Functions:
- `load_config(path) -> dict`  
  Reads watched.yaml. Raises on missing file.

- `load_state(path) -> dict`  
  Reads last_seen.json. Returns `{}` if file doesn't exist (first run).

- `save_state(state, path)`  
  Atomically writes last_seen.json (write to .tmp, rename).

### STEP 4 — poll.py: GitHub API client

Function:
- `gh_api(endpoint) -> list | dict`  
  Runs `gh api --paginate <endpoint>` as subprocess.  
  Returns parsed JSON. Raises `GHAPIError` on non-zero exit.

- `get_open_prs(owner, repo) -> list[dict]`  
  Calls `/repos/{owner}/{repo}/pulls?state=open`.  
  Returns list of PR dicts (number, title, html_url).

### STEP 5 — poll.py: event fetchers

Functions (each returns list of event dicts with `event_type`, `created_at`,
`actor`, `body`, `url`):

- `get_reviews(owner, repo, pr_number) -> list[dict]`  
  `/repos/{owner}/{repo}/pulls/{pr_number}/reviews`

- `get_review_comments(owner, repo, pr_number) -> list[dict]`  
  `/repos/{owner}/{repo}/pulls/{pr_number}/comments`

- `get_issue_comments(owner, repo, pr_number) -> list[dict]`  
  `/repos/{owner}/{repo}/issues/{pr_number}/comments`

### STEP 6 — poll.py: event diffing

Function:
- `new_events_since(events, cursor_ts) -> list[dict]`  
  Filters events to those with `created_at > cursor_ts`.  
  Returns sorted by `created_at` ascending.

### STEP 7 — poll.py: notification sender

Function:
- `notify(text)`  
  Runs `openclaw system event --text "<text>" --mode now` as subprocess.  
  Logs warning and continues on non-zero exit (best-effort).

- `format_notification(repo_slug, pr, event) -> str`  
  Builds the notification string:  
  `[gh-monitor] PR #N "title" — <actor> <action>:\n"<body[:200]>"\n<url>`

### STEP 8 — poll.py: error tracking

Module-level logic:
- `log_error(repo_slug, error, state)`  
  Appends to `state/errors.log`.  
  Increments `state["<repo_slug>"]["consecutive_errors"]` counter.  
  If counter >= 3 and not already alerted: fires one notify() alert.  
  Resets counter to 0 on successful poll for that repo.

### STEP 9 — poll.py: main poll loop

Function:
- `poll_repo(repo_cfg, state) -> dict`  
  1. Get cursor from state (or now if first run).  
  2. Fetch open PRs.  
  3. For each PR: fetch reviews, review_comments, issue_comments.  
  4. Filter to new events since cursor.  
  5. Fire notify() for each new event.  
  6. Update cursor to max(created_at) of processed events (or now if none).  
  7. Return updated state slice.

- `main()`  
  Loads config + state.  
  Calls poll_repo() for each repo in watched.yaml.  
  Saves state.  
  Exits 0.

Entry point: `if __name__ == "__main__": main()`

### STEP 10 — macOS LaunchAgent

Create `~/Library/LaunchAgents/com.hans.gh-monitor.plist`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.hans.gh-monitor</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/python3</string>
        <string>/Users/hansheinemann/Projects/hans-tools/gh-monitor/poll.py</string>
    </array>
    <key>StartInterval</key>
    <integer>300</integer>
    <key>StandardOutPath</key>
    <string>/Users/hansheinemann/Projects/hans-tools/gh-monitor/state/stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/hansheinemann/Projects/hans-tools/gh-monitor/state/stderr.log</string>
    <key>RunAtLoad</key>
    <false/>
</dict>
</plist>
```

Load with:
```bash
launchctl load ~/Library/LaunchAgents/com.hans.gh-monitor.plist
```

Pause/resume:
```bash
launchctl unload ~/Library/LaunchAgents/com.hans.gh-monitor.plist
launchctl load   ~/Library/LaunchAgents/com.hans.gh-monitor.plist
```

**Token cost:** Zero during polling. The main session is only woken when
`poll.py` calls `openclaw system event` — i.e. only when real PR activity
is detected.

---

## Testing Plan

Manual test steps (no automated tests for v1):

1. `python3 poll.py` with no state file → creates state, no notifications (first-run cursor set to now)
2. Post a comment on PR #1 → run poll.py → notification fires
3. Run poll.py again immediately → no duplicate notification (cursor advanced)
4. Break `gh` binary path temporarily → error logged, no crash
5. After 3 failed cycles → single alert fires

---

## What Is NOT in This Build

- Automated test suite
- Filtering by comment author
- Digest/batching mode
- Any write operations to GitHub
- Anything touching main branch