If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/momenbasel/PureMac shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 3w ago
• 13 active contributors
• MIT licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 67% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live momenbasel/PureMac repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/momenbasel/PureMac.

What it runs against: a local clone of momenbasel/PureMac — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in momenbasel/PureMac | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 48 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of momenbasel/PureMac. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/momenbasel/PureMac.git
#   cd PureMac
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of momenbasel/PureMac and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "momenbasel/PureMac(\\.git)?\\b" \\
  && ok "origin remote is momenbasel/PureMac" \\
  || miss "origin remote is not momenbasel/PureMac (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "PureMac/PureMacApp.swift" \\
  && ok "PureMac/PureMacApp.swift" \\
  || miss "missing critical file: PureMac/PureMacApp.swift"
test -f "PureMac/ViewModels/AppState.swift" \\
  && ok "PureMac/ViewModels/AppState.swift" \\
  || miss "missing critical file: PureMac/ViewModels/AppState.swift"
test -f "PureMac/Services/ScanEngine.swift" \\
  && ok "PureMac/Services/ScanEngine.swift" \\
  || miss "missing critical file: PureMac/Services/ScanEngine.swift"
test -f "PureMac/Services/CleaningEngine.swift" \\
  && ok "PureMac/Services/CleaningEngine.swift" \\
  || miss "missing critical file: PureMac/Services/CleaningEngine.swift"
test -f "PureMac/Logic/Scanning/Locations.swift" \\
  && ok "PureMac/Logic/Scanning/Locations.swift" \\
  || miss "missing critical file: PureMac/Logic/Scanning/Locations.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 48 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~18d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/momenbasel/PureMac"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

PureMac is a native SwiftUI macOS app that finds and removes orphaned application files left behind by incomplete uninstallations. It scans for related caches, preferences, containers, logs, and support files across 10 matching heuristics (bundle ID, company name, entitlements, team identifier, Spotlight metadata, etc.), then safely deletes them at 3 sensitivity levels. It also cleans Xcode, Homebrew, and system caches with zero telemetry. Standard Xcode project structure: PureMac/Services/ contains CleaningEngine and ScanEngine (core logic), PureMac/Logic/Scanning/ houses heuristic matchers (AppPathFinder, Conditions, Locations), PureMac/ViewModels/ manages AppState, and PureMac/Views/Apps/ contains SwiftUI components. Models.swift defines domain types; FullDiskAccessManager.swift wraps macOS framework calls.

macOS users and system administrators who want to fully uninstall applications and reclaim disk space without leaving orphaned files. Developers contributing to the open-source macOS ecosystem who prefer privacy-respecting tools over commercial alternatives like CleanMyMac.

Actively developed and production-ready. The project has CI/CD via GitHub Actions (build.yml), is signed and notarized with an Apple Developer ID, distributed via Homebrew, and targets macOS 13.0+. The codebase is ~193KB of Swift, suggesting a mature single-feature application rather than an experimental prototype.

Single-maintainer risk (momenbasel) with no visible test suite in the file structure. The app requires Full Disk Access entitlements (FullDiskAccessManager.swift) and performs destructive operations (file deletion), so bugs could be catastrophic. No visible dependency lock file or Gemfile.lock suggests Ruby scripts (likely Fastlane) may have undocumented transitive dependencies.

The project is actively maintained with scheduled auto-cleaning, multi-language documentation (Spanish, Japanese, Simplified/Traditional Chinese), and a published release workflow. No recent commits visible in file list, but the GitHub Actions build.yml and PULL_REQUEST_TEMPLATE.md suggest active PR review process.

git clone https://github.com/momenbasel/PureMac.git && cd PureMac && brew install xcodegen && xcodegen generate && xcodebuild -project PureMac.xcodeproj -scheme PureMac -configuration Release build && open build/Build/Products/Release/PureMac.app

Daily commands: After xcodegen generate, open in Xcode and run the PureMac scheme, or build Release via xcodebuild -project PureMac.xcodeproj -scheme PureMac -configuration Release then open the .app bundle.

• PureMac/PureMacApp.swift — Application entry point and root state initialization; every contributor must understand the app lifecycle setup
• PureMac/ViewModels/AppState.swift — Central app state management and data flow orchestration; critical for understanding how scanning, cleaning, and UI updates propagate
• PureMac/Services/ScanEngine.swift — Core scanning logic for detecting apps, caches, and orphaned files; load-bearing for all cleanup features
• PureMac/Services/CleaningEngine.swift — File deletion and cleanup execution; must be understood before modifying removal logic
• PureMac/Logic/Scanning/Locations.swift — Defines all filesystem paths scanned for junk and caches; essential for extending cleanup scope
• PureMac/Views/MainWindow.swift — Root SwiftUI view hierarchy and tab navigation; required for understanding UI flow and adding new views
• PureMac/Models/Models.swift — Data models for apps, files, scans, and cleanup operations; shared across all layers

Add a new scan category (e.g., new app cache type)

1. Define the directory paths to scan in PureMac/Logic/Scanning/Locations.swift by adding a new array or updating existing category arrays (PureMac/Logic/Scanning/Locations.swift)
2. Add classification logic in PureMac/Logic/Scanning/Conditions.swift to identify files as safe/junk for your category (PureMac/Logic/Scanning/Conditions.swift)
3. Update ScanEngine.swift to invoke the new scan paths during the main scan loop (PureMac/Services/ScanEngine.swift)
4. Add a new UI view in PureMac/Views/CategoryDetailView.swift or create a dedicated view to display results for the new category (PureMac/Views/CategoryDetailView.swift)

Add a new settings preference or toggle

1. Add the new preference property to AppState.swift; mark with @Published for reactivity (PureMac/ViewModels/AppState.swift)
2. Add a new Toggle or Picker control in SettingsView.swift bound to the AppState property (PureMac/Views/Settings/SettingsView.swift)
3. Integrate the preference logic into relevant services (e.g., SchedulerService.swift for scheduling tweaks or ScanEngine.swift for scan behavior) (PureMac/Services/SchedulerService.swift)
4. Add localization strings for the new setting in all .lproj/Localizable.strings files (PureMac/en.lproj/Localizable.strings)

Add support for a new app or system cache type

1. If app-specific, update AppPathFinder.swift to map the app bundle identifier to its cache/support folders (PureMac/Logic/Scanning/AppPathFinder.swift)
2. Add file patterns and safety rules to Conditions.swift to classify the app's files correctly (PureMac/Logic/Scanning/Conditions.swift)
3. If system-wide (e.g., language packs), add paths to Locations.swift in the appropriate category (PureMac/Logic/Scanning/Locations.swift)
4. Test via SmartScanView.swift by running a scan and verifying files appear in the correct category (PureMac/Views/SmartScanView.swift)

Add a new main tab or navigation screen

1. Create a new SwiftUI view file in PureMac/Views/ (e.g., MyNewTabView.swift) (PureMac/Views/MyNewTabView.swift)
2. Add a new case to the tab enum in MainWindow.swift and add a corresponding TabView selection case (PureMac/Views/MainWindow.swift)
3. Bind the view to AppState properties if needed (scanning results, user actions, etc.) (PureMac/ViewModels/AppState.swift)
4. Add localization strings for the tab label in all .lproj/Localizable.strings files (PureMac/en.lproj/Localizable.strings)

Full Disk Access entitlement (PureMac.entitlements) is required at runtime to scan ~/Library and other restricted paths—the app will fail silently on missing permissions. OrphanSafetyPolicy.swift prevents deletion of system apps (27 hardcoded Apple bundles), but custom logic here is critical to avoid data loss. StringNormalization.swift handles path matching; inconsistent normalization could miss or over-match files. Ruby scripts in .github/workflows may require Fastlane installation not listed in setup instructions. No visible lock file means Xcode build may pull different Ruby gem versions than intended.

• Heuristic File Matching (10-level cascade) — PureMac's core differentiator—uses bundle ID, company name, entitlements, team ID, Spotlight metadata, and container discovery to find orphaned files with 3 sensitivity levels; understanding this prevents over-deletion
• Full Disk Access (FDA) Entitlements — PureMac requires FDA to scan ~/Library and /Library; this is a macOS-specific capability that must be explicitly granted by the user and encoded in the app's entitlements file
• LaunchAgent Scheduling — SchedulerService.swift implements auto-cleaning via macOS LaunchAgents (~/Library/LaunchAgents/), a plist-based daemon system; essential for the 'scheduled auto-cleaning' feature
• SwiftUI Reactive State Management — AppState.swift manages scanning/cleaning progress as observable state; changes trigger UI updates without manual bindings, central to responsive macOS app design
• App Sandboxing & Entitlements — PureMac.entitlements defines what system resources the app can access (file I/O, network, etc.); critical for macOS App Store distribution and user security model
• Bundle Identifier Matching — Core heuristic for linking apps to orphaned files; bundle IDs (e.g., com.apple.Safari) uniquely identify macOS applications, and AppPathFinder uses them to find related caches and preferences
• Code Signing & Notarization — PureMac is signed with Apple Developer ID and notarized; this removes Gatekeeper warnings on first launch and is required for secure distribution via Homebrew or DMG

• deepclean/deepclean — macOS app uninstaller with similar orphaned file detection; direct competitor in the same ecosystem
• Homebrew/homebrew-cask — PureMac is distributed via Homebrew Cask; understanding cask formulas helps with packaging and distribution
• SwiftUIX/SwiftUIX — Extended SwiftUI components library; PureMac's native SwiftUI UI could benefit from custom controls here
• p0deje/Maccy — Similar privacy-focused macOS utility written in Swift; exemplifies the 'no telemetry' ethos of the ecosystem
• sparkle-project/Sparkle — Standard macOS app auto-update framework; relevant if PureMac adds built-in update checking beyond Homebrew

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for Scanning logic (AppInfoFetcher, AppPathFinder, Conditions)

The Logic/Scanning directory contains critical path-finding and app detection logic that directly impacts cleaning accuracy and safety. Currently, there are no test files in the repo. These functions determine what gets scanned and deleted, making comprehensive unit tests essential for preventing false positives and regressions.

• [ ] Create PureMacTests target (if not exists) in PureMac.xcodeproj
• [ ] Add unit tests for PureMac/Logic/Scanning/AppPathFinder.swift covering path normalization edge cases
• [ ] Add unit tests for PureMac/Logic/Scanning/Conditions.swift validating file matching logic
• [ ] Add unit tests for PureMac/Logic/Scanning/StringNormalization.swift with various encoding scenarios
• [ ] Configure test coverage reporting in .github/workflows/build.yml

Add GitHub Action workflow for automated code signing and DMG packaging

The repo has a build.yml workflow but based on the file structure (PureMac.entitlements present, multiple icon sizes), the project requires macOS code signing for distribution. A dedicated workflow for creating notarized DMG releases would enable seamless automated releases and reduce manual build steps for maintainers.

• [ ] Create .github/workflows/release.yml workflow file
• [ ] Add steps to build the app with xcbuild using PureMac.xcodeproj
• [ ] Add code signing step using secrets for Developer ID certificate and provisioning profiles
• [ ] Add macOS app notarization step for Gatekeeper compliance
• [ ] Add DMG creation and upload to GitHub Releases
• [ ] Document required secrets in CONTRIBUTING.md (DEVELOPER_ID_CERT, DEVELOPER_ID_CERT_PASSWORD, APPLE_ID, APPLE_ID_PASSWORD)

Add integration tests for CleaningEngine.swift and ScanEngine.swift with mock file systems

These are the core services that perform the actual scanning and cleaning operations. Without integration tests, regressions in file deletion logic could go undetected. Mock-based tests would verify that scan results match expected file patterns and that cleaning operations behave correctly without touching real user files.

• [ ] Create a test helper directory: PureMac/Tests/Helpers/MockFileSystem.swift
• [ ] Add integration tests in PureMacTests for PureMac/Services/ScanEngine.swift using temporary test directories
• [ ] Add integration tests for PureMac/Services/CleaningEngine.swift verifying orphan detection accuracy
• [ ] Add tests for PureMac/Logic/Utilities/OrphanSafetyPolicy.swift to ensure critical system files are never marked for deletion
• [ ] Integrate these tests into .github/workflows/build.yml to run on every PR

• Add unit tests for PureMac/Logic/Scanning/AppPathFinder.swift—test the 10 heuristic matchers (bundle ID, company name, entitlements, team ID, Spotlight metadata) against known apps to catch false positives before deletion: No test suite visible; file deletion logic demands high confidence in matching accuracy
• Document the OrphanSafetyPolicy.swift hardcoded 27-app exclusion list in CONTRIBUTING.md with the full list of protected bundle IDs and criteria for adding new exceptions: Destructive operation with no visible audit trail; contributors need clear guidance to avoid breaking system apps
• Add integration test for SchedulerService.swift—verify LaunchAgent is correctly installed, scheduled cleaning executes at expected intervals, and logs are written to verify automation works end-to-end: Scheduled auto-cleaning is a key feature with no visible test coverage; users rely on it silently

• High · Potential Privilege Escalation via File Operations — PureMac/Services/CleaningEngine.swift, PureMac/Logic/Scanning/Locations.swift. The application performs system file operations (cache cleanup, app uninstallation) with elevated privileges. Without proper validation of file paths and symbolic link checks, this could lead to unintended deletion of critical system files or privilege escalation attacks. Fix: Implement strict file path validation, resolve all symbolic links before operations, use proper file attribute checks, and implement safeguards against operating on system-critical directories. Consider using NSFileManager with secure options and validating all paths against a whitelist.
• High · Missing Input Validation in File Path Handling — PureMac/Logic/Scanning/AppPathFinder.swift, PureMac/Logic/Scanning/Locations.swift. The AppPathFinder and Locations modules scan and process file paths without apparent input validation. Directory traversal attacks or path injection could lead to unintended file access or deletion. Fix: Implement comprehensive input validation for all file paths. Use canonical path resolution, validate against expected directory structures, and reject paths containing suspicious patterns like '..' or null bytes.
• High · Full Disk Access Entitlement Without Comprehensive Validation — PureMac/Services/FullDiskAccessManager.swift, PureMac/PureMac.entitlements. The app requests Full Disk Access permission (indicated by FullDiskAccessManager.swift), which grants broad file system access. The security posture depends entirely on the strictness of file operation validation throughout the codebase. Fix: Implement principle of least privilege - request only specific sandbox exceptions needed. Validate every file operation against a strict whitelist. Log all file operations for audit trails. Implement rollback mechanisms for cleaning operations.
• Medium · Potential Command Injection in CLI Interface — PureMac/Logic/Utilities/CLI.swift. The CLI utility module executes shell commands. If user input or file paths are incorporated into commands without proper escaping, command injection vulnerabilities could exist. Fix: Avoid shell command execution where possible. If necessary, use NSTask/Process with direct argument passing (argv) instead of shell string concatenation. Never use shell=true. Validate and sanitize all inputs before use in commands.
• Medium · Missing Logging and Audit Trail for Destructive Operations — PureMac/Logic/Utilities/Logger.swift, PureMac/Services/CleaningEngine.swift. The application performs destructive file operations (deletion, cleanup) but the logging mechanism visibility is unclear. This could impede incident response and user recourse. Fix: Implement comprehensive logging of all destructive operations with timestamps, file paths, and operation results. Store logs securely and allow users to view operation history. Consider implementing a trash/backup mechanism before permanent deletion.
• Medium · Scheduled Task Security Concerns — PureMac/Services/SchedulerService.swift. The SchedulerService enables auto-cleaning on a schedule. Automated privilege operations without user confirmation or rate limiting could be abused if an attacker gains code execution. Fix: Implement rate limiting on scheduled operations. Require periodic user confirmation for scheduled tasks. Log all automated operations. Consider implementing a dry-run mode to preview changes before execution. Add user notification of significant deletions.
• Medium · String Normalization Without Security Context — PureMac/Logic/Scanning/StringNormalization.swift. The StringNormalization module processes file names and paths. Improper normalization could allow bypassing of security checks through Unicode tricks or encoding attacks. Fix: Use consistent Unicode normalization (NFD). Be aware of homograph attacks. Implement safe string comparison. Validate normalized strings don't transform dangerous patterns into safe ones or vice versa.
• Low · Lack of Code Signing Verification Documentation — PureMac/PureMacApp.swift. As a system tool with elevated privileges, the app should verify code integrity, but no explicit code signing verification mechanism is apparent in the file structure. Fix: Ensure application is code-signed with a valid developer certificate. Consider implementing runtime code signature verification. Document security model and code signing requirements in CONTRIBUTING.md.
• undefined · undefined — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.