devtidy 0.1.0__py3-none-any.whl

devtidy/__init__.py

@@ -0,0 +1,4 @@
+"""DevTidy public package interface."""
+
+__version__ = "0.1.0"
+

devtidy/__main__.py

@@ -0,0 +1,4 @@
+from devtidy.cli import main
+
+raise SystemExit(main())
+

devtidy/cli.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from devtidy import __version__
+from devtidy.models import Candidate
+from devtidy.rules import RULES
+from devtidy.safety import UnsafePathError
+from devtidy.scanner import scan
+from devtidy.storage import archive, delete, read_history, restore
+from devtidy.units import human_size, parse_duration, parse_size
+
+
+def _size(value: str) -> int:
+    try:
+        return parse_size(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError(str(error)) from error
+
+
+def _duration(value: str) -> float:
+    try:
+        return parse_duration(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError(str(error)) from error
+
+
+def _add_scan_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("paths", nargs="*", type=Path, default=[Path.cwd()])
+    parser.add_argument("--older-than", type=_duration, default=0, metavar="30d")
+    parser.add_argument("--min-size", type=_size, default=0, metavar="100MB")
+    parser.add_argument(
+        "--category",
+        action="append",
+        choices=sorted({rule.category for rule in RULES}),
+        dest="categories",
+    )
+    parser.add_argument("--exclude", action="append", default=[], metavar="GLOB")
+    parser.add_argument("--max-depth", type=int)
+    parser.add_argument("--json", action="store_true")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="devtidy",
+        description="Safely reclaim stale developer artifacts.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command")
+
+    scan_parser = subparsers.add_parser("scan", help="find cleanup candidates")
+    _add_scan_arguments(scan_parser)
+
+    clean_parser = subparsers.add_parser("clean", help="archive or delete candidates")
+    _add_scan_arguments(clean_parser)
+    action = clean_parser.add_mutually_exclusive_group(required=True)
+    action.add_argument("--archive", action="store_true")
+    action.add_argument("--delete", action="store_true")
+    clean_parser.add_argument(
+        "--yes",
+        action="store_true",
+        help="confirm the selected cleanup action",
+    )
+
+    restore_parser = subparsers.add_parser("restore", help="restore an archive session")
+    restore_parser.add_argument("session_id", nargs="?")
+    restore_parser.add_argument("--latest", action="store_true")
+    restore_parser.add_argument("--overwrite", action="store_true")
+    restore_parser.add_argument("--json", action="store_true")
+
+    history_parser = subparsers.add_parser("history", help="show local cleanup history")
+    history_parser.add_argument("--limit", type=int, default=10)
+    history_parser.add_argument("--json", action="store_true")
+
+    rules_parser = subparsers.add_parser("rules", help="explain built-in matching rules")
+    rules_parser.add_argument("--json", action="store_true")
+    return parser
+
+
+def _candidates(args: argparse.Namespace) -> list[Candidate]:
+    return scan(
+        args.paths or [Path.cwd()],
+        older_than_seconds=args.older_than,
+        min_size=args.min_size,
+        categories=set(args.categories) if args.categories else None,
+        exclusions=tuple(args.exclude),
+        max_depth=args.max_depth,
+    )
+
+
+def _print_candidates(candidates: list[Candidate]) -> None:
+    if not candidates:
+        print("No cleanup candidates found.")
+        return
+    for candidate in candidates:
+        activity = datetime.fromtimestamp(candidate.last_activity).strftime("%Y-%m-%d")
+        print(
+            f"{human_size(candidate.size):>10}  "
+            f"{candidate.category:<7}  {activity}  {candidate.path}"
+        )
+    print(f"\nPotential savings: {human_size(sum(item.size for item in candidates))}")
+
+
+def _scan_command(args: argparse.Namespace) -> int:
+    candidates = _candidates(args)
+    if args.json:
+        print(json.dumps([item.to_dict() for item in candidates], indent=2))
+    else:
+        _print_candidates(candidates)
+    return 0
+
+
+def _clean_command(args: argparse.Namespace) -> int:
+    candidates = _candidates(args)
+    if not candidates:
+        print("No cleanup candidates found.")
+        return 0
+    if not args.yes:
+        _print_candidates(candidates)
+        action = "archive" if args.archive else "permanently delete"
+        print(f"\nRefusing to {action} without --yes.", file=sys.stderr)
+        return 2
+
+    result = archive(candidates) if args.archive else delete(candidates)
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(
+            f"{result['action'].capitalize()} complete: "
+            f"{len(candidates)} item(s), {human_size(int(result['total_size']))}."
+        )
+        print(f"Session: {result['session_id']}")
+    return 0
+
+
+def _restore_command(args: argparse.Namespace) -> int:
+    result = restore(args.session_id, latest=args.latest, overwrite=args.overwrite)
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"Restored {len(result['items'])} item(s) from {result['session_id']}.")
+    return 0
+
+
+def _history_command(args: argparse.Namespace) -> int:
+    records = read_history(args.limit)
+    if args.json:
+        print(json.dumps(records, indent=2))
+        return 0
+    if not records:
+        print("No cleanup history found.")
+        return 0
+    for record in records:
+        created = datetime.fromtimestamp(record["created_at"]).strftime("%Y-%m-%d %H:%M")
+        print(
+            f"{created}  {record['action']:<7}  "
+            f"{human_size(int(record['total_size'])):>10}  {record['session_id']}"
+        )
+    return 0
+
+
+def _rules_command(args: argparse.Namespace) -> int:
+    rules = [
+        {
+            "name": rule.name,
+            "category": rule.category,
+            "directories": rule.directory_names,
+            "description": rule.description,
+        }
+        for rule in RULES
+    ]
+    if args.json:
+        print(json.dumps(rules, indent=2))
+    else:
+        for rule in rules:
+            names = ", ".join(rule["directories"])
+            print(f"{rule['name']} ({rule['category']}): {names}")
+            print(f"  {rule['description']}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = list(argv if argv is not None else sys.argv[1:])
+    known_commands = {"scan", "clean", "restore", "history", "rules"}
+    if not arguments:
+        arguments = ["scan", "."]
+    elif arguments[0] not in known_commands and arguments[0] not in {"-h", "--help", "--version"}:
+        arguments.insert(0, "scan")
+
+    parser = build_parser()
+    args = parser.parse_args(arguments)
+    try:
+        if args.command == "scan":
+            return _scan_command(args)
+        if args.command == "clean":
+            return _clean_command(args)
+        if args.command == "restore":
+            return _restore_command(args)
+        if args.command == "history":
+            return _history_command(args)
+        if args.command == "rules":
+            return _rules_command(args)
+        parser.print_help()
+        return 0
+    except (UnsafePathError, ValueError, FileExistsError, PermissionError) as error:
+        print(f"devtidy: error: {error}", file=sys.stderr)
+        return 1
+

devtidy/models.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Callable
+
+
+Validator = Callable[[Path], bool]
+
+
+@dataclass(frozen=True)
+class Rule:
+    name: str
+    category: str
+    directory_names: tuple[str, ...]
+    description: str
+    validator: Validator
+
+
+@dataclass(frozen=True)
+class Candidate:
+    path: Path
+    root: Path
+    rule: str
+    category: str
+    size: int
+    last_activity: float
+
+    def to_dict(self) -> dict[str, object]:
+        result = asdict(self)
+        result["path"] = str(self.path)
+        result["root"] = str(self.root)
+        return result
+

devtidy/rules.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from devtidy.models import Rule
+
+
+NODE_MARKERS = ("package.json",)
+PYTHON_MARKERS = ("pyproject.toml", "setup.py", "setup.cfg", "requirements.txt")
+PROJECT_MARKERS = NODE_MARKERS + PYTHON_MARKERS + (
+    ".git",
+    "Cargo.toml",
+    "go.mod",
+    "pom.xml",
+)
+
+
+def _has_parent_marker(path: Path, markers: tuple[str, ...]) -> bool:
+    return any((path.parent / marker).exists() for marker in markers)
+
+
+def _node_project(path: Path) -> bool:
+    return _has_parent_marker(path, NODE_MARKERS)
+
+
+def _python_venv(path: Path) -> bool:
+    return (path / "pyvenv.cfg").is_file()
+
+
+def _python_project(path: Path) -> bool:
+    return _has_parent_marker(path, PYTHON_MARKERS)
+
+
+def _known_project(path: Path) -> bool:
+    return _has_parent_marker(path, PROJECT_MARKERS)
+
+
+def _always(_: Path) -> bool:
+    return True
+
+
+RULES: tuple[Rule, ...] = (
+    Rule(
+        "node_modules",
+        "node",
+        ("node_modules",),
+        "Installed Node.js dependencies in a package.json project",
+        _node_project,
+    ),
+    Rule(
+        "python_venv",
+        "python",
+        (".venv", "venv", "env"),
+        "Python virtual environment containing pyvenv.cfg",
+        _python_venv,
+    ),
+    Rule(
+        "python_cache",
+        "cache",
+        ("__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache"),
+        "Regenerable Python tooling cache",
+        _always,
+    ),
+    Rule(
+        "tox_nox",
+        "python",
+        (".tox", ".nox"),
+        "Disposable test environments inside a Python project",
+        _python_project,
+    ),
+    Rule(
+        "web_build",
+        "build",
+        (".next", ".nuxt", ".svelte-kit", ".parcel-cache"),
+        "Regenerable web framework output in a Node.js project",
+        _node_project,
+    ),
+    Rule(
+        "project_build",
+        "build",
+        ("build", "dist", "coverage", "htmlcov"),
+        "Build or coverage output inside a recognized project",
+        _known_project,
+    ),
+)
+
+
+RULES_BY_DIRECTORY = {
+    directory_name: rule
+    for rule in RULES
+    for directory_name in rule.directory_names
+}
+

devtidy/safety.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+class UnsafePathError(ValueError):
+    pass
+
+
+def resolved(path: Path) -> Path:
+    return path.expanduser().resolve()
+
+
+def is_relative_to(path: Path, parent: Path) -> bool:
+    try:
+        path.relative_to(parent)
+        return True
+    except ValueError:
+        return False
+
+
+def protected_paths() -> set[Path]:
+    paths = {resolved(Path.home())}
+    anchor = Path(Path.cwd().anchor)
+    if anchor:
+        paths.add(resolved(anchor))
+
+    if os.name == "nt":
+        for variable in ("WINDIR", "ProgramFiles", "ProgramFiles(x86)", "ProgramData"):
+            value = os.environ.get(variable)
+            if value:
+                paths.add(resolved(Path(value)))
+    else:
+        paths.update(resolved(Path(path)) for path in ("/boot", "/etc", "/usr", "/var"))
+        if Path("/System").exists():
+            paths.add(resolved(Path("/System")))
+    return paths
+
+
+def validate_scan_root(path: Path) -> Path:
+    root = resolved(path)
+    if not root.exists():
+        raise UnsafePathError(f"scan root does not exist: {root}")
+    if not root.is_dir():
+        raise UnsafePathError(f"scan root is not a directory: {root}")
+    if root in protected_paths():
+        raise UnsafePathError(f"refusing protected scan root: {root}")
+    return root
+
+
+def validate_target(path: Path, root: Path) -> Path:
+    target = resolved(path)
+    safe_root = resolved(root)
+    if target == safe_root or not is_relative_to(target, safe_root):
+        raise UnsafePathError(f"target escaped scan root: {target}")
+    if target in protected_paths():
+        raise UnsafePathError(f"refusing protected target: {target}")
+    return target
+

devtidy/scanner.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import fnmatch
+import os
+import time
+from pathlib import Path
+from typing import Iterable
+
+from devtidy.models import Candidate
+from devtidy.rules import RULES_BY_DIRECTORY
+from devtidy.safety import validate_scan_root
+
+
+SKIP_NAMES = {".git", ".hg", ".svn"}
+ACTIVITY_IGNORES = {
+    ".DS_Store",
+    "Thumbs.db",
+    "desktop.ini",
+}
+
+
+def directory_size(path: Path) -> int:
+    total = 0
+    stack = [path]
+    while stack:
+        current = stack.pop()
+        try:
+            with os.scandir(current) as entries:
+                for entry in entries:
+                    try:
+                        if entry.is_symlink():
+                            continue
+                        if entry.is_dir(follow_symlinks=False):
+                            stack.append(Path(entry.path))
+                        elif entry.is_file(follow_symlinks=False):
+                            total += entry.stat(follow_symlinks=False).st_size
+                    except (FileNotFoundError, PermissionError, OSError):
+                        continue
+        except (FileNotFoundError, PermissionError, OSError):
+            continue
+    return total
+
+
+def project_activity(target: Path) -> float:
+    timestamps = [target.stat().st_mtime]
+    try:
+        with os.scandir(target.parent) as entries:
+            for entry in entries:
+                if entry.name == target.name or entry.name in ACTIVITY_IGNORES:
+                    continue
+                try:
+                    timestamps.append(entry.stat(follow_symlinks=False).st_mtime)
+                except (FileNotFoundError, PermissionError, OSError):
+                    continue
+    except (FileNotFoundError, PermissionError, OSError):
+        pass
+    return max(timestamps)
+
+
+def _excluded(path: Path, root: Path, patterns: Iterable[str]) -> bool:
+    relative = path.relative_to(root).as_posix()
+    return any(
+        fnmatch.fnmatch(relative, pattern) or fnmatch.fnmatch(path.name, pattern)
+        for pattern in patterns
+    )
+
+
+def scan(
+    roots: Iterable[Path],
+    *,
+    older_than_seconds: float = 0,
+    min_size: int = 0,
+    categories: set[str] | None = None,
+    exclusions: tuple[str, ...] = (),
+    max_depth: int | None = None,
+) -> list[Candidate]:
+    candidates: list[Candidate] = []
+    cutoff = time.time() - older_than_seconds
+
+    for supplied_root in roots:
+        root = validate_scan_root(supplied_root)
+        for current, directories, _ in os.walk(root, topdown=True, followlinks=False):
+            current_path = Path(current)
+            depth = len(current_path.relative_to(root).parts)
+            directories[:] = [
+                name
+                for name in directories
+                if name not in SKIP_NAMES
+                and not (current_path / name).is_symlink()
+                and not _excluded(current_path / name, root, exclusions)
+            ]
+            if max_depth is not None and depth >= max_depth:
+                directories[:] = []
+                continue
+
+            matched_names: list[str] = []
+            for name in directories:
+                rule = RULES_BY_DIRECTORY.get(name)
+                if rule is None or (categories and rule.category not in categories):
+                    continue
+                path = current_path / name
+                if not rule.validator(path):
+                    continue
+                activity = project_activity(path)
+                if older_than_seconds and activity > cutoff:
+                    continue
+                size = directory_size(path)
+                if size < min_size:
+                    continue
+                candidates.append(
+                    Candidate(path, root, rule.name, rule.category, size, activity)
+                )
+                matched_names.append(name)
+
+            # A matched artifact owns its subtree; nested caches are not separate savings.
+            directories[:] = [name for name in directories if name not in matched_names]
+
+    return sorted(candidates, key=lambda candidate: candidate.size, reverse=True)
+

devtidy/storage.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import json
+import shutil
+import time
+import uuid
+from pathlib import Path
+
+from devtidy.models import Candidate
+from devtidy.safety import is_relative_to, resolved, validate_target
+
+
+def state_dir() -> Path:
+    return Path.home() / ".devtidy"
+
+
+def archive_root() -> Path:
+    return state_dir() / "archives"
+
+
+def history_file() -> Path:
+    return state_dir() / "history.jsonl"
+
+
+def _record_history(record: dict[str, object]) -> None:
+    path = history_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as stream:
+        stream.write(json.dumps(record, sort_keys=True) + "\n")
+
+
+def archive(candidates: list[Candidate]) -> dict[str, object]:
+    session_id = time.strftime("%Y%m%d-%H%M%S") + "-" + uuid.uuid4().hex[:8]
+    session_dir = archive_root() / session_id
+    items_dir = session_dir / "items"
+    items_dir.mkdir(parents=True)
+    items: list[dict[str, object]] = []
+
+    for index, candidate in enumerate(candidates):
+        source = validate_target(candidate.path, candidate.root)
+        destination = items_dir / f"{index:04d}-{source.name}"
+        shutil.move(str(source), str(destination))
+        items.append(
+            {
+                **candidate.to_dict(),
+                "archived_path": str(destination),
+            }
+        )
+
+    manifest: dict[str, object] = {
+        "session_id": session_id,
+        "created_at": time.time(),
+        "action": "archive",
+        "total_size": sum(candidate.size for candidate in candidates),
+        "items": items,
+    }
+    (session_dir / "manifest.json").write_text(
+        json.dumps(manifest, indent=2, sort_keys=True),
+        encoding="utf-8",
+    )
+    _record_history(manifest)
+    return manifest
+
+
+def delete(candidates: list[Candidate]) -> dict[str, object]:
+    removed: list[dict[str, object]] = []
+    for candidate in candidates:
+        target = validate_target(candidate.path, candidate.root)
+        if target.is_symlink():
+            target.unlink()
+        else:
+            shutil.rmtree(target)
+        removed.append(candidate.to_dict())
+
+    record: dict[str, object] = {
+        "session_id": time.strftime("%Y%m%d-%H%M%S") + "-" + uuid.uuid4().hex[:8],
+        "created_at": time.time(),
+        "action": "delete",
+        "total_size": sum(candidate.size for candidate in candidates),
+        "items": removed,
+    }
+    _record_history(record)
+    return record
+
+
+def list_sessions() -> list[Path]:
+    root = archive_root()
+    if not root.exists():
+        return []
+    return sorted(
+        (path for path in root.iterdir() if (path / "manifest.json").is_file()),
+        key=lambda path: path.name,
+        reverse=True,
+    )
+
+
+def restore(session_id: str | None, *, latest: bool, overwrite: bool) -> dict[str, object]:
+    sessions = list_sessions()
+    if latest:
+        if not sessions:
+            raise ValueError("no archive sessions found")
+        session = sessions[0]
+    elif session_id:
+        session = archive_root() / session_id
+    else:
+        raise ValueError("provide a session ID or --latest")
+
+    manifest_path = session / "manifest.json"
+    if not manifest_path.is_file():
+        raise ValueError(f"archive session not found: {session.name}")
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+
+    restored: list[str] = []
+    for item in reversed(manifest["items"]):
+        archived_path = resolved(Path(item["archived_path"]))
+        original_path = resolved(Path(item["path"]))
+        original_root = resolved(Path(item["root"]))
+        if not is_relative_to(archived_path, resolved(session / "items")):
+            raise ValueError(f"invalid archived path in manifest: {archived_path}")
+        if original_path == original_root or not is_relative_to(original_path, original_root):
+            raise ValueError(f"invalid original path in manifest: {original_path}")
+        if not archived_path.exists():
+            continue
+        if original_path.exists():
+            if not overwrite:
+                raise FileExistsError(f"restore target already exists: {original_path}")
+            if original_path.is_dir() and not original_path.is_symlink():
+                shutil.rmtree(original_path)
+            else:
+                original_path.unlink()
+        original_path.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(archived_path), str(original_path))
+        restored.append(str(original_path))
+
+    record: dict[str, object] = {
+        "session_id": manifest["session_id"],
+        "created_at": time.time(),
+        "action": "restore",
+        "total_size": manifest["total_size"],
+        "items": restored,
+    }
+    _record_history(record)
+    return record
+
+
+def read_history(limit: int) -> list[dict[str, object]]:
+    path = history_file()
+    if not path.exists():
+        return []
+    records = [
+        json.loads(line)
+        for line in path.read_text(encoding="utf-8").splitlines()
+        if line.strip()
+    ]
+    return records[-limit:][::-1]

devtidy/units.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import re
+
+
+SIZE_UNITS = {
+    "B": 1,
+    "KB": 1000,
+    "MB": 1000**2,
+    "GB": 1000**3,
+    "TB": 1000**4,
+    "KIB": 1024,
+    "MIB": 1024**2,
+    "GIB": 1024**3,
+    "TIB": 1024**4,
+}
+TIME_UNITS = {
+    "H": 3600,
+    "D": 86400,
+    "W": 604800,
+}
+
+
+def parse_size(value: str) -> int:
+    match = re.fullmatch(r"\s*(\d+(?:\.\d+)?)\s*([kmgt]?i?b)?\s*", value, re.I)
+    if not match:
+        raise ValueError(f"invalid size: {value}")
+    number, unit = match.groups()
+    normalized = (unit or "B").upper()
+    if normalized not in SIZE_UNITS:
+        raise ValueError(f"unsupported size unit: {unit}")
+    return int(float(number) * SIZE_UNITS[normalized])
+
+
+def parse_duration(value: str) -> float:
+    match = re.fullmatch(r"\s*(\d+(?:\.\d+)?)\s*([hdw])\s*", value, re.I)
+    if not match:
+        raise ValueError(f"invalid duration: {value}; use values such as 24h, 30d, or 8w")
+    number, unit = match.groups()
+    return float(number) * TIME_UNITS[unit.upper()]
+
+
+def human_size(value: int) -> str:
+    amount = float(value)
+    for unit in ("B", "KiB", "MiB", "GiB", "TiB"):
+        if amount < 1024 or unit == "TiB":
+            return f"{amount:.1f} {unit}"
+        amount /= 1024
+    return f"{amount:.1f} TiB"

devtidy-0.1.0.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: devtidy
+Version: 0.1.0
+Summary: Safely find and reclaim stale developer build artifacts and environments.
+Author: Harish
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/harish-ai-engineer/devtidy
+Project-URL: Repository, https://github.com/harish-ai-engineer/devtidy.git
+Project-URL: Issues, https://github.com/harish-ai-engineer/devtidy/issues
+Keywords: cleanup,developer-tools,disk-space,node-modules,virtualenv
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# DevTidy
+
+DevTidy is a conservative, cross-platform command-line tool for finding stale
+developer artifacts such as `node_modules`, Python virtual environments, build
+outputs, and tool caches.
+
+It is an original implementation built around a simple rule: scanning should be
+easy, but removing data should require an explicit decision.
+
+## Highlights
+
+- Dry-run scanning is the default.
+- Recognizes project context before flagging risky directories.
+- Refuses to operate on protected system and home-directory roots.
+- Never follows directory symlinks.
+- Supports age, size, category, and exclusion filters.
+- Can archive files with a manifest and restore them later.
+- Produces machine-readable JSON for scripts and CI.
+- Stores cleanup history locally. No telemetry or network calls.
+
+## Install
+
+```console
+pipx install devtidy
+```
+
+For local development:
+
+```console
+python -m pip install -e .
+```
+
+## Quick start
+
+```console
+# Scan the current directory (never deletes)
+devtidy
+
+# Scan selected project folders
+devtidy scan ~/Projects ~/work --older-than 30d --min-size 100MB
+
+# Archive matches so they can be restored
+devtidy clean ~/Projects --older-than 60d --archive --yes
+
+# Permanently delete matches
+devtidy clean ~/Projects --older-than 90d --delete --yes
+
+# Restore the most recent archive session
+devtidy restore --latest
+
+# JSON output for automation
+devtidy scan . --json
+```
+
+## Commands
+
+### `scan`
+
+Find candidates without changing the filesystem. This is also the default
+command when no command is supplied.
+
+Useful options:
+
+- `--older-than 30d`: only include projects inactive for the given duration.
+- `--min-size 100MB`: only include artifacts at least this large.
+- `--category node,python,cache,build`: select rule categories.
+- `--exclude PATTERN`: skip matching paths; may be repeated.
+- `--max-depth N`: limit traversal depth.
+- `--json`: return structured output.
+
+### `clean`
+
+Uses the same filters as `scan`. Exactly one of `--archive` or `--delete` is
+required. `--yes` is mandatory for non-interactive execution.
+
+Archives live in `~/.devtidy/archives` by default. Each session contains a JSON
+manifest recording original paths, sizes, and timestamps.
+
+### `restore`
+
+Restore an archive by session ID, or use `--latest`. DevTidy will not overwrite
+an existing path unless `--overwrite` is supplied.
+
+### `history` and `rules`
+
+`history` shows local cleanup sessions. `rules` explains every built-in match
+and the project evidence required for it.
+
+## Built-in safety
+
+DevTidy refuses filesystem roots, user home directories, and common operating
+system directories as scan roots. It also checks that every cleanup target is
+inside an approved root immediately before acting, which helps protect against
+path changes between scanning and cleanup.
+
+Virtual environments must contain `pyvenv.cfg`. A `node_modules` directory must
+belong to a project containing `package.json`. Build directories are only
+matched inside recognized projects. Generic folders named `env`, `build`, or
+`dist` are therefore not removed merely because their name looks familiar.
+
+## Name ideas considered
+
+- **DevTidy**: clear, friendly, and broad enough for future cleanup rules.
+- **RepoRinse**: memorable, but sounds limited to repositories.
+- **DevSweep**: direct, though more generic.
+- **ByteBroom**: playful, but too close to the inspiration's branding.
+- **ProjectPrune**: descriptive, but may imply source-code deletion.
+
+Project source and issue tracking are available at
+<https://github.com/harish-ai-engineer/devtidy>.
+
+## License
+
+MIT

devtidy-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+devtidy/__init__.py,sha256=Z4vuUBnVF1p9sjnuw6TSoR3_Nqbz2LsHQQkw34OnaYM,64
+devtidy/__main__.py,sha256=oB9sGihtkKuwRy1YafgI1TkCQCuE-MRqGl3nGcEiTZs,56
+devtidy/cli.py,sha256=M9k9r3DG7w9z1Q0ADxAaRpavmtAqUsBU9iewEY6My_c,7386
+devtidy/models.py,sha256=fcI395AgFDDmjOyjOXIT_ISAlki7-NwGC5Oy39GmGYQ,643
+devtidy/rules.py,sha256=eIvKdQ57aRgP-D9YfUst-uJzpQLl7VX2ANal1YsSG3A,2140
+devtidy/safety.py,sha256=dkTnmk65dHbEDUMKBPMkercvh7YQ0K9COC9fiSn8_bo,1707
+devtidy/scanner.py,sha256=wAT3WEkTym7R1zprPCxMjfJOiEUmauTwKm2964Q4QQo,4079
+devtidy/storage.py,sha256=j4JMzgL30AsdOb8sczSs04RuZqg4Tc0wtCF6hPQP4l8,5053
+devtidy/units.py,sha256=lOSZef2GLsjDK0Hml-DdKB5w0_fDhPH0hZOoKFfda7Y,1267
+devtidy-0.1.0.dist-info/licenses/LICENSE,sha256=Mss4ldA6DvGYUV7jhNEl9t2Mpennj17PGSknGEOW-MI,1078
+devtidy-0.1.0.dist-info/METADATA,sha256=GX8N_XRk2Ae3m-0zu0cOxBDkzplxX_1cfdQ4FDoXB_I,4775
+devtidy-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+devtidy-0.1.0.dist-info/entry_points.txt,sha256=TJAHwZUwaFS1ZpSK2CTsYwGSl_qAARkQ8WXEYQs5wiY,45
+devtidy-0.1.0.dist-info/top_level.txt,sha256=WdMDu2bhqgO5u38O5pzzWoOzoonLJXisSFxP9PYW3dk,8
+devtidy-0.1.0.dist-info/RECORD,,

devtidy-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
+

devtidy-0.1.0.dist-info/entry_points.txt

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

devtidy-0.1.0.dist-info/licenses/LICENSE

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

devtidy-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+devtidy