cachekat 0.4.8__py3-none-any.whl

cachekat/tui.py

@@ -0,0 +1,322 @@
+"""Textual TUI: scan -> select -> confirm -> clean (dry-run switchable).
+
+Logic spine (deliberately boring and hard to misuse):
+- left panel: CLEANABLE findings, selectable (space); right panel: REPORT_ONLY,
+  visible but untouchable — the layout itself teaches the safety model.
+- `c` opens a confirm modal listing exactly what will run; nothing cleans
+  without an explicit yes.
+- `d` toggles dry-run: actions describe what they WOULD do, disk untouched.
+- clean runs in a worker thread; results land in the log panel, honestly
+  (failures included — never swallowed).
+
+All UI copy goes through cachekat.i18n.t — no hardcoded user-facing text.
+Language is set once at construction (CLI --lang, default auto by locale).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from rich.markup import escape
+from rich.text import Text
+from textual import work
+from textual.app import App, ComposeResult
+from textual.binding import Binding, BindingsMap
+from textual.containers import Horizontal, Vertical
+from textual.screen import ModalScreen
+from textual.widgets import (
+    Button,
+    DataTable,
+    Footer,
+    RichLog,
+    SelectionList,
+    Static,
+)
+
+from cachekat.actions import ActionResult, clean, consequence
+from cachekat.cli import human_size
+from cachekat.i18n import resolve_lang, set_lang, t
+from cachekat.models import Finding, Risk
+from cachekat.registry import run_scan
+
+FindingsFn = Callable[[], list[Finding]]
+
+
+def _fit_row(label: str, size: str, width: int) -> Text:
+    """One selection-list row: `~ label  size`, measured in display cells.
+
+    Long labels ellipsize; the size column stays visible — a row without its
+    price tag is a lie (2026-10-09 user report: container rows overran the
+    left panel edge). Full label still shows in the confirm modal."""
+    marker = Text("~ ", style="green")
+    size_txt = Text(size, style="dim")
+    # fudge: toggle button + gutter + trailing padding (~6 cells)
+    budget = width - size_txt.cell_len - marker.cell_len - 6
+    label_txt = Text(label)
+    if budget > 4 and label_txt.cell_len > budget:
+        label_txt.truncate(budget, overflow="ellipsis")
+    return Text.assemble(marker, label_txt, Text("  "), size_txt)
+
+
+class ConfirmModal(ModalScreen[bool]):
+    """The one gate between selection and deletion."""
+
+    BINDINGS = [
+        Binding("y,enter", "confirm", "confirm", show=False),
+        Binding("escape,n", "cancel", "cancel", show=False),
+    ]
+
+    def __init__(self, message: str) -> None:
+        super().__init__()
+        self._message = message
+
+    def compose(self) -> ComposeResult:
+        with Vertical(classes="dialog"):
+            yield Static(self._message, classes="msg")
+            with Horizontal(classes="buttons"):
+                yield Button(t("yes_button"), id="yes", variant="error")
+                yield Button(t("no_button"), id="no", variant="default")
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        self.dismiss(event.button.id == "yes")
+
+    def action_confirm(self) -> None:
+        self.dismiss(True)
+
+    def action_cancel(self) -> None:
+        self.dismiss(False)
+
+
+class CacheKatApp(App[None]):
+    TITLE = "CacheKat"
+
+    CSS = """
+    Screen { layout: vertical; }
+
+    #banner {
+        dock: top; height: 1; padding: 0 2;
+        background: $accent 20%; text-style: bold;
+    }
+    #summary {
+        dock: top; height: 3; padding: 0 2;
+        border: round $accent; content-align: center middle;
+        background: $surface;
+    }
+    #body { height: 1fr; }
+    #left, #right { width: 1fr; height: 1fr; padding: 0 1; }
+    #left { border: round $success; }
+    #right { border: round $error 60%; }
+    #left-label, #right-label, #log-label { text-style: bold; padding: 0 1; }
+    #cleanable { border: none; background: transparent; height: 1fr; }
+    #report { border: none; height: 1fr; }
+    #log { height: 10; border: round $panel; padding: 0 1; }
+    ConfirmModal { align: center middle; }
+    .dialog {
+        width: 78; height: auto; max-width: 95%;
+        border: thick $accent; background: $surface; padding: 1 2;
+    }
+    .dialog .msg { padding: 0 1; margin-bottom: 1; }
+    .dialog .buttons { height: auto; align-horizontal: center; }
+    .dialog Button { margin: 0 2; }
+    """
+
+    BINDINGS = [
+        Binding("a", "all", "all"),
+        Binding("n", "none", "none"),
+        Binding("d", "dry", "dry-run"),
+        Binding("c", "clean", "clean"),
+        Binding("r", "rescan", "rescan"),
+        Binding("q", "quit", "quit"),
+    ]
+
+    def __init__(
+        self, findings_provider: FindingsFn | None = None, lang: str = "auto"
+    ) -> None:
+        set_lang(resolve_lang(lang))  # language FIRST (it feeds compose())
+        super().__init__()
+        # Localize the footer bindings. Class BINDINGS are merged and baked
+        # at class-creation time (__init_subclass__), so swapping the class
+        # attribute does nothing (2026-10-08 real-world miss). The instance
+        # _bindings map is OUR copy — REBUILD it from the current one,
+        # preserving every built-in (ctrl+p palette, ctrl+q quit, ...) and
+        # only replacing our six descriptions.
+        override = {
+            "all": t("key_all"),
+            "none": t("key_none"),
+            "dry": t("key_dry"),
+            "clean": t("key_clean"),
+            "rescan": t("key_rescan"),
+            "quit": t("key_quit"),
+        }
+        rebuilt = BindingsMap()
+        for key, b in self._bindings:
+            desc = override.get(b.action, b.description)
+            rebuilt.bind(
+                key, b.action, desc, show=b.show, key_display=b.key_display,
+                priority=b.priority,
+            )
+        self._bindings = rebuilt
+        self._provider = findings_provider or run_scan
+        self._findings: list[Finding] = []
+        self._pending: list[Finding] = []
+        self._dry = False
+        self._busy = False
+        self._results: list[ActionResult] = []
+
+    def compose(self) -> ComposeResult:
+        yield Static(t("banner_title"), id="banner")
+        yield Static(t("scanning"), id="summary")
+        with Horizontal(id="body"):
+            with Vertical(id="left"):
+                yield Static(t("left_label"), id="left-label")
+                yield SelectionList(id="cleanable")
+            with Vertical(id="right"):
+                yield Static(t("right_label"), id="right-label")
+                yield DataTable(id="report")
+        yield Static(t("log_label"), id="log-label")
+        yield RichLog(id="log", markup=True)
+        # the real Footer (restored 2026-10-08, second attempt): clickable
+        # bindings + built-in command palette button (^p) — the Static keybar
+        # placeholder could not do either
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.query_one("#report", DataTable).add_columns(
+            t("col_item"), t("col_size"), t("col_note")
+        )
+        self._kick_scan()
+
+    # --- scanning -----------------------------------------------------------
+
+    def _kick_scan(self) -> None:
+        self._busy = True
+        self._render_summary(t("scanning"))
+        self._scan_worker()
+
+    @work(thread=True, exclusive=True)
+    def _scan_worker(self) -> None:
+        findings = self._provider()
+        self.call_from_thread(self._render, findings)
+
+    def _render(self, findings: list[Finding]) -> None:
+        self._findings = findings
+        self._busy = False
+        sel = self.query_one("#cleanable", SelectionList)
+        sel.clear_options()
+        panel_w = sel.size.width or 60  # 0 before first layout — sane fallback
+        for f in findings:
+            if f.risk is Risk.CLEANABLE:
+                sel.add_option(
+                    (_fit_row(f.label, human_size(f.size_bytes), panel_w), f.key)
+                )
+        table = self.query_one("#report", DataTable)
+        table.clear()
+        for f in findings:
+            if f.risk is Risk.REPORT_ONLY:
+                table.add_row(f.label, human_size(f.size_bytes), f.detail, key=f.key)
+        # probe crash reports ALSO land in the log panel: the table's note
+        # column truncates ("AttributeErro"…), the log shows the whole line
+        # with the raise site (2026-10-09 Windows case)
+        log = self.query_one("#log", RichLog)
+        for f in findings:
+            if f.is_error:
+                log.write(f"[red]✘[/red] {escape(f.label)}\n    {escape(f.detail)}")
+        self._render_summary()
+
+    def _render_summary(self, extra: str = "") -> None:
+        total = sum(f.size_bytes for f in self._findings if f.risk is Risk.CLEANABLE)
+        selected = self._selected_keys()
+        chosen = sum(
+            f.size_bytes for f in self._findings if f.risk is Risk.CLEANABLE and f.key in selected
+        )
+        dry = t("dry_on") if self._dry else t("dry_off")
+        text = t(
+            "summary_line",
+            size=f"[b]{human_size(total)}[/b]",
+            n=len(selected),
+            sel=human_size(chosen),
+            dry=dry,
+        )
+        if extra:
+            text += f"\n{extra}"
+        self.query_one("#summary", Static).update(text)
+
+    def _selected_keys(self) -> list[str]:
+        # no blanket except here (audit 2026-10-08): a failing query means a
+        # real bug (widget missing) and must crash loudly, not silently
+        # behave as "nothing selected"
+        sel = self.query_one("#cleanable", SelectionList).selected
+        return [str(v) for v in sel]
+
+    # --- bindings -----------------------------------------------------------
+
+    def action_all(self) -> None:
+        self.query_one("#cleanable", SelectionList).select_all()
+        self._render_summary()
+
+    def action_none(self) -> None:
+        self.query_one("#cleanable", SelectionList).deselect_all()
+        self._render_summary()
+
+    def action_dry(self) -> None:
+        self._dry = not self._dry
+        self._render_summary()
+
+    def action_rescan(self) -> None:
+        self._kick_scan()
+
+    def action_clean(self) -> None:
+        if self._busy:
+            self.notify(t("notify_busy"), severity="warning")
+            return
+        chosen = [
+            f
+            for f in self._findings
+            if f.risk is Risk.CLEANABLE and f.key in self._selected_keys()
+        ]
+        if not chosen:
+            self.notify(t("notify_none_selected"), severity="information")
+            return
+        size = human_size(sum(f.size_bytes for f in chosen))
+        verb = t("confirm_dry") if self._dry else t("confirm_real")
+        # 2026-10-08 lesson: item names alone don't warn — every line carries
+        # a plain-words consequence from actions.consequence()
+        lines = "\n".join(
+            f"~ {f.label}（{human_size(f.size_bytes)}）\n    ↳ {consequence(f)}"
+            for f in chosen
+        )
+        self.push_screen(
+            ConfirmModal(t("confirm_title", verb=verb, n=len(chosen), size=size) + "\n" + lines),
+            callback=self._on_confirm,
+        )
+        self._pending = chosen  # stash for the callback
+
+    def _on_confirm(self, ok: bool) -> None:
+        chosen = self._pending
+        if not ok:
+            self.notify(t("notify_cancelled"))
+            return
+        self._busy = True
+        self._clean_worker(chosen)
+
+    @work(thread=True, exclusive=True)
+    def _clean_worker(self, chosen: list[Finding]) -> None:
+        results = [clean(f, dry_run=self._dry) for f in chosen]
+        self.call_from_thread(self._show_results, results)
+
+    def _show_results(self, results: list[ActionResult]) -> None:
+        self._results = results
+        self._busy = False
+        log = self.query_one("#log", RichLog)
+        for r in results:
+            mark = "✔" if r.ok else "✘"
+            style = "" if r.ok else "[red]"
+            log.write(f"{style}{mark} {escape(r.key)} — {escape(r.detail)}")
+        ok_n = sum(1 for r in results if r.ok)
+        mode = t("mode_dry") if self._dry else t("mode_real")
+        self.notify(t("notify_done", ok=ok_n, n=len(results), mode=mode))
+
+
+def run_app(lang: str = "auto") -> int:
+    CacheKatApp(lang=lang).run()
+    return 0

cachekat-0.4.8.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,20 @@
+cachekat/__init__.py,sha256=Pwr6EdMnerwT7K0woEmfwTXKTGvtNIU64KmpI_wreRw,100
+cachekat/actions.py,sha256=AbfFOZ2yKucAO493NaGhaVD_JI6xu8gwGTHF7YjETi4,4864
+cachekat/cli.py,sha256=AVCEuWwcSN8iZR5czM9V1YavN-xamD5lnvD4iIplVMo,2953
+cachekat/fsutil.py,sha256=KzcDaxrN9oJw4bstiooGRL3TwuVE9xsE1SOFYXd3KqE,800
+cachekat/i18n.py,sha256=l4n-T-FNSCF3noehdijevXmg7zQ7eCteF7CXJ13j3Ic,10768
+cachekat/keys.py,sha256=AVUFCSelqBBRxjVSybynQWTa37xI2oOP8tJafH4R9Oo,767
+cachekat/models.py,sha256=Gaox3ltWDhVMv5BLhejLGOF14bwBsYHkEaC6kwylzAc,1305
+cachekat/registry.py,sha256=-2FIrGclNQzSafTF-E3Rmz3UEh8i4eptbpRhhzE9Mnk,2234
+cachekat/tui.py,sha256=83QxW725_2MQ2sNjEhMD2NXTCK85MxQMsHbnF5aZcS0,12145
+cachekat/probes/__init__.py,sha256=_DQiJ3_xdO_hvMAioWduzygOAAfJnATm0sqovOO-I20,228
+cachekat/probes/docker_df.py,sha256=DePG4thANtTc9FECoJ07IZhCedYo14BlsgIedzXeOms,7997
+cachekat/probes/npm_cache.py,sha256=mOM5mTirLruqi4DaYFS5H03xEMheJZUI97naOO4Eggk,2229
+cachekat/probes/pip_cache.py,sha256=2CFwsSBHmLS-huegcvAn7E2O5V7zHwrJOREQC2wAuKQ,1226
+cachekat/probes/playwright_cache.py,sha256=sUKD05LIc90s-3C6Lt1ZzJEVN1BjBXvtseDohFwwSgw,3761
+cachekat-0.4.8.dist-info/licenses/LICENSE,sha256=mY5mV9J0Ysc8Qc6PFi8KuvpKu5XgGp6T9OvzMM-bLF4,1064
+cachekat-0.4.8.dist-info/METADATA,sha256=1IHZGzms-MeFTE9aKxavsfATw3ywOQf373lRjF3wGhA,4543
+cachekat-0.4.8.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+cachekat-0.4.8.dist-info/entry_points.txt,sha256=E8TaivLjN9g-Kug1hCr8G_zi0EdJw7iEQ9ZnyDC4_bY,47
+cachekat-0.4.8.dist-info/top_level.txt,sha256=qkuCASxowPhCLiR_4sG0A7MZB_i6c_ZLxPLlYYsfaCU,9
+cachekat-0.4.8.dist-info/RECORD,,

cachekat-0.4.8.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cachekat-0.4.8.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cachekat = cachekat.cli:main

cachekat-0.4.8.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+cachekat