Development Setup

Everything you need to build and contribute to SeeleSeek locally.

Prerequisites

macOS 15+

SeeleSeek targets macOS 15 (Sequoia) or later. Both building and running the app require this version.

Xcode 15+ (Swift 6.x)

The project uses Swift 6 concurrency features (@Observable, @MainActor, actors). Xcode 15 or newer is required.

Getting the Code

1. Clone the repository

   git clone https://github.com/bretth18/seeleseek.git
   cd seeleseek
   
2. Open the project

   Open seeleseek.xcodeproj in Xcode:

   open seeleseek.xcodeproj
   

   Xcode will resolve the Swift Package Manager dependency (GRDB.swift) automatically on first open.

3. Build and run

   Select the seeleseek scheme and your Mac as the destination, then press ⌘R to build and run.

   You can also build from the command line without code signing:

   xcodebuild \
     -scheme seeleseek \
     -destination 'platform=macOS' \
     -configuration Release \
     build \
     CODE_SIGN_IDENTITY="" \
     CODE_SIGNING_REQUIRED=NO
   

Dependencies

SeeleSeek has a single external dependency managed via Swift Package Manager:

Package	Purpose
GRDB.swift	SQLite persistence — download queue, search cache, browse cache, message history, wishlists

Xcode fetches and caches this package automatically. No manual installation is needed.

Running Tests

The test suite lives in seeleseekTests/. Run it from Xcode with ⌘U, or from the command line:

xcodebuild \
  -scheme seeleseek \
  -destination 'platform=macOS' \
  test \
  CODE_SIGN_IDENTITY="" \
  CODE_SIGNING_REQUIRED=NO

Tests run without code signing, which matches the CI environment. If a test requires network access it will be skipped in sandboxed or offline environments.

CI/CD

GitHub Actions workflows are defined in .github/workflows/:

build.yml — Build and test on every push/PR

Triggered on pushes and pull requests targeting main. Runs two parallel jobs on macos-26:

• Build — compiles the Release configuration with xcodebuild.
• Test — runs the full unit test suite with xcodebuild test.

No code signing secrets are required for these jobs.

release.yml — Signed release on version tags

Triggered when a tag matching v* is pushed. The workflow:

1. Installs Developer ID Application and Installer certificates from repository secrets.
2. Archives and exports the app with xcodebuild -exportArchive.
3. Builds and signs a .pkg installer with pkgbuild + productsign.
4. Notarizes the package with xcrun notarytool and staples the ticket.
5. Publishes the release on GitHub with auto-generated release notes.

The release workflow requires several repository secrets (DEVELOPER_ID_APPLICATION_P12, DEVELOPER_ID_INSTALLER_P12, P12_PASSWORD, APPLE_ID, APPLE_ID_PASSWORD). These are only available to maintainers with repository access.

nightly.yml — Branch build artifact

Triggered on pushes to any branch except main. Archives the app with ad-hoc signing, renames it to SeeleSeek Nightly, and uploads a .zip artifact retained for 5 days. This lets you test unreleased changes without affecting the stable release channel.

Contributing

Contributions are welcome.

1. Open an issue first for large changes

   Before investing time in a large feature or refactor, open an issue to discuss the approach. This avoids duplicated effort and ensures the change fits the project direction.

2. Fork and create a branch

   git checkout -b feature/my-feature
   
3. Make your changes

   Follow the existing code style — Swift 6 strict concurrency, @Observable state classes, @MainActor for UI updates. See the Architecture page for structural conventions.

4. Submit a pull request

   Push your branch and open a PR against main. The build and test CI jobs will run automatically. A pull request template is provided at .github/pull_request_template.md.

Reporting Bugs

Open a GitHub issue and include:

• macOS version and SeeleSeek version
• Steps to reproduce
• Expected vs actual behavior
• Console logs if relevant (open Console.app and filter by com.seeleseek)