How Vorssaint Handles Uninstalled Feature Settings: Complete Technical Guide

Vorssaint treats feature uninstallation as a reversible state change rather than a destructive operation, preserving all settings in user defaults so features resume with their previous configuration upon re-installation.

The vorssaint/vorssaint-utils project implements a modular architecture where users can selectively enable or disable individual utilities. Understanding how uninstalled feature settings are managed requires examining the interplay between the FeatureCatalog, FeatureRuntime, and the underlying Defaults persistence layer.

The Uninstall-as-State-Change Architecture

Unlike traditional uninstall mechanisms that delete data, Vorssaint's approach centers on a single boolean flag. Each feature maintains an installed state alongside its dedicated preference keys under the namespace com.vorssaint.utils.feature.<id>.settings.

This design emerges from the project's "Install only what you use" philosophy, explicitly documented in the repository's README. The practical implication: users can experiment with features without fear of losing carefully tuned configurations.

How the Runtime Filters Uninstalled Features

The FeatureCatalog (Sources/Vorssaint/Core/FeatureCatalog.swift) serves as the gatekeeper at application startup. It reads the persisted installation flags from UserDefaults and builds an allow list of features to instantiate.

// FeatureCatalog.swift – startup filtering logic
func loadInstalledFeatures() -> [Feature] {
    return allAvailableFeatures.filter { feature in
        Defaults.isFeatureInstalled(feature.id)  // Only true = loaded
    }
}

Uninstalled features never reach the FeatureRuntime (Sources/Vorssaint/App/FeatureRuntime.swift). This guarantees zero resource consumption—no memory allocation, no background processes, no UI registration.

Persistent Settings Survive Uninstallation

The critical insight: the Defaults system receives no deletion commands during uninstall. The setFeatureInstalled(false, for: id) call only mutates the state flag, leaving all feature-specific preferences intact.

// Vorssaint's uninstall implementation preserves settings
func uninstallFeature(_ id: FeatureID) {
    Defaults.setFeatureInstalled(false, for: id)  // Toggle flag only
    // All preference keys remain in UserDefaults
}

This enables seamless restoration. When a user re-installs a feature, the previous volumeLevel, hotkeyBindings, or customScripts values are immediately available without migration or reconfiguration.

In-Session Behavior and Memory Management

The uninstall action triggers immediate UI feedback but deferred memory cleanup. The feature's row disappears from Settings → Features, yet the underlying object persists until application termination.

This behavior surfaces in the user-facing strings defined in Sources/Vorssaint/Core/FeatureHubStrings.swift:

// FeatureHubStrings.swift – user communication about restart requirement
static let restartNote = "Features uninstalled in this session stay loaded until the app restarts. Restart now to unload them from memory."

static let footerNote = "Uninstalling deletes nothing: the feature just leaves the app and stops loading. Install it again anytime and everything returns as it was."

The restartButton provides optional immediate cleanup, though users may continue working and restart at their convenience.

Accessing Settings of Currently Uninstalled Features

Because preferences exist independently of installation state, code can retrieve values for inactive features. This supports migration tools, backup utilities, or analytics that need historical configuration data.

// Settings remain accessible regardless of installation state
let mixerVolume = Defaults.float(forKey: "vorssaint.feature.mixer.volume")
let uninstallerPaths = Defaults.stringArray(forKey: "vorssaint.feature.uninstaller.safePaths")

Direct key access bypasses the FeatureCatalog filter, enabling advanced use cases while the standard runtime path remains blocked.

Complete Uninstallation and Deep Cleanup

For users requiring irreversible removal, the repository provides Tools/uninstall.sh. This shell script performs comprehensive teardown:

# uninstall.sh – destructive cleanup (external to app runtime)

defaults delete com.vorssaint.utils        # Removes ALL defaults including feature flags

rm -rf /Applications/Vorssaint.app

# Additional cleanup for login items, launch agents...

This script is not invoked by in-app uninstall actions—it requires deliberate manual execution, protecting against accidental data loss.

Code Reference: The Complete Settings Lifecycle

import VorssaintCore

// 1. Verify installation status (runtime-gated)
let catalog = FeatureCatalog.shared
if catalog.isFeatureInstalled(.uninstaller) {
    let feature = catalog.instantiate(.uninstaller)
    feature.activate()
}

// 2. Toggle installation state (survives app restarts)
Defaults.setFeatureInstalled(false, for: .uninstaller)  // Uninstall
Defaults.setFeatureInstalled(true, for: .uninstaller)   // Re-install

// 3. Direct preference access (bypasses installation check)
let legacySetting = Defaults.object(forKey: "vorssaint.feature.uninstaller.legacyPaths")

Summary

• State-based filtering: The installed flag in UserDefaults determines which features load at startup (FeatureCatalog.swift).
• Non-destructive uninstall: Only the state flag changes; all preference data persists for potential restoration.
• Memory retention: Uninstalled features remain in RAM until application restart, communicated via FeatureHubStrings.restartNote.
• Explicit deep cleanup: The separate Tools/uninstall.sh script handles irreversible removal when required.
• Direct access possible: Raw Defaults keys allow reading settings of uninstalled features outside the standard runtime path.

Frequently Asked Questions

Does uninstalling a Vorssaint feature delete my settings permanently?

No. The standard uninstall action toggles only the installed flag while preserving all preference keys. Your settings remain in UserDefaults and automatically restore when you re-install the feature.

Why do I need to restart Vorssaint after uninstalling features?

The runtime keeps uninstalled features in memory for the current session to ensure stability. The FeatureRuntime only respects the updated installed flag at the next launch cycle. The UI displays FeatureHubStrings.restartNote to explain this temporary state.

Can I backup settings from a feature I've already uninstalled?

Yes. Direct Defaults access using the feature's preference keys (e.g., vorssaint.feature.<id>.settingName) works regardless of installation status. The values were never cleared—just not loaded into the active runtime.

How is this different from the uninstall.sh script?

The in-app uninstall is a soft disable: reversible, settings-preserving, and runtime-controlled. The Tools/uninstall.sh script performs hard deletion: it removes the application bundle and executes defaults delete to purge all persisted state including feature flags.

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