Version 0.0.25

Relevant source files

The following files were used as context for generating this wiki page: - [Sources/UpdateChecker.swift](https://github.com/rauchg/typing-stats/blob/main/Sources/UpdateChecker.swift) - [Sources/AboutWindowController.swift](https://github.com/rauchg/typing-stats/blob/main/Sources/AboutWindowController.swift) - [Sources/AppDelegate.swift](https://github.com/rauchg/typing-stats/blob/main/Sources/AppDelegate.swift) - [skills/sparkle-github-actions.md](https://github.com/rauchg/typing-stats/blob/main/skills/sparkle-github-actions.md) - [build.sh](https://github.com/rauchg/typing-stats/blob/main/build.sh) - [appcast.xml](https://github.com/rauchg/typing-stats/blob/main/appcast.xml) - [Package.swift](https://github.com/rauchg/typing-stats/blob/main/Package.swift)

# Update Checker The Update Checker system in Typing Stats provides automated software update capabilities using the Sparkle framework. It is responsible for monitoring remote update feeds, notifying the user when a new version is available, and facilitating the download and installation process. The system integrates tightly with the macOS menu bar and the app's "About" interface to provide a seamless update experience. The implementation relies on an EdDSA-signed RSS feed (`appcast.xml`) hosted on GitHub, ensuring that updates are secure and verified before installation. The system is designed to handle background checks and provides visual cues, such as a blue notification badge in the menu bar, when updates are pending. ## Architecture and Components The update system is composed of several key components working together to manage the lifecycle of an update, from detection to installation. ### Core Logic: UpdateChecker Class The `UpdateChecker` class serves as the central manager for update operations. It wraps the Sparkle `SPUStandardUpdaterController` and implements the `SPUUpdaterDelegate` protocol to respond to update events. * **Singleton Pattern**: It uses a shared instance (`static let shared`) to ensure a single point of control throughout the app lifecycle. * **Version Tracking**: Maintains an `availableVersion` string which is populated when a valid update is found. * **Notifications**: Posts a `UpdateAvailable` notification to the `NotificationCenter` when a new version is detected. Sources: [Sources/UpdateChecker.swift:3-48]() ### User Interface Integration Updates are exposed to the user through two primary channels: 1. **AppDelegate**: Monitors the `UpdateChecker` and updates the macOS menu bar. It renders a blue dot badge on the menu bar icon and adds "Install Update" items to the status menu when an update is available. 2. **AboutWindowController**: Provides a dedicated UI for checking updates manually, displaying current version info, and showing progress indicators during the check. Sources: [Sources/AppDelegate.swift:65-79](), [Sources/AboutWindowController.swift:145-177]() ## Update Flow and Lifecycle The update process follows a specific sequence of events triggered either automatically on app launch or manually by the user. ### Sequence of Update Detection This diagram illustrates the interaction between the application components and the Sparkle framework during an update check. ```mermaid sequenceDiagram participant App as AppDelegate participant UC as UpdateChecker participant S as Sparkle Framework participant G as GitHub (appcast.xml) App->>UC: Initialize (shared) UC->>S: Start SPUStandardUpdaterController App->>UC: Observe "UpdateAvailable" UC->>S: checkForUpdatesInBackground() S->>G: Fetch appcast.xml G-->>S: Return New Version Info S->>UC: updater(didFindValidUpdate) UC->>UC: Set availableVersion UC->>App: Post "UpdateAvailable" Notification App->>App: Show Blue Badge & Update Menu ``` Sources: [Sources/UpdateChecker.swift:23-44](), [Sources/AppDelegate.swift:75-79]() ### Component Responsibilities | Component | Responsibility | Key Methods | | :--- | :--- | :--- | | `UpdateChecker` | Logic & Delegate Handling | `checkForUpdates()`, `installUpdate()` | | `AppDelegate` | Menu Bar UI & Badging | `handleUpdateAvailable()`, `setStatusItemUpdateBadgeVisible()` | | `AboutWindowController` | Detailed Status UI | `checkForUpdates()`, `updateCheckComplete()` | | `appcast.xml` | Remote update metadata | Contains version, URL, and EdDSA signature | Sources: [Sources/UpdateChecker.swift](), [Sources/AppDelegate.swift](), [Sources/AboutWindowController.swift](), [appcast.xml]() ## Security and Verification The system employs EdDSA (ed25519) cryptographic signing to verify the integrity of update packages. * **Public Key**: Stored in the app's `Info.plist` under the key `SUPublicEDKey`. * **Signatures**: Each update entry in `appcast.xml` contains a `sparkle:edSignature` attribute. * **Verification**: The Sparkle framework automatically compares the signature of the downloaded ZIP against the public key before allowing installation. Sources: [skills/sparkle-github-actions.md:59-71](), [appcast.xml:13]() ## Build and Deployment Integration The update system is supported by a build pipeline that ensures the app is properly signed and the update feed is updated. ### Build Requirements For Sparkle to function correctly, the app bundle must preserve internal symlinks. The project uses the `ditto` command instead of standard `zip` to ensure the `Sparkle.framework` structure remains intact. Additionally, the build script (`build.sh`) performs ad-hoc or Developer ID signing to seal the `Info.plist`, which is a prerequisite for Sparkle to read security keys. Sources: [skills/sparkle-github-actions.md:12-25](), [build.sh:58-81]() ### Update Metadata Structure The `appcast.xml` file follows the RSS 2.0 format with Sparkle extensions. ```xml Version 0.0.25 0.0.25 ``` Sources: [appcast.xml:6-14]() ## Summary The Update Checker module provides a robust, secure mechanism for keeping Typing Stats up to date. By leveraging the Sparkle framework and GitHub Actions, the system automates version tracking, secure verification via EdDSA signatures, and user notification through the macOS menu bar and specialized "About" windows. Its implementation ensures that users are always running the latest version with minimal friction while maintaining high security standards through mandatory code signing and signature verification.