How the Feature Hub in Vorssaint-Utils Installs and Uninstalls Modular Features

The feature hub in vorssaint-utils acts as a lightweight controller that toggles Boolean availability flags in UserDefaults, while the FeatureRuntime singleton handles the actual instantiation and teardown of feature services through registered bindings.

The vorssaint-utils toolkit provides a modular macOS utility architecture where individual features can be dynamically enabled or disabled at runtime. Understanding how the feature hub coordinates these installations is essential for developers extending the framework or debugging feature availability issues.

Architecture Overview

The feature hub UI is intentionally decoupled from feature implementations. According to the vorssaint-utils source code, the hub resides in Sources/Vorssaint/UI/Settings/FeatureHubSettings.swift and displays rows for each AppFeature defined in Sources/Vorssaint/Core/FeatureCatalog.swift. The actual lifecycle management occurs in Sources/Vorssaint/App/FeatureRuntime.swift, which maintains a static bindings dictionary containing the start and stop closures for every feature.

The Installation and Uninstallation Flow

When a user clicks Install or Uninstall in the feature hub, the system executes a coordinated six-step process across the UI and runtime layers.

UI Interaction and Method Invocation

Pressing a button in the hub triggers FeatureHubRow.flip(to:), which immediately delegates to FeatureRuntime.shared.setAvailable(_:,_). This method accepts an AppFeature enum case and a Boolean value indicating the desired availability state.

Hardware Validation and Availability Gating

Before persisting any changes, FeatureRuntime validates the request through its internal mayFlip logic. Installation is permitted only when feature.isHardwareSupported returns true for the current Mac hardware. Uninstallation operations bypass this validation and are always allowed.

Persisting State to UserDefaults

Once validated, the new availability state is written to UserDefaults using the key specified by feature.availabilityKey in FeatureCatalog.swift. This persistence mechanism ensures feature states survive application restarts.

Executing Feature Bindings

FeatureRuntime looks up the corresponding closure in its static bindings dictionary and executes it synchronously. These closures encapsulate the heavy lifting: creating service singletons, attaching observers, or cleaning up resources when tearing down a feature.

Notifying Observers of State Changes

After processing all state changes, FeatureRuntime increments its revision property and broadcasts updates to the command-bar. Any UI components observing the runtime refresh automatically to reflect the new availability state.

Bulk Operations for Installing and Uninstalling All Features

The hub provides Install All and Uninstall All buttons that invoke FeatureRuntime.setAllAvailable(_:). This method iterates over every registered AppFeature, applies the same hardware-support validation, persists flags to UserDefaults, executes bindings for each feature, and finally bumps the revision once for the entire batch operation.

Handling Restart Requirements After Uninstallation

Certain features create persistent UI elements such as panels or global shortcuts that remain active in the current session even after their services are stopped. When FeatureRuntime detects that a currently loaded feature has been uninstalled, it sets needsRestartToUnload to true, prompting the hub to display a restart banner informing users that a full application restart is required to complete the uninstallation.

Programmatic Control of Feature Installation

Developers can bypass the UI and control feature states directly through the FeatureRuntime singleton:

// Install a single feature from code (e.g. from a preset)
FeatureRuntime.shared.setAvailable(.keepAwake, true)

// Uninstall a single feature
FeatureRuntime.shared.setAvailable(.keepAwake, false)

// Install every supported feature at once
FeatureRuntime.shared.setAllAvailable(true)

// Uninstall every feature (useful for a “reset” action)
FeatureRuntime.shared.setAllAvailable(false)

Summary

• The feature hub in FeatureHubSettings.swift serves as a thin controller that delegates all logic to FeatureRuntime, keeping the UI completely decoupled from implementations.
• FeatureRuntime.setAvailable(_:,_) gates installation through hardware checks (isHardwareSupported) and persists state to UserDefaults via availabilityKey.
• Feature lifecycle management occurs through the bindings dictionary, which executes start/stop closures immediately upon state changes.
• Bulk operations use setAllAvailable(_:) to efficiently process multiple features with a single revision bump.
• Uninstalling active features may set needsRestartToUnload, requiring an app restart to fully release UI resources.

Frequently Asked Questions

What happens if I try to install a feature on unsupported hardware?

The FeatureRuntime checks feature.isHardwareSupported before allowing installation. If the current Mac does not meet the hardware requirements, the setAvailable call returns early without persisting the flag or executing the binding.

Where is feature availability stored between app launches?

Availability states are persisted in UserDefaults using keys defined by feature.availabilityKey in FeatureCatalog.swift. This allows FeatureRuntime to restore the previous configuration automatically on startup.

Can I install or uninstall features programmatically without using the UI?

Yes. The FeatureRuntime singleton exposes setAvailable(_:,_) for individual features and setAllAvailable(_:) for bulk operations, allowing programmatic control from setup wizards, command-line tools, or configuration presets.

Why does the hub sometimes show a restart banner after uninstalling?

Certain features create persistent UI elements like panels or shortcuts that cannot be fully released until the application restarts. When FeatureRuntime.needsRestartToUnload becomes true, the hub displays a banner indicating that a restart is required to complete the uninstallation process.

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