flexitracker 0.2.1.dev0__tar.gz

flexitracker-0.2.1.dev0/.gitignore

@@ -0,0 +1,20 @@
+# Node / Cloudflare
+node_modules/
+.wrangler/
+dist/
+*.log
+
+# Python daemon (uv / build / freeze artifacts)
+.venv/
+__pycache__/
+*.pyc
+daemon-py/build/
+*.spec
+
+# Local simulation state
+.dev-state/
+*.local
+
+# Screenshots / MCP artifacts
+.playwright-mcp/
+/*.png

flexitracker-0.2.1.dev0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: flexitracker
+Version: 0.2.1.dev0
+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.dev0/README.md

@@ -0,0 +1,40 @@
+# 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.dev0/install/README.md

@@ -0,0 +1,38 @@
+# Installing the FlexiTracker daemon
+
+The daemon is a pure-Python program. The **recommended** install on every OS is
+with [uv](https://docs.astral.sh/uv/) — no administrator rights, no compiler, and
+it works on managed machines that block unsigned executables.
+
+## Recommended: uv (all platforms)
+
+```bash
+uv tool install flexitracker
+flexitracker configure --key <YOUR_ACCESS_KEY>
+flexitracker test
+```
+
+Then enable auto-start on login:
+
+- **Linux:** `./install.sh` (installs a systemd *user* service).
+- **Windows:** `powershell -ExecutionPolicy Bypass -File install.ps1` (registers a
+  login task).
+
+## Alternative: standalone executable (machines that allow exes)
+
+If your machine permits running executables, download the standalone
+`flexitracker.exe` (Windows) or `flexitracker` (Linux) from the project's GitHub
+**Releases** page — it bundles its own Python runtime, so nothing else is needed.
+
+```bat
+flexitracker.exe configure --key <YOUR_ACCESS_KEY>
+flexitracker.exe test
+```
+
+### Windows SmartScreen (unsigned executable)
+
+The standalone executable is **not code-signed**, so Windows SmartScreen may warn
+on first run. To allow it: click **More info → Run anyway**, or right-click the
+file → **Properties** → tick **Unblock** → **OK**. If your organization blocks
+unsigned executables entirely, use the **uv** path above instead — it does not run
+an executable.

flexitracker-0.2.1.dev0/install/flexitracker.service

@@ -0,0 +1,12 @@
+[Unit]
+Description=FlexiTracker activity daemon
+After=graphical-session.target
+
+[Service]
+# Runs the entrypoint that `uv tool install flexitracker` puts on PATH.
+ExecStart=%h/.local/bin/flexitracker
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=default.target

flexitracker-0.2.1.dev0/install/install.ps1

@@ -0,0 +1,35 @@
+# FlexiTracker (Windows) — install the daemon into your user profile with uv
+# (no admin, no compiler) and register a login task so it starts on sign-in.
+#
+# This is the recommended path on managed machines that block unsigned
+# executables but permit a user-scope Python toolchain. If your machine allows
+# executables, you can instead download the standalone flexitracker.exe from the
+# GitHub Releases page (see install/README.md for the SmartScreen trust step).
+
+$ErrorActionPreference = "Stop"
+
+if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
+    Write-Error "uv is required: https://docs.astral.sh/uv/ (run: irm https://astral.sh/uv/install.ps1 | iex)"
+    exit 1
+}
+
+Write-Host "Installing flexitracker with uv…"
+uv tool install --upgrade flexitracker
+
+$bin = (Get-Command flexitracker -ErrorAction SilentlyContinue).Source
+if (-not $bin) { $bin = Join-Path $env:USERPROFILE ".local\bin\flexitracker.exe" }
+
+# Authorize this machine if not already configured.
+$cfg = Join-Path $env:APPDATA ".config\flexitracker\config.toml"
+if (-not (Test-Path $cfg)) {
+    Write-Host "`nAuthorize this machine (paste the access key from the web app):"
+    & $bin configure
+}
+
+# Register a login task that starts the daemon windowless.
+$action  = New-ScheduledTaskAction -Execute $bin
+$trigger = New-ScheduledTaskTrigger -AtLogOn
+$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -Hidden
+Register-ScheduledTask -TaskName "FlexiTracker" -Action $action -Trigger $trigger -Settings $settings -Force | Out-Null
+
+Write-Host "`nInstalled and registered to start on login. Check with:  flexitracker test"

flexitracker-0.2.1.dev0/install/install.sh

@@ -0,0 +1,35 @@
+#!/bin/sh
+# FlexiTracker (Linux) — install the daemon into your user profile with uv
+# (no admin, no compiler) and enable it as a systemd user service on login.
+set -e
+
+if ! command -v uv >/dev/null 2>&1; then
+    echo "uv is required: https://docs.astral.sh/uv/  (curl -LsSf https://astral.sh/uv/install.sh | sh)" >&2
+    exit 1
+fi
+
+echo "Installing flexitracker with uv…"
+uv tool install --upgrade flexitracker
+
+BIN="$HOME/.local/bin/flexitracker"
+if [ ! -x "$BIN" ]; then
+    # Fall back to whatever uv put on PATH.
+    BIN="$(command -v flexitracker || echo "$BIN")"
+fi
+
+# Authorize this machine if not already configured.
+if [ ! -f "$HOME/.config/flexitracker/config.toml" ]; then
+    echo
+    echo "Authorize this machine (paste the access key from the web app):"
+    "$BIN" configure
+fi
+
+# Install + enable the user service.
+mkdir -p "$HOME/.config/systemd/user"
+cp "$(dirname "$0")/flexitracker.service" "$HOME/.config/systemd/user/flexitracker.service"
+systemctl --user daemon-reload
+systemctl --user enable --now flexitracker.service
+
+echo
+echo "Installed and started. Check with:  flexitracker test"
+echo "Auto-starts on login. (You may need: loginctl enable-linger \"$USER\")"

flexitracker-0.2.1.dev0/pyinstaller_entry.py

@@ -0,0 +1,15 @@
+"""Entry point for the frozen single-file executable (PyInstaller/Nuitka).
+
+The wheel installs a `flexitracker` console script; the frozen exe needs a plain
+top-level script to freeze. Build (see release.yml):
+
+    uv run --group build pyinstaller --onefile --name flexitracker \
+        --paths src --console pyinstaller_entry.py
+"""
+
+import sys
+
+from flexitracker.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

flexitracker-0.2.1.dev0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "flexitracker"
+# Version is derived from the git tag by hatch-vcs at build time, so the tag IS
+# the version — the release tag and the wheel can never drift. Untagged builds
+# get a development version (which `flexitracker --version` reports as 0.0.0).
+dynamic = ["version"]
+description = "FlexiTracker activity daemon — pure-Python."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+# Pure-Python, near-stdlib on purpose: no compiled extension so `uv tool install`
+# needs no C toolchain and no admin rights (see openspec/specs/daemon-parity).
+# OS idle/lock detection uses ctypes (stdlib); HTTP uses urllib (stdlib);
+# TOML read uses tomllib (stdlib, 3.11+); TOML write is a tiny local emitter.
+dependencies = []
+
+[project.scripts]
+flexitracker = "flexitracker.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+# Freezing tool for the standalone single-file executable (GitHub Release asset,
+# for machines that permit executables). Not a runtime dependency; used only by
+# the release build. See daemon-py/pyinstaller_entry.py and release.yml.
+build = ["pyinstaller>=6"]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+# Version from the VCS tag. `root = ".."` points setuptools-scm at the repo root,
+# since this package lives in a subdirectory (its own pyproject would otherwise
+# not find the repo's .git and would fall back). `no-local-version` keeps the
+# version PyPI-acceptable (no +local segment); `fallback_version` lets a checkout
+# with no tags/history still build.
+[tool.hatch.version]
+source = "vcs"
+raw-options = { root = "..", local_scheme = "no-local-version", fallback_version = "0.0.0" }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flexitracker"]

flexitracker-0.2.1.dev0/src/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-0.2.1.dev0/src/flexitracker/__main__.py

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

flexitracker-0.2.1.dev0/src/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-0.2.1.dev0/src/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)