Metadata-Version: 2.4
Name: ado-dashboard
Version: 0.3.0
Summary: Interactive terminal dashboard for Azure DevOps PRs and work items
Project-URL: Homepage, https://github.com/gaburn/ado-dashboard
Project-URL: Repository, https://github.com/gaburn/ado-dashboard
Project-URL: Issues, https://github.com/gaburn/ado-dashboard/issues
Project-URL: Changelog, https://github.com/gaburn/ado-dashboard/blob/main/CHANGELOG.md
Author: ado-dashboard contributors
License: MIT License
        
        Copyright (c) 2026 ado-dashboard contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ado,azure-devops,dashboard,pull-requests,terminal,textual,tui,work-items
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: platformdirs>=3.0
Requires-Dist: textual<5,>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# ADO Dashboard

ADO Dashboard is a keyboard-driven terminal dashboard for Azure DevOps (ADO). If you spend your day reviewing PRs, triaging work items, and managing AI coding sessions — this keeps all of it in your terminal, no browser tabs required.

[![CI](https://github.com/gaburn/ado-dashboard/actions/workflows/ci.yml/badge.svg)](https://github.com/gaburn/ado-dashboard/actions/workflows/ci.yml)
![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

## Demo Mode

Try the dashboard instantly — no ADO credentials, no setup wizard, no real data.

```bash
ado-dashboard --demo
# or
ADO_DASHBOARD_DEMO=1 ado-dashboard
```

The `--demo` flag populates every tab with fictional Tolkien-themed fixture data (Middle-earth org, Fellowship project, Gandalf the Grey as user). It's perfect for screenshots, presentations, or just exploring the interface before connecting to a real ADO org. No Azure CLI calls are made.

## Install & Run

![ADO Dashboard — My PRs tab in demo mode](docs/screenshots/01-my-prs.png)

> _Screenshots above and below were captured in `--demo` mode with fictional Middle-earth data._


```bash
git clone https://github.com/gaburn/ado-dashboard.git
cd ado-dashboard
pip install -e .
ado-dashboard
```

On first launch an interactive setup wizard walks you through configuration.
Re-run it any time with `ado-dashboard --setup`.

## Prerequisites

| Requirement | Install / verify |
|---|---|
| **Python 3.12+** | `python --version` |
| **Azure CLI** (authenticated) | [Install](https://learn.microsoft.com/cli/azure/install-azure-cli), then `az login` |
| **azure-devops extension** | `az extension add --name azure-devops` |
| **Triage only:** PowerShell (`pwsh` or `powershell`) | A `Get-TriageItems.ps1.example` template is included; copy and customise it, then set `triage_script_path` in Settings |

## Tabs

| # | Tab | What it shows |
|---|---|---|
| 1 | **My PRs** | Active PRs you created (across multiple projects). Draft PRs are dimmed. Status column shows colored approval indicators: ✓ green (approved), ✗ red (rejected), ~ yellow (suggestions), · dim (no votes). |
| 2 | **Reviewing** | PRs where you are a reviewer. Vote status shown as ✓ approved / ✗ rejected / · pending. Declined PRs filtered out. Approved reviews highlighted green. |
| 3 | **Work Items** | ADO work items assigned to you. Filters out Closed, Done, Completed, Cut, and Resolved states. |
| 4 | **Triage** | On-call triage board with a board selector dropdown, priority groups, categorization, action plan, and clickable links. Switching boards refreshes the view with a loading indicator. |
| 5 | **Copilot Sessions** | Active Copilot CLI sessions with status, intent, and working directory. Press `R` (Shift+R) to resume an inactive session in a new Windows Terminal tab. Press `f` to focus the terminal of an active session. |

### Screenshots

<details>
<summary><strong>Reviewing</strong> — PRs where you are a reviewer</summary>

![Reviewing tab](docs/screenshots/02-reviewing.png)

</details>

<details>
<summary><strong>Work Items</strong> — assigned items across Epic / Feature / Story / Task / Bug</summary>

![Work Items tab](docs/screenshots/03-work-items.png)

</details>

<details>
<summary><strong>Triage</strong> — priority-grouped board with AI-assisted categorization</summary>

![Triage tab](docs/screenshots/04-triage.png)

</details>

<details>
<summary><strong>Copilot Sessions</strong> — resumable AI sessions with intent and last-active timestamps</summary>

![Copilot Sessions tab](docs/screenshots/05-copilot-sessions.png)

</details>

## Keyboard Shortcuts

| Key | Action |
|---|---|
| `↑` `↓` | Move between rows |
| `Enter` | Open detail view |
| `Escape` | Back to list / clear search |
| `1`–`5` | Switch tab |
| `o` | Open selected item in browser |
| `c` | Copy selected item to clipboard |
| `r` | Refresh data |
| `/` | Search / filter active tab |
| `SHIFT`+`0`–`6` | Sort by column |
| `R` (Shift+R) | Resume a Copilot session in new terminal tab |
| `f` | Focus terminal of active session |
| `s` | Settings screen |
| `i` | Investigate selected triage item (launches Copilot session) |
| `I` (Shift+I) | Investigate entire triage board |
| `h` | Help overlay |
| `q` | Quit |

## Configuration

Settings are resolved in order: **CLI args → environment variables → config file → defaults**.

Config file location: `%LOCALAPPDATA%\ado-dashboard\config.json` (Windows) or `~/.config/ado-dashboard/config.json` (Linux/macOS).

| Method | Example |
|---|---|
| Setup wizard | `ado-dashboard` (first run) or `ado-dashboard --setup` |
| CLI flag | `--projects MyProject,OtherProject` |
| In-app | Press `s` to open settings |

### CLI Flags

| Flag | Description |
|---|---|
| `--setup` | Re-run the configuration wizard |
| `--org` | Azure DevOps organization URL |
| `--projects` | Comma-separated project list for PR queries |
| `--user` | User email for ADO queries |

### Environment Variables

| Variable | Maps to |
|---|---|
| `ADO_ORG_URL` | Organization URL |
| `ADO_PROJECT` | Default project |
| `ADO_USER_EMAIL` | User email |
| `TRIAGE_BOARD` | Default triage board URL |
| `INVESTIGATION_MODEL` | Model for investigation sessions |
| `INVESTIGATION_AGENT` | Agent for investigation sessions |
| `INVESTIGATIONS_DIR` | Directory for investigation results |
| `ADO_DASHBOARD_REPO_ROOT` | Repository root (for skill discovery) |

In **Settings** (`s`), the **Triage Boards** section lets you configure multiple boards with separate **Name** and **URL** fields, then add/remove entries dynamically. Boards are stored in `config.json` as `[display_name, url]` pairs.

## UI Details

- **Status bar** — global counts per tab plus triage priority breakdown.
- **Dark theme** with ADO blue accent.
- **Version** displayed in the title bar, including git commit hash (e.g., `v0.2.0 (a3b4c5d)`) for detecting stale instances.
- **AI triage** — pluggable investigation backend (see `docs/investigation.md`) with rule-based fallback when no backend is configured.
- **Triage board selector** — dropdown to switch between configured ADO triage boards with a loading indicator while data refreshes.
- **Investigation launcher** — press `i`/`I` to launch AI-powered investigation sessions for triage items. Requires a configured `InvestigationLauncher` (see `docs/investigation.md`).
- **Dynamic settings** — investigation model and agent dropdowns are populated from the active launcher at runtime.
- **Title cleanup** — board name prefixes are automatically stripped from triage item titles for cleaner display.
- **Search** — press `/` to open a search bar that filters the active tab's table in real-time. Press `Enter` to keep the filter, `Escape` to clear it. Works on My PRs, Reviewing, Work Items, and Copilot Sessions tabs.

## How It Works

ADO Dashboard is a [Textual](https://textual.textualize.io/) TUI. It calls the `az` CLI asynchronously to fetch data from Azure DevOps, keeping the UI responsive. Detail views fetch richer metadata in the background (`az repos pr show`, `az boards work-item show`). Triage data comes from a configurable PowerShell script (see `docs/triage-and-investigation.md`). Investigation sessions are launched via the configured `InvestigationLauncher` adapter (see `docs/investigation.md`).

---

## Architecture

See [docs/architecture.md](docs/architecture.md) for module map and async model.

---

## For Contributors

| Document | Contents |
|---|---|
| [`docs/architecture.md`](docs/architecture.md) | Module map, dependency diagram, async model, screen lifecycle, state ownership |
| [`docs/ado-integration.md`](docs/ado-integration.md) | `az` command shapes, auth assumptions, error handling, JSON mapping |
| [`docs/triage-and-investigation.md`](docs/triage-and-investigation.md) | PowerShell script contract, categorizer pipeline, AI enrichment, investigation launcher |
| [`docs/investigation.md`](docs/investigation.md) | Pluggable InvestigationLauncher adapter: NoOpLauncher + custom backends |
| [`docs/configuration.md`](docs/configuration.md) | Full 4-layer resolution, config schema, setup wizard, in-app settings |
| [`docs/development.md`](docs/development.md) | Running locally, tests, adding a tab, adding a settings field, CSS conventions, known cruft |

---

## Troubleshooting / FAQ

**`az login` not authenticated**
Run `az login` to sign in, then `az account set --subscription <name-or-id>` to select the right subscription.

**No PRs or work items showing**
Verify your org URL in the config file (`%LOCALAPPDATA%\ado-dashboard\config.json` on Windows, `~/.config/ado-dashboard/config.json` on Linux/macOS). Re-run `ado-dashboard --setup` to reconfigure from scratch.

**PowerShell not found (Triage tab)**
Install [`pwsh`](https://github.com/PowerShell/PowerShell) or point the triage script to the Windows built-in `powershell`. PowerShell is only needed if you use the Triage tab.

**Triage tab shows "No triage board configured"**
That's expected — Triage is opt-in. Press `s` to open Settings and add a board URL.

**App shows version `v0.2.1-dirty`**
Your working tree has uncommitted changes. Commit or stash them and restart the app.
