scc-cli 1.5.3__py3-none-any.whl

scc_cli/doctor/checks/worktree.py

@@ -0,0 +1,278 @@
+"""Git worktree health checks for doctor module.
+
+Checks for worktree health, version compatibility, and branch conflicts.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from ..types import CheckResult
+
+
+def check_worktree_health(cwd: Path | None = None) -> CheckResult | None:
+    """Check health of git worktrees in the current repository.
+
+    Parses `git worktree list --porcelain` to detect:
+    - Prunable worktrees (stale entries)
+    - Locked worktrees (with lock reason)
+    - Detached HEAD states
+    - Branch conflicts (branch checked out elsewhere)
+
+    Args:
+        cwd: Directory to check (defaults to current working directory).
+
+    Returns:
+        CheckResult with worktree health status, or None if not in a git repo.
+    """
+    if cwd is None:
+        cwd = Path.cwd()
+
+    # Check if we're in a git repo
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(cwd), "rev-parse", "--is-inside-work-tree"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode != 0:
+            # Not a git repo - skip check
+            return None
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return None
+
+    # Parse worktree list --porcelain
+    worktree_data = _parse_worktree_porcelain(cwd)
+    if not worktree_data:
+        # No worktrees or failed to parse
+        return CheckResult(
+            name="Worktrees",
+            passed=True,
+            message="No worktrees configured (single checkout)",
+        )
+
+    # Count issues
+    prunable_count = sum(1 for wt in worktree_data if wt.get("prunable"))
+    locked_count = sum(1 for wt in worktree_data if wt.get("locked"))
+    detached_count = sum(1 for wt in worktree_data if wt.get("detached"))
+
+    # Build summary message
+    issues = []
+    if prunable_count > 0:
+        issues.append(f"{prunable_count} prunable")
+    if locked_count > 0:
+        issues.append(f"{locked_count} locked")
+    if detached_count > 0:
+        issues.append(f"{detached_count} detached")
+
+    total = len(worktree_data)
+
+    if not issues:
+        return CheckResult(
+            name="Worktrees",
+            passed=True,
+            message=f"{total} worktree{'s' if total != 1 else ''}, all healthy",
+        )
+
+    # Build fix hints
+    fix_hints = []
+    fix_commands = []
+    if prunable_count > 0:
+        fix_hints.append("Remove stale worktree entries with prune")
+        fix_commands.append("scc worktree prune")
+    if locked_count > 0:
+        # Find locked worktrees and show reasons
+        for wt in worktree_data:
+            if wt.get("locked"):
+                reason = wt.get("lock_reason", "no reason given")
+                path = Path(wt.get("path", "")).name
+                fix_hints.append(f"'{path}' locked: {reason}")
+
+    return CheckResult(
+        name="Worktrees",
+        passed=prunable_count == 0,  # Fail only if prunable (needs cleanup)
+        message=f"{total} worktree{'s' if total != 1 else ''}: {', '.join(issues)}",
+        fix_hint="; ".join(fix_hints) if fix_hints else None,
+        fix_commands=fix_commands if fix_commands else None,
+        severity="warning" if prunable_count > 0 else "info",
+    )
+
+
+def _parse_worktree_porcelain(repo_path: Path) -> list[dict[str, Any]]:
+    """Parse git worktree list --porcelain output.
+
+    Porcelain format example:
+        worktree /path/to/main
+        HEAD abc123
+        branch refs/heads/main
+
+        worktree /path/to/feature
+        HEAD def456
+        branch refs/heads/feature
+        locked
+        locked reason: deployment in progress
+
+        worktree /path/to/old
+        HEAD ghi789
+        detached
+        prunable
+
+    Returns:
+        List of dicts with keys: path, branch, detached, locked, lock_reason, prunable
+    """
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(repo_path), "worktree", "list", "--porcelain"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode != 0:
+            return []
+
+        worktrees = []
+        current: dict[str, Any] = {}
+
+        for line in result.stdout.split("\n"):
+            if line.startswith("worktree "):
+                # Start of new worktree entry
+                if current and current.get("path"):
+                    worktrees.append(current)
+                current = {
+                    "path": line[9:],
+                    "branch": "",
+                    "detached": False,
+                    "locked": False,
+                    "lock_reason": "",
+                    "prunable": False,
+                }
+            elif line.startswith("branch "):
+                current["branch"] = line[7:].replace("refs/heads/", "")
+            elif line == "detached":
+                current["detached"] = True
+            elif line == "locked":
+                current["locked"] = True
+            elif line.startswith("locked "):
+                # "locked reason: ..." format
+                current["locked"] = True
+                current["lock_reason"] = line[7:]  # Includes "reason: " prefix
+            elif line == "prunable":
+                current["prunable"] = True
+            elif line.startswith("prunable "):
+                # "prunable reason: ..." format
+                current["prunable"] = True
+
+        # Don't forget the last worktree
+        if current and current.get("path"):
+            worktrees.append(current)
+
+        return worktrees
+
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return []
+
+
+def check_git_version_for_worktrees() -> CheckResult | None:
+    """Check if git version supports stable worktree operations.
+
+    Git 2.20+ is recommended for stable worktree behavior.
+    Earlier versions may have issues with locked worktrees and pruning.
+
+    Returns:
+        CheckResult with version check status, or None if git not installed.
+    """
+    from ... import git as git_module
+
+    if not git_module.check_git_installed():
+        return None  # Already covered by check_git()
+
+    version = git_module.get_git_version()
+    if not version:
+        return None
+
+    # Parse version (e.g., "git version 2.39.3" or "git version 2.39.3 (Apple Git-145)")
+    # Extract the version number (third word or second word if starts with number)
+    words = version.split()
+    version_str = ""
+    for word in words:
+        if word and word[0].isdigit():
+            version_str = word
+            break
+
+    if not version_str:
+        return None
+
+    try:
+        parts = version_str.split(".")
+        major = int(parts[0]) if len(parts) > 0 else 0
+        minor = int(parts[1]) if len(parts) > 1 else 0
+
+        if major < 2 or (major == 2 and minor < 20):
+            return CheckResult(
+                name="Git Version (Worktrees)",
+                passed=True,  # Still pass, just warn
+                message=f"Git {version_str} works, but 2.20+ recommended for worktrees",
+                severity="info",
+            )
+
+        return CheckResult(
+            name="Git Version (Worktrees)",
+            passed=True,
+            message=f"Git {version_str} fully supports worktrees",
+        )
+    except (ValueError, IndexError):
+        # Can't parse version, skip
+        return None
+
+
+def check_worktree_branch_conflicts(cwd: Path | None = None) -> CheckResult | None:
+    """Check for branches that are checked out in multiple worktrees.
+
+    This is a common source of confusion when switching worktrees.
+    Git prevents checking out a branch that's already checked out elsewhere.
+
+    Args:
+        cwd: Directory to check (defaults to current working directory).
+
+    Returns:
+        CheckResult with branch conflict status, or None if not in a git repo.
+    """
+    if cwd is None:
+        cwd = Path.cwd()
+
+    worktree_data = _parse_worktree_porcelain(cwd)
+    if len(worktree_data) < 2:
+        # Need at least 2 worktrees for conflicts
+        return None
+
+    # Build a map of branch -> worktrees
+    branch_worktrees: dict[str, list[str]] = {}
+    for wt in worktree_data:
+        branch = wt.get("branch")
+        if branch:
+            path = Path(wt.get("path", "")).name
+            if branch not in branch_worktrees:
+                branch_worktrees[branch] = []
+            branch_worktrees[branch].append(path)
+
+    # Find branches checked out in multiple worktrees
+    conflicts = {branch: paths for branch, paths in branch_worktrees.items() if len(paths) > 1}
+
+    if not conflicts:
+        return None  # No conflicts to report
+
+    # Build message
+    conflict_msgs = []
+    for branch, paths in conflicts.items():
+        conflict_msgs.append(f"'{branch}' in: {', '.join(paths)}")
+
+    return CheckResult(
+        name="Branch Conflicts",
+        passed=False,
+        message=f"Branch checked out in multiple worktrees: {'; '.join(conflict_msgs)}",
+        fix_hint="Each branch can only be checked out in one worktree at a time",
+        severity="error",
+    )

scc_cli/doctor/render.py

@@ -0,0 +1,365 @@
+"""Orchestration and rendering functions for the doctor module.
+
+This module contains:
+- run_doctor(): Main orchestrator that runs all health checks
+- build_doctor_json_data(): JSON serialization for CLI output
+- render_doctor_results(): Rich terminal UI rendering
+- render_doctor_compact(): Compact inline status display
+- render_quick_status(): Single-line pass/fail indicator
+- quick_check(): Fast prerequisite validation
+- is_first_run(): First-run detection
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from scc_cli import __version__
+
+from .checks import (
+    check_config_directory,
+    check_docker,
+    check_docker_running,
+    check_docker_sandbox,
+    check_git,
+    check_user_config_valid,
+    check_workspace_path,
+    check_wsl2,
+)
+from .types import DoctorResult
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# JSON Serialization
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def build_doctor_json_data(result: DoctorResult) -> dict[str, Any]:
+    """Build JSON-serializable data from DoctorResult.
+
+    Args:
+        result: The DoctorResult to convert.
+
+    Returns:
+        Dictionary suitable for JSON envelope data field.
+    """
+    checks_data = []
+    for check in result.checks:
+        check_dict: dict[str, Any] = {
+            "name": check.name,
+            "passed": check.passed,
+            "message": check.message,
+            "severity": check.severity,
+        }
+        if check.version:
+            check_dict["version"] = check.version
+        if check.fix_hint:
+            check_dict["fix_hint"] = check.fix_hint
+        if check.fix_url:
+            check_dict["fix_url"] = check.fix_url
+        if check.fix_commands:
+            check_dict["fix_commands"] = check.fix_commands
+        if check.code_frame:
+            check_dict["code_frame"] = check.code_frame
+        checks_data.append(check_dict)
+
+    # Calculate summary stats
+    total = len(result.checks)
+    passed = sum(1 for c in result.checks if c.passed)
+    errors = sum(1 for c in result.checks if not c.passed and c.severity == "error")
+    warnings = sum(1 for c in result.checks if not c.passed and c.severity == "warning")
+
+    return {
+        "checks": checks_data,
+        "summary": {
+            "total": total,
+            "passed": passed,
+            "errors": errors,
+            "warnings": warnings,
+            "all_ok": result.all_ok,
+        },
+    }
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Main Doctor Orchestrator
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def run_doctor(workspace: Path | None = None) -> DoctorResult:
+    """Run all health checks and return comprehensive results.
+
+    Args:
+        workspace: Optional workspace path to check for optimization
+
+    Returns:
+        DoctorResult with all check results
+    """
+    result = DoctorResult()
+
+    # Git check
+    git_check = check_git()
+    result.checks.append(git_check)
+    result.git_ok = git_check.passed
+    result.git_version = git_check.version
+
+    # Docker check
+    docker_check = check_docker()
+    result.checks.append(docker_check)
+    result.docker_ok = docker_check.passed
+    result.docker_version = docker_check.version
+
+    # Docker daemon check (only if Docker is installed)
+    if result.docker_ok:
+        daemon_check = check_docker_running()
+        result.checks.append(daemon_check)
+        if not daemon_check.passed:
+            result.docker_ok = False
+
+    # Docker sandbox check (only if Docker is OK)
+    if result.docker_ok:
+        sandbox_check = check_docker_sandbox()
+        result.checks.append(sandbox_check)
+        result.sandbox_ok = sandbox_check.passed
+    else:
+        result.sandbox_ok = False
+
+    # WSL2 check
+    wsl2_check, is_wsl2 = check_wsl2()
+    result.checks.append(wsl2_check)
+    result.wsl2_detected = is_wsl2
+
+    # Workspace path check (if WSL2 and workspace provided)
+    if workspace:
+        path_check = check_workspace_path(workspace)
+        result.checks.append(path_check)
+        result.windows_path_warning = not path_check.passed and path_check.severity == "warning"
+
+    # Config directory check
+    config_check = check_config_directory()
+    result.checks.append(config_check)
+
+    # Git worktree health checks (may return None if not in a git repo)
+    from .checks import (
+        check_git_version_for_worktrees,
+        check_worktree_branch_conflicts,
+        check_worktree_health,
+    )
+
+    git_version_wt_check = check_git_version_for_worktrees()
+    if git_version_wt_check is not None:
+        result.checks.append(git_version_wt_check)
+
+    worktree_health_check = check_worktree_health()
+    if worktree_health_check is not None:
+        result.checks.append(worktree_health_check)
+
+    branch_conflict_check = check_worktree_branch_conflicts()
+    if branch_conflict_check is not None:
+        result.checks.append(branch_conflict_check)
+
+    # User config JSON validation check
+    user_config_check = check_user_config_valid()
+    result.checks.append(user_config_check)
+
+    return result
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Rich Terminal UI Rendering
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def render_doctor_results(console: Console, result: DoctorResult) -> None:
+    """Render doctor results with beautiful Rich formatting.
+
+    Uses consistent styling with the rest of the CLI:
+    - Cyan for info/brand
+    - Green for success
+    - Yellow for warnings
+    - Red for errors
+    """
+    # Header
+    console.print()
+
+    # Build results table
+    table = Table(
+        box=box.ROUNDED,
+        show_header=True,
+        header_style="bold cyan",
+        border_style="dim",
+        padding=(0, 1),
+    )
+
+    table.add_column("Status", width=8, justify="center")
+    table.add_column("Check", min_width=20)
+    table.add_column("Details", min_width=30)
+
+    for check in result.checks:
+        # Status icon with color
+        if check.passed:
+            status = Text("  ", style="bold green")
+        elif check.severity == "warning":
+            status = Text("  ", style="bold yellow")
+        else:
+            status = Text("  ", style="bold red")
+
+        # Check name
+        name = Text(check.name, style="white")
+
+        # Details with version and message
+        details = Text()
+        if check.version:
+            details.append(f"{check.version}\n", style="cyan")
+        details.append(check.message, style="dim" if check.passed else "white")
+
+        if not check.passed and check.fix_hint:
+            details.append(f"\n{check.fix_hint}", style="yellow")
+
+        table.add_row(status, name, details)
+
+    # Wrap table in panel
+    title_style = "bold green" if result.all_ok else "bold red"
+    version_suffix = f" (scc-cli v{__version__})"
+    title_text = (
+        f"System Health Check{version_suffix}"
+        if result.all_ok
+        else f"System Health Check - Issues Found{version_suffix}"
+    )
+
+    panel = Panel(
+        table,
+        title=f"[{title_style}]{title_text}[/{title_style}]",
+        border_style="green" if result.all_ok else "red",
+        padding=(1, 1),
+    )
+
+    console.print(panel)
+
+    # Display code frames for any checks with syntax errors (beautiful error display)
+    code_frame_checks = [c for c in result.checks if c.code_frame and not c.passed]
+    for check in code_frame_checks:
+        if check.code_frame is not None:  # Type guard for mypy
+            console.print()
+            # Create a panel for the code frame with Rich styling
+            code_panel = Panel(
+                check.code_frame,
+                title=f"[bold red]⚠️  JSON Syntax Error: {check.name}[/bold red]",
+                border_style="red",
+                padding=(1, 2),
+            )
+            console.print(code_panel)
+
+    # Summary line
+    if result.all_ok:
+        console.print()
+        console.print(
+            "  [bold green]All prerequisites met![/bold green] [dim]Ready to run Claude Code.[/dim]"
+        )
+    else:
+        console.print()
+        summary_parts = []
+        if result.error_count > 0:
+            summary_parts.append(f"[bold red]{result.error_count} error(s)[/bold red]")
+        if result.warning_count > 0:
+            summary_parts.append(f"[bold yellow]{result.warning_count} warning(s)[/bold yellow]")
+
+        console.print(f"  Found {' and '.join(summary_parts)}. ", end="")
+        console.print("[dim]Fix the issues above to continue.[/dim]")
+
+        # Next Steps section with fix_commands
+        checks_with_commands = [c for c in result.checks if not c.passed and c.fix_commands]
+        if checks_with_commands:
+            console.print()
+            console.print("  [bold cyan]Next Steps[/bold cyan]")
+            console.print("  [dim]────────────────────────────────────────────────────[/dim]")
+            console.print()
+
+            for check in checks_with_commands:
+                console.print(f"  [bold white]{check.name}:[/bold white]")
+                if check.fix_hint:
+                    console.print(f"    [dim]{check.fix_hint}[/dim]")
+                if check.fix_commands:
+                    for i, cmd in enumerate(check.fix_commands, 1):
+                        console.print(f"    [cyan]{i}.[/cyan] [white]{cmd}[/white]")
+                console.print()
+
+    console.print()
+
+
+def render_doctor_compact(console: Console, result: DoctorResult) -> None:
+    """Render compact doctor results for inline display.
+
+    Used during startup to show quick status.
+    """
+    checks = []
+
+    # Git
+    if result.git_ok:
+        checks.append("[green]Git[/green]")
+    else:
+        checks.append("[red]Git[/red]")
+
+    # Docker
+    if result.docker_ok:
+        checks.append("[green]Docker[/green]")
+    else:
+        checks.append("[red]Docker[/red]")
+
+    # Sandbox
+    if result.sandbox_ok:
+        checks.append("[green]Sandbox[/green]")
+    else:
+        checks.append("[red]Sandbox[/red]")
+
+    console.print(f"  [dim]Prerequisites:[/dim] {' | '.join(checks)}")
+
+
+def render_quick_status(console: Console, result: DoctorResult) -> None:
+    """Render a single-line status for quick checks.
+
+    Returns immediately with pass/fail indicator.
+    """
+    if result.all_ok:
+        console.print("[green]  All systems operational[/green]")
+    else:
+        failed = [c.name for c in result.checks if not c.passed and c.severity == "error"]
+        console.print(f"[red]  Issues detected:[/red] {', '.join(failed)}")
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Quick Check Utilities
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def quick_check() -> bool:
+    """Perform a quick prerequisite check.
+
+    Returns True if all critical prerequisites are met.
+    Used for fast startup validation.
+    """
+    result = run_doctor()
+    return result.all_ok
+
+
+def is_first_run() -> bool:
+    """Check if this is the first run of scc.
+
+    Returns True if config directory doesn't exist or is empty.
+    """
+    from scc_cli import config
+
+    config_dir = config.CONFIG_DIR
+
+    if not config_dir.exists():
+        return True
+
+    # Check if config file exists
+    config_file = config.CONFIG_FILE
+    return not config_file.exists()

scc_cli/doctor/types.py

@@ -0,0 +1,66 @@
+"""Define data types for the doctor health check module.
+
+Provide dataclasses for representing check results, validation results,
+and overall doctor diagnostic results.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class CheckResult:
+    """Result of a single health check."""
+
+    name: str
+    passed: bool
+    message: str
+    version: str | None = None
+    fix_hint: str | None = None
+    fix_url: str | None = None
+    severity: str = "error"  # "error", "warning", "info"
+    code_frame: str | None = None  # Optional code frame for syntax errors
+    fix_commands: list[str] | None = None  # Copy-pasteable fix commands
+
+
+@dataclass
+class JsonValidationResult:
+    """Result of JSON file validation with error details."""
+
+    valid: bool
+    error_message: str | None = None
+    line: int | None = None
+    column: int | None = None
+    file_path: Path | None = None
+    code_frame: str | None = None
+
+
+@dataclass
+class DoctorResult:
+    """Complete health check results."""
+
+    git_ok: bool = False
+    git_version: str | None = None
+    docker_ok: bool = False
+    docker_version: str | None = None
+    sandbox_ok: bool = False
+    wsl2_detected: bool = False
+    windows_path_warning: bool = False
+    checks: list[CheckResult] = field(default_factory=list)
+
+    @property
+    def all_ok(self) -> bool:
+        """Check if all critical prerequisites pass."""
+        return self.git_ok and self.docker_ok and self.sandbox_ok
+
+    @property
+    def error_count(self) -> int:
+        """Return the count of failed critical checks."""
+        return sum(1 for c in self.checks if not c.passed and c.severity == "error")
+
+    @property
+    def warning_count(self) -> int:
+        """Return the count of warnings."""
+        return sum(1 for c in self.checks if not c.passed and c.severity == "warning")