aisc-cli 0.1.0__py3-none-any.whl

aisc/application/doctor.py

@@ -0,0 +1,821 @@
+"""Doctor checks — host-only diagnosis.
+
+Each check is a simple callable that returns a ``CheckResult``.
+Checks are ordered and the report determines the final exit code.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+from pathlib import Path
+from typing import Callable, List, Optional
+
+from aisc.domain.models import CheckResult, CheckStatus, DoctorReport
+from aisc.adapters.system import ProcessRunner, RealProcessRunner
+
+
+# ---------------------------------------------------------------------------
+# Timeout constants (seconds)
+# ---------------------------------------------------------------------------
+
+DOCKER_TIMEOUT = 8.0
+GIT_TIMEOUT = 5.0
+COMPOSE_TIMEOUT = 5.0
+
+
+# ---------------------------------------------------------------------------
+# Check implementations
+# ---------------------------------------------------------------------------
+
+def _check_docker_cli(
+    docker_path: str,
+    runner: ProcessRunner,
+) -> CheckResult:
+    """Check 1: Docker CLI discovery / version."""
+    result = runner.run([docker_path, "--version"], timeout=DOCKER_TIMEOUT)
+    if result.command_not_found:
+        return CheckResult(
+            name="docker-cli",
+            status=CheckStatus.FAIL,
+            message="Docker CLI not found",
+            detail="docker command not available on PATH",
+            hint="Install Docker: https://docs.docker.com/get-docker/",
+        )
+    if result.timed_out:
+        return CheckResult(
+            name="docker-cli",
+            status=CheckStatus.FAIL,
+            message="Docker CLI timed out",
+            detail="docker --version did not respond",
+        )
+    if result.exit_code != 0:
+        return CheckResult(
+            name="docker-cli",
+            status=CheckStatus.FAIL,
+            message="Docker CLI returned an error",
+            detail=result.stderr.strip() or result.stdout.strip(),
+        )
+    version_line = (
+        result.stdout.strip().splitlines()[0]
+        if result.stdout.strip()
+        else "(unknown)"
+    )
+    return CheckResult(
+        name="docker-cli",
+        status=CheckStatus.PASS,
+        message=version_line,
+    )
+
+
+def _check_docker_daemon(
+    docker_path: str,
+    runner: ProcessRunner,
+    docker_cli_available: bool,
+) -> CheckResult:
+    """Check 2: Docker daemon (``docker info``)."""
+    if not docker_cli_available:
+        return CheckResult(
+            name="docker-daemon",
+            status=CheckStatus.SKIP,
+            message="Docker CLI not available",
+        )
+    result = runner.run([docker_path, "info"], timeout=DOCKER_TIMEOUT)
+    if result.timed_out:
+        return CheckResult(
+            name="docker-daemon",
+            status=CheckStatus.FAIL,
+            message="Docker daemon check timed out",
+            hint="Ensure the Docker daemon is running",
+        )
+    if result.exit_code != 0:
+        return CheckResult(
+            name="docker-daemon",
+            status=CheckStatus.FAIL,
+            message="Docker daemon not running or unreachable",
+            detail=result.stderr.strip() or result.stdout.strip(),
+            hint="Ensure the Docker daemon is running",
+        )
+    return CheckResult(
+        name="docker-daemon",
+        status=CheckStatus.PASS,
+        message="Docker daemon is running",
+    )
+
+
+def _check_docker_permission(
+    docker_path: str,
+    runner: ProcessRunner,
+    docker_cli_available: bool,
+    docker_daemon_failed: bool,
+) -> CheckResult:
+    """Check 3: Docker permission (``docker ps``)."""
+    if not docker_cli_available:
+        return CheckResult(
+            name="docker-permission",
+            status=CheckStatus.SKIP,
+            message="Docker CLI not available",
+        )
+    if docker_daemon_failed:
+        return CheckResult(
+            name="docker-permission",
+            status=CheckStatus.SKIP,
+            message="Docker daemon not available",
+        )
+    result = runner.run([docker_path, "ps"], timeout=DOCKER_TIMEOUT)
+    if result.timed_out:
+        return CheckResult(
+            name="docker-permission",
+            status=CheckStatus.FAIL,
+            message="Docker permission check timed out",
+        )
+    if result.exit_code != 0:
+        return CheckResult(
+            name="docker-permission",
+            status=CheckStatus.FAIL,
+            message="Permission denied — cannot access Docker daemon",
+            detail=result.stderr.strip() or result.stdout.strip(),
+            hint="Ensure your user has access to Docker (e.g. docker group membership)",
+        )
+    return CheckResult(
+        name="docker-permission",
+        status=CheckStatus.PASS,
+        message="Docker permission OK",
+    )
+
+
+def _check_docker_buildx(
+    docker_path: str,
+    runner: ProcessRunner,
+    docker_cli_available: bool,
+    docker_daemon_failed: bool,
+) -> CheckResult:
+    """Check 4: Docker Buildx (``docker buildx version``)."""
+    if not docker_cli_available:
+        return CheckResult(
+            name="docker-buildx",
+            status=CheckStatus.SKIP,
+            message="Docker CLI not available",
+        )
+    if docker_daemon_failed:
+        return CheckResult(
+            name="docker-buildx",
+            status=CheckStatus.SKIP,
+            message="Docker daemon not available",
+        )
+    result = runner.run([docker_path, "buildx", "version"], timeout=DOCKER_TIMEOUT)
+    if result.timed_out:
+        return CheckResult(
+            name="docker-buildx",
+            status=CheckStatus.WARN,
+            message="Docker Buildx check timed out",
+        )
+    if result.exit_code != 0:
+        return CheckResult(
+            name="docker-buildx",
+            status=CheckStatus.WARN,
+            message="Docker Buildx not available",
+            detail=result.stderr.strip() or result.stdout.strip(),
+            hint="Install buildx: https://docs.docker.com/buildx/",
+        )
+    version_line = (
+        result.stdout.strip().splitlines()[0]
+        if result.stdout.strip()
+        else "(unknown)"
+    )
+    return CheckResult(
+        name="docker-buildx",
+        status=CheckStatus.PASS,
+        message=version_line,
+    )
+
+
+def _check_tun_device() -> CheckResult:
+    """Check 5: Linux ``/dev/net/tun`` (character device)."""
+    if sys.platform != "linux":
+        return CheckResult(
+            name="tun-device",
+            status=CheckStatus.SKIP,
+            message="Not Linux — /dev/net/tun check skipped",
+        )
+    tun = Path("/dev/net/tun")
+    try:
+        st = tun.stat()
+        if stat.S_ISCHR(st.st_mode):
+            return CheckResult(
+                name="tun-device",
+                status=CheckStatus.PASS,
+                message="/dev/net/tun exists and is a character device",
+            )
+        return CheckResult(
+            name="tun-device",
+            status=CheckStatus.WARN,
+            message="/dev/net/tun exists but is not a character device",
+        )
+    except FileNotFoundError:
+        return CheckResult(
+            name="tun-device",
+            status=CheckStatus.WARN,
+            message="/dev/net/tun not found",
+            detail="TUN device required for transparent proxy mode",
+        )
+    except OSError:
+        return CheckResult(
+            name="tun-device",
+            status=CheckStatus.WARN,
+            message="/dev/net/tun inaccessible",
+        )
+
+
+def _check_aisc_root(
+    root: Optional[Path],
+    root_error: Optional[str] = None,
+) -> CheckResult:
+    """Check 6: AISC root / bundle discovery.
+
+    *root_error* is the original error message when an explicit or env
+    source was invalid.  Passed through verbatim.
+    """
+    if root_error is not None:
+        return CheckResult(
+            name="aisc-root",
+            status=CheckStatus.FAIL,
+            message=root_error,
+        )
+    if root is not None:
+        return CheckResult(
+            name="aisc-root",
+            status=CheckStatus.PASS,
+            message=f"Found at {root}",
+        )
+    return CheckResult(
+        name="aisc-root",
+        status=CheckStatus.WARN,
+        message="AISC root not found (no repo in parent directories)",
+        detail="Some checks require a repo root to read VERSION / container files",
+    )
+
+
+def _check_bundle_store(root: Optional[Path]) -> CheckResult:
+    """Check 6b: the fetched-bundle store (pip installs' build resources).
+
+    PASS when the ACTIVE root is a repo/frozen bundle (the store is
+    irrelevant); PASS when it resolves from ``bundles/<ver>/``; WARN when a
+    store exists but nothing is compatible; WARN on pip forms with no store
+    at all (build needs ``aisc bundle fetch``)."""
+    import sys as _sys
+
+    from aisc import __version__
+
+    pip_form = (
+        not getattr(_sys, "frozen", False)
+        and __file__ is not None
+        and "site-packages" in str(Path(__file__).resolve())
+    )
+    try:
+        from aisc.application.data_root import shared_root
+
+        dr = shared_root()
+    except Exception:
+        dr = None
+    if dr is not None:
+        from aisc.application.resources import find_data_root_bundles
+
+        candidates, skipped = find_data_root_bundles(dr)
+        if candidates:
+            return CheckResult(
+                name="aisc-bundle",
+                status=CheckStatus.PASS,
+                message=f"bundle store: {candidates[0]}",
+            )
+        if skipped:
+            return CheckResult(
+                name="aisc-bundle",
+                status=CheckStatus.WARN,
+                message="bundle store present but no compatible bundle",
+                detail="; ".join(skipped[:3]),
+            )
+    if root is not None:
+        return CheckResult(
+            name="aisc-bundle",
+            status=CheckStatus.PASS,
+            message=f"root resolves without the bundle store ({root})",
+        )
+    if pip_form:
+        return CheckResult(
+            name="aisc-bundle",
+            status=CheckStatus.WARN,
+            message="pip install without build resources",
+            detail="run `aisc bundle fetch` to download this version's bundle "
+                   "(build/docker-rebuild need it)",
+        )
+    return CheckResult(
+        name="aisc-bundle",
+        status=CheckStatus.WARN,
+        message="no bundle store and no repo root",
+    )
+
+
+def _check_channel_confusion() -> CheckResult:
+    """Check 6c: multiple `aisc` hits on PATH -> WARN with the list.
+
+    Only lists paths + file info by default — running every hit's
+    `--version` is `--verbose` territory (never execute unknown binaries
+    unprompted)."""
+    import shutil as _shutil
+
+    hits: list = []
+    for d in os.environ.get("PATH", "").split(os.pathsep):
+        if not d:
+            continue
+        for cand in (Path(d) / "aisc", Path(d) / "aisc.exe"):
+            try:
+                if cand.is_file() and cand.stat().st_size > 0:
+                    hits.append(str(cand))
+            except OSError:
+                continue
+    if len(hits) > 1:
+        return CheckResult(
+            name="channel-confusion",
+            status=CheckStatus.WARN,
+            message=f"{len(hits)} aisc executables on PATH",
+            detail="; ".join(hits[:4]) + (" …" if len(hits) > 4 else ""),
+        )
+    if len(hits) == 1:
+        return CheckResult(name="channel-confusion", status=CheckStatus.PASS,
+                           message=hits[0])
+    return CheckResult(name="channel-confusion", status=CheckStatus.WARN,
+                       message="no aisc executable found on PATH")
+
+
+def _check_platform_support() -> CheckResult:
+    """Check 6d: py3-none-any wheel installs anywhere; payloads are
+    linux-amd64. Unsupported combos get a WARN (no install-time hook
+    exists for pure wheels — guide 3.5.5)."""
+    import platform as _platform
+
+    combo = f"{_platform.system().lower()}-{_platform.machine().lower()}"
+    supported = {"windows-amd64", "linux-x86_64", "darwin-arm64"}
+    if combo in supported:
+        return CheckResult(name="platform-support", status=CheckStatus.PASS,
+                           message=combo)
+    return CheckResult(
+        name="platform-support",
+        status=CheckStatus.WARN,
+        message=f"unsupported combination {combo}",
+        detail="official artifacts are windows-x86_64 / linux-x86_64 / "
+               "macos-arm64; builds may be extremely slow or unstable here",
+    )
+
+
+def _check_root_files(root: Optional[Path]) -> List[CheckResult]:
+    """Check 7: Verify key root files exist."""
+    if root is None:
+        return [
+            CheckResult(
+                name="aisc-root-files",
+                status=CheckStatus.SKIP,
+                message="No AISC root found — file checks skipped",
+            )
+        ]
+
+    required = {
+        # A2 dual-shape: repo checkouts carry it at src/aisc/VERSION.
+        "VERSION": ("VERSION", "src/aisc/VERSION"),
+        "container/Dockerfile": ("container/Dockerfile",),
+        "config/versions.env": ("config/versions.env",),
+    }
+    results: List[CheckResult] = []
+    for label, rels in required.items():
+        p = next((root / rel for rel in rels if (root / rel).is_file()), None)
+        if p is not None:
+            results.append(
+                CheckResult(
+                    name=f"root-file:{label}",
+                    status=CheckStatus.PASS,
+                    message=f"{rels[0]} exists",
+                )
+            )
+        else:
+            results.append(
+                CheckResult(
+                    name=f"root-file:{label}",
+                    status=CheckStatus.FAIL,
+                    message=f"{rels[0]} not found",
+                )
+            )
+    return results
+
+
+def _check_git(
+    git_path: str,
+    runner: ProcessRunner,
+) -> CheckResult:
+    """Check 8: Git discovery / version."""
+    result = runner.run([git_path, "--version"], timeout=GIT_TIMEOUT)
+    if result.command_not_found or result.exit_code != 0:
+        return CheckResult(
+            name="git",
+            status=CheckStatus.WARN,
+            message="Git not available",
+        )
+    version_line = (
+        result.stdout.strip().splitlines()[0]
+        if result.stdout.strip()
+        else "(unknown)"
+    )
+    return CheckResult(
+        name="git",
+        status=CheckStatus.PASS,
+        message=version_line,
+    )
+
+
+def _check_docker_compose(
+    docker_path: Optional[str],
+    runner: ProcessRunner,
+    docker_cli_available: bool,
+) -> CheckResult:
+    """Check 9: Docker Compose (``docker compose version``)."""
+    if not docker_cli_available or docker_path is None:
+        return CheckResult(
+            name="docker-compose",
+            status=CheckStatus.SKIP,
+            message="Docker CLI not available",
+        )
+    result = runner.run(
+        [docker_path, "compose", "version"], timeout=COMPOSE_TIMEOUT,
+    )
+    if result.command_not_found:
+        return CheckResult(
+            name="docker-compose",
+            status=CheckStatus.WARN,
+            message="Docker Compose subcommand not available",
+            detail="docker command exists but 'compose' subcommand not found",
+            hint="Ensure Docker Compose plugin is installed: https://docs.docker.com/compose/install/",
+        )
+    if result.timed_out:
+        return CheckResult(
+            name="docker-compose",
+            status=CheckStatus.WARN,
+            message="Docker Compose check timed out",
+        )
+    if result.exit_code != 0:
+        detail = result.stderr.strip() or result.stdout.strip()
+        lowered = detail.lower()
+        if "unknown command" in lowered or "not a docker command" in lowered:
+            return CheckResult(
+                name="docker-compose",
+                status=CheckStatus.WARN,
+                message="Docker Compose subcommand not available",
+                detail=detail,
+                hint="Install the Docker Compose plugin: https://docs.docker.com/compose/install/",
+            )
+        return CheckResult(
+            name="docker-compose",
+            status=CheckStatus.WARN,
+            message="Docker Compose returned an error",
+            detail=detail,
+            hint="Run 'docker compose version' manually and check the Docker Compose plugin installation.",
+        )
+    version_line = (
+        result.stdout.strip().splitlines()[0]
+        if result.stdout.strip()
+        else "(unknown)"
+    )
+    return CheckResult(
+        name="docker-compose",
+        status=CheckStatus.PASS,
+        message=version_line,
+    )
+
+
+def _check_wsl_memory(
+    home: Optional[Path] = None,
+    total_ram_gb: Optional[Callable[[], Optional[float]]] = None,
+    platform: Optional[str] = None,
+) -> CheckResult:
+    """O6 (opt-batch, D-11): WSL2 memory guidance on low-RAM Windows hosts.
+
+    Docker Desktop's WSL2 backend defaults to ~50%/8GB of host RAM (whichever
+    is less) for the utility VM — on an 8GB machine the VM, Vmmem, and the
+    host then fight for memory and the container side (cc-switch daemon OOM,
+    see O5) suffers first. When the host has ≤8GB and `%USERPROFILE%\\.wslconfig`
+    does not cap `memory` under [wsl2], surface a WARN with the recommended
+    snippet. Advisory ONLY — never edits system config. Non-Windows hosts SKIP.
+    """
+    if (platform or sys.platform) != "win32":
+        return CheckResult(name="wsl-memory", status=CheckStatus.SKIP,
+                           message="Windows-only check")
+
+    home = home or Path.home()
+    cfg = home / ".wslconfig"
+
+    def _default_total_ram_gb() -> Optional[float]:
+        import ctypes
+
+        class MEMORYSTATUSEX(ctypes.Structure):
+            _fields_ = [
+                ("dwLength", ctypes.c_ulong),
+                ("dwMemoryLoad", ctypes.c_ulong),
+                ("ullTotalPhys", ctypes.c_ulonglong),
+                ("ullAvailPhys", ctypes.c_ulonglong),
+                ("ullTotalPageFile", ctypes.c_ulonglong),
+                ("ullAvailPageFile", ctypes.c_ulonglong),
+                ("ullTotalVirtual", ctypes.c_ulonglong),
+                ("ullAvailVirtual", ctypes.c_ulonglong),
+                ("ullAvailExtendedVirtual", ctypes.c_ulonglong),
+            ]
+
+        stat = MEMORYSTATUSEX()
+        stat.dwLength = ctypes.sizeof(MEMORYSTATUSEX)
+        if not ctypes.windll.kernel32.GlobalMemoryStatusEx(ctypes.byref(stat)):
+            return None
+        return stat.ullTotalPhys / (1024 ** 3)
+
+    ram = (total_ram_gb or _default_total_ram_gb)()
+    if ram is None:
+        return CheckResult(name="wsl-memory", status=CheckStatus.SKIP,
+                           message="Could not read physical memory")
+
+    capped = False
+    try:
+        if cfg.is_file():
+            in_wsl2 = False
+            for line in cfg.read_text(encoding="utf-8", errors="replace").splitlines():
+                stripped = line.strip()
+                if stripped.startswith("["):
+                    in_wsl2 = stripped.lower() == "[wsl2]"
+                elif in_wsl2 and stripped.lower().startswith("memory"):
+                    capped = True  # any memory= cap counts, value not judged
+                    break
+    except OSError:
+        pass
+
+    if capped or ram > 8.5:
+        return CheckResult(
+            name="wsl-memory",
+            status=CheckStatus.PASS,
+            message=(
+                f"物理内存 {ram:.0f}GB"
+                + ("，.wslconfig 已设 memory 上限" if capped else "，无需 WSL 内存上限")
+            ),
+        )
+    return CheckResult(
+        name="wsl-memory",
+        status=CheckStatus.WARN,
+        message=(
+            f"物理内存 {ram:.0f}GB 且 .wslconfig 未限制 WSL2 内存——"
+            "Docker 的 WSL2 虚拟机默认可占约 50% 内存，低配机上易与宿主争抢"
+            "（容器侧 cc-switch daemon 可能被 OOM）"
+        ),
+        hint=(
+            "建议在 %USERPROFILE%\\.wslconfig 添加：\n"
+            "[wsl2]\n"
+            f"memory={'4GB' if ram <= 4.5 else '5GB'}\n"
+            "保存后运行 `wsl --shutdown` 生效（仅建议，AISC 不会自动修改）"
+        ),
+    )
+
+
+def _check_root_writable(root: Optional[Path]) -> CheckResult:
+    """Check 10: Project root directory writability (read-only diagnostic)."""
+    if root is None:
+        return CheckResult(
+            name="root-writable",
+            status=CheckStatus.SKIP,
+            message="No AISC root found — writability check skipped",
+        )
+    try:
+        if not root.exists():
+            return CheckResult(
+                name="root-writable",
+                status=CheckStatus.WARN,
+                message=f"Root directory does not exist: {root}",
+                hint="Verify the project root path is correct",
+            )
+        if not root.is_dir():
+            return CheckResult(
+                name="root-writable",
+                status=CheckStatus.WARN,
+                message=f"Root path is not a directory: {root}",
+                hint="The project root must be a directory",
+            )
+        if os.access(str(root), os.W_OK):
+            return CheckResult(
+                name="root-writable",
+                status=CheckStatus.PASS,
+                message=f"Root directory is writable: {root}",
+            )
+        else:
+            return CheckResult(
+                name="root-writable",
+                status=CheckStatus.WARN,
+                message=f"Root directory may not be writable: {root}",
+                detail="Permission pre-check only — not a write guarantee",
+                hint="Check directory permissions (e.g. ls -ld on the directory)",
+            )
+    except OSError as exc:
+        return CheckResult(
+            name="root-writable",
+            status=CheckStatus.WARN,
+            message=f"Cannot check root writability: {root}",
+            detail=str(exc),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Exit code priority logic
+# ---------------------------------------------------------------------------
+
+EXIT_OK = 0
+EXIT_GENERAL = 1
+EXIT_USAGE = 2
+EXIT_DOCKER_UNAVAILABLE = 3
+EXIT_PERMISSION_DENIED = 9
+
+ERR_GENERAL = "AISC_ERR_GENERAL"
+ERR_DOCKER_UNAVAILABLE = "AISC_ERR_DOCKER_UNAVAILABLE"
+ERR_PERMISSION_DENIED = "AISC_ERR_PERMISSION_DENIED"
+
+
+def _compute_exit_code(checks: List[CheckResult]) -> tuple:
+    """Compute final exit code and error details from a completed check list."""
+    docker_cli_fail = any(
+        c.name == "docker-cli" and c.status == CheckStatus.FAIL for c in checks
+    )
+    docker_daemon_fail = any(
+        c.name == "docker-daemon" and c.status == CheckStatus.FAIL for c in checks
+    )
+    docker_permission_fail = any(
+        c.name == "docker-permission" and c.status == CheckStatus.FAIL for c in checks
+    )
+    explicit_root_invalid = any(
+        c.name == "aisc-root" and c.status == CheckStatus.FAIL for c in checks
+    )
+    any_other_fail = any(
+        c.status == CheckStatus.FAIL
+        and c.name
+        not in ("docker-cli", "docker-daemon", "docker-permission", "aisc-root")
+        for c in checks
+    )
+
+    if docker_cli_fail or docker_daemon_fail:
+        return EXIT_DOCKER_UNAVAILABLE, ERR_DOCKER_UNAVAILABLE, "Docker is not available"
+
+    if docker_permission_fail:
+        return EXIT_PERMISSION_DENIED, ERR_PERMISSION_DENIED, "Docker permission denied"
+
+    if explicit_root_invalid or any_other_fail:
+        return EXIT_GENERAL, ERR_GENERAL, "One or more checks failed"
+
+    return EXIT_OK, None, None
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+CheckFunc = Callable[[], CheckResult]
+CheckListFunc = Callable[[], List[CheckResult]]
+
+
+def run_doctor(
+    runner: Optional[ProcessRunner] = None,
+    root: Optional[Path] = None,
+    root_error: Optional[str] = None,
+    which: Optional[Callable[[str], Optional[str]]] = None,
+) -> DoctorReport:
+    """Run all host doctor checks and return a ``DoctorReport``.
+
+    Parameters
+    ----------
+    runner:
+        Process runner.  Defaults to ``RealProcessRunner``.
+    root:
+        Pre-located AISC root (may be ``None``).
+    root_error:
+        Original error message when an explicit or env root source was
+        invalid.  Passed through verbatim to the aisc-root check.
+    which:
+        Command-discovery callable.  Defaults to ``shutil.which``.
+        When ``which('docker')`` returns ``None``, docker-cli is **FAIL**
+        (exit 3 / AISC_ERR_DOCKER_UNAVAILABLE) and subsequent docker
+        sub-command checks are SKIP with zero subprocess calls.
+    """
+    import shutil as _shutil
+
+    r = runner or RealProcessRunner()
+    w: Callable[[str], Optional[str]] = which if which is not None else _shutil.which
+
+    docker_raw = w("docker")  # may be None when not on PATH / injected None-return
+    git_raw = w("git")
+
+    checks: List[CheckResult] = []
+
+    # 1. docker-cli
+    #    which('docker') is None  → FAIL (Docker CLI not found, exit 3)
+    #    which('docker') returns a path → run --version check
+    if docker_raw is None:
+        docker_cli = CheckResult(
+            name="docker-cli",
+            status=CheckStatus.FAIL,
+            message="Docker CLI not found",
+            detail="docker command not available on PATH",
+            hint="Install Docker: https://docs.docker.com/get-docker/",
+        )
+        docker_cli_available = False
+        docker_path = None
+    else:
+        docker_path = docker_raw
+        docker_cli = _check_docker_cli(docker_path, r)
+        docker_cli_available = docker_cli.status != CheckStatus.FAIL
+    checks.append(docker_cli)
+
+    # 2. docker-daemon  (SKIP when CLI unavailable — no subprocess call)
+    if docker_path and docker_cli_available:
+        docker_daemon = _check_docker_daemon(docker_path, r, docker_cli_available)
+    else:
+        docker_daemon = CheckResult(
+            name="docker-daemon",
+            status=CheckStatus.SKIP,
+            message="Docker CLI not available",
+        )
+    checks.append(docker_daemon)
+    docker_daemon_failed = docker_daemon.status == CheckStatus.FAIL
+
+    # 3. docker-permission  (SKIP when CLI/daemon unavailable)
+    if docker_path and docker_cli_available:
+        docker_perm = _check_docker_permission(
+            docker_path, r, docker_cli_available, docker_daemon_failed
+        )
+    else:
+        docker_perm = CheckResult(
+            name="docker-permission",
+            status=CheckStatus.SKIP,
+            message="Docker CLI not available",
+        )
+    checks.append(docker_perm)
+
+    # 4. buildx  (SKIP when CLI/daemon unavailable)
+    if docker_path and docker_cli_available:
+        buildx = _check_docker_buildx(
+            docker_path, r, docker_cli_available, docker_daemon_failed
+        )
+    else:
+        buildx = CheckResult(
+            name="docker-buildx",
+            status=CheckStatus.SKIP,
+            message="Docker CLI not available",
+        )
+    checks.append(buildx)
+
+    # 5. TUN
+    checks.append(_check_tun_device())
+
+    # 6. aisc root — pass through root_error verbatim
+    checks.append(_check_aisc_root(root, root_error=root_error))
+
+    # 6b. aisc-bundle store (0.1.0 A3, guide 3.3.4): append-only check —
+    # the pip install form has no repo, so the aisc-root WARN above is
+    # misleading there. This check names the fetch path explicitly.
+    checks.append(_check_bundle_store(root))
+
+    # 6c. A8 (guide 3.5.5): channel + platform-support — multi-channel
+    # installs are the #1 "upgraded but still old version" confusion.
+    checks.append(_check_channel_confusion())
+    checks.append(_check_platform_support())
+
+    # 7. root files
+    checks.extend(_check_root_files(root))
+
+    # 8. git  (WARN when missing, not SKIP)
+    if git_raw:
+        checks.append(_check_git(git_raw, r))
+    else:
+        checks.append(
+            CheckResult(
+                name="git",
+                status=CheckStatus.WARN,
+                message="Git not available",
+            )
+        )
+
+    # 9. docker-compose
+    checks.append(_check_docker_compose(docker_path, r, docker_cli_available))
+
+    # 10. root writability
+    checks.append(_check_root_writable(root))
+
+    # 11. WSL2 memory guidance (O6: WARN-only advisory, never a gate)
+    checks.append(_check_wsl_memory())
+
+    exit_code, error_code, error_message = _compute_exit_code(checks)
+
+    return DoctorReport(
+        checks=checks,
+        exit_code=exit_code,
+        error_code=error_code,
+        error_message=error_message,
+    )