trackerkeeper 0.1.0__py3-none-any.whl

trackerkeeper/__init__.py

@@ -0,0 +1,55 @@
+"""trackerkeeper — the wolfgang warehaus app base. See docs/PHILOSOPHY.md."""
+
+from trackerkeeper.identity import configure
+
+
+def _resolve_version() -> str:
+    """The single version source (docs/BAKING.md §2 principle 4). In a built
+    install, setuptools-scm has written ``trackerkeeper/_version.py`` from the git tag.
+    In a raw source checkout it hasn't, so fall back to the installed-package
+    metadata, then to a sentinel — never hardcode a number that could drift."""
+    try:
+        from trackerkeeper._version import version  # generated at build by setuptools-scm
+
+        return version
+    except ImportError:
+        pass
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+
+        try:
+            return version("trackerkeeper")
+        except PackageNotFoundError:
+            pass
+    except ImportError:
+        pass
+    return "0.0.0+unknown"
+
+
+__version__ = _resolve_version()
+
+# Curated public API. configure() is eager — it must be callable before anything
+# heavy imports (see trackerkeeper.identity: the font-scale loader reads QSettings at
+# import time). The rest resolve LAZILY via __getattr__ so `import trackerkeeper` stays
+# light: importing the chrome (window / app / design_tokens) would trip that
+# import-time read before a fork's configure() could run. Reach for them
+# (trackerkeeper.run_app, trackerkeeper.AppWindow, …) AFTER configuring.
+_LAZY = {
+    "run_app": ("trackerkeeper.app", "run_app"),
+    "AppWindow": ("trackerkeeper.window", "AppWindow"),
+    "AppBus": ("trackerkeeper.bus", "AppBus"),
+    "get_bus": ("trackerkeeper.bus", "get_bus"),
+    "Settings": ("trackerkeeper.settings", "Settings"),
+    "get_settings": ("trackerkeeper.settings", "get_settings"),
+}
+
+__all__ = ["__version__", "configure", *_LAZY]
+
+
+def __getattr__(name: str):
+    target = _LAZY.get(name)
+    if target is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    return getattr(importlib.import_module(target[0]), target[1])

trackerkeeper/__main__.py

@@ -0,0 +1,3 @@
+from trackerkeeper.app import main
+
+main()

trackerkeeper/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = 'gedcf50355'

trackerkeeper/app.py

@@ -0,0 +1,445 @@
+"""trackerkeeper app entry point.
+
+``main()`` does the cross-platform Qt setup every warehaus app needs — HiDPI
+rounding, app identity, the theme-matched palette, the app icon — then shows an
+``AppWindow`` with a placeholder. Fork it: set your identity, swap the
+placeholder for your content, wire your own controllers onto ``AppBus``.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from PySide6.QtCore import Qt
+from PySide6.QtGui import QGuiApplication, QIcon
+from PySide6.QtWidgets import (
+    QApplication,
+    QHBoxLayout,
+    QLabel,
+    QPushButton,
+    QVBoxLayout,
+    QWidget,
+)
+
+from trackerkeeper import __version__, ui_helpers
+from trackerkeeper.bus import AppBus
+from trackerkeeper.platform_compat import IS_MACOS
+
+
+def _setup_hidpi() -> None:
+    """Resolution independence: pass fractional scale through untouched (Qt 6.7+
+    talks wp_fractional_scale_v1 to KWin natively) and let widgets size from the
+    scaled tokens. Must run before QApplication is constructed."""
+    os.environ.setdefault("QT_SCALE_FACTOR_ROUNDING_POLICY", "PassThrough")
+    QGuiApplication.setHighDpiScaleFactorRoundingPolicy(
+        Qt.HighDpiScaleFactorRoundingPolicy.PassThrough
+    )
+
+
+def _placeholder() -> QWidget:
+    """The blank canvas a fresh fork boots to. Replace with your content via
+    ``window.set_content(...)``."""
+    from trackerkeeper.design_tokens import (
+        BTN_PRIMARY,
+        TYPE_BODY,
+        TYPE_DISPLAY,
+        button_qss,
+        type_qss,
+    )
+
+    w = QWidget()
+    w.setStyleSheet("background: transparent;")
+    lay = QVBoxLayout(w)
+    lay.setContentsMargins(40, 40, 40, 56)
+    lay.addStretch(1)
+
+    title = QLabel("trackerkeeper")
+    title.setAlignment(Qt.AlignmentFlag.AlignCenter)
+    title.setStyleSheet(f"color: {ui_helpers.TEXT}; {type_qss(TYPE_DISPLAY)}")
+    lay.addWidget(title)
+
+    sub = QLabel("your app starts here — edit trackerkeeper/app.py")
+    sub.setAlignment(Qt.AlignmentFlag.AlignCenter)
+    sub.setStyleSheet(f"color: {ui_helpers.TEXT_DIM}; {type_qss(TYPE_BODY)}")
+    lay.addWidget(sub)
+
+    btn = QPushButton("Open Settings")
+    btn.setCursor(Qt.CursorShape.PointingHandCursor)
+    btn.setStyleSheet(button_qss(BTN_PRIMARY))
+    btn.clicked.connect(lambda: AppBus.get().show_settings.emit())
+    row = QHBoxLayout()
+    row.addStretch(1)
+    row.addWidget(btn)
+    row.addStretch(1)
+    lay.addSpacing(18)
+    lay.addLayout(row)
+
+    lay.addStretch(2)
+    return w
+
+
+# Held for the process lifetime so faulthandler's file sink isn't garbage-
+# collected / closed out from under it on GUI-subsystem builds.
+_CRASH_LOG_FH = None
+
+
+def _diag_log_dir():
+    """Best-effort writable dir for crash / diagnostic logs, resolved WITHOUT a
+    QApplication (this runs before one exists). Windows → ``%LOCALAPPDATA%\\
+    {app}``; otherwise ``$XDG_CACHE_HOME`` (or ``~/.cache``) ``/{app}`` — where
+    ``{app}`` is the configured identity slug. Returns None if nothing writable."""
+    import os as _os
+
+    from trackerkeeper import identity as _ident
+
+    try:
+        if _os.name == "nt":
+            base = _os.environ.get("LOCALAPPDATA") or _os.path.expanduser("~")
+        else:
+            base = _os.environ.get("XDG_CACHE_HOME") or _os.path.join(
+                _os.path.expanduser("~"), ".cache"
+            )
+        d = _os.path.join(base, _ident.app())
+        _os.makedirs(d, exist_ok=True)
+        return d
+    except Exception:
+        return None
+
+
+def _enable_faulthandler() -> None:
+    """Convert a hard native crash (e.g. a cross-thread ``~QObject``) into an
+    attributable Python + C stack instead of silent process death.
+
+    On a normal interpreter this writes to stderr. Under a GUI-subsystem
+    interpreter (a pipx ``.exe`` gui-script on Windows / ``pythonw``)
+    ``sys.stderr`` is ``None`` and a bare ``enable()`` raises ``RuntimeError`` —
+    which would both kill the app before ``app.exec()`` AND leave a windowed
+    build's crash with zero trace. So there we instead point faulthandler at a
+    ``crash.log`` file and attach a file log (``{app}.log``, level from
+    ``TRACKERKEEPER_LOG_LEVEL``, default INFO) the user can hand back."""
+    import faulthandler
+
+    if sys.stderr is not None:
+        try:
+            faulthandler.enable()
+        except Exception:
+            # e.g. a stderr replaced by a fileno-less stream (test capture,
+            # embedded hosts) — losing the crash hook must never be fatal.
+            pass
+        return
+
+    # stderr is None (GUI-subsystem build) — route to files instead.
+    d = _diag_log_dir()
+    if not d:
+        return
+    import os as _os
+
+    global _CRASH_LOG_FH
+    try:
+        _CRASH_LOG_FH = open(_os.path.join(d, "crash.log"), "a", buffering=1)
+        faulthandler.enable(file=_CRASH_LOG_FH, all_threads=True)
+    except Exception:
+        pass
+    try:
+        import logging as _logging
+
+        from trackerkeeper import identity as _ident
+
+        level = (_os.environ.get("TRACKERKEEPER_LOG_LEVEL") or "INFO").upper()
+        fh = _logging.FileHandler(_os.path.join(d, f"{_ident.app()}.log"))
+        fh.setFormatter(
+            _logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s")
+        )
+        root = _logging.getLogger()
+        root.addHandler(fh)
+        root.setLevel(getattr(_logging, level, _logging.INFO))
+    except Exception:
+        pass
+
+
+def _reconcile_autostart() -> None:
+    """Re-assert an ENABLED launch-on-login entry at boot. ``enable()`` rewrites
+    the OS entry (XDG .desktop / Run key / LaunchAgent), self-healing a stale
+    ``Exec``/command after the executable or venv moved. Strictly opt-in: trackerkeeper
+    never turns autostart ON — only the Settings toggle does; if it's off or
+    unsupported this is a no-op. Best-effort, never fatal."""
+    try:
+        from trackerkeeper import autostart
+
+        if autostart.is_supported() and autostart.is_enabled():
+            autostart.enable()
+    except Exception:
+        pass
+
+
+def _wire_notifications(bus) -> None:
+    """Route ``AppBus.notify`` (title, body) to the desktop-notification
+    backend. App code emits the signal from its real events with zero imports;
+    ``trackerkeeper.notifications`` no-ops where unsupported and never raises."""
+
+    def _notify(title: str, body: str = "") -> None:
+        try:
+            from trackerkeeper import notifications
+
+            notifications.notify(title, body)
+        except Exception:
+            pass
+
+    bus.notify.connect(_notify)
+
+
+def run_app(content_factory, *, identity=None, single_instance=True) -> int:
+    """Boot a trackerkeeper app and run it to exit. Does the cross-platform Qt setup
+    every warehaus app needs — HiDPI rounding, app identity, persisted theme
+    overrides, the theme-matched palette + icon — then shows an ``AppWindow``
+    whose content is ``content_factory(window)``. Returns the process exit code.
+
+    Wires the chrome an app shouldn't re-solve, all unconditionally:
+      * **single instance** — a second launch raises the running window instead
+        of opening a duplicate (pass ``single_instance=False`` to opt out);
+      * **persisted theme** — accent / colour overrides load BEFORE the first
+        widget so every surface stamps from the saved palette;
+      * **the settings dialog** — wired to ``AppBus.show_settings``;
+      * **window geometry** — restored on launch, saved on quit;
+      * **launch on login** — re-asserts a user-enabled autostart entry (the
+        Settings toggle turns it on; trackerkeeper never does);
+      * **desktop notifications** — ``AppBus.notify.emit(title, body)`` reaches
+        the OS notification backend (silent no-op where unsupported);
+      * **translations** — ``trackerkeeper.i18n`` installs the catalog for the user's
+        language (Settings override → system locale) before any widget exists.
+
+    ``identity`` (optional) is a mapping forwarded to :func:`trackerkeeper.configure`
+    (``org`` / ``app`` / ``display_name``). NOTE: for the import-time font scale
+    to honour a custom identity, set it in ``trackerkeeper.identity`` or call
+    ``configure()`` BEFORE importing the app; Qt names, the AUMID, and QSettings
+    all honour it here regardless.
+    """
+    from trackerkeeper import identity as ident
+
+    if identity:
+        ident.configure(**identity)
+
+    # Crash/diagnostic logging first, so a native SIGSEGV during boot is still
+    # attributable (writes to files under a GUI-subsystem interpreter where
+    # stderr is None). Best-effort; never fatal.
+    _enable_faulthandler()
+
+    _setup_hidpi()
+    try:
+        from trackerkeeper.windows_shortcut import set_process_app_user_model_id
+
+        set_process_app_user_model_id()
+    except Exception:
+        pass
+
+    # macOS: set the application-menu name BEFORE QApplication builds the
+    # native menu, so a from-source run reads the app name rather than "Python"
+    # (a frozen .app already gets it from CFBundleName). Only ordering
+    # constraint here. No-op off macOS.
+    if IS_MACOS:
+        from trackerkeeper import macos_menubar
+
+        macos_menubar.set_app_name()
+
+    app = QApplication.instance() or QApplication(sys.argv)
+    app.setApplicationName(ident.app())
+    app.setApplicationDisplayName(ident.display_name())
+    app.setOrganizationName(ident.org())
+    app.setApplicationVersion(__version__)
+    # The installed .desktop is named by the reverse-DNS app-id
+    # (io.github.{owner}.{app}), so the desktop file name must carry
+    # desktop_id() for the taskbar to associate the window with its installed
+    # icon. Verified live (KDE, 2026-07-03): on Wayland this value becomes the
+    # window's app_id; on X11 Qt exports it as _KDE_NET_WM_DESKTOP_FILE (KDE's
+    # association path) while WM_CLASS stays the bare applicationName slug —
+    # which is why the .desktop's StartupWMClass keeps the slug (non-KDE X11
+    # matches on WM_CLASS). The KWin machinery survives the app_id change by
+    # design: the noborder rule and the drag_repaint effect both match the
+    # bare slug as a SUBSTRING (proven: noBorder=true under the new app_id).
+    app.setDesktopFileName(ident.desktop_id())
+
+    # Structured file logging (trackerkeeper.log): rotating file under the app state
+    # dir + a WARNING console handler, level from TRACKERKEEPER_LOG. Installed HERE —
+    # after the Qt identity names, so AppDataLocation resolves per-app; before
+    # everything else, so the whole boot is captured. Best-effort, never fatal.
+    try:
+        from trackerkeeper import log as _log
+
+        _log.install()
+    except Exception:
+        pass
+
+    # Versioned settings migrations — run BEFORE Settings (or anything that
+    # reads the store: i18n's language override, the persisted theme) is first
+    # read, so every accessor sees the post-migration key layout.
+    try:
+        from trackerkeeper import settings_migration
+
+        settings_migration.migrate()
+    except Exception:
+        pass
+
+    # Install translation catalogs (Settings override → system locale) before
+    # ANY widget is built — Qt translates at construction time. Never raises;
+    # a missing catalog just leaves the English source strings.
+    from trackerkeeper import i18n as _i18n
+
+    _i18n.install(app)
+
+    # Single instance: hand off to the already-running copy rather than opening
+    # a second window. Keep the lock object alive for the process lifetime.
+    si = None
+    if single_instance:
+        from trackerkeeper.single_instance import SingleInstance
+
+        si = SingleInstance(ident.app())
+        # Forward this launch's argv (file paths / URLs) so the running copy
+        # opens them — the "double-click a document while the app is open" path.
+        if not si.acquire(sys.argv[1:]):
+            return 0  # another instance was found and signalled to come forward
+        app._dough_single_instance = si
+        # Re-emit forwarded files on the bus so app code binds with zero refs.
+        si.files_received.connect(
+            lambda paths: AppBus.get().files_received.emit(list(paths))
+        )
+
+    # Persisted accent / colour overrides must load BEFORE the first widget, so
+    # every surface stamps from the saved palette rather than the defaults.
+    from trackerkeeper.color_tokens import load_persisted_overrides
+
+    load_persisted_overrides()
+
+    from trackerkeeper.ui_helpers import apply_app_palette, make_app_icon
+
+    app.setWindowIcon(QIcon(make_app_icon(64)))
+    apply_app_palette()
+
+    from trackerkeeper.settings import get_settings
+    from trackerkeeper.window import AppWindow
+
+    win = AppWindow(title=ident.display_name())
+    # Record whether a saved size was restored: content that wants its own
+    # default size (a utility window) checks this so it never overrides a size
+    # the user chose.
+    win._geometry_restored = get_settings().restore_geometry(win)
+    win.set_content(content_factory(win))
+
+    def _open_settings():
+        from trackerkeeper.settings_dialog import SettingsDialog
+
+        SettingsDialog(win).exec()
+
+    AppBus.get().show_settings.connect(_open_settings)
+
+    from trackerkeeper.single_instance import force_foreground
+
+    if si is not None:
+        si.raise_requested.connect(lambda: force_foreground(win))
+    AppBus.get().open_main_window.connect(lambda: force_foreground(win))
+
+    # Persist any pending QSettings writes (window geometry, theme overrides, …)
+    # before the process exits. A hard quit that skips the window's closeEvent
+    # (e.g. app.quit() from a tray/menu) still reaches aboutToQuit — without
+    # this the most recent toggles are silently lost on the next launch.
+    def _flush_settings():
+        try:
+            get_settings().flush()
+        except Exception:
+            pass
+
+    app.aboutToQuit.connect(_flush_settings)
+
+    # Launch-on-login + desktop notifications — the shipped subsystems, wired:
+    # autostart re-asserts an entry the user enabled (Settings toggle) so it
+    # survives a moved executable; AppBus.notify(title, body) reaches the OS
+    # notification backend. Both opt-in and best-effort.
+    _reconcile_autostart()
+    _wire_notifications(AppBus.get())
+
+    # macOS: the global menu bar (App/File/Edit/View/Window/Help) + native
+    # window chrome (transparent titlebar / full-size content view) — native
+    # conventions a Qt app otherwise lacks. Pure PySide6; only built on macOS,
+    # best-effort/no-op elsewhere.
+    if IS_MACOS:
+        from trackerkeeper import macos_menubar, macos_window
+
+        macos_menubar.install(win)
+        macos_window.apply(win)
+
+    # KDE Wayland borderless chrome: the main window stays server-side-decorated
+    # (so compositor blur survives a drag — a Qt-frameless window loses it) and a
+    # KWin `noborder` Force rule strips the visible decoration. Reconcile it
+    # BEFORE show so a fresh launch never flashes a titlebar; idempotent +
+    # self-healing, a no-op off KDE Wayland. `native_window_border` opts back into
+    # the real server-side titlebar.
+    from trackerkeeper import noborder
+
+    if get_settings().native_window_border:
+        noborder.remove_main_window_noborder()
+    else:
+        noborder.install_main_window_noborder()
+
+    # Follow the desktop accent colour if the user enabled it: apply it now
+    # (launch re-read) and watch the OS for live changes (XDG portal / DWM
+    # message / AppKit notification). Best-effort — a DE without the portal
+    # simply never fires. Pinned on `win` so the watcher lives with the window.
+    try:
+        from trackerkeeper.system_accent import SystemAccentFollower
+
+        win._accent_follower = SystemAccentFollower(win)
+        win._accent_follower.start()
+    except Exception:
+        pass
+
+    win.show()
+
+    # KWin drag-repaint effect — installed AFTER show (off the first-paint path;
+    # it only matters once a drag begins). Forces KWin's full-repaint render path
+    # while one of the app's windows is dragged, killing the NVIDIA-EGL stale-blur
+    # "line artifact" (KWin bug 455526/457727). Idempotent, best-effort, a no-op
+    # off KDE Wayland; TRACKERKEEPER_NO_DRAG_REPAINT=1 removes it instead.
+    from trackerkeeper import drag_repaint
+
+    drag_repaint.sync()
+
+    # Agent test bridge — dev-only remote control for live end-to-end testing.
+    # OFF unless TRACKERKEEPER_TEST_BRIDGE=1 is set at launch. Stands up a per-user
+    # local socket whose JSON commands (click / tree / screenshot / settings /
+    # eval …) run on the GUI thread, so an agent can drive the real app
+    # deterministically — including on Wayland, where synthetic OS input is
+    # unreliable. Never enabled in a shipped build. See trackerkeeper/test_bridge.py
+    # + docs/TEST_BRIDGE.md.
+    if os.environ.get("TRACKERKEEPER_TEST_BRIDGE") == "1":
+        from trackerkeeper.test_bridge import TestBridge
+
+        app._dough_test_bridge = TestBridge(app, win)
+        app._dough_test_bridge.start()
+
+    # Daily update check — deferred a few seconds off the first-paint path.
+    # Gated inside maybe_check(): the Settings toggle, the once-a-day throttle,
+    # and the channel rule (Store / MAS / AUR builds never nag). Best-effort.
+    def _check_updates():
+        try:
+            from trackerkeeper import updates
+
+            updates.maybe_check()
+        except Exception:
+            pass
+
+    from PySide6.QtCore import QTimer
+
+    QTimer.singleShot(3000, _check_updates)
+
+    return app.exec()
+
+
+def main() -> None:
+    """The default entry: boot tracker keeper with the update dashboard."""
+    from trackerkeeper.dashboard import build_content
+
+    sys.exit(run_app(build_content))
+
+
+if __name__ == "__main__":
+    main()

trackerkeeper/assets/__init__.py

@@ -0,0 +1,2 @@
+# Package marker so importlib.resources.files("trackerkeeper.assets") resolves the
+# bundled brand SVG in a built/installed wheel.

trackerkeeper/assets/trackerkeeper.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <defs>
+    <linearGradient id="dg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#9D8AE8"/>
+      <stop offset="1" stop-color="#7C66D0"/>
+    </linearGradient>
+  </defs>
+  <!-- a soft trackerkeeper blob -->
+  <path d="M32 7c15 0 25 8.5 25 22.5C57 46 46 57 32 57S7 46 7 29.5C7 15.5 17 7 32 7z"
+        fill="url(#dg)"/>
+  <ellipse cx="23" cy="23" rx="7" ry="4.5" fill="#ffffff" opacity="0.22"/>
+</svg>