Update Notification
Relevant source files
The following files were used as context for generating this wiki page:
The Update Notification system in QQcode is a background mechanism designed to inform users when a newer version of the CLI tool is available. It operates asynchronously to ensure that checking for updates does not block the primary user interface or agent interactions. The system compares the local CORE_VERSION against the latest release version fetched from the project's GitHub repository.
The scope of this feature includes version fetching via the GitHub API, state management within the Textual-based TUI, and user notification through non-intrusive "toast" messages. It is primarily controlled by the user's configuration, allowing the check to be disabled entirely if desired.
System Architecture
The update notification architecture follows a gateway pattern to decouple the UI from the external version-checking logic.
Components
| Component | Description |
|---|---|
VersionUpdateGateway | Protocol defining the interface for fetching version information. |
GitHubVersionUpdateGateway | Concrete implementation that queries the GitHub API for the latest release. |
VibeApp | The main Textual application that schedules the check and manages UI notifications. |
is_version_update_available | Utility function that compares versions and returns a VersionUpdate object if an update is found. |
Sources: vibe/cli/textual_ui/app.py:53-58, vibe/cli/update_notifier/version_update_gateway.py, vibe/cli/update_notifier/version_update.py
Logic Flow
The following diagram illustrates the sequence of events during a version check session:
The application initializes the update check immediately after mounting the UI, provided enable_update_checks is true in the configuration.
Sources: vibe/cli/textual_ui/app.py:171-172, vibe/cli/textual_ui/app.py:868-877
Implementation Details
GitHub Integration
The GitHubVersionUpdateGateway communicates with the GitHub API (https://api.github.com/repos/qnguyen3/qqcode/releases/latest). It requires a repository owner and name, and can optionally use a GitHub token from the GITHUB_TOKEN environment variable to avoid rate-limiting issues.
Sources: vibe/cli/textual_ui/app.py:910-912, vibe/cli/update_notifier/github_version_update_gateway.py
UI Notifications
When an update is detected, the application displays a notification with a severity of information. If the check fails due to an error (e.g., FORBIDDEN or network issues), a warning severity toast is shown instead.
# vibe/cli/textual_ui/app.py:902-907
def _display_update_notification(self, update: VersionUpdate) -> None:
if self._update_notification_shown:
return
message = f'{self._current_version} => {update.latest_version}\nRun "uv tool upgrade qqcode" to update'
self.notify(
message, title="Update available", severity="information", timeout=10
)
self._update_notification_shown = True
Sources: vibe/cli/textual_ui/app.py:902-907, tests/update_notifier/test_ui_version_update_notification.py:113-118
Version Comparison
The system uses the packaging.version library to handle semantic versioning comparisons accurately. This ensures that only versions strictly greater than the current local version trigger a notification.
Sources: vibe/cli/update_notifier/version_update.py, pyproject.toml:44
Configuration and Control
The feature is governed by parameters within the VibeConfig object, typically loaded from config.toml.
| Parameter | Type | Description |
|---|---|---|
enable_update_checks | bool | Master toggle for the update notification system. |
CORE_VERSION | str | The version string defined in the package metadata (e.g., 1.2.0). |
Sources: vibe/cli/textual_ui/app.py:125-127, vibe/core/config.py, pyproject.toml:3
Summary
The Update Notification system provides an essential feedback loop for users to maintain an up-to-date installation of QQcode. By utilizing asynchronous execution and abstracting the version retrieval via the VersionUpdateGateway, the system remains robust and does not impact the application's responsiveness. Users can verify the update status by looking for informational notifications that suggest using uv tool upgrade qqcode to perform the update.