flexitracker 0.2.1__py3-none-any.whl

flexitracker/__init__.py

@@ -0,0 +1,9 @@
+"""FlexiTracker activity daemon — the pure-Python daemon.
+
+Captures idle/active transitions and ships back-dated events to the backend.
+The trickiest behaviour (back-dating, suspend reconciliation, the emit watermark)
+is pinned by the behavioural vectors in `tests/vectors/`.
+
+The version is derived from the git tag by hatch-vcs at build time; see
+`version.get_version()` (reports 0.0.0 for a development build).
+"""

flexitracker/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

flexitracker/_backend.py

@@ -0,0 +1,16 @@
+"""Backend URL baked into the release build.
+
+Mirrors the Rust `option_env!("FLEXITRACKER_BACKEND_URL")`: the release pipeline
+rewrites `BAKED_BACKEND_URL` (from the PROD_BASE_URL variable) so a user runs only
+`flexitracker configure --key <KEY>`. The `FLEXITRACKER_BACKEND_URL` environment
+variable overrides it, and `--backend-url` overrides both.
+"""
+
+import os
+
+# Rewritten at release time. Empty in source so self-hosters must pass --backend-url.
+BAKED_BACKEND_URL = "https://flexitracker.vuorinet.net"
+
+
+def default_backend_url() -> str:
+    return os.environ.get("FLEXITRACKER_BACKEND_URL") or BAKED_BACKEND_URL

flexitracker/cli.py

@@ -0,0 +1,295 @@
+"""CLI + daemon loop.
+
+Fail-fast: unexpected conditions exit with a clear message rather than being
+silently absorbed. Subcommands: `configure` (authorize + self-test), `test`
+(connectivity check, sends no data), and the default daemon run.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+from ._backend import default_backend_url
+from .config import Config
+from .core import machine_descriptor
+from .idle import Sample, SimulatedIdle, platform_source
+from .outbox import Outbox
+from .sender import SenderError, fetch_thresholds, post_batch, whoami
+from .state_machine import Persisted, StateMachine, Tick
+
+HELP = """flexitracker — activity tracking daemon
+
+USAGE:
+    flexitracker configure [--key KEY] [--backend-url URL]   Authorize this machine
+    flexitracker test                                        Check connectivity (sends no data)
+    flexitracker [OPTIONS]                                   Run the daemon
+
+OPTIONS:
+    --key, --account-key KEY   Per-machine access key (saved to config)
+    --backend-url URL   Backend base URL (defaults to the built-in one)
+    --config PATH       Config file path (default: ~/.config/flexitracker/config.toml)
+    --simulate          Post a synthetic day through the real pipeline and exit
+    --once              Take a single reading, flush, and exit
+    --check             Alias for `test`
+    -V, --version       Print version
+    -h, --help          Print this help"""
+
+
+def now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _os_name() -> str:
+    # Match the Rust std::env::consts::OS values used on the wire.
+    return {"linux": "linux", "win32": "windows", "darwin": "macos"}.get(
+        sys.platform, sys.platform
+    )
+
+
+def machine_desc() -> dict:
+    hostname = os.environ.get("COMPUTERNAME") or os.environ.get("HOSTNAME") or socket.gethostname() or "unknown"
+    return machine_descriptor(hostname, _os_name())
+
+
+class Args:
+    def __init__(self) -> None:
+        self.cmd = "daemon"  # daemon | configure | test
+        self.account_key: Optional[str] = None
+        self.backend_url: Optional[str] = None
+        self.config_path: Optional[Path] = None
+        self.simulate = False
+        self.once = False
+
+
+def parse_args(argv: list) -> Args:
+    a = Args()
+    it = iter(argv)
+
+    def take(flag: str) -> str:
+        try:
+            return next(it)
+        except StopIteration:
+            raise ValueError(f"{flag} requires a value")
+
+    for arg in it:
+        if arg == "configure":
+            a.cmd = "configure"
+        elif arg in ("test", "--check"):
+            a.cmd = "test"
+        elif arg in ("--account-key", "--key"):
+            a.account_key = take(arg)
+        elif arg == "--backend-url":
+            a.backend_url = take(arg)
+        elif arg == "--config":
+            a.config_path = Path(take(arg))
+        elif arg == "--simulate":
+            a.simulate = True
+        elif arg == "--once":
+            a.once = True
+        elif arg in ("--version", "-V"):
+            from .version import get_version
+
+            print(f"flexitracker {get_version()}")
+            sys.exit(0)
+        elif arg in ("--help", "-h"):
+            print(HELP)
+            sys.exit(0)
+        else:
+            raise ValueError(f"unknown argument: {arg}")
+    return a
+
+
+def prompt(msg: str) -> str:
+    sys.stdout.write(msg)
+    sys.stdout.flush()
+    return sys.stdin.readline().strip()
+
+
+def self_test(cfg: Config) -> int:
+    print(f"Contacting {cfg.backend_url} …")
+    try:
+        w = whoami(cfg.backend_url, cfg.access_key)
+    except SenderError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    print("  ✓ Reachable")
+    print(f"  ✓ Key valid — account: {w.email}")
+    if w.machine_label:
+        print(f'  ✓ This machine: "{w.machine_label}"')
+    if w.active:
+        print("  ✓ Account active — no activity data was sent.")
+        return 0
+    print(f"error: account is {w.status} — not active yet (nothing was sent)", file=sys.stderr)
+    return 1
+
+
+def flush(cfg: Config, ob: Outbox) -> None:
+    batch = ob.next_batch()
+    if batch is None:
+        return
+    try:
+        post_batch(cfg.backend_url, cfg.access_key, batch)
+        ob.ack()
+    except SenderError as e:
+        print(f"flush deferred ({ob.pending_len()} pending): {e}", file=sys.stderr)
+
+
+def load_state(path: Path) -> Optional[Persisted]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError):
+        return None
+    return Persisted(
+        reported_state=data.get("reported_state", "Idle"),
+        last_active_time=data.get("last_active_time"),
+        last_heartbeat=data.get("last_heartbeat"),
+        pending_active_since=data.get("pending_active_since"),
+        last_emitted_ts=data.get("last_emitted_ts"),
+        last_seen_wall=data.get("last_seen_wall"),
+    )
+
+
+def save_state(path: Path, p: Persisted) -> None:
+    # Temp + rename: this file is the sole basis for reconstructing the end of a
+    # span after an ungraceful shutdown, so a torn write would corrupt exactly
+    # the record that exists to survive one.
+    data = {
+        "reported_state": p.reported_state,
+        "last_active_time": p.last_active_time,
+        "last_heartbeat": p.last_heartbeat,
+        "pending_active_since": p.pending_active_since,
+        "last_emitted_ts": p.last_emitted_ts,
+        "last_seen_wall": p.last_seen_wall,
+    }
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(data), encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def simulate(cfg: Config, ob: Outbox) -> int:
+    n = now_ms()
+    day = n - (n % 86_400_000)
+    h = 3_600_000
+    events = [
+        {"ts": day + 8 * h, "kind": "active"},
+        {"ts": day + 10 * h, "kind": "idle"},
+        {"ts": day + 13 * h, "kind": "active"},
+        {"ts": day + 16 * h, "kind": "idle"},
+    ]
+    ob.append(events)
+    try:
+        post_batch(cfg.backend_url, cfg.access_key, ob.next_batch())
+        ob.ack()
+    except SenderError as e:
+        print(f"error: simulate post failed: {e}", file=sys.stderr)
+        return 1
+    print(f"simulated day posted ({len(events)} events)")
+    return 0
+
+
+def run(argv: list) -> int:
+    try:
+        args = parse_args(argv)
+    except ValueError as e:
+        print(HELP)
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+    config_path = args.config_path or Config.default_path()
+
+    try:
+        cfg = Config.load(config_path)
+    except Exception:  # noqa: BLE001 — any load failure falls back to a fresh config (mirrors the Rust `.ok().unwrap_or_else`)
+        cfg = Config()
+
+    if args.account_key:
+        cfg.access_key = args.account_key
+    if args.backend_url:
+        cfg.backend_url = args.backend_url
+    if not cfg.backend_url:
+        cfg.backend_url = default_backend_url()
+
+    if args.cmd == "configure":
+        if not cfg.access_key:
+            cfg.access_key = prompt("Paste your machine access key: ")
+        if not cfg.access_key:
+            print("error: no access key provided", file=sys.stderr)
+            return 1
+        if not cfg.backend_url:
+            print("error: no backend url (pass --backend-url; releases have one built in)", file=sys.stderr)
+            return 1
+        cfg.save(config_path)
+        print(f"Saved config to {config_path}.")
+        return self_test(cfg)
+
+    if args.cmd == "test":
+        if not cfg.access_key or not cfg.backend_url:
+            print("error: not configured — run `flexitracker configure --key <KEY>` first", file=sys.stderr)
+            return 1
+        return self_test(cfg)
+
+    # Daemon
+    if not cfg.access_key or not cfg.backend_url:
+        print("error: missing access key or backend url (run `flexitracker configure --key <KEY>`)", file=sys.stderr)
+        return 1
+    cfg.save(config_path)
+
+    # Refresh thresholds; fall back to cached/defaults offline.
+    try:
+        cfg.thresholds = fetch_thresholds(cfg.backend_url, cfg.access_key, cfg.thresholds.poll_sec)
+        cfg.save(config_path)
+    except SenderError as e:
+        print(f"warning: using cached thresholds ({e})", file=sys.stderr)
+    thresholds = cfg.thresholds.to_thresholds()
+
+    state_path = config_path.with_name("state.json")
+    outbox_path = config_path.with_name("outbox.json")
+    ob = Outbox.open(outbox_path)
+    dropped = ob.trim_expired(now_ms())
+    if dropped > 0:
+        print(f"dropped {dropped} outbox event(s) older than the backend edit window", file=sys.stderr)
+    ob.set_machine(machine_desc())
+
+    if args.simulate:
+        return simulate(cfg, ob)
+
+    persisted = load_state(state_path) or Persisted()
+    sm = StateMachine(thresholds, persisted)
+
+    ob.append(sm.recover(now_ms()))
+    save_state(state_path, sm.p)
+    flush(cfg, ob)
+
+    try:
+        source = platform_source()
+    except OSError as e:
+        print(f"error: idle source: {e}", file=sys.stderr)
+        return 1
+
+    last_mono: Optional[float] = None
+    while True:
+        s: Sample = source.sample()
+        mono_now = time.monotonic()
+        mono_elapsed_ms = None if last_mono is None else int((mono_now - last_mono) * 1000)
+        last_mono = mono_now
+        events = sm.step(
+            Tick(now=now_ms(), idle_ms=s.idle_ms, locked=s.locked, mono_elapsed_ms=mono_elapsed_ms)
+        )
+        ob.append(events)
+        save_state(state_path, sm.p)
+        flush(cfg, ob)
+        if args.once:
+            return 0
+        time.sleep(thresholds.poll_ms / 1000)
+
+
+def main(argv: Optional[list] = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+    return run(argv)

flexitracker/config.py

@@ -0,0 +1,108 @@
+"""Daemon config file — mirror of `config.rs`.
+
+`{backend_url, access_key, account_id?, machine_id?, thresholds}` stored as TOML
+with 0600 permissions. Thresholds are refreshed from the backend on startup,
+falling back to these cached/default values when offline.
+
+Read uses stdlib `tomllib`; write uses a tiny local emitter (the schema is fixed
+and small, so no third-party TOML writer is pulled in).
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from .state_machine import Thresholds
+
+
+@dataclass
+class ThresholdCfg:
+    poll_sec: int = 15
+    min_inactivity_sec: int = 600
+    min_activity_sec: int = 30
+    heartbeat_sec: int = 300
+
+    def to_thresholds(self) -> Thresholds:
+        return Thresholds(
+            poll_ms=self.poll_sec * 1000,
+            min_inactivity_ms=self.min_inactivity_sec * 1000,
+            min_activity_ms=self.min_activity_sec * 1000,
+            heartbeat_ms=self.heartbeat_sec * 1000,
+        )
+
+
+@dataclass
+class Config:
+    backend_url: str = ""
+    access_key: str = ""
+    account_id: Optional[str] = None
+    machine_id: Optional[str] = None
+    thresholds: ThresholdCfg = field(default_factory=ThresholdCfg)
+
+    @staticmethod
+    def default_path() -> Path:
+        override = os.environ.get("FLEXITRACKER_CONFIG")
+        if override:
+            return Path(override)
+        base = os.environ.get("HOME") or os.environ.get("APPDATA") or "."
+        return Path(base) / ".config" / "flexitracker" / "config.toml"
+
+    @classmethod
+    def load(cls, path: Path) -> "Config":
+        with open(path, "rb") as fh:
+            data = tomllib.load(fh)
+        th = data.get("thresholds", {})
+        return cls(
+            backend_url=data.get("backend_url", ""),
+            access_key=data.get("access_key", ""),
+            account_id=data.get("account_id"),
+            machine_id=data.get("machine_id"),
+            thresholds=ThresholdCfg(
+                poll_sec=th.get("poll_sec", 15),
+                min_inactivity_sec=th.get("min_inactivity_sec", 600),
+                min_activity_sec=th.get("min_activity_sec", 30),
+                heartbeat_sec=th.get("heartbeat_sec", 300),
+            ),
+        )
+
+    def save(self, path: Path) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(self._to_toml(), encoding="utf-8")
+        _restrict_permissions(path)
+
+    def _to_toml(self) -> str:
+        lines = [
+            f'backend_url = "{_esc(self.backend_url)}"',
+            f'access_key = "{_esc(self.access_key)}"',
+        ]
+        if self.account_id is not None:
+            lines.append(f'account_id = "{_esc(self.account_id)}"')
+        if self.machine_id is not None:
+            lines.append(f'machine_id = "{_esc(self.machine_id)}"')
+        lines += [
+            "",
+            "[thresholds]",
+            f"poll_sec = {self.thresholds.poll_sec}",
+            f"min_inactivity_sec = {self.thresholds.min_inactivity_sec}",
+            f"min_activity_sec = {self.thresholds.min_activity_sec}",
+            f"heartbeat_sec = {self.thresholds.heartbeat_sec}",
+            "",
+        ]
+        return "\n".join(lines)
+
+
+def _esc(s: str) -> str:
+    return s.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _restrict_permissions(path: Path) -> None:
+    # No-op on Windows (POSIX modes do not apply); mirror the Rust cfg(unix) gate.
+    if os.name == "posix":
+        try:
+            os.chmod(path, 0o600)
+        except OSError:
+            pass

flexitracker/core.py

@@ -0,0 +1,29 @@
+"""Shared wire types — mirrors `flexitracker-core/src/lib.rs` and
+`docs/wire-schema.md`. Keep all in sync; the conformance harness proves it.
+
+Events are represented as plain dicts ``{"ts": int, "kind": str}`` so their JSON
+form is exactly the wire form. `kind` is one of the lowercase EventKind values.
+"""
+
+from __future__ import annotations
+
+
+class EventKind:
+    """The `kind` field values (serialize lowercase, per the wire schema)."""
+
+    ACTIVE = "active"
+    IDLE = "idle"
+    LOCK = "lock"
+    UNLOCK = "unlock"
+    LOGIN = "login"
+    LOGOUT = "logout"
+    HEARTBEAT = "heartbeat"
+
+
+def event(ts: int, kind: str) -> dict:
+    """A single back-dated activity event. `ts` is unix epoch milliseconds."""
+    return {"ts": ts, "kind": kind}
+
+
+def machine_descriptor(hostname: str, os_name: str) -> dict:
+    return {"hostname": hostname, "os": os_name}

flexitracker/idle.py

@@ -0,0 +1,97 @@
+"""Idle-time and session-lock detection — mirror of `idle.rs`, via ctypes.
+
+No input content is ever captured — only "how long since any input" and whether
+the session is locked. Platform sources are selected at runtime; a simulated
+source drives scripted runs and tests. Using ctypes (stdlib) means no compiled
+extension and so no C toolchain at install time.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import sys
+from dataclasses import dataclass
+
+
+@dataclass
+class Sample:
+    idle_ms: int
+    locked: bool
+
+
+class SimulatedIdle:
+    """Replays a scripted sequence of samples (scripted runs / tests)."""
+
+    def __init__(self, samples: list) -> None:
+        self._samples = samples
+        self._i = 0
+
+    def sample(self) -> Sample:
+        if self._i < len(self._samples):
+            s = self._samples[self._i]
+        else:
+            s = Sample(idle_ms=2**63 - 1, locked=False)  # exhausted -> very idle
+        self._i += 1
+        return s
+
+
+# XScreenSaverInfo: idle (unsigned long) is at byte offset 24 on LP64
+# (window u64, state i32, kind i32, since u64, idle u64, ...).
+_IDLE_OFFSET = 24
+
+
+class LinuxIdle:
+    def __init__(self) -> None:
+        try:
+            x11 = ctypes.CDLL("libX11.so.6")
+            xss = ctypes.CDLL("libXss.so.1")
+        except OSError as e:
+            raise OSError(f"cannot load X libraries ({e}); set them up or use --simulate") from e
+
+        x11.XOpenDisplay.restype = ctypes.c_void_p
+        x11.XOpenDisplay.argtypes = [ctypes.c_char_p]
+        x11.XDefaultRootWindow.restype = ctypes.c_ulong
+        x11.XDefaultRootWindow.argtypes = [ctypes.c_void_p]
+        xss.XScreenSaverAllocInfo.restype = ctypes.c_void_p
+        xss.XScreenSaverQueryInfo.argtypes = [ctypes.c_void_p, ctypes.c_ulong, ctypes.c_void_p]
+        xss.XScreenSaverQueryInfo.restype = ctypes.c_int
+
+        self._display = x11.XOpenDisplay(None)
+        if not self._display:
+            raise OSError("cannot open X display (set DISPLAY, or use --simulate)")
+        self._root = x11.XDefaultRootWindow(self._display)
+        self._info = xss.XScreenSaverAllocInfo()
+        self._query = xss.XScreenSaverQueryInfo
+
+    def sample(self) -> Sample:
+        self._query(self._display, self._root, self._info)
+        idle_ptr = ctypes.cast(self._info + _IDLE_OFFSET, ctypes.POINTER(ctypes.c_ulong))
+        return Sample(idle_ms=int(idle_ptr.contents.value), locked=False)
+
+
+class _LASTINPUTINFO(ctypes.Structure):
+    _fields_ = [("cbSize", ctypes.c_uint), ("dwTime", ctypes.c_uint)]
+
+
+class WindowsIdle:
+    def __init__(self) -> None:
+        self._user32 = ctypes.windll.user32  # type: ignore[attr-defined]
+        self._kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+
+    def sample(self) -> Sample:
+        info = _LASTINPUTINFO()
+        info.cbSize = ctypes.sizeof(_LASTINPUTINFO)
+        if self._user32.GetLastInputInfo(ctypes.byref(info)) == 0:
+            raise OSError("GetLastInputInfo failed")
+        tick = self._kernel32.GetTickCount() & 0xFFFFFFFF
+        idle_ms = (tick - info.dwTime) & 0xFFFFFFFF  # wrapping_sub, as u32
+        return Sample(idle_ms=idle_ms, locked=False)
+
+
+def platform_source():
+    """Construct the real platform idle source, or fail fast with a clear message."""
+    if sys.platform.startswith("linux"):
+        return LinuxIdle()
+    if sys.platform == "win32":
+        return WindowsIdle()
+    raise OSError(f"no idle source for platform {sys.platform!r}; use --simulate")

flexitracker/outbox.py

@@ -0,0 +1,109 @@
+"""Durable local outbox — mirror of `outbox.rs`.
+
+Events are buffered to disk so nothing is lost while offline; the whole queue is
+flushed on reconnect, and a monotonic `batch_seq` lets the backend deduplicate
+re-sent batches. The on-disk JSON format matches the Rust daemon's exactly so
+either implementation can resume the other's outbox (proven by the harness).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+# Events older than the backend's edit window are rejected on arrival; holding
+# them only grows the file.
+MAX_EVENT_AGE_MS = 120 * 86_400_000
+
+# Upper bound on one flush, so a long backlog drains across several acknowledged
+# batches rather than one oversized request that can never succeed.
+MAX_BATCH_EVENTS = 2_000
+
+
+class Outbox:
+    def __init__(self, path: Path, next_seq: int, pending: list, machine: Optional[dict]) -> None:
+        self.path = path
+        self.next_seq = next_seq
+        self.pending = pending
+        self.machine = machine
+
+    @classmethod
+    def open(cls, path: Path) -> "Outbox":
+        try:
+            text = path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return cls(path, 0, [], None)
+        try:
+            state = json.loads(text)
+        except json.JSONDecodeError as e:
+            # A torn file must not strand the daemon: refusing to start would
+            # hold buffered events hostage AND stop new capture. Move it aside so
+            # the contents stay recoverable, then start empty.
+            aside = path.with_suffix(".corrupt")
+            moved = False
+            try:
+                path.rename(aside)
+                moved = True
+            except OSError:
+                pass
+            extra = f" (previous contents kept at {aside})" if moved else ""
+            print(f"warning: outbox unreadable ({e}); starting with an empty queue{extra}")
+            return cls(path, 0, [], None)
+        return cls(
+            path,
+            state.get("next_seq", 0),
+            state.get("pending", []),
+            state.get("machine"),
+        )
+
+    def trim_expired(self, now: int) -> int:
+        """Drop events the backend would reject as too old. Returns how many went."""
+        before = len(self.pending)
+        self.pending = [e for e in self.pending if now - e["ts"] < MAX_EVENT_AGE_MS]
+        return before - len(self.pending)
+
+    def pending_len(self) -> int:
+        return len(self.pending)
+
+    def set_machine(self, machine: dict) -> None:
+        self.machine = machine
+        self._persist()
+
+    def append(self, events: list) -> None:
+        if not events:
+            return
+        self.pending.extend(events)
+        self._persist()
+
+    def next_batch(self) -> Optional[dict]:
+        """The next chunk to send (empty pending -> None). Includes the machine
+        descriptor on every batch until first successfully sent. Capped at
+        MAX_BATCH_EVENTS."""
+        if not self.pending:
+            return None
+        n = min(len(self.pending), MAX_BATCH_EVENTS)
+        return {
+            "batch_seq": self.next_seq,
+            "events": list(self.pending[:n]),
+            "machine": self.machine,
+        }
+
+    def ack(self) -> None:
+        """Drop exactly the events the just-sent batch carried and advance the
+        sequence, so the next chunk gets its own batch_seq."""
+        n = min(len(self.pending), MAX_BATCH_EVENTS)
+        del self.pending[:n]
+        self.next_seq += 1
+        self.machine = None
+        self._persist()
+
+    def _persist(self) -> None:
+        """Write via a temp file and rename (atomic within a directory), so a
+        reader never sees a torn file."""
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        state = {"next_seq": self.next_seq, "pending": self.pending, "machine": self.machine}
+        tmp = self.path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(state), encoding="utf-8")
+        os.replace(tmp, self.path)

flexitracker/sender.py

@@ -0,0 +1,97 @@
+"""Thin HTTP client to the backend — mirror of `sender.rs`.
+
+Post a batch, fetch thresholds, and the read-only whoami self-test. Uses stdlib
+`urllib` so no HTTP dependency is pulled in. The wire form is exactly the schema
+in `docs/wire-schema.md`; the black-box harness proves it matches the reference.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Optional
+
+from .config import ThresholdCfg
+
+
+class SenderError(Exception):
+    pass
+
+
+def _request(url: str, key: str, method: str, body: Optional[dict]) -> dict:
+    data = None
+    headers = {"authorization": f"Bearer {key}"}
+    if body is not None:
+        data = json.dumps(body).encode("utf-8")
+        headers["content-type"] = "application/json"
+    req = urllib.request.Request(url, data=data, headers=headers, method=method)
+    with urllib.request.urlopen(req) as resp:  # noqa: S310 (fixed backend URL)
+        raw = resp.read()
+    return json.loads(raw) if raw else {}
+
+
+def _ingest_url(base: str) -> str:
+    return f"{base.rstrip('/')}/ingest"
+
+
+def post_batch(base: str, key: str, batch: dict) -> None:
+    """Post a batch. 2xx (including a duplicate ack) is success; anything else
+    raises so the caller keeps the batch queued for retry.
+
+    `machine` is omitted from the body when absent (never sent as null), per the
+    wire schema.
+    """
+    body = {"batch_seq": batch["batch_seq"], "events": batch["events"]}
+    if batch.get("machine") is not None:
+        body["machine"] = batch["machine"]
+    try:
+        _request(_ingest_url(base), key, "POST", body)
+    except urllib.error.HTTPError as e:
+        raise SenderError(f"server returned {e.code}") from e
+    except urllib.error.URLError as e:
+        raise SenderError(str(e.reason)) from e
+
+
+@dataclass
+class WhoAmI:
+    email: str
+    machine_label: Optional[str]
+    status: str
+    active: bool
+
+
+def whoami(base: str, key: str) -> WhoAmI:
+    """Read-only account echo for the self-test. Sends/stores no activity data."""
+    url = f"{base.rstrip('/')}/whoami"
+    try:
+        data = _request(url, key, "GET", None)
+    except urllib.error.HTTPError as e:
+        if e.code == 401:
+            raise SenderError("key rejected (401)") from e
+        raise SenderError(f"server returned {e.code}") from e
+    except urllib.error.URLError as e:
+        raise SenderError(str(e.reason)) from e
+    return WhoAmI(
+        email=data["email"],
+        machine_label=data.get("machineLabel"),
+        status=data["status"],
+        active=data["active"],
+    )
+
+
+def fetch_thresholds(base: str, key: str, poll_sec: int) -> ThresholdCfg:
+    """Fetch current thresholds from the backend (keeps the caller's poll)."""
+    url = f"{base.rstrip('/')}/config"
+    try:
+        data = _request(url, key, "GET", None)
+    except (urllib.error.HTTPError, urllib.error.URLError) as e:
+        reason = getattr(e, "code", None) or getattr(e, "reason", e)
+        raise SenderError(str(reason)) from e
+    return ThresholdCfg(
+        poll_sec=poll_sec,
+        min_inactivity_sec=data["minInactivitySec"],
+        min_activity_sec=data["minActivitySec"],
+        heartbeat_sec=data["heartbeatSec"],
+    )

flexitracker/state_machine.py

@@ -0,0 +1,177 @@
+"""Debounced hysteresis state machine.
+
+Any change here MUST land as a change to the behavioural vectors in
+`tests/vectors/`, which are the daemon's oracle for this logic. The behaviour:
+- idle is confirmed only after `min_inactivity` and emitted **back-dated** to the
+  last real input,
+- return-to-active is confirmed only after `min_activity` of sustained input,
+- periodic heartbeats bound crash/sleep damage,
+- downtime (reboot/suspend/clock-step) is reconciled via monotonic-vs-wall
+  divergence and startup recover().
+
+Pure: `step` takes an observation and returns events, with no I/O. All arithmetic
+is integer milliseconds.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .core import EventKind, event
+
+# Input newer than this counts as "fresh" on a tick. Deliberately NOT poll_ms:
+# freshness is "how recent must input be to mean the user is here", independent
+# of how often we poll. See the Rust comment for the bug this prevents.
+FRESH_INPUT_MS = 20_000
+
+ACTIVE = "Active"
+IDLE = "Idle"
+
+
+@dataclass
+class Thresholds:
+    poll_ms: int = 15_000
+    min_inactivity_ms: int = 10 * 60_000
+    min_activity_ms: int = 30_000
+    heartbeat_ms: int = 5 * 60_000
+
+
+@dataclass
+class Persisted:
+    """The persisted part — survives restarts so reboots reconcile (see recover).
+
+    Written on every poll; accurate to the poll interval and independent of the
+    network.
+    """
+
+    reported_state: str = IDLE
+    last_active_time: Optional[int] = None
+    last_heartbeat: Optional[int] = None
+    pending_active_since: Optional[int] = None
+    # Timestamp of the most recently emitted event; a backwards clock must never
+    # emit below it (spans are paired in ts order).
+    last_emitted_ts: Optional[int] = None
+    # Wall clock at the previous tick, differenced against monotonic elapsed time
+    # to detect a suspend. Only meaningful within a single process run.
+    last_seen_wall: Optional[int] = None
+
+
+@dataclass
+class Tick:
+    """One observation from the OS."""
+
+    now: int
+    idle_ms: int
+    locked: bool = False
+    # Monotonic ms since the previous tick; None on the first tick.
+    mono_elapsed_ms: Optional[int] = None
+
+
+class StateMachine:
+    def __init__(self, thresholds: Thresholds, persisted: Persisted) -> None:
+        self.t = thresholds
+        self.p = persisted
+
+    def emit(self, ts: int, kind: str) -> dict:
+        """Emit an event, holding the monotonic-timestamp watermark. Clamping
+        here means no path can emit out of order."""
+        prev = self.p.last_emitted_ts
+        if prev is not None and ts < prev:
+            ts = prev
+        self.p.last_emitted_ts = ts
+        return event(ts, kind)
+
+    def input_fresh(self, tick: Tick) -> bool:
+        return (not tick.locked) and tick.idle_ms < FRESH_INPUT_MS
+
+    def last_evidence(self) -> Optional[int]:
+        """The most recent local evidence the user was here: the later of
+        heartbeat and last-active-time (last_active is written every poll)."""
+        h = self.p.last_heartbeat
+        a = self.p.last_active_time
+        if h is not None and a is not None:
+            return max(h, a)
+        return h if h is not None else a
+
+    def reconcile_gap(self, gap_ms: int) -> list:
+        """Reconcile an unobserved interval (reboot/crash/suspend). Gaps below
+        min_inactivity are absorbed; longer ones close the span back-dated to the
+        last local evidence. Shared by recover() and in-loop detection so they
+        cannot drift apart."""
+        if self.p.reported_state != ACTIVE or gap_ms < self.t.min_inactivity_ms:
+            return []
+        anchor = self.last_evidence()
+        if anchor is None:
+            return []
+        self.p.reported_state = IDLE
+        self.p.pending_active_since = None
+        return [self.emit(anchor, EventKind.IDLE)]
+
+    def recover(self, now: int) -> list:
+        """On startup, reconcile downtime the daemon could not observe. The gap
+        is measured from the last local evidence to now."""
+        a = self.last_evidence()
+        if a is None:
+            return []
+        return self.reconcile_gap(now - a)
+
+    def due_heartbeat(self, now: int) -> bool:
+        hb = self.p.last_heartbeat
+        if hb is None:
+            return True
+        return now - hb >= self.t.heartbeat_ms
+
+    def step(self, tick: Tick) -> list:
+        out: list = []
+
+        # Downtime the daemon slept through: wall advances across a suspend while
+        # the monotonic clock does not, so the difference isolates the frozen
+        # interval. Runs BEFORE state handling (fresh input on wake must not
+        # absorb the suspend). Backwards divergence is a clock correction, ignored.
+        if tick.mono_elapsed_ms is not None:
+            seen = self.p.last_seen_wall if self.p.last_seen_wall is not None else tick.now
+            divergence = (tick.now - seen) - tick.mono_elapsed_ms
+            if divergence > 0:
+                out.extend(self.reconcile_gap(divergence))
+        self.p.last_seen_wall = tick.now
+
+        fresh = self.input_fresh(tick)
+        if fresh:
+            self.p.last_active_time = tick.now
+
+        if self.p.reported_state == ACTIVE:
+            idle_long = tick.locked or tick.idle_ms >= self.t.min_inactivity_ms
+            if idle_long:
+                # Back-date idle to when input actually stopped. On the LOCK path
+                # keep the last-input anchor (reported idle at lock reflects the
+                # lock, not the user's last activity); otherwise now - idle_ms is
+                # the exact stop moment.
+                if tick.locked:
+                    ts = self.p.last_active_time if self.p.last_active_time is not None else tick.now
+                else:
+                    ts = tick.now - tick.idle_ms
+                out.append(self.emit(ts, EventKind.IDLE))
+                self.p.reported_state = IDLE
+                self.p.pending_active_since = None
+            elif self.due_heartbeat(tick.now):
+                out.append(self.emit(tick.now, EventKind.HEARTBEAT))
+                self.p.last_heartbeat = tick.now
+        else:  # IDLE
+            # "Activity persisted for min_activity" must tolerate short pauses.
+            # The claim dies only when idle reaches min_activity itself; below
+            # that the accumulator keeps running.
+            if tick.locked or tick.idle_ms >= self.t.min_activity_ms:
+                self.p.pending_active_since = None
+            else:
+                # Start only on genuinely fresh input; once started, short pauses
+                # no longer reset it. Anchor to the real resume moment.
+                if fresh and self.p.pending_active_since is None:
+                    self.p.pending_active_since = tick.now - tick.idle_ms
+                if self.p.pending_active_since is not None:
+                    if tick.now - self.p.pending_active_since >= self.t.min_activity_ms:
+                        out.append(self.emit(self.p.pending_active_since, EventKind.ACTIVE))
+                        self.p.reported_state = ACTIVE
+                        self.p.pending_active_since = None
+                        self.p.last_heartbeat = tick.now
+        return out

flexitracker/version.py

@@ -0,0 +1,26 @@
+"""Runtime version resolution.
+
+The package version is derived from the git tag by hatch-vcs at build time and
+read back here from the installed distribution metadata. A **development** build
+(an untagged checkout, or a build between tags) reports ``0.0.0`` so the version
+string unambiguously distinguishes a real release from a dev run.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as _dist_version
+
+
+def get_version() -> str:
+    """Return the released version, or ``0.0.0`` for a development build.
+
+    A version carrying a development marker (`dev`) or a local segment (`+…`),
+    or a distribution with no metadata at all, is a development build.
+    """
+    try:
+        v = _dist_version("flexitracker")
+    except PackageNotFoundError:
+        return "0.0.0"
+    if "dev" in v or "+" in v:
+        return "0.0.0"
+    return v

flexitracker-0.2.1.dist-info/METADATA

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: flexitracker
+Version: 0.2.1
+Summary: FlexiTracker activity daemon — pure-Python.
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# FlexiTracker daemon (Python)
+
+The FlexiTracker activity daemon: a pure-Python program that captures idle/active
+transitions and ships back-dated events to the backend. Pure stdlib, no compiled
+extension, so it installs with `uv` into a user profile — no admin rights and no
+compiler — which is what lets it run on managed machines that block unsigned
+executables. OS idle detection is done through `ctypes` (Windows
+`GetLastInputInfo`, Linux XScreenSaver).
+
+## Install
+
+Recommended (all platforms):
+
+```bash
+uv tool install flexitracker
+```
+
+Or, on a machine that allows executables, download the standalone
+`flexitracker` / `flexitracker.exe` from the GitHub **Releases** page (it bundles
+its own Python runtime). See `install/README.md` for per-OS auto-start and the
+Windows SmartScreen trust step.
+
+## Use
+
+```bash
+flexitracker configure --key <ACCESS_KEY>   # authorize this machine, then self-test
+flexitracker test                            # connectivity check, sends no data
+flexitracker                                 # run the daemon
+```
+
+## Develop
+
+```bash
+uv sync
+uv run pytest        # unit tests + the 24 behavioural vectors (tests/vectors/)
+```
+
+The behavioural vectors in `tests/vectors/` are the oracle for the state machine
+(back-dating, suspend reconciliation, the emit watermark, the return-to-work
+clock). Any change to that logic must be reflected in a vector.

flexitracker-0.2.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+flexitracker/__init__.py,sha256=Ijk0VDI5_Kss_9DC-AaoXL-kz-EQQ7Pik1leMoKUmZg,420
+flexitracker/__main__.py,sha256=4JMK66Wj4uLZTKbF-sT3LAxOsr6buig77PmOkJCRRxw,83
+flexitracker/_backend.py,sha256=nD5gFWdkExbN3Y2x4hMXH7X8dZ5kdq7_H7tqK_HrJHM,619
+flexitracker/cli.py,sha256=gJFr9ymEQqGubiync1K1aco35OMYysz1i00keZgjFeM,9685
+flexitracker/config.py,sha256=c8AFB0-LjP7bsiq04Gzay2sjujGidUiHccCFUuG9rkQ,3564
+flexitracker/core.py,sha256=tffEFMkr_JeoOVIT48wC2vCaaXuMQkUedPWzs9qFC7I,862
+flexitracker/idle.py,sha256=tSvPHIKLkvfx2Ec3qAg6-SHyT2NDNMeizjnwJPEKAsw,3477
+flexitracker/outbox.py,sha256=uIxcavH7adASIXBZwiHE7Ajev37uzSPuO_grS3pyViI,4005
+flexitracker/sender.py,sha256=BFS7n0u-FVVu9qWMsy4UaolgU0pQwoaI0VHWRE-tcVM,3230
+flexitracker/state_machine.py,sha256=wqeqKGz8Sl-Hyw1Fxciu2SuEjP5eN5LgEwFa7dnWR8k,7215
+flexitracker/version.py,sha256=dNIVXaHwLgB0iQc5CS4xF3Jq44lmTBURasN5pnhwkkc,895
+flexitracker-0.2.1.dist-info/METADATA,sha256=pqlE2ElAdx36Ty0JwnRh-0QaVgY1tsa8l_-ejT9vPUM,1592
+flexitracker-0.2.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+flexitracker-0.2.1.dist-info/entry_points.txt,sha256=39O8Xs-n_gy9XRyryRyzWqfbigxhmJNLUXSl8hsVd3U,55
+flexitracker-0.2.1.dist-info/RECORD,,

flexitracker-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

flexitracker-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+flexitracker = flexitracker.cli:main