ixt-cli 0.8.0__py3-none-any.whl

ixt/core/doctor.py

@@ -0,0 +1,591 @@
+"""Diagnostic checks for ixt health."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import site
+import subprocess  # nosemgrep: gitlab.bandit.B404
+import tempfile
+import urllib.error
+import urllib.parse
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ixt.config.settings import Settings, get_settings
+from ixt.core.bootstrap import (
+    MIN_BUN_VERSION,
+    MIN_UV_VERSION,
+    RuntimeName,
+    _parse_bun_version,
+    _parse_uv_version,
+)
+from ixt.core.cache import count_and_size, humanize_size
+from ixt.libs.shell import command_exists, shell_run
+from ixt.net.http import HttpError, get_bytes, get_final_url
+
+_MIN_FREE_BYTES = 100 * 1024 * 1024
+_NETWORK_TIMEOUT_SECONDS = 5
+_LOOSE_VERSION_RE = re.compile(r"v?(\d+(?:\.\d+)*)")
+_NETWORK_TARGETS = (
+    ("github", "GitHub connectivity", "https://api.github.com/"),
+    ("pypi", "PyPI connectivity", "https://pypi.org/pypi/pip/json"),
+    ("npm", "npm registry", "https://registry.npmjs.org/-/ping"),
+)
+
+
+@dataclass(slots=True)
+class Check:
+    """Result of a single diagnostic check."""
+
+    name: str
+    ok: bool
+    detail: str
+    hint: str = ""
+
+
+@dataclass(slots=True)
+class DoctorReport:
+    """Full diagnostic report."""
+
+    checks: list[Check] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return all(c.ok for c in self.checks)
+
+    @property
+    def warnings(self) -> list[Check]:
+        return [c for c in self.checks if not c.ok]
+
+
+def run_doctor(*, settings: Settings | None = None, network: bool = True) -> DoctorReport:
+    """Run all diagnostic checks and return a report."""
+    settings = settings or get_settings()
+    report = DoctorReport()
+
+    report.checks.append(_check_bin_in_path(settings))
+    report.checks.append(_check_shell())
+    report.checks.append(_check_shell_init(settings))
+    report.checks.append(_check_home_exists(settings))
+    report.checks.append(_check_home_writable(settings))
+    report.checks.append(_check_disk_space(settings))
+    report.checks.append(_check_install_mode())
+    report.checks.append(_check_managed_runtime(_UV_DOCTOR_SPEC, settings, network=network))
+    report.checks.append(_check_managed_runtime(_BUN_DOCTOR_SPEC, settings, network=network))
+    report.checks.append(_check_system_runtime(_UV_DOCTOR_SPEC))
+    report.checks.append(_check_system_runtime(_BUN_DOCTOR_SPEC))
+    report.checks.append(_check_github_token())
+    report.checks.append(_check_installed_tools(settings))
+    report.checks.append(_check_pattern_cache())
+    report.checks.append(_check_install_cache(settings))
+    report.checks.extend(_check_network(network))
+
+    return report
+
+
+def _check_bin_in_path(settings: Settings) -> Check:
+    """Check that the shims dir is in PATH."""
+    bin_dir = str(settings.bin_dir)
+    path_dirs = os.environ.get("PATH", "").split(os.pathsep)
+    found = any(os.path.normpath(d) == os.path.normpath(bin_dir) for d in path_dirs)
+    if found:
+        return Check("PATH", True, f"{bin_dir} is in PATH")
+    return Check(
+        "PATH",
+        False,
+        f"{bin_dir} not in PATH",
+        hint="Run: ixt setup path",
+    )
+
+
+def _check_shell() -> Check:
+    """Report the detected shell and the config file ixt expects to manage."""
+    from ixt.core.setup_path import _detect_shell, _target
+
+    shell = _detect_shell()
+    if shell == "unknown":
+        return Check("Shell", True, "unknown")
+    try:
+        target = _target(shell)
+    except ValueError:
+        return Check("Shell", True, shell)
+    return Check("Shell", True, f"{shell} ({target})")
+
+
+def _check_shell_init(settings: Settings) -> Check:
+    """Check whether shell startup config contains the ixt PATH block."""
+    from ixt.core.setup_path import _detect_shell, setup_path
+    from ixt.platform import is_windows
+
+    if _detect_shell() == "unknown" and not is_windows():
+        return Check(
+            "Shell init",
+            False,
+            "unknown shell; cannot verify shell startup file",
+            hint="Run: ixt setup path, then apply the printed snippet manually",
+        )
+
+    result = setup_path(check_only=True, settings=settings)
+    detail = result.message
+    if result.config_file is not None:
+        detail = f"{detail} ({result.config_file})"
+    if result.warning:
+        detail = f"{detail}; {result.warning}"
+
+    if result.status in ("ok", "ok_restart"):
+        return Check("Shell init", True, detail)
+
+    if result.status == "blocked":
+        return Check(
+            "Shell init",
+            False,
+            detail,
+            hint="Run: ixt setup path, then apply the printed snippet manually",
+        )
+
+    return Check("Shell init", False, detail, hint="Run: ixt setup path")
+
+
+def _check_home_exists(settings: Settings) -> Check:
+    """Check that the IXT_HOME directory structure exists."""
+    missing = []
+    for d in [
+        settings.home,
+        settings.config_dir,
+        settings.installed_dir,
+        settings.bin_dir,
+        settings.envs_dir,
+        settings.runtimes_dir,
+    ]:
+        if not d.exists():
+            missing.append(str(d))
+    if not missing:
+        return Check("Home", True, str(settings.home))
+    return Check(
+        "Home",
+        False,
+        f"Missing: {', '.join(missing)}",
+        hint="Directories will be created on first install",
+    )
+
+
+def _nearest_existing_parent(path: Path) -> Path | None:
+    current = path
+    while not current.exists():
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+    return current
+
+
+def _check_home_writable(settings: Settings) -> Check:
+    """Check that ``$IXT_HOME`` can be written or created."""
+    home = settings.home
+    if home.exists() and not home.is_dir():
+        return Check("Home writable", False, f"{home} exists but is not a directory")
+
+    if home.exists():
+        try:
+            with tempfile.NamedTemporaryFile(prefix=".ixt-doctor-", dir=home):
+                pass
+        except OSError as exc:
+            return Check("Home writable", False, f"{home} is not writable: {exc}")
+        return Check("Home writable", True, f"{home} is writable")
+
+    parent = _nearest_existing_parent(home)
+    if parent is None:
+        return Check("Home writable", False, f"no existing parent for {home}")
+    if os.access(parent, os.W_OK | os.X_OK):
+        return Check("Home writable", True, f"{home} can be created under {parent}")
+    return Check(
+        "Home writable",
+        False,
+        f"{parent} is not writable",
+        hint=f"Fix permissions for {parent}",
+    )
+
+
+def _check_disk_space(settings: Settings) -> Check:
+    """Check free disk space under the ixt data root."""
+    base = settings.home if settings.home.exists() else _nearest_existing_parent(settings.home)
+    if base is None:
+        return Check("Disk space", False, f"no existing parent for {settings.home}")
+    try:
+        usage = shutil.disk_usage(base)
+    except OSError as exc:
+        return Check("Disk space", False, f"cannot inspect {base}: {exc}")
+    free = usage.free
+    detail = f"{humanize_size(free)} free under {base}"
+    if free >= _MIN_FREE_BYTES:
+        return Check("Disk space", True, detail)
+    return Check(
+        "Disk space",
+        False,
+        detail,
+        hint=f"Free at least {humanize_size(_MIN_FREE_BYTES)} under {base}",
+    )
+
+
+def _run_quiet(cmd: list[str]) -> tuple[int, str]:
+    """Run *cmd* with a 5s timeout. Return ``(returncode, stdout)``.
+
+    Returns ``(1, "")`` on any failure (timeout, missing binary, etc.).
+    """
+    try:
+        result = shell_run(cmd, capture_output=True, check=False, timeout=5)
+    except (subprocess.TimeoutExpired, OSError):
+        return 1, ""
+    return result.returncode, result.stdout
+
+
+def _pkg_listed_by(bin_name: str, args: list[str]) -> bool:
+    """True iff ``<bin_name> <args>`` lists ``ixt`` on a line of its own."""
+    if not command_exists(bin_name):
+        return False
+    rc, out = _run_quiet([bin_name, *args])
+    if rc != 0:
+        return False
+    return bool(re.search(r"^ixt\b", out, re.MULTILINE))
+
+
+def _uv_tool_has_ixt() -> bool:
+    return _pkg_listed_by("uv", ["tool", "list"])
+
+
+def _pipx_has_ixt() -> bool:
+    return _pkg_listed_by("pipx", ["list", "--short"])
+
+
+def _pip_user_has_ixt() -> bool:
+    """True iff `pip show ixt` reports a Location under user site-packages."""
+    pip = shutil.which("pip") or shutil.which("pip3")
+    if not pip:
+        return False
+    rc, out = _run_quiet([pip, "show", "ixt"])
+    if rc != 0:
+        return False
+    try:
+        user_site = str(Path(site.getusersitepackages()).resolve())
+    except OSError:
+        return False
+    for line in out.splitlines():
+        if not line.startswith("Location:"):
+            continue
+        try:
+            location = str(Path(line.split(":", 1)[1].strip()).resolve())
+        except OSError:
+            return False
+        return location == user_site or location.startswith(user_site + os.sep)
+    return False
+
+
+def _detect_install_modes() -> list[tuple[str, str]]:
+    """Detect every ixt install across uv tool / pipx / pip --user.
+
+    Each mechanism is queried independently (``uv tool list``,
+    ``pipx list --short``, ``pip show ixt``) so that an install dormant
+    on PATH but visible to its package manager still surfaces. Multiple
+    entries mean ixt is installed via several mechanisms — flagged as
+    ambiguous so the user can consolidate.
+    """
+    modes: list[tuple[str, str]] = []
+    if _uv_tool_has_ixt():
+        modes.append(("uv tool", "uv tool upgrade ixt"))
+    if _pipx_has_ixt():
+        modes.append(("pipx", "pipx upgrade ixt"))
+    if _pip_user_has_ixt():
+        modes.append(("pip --user", "pip install --user --upgrade ixt"))
+    return modes
+
+
+def _check_install_mode() -> Check:
+    """Detect ixt's install mode and surface the matching upgrade command."""
+    modes = _detect_install_modes()
+    if len(modes) == 1:
+        label, cmd = modes[0]
+        return Check("install mode", True, f"installed via {label}", hint=f"upgrade: {cmd}")
+    if len(modes) > 1:
+        labels = " and ".join(label for label, _ in modes)
+        return Check(
+            "install mode",
+            False,
+            f"ambiguous: ixt installed via {labels}",
+            hint="Re-install via a single mode to enable upgrade auto-detection",
+        )
+    return Check("install mode", True, "not detected (dev / from source)")
+
+
+@dataclass(frozen=True)
+class _RuntimeDoctorSpec:
+    name: RuntimeName
+    min_version: tuple[int, ...]
+    parse_version: Callable[[str], tuple[int, ...]]
+    managed_path: Callable[[Settings], Path]
+    latest_owner: str
+    latest_repo: str
+    self_upgrade_cmd: str
+
+
+@dataclass(frozen=True)
+class _RuntimeCommand:
+    path: str
+    version: str | None
+    parsed: tuple[int, ...] | None
+    error: str | None = None
+
+
+@dataclass(frozen=True)
+class _LatestRuntime:
+    version: str | None
+    error: str | None = None
+
+
+_UV_DOCTOR_SPEC = _RuntimeDoctorSpec(
+    name="uv",
+    min_version=MIN_UV_VERSION,
+    parse_version=_parse_uv_version,
+    managed_path=lambda s: s.uv_runtime,
+    latest_owner="astral-sh",
+    latest_repo="uv",
+    self_upgrade_cmd="uv self update",
+)
+
+_BUN_DOCTOR_SPEC = _RuntimeDoctorSpec(
+    name="bun",
+    min_version=MIN_BUN_VERSION,
+    parse_version=_parse_bun_version,
+    managed_path=lambda s: s.bun_runtime,
+    latest_owner="oven-sh",
+    latest_repo="bun",
+    self_upgrade_cmd="bun upgrade",
+)
+
+
+def _inspect_runtime(path: str, parse_version: Callable[[str], tuple[int, ...]]) -> _RuntimeCommand:
+    rc, out = _run_quiet([path, "--version"])
+    if rc != 0:
+        return _RuntimeCommand(path=path, version=None, parsed=None, error="command failed")
+    version = out.strip().splitlines()[0] if out.strip() else "unknown"
+    try:
+        parsed = parse_version(version)
+    except Exception as exc:
+        return _RuntimeCommand(path=path, version=version, parsed=None, error=str(exc))
+    return _RuntimeCommand(path=path, version=version, parsed=parsed)
+
+
+def _version_tuple_str(version: tuple[int, ...]) -> str:
+    return ".".join(str(part) for part in version)
+
+
+def _parse_loose_version(text: str) -> tuple[int, ...] | None:
+    match = _LOOSE_VERSION_RE.search(text.strip())
+    if match is None:
+        return None
+    return tuple(int(part) for part in match.group(1).split("."))
+
+
+def _compare_version_tuples(a: tuple[int, ...], b: tuple[int, ...]) -> int:
+    length = max(len(a), len(b))
+    left = a + (0,) * (length - len(a))
+    right = b + (0,) * (length - len(b))
+    if left < right:
+        return -1
+    if left > right:
+        return 1
+    return 0
+
+
+def _latest_runtime_version(spec: _RuntimeDoctorSpec) -> _LatestRuntime:
+    from ixt.net.github_api import parse_tag_from_release_url
+
+    url = f"https://github.com/{spec.latest_owner}/{spec.latest_repo}/releases/latest"
+    try:
+        final = get_final_url(url, timeout=_NETWORK_TIMEOUT_SECONDS)
+    except HttpError as exc:
+        return _LatestRuntime(None, str(exc))
+    tag = parse_tag_from_release_url(final)
+    if tag is None:
+        return _LatestRuntime(None, f"unexpected redirect: {final}")
+    return _LatestRuntime(tag, None)
+
+
+def _latest_detail(latest: _LatestRuntime | None, *, network: bool) -> str:
+    if not network:
+        return "latest skipped (--no-network)"
+    if latest is None or latest.version is None:
+        error = latest.error if latest else "unknown"
+        return f"latest unavailable ({error})"
+    return f"latest {latest.version}"
+
+
+def _runtime_upgrade_hint(name: RuntimeName) -> str:
+    return f"Run: ixt runtime upgrade {name}"
+
+
+def _system_runtime_hint(spec: _RuntimeDoctorSpec) -> str:
+    return f"Run: {spec.self_upgrade_cmd}; or: ixt runtime upgrade {spec.name}"
+
+
+def _check_managed_runtime(
+    spec: _RuntimeDoctorSpec,
+    settings: Settings,
+    *,
+    network: bool,
+) -> Check:
+    path = spec.managed_path(settings)
+    latest = _latest_runtime_version(spec) if network else None
+    latest_text = _latest_detail(latest, network=network)
+    name = f"{spec.name} runtime"
+
+    if not path.exists():
+        return Check(
+            name,
+            False,
+            f"missing at {path}; {latest_text}",
+            hint=_runtime_upgrade_hint(spec.name),
+        )
+
+    status = _inspect_runtime(str(path), spec.parse_version)
+    if status.error or status.version is None or status.parsed is None:
+        return Check(
+            name,
+            False,
+            f"broken at {path}: {status.error or 'unknown error'}; {latest_text}",
+            hint=_runtime_upgrade_hint(spec.name),
+        )
+
+    detail = f"local {status.version} at {path}; {latest_text}"
+    if _compare_version_tuples(status.parsed, spec.min_version) < 0:
+        min_v = _version_tuple_str(spec.min_version)
+        return Check(
+            name,
+            False,
+            f"{detail}; minimum {min_v}",
+            hint=_runtime_upgrade_hint(spec.name),
+        )
+
+    latest_parsed = _parse_loose_version(latest.version) if latest and latest.version else None
+    if latest_parsed is not None and _compare_version_tuples(status.parsed, latest_parsed) < 0:
+        return Check(name, False, detail, hint=_runtime_upgrade_hint(spec.name))
+
+    return Check(name, True, detail)
+
+
+def _check_system_runtime(spec: _RuntimeDoctorSpec) -> Check:
+    path = shutil.which(spec.name)
+    name = f"system {spec.name}"
+    if path is None:
+        return Check(name, True, "not on PATH")
+
+    status = _inspect_runtime(path, spec.parse_version)
+    if status.error or status.version is None or status.parsed is None:
+        return Check(
+            name,
+            False,
+            f"broken at {path}: {status.error or 'unknown error'}",
+            hint=_system_runtime_hint(spec),
+        )
+
+    detail = f"{status.version} at {path}"
+    if _compare_version_tuples(status.parsed, spec.min_version) < 0:
+        min_v = _version_tuple_str(spec.min_version)
+        return Check(name, False, f"{detail}; minimum {min_v}", hint=_system_runtime_hint(spec))
+    return Check(name, True, detail)
+
+
+def _check_github_token() -> Check:
+    """Check GITHUB_TOKEN / GH_TOKEN availability."""
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    if token:
+        return Check("GitHub token", True, "set (5000 req/h)")
+    return Check(
+        "GitHub token",
+        False,
+        "not set (60 req/h)",
+        hint="export GITHUB_TOKEN=$(gh auth token)",
+    )
+
+
+def _check_installed_tools(settings: Settings) -> Check:
+    """Count installed tools per backend."""
+    counts: dict[str, int] = {"python": 0, "node": 0, "binary": 0}
+    total = 0
+    for meta_file in settings.iter_installed_metadata():
+        total += 1
+        try:
+            from ixt.config.models import ToolRecord
+
+            record = ToolRecord.load_json(meta_file)
+            counts[record.backend] = counts.get(record.backend, 0) + 1
+        except Exception:
+            pass
+    parts = [f"{v} {k}" for k, v in counts.items() if v > 0]
+    detail = f"{total} tools" + (f" ({', '.join(parts)})" if parts else "")
+    return Check("Tools", True, detail)
+
+
+def _check_pattern_cache() -> Check:
+    """Count learned asset patterns in the metadata cache."""
+    from ixt.config import asset_pattern_cache
+
+    path = asset_pattern_cache._cache_path()
+    count = len(asset_pattern_cache._load())
+    plural = "pattern" if count == 1 else "patterns"
+    return Check("Pattern cache", True, f"{count} {plural} — {path}")
+
+
+def _check_install_cache(settings: Settings) -> Check:
+    """Report size of the downloads cache."""
+    path = settings.downloads_dir
+    _, size = count_and_size(path)
+    return Check("Downloads cache", True, f"{humanize_size(size)} — {path}")
+
+
+def _probe_url(target_id: str) -> None:
+    url = ""
+    for candidate_id, _name, candidate_url in _NETWORK_TARGETS:
+        if candidate_id == target_id:
+            url = candidate_url
+            break
+    if not url:
+        raise OSError(f"URL not allowed for doctor probe: {target_id}")
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme != "https" or parsed.username:
+        raise OSError(f"URL not allowed for doctor probe: {target_id}")
+    get_bytes(url, headers={"User-Agent": "ixt-doctor/1"}, timeout=_NETWORK_TIMEOUT_SECONDS)
+
+
+def _check_network(enabled: bool) -> list[Check]:
+    if not enabled:
+        return [
+            Check(name, True, "skipped (--no-network)") for _target_id, name, _ in _NETWORK_TARGETS
+        ]
+
+    checks: list[Check] = []
+    for target_id, name, url in _NETWORK_TARGETS:
+        try:
+            _probe_url(target_id)
+        except (HttpError, OSError, urllib.error.URLError, urllib.error.HTTPError) as exc:
+            checks.append(
+                Check(
+                    name,
+                    False,
+                    f"failed: {exc}",
+                    hint="Check DNS/proxy/firewall, or rerun: ixt doctor --no-network",
+                )
+            )
+        else:
+            checks.append(Check(name, True, url))
+    return checks
+
+
+def _get_cmd_version(cmd: str) -> str:
+    """Get version string from a command."""
+    rc, out = _run_quiet([cmd, "--version"])
+    if rc != 0:
+        return "unknown"
+    return out.strip().split("\n")[0] or "unknown"