DotDoctor

DotDoctor is a Linux CLI utility for diagnosing development environment issues and checking available system updates.

Key Features

• Development environment checks (binary availability, version checks, PATH integrity, shell config sanity, directory permissions)
• Live terminal dashboard and plain report mode
• Optional interactive auto-fix flow for actionable findings
• System dry-run update audit (--sys) for Arch packages, AUR, Flatpak, firmware, and Oh-My-Zsh
• System upgrade flow (--sysup) with strict failure handling

System Update Safety Model

• AUR parsing recognizes flagged packages, including out-of-date markers from AUR helper output
• Exit codes from update commands are handled strictly (pacman/yay, flatpak, fwupdmgr)
• Fatal network and mirror failures are treated as hard failures
• Mirror fallback is attempted when package sync fails with mirror/network symptoms
• Fatal update failures terminate with exit code 1

Requirements

• Python >=3.11
• Linux environment
• Optional system tools for extended checks and updates:
  • checkupdates
  • yay
  • flatpak
  • fwupdmgr
  • cachyos-rate-mirrors or reflector

Installation

Using local repository:

python -m venv .venv
source .venv/bin/activate
pip install -e .

Install dev dependencies:

pip install -e .[dev]

Usage

Run default scan:

dotdoctor

Run profile explicitly:

dotdoctor scan --profile python-dev

Run without fullscreen UI:

dotdoctor scan --no-ui

Export JSON report:

dotdoctor scan --json-output artifacts/report.json

Run system dry-run checks:

dotdoctor --sys

Run system upgrades:

dotdoctor --sysup

Configuration

DotDoctor supports YAML-based configuration and profiles.

• Default file: dotdoctor.yml
• Example file: dotdoctor.example.yml
• Override path: --config /path/to/config.yml

Testing

Run tests:

.venv/bin/pytest --tb=short

Project Layout

• src/dotdoctor/domain: entities, models, config schemas, ports
• src/dotdoctor/application: use-cases and system update flows
• src/dotdoctor/infrastructure: check implementations and config loading
• src/dotdoctor/cli: Typer commands and terminal rendering
• tests/: unit and integration test suites