abanoub-ashraf/steipete-thomas

Swift macOS Production App (steipete-thomas)

Build production-grade macOS applications using Swift Package Manager (no Xcode project needed). This comprehensive skill covers modern Swift 6 architecture patterns, menu bar apps, plugin systems, build scripts, code signing, notarization, Sparkle auto-updates, and distribution.

When to Use This Skill

Use this skill when:

• Creating new macOS apps without Xcode project files
• Building menu bar (status item) apps
• Setting up multi-target Swift Package projects
• Implementing plugin/provider architectures
• Working with Swift 6 strict concurrency
• Creating @Observable state management with persistence
• Building WidgetKit extensions
• Adding Sparkle auto-updates to macOS apps
• Code signing and notarizing for direct distribution
• Setting up CI/CD for macOS app distribution
• Building API clients with proper caching
• Implementing search with debouncing
• Storing secrets in Keychain
• Writing production shell scripts for builds/releases
• Setting up testing infrastructure

Agent Behavior Contract

1. Analyze first: Check Package.swift for Swift version, platforms, and existing patterns before suggesting changes.
2. Prefer modular architecture: Split code into Core (platform-agnostic) and App (UI) targets.
3. Enforce strict concurrency: Always use @MainActor for UI classes and Sendable for data models.
4. Use @Observable over ObservableObject: Prefer the modern Observation framework (macOS 14+).
5. Script automation: Recommend shell scripts for repeatable build/release workflows.
6. Single source of truth: Version numbers in version.env, metadata in descriptors.
7. Debounce persistence: Never persist on every keystroke - debounce writes.
8. Lazy loading: Load expensive resources (Keychain, network) only when needed.
9. SwiftPM-only: No Xcode project files - everything in Package.swift.

Quick Decision Tree

1. Starting a new macOS app?

   • Read references/project-structure.md for recommended layout
   • Read references/package-swift.md for multi-target setup

2. Building a menu bar app?

   • Read references/menu-bar-app.md for StatusItem patterns
   • Read references/app-lifecycle.md for AppDelegate setup

3. Managing app state?

   • Read references/observable-state.md for @Observable patterns
   • Read references/settings-store.md for UserDefaults + Keychain

4. Need plugin/provider architecture?

   • Read references/plugin-architecture.md for Descriptor + Registry + Strategy patterns

5. Writing concurrent code?

   • Read references/swift-concurrency.md for Swift 6 patterns and background refresh loops

6. Building widgets?

   • Read references/widget-extension.md for WidgetKit patterns

7. Storing secrets?

   • Read references/keychain-storage.md for secure storage patterns

8. Setting up builds/releases?

   • Read references/build-scripts.md for shell script templates
   • Read references/code-quality.md for SwiftLint/SwiftFormat

9. Adding auto-updates?

   • Read references/sparkle-updates.md for Sparkle integration

10. Distributing your app?

    • Read references/distribution.md for code signing and notarization

---

Project Structure Template

MyApp/
├── Package.swift                 # SwiftPM manifest (Swift 6.0+)
├── version.env                   # MARKETING_VERSION and BUILD_NUMBER
├── package.json                  # npm scripts (start, test, release)
├── appcast.xml                   # Sparkle update feed
├── Icon.icns                     # App icon
├── Entitlements.plist            # App entitlements
├── CHANGELOG.md
├── Sources/
│   ├── MyAppCore/               # Platform-agnostic (Sendable models, services)
│   │   ├── Models/
│   │   ├── Services/
│   │   ├── Providers/
│   │   ├── Storage/
│   │   └── Utilities/
│   ├── MyApp/                   # macOS app (SwiftUI, AppKit, @Observable stores)
│   │   ├── App/
│   │   │   ├── MyAppApp.swift   # @main entry point with AppDelegate
│   │   │   └── AppDelegate.swift
│   │   ├── Stores/
│   │   │   ├── UsageStore.swift
│   │   │   └── SettingsStore.swift
│   │   ├── Views/
│   │   │   ├── MenuContentView.swift
│   │   │   ├── SettingsView.swift
│   │   │   └── Components/
│   │   └── Workers/             # Actor-based async workers
│   │       ├── FileWorker.swift
│   │       └── CLIWorker.swift
│   ├── MyAppCLI/                # Optional CLI tool
│   │   └── CLI.swift
│   └── MyAppWidget/             # WidgetKit extension
│       └── Widget.swift
├── Tests/
│   └── MyAppTests/
│       ├── CoreTests/
│       ├── StoreTests/
│       ├── Mocks/
│       └── Fixtures/
└── Scripts/
    ├── compile_and_run.sh       # Dev iteration script
    ├── package_app.sh           # Create .app bundle
    ├── sign-and-notarize.sh     # Release workflow
    ├── make_appcast.sh          # Sparkle feed generation
    └── bump-version.sh          # Version management

---

Package.swift Template

// swift-tools-version: 6.0
import PackageDescription

let package = Package(
    name: "MyApp",
    platforms: [.macOS(.v14)],
    products: [
        .executable(name: "MyApp", targets: ["MyApp"]),
        .executable(name: "myapp", targets: ["MyAppCLI"]),
    ],
    dependencies: [
        .package(url: "https://github.com/apple/swift-log", from: "1.5.0"),
        .package(url: "https://github.com/apple/swift-argument-parser", from: "1.3.0"),
        .package(url: "https://github.com/gonzalezreal/swift-markdown-ui.git", from: "2.4.1"),
        .package(url: "https://github.com/sparkle-project/Sparkle", from: "2.8.1"),
    ],
    targets: [
        // Platform-agnostic core library
        .target(
            name: "MyAppCore",
            dependencies: [
                .product(name: "Logging", package: "swift-log"),
            ],
            swiftSettings: [
                .enableUpcomingFeature("StrictConcurrency"),
            ]
        ),

        // macOS GUI app
        .executableTarget(
            name: "MyApp",
            dependencies: [
                "MyAppCore",
                .product(name: "MarkdownUI", package: "swift-markdown-ui"),
                .product(name: "Sparkle", package: "Sparkle"),
            ],
            swiftSettings: [
                .define("ENABLE_SPARKLE"),
                .enableUpcomingFeature("StrictConcurrency"),
            ]
        ),

        // CLI tool
        .executableTarget(
            name: "MyAppCLI",
            dependencies: [
                "MyAppCore",
                .product(name: "ArgumentParser", package: "swift-argument-parser"),
            ],
            swiftSettings: [
                .enableUpcomingFeature("StrictConcurrency"),
            ]
        ),

        // Tests
        .testTarget(
            name: "MyAppTests",
            dependencies: ["MyApp", "MyAppCore", "MyAppCLI"],
            resources: [.copy("Fixtures")],
            swiftSettings: [
                .enableUpcomingFeature("StrictConcurrency"),
                .enableExperimentalFeature("SwiftTesting"),
            ]
        ),
    ]
)

---

Core Architecture Patterns

1. Observable State Management with State Enums

Use @Observable with @MainActor and enum-based state machines to prevent impossible states:

@MainActor
@Observable final class DocumentStore {
    // List state - prevents impossible states (no booleans!)
    enum ListState: Equatable {
        case idle
        case loading
        case loaded
        case failed(String)
    }

    // Detail state - includes cache-aware states
    enum DetailState: Equatable {
        case idle
        case loading
        case loaded
        case cachedRefreshing  // Showing cached while fetching fresh
        case missing
        case failed(String)
    }

    // State properties
    var documents: [Document] = []
    var listState: ListState = .idle
    var detailState: DetailState = .idle
    var selectedDocumentID: Document.ID?
    var selectedContent: String = ""

    // Internal bookkeeping - doesn't trigger SwiftUI updates
    @ObservationIgnored private var cache: [String: Data] = [:]
    @ObservationIgnored private var refreshTask: Task<Void, Never>?
    @ObservationIgnored private let fileWorker = FileWorker()

    // Observation token for fine-grained SwiftUI tracking
    var settingsObservationToken: Int {
        _ = documents
        _ = listState
        _ = selectedDocumentID
        return 0
    }

    func loadDocuments() async {
        listState = .loading
        do {
            documents = try await fileWorker.scanDocuments()
                .sorted { $0.title.localizedCaseInsensitiveCompare($1.title) == .orderedAscending }
            listState = .loaded
        } catch {
            listState = .failed(error.localizedDescription)
        }
    }

    deinit {
        refreshTask?.cancel()
    }
}

Why enums instead of booleans?

• isLoading + hasError = 4 possible states, but only 3 are valid
• Enum makes impossible states unrepresentable
• Compiler enforces exhaustive handling in switch statements

2. Actor-Based Workers for Thread-Safe I/O

import CryptoKit

actor FileWorker {
    // Nested types must be Sendable
    struct ScannedDocument: Sendable {
        let id: String
        let name: String
        let title: String
        let folderURL: URL
    }

    func scanDocuments(at baseURL: URL) throws -> [ScannedDocument] {
        let fileManager = FileManager.default
        guard fileManager.fileExists(atPath: baseURL.path) else { return [] }

        let contents = try fileManager.contentsOfDirectory(
            at: baseURL,
            includingPropertiesForKeys: [.isDirectoryKey],
            options: [.skipsHiddenFiles]
        )

        return contents.compactMap { url -> ScannedDocument? in
            let values = try? url.resourceValues(forKeys: [.isDirectoryKey])
            guard values?.isDirectory == true else { return nil }

            let name = url.lastPathComponent
            return ScannedDocument(
                id: name,
                name: name,
                title: formatTitle(name),
                folderURL: url
            )
        }
    }

    // Compute SHA256 hash of directory contents (for change detection)
    func computeHash(for rootURL: URL) throws -> String {
        let fileManager = FileManager.default
        var hasher = SHA256()

        guard let enumerator = fileManager.enumerator(
            at: rootURL,
            includingPropertiesForKeys: [.isRegularFileKey],
            options: [.skipsHiddenFiles]
        ) else { return "" }

        var files: [URL] = []
        for case let fileURL as URL in enumerator {
            let path = fileURL.path
            if path.contains("/.git/") { continue }
            let values = try? fileURL.resourceValues(forKeys: [.isRegularFileKey])
            guard values?.isRegularFile == true else { continue }
            files.append(fileURL)
        }

        files.sort { $0.path < $1.path }

        for fileURL in files {
            guard let data = try? Data(contentsOf: fileURL) else { continue }
            hasher.update(data: data)
        }

        let digest = hasher.finalize()
        return digest.map { String(format: "%02x", $0) }.joined()
    }
}

Why actors?

• Automatic thread safety without manual locks
• Compiler enforces isolation at call sites
• Perfect for I/O operations that shouldn't block the main thread

3. Closure-Based Dependency Injection (API Client)

struct APIClient: Sendable {
    var fetchLatest: @Sendable (_ limit: Int) async throws -> [RemoteDocument]
    var search: @Sendable (_ query: String, _ limit: Int) async throws -> [RemoteDocument]
    var download: @Sendable (_ id: String) async throws -> URL
}

extension APIClient {
    // Shared URLSession with caching
    private static let session: URLSession = {
        let urlCache = URLCache(
            memoryCapacity: 10 * 1024 * 1024,   // 10 MB memory
            diskCapacity: 50 * 1024 * 1024       // 50 MB disk
        )
        let config = URLSessionConfiguration.default
        config.urlCache = urlCache
        return URLSession(configuration: config)
    }()

    // Production implementation
    static func live(baseURL: URL = URL(string: "https://api.example.com")!) -> APIClient {
        let session = Self.session

        return APIClient(
            fetchLatest: { limit in
                var components = URLComponents(
                    url: baseURL.appendingPathComponent("/api/v1/documents"),
                    resolvingAgainstBaseURL: false
                )
                components?.queryItems = [
                    URLQueryItem(name: "limit", value: String(limit)),
                ]
                guard let url = components?.url else { throw URLError(.badURL) }

                let (data, response) = try await session.data(from: url)
                try validate(response: response)
                return try JSONDecoder().decode([RemoteDocument].self, from: data)
            },
            search: { query, limit in
                // Implementation...
                []
            },
            download: { id in
                // Implementation...
                URL(fileURLWithPath: "/tmp/download.zip")
            }
        )
    }

    // Mock for testing/previews
    static var mock: APIClient {
        APIClient(
            fetchLatest: { _ in [] },
            search: { _, _ in [] },
            download: { _ in URL(fileURLWithPath: "/tmp/mock.zip") }
        )
    }
}

Why closure-based DI instead of protocols?

• No ceremony (no protocol definition, no conformance)
• Easy to create mock implementations inline
• Static factory methods (.live(), .mock()) for common variants
• Works great with SwiftUI previews

4. NSCache for Application-Level Caching

/// Memory cache with automatic eviction under memory pressure
final class DetailCache: @unchecked Sendable {
    static let shared = DetailCache()

    private let cache = NSCache<NSString, CacheEntry>()

    private final class CacheEntry {
        let content: String
        let metadata: [String: Any]?
        init(content: String, metadata: [String: Any]? = nil) {
            self.content = content
            self.metadata = metadata
        }
    }

    private init() {
        cache.countLimit = 50  // Max 50 entries
    }

    func get(key: String) -> (content: String, metadata: [String: Any]?)? {
        guard let entry = cache.object(forKey: key as NSString) else { return nil }
        return (entry.content, entry.metadata)
    }

    func set(content: String, metadata: [String: Any]? = nil, forKey key: String) {
        cache.setObject(CacheEntry(content: content, metadata: metadata), forKey: key as NSString)
    }
}

5. Search Debouncing with Task Cancellation

struct SearchableView: View {
    @State private var searchText = ""
    @State private var searchTask: Task<Void, Never>?

    var body: some View {
        content
            .searchable(text: $searchText, prompt: "Search...")
            .onChange(of: searchText) { _, newValue in
                // Cancel previous search
                searchTask?.cancel()

                // Start new debounced search
                searchTask = Task {
                    try? await Task.sleep(for: .milliseconds(300))
                    guard !Task.isCancelled else { return }
                    await performSearch(query: newValue)
                }
            }
    }
}

6. Token-Based Search Cancellation for Race Conditions

@MainActor
@Observable final class RemoteStore {
    var searchResults: [RemoteDocument] = []
    var searchState: LoadState = .idle

    private let apiClient: APIClient
    private var activeSearchToken = 0

    func search(query: String, limit: Int = 20) async {
        let trimmed = query.trimmingCharacters(in: .whitespacesAndNewlines)
        activeSearchToken += 1
        let token = activeSearchToken

        guard !trimmed.isEmpty else {
            searchResults = []
            searchState = .idle
            return
        }

        searchState = .loading
        do {
            let results = try await apiClient.search(trimmed, limit)

            // Ignore results if query changed (prevents showing stale results)
            guard token == activeSearchToken else { return }

            searchResults = results
            searchState = .loaded
        } catch {
            guard token == activeSearchToken else { return }
            searchState = .failed(error.localizedDescription)
        }
    }
}

7. Plugin/Provider Architecture

// Descriptor: Single source of truth for a provider
struct ProviderDescriptor: Sendable {
    let id: ProviderID
    let metadata: ProviderMetadata
    let branding: ProviderBranding
    let fetchPlan: ProviderFetchPlan
}

// Registry: Auto-discovery with lazy bootstrap
enum ProviderRegistry {
    private static let store = Store()
    private static let bootstrap: Void = {
        register(GitHubProviderDescriptor.make())
        register(SlackProviderDescriptor.make())
    }()

    static var all: [ProviderDescriptor] {
        _ = bootstrap
        return store.ordered
    }
}

// Strategy: Fallback chain with availability checks
protocol FetchStrategy: Sendable {
    var id: String { get }
    func isAvailable(_ context: FetchContext) async -> Bool
    func fetch(_ context: FetchContext) async throws -> Result
    func shouldFallback(on error: Error) -> Bool
}

8. Settings Store with Debounced Keychain Persistence

@MainActor
@Observable
final class SettingsStore {
    // UserDefaults-backed with immediate persistence
    var refreshInterval: TimeInterval {
        didSet { userDefaults.set(refreshInterval, forKey: "refreshInterval") }
    }

    // Keychain-backed with debounced persistence
    var apiToken: String {
        didSet { scheduleTokenPersist() }
    }

    @ObservationIgnored private let userDefaults: UserDefaults
    @ObservationIgnored private let tokenStore: any TokenStoring
    @ObservationIgnored private var tokenPersistTask: Task<Void, Never>?
    @ObservationIgnored private var tokenLoaded = false

    // Lazy Keychain loading
    func ensureTokenLoaded() {
        guard !tokenLoaded else { return }
        apiToken = (try? tokenStore.load()) ?? ""
        tokenLoaded = true
    }

    // Debounced Keychain writes (350ms)
    private func scheduleTokenPersist() {
        guard tokenLoaded else { return }
        tokenPersistTask?.cancel()
        tokenPersistTask = Task { @MainActor in
            try? await Task.sleep(nanoseconds: 350_000_000)
            guard !Task.isCancelled else { return }
            try? tokenStore.store(apiToken)
        }
    }
}

---

Menu Bar App Pattern

@MainActor
final class AppDelegate: NSObject, NSApplicationDelegate {
    private var statusItem: NSStatusItem?
    private var usageStore: UsageStore?

    func applicationDidFinishLaunching(_ notification: Notification) {
        // Create status item
        statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)

        // Configure button
        if let button = statusItem?.button {
            button.image = NSImage(systemSymbolName: "chart.bar", accessibilityDescription: "Usage")
        }

        // Attach menu
        statusItem?.menu = buildMenu()

        // Start background refresh
        usageStore?.startBackgroundRefresh()
    }
}

// SwiftUI App with menu bar presence
@main
struct MyApp: App {
    @NSApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        Settings {
            SettingsView()
        }
    }
}

---

App Entry Point with Sparkle Auto-Updates

import SwiftUI

#if canImport(Sparkle) && ENABLE_SPARKLE
import Sparkle
import Security
#endif

@main
struct MyAppApp: App {
    @NSApplicationDelegateAdaptor(AppDelegate.self) private var appDelegate
    @State private var store = DocumentStore()

    var body: some Scene {
        WindowGroup("My App") {
            MainSplitView()
                .environment(store)
        }
        .commands {
            CommandGroup(after: .appInfo) {
                Button("Check for Updates...") {
                    appDelegate.checkForUpdates()
                }
                .keyboardShortcut("u", modifiers: [.command, .option])
            }
        }
    }
}

@MainActor
final class AppDelegate: NSObject, NSApplicationDelegate {
    #if canImport(Sparkle) && ENABLE_SPARKLE
    private var updaterController: SPUStandardUpdaterController?
    #endif

    func applicationDidFinishLaunching(_ notification: Notification) {
        NSApplication.shared.setActivationPolicy(.regular)
        NSApplication.shared.activate(ignoringOtherApps: true)

        #if canImport(Sparkle) && ENABLE_SPARKLE
        guard shouldEnableSparkle() else { return }
        updaterController = SPUStandardUpdaterController(
            startingUpdater: true,
            updaterDelegate: nil,
            userDriverDelegate: nil
        )
        #endif
    }

    func checkForUpdates() {
        #if canImport(Sparkle) && ENABLE_SPARKLE
        updaterController?.checkForUpdates(nil)
        #endif
    }

    #if canImport(Sparkle) && ENABLE_SPARKLE
    private func shouldEnableSparkle() -> Bool {
        let bundleURL = Bundle.main.bundleURL
        guard bundleURL.pathExtension == "app" else { return false }

        let info = Bundle.main.infoDictionary
        let feedURL = info?["SUFeedURL"] as? String
        let publicKey = info?["SUPublicEDKey"] as? String
        return (feedURL?.isEmpty == false) && (publicKey?.isEmpty == false)
    }
    #endif
}

---

Build Scripts

version.env

MARKETING_VERSION=1.0.0
BUILD_NUMBER=1

compile_and_run.sh (Development)

#!/usr/bin/env bash
set -euo pipefail

ROOT="$(cd "$(dirname "$0")/.." && pwd)"
APP_NAME=${APP_NAME:-MyApp}

# Lock to prevent concurrent builds
LOCK_KEY="$(printf '%s' "${ROOT}" | shasum -a 256 | cut -c1-8)"
LOCK_DIR="${TMPDIR}/myapp-build-${LOCK_KEY}"

acquire_lock() {
    while ! mkdir "${LOCK_DIR}" 2>/dev/null; do
        if [[ -f "${LOCK_DIR}/pid" ]]; then
            existing_pid="$(cat "${LOCK_DIR}/pid")"
            if kill -0 "${existing_pid}" 2>/dev/null; then
                echo "Another build running (pid ${existing_pid})"
                exit 0
            fi
        fi
        rm -rf "${LOCK_DIR}"
    done
    echo "$$" > "${LOCK_DIR}/pid"
}

trap 'rm -rf "${LOCK_DIR}"' EXIT
acquire_lock

# Kill existing → Build → Package → Launch → Verify
pkill -x "${APP_NAME}" || true
swift build -c debug
"${ROOT}/Scripts/package_app.sh" debug
open "${ROOT}/${APP_NAME}.app"
sleep 1 && pgrep -x "${APP_NAME}" || exit 1

sign-and-notarize.sh (Release)

#!/usr/bin/env bash
set -euo pipefail

ROOT="$(cd "$(dirname "$0")/.." && pwd)"
source "$ROOT/version.env"

APP_NAME=${APP_NAME:-MyApp}
APP_IDENTITY=${APP_IDENTITY:?APP_IDENTITY required}
NOTARY_KEY=${NOTARY_KEY:?NOTARY_KEY required}
NOTARY_KEY_ID=${NOTARY_KEY_ID:?NOTARY_KEY_ID required}
NOTARY_ISSUER=${NOTARY_ISSUER:?NOTARY_ISSUER required}

# Build universal binary
ARCHES="arm64 x86_64" "$ROOT/Scripts/package_app.sh" release

# Notarize
xcrun notarytool submit /tmp/notarize.zip \
    --key "$NOTARY_KEY" \
    --key-id "$NOTARY_KEY_ID" \
    --issuer "$NOTARY_ISSUER" \
    --wait

# Staple
xcrun stapler staple "${ROOT}/${APP_NAME}.app"

echo "Done!"

---

Reference Files

Load these for detailed patterns:

• project-structure.md - Directory layout, module boundaries, target organization
• package-swift.md - Multi-target Package.swift templates, conditional compilation
• swift-concurrency.md - @MainActor, Sendable, Task.detached, cancellation
• observable-state.md - @Observable patterns, @ObservationIgnored, observation tokens
• settings-store.md - UserDefaults + Keychain, debounced persistence, lazy loading
• plugin-architecture.md - Descriptor + Registry + Strategy patterns
• menu-bar-app.md - NSStatusItem, menus, app lifecycle
• app-lifecycle.md - AppDelegate, system events, termination handling
• widget-extension.md - WidgetKit integration, shared data
• keychain-storage.md - Secure storage protocols, error handling
• build-scripts.md - Dev loop, packaging, release automation, locking
• sparkle-updates.md - Sparkle integration, appcast generation, Ed25519 keys
• distribution.md - Code signing, notarization, direct distribution
• code-quality.md - SwiftLint, SwiftFormat, npm scripts
• testing-patterns.md - Swift Testing, mocks, async testing, fixtures

---

Best Practices Summary

Swift Code

• [ ] All models conform to Sendable
• [ ] Use @Observable instead of ObservableObject
• [ ] Use @MainActor on all UI state classes
• [ ] Use actor for I/O workers
• [ ] Use enums for state machines (no boolean flags)
• [ ] Use defer for cleanup in file operations
• [ ] Use localizedCaseInsensitiveCompare for sorting
• [ ] Cancel tasks on new searches (debouncing)
• [ ] Use token-based search cancellation for race conditions

Caching

• [ ] URLSession configured with URLCache
• [ ] NSCache for application-level caching
• [ ] Cache check before network fetch
• [ ] Show cached content while refreshing

API Client

• [ ] Closure-based dependency injection
• [ ] Static factory methods (.live(), .mock())
• [ ] Shared URLSession instance
• [ ] Response validation helper

Settings Persistence

• [ ] UserDefaults for simple preferences
• [ ] Keychain for secrets (with protocol abstraction)
• [ ] Debounced writes (350ms+) for frequent changes
• [ ] Lazy loading pattern for expensive reads

Project Structure

• [ ] No Xcode project file (SwiftPM only)
• [ ] version.env for version tracking
• [ ] Modular targets: Core + App + CLI + Widget
• [ ] Scripts start with set -euo pipefail

Distribution

• [ ] Universal binary (arm64 + x86_64)
• [ ] Developer ID signing
• [ ] Apple notarization
• [ ] Sparkle auto-updates
• [ ] Code signature verification before enabling Sparkle

---

Checklists

New macOS Project

• [ ] Package.swift with Core + App targets
• [ ] StrictConcurrency enabled in swiftSettings
• [ ] version.env with MARKETING_VERSION and BUILD_NUMBER
• [ ] Scripts/ with dev.sh, package.sh
• [ ] .swiftformat and .swiftlint.yml
• [ ] package.json with npm scripts

@Observable Store

• [ ] @MainActor @Observable final class
• [ ] @ObservationIgnored for caches, tasks, loggers
• [ ] Observation token for grouped property tracking
• [ ] Task cancellation in deinit

Menu Bar App

• [ ] AppDelegate with NSStatusItem
• [ ] LSUIElement in Info.plist (no dock icon)
• [ ] Background refresh with Task
• [ ] System notifications (sleep/wake)

Sparkle Integration

• [ ] SUFeedURL in Info.plist
• [ ] SUPublicEDKey in Info.plist
• [ ] Ed25519 keypair generated
• [ ] appcast.xml with signed updates

---

Troubleshooting

| Issue | Solution | |-------|----------| | "App is damaged" | Run xcrun stapler staple MyApp.app | | "Developer cannot be verified" | Check notarization completed successfully | | Sparkle not working | Verify SUFeedURL and SUPublicEDKey in Info.plist | | Sparkle not starting | Check shouldEnableSparkle() - needs signed .app bundle | | Search results stale | Implement token-based cancellation | | Memory pressure | Use NSCache with countLimit | | Race conditions | Use actors, check task cancellation | | Build fails on Swift 6 | Add Sendable conformance to all data types | | App won't activate | Add NSApplication.shared.activate(ignoringOtherApps: true) | | Concurrent build issues | Use lock directory pattern in scripts |

---

Note: Patterns extracted from production-grade Swift macOS applications by @steipete and @thomas.