mooring 0.2.2__tar.gz → 0.2.4__tar.gz

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

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

{mooring-0.2.2 → mooring-0.2.4}/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.4}/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.4}/pyproject.toml

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

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

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

{mooring-0.2.2 → mooring-0.2.4}/src/mooring/auth.py

@@ -40,6 +40,26 @@ class AuthError(Exception):
     pass
 
 
+def device_flow_hint(host: str, exc: Exception) -> str:
+    """A friendly one-line explanation for a failed device-code request.
+
+    Names the host (and HTTP status, if any) so a misrouted login is obvious,
+    and only suggests setting a host when the request went to the default
+    github.com — a real GHE host that 404s has a different cause (device flow
+    disabled, or a client_id from the wrong instance).
+    """
+    status = getattr(getattr(exc, "response", None), "status_code", None)
+    head = f"Couldn't start GitHub login against {host}"
+    head += f" (HTTP {status})." if status else f": {exc}"
+    if host == githost.DEFAULT_HOST:
+        head += (
+            " If this repo is on GitHub Enterprise, set its host: run "
+            '`mooring login --host ghe.example.com`, or add `host = "ghe.example.com"` '
+            "under [github] in your config."
+        )
+    return head
+
+
 @dataclass
 class DeviceCode:
     device_code: str

{mooring-0.2.2 → mooring-0.2.4}/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",
@@ -73,7 +73,13 @@ def _build_parser() -> argparse.ArgumentParser:
     hub.add_argument("--no-browser", action="store_true", help="don't open a browser tab")
     hub.add_argument("--port", type=int, default=None, help="fixed port for the hub server")
 
-    sub.add_parser("login", help="log in to GitHub via device flow")
+    login = sub.add_parser("login", help="log in to GitHub via device flow")
+    login.add_argument(
+        "--host",
+        default=None,
+        help="GitHub host or URL for GitHub Enterprise (e.g. ghe.example.com); "
+        "saved as the global host before logging in",
+    )
     sub.add_parser("logout", help="forget the stored GitHub token")
     sub.add_parser("whoami", help="show the logged-in GitHub user")
     status = sub.add_parser("status", help="show sync status of workspace files")
@@ -98,7 +104,10 @@ def _build_parser() -> argparse.ArgumentParser:
     repo_use = repo_sub.add_parser("use", help="switch the active repo")
     repo_use.add_argument("alias")
     repo_rm = repo_sub.add_parser("remove", help="forget a repo (local files are kept)")
-    repo_rm.add_argument("alias")
+    repo_rm.add_argument("alias", nargs="?", default=None, help="alias to remove (omit when using --all)")
+    repo_rm.add_argument(
+        "--all", dest="all_repos", action="store_true", help="remove every registered repo"
+    )
 
     pull = sub.add_parser("pull", help="download changes from the team repo")
     pull_grp = pull.add_mutually_exclusive_group()
@@ -143,8 +152,8 @@ def _print_paths(cfg: config.Config) -> None:
     print(f"  config file : {paths.user_config_file()}")
     print(f"  workspace   : {cfg.workspace()}")
     print(f"  logs        : {paths.user_log_dir()}")
-    hint = legacy_workspace_hint(cfg)
-    if hint:
+    hints = (legacy_workspace_hint(cfg), paths.synced_folder_hint(cfg.workspace()))
+    for hint in (h for h in hints if h):
         print(f"  note        : {hint}")
 
 
@@ -162,7 +171,14 @@ def legacy_workspace_hint(cfg: config.Config) -> str:
     return ""
 
 
-def cmd_selftest(cfg: config.Config) -> int:
+def workspace_hint(cfg: config.Config) -> str:
+    """Combined workspace warnings (legacy location + cloud-sync folder) for the
+    hub and selftest, joined into one line."""
+    hints = (legacy_workspace_hint(cfg), paths.synced_folder_hint(cfg.workspace()))
+    return "  ".join(h for h in hints if h)
+
+
+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 +199,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:
@@ -214,15 +236,28 @@ def _client(cfg: config.Config):
     return GitHubClient(_require_token(cfg), cfg.owner, cfg.repo, host=cfg.host)
 
 
-def cmd_login(cfg: config.Config) -> int:
-    from mooring import auth
+def cmd_login(cfg: config.Config, host: str | None = None) -> int:
+    import requests
 
+    from mooring import auth, config_store
+
+    if host is not None:
+        try:
+            new_host = config_store.set_host(host)
+        except ValueError as exc:
+            sys.exit(str(exc))
+        print(f"Saved GitHub host: {new_host}")
+        cfg = config.load_config()  # pick up the host just written
     if not cfg.client_id:
         sys.exit(
             "No OAuth client_id configured. Set [github] client_id in "
             f"{paths.user_config_file()}."
         )
-    device = auth.start_device_flow(cfg.client_id, host=cfg.host)
+    print(f"Requesting device code from {cfg.host}…")
+    try:
+        device = auth.start_device_flow(cfg.client_id, host=cfg.host)
+    except (auth.AuthError, requests.RequestException) as exc:
+        sys.exit(auth.device_flow_hint(cfg.host, exc))
     print(f"Open {device.verification_uri} and enter code: {device.user_code}")
     print("Waiting for authorization...")
     token = auth.poll_for_token(cfg.client_id, device)
@@ -230,6 +265,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 +275,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 +284,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 +317,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 +334,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 +350,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 +378,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 +399,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 +430,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,14 +439,30 @@ 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":
+        if getattr(args, "all_repos", False):
+            aliases = list(app_cfg.aliases)
+            if not aliases:
+                print("No repos registered.")
+                return 0
+            config_store.remove_all_repos()
+            telemetry.log_event("repo_remove", alias="*")
+            print(
+                f"Removed all {len(aliases)} repo(s): {', '.join(aliases)}. "
+                "Workspace folders were kept; delete them manually."
+            )
+            return 0
+        if not args.alias:
+            sys.exit("Specify a repo alias to remove, or use --all.")
         try:
             ws = app_cfg.config_for(args.alias).workspace()
             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 +473,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
 
@@ -423,7 +494,7 @@ def main(argv: list[str] | None = None) -> int:
         port = getattr(args, "port", None)
         return run_hub(app_cfg, open_browser=not no_browser, port=port)
     if command == "login":
-        return cmd_login(cfg)
+        return cmd_login(cfg, getattr(args, "host", None))
     if command == "logout":
         return cmd_logout(cfg)
     if command == "whoami":
@@ -444,5 +515,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.4}/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.4}/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.4}/src/mooring/config_store.py

@@ -83,6 +83,19 @@ def add_repo(
     write_user_data(data)
 
 
+def set_host(host: str) -> str:
+    """Persist the global GitHub host; returns the normalized value.
+
+    Host is a single [github] setting shared by every repo, independent of the
+    [repos] registry, so this writes [github].host without materializing repos.
+    """
+    normalized = githost.normalize_host(host)
+    data = read_user_data()
+    data.setdefault("github", {})["host"] = normalized
+    write_user_data(data)
+    return normalized
+
+
 def remove_repo(alias: str) -> None:
     data = _materialized(read_user_data())
     if alias not in data["repos"] or alias in RESERVED_ALIASES:
@@ -97,6 +110,18 @@ def remove_repo(alias: str) -> None:
     write_user_data(data)
 
 
+def remove_all_repos() -> None:
+    """Clear the entire repo registry. Workspaces and the saved token are kept.
+
+    An explicit empty [repos] is authoritative — it also overrides any
+    owner/repo baked into the packaged default (repo_specs_from_data treats a
+    present [repos] section as the whole truth).
+    """
+    data = read_user_data()
+    data["repos"] = {}
+    write_user_data(data)
+
+
 def set_active(alias: str) -> None:
     data = _materialized(read_user_data())
     if alias not in data["repos"] or alias in RESERVED_ALIASES: