Doctor

Doctor & Health Checks

The Doctor system in Numan provides a comprehensive diagnostic suite designed to verify the health and integrity of the Numan environment. Its primary purpose is to identify configuration issues, stale state, or filesystem drift that could impede package management operations. It operates by scanning the Numan root directory, checking Nushell integration paths, verifying lockfile consistency, and inspecting internal journals for interrupted transactions.

Beyond reporting, the system supports safe, automated repairs for identified issues. Repairs are categorized into tiers (e.g., Auto, Confirm) based on their potential impact, ensuring that destructive or significant changes—such as refreshing Nushell path caches—require explicit user consent. The system is designed to be highly observable, offering both human-readable console output and machine-readable JSON reports.

System Architecture

The Doctor system is implemented as a CLI subcommand that delegates logic to a central checking engine. It interacts with nearly every major state component of Numan, including the Lockfile, NuPaths, and various transaction journals.

Data Structures

The system uses a structured report format to categorize diagnostic results:

Structure	Purpose
Finding	Represents a single diagnostic result, including its severity and a potential fix hint.
Severity	Enum indicating the impact of a finding: Ok, Info, Warn, or Error.
RepairTier	Categorizes how a fix is applied: None, Auto, Confirm, or Manual.
RepairRecord	Logs the outcome of an attempted repair (Applied, Skipped, Failed).
DoctorReport	The top-level container for all findings, summaries, and repair records.

Diagnostic Flow

The following diagram illustrates the sequence of checks performed during a numan doctor execution:

flowchart TD
    Start([Start Doctor]) --> RootCheck[Root Layout & Permissions]
    RootCheck --> NuPathCheck[Nu Path Cache & Drift]
    NuPathCheck --> JournalCheck[Pending Journals]
    JournalCheck --> LockfileCheck[Lockfile Integrity]
    LockfileCheck --> ActivationCheck[Activation Stale Checks]
    ActivationCheck --> RegistryCheck[Registry Configuration]
    RegistryCheck --> NupmCheck[nupm Coexistence]
    NupmCheck --> Report([Generate Report])

Loading

The diagnostic engine sequentially validates the filesystem, Nushell environment, internal state files, and external compatibility.

Health Check Categories

1. Root and Layout

The system verifies that the Numan root directory exists and is writable by performing a temporary file write test (.doctor-write-test). It also ensures the presence of the standard directory layout: nu_state/, state/, packages/, and registries/.

2. Nushell Paths and Drift

This check validates the cached Nushell environment. It detects if the current Nushell binary hash differs from the one cached during numan init (binary drift) or if the vendor-autoload directories have changed.

3. Journal Reconciliation

The doctor inspects internal journals to find interrupted operations. It identifies:

• Pending Activation Journals: Interrupted plugin or module registrations.
• Stale Journals: Journals tied to a Nushell identity that no longer matches the current binary.
• Lifecycle Journals: Interrupted update, remove, or gc operations that require manual intervention.

4. Activation and Lockfile

The system cross-references the lockfile with the current environment to ensure all active packages are compatible.

• Stale Activation: Detects if a plugin or module was activated for a different version of Nushell.
• Managed File Integrity: Verifies the numan.nu autoload file exists and bears the OWNERSHIP_MARKER to prevent overwriting foreign files.
• Payload Verification: Checks if the immutable package directories referenced in the lockfile actually exist on disk.

Repair Mechanism

The repair system applies fixes based on the RepairTier associated with each Finding. When numan doctor --fix is invoked, the system follows a specific protocol:

1. Mutation Lock: The system acquires a global mutation lock on the Numan root to prevent concurrent writes.
2. Tiered Execution:
   • Auto: Fixes like creating missing layout directories or syncing missing registry indexes are applied automatically.
   • Confirm: Fixes that refresh path caches (init --refresh) or reconcile journals require the --yes flag or interactive confirmation.
   • Manual: Issues like foreign ownership of managed files or missing package payloads require user intervention and provide specific command hints.

Repair Execution Sequence

sequenceDiagram
    participant CLI as Doctor CLI
    participant Mut as Mutation Lock
    participant Rep as Repair Engine
    participant Disk as Filesystem/State

    CLI->>Mut: acquire_mutation_lock(root)
    Mut-->>CLI: Lock Acquired
    loop For each Finding
        CLI->>Rep: Attempt Repair
        alt Tier == Auto
            Rep->>Disk: Apply Fix
        else Tier == Confirm AND --yes
            Rep->>Disk: Apply Fix (e.g. init::execute)
        else Tier == Manual
            Note right of Rep: Skip (Print Fix Hint)
        end
        Rep-->>CLI: Return RepairRecord
    end
    CLI->>Mut: release lock

Loading

The repair engine uses the same command handlers as init and activate to ensure consistency.

Command Reference

Flag	Type	Description
--fix	Boolean	Applies safe automated repairs after reporting.
--yes	Boolean	Skips confirmation prompts for Confirm tier repairs.
--json	Boolean	Emits the report in machine-readable JSON format.
--nupm-home	Path	Overrides the nupm home path for coexistence checks.

Summary

The Doctor & Health Checks module serves as the primary reliability tool for Numan. By combining deep state inspection with a tiered repair system, it ensures that users can recover from interrupted transactions and maintain a synchronized environment between Numan and the Nushell binary. It is a critical component of the Phase 7 "Polish" milestone, providing the necessary UX hints and diagnostic depth for a production-grade package manager.

See also

• Canonical spec: docs/numan-doctor.md