synodic-client 0.0.1.dev35__tar.gz → 0.0.1.dev37__tar.gz

{synodic_client-0.0.1.dev35 → synodic_client-0.0.1.dev37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: synodic_client
-Version: 0.0.1.dev35
+Version: 0.0.1.dev37
 Author-Email: Synodic Software <contact@synodic.software>
 License: LGPL-3.0-or-later
 Project-URL: homepage, https://github.com/synodic/synodic-client
@@ -8,7 +8,7 @@ Project-URL: repository, https://github.com/synodic/synodic-client
 Requires-Python: <3.15,>=3.14
 Requires-Dist: pyside6>=6.10.2
 Requires-Dist: packaging>=26.0
-Requires-Dist: porringer>=0.2.1.dev52
+Requires-Dist: porringer>=0.2.1.dev53
 Requires-Dist: qasync>=0.28.0
 Requires-Dist: velopack>=0.0.1442.dev64255
 Requires-Dist: typer>=0.24.1

{synodic_client-0.0.1.dev35 → synodic_client-0.0.1.dev37}/pyproject.toml

@@ -10,12 +10,12 @@ requires-python = ">=3.14, <3.15"
 dependencies = [
     "pyside6>=6.10.2",
     "packaging>=26.0",
-    "porringer>=0.2.1.dev52",
+    "porringer>=0.2.1.dev53",
     "qasync>=0.28.0",
     "velopack>=0.0.1442.dev64255",
     "typer>=0.24.1",
 ]
-version = "0.0.1.dev35"
+version = "0.0.1.dev37"
 
 [project.license]
 text = "LGPL-3.0-or-later"
@@ -75,6 +75,14 @@ select = [
     "PT",
 ]
 
+[tool.ruff.lint.per-file-ignores]
+"synodic_client/application/bootstrap.py" = [
+    "E402",
+]
+"synodic_client/cli.py" = [
+    "PLC0415",
+]
+
 [tool.ruff.lint.pydocstyle]
 convention = "google"
 

synodic_client-0.0.1.dev37/synodic_client/_version.py

@@ -0,0 +1 @@
+__version__ = '0.0.1.dev37'

{synodic_client-0.0.1.dev35 → synodic_client-0.0.1.dev37}/synodic_client/application/bootstrap.py

@@ -44,7 +44,7 @@ if not _dev_mode:
         remove_startup()
 
 # Heavy imports happen here — PySide6, porringer, etc.
-from synodic_client.application.qt import application  # noqa: E402
+from synodic_client.application.qt import application
 
 _uri = next((a for a in sys.argv[1:] if a.lower().startswith(f'{_PROTOCOL_SCHEME}://')), None)
 application(uri=_uri, dev_mode=_dev_mode)

{synodic_client-0.0.1.dev35 → synodic_client-0.0.1.dev37}/synodic_client/application/icon.py

@@ -4,13 +4,14 @@ Loads the icon once from package resources and caches the ``QIcon``
 so every caller shares the same instance.
 """
 
+import functools
+
 from PySide6.QtGui import QIcon, QPixmap
 
 from synodic_client.client import Client
 
-_cached_icon: QIcon | None = None
-
 
+@functools.cache
 def app_icon() -> QIcon:
     """Return the shared application ``QIcon``, loading it on first call.
 
@@ -20,8 +21,5 @@ def app_icon() -> QIcon:
     Returns:
         A ``QIcon`` backed by the application logo.
     """
-    global _cached_icon  # noqa: PLW0603
-    if _cached_icon is None:
-        with Client.resource(Client.icon) as icon_path:
-            _cached_icon = QIcon(QPixmap(str(icon_path)))
-    return _cached_icon
+    with Client.resource(Client.icon) as icon_path:
+        return QIcon(QPixmap(str(icon_path)))

{synodic_client-0.0.1.dev35 → synodic_client-0.0.1.dev37}/synodic_client/application/screen/__init__.py

@@ -6,7 +6,7 @@ execution log panel live here to avoid circular imports.
 
 from __future__ import annotations
 
-from porringer.schema import SkipReason
+from porringer.schema import SetupAction, SkipReason
 from porringer.schema.plugin import PluginKind
 
 ACTION_KIND_LABELS: dict[PluginKind | None, str] = {
@@ -54,3 +54,17 @@ def skip_reason_label(reason: SkipReason | None) -> str:
     if reason is None:
         return 'Skipped'
     return SKIP_REASON_LABELS.get(reason, reason.name.replace('_', ' ').capitalize())
+
+
+def format_cli_command(action: SetupAction) -> str:
+    """Return a human-readable CLI command string for *action*.
+
+    Prefers ``cli_command``, falls back to ``command``, then synthesises
+    an ``installer install <package>`` string for package actions, and
+    finally returns the action description as a last resort.
+    """
+    if parts := (action.cli_command or action.command):
+        return ' '.join(parts)
+    if action.kind == PluginKind.PACKAGE and action.package:
+        return f'{action.installer or "pip"} install {action.package}'
+    return action.description

{synodic_client-0.0.1.dev35 → synodic_client-0.0.1.dev37}/synodic_client/application/screen/action_card.py

@@ -33,7 +33,7 @@ from PySide6.QtWidgets import (
     QWidget,
 )
 
-from synodic_client.application.screen import ACTION_KIND_LABELS, skip_reason_label
+from synodic_client.application.screen import ACTION_KIND_LABELS, format_cli_command, skip_reason_label
 from synodic_client.application.theme import (
     ACTION_CARD_COMMAND_STYLE,
     ACTION_CARD_DESC_STYLE,
@@ -48,6 +48,7 @@ from synodic_client.application.theme import (
     ACTION_CARD_STATUS_DONE,
     ACTION_CARD_STATUS_FAILED,
     ACTION_CARD_STATUS_NEEDED,
+    ACTION_CARD_STATUS_PENDING,
     ACTION_CARD_STATUS_RUNNING,
     ACTION_CARD_STATUS_SATISFIED,
     ACTION_CARD_STATUS_SKIPPED,
@@ -113,12 +114,14 @@ def action_sort_key(action: SetupAction) -> int:
 
 
 def _format_command(action: SetupAction) -> str:
-    """Return a short CLI command string for display."""
-    if parts := (action.cli_command or action.command):
-        return ' '.join(parts)
-    if action.kind == PluginKind.PACKAGE and action.package:
-        return f'{action.installer or "pip"} install {action.package}'
-    return ''
+    """Return a short CLI command string for display.
+
+    Wraps :func:`~synodic_client.application.screen.format_cli_command`
+    but returns an empty string instead of the description fallback so
+    cards only show an explicit command line.
+    """
+    text = format_cli_command(action)
+    return '' if text == action.description else text
 
 
 # ---------------------------------------------------------------------------
@@ -138,7 +141,7 @@ class _CardSpinner(QWidget):
         self._angle = 0
         self.setFixedSize(ACTION_CARD_SPINNER_SIZE, ACTION_CARD_SPINNER_SIZE)
 
-    def paintEvent(self, _event: object) -> None:  # noqa: N802
+    def paintEvent(self, _event: object) -> None:
         """Draw the muted track and animated highlight arc."""
         painter = QPainter(self)
         painter.setRenderHint(QPainter.RenderHint.Antialiasing)
@@ -379,7 +382,7 @@ class ActionCard(QFrame):
     # Mouse events (toggle log)
     # ------------------------------------------------------------------
 
-    def mousePressEvent(self, event: object) -> None:  # noqa: N802
+    def mousePressEvent(self, event: object) -> None:
         """Toggle the inline log body on click."""
         if self._is_skeleton or not hasattr(self, '_log_output'):
             return
@@ -471,23 +474,8 @@ class ActionCard(QFrame):
 
         self._version_label.setText('')
 
-        # Status — check plugin presence first
-        installer_missing = (
-            action.installer is not None
-            and action.installer in plugin_installed
-            and not plugin_installed[action.installer]
-        )
-
-        if installer_missing:
-            self._status_label.setText('Not installed')
-            self._status_label.setStyleSheet(ACTION_CARD_STATUS_UNAVAILABLE)
-            self._status_label.show()
-        else:
-            # Show spinner instead of status text while checking
-            self._status_label.hide()
-            self._checking = True
-            self._spinner_canvas.show()
-            self._spinner_timer.start()
+        # Status
+        self._populate_status(action, plugin_installed)
 
         # Pre-release checkbox
         if action.package is not None:
@@ -525,6 +513,40 @@ class ActionCard(QFrame):
         else:
             self._command_row.hide()
 
+    def _populate_status(
+        self,
+        action: SetupAction,
+        plugin_installed: dict[str, bool],
+    ) -> None:
+        """Set the initial status badge during :meth:`populate`.
+
+        Bare-command actions (``kind is None``) show a static *Pending*
+        badge.  Plugin-backed actions either flag a missing installer or
+        start the dry-run spinner.
+        """
+        if action.kind is None:
+            self._status_label.setText('Pending')
+            self._status_label.setStyleSheet(ACTION_CARD_STATUS_PENDING)
+            self._status_label.show()
+            return
+
+        installer_missing = (
+            action.installer is not None
+            and action.installer in plugin_installed
+            and not plugin_installed[action.installer]
+        )
+
+        if installer_missing:
+            self._status_label.setText('Not installed')
+            self._status_label.setStyleSheet(ACTION_CARD_STATUS_UNAVAILABLE)
+            self._status_label.show()
+        else:
+            # Show spinner instead of status text while checking
+            self._status_label.hide()
+            self._checking = True
+            self._spinner_canvas.show()
+            self._spinner_timer.start()
+
     def initial_status(self) -> str:
         """Return the initial status text set during :meth:`populate`."""
         if self._is_skeleton or not hasattr(self, '_status_label'):
@@ -549,6 +571,15 @@ class ActionCard(QFrame):
     def set_check_result(self, result: SetupActionResult) -> None:
         """Update the card with a dry-run check result.
 
+        Handles four cases:
+
+        * **Skipped (update available)** — amber "Update available" badge.
+        * **Skipped (other)** — muted satisfied badge.
+        * **Failed** — red "Failed" badge with diagnostic tooltip.
+          This covers backend failures surfaced during the dry-run
+          (e.g. missing SCM plugin, unresolvable deferred action).
+        * **Needed** — default blue badge.
+
         Args:
             result: The action check result from the preview worker.
         """
@@ -565,6 +596,15 @@ class ActionCard(QFrame):
             label = skip_reason_label(result.skip_reason)
             self._status_label.setText(label)
             self._status_label.setStyleSheet(ACTION_CARD_STATUS_SATISFIED)
+        elif not result.success:
+            label = 'Failed'
+            self._status_label.setText(label)
+            self._status_label.setStyleSheet(ACTION_CARD_STATUS_FAILED)
+            logger.warning(
+                'Dry-run check failed for %s: %s',
+                self._action.description if self._action else '(unknown)',
+                result.message or 'unknown error',
+            )
         else:
             label = 'Needed'
             self._status_label.setText(label)
@@ -768,10 +808,7 @@ class ActionCardList(QScrollArea):
             prerelease_overrides: Package names with user pre-release overrides.
         """
         self.clear()
-        sorted_actions = sorted(
-            (a for a in actions if a.kind is not None),
-            key=action_sort_key,
-        )
+        sorted_actions = sorted(actions, key=action_sort_key)
         for act in sorted_actions:
             card = ActionCard(self._container)
             card.populate(

{synodic_client-0.0.1.dev35 → synodic_client-0.0.1.dev37}/synodic_client/application/screen/card.py

@@ -64,7 +64,7 @@ class ClickableHeader(QWidget):
 
     # --- Event handling ---------------------------------------------------
 
-    def mousePressEvent(self, _event: object) -> None:  # noqa: N802
+    def mousePressEvent(self, _event: object) -> None:
         """Emit :attr:`clicked` on any mouse press."""
         self.clicked.emit()
 

{synodic_client-0.0.1.dev35 → synodic_client-0.0.1.dev37}/synodic_client/application/screen/install.py

@@ -14,6 +14,7 @@ import asyncio
 import logging
 import shutil
 import tempfile
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 from urllib.parse import urlparse
@@ -32,11 +33,8 @@ from porringer.schema import (
     SubActionProgress,
     SyncStrategy,
 )
-from porringer.schema.plugin import PluginKind
-from PySide6.QtCore import Qt, QThread, QTimer, Signal
-from PySide6.QtGui import QFont
+from PySide6.QtCore import QThread, QTimer, Signal
 from PySide6.QtWidgets import (
-    QApplication,
     QFileDialog,
     QFrame,
     QHBoxLayout,
@@ -45,7 +43,6 @@ from PySide6.QtWidgets import (
     QMainWindow,
     QMessageBox,
     QPushButton,
-    QToolButton,
     QVBoxLayout,
     QWidget,
 )
@@ -56,19 +53,12 @@ from synodic_client.application.screen.card import CardFrame
 from synodic_client.application.theme import (
     ACTION_CARD_SKELETON_BAR_STYLE,
     CARD_SPACING,
-    COMMAND_HEADER_STYLE,
     COMPACT_MARGINS,
     CONTENT_MARGINS,
-    COPY_BTN_SIZE,
-    COPY_BTN_STYLE,
-    COPY_FEEDBACK_MS,
-    COPY_ICON,
     HEADER_STYLE,
     INSTALL_PREVIEW_MIN_SIZE,
     METADATA_SKELETON_HEIGHT,
     METADATA_SKELETON_STYLE,
-    MONOSPACE_FAMILY,
-    MONOSPACE_SIZE,
     MUTED_STYLE,
     NO_MARGINS,
 )
@@ -94,13 +84,13 @@ def normalize_manifest_key(path_or_url: str) -> str:
         return path_or_url
 
 
-def format_cli_command(action: SetupAction) -> str:
-    """Return a copyable CLI command string for *action*."""
-    if parts := (action.cli_command or action.command):
-        return ' '.join(parts)
-    if action.kind == PluginKind.PACKAGE and action.package:
-        return f'{action.installer or "pip"} install {action.package}'
-    return action.description
+@dataclass(frozen=True, slots=True)
+class InstallConfig:
+    """Optional execution parameters for :class:`InstallWorker`."""
+
+    project_directory: Path | None = None
+    strategy: SyncStrategy = SyncStrategy.MINIMAL
+    prerelease_packages: set[str] | None = field(default=None)
 
 
 class InstallWorker(QThread):
@@ -116,15 +106,12 @@ class InstallWorker(QThread):
     sub_progress = Signal(object, object)  # (SetupAction, SubActionProgress)
     error = Signal(str)
 
-    def __init__(  # noqa: PLR0913
+    def __init__(
         self,
         porringer: API,
         manifest_path: Path,
         cancellation_token: CancellationToken,
-        *,
-        project_directory: Path | None = None,
-        strategy: SyncStrategy = SyncStrategy.MINIMAL,
-        prerelease_packages: set[str] | None = None,
+        config: InstallConfig | None = None,
     ) -> None:
         """Initialize the worker.
 
@@ -132,19 +119,14 @@ class InstallWorker(QThread):
             porringer: The porringer API instance.
             manifest_path: Path to the manifest file to execute.
             cancellation_token: Token for cooperative cancellation.
-            project_directory: Working directory for project sync actions.
-            strategy: Sync strategy — ``LATEST`` when upgrades are pending.
-            prerelease_packages: Package names whose ``include_prereleases``
-                flag should be forced to ``True``, overriding the manifest
-                default.
+            config: Optional execution parameters (directory, strategy,
+                prerelease overrides).
         """
         super().__init__()
         self._porringer = porringer
         self._manifest_path = manifest_path
         self._cancellation_token = cancellation_token
-        self._project_directory = project_directory
-        self._strategy = strategy
-        self._prerelease_packages = prerelease_packages
+        self._config = config or InstallConfig()
 
     def run(self) -> None:
         """Execute the setup actions on this thread's event loop."""
@@ -161,9 +143,9 @@ class InstallWorker(QThread):
         """Stream execution events and collect results."""
         params = SetupParameters(
             paths=[self._manifest_path],
-            project_directory=self._project_directory,
-            strategy=self._strategy,
-            prerelease_packages=self._prerelease_packages,
+            project_directory=self._config.project_directory,
+            strategy=self._config.strategy,
+            prerelease_packages=self._config.prerelease_packages,
         )
         actions: list[SetupAction] = []
         collected: list[SetupActionResult] = []
@@ -195,109 +177,6 @@ class InstallWorker(QThread):
         )
 
 
-class PostInstallSection(QWidget):
-    """Always-visible section showing bare-command (post-install) actions.
-
-    Bare-command actions (``kind is None``) cannot be dry-run checked, so
-    they are excluded from the main actions table.  This widget gives
-    them a dedicated, always-visible home with copyable CLI text.
-    """
-
-    def __init__(self, parent: QWidget | None = None) -> None:
-        """Initialise the section (hidden until :meth:`populate` is called)."""
-        super().__init__(parent)
-        self.hide()
-
-        self._layout = QVBoxLayout(self)
-        self._layout.setContentsMargins(*NO_MARGINS)
-        self._layout.setSpacing(4)
-
-        header = QLabel('Post-Install Commands')
-        header.setStyleSheet(COMMAND_HEADER_STYLE)
-        self._layout.addWidget(header)
-
-        self._content = QWidget()
-        self._content_layout = QVBoxLayout(self._content)
-        self._content_layout.setContentsMargins(*NO_MARGINS)
-        self._content_layout.setSpacing(4)
-        self._layout.addWidget(self._content)
-
-    def populate(self, actions: list[SetupAction]) -> None:
-        """Show command actions from *actions*.
-
-        Only actions whose ``kind`` is ``None`` are shown.  If there are
-        none the widget stays hidden.
-
-        Args:
-            actions: The full list of setup actions.
-        """
-        # Clear previous content
-        while self._content_layout.count():
-            item = self._content_layout.takeAt(0)
-            if item is not None:
-                widget = item.widget()
-                if widget is not None:
-                    widget.deleteLater()
-
-        commands = [(i, a) for i, a in enumerate(actions, 1) if a.kind is None]
-        if not commands:
-            self.hide()
-            return
-
-        mono = QFont(MONOSPACE_FAMILY, MONOSPACE_SIZE)
-        for idx, action in commands:
-            desc = action.package_description or action.description
-            label = QLabel(f'{idx}. {desc}')
-            label.setStyleSheet(COMMAND_HEADER_STYLE)
-            self._content_layout.addWidget(label)
-
-            field = QLineEdit(format_cli_command(action))
-            field.setReadOnly(True)
-            field.setFont(mono)
-
-            row_layout = QHBoxLayout()
-            row_layout.setContentsMargins(*NO_MARGINS)
-            row_layout.setSpacing(4)
-            row_layout.addWidget(field)
-            row_layout.addWidget(_make_copy_button(field))
-
-            row_widget = QWidget()
-            row_widget.setLayout(row_layout)
-            self._content_layout.addWidget(row_widget)
-
-        self.show()
-
-
-def _make_copy_button(field: QLineEdit) -> QToolButton:
-    """Create a copy-to-clipboard button bound to *field*."""
-    btn = QToolButton()
-    btn.setText(COPY_ICON)
-    btn.setToolTip('Copy to clipboard')
-    btn.setFixedSize(*COPY_BTN_SIZE)
-    btn.setStyleSheet(COPY_BTN_STYLE)
-    btn.setCursor(Qt.CursorShape.PointingHandCursor)
-    btn.clicked.connect(lambda: _copy_command(field, btn))
-    return btn
-
-
-def _copy_command(field: QLineEdit, button: QToolButton) -> None:
-    """Copy the field text to the clipboard and briefly show a check mark."""
-    clipboard = QApplication.clipboard()
-    if clipboard:
-        clipboard.setText(field.text())
-    button.setText('\u2713')
-    button.setToolTip('Copied!')
-
-    def _restore() -> None:
-        try:
-            button.setText(COPY_ICON)
-            button.setToolTip('Copy to clipboard')
-        except RuntimeError:
-            pass
-
-    QTimer.singleShot(COPY_FEEDBACK_MS, _restore)
-
-
 # ---------------------------------------------------------------------------
 # SetupPreviewWidget — reusable preview + install widget
 # ---------------------------------------------------------------------------
@@ -400,10 +279,6 @@ class SetupPreviewWidget(QWidget):
         self._card_list.prerelease_toggled.connect(self._on_prerelease_row_toggled)
         outer.addWidget(self._card_list, stretch=1)
 
-        # Post-install section lives below the card list but still scrolls.
-        # It starts hidden and is inserted into the layout after populate().
-        self._post_install_section = PostInstallSection()
-
         # --- Button bar (fixed at bottom) ---
         button_bar = self._init_button_bar()
         outer.addLayout(button_bar)
@@ -524,7 +399,6 @@ class SetupPreviewWidget(QWidget):
         self._prerelease_debounce.stop()
 
         self._card_list.clear()
-        self._post_install_section.hide()
         self._name_label.hide()
         self._description_label.hide()
         self._meta_label.hide()
@@ -643,8 +517,6 @@ class SetupPreviewWidget(QWidget):
 
         # Mark installer-missing actions as 'Not installed' in the status list
         for i, action in enumerate(preview.actions):
-            if action.kind is None:
-                continue
             installer_missing = (
                 action.installer is not None
                 and action.installer in self._plugin_installed
@@ -653,13 +525,6 @@ class SetupPreviewWidget(QWidget):
             if installer_missing:
                 self._action_statuses[i] = 'Not installed'
 
-        # Populate post-install commands and place them after all cards.
-        self._post_install_section.populate(preview.actions)
-        self._card_list._layout.insertWidget(
-            self._card_list._layout.count() - 1,
-            self._post_install_section,
-        )
-
         self._install_btn.setEnabled(True)
 
     def on_preview_resolved(self, preview: SetupResults) -> None:
@@ -688,6 +553,8 @@ class SetupPreviewWidget(QWidget):
             self._upgradable_rows.add(row)
         elif result.skipped:
             label = skip_reason_label(result.skip_reason)
+        elif not result.success:
+            label = 'Failed'
         else:
             label = 'Needed'
 
@@ -724,7 +591,8 @@ class SetupPreviewWidget(QWidget):
         needed = sum(1 for s in self._action_statuses if s == 'Needed')
         upgradable = len(self._upgradable_rows)
         unavailable = sum(1 for s in self._action_statuses if s == 'Not installed')
-        satisfied = total - needed - upgradable - unavailable
+        failed = sum(1 for s in self._action_statuses if s == 'Failed')
+        satisfied = total - needed - upgradable - unavailable - failed
 
         parts: list[str] = []
         if needed:
@@ -735,21 +603,24 @@ class SetupPreviewWidget(QWidget):
             parts.append(f'{satisfied} already satisfied')
         if unavailable:
             parts.append(f'{unavailable} unavailable (plugin not installed)')
+        if failed:
+            parts.append(f'{failed} failed')
 
         actionable = needed + upgradable
-        if actionable == 0 and unavailable == 0:
+        if actionable == 0 and unavailable == 0 and failed == 0:
             self._status_label.setText(f'{total} action(s) \u2014 all already satisfied.')
             self._install_btn.setEnabled(False)
         else:
             self._status_label.setText(f'{total} action(s): {", ".join(parts)}.')
 
         logger.info(
-            'Preview complete: %d total, %d needed, %d upgradable, %d satisfied, %d unavailable',
+            'Preview complete: %d total, %d needed, %d upgradable, %d satisfied, %d unavailable, %d failed',
             total,
             needed,
             upgradable,
             satisfied,
             unavailable,
+            failed,
         )
 
     def on_preview_error(self, message: str) -> None:
@@ -818,9 +689,11 @@ class SetupPreviewWidget(QWidget):
             self._porringer,
             self._manifest_path,
             self._cancellation_token,
-            project_directory=self._project_directory,
-            strategy=strategy,
-            prerelease_packages=self._prerelease_overrides or None,
+            InstallConfig(
+                project_directory=self._project_directory,
+                strategy=strategy,
+                prerelease_packages=self._prerelease_overrides or None,
+            ),
         )
         worker.action_started.connect(self._on_action_started)
         worker.sub_progress.connect(self._on_sub_progress)

{synodic_client-0.0.1.dev35 → synodic_client-0.0.1.dev37}/synodic_client/application/screen/screen.py

@@ -38,6 +38,7 @@ from synodic_client.application.screen.install import (
     normalize_manifest_key,
 )
 from synodic_client.application.screen.spinner import SpinnerWidget
+from synodic_client.application.screen.update_banner import UpdateBanner
 from synodic_client.application.theme import (
     CARD_SPACING,
     COMPACT_MARGINS,
@@ -565,7 +566,7 @@ class ProjectsView(QWidget):
         self._loading_spinner.raise_()
 
     # ------------------------------------------------------------------
-    def resizeEvent(self, event: QResizeEvent) -> None:  # noqa: N802
+    def resizeEvent(self, event: QResizeEvent) -> None:
         """Keep the overlay spinner filling the entire view."""
         super().resizeEvent(event)
         self._loading_spinner.setGeometry(self.rect())
@@ -815,6 +816,9 @@ class MainWindow(QMainWindow):
         self.setMinimumSize(*MAIN_WINDOW_MIN_SIZE)
         self.setWindowIcon(app_icon())
 
+        # Update banner — always available, starts hidden.
+        self._update_banner = UpdateBanner(self)
+
     @property
     def porringer(self) -> API | None:
         """Return the porringer API instance, if available."""
@@ -825,6 +829,11 @@ class MainWindow(QMainWindow):
         """Return the plugins view, if initialised."""
         return self._plugins_view
 
+    @property
+    def update_banner(self) -> UpdateBanner:
+        """Return the update banner widget."""
+        return self._update_banner
+
     def show(self) -> None:
         """Show the window, initializing UI lazily on first show."""
         if self._tabs is None and self._porringer is not None and self._config is not None:
@@ -843,7 +852,14 @@ class MainWindow(QMainWindow):
             gear_btn.clicked.connect(self.settings_requested.emit)
             self._tabs.setCornerWidget(gear_btn)
 
-            self.setCentralWidget(self._tabs)
+            # Container: banner above tabs
+            container = QWidget(self)
+            container_layout = QVBoxLayout(container)
+            container_layout.setContentsMargins(0, 0, 0, 0)
+            container_layout.setSpacing(0)
+            container_layout.addWidget(self._update_banner)
+            container_layout.addWidget(self._tabs)
+            self.setCentralWidget(container)
 
         # Paint the window immediately, then refresh data asynchronously
         super().show()