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/alienator88/Pearcleaner 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.

WAIT — Slowing — last commit 3mo ago

• Last commit 3mo ago
• 4 active contributors
• Other licensed
• CI configured
• ⚠ Slowing — last commit 3mo ago
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 97% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ 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 alienator88/Pearcleaner repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/alienator88/Pearcleaner.

What it runs against: a local clone of alienator88/Pearcleaner — 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 alienator88/Pearcleaner | Confirms the artifact applies here, not a fork | | 2 | License is still Other | 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 ≤ 129 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of alienator88/Pearcleaner. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/alienator88/Pearcleaner.git
#   cd Pearcleaner
#
# 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 alienator88/Pearcleaner and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other 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 "Pearcleaner/Logic/AppState.swift" \\
  && ok "Pearcleaner/Logic/AppState.swift" \\
  || miss "missing critical file: Pearcleaner/Logic/AppState.swift"
test -f "Pearcleaner/Logic/AppCommands.swift" \\
  && ok "Pearcleaner/Logic/AppCommands.swift" \\
  || miss "missing critical file: Pearcleaner/Logic/AppCommands.swift"
test -f "Pearcleaner/Logic/AppPathsFetch.swift" \\
  && ok "Pearcleaner/Logic/AppPathsFetch.swift" \\
  || miss "missing critical file: Pearcleaner/Logic/AppPathsFetch.swift"
test -f "Pearcleaner/Logic/AppsUpdater/UpdateManager.swift" \\
  && ok "Pearcleaner/Logic/AppsUpdater/UpdateManager.swift" \\
  || miss "missing critical file: Pearcleaner/Logic/AppsUpdater/UpdateManager.swift"
test -f "Pearcleaner/Logic/Brew/HomebrewController.swift" \\
  && ok "Pearcleaner/Logic/Brew/HomebrewController.swift" \\
  || miss "missing critical file: Pearcleaner/Logic/Brew/HomebrewController.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 129 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~99d)"
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/alienator88/Pearcleaner"
  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).

Pearcleaner is a native Swift/SwiftUI macOS app that performs deep uninstallation of applications by searching and removing orphaned files, caches, and associated data—similar to AppCleaner but open-source. It extends beyond simple app deletion by offering orphaned file discovery, Homebrew package management, app architecture stripping (lipo), plugins/services cleanup, and a Finder extension for right-click uninstalls. Single monolithic Xcode project (Pearcleaner.xcodeproj) with a main app target and a FinderOpen Finder extension companion target. Swift is the primary language (~1.9MB) with some legacy Objective-C (~47KB) and minimal C (~163B). Resources live in 'Pear Resources/' (icons, assets); CI workflows are minimal (.github/workflows/issues.yml for automation only).

macOS users who want thorough app uninstallation without leaving behind caches and preference files; developers using Swift/SwiftUI who want to learn macOS filesystem handling, app installation mechanics, and desktop UI patterns; contributors interested in fair-code licensed open-source tools.

Moderately mature but currently dormant: v5.4.3 is stable and released, but the maintainer explicitly stated in the README they have no spare time due to a new SaaS venture and are not actively reviewing issues or merging PRs. The codebase is production-ready for end users (no known critical bugs visible), but the project is in maintenance-only mode with infrequent updates.

Single-maintainer burnout risk is explicit and documented—the author has paused active development indefinitely. No visible automated tests in the file list (no Tests/ directory shown) increases regression risk on contributions. The project accepts PRs only when maintainer has bandwidth, creating review bottlenecks. macOS platform-specific code paths (FSEvents, file system operations, Finder integration) have narrow testing surface.

Active maintenance is paused. The README explicitly states the maintainer is unavailable. The last notable activity was version 5.4.3 release. Community PRs are invited but not actively reviewed. No visible open milestones or feature branches in the provided file list.

Clone the repo and open in Xcode 15+: git clone https://github.com/alienator88/Pearcleaner.git && cd Pearcleaner && open Pearcleaner.xcodeproj. Then select the 'Pearcleaner' scheme and press Cmd+R to build and run. Requires macOS 12+ as a target.

Daily commands: Open Pearcleaner.xcodeproj in Xcode 15+, select the 'Pearcleaner' scheme, and press Cmd+R. The app launches as a regular macOS application. For the Finder extension, select the 'FinderOpen' scheme and run to install it in the active Finder session.

• Pearcleaner/Logic/AppState.swift — Central state management object for the entire application; all UI and logic flows depend on this singleton
• Pearcleaner/Logic/AppCommands.swift — Core command handler that orchestrates app deletion, file scanning, and cleanup operations
• Pearcleaner/Logic/AppPathsFetch.swift — Critical file discovery engine that locates app-related artifacts across the filesystem
• Pearcleaner/Logic/AppsUpdater/UpdateManager.swift — Coordinates update checking and installation across App Store, Homebrew, and Sparkle frameworks
• Pearcleaner/Logic/Brew/HomebrewController.swift — Primary interface for Homebrew package management integration
• Pearcleaner/Logic/AppInfoFetch.swift — Aggregates application metadata and dependency information for display and cleanup decisions

• AppState (Swift, Combine @Published) — Single source of truth for all application state: selected apps, cleanup results, settings, update status
  • Failure mode: State corruption leads to UI displaying incorrect or stale data; lost user selections
• AppPathsFetch (FileManager API, Bundle inspection) — Discovers all artifacts associated with an app (caches, preferences, frameworks, support files)
  • Failure mode: Incomplete artifact discovery leaves behind orphaned files; over-aggressive deletion removes unrelated files
• AppCommands (FileManager, Process (shell), AppPathsFetch, HomebrewController) — Executes the actual deletion, restoration, and cleanup workflows; orchestrates other services
  • Failure mode: Deletion failure causes app to appear broken; restoration failure leaves app in unrecoverable state
• UpdateManager (CommerceKit, StoreFoundation, Sparkle, URLSession) — Coordinates update detection and installation across App Store, Homebrew, and Sparkle sources
  • Failure mode: Failed update check silently, leaving user unaware of available updates; failed installation corrupts app
• HomebrewController (Process, shell (bash), Homebrew CLI) — Bridge between Pearcleaner and Homebrew; enumerates packages and invokes brew commands
  • Failure mode: Homebrew not installed or in unexpected path causes package operations to fail silently

• User selection in UI → AppState — User marks apps for cleanup; state updated reactively
• undefined → undefined — undefined

Add a new app update source

1. Create a new checker class conforming to the update protocol in AppsUpdater/ (Pearcleaner/Logic/AppsUpdater/[NewSourceName]UpdateChecker.swift)
2. Add checker instantiation and type in UpdateManager.swift switch/case logic (Pearcleaner/Logic/AppsUpdater/UpdateManager.swift)
3. Define Models for the new source if needed (version, download URL, etc.) (Pearcleaner/Logic/AppsUpdater/Models.swift)

Add a new artifact type to clean

1. Define search paths and file patterns in AppPathsFetch.swift for the new artifact category (Pearcleaner/Logic/AppPathsFetch.swift)
2. Update AppState.swift to add a new boolean or array property to track the artifact type (Pearcleaner/Logic/AppState.swift)
3. Add deletion logic in AppCommands.swift to handle removal of the new artifact type (Pearcleaner/Logic/AppCommands.swift)

Add a new Homebrew-related feature

1. Extend HomebrewController.swift with a new public function that wraps brew CLI command (Pearcleaner/Logic/Brew/HomebrewController.swift)
2. If background checking is needed, add logic to HomebrewAutoUpdateManager.swift (Pearcleaner/Logic/Brew/HomebrewAutoUpdateManager.swift)
3. Call new function from AppCommands.swift or update-related code (Pearcleaner/Logic/AppCommands.swift)

• SwiftUI — Modern declarative UI framework native to macOS; enables reactive state-driven interface updates
• Combine framework — Reactive programming for event-driven state management and asynchronous task coordination
• Homebrew CLI — Direct integration with widely-used package manager; no need to reimplement package detection
• App Store private frameworks (CommerceKit, StoreFoundation) — Direct App Store integration for update checking and purchase management without REST API dependency
• Sparkle framework — Industry-standard update delivery system for indie macOS apps; handles delta updates and code signing

• Use private frameworks for App Store integration

  • Why: Avoids relying on undocumented web APIs and provides direct access to real update channels
  • Consequence: Fragile to macOS/framework updates; may break on OS updates; not officially supported by Apple

• Serialize update operations in UpdateQueue rather than parallel installation

  • Why: Prevents race conditions and file lock conflicts during concurrent updates
  • Consequence: Slower multi-app updates; user must wait longer for bulk operations to complete

• Shell out to Homebrew CLI rather than linking against Homebrew libraries

  • Why: Simplifies dependency management and avoids coupling to Homebrew's internal APIs
  • Consequence: Process spawning overhead; requires Homebrew to be installed; slower than direct library calls

• Cross-platform support (macOS-only)
• Real-time file system monitoring during cleanup
• Network-based remote cleaning or cloud synchronization
• Integration with paid app distribution services beyond App Store
• Malware or threat detection (artifact-only cleaner, not antivirus)

Finder extension requires specific entitlements and code signing—development builds may fail to load the extension without proper provisioning profiles. File system operations on macOS require Full Disk Access permission granted in System Preferences, which the app requests at runtime but cannot grant programmatically. The app uses Objective-C bridges to system frameworks that may be deprecated in future macOS versions—no abstraction layer visible to ease future updates. Homebrew detection likely depends on hardcoded /usr/local/ or /opt/homebrew/ paths which differ between Intel and Apple Silicon Macs.

• Finder Extension (FinderSync framework) — Pearcleaner's right-click context menu integration uses FinderSync; understanding how to communicate with Finder and handle IPC is essential for this feature.
• Code Signing and Entitlements — The app requires Full Disk Access and Finder extension entitlements; macOS sandboxing means understanding .entitlements files and provisioning profiles is mandatory for local development.
• File System Enumeration (FSEvents, FileManager) — Core to the orphaned file discovery feature; Pearcleaner must efficiently walk the file system and identify files associated with deleted apps, requiring knowledge of macOS file APIs.
• App Bundle Structure and Info.plist — Uninstall logic depends on parsing app bundles and their metadata; contributors need to understand macOS app anatomy (CFBundleIdentifier, executable paths, etc.).
• Process Management and Task Execution — Pearcleaner runs shell commands (e.g., brew list, lipo for architecture stripping) via Process/Foundation tasks; understanding stdout/stderr capture and exit codes is needed.
• SwiftUI Architecture Patterns (MVVM, State Management) — The UI is built in SwiftUI; contributors must understand @State, @ObservedObject, and navigation patterns to modify or extend views without breaking reactivity.
• Sparse Uninstall Metadata (Plist Parsing) — App caches, preferences, and metadata live in Library/ subdirectories and ~/.app-specific folders; parsing plist files and matching heuristics is core to finding orphans.

• freemacsoft/AppCleaner — Direct inspiration for Pearcleaner; closed-source commercial cleaner that Pearcleaner aims to replicate as open-source alternative.
• sunknudsen/privacy-guides — Original shell-script-based app cleaner that inspired the manual app uninstall approach; demonstrates the problem domain before native macOS apps tackled it.
• mas-cli/mas — Swift-based macOS utility for managing App Store apps from CLI; shares similar Swift ecosystem patterns and macOS framework usage that Pearcleaner contributors will encounter.
• homebrew/brew — Pearcleaner integrates with Homebrew package management; understanding brew's structure and CLI output parsing is needed for the Homebrew Manager feature.
• SwiftUIX/SwiftUIX — Community SwiftUI component library that could modernize Pearcleaner's UI if adopted; relevant for contributors exploring SwiftUI extension patterns.

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 GitHub Actions workflow for Swift build validation and testing

The repo has xcschemes defined (Pearcleaner Debug, Pearcleaner Release, PearcleanerSentinel, FinderOpen) but no CI workflow to validate builds on PRs. This prevents catch regressions early and builds confidence for contributors. A Swift/xcodebuild workflow would validate that incoming PRs compile successfully and don't break existing schemes.

• [ ] Create .github/workflows/swift-build.yml that runs on PR events
• [ ] Add xcodebuild steps for each scheme: 'Pearcleaner Debug', 'Pearcleaner Release', 'FinderOpen'
• [ ] Configure to build for macOS platform matching the xcodeproj SDK settings
• [ ] Add step to validate no build warnings are introduced (optional but valuable)
• [ ] Test workflow locally with act or by pushing to a fork

Create integration tests for AppPathsFetch.swift and AppInfoFetch.swift

The Logic folder contains critical data-fetching modules (AppPathsFetch.swift, AppInfoFetch.swift, AppCommands.swift) but there are no visible test files in the repo structure. These modules directly impact app uninstall safety and accuracy. Adding tests would prevent regressions and document expected behavior for path detection and app metadata fetching.

• [ ] Create Pearcleaner/Tests/ directory with AppPathsFetchTests.swift
• [ ] Add test cases for common app bundle paths (/Applications, ~/Applications, /usr/local/bin)
• [ ] Create AppInfoFetchTests.swift with mock plist parsing scenarios
• [ ] Test edge cases: missing Info.plist, malformed app bundles, permission-denied scenarios
• [ ] Ensure tests can run via xcodebuild test scheme

Document the FinderOpen helper app and Sentinel target purpose in README

The repo contains two non-obvious targets: FinderOpen (a helper app) and PearcleanerSentinel (two schemes in xcshareddata), but the main README provides no explanation of their roles. New contributors will struggle to understand the architecture. Adding a brief architecture section clarifies why these exist and how they integrate with the main Pearcleaner app.

• [ ] Add 'Architecture' section to README.md after the Project Status note
• [ ] Explain FinderOpen's role (appears to be a helper for Finder integration based on FinderOpen.swift and entitlements)
• [ ] Document PearcleanerSentinel's purpose (privilege escalation helper for deletions?)
• [ ] Add diagram or ASCII art showing component relationships if possible
• [ ] Reference relevant files: FinderOpen/FinderOpen.swift, PearcleanerSentinel scheme definitions

• Add unit tests for the file orphan-discovery logic (likely in a module not shown in file list) to ensure regex patterns and path matching are correct across different app configurations—currently no Tests/ directory visible, making regression risky.
• Expand the localization coverage in Localizable.xcstrings to languages not yet included (examine which .strings files exist) and document the translation process in a CONTRIBUTING.md guide for community translators.
• Create a GitHub Actions workflow to automatically build and code-sign release artifacts on new tags, reducing the manual distribution burden on the maintainer shown in Builds/ExportOptions.plist.

The Pearcleaner codebase shows concerning use of private Apple frameworks and file system operations that present moderate to high security risks. The app performs system-level operations (app deletion, package management) that require careful security controls. Primary concerns include: (1) reliance on undocumented private frameworks, (2) file system operations requiring strict validation, (3) integration with package managers needing secure subprocess handling, and (4) App Store API integration requiring transport security. The project demonstrates typical macOS app architecture but lacks visible implementation of

• High · Use of Private Frameworks — Pearcleaner/Logic/AppsUpdater/PrivateFrameworks/. The codebase includes private Apple frameworks (CommerceKit, StoreFoundation, CFBundle) that are not part of the public SDK. These frameworks are undocumented and subject to change without notice. Using them may violate Apple's App Store guidelines and could cause the app to break on macOS updates. Additionally, private framework usage increases security risks due to lack of transparency and official support. Fix: Replace private framework usage with public APIs from AppKit, Foundation, and other official macOS frameworks. Contact Apple if specific functionality requires private APIs and consider filing a feature request through Apple's developer program.
• High · Unrestricted File System Operations — Pearcleaner/Logic/AppCommands.swift, Pearcleaner/Logic/AppPathsFetch.swift. The app performs file deletion and traversal operations (AppPathsFetch.swift, AppCommands.swift). Without visible input validation and sandboxing restrictions, there is risk of accidental or malicious deletion of critical system files if path traversal vulnerabilities exist or if user input is not properly sanitized. Fix: Implement strict input validation for all file paths, use file system sandbox restrictions via entitlements, verify paths against a whitelist of safe deletion targets, and require explicit user confirmation for sensitive operations. Review entitlements in FinderOpen/FinderOpen.entitlements.
• Medium · Homebrew Package Management Integration — Pearcleaner/Logic/AppsUpdater/HomebrewUpdateChecker.swift, Pearcleaner/Logic/AppsUpdater/HomebrewAdoption.swift. The app integrates with Homebrew (HomebrewUpdateChecker.swift, HomebrewAdoption.swift) to manage package installations and updates. If not properly validated, this could allow execution of arbitrary commands or installation of compromised packages. Fix: Validate all Homebrew package names and versions against known safe sources. Use subprocess execution best practices with explicit argument arrays (not shell strings). Verify GPG signatures on downloaded packages when possible and implement integrity checks.
• Medium · App Store API Integration Security — Pearcleaner/Logic/AppsUpdater/AppStoreUpdateChecker.swift, Pearcleaner/Logic/AppsUpdater/AppStoreUpdater.swift. The codebase includes App Store update checking and installation (AppStoreUpdateChecker.swift, AppStoreUpdater.swift). Network requests to App Store servers should be validated and certificate pinning should be considered to prevent MITM attacks. Fix: Implement certificate pinning for App Store API requests, validate all responses, use HTTPS exclusively, implement timeout protections, and log security-relevant events. Consider using official App Store frameworks where available.
• Medium · Missing Dependency Vulnerability Scanning — Pearcleaner.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved. The Package.resolved file exists but cannot be fully analyzed from the provided context. Swift Package Manager dependencies should be regularly scanned for known vulnerabilities. Fix: Implement automated dependency scanning using tools like Swift Security Scanner or GitHub's dependency checking. Regularly audit and update all direct and transitive dependencies. Pin specific versions and review changelog before updating.
• Low · Potential Information Disclosure via Logging — Pearcleaner/Logic/AppInfoFetch.swift, Pearcleaner/Logic/AppState.swift. AppInfoFetch.swift and other logic files may log sensitive application data. If logging is too verbose or not properly redacted, it could expose user paths, app names, or other system information in logs. Fix: Review all logging statements and ensure sensitive information (file paths, user data, system details) is redacted or not logged in production builds. Use appropriate log levels (Debug for verbose output, Info for important events only).

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.