Development

TL;DR: clone the repo, copy Config.xcconfig, run make build and make test, then open a PR. This page is for contributors. Just want to use the app? See Installation.

The pathCopy Anchor Link

1. Check the prerequisites.
2. Clone the repo.
3. Add your API keys in Config.xcconfig.
4. Build and run the Debug app.
5. Run the tests and the lint gates.
6. Open a pull request.

PrerequisitesCopy Anchor Link

• macOS 26.0+ (Tahoe) on Apple Silicon (M1 or later).
• Xcode 26+, with Command Line Tools (xcode-select --install).
• Docker Desktop, only for make lint and make lint-crash-safety (they run a pinned SwiftLint image).
• bun 1.3.11, only if you touch the docs site, OBS widget, Stream Deck plugin, or design tokens.
  • Use exactly the version in the root package.json packageManager field.
  • Other bun releases minify the widget differently, so CI's drift check fails.

Only editing Swift? You don't need bun. Xcode ships the committed widget.html as-is.

Clone the repoCopy Anchor Link

git clone https://github.com/MrDemonWolf/wolfwave.git
cd wolfwave

Touching web code too? Install the workspaces with the pinned bun:

bunx bun@1.3.11 install --frozen-lockfile

--frozen-lockfile keeps bun.lock unchanged. Don't commit lockfile churn.

Configure API keysCopy Anchor Link

Copy the example config:

cp apps/native/WolfWave/Config.xcconfig.example apps/native/WolfWave/Config.xcconfig

Then fill in the two required keys:

TWITCH_CLIENT_ID = your_twitch_client_id_here
DISCORD_CLIENT_ID = your_discord_application_id_here

• Twitch Client ID: create an app at dev.twitch.tv/console/apps.
• Discord Application ID: create an app at discord.com/developers/applications.
• Discord art assets: upload apple_music and pause to your Discord app. See Rich Presence art assets.

Optional keysCopy Anchor Link

Where these values come from, in priority order:

1. Your Config.xcconfig. Local builds only.
2. CI. Release and test workflows write the keys into a generated Config.xcconfig.
3. Core/AppConstants. The fallback when a key is blank.

To rename the app itself, set PRODUCT_NAME and INFOPLIST_KEY_CFBundleDisplayName in the build configuration. Keep the Debug and Release names different.

Build and runCopy Anchor Link

make open-xcode

Press ⌘R in Xcode. Or build from the terminal with make build.

• Debug builds are a separate app: WolfWave Dev (com.mrdemonwolf.wolfwave.dev), with a DEV badge on its icon.
• It lives beside a real WolfWave install without touching its settings or Keychain.
• make clean-dev resets WolfWave Dev to a fresh first run. It never touches the production app.

Make targetsCopy Anchor Link

make build, every make test* target, and make prod-build run sponsor-config first, so you rarely call it yourself.

TestingCopy Anchor Link

Run make test (or ⌘U in Xcode). It prints the file and pass count.

• Unit tests live in apps/native/WolfWaveTests/.
• New test file? Drop a .swift file in that folder and @testable import WolfWave. No Xcode project edit needed.
• Your real data is safe. Tests use a throwaway settings suite and an in-memory Keychain. Never use UserDefaults.standard in a test.
• Isolated output. make test* builds into the gitignored DerivedData/Tests, so the unsigned test host never replaces your signed Debug app.

The rules for shared test state (the SharedTestStateIsolation lock, WolfWaveTestCase) are in the repo's CLAUDE.md.

UI testsCopy Anchor Link

make test-ui runs WolfWaveUITests. It launches the real app and drives it:

• the onboarding wizard, end to end;
• every settings pane, with a screenshot of each attached to the result.

The app runs with WOLFWAVE_UI_TEST=1, which swaps in throwaway settings and Keychain storage and keeps Apple Music, Twitch, Discord, and Sparkle off. UI tests run as their own CI job and never gate a release. Details: apps/native/docs/end-to-end-testing.md.

Web workspace testsCopy Anchor Link

bun run --filter widget test       # OBS widget (bun test + happy-dom)
bun run --filter streamdeck test   # Stream Deck plugin
bun run ds:test                    # design-system lint rules

Lint gatesCopy Anchor Link

Run these before you push. CI runs the same ones.

make lint                # SwiftLint against the tracked baseline
make lint-crash-safety   # Blocking: no new force unwrap, try!, or as!
make lint-headers        # Blocking: Swift file headers match the Xcode template
make lint-sync           # Blocking: source, catalog, and docs stay in sync
bun run ds:lint          # Blocking: no literal font sizes, spacing, padding, or radius in views
bun run ds:schema        # Validate tokens.json against its schema

Generated filesCopy Anchor Link

Some committed files are generated. Never edit them by hand.

Commit the regenerated output with your source change. make check-drift runs CI's drift check locally. The widget pipeline is covered on the OBS Widget page.

Open a pull requestCopy Anchor Link

1. Branch off main. One concern per PR.
2. Run make test and the lint gates.
3. Fill in the PR template checklists.
4. User-facing change? Add a one-line bullet to CHANGELOG.md under the top ## [x.y.z] heading, and to the top block of changelog.mdx.
5. Contributor-only change? Put it under ### Developer in CHANGELOG.md. It skips the in-app notes and the docs changelog.
6. Update the docs your change touches (features, settings, bot-commands, architecture).
7. Attach a screenshot or recording for any UI change.

Don't bump CURRENT_PROJECT_VERSION. CI sets the build number from scripts/version.sh.

More detail: CONTRIBUTING.md and CLAUDE.md.

Rich Presence art assets (fork maintainers)Copy Anchor Link

Rich Presence shows two images registered on the Discord app. They are not bundled with WolfWave.

Shipping a fork with your own DISCORD_CLIENT_ID?

1. Open your Discord app's Rich Presence → Art Assets page.
2. Upload both PNGs from discord-assets/ with those exact lowercase names.
3. Wait about 10 minutes for Discord's CDN.

Production buildCopy Anchor Link

make prod-build

• The DMG lands at builds/WolfWave-{version}.dmg.
• With a Developer ID Application certificate in your Keychain, the app is re-signed for distribution (inside-out, via scripts/codesign-app.sh, the same script CI uses).
• make prod-install builds and copies the app to /Applications.
• The DMG background comes from scripts/generate-dmg-background.swift. Regenerate with swift scripts/generate-dmg-background.swift assets and commit the PNGs.

NotarizationCopy Anchor Link

APPLE_ID=you@example.com \
APPLE_TEAM_ID=YOUR_TEAM_ID \
APPLE_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx \
make notarize

• make notarize signs, submits, and staples the DMG.
• It then runs stapler validate and spctl --assess, so a bad ticket fails here, not on a user's Mac.
• make verify-notarize reruns those two checks on an existing DMG.

CI/CDCopy Anchor Link

Required GitHub secretsCopy Anchor Link

Cutting a releaseCopy Anchor Link

Push a tag that matches MARKETING_VERSION:

git tag vX.Y.Z
git push origin vX.Y.Z

1. The workflow uploads to a draft release. Rerunning updates the draft; it never replaces a published release.
2. Review the draft and publish it.
3. The Homebrew cask and the docs site update on their own.

The full list is the Release Checklist.

Next stepsCopy Anchor Link