Metadata-Version: 2.4
Name: twgh
Version: 0.2.0
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>
```

A **chronological reading view** of everything said on a PR: top-level comments
and inline review comments, sorted by time. Think of it as a chat log — you
read top to bottom to understand the full conversation timeline. Comments in
resolved threads are hidden (`--all` to include), `--by <user>` / `--mine` to
filter.

Use `comments` when you want to **understand what happened** — context, history,
the sequence of arguments.

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

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

An **action-oriented triage view**: one row per review conversation with a
verdict showing whether it still needs attention:

- `✓ 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

Use `threads` when you want to **decide what to act on** — scan, triage, move
on.

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

#### threads vs comments

Both draw from the same PR data but serve different workflows:

| | `threads` | `comments` |
|---|---|---|
| Unit | one row per conversation | one row per comment |
| Order | by file path | by time |
| Key info | actionable verdict | full message body |
| Question answered | "what needs my response?" | "what was said?" |
| Scope | single PR or global inbox | single PR only |

### 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.

## Configuration

Optional TOML config at `~/.config/twgh/config.toml` (override with `--config`).
Bootstrap a starter with:

```sh
twgh edit --init
```

### Author exclusion

Hide PRs from bots/service accounts in `status` and `threads` (inbox mode):

```toml
[exclude]
authors = ["dependabot[bot]", "self-hosted-renovate[bot]"]

# Per-host additions (extends the global list):
[exclude."github.enterprise.com"]
authors = ["renovate-enterprise[bot]"]
```

Override the exclusion list to show a specific author:

```sh
twgh status --author "dependabot[bot]"
```

## Development

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