Development

This guide covers everything you need to contribute to WolfWave.

Prerequisites

• macOS 15.0+
• Xcode 16.0+
• Swift 5.9+
• Command Line Tools: xcode-select --install

Setup

1. Fork and clone the repository
2. Copy src/wolfwave/Config.xcconfig.example to src/wolfwave/Config.xcconfig
3. Set your Twitch Client ID and Discord Client ID in Config.xcconfig
4. Open the project: make open-xcode
5. Resolve dependencies: make update-deps

Development Commands

Code Quality

This project follows Swift best practices with professional-grade documentation:

• Swift 5.9+ with modern concurrency (async/await)
• SwiftUI for user interfaces
• Comprehensive Documentation: DocC-style comments throughout with usage examples
• MARK Sections: All files organized with clear section markers for easy navigation
• Separation of Concerns: Clean architecture across Core/Services/Views/Monitors
• Secure Credential Storage: macOS Keychain for all sensitive data
• ScriptingBridge Integration: Direct Apple Music communication without spawning subprocesses
• Robust Error Handling: Typed errors with localized descriptions
• Type Safety: Strongly typed models for all data structures
• Zero Dependencies: All functionality uses native Apple frameworks

Twitch Chat Service

The bot is implemented with TwitchChatService using Twitch Helix + EventSub (no IRC).

Features

• EventSub WebSocket: Real-time chat message notifications
• OAuth Device Code Flow: Secure authentication via TwitchDeviceAuth
• Token Validation: Automatic token validation on app launch
• Command System: Extensible bot command architecture

Usage

• Connect with saved credentials: joinChannel(broadcasterID:botID:token:clientID:) or connectToChannel(channelName:token:clientID:)
• Send chat messages via Helix: sendMessage(_:) or sendMessage(_:replyTo:)
• Supply current track info for commands: set getCurrentSongInfo on the service
• Commands can be toggled in Settings ("Bot Commands" → "Current Song")
• The service respects commandsEnabled so you can disable all commands from Settings

Documentation

• Comprehensive MARK sections organize the 700+ line service file
• DocC-style comments document all public methods
• Typed errors with localized descriptions (ConnectionError)
• Models for chat messages, badges, and replies

Discord Rich Presence Service

DiscordRPCService communicates with Discord via the local IPC Unix domain socket.

Features

• IPC Socket Client: Connects to Discord's local Unix domain socket (discord-ipc-{0..9})
• Dynamic Artwork: Fetches album art from the iTunes Search API with caching
• Auto-reconnect: Automatic reconnection with backoff when Discord restarts
• Sandbox Compatible: Works within the macOS App Sandbox via SBPL entitlements

Usage

• Start the service: connect() — discovers and connects to Discord's IPC socket
• Update presence: updatePresence(track:artist:album:duration:elapsed:) — sets the listening activity
• Clear presence: clearPresence() — removes the activity from the user's profile
• The service is wired into the music playback delegate in WolfWaveApp.swift

CI/CD

The project includes a GitHub Actions workflow (.github/workflows/release.yml) that automates the release process.

Required GitHub Secrets

Triggering a Release

git tag v1.0.0
git push origin v1.0.0

This will build, sign, notarize, and create a GitHub Release with the DMG attached.