devklean 1.0.0__py3-none-any.whl

devklean/deletion/safety.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Sequence
+
+from devklean.models import CleanableItem
+
+
+@dataclass(frozen=True)
+class SafetyViolation:
+    """A single safety rule that a path violated."""
+
+    rule: str
+    path: str
+    message: str
+
+
+def _posix_protected_paths() -> set[str]:
+    paths = {
+        "/",
+        "/bin",
+        "/sbin",
+        "/boot",
+        "/dev",
+        "/etc",
+        "/lib",
+        "/lib32",
+        "/lib64",
+        "/proc",
+        "/sys",
+        "/usr",
+        "/var",
+        "/opt",
+        "/root",
+        "/run",
+        "/srv",
+    }
+    if sys.platform == "darwin":
+        paths |= {
+            "/System",
+            "/Library",
+            "/Applications",
+            "/private",
+            "/cores",
+            "/Volumes",
+        }
+    return paths
+
+
+def _windows_protected_paths() -> set[str]:
+    paths: set[str] = set()
+    system_root = os.environ.get("SystemRoot")
+    if system_root:
+        paths.add(system_root)
+    system_drive = os.environ.get("SystemDrive", "C:")
+    paths.add(system_drive + "\\")
+    paths.add(system_drive + "\\Program Files")
+    paths.add(system_drive + "\\Program Files (x86)")
+    return paths
+
+
+def protected_system_paths() -> frozenset[str]:
+    """Return the platform-aware set of protected system directories.
+
+    Paths are normalized (and lower-cased on Windows) for exact-match
+    comparison against a resolved real path.
+    """
+    raw = _windows_protected_paths() if os.name == "nt" else _posix_protected_paths()
+    return frozenset(_normalize(path) for path in raw)
+
+
+def _normalize(path: str) -> str:
+    normalized = os.path.normpath(path)
+    if os.name == "nt":
+        return normalized.lower()
+    return normalized
+
+
+class SafetyValidator:
+    """The single place safety checks live for all deletion strategies.
+
+    Every rule is checked here so strategies never duplicate validation.
+    """
+
+    def __init__(
+        self,
+        allow_symlinks: bool = False,
+        protected_paths: frozenset[str] | None = None,
+    ) -> None:
+        self._allow_symlinks = allow_symlinks
+        # Normalize whatever set we hold so injected protected_paths match the
+        # same way the default set does (_normalize is idempotent). Without this
+        # an injected raw path never matches the normalized candidate on Windows,
+        # where _normalize also lower-cases.
+        raw = protected_paths if protected_paths is not None else protected_system_paths()
+        self._protected = frozenset(_normalize(path) for path in raw)
+
+    def validate(self, path: str) -> SafetyViolation | None:
+        """Return the first violated rule for ``path``, or None if safe.
+
+        Structural location rules (root, home, mount, protected) are checked
+        before the symlink rule, and against both the literal and the resolved
+        path. This matters on macOS, where ``/etc``, ``/var``, and ``/tmp`` are
+        themselves symlinks into ``/private``: such a path must be reported as a
+        protected system directory — and must not be bypassable with
+        ``--allow-symlinks`` — rather than as a plain symbolic link.
+        """
+        real = os.path.realpath(path)
+
+        if real == os.path.abspath(os.sep) or self._normalized(real) == os.sep:
+            return SafetyViolation(
+                rule="filesystem_root",
+                path=path,
+                message=f"Refusing to delete '{path}': it is the filesystem root.",
+            )
+
+        home = self._home_dir()
+        if home is not None and self._normalized(real) == home:
+            return SafetyViolation(
+                rule="home_directory",
+                path=path,
+                message=f"Refusing to delete '{path}': it is your home directory.",
+            )
+
+        if os.path.ismount(real):
+            return SafetyViolation(
+                rule="mount_point",
+                path=path,
+                message=f"Refusing to delete '{path}': it is a mounted drive root.",
+            )
+
+        if self._normalized(path) in self._protected or self._normalized(real) in self._protected:
+            return SafetyViolation(
+                rule="protected_system_directory",
+                path=path,
+                message=f"Refusing to delete '{path}': protected system directory.",
+            )
+
+        if not self._allow_symlinks and os.path.islink(path):
+            return SafetyViolation(
+                rule="symlink",
+                path=path,
+                message=(
+                    f"Refusing to delete '{path}': it is a symbolic link "
+                    f"(use --allow-symlinks to override)."
+                ),
+            )
+
+        return None
+
+    def partition(
+        self,
+        items: Sequence[CleanableItem],
+    ) -> tuple[list[CleanableItem], list[tuple[CleanableItem, SafetyViolation]]]:
+        """Split items into (safe, blocked) where blocked carries the violation."""
+        safe: list[CleanableItem] = []
+        blocked: list[tuple[CleanableItem, SafetyViolation]] = []
+        for item in items:
+            violation = self.validate(item.path)
+            if violation is None:
+                safe.append(item)
+            else:
+                blocked.append((item, violation))
+        return safe, blocked
+
+    def _normalized(self, real: str) -> str:
+        return _normalize(real)
+
+    def _home_dir(self) -> str | None:
+        try:
+            return _normalize(os.path.realpath(Path.home()))
+        except (RuntimeError, OSError):
+            return None

devklean/deletion/trash.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from send2trash import send2trash
+
+from devklean.deletion.metadata import MetadataManager
+from devklean.deletion.safety import SafetyValidator
+from devklean.logging_setup import get_logger
+from devklean.models import CleanableItem, DeleteFailure, DeleteResult
+
+# The single deletion backend is the native OS trash (Recycle Bin on Windows,
+# ~/.Trash on macOS, the freedesktop trash on Linux) via send2trash. There is
+# only one method, so the name recorded in metadata/history is a literal.
+STRATEGY_NAME = "trash"
+
+
+def delete_items(
+    items: Sequence[CleanableItem],
+    total_size: int,
+    *,
+    validator: SafetyValidator | None = None,
+    metadata_manager: MetadataManager | None = None,
+    dry_run: bool = False,
+) -> DeleteResult:
+    """Validate, then move safe items to the native OS trash via ``send2trash``.
+
+    Safety validation runs first; only validated ("safe") items are ever passed
+    to ``send2trash``. Under ``dry_run`` the function returns the planned result
+    *before any ``send2trash`` call is reachable* — the structural guarantee
+    that a dry run performs no filesystem operations. Successful deletions are
+    recorded in the metadata store (used by ``history`` and ``doctor``).
+    """
+    validator = validator or SafetyValidator()
+    safe, blocked = validator.partition(items)
+    blocked_failures = tuple(
+        DeleteFailure(path=item.path, error=violation.message) for item, violation in blocked
+    )
+    safe_total = sum(item.size for item in safe)
+    logger = get_logger()
+
+    if dry_run:
+        # Structural dry-run guard: no send2trash call below is reachable.
+        result = DeleteResult(
+            deleted=tuple(item.path for item in safe),
+            failed=blocked_failures,
+            total_size=safe_total,
+        )
+        logger.info(
+            "dry-run plan strategy=%s would_delete=%d size=%d",
+            STRATEGY_NAME,
+            result.deleted_count,
+            result.total_size,
+        )
+        return result
+
+    deleted: list[str] = []
+    failures: list[DeleteFailure] = []
+    for item in safe:
+        try:
+            send2trash(item.path)
+            deleted.append(item.path)
+        except OSError as exc:
+            # TrashPermissionError subclasses OSError; ENOENT/EACCES and
+            # platform-specific failures surface here too. Report the path and
+            # keep going so one bad item never aborts the batch.
+            failures.append(DeleteFailure(path=item.path, error=str(exc)))
+
+    result = DeleteResult(
+        deleted=tuple(deleted),
+        failed=tuple(failures) + blocked_failures,
+        total_size=safe_total,
+    )
+
+    for path in result.deleted:
+        logger.info("deleted strategy=%s path=%s", STRATEGY_NAME, path)
+    for failure in result.failed:
+        logger.warning("delete failed path=%s error=%s", failure.path, failure.error)
+    logger.info(
+        "deletion summary strategy=%s deleted=%d failed=%d size=%d",
+        STRATEGY_NAME,
+        result.deleted_count,
+        result.failed_count,
+        result.total_size,
+    )
+
+    manager = metadata_manager or MetadataManager()
+    manager.record_successes(items, result, STRATEGY_NAME)
+    return result

devklean/formatting.py

@@ -0,0 +1,31 @@
+from datetime import datetime
+
+
+def format_size(size_bytes: float) -> str:
+    for unit in ["B", "KB", "MB", "GB"]:
+        if size_bytes < 1024:
+            return f"{size_bytes:.1f} {unit}"
+        size_bytes /= 1024
+    return f"{size_bytes:.1f} TB"
+
+
+def format_timestamp(value: str) -> str:
+    """Render a stored UTC ISO timestamp as local ``YYYY-MM-DD HH:MM``.
+
+    Falls back to the raw value if it cannot be parsed.
+    """
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError:
+        return value
+    return parsed.astimezone().strftime("%Y-%m-%d %H:%M")
+
+
+def truncate(text: str, max_len: int) -> str:
+    if max_len <= 0:
+        return ""
+    if len(text) <= max_len:
+        return text
+    if max_len <= 3:
+        return text[:max_len]
+    return text[: max_len - 3] + "..."

devklean/logging_setup.py

@@ -0,0 +1,74 @@
+"""File-based structured logging, kept entirely separate from terminal output.
+
+The renderers own everything the user sees on stdout/stderr. This logger writes
+detail to a rotating file and never attaches a console handler, so the two
+concerns cannot interfere.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+_LOGGER_NAME = "devklean"
+_MAX_BYTES = 1_000_000
+_BACKUP_COUNT = 5
+
+
+def get_log_path() -> Path:
+    """Return the rotating log file path (XDG cache / Windows LOCALAPPDATA aware).
+
+    An explicit ``XDG_CACHE_HOME`` override is honored on every platform; the
+    Windows-native ``LOCALAPPDATA`` location is only the fallback when it is unset.
+    """
+    cache = os.environ.get("XDG_CACHE_HOME")
+    if cache:
+        return Path(cache) / "devklean" / "logs" / "latest.log"
+
+    if sys.platform == "win32":
+        base = os.environ.get("LOCALAPPDATA")
+        root = Path(base) if base else Path.home() / "AppData" / "Local"
+        return root / "devklean" / "logs" / "latest.log"
+
+    return Path.home() / ".cache" / "devklean" / "logs" / "latest.log"
+
+
+def get_logger() -> logging.Logger:
+    return logging.getLogger(_LOGGER_NAME)
+
+
+def configure_logging(level: int = logging.INFO) -> logging.Logger:
+    """Configure the devklean file logger. Idempotent and re-pointable."""
+    logger = get_logger()
+    logger.setLevel(level)
+    logger.propagate = False
+
+    # Reset handlers so repeated calls (and tests pointing elsewhere) re-target.
+    for handler in list(logger.handlers):
+        logger.removeHandler(handler)
+        handler.close()
+
+    try:
+        log_path = get_log_path()
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        handler = RotatingFileHandler(
+            log_path, maxBytes=_MAX_BYTES, backupCount=_BACKUP_COUNT, encoding="utf-8"
+        )
+        handler.setFormatter(
+            logging.Formatter(
+                fmt="%(asctime)s %(levelname)s %(message)s",
+                datefmt="%Y-%m-%dT%H:%M:%S%z",
+            )
+        )
+        logger.addHandler(handler)
+    except OSError:
+        # Logging must never break the CLI; degrade to no file logging.
+        logger.addHandler(logging.NullHandler())
+    return logger
+
+
+def log_invocation(argv: list[str], command: str | None) -> None:
+    get_logger().info("invoke command=%s argv=%s", command, " ".join(argv))

devklean/models.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CleanableItem:
+    """A discovered directory that devklean can remove."""
+
+    path: str
+    name: str
+    size: int
+    display_label: str
+
+
+@dataclass(frozen=True)
+class DeleteFailure:
+    path: str
+    error: str
+
+
+@dataclass(frozen=True)
+class DeleteResult:
+    deleted: tuple[str, ...]
+    failed: tuple[DeleteFailure, ...]
+    total_size: int
+
+    @property
+    def deleted_count(self) -> int:
+        return len(self.deleted)
+
+    @property
+    def failed_count(self) -> int:
+        return len(self.failed)

devklean/output/__init__.py

@@ -0,0 +1,5 @@
+from devklean.output.base import Renderer
+from devklean.output.json import JsonRenderer
+from devklean.output.text import TextRenderer
+
+__all__ = ["JsonRenderer", "Renderer", "TextRenderer"]

devklean/output/base.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Protocol, Sequence
+
+from devklean.deletion.history import HistoryOperation
+from devklean.models import CleanableItem, DeleteResult
+
+
+class Renderer(Protocol):
+    """Output abstraction for presenting devklean results to the user."""
+
+    def scan_start(self, root: str) -> None: ...
+
+    def scan_summary(self, items: list[CleanableItem]) -> int: ...
+
+    def nothing_to_clean(self) -> None: ...
+
+    def dry_run_nothing_deleted(self) -> None: ...
+
+    def dry_run_selected(self, count: int) -> None: ...
+
+    def aborted(self) -> None: ...
+
+    def no_items_selected(self) -> None: ...
+
+    def invalid_directory(self, path: str) -> None: ...
+
+    def confirm_prompt(self, count: int, total_size: int = 0) -> str: ...
+
+    def deletion_result(self, result: DeleteResult) -> None: ...
+
+    def permission_warnings(self, paths: Sequence[str]) -> None: ...
+
+    def history(
+        self,
+        operations: Sequence[HistoryOperation],
+        invalid_count: int,
+    ) -> None: ...

devklean/output/console.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import os
+import sys
+from typing import TextIO
+
+from devklean.output.theme import Palette, get_theme
+
+# Semantic symbols — fixed across every command and renderer.
+SYM_SUCCESS = "✓"
+SYM_ERROR = "✗"
+SYM_WARNING = "⚠"
+SYM_INFO = "•"
+
+_ROLE_TO_CODE = {
+    "success": "green",
+    "error": "red",
+    "warning": "yellow",
+    "info": "cyan",
+    "detail": "dim",
+    "bold": "bold",
+}
+
+
+def should_use_color(stream: TextIO, theme_name: str) -> bool:
+    """Color is on only when NO_COLOR is unset, stream is a tty, theme != mono."""
+    if os.environ.get("NO_COLOR") is not None:
+        return False
+    if theme_name == "mono":
+        return False
+    isatty = getattr(stream, "isatty", None)
+    return bool(isatty and isatty())
+
+
+class Console:
+    """Centralized, color-gated terminal output with a fixed symbol scheme."""
+
+    def __init__(
+        self,
+        stream: TextIO | None = None,
+        theme: str = "default",
+        color: bool | None = None,
+    ) -> None:
+        self._stream = stream if stream is not None else sys.stdout
+        self._theme = get_theme(theme)
+        self._use_color = color if color is not None else should_use_color(self._stream, theme)
+
+    @property
+    def palette(self) -> Palette:
+        return self._theme.palette
+
+    @property
+    def use_color(self) -> bool:
+        return self._use_color
+
+    def code(self, role: str) -> str:
+        """Return the ANSI code for a semantic role, or '' when color is off."""
+        if not self._use_color:
+            return ""
+        attr = _ROLE_TO_CODE.get(role)
+        return getattr(self.palette, attr) if attr else ""
+
+    @property
+    def reset(self) -> str:
+        return self.palette.reset if self._use_color else ""
+
+    def paint(self, text: str, role: str) -> str:
+        """Wrap text in the role's color, or return it unchanged when color is off."""
+        code = self.code(role)
+        if not code:
+            return text
+        return f"{code}{text}{self.reset}"
+
+    def _line(self, symbol: str, role: str, message: str) -> None:
+        prefix = self.paint(symbol, role)
+        print(f"{prefix} {message}", file=self._stream)
+
+    def success(self, message: str) -> None:
+        self._line(SYM_SUCCESS, "success", message)
+
+    def error(self, message: str) -> None:
+        self._line(SYM_ERROR, "error", message)
+
+    def warning(self, message: str) -> None:
+        self._line(SYM_WARNING, "warning", message)
+
+    def info(self, message: str) -> None:
+        self._line(SYM_INFO, "info", message)
+
+    def detail(self, message: str) -> None:
+        print(self.paint(message, "detail"), file=self._stream)
+
+    def plain(self, message: str = "") -> None:
+        print(message, file=self._stream)

devklean/output/history_payload.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Sequence
+
+from devklean.deletion.history import HistoryOperation
+from devklean.formatting import format_size
+
+HISTORY_OUTPUT_VERSION = "1.0"
+
+
+def build_history_payload(operations: Sequence[HistoryOperation]) -> dict:
+    """Build the canonical history result structure for renderers and tooling."""
+    total_reclaimed_size = sum(op.reclaimed_size for op in operations)
+
+    return {
+        "version": HISTORY_OUTPUT_VERSION,
+        "operations": [serialize_history_operation(op) for op in operations],
+        "summary": {
+            "count": len(operations),
+            "total_reclaimed_size": total_reclaimed_size,
+            "formatted_total_reclaimed_size": format_size(total_reclaimed_size),
+        },
+    }
+
+
+def serialize_history_operation(operation: HistoryOperation) -> dict:
+    return {
+        "run_id": operation.run_id,
+        "timestamp": operation.timestamp,
+        "strategy": operation.strategy,
+        "item_count": operation.item_count,
+        "reclaimed_size": operation.reclaimed_size,
+        "formatted_reclaimed_size": format_size(operation.reclaimed_size),
+    }

devklean/output/json.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import json
+import sys
+from typing import Sequence
+
+from devklean.deletion.history import HistoryOperation
+from devklean.models import CleanableItem, DeleteResult
+from devklean.output.history_payload import build_history_payload
+from devklean.output.scan_payload import (
+    build_error_payload,
+    build_scan_payload,
+)
+
+
+class JsonRenderer:
+    """Machine-readable JSON output for tooling and automation."""
+
+    def __init__(self, *, stream=None) -> None:
+        self._stream = stream if stream is not None else sys.stdout
+        self._root = ""
+        self._permission_errors: list[str] = []
+
+    def scan_start(self, root: str) -> None:
+        self._root = root
+
+    def scan_summary(self, items: list[CleanableItem]) -> int:
+        payload = build_scan_payload(self._root, items, self._permission_errors)
+        self._emit(payload)
+        return payload["summary"]["total_size"]
+
+    def nothing_to_clean(self) -> None:
+        self._emit(build_scan_payload(self._root, [], self._permission_errors))
+
+    def dry_run_nothing_deleted(self) -> None:
+        pass
+
+    def dry_run_selected(self, count: int) -> None:
+        pass
+
+    def aborted(self) -> None:
+        pass
+
+    def no_items_selected(self) -> None:
+        pass
+
+    def invalid_directory(self, path: str) -> None:
+        self._emit(
+            build_error_payload(
+                "invalid_directory",
+                f"'{path}' is not a directory.",
+            )
+        )
+
+    def confirm_prompt(self, count: int, total_size: int = 0) -> str:
+        raise NotImplementedError("confirm_prompt is not supported in JSON mode")
+
+    def deletion_result(self, result: DeleteResult) -> None:
+        pass
+
+    def permission_warnings(self, paths) -> None:
+        # Captured here and emitted in the scan payload so JSON consumers see
+        # the same skipped-path information the text renderer prints.
+        self._permission_errors = list(paths)
+
+    def history(
+        self,
+        operations: Sequence[HistoryOperation],
+        invalid_count: int,
+    ) -> None:
+        self._emit(build_history_payload(operations))
+
+    def _emit(self, payload: dict) -> None:
+        json.dump(payload, self._stream, indent=2)
+        self._stream.write("\n")