devklean 1.0.0__py3-none-any.whl

devklean/__init__.py

@@ -0,0 +1,6 @@
+"""devklean — scan and remove node_modules / venvs to reclaim disk space."""
+
+from devklean._version import __version__
+from devklean.models import CleanableItem, DeleteFailure, DeleteResult
+
+__all__ = ["CleanableItem", "DeleteFailure", "DeleteResult", "__version__"]

devklean/__main__.py

@@ -0,0 +1,4 @@
+from devklean.cli import main
+
+if __name__ == "__main__":
+    main()

devklean/_version.py

@@ -0,0 +1,8 @@
+"""Package version for devklean.
+
+Single source of truth for the version. Hatchling reads ``__version__`` from
+this file (see ``[tool.hatch.version]`` in pyproject.toml), so a release bump is
+a one-line change here and nowhere else.
+"""
+
+__version__ = "1.0.0"

devklean/cli/__init__.py

@@ -0,0 +1,3 @@
+from devklean.cli.main import main
+
+__all__ = ["main"]

devklean/cli/commands/__init__.py

@@ -0,0 +1,4 @@
+from devklean.cli.commands.clean import run_clean
+from devklean.cli.commands.scan import run_scan
+
+__all__ = ["run_clean", "run_scan"]

devklean/cli/commands/clean.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import sys
+
+from devklean.cli.commands.common import scan_directory
+from devklean.cli.confirmation import (
+    DEFAULT_LARGE_THRESHOLD,
+    confirm_large_deletion,
+    exceeds_threshold,
+)
+from devklean.config.models import AppConfig
+from devklean.deletion import SafetyValidator, delete_items
+from devklean.models import CleanableItem
+from devklean.output.base import Renderer
+
+
+def _confirm_deletion(
+    renderer: Renderer,
+    count: int,
+    total_size: int,
+    default_yes: bool,
+    confirm_threshold: int,
+) -> bool:
+    """Return True when the user has authorized the deletion.
+
+    Large batches (>= threshold) always require a typed confirmation, even when
+    ``default_yes`` is set — config must not be able to defeat that guard.
+    """
+    if exceeds_threshold(total_size, confirm_threshold):
+        return confirm_large_deletion(count, total_size, confirm_threshold)
+    if default_yes:
+        return True
+    return input(renderer.confirm_prompt(count, total_size)).strip().lower() == "y"
+
+
+def run_standard(
+    renderer: Renderer,
+    found: list[CleanableItem],
+    dry_run: bool,
+    validator: SafetyValidator | None = None,
+    *,
+    default_yes: bool = False,
+    confirm_threshold: int = DEFAULT_LARGE_THRESHOLD,
+) -> None:
+    total_size = renderer.scan_summary(found)
+
+    if dry_run:
+        renderer.dry_run_selected(len(found))
+        return
+
+    if not _confirm_deletion(renderer, len(found), total_size, default_yes, confirm_threshold):
+        renderer.aborted()
+        return
+
+    result = delete_items(found, total_size, validator=validator)
+    renderer.deletion_result(result)
+
+
+def run_clean(
+    args,
+    renderer: Renderer,
+    config: AppConfig,
+    validator: SafetyValidator | None = None,
+) -> int:
+    """Scan and optionally delete cleanable directories."""
+    exit_code, found = scan_directory(args, renderer, config)
+    if exit_code != 0 or found is None:
+        return exit_code
+
+    defaults = config.defaults
+    default_yes = getattr(args, "yes", False) or getattr(defaults, "default_yes", False)
+    confirm_threshold = getattr(defaults, "confirm_threshold", DEFAULT_LARGE_THRESHOLD)
+
+    if args.interactive:
+        # Interactive mode relies on curses, which is unavailable on Windows.
+        # Fail with a clear message rather than crashing on the curses import.
+        if sys.platform == "win32":
+            print(
+                "devklean: interactive mode (-i/--interactive) isn't available on "
+                "Windows yet. Run without -i, or see the 'Platform support' section "
+                "of the README for details.",
+                file=sys.stderr,
+            )
+            return 2
+        # Imported lazily so non-interactive commands never load the TUI/curses
+        # stack, and to avoid a circular import (tui -> cli -> clean -> tui).
+        from devklean.tui import run_interactive
+
+        run_interactive(
+            renderer,
+            found,
+            args.dry_run,
+            validator,
+            confirm_threshold=confirm_threshold,
+        )
+    else:
+        run_standard(
+            renderer,
+            found,
+            args.dry_run,
+            validator,
+            default_yes=default_yes,
+            confirm_threshold=confirm_threshold,
+        )
+
+    return 0

devklean/cli/commands/common.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import os
+
+from devklean.config.models import AppConfig
+from devklean.logging_setup import get_logger
+from devklean.models import CleanableItem
+from devklean.output.base import Renderer
+from devklean.scanner.scanner import scan_tree
+
+
+def scan_directory(
+    args,
+    renderer: Renderer,
+    config: AppConfig,
+) -> tuple[int, list[CleanableItem] | None]:
+    """Validate the root path, scan, and report when nothing is found."""
+    root = os.path.abspath(args.path)
+    if not os.path.isdir(root):
+        renderer.invalid_directory(root)
+        return 1, None
+
+    renderer.scan_start(root)
+    report = scan_tree(root, settings=config.scan_settings)
+    get_logger().info(
+        "scan root=%s found=%d permission_errors=%d",
+        root,
+        len(report.items),
+        len(report.permission_errors),
+    )
+    if report.permission_errors:
+        renderer.permission_warnings(report.permission_errors)
+
+    if not report.items:
+        renderer.nothing_to_clean()
+        return 0, None
+
+    return 0, report.items

devklean/cli/commands/doctor.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from devklean.deletion.integrity import check_integrity
+from devklean.deletion.metadata import MetadataManager
+
+if TYPE_CHECKING:
+    from devklean.output.text import TextRenderer
+
+
+def run_doctor(args, renderer: TextRenderer, config) -> int:
+    """Inspect the metadata store and remove confirmed-corrupt records.
+
+    Text-only by design: the command is interactive (it prompts before
+    deleting), so it is always given a ``TextRenderer`` and never runs in JSON
+    mode.
+    """
+    manager = MetadataManager()
+    report = check_integrity(manager)
+
+    if report.healthy:
+        renderer.doctor_healthy()
+        return 0
+
+    renderer.doctor_corruption_report(report)
+
+    if not getattr(args, "yes", False):
+        confirm = input(renderer.doctor_confirm_prompt(len(report.corrupt))).strip().lower()
+        if confirm != "y":
+            renderer.doctor_kept()
+            return 0
+
+    removed = 0
+    for entry in report.corrupt:
+        try:
+            manager.remove_record(entry)
+            removed += 1
+        except OSError as exc:
+            renderer.doctor_remove_error(entry.path.name, str(exc))
+
+    renderer.doctor_removed(removed)
+    return 0

devklean/cli/commands/history.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from devklean.config.models import AppConfig
+from devklean.deletion.history import build_history
+from devklean.deletion.metadata import MetadataManager
+from devklean.output.base import Renderer
+
+
+def run_history(args, renderer: Renderer, config: AppConfig) -> int:
+    """Display previous cleanup operations from the metadata store."""
+    snapshot = MetadataManager().load_records()
+    operations = build_history(snapshot.records)
+    renderer.history(operations, snapshot.invalid_count)
+    return 0

devklean/cli/commands/restore.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from devklean.output.text import TextRenderer
+
+
+def run_restore(args, renderer: TextRenderer, config) -> int:
+    """Explain how to recover deleted items from the native OS trash.
+
+    devklean moves items to the operating system's own trash rather than
+    deleting them, and the OS owns that trash — devklean cannot move items back
+    programmatically. Recovery is done through the file manager's trash UI.
+
+    Text-only by design (human guidance), so it is always given a
+    ``TextRenderer`` and never runs in JSON mode.
+    """
+    renderer.restore_help()
+    return 0

devklean/cli/commands/scan.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from devklean.cli.commands.common import scan_directory
+from devklean.config.models import AppConfig
+from devklean.output.base import Renderer
+
+
+def run_scan(args, renderer: Renderer, config: AppConfig) -> int:
+    """Scan for cleanable directories and display results without deleting."""
+    exit_code, found = scan_directory(args, renderer, config)
+    if exit_code != 0 or found is None:
+        return exit_code
+
+    renderer.scan_summary(found)
+    renderer.dry_run_nothing_deleted()
+    return 0

devklean/cli/confirmation.py

@@ -0,0 +1,51 @@
+"""Large-deletion typed confirmation.
+
+This is a *batch-magnitude* gate, deliberately separate from the per-path
+``SafetyValidator``. The validator answers "is this path safe to delete?"; this
+answers "is this batch large enough to demand an explicit, typed confirmation?".
+The two concerns do not share logic.
+
+The gate is NOT bypassed by ``default_yes``/``--yes`` — only dry-run skips it —
+because allowing config to defeat the large-deletion guard would defeat its
+purpose.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Callable, TextIO
+
+from devklean.config.models import DEFAULT_CONFIRM_THRESHOLD
+from devklean.formatting import format_size
+from devklean.output.console import Console
+
+# Re-export the single source of truth (config.models) under the name the
+# confirmation flow uses.
+DEFAULT_LARGE_THRESHOLD = DEFAULT_CONFIRM_THRESHOLD
+
+_CONFIRM_WORD = "DELETE"
+
+
+def exceeds_threshold(total_size: int, threshold: int) -> bool:
+    """True when a deletion is large enough to require typed confirmation."""
+    return threshold > 0 and total_size >= threshold
+
+
+def confirm_large_deletion(
+    count: int,
+    total_size: int,
+    threshold: int,
+    *,
+    input_fn: Callable[[str], str] | None = None,
+    stream: TextIO | None = None,
+) -> bool:
+    """Prompt for an explicit typed confirmation; return True only on 'DELETE'."""
+    # Resolve at call time so a monkeypatched builtins.input is honored.
+    ask = input_fn if input_fn is not None else input
+    out = stream if stream is not None else sys.stderr
+    console = Console(stream=out)
+    word = "directory" if count == 1 else "directories"
+    console.warning(f"About to delete {count} {word} (~{format_size(total_size)}).")
+    console.detail(f"This exceeds the {format_size(threshold)} safety threshold.")
+    answer = ask(f"Type {_CONFIRM_WORD} to confirm: ")
+    return answer.strip() == _CONFIRM_WORD

devklean/cli/dispatcher.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import sys
+from typing import Callable
+
+from devklean.cli.commands.clean import run_clean
+from devklean.cli.commands.doctor import run_doctor
+from devklean.cli.commands.history import run_history
+from devklean.cli.commands.restore import run_restore
+from devklean.cli.commands.scan import run_scan
+from devklean.cli.parser import IMPLEMENTED_COMMANDS, RESERVED_COMMANDS
+from devklean.config.models import AppConfig
+from devklean.deletion import SafetyValidator
+from devklean.output.base import Renderer
+
+CommandHandler = Callable[..., int]
+
+DEFAULT_COMMAND = "clean"
+
+_COMMANDS: dict[str, CommandHandler] = {
+    "scan": run_scan,
+    "clean": run_clean,
+    "history": run_history,
+    "doctor": run_doctor,
+    "restore": run_restore,
+}
+
+
+def dispatch(args, renderer: Renderer, config: AppConfig) -> int:
+    """Route parsed arguments to the appropriate command handler."""
+    command = getattr(args, "command", None) or DEFAULT_COMMAND
+
+    if command in RESERVED_COMMANDS:
+        print(f"devklean {command}: not yet implemented", file=sys.stderr)
+        return 2
+
+    if command not in IMPLEMENTED_COMMANDS:
+        print(f"devklean: unknown command {command!r}", file=sys.stderr)
+        return 2
+
+    handler = _COMMANDS[command]
+    if command == "clean":
+        allow_symlinks = getattr(args, "allow_symlinks", False)
+        return handler(args, renderer, config, SafetyValidator(allow_symlinks=allow_symlinks))
+    return handler(args, renderer, config)

devklean/cli/main.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import sys
+
+from devklean.cli.dispatcher import dispatch
+from devklean.cli.parser import build_parser, resolve_bare_invocation
+from devklean.config import ConfigManager
+from devklean.logging_setup import configure_logging, log_invocation
+from devklean.output import JsonRenderer, TextRenderer
+from devklean.output.console import Console
+
+
+def select_renderer(args, config=None):
+    theme = "default"
+    if config is not None:
+        theme = getattr(config.defaults, "theme", "default")
+    if getattr(args, "command", None) in {"scan", "history"} and getattr(args, "json", False):
+        return JsonRenderer()
+    return TextRenderer(console=Console(stream=sys.stdout, theme=theme))
+
+
+def main() -> None:
+    # Force UTF-8 on the console before anything writes output. Windows' default
+    # console codepage can't encode the Unicode symbols (⚠/✓/✗) the renderers
+    # emit, so a stock cmd.exe/PowerShell session would crash with
+    # UnicodeEncodeError. errors="replace" degrades any future unencodable
+    # character to a placeholder rather than crashing.
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+    raw_argv = list(sys.argv)
+    argv = resolve_bare_invocation(raw_argv)
+
+    configure_logging()
+
+    config_manager = ConfigManager()
+    result = config_manager.load_full()
+    config = result.config
+
+    parser = build_parser()
+    args = parser.parse_args(argv[1:])
+    args._config = config
+    config_manager.apply_defaults(args, raw_argv)
+
+    log_invocation(raw_argv, getattr(args, "command", None))
+
+    # Surface config warnings on stderr so stdout/JSON stay clean.
+    if result.warnings:
+        warn_console = Console(
+            stream=sys.stderr, theme=getattr(config.defaults, "theme", "default")
+        )
+        for warning in result.warnings:
+            warn_console.warning(warning)
+
+    renderer = select_renderer(args, config)
+    exit_code = dispatch(args, renderer, config)
+
+    if exit_code != 0:
+        sys.exit(exit_code)

devklean/cli/parser.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import argparse
+
+from devklean._version import __version__
+
+COMMAND_NAMES = frozenset(
+    {"scan", "clean", "history", "doctor", "stats", "restore", "config", "plugins"}
+)
+IMPLEMENTED_COMMANDS = frozenset({"scan", "clean", "history", "doctor", "restore"})
+RESERVED_COMMANDS = frozenset({"stats", "config", "plugins"})
+GLOBAL_OPTIONS = frozenset({"-h", "--help", "--version"})
+
+
+def _add_global_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"devklean v{__version__}",
+    )
+
+
+def _add_path_argument(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="Root directory to scan (default: current directory)",
+    )
+
+
+def _add_clean_arguments(parser: argparse.ArgumentParser) -> None:
+    _add_path_argument(parser)
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be deleted without deleting anything",
+    )
+    parser.add_argument(
+        "-i",
+        "--interactive",
+        action="store_true",
+        help="Interactively select items to delete (Linux/macOS only)",
+    )
+    parser.add_argument(
+        "--allow-symlinks",
+        action="store_true",
+        help="Permit deletion of symbolic links (blocked by default)",
+    )
+    parser.add_argument(
+        "-y",
+        "--yes",
+        action="store_true",
+        help="Skip the confirmation prompt (large deletions still require typing DELETE)",
+    )
+
+
+def _add_subparsers(parser: argparse.ArgumentParser) -> None:
+    subparsers = parser.add_subparsers(dest="command")
+
+    scan_parser = subparsers.add_parser(
+        "scan",
+        help="Scan for cleanable directories without deleting",
+    )
+    _add_path_argument(scan_parser)
+    scan_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output scan results as JSON",
+    )
+
+    clean_parser = subparsers.add_parser(
+        "clean",
+        help="Scan and remove cleanable directories",
+    )
+    _add_clean_arguments(clean_parser)
+
+    subparsers.add_parser(
+        "restore", help="Show how to recover deleted items from your system trash"
+    )
+
+    history_parser = subparsers.add_parser(
+        "history",
+        help="Show previous cleanup operations",
+    )
+    history_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output history as JSON",
+    )
+
+    doctor_parser = subparsers.add_parser(
+        "doctor",
+        help="Inspect and repair the deletion metadata store",
+    )
+    doctor_parser.add_argument(
+        "-y",
+        "--yes",
+        action="store_true",
+        help="Remove corrupt records without confirmation",
+    )
+
+    subparsers.add_parser("stats", help="Show cleanup statistics (not yet implemented)")
+    subparsers.add_parser("config", help="Manage configuration (not yet implemented)")
+    subparsers.add_parser("plugins", help="Manage plugins (not yet implemented)")
+
+
+def default_command_for_flags(args: list[str]) -> str:
+    """Pick the default subcommand for a bare top-level invocation.
+
+    With no explicit command, a bare ``--dry-run`` (without ``-i``) is a preview,
+    so it maps to ``scan``; everything else defaults to ``clean``.
+    """
+    dry_run = "--dry-run" in args
+    interactive = "-i" in args or "--interactive" in args
+    if dry_run and not interactive:
+        return "scan"
+    return "clean"
+
+
+def strip_flags(argv: list[str], flags: set[str]) -> list[str]:
+    """Remove specific flags from an argument vector."""
+    return [arg for arg in argv if arg not in flags]
+
+
+def resolve_bare_invocation(argv: list[str]) -> list[str]:
+    """Resolve a bare invocation (no explicit subcommand) to one.
+
+    devklean accepts a default-command shorthand: ``devklean`` alone, or with a
+    path/flags but no command word, runs ``clean`` (e.g. ``devklean ~/code`` ==
+    ``devklean clean ~/code``); a bare ``--dry-run`` is treated as ``scan``.
+    Explicit subcommands and global options (``--help``/``--version``) pass
+    through unchanged.
+    """
+    if len(argv) <= 1:
+        return [argv[0], "clean"]
+
+    if argv[1] in GLOBAL_OPTIONS:
+        return argv
+
+    if argv[1] in COMMAND_NAMES:
+        return argv
+
+    if not argv[1].startswith("-"):
+        command = default_command_for_flags(argv[2:])
+        rewritten = [argv[0], command, argv[1], *argv[2:]]
+        if command == "scan":
+            return strip_flags(rewritten, {"--dry-run", "--allow-symlinks"})
+        return rewritten
+
+    command = default_command_for_flags(argv[1:])
+    rewritten = [argv[0], command, *argv[1:]]
+    if command == "scan":
+        return strip_flags(rewritten, {"--dry-run", "--allow-symlinks"})
+    return rewritten
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Scan and remove node_modules/venvs to reclaim disk space.",
+    )
+    _add_global_arguments(parser)
+    _add_subparsers(parser)
+    return parser

devklean/config/__init__.py

@@ -0,0 +1,15 @@
+from devklean.config.defaults import DEFAULT_TARGETS
+from devklean.config.manager import ConfigManager
+from devklean.config.models import AppConfig, DefaultsConfig, ScanSettings
+from devklean.config.paths import get_config_path
+from devklean.config.targets import merge_targets
+
+__all__ = [
+    "AppConfig",
+    "ConfigManager",
+    "DEFAULT_TARGETS",
+    "DefaultsConfig",
+    "ScanSettings",
+    "get_config_path",
+    "merge_targets",
+]

devklean/config/defaults.py

@@ -0,0 +1,14 @@
+"""Built-in default target definitions."""
+
+from __future__ import annotations
+
+DEFAULT_TARGETS: dict[str, str] = {
+    "node_modules": "Node.js",
+    "venv": "Python venv",
+    ".venv": "Python venv",
+    "env": "Python env",
+    "__pycache__": "Python cache",
+    ".next": "Next.js build",
+    "dist": "Build output",
+    ".cache": "Cache",
+}