Metadata-Version: 2.4
Name: twgh
Version: 0.1.2
Summary: Read-only GitHub reviewer CLI: triage, re-review diffs, comment threads
Author-email: sysid <sysid@gmx.de>
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.15.1
Requires-Dist: rich>=13.0.0

# twgh

Read-only GitHub reviewer CLI: triage what needs you, re-review only what changed
since you last looked (force-push robust), and see which of your comments were
addressed — across github.com and GitHub Enterprise.

twgh never writes to GitHub — no approvals, no comments, no merges. It is the
read side of reviewing; for actions it hands you off to the browser.

## Install

From PyPI (requires Python ≥ 3.12):

```sh
uv tool install twgh      # or: pipx install twgh
```

From source:

```sh
make install      # uv tool install -e . + bash completion
```

### Prerequisites

- The GitHub CLI [`gh`](https://cli.github.com), authenticated for each host you
  review on: `gh auth login --hostname <host>`. twgh borrows gh for auth, host
  routing, and transport; it never handles your token.

## Use-cases

### 1. Triage — which PRs need me right now?

```sh
twgh status
```

Cross-repo rollup of every open PR you are review-requested on, commented on,
or have reviewed. Per PR: author, your review state against the current head
(`needs_review` / `needs_re_review` / `up_to_date`), and open-thread count.
★ marks PRs that moved since your last `status` run — new head or new comments,
tracked via a local snapshot (the first run deliberately flags nothing).
`--json` for scripting.

### 2. Re-review — what changed since I last looked?

```sh
twgh diff <ref>
```

The author pushed again; you don't want to re-read the whole PR. `diff` anchors
on your last submitted review (else your last inline comment) and shows
anchor→HEAD, restricted to the files you commented on (`--all` for the whole
PR). The anchor is a commit OID, so the diff survives force-pushes and rebases.
With no prior review there is nothing to re-diff — it points you at `twgh open`
instead.

### 3. Catch up — what was said while I was away?

```sh
twgh comments <ref>
```

All PR discussion in one chronological stream: top-level comments plus inline
review comments. Comments in resolved threads are hidden (`--all` to include),
`--by <user>` / `--mine` to filter.

### 4. Follow up — were my comments addressed?

```sh
twgh threads [<ref>]
```

Each open conversation gets a verdict from what GitHub knows:

- `✓ resolved` — the thread is marked resolved
- `~ changed` — the anchored code moved since the comment (inspect with `twgh diff`)
- `· untouched` — the point still stands as written

Omit `<ref>` for a global inbox of open threads across all PRs that involve
you. `--mine` / `--by <user>` to filter, `--all` to include resolved.

### 5. Act — everything twgh stays out of

```sh
twgh open <ref>
```

Opens the PR in the browser for the write actions: approving, replying,
resolving, merging.

## PR references

`<ref>` is a PR URL, `host/owner/repo#N`, `owner/repo#N`, `owner/repo/N`, or a
bare number inside a repo checkout. `status` prints URLs — paste them straight
back.

## Host selection

`-H/--gh-host` overrides `$GH_HOST`, which defaults to `github.com`. Works as a
global option (`twgh -H bmw.ghe.com status`) or per command.

## Development

```sh
make test              # pytest + coverage (floor 85%)
make static-analysis   # ruff lint-fix, format, ty
```
