Features/p0

.github/workflow/workflow.yml → .github/workflows/ci.yml

@@ -7,6 +7,9 @@ on:
     branches: [main, develop]
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
@@ -15,8 +18,13 @@ jobs:
   lint:
     name: Lint & Type Check
     runs-on: macos-latest
+    timeout-minutes: 20
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+          persist-credentials: false
 
       - name: Set up Python 3.11
         uses: actions/setup-python@v5
@@ -25,74 +33,61 @@ jobs:
           cache: pip
 
       - name: Install dev dependencies
-        run: pip install ruff mypy types-PyYAML
-
-      - name: Ruff lint
-        run: ruff check src/ tests/
-
-      - name: Ruff format check
-        run: ruff format --check src/ tests/
-
-      - name: Mypy type check
-        run: mypy src/ --ignore-missing-imports
+        run: pip install --upgrade pip && pip install ruff mypy types-PyYAML
 
   test:
     name: Test / Python ${{ matrix.python-version }} / ${{ matrix.os }}
     needs: lint
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 40
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
         os: [macos-13, macos-14, macos-latest]
         exclude:
           # Python 3.9 not available on macos-14 (arm64 runner)
           - os: macos-14
             python-version: "3.9"
 
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+          persist-credentials: false
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
 
-      - name: Install package (editable) + dev extras
-        run: pip install -e ".[dev]"
-
-      - name: Run pytest with coverage
+      - name: CI install + smoke test (venv)
         run: |
-          pytest tests/ \
-            --tb=short \
-            --cov=src \
-            --cov-report=term-missing \
-            --cov-report=xml \
-            -v
-
-      - name: Upload coverage to Codecov
-        if: matrix.python-version == '3.11' && matrix.os == 'macos-latest'
-        uses: codecov/codecov-action@v4
-        with:
-          files: coverage.xml
-          flags: unittests
-          fail_ci_if_error: false
+          bash scripts/build.sh venv
+          bash scripts/build.sh test
 
   build-check:
     name: Build Distribution Check
     needs: test
     runs-on: macos-latest
+    timeout-minutes: 25
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+          persist-credentials: false
 
       - name: Set up Python 3.11
         uses: actions/setup-python@v5
         with:
           python-version: "3.11"
+          cache: pip
 
       - name: Install build tools
-        run: pip install build twine
+        run: pip install --upgrade pip && pip install build twine
 
       - name: Build wheel + sdist
         run: python -m build
@@ -111,4 +106,5 @@ jobs:
         with:
           name: dist-packages
           path: dist/
-          retention-days: 7
+          retention-days: 7
+

CHANGELOG.md

@@ -3,11 +3,37 @@
 All notable changes to **mac-deep-cleaner** will be documented in this file.
 
 ## Unreleased
+
+## v1.5.0 (2026-05-12)
 ### Added
-- Debug logging flags (`--verbose`, `--log-file`) with file rotation
-- Basic test coverage for utilities and matching
+#### P0 (baseline UX and safety)
+- [x] Global --dry-run flag (src/core/dry_run.py)
+- [x] Shell completion command (src/core/completions.py)
+- [x] Full app uninstaller (src/core/uninstaller.py)
+
+#### P1 (highest demand data and visibility)
+- [x] Browser data cleaner (src/scanners/browser_data.py)
+- [x] Visual disk space map (src/scanners/space_map.py)
+- [x] Photo library analyzer (src/scanners/photos_analyzer.py)
+- [x] iOS simulator deep cleaner (src/scanners/simulators.py)
+
+#### P2 (system utilities and maintenance)
+- [x] Memory pressure reliever (src/core/memory_pressure.py)
+- [x] Homebrew deep manager (src/core/brew_manager.py)
+- [x] Storage trend tracker (src/reporting/storage_trend.py)
+- [x] Recent files and activity cleaner (src/scanners/recent_activity.py)
+
+#### P3 (advanced and higher risk features)
+- [x] Permissions auditor (src/core/permissions_auditor.py)
+- [x] APFS snapshot guard (src/core/apfs_snapshots.py)
+- [x] Menu bar companion (src/core/menubar.py)
+- [x] Data breach monitor (src/core/breach_monitor.py)
+- [x] Cloud storage junk scanner (src/scanners/cloud_junk.py)
 
 ### Changed
+- CLI wiring for new P0/P1 commands and dry-run behavior
+- Module layout aligned to core/scanners (removed features package)
+- README, checklist, and roadmap paths updated for the new layout
 - Improved error handling with debug logs across filesystem and subprocess paths
 - Dev junk scanner traversal now uses a deque for better performance
 
@@ -21,7 +47,7 @@ All notable changes to **mac-deep-cleaner** will be documented in this file.
 ### Changed
 - Live dashboard now shows top findings and dev junk totals
 - Scan history schema extended with developer junk totals
-- Version bump to v1.2.0 across docs and UI
+- Version bump to v1.5.0 across docs and UI
 
 ## v1.0.0 (2026-05-10)
 ### Added

README.md

@@ -1,4 +1,4 @@
-# Mac Deep Cleaner v1.2.0
+# Mac Deep Cleaner v1.5.0
 
 **Professional macOS cleanup tool — Smart App Orphan Detector**
 
@@ -23,6 +23,12 @@ mdc scan
 - **Duplicate finder** — SHA-256 content hashing, two-phase (head + full), sorted by wasted space
 - **Large file scanner** — finds files ≥100 MB (configurable), categorised by type
 - **Broken symlink detector** — walks `/usr/local`, `/opt/homebrew`, `~/bin`, etc.
+- **Browser data cleaner** — cache, cookies, history, sessions (opt-in delete)
+- **Space map** — disk usage overview by folder tree
+- **Photos analyzer** — summaries of Photos libraries and originals
+- **iOS simulator cleaner** — shows simulator sizes and can purge
+- **Full app uninstaller** — remove app bundle plus known data
+- **Shell completions** — bash, zsh, fish
 - **iOS backup finder** — parses `MobileSync/Backup` manifests, shows device/age/size
 - **Language pack stripper** — detects removable `.lproj` dirs in every installed app
 - **Universal binary thinner** — uses `ditto --arch` safely; creates `.fat_backup` by default
@@ -32,6 +38,15 @@ mdc scan
 - **Diff** — compare any two scans to see what's new or resolved
 - **HTML report** — self-contained with Chart.js doughnut + collapsible sections
 - **System inspector** — LaunchAgents, LaunchDaemons, login items, SIP status
+- **Memory pressure reliever** — reports pressure, optional cache purge
+- **Homebrew manager** — cache sizes, outdated list, cleanup and autoremove
+- **Storage trend tracker** — snapshots disk usage over time
+- **Recent activity cleaner** — scans recent-items files (safe clear)
+- **Permissions auditor** — TCC privacy access audit (read-only)
+- **APFS snapshot guard** — list and prune local snapshots
+- **Menu bar companion** — SwiftBar/xbar plugin for last scan summary
+- **Data breach monitor** — checks emails via HIBP API (opt-in)
+- **Cloud storage junk** — scans Dropbox/Drive/OneDrive/Box caches
 - **Scheduler** — installs a LaunchAgent for weekly auto-scans
 - **macOS notifications** — via `osascript`, no dependencies
 - **CI mode** — JSON-only scan summary with threshold-based exit code
@@ -84,6 +99,9 @@ mac-cleaner clean
 # Auto-delete everything detected
 mac-cleaner clean --auto
 
+# Force preview mode (no deletes anywhere)
+mac-cleaner --dry-run clean
+
 # Permanently delete (skip undo staging)
 mac-cleaner clean --no-undo
 
@@ -125,6 +143,26 @@ mac-cleaner scan --log-file ~/mac-cleaner.log
 
 ### New scanners
 ```bash
+# Shell completions
+mac-cleaner completions --shell zsh --instructions
+
+# Full app uninstall
+mac-cleaner uninstall "Slack"
+
+# Browser data cleanup
+mac-cleaner browser-data
+mac-cleaner browser-data --browser chrome --category cache --clean
+
+# Disk usage map
+mac-cleaner space-map --depth 2 --limit 12
+
+# Photos library analyzer
+mac-cleaner photos --details
+
+# iOS simulator cleaner
+mac-cleaner simulators
+mac-cleaner simulators --purge-unavailable --yes
+
 # Find duplicate files (default: ~/Downloads, ~/Documents, ~/Desktop, ~/Pictures)
 mac-cleaner duplicates
 mac-cleaner duplicates --path ~/Movies --min-size 500
@@ -189,6 +227,44 @@ mac-cleaner system --login-items
 mac-cleaner system --health
 ```
 
+### P2/P3 system utilities
+```bash
+# Memory pressure
+mac-cleaner memory-pressure
+mac-cleaner memory-pressure --relieve
+
+# Homebrew manager
+mac-cleaner brew --outdated
+mac-cleaner brew --cleanup --yes
+
+# Storage trend snapshots
+mac-cleaner storage-trend --record
+mac-cleaner storage-trend --days 7
+
+# Recent activity cleanup (Recent Items folder only)
+mac-cleaner recent-activity
+mac-cleaner recent-activity --clear
+
+# Permissions audit (TCC)
+mac-cleaner permissions
+mac-cleaner permissions --system --export tcc.json
+
+# APFS snapshots
+mac-cleaner snapshots
+mac-cleaner snapshots --delete-older-than 14 --yes
+
+# Menu bar companion
+mac-cleaner menubar install --interval 15
+mac-cleaner menubar status --format swiftbar
+
+# Breach monitor (HIBP)
+mac-cleaner breach --email you@example.com --api-key $HIBP_API_KEY
+
+# Cloud storage junk
+mac-cleaner cloud-junk
+mac-cleaner cloud-junk --provider dropbox --clean
+```
+
 ### Scheduler
 ```bash
 mac-cleaner schedule install

SECURITY.md

@@ -1,21 +1,31 @@
 # Security Policy
 
-## Supported Versions
+## Reporting a Vulnerability
 
-Use this section to tell people about which versions of your project are
-currently being supported with security updates.
+### Security contact
+For security issues, please report privately by opening a GitHub issue on the project with the label `security` (or describing it as a security report in the issue title).
 
-| Version | Supported          |
-| ------- | ------------------ |
-| 5.1.x   | :white_check_mark: |
-| 5.0.x   | :x:                |
-| 4.0.x   | :white_check_mark: |
-| < 4.0   | :x:                |
+**Where to report:**
+- https://github.com/NK2552003/Mac-Cleaner/issues
 
-## Reporting a Vulnerability
+### What to include
+When reporting, please include:
+- A clear description of the vulnerability
+- Steps to reproduce (if applicable)
+- Expected vs actual behavior
+- Impact (e.g., data exposure, privilege escalation, remote code execution)
+- Affected versions (if known)
+
+### Disclosure expectations
+- We will acknowledge receipt of your report as soon as possible (typically within **2–3 business days**).
+- We will provide a response on whether the report is accepted and what the remediation plan/timeline looks like.
+- If accepted, we’ll work to release a fix in a subsequent release for the supported versions listed above.
+
+### Responsible disclosure
+- Do **not** publish exploit details publicly until a fix is released (or we confirm the issue is non-actionable).
+- Do **not** attempt to cause real-world damage.
+- Avoid including sensitive personal data or credentials in the report.
 
-Use this section to tell people how to report a vulnerability.
+### If you can’t use GitHub issues
+If GitHub issues are not appropriate, add a note in your report explaining why and include as much of the above information as possible.
 
-Tell them where to go, how often they can expect to get an update on a
-reported vulnerability, what to expect if the vulnerability is accepted or
-declined, etc.

checklist.md

@@ -2,45 +2,19 @@
 
 Date: 2026-05-11
 
-Use this file as the execution order. Check items only after the feature is fully implemented, wired to CLI, and covered by tests when feasible.
-
-## P0 (baseline UX and safety)
-- [ ] Global --dry-run flag (src/features/ux/dry_run.py)
-- [ ] Shell completion command (src/features/ux/completions.py)
-- [ ] Full app uninstaller (src/features/apps/uninstaller.py)
-
-## P1 (highest demand data and visibility)
-- [ ] Browser data cleaner (src/features/privacy/browser_data.py)
-- [ ] Visual disk space map (src/features/storage/space_map.py)
-- [ ] Photo library analyzer (src/features/storage/photos_analyzer.py)
-- [ ] iOS simulator deep cleaner (src/features/dev/simulators.py)
-
-## P2 (system utilities and maintenance)
-- [ ] Memory pressure reliever (src/features/system/memory_pressure.py)
-- [ ] Homebrew deep manager (src/features/apps/brew_manager.py)
-- [ ] Storage trend tracker (src/features/reporting/storage_trend.py)
-- [ ] Recent files and activity cleaner (src/features/privacy/recent_activity.py)
-
-## P3 (advanced and higher risk features)
-- [ ] Permissions auditor (src/features/security/permissions_auditor.py)
-- [ ] APFS snapshot guard (src/features/safety/apfs_snapshots.py)
-- [ ] Menu bar companion (src/features/ux/menubar.py)
-- [ ] Data breach monitor (src/features/security/breach_monitor.py)
-- [ ] Cloud storage junk scanner (src/features/storage/cloud_junk.py)
-
 ## Additional (not yet scheduled)
-- [ ] Purgeable space reclaimer (src/features/storage/purgeable.py)
-- [ ] Installer and PKG file hunter (src/features/storage/installer_hunter.py)
-- [ ] DNS cache flush (src/features/system/dns_cache.py)
-- [ ] Font cache rebuild (src/features/system/font_cache.py)
-- [ ] Spotlight re-index (src/features/system/spotlight.py)
-- [ ] Sleep and power optimizer (src/features/system/power_optimizer.py)
-- [ ] App update checker (src/features/apps/update_checker.py)
-- [ ] PKG receipt manager (src/features/apps/pkg_receipts.py)
-- [ ] Xcode derived data cleaner (src/features/dev/xcode_cleaner.py)
-- [ ] Weekly digest report (src/features/reporting/weekly_digest.py)
-- [ ] Cleaning impact score (src/features/reporting/impact_score.py)
-- [ ] Interactive TUI app picker (src/features/ux/tui_picker.py)
-- [ ] Multi-Mac config sync (src/features/ux/config_sync.py)
-- [ ] Time Machine backup guard (src/features/safety/time_machine_guard.py)
-- [ ] Restore checksum verification (src/features/safety/restore_checksums.py)
+- [ ] Purgeable space reclaimer (src/scanners/purgeable.py)
+- [ ] Installer and PKG file hunter (src/scanners/installer_hunter.py)
+- [ ] DNS cache flush (src/core/dns_cache.py)
+- [ ] Font cache rebuild (src/core/font_cache.py)
+- [ ] Spotlight re-index (src/core/spotlight.py)
+- [ ] Sleep and power optimizer (src/core/power_optimizer.py)
+- [ ] App update checker (src/core/update_checker.py)
+- [ ] PKG receipt manager (src/core/pkg_receipts.py)
+- [ ] Xcode derived data cleaner (src/scanners/xcode_cleaner.py)
+- [ ] Weekly digest report (src/reporting/weekly_digest.py)
+- [ ] Cleaning impact score (src/reporting/impact_score.py)
+- [ ] Interactive TUI app picker (src/core/tui_picker.py)
+- [ ] Multi-Mac config sync (src/core/config_sync.py)
+- [ ] Time Machine backup guard (src/core/time_machine_guard.py)
+- [ ] Restore checksum verification (src/core/restore_checksums.py)