bloatr 0.1.0__py3-none-any.whl

bloatr/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

bloatr/__main__.py

@@ -0,0 +1,3 @@
+from bloatr.cli import main
+
+main()

bloatr/app.py

@@ -0,0 +1,509 @@
+"""Textual TUI for bloatr."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import ClassVar
+
+from textual import work
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Vertical
+from textual.screen import ModalScreen
+from textual.widgets import DataTable, Footer, Header, Label, ProgressBar, Static
+
+from bloatr.cleaner import delete_with_progress
+from bloatr.models import Item
+from bloatr.scanner import list_children, scan_locations
+from bloatr.sizes import format_size
+
+
+# ========================================================================= #
+# Confirmation modal
+# ========================================================================= #
+
+
+class ConfirmScreen(ModalScreen[bool]):
+    """Modal 'are you sure?' prompt shown before any deletion runs."""
+
+    DEFAULT_CSS = """
+    ConfirmScreen {
+        align: center middle;
+    }
+    #confirm-dialog {
+        padding: 2 4;
+        background: $surface;
+        border: tall $warning;
+        width: 70;
+        height: auto;
+    }
+    #confirm-question {
+        text-align: center;
+        margin-bottom: 1;
+        text-style: bold;
+    }
+    #confirm-hint {
+        text-align: center;
+        color: $text-muted;
+    }
+    """
+
+    BINDINGS: ClassVar = [
+        Binding("y", "confirm", "Yes"),
+        Binding("n,escape", "cancel", "No"),
+    ]
+
+    def __init__(self, total_size: int, count: int, dry_run: bool) -> None:
+        super().__init__()
+        self._total_size = total_size
+        self._count = count
+        self._dry_run = dry_run
+
+    def compose(self) -> ComposeResult:
+        prefix = "DRY RUN — would delete" if self._dry_run else "Delete"
+        with Vertical(id="confirm-dialog"):
+            yield Static(
+                f"{prefix} {self._count} item(s)  ({format_size(self._total_size)})?",
+                id="confirm-question",
+            )
+            yield Static(
+                "Press  Y  to confirm,  N  or  ESC  to cancel",
+                id="confirm-hint",
+            )
+
+    def action_confirm(self) -> None:
+        self.dismiss(True)
+
+    def action_cancel(self) -> None:
+        self.dismiss(False)
+
+
+# ========================================================================= #
+# Progress modal — live deletion progress
+# ========================================================================= #
+
+
+class ProgressResult:
+    """Result object dismissed from :class:`ProgressScreen`."""
+
+    def __init__(
+        self,
+        freed: int,
+        errors: list[tuple[Item, str]],
+        done_paths: set[Path],
+    ) -> None:
+        self.freed = freed
+        self.errors = errors
+        self.done_paths = done_paths
+
+
+class ProgressScreen(ModalScreen[ProgressResult]):
+    """Modal that streams live deletion progress and runs the worker."""
+
+    DEFAULT_CSS = """
+    ProgressScreen {
+        align: center middle;
+    }
+    #progress-dialog {
+        padding: 2 4;
+        background: $surface;
+        border: tall $primary;
+        width: 90;
+        height: auto;
+    }
+    #progress-title {
+        text-align: center;
+        text-style: bold;
+        margin-bottom: 1;
+    }
+    #progress-current {
+        color: $text-muted;
+        margin-bottom: 1;
+        width: 100%;
+    }
+    #progress-bar {
+        margin-bottom: 1;
+    }
+    #progress-stats {
+        text-align: center;
+        color: $text;
+    }
+    """
+
+    BINDINGS: ClassVar = []  # no keys — user waits for worker
+
+    def __init__(self, items: list[Item], dry_run: bool) -> None:
+        super().__init__()
+        self._items = items
+        self._dry_run = dry_run
+        self._total_bytes = max(sum(max(i.size, 0) for i in items), 1)
+        self._freed = 0
+        self._errors: list[tuple[Item, str]] = []
+        self._done_paths: set[Path] = set()
+
+    def compose(self) -> ComposeResult:
+        title = "DRY RUN — simulating deletion" if self._dry_run else "Deleting"
+        with Vertical(id="progress-dialog"):
+            yield Static(title, id="progress-title")
+            yield Static(
+                f"[1/{len(self._items)}] preparing…",
+                id="progress-current",
+            )
+            yield ProgressBar(
+                total=self._total_bytes,
+                show_eta=False,
+                show_percentage=True,
+                id="progress-bar",
+            )
+            yield Static(
+                f"0 B / {format_size(self._total_bytes)}",
+                id="progress-stats",
+            )
+
+    def on_mount(self) -> None:
+        self._run_worker()
+
+    # ------------------------------------------------------------------ #
+    # Worker — runs in a background thread
+    # ------------------------------------------------------------------ #
+
+    @work(thread=True, exclusive=True)
+    def _run_worker(self) -> None:
+        # Throttle UI updates: batch byte deltas and push at ~12 fps.
+        state = {"pending_bytes": 0, "last_push": 0.0}
+        UPDATE_INTERVAL = 0.08  # seconds
+
+        def flush_progress() -> None:
+            if state["pending_bytes"] > 0:
+                delta = state["pending_bytes"]
+                state["pending_bytes"] = 0
+                state["last_push"] = time.monotonic()
+                self.app.call_from_thread(self._add_progress, delta)
+
+        for idx, item in enumerate(self._items):
+            # Flush previous item's leftover bytes first.
+            flush_progress()
+
+            # Update "current item" line in the UI.
+            self.app.call_from_thread(self._set_current, idx, item)
+
+            def on_progress(delta: int, _path: str) -> None:
+                state["pending_bytes"] += delta
+                now = time.monotonic()
+                if now - state["last_push"] >= UPDATE_INTERVAL:
+                    pending = state["pending_bytes"]
+                    state["pending_bytes"] = 0
+                    state["last_push"] = now
+                    self.app.call_from_thread(self._add_progress, pending)
+
+            try:
+                _, error = delete_with_progress(
+                    item,
+                    on_progress=on_progress,
+                    dry_run=self._dry_run,
+                )
+                if error:
+                    self._errors.append((item, error))
+                else:
+                    self._done_paths.add(item.path)
+            except Exception as exc:
+                self._errors.append((item, str(exc)))
+
+        # Final flush.
+        flush_progress()
+        self.app.call_from_thread(self._finish)
+
+    # ------------------------------------------------------------------ #
+    # UI update methods — always called from the main thread
+    # ------------------------------------------------------------------ #
+
+    def _set_current(self, idx: int, item: Item) -> None:
+        current = self.query_one("#progress-current", Static)
+        current.update(f"[{idx + 1}/{len(self._items)}]  {item.display}")
+
+    def _add_progress(self, delta: int) -> None:
+        self._freed += delta
+        capped = min(self._freed, self._total_bytes)
+        bar = self.query_one("#progress-bar", ProgressBar)
+        bar.update(progress=capped)
+        stats = self.query_one("#progress-stats", Static)
+        stats.update(
+            f"{format_size(self._freed)} / {format_size(self._total_bytes)}"
+        )
+
+    def _finish(self) -> None:
+        self.dismiss(
+            ProgressResult(
+                freed=self._freed,
+                errors=self._errors,
+                done_paths=self._done_paths,
+            )
+        )
+
+
+# ========================================================================= #
+# Main application
+# ========================================================================= #
+
+
+class BloatrApp(App):
+    """Main bloatr Textual application."""
+
+    TITLE = "bloatr"
+    SUB_TITLE = "Kill your Mac's bloat"
+
+    CSS = """
+    DataTable {
+        height: 1fr;
+    }
+    #status {
+        height: 1;
+        background: $panel;
+        padding: 0 1;
+        color: $text-muted;
+        dock: bottom;
+    }
+    """
+
+    BINDINGS: ClassVar = [
+        Binding("j,down", "cursor_down", "Down", show=False),
+        Binding("k,up", "cursor_up", "Up", show=False),
+        Binding("space", "toggle_select", "Select"),
+        Binding("enter", "drill_in", "Explore"),
+        Binding("escape,backspace", "go_back", "Back"),
+        Binding("d", "delete_selected", "Delete"),
+        Binding("r", "rescan", "Rescan"),
+        Binding("q", "quit", "Quit"),
+    ]
+
+    def __init__(
+        self,
+        items: list[Item],
+        dry_run: bool = False,
+        scan_root: Path | None = None,
+    ) -> None:
+        super().__init__()
+        self._items = items
+        self._dry_run = dry_run
+        self._scan_root = scan_root
+        self._stack: list[tuple[str, list[Item]]] = []  # (breadcrumb, items)
+        self._selected: set[Path] = set()
+        self._current_path: str = str(scan_root) if scan_root else "~"
+
+    # ------------------------------------------------------------------ #
+    # Composition & mount
+    # ------------------------------------------------------------------ #
+
+    def compose(self) -> ComposeResult:
+        yield Header(show_clock=False)
+        yield DataTable(id="table", cursor_type="row", zebra_stripes=True)
+        yield Label("", id="status")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        table = self.query_one(DataTable)
+        table.add_column(" ", width=3, key="checkbox")
+        table.add_column("SIZE", width=12, key="size")
+        table.add_column("LOCATION", key="location")
+        self._load_items(self._items)
+
+    # ------------------------------------------------------------------ #
+    # Rendering
+    # ------------------------------------------------------------------ #
+
+    def _load_items(self, items: list[Item]) -> None:
+        """Refresh the DataTable with *items* as the current view."""
+        self._items = items
+        table = self.query_one(DataTable)
+        table.clear()
+
+        if not items:
+            table.add_row("", "", "(no items)", key="__empty__")
+            self._set_status("No items in this view. Press ESC to go back or Q to quit.")
+            return
+
+        for item in items:
+            checkbox = "✓" if item.path in self._selected else "○"
+            if item.error:
+                size_str = "-- missing --"
+            else:
+                size_str = format_size(item.size)
+            explore = " ▶" if item.is_dir and not item.error else "  "
+            table.add_row(checkbox, size_str, f"{item.display}{explore}", key=str(item.path))
+
+        self._update_status()
+
+    def _update_status(self) -> None:
+        count = len(self._selected)
+        total = sum(i.size for i in self._items if i.path in self._selected)
+        mode = "  [DRY RUN]" if self._dry_run else ""
+        if count:
+            self._set_status(
+                f"{count} selected — {format_size(total)} to free  |  press D to delete{mode}"
+            )
+        else:
+            self._set_status(
+                f"SPACE select  •  ENTER explore  •  ESC back  •  D delete  •  R rescan  •  Q quit{mode}"
+            )
+
+    def _set_status(self, msg: str) -> None:
+        self.query_one("#status", Label).update(msg)
+
+    def _current_item(self) -> Item | None:
+        table = self.query_one(DataTable)
+        try:
+            coord = table.cursor_coordinate
+            row_key = table.coordinate_to_cell_key(coord).row_key
+            path_str = row_key.value
+            if path_str is None or path_str == "__empty__":
+                return None
+            return next((i for i in self._items if str(i.path) == path_str), None)
+        except Exception:
+            return None
+
+    # ------------------------------------------------------------------ #
+    # Actions
+    # ------------------------------------------------------------------ #
+
+    def action_cursor_down(self) -> None:
+        self.query_one(DataTable).action_cursor_down()
+
+    def action_cursor_up(self) -> None:
+        self.query_one(DataTable).action_cursor_up()
+
+    def action_toggle_select(self) -> None:
+        item = self._current_item()
+        if item is None or item.error:
+            return
+
+        if item.path in self._selected:
+            self._selected.discard(item.path)
+        else:
+            self._selected.add(item.path)
+
+        # Update ONLY the checkbox cell — cursor position is preserved.
+        checkbox = "✓" if item.path in self._selected else "○"
+        table = self.query_one(DataTable)
+        table.update_cell(str(item.path), "checkbox", checkbox)
+        self._update_status()
+
+    # DataTable intercepts Enter internally and emits RowSelected before
+    # App-level key bindings fire — so we handle drill-in via the event,
+    # not the key binding.  action_drill_in is kept as a documented fallback.
+    def on_data_table_row_selected(self, event: DataTable.RowSelected) -> None:
+        self._drill_into_key(event.row_key.value)
+
+    def action_drill_in(self) -> None:
+        item = self._current_item()
+        if item:
+            self._drill_into_key(str(item.path))
+
+    def _drill_into_key(self, path_str: str | None) -> None:
+        if path_str is None or path_str == "__empty__":
+            return
+        item = next((i for i in self._items if str(i.path) == path_str), None)
+        if item is None or not item.is_dir or item.error:
+            return
+        self._stack.append((self._current_path, self._items))
+        self._current_path = item.display
+        self._set_status(f"Scanning {item.display}…")
+        self._fetch_children(item)
+
+    @work(thread=True)
+    def _fetch_children(self, item: Item) -> None:
+        children = list_children(item)
+        self.call_from_thread(self._load_items, children)
+
+    def action_go_back(self) -> None:
+        if not self._stack:
+            return
+        prev_path, prev_items = self._stack.pop()
+        self._current_path = prev_path
+        self._load_items(prev_items)
+
+    def action_rescan(self) -> None:
+        """Rescan from scratch — either the custom root or built-in locations."""
+        self._stack.clear()
+        self._current_path = str(self._scan_root) if self._scan_root else "~"
+        self._selected.clear()
+        self._set_status("Rescanning…")
+        self._do_rescan()
+
+    @work(thread=True)
+    def _do_rescan(self) -> None:
+        if self._scan_root:
+            root_item = Item.from_path(self._scan_root)
+            items = list_children(root_item)
+        else:
+            from bloatr.locations import get_locations
+            items = scan_locations(get_locations())
+        self.call_from_thread(self._load_items, items)
+
+    def action_delete_selected(self) -> None:
+        selected_items = [i for i in self._items if i.path in self._selected]
+        if not selected_items:
+            self._set_status("Nothing selected. Press SPACE on items first.")
+            return
+
+        total = sum(i.size for i in selected_items)
+
+        def handle_confirm(confirmed: bool | None) -> None:
+            if not confirmed:
+                self._set_status("Cancelled.")
+                return
+
+            def handle_progress(result: ProgressResult | None) -> None:
+                if result is None:
+                    return
+                # Drop deleted items from current view
+                self._selected -= result.done_paths
+                self._items = [i for i in self._items if i.path not in result.done_paths]
+                self._load_items(self._items)
+
+                # Summarise
+                if self._dry_run:
+                    self._set_status(
+                        f"DRY RUN complete — would have freed {format_size(result.freed)}"
+                    )
+                elif result.errors:
+                    first = result.errors[0]
+                    errmsg = f"{first[0].display}: {first[1]}"
+                    self._set_status(
+                        f"Freed {format_size(result.freed)} — {len(result.errors)} error(s). First: {errmsg}"
+                    )
+                else:
+                    self._set_status(
+                        f"✓ Success! Freed {format_size(result.freed)} across {len(result.done_paths)} item(s)."
+                    )
+
+            self.push_screen(
+                ProgressScreen(selected_items, self._dry_run),
+                handle_progress,
+            )
+
+        self.push_screen(
+            ConfirmScreen(total, len(selected_items), self._dry_run),
+            handle_confirm,
+        )
+
+
+# ========================================================================= #
+# Entry point
+# ========================================================================= #
+
+
+def run_tui(
+    items: list[Item],
+    dry_run: bool = False,
+    scan_root: Path | None = None,
+) -> None:
+    """Launch the bloatr TUI.
+
+    Args:
+        items: Pre-scanned list of Items to display on first paint.
+        dry_run: When True, deletions are simulated only.
+        scan_root: When set, rescans this directory instead of built-in locations.
+    """
+    app = BloatrApp(items=items, dry_run=dry_run, scan_root=scan_root)
+    app.run()

bloatr/cleaner.py

@@ -0,0 +1,216 @@
+"""Safe deletion utilities for bloatr."""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+from typing import TYPE_CHECKING, Callable
+
+if TYPE_CHECKING:
+    from bloatr.models import Item
+
+
+class UnsafePathError(Exception):
+    """Raised when a path fails the safety check and must not be deleted."""
+
+
+MIN_DEPTH: int = 1  # Minimum number of path components below home directory.
+
+# Top-level home subdirectories that must never be deleted outright.
+_BLOCKLIST: frozenset[str] = frozenset({
+    "Library", "Documents", "Desktop", "Downloads",
+    "Pictures", "Music", "Movies", "Applications",
+    "Public", "Sites",
+})
+
+
+ProgressCallback = Callable[[int, str], None]
+"""A callback that receives (bytes_delta, current_path) as deletion progresses."""
+
+
+def is_safe_path(path: Path) -> bool:
+    """Return True only if *path* is safe to delete.
+
+    Safety criteria (all must hold):
+
+    1. The resolved path must be located inside the user's home directory.
+    2. The resolved path must be at least :data:`MIN_DEPTH` components below
+       the home directory.
+    3. The path must not be a bare top-level directory listed in ``_BLOCKLIST``
+       (``~/Library``, ``~/Documents``, etc.).
+
+    Symlinks are resolved before the check so that a symlink pointing outside
+    the home directory is correctly rejected.
+
+    Args:
+        path: The path to check.  Need not exist on disk.
+
+    Returns:
+        ``True`` if the path passes the safety checks, ``False`` otherwise.
+    """
+    home = Path.home().resolve()
+    resolved = path.resolve()
+
+    try:
+        relative = resolved.relative_to(home)
+    except ValueError:
+        return False
+
+    if len(relative.parts) < MIN_DEPTH:
+        return False
+
+    if len(relative.parts) == 1 and relative.parts[0] in _BLOCKLIST:
+        return False
+
+    return True
+
+
+def delete(item: "Item", dry_run: bool = False) -> None:
+    """Delete the filesystem entry represented by *item* (no progress).
+
+    Simpler wrapper around :func:`delete_with_progress` used by the CLI's
+    non-interactive paths and tests.
+
+    Raises:
+        UnsafePathError: If ``item.path`` is not safe to delete.
+        OSError: If the underlying filesystem operation fails.
+    """
+    if not is_safe_path(item.path):
+        raise UnsafePathError(f"Refusing to delete unsafe path: {item.path!r}")
+
+    if dry_run:
+        return
+
+    if item.is_dir:
+        shutil.rmtree(item.path)
+    else:
+        item.path.unlink()
+
+
+def delete_with_progress(
+    item: "Item",
+    on_progress: ProgressCallback | None = None,
+    dry_run: bool = False,
+) -> tuple[int, str | None]:
+    """Delete *item* file-by-file so progress can be streamed to a callback.
+
+    Walks the directory bottom-up using :func:`os.walk`, deleting individual
+    files and empty subdirectories.  After each file is removed, the caller's
+    ``on_progress`` callback is invoked with ``(bytes_freed_delta, path)`` so
+    the UI can update a progress bar in real time.
+
+    Args:
+        item: The :class:`~bloatr.models.Item` to delete.
+        on_progress: Optional callback invoked with ``(bytes_delta, current_path)``
+            for every file removed (or once, with the total, in dry-run mode).
+        dry_run: When True, report progress but make no filesystem changes.
+
+    Returns:
+        A tuple ``(bytes_freed, first_error_or_None)``.  Errors on individual
+        files are recorded and processing continues; only the first error
+        message is returned.
+
+    Raises:
+        UnsafePathError: If ``item.path`` fails the safety check.
+    """
+    if not is_safe_path(item.path):
+        raise UnsafePathError(f"Refusing to delete unsafe path: {item.path!r}")
+
+    if not item.path.exists() and not item.path.is_symlink():
+        return 0, "not found"
+
+    # Dry-run: just report the pre-computed size and bail.
+    if dry_run:
+        if on_progress:
+            on_progress(item.size, str(item.path))
+        return item.size, None
+
+    # Non-directory path (file or symlink).
+    if not item.path.is_dir() or item.path.is_symlink():
+        try:
+            size = item.path.lstat().st_size
+            item.path.unlink()
+            if on_progress:
+                on_progress(size, str(item.path))
+            return size, None
+        except OSError as exc:
+            return 0, str(exc)
+
+    # Directory: walk bottom-up, delete per-file.
+    freed = 0
+    first_error: str | None = None
+    walk_errors: list[str] = []
+
+    def on_walk_error(exc: OSError) -> None:
+        walk_errors.append(str(exc))
+
+    for root, dirs, files in os.walk(
+        item.path,
+        topdown=False,
+        followlinks=False,
+        onerror=on_walk_error,
+    ):
+        for name in files:
+            fpath = os.path.join(root, name)
+            try:
+                st = os.lstat(fpath)
+                os.unlink(fpath)
+                freed += st.st_size
+                if on_progress:
+                    on_progress(st.st_size, fpath)
+            except OSError as exc:
+                if first_error is None:
+                    first_error = str(exc)
+
+        for name in dirs:
+            dpath = os.path.join(root, name)
+            try:
+                # rmdir only succeeds on empty dirs; that's the invariant after
+                # the files loop above.
+                os.rmdir(dpath)
+            except OSError as exc:
+                if first_error is None:
+                    first_error = str(exc)
+
+    try:
+        os.rmdir(item.path)
+    except OSError as exc:
+        if first_error is None:
+            first_error = str(exc)
+
+    if first_error is None and walk_errors:
+        first_error = walk_errors[0]
+
+    return freed, first_error
+
+
+def delete_many(
+    items: list["Item"],
+    dry_run: bool = False,
+) -> list[tuple["Item", Exception | None]]:
+    """Delete multiple items, capturing any per-item errors.
+
+    Each item is deleted independently via :func:`delete`.  If an exception
+    is raised for a particular item it is caught and recorded; processing
+    continues with the remaining items.
+
+    Args:
+        items: List of :class:`~bloatr.models.Item` objects to delete.
+        dry_run: Passed through to :func:`delete` for every item.
+
+    Returns:
+        A list of ``(item, error)`` tuples in the same order as *items*.
+        ``error`` is ``None`` when deletion succeeded, or the exception
+        instance when it failed.
+    """
+    results: list[tuple[Item, Exception | None]] = []
+
+    for item in items:
+        try:
+            delete(item, dry_run=dry_run)
+            results.append((item, None))
+        except Exception as exc:
+            results.append((item, exc))
+
+    return results

bloatr/cli.py

@@ -0,0 +1,122 @@
+"""CLI entry point for bloatr."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from pathlib import Path
+
+from bloatr import __version__
+from bloatr.app import run_tui
+from bloatr.locations import get_locations
+from bloatr.models import Item
+from bloatr.scanner import list_children, scan_locations
+from bloatr.sizes import format_size, parse_size
+
+
+def main() -> None:
+    """Parse CLI flags, run the scanner, then launch TUI or JSON output."""
+    parser = argparse.ArgumentParser(
+        prog="bloatr",
+        description="Kill your Mac's bloat. Select. Delete. Done.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  bloatr                      # launch interactive TUI (built-in locations)
+  bloatr ~/                   # scan home directory children
+  bloatr ~/Documents          # scan a specific folder's children
+  bloatr --dry-run            # TUI, but don't actually delete anything
+  bloatr --min-size 1G        # only show items larger than 1 GB
+  bloatr --json               # print JSON to stdout (no TUI)
+  bloatr --json | jq '.[].size_human'
+        """,
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be deleted without actually deleting",
+    )
+    parser.add_argument(
+        "--min-size",
+        default=None,
+        metavar="SIZE",
+        help="Only show items larger than SIZE (e.g. 500M, 1G, 2T)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_output",
+        help="Output scan results as JSON and exit (non-interactive)",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"bloatr {__version__}",
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=None,
+        metavar="PATH",
+        help="Scan this directory's children instead of the built-in developer locations (e.g. ~/ or ~/Documents)",
+    )
+    args = parser.parse_args()
+
+    # Validate --min-size
+    min_size = 0
+    if args.min_size:
+        try:
+            min_size = parse_size(args.min_size)
+        except ValueError as exc:
+            print(f"bloatr: invalid --min-size value: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    # Scan — either a user-supplied path or the built-in developer locations.
+    scan_root: Path | None = None
+
+    if args.path:
+        scan_root = Path(args.path).expanduser().resolve()
+        if not scan_root.exists():
+            print(f"bloatr: path does not exist: {scan_root}", file=sys.stderr)
+            sys.exit(1)
+        if not scan_root.is_dir():
+            print(f"bloatr: not a directory: {scan_root}", file=sys.stderr)
+            sys.exit(1)
+        if not args.json_output:
+            print(f"bloatr: scanning {scan_root}…", file=sys.stderr)
+        root_item = Item.from_path(scan_root)
+        items = list_children(root_item)
+    else:
+        locations = get_locations()
+        if not args.json_output:
+            print("bloatr: scanning…", file=sys.stderr)
+        items = scan_locations(locations)
+
+    # Filter by min-size
+    if min_size > 0:
+        items = [i for i in items if i.size >= min_size]
+
+    # JSON mode — print and exit
+    if args.json_output:
+        data = [
+            {
+                "path": str(item.path),
+                "display": item.display,
+                "size": item.size,
+                "size_human": format_size(item.size),
+                "is_dir": item.is_dir,
+                "error": item.error,
+            }
+            for item in items
+        ]
+        print(json.dumps(data, indent=2))
+        return
+
+    # Interactive TUI
+    run_tui(items, dry_run=args.dry_run, scan_root=scan_root)
+
+
+if __name__ == "__main__":
+    main()

bloatr/locations.py

@@ -0,0 +1,70 @@
+"""Known macOS developer bloat locations for bloatr."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+KNOWN_PATHS: tuple[str, ...] = (
+    "~/Library/Developer/Xcode/DerivedData",
+    "~/Library/Developer/Xcode/Archives",
+    "~/Library/Developer/CoreSimulator/Runtimes",
+    "~/Library/Caches",
+    "~/Library/Developer/Xcode/iOS DeviceSupport",
+    "~/.gradle/caches",
+    "~/.npm",
+    "~/.yarn/cache",
+    "~/.pnpm-store",
+    "~/.cocoapods/repos",
+    "~/.cargo/registry",
+    "~/.cargo/git",
+    "~/.pub-cache",
+    "~/go/pkg/mod",
+    "~/.expo",
+    "~/Library/Android/sdk",
+    "~/Library/Application Support/JetBrains",
+)
+
+
+def _brew_cache() -> Path | None:
+    """Return the Homebrew cache directory, or None if brew is unavailable.
+
+    Runs ``brew --cache`` with a 5-second timeout.  Any exception (including
+    FileNotFoundError when brew is not installed, TimeoutExpired, or a
+    non-zero exit code) results in None being returned.
+
+    Returns:
+        Path to the brew cache directory, or None.
+    """
+    try:
+        result = subprocess.run(
+            ["brew", "--cache"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            cache_path = result.stdout.strip()
+            if cache_path:
+                return Path(cache_path)
+        return None
+    except Exception:
+        return None
+
+
+def get_locations() -> list[Path]:
+    """Return the full list of developer bloat paths to scan.
+
+    Expands all entries in ``KNOWN_PATHS`` and appends the Homebrew cache
+    directory if ``brew`` is available.
+
+    Returns:
+        List of absolute ``Path`` objects (paths may or may not exist on disk).
+    """
+    locations: list[Path] = [Path(p).expanduser() for p in KNOWN_PATHS]
+
+    brew = _brew_cache()
+    if brew is not None:
+        locations.append(brew)
+
+    return locations

bloatr/models.py

@@ -0,0 +1,72 @@
+"""Data models for bloatr."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from bloatr.sizes import format_size
+
+
+@dataclass(frozen=True)
+class Item:
+    """Represents a single filesystem entry that bloatr can inspect or delete.
+
+    Attributes:
+        path: Absolute path to the entry.
+        display: Path in ``~/...`` form relative to the user's home directory.
+        size: Size in bytes; 0 when the entry is missing or the size could not
+            be determined.
+        is_dir: True when the entry is a directory.
+        error: Human-readable error message if something went wrong during
+            scanning; None otherwise.
+    """
+
+    path: Path
+    display: str
+    size: int
+    is_dir: bool
+    error: str | None = None
+
+    @classmethod
+    def from_path(cls, path: Path) -> "Item":
+        """Construct an Item from an absolute path.
+
+        The ``display`` field is computed by replacing the user's home
+        directory prefix with ``~``.  ``size`` is initialised to 0; callers
+        are responsible for populating real size data via a scanner.
+        ``is_dir`` reflects whether *path* is a directory at construction
+        time.
+
+        Args:
+            path: Absolute path to the filesystem entry.
+
+        Returns:
+            A new :class:`Item` with ``size=0`` and ``error=None``.
+        """
+        home = Path.home()
+        try:
+            relative = path.relative_to(home)
+            display = f"~/{relative}"
+        except ValueError:
+            display = str(path)
+
+        is_dir = path.is_dir()
+
+        return cls(
+            path=path,
+            display=display,
+            size=0,
+            is_dir=is_dir,
+            error=None,
+        )
+
+    def size_display(self) -> str:
+        """Return the size formatted as a human-readable string.
+
+        Delegates to :func:`bloatr.sizes.format_size`.
+
+        Returns:
+            Human-readable size string, e.g. ``"1.5 GB"``.
+        """
+        return format_size(self.size)

bloatr/scanner.py

@@ -0,0 +1,145 @@
+"""Concurrent directory scanner for bloatr."""
+
+from __future__ import annotations
+
+import os
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+
+from bloatr.models import Item
+
+
+def compute_size(path: Path) -> tuple[int, str | None]:
+    """Compute the total size of a directory tree iteratively.
+
+    Uses an explicit stack to avoid hitting Python's recursion limit on deep
+    directory trees.  Symlinks are skipped entirely.  Per-entry permission
+    errors are swallowed; the first error message is returned alongside the
+    partial size.
+
+    Args:
+        path: Root directory to measure.
+
+    Returns:
+        A ``(total_bytes, first_error_or_None)`` tuple.
+    """
+    if not path.exists():
+        return 0, "not found"
+
+    if path.is_file():
+        try:
+            return path.stat().st_size, None
+        except OSError as exc:
+            return 0, str(exc)
+
+    total = 0
+    first_error: str | None = None
+    stack: list[str] = [str(path)]
+
+    while stack:
+        current = stack.pop()
+        try:
+            with os.scandir(current) as it:
+                for entry in it:
+                    if entry.is_symlink():
+                        continue
+                    try:
+                        if entry.is_dir(follow_symlinks=False):
+                            stack.append(entry.path)
+                        else:
+                            total += entry.stat(follow_symlinks=False).st_size
+                    except (PermissionError, OSError) as exc:
+                        if first_error is None:
+                            first_error = str(exc)
+        except (PermissionError, OSError) as exc:
+            if first_error is None:
+                first_error = str(exc)
+
+    return total, first_error
+
+
+def _size_one(path: Path) -> Item:
+    """Size a single location and return a complete Item."""
+    base = Item.from_path(path)
+
+    if not path.exists():
+        return Item(
+            path=path,
+            display=base.display,
+            size=0,
+            is_dir=False,
+            error="not found",
+        )
+
+    size, error = compute_size(path)
+    return Item(
+        path=path,
+        display=base.display,
+        size=size,
+        is_dir=path.is_dir(),
+        error=error,
+    )
+
+
+def scan_locations(paths: list[Path], max_workers: int = 8) -> list[Item]:
+    """Scan a list of locations concurrently and return Items sorted by size.
+
+    Each path is measured in a separate thread.  Missing paths produce an Item
+    with ``error="not found"`` and ``size=0``.
+
+    Args:
+        paths: Absolute paths to scan.
+        max_workers: Thread pool size (default 8).
+
+    Returns:
+        List of :class:`~bloatr.models.Item` objects sorted descending by size.
+    """
+    results: list[Item] = []
+
+    with ThreadPoolExecutor(max_workers=max_workers) as pool:
+        future_to_path = {pool.submit(_size_one, p): p for p in paths}
+        for future in as_completed(future_to_path):
+            try:
+                results.append(future.result())
+            except Exception as exc:
+                p = future_to_path[future]
+                base = Item.from_path(p)
+                results.append(
+                    Item(
+                        path=p,
+                        display=base.display,
+                        size=0,
+                        is_dir=False,
+                        error=str(exc),
+                    )
+                )
+
+    results.sort(key=lambda i: i.size, reverse=True)
+    return results
+
+
+def list_children(item: Item) -> list[Item]:
+    """Return immediate children of a directory item, sorted by size desc.
+
+    Each child is sized individually.  Non-directory items and missing paths
+    return an empty list.
+
+    Args:
+        item: The parent directory item to drill into.
+
+    Returns:
+        Sorted list of child :class:`~bloatr.models.Item` objects.
+    """
+    if not item.is_dir or not item.path.exists():
+        return []
+
+    children: list[Path] = []
+    try:
+        with os.scandir(item.path) as it:
+            for entry in it:
+                if not entry.name.startswith(".") or True:  # show hidden too
+                    children.append(Path(entry.path))
+    except (PermissionError, OSError):
+        return []
+
+    return scan_locations(children)

bloatr/sizes.py

@@ -0,0 +1,80 @@
+"""Size parsing and formatting utilities for bloatr."""
+
+_SUFFIXES: dict[str, int] = {
+    "K": 1024,
+    "M": 1024**2,
+    "G": 1024**3,
+    "T": 1024**4,
+}
+
+_FORMAT_UNITS: list[tuple[str, float]] = [
+    ("TB", 1024.0**4),
+    ("GB", 1024.0**3),
+    ("MB", 1024.0**2),
+    ("KB", 1024.0),
+    ("B", 1.0),
+]
+
+
+def parse_size(s: str) -> int:
+    """Parse a human-readable size string into bytes.
+
+    Supports suffixes K, M, G, T (case-insensitive) and bare integers.
+    Examples: "500M", "1.5G", "100", "2T", "10K".
+
+    Args:
+        s: Size string to parse.
+
+    Returns:
+        Size in bytes as an integer.
+
+    Raises:
+        ValueError: If the string is empty, has an unknown suffix, or is
+            otherwise malformed.
+    """
+    if not s:
+        raise ValueError("Empty size string")
+
+    upper = s.strip().upper()
+
+    if upper[-1] in _SUFFIXES:
+        multiplier = _SUFFIXES[upper[-1]]
+        numeric_part = upper[:-1]
+    else:
+        multiplier = 1
+        numeric_part = upper
+
+    if not numeric_part:
+        raise ValueError(f"No numeric component in size string: {s!r}")
+
+    try:
+        value = float(numeric_part)
+    except ValueError:
+        raise ValueError(f"Invalid size string: {s!r}")
+
+    return int(value * multiplier)
+
+
+def format_size(n: int) -> str:
+    """Format a byte count as a human-readable string.
+
+    Returns values like "0 B", "1.5 KB", "24.3 GB".  Values below 1 KB are
+    shown without a decimal place; everything else uses one decimal place.
+
+    Args:
+        n: Number of bytes (non-negative integer).
+
+    Returns:
+        Human-readable size string.
+    """
+    if n == 0:
+        return "0 B"
+
+    for unit, threshold in _FORMAT_UNITS:
+        if n >= threshold:
+            value = n / threshold
+            if unit == "B":
+                return f"{n} B"
+            return f"{value:.1f} {unit}"
+
+    return f"{n} B"

bloatr-0.1.0.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: bloatr
+Version: 0.1.0
+Summary: Kill your Mac's bloat. Select. Delete. Done.
+Project-URL: Homepage, https://github.com/suhasdinesh/bloatr
+Project-URL: Repository, https://github.com/suhasdinesh/bloatr
+Project-URL: Bug Tracker, https://github.com/suhasdinesh/bloatr/issues
+License: MIT
+Keywords: cleanup,developer,disk,macos,storage
+Requires-Python: >=3.11
+Requires-Dist: textual>=0.60
+Description-Content-Type: text/markdown
+
+# bloatr
+
+> Kill your Mac's bloat. Select. Delete. Done.
+
+A dead-simple macOS CLI that finds your biggest developer cache directories, lets you browse them, and deletes what you don't need — with a clean terminal UI.
+
+```
+  SIZE        LOCATION
+  24.3 GB ▶   ~/Library/Developer/Xcode/DerivedData
+  11.2 GB     ~/Library/Caches
+   4.1 GB     ~/Library/Android/sdk
+   3.1 GB     ~/.expo
+   1.9 GB     ~/.gradle/caches
+   515 MB      ~/.npm
+
+  space:select  enter:explore  esc:back  d:delete  q:quit
+```
+
+---
+
+## Install
+
+```bash
+pipx install bloatr
+```
+
+Or with pip:
+
+```bash
+pip install bloatr
+```
+
+---
+
+## Usage
+
+```bash
+# Launch interactive TUI (scans known developer bloat locations)
+bloatr
+
+# Scan any directory — like `du` but interactive
+bloatr ~/
+bloatr ~/Documents
+bloatr ~/Library/Caches
+
+# Preview what would be deleted (safe mode)
+bloatr --dry-run
+
+# Only show items > 1 GB
+bloatr --min-size 1G
+
+# JSON output (pipe-friendly)
+bloatr --json
+bloatr --json ~/Library | jq '.[].size_human'
+```
+
+---
+
+## What it scans
+
+| Location | What it is |
+|---|---|
+| `~/Library/Developer/Xcode/DerivedData` | Xcode build artifacts |
+| `~/Library/Developer/Xcode/Archives` | Xcode app archives |
+| `~/Library/Developer/CoreSimulator/Runtimes` | iOS/watchOS simulator runtimes |
+| `~/Library/Developer/Xcode/iOS DeviceSupport` | Per-device debug symbols |
+| `~/Library/Caches` | App caches |
+| `~/.gradle/caches` | Gradle build cache |
+| `~/.npm` | npm package cache |
+| `~/.yarn/cache` | Yarn package cache |
+| `~/.pnpm-store` | pnpm content-addressable store |
+| `~/.cocoapods/repos` | CocoaPods spec repos |
+| `~/.cargo/registry` | Rust crate registry |
+| `~/.cargo/git` | Rust git dependencies |
+| `~/.pub-cache` | Flutter/Dart package cache |
+| `~/go/pkg/mod` | Go module cache |
+| `~/.expo` | Expo/React Native cache |
+| `~/Library/Android/sdk` | Android SDK |
+| `~/Library/Application Support/JetBrains` | JetBrains IDE caches |
+| Homebrew cache | `brew --cache` output |
+
+---
+
+## Keyboard shortcuts
+
+| Key | Action |
+|---|---|
+| `j` / `↓` | Move down |
+| `k` / `↑` | Move up |
+| `space` | Toggle select |
+| `enter` | Drill into folder |
+| `esc` / `backspace` | Go back |
+| `d` | Delete selected items |
+| `r` | Rescan from scratch |
+| `q` | Quit |
+
+---
+
+## Safety
+
+bloatr will **never** delete:
+- Anything outside your home directory (`~`)
+- Top-level protected directories (`~/Library`, `~/Documents`, `~/Desktop`, etc.)
+- The home directory itself
+
+Every deletion requires an explicit confirmation prompt. Use `--dry-run` to preview without touching anything.
+
+---
+
+## Credits
+
+Idea and direction by a human who lost 100 GB to Mac bloat one too many times. Code written entirely by [Claude Code](https://claude.ai/code).
+
+---
+
+## License
+
+MIT

bloatr-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+bloatr/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+bloatr/__main__.py,sha256=T2828FUbE1pmpVsrPJJhUhRD-Eq1DAlndk3_JNtp5Yo,36
+bloatr/app.py,sha256=X1A3KiZk2vGfJdlnho0rx3OG9tKthLLzWLNm816wPvc,17245
+bloatr/cleaner.py,sha256=zmkJH4DqaEdAij-MEByhkm5v4l4LfGI26W23q6I3I0M,6681
+bloatr/cli.py,sha256=PPe-BsIpWm3YAxpsz6GCRmHTuJgAtoWQdghniHfa1oA,3809
+bloatr/locations.py,sha256=rd4mHNy_nJqMCmUhpYYr3rcScUAvWQt-p0k820QkRos,1923
+bloatr/models.py,sha256=aPeBbKteH7CFNqSi3XNI0d2oqEBvsFiiRBFwOzqMQ-Q,2035
+bloatr/scanner.py,sha256=v7zju64xgxGd_CuoqOAl2hzMuVEvC6x9t_WAwNdc_io,4313
+bloatr/sizes.py,sha256=ODG-un7OngJohe0-jo7ma6J1bo5Yw0cdMbOAXDRi31Q,1882
+bloatr-0.1.0.dist-info/METADATA,sha256=lw81FNqc6SJWgpuklVxYd2vYYNRjJBR5I-L-fBBpJZ8,3210
+bloatr-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+bloatr-0.1.0.dist-info/entry_points.txt,sha256=xKF1DYLsd354F_ta45lGfbjDf9cxqkVaKC0GLHCX-oQ,43
+bloatr-0.1.0.dist-info/RECORD,,

bloatr-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

bloatr-0.1.0.dist-info/entry_points.txt

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