Metadata-Version: 2.4
Name: prdash-tui
Version: 0.2.0
Summary: Terminal-based TUI dashboard for monitoring GitHub PRs requiring your attention
Project-URL: Homepage, https://github.com/prdash/prdash
Project-URL: Repository, https://github.com/prdash/prdash
Project-URL: Issues, https://github.com/prdash/prdash/issues
Author: prdash contributors
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: httpx
Requires-Dist: pydantic
Requires-Dist: textual
Description-Content-Type: text/markdown

# PR Dash

Terminal-based TUI dashboard for monitoring GitHub pull requests that need your attention. Built with [Textual](https://textual.textualize.io/) for a rich terminal experience.

## Prerequisites

- **Python 3.12+**
- **[uv](https://docs.astral.sh/uv/)** — Python package manager
- **[gh CLI](https://cli.github.com/)** — GitHub CLI, authenticated (`gh auth login`)

## Installation

### Homebrew (macOS)

```bash
brew tap prdash/prdash
brew install prdash
```

> **Note:** You may see `Failed changing dylib ID` or `Failed to fix install linkage` warnings during installation. These are cosmetic — Homebrew tries to rewrite dylib IDs in pydantic-core's compiled extensions but the Mach-O headers lack sufficient padding. The app works correctly despite these warnings.

### From PyPI

```bash
# Using uv (recommended)
uv tool install prdash-tui

# Using pipx
pipx install prdash-tui

# Using pip
pip install prdash-tui
```

### Dev build (latest main branch)

```bash
brew install --head prdash
```

This builds from the latest commit on main. The version will reflect the dev state (e.g., `0.1.dev47+gc54497e`). Not recommended for general use.

### From source (development)

```bash
git clone https://github.com/prdash/prdash.git
cd prdash
uv sync                    # install dependencies
uv tool install -e .       # add `prdash` to your PATH (editable)
```

### Updating

```bash
prdash --update
```

This auto-detects your install method (Homebrew/uv/pipx/pip) and runs the appropriate upgrade command.

## Quick Start

```bash
prdash
```

Or, if running from the project directory without a global install:

```bash
uv run prdash
```

On first run, a **setup wizard** walks you through configuration:

1. **Repository** — org and repo name (auto-detected from git remote if available), or skip to monitor all repos
2. **Username** — your GitHub username (auto-detected from your auth token)
3. **Teams** — team slugs for team review requests (auto-detected from GitHub API)
4. **Confirm** — review and save

After setup, the dashboard launches automatically.

## Configuration

Config file location: `~/.config/prdash/config.toml`

### Example config

```toml
username = "octocat"
repos = ["my-org/my-repo"]  # empty list = all repos
team_slugs = ["frontend", "platform"]
poll_interval = 300
timeout = 30.0

[[query_groups]]
type = "direct_reviewer"
name = "Requested Reviewer"
enabled = true

[[query_groups]]
type = "team_reviewer"
name = "Team Reviewer"
enabled = true

[[query_groups]]
type = "mentioned"
name = "Mentioned/Involved"
enabled = true

[[query_groups]]
type = "authored"
name = "My PRs"
enabled = true

[[query_groups]]
type = "label"
name = "Labeled"
labels = ["needs-review"]
enabled = false
```

### Field reference

| Field | Type | Default | Description |
|---|---|---|---|
| `username` | string | *(required)* | Your GitHub username |
| `repos` | list[str] | `[]` | Repo filters as `"org/name"` — empty = all repos |
| `team_slugs` | list[str] | `[]` | Team slugs for team review queries |
| `poll_interval` | int | `300` | Auto-refresh interval in seconds (min 30) |
| `timeout` | float | `30.0` | HTTP request timeout in seconds (min 1.0) |
| `theme` | string | `"textual-dark"` | Color theme (20 built-in options) |
| `query_groups` | list | 5 defaults | PR query groups (see below) |

#### Query group fields

| Field | Type | Default | Description |
|---|---|---|---|
| `type` | string | *(required)* | One of the query group types below |
| `name` | string | *(required)* | Display name in the PR list |
| `labels` | list[str] | `[]` | Label filters (only for `label` type) |
| `enabled` | bool | `true` | Whether this group is active |

## CLI Flags

| Flag | Description |
|---|---|
| `-V`, `--version` | Print version and exit |
| `--update` | Update to the latest version |

## Usage

```bash
prdash
```

The dashboard has a split-pane layout:

- **Left pane** — PR list organized by query group, with collapsible sections showing title, author, age, CI status, and review status
- **Right pane** — Detail view for the selected PR with reviewers panel, Markdown description, labels, CI checks, and timeline

## Keybindings

| Key | Action |
|---|---|
| `j` / `Down` | Move cursor down in PR list |
| `k` / `Up` | Move cursor up in PR list |
| `Enter` | Toggle group collapse/expand, or open PR in browser |
| `Left` / `Right` | Collapse / expand group header |
| `Tab` | Switch focus between left and right panes |
| `r` | Refresh PR data |
| `c` | Checkout selected PR branch (via `gh pr checkout`) |
| `y` | Copy selected PR URL to clipboard |
| `Y` | Copy PR reference (`org/repo#123`) or branch name |
| `/` | Search / filter PRs by title, author, repo, or number |
| `Ctrl+P` | Open command palette |
| `?` | Show keyboard shortcuts help |
| `S` | Open settings screen |
| `Escape` | Close overlay / clear filter |
| `q` | Quit |

## Query Groups

Query groups define which PRs appear in the dashboard. There are 5 types:

| Type | Description |
|---|---|
| `direct_reviewer` | PRs where you are directly requested as a reviewer |
| `team_reviewer` | PRs where one of your teams is requested for review |
| `mentioned` | PRs where you are mentioned or involved |
| `authored` | PRs you authored |
| `reviewed_by` | PRs you have already reviewed |
| `assigned` | PRs assigned to you |
| `label` | PRs matching specific labels (set via `labels` field) |
| `ready_to_pr` | Local branches without open PRs (ready to create a PR) |

PRs are deduplicated across groups — each PR appears only in its highest-priority group (priority follows the order listed above).

You can customize query groups by:

- **Adding/removing groups** in `config.toml` or via the in-app query groups screen
- **Reordering** to change display and deduplication priority
- **Toggling** `enabled` to hide groups without deleting them
- **Using labels** with the `label` type to track specific categories

## In-App Settings

Press `S` to open the settings screen where you can edit:

- Repos (comma-separated `org/name` slugs, empty = all repos)
- Username
- Team slugs
- Poll interval

From settings, you can also open the **Query Groups** screen to add, remove, reorder, and toggle query groups. Changes are saved immediately and trigger a data refresh.

## Command Palette

Press `Ctrl+P` to open the command palette with fuzzy search across all actions:

- **Jump to group** — scroll to any query group by name
- **Sort PRs** — sort by newest/oldest, CI status, review status, or diff size
- **Change theme** — switch between 20 built-in themes (dracula, monokai, nord, solarized, catppuccin, etc.)
- **Refresh**, **Settings**, **Query Groups**

## PR List Indicators

Each PR row shows:

- **CI status** — `CI:pass` (green), `CI:fail` (red), `CI:pend` (yellow)
- **Review status** — `Rev:ok` (green), `Rev:chg` (red), `Rev:pend` (yellow)
- **Merge state** — `CONFLICT` (red), `BLOCKED` (yellow), `BEHIND` (yellow)
- **Diff size** — `+350/-120` (additions in green, deletions in red)
- **Comments** — `5💬` when comments exist
- **Draft badge** — cyan `DRAFT` indicator for draft PRs
- **New PR marker** — bold dot for PRs appearing since last refresh
