Metadata-Version: 2.4
Name: trackerkeeper
Version: 0.1.1
Summary: One dashboard for software & firmware updates across everything you own
Author-email: august <augustvontrips@gmail.com>
License: GPL-2.0-or-later
Project-URL: Homepage, https://github.com/wolfgangwarehaus/trackerkeeper
Project-URL: Repository, https://github.com/wolfgangwarehaus/trackerkeeper
Keywords: pyside6,qt,desktop,starter,template,frosted-glass,cross-platform,kde,windows
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6<7.0,>=6.6.0
Provides-Extra: bake
Requires-Dist: jinja2>=3; extra == "bake"
Provides-Extra: terminal
Requires-Dist: pyte>=0.8; extra == "terminal"
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: setuptools-scm>=8; extra == "dev"
Requires-Dist: jinja2>=3; extra == "dev"
Requires-Dist: pyte>=0.8; extra == "dev"
Requires-Dist: keyring>=24; extra == "dev"
Requires-Dist: cryptography>=42; sys_platform != "win32" and extra == "dev"
Provides-Extra: credentials
Requires-Dist: keyring>=24; extra == "credentials"
Requires-Dist: cryptography>=42; sys_platform != "win32" and extra == "credentials"
Provides-Extra: macos
Requires-Dist: pyobjc-core>=10.0; sys_platform == "darwin" and extra == "macos"
Requires-Dist: pyobjc-framework-Cocoa>=10.0; sys_platform == "darwin" and extra == "macos"
Requires-Dist: pyobjc-framework-UserNotifications>=10.0; sys_platform == "darwin" and extra == "macos"
Requires-Dist: pyobjc-framework-ServiceManagement>=10.0; sys_platform == "darwin" and extra == "macos"
Dynamic: license-file

<h1 align="center">trackerkeeper</h1>

<p align="center">
  A frosted, cross-platform <a href="https://doc.qt.io/qtforpython/">PySide6</a>
  app base — the shared starter every wolfgang warehaus app is baked from.
</p>

trackerkeeper is a **fork-and-own starter**, not a dependency. Clone it, rename it,
delete what you don't need, and build. It solves the cross-platform window
chrome, the design system, and the platform scaffolding *once* — so a new app
is mostly its own idea plus a thin layer on top.

It boots to a themed, frosted, frameless window with a live Settings dialog —
a blank canvas with the hard parts already done. See
[`docs/PHILOSOPHY.md`](docs/PHILOSOPHY.md) for the why.

## What you get

- **`AppWindow`** — a frosted, frameless main window that's borderless on KDE
  Wayland and Windows (with the native-frame smooth-resize fix), shapes
  compositor blur to a rounded self-painted body, and falls back to a
  near-opaque panel where blur isn't available (never see-through).
- **Design system** — a three-family theme (frosted dark/light + solid), accent
  presets with WCAG-safe glyph contrast, scalable typography tiers, a 4-based
  spacing/radius scale. Live theme + accent switching, OS-following auto mode.
- **Widget kit** — `FrostedDialog`, the `Selector` dropdown, `IconButton` with
  crisp HiDPI icons, keyboard-nav helpers, a top bar that doubles as the titlebar.
- **Cross-platform scaffolding** — `platform_compat`, threaded `async_io`, the
  per-platform backend pattern (autostart / notifications / power), a minimal
  `AppBus` signal bus, slim persistent `Settings`, single-instance.
- **HiDPI done right** — PassThrough fractional scaling + device-pixel snapping.
- **Languages for free** — Qt translation catalogs wired at boot, plural-aware
  strings, locale-safe number/date/duration formatting (`trackerkeeper.i18n.fmt`),
  RTL-mirrored chrome. See `docs/TRANSLATING.md`.
- **Accessible by default** — every kit control announces to screen readers
  (a test fails the build on unnamed ones), visible keyboard-focus states, a
  keyboard path for every mouse path. See `docs/ACCESSIBILITY.md`.
- **Structured logging** — an opt-in rotating file log (~1 MB × 3) in the app's
  state dir, console noise capped at WARNING, `TRACKERKEEPER_LOG=debug` to turn it up.
- **Settings migrations** — a versioned run-once migration runner
  (`meta/schema_version`), so a renamed key never strands an installed user.
- **Credentials store** — `save_secret`/`load_secret`: OS keyring first, an
  encrypted per-machine blob (AES-GCM, or DPAPI on Windows) as the fallback —
  plaintext never touches disk.
- **Second-launch file forwarding** — double-click a document while the app is
  open and the running instance raises + receives it (`AppBus.files_received`).
- **Update chip** — a quiet daily GitHub release check with a dismissable
  Download / What's-new pill in the top bar; store/AUR builds stay silent.
- **Diagnostics bundle** — a "Copy diagnostics" button that snapshots versions,
  platform, theme/blur state, settings (secrets excluded), and the log tail.

## Quick start

```bash
git clone https://github.com/wolfgangwarehaus/trackerkeeper.git
cd trackerkeeper
pip install -e .
python -m trackerkeeper          # or: trackerkeeper  (the console script)
```

Runs straight from a checkout — the flat layout means no install is strictly
required (`python -m trackerkeeper`).

## Make it yours

1. **Rename the package + set your identity.** Rename the `trackerkeeper/` package to your
   app, then set your identity in **one** place — `trackerkeeper/identity.py` (`org`, `app`,
   `display_name`). It's the single source the QSettings handle, the Qt app/org
   names, the window title, and the Windows AUMID all read. (Or, for programmatic
   control, call `trackerkeeper.configure(org=…, app=…, display_name=…)` once, before
   importing the app — the font-scale loader reads identity at import time.)
2. **Boot your content.** Call `trackerkeeper.run_app(lambda window: YourWidget(window))`
   — it does the full cross-platform boot (identity, blur, HiDPI, single-instance,
   persisted theme, window geometry, the settings dialog) and shows your content.
   (Or, for the quickest start, just edit `trackerkeeper/app.py::_placeholder`.)
3. **Extend the bus.** Add your app's signals by subclassing `AppBus`
   (`trackerkeeper/bus.py`); the base stays minimal.
4. **Keep it light.** Heavy/native deps (a PDF engine, mpv, …) go in
   `[project.optional-dependencies]`, never the PySide6-only core.

## Layout

```
trackerkeeper/
  app.py          # main() + the placeholder you replace
  window.py       # AppWindow — the frosted cross-platform chrome
  top_bar.py      # the titlebar / top bar
  settings_dialog.py
  bus.py          # AppBus (signal bus)
  settings.py     # slim QSettings wrapper
  theme.py  design_tokens.py  color_tokens.py  ui_helpers.py   # the design system
  blur/  win_frameless.py  frosted_dialog.py  selector.py  icon_button.py  icons.py
  autostart/  notifications/  power/   # per-platform backend pattern
docs/PHILOSOPHY.md
```

## License

GPL-2.0-or-later (matching the warehaus family). It's a starter you own — feel
free to relicense your fork.
