cachekat 0.4.8__py3-none-any.whl

cachekat/__init__.py

@@ -0,0 +1,3 @@
+"""CacheKat — see which dev caches eat your disk, reclaim space safely."""
+
+__version__ = "0.4.8"

cachekat/actions.py

@@ -0,0 +1,127 @@
+"""Clean actions, one per finding key. The refusal path is the feature.
+
+Rules:
+- REPORT_ONLY findings are refused, always — even in dry-run, even by
+  internal callers. There is no flag that unlocks this.
+- dry_run=True must not touch disk or run any CLI, period.
+- Unknown cleanable keys fail loudly ("no clean action implemented") —
+  pretending to clean is worse than admitting we can't.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import Protocol
+
+from cachekat import keys
+from cachekat.i18n import t
+from cachekat.models import Finding, Risk
+
+_TIMEOUT = 600  # docker prunes can be slow on big machines
+
+
+@dataclass(frozen=True)
+class ActionResult:
+    key: str
+    ok: bool
+    detail: str
+
+
+class _Runner(Protocol):
+    def __call__(self, cmd: list[str]) -> subprocess.CompletedProcess[str]: ...
+
+
+def _run(cmd: list[str]) -> subprocess.CompletedProcess[str]:
+    # explicit UTF-8: same zh-Windows reader-thread hazard as probes (a
+    # swallowed decode crash surfaces as stdout=None, see docker_df._run)
+    return subprocess.run(
+        cmd, capture_output=True, text=True,
+        encoding="utf-8", errors="replace", timeout=_TIMEOUT,
+    )
+
+
+def _cmd_action(
+    finding: Finding, dry_run: bool, run: _Runner, cmd: list[str], desc: str
+) -> ActionResult:
+    if dry_run:
+        return ActionResult(finding.key, True, f"[dry-run] would {desc}")
+    cp = run(cmd)
+    if cp.returncode == 0:
+        tail = (cp.stdout or "").strip().splitlines()
+        return ActionResult(finding.key, True, f"{desc}: {tail[-1]}" if tail else desc)
+    err = (cp.stderr or cp.stdout or "").strip().splitlines()
+    return ActionResult(
+        finding.key, False, f"{desc} failed (exit {cp.returncode}): {err[-1] if err else ''}"
+    )
+
+
+def _rmtree_action(finding: Finding, dry_run: bool) -> ActionResult:
+    if finding.path is None:
+        return ActionResult(finding.key, False, "no path on finding — cannot remove")
+    desc = f"delete {finding.path}"
+    if dry_run:
+        return ActionResult(finding.key, True, f"[dry-run] would {desc}")
+    shutil.rmtree(finding.path)
+    return ActionResult(finding.key, True, desc)
+
+
+# docker prunes: -f skips their interactive prompt; our TUI is the prompt.
+# 2026-10-08 incident: image prune -a / container prune are indiscriminate
+# ("unused"/"stopped" != unwanted — a user's persistent test bench was
+# pruned). Both docker rows are REPORT_ONLY now; only build cache (true
+# cache semantics) remains cleanable here.
+_DOCKER_ACTIONS = {
+    keys.DOCKER_BUILD_CACHE: (
+        ["docker", "builder", "prune", "-f"],
+        "docker builder prune -f",
+    ),
+}
+
+# what each clean actually does, in plain words — the confirm modal shows
+# these BEFORE anything runs (2026-10-08 lesson: item names alone don't warn).
+# Wording lives in cachekat.i18n (en source of truth, zh table).
+_CONSEQUENCE_KEYS = {
+    keys.PIP_CACHE: "cons_pip",
+    keys.NPM_CACHE: "cons_npm",
+    keys.DOCKER_BUILD_CACHE: "cons_build_cache",
+}
+
+
+def consequence(finding: Finding) -> str:
+    """One plain sentence about what cleaning this finding does."""
+    if finding.key.startswith(keys.DOCKER_CONTAINER_PREFIX):
+        return t("cons_container")
+    if finding.key in _CONSEQUENCE_KEYS:
+        return t(_CONSEQUENCE_KEYS[finding.key])
+    if finding.key.startswith(keys.PLAYWRIGHT_PREFIX):
+        return t("cons_playwright")
+    return t("cons_none")
+
+
+def clean(
+    finding: Finding, *, dry_run: bool = False, runner: _Runner | None = None
+) -> ActionResult:
+    run = runner if runner is not None else _run
+    if finding.risk is not Risk.CLEANABLE:
+        return ActionResult(finding.key, False, "refused: report-only is never cleaned")
+    if finding.key == keys.PIP_CACHE:
+        cmd = [sys.executable, "-m", "pip", "cache", "purge"]
+        return _cmd_action(finding, dry_run, run, cmd, "pip cache purge")
+    if finding.key == keys.NPM_CACHE:
+        return _rmtree_action(finding, dry_run)
+    if finding.key.startswith(keys.PLAYWRIGHT_PREFIX):
+        return _rmtree_action(finding, dry_run)
+    if finding.key.startswith(keys.DOCKER_CONTAINER_PREFIX):
+        # name derivation by documented prefix-strip (see cachekat/keys.py):
+        # docker names never contain "/", display text is never parsed
+        name = finding.key.removeprefix(keys.DOCKER_CONTAINER_PREFIX)
+        # no -f: a container that started since the scan refuses naturally,
+        # and docker rm never touches volumes
+        return _cmd_action(finding, dry_run, run, ["docker", "rm", name], f"docker rm {name}")
+    if finding.key in _DOCKER_ACTIONS:
+        cmd, desc = _DOCKER_ACTIONS[finding.key]
+        return _cmd_action(finding, dry_run, run, cmd, desc)
+    return ActionResult(finding.key, False, "no clean action implemented for this finding")

cachekat/cli.py

@@ -0,0 +1,89 @@
+"""CLI entry point: `cachekat scan` (read-only report) and `cachekat tui`.
+
+Language: every invocation resolves --lang (default auto: system locale,
+zh* -> zh, else en) and resets the i18n state — no cross-call leakage.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict
+
+from cachekat import probes  # noqa: F401  (probe registration by import)
+from cachekat.i18n import resolve_lang, set_lang, t
+from cachekat.models import Finding, Risk
+from cachekat.registry import run_scan
+
+
+def human_size(n: int) -> str:
+    steps = ("B", "KiB", "MiB", "GiB", "TiB")
+    size = float(n)
+    for unit in steps:
+        if size < 1024 or unit == steps[-1]:
+            return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
+        size /= 1024
+    return f"{size:.1f} TiB"  # pragma: no cover (loop always returns above)
+
+
+def format_table(findings: list[Finding]) -> str:
+    lines = [
+        t("scan_title"),
+        "=" * 64,
+    ]
+    for f in findings:
+        marker = "~" if f.risk is Risk.CLEANABLE else "!"
+        lines.append(
+            f"[{marker}] {f.label:<28} {human_size(f.size_bytes):>10}"
+            f"  {f.detail}"
+        )
+    lines.append("=" * 64)
+    reclaimable = sum(f.size_bytes for f in findings if f.risk is Risk.CLEANABLE)
+    lines.append(t("scan_summary", size=human_size(reclaimable)))
+    if any(f.risk is Risk.REPORT_ONLY for f in findings):
+        lines.append(t("scan_report_note"))
+    return "\n".join(lines)
+
+
+def to_json(findings: list[Finding]) -> str:
+    rows = [
+        asdict(f)
+        | {
+            "risk": f.risk.value,
+            "path": str(f.path) if f.path is not None else None,
+        }
+        for f in findings
+    ]
+    return json.dumps(rows, ensure_ascii=False, indent=2)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="cachekat",
+        description="See which dev caches eat your disk. Scans are read-only; "
+        "cleaning is always an explicit, confirmed choice.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    p_scan = sub.add_parser("scan", help="read-only scan and report")
+    p_scan.add_argument("--json", action="store_true", help="machine-readable output")
+    p_scan.add_argument("--lang", default="auto", choices=["auto", "en", "zh"])
+    p_tui = sub.add_parser("tui", help="interactive TUI (select, confirm, clean)")
+    p_tui.add_argument("--lang", default="auto", choices=["auto", "en", "zh"])
+    args = parser.parse_args(argv)
+
+    set_lang(resolve_lang(args.lang))
+
+    if args.command == "tui":
+        from cachekat.tui import run_app  # lazy: keeps scan light without textual
+
+        return run_app(lang=args.lang)
+
+    findings = run_scan()
+    if args.command == "scan":
+        print(to_json(findings) if args.json else format_table(findings))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cachekat/fsutil.py

@@ -0,0 +1,25 @@
+"""Filesystem helpers shared by probes (single implementation, no copies)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def dir_size_bytes(path: Path) -> int:
+    """Recursive on-disk size. Missing path -> 0.
+
+    Files that vanish or are locked mid-walk are skipped, so the result is a
+    LOWER BOUND. Known limitation, not hidden: for cache directories this
+    undershoot is tiny and harmless; revisit if a probe ever needs exactness.
+    """
+    if not path.exists():
+        return 0
+    total = 0
+    for root, _dirs, files in os.walk(path):
+        for name in files:
+            try:
+                total += (Path(root) / name).stat().st_size
+            except OSError:
+                continue  # raced-away or locked file (see docstring)
+    return total

cachekat/i18n.py

@@ -0,0 +1,265 @@
+"""Single home for every user-facing string (2026-10-08 design decision).
+
+Rules:
+- ALL UI copy goes through `t()` — hardcoded user-facing text is a review
+  blocker (see AGENTS.md conventions).
+- en is the source of truth; zh is a full table. A missing zh entry falls
+  back to en (never crashes the TUI); a missing KEY fails loudly.
+- Language is a process-wide choice set once at entry (CLI flag -> set_lang);
+  runtime hot-switching is deliberately out of scope until real users ask.
+"""
+
+from __future__ import annotations
+
+import locale
+import os
+import sys
+
+Lang = str  # "en" | "zh"
+
+_LANG: Lang = "en"  # safe default until an entry point resolves it
+
+_STRINGS: dict[str, dict[str, str]] = {
+    # --- TUI chrome -------------------------------------------------------
+    "banner_title": {
+        "en": "🐈 CacheKat — dev cache checkup",
+        "zh": "🐈 CacheKat — 开发缓存体检",
+    },
+    "col_item": {"en": "item", "zh": "项"},
+    "col_size": {"en": "size", "zh": "大小"},
+    "col_note": {"en": "note", "zh": "说明"},
+    "key_all": {"en": "select all", "zh": "全选"},
+    "key_none": {"en": "clear selection", "zh": "清空选择"},
+    "key_dry": {"en": "dry-run on/off", "zh": "干跑 开/关"},
+    "key_clean": {"en": "clean selected", "zh": "清理选中"},
+    "key_rescan": {"en": "rescan", "zh": "重新扫描"},
+    "key_quit": {"en": "quit", "zh": "退出"},
+    "left_label": {
+        "en": "cleanable (select with space, run with c)",
+        "zh": "可清理（勾选后 c 执行）",
+    },
+    "right_label": {
+        "en": "report-only (data / uncertain)",
+        "zh": "只报不动（数据/判不准）",
+    },
+    "log_label": {"en": "action log", "zh": "执行日志"},
+    "scanning": {"en": "scanning…", "zh": "扫描中…"},
+    "summary_line": {
+        "en": "reclaimable total {size} · selected {n} items ({sel}) · {dry}",
+        "zh": "可回收合计 {size} · 已选 {n} 项（{sel}）· {dry}",
+    },
+    "dry_on": {
+        "en": "dry-run ON (rehearse — nothing is deleted)",
+        "zh": "干跑 开（只演示，不删任何东西）",
+    },
+    "dry_off": {
+        "en": "dry-run OFF (clean executes for real)",
+        "zh": "干跑 关（c 执行即真删）",
+    },
+    "notify_busy": {"en": "scanning, wait a beat", "zh": "扫描中，稍等"},
+    "notify_none_selected": {
+        "en": "nothing selected — press space on a row",
+        "zh": "没勾任何可清项——space 勾选",
+    },
+    "confirm_dry": {"en": "dry-run", "zh": "干跑演示"},
+    "confirm_real": {"en": "DELETE", "zh": "真删"},
+    "confirm_title": {
+        "en": "{verb} {n} items, ~{size}:",
+        "zh": "{verb} {n} 项，约 {size}：",
+    },
+    "notify_cancelled": {
+        "en": "cancelled — nothing touched",
+        "zh": "已取消，什么都没动",
+    },
+    "notify_done": {"en": "{ok}/{n} done ({mode})", "zh": "{ok}/{n} 项完成（{mode}）"},
+    "mode_dry": {"en": "dry-run", "zh": "干跑"},
+    "mode_real": {"en": "executed", "zh": "已执行"},
+    "yes_button": {"en": "confirm [Y]", "zh": "确认 [Y]"},
+    "no_button": {"en": "cancel [Esc]", "zh": "取消 [Esc]"},
+    # --- scan CLI ----------------------------------------------------------
+    "scan_title": {
+        "en": "CacheKat scan (read-only — nothing is deleted)",
+        "zh": "CacheKat 扫描（只读——不删任何东西）",
+    },
+    "scan_report_note": {
+        "en": "[!] lines are report-only — CacheKat never cleans those",
+        "zh": "[!] 行为只报不动——CacheKat 永不清理它们",
+    },
+    "scan_summary": {
+        "en": "reclaimable (cache, re-download cost only): {size}",
+        "zh": "可回收（缓存，重下代价而已）：{size}",
+    },
+    "probe_failed_label": {
+        "en": "{probe} probe failed — full reason in the log below",
+        "zh": "{probe} 探针崩溃——完整原因见下方执行日志",
+    },
+    # --- actions.consequence ------------------------------------------------
+    "cons_pip": {
+        "en": "purge pip download cache — packages re-download on next install",
+        "zh": "清空 pip 下载缓存——下次装包重新下载",
+    },
+    "cons_npm": {
+        "en": "delete the npm cache directory — npm re-downloads on demand",
+        "zh": "删除 npm 缓存目录——用时重新下载",
+    },
+    "cons_build_cache": {
+        "en": "docker builder prune -f — removes ORPHANED build cache only "
+        "(in-use cache untouched); next build re-runs cold steps",
+        "zh": "docker builder prune -f——只删无主构建缓存（在用的不动）；"
+        "下次构建重跑冷步骤",
+    },
+    "cons_container": {
+        "en": "docker rm — deletes the CONTAINER ITSELF, not a cache; "
+        "recreate with docker run / compose up if needed. Volumes untouched",
+        "zh": "docker rm——删除的是容器本体（不是缓存）；需要时用 "
+        "docker run/compose 重建。卷不受影响",
+    },
+    "cons_playwright": {
+        "en": "delete this browser directory — `playwright install` "
+        "re-downloads if ever needed",
+        "zh": "删除该浏览器目录——需要时 `playwright install` 重下",
+    },
+    "cons_none": {
+        "en": "no clean action for this finding",
+        "zh": "此条目暂无可执行清理",
+    },
+    # --- docker probe -------------------------------------------------------
+    "dock_volumes_label": {"en": "docker volumes (data!)", "zh": "docker 卷（数据！）"},
+    "dock_volumes_detail": {
+        "en": "{n} volumes — CacheKat never cleans volumes",
+        "zh": "{n} 个卷——CacheKat 永不清理卷",
+    },
+    "dock_images_label": {
+        "en": "docker unused images (report-only)",
+        "zh": "docker 未用镜像（只报）",
+    },
+    "dock_images_detail": {
+        "en": "docker image prune -a would remove ALL unused images — "
+        "per-image selection pending; use `docker rmi` yourself meanwhile",
+        "zh": "docker image prune -a 会删掉全部未用镜像——逐镜像勾选待做；"
+        "需要清理请自己 `docker rmi` 挑着删",
+    },
+    "dock_build_label": {"en": "docker build cache", "zh": "docker 构建缓存"},
+    "dock_build_detail": {
+        "en": "build cache layers, per docker system df (builder prune keeps in-use cache)",
+        "zh": "构建缓存层，docker system df 口径（builder prune 保留在用缓存）",
+    },
+    "dock_container_label": {
+        "en": "container: {name} ({image})",
+        "zh": "容器：{name}（{image}）",
+    },
+    "dock_container_detail": {
+        "en": "{status} — docker rm deletes the CONTAINER ITSELF, not a "
+        "cache; recreate via docker run / compose up. Volumes are NOT touched",
+        "zh": "{status}——docker rm 删除的是容器本体而非缓存；可 docker "
+        "run/compose 重建。卷不受影响",
+    },
+    "dock_daemon_unreachable": {
+        "en": "docker CLI exists but exited {rc} — start Docker Desktop, "
+        "then press r in the TUI to rescan",
+        "zh": "docker CLI 存在但退出码 {rc}——启动 Docker Desktop 后在 "
+        "TUI 里按 r 重扫",
+    },
+    "dock_daemon_timeout": {
+        "en": "docker CLI exists but `docker system df` timed out",
+        "zh": "docker CLI 存在但 `docker system df` 超时",
+    },
+    "dock_ps_timeout": {
+        "en": "container listing timed out",
+        "zh": "容器列表获取超时",
+    },
+    "dock_ps_failed": {
+        "en": "exited {rc} — container listing unavailable",
+        "zh": "退出码 {rc}——容器列表不可用",
+    },
+    "dock_ps_timeout_label": {"en": "docker ps timed out", "zh": "docker ps 超时"},
+    "dock_ps_failed_label": {"en": "docker ps failed", "zh": "docker ps 失败"},
+    "dock_daemon_label": {
+        "en": "docker daemon unreachable",
+        "zh": "docker 守护进程连不上",
+    },
+    "dock_daemon_timeout_label": {
+        "en": "docker daemon timed out",
+        "zh": "docker 守护进程超时",
+    },
+    # --- playwright probe ----------------------------------------------------
+    "pw_orphan_label": {
+        "en": "playwright {name} (orphan)",
+        "zh": "playwright {name}（孤儿）",
+    },
+    "pw_inuse_label": {"en": "playwright {name}", "zh": "playwright {name}"},
+    "pw_orphan_detail": {
+        "en": "not referenced by installed playwright",
+        "zh": "未被当前 playwright 引用",
+    },
+    "pw_unknown_label": {
+        "en": "playwright browsers (liveness unknown)",
+        "zh": "playwright 浏览器（活性未知）",
+    },
+    "pw_unknown_detail": {
+        "en": "{path} — playwright package not importable here, cannot tell "
+        "orphans from in-use",
+        "zh": "{path}——此环境 import 不到 playwright 包，判不了哪些在用",
+    },
+}
+
+
+def _windows_prefers_zh() -> bool:
+    """Ask Windows directly: GetUserDefaultUILanguage LANGID, primary
+    language 0x04 = Chinese (2026-10-08 real-world bug: cmd sets no LANG and
+    locale.getlocale() returns (None, None) — auto never resolved zh)."""
+    if sys.platform != "win32":
+        return False
+    try:
+        import ctypes
+
+        lang_id = ctypes.windll.kernel32.GetUserDefaultUILanguage()
+        return (lang_id & 0x3FF) == 0x04
+    except Exception:  # noqa: BLE001 — detection must never crash the app
+        return False
+
+
+def _system_prefers_zh() -> bool:
+    """Env vars first (POSIX semantics: first set var wins), then the OS
+    native call on Windows, locale last. getdefaultlocale is NOT used:
+    deprecated, removed in 3.15."""
+    for var in ("LC_ALL", "LC_MESSAGES", "LANG", "LANGUAGE"):
+        val = os.environ.get(var, "")
+        if val:
+            return val.lower().startswith("zh")
+    if sys.platform == "win32":
+        return _windows_prefers_zh()
+    try:
+        loc = locale.getlocale()[0] or ""
+    except ValueError:
+        loc = ""
+    return loc.lower().startswith("zh")
+
+
+def resolve_lang(spec: str) -> Lang:
+    """'auto' follows the system preference (zh* -> zh, else en)."""
+    if spec in ("en", "zh"):
+        return spec
+    return "zh" if _system_prefers_zh() else "en"
+
+
+def set_lang(lang: Lang) -> None:
+    global _LANG
+    if lang not in ("en", "zh"):
+        msg = f"unknown lang {lang!r}"
+        raise ValueError(msg)
+    _LANG = lang
+
+
+def current_lang() -> Lang:
+    return _LANG
+
+
+def t(key: str, **fmt: object) -> str:
+    """Translate `key` in the active language. Missing zh -> en fallback."""
+    entry = _STRINGS.get(key)
+    if entry is None:
+        msg = f"missing i18n key {key!r}"
+        raise KeyError(msg)
+    text = entry.get(_LANG) or entry["en"]
+    return text.format(**fmt) if fmt else text

cachekat/keys.py

@@ -0,0 +1,22 @@
+"""Finding-key contract — the single source of every key string.
+
+Probes emit these keys; actions dispatch on them; the TUI passes them as
+selection values. src code MUST use these constants — no fresh literals.
+Tests intentionally pin the literal strings (contract tests: if a key ever
+changes, tests fail loudly rather than silently following the constant).
+"""
+
+from __future__ import annotations
+
+PIP_CACHE = "pip/cache"
+NPM_CACHE = "npm/cache"
+
+PLAYWRIGHT_PREFIX = "playwright/"
+PLAYWRIGHT_BROWSERS = "playwright/browsers"
+
+DOCKER_VOLUMES = "docker/volumes"
+DOCKER_IMAGES = "docker/images-reclaimable"
+DOCKER_BUILD_CACHE = "docker/build-cache"
+DOCKER_CONTAINER_PREFIX = "docker/container/"
+DOCKER_DAEMON = "docker/daemon"
+DOCKER_PS_ERROR = "docker/ps-error"

cachekat/models.py

@@ -0,0 +1,39 @@
+"""Core data shapes — explicit types at every boundary, no magic strings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, unique
+from pathlib import Path
+
+
+@unique
+class Risk(str, Enum):
+    """What a finding is allowed to become.
+
+    CLEANABLE: cache/junk — deleting it only costs a later re-download.
+    REPORT_ONLY: valuable or risky (data volumes, vhdx) — show, never clean.
+    """
+
+    CLEANABLE = "cleanable"
+    REPORT_ONLY = "report-only"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One scan result. Immutable; the report layer renders, probes fill.
+
+    path: the on-disk location this finding measures, when there is one
+    (docker rows are CLI-level facts, not paths). Actions consume it —
+    parsing paths back out of `detail` (display text) is forbidden.
+    """
+
+    key: str  # stable id from cachekat.keys — the wire contract
+    label: str  # human name, e.g. "pip download cache"
+    size_bytes: int  # 0 when unknown/absent — never negative
+    detail: str  # path or explanation shown to the user
+    risk: Risk
+    path: Path | None = None
+    # registry sets this when a probe CRASHED (finding = the crash report):
+    # explicit flag at the boundary, no key-string sniffing downstream
+    is_error: bool = False

cachekat/probes/__init__.py

@@ -0,0 +1,5 @@
+"""Probes: one module per cache family. Import side effect = registration."""
+
+from cachekat.probes import docker_df, npm_cache, pip_cache, playwright_cache
+
+__all__ = ["docker_df", "npm_cache", "pip_cache", "playwright_cache"]