How to Use vorssaint‑utils: 5 Practical Code Examples and Full Architecture Guide

vorssaint‑utils is a Swift macOS utility collection that exposes each feature as an observable service you can programmatically control from your own code.

The repository bundles independent tools—window snapping, text snippets, system monitoring, keep‑awake timers, and more—behind a single menu‑bar application. Every utility lives in Sources/Vorssaint and implements the observable service pattern, making them easy to script, extend, or embed in custom workflows. This guide demonstrates practical vorssaint‑utils examples drawn directly from the source code.

---

Getting Started: Importing the Module

Add the package to your Xcode project, then import the Vorssaint module defined in Package.swift:

import Vorssaint

All subsequent examples assume this import is present.

---

Example 1: Launch the App Programmatically

The VorssaintMain.run method provides a thin wrapper around the boot‑strap logic in Sources/Vorssaint/main.swift. You can launch the full application—or run diagnostics—without touching the command line:

VorssaintMain.run(arguments: ["--selftest"])   // Execute built‑in self‑test
VorssaintMain.run(arguments: [])               // Normal UI launch

The same flags available to the binary (--selftest, --sensors, --uninstall) are accepted here. See main.swift for the underlying parsing logic.

---

Example 2: Trigger Text Snippet Expansion

The TextSnippetService manages low‑level event taps that listen for trigger strings and expand them into templates. You can programmatically register snippets:

let snippet = TextSnippet(
    trigger: "date",
    expansion: .immediate,
    template: "{{date}}",
    enabled: true
)
TextSnippetService.shared.set(snippet: snippet)
TextSnippetService.shared.syncWithPreferences()

Key implementation details from Sources/Vorssaint/Services/Snippets/TextSnippetService.swift:

• Snippets persist to UserDefaults
• The service maintains an event tap for global keyboard monitoring
• Call syncWithPreferences() to force‑reload the active trigger set

---

Example 3: Snap Windows Programmatically

WindowLayoutService exposes move(_:to:animation:) for calculated window positioning. Snapping the frontmost window left takes two lines:

guard let frontmost = NSApplication.shared.orderedWindows.first else { return }

WindowLayoutService.shared.move(
    window: frontmost,
    to: .leftHalf,
    animation: .smooth
)

The method internally delegates to WindowEdgeSnapSupport for frame calculations. Source: Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift.

---

Example 4: Add Files to the Shelf

The Shelf is a quick‑drop panel for frequently accessed files. Use ShelfService to add links programmatically:

let fileURL = URL(fileURLWithPath: "/Users/me/Documents/report.pdf")
ShelfService.shared.addLink(title: "Report", url: fileURL)

Sources/Vorssaint/Services/Shelf/ShelfService.swift handles persistence, drag‑and‑drop UI updates, and link resolution when items are activated.

---

Example 5: Run a Keep‑Awake Timer

Prevent macOS sleep for a fixed duration—useful for long downloads or presentations:

KeepAwakeService.shared.startTimer(minutes: 15)
// ...work continues even if lid is closed...

KeepAwakeService.shared.stop()   // Cancel early when done

The implementation in Sources/Vorssaint/Services/KeepAwake wraps IOPMAssertionCreateWithName to create a proper power management assertion.

---

Architecture: How Services Tie Together

vorssaint‑utils follows a consistent pattern across all utilities:

Layer	Responsibility	Key File
Entry point	CLI parsing, defaults registration, app launch	Sources/Vorssaint/main.swift
Lifecycle	Service instantiation, UI wiring, cleanup	Sources/Vorssaint/App/AppDelegate.swift
Features	Observable services that react to permissions and preferences	Services/*/*.swift
UI	SwiftUI panels mixed with NSView subclasses for custom drawing	Instantiated in AppDelegate

Each service conforms to ObservableObject, so SwiftUI views automatically refresh when state changes. The Features settings page lets users install or uninstall entire utilities—this simply toggles the corresponding service on or off.

---

Key Source Files Reference

• Application boot: Sources/Vorssaint/main.swift
• UI and service wiring: Sources/Vorssaint/App/AppDelegate.swift
• Text snippets: Sources/Vorssaint/Services/Snippets/TextSnippetService.swift
• Window management: Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift
• Quick‑drop shelf: Sources/Vorssaint/Services/Shelf/ShelfService.swift
• System metrics: Sources/Vorssaint/Services/SystemMonitor/SystemMonitor.swift
• Update engine: Sources/Vorssaint/Services/Update/UpdateService.swift
• Complete removal: Sources/Vorssaint/Services/Uninstall/AppUninstaller.swift

---

Summary

• Import once: import Vorssaint exposes all service APIs.
• Script anything: Launch flags, snippets, window moves, shelf items, and power assertions all have programmatic interfaces.
• Observable pattern: Services publish state changes; UI updates automatically.
• Modular by design: Uninstall a feature and its service stops cleanly.

These vorssaint‑utils examples demonstrate how the codebase prioritizes automation and extensibility over a locked‑down GUI.

---

Frequently Asked Questions

Can I use vorssaint‑utils without the full menu‑bar app?

Yes. Import the Vorssaint module and invoke individual services directly. The VorssaintMain.run method exists for complete launches, but TextSnippetService.shared, WindowLayoutService.shared, and others function independently once imported.

Where are user settings stored?

Services persist configuration to UserDefaults under domain‑specific keys. TextSnippetService, for example, serializes snippets to standard preferences, which syncWithPreferences() re‑reads at runtime.

How do I add a new utility to vorssaint‑utils?

Create a new ObservableObject service in Sources/Vorssaint/Services/, wire it to AppDelegate.swift for lifecycle management, and expose install/uninstall toggles through the Features UI. Follow the existing pattern in ShelfService or KeepAwakeService for consistency.

Is there a public API for the system monitor?

The SystemMonitor class publishes CPU, GPU, memory, and temperature data. Instantiate it or access a shared instance if exposed, then subscribe to its ObservableObject output for real‑time metrics in custom SwiftUI views.

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