devcull 0.1.0__py3-none-any.whl

cull/__init__.py

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

cull/__main__.py

@@ -0,0 +1,2 @@
+from cull.cli import cli
+cli()

cull/cli.py

@@ -0,0 +1,189 @@
+import shutil
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+from rich import print as rprint
+
+from cull import __version__
+from cull.scan import scan, Hit
+
+
+console = Console()
+
+
+def _fmt_size(n: int) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024:
+            return f"{n:.1f} {unit}"
+        n /= 1024
+    return f"{n:.1f} TB"
+
+
+def _age_days(dt: datetime) -> int:
+    now = datetime.now(tz=timezone.utc)
+    return (now - dt).days
+
+
+def _delete(h: Hit):
+    try:
+        shutil.rmtree(h.path)
+        return True
+    except Exception as e:
+        console.print(f"  [red]couldn't remove {h.path.name}: {e}[/red]")
+        return False
+
+
+def _show_table(hits: list[Hit]):
+    t = Table(show_header=True, header_style="bold", box=None, pad_edge=False, show_edge=False)
+    t.add_column("#", style="dim", width=4)
+    t.add_column("path", no_wrap=False, max_width=60)
+    t.add_column("size", justify="right", style="yellow")
+    t.add_column("last commit", justify="right", style="cyan")
+
+    for i, h in enumerate(hits, 1):
+        age = _age_days(h.last_used)
+        if age > 365:
+            age_str = f"{age // 365}y ago"
+        elif age > 30:
+            age_str = f"{age // 30}mo ago"
+        else:
+            age_str = f"{age}d ago"
+
+        t.add_row(
+            str(i),
+            str(h.path),
+            _fmt_size(h.size),
+            age_str,
+        )
+
+    console.print(t)
+
+
+@click.command()
+@click.argument("path", default=".", type=click.Path(exists=True, file_okay=False))
+@click.option("--older-than", default=90, metavar="DAYS",
+              help="only show caches not touched in N days (default: 90)")
+@click.option("--delete", is_flag=True, help="interactively delete found caches")
+@click.option("--all", "delete_all", is_flag=True, help="delete everything without asking (use with care)")
+@click.option("--dry-run", is_flag=True, help="show what would be deleted but don't touch anything")
+@click.version_option(__version__, prog_name="cull")
+def cli(path, older_than, delete, delete_all, dry_run):
+    """Find and remove stale dev cache directories.
+
+    Scans PATH (default: current directory) for node_modules, .venv,
+    __pycache__, and similar directories that are safe to delete.
+    """
+    root = Path(path).resolve()
+
+    hits: list[Hit] = []
+
+    with console.status(f"scanning [dim]{root}[/dim]...", spinner="dots") as status:
+        def on_progress(p: Path):
+            # trim the path so it doesn't wrap
+            label = str(p)
+            if len(label) > 60:
+                label = "..." + label[-57:]
+            status.update(f"scanning [dim]{label}[/dim]")
+
+        hits = scan(root, progress_cb=on_progress)
+
+    if not hits:
+        rprint("[green]nothing found, you're clean[/green]")
+        return
+
+    # filter by age
+    now = datetime.now(tz=timezone.utc)
+    filtered = [h for h in hits if _age_days(h.last_used) >= older_than]
+
+    if not filtered:
+        rprint(f"[green]found {len(hits)} cache dirs but all were touched in the last {older_than} days[/green]")
+        return
+
+    total = sum(h.size for h in filtered)
+    rprint(f"\nfound [bold]{len(filtered)}[/bold] stale cache dirs totaling [yellow bold]{_fmt_size(total)}[/yellow bold]\n")
+    _show_table(filtered)
+
+    if dry_run:
+        rprint("\n[dim](dry run — nothing deleted)[/dim]")
+        return
+
+    if not delete and not delete_all:
+        return
+
+    print()
+
+    if delete_all:
+        if not click.confirm(f"delete all {len(filtered)} dirs ({_fmt_size(total)})?"):
+            return
+        removed = freed = 0
+        for h in filtered:
+            if _delete(h):
+                freed += h.size
+                removed += 1
+        rprint(f"\n[green]removed {removed} dirs, freed {_fmt_size(freed)}[/green]")
+        return
+
+    # interactive mode
+    rprint("[dim]enter numbers to delete (e.g. 1 3 5), 'a' for all, or q to quit[/dim]\n")
+    while True:
+        try:
+            raw = input("> ").strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            break
+
+        if raw in ("q", "quit", ""):
+            break
+
+        if raw == "a":
+            chosen = filtered
+        else:
+            indices = []
+            valid = True
+            for tok in raw.split():
+                try:
+                    n = int(tok)
+                    if 1 <= n <= len(filtered):
+                        indices.append(n - 1)
+                    else:
+                        rprint(f"[red]{n} is out of range[/red]")
+                        valid = False
+                        break
+                except ValueError:
+                    rprint(f"[red]'{tok}' isn't a number[/red]")
+                    valid = False
+                    break
+            if not valid:
+                continue
+            chosen = [filtered[i] for i in indices]
+
+        if not chosen:
+            continue
+
+        sz = sum(h.size for h in chosen)
+        if not click.confirm(f"delete {len(chosen)} dir(s) ({_fmt_size(sz)})?"):
+            continue
+
+        removed = freed = 0
+        for h in chosen:
+            console.print(f"  removing [dim]{h.path}[/dim]...", end=" ")
+            if _delete(h):
+                freed += h.size
+                removed += 1
+                console.print("[green]done[/green]")
+            # remove from list so 'a' doesn't re-select deleted entries
+            filtered = [x for x in filtered if x.path != h.path]
+
+        rprint(f"[green]freed {_fmt_size(freed)}[/green]")
+
+        if not filtered:
+            rprint("[green]nothing left[/green]")
+            break
+
+        # reprint table with updated indices
+        print()
+        _show_table(filtered)
+        print()

cull/scan.py

@@ -0,0 +1,145 @@
+import os
+import subprocess
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+# directories that are definitely just build/cache garbage
+CACHE_DIRS = {
+    "node_modules",
+    ".venv", "venv", ".virtualenv",
+    ".next", ".nuxt", ".svelte-kit", ".solid",
+    "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache",
+    ".tox",
+    "dist", "build", "out",
+    ".parcel-cache", ".turbo", ".sass-cache",
+    ".gradle", ".gradle-cache",
+    ".angular",
+}
+
+# only count these as cache if there's a project marker nearby
+# (don't nuke a top-level "target" folder that could be anything)
+CONDITIONAL = {
+    "target",  # rust/maven — check for Cargo.toml or pom.xml
+}
+
+PROJECT_MARKERS = {
+    "package.json", "Cargo.toml", "pom.xml", "pyproject.toml",
+    "setup.py", "go.mod", "build.gradle", ".git",
+}
+
+
+@dataclass
+class Hit:
+    path: Path
+    size: int = 0           # bytes
+    last_used: datetime = field(default_factory=lambda: datetime.min.replace(tzinfo=timezone.utc))
+    project: Path | None = None
+
+
+def _project_root(p: Path) -> Path | None:
+    """walk up from p looking for a project marker"""
+    cur = p.parent
+    for _ in range(6):  # don't walk forever
+        if any((cur / m).exists() for m in PROJECT_MARKERS):
+            return cur
+        if cur.parent == cur:
+            break
+        cur = cur.parent
+    return None
+
+
+def _dir_size(p: Path) -> int:
+    total = 0
+    # os.scandir is faster than os.walk for shallow trees,
+    # but node_modules can be 8 levels deep so we walk
+    try:
+        for entry in os.scandir(p):
+            if entry.is_symlink():
+                continue
+            if entry.is_dir(follow_symlinks=False):
+                total += _dir_size(Path(entry.path))
+            else:
+                try:
+                    total += entry.stat(follow_symlinks=False).st_size
+                except OSError:
+                    pass
+    except PermissionError:
+        pass
+    return total
+
+
+def _last_git_commit(project: Path) -> datetime | None:
+    # git log is slow but mtime lies on windows (copying a file updates mtime)
+    try:
+        r = subprocess.run(
+            ["git", "-C", str(project), "log", "-1", "--format=%ct"],
+            capture_output=True, text=True, timeout=5,
+        )
+        if r.returncode == 0 and r.stdout.strip():
+            ts = int(r.stdout.strip())
+            return datetime.fromtimestamp(ts, tz=timezone.utc)
+    except Exception:
+        pass
+    return None
+
+
+def _last_used(hit_path: Path, project: Path | None) -> datetime:
+    if project:
+        t = _last_git_commit(project)
+        if t:
+            return t
+    # fall back to the mtime of the cache dir itself
+    try:
+        st = hit_path.stat()
+        return datetime.fromtimestamp(st.st_mtime, tz=timezone.utc)
+    except OSError:
+        return datetime.min.replace(tzinfo=timezone.utc)
+
+
+def scan(root: Path, progress_cb=None) -> list[Hit]:
+    """
+    Walk root looking for cache directories. Doesn't recurse into found dirs.
+    progress_cb(path) is called as we enter each directory, for spinner updates.
+    """
+    hits = []
+    # TODO: handle junction points (windows symlink variant)
+
+    for dirpath, dirnames, _ in os.walk(root, topdown=True, onerror=None, followlinks=False):
+        p = Path(dirpath)
+
+        if progress_cb:
+            progress_cb(p)
+
+        # prune dirs we should never descend into
+        prune = []
+        for d in dirnames:
+            if d.startswith(".git") and d != ".git":
+                prune.append(d)
+                continue
+
+            if d in CACHE_DIRS:
+                full = p / d
+                proj = _project_root(full)
+                h = Hit(path=full, project=proj)
+                hits.append(h)
+                prune.append(d)
+                continue
+
+            if d in CONDITIONAL:
+                # only include 'target' if a build marker is in the immediate parent
+                if (p / "Cargo.toml").exists() or (p / "pom.xml").exists():
+                    full = p / d
+                    hits.append(Hit(path=full, project=p))
+                    prune.append(d)
+
+        for d in prune:
+            dirnames.remove(d)
+
+    # fill in sizes + last-used after the walk so the spinner can run cleanly
+    for h in hits:
+        h.size = _dir_size(h.path)
+        h.last_used = _last_used(h.path, h.project)
+
+    return hits

devcull-0.1.0.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: devcull
+Version: 0.1.0
+Summary: remove stale dev cache directories
+License-Expression: MIT
+Project-URL: Repository, https://github.com/gnomecromancer/cull
+Keywords: developer-tools,cache,cleanup,node_modules
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+
+# cull
+
+I ran WinDirStat one afternoon because my SSD was at 94% and found 74 GB of `node_modules` from projects I hadn't touched in over a year. Deleting them by hand is tedious. This does it for you.
+
+```
+$ cull ~/projects
+found 23 stale cache dirs totaling 61.3 GB
+
+#    path                                        size      last commit
+1    ~/projects/old-saas/node_modules           18.2 GB   14mo ago
+2    ~/projects/prototype-v2/node_modules        9.4 GB   11mo ago
+3    ~/projects/prototype-v2/.next               2.1 GB   11mo ago
+...
+
+> a
+delete 23 dir(s) (61.3 GB)? [y/N]: y
+freed 61.3 GB
+```
+
+## install
+
+```
+pip install cull
+```
+
+## usage
+
+```
+cull [PATH]                  scan PATH (default: current dir)
+  --older-than DAYS          only show caches untouched for N days (default: 90)
+  --delete                   interactively pick what to remove
+  --all                      delete everything found without asking
+  --dry-run                  show what would go, don't touch anything
+```
+
+## what it looks for
+
+- `node_modules`, `.next`, `.nuxt`, `.svelte-kit`, `.parcel-cache`, `.turbo`
+- `.venv`, `venv`, `.virtualenv`, `.tox`
+- `__pycache__`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`
+- `dist`, `build`, `out` (inside project directories)
+- `.gradle`, `.angular`, `.sass-cache`
+- `target` (only inside Rust or Maven projects)
+
+## what it won't do
+
+It won't scan for "large files" generically. It won't suggest you delete your Downloads folder or anything outside the above list. The whole point is that it only removes things you can safely recreate by running `npm install` or `pip install` again.
+
+It also won't run automatically or add itself to your startup. You run it when you want to run it.
+
+## "last commit" column
+
+cull tries to find the last git commit in the parent project. If there's no git repo, it falls back to the directory's modification time. The commit date is more reliable — copying files around updates mtime but doesn't change when you actually worked on the project.
+
+## license
+
+MIT

devcull-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+cull/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+cull/__main__.py,sha256=tBonSz1D22vdWC05SzTjRxMyJGHE07Upl-Wsciig7Lo,31
+cull/cli.py,sha256=0GNCS0HsCILZ3HFyPhWBdMireRqQUUrBynaI_dnsVJo,5786
+cull/scan.py,sha256=S6eg4Zz6Yr2gSfKoi0rVeP1Ck-OrTtXF6_wpiwglgAI,4415
+devcull-0.1.0.dist-info/METADATA,sha256=p6HRmTZkN1Uw7TdMXge4uxf6pwfFrTSZXGa5AlPYC1k,2624
+devcull-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+devcull-0.1.0.dist-info/entry_points.txt,sha256=WW4h2nPFJjgc74nd6oPUaBYsf3HGfmkPa_IVil9gSSA,38
+devcull-0.1.0.dist-info/top_level.txt,sha256=mnLdGAQAr6_XdZQHse8OrLmQM8PWEa20JMh5ZAeNrls,5
+devcull-0.1.0.dist-info/RECORD,,

devcull-0.1.0.dist-info/WHEEL

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

devcull-0.1.0.dist-info/entry_points.txt

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

devcull-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cull