feat(updater): prereleases, semver max, auto-check opt-out

- List GitHub releases (paginated) and pick single highest PEP 440 version
  newer than local; include alpha/beta/rc and GitHub prerelease flag.
- ReleaseInfo.is_prerelease drives dialog copy with feedback email and
  issues URL from config.
- Persist updater/auto_check_enabled; skip deferred check when disabled;
  Help dialog checkbox + opt-out on update notification (manual check
  still uses force=True).

Made-with: Cursor

Author: richardkoehler

src/dbs_annotator/config.py

@@ -22,6 +22,11 @@
 FS_ORG_NAME = "WyssCenter"
 FS_APP_NAME = "DBSAnnotator"
 
+# Canonical upstream (releases + issue tracker; keep aligned with updater repo slug).
+APP_REPOSITORY_URL = "https://github.com/Brain-Modulation-Lab/App_ClinicalDBSAnnot"
+APP_ISSUES_URL = f"{APP_REPOSITORY_URL}/issues"
+UPDATE_FEEDBACK_EMAIL = "richard.koehler@wysscenter.ch"
+
 # File paths (relative to executable)
 ICON_FILENAME = "logoneutral.png"
 ICO_FILENAME = "logoneutral.ico"

src/dbs_annotator/utils/updater.py

@@ -10,7 +10,11 @@
 * The HTTP fetch runs on a worker thread via :class:`QThreadPool`; the
   main-thread slot is only invoked if a strictly-newer version is found.
 * The user can always trigger a check from a menu / button with
-  ``force=True``.
+  ``force=True`` (even when automatic checks are disabled in preferences).
+* Among all published (non-draft) releases, only the **highest** version
+  greater than the running build is considered (PEP 440 ordering, including
+  alpha / beta / rc). GitHub's ``/releases/latest`` endpoint is not used
+  because it omits pre-releases.
 
 The release repository is hardcoded to the canonical upstream; change
 :data:`DEFAULT_RELEASES_REPO` if the project moves.
@@ -25,6 +29,7 @@
 from collections.abc import Callable
 from dataclasses import dataclass
 from datetime import UTC, datetime, timedelta
+from typing import Any, cast
 
 from packaging.version import InvalidVersion, Version
 from PySide6.QtCore import QObject, QRunnable, QSettings, QThreadPool, Signal
@@ -39,6 +44,9 @@
 DEFAULT_COOLDOWN = timedelta(hours=24)
 DEFAULT_TIMEOUT_SECONDS = 10
 _LAST_CHECK_KEY = "updater/last_check_iso"
+_AUTO_CHECK_KEY = "updater/auto_check_enabled"
+_RELEASES_PAGE_SIZE = 100
+_MAX_RELEASE_PAGES = 5
 
 
 @dataclass(frozen=True)
@@ -50,6 +58,9 @@ class ReleaseInfo:
     html_url: str
     published_at: str
     body: str
+    #: ``True`` if GitHub marked the release as pre-release or the tag parses
+    #: as a PEP 440 pre-release (alpha / beta / rc).
+    is_prerelease: bool
 
 
 def _parse_version(tag: str) -> Version | None:
@@ -66,6 +77,21 @@ def _parse_version(tag: str) -> Version | None:
         return None
 
 
+def _coerce_bool(value: object, default: bool) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        s = value.lower().strip()
+        if s in ("false", "0", "no", ""):
+            return False
+        if s in ("true", "1", "yes"):
+            return True
+        return default
+    if value is None:
+        return default
+    return bool(value)
+
+
 class _CheckSignals(QObject):
     """Qt signals for a check worker.
 
@@ -96,7 +122,7 @@ def __init__(
 
     def run(self) -> None:
         try:
-            latest = self._fetch_latest_release()
+            latest = self._fetch_newest_applicable_release()
         except Exception as exc:
             logger.info("Update check failed: %s", exc)
             self._signals.failed.emit(str(exc))
@@ -108,53 +134,94 @@ def run(self) -> None:
 
         self._signals.update_available.emit(latest)
 
-    def _fetch_latest_release(self) -> ReleaseInfo | None:
-        url = f"https://api.github.com/repos/{self._repo}/releases/latest"
-        request = urllib.request.Request(
+    def _request(self, url: str) -> urllib.request.Request:
+        return urllib.request.Request(
             url,
             headers={
                 "Accept": "application/vnd.github+json",
                 "User-Agent": f"DBSAnnotator/{self._current_version}",
             },
         )
+
+    def _urlopen_json(self, url: str) -> object:
+        request = self._request(url)
+        with urllib.request.urlopen(request, timeout=self._timeout) as response:
+            return json.loads(response.read().decode("utf-8"))
+
+    def _fetch_releases_page(self, page: int) -> list[dict] | None:
+        url = (
+            f"https://api.github.com/repos/{self._repo}/releases"
+            f"?per_page={_RELEASES_PAGE_SIZE}&page={page}"
+        )
         try:
-            with urllib.request.urlopen(request, timeout=self._timeout) as response:
-                payload = json.loads(response.read().decode("utf-8"))
+            payload = self._urlopen_json(url)
         except urllib.error.HTTPError as exc:
-            # GitHub returns 404 when repo has no published releases (or repo missing).
             if exc.code == 404:
                 logger.debug(
-                    "No GitHub releases/latest for %s (HTTP %s); treat as no update",
+                    "No GitHub releases list for %s (HTTP %s); treat as no update",
                     self._repo,
                     exc.code,
                 )
                 return None
             raise
-
-        tag = str(payload.get("tag_name", ""))
-        if not tag:
+        if not isinstance(payload, list):
+            return []
+        return cast(list[dict[str, Any]], payload)
+
+    def _fetch_all_releases(self) -> list[dict]:
+        merged: list[dict] = []
+        for page in range(1, _MAX_RELEASE_PAGES + 1):
+            batch = self._fetch_releases_page(page)
+            if batch is None:
+                return []
+            merged.extend(batch)
+            if len(batch) < _RELEASES_PAGE_SIZE:
+                break
+        return merged
+
+    def _fetch_newest_applicable_release(self) -> ReleaseInfo | None:
+        """Return single newest published release with version *>* local."""
+        payloads = self._fetch_all_releases()
+        if not payloads:
             return None
 
-        remote = _parse_version(tag)
         local = _parse_version(self._current_version)
-        if remote is None or local is None:
+        if local is None:
             logger.debug(
-                "Skipping update comparison for tag=%r current=%r",
-                tag,
+                "Skipping update comparison; local version not PEP 440: %r",
                 self._current_version,
             )
             return None
-        if payload.get("prerelease"):
-            return None
-        if remote <= local:
+
+        best_remote: Version | None = None
+        best_payload: dict | None = None
+
+        for payload in payloads:
+            if payload.get("draft"):
+                continue
+            tag = str(payload.get("tag_name", ""))
+            if not tag:
+                continue
+            remote = _parse_version(tag)
+            if remote is None or remote <= local:
+                continue
+            if best_remote is None or remote > best_remote:
+                best_remote = remote
+                best_payload = payload
+
+        if best_remote is None or best_payload is None:
             return None
 
+        gh_prerelease = bool(best_payload.get("prerelease"))
+        is_prerelease = gh_prerelease or best_remote.is_prerelease
+
         return ReleaseInfo(
-            version=str(remote),
-            tag_name=tag,
-            html_url=str(payload.get("html_url", "")),
-            published_at=str(payload.get("published_at", "")),
-            body=str(payload.get("body", "")),
+            version=str(best_remote),
+            tag_name=str(best_payload.get("tag_name", "")),
+            html_url=str(best_payload.get("html_url", "")),
+            published_at=str(best_payload.get("published_at", "")),
+            body=str(best_payload.get("body", "")),
+            is_prerelease=is_prerelease,
         )
 
 
@@ -164,6 +231,8 @@ class UpdateChecker(QObject):
     Create one of these on the main thread (typically owned by the main
     window) and call :meth:`check_async`. A ``check_async(force=True)`` call
     bypasses the cooldown -- wire it to a "Check for updates" menu action.
+    Automatic checks respect :meth:`auto_update_checks_enabled` (stored in
+    ``QSettings`` under :data:`_AUTO_CHECK_KEY`).
     """
 
     update_available = Signal(object)
@@ -189,6 +258,16 @@ def __init__(
         self._signals.up_to_date.connect(self._on_up_to_date)
         self._signals.failed.connect(self._on_failed)
 
+    def auto_update_checks_enabled(self) -> bool:
+        """Whether startup / periodic background checks are allowed."""
+        raw = self._settings.value(_AUTO_CHECK_KEY, True)
+        return _coerce_bool(raw, True)
+
+    def set_auto_update_checks_enabled(self, enabled: bool) -> None:
+        """Persist preference for automatic update checks."""
+        self._settings.setValue(_AUTO_CHECK_KEY, enabled)
+        self._settings.sync()
+
     def _on_update_available(self, release: ReleaseInfo) -> None:
         self._record_check_time()
         self.update_available.emit(release)
@@ -211,13 +290,16 @@ def check_async(
         """Schedule a background check.
 
         Args:
-            force: If True, bypass the cooldown.
+            force: If True, bypass the cooldown and automatic-check opt-out.
             now: Injectable clock, only for tests.
 
         Returns:
             True if a check was scheduled; False if the cooldown suppressed
-            it.
+            it, automatic checks are disabled, or (when not forced) opt-out
+            applies.
         """
+        if not force and not self.auto_update_checks_enabled():
+            return False
         if not force and not self._cooldown_elapsed(now()):
             return False
 

src/dbs_annotator/views/wizard_window.py

@@ -5,6 +5,7 @@
 navigation, and coordinates views with the controller.
 """
 
+import html
 import logging
 import os
 import typing
@@ -14,6 +15,7 @@
 from PySide6.QtGui import QDesktopServices, QIcon, QPixmap
 from PySide6.QtWidgets import (
     QAbstractButton,
+    QCheckBox,
     QDialog,
     QFrame,
     QHBoxLayout,
@@ -31,14 +33,17 @@
 )
 
 from ..config import (
+    APP_ISSUES_URL,
     APP_NAME,
+    APP_REPOSITORY_URL,
     APP_VERSION,
     BASE_DPI,
     FONT_SCALE_ENABLED,
     ICON_FILENAME,
     ICONS_DIR,
     RESPONSIVE_WINDOW_RATIOS,
     SCREEN_SIZE_THRESHOLDS,
+    UPDATE_FEEDBACK_EMAIL,
     WINDOW_MAX_SIZE_RATIO,
     WINDOW_MIN_SIZE,
     WINDOW_SIZE_RATIO,
@@ -102,7 +107,11 @@ def __init__(self, app):
         self._update_checker = UpdateChecker(parent=self)
         self._update_checker.update_available.connect(self._on_update_available)
         # Defer slightly so the window is painted before any dialog appears.
-        QTimer.singleShot(1500, lambda: self._update_checker.check_async())
+        QTimer.singleShot(1500, self._run_deferred_update_check)
+
+    def _run_deferred_update_check(self) -> None:
+        """Background update check; skipped if user disabled automatic checks."""
+        self._update_checker.check_async()
 
     def _setup_window(self) -> None:
         """Configure the main window properties with responsive sizing."""
@@ -371,7 +380,8 @@ def _show_info_dialog(self) -> None:
         # Description
         desc_text = QTextEdit()
         desc_text.setReadOnly(True)
-        desc_text.setHtml("""
+        desc_text.setHtml(
+            f"""
         <h3>About this application</h3>
         <p>DBS Annotator is a specialized tool for clinicians and researchers
         working with Deep Brain Stimulation (DBS) systems. This application provides:</p>
@@ -400,17 +410,28 @@ def _show_info_dialog(self) -> None:
         </ol>
 
         <h3>Support & Contact</h3>
-        <p><b>GitHub Repository:</b> <a href='https://github.com/your-username/dbs-annotator'>https://github.com/your-username/dbs-annotator</a></p>
-        <p>For bug reports, feature requests, or general support, please visit our GitHub repository
-        or contact Lucia Poma directly at</b> <a href='mailto:lucia.poma@wysscenter.ch'>lucia.poma@wysscenter.ch</a></p>.
+        <p><b>Repository:</b> <a href="{APP_REPOSITORY_URL}">{APP_REPOSITORY_URL}</a></p>
+        <p>For bug reports and feature requests, use the
+        <a href="{APP_ISSUES_URL}">issue tracker</a> or email
+        <a href="mailto:{UPDATE_FEEDBACK_EMAIL}">{UPDATE_FEEDBACK_EMAIL}</a>.</p>
 
         <h3>License</h3>
         <p>This software is released under an open-source license. Please see the GitHub repository
         for detailed licensing information.</p>
-        """)
+        """
+        )
 
         layout.addWidget(desc_text)
 
+        auto_check_cb = QCheckBox(
+            "Automatically check for updates (about once per day)"
+        )
+        auto_check_cb.setChecked(self._update_checker.auto_update_checks_enabled())
+        auto_check_cb.toggled.connect(
+            self._update_checker.set_auto_update_checks_enabled
+        )
+        layout.addWidget(auto_check_cb)
+
         # Footer buttons
         button_layout = QHBoxLayout()
 
@@ -480,22 +501,48 @@ def on_failed(error: str) -> None:
     def _on_update_available(self, release: ReleaseInfo) -> None:
         """Show a non-blocking dialog when a newer release is published."""
         box = QMessageBox(self)
+        box.setTextFormat(Qt.TextFormat.RichText)
         box.setIcon(QMessageBox.Icon.Information)
-        box.setWindowTitle("Update available")
+        box.setWindowTitle(
+            "Pre-release available" if release.is_prerelease else "Update available"
+        )
         box.setText(
             f"A new version of {APP_NAME} is available: "
-            f"<b>{release.version}</b> (you have {APP_VERSION})."
+            f"<b>{html.escape(release.version)}</b> "
+            f"(you have {html.escape(APP_VERSION)})."
         )
+        info_parts: list[str] = []
+        if release.is_prerelease:
+            mail_href = html.escape(f"mailto:{UPDATE_FEEDBACK_EMAIL}", quote=True)
+            issues_href = html.escape(APP_ISSUES_URL, quote=True)
+            email_lbl = html.escape(UPDATE_FEEDBACK_EMAIL)
+            info_parts.append(
+                "<p><b>Note:</b> This is <u>not</u> a stable release; bugs may occur. "
+                "If you try this version, please report issues to "
+                f'<a href="{mail_href}">{email_lbl}</a> or on '
+                f'<a href="{issues_href}">GitHub</a>.</p>'
+            )
         notes = release.body.strip() if release.body else ""
         if notes:
             excerpt = notes if len(notes) <= 600 else notes[:600] + "…"
-            box.setInformativeText("Release notes:\n\n" + excerpt)
+            excerpt_html = html.escape(excerpt).replace("\n", "<br>")
+            info_parts.append(f"<p>Release notes:</p><p>{excerpt_html}</p>")
+        if info_parts:
+            box.setInformativeText("".join(info_parts))
+
+        opt_out_cb = QCheckBox("Don't notify me automatically about new updates")
+        opt_out_cb.setChecked(False)
+        box.setCheckBox(opt_out_cb)
+
         download_btn = box.addButton(
             "Open download page", QMessageBox.ButtonRole.AcceptRole
         )
         box.addButton("Remind me later", QMessageBox.ButtonRole.RejectRole)
         box.exec()
 
+        if opt_out_cb.isChecked():
+            self._update_checker.set_auto_update_checks_enabled(False)
+
         if box.clickedButton() is download_btn and release.html_url:
             QDesktopServices.openUrl(QUrl(release.html_url))