How the AppUninstaller in vorssaint-utils Finds and Removes Application Leftovers

The AppUninstaller in vorssaint-utils removes application leftovers by executing a comprehensive shell script that terminates processes, deregisters system daemons, resets TCC permissions, and scrubs filesystem artifacts across user and system directories.

The vorssaint-utils repository provides a Swift-based utility suite for macOS system management, featuring a robust uninstallation mechanism designed to eliminate all traces of the application. The AppUninstaller coordinates between Swift-based entry points and a bundled bash script to ensure complete removal of binaries, preferences, and system configurations. This analysis examines the exact file paths, method signatures, and command sequences used to locate and delete these remnants according to the vorssaint/vorssaint-utils source code.

Entry Point Detection in main.swift

In Sources/Vorssaint/main.swift at lines 17-19, the application detects the --uninstall flag during launch initialization. When this argument is present, control immediately transfers to the Swift Uninstaller component rather than initializing the standard graphical interface.

The Uninstaller class defined in Sources/Vorssaint/Support/Uninstaller.swift serves as the primary Swift wrapper for in-app uninstall operations. This component does not perform filesystem cleanup directly; instead, it locates and executes the bundled shell script at Tools/uninstall.sh, passing the necessary execution context and privileges required for system-level modifications.

The Shell Script Driver

The exhaustive cleanup logic resides entirely within Tools/uninstall.sh, which the Swift layer invokes to perform coordinated system cleaning. The script operates through eight distinct stages, each targeting specific categories of application leftovers through deterministic discovery methods and forced removal techniques.

Locating Application Leftovers

The AppUninstaller discovers residual artifacts through three primary discovery mechanisms implemented in the shell script:

• Static Bundle Identification: Hardcoded absolute paths to /Applications/Vorssaint.app and the legacy /Applications/Vorssaint Utils.app bundle locations.
• Launchctl Registration Queries: Direct inspection of the macOS service management framework for fan-helper daemon registrations under the com.vorssaint.utils bundle identifier.
• User Defaults Inspection: Reading the custom vorssDisabledSleep preference flag to determine if system sleep settings require restoration.

Systematic Removal of Components

Process Termination

Lines 16-19 of uninstall.sh immediately terminate any running application instances using pkill -x to send SIGTERM signals to processes matching Vorssaint or VorssaintUtils. This prevents file-locking issues during subsequent deletion steps.

Daemon Deregistration and Login Item Removal

Between lines 26-44, the script executes deregistration logic for the fan-control launch-daemon and login items. The script first attempts to invoke the app binary with the --uninstall argument if the bundle remains accessible. If the binary has been deleted, it falls back to querying launchctl directly for service registration status and forcibly removes the persistent daemon.

System Sleep State Restoration

Lines 47-61 handle restoration of system power management settings. The script checks the defaults database for the vorssDisabledSleep key. If the application had previously disabled system sleep, the script queries pmset to verify whether sleep remains disabled and emits a terminal warning to alert the user to manual intervention requirements.

TCC Permission Reset

At lines 54-56, the script executes tccutil reset All targeting the com.vorssaint.utils bundle identifier. This command purges Accessibility and Screen Recording permissions from the macOS Transparency, Consent, and Control database, ensuring no residual entitlements exist post-removal.

Filesystem Cleanup Execution

The script performs recursive deletion of multiple artifact categories:

• Application Bundles: Removes /Applications/Vorssaint.app and legacy variants at lines 57-58 using rm -rf.
• Preferences and Saved State: Executes defaults delete for the bundle identifier, manually removes plist files from ~/Library/Preferences/, deletes saved-state directories, and removes the generic-password Keychain entry used for command-bar query-habits storage at lines 59-64.
• User Data Directories: Purges ~/Library/Application Support/<bundle>/, cache folders, HTTP storage directories, and ByHost-specific plist files at lines 66-77.

Sudoers Configuration Removal

Lines 78-82 check for privilege escalation rules in /etc/sudoers.d/ that facilitate closed-lid operation. When pre-installed snippets are detected, the script invokes AppleScript privilege escalation prompts to remove these security-sensitive configurations.

Final Status Reporting

Lines 84-122 implement conditional logic that evaluates the success of the detach, sleep-restore, and daemon-removal operations. The script prints structured progress messages and exits with appropriate status codes indicating full success or specific component failures.

Practical Execution Examples

Execute the uninstaller directly from Terminal using the binary's command-line interface:

# Standard invocation through the app binary

/Applications/Vorssaint.app/Contents/MacOS/Vorssaint --uninstall

# Direct script execution if the bundle was previously deleted

sudo /tmp/instagit_crcud1rs/Tools/uninstall.sh

The script emits structured progress output during operation:

▸ Quitting…
▸ Detaching the fan helper and login item, restoring sleep…
▸ Resetting permissions (Accessibility, Screen Recording)…
▸ Removing app, preferences, saved state and stored data…
✓ Vorssaint fully removed.

If the fan-helper daemon remains registered after deregistration attempts, the script emits specific warnings in the final reporting phase while completing all other cleanup operations.

Summary

• Entry Detection: Sources/Vorssaint/main.swift catches the --uninstall flag at lines 17-19 and routes execution to the Uninstaller class.
• Script Invocation: Sources/Vorssaint/Support/Uninstaller.swift wraps and executes Tools/uninstall.sh with appropriate privileges.
• Discovery Method: Combines static bundle paths, launchctl queries for com.vorssaint.utils, and inspection of the vorssDisabledSleep user default.
• Complete Cleanup: Terminates processes via pkill, deregisters launch-daemons, resets TCC permissions via tccutil, restores pmset sleep configurations, and purges filesystem artifacts including preferences, caches, and sudoers rules.

Frequently Asked Questions

How do I manually trigger the AppUninstaller from the command line?

Execute the binary with the --uninstall flag: /Applications/Vorssaint.app/Contents/MacOS/Vorssaint --uninstall. If the application bundle has already been removed, run the shell script directly with superuser privileges: sudo /path/to/Tools/uninstall.sh.

Which system permissions does the uninstaller reset?

According to lines 54-56 of Tools/uninstall.sh, the script runs tccutil reset All com.vorssaint.utils, which clears all Accessibility and Screen Recording permissions granted to the application from the macOS TCC database.

Does the AppUninstaller restore system sleep settings altered by the application?

Yes. The script checks the vorssDisabledSleep preference at lines 47-61. If the utility previously disabled system sleep, the script queries pmset to verify the current power state and emits a warning if sleep remains disabled, as this requires manual user correction.

What occurs if the fan-helper daemon cannot be removed?

At lines 26-44, the script attempts deregistration by executing the app binary with --uninstall or querying launchctl directly. If the daemon remains registered after these attempts, the final status reporting block at lines 84-122 emits a specific warning but continues with remaining cleanup tasks, ensuring partial removal does not block other critical cleanup operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}