devcleaner-cli 1.0.0__py3-none-any.whl

dev_cleaner/__init__.py

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

dev_cleaner/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from dev_cleaner.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

dev_cleaner/cleaners/__init__.py

@@ -0,0 +1 @@
+# __init__.py

dev_cleaner/cleaners/base.py

@@ -0,0 +1,8 @@
+from pathlib import Path, PurePosixPath
+from typing import Protocol
+
+
+class FileSystemCleaner(Protocol):
+    def remove(self, path: Path | PurePosixPath) -> None:
+        """Remove a directory from the filesystem."""
+        ...

dev_cleaner/cleaners/native.py

@@ -0,0 +1,18 @@
+import os
+import shutil
+import stat
+from pathlib import Path
+
+
+def _handle_remove_error(function, path, exc_info) -> None:
+    # Read-only files (common inside node_modules on Windows) block rmtree.
+    os.chmod(path, stat.S_IWRITE)
+    function(path)
+
+
+class NativeCleaner:
+    def remove(self, path: Path) -> None:
+        if not path.is_dir():
+            return
+
+        shutil.rmtree(path, onexc=_handle_remove_error)

dev_cleaner/cleaners/wsl.py

@@ -0,0 +1,37 @@
+import shutil
+import subprocess
+from pathlib import PurePosixPath
+
+
+class WslCleaner:
+    def __init__(self, distribution: str = "Ubuntu"):
+        if shutil.which("wsl") is None:
+            raise ValueError(
+                "The wsl backend requires Windows with WSL installed. "
+                "Use the native backend on Linux."
+            )
+
+        self.distribution = distribution
+
+    def remove(self, path: PurePosixPath) -> None:
+        result = subprocess.run(
+            [
+                "wsl",
+                "-d",
+                self.distribution,
+                "--",
+                "rm",
+                "-rf",
+                "--",
+                str(path),
+            ],
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            message = result.stderr.strip() or result.stdout.strip()
+
+            raise RuntimeError(
+                message or f"wsl rm failed with exit code {result.returncode}"
+            )

dev_cleaner/cli/__init__.py

@@ -0,0 +1 @@
+# __init__.py

dev_cleaner/cli/interface.py

@@ -0,0 +1,272 @@
+import os
+import sys
+import threading
+import time
+from typing import TextIO
+
+from dev_cleaner import __version__
+from dev_cleaner.core.cleaner import Cleaner, CleanupReport
+
+GREEN = "32"
+RED = "31"
+YELLOW = "33"
+CYAN = "36"
+DIM = "2"
+
+LABEL_WIDTH = 12
+SPINNER_FRAMES = "|/-\\"
+SPINNER_INTERVAL = 0.1
+SPINNER_DELAY = 0.2
+STATUS_PROJECT_WIDTH = 20
+
+
+def _enable_windows_ansi(stream: TextIO) -> None:
+    if os.name != "nt":
+        return
+
+    try:
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32
+        handle_id = -12 if stream is sys.stderr else -11
+        handle = kernel32.GetStdHandle(handle_id)
+        mode = ctypes.c_uint32()
+
+        if kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+            kernel32.SetConsoleMode(handle, mode.value | 0x0004)
+    except Exception:
+        pass
+
+
+def supports_color(stream: TextIO) -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+
+    if os.environ.get("TERM") == "dumb":
+        return False
+
+    if not (hasattr(stream, "isatty") and stream.isatty()):
+        return False
+
+    _enable_windows_ansi(stream)
+
+    return True
+
+
+def backend_label(backend: str, distribution: str | None) -> str:
+    if backend == "wsl":
+        return f"wsl:{distribution}"
+
+    return "native"
+
+
+def plural(count: int, word: str) -> str:
+    suffix = "" if count == 1 else "s"
+
+    return f"{count} {word}{suffix}"
+
+
+def supports_animation(stream: TextIO) -> bool:
+    if os.environ.get("TERM") == "dumb":
+        return False
+
+    return hasattr(stream, "isatty") and stream.isatty()
+
+
+def format_elapsed(seconds: float) -> str:
+    total = int(seconds)
+    minutes, secs = divmod(total, 60)
+    hours, minutes = divmod(minutes, 60)
+
+    if hours:
+        return f"{hours}:{minutes:02d}:{secs:02d}"
+
+    return f"{minutes}:{secs:02d}"
+
+
+def shorten(text: str, width: int = STATUS_PROJECT_WIDTH) -> str:
+    if len(text) <= width:
+        return text
+
+    return text[: width - 3] + "..."
+
+
+class Spinner:
+    """Single-line spinner with an elapsed timer, rendered only on a TTY."""
+
+    def __init__(self, stream: TextIO, enabled: bool):
+        self.stream = stream
+        self.enabled = enabled
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._status = ""
+        self._start = 0.0
+        self._width = 0
+
+    def __enter__(self) -> "Spinner":
+        self._start = time.monotonic()
+
+        if self.enabled:
+            self._thread = threading.Thread(target=self._spin, daemon=True)
+            self._thread.start()
+
+        return self
+
+    def __exit__(self, exc_type, exc, traceback) -> None:
+        self._stop.set()
+
+        if self._thread is not None:
+            self._thread.join()
+
+        if self._width:
+            self.stream.write("\r" + " " * self._width + "\r")
+            self.stream.flush()
+
+    def update(self, status: str) -> None:
+        self._status = status
+
+    def _spin(self) -> None:
+        index = 0
+
+        while not self._stop.wait(SPINNER_INTERVAL):
+            if time.monotonic() - self._start < SPINNER_DELAY:
+                continue
+
+            elapsed = format_elapsed(time.monotonic() - self._start)
+            frame = SPINNER_FRAMES[index % len(SPINNER_FRAMES)]
+            line = f"{frame} {self._status} {elapsed}"
+
+            self._width = max(self._width, len(line))
+            self.stream.write("\r" + line.ljust(self._width))
+            self.stream.flush()
+            index += 1
+
+
+class CLI:
+    def __init__(self, out: TextIO | None = None, err: TextIO | None = None):
+        self.out = out if out is not None else sys.stdout
+        self.err = err if err is not None else sys.stderr
+        self.out_color = supports_color(self.out)
+        self.err_color = supports_color(self.err)
+
+    def style(self, text: str, code: str, *, err: bool = False) -> str:
+        enabled = self.err_color if err else self.out_color
+
+        if not enabled:
+            return text
+
+        return f"\033[{code}m{text}\033[0m"
+
+    def show_header(
+        self,
+        workspace: str,
+        backend: str,
+        distribution: str | None,
+    ) -> None:
+        version = self.style(f"dev-cleaner {__version__}", DIM)
+        label = backend_label(backend, distribution)
+
+        print(f"{version} | {label} | {workspace}", file=self.out)
+
+    def confirm(self, targets: list[str]) -> bool:
+        names = ", ".join(targets)
+
+        self.out.write(f"Remove {names} from every project? [y/N] ")
+        self.out.flush()
+
+        try:
+            answer = sys.stdin.readline()
+        except KeyboardInterrupt:
+            self.out.write("\n")
+            return False
+
+        if not answer:
+            self.out.write("\n")
+            return False
+
+        return answer.strip().lower() in {"y", "yes"}
+
+    def show_results(self, report: CleanupReport, dry_run: bool = False) -> None:
+        for result in report.results:
+            path = f"{result.project}/{result.target}"
+
+            if not result.success:
+                label = self.style(f"{'failed':<{LABEL_WIDTH}}", RED, err=True)
+                print(f"{label} {path}  {result.error}", file=self.err)
+                continue
+
+            if dry_run:
+                label = self.style(f"{'would remove':<{LABEL_WIDTH}}", CYAN)
+            else:
+                label = self.style(f"{'removed':<{LABEL_WIDTH}}", GREEN)
+
+            print(f"{label} {path}", file=self.out)
+
+    def show_summary(
+        self,
+        report: CleanupReport,
+        dry_run: bool = False,
+        elapsed: float | None = None,
+    ) -> None:
+        projects = plural(report.projects_scanned, "project")
+        removed = len(report.removed)
+        failed = len(report.failed)
+
+        if dry_run:
+            summary = f"{removed} matched ({projects}) [dry run]"
+        elif failed:
+            summary = f"{removed} removed, {failed} failed ({projects})"
+        else:
+            summary = f"{removed} removed ({projects})"
+
+        if elapsed is not None and not dry_run and elapsed >= 1.0:
+            summary += f" in {format_elapsed(elapsed)}"
+
+        code = YELLOW if failed else GREEN
+
+        print(self.style(summary, code), file=self.out)
+
+    def run(
+        self,
+        cleaner: Cleaner,
+        workspace: str,
+        backend: str,
+        distribution: str | None = None,
+        assume_yes: bool = False,
+    ) -> int:
+        self.show_header(workspace, backend, distribution)
+        print(file=self.out)
+
+        if not cleaner.dry_run and not assume_yes:
+            if not self.confirm(cleaner.target_folders):
+                print(self.style("cancelled", YELLOW), file=self.out)
+                return 0
+
+            print(file=self.out)
+
+        action = "scanning" if cleaner.dry_run else "cleaning"
+        start = time.monotonic()
+
+        with Spinner(
+            self.out,
+            enabled=supports_animation(self.out),
+        ) as spinner:
+            spinner.update(f"{action}...")
+
+            def on_target(current: int, total: int, project, target: str) -> None:
+                name = f"{shorten(project.name)}/{target}"
+                spinner.update(f"{action} {name} ({current}/{total})")
+
+            report = cleaner.run(on_target=on_target)
+
+        elapsed = time.monotonic() - start
+
+        if not report.results:
+            print("no matching directories", file=self.out)
+            return 0
+
+        self.show_results(report, dry_run=cleaner.dry_run)
+        print(file=self.out)
+        self.show_summary(report, dry_run=cleaner.dry_run, elapsed=elapsed)
+
+        return 1 if report.failed else 0

dev_cleaner/cli/parser.py

@@ -0,0 +1,81 @@
+import argparse
+
+from dev_cleaner import __version__
+
+DEFAULT_TARGETS = [
+    "node_modules",
+    ".next",
+    "dist",
+]
+
+
+def create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="dev-cleaner",
+        description="Remove generated directories from every project in a workspace.",
+        epilog=(
+            "examples:\n"
+            "  python -m src.main -w C:/Users/me/workspace\n"
+            "  python -m src.main -w /home/me/workspace -n\n"
+            "  python -m src.main -w /home/me/workspace -t node_modules -t .venv -y\n"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument(
+        "-w",
+        "--workspace",
+        required=True,
+        metavar="PATH",
+        help="Workspace directory to scan.",
+    )
+
+    parser.add_argument(
+        "-t",
+        "--target",
+        action="append",
+        dest="targets",
+        metavar="DIR",
+        help=(
+            "Directory to remove. Repeatable. "
+            f"Defaults to: {', '.join(DEFAULT_TARGETS)}."
+        ),
+    )
+
+    parser.add_argument(
+        "-b",
+        "--backend",
+        type=str.lower,
+        choices=["native", "wsl"],
+        metavar="NAME",
+        help="Force native or wsl. Defaults to auto-detection.",
+    )
+
+    parser.add_argument(
+        "-d",
+        "--distribution",
+        metavar="DISTRO",
+        help="WSL distribution. Defaults to the detected default, then Ubuntu.",
+    )
+
+    parser.add_argument(
+        "-n",
+        "--dry-run",
+        action="store_true",
+        help="Show what would be removed without deleting anything.",
+    )
+
+    parser.add_argument(
+        "-y",
+        "--yes",
+        action="store_true",
+        help="Do not ask for confirmation.",
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    return parser

dev_cleaner/core/__init__.py

@@ -0,0 +1 @@
+# __init__.py

dev_cleaner/core/cleaner.py

@@ -0,0 +1,171 @@
+import os
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path, PurePosixPath
+
+from dev_cleaner.cleaners.base import FileSystemCleaner
+
+
+def is_link(path: Path) -> bool:
+    """True for symlinks and, on Windows, directory junctions."""
+
+    if path.is_symlink():
+        return True
+
+    is_junction = getattr(os.path, "isjunction", None)
+
+    return bool(is_junction and is_junction(path))
+
+
+@dataclass
+class CleanupResult:
+    project: str
+    target: str
+    path: Path | PurePosixPath
+    success: bool
+    error: str | None = None
+
+
+@dataclass
+class CleanupReport:
+    projects_scanned: int = 0
+    results: list[CleanupResult] = field(default_factory=list)
+
+    @property
+    def removed(self) -> list[CleanupResult]:
+        return [result for result in self.results if result.success]
+
+    @property
+    def failed(self) -> list[CleanupResult]:
+        return [result for result in self.results if not result.success]
+
+
+class Cleaner:
+    def __init__(
+        self,
+        workspace_path: Path,
+        target_folders: list[str],
+        filesystem: FileSystemCleaner,
+        wsl_workspace_path: str | None = None,
+        dry_run: bool = False,
+    ):
+        self.workspace_path = workspace_path
+        self.target_folders = target_folders
+        self.filesystem = filesystem
+        self.wsl_workspace_path = wsl_workspace_path
+        self.dry_run = dry_run
+
+        self._validate_workspace()
+        self._validate_targets()
+
+    def _validate_workspace(self) -> None:
+        anchor = self.workspace_path.anchor
+
+        if anchor and self.workspace_path == Path(anchor):
+            raise ValueError(
+                f"Refusing to scan a filesystem root: {self.workspace_path}"
+            )
+
+        if not self.workspace_path.is_dir():
+            raise NotADirectoryError(f"Workspace not found: {self.workspace_path}")
+
+    def _validate_targets(self) -> None:
+        for target in self.target_folders:
+            target_path = Path(target)
+
+            if (
+                target_path.is_absolute()
+                or len(target_path.parts) != 1
+                or target in {".", ".."}
+            ):
+                raise ValueError(f"Invalid target directory: {target}")
+
+    def _removal_path(self, target_path: Path) -> Path | PurePosixPath:
+        if self.wsl_workspace_path is None:
+            return target_path
+
+        relative_path = target_path.relative_to(self.workspace_path)
+
+        return PurePosixPath(self.wsl_workspace_path, *relative_path.parts)
+
+    def get_projects(self) -> list[Path]:
+        if not self.workspace_path.is_dir():
+            raise NotADirectoryError(f"Workspace not found: {self.workspace_path}")
+
+        return [
+            item
+            for item in self.workspace_path.iterdir()
+            if item.is_dir() and not is_link(item)
+        ]
+
+    def clean_project(
+        self,
+        project: Path,
+        on_target: Callable[[Path, str], None] | None = None,
+    ) -> list[CleanupResult]:
+        results = []
+
+        for target in self.target_folders:
+            target_path = project / target
+
+            if is_link(target_path) or not target_path.is_dir():
+                continue
+
+            if on_target:
+                on_target(project, target)
+
+            try:
+                removal_path = self._removal_path(target_path)
+
+                if not self.dry_run:
+                    self.filesystem.remove(removal_path)
+
+                results.append(
+                    CleanupResult(
+                        project=project.name,
+                        target=target,
+                        path=removal_path,
+                        success=True,
+                    )
+                )
+
+            except Exception as error:
+                results.append(
+                    CleanupResult(
+                        project=project.name,
+                        target=target,
+                        path=target_path,
+                        success=False,
+                        error=str(error),
+                    )
+                )
+
+        return results
+
+    def run(
+        self,
+        on_progress: Callable[[int, int, Path], None] | None = None,
+        on_target: Callable[[int, int, Path, str], None] | None = None,
+    ) -> CleanupReport:
+        projects = self.get_projects()
+
+        report = CleanupReport(
+            projects_scanned=len(projects),
+        )
+
+        for index, project in enumerate(projects, start=1):
+
+            def report_target(
+                target_project: Path,
+                target: str,
+                index: int = index,
+            ) -> None:
+                if on_target is not None:
+                    on_target(index, len(projects), target_project, target)
+
+            report.results.extend(self.clean_project(project, on_target=report_target))
+
+            if on_progress:
+                on_progress(index, len(projects), project)
+
+        return report

dev_cleaner/main.py

@@ -0,0 +1,180 @@
+import os
+import subprocess
+import sys
+from pathlib import Path, PurePosixPath
+
+from dev_cleaner.cleaners.base import FileSystemCleaner
+from dev_cleaner.cleaners.native import NativeCleaner
+from dev_cleaner.cleaners.wsl import WslCleaner
+from dev_cleaner.cli.interface import CLI
+from dev_cleaner.cli.parser import DEFAULT_TARGETS, create_parser
+from dev_cleaner.core.cleaner import Cleaner
+
+DEFAULT_DISTRIBUTION = "Ubuntu"
+WSL_UNC_HOST = "wsl.localhost"
+WSL_UNC_HOSTS = {WSL_UNC_HOST, "wsl$"}
+
+
+def is_wsl_unc_path(workspace: str) -> bool:
+    parts = PurePosixPath(workspace.replace("\\", "/")).parts
+
+    return len(parts) >= 3 and parts[0] == "//" and parts[1].lower() in WSL_UNC_HOSTS
+
+
+def split_wsl_unc_path(workspace: str) -> tuple[str, PurePosixPath] | None:
+    if not is_wsl_unc_path(workspace):
+        return None
+
+    parts = PurePosixPath(workspace.replace("\\", "/")).parts
+
+    if len(parts) < 4:
+        raise ValueError(
+            "Workspace must point to a directory inside the WSL distribution, "
+            "not to the distribution root."
+        )
+
+    distribution = parts[2]
+    linux_path = PurePosixPath("/", *parts[3:])
+
+    return distribution, linux_path
+
+
+def detect_backend(workspace: str) -> str:
+    """Pick a backend from the shape of the workspace path.
+
+    WSL is only considered when running on Windows, because Linux already
+    sees WSL paths natively and has no ``wsl`` command to delegate to.
+    """
+
+    if os.name != "nt":
+        return "native"
+
+    if is_wsl_unc_path(workspace):
+        return "wsl"
+
+    # A POSIX path such as /home/user/workspace is not a valid Windows path,
+    # so it must refer to a filesystem inside WSL.
+    if PurePosixPath(workspace).is_absolute() and not Path(workspace).is_absolute():
+        return "wsl"
+
+    return "native"
+
+
+def decode_wsl_output(data: bytes) -> str:
+    # wsl.exe writes UTF-16LE to pipes, which looks like ASCII with NUL bytes.
+    if b"\x00" in data:
+        text = data.decode("utf-16-le", errors="replace")
+    else:
+        text = data.decode("utf-8", errors="replace")
+
+    return text.replace("\ufeff", "").replace("\x00", "")
+
+
+def detect_default_distribution() -> str | None:
+    """Return the default WSL distribution, or None when WSL is unavailable."""
+
+    try:
+        result = subprocess.run(
+            ["wsl", "-l", "-q"],
+            capture_output=True,
+            timeout=15,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+    if result.returncode != 0:
+        return None
+
+    for line in decode_wsl_output(result.stdout).splitlines():
+        name = line.strip()
+
+        if name:
+            return name
+
+    return None
+
+
+def create_cleaner(backend: str, distribution: str) -> FileSystemCleaner:
+    if backend == "native":
+        return NativeCleaner()
+
+    return WslCleaner(distribution)
+
+
+def resolve_workspace(
+    workspace: str,
+    backend: str,
+    distribution: str | None,
+) -> tuple[Path, str | None, str]:
+    """Return the path to scan, the Linux path for WSL, and the distribution."""
+
+    if backend == "native":
+        return (
+            Path(workspace).expanduser(),
+            None,
+            distribution or DEFAULT_DISTRIBUTION,
+        )
+
+    unc = split_wsl_unc_path(workspace)
+
+    if unc is not None:
+        unc_distribution, linux_path = unc
+        distribution = distribution or unc_distribution
+    else:
+        linux_path = PurePosixPath(workspace)
+
+    if not linux_path.is_absolute():
+        raise ValueError(
+            "WSL workspace must be an absolute Linux path, "
+            "for example /home/user/workspace."
+        )
+
+    if ".." in linux_path.parts:
+        raise ValueError("WSL workspace cannot contain '..'.")
+
+    distribution = distribution or detect_default_distribution() or DEFAULT_DISTRIBUTION
+
+    scan_path = Path(f"//{WSL_UNC_HOST}/{distribution}{linux_path.as_posix()}")
+
+    return scan_path, linux_path.as_posix(), distribution
+
+
+def main() -> int:
+    args = create_parser().parse_args()
+
+    try:
+        backend = args.backend or detect_backend(args.workspace)
+
+        workspace_path, wsl_workspace_path, distribution = resolve_workspace(
+            workspace=args.workspace,
+            backend=backend,
+            distribution=args.distribution,
+        )
+
+        cleaner = Cleaner(
+            workspace_path=workspace_path,
+            target_folders=args.targets or DEFAULT_TARGETS,
+            filesystem=create_cleaner(backend, distribution),
+            wsl_workspace_path=wsl_workspace_path,
+            dry_run=args.dry_run,
+        )
+
+        return CLI().run(
+            cleaner=cleaner,
+            workspace=args.workspace,
+            backend=backend,
+            distribution=distribution if backend == "wsl" else None,
+            assume_yes=args.yes,
+        )
+
+    except KeyboardInterrupt:
+        print("\nCancelled.", file=sys.stderr)
+        return 130
+
+    except (NotADirectoryError, ValueError, OSError) as error:
+        print(f"Error: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

devcleaner_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,468 @@
+Metadata-Version: 2.5
+Name: devcleaner-cli
+Version: 1.0.0
+Summary: Remove generated directories such as node_modules, .next, and dist from every project in a workspace.
+Project-URL: Homepage, https://github.com/adonesbalica/dev-cleaner
+Project-URL: Repository, https://github.com/adonesbalica/dev-cleaner
+Project-URL: Issues, https://github.com/adonesbalica/dev-cleaner/issues
+Author-email: Adones Balica <adonesbalica@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cleanup,cli,developer-tools,disk-space,node-modules,wsl
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: ruff>=0.17; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dev-cleaner
+
+A lightweight, cross-platform CLI tool to clean unnecessary directories from development projects.
+
+`dev-cleaner` helps developers keep their workspaces clean by automatically detecting projects and removing generated or dependency directories such as `node_modules`, `.next`, and `dist`.
+
+## Table of contents
+
+- [Features](#features)
+- [Supported environments](#supported-environments)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Tutorial](#tutorial)
+- [Usage](#usage)
+- [Development](#development)
+- [Project structure](#project-structure)
+- [Architecture](#architecture)
+- [Safety](#safety)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
+
+## Features
+
+- **Cross-platform:** runs natively on Windows, Linux, and inside WSL.
+- **Automatic backend selection:** the right filesystem implementation is picked from the workspace path.
+- **Windows → WSL support:** clean Linux filesystems from Windows without leaving the terminal.
+- **Configurable targets:** defaults to `node_modules`, `.next`, and `dist`, and accepts custom targets.
+- **Safe by default:** asks for confirmation, supports `--dry-run`, skips symlinks and junctions, and refuses to scan a filesystem root.
+- **Per-operation reporting:** failures are reported per project instead of aborting the whole run.
+- **Live progress:** a spinner and elapsed timer show that a long cleanup is still running.
+- **Installable:** published on PyPI as `devcleaner-cli` and exposes the `dev-cleaner` command.
+- **No dependencies:** the CLI uses only the Python standard library.
+
+## Supported environments
+
+| Where you run it | Workspace path | Backend |
+|---|---|---|
+| Windows | `C:\Users\me\workspace` | `native` (Windows filesystem) |
+| Windows | `/home/me/workspace` | `wsl` (default distribution) |
+| Windows | `//wsl.localhost/Ubuntu/home/me/workspace` | `wsl` (distribution taken from the path) |
+| Linux | `/home/me/workspace` | `native` (Linux filesystem) |
+| Inside WSL | `/home/me/workspace` or `/mnt/c/...` | `native` (Linux filesystem) |
+
+The backend is detected automatically. Use `--backend` only to override the detection.
+
+## Requirements
+
+- Python 3.12 or higher.
+- WSL 2 with a Linux distribution such as Ubuntu (only when cleaning a Linux filesystem from Windows).
+
+No third-party packages are required.
+
+## Installation
+
+The package is published on PyPI as [`devcleaner-cli`](https://pypi.org/project/devcleaner-cli/) and installs the `dev-cleaner` command.
+
+**pipx (recommended for CLI tools):**
+
+```bash
+pipx install devcleaner-cli
+```
+
+**uv:**
+
+```bash
+uv tool install devcleaner-cli
+```
+
+**pip:**
+
+```bash
+python -m pip install --user devcleaner-cli
+```
+
+On Windows, install pipx with `py -m pip install --user pipx` and run `py -m pipx ensurepath`, then reopen the terminal.
+
+**From source:**
+
+```bash
+git clone https://github.com/adonesbalica/dev-cleaner.git
+cd dev-cleaner
+pipx install .
+```
+
+After installing, `dev-cleaner` works from any directory:
+
+```bash
+dev-cleaner --version
+```
+
+If the command is not found, reopen the terminal so the updated `PATH` is loaded, or run `python -m dev_cleaner`. The package has no runtime dependencies.
+
+## Tutorial
+
+This walkthrough creates a throwaway workspace, so nothing real is deleted. It takes about two minutes.
+
+### 1. Create a practice workspace
+
+**Windows (PowerShell):**
+
+```powershell
+$demo = Join-Path $env:TEMP "dev-cleaner-demo"
+New-Item -ItemType Directory -Force "$demo\app-a\node_modules\react" | Out-Null
+New-Item -ItemType Directory -Force "$demo\app-a\dist" | Out-Null
+New-Item -ItemType Directory -Force "$demo\app-b\.next" | Out-Null
+New-Item -ItemType Directory -Force "$demo\app-c\src" | Out-Null
+```
+
+**Linux or WSL:**
+
+```bash
+demo="$(mktemp -d)"
+mkdir -p "$demo/app-a/node_modules/react" "$demo/app-a/dist"
+mkdir -p "$demo/app-b/.next" "$demo/app-c/src"
+```
+
+You now have three projects: `app-a` and `app-b` contain generated directories, while `app-c` contains only source code.
+
+### 2. Preview the cleanup with a dry run
+
+**Windows:**
+
+```powershell
+dev-cleaner -w $demo -n
+```
+
+**Linux or WSL:**
+
+```bash
+dev-cleaner -w "$demo" -n
+```
+
+Expected output:
+
+```text
+dev-cleaner 1.0.0 | native | <workspace>
+
+would remove app-a/node_modules
+would remove app-a/dist
+would remove app-b/.next
+
+3 matched (3 projects) [dry run]
+```
+
+The first line shows the tool version, the selected backend, and the workspace you passed. Nothing has been deleted; the `[dry run]` marker confirms it. The order of the lines depends on the filesystem; the counts are what matter.
+
+### 3. Run the cleanup for real
+
+Drop `-n` and add `-y` to skip the confirmation prompt:
+
+```bash
+dev-cleaner -w "$demo" -y
+```
+
+Expected output:
+
+```text
+dev-cleaner 1.0.0 | native | <workspace>
+
+removed      app-a/node_modules
+removed      app-a/dist
+removed      app-b/.next
+
+3 removed (3 projects)
+```
+
+On a real terminal, a single-line spinner and timer appear while the directories are removed, so a slow cleanup never looks frozen:
+
+```text
+| cleaning app-a/node_modules (1/3) 0:04
+```
+
+The line is erased when the run finishes, and the summary appends the total time when it took at least one second (for example `3 removed (3 projects) in 0:04`). When the output is piped or redirected, the spinner is skipped and only the final lines are written, which keeps the output easy to parse.
+
+Without `-y`, the tool asks first:
+
+```text
+Remove node_modules, .next, dist from every project? [y/N]
+```
+
+Press `y` and Enter to continue, or Enter to cancel. The default is always **No**.
+
+### 4. Verify the result
+
+**Windows:**
+
+```powershell
+Get-ChildItem -Directory -Recurse $demo | Select-Object -ExpandProperty FullName
+```
+
+**Linux or WSL:**
+
+```bash
+find "$demo" -type d
+```
+
+Only `app-a`, `app-b`, and `app-c` (plus `app-c/src`) should remain. The generated directories are gone.
+
+### 5. Remove the practice workspace
+
+**Windows:**
+
+```powershell
+Remove-Item $demo -Recurse -Force
+```
+
+**Linux or WSL:**
+
+```bash
+rm -rf "$demo"
+```
+
+### Tutorial: clean a WSL workspace from Windows
+
+Use the Linux path of the workspace. The tool detects that it is not a Windows path and switches to the WSL backend automatically.
+
+```powershell
+# See which distributions are available
+wsl -l -q
+
+# Preview the cleanup
+dev-cleaner -w /home/me/workspace -n
+
+# Use a specific distribution if the default is not the right one
+dev-cleaner -w /home/me/workspace -d Ubuntu -n
+
+# Run it
+dev-cleaner -w /home/me/workspace -y
+```
+
+The header shows which backend and distribution were selected:
+
+```text
+dev-cleaner 1.0.0 | wsl:Ubuntu | /home/me/workspace
+```
+
+You can also pass a Windows UNC path such as `//wsl.localhost/Ubuntu/home/me/workspace`; the distribution is read from the path.
+
+### Tutorial: use custom targets
+
+Passing `-t` **replaces** the default target list, so list every directory you want to remove:
+
+```bash
+dev-cleaner -w /home/me/workspace -t node_modules -t .venv -t target -n
+```
+
+This removes only `node_modules`, `.venv`, and `target`; it does not also remove `.next` or `dist`.
+
+### Tutorial: use it in a script
+
+Use `-y` so the command never waits for input, and check the exit code:
+
+**Bash:**
+
+```bash
+dev-cleaner -w /home/me/workspace -y
+if [ $? -ne 0 ]; then
+    echo "cleanup failed" >&2
+fi
+```
+
+**PowerShell:**
+
+```powershell
+dev-cleaner -w C:/Users/me/workspace -y
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "cleanup failed"
+}
+```
+
+## Usage
+
+```bash
+dev-cleaner -w <workspace> [options]
+```
+
+### Options
+
+| Option | Description |
+|---|---|
+| `-w`, `--workspace` | Workspace directory to scan. Required. |
+| `-t`, `--target` | Directory to remove. Repeatable; replaces the defaults. Defaults to `node_modules`, `.next`, `dist`. |
+| `-b`, `--backend` | Force `native` or `wsl`. Auto-detected by default. |
+| `-d`, `--distribution` | WSL distribution to use. Defaults to the WSL default distribution, or `Ubuntu`. |
+| `-n`, `--dry-run` | Show what would be removed without deleting anything. |
+| `-y`, `--yes` | Do not ask for confirmation. |
+| `--version` | Show the version and exit. |
+
+### Progress indicator
+
+While scanning or deleting, the CLI shows one animated line with the directory being removed and an elapsed timer:
+
+```text
+/ cleaning app-a/node_modules (2/7) 0:12
+```
+
+- The spinner uses plain ASCII frames (`|`, `/`, `-`, `\`), so it works in any terminal.
+- The status updates before **each directory** is removed, so the name changes even when a single project takes a long time.
+- The timer uses `m:ss`, switching to `h:mm:ss` after one hour.
+- The line is cleared before the per-directory results are printed.
+- The summary appends `in m:ss` when the run took at least one second.
+- The spinner is **TTY-only**. Piped or redirected output never contains the animation, so logs and scripts stay clean.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success, including "nothing to remove" and a cancelled prompt. |
+| `1` | Error: invalid workspace, invalid target, failed removal, or WSL unavailable. |
+| `2` | Invalid command-line arguments. |
+| `130` | Interrupted with Ctrl+C. |
+
+### How it works
+
+1. Detects the backend from the workspace path (unless `--backend` is given).
+2. Maps the workspace to a scan path and, for WSL, to the equivalent Linux path.
+3. Lists the direct children of the workspace as projects.
+4. Checks each project for the configured target directories.
+5. Removes matching directories using the selected backend, reporting every operation.
+
+Only direct children of the workspace are treated as projects, and only direct children of each project are removed. Symlinked projects and targets, as well as Windows directory junctions, are skipped.
+
+## Development
+
+Clone the repository and create a virtual environment:
+
+```bash
+git clone https://github.com/adonesbalica/dev-cleaner.git
+cd dev-cleaner
+python -m venv .venv
+```
+
+Activate it:
+
+**Windows (PowerShell):**
+
+```powershell
+.venv\Scripts\Activate.ps1
+```
+
+**Linux / WSL:**
+
+```bash
+source .venv/bin/activate
+```
+
+Install the package in editable mode with the development tools:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Run the CLI without the console script:
+
+```bash
+python -m dev_cleaner --help
+```
+
+Run the checks and build the distribution:
+
+```bash
+ruff check src
+ruff format --check src
+python -m build
+```
+
+The build writes `dist/devcleaner_cli-<version>-py3-none-any.whl` and a source archive. See [RELEASING.md](https://github.com/adonesbalica/dev-cleaner/blob/main/RELEASING.md) for the publish steps.
+
+## Project structure
+
+```text
+dev-cleaner/
+├── src/
+│   └── dev_cleaner/
+│       ├── __init__.py
+│       ├── __main__.py
+│       ├── main.py
+│       ├── core/
+│       │   ├── __init__.py
+│       │   └── cleaner.py
+│       ├── cleaners/
+│       │   ├── __init__.py
+│       │   ├── base.py
+│       │   ├── native.py
+│       │   └── wsl.py
+│       └── cli/
+│           ├── __init__.py
+│           ├── interface.py
+│           └── parser.py
+├── pyproject.toml
+├── README.md
+├── RELEASING.md
+├── LICENSE
+└── .gitignore
+```
+
+## Architecture
+
+The project uses a strategy-based architecture to separate cleanup orchestration from filesystem operations.
+
+- **`FileSystemCleaner`:** defines the contract for filesystem cleanup implementations.
+- **`NativeCleaner`:** uses `shutil.rmtree` on the filesystem the application runs on (Windows or Linux), including retries for read-only files.
+- **`WslCleaner`:** runs `wsl -d <distribution> -- rm -rf` to remove directories inside a Linux filesystem from Windows.
+- **`Cleaner`:** handles workspace scanning, project detection, WSL path mapping, dry runs, and cleanup orchestration.
+- **`main.py`:** detects the backend, resolves the workspace paths, and wires everything together.
+- **`cli/`:** parses arguments, shows the TTY-only spinner and timer, and prints plain-text results, a summary, and the confirmation prompt. No third-party dependencies.
+
+This design allows new filesystem cleanup implementations to be added without changing the core cleanup logic.
+
+## Safety
+
+Directory removal is permanent.
+
+Before running the application, make sure that:
+
+- The workspace path is correct.
+- The target directories are the ones you intend to remove.
+- The selected backend matches your environment.
+
+Use `--dry-run` first to review what will be removed. Symlinked projects and targets are skipped, and the tool refuses to scan a filesystem root. Only direct children of the workspace are considered, so pointing `-w` at a folder that contains projects is safer than pointing it at a single project.
+
+## Troubleshooting
+
+| Problem | Cause and fix |
+|---|---|
+| `Error: Workspace not found: ...` | The path is wrong, or the WSL distribution is not running. Check the path and run `wsl -l -q` to see available distributions. |
+| `Error: The wsl backend requires Windows with WSL installed.` | You forced `-b wsl` on Linux. Remove `-b wsl`; Linux paths already work with the native backend. |
+| `Error: Refusing to scan a filesystem root: ...` | Pass the folder that contains your projects, not `/`, `C:\`, or a WSL distribution root. |
+| `Error: Invalid target directory: ...` | Targets must be a single directory name. Do not use paths such as `src/dist` or `..`. |
+| `failed ... [WinError 32]` or `Permission denied` | A file is open or read-only. Close editors, dev servers, and terminals using the directory, then retry. |
+| Nothing is removed | Only direct children of the workspace are scanned. Point `-w` at the folder containing your project folders. |
+| Paths with spaces do not work | Quote the path: `-w "C:/Users/me/My Projects"`. |
+| Colors look wrong or appear as escape codes | Set `NO_COLOR=1`, or use a terminal with ANSI support. |
+| No spinner or timer appears | The spinner is TTY-only. It is hidden when output is piped or redirected, and when `TERM=dumb`. Run the tool directly in a terminal to see it. |
+| `dev-cleaner` is not recognized | Install it with `pipx install devcleaner-cli` or `uv tool install devcleaner-cli`, then reopen the terminal so `PATH` is updated. You can always run `python -m dev_cleaner` instead. |
+
+## License
+
+This project is licensed under the MIT License.

devcleaner_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+dev_cleaner/__init__.py,sha256=J-j-u0itpEFT6irdmWmixQqYMadNl1X91TxUmoiLHMI,22
+dev_cleaner/__main__.py,sha256=IuIEzeQW7UXTs6IfuP-K7IC8RCKRcAu-n74mLVE5zi0,95
+dev_cleaner/main.py,sha256=cc2SEtRxBftfk9TxWPgpV_u9POP0wS9qk3gzBQZTiVQ,5108
+dev_cleaner/cleaners/__init__.py,sha256=5YdTwwQoP6maFB-_aV12Jf5cZJMLoUeunz-pb1XWKV0,14
+dev_cleaner/cleaners/base.py,sha256=ez3K4ptQfKTQBoKwO7-EOhYfmijzhslypQ8mB1cVedM,229
+dev_cleaner/cleaners/native.py,sha256=-FBXjTNCBa66QMeaMkvzkyJgeHulku2Ji3gW-TJvWdo,423
+dev_cleaner/cleaners/wsl.py,sha256=HtbQoQe2_vTPtIaeqnFWfiC5lK9EqOejDi8DUhEjxCg,996
+dev_cleaner/cli/__init__.py,sha256=5YdTwwQoP6maFB-_aV12Jf5cZJMLoUeunz-pb1XWKV0,14
+dev_cleaner/cli/interface.py,sha256=gG4CEyCujGmAluImSMFgdj_EKPEOvYdMBvQcvjdFhfI,7593
+dev_cleaner/cli/parser.py,sha256=MU6HyZlMh5WDC4eKltcBhMwfBn8PqQoyb_6N0vF7x0I,1926
+dev_cleaner/core/__init__.py,sha256=5YdTwwQoP6maFB-_aV12Jf5cZJMLoUeunz-pb1XWKV0,14
+dev_cleaner/core/cleaner.py,sha256=9tdpYNtunSFTitKDoc0CjIqV8EsNeXjWhoMX09oTu1U,4976
+devcleaner_cli-1.0.0.dist-info/METADATA,sha256=V8inQgEtDMW4zTV_9evWRq71pfwmspEzxVoiBYr2uxI,15578
+devcleaner_cli-1.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+devcleaner_cli-1.0.0.dist-info/entry_points.txt,sha256=weNwCHbPFbggrX7BEHfpZlh0oRib4jxKfQU71csaHoI,54
+devcleaner_cli-1.0.0.dist-info/licenses/LICENSE,sha256=GjwWVWb-7ncF_RZHaRzniNX6hDPkOkWqKqRw_O5i-Lk,1069
+devcleaner_cli-1.0.0.dist-info/RECORD,,

devcleaner_cli-1.0.0.dist-info/WHEEL

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

devcleaner_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dev-cleaner = dev_cleaner.main:main

devcleaner_cli-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 adonesbalica
+
+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.