Doctor Diagnostics
Relevant source files
The following files were used as context for generating this wiki page:
The Doctor Diagnostics system is a comprehensive health-check and configuration validation module within the OhMyOpenCode ecosystem. Its primary purpose is to verify the operational readiness of the environment by inspecting system information, configuration validity, available tools (such as LSP servers and Git), and MCP (Model Context Protocol) integration status.
This system serves as a first-line troubleshooting tool for developers, ensuring that all necessary dependencies—including Bun versions, OpenCode paths, and plugin versions—are correctly aligned. It provides structured feedback in various formats (Default, Status, Verbose, or JSON) to help users identify and fix environmental issues.
Sources: src/cli/doctor/formatter.test.ts:10-40, src/cli/doctor/formatter.test.ts:70-130
Architecture and Data Flow
The diagnostic process follows a structured flow from system inspection to formatted output. The DoctorResult object acts as the central data structure, aggregating results from individual check modules.
Diagnostic Result Structure
The diagnostic output is categorized into several high-level blocks:
- System Info: Tracks core versions (OpenCode, Bun, Plugin) and paths.
- Results: A collection of individual check outcomes (Pass/Warn/Fail) with specific issue descriptions and suggested fixes.
- Tools: Status of external dependencies like
ghCLI,ast-grep, and LSP servers. - MCPs: Lists both built-in and user-defined Model Context Protocol extensions.
Sources: src/cli/doctor/formatter.test.ts:7-40
Processing Flow
The following diagram illustrates how the system aggregates diagnostic data and transforms it into user-readable reports:
The system performs parallel checks across different domains (System, Config, Tools) and merges them into a single DoctorResult for formatting.
Sources: src/cli/doctor/formatter.test.ts:7-150
Output Modes and Formatting
The system supports multiple output modes to accommodate different user needs, from quick status checks to deep-dive debugging.
Supported Modes
| Mode | Purpose | Key Information Included |
|---|---|---|
| Default | General health summary | Overall status, issue count, and actionable fixes. |
| Status | Minimalist versioning | Compact string of Bun, OpenCode, and Plugin versions. |
| Verbose | Detailed debugging | Full system info, all check details, and MCP lists. |
| JSON | Machine-readable | Complete DoctorResult object for CI/CD or programmatic use. |
Sources: src/cli/doctor/formatter.test.ts:66-145
Formatting Logic
The formatting layer utilizes shared utilities to handle visual elements such as ANSI color removal for testing and consistent rendering of issues.
The format-shared.ts module provides the stripAnsi function used to sanitize output, particularly for verifying contents in the test suite.
Sources: src/cli/doctor/format-shared.ts, src/cli/doctor/formatter.test.ts:4-6
Key Components and Data Models
The DoctorResult Object
The core data model is defined by the DoctorResult structure, which includes detailed counts for the diagnostic summary.
| Field | Type | Description |
|---|---|---|
summary.total | number | Total number of checks executed. |
summary.passed | number | Number of successful checks. |
summary.failed | number | Number of checks with error severity. |
summary.warnings | number | Number of checks with warning severity. |
systemInfo.isLocalDev | boolean | Flag indicating if running in a development environment. |
tools.lspServers | Array | List of detected LSP servers (e.g., typescript, pyright). |
Sources: src/cli/doctor/formatter.test.ts:7-40
Issue Tracking
Issues within the results are highly structured to ensure they remain actionable. Each issue contains a title, description, a severity (error or warning), and an optional fix string that provides the user with the exact command or step needed to resolve the problem.
Sources: src/cli/doctor/formatter.test.ts:45-50
Conclusion
The Doctor Diagnostics system is a robust environmental validation framework. By providing specific severity-based feedback and categorized tool reporting, it ensures that the OhMyOpenCode environment is stable. Its modular architecture allows for the easy addition of new checks (LSP, MCP, or System-level) while maintaining flexible output options for both human developers and automated systems.