Add README.md

README.md

@@ -0,0 +1,121 @@
+# prch - Pretty PR Checks
+
+A beautiful command-line tool for viewing GitHub Pull Request checks with style using [gum](https://github.com/charmbracelet/gum).
+
+Created for streamlined PR review workflows with Terraform Cloud and GitHub Actions.
+
+
+## Features
+
+- Color-coded PR status (Draft, Open, Merged, Closed)
+- Review approval status tracking
+- Comment count display
+- Intelligent filtering (shows only Terraform plans with changes, failures, or pending checks)
+- Compact Terraform plan formatting with emoji indicators 
+- Watch mode for continuous updates
+- Clean, formatted table output
+
+## Prerequisites
+
+- [GitHub CLI (`gh`)](https://cli.github.com/) - GitHub's official command line tool
+- [gum](https://github.com/charmbracelet/gum) - Charm's tool for glamorous shell scripts
+- `jq` - Command-line JSON processor
+- `column` - Text column formatting utility (usually pre-installed on Linux/macOS)
+
+## Installation
+
+1. Copy the script to your system:
+   ```bash
+   sudo cp prch /usr/local/bin/prch
+   sudo chmod 755 /usr/local/bin/prch
+   ```
+
+2. Verify installation:
+   ```bash
+   prch --help
+   ```
+
+## Usage
+
+### Basic Usage
+
+View PR checks for a specific pull request:
+```bash
+prch <PR_NUMBER>
+```
+
+Example:
+```bash
+prch 5
+```
+
+### Watch Mode
+
+Continuously monitor PR checks with automatic updates every 10 seconds:
+```bash
+prch <PR_NUMBER> --watch
+# or
+prch <PR_NUMBER> -w
+```
+
+Example:
+```bash
+prch 5 --watch
+```
+
+Watch mode features:
+- Auto-refreshes every 10 seconds
+- Shows "Last updated" timestamp
+- Automatically stops when all checks complete
+- Press `Ctrl+C` to exit manually
+
+## Output Format
+
+The tool displays:
+
+1. **Header**: PR number, title, and URL in a bordered box
+2. **Status Line**: PR state (Draft/Open/Merged/Closed), review status, and comment count
+3. **Check Statistics**: Total checks, successes (with hidden count), failures, and pending
+4. **Check Table**: Filtered list of checks showing:
+   - Status icon (✓ success, ✗ failure, ⏳ pending)
+   - Check name (abbreviated for Terraform Cloud checks)
+   - Description (compact format for Terraform plans: 🟢+13 🛠~3 🗑-0)
+   - Full URL to check details
+
+### Intelligent Filtering
+
+The tool only shows checks that matter:
+- ✓ Terraform plans with actual changes
+- ✓ Failed checks
+- ✓ Pending or in-progress checks
+- ✗ Successful routine checks (hidden to reduce noise)
+- ✗ "Run not triggered" entries
+
+When all notable checks are hidden, displays: "✓ All checks passed"
+
+## Example Output
+
+```
+╔═══════════════════════════════════════════════════════════════════╗
+║                                                                   ║
+║  #680 | Adding automatic back up module to its-prod-p1p2          ║
+║       https://github.com/ucsb/its.infr.util.iac/pull/680         ║
+║                                                                   ║
+╚═══════════════════════════════════════════════════════════════════╝
+
+Status: Open | Reviews: ✓ Approved (2) | Comments: 5
+
+Total: 19 | Success: 19 (18 hidden) | Failed: 0 | Pending: 0
+
+  STATUS  NAME              DESCRIPTION       URL
+  ──────  ────              ───────────       ───
+
+  ✓       TF - its-prod-p1p2  🟢+13 🛠~3 🗑-0  https://app.terraform.io/app/...
+```
+
+## License
+
+MIT
+
+## Author
+