fadenstack 0.4.2__py3-none-any.whl

faden_cli/core/detect.py

@@ -0,0 +1,580 @@
+"""System detection — OS, Docker, GPU, ports, disk, RAM.
+
+Every detection function returns a typed result dataclass so callers
+can render them however suits (Rich table, Textual widget, JSON, etc.).
+All detection is synchronous and subprocess-based — no Docker SDK
+dependency, just ``docker`` and ``nvidia-smi`` / ``rocm-smi`` on PATH.
+"""
+
+from __future__ import annotations
+
+import platform
+import re
+import shutil
+import socket
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import psutil
+
+# ── Result types ──────────────────────────────────────────────────
+
+
+@dataclass
+class OSInfo:
+    """Operating system details."""
+
+    system: str  # "Linux", "Windows", "Darwin"
+    release: str
+    version: str
+    machine: str  # "x86_64", "aarch64"
+
+    @property
+    def display(self) -> str:
+        """Human-friendly OS string."""
+        return f"{self.system} {self.release} ({self.machine})"
+
+
+@dataclass
+class DockerInfo:
+    """Docker Engine + Compose availability."""
+
+    installed: bool = False
+    version: str = ""
+    compose_installed: bool = False
+    compose_version: str = ""
+    daemon_running: bool = False
+    error: str = ""
+
+    @property
+    def ok(self) -> bool:
+        """Docker, Compose v2, and daemon are all available."""
+        return self.installed and self.compose_installed and self.daemon_running
+
+    @property
+    def daemon_hint(self) -> str:
+        """Cross-platform hint for starting the Docker daemon."""
+        system = platform.system()
+        if system in ("Darwin", "Windows"):
+            # Docker Desktop or its open-source alternative, Rancher
+            # Desktop.  The CLI automatically falls back to the Rancher
+            # Desktop endpoint when the active one is not reachable.
+            if self.error and "dockerDesktop" in self.error:
+                return (
+                    "Start Docker Desktop, or start Rancher Desktop "
+                    "(with Docker support enabled)."
+                )
+            return "Start Docker Desktop (or Rancher Desktop)."
+        return "Start the Docker daemon: sudo systemctl start docker"
+
+    @property
+    def install_hint(self) -> str:
+        """Platform-specific install URL for Docker."""
+        system = platform.system()
+        if system == "Windows":
+            return (
+                "https://docs.docker.com/desktop/setup/install/windows-install/ "
+                "or https://docs.rancherdesktop.io/"
+            )
+        if system == "Darwin":
+            return "https://docs.docker.com/desktop/setup/install/mac-install/"
+        return "https://docs.docker.com/engine/install/"
+
+
+@dataclass
+class GpuDevice:
+    """Single GPU device."""
+
+    index: int
+    name: str
+    vram_mb: int
+    driver_version: str
+    cuda_version: str = ""
+
+
+@dataclass
+class GpuInfo:
+    """GPU detection result."""
+
+    vendor: str = "none"  # "nvidia", "amd", "none"
+    devices: list[GpuDevice] = field(default_factory=list)
+    driver_version: str = ""
+    cuda_version: str = ""
+    rocm_version: str = ""
+    error: str = ""
+
+    @property
+    def has_gpu(self) -> bool:
+        """At least one GPU detected."""
+        return len(self.devices) > 0
+
+    @property
+    def total_vram_mb(self) -> int:
+        """Sum of VRAM across all devices."""
+        return sum(d.vram_mb for d in self.devices)
+
+    @property
+    def display(self) -> str:
+        """Short human-friendly GPU summary."""
+        if not self.has_gpu:
+            return "None detected"
+        count = len(self.devices)
+        name = self.devices[0].name
+        vram = self.total_vram_mb
+        suffix = f" × {count}" if count > 1 else ""
+        return f"{name}{suffix} · {vram} MB VRAM"
+
+
+@dataclass
+class DiskInfo:
+    """Disk space for a given path."""
+
+    path: str
+    total_gb: float
+    free_gb: float
+    used_pct: float
+
+
+@dataclass
+class RamInfo:
+    """System memory."""
+
+    total_gb: float
+    available_gb: float
+    used_pct: float
+
+
+@dataclass
+class PortCheck:
+    """Result of checking whether a port is in use."""
+
+    port: int
+    label: str
+    in_use: bool
+    #: Held by one of Fadenstack's own containers: not a conflict.
+    ours: bool = False
+
+
+@dataclass
+class ToolCheck:
+    """Result of checking whether a CLI tool is on PATH."""
+
+    name: str
+    found: bool
+    version: str = ""
+    path: str = ""
+    install_hint: str = ""
+
+
+# ── Install hints for common tools ────────────────────────────────
+
+TOOL_INSTALL_HINTS: dict[str, str] = {
+    "docker": "https://docs.docker.com/engine/install/",
+    "git": "https://git-scm.com/downloads",
+    "uv": "pip install uv",
+    "node": "https://nodejs.org/en/download",
+    "npm": "https://nodejs.org/en/download",
+    "poetry": "pip install poetry",
+}
+
+
+@dataclass
+class SystemReport:
+    """Aggregated detection results."""
+
+    os: OSInfo
+    docker: DockerInfo
+    gpu: GpuInfo
+    ram: RamInfo
+    disk: DiskInfo
+    ports: list[PortCheck] = field(default_factory=list)
+    tools: list[ToolCheck] = field(default_factory=list)
+
+    @property
+    def all_clear(self) -> bool:
+        """No blocking issues found."""
+        return self.docker.ok and not any(p.in_use for p in self.ports)
+
+
+# ── Detection functions ───────────────────────────────────────────
+
+
+def detect_os() -> OSInfo:
+    """Detect the operating system."""
+    return OSInfo(
+        system=platform.system(),
+        release=platform.release(),
+        version=platform.version(),
+        machine=platform.machine(),
+    )
+
+
+def _run(
+    cmd: list[str], *, timeout: int = 10, env: dict[str, str] | None = None,
+) -> subprocess.CompletedProcess[str]:
+    """Run a subprocess, capturing output."""
+    return subprocess.run(  # noqa: S603
+        cmd,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        env=env,
+    )
+
+
+def detect_docker() -> DockerInfo:
+    """Detect Docker Engine and Docker Compose v2.
+
+    Runs against the endpoint chosen by
+    :func:`faden_cli.core.docker_env.ensure_docker_host` (the CLI's default
+    context first, a live Rancher Desktop endpoint as a fallback).  That
+    endpoint is exported to ``os.environ`` at CLI startup, so every
+    ``docker`` subprocess here inherits it automatically — no re-plumbing.
+    """
+    info = DockerInfo()
+
+    docker_bin = shutil.which("docker")
+    if not docker_bin:
+        info.error = "docker not found on PATH"
+        return info
+
+    # Client-only check (no daemon needed)
+    try:
+        result = _run([docker_bin, "version", "--format", "{{.Client.Version}}"])
+        if result.returncode == 0 and result.stdout.strip():
+            info.installed = True
+            info.version = result.stdout.strip()
+        else:
+            stderr = result.stderr.strip()
+            # Permission denied means Docker is installed but user lacks socket access
+            if "permission denied" in stderr.lower():
+                info.installed = True
+                info.daemon_running = False
+                info.error = (
+                    "Permission denied on Docker socket. "
+                    "Add your user to the docker group: "
+                    "sudo usermod -aG docker $USER && newgrp docker"
+                )
+                return info
+            info.error = stderr or "docker version failed"
+            return info
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError) as exc:
+        info.error = str(exc)
+        return info
+
+    # Daemon reachability + server version in one call
+    try:
+        result = _run([docker_bin, "version", "--format", "{{.Server.Version}}"], timeout=30)
+        if result.returncode == 0 and result.stdout.strip():
+            info.daemon_running = True
+            info.version = result.stdout.strip()
+        else:
+            info.daemon_running = False
+            stderr = result.stderr.strip()
+            if "permission denied" in stderr.lower():
+                info.error = (
+                    "Permission denied on Docker socket. "
+                    "Add your user to the docker group: "
+                    "sudo usermod -aG docker $USER && newgrp docker"
+                )
+            else:
+                info.error = stderr
+    except subprocess.TimeoutExpired:
+        info.daemon_running = False
+        info.error = "docker daemon did not respond within 30 s"
+    except (FileNotFoundError, OSError):
+        info.daemon_running = False
+
+    # Docker Compose v2 (docker compose subcommand)
+    try:
+        result = _run([docker_bin, "compose", "version", "--short"])
+        if result.returncode == 0 and result.stdout.strip():
+            info.compose_installed = True
+            info.compose_version = result.stdout.strip().lstrip("v")
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        pass
+
+    return info
+
+
+def detect_gpu() -> GpuInfo:
+    """Detect GPU vendor and devices (NVIDIA via nvidia-smi, AMD via rocm-smi)."""
+    info = GpuInfo()
+
+    # Try NVIDIA first
+    nvidia_smi = shutil.which("nvidia-smi")
+    if nvidia_smi:
+        try:
+            result = _run([
+                nvidia_smi,
+                "--query-gpu=index,name,memory.total,driver_version",
+                "--format=csv,noheader,nounits",
+            ])
+            if result.returncode == 0 and result.stdout.strip():
+                info.vendor = "nvidia"
+                for line in result.stdout.strip().splitlines():
+                    parts = [p.strip() for p in line.split(",")]
+                    if len(parts) >= 4:  # noqa: PLR2004
+                        try:
+                            vram = int(float(parts[2]))
+                        except (ValueError, TypeError):
+                            vram = 0
+                        device = GpuDevice(
+                            index=int(parts[0]),
+                            name=parts[1],
+                            vram_mb=vram,
+                            driver_version=parts[3],
+                        )
+                        info.devices.append(device)
+                        info.driver_version = parts[3]
+
+                # Get CUDA version
+                cuda_result = _run([nvidia_smi])
+                if cuda_result.returncode == 0:
+                    match = re.search(r"CUDA Version:\s*([\d.]+)", cuda_result.stdout)
+                    if match:
+                        info.cuda_version = match.group(1)
+                        for d in info.devices:
+                            d.cuda_version = match.group(1)
+                return info
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError, ValueError) as exc:
+            info.error = str(exc)
+
+    # Try AMD ROCm
+    rocm_smi = shutil.which("rocm-smi")
+    if rocm_smi:
+        try:
+            result = _run([rocm_smi, "--showproductname", "--showmeminfo", "vram", "--csv"])
+            if result.returncode == 0 and result.stdout.strip():
+                info.vendor = "amd"
+                # ROCm CSV parsing is more complex; simplified version
+                for i, line in enumerate(result.stdout.strip().splitlines()[1:]):
+                    parts = [p.strip() for p in line.split(",")]
+                    if len(parts) >= 2:  # noqa: PLR2004
+                        info.devices.append(
+                            GpuDevice(
+                                index=i,
+                                name=parts[1] if len(parts) > 1 else f"AMD GPU {i}",
+                                vram_mb=0,  # parsed separately in real impl
+                                driver_version="",
+                            ),
+                        )
+                # ROCm version
+                rocm_ver = _run(["rocm-smi", "--version"])
+                if rocm_ver.returncode == 0:
+                    info.rocm_version = rocm_ver.stdout.strip()
+                return info
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError) as exc:
+            info.error = str(exc)
+
+    return info
+
+
+def detect_ram() -> RamInfo:
+    """Detect system memory."""
+    mem = psutil.virtual_memory()
+    return RamInfo(
+        total_gb=round(mem.total / (1024**3), 1),
+        available_gb=round(mem.available / (1024**3), 1),
+        used_pct=mem.percent,
+    )
+
+
+def detect_disk(path: str = "/") -> DiskInfo:
+    """Detect disk space for the given path."""
+    if platform.system() == "Windows":
+        path = "C:\\"
+    usage = psutil.disk_usage(path)
+    return DiskInfo(
+        path=path,
+        total_gb=round(usage.total / (1024**3), 1),
+        free_gb=round(usage.free / (1024**3), 1),
+        used_pct=usage.percent,
+    )
+
+
+# ── Port map (all ports used by Fadenstack) ─────────────────────────
+
+from faden_cli.core.registry import KNOWN_PORTS
+
+
+def check_port(port: int, label: str = "") -> PortCheck:
+    """Check if a TCP port is already in use on localhost."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.settimeout(0.5)
+        in_use = s.connect_ex(("127.0.0.1", port)) == 0
+    return PortCheck(port=port, label=label, in_use=in_use)
+
+
+def check_known_ports() -> list[PortCheck]:
+    """Check all known Fadenstack ports."""
+    return [check_port(port, label) for port, label in KNOWN_PORTS]
+
+
+#: What a production install publishes on the host, for when the compose file
+#: cannot be asked (no Docker yet). ``check_install_ports`` reads the real list.
+FALLBACK_INSTALL_PORTS: list[tuple[int, str]] = [
+    (80, "nginx: console, API, gateway"),
+    (443, "nginx: the same over HTTPS, once a certificate is installed"),
+    (3001, "grafana"),
+    (3002, "langfuse-web"),
+    (3100, "loki"),
+    (9099, "prometheus"),
+]
+
+
+def _published_ports(compose_file: Path, env_file: Path | None) -> list[tuple[int, str]] | None:
+    """The host ports *compose_file* publishes, with the service, or ``None`` if Docker cannot say."""
+    import json  # noqa: PLC0415
+
+    docker = shutil.which("docker")
+    if not docker:
+        return None
+    cmd = [docker, "compose", "-f", str(compose_file)]
+    if env_file is not None and env_file.is_file():
+        cmd += ["--env-file", str(env_file)]
+    # The compose file requires its secrets (${NAME:?...}) and stops without them, before
+    # deploy has written any. Ports do not depend on them: placeholders let it answer, and
+    # the real ones never reach this process's output.
+    import os  # noqa: PLC0415
+
+    from faden_cli.core.env_gen import REQUIRED_KEYS  # noqa: PLC0415
+
+    env = {**os.environ, **dict.fromkeys(REQUIRED_KEYS, "placeholder")}
+    try:
+        out = _run([*cmd, "config", "--format", "json"], timeout=30, env=env)
+        spec = json.loads(out.stdout or "{}") if out.returncode == 0 else None
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return None
+    if not spec:
+        return None
+    ports: dict[int, str] = {}
+    for name, service in (spec.get("services") or {}).items():
+        for mapping in (service or {}).get("ports") or []:
+            try:
+                ports.setdefault(int(mapping.get("published")), name)
+            except (TypeError, ValueError):
+                continue
+    return sorted(ports.items())
+
+
+def _ports_held_by_faden() -> set[int]:
+    """Host ports Fadenstack's own containers publish (``faden-*``)."""
+    docker = shutil.which("docker")
+    if not docker:
+        return set()
+    try:
+        out = _run([docker, "ps", "--format", "{{.Names}}\t{{.Ports}}"], timeout=15)
+    except (OSError, subprocess.SubprocessError):
+        return set()
+    held: set[int] = set()
+    for line in (out.stdout or "").splitlines():
+        name, _, ports = line.partition("\t")
+        if not name.startswith("faden-"):
+            continue
+        # "0.0.0.0:80->80/tcp, [::]:80->80/tcp, 127.0.0.1:9099->9090/tcp"
+        for match in re.finditer(r":(\d+)->", ports):
+            held.add(int(match.group(1)))
+    return held
+
+
+def check_install_ports(compose_file: Path | None, env_file: Path | None = None) -> list[PortCheck]:
+    """The host ports an install needs, and whether something else holds them.
+
+    Read from the compose file the install runs, so the list is what
+    ``docker compose up`` will bind -- a port held by something else stops
+    it ("port is already allocated"). Ports Fadenstack's own containers hold
+    are marked as such, not as conflicts.
+    """
+    published = _published_ports(compose_file, env_file) if compose_file else None
+    wanted = published if published is not None else FALLBACK_INSTALL_PORTS
+    ours = _ports_held_by_faden()
+    checks = []
+    for port, label in wanted:
+        check = check_port(port, label)
+        check.ours = check.in_use and port in ours
+        checks.append(check)
+    return checks
+
+
+# Directories probed for freshly installed tools that are not yet on
+# the session PATH (e.g. the uv installer drops into ~/.local/bin).
+EXTRA_TOOL_DIRS: tuple[str, ...] = (
+    str(Path.home() / ".local" / "bin"),
+    str(Path.home() / ".cargo" / "bin"),
+)
+
+
+def ensure_tool_path() -> None:
+    """Prepend common tool dirs to this process's PATH (in-place).
+
+    Call once at CLI startup so child subprocesses (``uv sync``, ``npm``…)
+    can find tools that the user's shell put in ``~/.local/bin`` /
+    ``~/.cargo/bin`` but that are missing from the current PATH
+    (headless SSH sessions, cron, GUI-launched terminals).
+    """
+    import os
+
+    path_parts = os.environ.get("PATH", "").split(os.pathsep)
+    for extra in reversed(EXTRA_TOOL_DIRS):
+        if extra not in path_parts:
+            path_parts.insert(0, extra)
+    os.environ["PATH"] = os.pathsep.join(path_parts)
+
+
+def find_tool_path(name: str) -> str | None:
+    """Locate a CLI tool on PATH or in common post-install locations."""
+    path = shutil.which(name)
+    if path:
+        return path
+    for extra in EXTRA_TOOL_DIRS:
+        candidate = Path(extra) / name
+        if candidate.is_file() and candidate.stat().st_mode & 0o111:
+            return str(candidate)
+    return None
+
+
+def check_tool(name: str, *, version_flag: str = "--version") -> ToolCheck:
+    """Check if a CLI tool exists on PATH (or a known install dir) + version."""
+    hint = TOOL_INSTALL_HINTS.get(name, "")
+    path = find_tool_path(name)
+    if not path:
+        return ToolCheck(name=name, found=False, install_hint=hint)
+    try:
+        result = _run([path, version_flag])
+        version = result.stdout.strip() or result.stderr.strip()
+        # Extract just the version number from common formats
+        match = re.search(r"(\d+\.\d+[\.\d]*)", version)
+        ver = match.group(1) if match else version[:60]
+        return ToolCheck(name=name, found=True, version=ver, path=path, install_hint=hint)
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return ToolCheck(name=name, found=True, path=path, install_hint=hint)
+
+
+def check_dev_tools() -> list[ToolCheck]:
+    """Check all tools needed for dev mode."""
+    return [
+        check_tool("docker"),
+        check_tool("git"),
+        check_tool("uv"),
+        check_tool("node"),
+        check_tool("npm"),
+        check_tool("poetry"),
+    ]
+
+
+# ── Full system report ────────────────────────────────────────────
+
+
+def full_report(*, check_ports: bool = True, install_path: str = "/") -> SystemReport:
+    """Run all detection checks and return a unified report."""
+    return SystemReport(
+        os=detect_os(),
+        docker=detect_docker(),
+        gpu=detect_gpu(),
+        ram=detect_ram(),
+        disk=detect_disk(install_path),
+        ports=check_known_ports() if check_ports else [],
+        tools=check_dev_tools(),
+    )