mooring 0.2.2__tar.gz → 0.2.3__tar.gz

{mooring-0.2.2 → mooring-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mooring
-Version: 0.2.2
+Version: 0.2.3
 Summary: Git-free marimo notebook sharing via GitHub
 Requires-Python: <3.13,>=3.12
 Requires-Dist: altair

{mooring-0.2.2 → mooring-0.2.3}/docs/admins/build-and-distribute.md

@@ -27,6 +27,10 @@ Edit `src/mooring/config_default.toml` with your `client_id`, `owner`, `repo`,
 and `branch` (and adjust `[sync]` limits if needed) so analysts get a
 ready-to-use app. See [Configuration](configuration.md) for every key.
 
+To watch usage and field errors across your team, set `[logging] endpoint` to a
+collector URL or a shared folder/UNC path — see
+[Central logging](configuration.md#central-logging). Leave it empty to disable.
+
 ## 2. Build the artifacts
 
 ```bash

{mooring-0.2.2 → mooring-0.2.3}/docs/admins/configuration.md

@@ -83,6 +83,13 @@ direction.
 |-----|---------|---------|
 | `path` | `""` | Override the workspace location (single-repo form; with `[repos]`, use the per-repo `workspace` key). Empty means `~/Documents/mooring/<owner>/<repo>`. Supports `~` expansion. |
 
+### `[logging]`
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `endpoint` | `""` | Where to send usage/error events. Empty disables logging. See [Central logging](#central-logging) for the auto-detected URL-vs-path behaviour. |
+| `level` | `"info"` | `"info"` logs usage events **and** errors; `"error"` logs only errors. |
+
 ## The packaged default file
 
 `src/mooring/config_default.toml` is baked into every build. Edit it **before
@@ -102,6 +109,10 @@ max_file_mb = 45
 
 [workspace]
 path = ""                  # empty = ~/Documents/mooring/<owner>/<repo>
+
+[logging]
+endpoint = ""              # optional; see Central logging below
+level = "info"
 ```
 
 To bake **several** repos in, use the `[repos]` form shown above instead of
@@ -172,10 +183,58 @@ integration testing and CI, but work anywhere:
 | `MOORING_WORKSPACE` | The active repo's workspace path |
 | `MOORING_TOKEN` | The stored auth token — set this to skip device-flow login entirely (a personal access token works). |
 | `MOORING_TRUSTSTORE` | Set to `0` to disable [OS trust store TLS verification](#corporate-networks-tls) and fall back to the bundled CA list. |
+| `MOORING_LOG_ENDPOINT` | `[logging] endpoint` — the central log destination (see [Central logging](#central-logging)). |
+| `MOORING_LOG_LEVEL` | `[logging] level` — `info` or `error`. |
 
 See [Contributing](../developers/contributing.md#integration-testing) for using
 these to test against a scratch repo.
 
+## Central logging
+
+Set `[logging] endpoint` (baked into the build, or in a user `config.toml`) to
+collect a record of how the app is used and what fails, from every copy, in one
+place. It is **off by default** — no endpoint, no logging. When an endpoint is
+set, logging is always on for users (there is no per-user off switch).
+
+The value is **auto-detected**:
+
+- An `http://` / `https://` URL → each event is **POSTed as JSON** to that URL.
+  HTTPS uses the OS trust store like the rest of the app, so a corporate
+  proxy's root CA is honoured automatically.
+- Anything else is treated as a **folder or UNC path** → events are appended to
+  a per-user file `<os-user>@<host>.jsonl` in that folder (e.g.
+  `\\fileserver\share\mooring-logs`). One file per user means no write
+  contention between teammates on a shared drive.
+
+```toml
+[logging]
+endpoint = "https://collector.example.com/mooring"   # or \\server\share\mooring-logs
+level = "info"   # "info" = usage + errors; "error" = errors only
+```
+
+### What gets logged
+
+Each event is one JSON object: a UTC timestamp, the event name, identity, and a
+few event-specific fields. Identity is **OS username, hostname, app version, OS,
+Python version, and the GitHub login** (added once the user has logged in).
+
+```json
+{"ts":"2026-06-13T12:34:56.789Z","event":"push","version":"0.2.2",
+ "os_user":"jdoe","host":"FIN-LT-042","os":"Windows-11-10.0.26200",
+ "python":"3.12.4","user":"octocat","pushed":3,"conflicts":0,"lines":4}
+```
+
+Events cover the app/command start, login/logout, repo add/switch/remove,
+pull/push/propose (with counts), open/new, and errors (`event:"error"` with the
+exception type and message). **No file contents, file paths, or full tracebacks
+are ever sent** — only counts and coarse kinds. An error message may incidentally
+contain a URL or path.
+
+Logging is strictly best-effort: it runs on a background thread, never blocks a
+command, and silently drops events if the destination is slow or unreachable
+(the process still exits within a few seconds). `mooring selftest` prints a
+`logging` line showing the active destination.
+
 ## Corporate networks & TLS
 
 Mooring verifies TLS connections against the **operating system's trust

{mooring-0.2.2 → mooring-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mooring"
-version = "0.2.2"
+version = "0.2.3"
 description = "Git-free marimo notebook sharing via GitHub"
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{mooring-0.2.2 → mooring-0.2.3}/src/mooring/__init__.py

@@ -1,3 +1,3 @@
 """Mooring: git-free marimo notebook sharing via GitHub."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"

{mooring-0.2.2 → mooring-0.2.3}/src/mooring/cli.py

@@ -9,7 +9,7 @@ import sys
 from collections.abc import Mapping
 from pathlib import Path
 
-from mooring import __version__, config, paths
+from mooring import __version__, config, paths, telemetry
 
 SELFTEST_PACKAGES = (
     "marimo",
@@ -162,7 +162,7 @@ def legacy_workspace_hint(cfg: config.Config) -> str:
     return ""
 
 
-def cmd_selftest(cfg: config.Config) -> int:
+def cmd_selftest(app_cfg: config.AppConfig, cfg: config.Config) -> int:
     import importlib.metadata
 
     print(f"mooring {__version__}  (python {sys.version.split()[0]}, {sys.executable})")
@@ -183,6 +183,12 @@ def cmd_selftest(cfg: config.Config) -> int:
         else "OS trust store (truststore)"
     )
     print(f"  tls trust   : {tls}")
+    log_dest = app_cfg.log_endpoint.strip()
+    if log_dest:
+        kind = "url" if log_dest.lower().startswith(("http://", "https://")) else "path"
+        print(f"  logging     : on -> {log_dest} ({kind})")
+    else:
+        print("  logging     : off (no endpoint configured)")
     if cfg.is_configured:
         print(f"  team repo   : {cfg.repo_slug} (branch {cfg.branch}, host {cfg.host})")
     else:
@@ -230,6 +236,8 @@ def cmd_login(cfg: config.Config) -> int:
     from mooring.github import GitHubClient
 
     user = GitHubClient(token, cfg.owner, cfg.repo, host=cfg.host).get_user()
+    telemetry.set_user(user["login"])
+    telemetry.log_event("login")
     print(f"Logged in as {user['login']}.")
     return 0
 
@@ -238,6 +246,7 @@ def cmd_logout(cfg: config.Config) -> int:
     from mooring import auth
 
     auth.delete_token(host=cfg.host)
+    telemetry.log_event("logout")
     print("Logged out.")
     return 0
 
@@ -246,6 +255,8 @@ def cmd_whoami(cfg: config.Config) -> int:
     from mooring.github import GitHubClient
 
     user = GitHubClient(_require_token(cfg), cfg.owner, cfg.repo, host=cfg.host).get_user()
+    telemetry.set_user(user["login"])
+    telemetry.log_event("whoami")
     print(user["login"])
     return 0
 
@@ -277,6 +288,13 @@ def cmd_pull(cfg: config.Config, theirs: bool, keep_both: bool) -> int:
         else sync.ConflictStrategy.SKIP
     )
     result = sync.pull(_client(cfg), cfg, strategy=strategy)
+    telemetry.log_event(
+        "pull",
+        pulled=result.pulled,
+        conflicts=len(result.skipped_conflicts),
+        lines=len(result.lines),
+        strategy=strategy.value,
+    )
     for line in result.lines:
         print(f"  {line}")
     print(result.summary())
@@ -287,6 +305,12 @@ def cmd_push(cfg: config.Config, only_paths: list[str], message: str | None) ->
     from mooring import sync
 
     result = sync.push(_client(cfg), cfg, paths=only_paths or None, message=message)
+    telemetry.log_event(
+        "push",
+        pushed=result.pushed,
+        conflicts=len(result.blocked_conflicts),
+        lines=len(result.lines),
+    )
     for line in result.lines:
         print(f"  {line}")
     print(result.summary())
@@ -297,6 +321,12 @@ def cmd_propose(cfg: config.Config, only_paths: list[str], message: str | None)
     from mooring import sync
 
     result = sync.propose(_client(cfg), cfg, paths=only_paths or None, message=message)
+    telemetry.log_event(
+        "propose",
+        proposed=result.proposed,
+        conflicts=len(result.blocked_conflicts),
+        review_branch=bool(result.review_branch),
+    )
     for line in result.lines:
         print(f"  {line}")
     print(result.summary())
@@ -319,11 +349,13 @@ def cmd_open(cfg: config.Config, rel_path: str) -> int:
             pbip.launch(target)
         except pbip.PbipLaunchError as exc:
             sys.exit(str(exc))
+        telemetry.log_event("open", kind="pbip")
         print(f"Opened {rel_path} in Power BI Desktop.")
         return 0
     server = EditorServer(workspace)
     server.ensure_started()
     url = server.url_for(rel_path)
+    telemetry.log_event("open", kind="notebook")
     print(f"Editor running at {url} (Ctrl+C to stop)")
     webbrowser.open(url)
     try:
@@ -338,6 +370,7 @@ def cmd_new(cfg: config.Config, name: str) -> int:
 
     workspace = cfg.workspace()
     rel_path = notebook_template.create(workspace, name)
+    telemetry.log_event("new")
     print(f"Created {rel_path}")
     return cmd_open(cfg, rel_path)
 
@@ -368,6 +401,7 @@ def cmd_repo(app_cfg: config.AppConfig, args: argparse.Namespace) -> int:
             )
         except ValueError as exc:
             sys.exit(str(exc))
+        telemetry.log_event("repo_add", alias=alias)
         active = " (now active)" if not args.no_use else ""
         print(f"Registered {owner}/{repo} as {alias!r}{active}.")
         return 0
@@ -376,6 +410,7 @@ def cmd_repo(app_cfg: config.AppConfig, args: argparse.Namespace) -> int:
             config_store.set_active(args.alias)
         except KeyError:
             sys.exit(_unknown_alias(args.alias, app_cfg))
+        telemetry.log_event("repo_switch", alias=args.alias)
         print(f"Active repo is now {args.alias!r}.")
         return 0
     if args.repo_command == "remove":
@@ -384,6 +419,7 @@ def cmd_repo(app_cfg: config.AppConfig, args: argparse.Namespace) -> int:
             config_store.remove_repo(args.alias)
         except KeyError:
             sys.exit(_unknown_alias(args.alias, app_cfg))
+        telemetry.log_event("repo_remove", alias=args.alias)
         print(f"Removed {args.alias!r}. Workspace folder {ws} was kept; delete it manually.")
         return 0
     return 2
@@ -394,28 +430,20 @@ def _unknown_alias(alias: str, app_cfg: config.AppConfig) -> str:
     return f"Unknown repo alias {alias!r}. Known: {known}"
 
 
-def main(argv: list[str] | None = None) -> int:
-    _inject_truststore()
-    _ensure_child_pythonpath()
-    parser = _build_parser()
-    args = parser.parse_args(argv)
-    command = args.command or "hub"
-    try:
-        app_cfg = config.load_app_config()
-    except ValueError as exc:  # e.g. a malformed [github] host
-        sys.exit(str(exc))
-    try:
-        cfg = app_cfg.config_for(getattr(args, "repo", None))
-    except KeyError:
-        sys.exit(_unknown_alias(args.repo, app_cfg))
-
+def _dispatch(
+    parser: argparse.ArgumentParser,
+    command: str,
+    app_cfg: config.AppConfig,
+    cfg: config.Config,
+    args: argparse.Namespace,
+) -> int:
     if command == "version":
         print(f"mooring {__version__}")
         return 0
     if command == "repo":
         return cmd_repo(app_cfg, args)
     if command == "selftest":
-        return cmd_selftest(cfg)
+        return cmd_selftest(app_cfg, cfg)
     if command == "hub":
         from mooring.hub.server import run_hub
 
@@ -444,5 +472,36 @@ def main(argv: list[str] | None = None) -> int:
     return 2
 
 
+def main(argv: list[str] | None = None) -> int:
+    _inject_truststore()
+    _ensure_child_pythonpath()
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    command = args.command or "hub"
+    try:
+        app_cfg = config.load_app_config()
+    except ValueError as exc:  # e.g. a malformed [github] host
+        sys.exit(str(exc))
+    try:
+        cfg = app_cfg.config_for(getattr(args, "repo", None))
+    except KeyError:
+        sys.exit(_unknown_alias(args.repo, app_cfg))
+
+    telemetry.configure(
+        app_cfg.log_endpoint,
+        identity=telemetry.base_identity(),
+        level=app_cfg.log_level,
+    )
+    telemetry.log_event("app_start", command=command)
+
+    try:
+        return _dispatch(parser, command, app_cfg, cfg, args)
+    except SystemExit:
+        raise  # user-facing errors (sys.exit / argparse) are not app failures
+    except BaseException as exc:  # noqa: BLE001 - record genuine failures, then re-raise
+        telemetry.log_error(exc=exc, command=command)
+        raise
+
+
 if __name__ == "__main__":
     sys.exit(main())

{mooring-0.2.2 → mooring-0.2.3}/src/mooring/config.py

@@ -66,6 +66,8 @@ class AppConfig:
     folders: tuple[str, ...] = ("notebooks", "data", "reports")
     warn_file_mb: int = 10
     max_file_mb: int = 45
+    log_endpoint: str = ""
+    log_level: str = "info"
 
     @property
     def aliases(self) -> list[str]:
@@ -174,6 +176,7 @@ def load_app_config(
     gh = data.get("github", {})
     sync = data.get("sync", {})
     ws = data.get("workspace", {})
+    log = data.get("logging", {})
 
     specs, active = repo_specs_from_data(data)
     if env.get("MOORING_ACTIVE_REPO") in {s.alias for s in specs}:
@@ -211,6 +214,8 @@ def load_app_config(
         folders=tuple(sync.get("folders", ("notebooks", "data", "reports"))),
         warn_file_mb=int(sync.get("warn_file_mb", 10)),
         max_file_mb=int(sync.get("max_file_mb", 45)),
+        log_endpoint=env.get("MOORING_LOG_ENDPOINT", str(log.get("endpoint", ""))),
+        log_level=env.get("MOORING_LOG_LEVEL", str(log.get("level", "info"))),
     )
 
 

{mooring-0.2.2 → mooring-0.2.3}/src/mooring/config_default.toml

@@ -30,3 +30,13 @@ max_file_mb = 45
 
 [workspace]
 path = ""        # empty = ~/Documents/mooring/<owner>/<repo>
+
+# Central logging. Set `endpoint` to collect usage events and errors from every
+# copy of the app in one place. The value is auto-detected:
+#   http(s)://...  -> each event is POSTed as JSON
+#   anything else  -> treated as a folder/UNC path; events are appended as a
+#                     per-user JSONL file (e.g. \\server\share\mooring-logs).
+# Empty = disabled (the shipped default). When set, it is always on for users.
+[logging]
+endpoint = ""
+level = "info"   # "info" logs usage + errors; "error" logs only errors

{mooring-0.2.2 → mooring-0.2.3}/src/mooring/hub/server.py

@@ -22,7 +22,7 @@ from starlette.responses import FileResponse, JSONResponse
 from starlette.routing import Mount, Route
 from starlette.staticfiles import StaticFiles
 
-from mooring import __version__, auth, config, config_store, pbip, sync
+from mooring import __version__, auth, config, config_store, pbip, sync, telemetry
 from mooring.cli import SELFTEST_PACKAGES, legacy_workspace_hint
 from mooring.editor import EditorServer, _free_port
 from mooring.github import AuthFailed, GitHubClient, GitHubError, compare_url
@@ -64,6 +64,7 @@ class Hub:
     def username(self) -> str:
         if not self._user_login:
             self._user_login = self.client().get_user()["login"]
+            telemetry.set_user(self._user_login)
         return self._user_login
 
     def ensure_editor(self) -> EditorServer:
@@ -150,6 +151,7 @@ class Hub:
             body["logged_in"] = False
             body["error"] = "Your GitHub login expired. Please log in again."
         except GitHubError as exc:
+            telemetry.log_error(exc=exc, op="state")
             body["error"] = str(exc)
         return JSONResponse(body)
 
@@ -177,6 +179,7 @@ class Hub:
         except ValueError as exc:
             return JSONResponse({"error": str(exc)}, status_code=400)
         self.reload()
+        telemetry.log_event("repo_add", alias=fields["alias"] or fields["repo"])
         return JSONResponse({"ok": True, "active_repo": self.app_cfg.active_alias})
 
     async def api_repo_switch(self, request: Request) -> JSONResponse:
@@ -187,6 +190,7 @@ class Hub:
         except KeyError:
             return JSONResponse({"error": f"Unknown repo alias {alias!r}."}, status_code=400)
         self.reload()
+        telemetry.log_event("repo_switch", alias=alias)
         return JSONResponse({"ok": True, "active_repo": alias})
 
     async def api_repo_remove(self, request: Request) -> JSONResponse:
@@ -198,6 +202,7 @@ class Hub:
         except KeyError:
             return JSONResponse({"error": f"Unknown repo alias {alias!r}."}, status_code=400)
         self.reload()
+        telemetry.log_event("repo_remove", alias=alias)
         return JSONResponse(
             {"ok": True, "lines": [f"Removed {alias!r}; workspace folder kept at {workspace}"]}
         )
@@ -235,6 +240,7 @@ class Hub:
             with self._lock:
                 self._device = None
             self._user_login = ""
+            telemetry.log_event("login")
             return JSONResponse({"status": "ok"})
         with self._lock:
             self._poll_interval = result.interval
@@ -244,36 +250,49 @@ class Hub:
     def api_logout(self, request: Request) -> JSONResponse:
         auth.delete_token(host=self.cfg.host)
         self._user_login = ""
+        telemetry.log_event("logout")
         return JSONResponse({"ok": True})
 
     async def api_pull(self, request: Request) -> JSONResponse:
         data = await request.json() if await request.body() else {}
         strategy = sync.ConflictStrategy(data.get("strategy", "skip"))
-        return self._sync_op(lambda: sync.pull(self.client(), self.cfg, strategy=strategy))
+        return self._sync_op("pull", lambda: sync.pull(self.client(), self.cfg, strategy=strategy))
 
     async def api_push(self, request: Request) -> JSONResponse:
         data = await request.json() if await request.body() else {}
         paths_arg = data.get("paths") or None
-        return self._sync_op(lambda: sync.push(self.client(), self.cfg, paths=paths_arg))
+        return self._sync_op("push", lambda: sync.push(self.client(), self.cfg, paths=paths_arg))
 
     async def api_propose(self, request: Request) -> JSONResponse:
         data = await request.json() if await request.body() else {}
         paths_arg = data.get("paths") or None
-        return self._sync_op(lambda: sync.propose(self.client(), self.cfg, paths=paths_arg))
+        return self._sync_op(
+            "propose", lambda: sync.propose(self.client(), self.cfg, paths=paths_arg)
+        )
 
     async def api_resolve(self, request: Request) -> JSONResponse:
         data = await request.json()
         strategy = sync.ConflictStrategy(data["strategy"])
         username = self.username() if strategy is sync.ConflictStrategy.PUSH_COPY else ""
         return self._sync_op(
-            lambda: sync.resolve(self.client(), self.cfg, data["path"], strategy, username)
+            "resolve",
+            lambda: sync.resolve(self.client(), self.cfg, data["path"], strategy, username),
         )
 
-    def _sync_op(self, op) -> JSONResponse:
+    def _sync_op(self, name: str, op) -> JSONResponse:
         try:
             result = op()
         except (GitHubError, OSError) as exc:
+            telemetry.log_error(exc=exc, op=name)
             return JSONResponse({"error": str(exc)}, status_code=502)
+        telemetry.log_event(
+            name,
+            pulled=result.pulled,
+            pushed=result.pushed,
+            proposed=result.proposed,
+            conflicts=len(result.skipped_conflicts) + len(result.blocked_conflicts),
+            lines=len(result.lines),
+        )
         body = {"lines": result.lines, "summary": result.summary()}
         if result.review_branch:
             body["review_branch"] = result.review_branch
@@ -288,6 +307,7 @@ class Hub:
             rel_path = notebook_template.create(self.cfg.workspace(), data.get("name", ""))
         except (ValueError, FileExistsError) as exc:
             return JSONResponse({"error": str(exc)}, status_code=400)
+        telemetry.log_event("new")
         return self._open(rel_path)
 
     async def api_open(self, request: Request) -> JSONResponse:
@@ -309,6 +329,7 @@ class Hub:
             except pbip.PbipLaunchError as exc:
                 return JSONResponse({"error": str(exc)}, status_code=400)
             name = rel_path.rsplit("/", 1)[-1]
+            telemetry.log_event("open", kind="pbip")
             return JSONResponse(
                 {"path": rel_path, "lines": [f"Opened {name} in Power BI Desktop"]}
             )
@@ -321,6 +342,7 @@ class Hub:
             editor = self.ensure_editor()
         except Exception as exc:  # noqa: BLE001 - shown in the UI
             return JSONResponse({"error": f"Could not start the editor: {exc}"}, status_code=502)
+        telemetry.log_event("open", kind="notebook")
         return JSONResponse({"path": rel_path, "url": editor.url_for(rel_path)})
 
 
@@ -333,6 +355,7 @@ def create_app(hub: Hub) -> Starlette:
             yield
         finally:
             hub.shutdown()
+            telemetry.flush(timeout=3.0)
 
     return Starlette(
         routes=[
@@ -363,6 +386,7 @@ def run_hub(
     app = create_app(hub)
     port = port or _free_port()
     url = f"http://127.0.0.1:{port}/"
+    telemetry.log_event("hub_start")
     print(f"mooring hub running at {url} (Ctrl+C to quit)")
     if open_browser:
         threading.Timer(0.8, webbrowser.open, args=(url,)).start()

mooring-0.2.3/src/mooring/telemetry.py

@@ -0,0 +1,243 @@
+"""Fire-and-forget usage/error telemetry to an admin-configured central sink.
+
+The admin who builds the .pyz bakes a destination into ``[logging] endpoint``:
+an ``http(s)://`` URL receives each event as a JSON POST; any other value is
+treated as a folder/UNC path and gets a per-user JSONL file appended to it
+(``<os_user>@<host>.jsonl``). An empty endpoint disables telemetry entirely —
+that is the shipped default, and what keeps the test suite hermetic.
+
+Everything here is best-effort and must never block or crash the app (the same
+spirit as the truststore guard in ``cli.py``): ``log_event`` only enqueues, a
+daemon thread drains the queue, and all sink I/O is wrapped so a slow or
+unreachable destination can at worst drop events. An ``atexit`` flush with a
+wall-clock-bounded wait makes sure a short-lived CLI run still ships its events
+without an unreachable endpoint hanging the exit.
+"""
+
+from __future__ import annotations
+
+import atexit
+import getpass
+import json
+import platform
+import queue
+import socket
+import threading
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+from mooring import __version__
+
+# Severity gate: "info" lets everything through, "error" keeps only errors.
+_INFO = 20
+_ERROR = 40
+_LEVELS = {"info": _INFO, "error": _ERROR}
+
+_lock = threading.Lock()
+_queue: queue.Queue = queue.Queue()
+_thread: threading.Thread | None = None
+_sink = None  # callable(event: dict) -> None
+_identity: dict = {}
+_user_login = ""
+_enabled = False
+_level = _INFO
+_session = None  # lazy/injected requests.Session for URL sinks
+_atexit_registered = False
+
+
+# -- sinks -------------------------------------------------------------------
+
+
+class _UrlSink:
+    def __init__(self, url: str) -> None:
+        self.url = url
+
+    def __call__(self, event: dict) -> None:
+        # truststore.inject_into_ssl() has already run in cli.main(), so this
+        # POST verifies against the corporate trust store like the rest of the app.
+        _get_session().post(self.url, json=event, timeout=(3.05, 3))
+
+
+class _PathSink:
+    def __init__(self, folder: str) -> None:
+        self.folder = Path(folder)
+
+    def __call__(self, event: dict) -> None:
+        self.folder.mkdir(parents=True, exist_ok=True)
+        name = _safe_filename(event.get("os_user", "user"), event.get("host", "host"))
+        # One open-append-close per event: a share blip loses at most one line,
+        # and the per-user filename means concurrent users never clobber each other.
+        with (self.folder / name).open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(event) + "\n")
+
+
+def _safe_filename(os_user: str, host: str) -> str:
+    def clean(value: str) -> str:
+        return "".join(c for c in str(value) if c.isalnum() or c in "-_.") or "unknown"
+
+    return f"{clean(os_user)}@{clean(host)}.jsonl"
+
+
+def _resolve_sink(destination: str):
+    dest = (destination or "").strip()
+    if not dest:
+        return None
+    if dest.lower().startswith(("http://", "https://")):
+        return _UrlSink(dest)
+    return _PathSink(dest)
+
+
+def _get_session():
+    global _session
+    if _session is None:
+        import requests
+
+        _session = requests.Session()
+    return _session
+
+
+# -- public API --------------------------------------------------------------
+
+
+def base_identity() -> dict:
+    """The machine/app fields stamped onto every event."""
+    return {
+        "version": __version__,
+        "os_user": _safe(getpass.getuser),
+        "host": _safe(socket.gethostname),
+        "os": _safe(platform.platform),
+        "python": platform.python_version(),
+    }
+
+
+def configure(destination: str, *, identity: dict, level: str = "info", session=None) -> None:
+    """Point telemetry at a destination. Blank destination = disabled (no-op).
+
+    Idempotent and total: any failure here just leaves telemetry disabled — it
+    must never raise into the caller.
+    """
+    global _sink, _identity, _enabled, _level, _thread, _session, _atexit_registered
+    try:
+        with _lock:
+            _identity = dict(identity or {})
+            _level = _LEVELS.get(str(level).strip().lower(), _INFO)
+            _session = session
+            sink = _resolve_sink(destination)
+            if sink is None:
+                _enabled = False
+                _sink = None
+                return
+            _sink = sink
+            _enabled = True
+            _ensure_thread()
+            if not _atexit_registered:
+                atexit.register(flush)
+                _atexit_registered = True
+    except Exception:  # noqa: BLE001 - telemetry must never break the app
+        _enabled = False
+        _sink = None
+
+
+def _ensure_thread() -> None:
+    """Start the single background sender once and keep it for the process.
+
+    A singleton matters: configure() runs once in production, but the test suite
+    reconfigures repeatedly, and two live daemons draining one queue would
+    reorder events. The daemon reads the module-level _sink each loop, so
+    swapping sinks needs no new thread.
+    """
+    global _thread
+    if _thread is None or not _thread.is_alive():
+        _thread = threading.Thread(target=_run, name="mooring-telemetry", daemon=True)
+        _thread.start()
+
+
+def set_user(login: str) -> None:
+    """Record the GitHub login once it's known; overlaid onto later events."""
+    global _user_login
+    if login:
+        _user_login = str(login)
+
+
+def log_event(name: str, **fields) -> None:
+    _emit(name, _INFO, fields)
+
+
+def log_error(*, exc: BaseException, **fields) -> None:
+    """Record an error as type + message only — never a traceback."""
+    fields = dict(fields)
+    fields["error_type"] = type(exc).__name__
+    fields["error_msg"] = str(exc)
+    _emit("error", _ERROR, fields)
+
+
+def flush(timeout: float = 3.0) -> None:
+    """Wait (at most ``timeout`` seconds) for queued events to be sent."""
+    try:
+        if not _enabled:
+            return
+        deadline = time.monotonic() + timeout
+        while _queue.unfinished_tasks > 0 and time.monotonic() < deadline:
+            time.sleep(0.02)
+    except Exception:  # noqa: BLE001 - flushing is best-effort
+        pass
+
+
+# -- internals ---------------------------------------------------------------
+
+
+def _emit(name: str, severity: int, fields: dict) -> None:
+    if not _enabled or severity < _level:
+        return
+    try:
+        event = dict(_identity)
+        event["ts"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+        event["event"] = name
+        event["user"] = _user_login
+        event.update(fields)
+        _queue.put_nowait(event)
+    except Exception:  # noqa: BLE001 - dropping an event must never raise
+        pass
+
+
+def _run() -> None:
+    while True:
+        item = _queue.get()
+        try:
+            sink = _sink
+            if item is not None and sink is not None:
+                sink(item)
+        except Exception:  # noqa: BLE001 - drop the event, never die
+            pass
+        finally:
+            _queue.task_done()
+
+
+def _safe(fn, default: str = "unknown") -> str:
+    try:
+        return str(fn())
+    except Exception:  # noqa: BLE001
+        return default
+
+
+def _reset_for_tests() -> None:
+    """Drop sink/state and drain the queue so tests don't leak into each other.
+
+    The singleton daemon is deliberately left running (it reads _sink=None now,
+    so it's a no-op until the next configure()).
+    """
+    global _sink, _identity, _user_login, _enabled, _level, _session
+    with _lock:
+        _enabled = False
+        _sink = None
+        _identity = {}
+        _user_login = ""
+        _level = _INFO
+        _session = None
+        try:
+            while True:
+                _queue.get_nowait()
+                _queue.task_done()
+        except queue.Empty:
+            pass

{mooring-0.2.2 → mooring-0.2.3}/tests/conftest.py

@@ -9,6 +9,25 @@ from mooring.github import NotFound, RefAlreadyExists, RemoteConflict, TreeEntry
 DEFAULT_BRANCH = "main"
 
 
+@pytest.fixture(autouse=True)
+def _hermetic_telemetry(monkeypatch):
+    """Keep telemetry off and isolated for the whole suite.
+
+    With no MOORING_LOG_ENDPOINT, ``telemetry.configure()`` is a no-op, so the
+    suite never POSTs or writes to the real log dir. Tests that want to exercise
+    telemetry set MOORING_LOG_ENDPOINT to a tmp path themselves. The teardown
+    drops the daemon/state so nothing leaks across tests.
+    """
+    monkeypatch.delenv("MOORING_LOG_ENDPOINT", raising=False)
+    monkeypatch.delenv("MOORING_LOG_LEVEL", raising=False)
+    monkeypatch.setenv("MOORING_TRUSTSTORE", "0")  # main() injects into global ssl
+    yield
+    from mooring import telemetry
+
+    telemetry.flush(0.2)
+    telemetry._reset_for_tests()
+
+
 class FakeClient:
     def __init__(self, files: dict[str, bytes] | None = None):
         self.blobs: dict[str, bytes] = {}

{mooring-0.2.2 → mooring-0.2.3}/tests/test_cli_repo.py

@@ -1,10 +1,11 @@
 """CLI repo-management commands driven through cli.main()."""
 
+import json
 import tomllib
 
 import pytest
 
-from mooring import cli, paths
+from mooring import cli, paths, telemetry
 
 
 @pytest.fixture(autouse=True)
@@ -84,3 +85,20 @@ def test_status_with_unknown_repo_alias_exits():
 def test_repo_list_when_empty(capsys):
     assert cli.main(["repo", "list"]) == 0
     assert "No repos registered" in capsys.readouterr().out
+
+
+def test_telemetry_records_events_through_main(tmp_path, monkeypatch):
+    """A baked path endpoint makes cli.main() emit app_start + the command event."""
+    logdir = tmp_path / "telemetry"
+    monkeypatch.setenv("MOORING_LOG_ENDPOINT", str(logdir))
+    assert cli.main(["repo", "add", "acme/nbs"]) == 0
+    telemetry.flush(2.0)
+    files = list(logdir.glob("*.jsonl"))
+    assert len(files) == 1
+    events = [json.loads(line) for line in files[0].read_text("utf-8").splitlines() if line.strip()]
+    by_name = {e["event"]: e for e in events}
+    assert "app_start" in by_name and "repo_add" in by_name
+    assert by_name["app_start"]["command"] == "repo"
+    assert by_name["repo_add"]["alias"] == "nbs"
+    assert by_name["app_start"]["ts"].endswith("Z")
+    assert by_name["app_start"]["version"]  # identity stamped

{mooring-0.2.2 → mooring-0.2.3}/tests/test_config.py

@@ -153,6 +153,36 @@ def test_active_repo_env_override(tmp_path):
     assert app2.config_for("sandbox").branch == "dev"  # untouched
 
 
+# -- central logging ([logging] section) ------------------------------------
+
+
+def test_logging_defaults_off(tmp_path):
+    app = load_app_config(user_config_path=tmp_path / "missing.toml", env={})
+    assert app.log_endpoint == ""
+    assert app.log_level == "info"
+
+
+def test_logging_from_user_config(tmp_path):
+    user = tmp_path / "config.toml"
+    user.write_text(
+        '[logging]\nendpoint = "https://collector.example/m"\nlevel = "error"\n', "utf-8"
+    )
+    app = load_app_config(user_config_path=user, env={})
+    assert app.log_endpoint == "https://collector.example/m"
+    assert app.log_level == "error"
+
+
+def test_logging_env_overrides(tmp_path):
+    user = tmp_path / "config.toml"
+    user.write_text('[logging]\nendpoint = "https://baked.example"\n', "utf-8")
+    app = load_app_config(
+        user_config_path=user,
+        env={"MOORING_LOG_ENDPOINT": r"\\server\share\logs", "MOORING_LOG_LEVEL": "error"},
+    )
+    assert app.log_endpoint == r"\\server\share\logs"
+    assert app.log_level == "error"
+
+
 def test_default_workspace_keyed_by_owner():
     a = paths.default_workspace("acme", "notebooks")
     b = paths.default_workspace("phil", "notebooks")

mooring-0.2.3/tests/test_telemetry.py

@@ -0,0 +1,183 @@
+"""Telemetry sink dispatch, identity tagging, and fail-safe behavior."""
+
+import json
+import threading
+import time
+
+import pytest
+
+from mooring import telemetry
+
+IDENTITY = {
+    "version": "9.9.9",
+    "os_user": "tester",
+    "host": "test-host",
+    "os": "TestOS",
+    "python": "3.12.0",
+}
+
+
+@pytest.fixture(autouse=True)
+def _reset():
+    telemetry._reset_for_tests()
+    yield
+    telemetry.flush(0.5)
+    telemetry._reset_for_tests()
+
+
+class FakeSession:
+    """Stand-in for a requests.Session that records POSTs."""
+
+    def __init__(self, raise_exc=None, block=None):
+        self.posts = []
+        self._raise = raise_exc
+        self._block = block  # an Event the sender waits on, to simulate a hung POST
+
+    def post(self, url, json=None, timeout=None):
+        if self._block is not None:
+            self._block.wait(5)
+        if self._raise:
+            raise self._raise
+        self.posts.append((url, json, timeout))
+        return type("R", (), {"status_code": 200})()
+
+
+def _drain():
+    telemetry.flush(2.0)
+
+
+def test_disabled_when_no_destination(tmp_path):
+    telemetry.configure("", identity=IDENTITY)
+    telemetry.log_event("app_start", command="hub")
+    _drain()
+    assert telemetry._enabled is False
+    assert list(tmp_path.iterdir()) == []  # nothing written anywhere
+
+
+def test_url_sink_posts_json():
+    sess = FakeSession()
+    telemetry.configure("https://collector.example/mooring", identity=IDENTITY, session=sess)
+    telemetry.log_event("push", pushed=3, conflicts=0, lines=4)
+    _drain()
+    assert len(sess.posts) == 1
+    url, body, timeout = sess.posts[0]
+    assert url == "https://collector.example/mooring"
+    assert body["event"] == "push"
+    assert body["pushed"] == 3
+    assert body["version"] == "9.9.9"
+    assert body["os_user"] == "tester"
+    assert body["host"] == "test-host"
+    assert body["ts"].endswith("Z")
+    assert timeout is not None  # bounded so a hung endpoint can't stall the sender
+
+
+def test_path_sink_appends_jsonl(tmp_path):
+    folder = tmp_path / "logs"
+    telemetry.configure(str(folder), identity=IDENTITY)
+    telemetry.log_event("app_start", command="status")
+    telemetry.log_event("pull", pulled=1)
+    _drain()
+    files = list(folder.glob("*.jsonl"))
+    assert len(files) == 1
+    assert files[0].name == "tester@test-host.jsonl"
+    lines = files[0].read_text("utf-8").strip().splitlines()
+    assert len(lines) == 2  # second event appends, never truncates
+    assert json.loads(lines[0])["command"] == "status"
+    assert json.loads(lines[1])["event"] == "pull"
+
+
+def test_per_user_filename_sanitized(tmp_path):
+    ident = dict(IDENTITY, os_user="DOMAIN\\jdoe", host="host:42")
+    telemetry.configure(str(tmp_path), identity=ident)
+    telemetry.log_event("app_start", command="hub")
+    _drain()
+    files = list(tmp_path.glob("*.jsonl"))
+    assert len(files) == 1
+    name = files[0].name
+    assert "\\" not in name and ":" not in name and "/" not in name
+
+
+@pytest.mark.parametrize(
+    "dest,is_url",
+    [
+        ("http://x/y", True),
+        ("https://x/y", True),
+        ("HTTPS://X/Y", True),
+        (r"\\srv\share\logs", False),
+        ("D:/logs", False),
+        ("/var/log/mooring", False),
+    ],
+)
+def test_url_vs_path_autodetect(dest, is_url):
+    sink = telemetry._resolve_sink(dest)
+    assert isinstance(sink, telemetry._UrlSink) is is_url
+
+
+def test_identity_on_every_event(tmp_path):
+    telemetry.configure(str(tmp_path), identity=IDENTITY)
+    telemetry.log_event("a")
+    telemetry.log_event("b")
+    _drain()
+    lines = (tmp_path / "tester@test-host.jsonl").read_text("utf-8").strip().splitlines()
+    for raw in lines:
+        e = json.loads(raw)
+        assert e["version"] == "9.9.9"
+        assert e["os_user"] == "tester"
+        assert e["ts"].endswith("Z")
+        assert "event" in e
+
+
+def test_set_user_tags_subsequent_events(tmp_path):
+    telemetry.configure(str(tmp_path), identity=IDENTITY)
+    telemetry.log_event("before")
+    telemetry.set_user("octocat")
+    telemetry.log_event("after")
+    _drain()
+    before, after = (
+        json.loads(raw)
+        for raw in (tmp_path / "tester@test-host.jsonl").read_text("utf-8").strip().splitlines()
+    )
+    assert before["user"] == ""
+    assert after["user"] == "octocat"
+
+
+def test_swallow_on_sink_error():
+    sess = FakeSession(raise_exc=RuntimeError("network down"))
+    telemetry.configure("https://x", identity=IDENTITY, session=sess)
+    telemetry.log_event("push")  # must not raise
+    _drain()  # must not raise
+    assert sess.posts == []
+
+
+def test_flush_timeout_is_bounded():
+    release = threading.Event()
+    sess = FakeSession(block=release)
+    telemetry.configure("https://x", identity=IDENTITY, session=sess)
+    telemetry.log_event("push")
+    start = time.monotonic()
+    telemetry.flush(0.2)
+    assert time.monotonic() - start < 1.5  # a hung POST can't stall the exit
+    release.set()  # let the sender finish so it doesn't block later tests
+
+
+def test_level_error_drops_usage_events(tmp_path):
+    telemetry.configure(str(tmp_path), identity=IDENTITY, level="error")
+    telemetry.log_event("push", pushed=1)  # usage event, should be dropped
+    telemetry.log_error(exc=ValueError("boom"))  # error, should pass
+    _drain()
+    lines = (tmp_path / "tester@test-host.jsonl").read_text("utf-8").strip().splitlines()
+    events = [json.loads(raw)["event"] for raw in lines]
+    assert events == ["error"]
+
+
+def test_log_error_type_and_message_no_traceback(tmp_path):
+    telemetry.configure(str(tmp_path), identity=IDENTITY)
+    telemetry.log_error(exc=ValueError("boom"), op="push")
+    _drain()
+    event = json.loads((tmp_path / "tester@test-host.jsonl").read_text("utf-8").strip())
+    assert event["event"] == "error"
+    assert event["error_type"] == "ValueError"
+    assert event["error_msg"] == "boom"
+    assert event["op"] == "push"
+    assert "traceback" not in event
+    assert not any("Traceback" in str(v) for v in event.values())

{mooring-0.2.2 → mooring-0.2.3}/uv.lock

@@ -450,7 +450,7 @@ wheels = [
 
 [[package]]
 name = "mooring"
-version = "0.2.2"
+version = "0.2.3"
 source = { editable = "." }
 dependencies = [
     { name = "altair" },