puter/paseo
1
0
Fork 0
mirror of https://github.com/getpaseo/paseo.git synced 2026-07-29 12:01:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add doctor health check design doc

Browse Source
This commit is contained in:
Zi Makki
2026-03-09 12:44:23 +01:00
parent 7b22fc5c3f
commit bb737dea52
1 changed files with 47 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/plans/2026-03-09-doctor-health-check-design.md Normal file
View File

@@ -0,0 +1,47 @@
# Paseo Doctor / Health Check
## Problem
Users need a way to diagnose their Paseo setup: are agent binaries installed, what versions are running, is the config valid? Currently there's no unified diagnostic — errors only surface when you try to launch an agent and it fails.
## Decision: Shared library + HTTP endpoint
The check logic lives as a pure module in `packages/server` (no daemon dependency). It inspects the local filesystem and runs `which`/`--version` commands.
- **Daemon** exposes it via `GET /api/doctor` (stateless, no WS session needed).
- **CLI** imports the module directly for offline use (`paseo doctor`), or calls the HTTP endpoint with `--remote`.
- **App** calls the HTTP endpoint from the settings screen.
## Data Model
```typescript
type CheckStatus = "ok" | "warn" | "error";
interface DoctorCheckResult {
id: string; // e.g. "provider.claude.binary"
label: string; // e.g. "Claude CLI"
status: CheckStatus;
detail: string; // e.g. "/usr/local/bin/claude (v1.0.42)"
}
interface DoctorReport {
checks: DoctorCheckResult[];
summary: { ok: number; warn: number; error: number };
timestamp: string;
}
```
## Checks
| ID | What it checks | ok | warn | error |
|---|---|---|---|---|
| provider.claude.binary | which claude | Found + path | — | Not found |
| provider.claude.version | claude --version | Version string | Parse failed | Binary missing |
| provider.codex.binary | which codex | Found + path | — | Not found |
| provider.codex.version | codex --version | Version string | Parse failed | Binary missing |
| provider.opencode.binary | which opencode | Found + path | — | Not found |
| provider.opencode.version | opencode --version | Version string | Parse failed | Binary missing |
| config.valid | Parse config.json | Valid | — | Parse/schema error |
| config.listen | Listen address format | Valid | — | Malformed |
| runtime.node | Node.js version | Version | — | Not found |
| runtime.paseo | Paseo daemon version | Version | — | Unknown |