trackerkeeper 0.1.0__py3-none-any.whl

trackerkeeper/autostart/_msix.py

@@ -0,0 +1,181 @@
+"""Windows MSIX (packaged-app) launch-on-login backend.
+
+Packaged apps can't use the per-user Run key — Windows ignores Run-key
+entries from packages. Autostart for a packaged app is a *startup task*
+declared in the manifest (``windows.startupTask`` with
+``TaskId="<app>Startup"``) and toggled at runtime through the
+``Windows.ApplicationModel.StartupTask`` WinRT API. The user can always
+override us from Settings -> Apps -> Startup; once they disable it there,
+Windows forbids programmatic re-enable (state ``DisabledByUser``).
+
+Mirrors the public backend API (``is_supported``/``is_enabled``/``enable``/
+``disable``). Every call is defensively wrapped: a WinRT/projection failure
+degrades to "unsupported" instead of raising, so a packaging quirk can never
+crash startup.
+
+Threading — why every call hops to a worker thread:
+``StartupTask``'s API is asynchronous, and the only synchronous way to consume
+an ``IAsyncOperation`` is its blocking ``.get()`` — which WinRT forbids on a
+single-threaded apartment. The Qt GUI thread is an STA (Qt and ``comtypes``
+initialise it that way), so calling ``.get()`` there raises ``RuntimeError:
+Cannot call blocking method from single-threaded apartment`` (observed
+in-package 2026-06-18). Each WinRT touch therefore runs on a short-lived thread
+initialised ``MULTI_THREADED`` (an MTA), where the blocking wait is legal; only
+a plain ``bool`` crosses back to the GUI thread. (Synchronous WinRT calls are
+fine on the STA; only the blocking await is not.) ``_TASK_ID`` must match
+``AppxManifest.xml`` exactly.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from trackerkeeper import identity
+
+logger = logging.getLogger(__name__)
+
+# Must match the <desktop:StartupTask TaskId="..."> in AppxManifest.xml.
+_TASK_ID = f"{identity.app()}Startup"
+
+
+def _run_in_mta(fn):
+    """Run ``fn`` on a dedicated MTA thread and return its result (or None).
+
+    WinRT's blocking ``IAsyncOperation.get()`` cannot run on the Qt GUI thread
+    (an STA). A fresh thread initialised ``MULTI_THREADED`` runs the blocking
+    waits legally; it is discarded after the call, so the apartment lifecycle
+    stays clean and the rare autostart toggles never touch a shared pool. Any
+    failure (no winrt, apartment init refused, projection error) degrades to
+    ``None`` so the public API can never raise.
+    """
+    import threading
+
+    box = {}
+
+    def _target():
+        try:
+            from winrt.runtime import (
+                ApartmentType,
+                init_apartment,
+                uninit_apartment,
+            )
+        except Exception as e:  # pragma: no cover — Windows/MSIX-only
+            logger.debug("winrt apartment API unavailable: %s", e)
+            return
+        try:
+            init_apartment(ApartmentType.MULTI_THREADED)
+        except Exception as e:  # pragma: no cover — Windows/MSIX-only
+            logger.debug("init_apartment(MTA) failed: %s", e)
+            return
+        try:
+            box["result"] = fn()
+        except Exception as e:  # pragma: no cover — Windows/MSIX-only
+            logger.debug("StartupTask worker call failed: %s", e)
+        finally:
+            try:
+                uninit_apartment()
+            except Exception:  # pragma: no cover — Windows/MSIX-only
+                pass
+
+    # Sanctioned raw-thread exception: the WinRT call needs its own COM MTA
+    # apartment, so it gets a dedicated thread (start + join), not a pool slot.
+    t = threading.Thread(target=_target, name="trackerkeeper-startuptask", daemon=True)
+    t.start()
+    t.join()
+    return box.get("result")
+
+
+def _resolve(op):
+    """Block on a WinRT IAsyncOperation. Legal only off the GUI STA — callers
+    reach it through ``_run_in_mta``. The projection exposes ``.get()`` for
+    synchronous callers; fall back to asyncio if a build only awaits."""
+    get = getattr(op, "get", None)
+    if callable(get):
+        return get()
+    import asyncio
+
+    return asyncio.run(op)  # pragma: no cover — projection-dependent
+
+
+def _get_task():
+    """Our StartupTask, or None if the API/projection is unavailable.
+    MUST run inside ``_run_in_mta`` — it performs the blocking WinRT wait."""
+    try:
+        from winrt.windows.applicationmodel import StartupTask
+
+        return _resolve(StartupTask.get_async(_TASK_ID))
+    except Exception as e:  # pragma: no cover — Windows/MSIX-only
+        logger.debug("StartupTask.get_async(%s) failed: %s", _TASK_ID, e)
+        return None
+
+
+def _is_enabled_state(state) -> bool:
+    try:
+        from winrt.windows.applicationmodel import StartupTaskState
+
+        return state in (StartupTaskState.ENABLED, StartupTaskState.ENABLED_BY_POLICY)
+    except Exception:  # pragma: no cover — Windows/MSIX-only
+        return False
+
+
+# ── Worker-thread implementations (each runs inside an MTA via _run_in_mta) ──
+
+
+def _is_supported_impl() -> bool:
+    return _get_task() is not None
+
+
+def _is_enabled_impl() -> bool:
+    task = _get_task()
+    if task is None:
+        return False
+    try:
+        return _is_enabled_state(task.state)
+    except Exception as e:  # pragma: no cover — Windows/MSIX-only
+        logger.debug("StartupTask state read failed: %s", e)
+        return False
+
+
+def _enable_impl() -> bool:
+    task = _get_task()
+    if task is None:
+        return False
+    try:
+        return _is_enabled_state(_resolve(task.request_enable_async()))
+    except Exception as e:  # pragma: no cover — Windows/MSIX-only
+        logger.debug("StartupTask request_enable failed: %s", e)
+        return False
+
+
+def _disable_impl() -> bool:
+    task = _get_task()
+    if task is None:
+        return False
+    try:
+        task.disable()
+        return True
+    except Exception as e:  # pragma: no cover — Windows/MSIX-only
+        logger.debug("StartupTask disable failed: %s", e)
+        return False
+
+
+# ── Public API — mirrors the platform-agnostic backend contract ─────────────
+
+
+def is_supported() -> bool:
+    return bool(_run_in_mta(_is_supported_impl))
+
+
+def is_enabled() -> bool:
+    return bool(_run_in_mta(_is_enabled_impl))
+
+
+def enable() -> bool:
+    """Request enable. Returns True only if Windows actually enabled it — a
+    user who turned it off in Settings (DisabledByUser) blocks us, and the
+    caller should point them at Settings -> Apps -> Startup."""
+    return bool(_run_in_mta(_enable_impl))
+
+
+def disable() -> bool:
+    return bool(_run_in_mta(_disable_impl))

trackerkeeper/autostart/_unsupported.py

@@ -0,0 +1,22 @@
+"""Stub autostart backend for platforms with no launch-on-login mechanism
+(Linux, Windows, and macOS each have a real backend). Every call returns
+False so the settings UI can hide the toggle and call sites no-op cleanly.
+"""
+
+from __future__ import annotations
+
+
+def is_supported() -> bool:
+    return False
+
+
+def is_enabled() -> bool:
+    return False
+
+
+def enable() -> bool:
+    return False
+
+
+def disable() -> bool:
+    return False

trackerkeeper/autostart/_windows.py

@@ -0,0 +1,96 @@
+"""Windows launch-on-login backend. Manages a value under the per-user
+Run key (``HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run``) —
+no elevation needed, honored by Explorer at login, and surfaced to the
+user in Task Manager's Startup tab and Settings → Apps → Startup.
+
+The command targets the gui-script launcher exe when one exists (pip /
+pipx install) so login launches without a console window. A source
+checkout falls back to ``pythonw.exe -m <app>`` (then plain
+``python.exe`` if pythonw is missing).
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+from trackerkeeper import identity
+
+try:
+    import winreg
+except ImportError:  # pragma: no cover — non-Windows; tests patch this attr
+    winreg = None  # type: ignore[assignment]
+
+logger = logging.getLogger(__name__)
+
+_RUN_KEY = r"Software\Microsoft\Windows\CurrentVersion\Run"
+_VALUE_NAME = identity.app()
+
+
+def _launch_command() -> str:
+    """The command line to register: the launcher exe if we have one,
+    else a ``-m <app>`` invocation, preferring pythonw so a login
+    launch doesn't flash a console."""
+    from trackerkeeper.windows_shortcut import _launcher_exe
+
+    exe = _launcher_exe()
+    if exe is not None:
+        return f'"{exe}"'
+    interp = Path(sys.executable or "python")
+    pythonw = interp.with_name("pythonw.exe")
+    if pythonw.is_file():
+        interp = pythonw
+    return f'"{interp}" -m {identity.app()}'
+
+
+def is_supported() -> bool:
+    return winreg is not None
+
+
+def is_enabled() -> bool:
+    if winreg is None:
+        return False
+    try:
+        with winreg.OpenKey(
+            winreg.HKEY_CURRENT_USER, _RUN_KEY, 0, winreg.KEY_READ
+        ) as key:
+            value, _kind = winreg.QueryValueEx(key, _VALUE_NAME)
+        return bool(value)
+    except FileNotFoundError:
+        return False
+    except Exception as e:
+        logger.debug("autostart is_enabled read failed: %s", e)
+        return False
+
+
+def enable() -> bool:
+    if winreg is None:
+        return False
+    try:
+        with winreg.CreateKeyEx(
+            winreg.HKEY_CURRENT_USER, _RUN_KEY, 0, winreg.KEY_SET_VALUE
+        ) as key:
+            winreg.SetValueEx(key, _VALUE_NAME, 0, winreg.REG_SZ, _launch_command())
+        return True
+    except Exception as e:
+        logger.debug("autostart enable failed: %s", e)
+        return False
+
+
+def disable() -> bool:
+    """Remove the Run-key value. Returns True if a value was removed,
+    False if there was nothing to do (or removal failed)."""
+    if winreg is None:
+        return False
+    try:
+        with winreg.OpenKey(
+            winreg.HKEY_CURRENT_USER, _RUN_KEY, 0, winreg.KEY_SET_VALUE
+        ) as key:
+            winreg.DeleteValue(key, _VALUE_NAME)
+        return True
+    except FileNotFoundError:
+        return False
+    except Exception as e:
+        logger.debug("autostart disable failed: %s", e)
+        return False

trackerkeeper/bake.py

@@ -0,0 +1,217 @@
+"""``trackerkeeper bake`` — render the packaging tree from the one metadata source.
+
+The oven half of the baking phase (docs/BAKING.md §2): walk
+``packaging/templates/**/*.j2``, render each template's BODY *and its filename*
+(filenames carry ``{{ app_id_base }}`` etc.) from :func:`trackerkeeper.metadata.context`,
+and write the result under ``packaging/``. None of the manifests is hand-authored.
+
+The verify half is :func:`check`: re-render into memory and diff against the
+committed files — reporting a hand-edit, a stale render, a missing file, AND an
+orphan (a committed file no template produces). A CI gate (``trackerkeeper bake --check``,
+mirrored by ``tests/test_bake.py``) fails the build on any drift. jellytoast
+*lints* its manifests after the fact; trackerkeeper regenerates and proves nothing drifted.
+
+Jinja2 is a build-time-only dependency (the ``bake`` extra) — the shipped app
+never imports it. ``StrictUndefined`` makes a template that references a missing
+context key a hard error, so a template/metadata mismatch fails loudly at render.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import os
+import re
+import stat
+import sys
+from pathlib import Path
+
+from trackerkeeper import metadata
+
+TEMPLATES_SUBDIR = "templates"
+
+
+class BakeError(RuntimeError):
+    """A render/verify failure (missing engine, colliding outputs, …)."""
+
+
+def _repo_root() -> Path:
+    """The repo root — the dir holding pyproject.toml (and packaging/)."""
+    return metadata._find_pyproject().parent
+
+
+def _environment(templates_dir: Path):
+    try:
+        from jinja2 import Environment, FileSystemLoader, StrictUndefined
+    except ImportError as exc:  # pragma: no cover — exercised only without the extra
+        raise BakeError(
+            "trackerkeeper bake needs Jinja2 — install the bake extra: pip install 'trackerkeeper[bake]'"
+        ) from exc
+    return Environment(
+        loader=FileSystemLoader(str(templates_dir)),
+        undefined=StrictUndefined,  # a missing context key is a hard error
+        keep_trailing_newline=True,
+        trim_blocks=True,
+        lstrip_blocks=True,
+        autoescape=False,  # shell / desktop / XML — escape per-field with |e
+    )
+
+
+def _committed_files(packaging_dir: Path) -> list[Path]:
+    """Every committed (non-source) file under ``packaging/`` — skips the
+    ``templates/`` sources and any stray ``__pycache__``."""
+    out: list[Path] = []
+    for path in sorted(packaging_dir.rglob("*")):
+        if not path.is_file():
+            continue
+        parts = path.relative_to(packaging_dir).parts
+        if TEMPLATES_SUBDIR in parts or "__pycache__" in parts:
+            continue
+        out.append(path)
+    return out
+
+
+def render(packaging_dir: Path, ctx: dict | None = None) -> dict[str, str]:
+    """Render every ``*.j2`` under ``<packaging>/templates`` and return
+    ``{output_relpath: rendered_text}`` — the output path has the rendered
+    filename (``{{ app_id_base }}`` resolved) with the ``.j2`` suffix dropped.
+    Keys are POSIX relpaths on every OS. Raises :class:`BakeError` if two
+    templates resolve to the same output path (one would silently shadow the
+    other)."""
+    ctx = metadata.context() if ctx is None else ctx
+    templates_dir = packaging_dir / TEMPLATES_SUBDIR
+    env = _environment(templates_dir)
+    out: dict[str, str] = {}
+    for tpl in sorted(templates_dir.rglob("*.j2")):
+        rel = tpl.relative_to(templates_dir)
+        out_rel = env.from_string(rel.with_suffix("").as_posix()).render(**ctx)  # render the path too
+        if out_rel in out:
+            raise BakeError(f"two templates render to the same output path: {out_rel}")
+        out[out_rel] = env.get_template(rel.as_posix()).render(**ctx)
+    return out
+
+
+def write(packaging_dir: Path, ctx: dict | None = None) -> dict[str, str]:
+    """Render and write the tree under ``packaging_dir``. Writes LF newlines on
+    every OS (committed files are LF; shell scripts break with CRLF) and gives
+    ``.sh`` outputs the executable bit. Returns the rendered map."""
+    rendered = render(packaging_dir, ctx)
+    for rel, body in rendered.items():
+        dest = packaging_dir / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(body, encoding="utf-8", newline="\n")  # never CRLF
+        # Exec bits are POSIX semantics — on Windows chmod can't grant X and
+        # the bit isn't meaningful; the scripts run on Linux/macOS anyway.
+        if dest.suffix == ".sh" and os.name == "posix":
+            dest.chmod(dest.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return rendered
+
+
+def check(packaging_dir: Path, ctx: dict | None = None) -> list[str]:
+    """Return a list of drift descriptions (empty ⇒ in sync). Catches: a missing
+    file, a content/byte difference (CRLF included — compared as bytes), a ``.sh``
+    that lost its executable bit, and an ORPHAN (a committed file no template
+    produces)."""
+    rendered = render(packaging_dir, ctx)
+    drift: list[str] = []
+    for rel, body in rendered.items():
+        dest = packaging_dir / rel
+        if not dest.is_file():
+            drift.append(f"missing (run `trackerkeeper bake`): {rel}")
+            continue
+        if dest.read_bytes() != body.encode("utf-8"):
+            drift.append(f"drift (re-run `trackerkeeper bake`): {rel}")
+        elif (
+            dest.suffix == ".sh"
+            and os.name == "posix"  # exec bits don't exist on Windows
+            and not (dest.stat().st_mode & stat.S_IXUSR)
+        ):
+            drift.append(f"not executable (re-run `trackerkeeper bake`): {rel}")
+    produced = set(rendered)
+    for path in _committed_files(packaging_dir):
+        rel = path.relative_to(packaging_dir).as_posix()
+        if rel not in produced:
+            drift.append(f"orphan (delete it, or add a template): {rel}")
+    return drift
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="trackerkeeper-bake",
+        description="Render the packaging tree from [tool.trackerkeeper.metadata] (docs/BAKING.md §2).",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="verify committed files match a fresh render; exit 1 on drift (the CI gate)",
+    )
+    parser.add_argument(
+        "--packaging",
+        type=Path,
+        default=None,
+        help="packaging dir (default: <repo>/packaging)",
+    )
+    parser.add_argument(
+        "--release-version",
+        default=None,
+        metavar="VER",
+        help="inject a <release> entry into version-bearing manifests — the "
+        "release-time render (docs/BAKING.md §6.2). Omit for the committed, "
+        "version-free tree.",
+    )
+    parser.add_argument(
+        "--release-date",
+        default=None,
+        metavar="YYYY-MM-DD",
+        help="date for the injected <release> (defaults to empty)",
+    )
+    args = parser.parse_args(argv)
+    if args.release_date and not args.release_version:
+        parser.error("--release-date has no effect without --release-version")
+    if args.release_version and args.packaging is None:
+        # A release render injects a <release> the COMMITTED tree must never carry
+        # (docs/BAKING.md §6.2) — writing it in-place would dirty packaging/ and
+        # break `trackerkeeper bake --check`. Force an explicit target (CI renders into
+        # packaging/ in its ephemeral checkout via --packaging packaging).
+        parser.error(
+            "--release-version would overwrite the committed packaging tree; pass an "
+            "explicit --packaging <dir> (the committed tree must stay version-free)"
+        )
+    packaging_dir = args.packaging or (_repo_root() / "packaging")
+
+    # Release-time render: fold the version into the context so the metainfo gets
+    # a <release>. --check stays version-free (it gates the committed tree). A date
+    # is ALWAYS set (AppStream rejects a <release> with an empty date).
+    ctx = None
+    if args.release_version:
+        ctx = metadata.context()
+        ctx["release_version"] = args.release_version
+        ctx["release_date"] = (
+            args.release_date or datetime.datetime.now(datetime.timezone.utc).date().isoformat()
+        )
+        # The Windows VSVersionInfo filevers must be 4 INTEGERS. Take each dotted
+        # segment's leading digit run so a PEP 440 pre-release (0.1.0rc1) yields
+        # (0, 1, 0, 0) — not a bare 0rc1 that breaks the eval'd version file.
+        _segs = (args.release_version.split("+")[0].split(".") + ["0", "0", "0", "0"])[:4]
+        ctx["filevers"] = tuple(int(re.match(r"\d*", s).group() or "0") for s in _segs)
+
+    try:
+        if args.check:
+            drift = check(packaging_dir)
+            if drift:
+                print("packaging out of sync with [tool.trackerkeeper.metadata]:", file=sys.stderr)
+                print("  " + "\n  ".join(drift), file=sys.stderr)
+                return 1
+            print("packaging is in sync with [tool.trackerkeeper.metadata].")
+            return 0
+        rendered = write(packaging_dir, ctx)
+    except BakeError as exc:
+        print(f"trackerkeeper bake: {exc}", file=sys.stderr)
+        return 1
+    print(f"rendered {len(rendered)} file(s) into {packaging_dir}:")
+    print("  " + "\n  ".join(sorted(rendered)))
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())