fruxon 0.8.2__tar.gz → 0.8.4__tar.gz

{fruxon-0.8.2 → fruxon-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fruxon
-Version: 0.8.2
+Version: 0.8.4
 Summary: The Fruxon SDK is a lightweight Python client for integrating with the Fruxon platform.
 Project-URL: bugs, https://github.com/fruxon-ai/fruxon-sdk/issues
 Project-URL: changelog, https://github.com/fruxon-ai/fruxon-sdk/blob/main/HISTORY.md

{fruxon-0.8.2 → fruxon-0.8.4}/src/fruxon/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.8.2'
-__version_tuple__ = version_tuple = (0, 8, 2)
+__version__ = version = '0.8.4'
+__version_tuple__ = version_tuple = (0, 8, 4)
 
 __commit_id__ = commit_id = None

{fruxon-0.8.2 → fruxon-0.8.4}/src/fruxon/cli/__init__.py

@@ -19,7 +19,7 @@ from typing import Annotated
 import typer
 from typer.core import TyperGroup
 
-from fruxon import credentials
+from fruxon import credentials, telemetry
 from fruxon.ui import (
     cli_docs_url,
     dashboard_url,
@@ -32,6 +32,34 @@ from fruxon.ui import (
 )
 
 
+def _classify_exception(exc: BaseException) -> str:
+    """Map an exception to one of the schema's error_class enum values.
+
+    The wire allowlist (see CliTelemetrySchema.ErrorClasses on the
+    backend) deliberately keeps this set small — free-form error text
+    could carry user data (paths, agent names, prompts) we don't want
+    in the event stream. Mapping at the boundary is where we narrow
+    real exceptions to one of those buckets.
+    """
+    import socket
+    import ssl
+    import urllib.error as _ue
+
+    if isinstance(exc, typer.Exit):
+        # ``typer.Exit`` is a normal-flow signal even with a non-zero
+        # exit code — it's how we surface user-input errors, not a
+        # crash. The actual error class was tagged via the typer call
+        # site (we don't see it here). Treat as "user_input" by default.
+        return "user_input"
+    if isinstance(exc, KeyboardInterrupt):
+        return "user_input"
+    if isinstance(exc, (_ue.URLError, socket.timeout, ConnectionError, ssl.SSLError, OSError)):
+        return "network"
+    if isinstance(exc, (PermissionError, FileNotFoundError)):
+        return "config"
+    return "other"
+
+
 class _FruxonTyperGroup(TyperGroup):
     """Branded replacement for Typer's stock ``no such command`` error.
 
@@ -49,6 +77,49 @@ class _FruxonTyperGroup(TyperGroup):
     signal.
     """
 
+    def invoke(self, ctx):
+        """Wrap subcommand execution with telemetry timing.
+
+        Telemetry is fire-and-forget on a background thread — see
+        :mod:`fruxon.telemetry`. This wrapper exists so the event
+        carries (a) which subcommand was actually invoked, (b) whether
+        it succeeded, (c) how long it took, and (d) which error class
+        any failure mapped to. ``telemetry.track`` itself silently
+        no-ops when opted out or unauthenticated, so this code path is
+        unconditional.
+        """
+        import time as _time
+
+        command_name = ctx.invoked_subcommand or "(root)"
+        started = _time.monotonic()
+        succeeded = False
+        try:
+            result = super().invoke(ctx)
+            succeeded = True
+            return result
+        except BaseException as exc:
+            duration_ms = int((_time.monotonic() - started) * 1000)
+            telemetry.track(
+                "CLI Command Failed",
+                {
+                    "command": command_name,
+                    "error_class": _classify_exception(exc),
+                    "duration_ms": duration_ms,
+                },
+            )
+            raise
+        finally:
+            if succeeded:
+                duration_ms = int((_time.monotonic() - started) * 1000)
+                telemetry.track(
+                    "CLI Command Invoked",
+                    {
+                        "command": command_name,
+                        "succeeded": True,
+                        "duration_ms": duration_ms,
+                    },
+                )
+
     def get_command(self, ctx, cmd_name):
         cmd = super().get_command(ctx, cmd_name)
         if cmd is not None:
@@ -80,6 +151,11 @@ class _FruxonTyperGroup(TyperGroup):
 # never raise, so this is the right place.
 atexit.register(maybe_print_update_notice)
 
+# Print the one-time telemetry notice at the end of the first invocation
+# (TTY only, never in agent mode, never if already opted out). atexit so
+# it lands after the user's actual command output rather than before it.
+atexit.register(telemetry.maybe_print_first_run_notice)
+
 app = typer.Typer(
     help="Fruxon CLI · tools for working with the Fruxon platform.",
     pretty_exceptions_enable=False,

{fruxon-0.8.2 → fruxon-0.8.4}/src/fruxon/cli/auth.py

@@ -126,6 +126,7 @@ def login(
     # Resolve the API key. Two paths:
     #   * ``--api-key`` supplied → headless, skip browser flow entirely.
     #   * No ``--api-key`` → browser flow via :func:`_browser_login`.
+    api_key_flag = api_key is not None
     slug_from_grant: str | None = None
     if api_key is None:
         # Browser flow blocks on a human confirming the grant. Surface
@@ -150,6 +151,11 @@ def login(
         api_key=api_key,
         org=org or slug_from_grant or existing.org,
         base_url=base_url or existing.base_url,
+        # Preserve the user's telemetry preferences across login —
+        # signing in shouldn't silently re-enable opted-out tracking
+        # or re-trigger the first-run notice.
+        telemetry=existing.telemetry,
+        telemetry_notice_shown=existing.telemetry_notice_shown,
     )
     path = credentials.save(new_creds)
 
@@ -167,6 +173,17 @@ def login(
         )
     if new_creds.base_url:
         say_ok(f"Base URL [bold]{new_creds.base_url}[/bold]")
+
+    # Fire after credentials.save so the telemetry POST authenticates
+    # against the brand-new key. The method tag distinguishes browser-
+    # poll flow from --api-key flag (used for headless / CI setups).
+    from fruxon import telemetry as _telemetry
+
+    _telemetry.track(
+        "CLI Login Completed",
+        {"method": "api_key_flag" if api_key_flag else "browser"},
+    )
+
     say_next(
         ("fruxon agents list", "browse what's deployed"),
         ("fruxon run <agent>", "execute one"),

{fruxon-0.8.2 → fruxon-0.8.4}/src/fruxon/cli/config.py

@@ -48,7 +48,7 @@ config_app = typer.Typer(
 )
 app.add_typer(config_app, name="config")
 
-_CONFIG_KEYS = ("api_key", "org", "base_url")
+_CONFIG_KEYS = ("api_key", "org", "base_url", "telemetry")
 
 
 def _ensure_config_key(key: str) -> str:
@@ -243,10 +243,32 @@ def config_set(
                 value = stripped
         updates[key] = value
 
+    # ``telemetry`` is the one non-string-shaped field — accept true/false/
+    # 1/0/yes/no on the CLI and persist as a real bool. Anything else is a
+    # validation error rather than getting silently stored as a truthy
+    # string. (Pop it out of ``updates`` so the success line below still
+    # prints the user-visible value, not a normalized "true"/"false".)
+    telemetry_update: bool | None = None
+    if "telemetry" in updates:
+        raw_telemetry = updates["telemetry"]
+        norm = raw_telemetry.strip().lower()
+        if norm in {"true", "1", "yes", "on"}:
+            telemetry_update = True
+        elif norm in {"false", "0", "no", "off"}:
+            telemetry_update = False
+        else:
+            fail(
+                f"Invalid value for [bold]telemetry[/bold]: {raw_telemetry}",
+                hint="Use [bold]true[/bold] or [bold]false[/bold].",
+                code=EXIT_VALIDATION,
+            )
+
     new_creds = StoredCredentials(
         api_key=updates.get("api_key", creds.api_key),
         org=updates.get("org", creds.org),
         base_url=updates.get("base_url", creds.base_url),
+        telemetry=telemetry_update if "telemetry" in updates else creds.telemetry,
+        telemetry_notice_shown=creds.telemetry_notice_shown,
     )
     credentials.save(new_creds)
 
@@ -291,6 +313,11 @@ def config_unset(
         api_key=None if "api_key" in keys else creds.api_key,
         org=None if "org" in keys else creds.org,
         base_url=None if "base_url" in keys else creds.base_url,
+        # ``unset telemetry`` reverts to the default (enabled). We don't
+        # forget that the user has been told about telemetry, though —
+        # the first-run notice should still stay quiet once shown.
+        telemetry=None if "telemetry" in keys else creds.telemetry,
+        telemetry_notice_shown=creds.telemetry_notice_shown,
     )
 
     # If everything is now empty, remove the file entirely instead of

{fruxon-0.8.2 → fruxon-0.8.4}/src/fruxon/cli/doctor.py

@@ -88,6 +88,32 @@ def doctor(
     results = run_checks(skip_network=skip_network)
     overall = overall_status(results)
 
+    # Telemetry: send the outcome (and which checks failed, from a small
+    # allowlist) so we can spot setup friction patterns across the user
+    # base without ever capturing the per-check detail strings.
+    from fruxon import telemetry as _telemetry
+
+    _DOCTOR_TITLE_TO_KEY = {
+        "Python interpreter": "interpreter",
+        "Fruxon SDK": "sdk_version",
+        "Credentials file": "credentials",
+        "API key": "credentials",
+        "Organization": "credentials",
+        "Base URL": "credentials",
+        "API reachability": "api_reachability",
+        "Auth health": "auth",
+    }
+    failed_keys = sorted(
+        {_DOCTOR_TITLE_TO_KEY[r.title] for r in results if r.status != "ok" and r.title in _DOCTOR_TITLE_TO_KEY}
+    )
+    _telemetry.track(
+        "CLI Doctor Run",
+        {
+            "result": "all_pass" if overall == "ok" else "some_failed",
+            "failed_checks": failed_keys,
+        },
+    )
+
     if output == "json":
         payload = {
             "overall": overall,

{fruxon-0.8.2 → fruxon-0.8.4}/src/fruxon/credentials.py

@@ -72,6 +72,16 @@ class StoredCredentials:
     api_key: str | None = None
     org: str | None = None
     base_url: str | None = None
+    # CLI telemetry preference. ``None`` = default (enabled), ``False`` =
+    # explicit opt-out via ``fruxon config set telemetry false`` or the
+    # one-time question on first run. We track the tri-state so a future
+    # change of default never quietly overrides a user's explicit choice.
+    telemetry: bool | None = None
+    # Whether we've ever printed the first-run telemetry notice on this
+    # machine. Stored here (not as a separate flag file) so it's covered
+    # by the same atomic write + ``FRUXON_CONFIG_DIR`` override as
+    # everything else.
+    telemetry_notice_shown: bool = False
 
 
 def config_dir() -> Path:
@@ -127,6 +137,8 @@ def load() -> StoredCredentials:
         api_key=api_key,
         org=_str_or_none(file_data.get("org")),
         base_url=_str_or_none(file_data.get("base_url")),
+        telemetry=_bool_or_none(file_data.get("telemetry")),
+        telemetry_notice_shown=bool(file_data.get("telemetry_notice_shown") or False),
     )
     _cache = (creds, source)
     return creds
@@ -171,11 +183,18 @@ def save(creds: StoredCredentials) -> Path:
     # Try keyring first. On success, the file payload omits the secret
     # entirely — no copies of the key anywhere on disk. On failure, the
     # file holds it as the only persistent store.
-    payload: dict[str, str] = {}
+    payload: dict[str, object] = {}
     if creds.org:
         payload["org"] = creds.org
     if creds.base_url:
         payload["base_url"] = creds.base_url
+    if creds.telemetry is not None:
+        # Only write the key when explicitly set so the absence of the
+        # field continues to mean "default" — letting us change the
+        # default later without invalidating users' on-disk state.
+        payload["telemetry"] = bool(creds.telemetry)
+    if creds.telemetry_notice_shown:
+        payload["telemetry_notice_shown"] = True
 
     keyring_ok = False
     if creds.api_key:
@@ -264,6 +283,58 @@ def _str_or_none(value: object) -> str | None:
     return None
 
 
+def _bool_or_none(value: object) -> bool | None:
+    """Parse a stored JSON value to a tri-state bool / None.
+
+    JSON has no "missing" sentinel for the value space we care about, so
+    we keep ``None`` when the key is absent (= default behavior) and only
+    return ``True`` / ``False`` for explicit values. Strings ``"true"`` /
+    ``"false"`` are accepted defensively for users who hand-edit the file.
+    """
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        s = value.strip().lower()
+        if s in {"true", "1", "yes"}:
+            return True
+        if s in {"false", "0", "no"}:
+            return False
+    return None
+
+
+def set_telemetry(enabled: bool) -> Path:
+    """Persist the user's telemetry on/off choice.
+
+    Convenience helper so callers (``fruxon config set telemetry …`` and
+    any future setup wizard) don't need to round-trip through
+    :func:`load` + :func:`save` themselves.
+    """
+    current = load()
+    return save(
+        StoredCredentials(
+            api_key=current.api_key,
+            org=current.org,
+            base_url=current.base_url,
+            telemetry=enabled,
+            telemetry_notice_shown=current.telemetry_notice_shown,
+        )
+    )
+
+
+def mark_telemetry_notice_shown() -> Path:
+    """Flip the first-run notice flag so we don't print it again."""
+    current = load()
+    return save(
+        StoredCredentials(
+            api_key=current.api_key,
+            org=current.org,
+            base_url=current.base_url,
+            telemetry=current.telemetry,
+            telemetry_notice_shown=True,
+        )
+    )
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # File and keyring backends
 # ─────────────────────────────────────────────────────────────────────────────

{fruxon-0.8.2 → fruxon-0.8.4}/src/fruxon/fruxon.py

@@ -935,15 +935,11 @@ class FruxonClient:
         that share the same envelope (integrations, tools, …) don't each
         reimplement the unwrap.
 
-        The server-side ``PagingModelBinder`` reads ``page_token`` /
-        ``page_size`` in snake_case; camelCase variants are silently
-        ignored, which manifests as the server echoing the same token
-        back forever. Sending the snake_case name is the actual fix; the
-        cycle-detection in callers is now just defense-in-depth.
+        Query param is ``pageToken`` (camelCase per AIP-127).
         """
         params = list(base_params)
         if page_token:
-            params.append(("page_token", page_token))
+            params.append(("pageToken", page_token))
         url = base_url + ("?" + urllib.parse.urlencode(params) if params else "")
         raw = self._get_json(url)
         if isinstance(raw, dict):

fruxon-0.8.4/src/fruxon/telemetry.py

@@ -0,0 +1,340 @@
+"""Anonymous CLI usage telemetry.
+
+The CLI POSTs a single event per invocation to ``{base_url}/v1/cli-events``
+on a background thread. The backend validates each event against an
+allowlist and forwards to Mixpanel — see
+``fruxon-backend/Server/Controllers/CliTelemetryController.cs`` and
+``CliTelemetrySchema.cs``.
+
+What we track:
+    * Which command was invoked, and whether it succeeded.
+    * Local-only commands (``describe``, ``examples``, ``guides``).
+    * Diagnostic outcomes (``doctor``, version updates, login).
+    * CLI version, Python version, OS, and whether an AI driver is
+      running the show (``human`` vs ``ai_agent``).
+
+What we never send:
+    Command arguments, output, file paths, hostnames, usernames,
+    exception messages, doctor output text, the API key. See
+    https://fruxon.com/privacy-policy for the full list.
+
+Identity:
+    Telemetry only fires when ``fruxon login`` has succeeded. The
+    backend derives the Mixpanel ``distinct_id`` (user email) and
+    ``$groups: {org: slug}`` from the API key; the CLI never sends
+    those fields. Anonymous (pre-login) events are deliberately not
+    collected.
+
+Opt-out (resolution order, first wins):
+    1. ``FRUXON_NO_TELEMETRY=1``    — env var
+    2. ``DO_NOT_TRACK=1``           — env var (community convention)
+    3. ``fruxon config set telemetry false`` — persisted in
+       ``~/.fruxon/credentials``
+    4. Default: enabled.
+
+Design notes:
+    * Pure stdlib (``urllib.request``). The SDK already uses urllib for
+      ``cli_auth.py`` — no new dependency.
+    * Background thread with a small daemon queue. The CLI never waits.
+    * Failures are silently logged via the standard ``logging`` module;
+      telemetry must never affect the exit code, latency, or stderr.
+    * Built-in disable when the queue is bounded and full — if the
+      backend is slow we drop events rather than blocking shutdown.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import platform
+import queue
+import ssl
+import sys
+import threading
+import urllib.error
+import urllib.request
+from typing import Any
+
+from . import credentials
+from ._ssl import context_for as _ssl_context_for
+from .ui import get_version
+
+logger = logging.getLogger("fruxon.telemetry")
+
+# Cap how many events can pile up before we start dropping. A bounded
+# queue keeps a slow / unreachable backend from causing the CLI to hang
+# during shutdown.
+_QUEUE_CAPACITY = 64
+
+# How long the background thread waits at exit for in-flight POSTs.
+# Short on purpose: telemetry must never delay the user's prompt return.
+_SHUTDOWN_WAIT_SECONDS = 0.5
+
+# Per-request HTTP timeout. Short and decisive — a slow Mixpanel is
+# something we'd rather drop and move on from.
+_HTTP_TIMEOUT_SECONDS = 2.0
+
+# Default backend ingest URL. Overridable via ``FRUXON_BASE_URL`` (the
+# same env that overrides every other API call), which is what we want
+# for staging / self-hosted deployments.
+_DEFAULT_BASE_URL = "https://api.fruxon.com"
+_EVENT_PATH = "/v1/cli-events"
+
+
+def _detect_driver() -> str:
+    """Tag the event with whether a human or an AI agent is driving.
+
+    Mirrors :func:`fruxon.ui.is_agent_mode` — Claude Code (``CLAUDECODE=1``)
+    and CI runners (``CI=1``) are treated as "non-human" along with the
+    explicit ``FRUXON_AGENT_MODE=1``. This is the one signal that's hard
+    to get from any other telemetry pipeline, and it's what makes
+    human-vs-agent usage analyses possible in Mixpanel.
+    """
+    for var in ("FRUXON_AGENT_MODE", "CLAUDECODE"):
+        if (os.environ.get(var) or "").strip().lower() in {"1", "true", "yes"}:
+            return "ai_agent"
+    ci = (os.environ.get("CI") or "").strip().lower()
+    if ci in {"1", "true", "yes"}:
+        return "ai_agent"
+    return "human"
+
+
+def _base_properties() -> dict[str, Any]:
+    """Properties attached to every event (the schema's universal set).
+
+    These describe the local environment — version, OS, driver mode.
+    Everything else is per-event.
+    """
+    return {
+        "cli_version": get_version(),
+        "python_version": f"{sys.version_info.major}.{sys.version_info.minor}",
+        "os": platform.system().lower() or "unknown",
+        "driver": _detect_driver(),
+    }
+
+
+def _is_disabled_via_env() -> bool:
+    """Either of the documented env vars hard-disables telemetry.
+
+    Honors ``DO_NOT_TRACK`` (a community convention some users wire into
+    their shell rc) alongside the project-specific ``FRUXON_NO_TELEMETRY``.
+    """
+    for var in ("FRUXON_NO_TELEMETRY", "DO_NOT_TRACK"):
+        if (os.environ.get(var) or "").strip().lower() in {"1", "true", "yes"}:
+            return True
+    return False
+
+
+def is_enabled() -> bool:
+    """Resolve the final on/off decision for the current invocation.
+
+    Order: env-var off > config off > default on. We don't check for the
+    API key here — :class:`TelemetryClient` does that just-in-time so
+    ``is_enabled`` stays cheap (a couple of env lookups and a config
+    read) and can be called from tests without network reach.
+    """
+    if _is_disabled_via_env():
+        return False
+    pref = credentials.load().telemetry
+    if pref is False:
+        return False
+    return True
+
+
+class TelemetryClient:
+    """Background worker that POSTs CLI events to the backend.
+
+    One instance per process, created lazily by :func:`get_client`. The
+    worker thread is daemonized so the interpreter can exit cleanly even
+    if Mixpanel is unreachable.
+    """
+
+    def __init__(self) -> None:
+        self._queue: queue.Queue[dict[str, Any] | None] = queue.Queue(maxsize=_QUEUE_CAPACITY)
+        self._thread: threading.Thread | None = None
+        self._lock = threading.Lock()
+        self._dropped = 0
+
+    def track(self, event_name: str, properties: dict[str, Any] | None = None) -> None:
+        """Schedule an event for background submission.
+
+        Always safe to call — opt-out and auth checks happen here so
+        callers don't need to guard. The actual HTTP work happens on a
+        daemon thread; the call returns immediately.
+        """
+        if not is_enabled():
+            return
+
+        # We only send post-login events. Anonymous pre-auth tracking
+        # would require backend allowlisting of unauthenticated calls
+        # plus a machine UUID to alias — deliberately deferred.
+        api_key = credentials.resolve_api_key(None)
+        if not api_key:
+            return
+
+        base_url = (credentials.resolve_base_url(None) or _DEFAULT_BASE_URL).rstrip("/")
+
+        payload = {
+            "eventName": event_name,
+            "properties": {**_base_properties(), **(properties or {})},
+        }
+
+        envelope = {"url": base_url + _EVENT_PATH, "api_key": api_key, "payload": payload}
+
+        try:
+            self._queue.put_nowait(envelope)
+        except queue.Full:
+            # Drop and move on. Bounded queue is the point — a slow or
+            # unreachable backend can't grow memory or block shutdown.
+            self._dropped += 1
+            return
+
+        self._ensure_worker_started()
+
+    def shutdown(self, *, wait: float = _SHUTDOWN_WAIT_SECONDS) -> None:
+        """Signal the worker to finish, give it up to ``wait`` seconds.
+
+        Called from an :mod:`atexit` hook; do not call directly. The
+        wait is intentionally short — we'd rather drop the tail than
+        hang the user's prompt by even a second.
+        """
+        if self._thread is None or not self._thread.is_alive():
+            return
+        try:
+            self._queue.put_nowait(None)
+        except queue.Full:
+            # The queue is already full — the worker is busy or stuck;
+            # there's nothing useful to do but let the daemon thread die
+            # with the interpreter.
+            return
+        self._thread.join(timeout=wait)
+
+    def _ensure_worker_started(self) -> None:
+        with self._lock:
+            if self._thread is not None and self._thread.is_alive():
+                return
+            self._thread = threading.Thread(target=self._run, name="fruxon-telemetry", daemon=True)
+            self._thread.start()
+
+    def _run(self) -> None:
+        while True:
+            try:
+                item = self._queue.get(timeout=1.0)
+            except queue.Empty:
+                # No work pending. Exit so the daemon doesn't stay
+                # parked for the lifetime of long-running commands
+                # (``fruxon chat`` can stay open for hours). It restarts
+                # on the next track() call.
+                return
+            if item is None:
+                return
+            try:
+                self._post(item)
+            except Exception:  # noqa: BLE001 — never let telemetry crash
+                logger.debug("CLI telemetry POST failed", exc_info=True)
+            finally:
+                self._queue.task_done()
+
+    @staticmethod
+    def _post(envelope: dict[str, Any]) -> None:
+        url = envelope["url"]
+        body = json.dumps(envelope["payload"]).encode("utf-8")
+        req = urllib.request.Request(
+            url,
+            data=body,
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {envelope['api_key']}",
+                "User-Agent": f"fruxon-cli/{get_version()}",
+            },
+        )
+        context: ssl.SSLContext | None = _ssl_context_for(url)
+        try:
+            with urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT_SECONDS, context=context):
+                # We don't care about the response body; the backend
+                # returns 202 Accepted for any valid event and ignores
+                # the rest. Read implicitly closes the connection.
+                pass
+        except urllib.error.HTTPError as exc:
+            # 4xx ≠ programming bug worth surfacing here. The backend
+            # logs unknown event names; nothing the user can do.
+            logger.debug("telemetry HTTP %s for %s", exc.code, url)
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            # Offline laptop, DNS hiccup, captive portal, sleeping
+            # machine — none of these should bother the user.
+            logger.debug("telemetry network error: %s", exc)
+
+
+_client: TelemetryClient | None = None
+_client_lock = threading.Lock()
+_atexit_registered = False
+
+
+def get_client() -> TelemetryClient:
+    """Lazily create the process-wide :class:`TelemetryClient`.
+
+    Lazy so importing this module from tests has no cost. The
+    :func:`atexit` registration also runs once, here.
+    """
+    global _client, _atexit_registered
+    if _client is not None:
+        return _client
+    with _client_lock:
+        if _client is None:
+            _client = TelemetryClient()
+            if not _atexit_registered:
+                import atexit
+
+                atexit.register(_client.shutdown)
+                _atexit_registered = True
+    return _client
+
+
+# Convenience: most call sites only want a one-liner.
+def track(event_name: str, properties: dict[str, Any] | None = None) -> None:
+    """Module-level wrapper so callers can ``from .telemetry import track``."""
+    get_client().track(event_name, properties)
+
+
+# -----------------------------------------------------------------------------
+# First-run notice
+# -----------------------------------------------------------------------------
+
+_NOTICE = (
+    "ℹ️  Fruxon CLI collects usage data to improve the tool.\n"
+    "   See: https://fruxon.com/privacy-policy\n"
+    "   Disable: fruxon config set telemetry false  (or DO_NOT_TRACK=1)\n"
+)
+
+
+def maybe_print_first_run_notice() -> None:
+    """Print the telemetry notice once per machine, on a TTY.
+
+    Gated by a flag in the credentials file so we only ever say it
+    once. Piped / non-interactive runs (CI, scripts, AI agents) never
+    see it — they're not going to read it and it would only show up
+    as unexpected text on stderr.
+    """
+    if not sys.stderr.isatty():
+        return
+    if _is_disabled_via_env():
+        return
+    creds = credentials.load()
+    if creds.telemetry_notice_shown:
+        return
+    if creds.telemetry is False:
+        # User has already opted out — no reason to nag.
+        return
+
+    sys.stderr.write("\n" + _NOTICE + "\n")
+    sys.stderr.flush()
+
+    # Persist the "shown" flag so we don't re-print on the next command.
+    try:
+        credentials.mark_telemetry_notice_shown()
+    except Exception:  # noqa: BLE001
+        # If we can't write the credentials file, falling through to a
+        # second print on the next command is still cheap and harmless.
+        logger.debug("failed to persist telemetry notice flag", exc_info=True)

fruxon-0.8.4/tests/test_telemetry.py

@@ -0,0 +1,216 @@
+"""Telemetry unit tests.
+
+These exercise the resolution rules (opt-out, auth gating, env vars) and
+the bookkeeping around the first-run notice. The actual HTTP POST is
+mocked so the tests don't reach Mixpanel — that path is tested separately
+via the backend's controller tests.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from unittest import mock
+
+import pytest
+
+from fruxon import credentials, telemetry
+
+
+@pytest.fixture(autouse=True)
+def _isolate_config(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    """Point the CLI's config directory at a per-test tmpdir.
+
+    Without this, the tests would clobber the developer's real
+    ``~/.fruxon/credentials`` file every run. Also clears the in-process
+    credentials cache between tests since it survives function scope.
+    """
+    monkeypatch.setenv("FRUXON_CONFIG_DIR", str(tmp_path))
+    # Strip any developer-leaking env vars that would skew resolution.
+    for var in (
+        "FRUXON_NO_TELEMETRY",
+        "DO_NOT_TRACK",
+        "FRUXON_API_KEY",
+        "FRUXON_AGENT_MODE",
+        "CLAUDECODE",
+        "CI",
+    ):
+        monkeypatch.delenv(var, raising=False)
+    credentials._invalidate_cache()
+    return tmp_path
+
+
+@pytest.fixture()
+def _patched_client(monkeypatch: pytest.MonkeyPatch):
+    """Replace the lazy global with a fresh, mockable instance per test.
+
+    Reaching into module state isn't pretty but it's the only way to
+    keep tests independent of each other given the ``atexit``
+    side-effect on first :func:`telemetry.get_client` call.
+    """
+    monkeypatch.setattr(telemetry, "_client", None, raising=False)
+    return telemetry
+
+
+def _write_creds(*, api_key: str | None = None, telemetry_pref: bool | None = None) -> None:
+    """Persist a credentials snapshot via the public API so the test
+    exercises the same code path the real CLI does."""
+    credentials.save(
+        credentials.StoredCredentials(
+            api_key=api_key,
+            telemetry=telemetry_pref,
+        )
+    )
+    credentials._invalidate_cache()
+
+
+# -----------------------------------------------------------------------------
+# is_enabled
+# -----------------------------------------------------------------------------
+
+
+def test_is_enabled_default_is_true_when_no_signal() -> None:
+    """No env var, no config → telemetry on. That's the documented default."""
+    assert telemetry.is_enabled() is True
+
+
+def test_is_enabled_respects_fruxon_no_telemetry_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("FRUXON_NO_TELEMETRY", "1")
+    assert telemetry.is_enabled() is False
+
+
+def test_is_enabled_respects_do_not_track_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    """The community-standard DO_NOT_TRACK convention is honored."""
+    monkeypatch.setenv("DO_NOT_TRACK", "1")
+    assert telemetry.is_enabled() is False
+
+
+def test_is_enabled_respects_config_false() -> None:
+    """``fruxon config set telemetry false`` persists to the file."""
+    _write_creds(telemetry_pref=False)
+    assert telemetry.is_enabled() is False
+
+
+def test_is_enabled_env_overrides_config_true(monkeypatch: pytest.MonkeyPatch) -> None:
+    """If the user opts out via env, even an explicit ``true`` config doesn't override."""
+    _write_creds(telemetry_pref=True)
+    monkeypatch.setenv("FRUXON_NO_TELEMETRY", "1")
+    assert telemetry.is_enabled() is False
+
+
+# -----------------------------------------------------------------------------
+# track() — auth and opt-out gating
+# -----------------------------------------------------------------------------
+
+
+def test_track_noop_when_disabled(_patched_client: telemetry, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Opted-out users never even enqueue the event."""
+    _write_creds(telemetry_pref=False, api_key="fxn_test")
+    client = _patched_client.get_client()
+    with mock.patch.object(client, "_ensure_worker_started") as worker:
+        client.track("CLI Command Invoked", {"command": "doctor"})
+    worker.assert_not_called()
+
+
+def test_track_noop_when_unauthenticated(_patched_client: telemetry) -> None:
+    """No API key → no telemetry. Anonymous tracking was a deliberate
+    non-goal — pre-login events don't go to Mixpanel."""
+    client = _patched_client.get_client()
+    with mock.patch.object(client, "_ensure_worker_started") as worker:
+        client.track("CLI Command Invoked", {"command": "doctor"})
+    worker.assert_not_called()
+
+
+def test_track_enqueues_when_authenticated(_patched_client: telemetry) -> None:
+    """Happy path: authenticated + enabled → event hits the queue."""
+    _write_creds(api_key="fxn_test")
+    client = _patched_client.get_client()
+    with mock.patch.object(client, "_ensure_worker_started") as worker:
+        client.track("CLI Command Invoked", {"command": "doctor"})
+    worker.assert_called_once()
+
+
+def test_track_attaches_universal_properties(_patched_client: telemetry) -> None:
+    """Every event carries cli_version, python_version, os, driver."""
+    _write_creds(api_key="fxn_test")
+    client = _patched_client.get_client()
+
+    captured: list[dict] = []
+    with mock.patch.object(client, "_ensure_worker_started"):
+        # Drain whatever the queue captures so we can inspect it.
+        client.track("CLI Command Invoked", {"command": "doctor"})
+        captured.append(client._queue.get_nowait())
+
+    envelope = captured[0]
+    props = envelope["payload"]["properties"]
+    assert props["command"] == "doctor"
+    assert "cli_version" in props
+    assert "python_version" in props
+    assert "os" in props
+    assert props["driver"] in {"human", "ai_agent"}
+
+
+def test_track_tags_ai_driver(_patched_client: telemetry, monkeypatch: pytest.MonkeyPatch) -> None:
+    """CLAUDECODE / FRUXON_AGENT_MODE / CI flip driver to ai_agent."""
+    _write_creds(api_key="fxn_test")
+    monkeypatch.setenv("CLAUDECODE", "1")
+    client = _patched_client.get_client()
+    with mock.patch.object(client, "_ensure_worker_started"):
+        client.track("CLI Command Invoked", {"command": "doctor"})
+        envelope = client._queue.get_nowait()
+    assert envelope["payload"]["properties"]["driver"] == "ai_agent"
+
+
+# -----------------------------------------------------------------------------
+# Bounded queue — never grow without bound
+# -----------------------------------------------------------------------------
+
+
+def test_track_drops_when_queue_full(_patched_client: telemetry, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Once the queue hits capacity, new events get dropped silently.
+    The CLI must never hang waiting for telemetry to drain."""
+    _write_creds(api_key="fxn_test")
+    client = _patched_client.get_client()
+    # Patch ``put_nowait`` to always raise Full so we don't have to
+    # actually fill the queue (capacity is 64).
+    import queue as _queue
+
+    with mock.patch.object(client, "_ensure_worker_started"):
+        with mock.patch.object(client._queue, "put_nowait", side_effect=_queue.Full):
+            client.track("CLI Command Invoked", {"command": "doctor"})
+            assert client._dropped == 1
+
+
+# -----------------------------------------------------------------------------
+# First-run notice
+# -----------------------------------------------------------------------------
+
+
+def test_notice_does_not_print_when_not_a_tty(monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture) -> None:
+    """CI / piped output never sees the notice — they're not going to
+    read it and it would clutter logs."""
+    monkeypatch.setattr(sys.stderr, "isatty", lambda: False, raising=False)
+    telemetry.maybe_print_first_run_notice()
+    out = capsys.readouterr()
+    assert "Fruxon CLI collects" not in out.err
+
+
+def test_notice_does_not_print_after_opt_out(monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture) -> None:
+    """If the user has already opted out, no nag."""
+    monkeypatch.setattr(sys.stderr, "isatty", lambda: True, raising=False)
+    _write_creds(telemetry_pref=False)
+    telemetry.maybe_print_first_run_notice()
+    out = capsys.readouterr()
+    assert "Fruxon CLI collects" not in out.err
+
+
+def test_notice_prints_once_then_persists_flag(monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture) -> None:
+    """First call prints, second call is silent."""
+    monkeypatch.setattr(sys.stderr, "isatty", lambda: True, raising=False)
+    telemetry.maybe_print_first_run_notice()
+    first = capsys.readouterr()
+    assert "Fruxon CLI collects" in first.err
+
+    telemetry.maybe_print_first_run_notice()
+    second = capsys.readouterr()
+    assert "Fruxon CLI collects" not in second.err