cachekat 0.4.8__tar.gz

cachekat-0.4.8/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aeluris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cachekat-0.4.8/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: cachekat
+Version: 0.4.8
+Summary: A TUI to see which dev caches eat your disk - and reclaim space safely, risk-graded.
+License: MIT
+Project-URL: Homepage, https://github.com/Aeluris/CacheKat
+Project-URL: Issues, https://github.com/Aeluris/CacheKat/issues
+Project-URL: Changelog, https://github.com/Aeluris/CacheKat/blob/main/CHANGELOG.md
+Keywords: cache,disk-space,tui,docker,textual,cleanup
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# CacheKat 🐈
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+> A TUI to see which dev caches eat your disk — and reclaim space safely,
+> risk-graded. **Never touches your data.**
+
+**Main view** — cleanable items on the left (select with space, run with `c`);
+report-only facts on the right (docker volumes, unknown liveness) are visible
+but untouchable — the layout itself teaches the safety model:
+
+![main view](docs/screenshots/en-main.png)
+
+**Confirm gate** — nothing cleans without an explicit yes; each item carries
+its size and a plain-words consequence, and dry-run (`d`) describes what
+would happen without touching the disk:
+
+![confirm modal](docs/screenshots/en-confirm.png)
+
+[![ci](https://github.com/Aeluris/CacheKat/actions/workflows/ci.yml/badge.svg)](https://github.com/Aeluris/CacheKat/actions/workflows/ci.yml)
+[![python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## Why
+
+Every developer machine accumulates caches that nobody watches: pip wheels,
+npm tarballs, playwright browsers (old versions pile up per release), docker
+build cache, dangling images, stopped containers... A fresh scan answers the
+only question that matters: **who is eating the disk, and what is actually
+safe to reclaim?**
+
+## Safety model (the feature)
+
+| Category | Behavior |
+|---|---|
+| True caches (pip, npm, playwright orphans, docker build cache) | Selectable — each row states its plain-words consequence before anything runs |
+| **Docker volumes (your data)** | **Report-only. Never cleaned. No flag unlocks this.** |
+| Docker stopped containers / unused images | Containers: cleanable **one by one**, each warning that `docker rm` deletes the container **itself** (recreate via `docker run`/`compose up`; volumes untouched). Images: report-only until per-image selection ships. |
+| Anything the probe cannot judge | Honest report-only ("liveness unknown"), never a guess |
+
+- Every scan is read-only; cleaning is an explicit, confirmed selection.
+- Dry-run mode (`d`): rehearse exactly what would happen — disk untouched.
+- Probes that fail surface as visible error rows, never swallowed.
+
+## Install
+
+```
+pipx install cachekat
+```
+
+Or from source: `pipx install git+https://github.com/Aeluris/CacheKat.git`
+
+## Use
+
+```
+cachekat tui             # interactive: scan -> select -> confirm -> clean
+cachekat scan            # read-only report: who eats the disk
+cachekat scan --json     # machine-readable
+# every command accepts --lang auto|en|zh (auto follows the system language)
+```
+
+Docker rows need the docker daemon running — if the TUI shows
+`docker daemon unreachable`, start Docker Desktop and press `r` to rescan.
+
+## Roadmap
+
+- [x] M0 — skeleton, registry, `scan` CLI, pip probe, CI (win+linux)
+- [x] M1 — docker / npm / playwright probes (orphan detection, volumes red-lined)
+- [x] M2 — textual TUI: select, confirm, clean, dry-run
+- [x] Per-container selection with loud not-a-cache warnings
+- [x] i18n: full en/zh, `--lang auto|en|zh`
+- [ ] per-image selection, more cache families (cargo, gradle, ...)
+
+See [CHANGELOG.md](CHANGELOG.md) for details, [CONTRIBUTING.md](CONTRIBUTING.md)
+to help, [AGENTS.md](AGENTS.md) for the engineering rulebook.
+
+## License
+
+[MIT](LICENSE) — © 2026 Aeluris

cachekat-0.4.8/README.md

@@ -0,0 +1,79 @@
+# CacheKat 🐈
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+> A TUI to see which dev caches eat your disk — and reclaim space safely,
+> risk-graded. **Never touches your data.**
+
+**Main view** — cleanable items on the left (select with space, run with `c`);
+report-only facts on the right (docker volumes, unknown liveness) are visible
+but untouchable — the layout itself teaches the safety model:
+
+![main view](docs/screenshots/en-main.png)
+
+**Confirm gate** — nothing cleans without an explicit yes; each item carries
+its size and a plain-words consequence, and dry-run (`d`) describes what
+would happen without touching the disk:
+
+![confirm modal](docs/screenshots/en-confirm.png)
+
+[![ci](https://github.com/Aeluris/CacheKat/actions/workflows/ci.yml/badge.svg)](https://github.com/Aeluris/CacheKat/actions/workflows/ci.yml)
+[![python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## Why
+
+Every developer machine accumulates caches that nobody watches: pip wheels,
+npm tarballs, playwright browsers (old versions pile up per release), docker
+build cache, dangling images, stopped containers... A fresh scan answers the
+only question that matters: **who is eating the disk, and what is actually
+safe to reclaim?**
+
+## Safety model (the feature)
+
+| Category | Behavior |
+|---|---|
+| True caches (pip, npm, playwright orphans, docker build cache) | Selectable — each row states its plain-words consequence before anything runs |
+| **Docker volumes (your data)** | **Report-only. Never cleaned. No flag unlocks this.** |
+| Docker stopped containers / unused images | Containers: cleanable **one by one**, each warning that `docker rm` deletes the container **itself** (recreate via `docker run`/`compose up`; volumes untouched). Images: report-only until per-image selection ships. |
+| Anything the probe cannot judge | Honest report-only ("liveness unknown"), never a guess |
+
+- Every scan is read-only; cleaning is an explicit, confirmed selection.
+- Dry-run mode (`d`): rehearse exactly what would happen — disk untouched.
+- Probes that fail surface as visible error rows, never swallowed.
+
+## Install
+
+```
+pipx install cachekat
+```
+
+Or from source: `pipx install git+https://github.com/Aeluris/CacheKat.git`
+
+## Use
+
+```
+cachekat tui             # interactive: scan -> select -> confirm -> clean
+cachekat scan            # read-only report: who eats the disk
+cachekat scan --json     # machine-readable
+# every command accepts --lang auto|en|zh (auto follows the system language)
+```
+
+Docker rows need the docker daemon running — if the TUI shows
+`docker daemon unreachable`, start Docker Desktop and press `r` to rescan.
+
+## Roadmap
+
+- [x] M0 — skeleton, registry, `scan` CLI, pip probe, CI (win+linux)
+- [x] M1 — docker / npm / playwright probes (orphan detection, volumes red-lined)
+- [x] M2 — textual TUI: select, confirm, clean, dry-run
+- [x] Per-container selection with loud not-a-cache warnings
+- [x] i18n: full en/zh, `--lang auto|en|zh`
+- [ ] per-image selection, more cache families (cargo, gradle, ...)
+
+See [CHANGELOG.md](CHANGELOG.md) for details, [CONTRIBUTING.md](CONTRIBUTING.md)
+to help, [AGENTS.md](AGENTS.md) for the engineering rulebook.
+
+## License
+
+[MIT](LICENSE) — © 2026 Aeluris

cachekat-0.4.8/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cachekat"
+version = "0.4.8"
+description = "A TUI to see which dev caches eat your disk - and reclaim space safely, risk-graded."
+readme = "README.md"
+requires-python = ">=3.10"
+# textual is the single runtime dependency; everything else stdlib
+dependencies = ["textual>=1.0"]
+license = {text = "MIT"}
+keywords = ["cache", "disk-space", "tui", "docker", "textual", "cleanup"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Filesystems",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/Aeluris/CacheKat"
+Issues = "https://github.com/Aeluris/CacheKat/issues"
+Changelog = "https://github.com/Aeluris/CacheKat/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+cachekat = "cachekat.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]

cachekat-0.4.8/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cachekat-0.4.8/src/cachekat/__init__.py

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

cachekat-0.4.8/src/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-0.4.8/src/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-0.4.8/src/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