How to Set Up a Local Development Environment for Vorssaint-Utils: Complete Guide

Setting up a local development environment for vorssaint-utils requires macOS 14 Sonoma on Apple Silicon, Xcode Command-Line Tools, and a single build script—no external package managers needed.

Vorssaint-utils is a self-contained macOS Swift utility suite that compiles with swiftc and ships with its own build orchestration. This guide walks through the exact steps derived from the repository's README.md and CONTRIBUTING.md, including optional code signing setup for persistent macOS permissions.

Prerequisites for Vorssaint-Utils Development

Before cloning the repository, verify your system meets these requirements:

• macOS 14 Sonoma or newer – The source code in Sources/Vorssaint/ uses APIs introduced in macOS 14
• Apple Silicon (M1/M2/M3) – The build scripts assume ARM64 architecture
• Xcode Command-Line Tools – Provides swiftc, codesign, and other build utilities

Install the command-line tools if missing:

xcode-select --install

No additional package managers (Homebrew, Mint, etc.) are required. The Package.swift file exists only for IDE support and is not used during compilation.

Clone and Build Vorssaint-Utils

Start by pulling the source and entering the project directory:

git clone https://github.com/vorssaint/vorssaint-utils.git
cd vorssaint-utils

The repository follows a flat structure with source files under Sources/Vorssaint/ and helper scripts in Tools/.

Optional: Configure Stable Code Signing

To prevent macOS from revoking Accessibility and Screen Recording permissions after every rebuild, create a persistent self-signed identity:

./Tools/setup-signing.sh

This script generates a certificate named "Vorssaint Utils Signing" in your login keychain. According to the CONTRIBUTING.md guidelines, stable signing is strongly recommended for contributors who will iterate frequently.

Build the Application

Run the core build script:

./build.sh

The build.sh script in the repository root performs several operations:

1. Compiles Swift sources using swiftc directly (no SwiftPM build)
2. Creates the app bundle structure
3. Codesigns the binary with the configured identity
4. Outputs to ./build/Vorssaint.app

Verify the compiled binary works correctly:

./build/Vorssaint --selftest

Expect output: SELFTEST OK. This self-test is mandatory for CI compliance—pull requests must pass this check.

Install and Run Locally

To test the full UI experience, install the app to /Applications:

./build.sh --install

This copies the signed bundle and launches it immediately. Alternatively, run without installing:

open ./build/Vorssaint.app

Managing macOS Permissions

After initial builds, macOS may cache stale permission grants. Reset them to force fresh prompts:

tccutil reset Accessibility com.vorssaint.utils.dev
tccutil reset ScreenRecording com.vorssaint.utils.dev

The bundle identifier com.vorssaint.utils.dev is used for development builds. Production releases use com.vorssaint.utils.

Project Structure Key Files

Understanding these files accelerates contribution:

• build.sh – Core build orchestration; handles compilation, signing, and installation
• Tools/setup-signing.sh – Creates the persistent signing identity for stable permissions
• Tools/uninstall.sh – Complete cleanup: removes app, login item, and all privacy grants
• Sources/Vorssaint/main.swift – Application entry point; initializes the menu-bar status item
• Sources/Vorssaint/Core/Localization.swift – Central string catalog for multilingual support
• Sources/Vorssaint/UI/ – SwiftUI views; pure presentation layer with no business logic

Development Workflow Summary

# Complete setup from scratch

git clone https://github.com/vorssaint/vorssaint-utils.git
cd vorssaint-utils
./Tools/setup-signing.sh    # Optional but recommended

./build.sh
./build/Vorssaint --selftest
./build.sh --install        # Optional

Open any source file in Xcode, VS Code, or another Swift-aware editor to begin modifying features. The project intentionally avoids external dependencies to maintain build simplicity.

Summary

• No package manager required – Swift sources compile directly with swiftc via build.sh
• macOS 14 + Apple Silicon mandatory – Hard requirements from the codebase
• Stable signing prevents permission fatigue – Use Tools/setup-signing.sh for iterative development
• Self-test is mandatory – ./build/Vorssaint --selftest must pass for CI acceptance
• Clean uninstall available – Tools/uninstall.sh resets all state for fresh testing

Frequently Asked Questions

Do I need Xcode installed to build vorssaint-utils?

No. Only the Xcode Command-Line Tools are required, which provide swiftc and codesign. Run xcode-select --install to obtain them. The full Xcode IDE is optional—any Swift-aware editor works for development.

Why does the build script use swiftc instead of swift build?

The vorssaint-utils project is deliberately self-contained. The Package.swift file exists solely for IDE indexing and autocomplete support. The actual build in build.sh invokes swiftc directly, avoiding SwiftPM dependency resolution entirely.

What happens if I skip the signing setup script?

The build will still succeed using ad-hoc signing, but macOS will treat each rebuild as a different application. This causes previously granted Accessibility and Screen Recording permissions to become invalid, requiring manual re-approval in System Settings after every compile.

How do I completely reset my development environment?

Run ./Tools/uninstall.sh to remove the app from /Applications, delete the login item, and clear all stored privacy grants. For permission resets without full uninstall, use tccutil reset with the development bundle identifier com.vorssaint.utils.dev.

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