# devpulse — Project Health Dashboard for Your Terminal
## What It Does
`devpulse` scans a directory of projects and displays a TUI dashboard showing the health of each:
- **Git status** — clean, dirty, ahead/behind remote, stale branches
- **Last activity** — time since last commit (color-coded: green < 1 week, yellow < 1 month, red > 1 month)
- **Export formats** — JSON, CSV, Markdown output
- **Interactive TUI** — keyboard navigation, open repos in browser
- **Watch mode** — continuous monitoring with configurable refresh
## Architecture
Single Rust binary. No server, no config files needed. Just run `devpulse` or `devpulse ~/projects`.
### Core Modules
```
src/
├── main.rs # CLI entry point (clap)
├── scanner.rs # Walks directory, discovers projects
├── git.rs # Git status checks (uses git2 crate)
├── tui.rs # Terminal UI (ratatui)
└── types.rs # Shared types
```
### Dependencies
- `clap` — CLI argument parsing
- `git2` — Git operations (libgit2 bindings, no shelling out)
- `ratatui` + `crossterm` — Terminal UI
- `tokio` — Async runtime (for parallel scanning + API calls)
- `reqwest` — HTTP client (GitHub API)
- `serde` + `serde_json` — JSON parsing
- `chrono` — Time handling
- `dirs` — Home directory resolution
## Development Rules
- **Incremental development.** One feature at a time, verify it works before moving on.
- **Each GitHub issue = one small, testable piece of work.**
- **Compile and test after every change.** No big bang commits.
- **Error handling:** Use `anyhow` for application errors. Never panic in production code.
- **No unwrap() in production code.** Use `?` or proper error handling.
- **Clippy clean.** Run `cargo clippy` before committing.
- **Format.** Run `cargo fmt` before committing.
## Build & Run
```bash
cargo build # Dev build
cargo run # Run (scans current directory's parent)
cargo run -- ~/projects # Scan specific directory
cargo clippy # Lint
cargo fmt # Format
cargo test # Test
```
## MVP Scope (v0.1.0)
The MVP is a **non-interactive table view** (not full TUI yet):
1. Scan a directory for projects (look for .git directories)
2. For each project, gather:
- Git status (clean/dirty, branch, ahead/behind)
- Last commit timestamp
- Uncommitted file count
3. Display a colored table in the terminal
4. Sort by last activity (most stale first)
That's it. No CI, no deps, no TUI interactions yet. Ship the simplest useful thing first.
## Future Features (post-MVP)
- Interactive TUI with keyboard navigation
- CI status from GitHub Actions
- Watch mode (auto-refresh)
- Config file for custom project paths
- Export to JSON/markdown
- Git branch cleanup suggestions
## Quality Gates (v0.1.0 Release Criteria)
Before tagging v0.1.0, ALL of the following must be true:
1. **Integration tests exist** in `tests/` directory — minimum 15 tests
2. **Integration tests verify actual binary output** against known git repo states
3. **All flags tested end-to-end:** --json, --filter, --since, --group, --sort, --no-color, --output, --csv, --markdown
4. **Error cases tested:** nonexistent dir, empty dir, not a git repo, permission errors
5. **All unit tests pass** (`cargo test`)
6. **Clippy clean** (`cargo clippy -- -D warnings`)
7. **No unwrap() in production code**
8. **README is accurate** — every documented feature actually works as described
No new features until these gates are met. Test coverage and verified output come first.
Revenue depends on trust. Trust depends on the tool doing exactly what it says.