cursor-chat-cleaner 0.1.0__py3-none-any.whl

cursor_chat_cleaner/__init__.py

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

cursor_chat_cleaner/__main__.py

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

cursor_chat_cleaner/cli.py

@@ -0,0 +1,500 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sqlite3
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from cursor_chat_cleaner import __version__
+from cursor_chat_cleaner.store import (
+    SORT_KEYS,
+    CursorPaths,
+    aggregate_stats,
+    backup_chats,
+    cleanup_chat_artifacts,
+    cursor_is_running,
+    default_backup_dir,
+    delete_chats,
+    format_bytes,
+    format_conversation,
+    format_stats,
+    list_chats,
+    load_conversation,
+    summarize_repos,
+)
+
+_CLI_ERRORS = (FileNotFoundError, RuntimeError, ValueError, sqlite3.Error, OSError)
+
+GC_BLOBS_HINT = (
+    "Deleted chats leave orphaned hash-keyed rows in state.vscdb "
+    "(agentKv:blob, composer.content.*, and inlineDiff). This tool cannot "
+    "safely remove them. After Cursor is quit, run Developer: GC Agent KV "
+    "Blobs from the Command Palette (Cmd+Shift+P) to reclaim unreferenced "
+    "agentKv blobs. It does not remove chats. composer.content and "
+    "inlineDiff rows may still remain."
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cursor-chat-cleaner",
+        description="Find, back up, and delete Cursor chats on this Mac.",
+        epilog=(
+            "Quit Cursor before deleting. After a large cleanup, run "
+            "'Developer: GC Agent KV Blobs' from the Command Palette to reclaim "
+            "orphaned blob space."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "--user-dir",
+        type=Path,
+        help=(
+            "Cursor User directory (default: ~/Library/Application Support/Cursor/User). "
+            "For Nightly: ~/Library/Application Support/Cursor Nightly/User"
+        ),
+    )
+    parser.add_argument(
+        "--projects-dir",
+        type=Path,
+        help="Cursor projects directory (default: ~/.cursor/projects)",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    list_p = sub.add_parser("list", help="Show chats (archived only by default)")
+    _add_filters(list_p)
+    list_p.add_argument(
+        "--all",
+        action="store_true",
+        help="Include active chats, not only archived",
+    )
+    list_p.add_argument(
+        "--sort",
+        choices=SORT_KEYS,
+        default="updated",
+        help="Sort by this field (default: updated, newest first)",
+    )
+    list_p.add_argument(
+        "--reverse",
+        action="store_true",
+        help="Flip the default sort direction",
+    )
+    list_p.add_argument("--json", action="store_true", help="Print JSON")
+    list_p.add_argument(
+        "--repos",
+        action="store_true",
+        help="List unique repos instead of chats",
+    )
+
+    backup_p = sub.add_parser(
+        "backup",
+        help="Copy selected chats (archived only unless --id, --repo, or --all)",
+    )
+    _add_filters(backup_p)
+    backup_p.add_argument(
+        "--all",
+        action="store_true",
+        help="Include active chats, not only archived",
+    )
+    backup_p.add_argument(
+        "--dest",
+        type=Path,
+        help="Backup directory (default: ~/cursor-chat-cleaner-backups/<timestamp>)",
+    )
+
+    delete_p = sub.add_parser(
+        "delete",
+        help="Delete chats (archived only unless --id or --repo)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=GC_BLOBS_HINT,
+    )
+    _add_filters(delete_p)
+    delete_p.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be deleted without changing anything",
+    )
+    delete_p.add_argument(
+        "--yes",
+        action="store_true",
+        help="Actually delete (refused unless Cursor is quit, or --force)",
+    )
+    delete_p.add_argument(
+        "--force",
+        action="store_true",
+        help="Delete even if Cursor is still running (history may come back)",
+    )
+    delete_p.add_argument(
+        "--backup",
+        nargs="?",
+        const="__default__",
+        metavar="DIR",
+        help="Back up selected chats before deleting (default: ~/cursor-chat-cleaner-backups/<timestamp>)",
+    )
+    delete_p.add_argument(
+        "--vacuum",
+        action="store_true",
+        help="VACUUM the database after delete to reclaim file space",
+    )
+
+    stats_p = sub.add_parser("stats", help="Show model, line, and token totals")
+    _add_filters(stats_p)
+    stats_p.add_argument(
+        "--archived",
+        action="store_true",
+        help="Archived chats only (default: all chats)",
+    )
+    stats_p.add_argument("--json", action="store_true", help="Print JSON")
+
+    view_p = sub.add_parser("view", help="Print one chat")
+    view_p.add_argument("composer_id", metavar="ID", help="Composer id from list")
+    view_p.add_argument("--json", action="store_true", help="Print JSON")
+    view_p.add_argument(
+        "--thinking",
+        action="store_true",
+        help="Include thinking bubbles",
+    )
+
+    cleanup_p = sub.add_parser(
+        "cleanup",
+        help="Retry search-index and transcript cleanup by chat id",
+    )
+    cleanup_p.add_argument(
+        "--id",
+        action="append",
+        dest="ids",
+        required=True,
+        metavar="COMPOSER_ID",
+        help="Chat id left by a partial delete (repeatable)",
+    )
+    cleanup_p.add_argument(
+        "--yes",
+        action="store_true",
+        help="Actually remove matching search rows and transcript directories",
+    )
+    cleanup_p.add_argument(
+        "--force",
+        action="store_true",
+        help="Clean up even if Cursor is still running",
+    )
+    cleanup_p.add_argument(
+        "--vacuum",
+        action="store_true",
+        help="VACUUM the main database after cleanup",
+    )
+    return parser
+
+
+def _add_filters(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--workspace",
+        help="Only chats whose workspace path, id, or repo contains this text",
+    )
+    parser.add_argument(
+        "--repo",
+        help="Only chats whose repo name matches exactly (folder name)",
+    )
+    parser.add_argument(
+        "--older-than",
+        type=_positive_days,
+        metavar="DAYS",
+        help="Only chats last updated more than DAYS ago (minimum 1)",
+    )
+    parser.add_argument(
+        "--id",
+        action="append",
+        dest="ids",
+        metavar="COMPOSER_ID",
+        help="This chat id, archived or not (repeatable)",
+    )
+
+
+def _positive_days(value: str) -> int:
+    try:
+        days = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("DAYS must be an integer") from exc
+    if days < 1:
+        raise argparse.ArgumentTypeError("DAYS must be at least 1")
+    return days
+
+
+def paths_from_args(args) -> CursorPaths:
+    kwargs: dict[str, Path] = {}
+    if getattr(args, "user_dir", None) is not None:
+        kwargs["user_dir"] = args.user_dir.expanduser()
+    if getattr(args, "projects_dir", None) is not None:
+        kwargs["projects_dir"] = args.projects_dir.expanduser()
+    return CursorPaths(**kwargs)
+
+
+def selection_archived_only(command: str, args) -> bool:
+    if command == "stats":
+        return bool(getattr(args, "archived", False))
+    if getattr(args, "ids", None) or getattr(args, "all", False):
+        return False
+    if command in {"delete", "backup"} and getattr(args, "repo", None):
+        return False
+    return True
+
+
+def active_delete_warning(chats) -> str | None:
+    active = sum(1 for chat in chats if not chat.is_archived)
+    if not active:
+        return None
+    return (
+        f"{active} active chat(s) in this selection will be deleted, "
+        "not only archived."
+    )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    command = args.command or "list"
+    paths = paths_from_args(args)
+    if command == "view":
+        return _cmd_view(args, paths)
+    if command == "cleanup":
+        return _cmd_cleanup(args, paths)
+    ids = getattr(args, "ids", None)
+    repo = getattr(args, "repo", None)
+    archived_only = selection_archived_only(command, args)
+
+    try:
+        chats = list_chats(
+            paths,
+            workspace=getattr(args, "workspace", None),
+            repo=repo,
+            older_than_days=getattr(args, "older_than", None),
+            ids=ids,
+            archived_only=archived_only,
+            sort=getattr(args, "sort", "updated"),
+            reverse=getattr(args, "reverse", False),
+            sizes=command != "stats" and not getattr(args, "repos", False),
+        )
+    except _CLI_ERRORS as exc:
+        print(exc, file=sys.stderr)
+        return 2
+
+    if ids:
+        found = {chat.composer_id for chat in chats}
+        missing = [chat_id for chat_id in ids if chat_id not in found]
+        if missing:
+            print("Chat not found: " + ", ".join(missing), file=sys.stderr)
+            return 2
+
+    if command == "list":
+        if getattr(args, "repos", False):
+            _print_repos(chats, as_json=getattr(args, "json", False))
+        elif getattr(args, "json", False):
+            print(json.dumps([_chat_json(chat) for chat in chats], indent=2))
+        else:
+            _print_table(chats)
+        return 0
+
+    if command == "stats":
+        stats = aggregate_stats(chats)
+        if getattr(args, "json", False):
+            print(
+                json.dumps(
+                    {
+                        "chats": stats.chats,
+                        "archived": stats.archived,
+                        "lines_added": stats.lines_added,
+                        "lines_removed": stats.lines_removed,
+                        "files_changed": stats.files_changed,
+                        "tokens": stats.tokens,
+                        "models": stats.models,
+                        "repos": stats.repos,
+                    },
+                    indent=2,
+                )
+            )
+        else:
+            print(format_stats(stats), end="")
+        return 0
+
+    if not chats:
+        print("No chats matched.")
+        return 0
+
+    _print_table(chats)
+
+    if command == "backup":
+        dest = args.dest if args.dest is not None else default_backup_dir()
+        try:
+            result = backup_chats(paths, chats, dest)
+        except _CLI_ERRORS as exc:
+            print(exc, file=sys.stderr)
+            return 2
+        print(f"Backed up {result.chats} chat(s) to {result.path}")
+        return 0
+
+    warning = active_delete_warning(chats)
+    if warning:
+        print(warning)
+
+    if args.dry_run or not args.yes:
+        print("Dry run. Re-run with --yes to delete. Quit Cursor first.")
+        if args.backup:
+            print("A backup would be written first.")
+        return 0
+
+    if cursor_is_running() and not args.force:
+        print(
+            "Cursor is running. Quit it fully, then re-run, or pass --force.",
+            file=sys.stderr,
+        )
+        return 3
+
+    backup_dir = None
+    if args.backup:
+        backup_dir = default_backup_dir() if args.backup == "__default__" else Path(args.backup)
+
+    try:
+        result = delete_chats(
+            paths,
+            chats,
+            vacuum=args.vacuum,
+            backup_dir=backup_dir,
+            require_cursor_stopped=not args.force,
+        )
+    except _CLI_ERRORS as exc:
+        print(exc, file=sys.stderr)
+        return 2
+    print(
+        f"Deleted {result.chats} chat(s): "
+        f"{result.header_rows} headers, {result.kv_rows} kv rows, "
+        f"{result.search_rows} search rows, "
+        f"{result.transcript_dirs} transcript directories, "
+        f"{result.transcript_files} nested transcript files "
+        f"({format_bytes(result.bytes_removed)})."
+    )
+    if result.backup_path:
+        print(f"Backup: {result.backup_path}")
+    if result.vacuumed:
+        print("Database vacuumed.")
+    print(GC_BLOBS_HINT)
+    return 0
+
+
+def _cmd_cleanup(args, paths: CursorPaths) -> int:
+    ids = list(dict.fromkeys(args.ids))
+    print("Cleanup IDs:")
+    for composer_id in ids:
+        print(f"  {composer_id}")
+    if not args.yes:
+        print("Dry run. Re-run with --yes to remove leftover search rows and transcripts.")
+        return 0
+    if cursor_is_running() and not args.force:
+        print(
+            "Cursor is running. Quit it fully, then re-run, or pass --force.",
+            file=sys.stderr,
+        )
+        return 3
+    try:
+        result = cleanup_chat_artifacts(
+            paths,
+            ids,
+            vacuum=args.vacuum,
+            require_cursor_stopped=not args.force,
+        )
+    except _CLI_ERRORS as exc:
+        print(exc, file=sys.stderr)
+        return 2
+    print(
+        f"Cleanup complete: {result.search_rows} search rows, "
+        f"{result.transcript_dirs} transcript directories, "
+        f"{result.transcript_files} nested transcript files."
+    )
+    if result.vacuumed:
+        print("Database vacuumed.")
+    return 0
+
+
+def _cmd_view(args, paths: CursorPaths) -> int:
+    try:
+        chat, messages = load_conversation(paths, args.composer_id)
+    except _CLI_ERRORS as exc:
+        print(exc, file=sys.stderr)
+        return 2
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    **_chat_json(chat),
+                    "messages": [
+                        {
+                            "role": message.role,
+                            "text": message.text,
+                            "tool_name": message.tool_name,
+                        }
+                        for message in messages
+                    ],
+                },
+                indent=2,
+            )
+        )
+        return 0
+    print(format_conversation(chat, messages, thinking=args.thinking), end="")
+    return 0
+
+
+def _chat_json(chat) -> dict:
+    return {
+        "id": chat.composer_id,
+        "title": chat.title,
+        "workspace_id": chat.workspace_id,
+        "workspace": chat.workspace_path,
+        "repo": chat.repo,
+        "updated_at": chat.updated_at.isoformat(timespec="seconds"),
+        "size_bytes": chat.size_bytes,
+        "is_archived": chat.is_archived,
+        "subcomposer_ids": chat.subcomposer_ids,
+    }
+
+
+def _print_repos(chats, *, as_json: bool) -> None:
+    rows = summarize_repos(chats)
+    if as_json:
+        print(json.dumps(rows, indent=2))
+        return
+    if not rows:
+        print("No chats found.")
+        return
+    print(f"{'REPO':<24} {'CHATS':>5} {'ARCH':>5}")
+    for row in rows:
+        repo = str(row["repo"])
+        if len(repo) > 24:
+            repo = repo[:23] + "…"
+        print(f"{repo:<24} {row['chats']:>5} {row['archived']:>5}")
+    print()
+    print(f"{len(rows)} repo(s), {sum(int(row['chats']) for row in rows)} chat(s)")
+
+
+def _print_table(chats) -> None:
+    if not chats:
+        print("No chats found.")
+        return
+    print(f"{'ARCH':<5} {'UPDATED':<17} {'SIZE':>8}  {'REPO':<16}  {'ID':<36}  TITLE")
+    for chat in chats:
+        title = chat.title.replace("\n", " ")
+        repo = chat.repo
+        if len(repo) > 16:
+            repo = repo[:15] + "…"
+        print(
+            f"{'yes' if chat.is_archived else 'no':<5} "
+            f"{chat.updated_at.strftime('%Y-%m-%d %H:%M'):<17} "
+            f"{format_bytes(chat.size_bytes):>8}  "
+            f"{repo:<16}  "
+            f"{chat.composer_id:<36}  {title}"
+        )
+    archived = sum(1 for chat in chats if chat.is_archived)
+    print()
+    print(
+        f"{len(chats)} chat(s) ({archived} archived), "
+        f"{format_bytes(sum(c.size_bytes for c in chats))}"
+    )

cursor_chat_cleaner/schema.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+
+_REQUIRED_TABLES = {
+    "ItemTable": frozenset({"key", "value"}),
+    "cursorDiskKV": frozenset({"key", "value"}),
+    "composerHeaders": frozenset({"composerId", "isArchived", "isSubagent", "value"}),
+}
+
+_KV_PREFIXES = (
+    "composerData:{id}",
+    "bubbleId:{id}:",
+    "checkpointId:{id}:",
+    "ofsContent:{id}:",
+    "codeBlockPartialInlineDiffFates:{id}:",
+    "composerVirtualRowHeights:{id}",
+)
+
+_ITEM_KEYS = ("glass/cursor/{id}",)
+
+
+def table_exists(connection: sqlite3.Connection, name: str) -> bool:
+    row = connection.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?",
+        (name,),
+    ).fetchone()
+    return row is not None
+
+
+def table_columns(connection: sqlite3.Connection, table: str) -> set[str]:
+    return {str(row[1]) for row in connection.execute(f"PRAGMA table_info({table})")}
+
+
+def kv_patterns(composer_id: str) -> list[tuple[str, bool]]:
+    patterns: list[tuple[str, bool]] = []
+    for template in _KV_PREFIXES:
+        key = template.format(id=composer_id)
+        if key.endswith(":"):
+            escaped = key.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+            patterns.append((escaped + "%", True))
+        else:
+            patterns.append((key, False))
+    return patterns
+
+
+def item_keys(composer_id: str) -> list[str]:
+    return [template.format(id=composer_id) for template in _ITEM_KEYS]
+
+
+def schema_problems(global_db: Path, search_db: Path) -> list[str]:
+    if not global_db.is_file():
+        return [f"Cursor database not found: {global_db}"]
+
+    problems: list[str] = []
+    connection = _connect_readonly(global_db)
+    try:
+        for table, required in _REQUIRED_TABLES.items():
+            if not table_exists(connection, table):
+                problems.append(f"missing table {table}")
+                continue
+            missing = required - table_columns(connection, table)
+            if missing:
+                problems.append(f"{table} missing columns: {', '.join(sorted(missing))}")
+
+        if table_exists(connection, "ItemTable"):
+            row = connection.execute(
+                "SELECT value FROM ItemTable "
+                "WHERE key = 'composer.composerHeaders.tableGateEnabled'"
+            ).fetchone()
+            if row is None:
+                problems.append("composer.composerHeaders.tableGateEnabled is missing")
+            elif _decode(row["value"]).strip().lower() not in {"true", "1"}:
+                problems.append("composer.composerHeaders.tableGateEnabled is not true")
+    finally:
+        connection.close()
+
+    if search_db.is_file():
+        search = _connect_readonly(search_db)
+        try:
+            if not table_exists(search, "conversations"):
+                problems.append("conversation-search.db missing table conversations")
+            else:
+                missing = {"id", "is_archived", "fts_rowid"} - table_columns(
+                    search,
+                    "conversations",
+                )
+                if missing:
+                    problems.append(
+                        "conversations missing columns: " + ", ".join(sorted(missing))
+                    )
+            if not table_exists(search, "conversation_fts"):
+                problems.append("conversation-search.db missing table conversation_fts")
+        finally:
+            search.close()
+    return problems
+
+
+def assert_writable_schema(global_db: Path, search_db: Path) -> None:
+    problems = schema_problems(global_db, search_db)
+    if problems:
+        raise RuntimeError(
+            "Refusing to change Cursor data; schema is not the expected "
+            "composerHeaders layout:\n  - " + "\n  - ".join(problems)
+        )
+
+
+def _connect_readonly(path: Path) -> sqlite3.Connection:
+    uri = path.resolve().as_uri() + "?mode=ro"
+    connection = sqlite3.connect(uri, uri=True)
+    connection.row_factory = sqlite3.Row
+    return connection
+
+
+def _decode(value: object) -> str:
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+    return str(value or "")