KiCad - the KiCad Bridge

"""kicad_diagnostics — read-only self-inspection so debugging the bridge never
needs Bridge's approval-gated `run_script`/shell.

Everything here runs INSIDE the bridge process, which already has full filesystem
+ subprocess access on the user's desktop (no approval prompt). During the
ADOMBASELINE bring-up we kept reaching for Bridge's `run_script` (powershell) just to
answer "where did KiCad install?", "what env does the bridge see?", "is pcbnew
running?" — all of which the bridge can answer directly. This verb exposes that,
so an agent can diagnose a detection/config/env problem with zero shell approval.

Args (all optional):
  probePaths: [str]  — for each path report exists/isDir/isFile/size + (dirs) a
                       capped child listing. Read-only metadata.
  readFile:   str    — return the text content of a single file if it's small
                       (<256 KB) and decodes as UTF-8. For peeking config/output.
  maxEntries: int    — cap on dir-listing length per probed dir (default 60).
"""

import os
import sys
import platform
import subprocess
from pathlib import Path

_READ_LIMIT = 256 * 1024
_ENV_KEYS = (
    "LOCALAPPDATA", "APPDATA", "USERPROFILE", "HOMEDRIVE", "HOMEPATH",
    "PROGRAMFILES", "PROGRAMFILES(X86)", "PROGRAMDATA", "TEMP", "TMP",
    "ADOM_BIND_HOST", "PATH",
)
_PROC_NAMES = ("kicad", "kicad-cli", "pcbnew", "eeschema", "gerbview",
               "pl_editor", "bitmap2component", "pcb_calculator")


def _list_processes() -> list:
    """Running KiCad-family processes (name + pid + exe). On Windows uses the
    ctypes EnumProcesses API (instant, in-process) instead of spawning tasklist,
    which timed out dumping the full process table on a busy VM."""
    procs = []
    exes = {n + ".exe" for n in _PROC_NAMES}
    if sys.platform == "win32":
        try:
            import ctypes
            import ctypes.wintypes
            psapi = ctypes.windll.psapi
            kernel32 = ctypes.windll.kernel32
            PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
            arr = (ctypes.wintypes.DWORD * 8192)()
            br = ctypes.wintypes.DWORD()
            if not psapi.EnumProcesses(ctypes.byref(arr), ctypes.sizeof(arr), ctypes.byref(br)):
                return [{"error": "EnumProcesses failed"}]
            count = br.value // ctypes.sizeof(ctypes.wintypes.DWORD)
            buf = ctypes.create_unicode_buffer(1024)
            for i in range(count):
                pid = arr[i]
                if not pid:
                    continue
                h = kernel32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
                if not h:
                    continue
                try:
                    size = ctypes.wintypes.DWORD(1024)
                    if kernel32.QueryFullProcessImageNameW(h, 0, buf, ctypes.byref(size)):
                        p = buf.value
                        if os.path.basename(p).lower() in exes:
                            procs.append({"name": os.path.basename(p), "pid": pid, "exe": p})
                finally:
                    kernel32.CloseHandle(h)
        except Exception as e:  # pylint: disable=broad-except
            return [{"error": f"EnumProcesses failed: {e}"}]
    else:
        try:
            out = subprocess.run(["ps", "-eo", "pid,comm"], capture_output=True,
                                 text=True, timeout=10).stdout
            for line in out.splitlines()[1:]:
                bits = line.split(None, 1)
                if len(bits) == 2 and any(n in bits[1].lower() for n in _PROC_NAMES):
                    procs.append({"name": bits[1].strip(), "pid": bits[0]})
        except Exception as e:  # pylint: disable=broad-except
            return [{"error": f"ps failed: {e}"}]
    return procs


def _probe(path_str: str, max_entries: int) -> dict:
    p = Path(path_str)
    info = {"path": str(p), "exists": False, "isDir": False, "isFile": False}
    try:
        info["exists"] = p.exists()
        if not info["exists"]:
            return info
        info["isDir"] = p.is_dir()
        info["isFile"] = p.is_file()
        if info["isFile"]:
            info["size"] = p.stat().st_size
        elif info["isDir"]:
            names = []
            for i, entry in enumerate(sorted(p.iterdir(), key=lambda e: e.name)):
                if i >= max_entries:
                    info["truncated"] = True
                    break
                names.append(entry.name + ("/" if entry.is_dir() else ""))
            info["entries"] = names
    except Exception as e:  # pylint: disable=broad-except
        info["error"] = str(e)
    return info


def handle_diagnostics(kicad_info: dict, args: dict) -> dict:
    args = args or {}
    out = {"success": True}

    # 1. What environment does THE BRIDGE see (not the desktop user — Bridge strips it).
    out["environment"] = {
        "vars": {k: os.environ.get(k) for k in _ENV_KEYS},
        "homeResolved": str(Path.home()),
        "pythonExe": sys.executable,
        "pythonVersion": sys.version.split()[0],
        "platform": platform.platform(),
        "pid": os.getpid(),
        "cwd": os.getcwd(),
    }

    # 2. KiCad-detection breakdown: every base the detector scans, whether it
    #    exists, and which version dirs / kicad.exe it finds. This is the direct
    #    lens on the "%LOCALAPPDATA% stripped → per-user install invisible" class.
    try:
        import kicad_detect
        bases = []
        for b in getattr(kicad_detect, "WIN_KICAD_BASES", []):
            bp = Path(b)
            entry = {"base": str(bp), "exists": bp.exists(), "versionDirs": []}
            if entry["exists"]:
                try:
                    for d in sorted(bp.iterdir()):
                        if d.is_dir():
                            exe = d / "bin" / "kicad.exe"
                            entry["versionDirs"].append(
                                {"dir": d.name, "kicadExe": str(exe), "exeExists": exe.exists()})
                except Exception as e:  # pylint: disable=broad-except
                    entry["error"] = str(e)
            bases.append(entry)
        out["kicadSearch"] = {
            "bases": bases,
            "detected": kicad_detect.detect_all_kicad_versions(),
        }
    except Exception as e:  # pylint: disable=broad-except
        out["kicadSearch"] = {"error": str(e)}

    # 3. Running KiCad-family processes.
    out["processes"] = _list_processes()

    # 4. The kicad_info the bridge is currently operating with + dir existence.
    ki = {k: kicad_info.get(k) for k in
          ("version", "activeVersion", "kicad_exe", "base_dir",
           "config_dir", "user_dir", "installed")}
    for key in ("config_dir", "user_dir", "base_dir"):
        v = kicad_info.get(key)
        ki[key + "_exists"] = bool(v and Path(v).exists())
    out["kicadInfo"] = ki

    # 5. Optional scoped path probes + a small-file read (read-only).
    probe_paths = args.get("probePaths") or []
    if isinstance(probe_paths, str):
        probe_paths = [probe_paths]
    max_entries = int(args.get("maxEntries", 60))
    if probe_paths:
        out["probes"] = [_probe(p, max_entries) for p in probe_paths]

    read_file = args.get("readFile")
    if read_file:
        rp = Path(read_file)
        fr = {"path": str(rp)}
        try:
            if not rp.is_file():
                fr["error"] = "not a file"
            elif rp.stat().st_size > _READ_LIMIT:
                fr["error"] = f"too large ({rp.stat().st_size} bytes > {_READ_LIMIT})"
            else:
                fr["content"] = rp.read_text(encoding="utf-8", errors="replace")
        except Exception as e:  # pylint: disable=broad-except
            fr["error"] = str(e)
        out["fileRead"] = fr

    out["_hint"] = (
        "Read-only bridge self-diagnostics — use this INSTEAD of Bridge's approval-gated "
        "run_script/shell when debugging the bridge. `environment` shows what env the "
        "BRIDGE sees (Bridge strips it — a missing LOCALAPPDATA here explains a per-user "
        "KiCad going undetected). `kicadSearch.bases` shows every path the detector "
        "scans and what it finds. `processes` lists running KiCad exes. Pass "
        "probePaths:[...] to stat/list any path and readFile:\"...\" to peek a small "
        "config/output file — all without a shell-approval prompt."
    )
    return out