macbroom 1.1.0__py3-none-any.whl

macbroom/__init__.py

@@ -0,0 +1,5 @@
+"""MacBroom —— 本地、安全、可视化的 macOS 清理工具。"""
+
+from __future__ import annotations
+
+__version__ = "1.1.0"

macbroom/__main__.py

@@ -0,0 +1,8 @@
+"""支持 ``python -m macbroom`` 启动。"""
+
+from __future__ import annotations
+
+from macbroom.cli import main
+
+if __name__ == "__main__":
+    main()

macbroom/cli.py

@@ -0,0 +1,128 @@
+"""MacBroom CLI —— 启动本地服务，或在终端直接扫描出报告。
+
+用法：
+    macbroom                      # 默认 127.0.0.1:37700，启动 Web UI 并打开浏览器
+    macbroom --port 40000
+    macbroom --no-open            # 不自动打开浏览器
+    python -m macbroom            # 等价调用
+
+    macbroom scan                 # 在终端扫描并打印汇总（不启动服务）
+    macbroom scan --json          # 输出 JSON，便于脚本 / CI 消费
+    macbroom scan --lang en
+    macbroom scan --category caches,login_items
+
+仅依赖 Python 3 标准库。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import threading
+import webbrowser
+
+from macbroom.core import audit
+from macbroom.core.fsutil import human_size
+from macbroom.core.i18n import normalize_lang
+from macbroom.core.server import serve
+from macbroom.scanners import categories as list_categories, scan_category
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 37700  # 已在端口登记表登记
+
+
+def _run_serve(args: argparse.Namespace) -> None:
+    if not args.no_open:
+        url = f"http://{args.host}:{args.port}"
+        threading.Timer(1.0, lambda: webbrowser.open(url)).start()
+    serve(args.host, args.port)
+
+
+def _run_scan(args: argparse.Namespace) -> None:
+    lang = normalize_lang(args.lang)
+    cats = list_categories(lang)
+    title_by_key = {c.key: c.title for c in cats}
+    icon_by_key = {c.key: c.icon for c in cats}
+
+    if args.category:
+        keys = [k.strip() for k in args.category.split(",") if k.strip()]
+    else:
+        keys = [c.key for c in cats]
+
+    results: list[tuple[str, list]] = []
+    for key in keys:
+        results.append((key, scan_category(key, lang)))
+
+    all_items = [it for _, items in results for it in items]
+    audit.record("cli_scan", categories=keys, count=len(all_items))
+
+    if args.json:
+        print(json.dumps([it.to_dict() for it in all_items],
+                         ensure_ascii=False, indent=2))
+        return
+
+    grand = 0
+    for key, items in results:
+        size = sum(it.size or 0 for it in items)
+        grand += size
+        icon = icon_by_key.get(key, "•")
+        title = title_by_key.get(key, key)
+        print(f"{icon}  {title}: {len(items)} items · {human_size(size)}")
+    print("-" * 40)
+    print(f"Total reclaimable: {human_size(grand)} across {len(all_items)} items")
+    print("Tip: run `macbroom` for the visual UI, or add --json for machine output.")
+
+
+def _resolve_version() -> str:
+    """已安装时以包元数据（pyproject 版本）为准，源码运行回退到 __version__。"""
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+        try:
+            return version("macbroom")
+        except PackageNotFoundError:
+            pass
+    except Exception:
+        pass
+    from macbroom import __version__
+    return __version__
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="MacBroom - open-source macOS cleaner")
+    parser.add_argument("--version", action="version",
+                        version=f"macbroom {_resolve_version()}")
+    parser.add_argument("--host", default=DEFAULT_HOST)
+    parser.add_argument("--port", type=int, default=DEFAULT_PORT)
+    parser.add_argument("--no-open", action="store_true", help="不自动打开浏览器")
+
+    sub = parser.add_subparsers(dest="cmd")
+    p_scan = sub.add_parser("scan", help="在终端扫描并输出报告，不启动服务")
+    p_scan.add_argument("--json", action="store_true", help="以 JSON 输出，便于脚本消费")
+    p_scan.add_argument("--lang", default="zh", help="zh 或 en")
+    p_scan.add_argument("--category", default="",
+                        help="只扫描指定分类，逗号分隔，如 caches,login_items")
+
+    p_doctor = sub.add_parser("doctor", help="环境预检：Python/macOS/完全磁盘访问/端口等")
+    p_doctor.add_argument("--json", action="store_true", help="JSON 输出")
+    p_doctor.add_argument("--lang", default="zh", help="zh 或 en")
+    p_doctor.add_argument("--port", type=int, default=DEFAULT_PORT,
+                          help="待检测的 Web UI 端口（默认 37700）")
+
+    args = parser.parse_args()
+    if args.cmd == "scan":
+        _run_scan(args)
+    elif args.cmd == "doctor":
+        from macbroom.doctor import format_report, run_checks
+        checks = run_checks(getattr(args, "port", DEFAULT_PORT))
+        if args.json:
+            print(json.dumps(checks, ensure_ascii=False, indent=2))
+        else:
+            print(format_report(checks, normalize_lang(args.lang)))
+        if not all(c["ok"] for c in checks):
+            raise SystemExit(1)
+    else:
+        _run_serve(args)
+
+
+if __name__ == "__main__":
+    main()

macbroom/core/__init__.py

@@ -0,0 +1 @@
+"""MacBroom core package."""

macbroom/core/audit.py

@@ -0,0 +1,61 @@
+"""操作审计日志：把每次扫描与删除写到本地文件，可事后追溯。
+
+参考 MacSift / MacOS-Maid 的做法：清理工具必须留痕，用户不开调试器也能
+知道「这个工具到底动了什么」。
+
+设计要点（对应全局「自测数据安全」硬约束）：
+- 日志目录可用环境变量 ``MACBROOM_LOG_DIR`` 覆盖，自测一律指向 /tmp，
+  绝不污染用户真实日志目录。
+- 单文件大小封顶，超过就轮转一次（.1），避免无限增长。
+- 仅本地写文件，不发网络，不记录文件内容、仅记录路径与动作。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+
+_DEFAULT_DIR = os.path.join(os.path.expanduser("~"), "Library", "Logs", "MacBroom")
+_MAX_BYTES = 512 * 1024  # 512KB 封顶，超过轮转
+_LOCK = threading.Lock()
+
+
+def log_dir() -> str:
+    return os.environ.get("MACBROOM_LOG_DIR", _DEFAULT_DIR)
+
+
+def log_path() -> str:
+    return os.path.join(log_dir(), "macbroom.log")
+
+
+def _rotate_if_needed(path: str) -> None:
+    try:
+        if os.path.getsize(path) <= _MAX_BYTES:
+            return
+    except OSError:
+        return
+    backup = path + ".1"
+    try:
+        if os.path.exists(backup):
+            os.remove(backup)
+        os.rename(path, backup)
+    except OSError:
+        pass
+
+
+def record(event: str, **fields) -> None:
+    """追加一条结构化日志。失败时静默（日志不应影响主流程）。"""
+    line = {"ts": time.strftime("%Y-%m-%dT%H:%M:%S"), "event": event}
+    line.update(fields)
+    try:
+        with _LOCK:
+            d = log_dir()
+            os.makedirs(d, exist_ok=True)
+            path = log_path()
+            _rotate_if_needed(path)
+            with open(path, "a", encoding="utf-8") as f:
+                f.write(json.dumps(line, ensure_ascii=False) + "\n")
+    except OSError:
+        pass

macbroom/core/fsutil.py

@@ -0,0 +1,186 @@
+"""文件系统工具：体量计算、安全遍历、受保护路径判定。
+
+所有扫描器共用这里的能力，避免各自重写 du / walk 逻辑。
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Iterator
+
+HOME = os.path.expanduser("~")
+
+# iCloud Drive 在本地的根目录。位于其下的文件删除后会同步到所有设备，需高风险对待。
+ICLOUD_ROOT = os.path.join(HOME, "Library", "Mobile Documents", "com~apple~CloudDocs")
+
+
+def is_icloud_path(path: str) -> bool:
+    """判断路径是否落在 iCloud 同步范围内。
+
+    覆盖两种情况：
+    1. 直接位于 iCloud Drive（~/Library/Mobile Documents/com~apple~CloudDocs）；
+    2. 开启「桌面与文档存入 iCloud」后，~/Desktop、~/Documents 实际被 iCloud 接管
+       （其 realpath 会指向 Mobile Documents 下）。
+    """
+    try:
+        real = os.path.realpath(path)
+    except OSError:
+        return False
+    mobile_docs = os.path.join(HOME, "Library", "Mobile Documents")
+    return real == mobile_docs or real.startswith(mobile_docs + os.sep)
+
+
+# 绝不触碰的路径前缀（即便扫描到也不允许作为删除项）。
+PROTECTED_PREFIXES = (
+    "/System",
+    "/usr",
+    "/bin",
+    "/sbin",
+    "/private/var/db",
+    "/Library/Apple",
+    os.path.join(HOME, "Library", "Keychains"),
+    os.path.join(HOME, ".ssh"),
+    os.path.join(HOME, ".gnupg"),
+)
+
+# 大文件遍历时跳过的目录名（性能 + 噪音控制）。
+SKIP_DIR_NAMES = {
+    ".git",
+    "node_modules",
+    ".Trash",
+    "CoreSimulator",          # iOS 模拟器单独扫
+    "DerivedData",            # iOS 构建产物单独扫
+}
+
+# 大文件遍历时跳过的目录后缀（macOS 的「包」本质是目录）。
+SKIP_DIR_SUFFIXES = (
+    ".app",
+    ".framework",
+    ".photoslibrary",
+    ".photolibrary",
+    ".pkg",
+)
+
+
+def actual_size(st: os.stat_result) -> int:
+    """实际占用磁盘的字节数（按 512B 块计），正确处理稀疏文件。
+
+    稀疏镜像（OrbStack/VM/磁盘镜像）的 st_size 是逻辑大小，可能远大于真实占用，
+    用 st_blocks 才不会虚报可释放空间。
+    """
+    try:
+        return st.st_blocks * 512
+    except AttributeError:
+        return st.st_size
+
+
+def human_size(num: float) -> str:
+    """字节数转可读字符串。"""
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if abs(num) < 1024.0:
+            return f"{num:.1f} {unit}" if unit != "B" else f"{int(num)} B"
+        num /= 1024.0
+    return f"{num:.1f} PB"
+
+
+# Freedesktop 缓存目录标记（CACHEDIR.TAG）及少数工具使用的 CACHEDIR.txt。
+_CACHE_MARKERS = ("CACHEDIR.TAG", "CACHEDIR.txt")
+
+
+def is_marked_cache_dir(path: str) -> bool:
+    """目录内是否带有标准缓存标记文件。"""
+    if not path or not os.path.isdir(path):
+        return False
+    return any(os.path.isfile(os.path.join(path, name)) for name in _CACHE_MARKERS)
+
+
+def is_protected(path: str) -> bool:
+    real = os.path.realpath(path)
+    return any(real == p or real.startswith(p + os.sep) for p in PROTECTED_PREFIXES)
+
+
+def safe_listdir(path: str) -> list[str]:
+    try:
+        return os.listdir(path)
+    except (PermissionError, FileNotFoundError, NotADirectoryError, OSError):
+        return []
+
+
+def dir_size(path: str, follow_symlinks: bool = False) -> int:
+    """递归计算目录占用，吞掉权限/损坏错误。文件则返回自身大小。"""
+    try:
+        st = os.lstat(path)
+    except OSError:
+        return 0
+    if os.path.islink(path):
+        return 0
+    if not os.path.isdir(path):
+        return actual_size(st)
+    total = 0
+    for root, dirs, files in os.walk(path, topdown=True, onerror=lambda e: None,
+                                     followlinks=follow_symlinks):
+        for name in files:
+            fp = os.path.join(root, name)
+            try:
+                if not os.path.islink(fp):
+                    total += actual_size(os.lstat(fp))
+            except OSError:
+                continue
+    return total
+
+
+def path_mtime(path: str) -> float:
+    try:
+        return os.lstat(path).st_mtime
+    except OSError:
+        return 0.0
+
+
+def iter_large_files(roots: list[str], min_bytes: int,
+                     same_device_as: str | None = None) -> Iterator[tuple[str, int, float]]:
+    """遍历 roots 下大于 min_bytes 的普通文件，产出 (path, size, mtime)。
+
+    会跳过符号链接、受保护路径、SKIP 目录、跨设备挂载点。
+    """
+    base_dev = None
+    if same_device_as:
+        try:
+            base_dev = os.lstat(same_device_as).st_dev
+        except OSError:
+            base_dev = None
+
+    seen: set[str] = set()
+    for root in roots:
+        root = os.path.realpath(root)
+        if root in seen:
+            continue
+        seen.add(root)
+        for cur, dirs, files in os.walk(root, topdown=True, onerror=lambda e: None):
+            # 原地裁剪要跳过的子目录
+            pruned = []
+            for d in dirs:
+                full = os.path.join(cur, d)
+                if os.path.islink(full):
+                    continue
+                if d in SKIP_DIR_NAMES or d.endswith(SKIP_DIR_SUFFIXES):
+                    continue
+                if base_dev is not None:
+                    try:
+                        if os.lstat(full).st_dev != base_dev:
+                            continue
+                    except OSError:
+                        continue
+                pruned.append(d)
+            dirs[:] = pruned
+
+            for name in files:
+                fp = os.path.join(cur, name)
+                try:
+                    st = os.lstat(fp)
+                except OSError:
+                    continue
+                if os.path.islink(fp):
+                    continue
+                size = actual_size(st)
+                if size >= min_bytes:
+                    yield fp, size, st.st_mtime