cachekat 0.4.8__py3-none-any.whl

cachekat/probes/docker_df.py

@@ -0,0 +1,226 @@
+"""Docker disk usage probe — `docker system df --format json`, risk-graded.
+
+Red line: Local Volumes are data, REPORT_ONLY forever. Sizes come from
+docker's own numbers (reclaimable for cleanable rows).
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from cachekat import keys
+from cachekat.i18n import t
+from cachekat.models import Finding, Risk
+from cachekat.registry import register
+
+RunFn = Callable[[list[str]], subprocess.CompletedProcess[str]]
+
+_DF_TIMEOUT = 30  # seconds; system df on a big machine can take a while
+_DF_CMD = ["docker", "system", "df", "--format", "{{json .}}"]
+
+
+@dataclass(frozen=True)
+class _Row:
+    type: str
+    size_bytes: int
+    reclaimable_bytes: int
+    count: int
+
+
+def _run(cmd: list[str]) -> subprocess.CompletedProcess[str]:
+    # encoding is EXPLICIT: docker speaks UTF-8 on every platform. With the
+    # default locale codec (cp936 on zh-Windows) a non-ASCII byte sequence
+    # crashes the hidden Windows reader thread inside communicate() — the
+    # exception is swallowed by the thread and we get stdout=None, rc=0
+    # (2026-10-09 real-machine incident, see tests/test_docker_probe.py).
+    return subprocess.run(
+        cmd, capture_output=True, text=True,
+        encoding="utf-8", errors="replace", timeout=_DF_TIMEOUT,
+    )
+
+
+def parse_size(text: str) -> int:
+    """'516.2MB (55%)' -> 516_200_000 (docker uses decimal SI units)."""
+    s = text.split("(")[0].strip().replace(" ", "")
+    if not s or s == "0B":
+        return 0
+    # longest-first is load-bearing: "516.2MB" also ends with "B"
+    units = {"TB": 10**12, "GB": 10**9, "MB": 10**6, "KB": 10**3, "B": 1}
+    for suffix, mult in units.items():
+        if s.endswith(suffix):
+            num = s[: -len(suffix)]
+            try:
+                value = float(num) if "." in num else int(num)
+            except ValueError:
+                return 0
+            return int(value * mult)
+    return 0
+
+
+def _parse_rows(stdout: str) -> list[_Row]:
+    rows: list[_Row] = []
+    for line in stdout.splitlines():
+        if not line.strip():
+            continue
+        d = json.loads(line)  # malformed line = probe error, surfaces upstream
+        rows.append(
+            _Row(
+                type=str(d.get("Type", "")),
+                size_bytes=parse_size(str(d.get("Size", ""))),
+                reclaimable_bytes=parse_size(str(d.get("Reclaimable", ""))),
+                count=int(d.get("TotalCount", 0) or 0),
+            )
+        )
+    return rows
+
+
+def _findings_from_rows(rows: list[_Row]) -> list[Finding]:
+    """Aggregate rows: volumes/images/build-cache. Containers are NOT here —
+    they are per-container findings from `docker ps` (user selects each one;
+    deleting a container is removing the thing itself, not a cache)."""
+    findings: list[Finding] = []
+    for r in rows:
+        if r.type == "Local Volumes":
+            findings.append(
+                Finding(
+                    key=keys.DOCKER_VOLUMES,
+                    label=t("dock_volumes_label"),
+                    size_bytes=r.size_bytes,
+                    detail=t("dock_volumes_detail", n=r.count),
+                    risk=Risk.REPORT_ONLY,
+                )
+            )
+        elif r.type == "Images":
+            findings.append(
+                Finding(
+                    key=keys.DOCKER_IMAGES,
+                    label=t("dock_images_label"),
+                    size_bytes=r.reclaimable_bytes,
+                    detail=t("dock_images_detail"),
+                    risk=Risk.REPORT_ONLY,
+                )
+            )
+        elif r.type == "Build Cache":
+            findings.append(
+                Finding(
+                    key=keys.DOCKER_BUILD_CACHE,
+                    label=t("dock_build_label"),
+                    size_bytes=r.reclaimable_bytes,
+                    detail=t("dock_build_detail"),
+                    risk=Risk.CLEANABLE,
+                )
+            )
+    return findings
+
+
+# per-container: stopped states only — running/paused/restarting never listed
+_STOPPED_STATES = {"exited", "created", "dead"}
+_PS_CMD = ["docker", "ps", "-a", "-s", "--format", "{{json .}}"]
+
+
+def _short_image(image: str) -> str:
+    """'docker.n8n.io/n8nio/n8n:latest' -> 'n8n:latest' — registry hosts
+    are noise in a list row (2026-10-09 user report: rows overran the
+    panel). The TUI ellipsizes too, but labels shouldn't START at hopeless."""
+    return image.rsplit("/", 1)[-1]
+
+
+def _container_findings(run: RunFn) -> list[Finding]:
+    """One finding per stopped container, each CLEANABLE but individually
+    chosen. The warning is load-bearing: docker rm removes the CONTAINER
+    ITSELF, not a cache (2026-10-08 incident, explicit design decision)."""
+    try:
+        cp = run(_PS_CMD)
+    except subprocess.TimeoutExpired:
+        return [
+            Finding(
+                key=keys.DOCKER_PS_ERROR,
+                label=t("dock_ps_timeout_label"),
+                size_bytes=0,
+                detail=t("dock_ps_timeout"),
+                risk=Risk.REPORT_ONLY,
+            )
+        ]
+    if cp.returncode != 0:
+        return [
+            Finding(
+                key=keys.DOCKER_PS_ERROR,
+                label=t("dock_ps_failed_label"),
+                size_bytes=0,
+                detail=t("dock_ps_failed", rc=cp.returncode),
+                risk=Risk.REPORT_ONLY,
+            )
+        ]
+    findings: list[Finding] = []
+    for line in _stdout_or_raise(cp, "docker ps").splitlines():
+        if not line.strip():
+            continue
+        d = json.loads(line)
+        if str(d.get("State", "")) not in _STOPPED_STATES:
+            continue  # running/paused containers are never offered
+        names = str(d.get("Names", "")).split()
+        if not names:
+            continue
+        name = names[0]
+        findings.append(
+            Finding(
+                key=f"{keys.DOCKER_CONTAINER_PREFIX}{name}",
+                label=t(
+                    "dock_container_label",
+                    name=name,
+                    image=_short_image(str(d.get("Image", "?"))),
+                ),
+                size_bytes=parse_size(str(d.get("Size", ""))),
+                detail=t("dock_container_detail", status=d.get("Status", "?")),
+                risk=Risk.CLEANABLE,
+            )
+        )
+    return findings
+
+
+def _stdout_or_raise(cp: subprocess.CompletedProcess[str], cmd_name: str) -> str:
+    """rc=0 with stdout=None is a LIE: communicate() swallows reader-thread
+    crashes (the 2026-10-09 zh-Windows GBK decode incident). Refuse to guess."""
+    if cp.stdout is None:
+        msg = (
+            f"{cmd_name} exited rc={cp.returncode!r} but stdout is None — "
+            "a swallowed pipe-reader crash; see _run's encoding note"
+        )
+        raise RuntimeError(msg)
+    return cp.stdout
+
+
+@register("docker")
+def probe(runner: RunFn | None = None) -> list[Finding]:
+    """runner param exists for tests (canned CompletedProcess injection)."""
+    run = runner or _run
+    try:
+        cp = run(_DF_CMD)
+    except FileNotFoundError:
+        return []  # docker not installed on this machine — nothing to report
+    except subprocess.TimeoutExpired:
+        return [
+            Finding(
+                key=keys.DOCKER_DAEMON,
+                label=t("dock_daemon_timeout_label"),
+                size_bytes=0,
+                detail=t("dock_daemon_timeout"),
+                risk=Risk.REPORT_ONLY,
+            )
+        ]
+    if cp.returncode != 0:
+        return [
+            Finding(
+                key=keys.DOCKER_DAEMON,
+                label=t("dock_daemon_label"),
+                size_bytes=0,
+                detail=t("dock_daemon_unreachable", rc=cp.returncode),
+                risk=Risk.REPORT_ONLY,
+            )
+        ]
+    findings = _findings_from_rows(_parse_rows(_stdout_or_raise(cp, "docker system df")))
+    findings.extend(_container_findings(run))
+    return findings

cachekat/probes/npm_cache.py

@@ -0,0 +1,72 @@
+"""npm cache probe. Prefers asking npm itself; falls back to default paths."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+from cachekat import keys
+from cachekat.fsutil import dir_size_bytes
+from cachekat.models import Finding, Risk
+from cachekat.registry import register
+
+RunFn = Callable[[str], str]  # cmd -> stdout (raises OSError when missing)
+
+_NPM_TIMEOUT = 10  # seconds; `npm config get cache` should be near-instant
+
+
+def npm_default_cache_dir() -> Path:
+    """npm's documented defaults when we cannot ask npm itself."""
+    if sys.platform == "win32":
+        local = os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local"
+        return Path(local) / "npm-cache"
+    return Path.home() / ".npm"
+
+
+def _subprocess_stdout(cmd: str) -> str:
+    exe = shutil.which(cmd)  # resolves npm.cmd on Windows
+    if exe is None:
+        msg = f"{cmd} not on PATH"
+        raise FileNotFoundError(msg)
+    cp = subprocess.run(
+        [exe, "config", "get", "cache"],
+        capture_output=True, text=True,
+        encoding="utf-8", errors="replace",  # npm paths may carry non-ASCII
+        timeout=_NPM_TIMEOUT,
+    )
+    if cp.returncode != 0:
+        msg = f"{cmd} exited {cp.returncode}"
+        raise RuntimeError(msg)
+    return cp.stdout
+
+
+def resolve_cache_dir(runner: RunFn | None = None) -> Path:
+    """npm config get cache (authoritative) -> default paths (fallback)."""
+    run = runner or _subprocess_stdout
+    try:
+        out = run("npm").strip()
+    except (OSError, RuntimeError, subprocess.SubprocessError):
+        return npm_default_cache_dir()
+    if out:
+        return Path(out)
+    return npm_default_cache_dir()
+
+
+@register("npm")
+def probe(cache_dir: Path | None = None) -> list[Finding]:
+    """cache_dir param exists for tests (fake tree injection)."""
+    d = cache_dir if cache_dir is not None else resolve_cache_dir()
+    return [
+        Finding(
+            key=keys.NPM_CACHE,
+            label="npm cache (_cacache/_npx/_logs)",
+            size_bytes=dir_size_bytes(d),
+            detail=str(d),
+            risk=Risk.CLEANABLE,
+            path=d,
+        )
+    ]

cachekat/probes/pip_cache.py

@@ -0,0 +1,40 @@
+"""pip download cache probe (M0 reference probe)."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from cachekat import keys
+from cachekat.fsutil import dir_size_bytes
+from cachekat.models import Finding, Risk
+from cachekat.registry import register
+
+
+def pip_cache_dir() -> Path:
+    """Platform cache dir per pip docs (https://pip.pypa.io/en/stable/topics/caching/)."""
+    home = Path.home()
+    if sys.platform == "win32":
+        local = os.environ.get("LOCALAPPDATA") or home / "AppData" / "Local"
+        return Path(local) / "pip" / "cache"
+    if sys.platform == "darwin":
+        return home / "Library" / "Caches" / "pip"
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    return Path(xdg) / "pip" if xdg else home / ".cache" / "pip"
+
+
+@register("pip")
+def probe(cache_dir: Path | None = None) -> list[Finding]:
+    """cache_dir param exists for tests (fake tree injection)."""
+    d = cache_dir if cache_dir is not None else pip_cache_dir()
+    return [
+        Finding(
+            key=keys.PIP_CACHE,
+            label="pip download cache",
+            size_bytes=dir_size_bytes(d),
+            detail=str(d),
+            risk=Risk.CLEANABLE,
+            path=d,
+        )
+    ]

cachekat/probes/playwright_cache.py

@@ -0,0 +1,104 @@
+"""Playwright browser cache probe — orphan-version aware.
+
+Liveness comes from the installed playwright package's browsers.json
+(driver/package/browsers.json). When playwright is not importable in this
+interpreter we CANNOT tell orphans from in-use browsers — the finding is
+REPORT_ONLY with that stated, instead of a guess.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import sys
+from pathlib import Path
+
+from cachekat import keys
+from cachekat.fsutil import dir_size_bytes
+from cachekat.i18n import t
+from cachekat.models import Finding, Risk
+from cachekat.registry import register
+
+
+def browsers_dir() -> Path:
+    """Playwright's download roots per platform (PLAYWRIGHT_BROWSERS_PATH wins)."""
+    env = os.environ.get("PLAYWRIGHT_BROWSERS_PATH")
+    if env:
+        return Path(env)
+    home = Path.home()
+    if sys.platform == "win32":
+        return home / "AppData" / "Local" / "ms-playwright"
+    if sys.platform == "darwin":
+        return home / "Library" / "Caches" / "ms-playwright"
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    return Path(xdg) / "ms-playwright" if xdg else home / ".cache" / "ms-playwright"
+
+
+def needed_revisions(browsers_json: Path | None = None) -> set[str] | None:
+    """Revisions the installed playwright wants, e.g. {"chromium-1148"}.
+
+    None = playwright not importable (or browsers.json unreadable) — caller
+    must treat liveness as unknown.
+    """
+    bj = browsers_json
+    if bj is None:
+        spec = importlib.util.find_spec("playwright")
+        if spec is None or not spec.submodule_search_locations:
+            return None
+        pkg = Path(next(iter(spec.submodule_search_locations)))
+        bj = pkg / "driver" / "package" / "browsers.json"
+    if not bj.exists():
+        return None
+    try:
+        data = json.loads(bj.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    revs = {
+        f"{b.get('name')}-{b.get('revision')}"
+        for b in data.get("browsers", [])
+        if b.get("name") and b.get("revision")
+    }
+    return revs or None
+
+
+@register("playwright")
+def probe(browsers_root: Path | None = None, needed: set[str] | None = ...) -> list[Finding]:
+    """Both params exist for tests (fake tree + fake revision set).
+
+    `needed=...` (default) means: derive from the installed playwright.
+    Pass an explicit set (possibly None) to pin behaviour in tests.
+    """
+    d = browsers_root if browsers_root is not None else browsers_dir()
+    if not d.exists():
+        return []
+    revs = needed_revisions() if needed is ... else needed
+    # hidden entries (".links" = playwright's driver registry) are infra, not
+    # browsers — never counted, never cleaned
+    entries = sorted(p for p in d.iterdir() if p.is_dir() and not p.name.startswith("."))
+    if revs is None:
+        total = sum(dir_size_bytes(e) for e in entries)
+        return [
+            Finding(
+                key=keys.PLAYWRIGHT_BROWSERS,
+                label=t("pw_unknown_label"),
+                size_bytes=total,
+                detail=t("pw_unknown_detail", path=d),
+                risk=Risk.REPORT_ONLY,
+                path=d,
+            )
+        ]
+    findings: list[Finding] = []
+    for e in entries:
+        in_use = e.name in revs
+        findings.append(
+            Finding(
+                key=f"{keys.PLAYWRIGHT_PREFIX}{e.name}",
+                label=t("pw_orphan_label" if not in_use else "pw_inuse_label", name=e.name),
+                size_bytes=dir_size_bytes(e),
+                detail=str(e) + ("" if in_use else f" — {t('pw_orphan_detail')}"),
+                risk=Risk.REPORT_ONLY if in_use else Risk.CLEANABLE,
+                path=e,
+            )
+        )
+    return findings

cachekat/registry.py

@@ -0,0 +1,71 @@
+"""Probe registry — the ONE place probes register. Interface convergence."""
+
+from __future__ import annotations
+
+import os
+import traceback
+from collections.abc import Callable, Iterable
+from typing import TypeVar
+
+from cachekat.i18n import t
+from cachekat.models import Finding, Risk
+
+ProbeFn = Callable[..., list[Finding]]
+T = TypeVar("T", bound=ProbeFn)
+
+_REGISTRY: dict[str, ProbeFn] = {}
+
+
+def register(probe_id: str) -> Callable[[T], T]:
+    """Decorator: register a probe under a stable id. Duplicate ids are a bug."""
+
+    def deco(fn: T) -> T:
+        if probe_id in _REGISTRY:
+            msg = f"probe id {probe_id!r} already registered"
+            raise ValueError(msg)
+        _REGISTRY[probe_id] = fn
+        return fn
+
+    return deco
+
+
+def all_probes() -> Iterable[tuple[str, ProbeFn]]:
+    return sorted(_REGISTRY.items())
+
+
+def _crash_detail(exc: Exception) -> str:
+    """One-line crash report: exception type, raise site, message.
+
+    2026-10-09 real-world case: a probe crashed on a Windows machine and the
+    TUI's narrow table column truncated the detail to "AttributeErro" —
+    invisible WHERE. The raise site (file:line in func) makes the next
+    screenshot self-sufficient."""
+    tb = exc.__traceback__
+    last = traceback.extract_tb(tb)[-1] if tb else None
+    where = (
+        f" @{os.path.basename(last.filename)}:{last.lineno} in {last.name}"
+        if last
+        else ""
+    )
+    return f"{type(exc).__name__}{where}: {exc}"
+
+
+def run_scan() -> list[Finding]:
+    """Run every probe. A crashing probe becomes a visible error finding —
+    failures are surfaced, never swallowed (anti-fake-work clause)."""
+    findings: list[Finding] = []
+    for probe_id, fn in all_probes():
+        try:
+            findings.extend(fn())
+        except Exception as exc:  # noqa: BLE001 — deliberate: report, don't die
+            findings.append(
+                Finding(
+                    key=f"{probe_id}/error",
+                    label=t("probe_failed_label", probe=probe_id),
+                    size_bytes=0,
+                    detail=_crash_detail(exc),
+                    risk=Risk.REPORT_ONLY,
+                    is_error=True,
+                )
+            )
+    return findings