deva doctor: preflight and diagnostics

[lroolle]

Description

Half the auth/mount issue queue is users lacking a diagnostic. deva doctor checks the environment and prints pass/warn/fail lines.

Type

• New feature

Details

Checks: docker reachable; image present and tag vs versions.env expectation; per-agent auth state (config dirs exist, credential files readable, api-key env set); mount shape sanity; proxy env that breaks builds (HTTP_PROXY on docker builds); deprecated layouts (feeds #518 migration). Read-only, exit non-zero on fail, plain ascii output.

Related Files

• deva.sh
• scripts/test-status-helpers.sh

Test Plan

• doctor passes on healthy setup
• each failing check produces one actionable line and non-zero exit
• no writes anywhere (hermetic run under scratch XDG)

[lroolle]

Spec sharpened as part of the framework-vnext wrapper track (W3; W1 layered help landed in #555). Design doc: deva-bun docs/design/framework-vnext.md.

Check catalog v1 (read-only, ordered cheap-to-expensive, stop nothing on fail):

1. docker: daemon reachable; server version; socket path in use
2. image: resolved image:tag (with source: env/.deva/default); present locally? pullable? profile Dockerfile fallback would trigger?
3. config root: ~/.config/deva layout (which agent subdirs populated, autolink state per agent - linked/dir/absent)
4. per-agent auth (x7): which auth mode WOULD resolve right now and from where (mounted dir / env key / nothing) - reuse the existing resolution code paths, do not reimplement
5. workspace: .deva presence, CLAUDE.local.md/AGENTS.md injection state, git info/exclude entries
6. ports: trace UI 9317-9328 range availability; serve 3382 (port-only)
7. env hazards: HTTP(S)_PROXY set (breaks image builds), conflicting provider keys that the env scrub would drop

Output contract:

• one line per check: ok|warn|fail <area> <finding>
• every warn/fail line is followed by fix: <exact command> - doctor doubles as the first-run tutor
• plain ascii, no color codes when not a tty

Exit codes (these seed the W2 machine-surface contract, so they are load-bearing):

• 0 all ok (warns allowed with --strict off)
• 1 at least one fail
• 2 doctor itself could not run a check (e.g. docker CLI absent)

Non-goals v1: no --json (that is W2, keyed off the same check registry), no fixing/mutation, no network beyond docker calls (no registry pulls - report "not present locally" and the pull command as the fix hint).