feat(cmd): add doctor command for diagnosing configuration issues

[CalvinAllen]

@

Summary

Add a new dtvem doctor command that diagnoses common dtvem configuration problems (stale PATH entries, missing shims, runtime conflicts, XDG/non-XDG inconsistencies, etc.). Default behavior is report-only; --fix enables interactive remediation.

Motivation

Issue #247 surfaced a class of problem that is easy to misdiagnose: dtvem-internal paths resolve correctly (XDG-aware), but external state — primarily the users PATH — can drift out of sync (e.g. stale ~/.dtvem/shims entry left over from a pre-XDG-support install). Today theres no single command that surfaces these inconsistencies. A doctor command gives users (and us, when triaging) one place to look.

Behavior

Default: report-only

$ dtvem doctor

• Runs all checks
• Prints findings grouped by severity (error / warning / info)
• For each finding, indicates whether it is fixable automatically or requires manual intervention
• Exits non-zero if any errors are found (useful for CI/scripts)
• Does NOT modify any state

--fix flag: interactive remediation

$ dtvem doctor --fix

• Runs all checks, prints findings as above
• For each fixable issue, prompts the user: Fix this? [y/N]
• Skips findings that require manual intervention (those still appear in the report with instructions)
• Honors -y / --yes to skip prompts and auto-apply all fixable items

--no-fix flag (or default behavior)

• Explicit opt-out for scripts that want guaranteed read-only behavior

Initial Check List

Each check should declare whether it is fixable, manual, or informational.

Check	Fixable?	Notes
Stale *\dtvem\shims entry in PATH (doesnt match current resolved ShimsDir())	Yes	Remove from registry; restart terminal
Current ShimsDir() not in PATH	Yes	Add to registry
Shims directory exists but is empty (after install)	Yes	Run reshim
Shim binaries on disk but not in shim-map cache	Yes	Reseed cache
dtvem-shim binary missing from install dir	Manual	Reinstall dtvem
System-installed runtime on PATH ahead of dtvem shims	Manual	Uninstall system runtime or reorder PATH
XDG_DATA_HOME set but install lives at ~/.dtvem (split-state)	Manual	User decision: migrate or unset XDG
~/.dtvem/config/runtimes.json references a runtime version not installed	Manual	Install the version or update config
Runtime version directory exists but provider missing executable	Manual	Reinstall runtime version

(List is not exhaustive — additional checks can be added as we identify them.)

Output Format

Each finding should include:

• Severity — error / warning / info (use existing internal/ui colors)
• Title — short description
• Detail — what was detected (e.g., the actual stale PATH value)
• Resolution — either [fixable] with what would be done, or [manual] with step-by-step instructions

Example:

✗ Stale shims entry in PATH                                       [fixable]
  Found:    C:\Users\Brad.Knowles\.dtvem\shims
  Expected: C:\Users\Brad.Knowles\.local\share\dtvem\shims
  Fix:      Remove the stale entry from User PATH

⚠ System-installed Python on PATH                                 [manual]
  Path: C:\Python311\python.exe
  This will take precedence over dtvem-managed Python versions.
  To resolve: uninstall system Python, or move dtvem shims earlier in PATH.

✓ Shim binaries match shim-map cache
✓ All configured runtime versions are installed

Architecture Sketch

• New file: src/cmd/doctor.go
• New package: src/internal/doctor/ containing:
  • Check interface with Run() Finding and Fix() error
  • Finding struct (severity, title, detail, fixable, fix instructions)
  • One file per check, registered in an init slice
• doctor command iterates registered checks, formats findings, optionally invokes Fix() per user prompt
• Tests: each check gets a unit test with table-driven scenarios

Acceptance Criteria

• dtvem doctor runs all checks read-only and prints a report
• Findings clearly indicate fixable vs manual
• dtvem doctor --fix interactively prompts per fixable finding
• dtvem doctor --fix --yes applies all fixable findings non-interactively
• Exit code is non-zero when any error-severity finding is present
• At minimum the checks listed in the table above are implemented
• All checks have unit tests
• Cross-platform (Windows, macOS, Linux)

Related

• [Bug]: reshim isn't creating shims #247 — original bug that motivated this
  @