trackerkeeper 0.1.0__py3-none-any.whl

trackerkeeper/bus.py

@@ -0,0 +1,110 @@
+"""AppBus — the app-wide Qt signal bus (trackerkeeper's decoupling spine).
+
+UI surfaces emit *intents*; controllers react and emit *state*; neither side
+holds a reference to the other. trackerkeeper ships only the GENERIC chrome/app
+signals here. An app adds its own by subclassing AppBus or standing up a
+second domain bus (jellytoast, for instance, carries ~60 music signals on a
+PlayerBus that subclasses this) — the base stays minimal on purpose.
+
+Singleton access mirrors the pattern the lifted widgets expect::
+
+    from trackerkeeper.bus import AppBus
+    AppBus.get().theme_changed.connect(widget.restyle)
+    AppBus.get().theme_changed.emit()
+"""
+
+from __future__ import annotations
+
+from PySide6.QtCore import QObject, Signal
+
+
+class AppBus(QObject):
+    # ── Appearance ────────────────────────────────────────────────────
+    theme_changed = Signal()          # palette / mode / font swap → re-stamp the app
+    accent_changed = Signal(str)      # new accent hex
+
+    # ── Window / navigation ───────────────────────────────────────────
+    open_main_window = Signal()       # single-instance re-activate, tray, autostart
+    show_settings = Signal()          # open the settings dialog
+    navigate = Signal(object)         # generic navigation intent; app defines the payload
+    files_received = Signal(list)     # paths/URLs forwarded by a second launch (the
+    #                                   "double-click a document while the app is open"
+    #                                   case); run_app bridges it from SingleInstance
+
+    # ── App lifecycle ─────────────────────────────────────────────────
+    update_available = Signal(str, str, str)  # (version, download_url, notes_url) —
+    #                                   trackerkeeper.updates found a newer release; the
+    #                                   top-bar UpdateChip listens
+
+    # ── System ────────────────────────────────────────────────────────
+    hotkeys_changed = Signal()        # global hotkeys reconfigured
+    dpr_changed = Signal()            # device-pixel-ratio changed → re-rasterize cached art
+    notify = Signal(str, str)         # (title, body) → a desktop notification; run_app
+    #                                   routes it to trackerkeeper.notifications (no-op where
+    #                                   unsupported), so app code emits with zero imports
+
+    _instance: "AppBus | None" = None
+    _factory = None  # optional callable -> AppBus (subclass); see set_factory()
+
+    @classmethod
+    def set_factory(cls, factory) -> None:
+        """Register the factory that builds the process-wide bus the first time
+        :meth:`get` is called. An app with a richer bus — a subclass carrying its
+        own signals (jellytoast's ``PlayerBus``, ~60 of them) — registers it here
+        so every leaf widget that calls ``AppBus.get()`` shares the ONE bus. Must
+        run BEFORE the first ``get()`` (raises otherwise): the singleton is built
+        once and cached, so a late factory would silently split the bus."""
+        if AppBus._instance is not None:
+            raise RuntimeError(
+                "AppBus singleton already exists — set_factory() must run before "
+                "the first AppBus.get()"
+            )
+        AppBus._factory = factory
+
+    @classmethod
+    def get(cls) -> "AppBus":
+        """The process-wide bus. Created lazily (via the registered factory, if
+        any) so importing this module never requires a running QApplication. The
+        singleton lives on ``AppBus`` itself, so a subclass's ``get()`` returns
+        the same instance."""
+        if AppBus._instance is None:
+            AppBus._instance = AppBus._factory() if AppBus._factory else cls()
+        return AppBus._instance
+
+
+def get_bus() -> AppBus:
+    """Convenience accessor — equivalent to ``AppBus.get()``."""
+    return AppBus.get()
+
+
+def register_for_theme(widget, restyle_fn) -> None:
+    """Make a surface's OWN stylesheet track live accent/theme changes.
+
+    Calls ``restyle_fn`` now, again on every ``theme_changed``, and auto-
+    disconnects when ``widget`` is destroyed — the one-line way to fix the
+    "accent didn't apply live" class (a surface that bakes ``ui_helpers.ACCENT``
+    into its own ``setStyleSheet`` and never re-stamps). ``restyle_fn`` MUST read
+    the accent FRESH each call via a module-attribute read (``ui_helpers.ACCENT``
+    / a fresh ``selector_qss()``), never a value captured at construction — see
+    ``update_chip._accent_rgb``. The ``destroyed`` teardown keeps the bus from
+    holding a dangling slot into a deleted C++ widget (segfault-safe)."""
+    bus = AppBus.get()
+    bus.theme_changed.connect(restyle_fn)
+
+    def _drop(*_):
+        # Best-effort: Qt already auto-disconnects a bound-method slot when its
+        # QObject dies, so this often finds nothing — the disconnect then raises
+        # (deleted C++ object) OR merely emits a libpyside "Failed to disconnect"
+        # RuntimeWarning. Swallow the exception AND silence the warning; teardown
+        # must never surface either.
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", RuntimeWarning)
+            try:
+                bus.theme_changed.disconnect(restyle_fn)
+            except Exception:
+                pass
+
+    widget.destroyed.connect(_drop)
+    restyle_fn()

trackerkeeper/catalog.py

@@ -0,0 +1,176 @@
+"""The catalog — the maker's tracked fleet, and how it persists.
+
+An :class:`Item` is one thing you watch for updates (an app, a device, a game).
+It carries what you HAVE (``installed``) and what the last check FOUND
+(``latest`` + date + url), so the dashboard reads offline from cache and only
+the network refresh mutates the "latest" side. "There's a new update" is simply
+``latest`` present and ``!= installed``.
+
+State is a JSON file under the app data dir (``QStandardPaths.AppDataLocation``),
+so it travels with the user, not the code. The path is resolved lazily and can
+be overridden (tests, a portable mode) via :func:`set_catalog_path`.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, fields
+from pathlib import Path
+
+# source KINDS the app knows how to check (sources.py owns the checkers). A
+# manual item has no checker — you set `installed` yourself and it never fetches.
+KINDS = ("github", "arch", "appstore", "cachyos", "appledev", "steam", "manual")
+
+
+@dataclass
+class Item:
+    """One tracked thing. ``kind`` picks the checker; ``ref`` is that checker's
+    handle (github: ``owner/repo``; arch: the package name; manual: unused)."""
+
+    name: str
+    platform: str = ""          # freeform label: "Linux", "Steam", "iOS", "Firmware"…
+    group: str = ""             # user category ("iPhone", "Gaming", "PC"); "" = ungrouped
+    kind: str = "manual"        # one of KINDS
+    ref: str = ""               # checker handle
+    installed: str = ""         # the version you have / last acknowledged
+    changelog_url: str = ""     # where to read what changed
+    # ── last-check cache (only the refresh writes these) ──
+    latest: str = ""            # newest version the source reported
+    latest_url: str = ""        # release/changelog URL from the source
+    latest_date: str = ""       # ISO date (YYYY-MM-DD) the latest was published
+    latest_at: str = ""         # full ISO timestamp of the latest, when the source
+                                # gives one — drives "N hours ago"; "" if day-only
+    checked_at: str = ""        # ISO timestamp of the last successful check
+    error: str = ""             # last check's error, if any (else "")
+
+    def has_update(self) -> bool:
+        """True when the source found a version you don't have yet."""
+        return bool(self.latest) and self.latest != self.installed
+
+    def sort_key(self) -> tuple:
+        """Newest-update-first: items WITH an update rank above those without,
+        then by the latest release date (descending), then name."""
+        return (0 if self.has_update() else 1, _neg_date(self.latest_date), self.name.lower())
+
+
+def _neg_date(iso: str) -> str:
+    """A descending-by-date sort helper: map an ISO date to a string that sorts
+    in reverse. Empty (unknown date) sorts last."""
+    if not iso:
+        return "0000-00-00"
+    # invert each digit so lexical ascending == date descending
+    return "".join(str(9 - int(c)) if c.isdigit() else c for c in iso)
+
+
+_VALID = {f.name for f in fields(Item)}
+
+
+def item_from_dict(d: dict) -> Item:
+    """Build an Item from stored JSON, ignoring unknown keys so an older or
+    newer file never crashes the load."""
+    return Item(**{k: v for k, v in d.items() if k in _VALID})
+
+
+# ── persistence ──────────────────────────────────────────────────────────────
+
+_override_path: Path | None = None
+
+
+def set_catalog_path(path: Path | None) -> None:
+    """Pin the catalog file (tests, portable mode). None → resolve normally."""
+    global _override_path
+    _override_path = Path(path) if path else None
+
+
+def catalog_path() -> Path:
+    """The catalog JSON path — the override, else ``<AppData>/catalog.json``.
+    Resolving AppData needs a QApplication with the identity names set (run_app
+    does this); falls back to an XDG-style path so headless/agent use still
+    works."""
+    if _override_path is not None:
+        return _override_path
+    base = _appdata_dir()
+    return base / "catalog.json"
+
+
+def _appdata_dir() -> Path:
+    try:
+        from PySide6.QtCore import QStandardPaths
+
+        loc = QStandardPaths.writableLocation(
+            QStandardPaths.StandardLocation.AppDataLocation
+        )
+        if loc:
+            return Path(loc)
+    except Exception:
+        pass
+    import os
+
+    from trackerkeeper import identity
+
+    base = os.environ.get("XDG_DATA_HOME") or os.path.join(
+        os.path.expanduser("~"), ".local", "share"
+    )
+    return Path(base) / identity.app()
+
+
+def load() -> list[Item]:
+    """The stored fleet, or the seed on first run (a missing/blank file)."""
+    path = catalog_path()
+    if not path.is_file():
+        return default_fleet()
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+        items = [item_from_dict(d) for d in raw.get("items", [])]
+        return items if items else default_fleet()
+    except (json.JSONDecodeError, OSError):
+        return default_fleet()
+
+
+def save(items: list[Item]) -> None:
+    """Write the fleet atomically (tmp + replace) so a crash mid-write never
+    truncates the catalog."""
+    path = catalog_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {"schema": 1, "items": [asdict(i) for i in items]}
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+    tmp.replace(path)
+
+
+# ── the seed: the maker's real fleet ─────────────────────────────────────────
+
+
+def default_fleet() -> list[Item]:
+    """tracker keeper's first run shows a REAL dashboard, not an empty box:
+    August's fleet, each mapped to the best source we can check today. The auto
+    ones (github/arch) fill their `latest` on the first Refresh; the manual ones
+    hold what you enter until a checker for their world exists."""
+    return [
+        Item(name="KDE Plasma", platform="Linux", group="PC", kind="arch", ref="plasma-desktop",
+             changelog_url="https://kde.org/announcements/"),
+        Item(name="Ghostty", platform="Terminal", group="PC", kind="github",
+             ref="ghostty-org/ghostty",
+             changelog_url="https://github.com/ghostty-org/ghostty/releases"),
+        Item(name="CachyOS", platform="Linux", group="PC", kind="cachyos", ref="desktop",
+             changelog_url="https://cachyos.org/blog/"),
+        Item(name="Slay the Spire 2", platform="Steam", group="Gaming", kind="steam", ref="2868840",
+             changelog_url="https://store.steampowered.com/news/app/2868840"),
+        Item(name="SteamOS (Armada)", platform="Handheld", group="Gaming", kind="github",
+             ref="virtudude/armada",
+             changelog_url="https://github.com/virtudude/armada"),
+        Item(name="iOS Developer Beta", platform="iOS", group="iPhone", kind="appledev",
+             ref="iOS 27",
+             changelog_url="https://developer.apple.com/news/releases/"),
+        Item(name="Blackmagic Camera", platform="iOS", group="iPhone", kind="appstore",
+             ref="6449580241", installed="3.4",
+             changelog_url="https://www.blackmagicdesign.com/support/family/blackmagic-camera"),
+        Item(name="FEX", platform="ARM", group="Gaming", kind="github", ref="FEX-Emu/FEX",
+             changelog_url="https://github.com/FEX-Emu/FEX/releases"),
+        Item(name="Purple Turnip", platform="Adreno", group="Gaming", kind="github",
+             ref="MrPurple666/purple-turnip",
+             changelog_url="https://github.com/MrPurple666/purple-turnip/releases"),
+        Item(name="GameNative", platform="Android", group="Gaming", kind="github",
+             ref="utkarshdalal/GameNative",
+             changelog_url="https://github.com/utkarshdalal/GameNative/releases"),
+    ]