dotman-cli 0.2.9__tar.gz → 0.3.0__tar.gz

{dotman_cli-0.2.9/src/dotman_cli.egg-info → dotman_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotman-cli
-Version: 0.2.9
+Version: 0.3.0
 Summary: One more dot file manager but an interesting and easy to use one.
 Author: Nimit Bhardwaj
 License: MIT
@@ -165,6 +165,7 @@ packages:
 | `dotman rollback [id]`       | Rollback a deployment by ID                    |
 | `dotman repo add <name>`     | Register current directory as a repository     |
 | `dotman repo list`           | List all registered repositories               |
+| `dotman doctor [packages]`   | Check required executables are present         |
 
 ### Options
 
@@ -221,6 +222,156 @@ packages:
 
 The `absorb_ignore` field accepts a list of regex patterns that are matched against the full file path. If a file matches any pattern, it will be skipped during absorption.
 
+## Doctor Configuration
+
+Dotman can check if required executables are present on your system before deploying packages. This helps identify missing dependencies early, preventing partial deployments and confusing errors.
+
+### Basic Configuration
+
+Define executable requirements in your package configuration:
+
+```yaml
+packages:
+  nvim:
+    depends: []
+    files:
+      - source: "nvim"
+        target: "~/.config/nvim"
+    doctor:
+      executables:
+        - name: nvim
+          severity: error
+        - name: git
+          severity: error
+```
+
+### Severity Levels
+
+The `severity` field determines how missing executables are treated:
+
+- **`error`**: The executable is required for the package to work. If missing, `dotman deploy` may fail or produce unexpected results. The doctor command returns exit code 1.
+- **`warning`**: The executable is optional or only needed for certain features. If missing, the package may still work with reduced functionality. The doctor command returns exit code 0 but shows a warning.
+
+### Example Configuration
+
+```yaml
+packages:
+  nvim-base:
+    description: "Neovim configuration with LazyVim for base"
+    files:
+      - source: "nvim/base/"
+        target: "~/.config/nvim"
+    doctor:
+      executables:
+        - name: nvim
+          severity: error
+        - name: git
+          severity: error
+
+  opencode:
+    description: "OpenCode AI assistant configuration"
+    files:
+      - source: "opencode"
+        target: "~/.config/opencode"
+    doctor:
+      executables:
+        - name: node
+          severity: warning
+        - name: bun
+          severity: warning
+
+  zsh:
+    description: "Zsh Config for the system"
+    files:
+      - source: "zsh/.zshrc"
+        target: "~/.zshrc"
+    doctor:
+      executables:
+        - name: zsh
+          severity: error
+```
+
+### Using the Doctor Command
+
+```bash
+# Check all enabled packages
+dotman doctor
+
+# Check specific packages
+dotman doctor nvim zsh
+
+# Check with custom config directory
+dotman doctor --config-dir ~/.dotfiles
+```
+
+### Example Output
+
+```
+$ dotman doctor
+
+╭───────────────────────────────────────────────────────────────────────────╮
+│ Doctor Check Results                                                      │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: nvim-base                                                        │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│ nvim         ✓ Found   error       /usr/bin/nvim                          │
+│ git          ✓ Found   error       /usr/bin/git                           │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: opencode                                                         │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│ node         ✓ Found   warning     /usr/bin/node                          │
+│ bun          ✗ Missing warning     Not in PATH                           │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: zsh                                                              │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│ zsh          ✓ Found   error       /usr/bin/zsh                           │
+╰───────────────────────────────────────────────────────────────────────────╯
+
+Summary: 0 errors, 1 warning, 4 passed
+```
+
+### Exit Codes
+
+- **Exit code 0**: No error-severity executables are missing (warnings are acceptable)
+- **Exit code 1**: One or more error-severity executables are missing
+
+### How It Works
+
+1. The doctor command loads your configuration and resolves the package dependency tree
+2. For each package with `doctor.executables` defined, it checks if each executable exists in your system's PATH
+3. Executable lookup uses `shutil.which()` for cross-platform compatibility (Linux, macOS, Windows)
+4. Results are displayed in a formatted table grouped by package
+5. A summary shows totals for errors, warnings, and passed checks
+
+### Packages Without Doctor Config
+
+Packages without a `doctor` configuration are still shown in the output with "No executable requirements":
+
+```
+$ dotman doctor
+
+╭───────────────────────────────────────────────────────────────────────────╮
+│ Doctor Check Results                                                      │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: simple-config                                                    │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│              No executable requirements                                   │
+╰───────────────────────────────────────────────────────────────────────────╯
+
+Summary: 0 errors, 0 warnings, 0 passed
+```
+
+### Best Practices
+
+- Set `severity: error` for executables that are strictly required (e.g., `nvim`, `git`)
+- Set `severity: warning` for executables that are optional or only needed for specific features
+- Run `dotman doctor` before `dotman deploy` to catch missing dependencies early
+- Use `--dry-run` with deploy to preview changes after fixing any doctor issues
+
 ### Overlapping Targets
 
 If multiple packages target the same directory, the first package (alphabetically) processes the files, and subsequent packages are skipped with a warning. This ensures predictable behavior:

{dotman_cli-0.2.9 → dotman_cli-0.3.0}/README.md

@@ -144,6 +144,7 @@ packages:
 | `dotman rollback [id]`       | Rollback a deployment by ID                    |
 | `dotman repo add <name>`     | Register current directory as a repository     |
 | `dotman repo list`           | List all registered repositories               |
+| `dotman doctor [packages]`   | Check required executables are present         |
 
 ### Options
 
@@ -200,6 +201,156 @@ packages:
 
 The `absorb_ignore` field accepts a list of regex patterns that are matched against the full file path. If a file matches any pattern, it will be skipped during absorption.
 
+## Doctor Configuration
+
+Dotman can check if required executables are present on your system before deploying packages. This helps identify missing dependencies early, preventing partial deployments and confusing errors.
+
+### Basic Configuration
+
+Define executable requirements in your package configuration:
+
+```yaml
+packages:
+  nvim:
+    depends: []
+    files:
+      - source: "nvim"
+        target: "~/.config/nvim"
+    doctor:
+      executables:
+        - name: nvim
+          severity: error
+        - name: git
+          severity: error
+```
+
+### Severity Levels
+
+The `severity` field determines how missing executables are treated:
+
+- **`error`**: The executable is required for the package to work. If missing, `dotman deploy` may fail or produce unexpected results. The doctor command returns exit code 1.
+- **`warning`**: The executable is optional or only needed for certain features. If missing, the package may still work with reduced functionality. The doctor command returns exit code 0 but shows a warning.
+
+### Example Configuration
+
+```yaml
+packages:
+  nvim-base:
+    description: "Neovim configuration with LazyVim for base"
+    files:
+      - source: "nvim/base/"
+        target: "~/.config/nvim"
+    doctor:
+      executables:
+        - name: nvim
+          severity: error
+        - name: git
+          severity: error
+
+  opencode:
+    description: "OpenCode AI assistant configuration"
+    files:
+      - source: "opencode"
+        target: "~/.config/opencode"
+    doctor:
+      executables:
+        - name: node
+          severity: warning
+        - name: bun
+          severity: warning
+
+  zsh:
+    description: "Zsh Config for the system"
+    files:
+      - source: "zsh/.zshrc"
+        target: "~/.zshrc"
+    doctor:
+      executables:
+        - name: zsh
+          severity: error
+```
+
+### Using the Doctor Command
+
+```bash
+# Check all enabled packages
+dotman doctor
+
+# Check specific packages
+dotman doctor nvim zsh
+
+# Check with custom config directory
+dotman doctor --config-dir ~/.dotfiles
+```
+
+### Example Output
+
+```
+$ dotman doctor
+
+╭───────────────────────────────────────────────────────────────────────────╮
+│ Doctor Check Results                                                      │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: nvim-base                                                        │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│ nvim         ✓ Found   error       /usr/bin/nvim                          │
+│ git          ✓ Found   error       /usr/bin/git                           │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: opencode                                                         │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│ node         ✓ Found   warning     /usr/bin/node                          │
+│ bun          ✗ Missing warning     Not in PATH                           │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: zsh                                                              │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│ zsh          ✓ Found   error       /usr/bin/zsh                           │
+╰───────────────────────────────────────────────────────────────────────────╯
+
+Summary: 0 errors, 1 warning, 4 passed
+```
+
+### Exit Codes
+
+- **Exit code 0**: No error-severity executables are missing (warnings are acceptable)
+- **Exit code 1**: One or more error-severity executables are missing
+
+### How It Works
+
+1. The doctor command loads your configuration and resolves the package dependency tree
+2. For each package with `doctor.executables` defined, it checks if each executable exists in your system's PATH
+3. Executable lookup uses `shutil.which()` for cross-platform compatibility (Linux, macOS, Windows)
+4. Results are displayed in a formatted table grouped by package
+5. A summary shows totals for errors, warnings, and passed checks
+
+### Packages Without Doctor Config
+
+Packages without a `doctor` configuration are still shown in the output with "No executable requirements":
+
+```
+$ dotman doctor
+
+╭───────────────────────────────────────────────────────────────────────────╮
+│ Doctor Check Results                                                      │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: simple-config                                                    │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│              No executable requirements                                   │
+╰───────────────────────────────────────────────────────────────────────────╯
+
+Summary: 0 errors, 0 warnings, 0 passed
+```
+
+### Best Practices
+
+- Set `severity: error` for executables that are strictly required (e.g., `nvim`, `git`)
+- Set `severity: warning` for executables that are optional or only needed for specific features
+- Run `dotman doctor` before `dotman deploy` to catch missing dependencies early
+- Use `--dry-run` with deploy to preview changes after fixing any doctor issues
+
 ### Overlapping Targets
 
 If multiple packages target the same directory, the first package (alphabetically) processes the files, and subsequent packages are skipped with a warning. This ensures predictable behavior:

{dotman_cli-0.2.9 → dotman_cli-0.3.0}/pyproject.toml

@@ -15,7 +15,7 @@ classifiers = [
     "Environment :: Console",
     "License :: OSI Approved :: MIT License",
 ]
-version = "0.2.9"
+version = "0.3.0"
 description = "One more dot file manager but an interesting and easy to use one."
 readme = "README.md"
 requires-python = ">=3.12"

{dotman_cli-0.2.9 → dotman_cli-0.3.0}/src/dotman/cli/__init__.py

@@ -5,6 +5,7 @@ from dotman.cli.commands import (
     add_repository,
     clone,
     deploy,
+    doctor,
     history,
     init,
     list_packages,
@@ -32,6 +33,7 @@ __all__ = [
     "add_repository",
     "app",
     "console",
+    "doctor",
     "get_config",
     "get_repository_option",
     "repo_app",

{dotman_cli-0.2.9 → dotman_cli-0.3.0}/src/dotman/cli/commands/__init__.py

@@ -5,6 +5,7 @@ from dotman.cli.commands.absorb import absorb_changes
 from dotman.cli.commands.clean import clean
 from dotman.cli.commands.clone import clone
 from dotman.cli.commands.deploy import deploy, undeploy
+from dotman.cli.commands.doctor import doctor
 from dotman.cli.commands.init import init
 from dotman.cli.commands.pull import pull
 from dotman.cli.commands.push import push
@@ -27,6 +28,7 @@ __all__ = [
     "clean",
     "clone",
     "deploy",
+    "doctor",
     "history",
     "init",
     "list_packages",

dotman_cli-0.3.0/src/dotman/cli/commands/doctor.py

@@ -0,0 +1,135 @@
+"""Doctor command for checking required executables."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.table import Table
+
+from dotman.cli_utils import app, console, get_config
+from dotman.core.exceptions import MissingDependencyError
+from dotman.services import DoctorCheckResult, DoctorCommandResult, ExecutableChecker
+
+
+@app.command(name="doctor")
+def doctor(
+    packages: Annotated[
+        list[str] | None,
+        typer.Argument(help="Packages to check (default: all enabled)"),
+    ] = None,
+    config_dir: Annotated[
+        Path | None,
+        typer.Option("--config-dir", "-c", help="The path of config directory"),
+    ] = None,
+    backup_dir: Annotated[
+        str | None,
+        typer.Option("--backup-dir", help="Override backup directory"),
+    ] = None,
+    repo_name: Annotated[
+        str | None,
+        typer.Option("--repo", "-r", help="Repository name"),
+    ] = None,
+) -> None:
+    """Check if required executables are present in PATH."""
+    config = get_config(config_dir, backup_dir, repo_name=repo_name)
+
+    if not config.is_initialized():
+        console.print("[red]Dotman is not initialized. Run 'dotman init' first.[/red]")
+        raise typer.Exit(1)
+
+    try:
+        packages_to_check = config.get_all_packages_with_dependencies(packages)
+    except MissingDependencyError as e:
+        console.print(f"[red]Dependency error:[/red] {e}")
+        raise typer.Exit(1)
+
+    if not packages_to_check:
+        console.print("[yellow]No packages to check.[/yellow]")
+        return
+
+    checker = ExecutableChecker()
+    all_results: list[DoctorCommandResult] = []
+
+    for pkg_name in packages_to_check:
+        pkg = config.get_package(pkg_name)
+        if not pkg:
+            continue
+
+        pkg_result = DoctorCommandResult(package_name=pkg_name)
+        if pkg.doctor is None or not pkg.doctor.executables:
+            all_results.append(pkg_result)
+            continue
+
+        for executable in pkg.doctor.executables:
+            found, path = checker.find_executable(executable.name)
+            check_result = DoctorCheckResult(
+                package_name=pkg_name,
+                executable_name=executable.name,
+                found=found,
+                path=path,
+                severity=executable.severity,
+            )
+            pkg_result.checks.append(check_result)
+
+        pkg_result.summary = pkg_result.compute_summary()
+        all_results.append(pkg_result)
+
+    table = Table(title="Doctor Check Results")
+    table.add_column("Package", style="cyan")
+    table.add_column("Executable", style="white")
+    table.add_column("Status", style="white")
+    table.add_column("Severity", style="white")
+    table.add_column("Path", style="dim")
+
+    for pkg_result in all_results:
+        table.add_section()
+        table.add_row(
+            f"[bold]{pkg_result.package_name}[/bold]",
+            "",
+            "",
+            "",
+            "",
+        )
+        if not pkg_result.checks:
+            table.add_row(
+                "",
+                "[dim]No executable requirements[/dim]",
+                "",
+                "",
+                "",
+            )
+        else:
+            for check in pkg_result.checks:
+                if check.found:
+                    status = "[green]✓ Found[/green]"
+                else:
+                    status = "[red]✗ Missing[/red]"
+
+                if check.severity == "error":
+                    severity = "[red]error[/red]"
+                else:
+                    severity = "[yellow]warning[/yellow]"
+
+                path_str = check.path if check.path else "Not in PATH"
+                table.add_row(
+                    "",
+                    check.executable_name,
+                    status,
+                    severity,
+                    path_str,
+                )
+
+    console.print(table)
+
+    total_errors = sum(r.summary.get("errors", 0) for r in all_results)
+    total_warnings = sum(r.summary.get("warnings", 0) for r in all_results)
+    total_passed = sum(r.summary.get("passed", 0) for r in all_results)
+
+    console.print(
+        f"\nSummary: [red]{total_errors} errors[/red],"
+        f" [yellow]{total_warnings} warnings[/yellow],"
+        f" [green]{total_passed} passed[/green]"
+    )
+
+    if total_errors > 0:
+        raise typer.Exit(1)

{dotman_cli-0.2.9 → dotman_cli-0.3.0}/src/dotman/core/config.py

@@ -1,7 +1,7 @@
 """Configuration management for Dotman."""
 
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 import yaml
 from pydantic import BaseModel, Field
@@ -33,6 +33,19 @@ class HookConfig(BaseModel):
     post_deploy: list[str] = Field(default_factory=list)
 
 
+class DoctorExecutable(BaseModel):
+    """A required or optional executable for a package."""
+
+    name: str
+    severity: Literal["error", "warning"]
+
+
+class DoctorConfig(BaseModel):
+    """Configuration for doctor executable checks."""
+
+    executables: list[DoctorExecutable] = Field(default_factory=list)
+
+
 class PackageConfig(BaseModel):
     """Configuration for a single package."""
 
@@ -40,6 +53,7 @@ class PackageConfig(BaseModel):
     files: list[FileMapping] = Field(default_factory=list)
     variables: dict[str, Any] = Field(default_factory=dict)
     hooks: HookConfig = Field(default_factory=HookConfig)
+    doctor: DoctorConfig | None = None
 
 
 class GlobalSettings(BaseModel):

{dotman_cli-0.2.9 → dotman_cli-0.3.0}/src/dotman/core/exceptions.py

@@ -209,3 +209,15 @@ class NothingToCommitError(RepositoryError):
     """No changes to commit in the repository."""
 
     pass
+
+
+class DoctorError(DotmanError):
+    """Doctor-related errors."""
+
+    pass
+
+
+class MissingExecutableError(DoctorError):
+    """Required executable is not found in PATH."""
+
+    pass

dotman_cli-0.3.0/src/dotman/services/__init__.py

@@ -0,0 +1,19 @@
+"""Execution services for Dotman.
+
+Provides services for executing shell command hooks during package deployment
+and checking for required executables.
+"""
+
+from dotman.services.doctor import (
+    DoctorCheckResult,
+    DoctorCommandResult,
+    ExecutableChecker,
+)
+from dotman.services.hook_executor import HookExecutor
+
+__all__ = [
+    "DoctorCheckResult",
+    "DoctorCommandResult",
+    "ExecutableChecker",
+    "HookExecutor",
+]

dotman_cli-0.3.0/src/dotman/services/doctor.py

@@ -0,0 +1,109 @@
+"""Executable checking services for the doctor command."""
+
+import shutil
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class DoctorCheckResult(BaseModel):
+    """Result of a single executable check for a package."""
+
+    package_name: str
+    executable_name: str
+    found: bool
+    path: str | None
+    severity: Literal["error", "warning"]
+
+
+class DoctorCommandResult(BaseModel):
+    """Result of the doctor command for a single package."""
+
+    package_name: str
+    checks: list[DoctorCheckResult] = Field(default_factory=list)
+    summary: dict[str, int] = Field(default_factory=dict)
+
+    def compute_summary(self) -> dict[str, int]:
+        """Compute summary statistics from checks.
+
+        Returns:
+            A dictionary with totals for 'errors', 'warnings', and 'passed'.
+        """
+        errors = 0
+        warnings = 0
+        passed = 0
+
+        for check in self.checks:
+            if check.found:
+                passed += 1
+            elif check.severity == "error":
+                errors += 1
+            else:
+                warnings += 1
+
+        return {"errors": errors, "warnings": warnings, "passed": passed}
+
+
+class ExecutableChecker:
+    """Checks if executables are present in the system PATH."""
+
+    def __init__(self) -> None:
+        """Initialize the executable checker with an empty cache."""
+        self._cache: dict[str, tuple[bool, str | None]] = {}
+
+    def find_executable(self, name: str) -> tuple[bool, str | None]:
+        """Find an executable in the system PATH.
+
+        Args:
+            name: The name of the executable to find.
+
+        Returns:
+            A tuple of (found, path) where:
+            - found: True if the executable exists in PATH
+            - path: The full path to the executable if found, None otherwise
+        """
+        if not name:
+            return (False, None)
+
+        name = name.strip()
+
+        if not name:
+            return (False, None)
+
+        if name in self._cache:
+            return self._cache[name]
+
+        try:
+            path: str | None = shutil.which(name)
+            if path is not None:
+                result: tuple[bool, str | None] = (True, path)
+            else:
+                result = (False, None)
+        except (OSError, TypeError, ValueError):
+            result = (False, None)
+
+        self._cache[name] = result
+        return result
+
+    def find_executables(self, names: list[str]) -> dict[str, tuple[bool, str | None]]:
+        """Find multiple executables in the system PATH.
+
+        Args:
+            names: List of executable names to find.
+
+        Returns:
+            A dictionary mapping executable names to (found, path) tuples.
+        """
+        return {name: self.find_executable(name) for name in names}
+
+    def clear_cache(self) -> None:
+        """Clear the executable cache."""
+        self._cache.clear()
+
+    def get_cache_size(self) -> int:
+        """Get the number of cached lookups.
+
+        Returns:
+            The number of executables in the cache.
+        """
+        return len(self._cache)

{dotman_cli-0.2.9 → dotman_cli-0.3.0/src/dotman_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotman-cli
-Version: 0.2.9
+Version: 0.3.0
 Summary: One more dot file manager but an interesting and easy to use one.
 Author: Nimit Bhardwaj
 License: MIT
@@ -165,6 +165,7 @@ packages:
 | `dotman rollback [id]`       | Rollback a deployment by ID                    |
 | `dotman repo add <name>`     | Register current directory as a repository     |
 | `dotman repo list`           | List all registered repositories               |
+| `dotman doctor [packages]`   | Check required executables are present         |
 
 ### Options
 
@@ -221,6 +222,156 @@ packages:
 
 The `absorb_ignore` field accepts a list of regex patterns that are matched against the full file path. If a file matches any pattern, it will be skipped during absorption.
 
+## Doctor Configuration
+
+Dotman can check if required executables are present on your system before deploying packages. This helps identify missing dependencies early, preventing partial deployments and confusing errors.
+
+### Basic Configuration
+
+Define executable requirements in your package configuration:
+
+```yaml
+packages:
+  nvim:
+    depends: []
+    files:
+      - source: "nvim"
+        target: "~/.config/nvim"
+    doctor:
+      executables:
+        - name: nvim
+          severity: error
+        - name: git
+          severity: error
+```
+
+### Severity Levels
+
+The `severity` field determines how missing executables are treated:
+
+- **`error`**: The executable is required for the package to work. If missing, `dotman deploy` may fail or produce unexpected results. The doctor command returns exit code 1.
+- **`warning`**: The executable is optional or only needed for certain features. If missing, the package may still work with reduced functionality. The doctor command returns exit code 0 but shows a warning.
+
+### Example Configuration
+
+```yaml
+packages:
+  nvim-base:
+    description: "Neovim configuration with LazyVim for base"
+    files:
+      - source: "nvim/base/"
+        target: "~/.config/nvim"
+    doctor:
+      executables:
+        - name: nvim
+          severity: error
+        - name: git
+          severity: error
+
+  opencode:
+    description: "OpenCode AI assistant configuration"
+    files:
+      - source: "opencode"
+        target: "~/.config/opencode"
+    doctor:
+      executables:
+        - name: node
+          severity: warning
+        - name: bun
+          severity: warning
+
+  zsh:
+    description: "Zsh Config for the system"
+    files:
+      - source: "zsh/.zshrc"
+        target: "~/.zshrc"
+    doctor:
+      executables:
+        - name: zsh
+          severity: error
+```
+
+### Using the Doctor Command
+
+```bash
+# Check all enabled packages
+dotman doctor
+
+# Check specific packages
+dotman doctor nvim zsh
+
+# Check with custom config directory
+dotman doctor --config-dir ~/.dotfiles
+```
+
+### Example Output
+
+```
+$ dotman doctor
+
+╭───────────────────────────────────────────────────────────────────────────╮
+│ Doctor Check Results                                                      │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: nvim-base                                                        │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│ nvim         ✓ Found   error       /usr/bin/nvim                          │
+│ git          ✓ Found   error       /usr/bin/git                           │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: opencode                                                         │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│ node         ✓ Found   warning     /usr/bin/node                          │
+│ bun          ✗ Missing warning     Not in PATH                           │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: zsh                                                              │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│ zsh          ✓ Found   error       /usr/bin/zsh                           │
+╰───────────────────────────────────────────────────────────────────────────╯
+
+Summary: 0 errors, 1 warning, 4 passed
+```
+
+### Exit Codes
+
+- **Exit code 0**: No error-severity executables are missing (warnings are acceptable)
+- **Exit code 1**: One or more error-severity executables are missing
+
+### How It Works
+
+1. The doctor command loads your configuration and resolves the package dependency tree
+2. For each package with `doctor.executables` defined, it checks if each executable exists in your system's PATH
+3. Executable lookup uses `shutil.which()` for cross-platform compatibility (Linux, macOS, Windows)
+4. Results are displayed in a formatted table grouped by package
+5. A summary shows totals for errors, warnings, and passed checks
+
+### Packages Without Doctor Config
+
+Packages without a `doctor` configuration are still shown in the output with "No executable requirements":
+
+```
+$ dotman doctor
+
+╭───────────────────────────────────────────────────────────────────────────╮
+│ Doctor Check Results                                                      │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: simple-config                                                    │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│              No executable requirements                                   │
+╰───────────────────────────────────────────────────────────────────────────╯
+
+Summary: 0 errors, 0 warnings, 0 passed
+```
+
+### Best Practices
+
+- Set `severity: error` for executables that are strictly required (e.g., `nvim`, `git`)
+- Set `severity: warning` for executables that are optional or only needed for specific features
+- Run `dotman doctor` before `dotman deploy` to catch missing dependencies early
+- Use `--dry-run` with deploy to preview changes after fixing any doctor issues
+
 ### Overlapping Targets
 
 If multiple packages target the same directory, the first package (alphabetically) processes the files, and subsequent packages are skipped with a warning. This ensures predictable behavior:

{dotman_cli-0.2.9 → dotman_cli-0.3.0}/src/dotman_cli.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ src/dotman/cli/commands/absorb.py
 src/dotman/cli/commands/clean.py
 src/dotman/cli/commands/clone.py
 src/dotman/cli/commands/deploy.py
+src/dotman/cli/commands/doctor.py
 src/dotman/cli/commands/history.py
 src/dotman/cli/commands/init.py
 src/dotman/cli/commands/pull.py
@@ -28,6 +29,7 @@ src/dotman/managers/remote.py
 src/dotman/managers/repository.py
 src/dotman/managers/watcher.py
 src/dotman/services/__init__.py
+src/dotman/services/doctor.py
 src/dotman/services/hook_executor.py
 src/dotman_cli.egg-info/PKG-INFO
 src/dotman_cli.egg-info/SOURCES.txt

dotman_cli-0.2.9/src/dotman/services/__init__.py

@@ -1,8 +0,0 @@
-"""Execution services for Dotman.
-
-Provides services for executing shell command hooks during package deployment.
-"""
-
-from dotman.services.hook_executor import HookExecutor
-
-__all__ = ["HookExecutor"]