macbroom 1.1.0__tar.gz

macbroom-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 3Kiven
+
+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.

macbroom-1.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: macbroom
+Version: 1.1.0
+Summary: Open-source macOS cleaner — free up disk space safely with a local web UI. Caches, app leftovers, large & duplicate files, dev junk.
+Author: MacBroom contributors
+License: MIT License
+        
+        Copyright (c) 2026 3Kiven
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/mythkiven/MacBroom
+Project-URL: Repository, https://github.com/mythkiven/MacBroom
+Project-URL: Issues, https://github.com/mythkiven/MacBroom/issues
+Keywords: macos,open-source,mac-cleaner,macos-cleaner,cleanmymac-alternative,cleanmymac,appcleaner,pearcleaner,disk-cleanup,disk-space,cache-cleaner,duplicate-finder,cleanup,uninstaller,developer-tools,xcode-cleaner,homebrew,privacy
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<div align="center">
+
+# 🧹 MacBroom
+
+**Open-source macOS cleaner — free up disk space safely**
+<br>**开源 macOS 清理工具 — 安全、可视化地释放磁盘空间**
+
+An **open-source CleanMyMac alternative**: scan reclaimable space → group it by app → tick and clean. Deletions go to the Trash by default and can be restored. Local-only, zero-dependency, no telemetry.
+
+> 一个 **开源的 CleanMyMac 替代品**：扫描可释放空间 → 按软件分组 → 勾选一键清理。默认移入废纸篓、可还原；纯本地、零依赖、不联网。**完整中文文档见 [README.zh.md](./README.zh.md)。**
+
+[简体中文](./README.zh.md) · English
+
+[![CI](https://github.com/mythkiven/MacBroom/actions/workflows/ci.yml/badge.svg)](https://github.com/mythkiven/MacBroom/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+![Platform: macOS](https://img.shields.io/badge/platform-macOS-lightgrey.svg)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
+
+</div>
+
+![MacBroom main window](docs/screenshot.png)
+
+---
+
+## ✨ Features
+
+- **Local only · zero dependencies**: pure Python 3 standard library, no network calls, no telemetry.
+- **Safety first**: files go to the macOS Trash (not `rm`), restorable from Trash; system-critical paths (`/System`, Keychains, SSH keys, …) are hard-blocked.
+- **Risk grading**: every item is tagged `safe / moderate / risky`. Risky items (personal data, irreversible actions) are **hidden by default** until you tick "Show risky items".
+- **Explainable leftovers**: each suspected uninstall leftover shows *why* it was flagged (bundle id with no matching app) and can be **expanded to inspect the actual files** before you decide.
+- **Confirm before delete (dry-run)**: the dialog lists every selected item with its path and reason, total count and reclaimable size; large totals (>10 GB) or risky selections get an extra warning.
+- **Sort & drill-down**: sort results by size or name, expand any group or item to see what is inside.
+- **Audit log**: every scan and deletion is written to `~/Library/Logs/MacBroom/macbroom.log` (override the directory with `MACBROOM_LOG_DIR`).
+- **Grouped by app**: caches and the like are grouped per app; your selection is preserved across rescans.
+- **Customizable**: toggle each scan category on/off; a persistent **exclusion list** for false positives; long scans are **cancelable**.
+- **iCloud-aware**: detects iCloud-synced folders to avoid breaking cross-device sync.
+- **Respects `CACHEDIR.TAG`**: standard cache markers are recognized so the right directories are treated as cache.
+- **Covers popular apps**: beyond browser/dev caches, also Slack, Discord, VS Code, Microsoft Teams, Spotify, Steam, Telegram, Minecraft.
+- **Login items check**: finds orphaned launch-at-login items pointing to deleted programs (the "background items" macOS warns about) and removes them.
+- **CLI / scripting friendly**: `macbroom scan --json` prints a report right in the terminal for automation and CI.
+- **`macbroom doctor`**: pre-flight checks for Python, Full Disk Access, log directory, and port availability before you scan.
+- **No forced deletion**: items that can't be removed are listed with a copy-paste Terminal command for you to run.
+- **Clean web UI**: collapsible groups, group-level select-all, live reclaimable-space totals.
+
+## 🔍 What it detects
+
+| Category | Description |
+|---|---|
+| 🧹 **App Caches** | Rebuildable caches grouped by app (incl. npm/pip/Gradle/CocoaPods/Homebrew dev caches and Chrome/Edge/Brave/Arc/Firefox browser caches) |
+| 👻 **App Leftovers** | Support files, containers, logs and preferences likely left by uninstalled apps (heuristic; review first) |
+| 🐘 **Large Files** | Single files larger than 100 MB — find space-hungry videos / images / archives |
+| 🛠️ **Dev Clutter** | Build products, caches, simulators and SDK temp dirs for iOS/Xcode, Android/Android Studio, HarmonyOS/DevEco Studio |
+| 🧬 **Duplicate Files** | Byte-for-byte identical files (size → partial hash → full SHA-256), keeping the newest copy per group |
+| 🚀 **Login / Startup Items** | Launch-at-login LaunchAgents / LaunchDaemons, focusing on orphaned entries pointing to deleted programs |
+| ✨ **Other Cleanup** | Diagnostic reports, iOS device backups, Homebrew leftovers, Docker images, Time Machine local snapshots, scattered `node_modules`, mail attachment caches, old downloads |
+
+## 💡 Why MacBroom? — built from real cleaner failures
+
+We read **hundreds of issues across popular open-source Mac cleaners** and designed MacBroom to *not* repeat their most painful, real, reported accidents:
+
+| Real-world failure reported in other cleaners | How MacBroom avoids it by design |
+|---|---|
+| A cleaner deleted a user's **entire Chrome profile** — logins and bookmarks gone | We only target precise `Default/Cache` & `Code Cache` dirs — **never** the profile directory |
+| **Apple Notes / Claude Code CLI deleted** as "leftovers" (matched by name, not identity) | Leftover detection matches **bundle id exactly**; each flagged item shows *why*, with an expandable file list to review before deleting |
+| **Shell history wiped** (`~/.zsh_history`) as "junk" | We never scan or touch shell history |
+| Cleanup **broke iCloud sync** (Desktop/Documents) | We **detect iCloud-synced paths**, mark them risky and hide them by default |
+| Uninstall **misidentified unrelated files** (`~/Public`, printer configs, another app's data) | Bundle-id matching + risk grading + a persistent **exclusion list** to permanently skip false positives |
+| **Wrong / negative free-space numbers** (sparse images counted by logical size) | Real on-disk usage via `st_blocks`, so sparse VM/disk images are not over-counted |
+| **Untranslated or mistranslated UI** | Native-quality **English and Chinese** from day one, not machine-translated strings |
+| **Simulator cleanup throwing errors** | iOS/Xcode simulators are cleaned through the official `xcrun simctl` interface, not by blindly deleting paths |
+| **Long scans froze the app** with no way to stop | Every scan is **cancelable** mid-run |
+| Orphaned **login items** left erroring in System Settings after uninstalls | Dedicated **Login Items scanner** flags startup entries pointing to deleted programs |
+
+In short: **other cleaners delete first and apologize later. MacBroom is designed to be un-dangerous** — Trash-by-default, risky items hidden, dry-run confirmation that lists exactly what goes, and an audit log of everything it does.
+
+## 🚀 Usage
+
+### Option A: run from source (works today, no install)
+
+```bash
+git clone https://github.com/mythkiven/MacBroom.git
+cd MacBroom
+./run.sh                   # or: python -m macbroom
+```
+
+### Option B: pipx / pip
+
+> Published to PyPI with the first tagged release. Until then, use Option A.
+
+```bash
+pipx install macbroom      # or: pip install macbroom
+macbroom                   # starts and opens the browser
+```
+
+The browser opens at `http://127.0.0.1:37700`. Click "Start Scan", then "Clean Selected".
+
+```bash
+macbroom --port 40000      # custom port
+macbroom --no-open         # don't open the browser
+```
+
+### Option C: command-line report (headless / scripting)
+
+```bash
+macbroom doctor                # pre-flight: Python, FDA, port, log dir
+macbroom scan                                  # print per-category summary and total
+macbroom scan --json                           # JSON output for scripts / CI
+macbroom scan --category caches,login_items    # scan specific categories only
+```
+
+## 🛡️ Security
+
+See [SECURITY.md](./SECURITY.md) for the full security model and how to report vulnerabilities. In short: local-only, Trash-by-default, protected-path hard blocks, risk grading, audit log, loopback-only with Host validation + per-session CSRF token on the delete endpoint.
+
+## 🖥️ Compatibility
+
+- Python 3.9+ (standard library only).
+- macOS 12 (Monterey) through 15 (Sequoia) / 26 (Tahoe). On older systems, any missing path or command (e.g. `simctl runtime`, `tmutil thinlocalsnapshots`) is skipped automatically without affecting other categories.
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). MacBroom needs no third-party packages; run tests with:
+
+```bash
+MACBROOM_LOG_DIR=/tmp/macbroom-test python -m unittest discover -s tests -v
+```
+
+## 📄 License
+
+[MIT](./LICENSE)

macbroom-1.1.0/README.md

@@ -0,0 +1,131 @@
+<div align="center">
+
+# 🧹 MacBroom
+
+**Open-source macOS cleaner — free up disk space safely**
+<br>**开源 macOS 清理工具 — 安全、可视化地释放磁盘空间**
+
+An **open-source CleanMyMac alternative**: scan reclaimable space → group it by app → tick and clean. Deletions go to the Trash by default and can be restored. Local-only, zero-dependency, no telemetry.
+
+> 一个 **开源的 CleanMyMac 替代品**：扫描可释放空间 → 按软件分组 → 勾选一键清理。默认移入废纸篓、可还原；纯本地、零依赖、不联网。**完整中文文档见 [README.zh.md](./README.zh.md)。**
+
+[简体中文](./README.zh.md) · English
+
+[![CI](https://github.com/mythkiven/MacBroom/actions/workflows/ci.yml/badge.svg)](https://github.com/mythkiven/MacBroom/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+![Platform: macOS](https://img.shields.io/badge/platform-macOS-lightgrey.svg)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
+
+</div>
+
+![MacBroom main window](docs/screenshot.png)
+
+---
+
+## ✨ Features
+
+- **Local only · zero dependencies**: pure Python 3 standard library, no network calls, no telemetry.
+- **Safety first**: files go to the macOS Trash (not `rm`), restorable from Trash; system-critical paths (`/System`, Keychains, SSH keys, …) are hard-blocked.
+- **Risk grading**: every item is tagged `safe / moderate / risky`. Risky items (personal data, irreversible actions) are **hidden by default** until you tick "Show risky items".
+- **Explainable leftovers**: each suspected uninstall leftover shows *why* it was flagged (bundle id with no matching app) and can be **expanded to inspect the actual files** before you decide.
+- **Confirm before delete (dry-run)**: the dialog lists every selected item with its path and reason, total count and reclaimable size; large totals (>10 GB) or risky selections get an extra warning.
+- **Sort & drill-down**: sort results by size or name, expand any group or item to see what is inside.
+- **Audit log**: every scan and deletion is written to `~/Library/Logs/MacBroom/macbroom.log` (override the directory with `MACBROOM_LOG_DIR`).
+- **Grouped by app**: caches and the like are grouped per app; your selection is preserved across rescans.
+- **Customizable**: toggle each scan category on/off; a persistent **exclusion list** for false positives; long scans are **cancelable**.
+- **iCloud-aware**: detects iCloud-synced folders to avoid breaking cross-device sync.
+- **Respects `CACHEDIR.TAG`**: standard cache markers are recognized so the right directories are treated as cache.
+- **Covers popular apps**: beyond browser/dev caches, also Slack, Discord, VS Code, Microsoft Teams, Spotify, Steam, Telegram, Minecraft.
+- **Login items check**: finds orphaned launch-at-login items pointing to deleted programs (the "background items" macOS warns about) and removes them.
+- **CLI / scripting friendly**: `macbroom scan --json` prints a report right in the terminal for automation and CI.
+- **`macbroom doctor`**: pre-flight checks for Python, Full Disk Access, log directory, and port availability before you scan.
+- **No forced deletion**: items that can't be removed are listed with a copy-paste Terminal command for you to run.
+- **Clean web UI**: collapsible groups, group-level select-all, live reclaimable-space totals.
+
+## 🔍 What it detects
+
+| Category | Description |
+|---|---|
+| 🧹 **App Caches** | Rebuildable caches grouped by app (incl. npm/pip/Gradle/CocoaPods/Homebrew dev caches and Chrome/Edge/Brave/Arc/Firefox browser caches) |
+| 👻 **App Leftovers** | Support files, containers, logs and preferences likely left by uninstalled apps (heuristic; review first) |
+| 🐘 **Large Files** | Single files larger than 100 MB — find space-hungry videos / images / archives |
+| 🛠️ **Dev Clutter** | Build products, caches, simulators and SDK temp dirs for iOS/Xcode, Android/Android Studio, HarmonyOS/DevEco Studio |
+| 🧬 **Duplicate Files** | Byte-for-byte identical files (size → partial hash → full SHA-256), keeping the newest copy per group |
+| 🚀 **Login / Startup Items** | Launch-at-login LaunchAgents / LaunchDaemons, focusing on orphaned entries pointing to deleted programs |
+| ✨ **Other Cleanup** | Diagnostic reports, iOS device backups, Homebrew leftovers, Docker images, Time Machine local snapshots, scattered `node_modules`, mail attachment caches, old downloads |
+
+## 💡 Why MacBroom? — built from real cleaner failures
+
+We read **hundreds of issues across popular open-source Mac cleaners** and designed MacBroom to *not* repeat their most painful, real, reported accidents:
+
+| Real-world failure reported in other cleaners | How MacBroom avoids it by design |
+|---|---|
+| A cleaner deleted a user's **entire Chrome profile** — logins and bookmarks gone | We only target precise `Default/Cache` & `Code Cache` dirs — **never** the profile directory |
+| **Apple Notes / Claude Code CLI deleted** as "leftovers" (matched by name, not identity) | Leftover detection matches **bundle id exactly**; each flagged item shows *why*, with an expandable file list to review before deleting |
+| **Shell history wiped** (`~/.zsh_history`) as "junk" | We never scan or touch shell history |
+| Cleanup **broke iCloud sync** (Desktop/Documents) | We **detect iCloud-synced paths**, mark them risky and hide them by default |
+| Uninstall **misidentified unrelated files** (`~/Public`, printer configs, another app's data) | Bundle-id matching + risk grading + a persistent **exclusion list** to permanently skip false positives |
+| **Wrong / negative free-space numbers** (sparse images counted by logical size) | Real on-disk usage via `st_blocks`, so sparse VM/disk images are not over-counted |
+| **Untranslated or mistranslated UI** | Native-quality **English and Chinese** from day one, not machine-translated strings |
+| **Simulator cleanup throwing errors** | iOS/Xcode simulators are cleaned through the official `xcrun simctl` interface, not by blindly deleting paths |
+| **Long scans froze the app** with no way to stop | Every scan is **cancelable** mid-run |
+| Orphaned **login items** left erroring in System Settings after uninstalls | Dedicated **Login Items scanner** flags startup entries pointing to deleted programs |
+
+In short: **other cleaners delete first and apologize later. MacBroom is designed to be un-dangerous** — Trash-by-default, risky items hidden, dry-run confirmation that lists exactly what goes, and an audit log of everything it does.
+
+## 🚀 Usage
+
+### Option A: run from source (works today, no install)
+
+```bash
+git clone https://github.com/mythkiven/MacBroom.git
+cd MacBroom
+./run.sh                   # or: python -m macbroom
+```
+
+### Option B: pipx / pip
+
+> Published to PyPI with the first tagged release. Until then, use Option A.
+
+```bash
+pipx install macbroom      # or: pip install macbroom
+macbroom                   # starts and opens the browser
+```
+
+The browser opens at `http://127.0.0.1:37700`. Click "Start Scan", then "Clean Selected".
+
+```bash
+macbroom --port 40000      # custom port
+macbroom --no-open         # don't open the browser
+```
+
+### Option C: command-line report (headless / scripting)
+
+```bash
+macbroom doctor                # pre-flight: Python, FDA, port, log dir
+macbroom scan                                  # print per-category summary and total
+macbroom scan --json                           # JSON output for scripts / CI
+macbroom scan --category caches,login_items    # scan specific categories only
+```
+
+## 🛡️ Security
+
+See [SECURITY.md](./SECURITY.md) for the full security model and how to report vulnerabilities. In short: local-only, Trash-by-default, protected-path hard blocks, risk grading, audit log, loopback-only with Host validation + per-session CSRF token on the delete endpoint.
+
+## 🖥️ Compatibility
+
+- Python 3.9+ (standard library only).
+- macOS 12 (Monterey) through 15 (Sequoia) / 26 (Tahoe). On older systems, any missing path or command (e.g. `simctl runtime`, `tmutil thinlocalsnapshots`) is skipped automatically without affecting other categories.
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). MacBroom needs no third-party packages; run tests with:
+
+```bash
+MACBROOM_LOG_DIR=/tmp/macbroom-test python -m unittest discover -s tests -v
+```
+
+## 📄 License
+
+[MIT](./LICENSE)

macbroom-1.1.0/macbroom/__init__.py

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

macbroom-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-1.1.0/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-1.1.0/macbroom/core/__init__.py

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

macbroom-1.1.0/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