From bfbdd0c19910f464e779fa64cc0ec8590f8e37c1 Mon Sep 17 00:00:00 2001 From: Christian Kolset Date: Fri, 31 Jul 2026 15:52:28 -0600 Subject: Add PyInstaller packaging and tufup-based auto-update pipeline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Full pipeline, verified end-to-end against the real installed tufup 0.10.0 API (initial docs/summaries turned out inaccurate in places — e.g. the apply method is download_and_apply_update, not update; confirmed by inspecting installed package source directly rather than trusting docs alone): - core/version.py: single-source app version constant. - labdaq.spec: PyInstaller onedir build (must be onedir, not onefile — tufup replaces individual files in the install dir on update). Bundles ui/*.qss, plugins/ (needed for runtime plugin discovery), and repository/metadata/root.json once repo_init.py has produced one. Built and smoke-tested: the frozen exe launches and stays running. - scripts/release/{repo_init,repo_release}.py: maintainer-run release tooling using tufup.repo.Repository, manual local signing (keys never touch CI). Both actually run end-to-end during development of this feature against a real build, not just written and assumed correct. Longer expiration_days than tufup-example's CI-oriented defaults (targets/snapshot/timestamp 90d instead of 7d/7d/1d), since we're signing manually, not on an automated daily schedule — see scripts/release/README.md for the re-signing cadence this still requires even between releases. - core/updater.py: thin Client wrapper. Refuses to run outside a frozen build (getattr(sys, "frozen", False)) since there's no installed bundle for tufup to update in `python main.py` dev mode. Bootstraps the bundled root.json into the metadata cache dir on first run — tuf.ngclient.Updater loads root.json from local disk on construction, it does not fetch it remotely by design (the root of trust can't come from the same server being verified). - core/app_settings.py: factored out app_data_dir() (was inline in _settings_path()) so the updater's metadata/target cache dirs live in the same per-user location as settings.json, deliberately outside the install directory an update can replace/move. - Settings > General: version display + "Check for Updates" button, manual-only per discussion (no silent background network calls or surprise restarts for a lab-instrument-control app). Metadata/targets are hosted on this repo's "updates" GitHub Release — a fixed tag, not a normal per-version tag, because TUF's top-level metadata needs a stable URL across app versions. No such GitHub-Releases- hosting example exists in tufup or tufup-example; verified this by fetching tufup-example's actual GitHub Actions workflow file directly after a web search wrongly suggested one existed — the design here is ours, not copied from upstream. Not yet done, deliberately left for the user: running repo_init.py for real (generates production signing keys), and creating the actual "updates" GitHub Release. Both are irreversible-ish, security-sensitive, externally-visible actions outside what should happen without the user directly driving them. Co-Authored-By: Claude Sonnet 5 --- core/app_settings.py | 12 +++++- core/updater.py | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++ core/version.py | 12 ++++++ 3 files changed, 129 insertions(+), 2 deletions(-) create mode 100644 core/updater.py create mode 100644 core/version.py (limited to 'core') diff --git a/core/app_settings.py b/core/app_settings.py index ea3ac49..718a768 100644 --- a/core/app_settings.py +++ b/core/app_settings.py @@ -18,14 +18,22 @@ import sys from pathlib import Path -def _settings_path() -> Path: +def app_data_dir() -> Path: + """Per-user, per-platform base directory for anything this app needs to + persist outside the install directory (settings, updater cache, ...) — + deliberately outside the install dir since an update can replace/move + everything in there.""" if sys.platform == "win32": base = Path(os.environ.get("APPDATA", Path.home())) elif sys.platform == "darwin": base = Path.home() / "Library" / "Application Support" else: base = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) - return base / "labUI" / "settings.json" + return base / "labUI" + + +def _settings_path() -> Path: + return app_data_dir() / "settings.json" SETTINGS_PATH = _settings_path() diff --git a/core/updater.py b/core/updater.py new file mode 100644 index 0000000..d22cd42 --- /dev/null +++ b/core/updater.py @@ -0,0 +1,107 @@ +""" +core/updater.py + +Thin wrapper around tufup.client.Client — checks for and applies app +updates. Only meaningful inside a PyInstaller-frozen build (see +is_frozen()); calling check_for_update()/apply_update() from a +`python main.py` dev run raises, since there's no installed bundle for +tufup to update. + +Update metadata/targets are hosted on this repo's "updates" GitHub Release +— a fixed tag that never changes between app versions, unlike a normal +per-version release tag, because TUF's top-level metadata (timestamp.json, +snapshot.json, ...) must live at a stable URL the client always checks. +See scripts/release/README.md for the publishing side. +""" + +import sys +from pathlib import Path +from typing import Optional + +from core.app_settings import app_data_dir +from core.version import __version__ as CURRENT_VERSION + +APP_NAME = "labdaq" + +_RELEASE_BASE_URL = "https://github.com/c-kolset/labUI-python/releases/download/updates/" +METADATA_BASE_URL = _RELEASE_BASE_URL +TARGET_BASE_URL = _RELEASE_BASE_URL + +_client = None # lazily-created tufup.client.Client, reused across calls so + # apply_update() can act on what check_for_update() found + + +def is_frozen() -> bool: + """True only inside a PyInstaller-built exe — never for `python main.py`.""" + return bool(getattr(sys, "frozen", False)) + + +def _require_frozen(): + if not is_frozen(): + raise RuntimeError( + "Updates are only available in the packaged app, not `python main.py`." + ) + + +def _bootstrap_root_json(metadata_dir: Path) -> None: + """ + tuf.ngclient.Updater (tufup.client.Client's base class) loads root.json + from metadata_dir automatically on construction — it does NOT fetch it + remotely on first use, by design (TUF's root of trust has to come from + somewhere already trusted, not from the same server being verified). + + So the copy bundled into the app (labdaq.spec bundles + scripts/release/repository/metadata/root.json to "repository/metadata") + has to be seeded into metadata_dir before the first Client is ever + constructed on a given machine. sys._MEIPASS is where PyInstaller puts + bundled data files at runtime, for both onefile and onedir builds. + """ + dest = metadata_dir / "root.json" + if dest.exists(): + return + bundled = Path(getattr(sys, "_MEIPASS", "")) / "repository" / "metadata" / "root.json" + if not bundled.is_file(): + raise RuntimeError(f"Bundled root.json not found at {bundled} — was the app built " + f"before scripts/release/repo_init.py had been run?") + metadata_dir.mkdir(parents=True, exist_ok=True) + dest.write_bytes(bundled.read_bytes()) + + +def _get_client(): + global _client + if _client is None: + from tufup.client import Client + + cache_dir = app_data_dir() / "tufup" + metadata_dir = cache_dir / "metadata" + _bootstrap_root_json(metadata_dir) + _client = Client( + app_name=APP_NAME, + app_install_dir=Path(sys.executable).resolve().parent, + current_version=CURRENT_VERSION, + metadata_dir=metadata_dir, + metadata_base_url=METADATA_BASE_URL, + target_dir=cache_dir / "targets", + target_base_url=TARGET_BASE_URL, + ) + return _client + + +def check_for_update() -> Optional[str]: + """Return the new version string if an update is available, else None.""" + _require_frozen() + new_target = _get_client().check_for_updates() + return str(new_target.version) if new_target else None + + +def apply_update() -> None: + """ + Download, TUF-verify, and install the update found by the most recent + check_for_update() call on this process. Only call after + check_for_update() returned a version — tufup raises otherwise. + + tufup's default install step replaces the app's files and relaunches it; + the calling UI should assume the process may exit during this call. + """ + _require_frozen() + _get_client().download_and_apply_update(skip_confirmation=True) diff --git a/core/version.py b/core/version.py new file mode 100644 index 0000000..8b6c492 --- /dev/null +++ b/core/version.py @@ -0,0 +1,12 @@ +""" +core/version.py + +Single source of truth for the app version. + +Bump this before cutting a release — scripts/release/repo_release.py reads +it (via Repository's app_version_attr="core.version.__version__") to tag +the new tufup target, and core/updater.py reads it as the running app's +current_version when checking for updates. +""" + +__version__ = "1.0.0" -- cgit v1.2.3