tidy-gmail 0.1.0__py3-none-any.whl

tidy_gmail/__init__.py

@@ -0,0 +1 @@
+"""Local-first, data-driven Gmail cleanup tool."""

tidy_gmail/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

tidy_gmail/auth.py

@@ -0,0 +1,71 @@
+"""Gmail OAuth authorization and local credential management."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import tempfile
+from typing import Any
+
+SCOPES = ["https://www.googleapis.com/auth/gmail.modify"]
+
+
+def connect(root: Path) -> Any:
+    """Authorize the user's own desktop OAuth client, stored locally."""
+    from google.auth.transport.requests import Request
+    from google.oauth2.credentials import Credentials
+    from google_auth_oauthlib.flow import InstalledAppFlow
+    from googleapiclient.discovery import build
+
+    secret = root / ".local" / "credentials.json"
+    token = root / ".local" / "token.json"
+
+    if not secret.is_file():
+        raise FileNotFoundError(
+            f"Missing {secret}. Create a Google Cloud Desktop OAuth "
+            "client with Gmail API enabled and save its JSON here."
+        )
+
+    credentials = None
+
+    if token.is_file():
+        credentials = Credentials.from_authorized_user_file(
+            str(token),
+            SCOPES,
+        )
+
+    if not credentials or not credentials.valid:
+        if credentials and credentials.expired and credentials.refresh_token:
+            credentials.refresh(Request())
+        else:
+            credentials = InstalledAppFlow.from_client_secrets_file(
+                str(secret),
+                SCOPES,
+            ).run_local_server(port=0)
+
+        # WHY: Create private temporary storage before writing token contents.
+        temporary: str | None = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                dir=token.parent,
+                prefix=".token-",
+                suffix=".tmp",
+                encoding="utf-8",
+                delete=False,
+            ) as stream:
+                temporary = stream.name
+                stream.write(credentials.to_json())
+                stream.flush()
+                os.fsync(stream.fileno())
+            os.replace(temporary, token)
+        finally:
+            if temporary and os.path.exists(temporary):
+                os.unlink(temporary)
+
+    return build(
+        "gmail",
+        "v1",
+        credentials=credentials,
+        cache_discovery=False,
+    )

tidy_gmail/classify.py

@@ -0,0 +1,34 @@
+"""Classify inventory using current protection rules."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .inventory import read_inventory
+from .rules import Settings, eligible
+
+
+def select_candidates(
+    root: Path,
+    settings: Settings,
+    protected: set[str],
+    decisions: dict[str, str],
+) -> list[dict[str, str]]:
+    """Select messages using current user-maintained rules."""
+    rows = read_inventory(root)
+
+    ids = [row["id"] for row in rows]
+
+    if len(ids) != len(set(ids)):
+        raise ValueError("Duplicate Gmail message IDs in inventory; scan again")
+
+    return [
+        row
+        for row in rows
+        if eligible(
+            row,
+            settings,
+            protected,
+            decisions,
+        )
+    ]

tidy_gmail/cleanup.py

@@ -0,0 +1,172 @@
+"""Execute explicitly confirmed Gmail cleanup operations."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from . import gmail_client as gmail
+from . import storage
+from .classify import select_candidates
+from .rules import Settings, eligible, gmail_query, protection_reason, sender_approval
+
+
+def confirm(action: str, count: int) -> bool:
+    """Require an explicit confirmation for a modifying batch."""
+    required = f"{action} {count}"
+
+    print(f"Type {required!r} to authorize this batch.")
+
+    return input("> ").strip() == required
+
+
+def trash(
+    root: Path,
+    settings: Settings,
+    protected: set[str],
+    decisions: dict[str, str],
+    *,
+    execute: bool,
+    limit: int,
+) -> None:
+    """Revalidate approved messages before moving them to Trash."""
+    if not 1 <= limit <= settings.batch_size:
+        raise ValueError(
+            f"--limit must be 1..{settings.batch_size} (config batch_size)"
+        )
+
+    all_candidates = select_candidates(
+        root,
+        settings,
+        protected,
+        decisions,
+    )
+
+    proposal = all_candidates[:limit]
+
+    print(f"Proposed Trash batch: {len(proposal)} of {len(all_candidates)} candidates")
+
+    if not proposal:
+        return
+
+    if settings.dry_run or not execute:
+        print("DRY RUN. For execution, set cleanup.dry_run=false and pass --execute.")
+        return
+
+    api = gmail.connect(root)
+
+    # Recheck Gmail's current category, age, Inbox,
+    # starred, important, and attachment search conditions.
+    current_ids = set(
+        gmail.list_ids(
+            api,
+            gmail_query(settings),
+        )
+    )
+
+    approved: list[dict[str, str]] = []
+
+    for stored in proposal:
+        if stored["id"] not in current_ids:
+            continue
+
+        current = checked_metadata(api, stored, settings, protected, decisions)
+        if current is not None:
+            approved.append(current)
+
+    print(f"Still eligible after live Gmail recheck: {len(approved)}")
+
+    if not approved or not confirm(
+        "TRASH",
+        len(approved),
+    ):
+        print("Cancelled. No messages changed.")
+        return
+
+    log = root / "output" / "cleanup_log.csv"
+    count = 0
+
+    for stored in approved:
+        # WHY: Attachment and from:me protections rely on current Gmail search.
+        try:
+            matches = any(
+                message_id == stored["id"]
+                for message_id in gmail.list_ids(api, gmail_query(settings))
+            )
+        except Exception as exc:  # noqa: BLE001
+            print(f"Skipped {stored['id']}: search_unavailable ({type(exc).__name__})")
+            continue
+        if not matches:
+            print(f"Skipped {stored['id']}: current Gmail protections")
+            continue
+        # REQ: Recheck after confirmation, immediately before each mutation.
+        row = checked_metadata(api, stored, settings, protected, decisions)
+        if row is None:
+            continue
+        # Log the intention before issuing the Gmail operation.
+        storage.audit(
+            log,
+            "trash_requested",
+            row,
+        )
+
+        try:
+            gmail.trash(
+                api,
+                row["id"],
+            )
+
+        except Exception as exc:
+            storage.audit(
+                log,
+                "trash_failed",
+                row,
+                type(exc).__name__,
+            )
+            raise
+
+        storage.audit(
+            log,
+            "trashed",
+            row,
+        )
+
+        count += 1
+
+    print(f"Moved {count} individual messages to Gmail Trash. Audit: {log}")
+
+
+def checked_metadata(
+    api: Any,
+    stored: dict[str, str],
+    settings: Settings,
+    protected: set[str],
+    decisions: dict[str, str],
+) -> dict[str, str] | None:
+    """Skip messages whose current metadata cannot authorize cleanup safely."""
+    message_id = stored["id"]
+    try:
+        current = gmail.metadata(api, message_id)
+        reason = protection_reason(current)
+        if not reason and current.get("sender", "").strip().casefold() in protected:
+            reason = "sender_protected"
+        if not reason:
+            approval = sender_approval(current.get("sender", ""), decisions)
+            if approval.startswith("conflict:"):
+                reason = approval
+        if not reason and (
+            current.get("id") != message_id
+            or current.get("sender") != stored.get("sender")
+            or current.get("subject") != stored.get("subject")
+        ):
+            reason = "metadata_changed"
+        if not reason and not eligible(current, settings, protected, decisions):
+            reason = "existing_protection_or_ineligible"
+    except Exception as exc:  # noqa: BLE001
+        # WHY: API failures and malformed responses are never permission to delete.
+        print(f"Skipped {message_id}: metadata_unavailable ({type(exc).__name__})")
+        return None
+    if reason:
+        print(f"Skipped {message_id}: {reason}")
+        return None
+    return current

tidy_gmail/cli.py

@@ -0,0 +1,224 @@
+"""cli.py - command line interface.
+
+uvx tidy-gmail init
+uvx tidy-gmail doctor
+uvx tidy-gmail scan
+uvx tidy-gmail report
+uvx tidy-gmail candidates
+uvx tidy-gmail trash
+uvx tidy-gmail restore
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sqlite3
+import sys
+
+from . import gmail_client as gmail  # noqa: F401
+from . import storage
+from .classify import select_candidates  # noqa: F401
+from .cleanup import confirm, trash  # noqa: F401
+from .inventory import read_inventory, scan  # noqa: F401
+from .reports import candidates, report
+from .restore import restorable, restore  # noqa: F401
+from .rules import (
+    Settings,
+    load_settings,
+    sender_rules,
+)
+
+APP_NAME = "tidy-gmail"
+
+
+def prepare(
+    root: Path,
+) -> tuple[Settings, set[str], dict[str, str]]:
+    """Validate the existing workspace without repairing it."""
+    storage.check_repos_case(root)
+
+    for name in ("data", "output", ".local"):
+        if not (root / name).is_dir():
+            raise FileNotFoundError(f"Missing {root / name}; run tidy-gmail init")
+
+    settings = load_settings(root / "data" / "config.toml")
+
+    protected, decisions = sender_rules(root / "data")
+
+    return settings, protected, decisions
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the CLI parser and register every command."""
+    parser = argparse.ArgumentParser(
+        prog=APP_NAME,
+        description="Conservative Gmail cleanup",
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="tidy-gmail 0.1.0",
+    )
+
+    parser.add_argument(
+        "--workspace", type=Path, help="Use an existing local workspace"
+    )
+
+    sub = parser.add_subparsers(
+        dest="command",
+        required=True,
+    )
+
+    init_parser = sub.add_parser(
+        "init",
+        help=("Create the local workspace without overwriting existing files"),
+    )
+
+    init_parser.add_argument(
+        "--yes",
+        action="store_true",
+        help="Create only missing files without a prompt",
+    )
+
+    sub.add_parser(
+        "doctor",
+        help="Validate the local configuration",
+    )
+
+    scan_parser = sub.add_parser(
+        "scan",
+        help="Fetch Gmail metadata and discover senders",
+    )
+
+    scan_parser.add_argument(
+        "--limit",
+        type=int,
+        default=5000,
+        help="Maximum additional unique messages this invocation (automatically resumes)",
+    )
+
+    scan_parser.add_argument(
+        "--restart",
+        action="store_true",
+        help="Archive previous results and begin a fresh scan",
+    )
+
+    sub.add_parser(
+        "report",
+        help="Show sender counts and candidate totals",
+    )
+
+    sub.add_parser(
+        "candidates",
+        help="Save candidate CSV without Gmail modifications",
+    )
+
+    for command in ("trash", "restore"):
+        command_parser = sub.add_parser(
+            command,
+            help=f"{command.title()} logged Gmail messages",
+        )
+
+        command_parser.add_argument(
+            "--limit",
+            type=int,
+            default=None,
+        )
+
+        command_parser.add_argument(
+            "--execute",
+            action="store_true",
+            help="Request actual mailbox modification",
+        )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Execute the requested CLI command."""
+    args = build_parser().parse_args(argv)
+    root = (
+        args.workspace.expanduser().resolve() if args.workspace else storage.workspace()
+    )
+
+    try:
+        if args.command == "init":
+            storage.init(
+                root,
+                confirm=args.yes,
+            )
+            return 0
+
+        settings, protected, decisions = prepare(root)
+
+        if args.command == "doctor":
+            print(f"Workspace valid: {root}")
+            print("OAuth not tested; no Gmail connection made")
+
+        elif args.command == "scan":
+            scan(
+                root,
+                settings,
+                limit=args.limit,
+                restart=args.restart,
+            )
+
+        elif args.command == "report":
+            report(
+                root,
+                settings,
+                protected,
+                decisions,
+            )
+
+        elif args.command == "candidates":
+            candidates(
+                root,
+                settings,
+                protected,
+                decisions,
+            )
+
+        elif args.command == "trash":
+            trash(
+                root,
+                settings,
+                protected,
+                decisions,
+                execute=args.execute,
+                limit=settings.batch_size if args.limit is None else args.limit,
+            )
+
+        elif args.command == "restore":
+            restore(
+                root,
+                execute=args.execute and not settings.dry_run,
+                limit=settings.batch_size if args.limit is None else args.limit,
+            )
+
+    except KeyboardInterrupt:
+        print(
+            "Interrupted. Completed scan work is saved; run scan again to resume.",
+            file=sys.stderr,
+        )
+        return 130
+    except (
+        sqlite3.Error,
+        OSError,
+        ValueError,
+        KeyError,
+        EOFError,
+    ) as exc:
+        print(
+            f"Error: {exc}",
+            file=sys.stderr,
+        )
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())