plexus-python 0.11.1__tar.gz → 0.11.3__tar.gz

{plexus_python-0.11.1 → plexus_python-0.11.3}/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 ## [Unreleased]
 
+## [0.11.3] - 2026-09-02 - Let the CLI diagnose the CLI
+
+All three of these came out of one evening of actually using it.
+
+### Added
+
+- **`plexus --version`.** It previously exited 2 with "the following
+  arguments are required: command" — the least useful possible reply to the
+  first thing anyone types when a CLI misbehaves.
+
+### Fixed
+
+- **An unknown subcommand now names the running version and the upgrade.**
+  `invalid choice: 'skills'` sends people hunting for a typo when the real
+  cause is an old install — a pipx shim from four months earlier shadowing a
+  fresh `pip install`, in the case that prompted this. The command genuinely
+  does not exist *there*, and the fix is an upgrade, so the error says which
+  version is running and gives both the pip and pipx forms.
+
+- **`whoami` now asks the server whether the key is actually good.** It used
+  to print the local key and exit 0 without checking anything, so a revoked
+  or expired credential produced a confident-looking summary and the 401s
+  that followed looked unrelated. It now reports the org and scopes on
+  success, distinguishes rejected (401) from access-disabled (403), and
+  treats unreachable as *unknown* rather than invalid — conflating those is
+  how a flaky connection becomes an afternoon of regenerating good
+  credentials. `--no-verify` keeps the old local-only behaviour.
+
+## [0.11.2] - 2026-09-02 - Stamp run boundaries on the server's clock
+
+### Fixed
+
+- **A run's window was measured by a different clock than the points inside
+  it.** `_normalize_ts_ms` corrects generated timestamps by the offset the
+  gateway reports on connect; `start_run` / `end_run` read the local clock
+  instead. Every point taken in the final `offset` milliseconds of a run
+  therefore landed *after* `ended_at` and fell outside the window its own run
+  was evaluated over.
+
+  Measured on production: a device running 58ms behind the server sent 300
+  points and its run was judged on 284 of them. The shortfall reads exactly
+  like ingest lag, which is what it was mistaken for — a pass criterion can
+  come back green because the excursion that would have failed it was outside
+  the window by 58 milliseconds. Run boundaries now carry the same correction
+  as the telemetry. An explicitly passed `started_at` / `ended_at` is still
+  left alone.
+
 ## [0.11.1] - 2026-09-02 - Correct what the agent skills teach
 
 ### Fixed

{plexus_python-0.11.1 → plexus_python-0.11.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plexus-python
-Version: 0.11.1
+Version: 0.11.3
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.company
 Project-URL: Documentation, https://docs.plexus.company

{plexus_python-0.11.1 → plexus_python-0.11.3}/plexus/__init__.py

@@ -23,7 +23,7 @@ from plexus.client import (
 )
 from plexus.config import RetryConfig
 
-__version__ = "0.11.1"
+__version__ = "0.11.3"
 __all__ = [
     "AuthenticationError",
     "BatchSender",

{plexus_python-0.11.1 → plexus_python-0.11.3}/plexus/cli.py

@@ -31,6 +31,7 @@ import threading
 import urllib.parse
 import webbrowser
 from pathlib import Path
+from typing import Any
 
 from . import config
 
@@ -428,8 +429,15 @@ def cmd_logout(_args: argparse.Namespace) -> int:
     return 0
 
 
-def cmd_whoami(_args: argparse.Namespace) -> int:
-    """Print the prefix of the locally stored key + the configured endpoint."""
+def cmd_whoami(args: argparse.Namespace) -> int:
+    """Report the local key, and whether the server still accepts it.
+
+    Printing the key alone was worse than printing nothing: a revoked or
+    expired credential produced confident-looking output and a zero exit, and
+    the 401s that followed from the SDK looked unrelated. `whoami` is what
+    someone runs precisely when they suspect their auth — it has to answer
+    that question rather than confirm a file exists.
+    """
     key = config.get_api_key()
     endpoint = config.get_endpoint()
     if not key:
@@ -438,7 +446,60 @@ def cmd_whoami(_args: argparse.Namespace) -> int:
     masked = f"{key[:8]}…{key[-4:]}" if len(key) > 12 else key
     print(f"key:      {masked}")
     print(f"endpoint: {endpoint}")
-    return 0
+
+    if args.no_verify:
+        return 0
+
+    status, body = _verify_key(endpoint, key)
+    if status == 200:
+        org = body.get("org_id") or "unknown"
+        scopes = ", ".join(body.get("scopes") or []) or "default"
+        print(f"org:      {org}")
+        print(f"scopes:   {scopes}")
+        print("status:   valid")
+        return 0
+    if status == 401:
+        print("status:   REJECTED — this key is invalid, revoked or expired.")
+        print("          Run `plexus init --force` to authorize this machine again.")
+        return 1
+    if status == 403:
+        print("status:   DISABLED — the key is real but access is switched off.")
+        print("          Usually billing; check with your org admin.")
+        return 1
+    if status is None:
+        # Could not ask. Say so rather than implying either answer.
+        print(f"status:   unknown — could not reach {endpoint} ({body})")
+        return 0
+    print(f"status:   unexpected response ({status})")
+    return 1
+
+
+def _verify_key(endpoint: str, key: str) -> tuple[int | None, Any]:
+    """Ask the server whether a key is good. Returns (status, parsed_or_reason).
+
+    A network failure returns (None, reason): unreachable is not the same as
+    rejected, and reporting one as the other is how a flaky connection gets
+    mistaken for a credentials problem.
+    """
+    import json as _json
+    import urllib.error
+    import urllib.request
+
+    req = urllib.request.Request(
+        f"{endpoint.rstrip('/')}/api/auth/verify-key",
+        headers={"x-api-key": key},
+        method="GET",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            return resp.status, _json.loads(resp.read().decode() or "{}")
+    except urllib.error.HTTPError as e:
+        try:
+            return e.code, _json.loads(e.read().decode() or "{}")
+        except Exception:
+            return e.code, {}
+    except Exception as e:  # DNS, TLS, timeout, offline
+        return None, str(e)
 
 
 def _bundled_skills_dir() -> Path | None:
@@ -507,11 +568,50 @@ def _default_skills_target(args: argparse.Namespace) -> Path:
     return Path.home() / ".claude" / "skills"
 
 
+class _VersionAwareParser(argparse.ArgumentParser):
+    """Turns an unknown subcommand into a version diagnosis.
+
+    argparse says `invalid choice: 'skills'` and stops. When the real cause is
+    an old install — a pipx shim from months ago shadowing a fresh pip
+    install, say — that message sends people looking for a typo instead of at
+    their version. The command they were told to run genuinely does not exist
+    *here*, and the fix is an upgrade, so say which version is running and how
+    to move it.
+    """
+
+    def error(self, message: str) -> None:  # type: ignore[override]
+        if "invalid choice" in message:
+            from plexus import __version__
+
+            self.print_usage(sys.stderr)
+            print(f"\n{self.prog}: error: {message}", file=sys.stderr)
+            print(
+                f"\nYou are running plexus-python {__version__}. If you were "
+                "following a doc that\nnames this command, your install is "
+                "probably older than the doc:\n"
+                "\n    pip install --upgrade plexus-python"
+                "\n    pipx upgrade plexus-python      # if you installed with pipx"
+                "\n\nThen check with: plexus --version",
+                file=sys.stderr,
+            )
+            self.exit(2)
+        super().error(message)
+
+
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
+    from plexus import __version__
+
+    parser = _VersionAwareParser(
         prog="plexus",
         description="Plexus CLI — auth, send, query telemetry from your terminal.",
     )
+    # The first thing anyone types when a CLI misbehaves, and previously an
+    # error: `plexus --version` demanded a subcommand and told you nothing.
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"plexus-python {__version__}",
+    )
     sub = parser.add_subparsers(dest="command", required=True)
 
     init = sub.add_parser(
@@ -537,6 +637,11 @@ def build_parser() -> argparse.ArgumentParser:
     logout.set_defaults(func=cmd_logout)
 
     whoami = sub.add_parser("whoami", help="Show the local credential summary.")
+    whoami.add_argument(
+        "--no-verify",
+        action="store_true",
+        help="Skip the server check and only print what is stored locally.",
+    )
     whoami.set_defaults(func=cmd_whoami)
 
     skills = sub.add_parser(

{plexus_python-0.11.1 → plexus_python-0.11.3}/plexus/client.py

@@ -60,10 +60,12 @@ if TYPE_CHECKING:  # pragma: no cover - typing only
 logger = logging.getLogger(__name__)
 
 
-def _utc_now_iso() -> str:
-    """Now as ISO-8601 with a Z offset — the shape /api/runs validates."""
-    return datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace(
-        "+00:00", "Z"
+def _iso_from_ms(ms: int) -> str:
+    """Epoch milliseconds as ISO-8601 with a Z offset — /api/runs validates the shape."""
+    return (
+        datetime.fromtimestamp(ms / 1000, timezone.utc)
+        .isoformat(timespec="milliseconds")
+        .replace("+00:00", "Z")
     )
 
 
@@ -350,6 +352,22 @@ class Plexus:
             return int(timestamp * 1000)
         return int(timestamp)
 
+    def _now_iso(self) -> str:
+        """Now on the SERVER's clock, as ISO-8601.
+
+        Run boundaries have to be stamped on the same clock as the telemetry
+        they bound, and `_normalize_ts_ms` corrects generated timestamps by the
+        offset the gateway reports on connect. Reading the local clock here
+        instead — which this did — leaves `ended_at` behind every point taken
+        in the final `offset` milliseconds of the run, and those points then
+        fall outside the window their own run is evaluated over.
+
+        The failure is quiet and looks like something else entirely: on a
+        device running 58ms behind the server, a 300-point run was evaluated
+        over 284 of them, and the shortfall reads exactly like ingest lag.
+        """
+        return _iso_from_ms(int(time.time() * 1000) + self._clock_offset_ms)
+
     @staticmethod
     def _infer_class(value: FlexValue) -> str:
         """Numbers are metrics; everything else (str/bool/dict/list) is an event.
@@ -584,7 +602,10 @@ class Plexus:
         Returns:
             The created run dict, including its "id".
         """
-        body: dict[str, Any] = {"name": name, "started_at": started_at or _utc_now_iso()}
+        body: dict[str, Any] = {
+            "name": name,
+            "started_at": started_at or self._now_iso(),
+        }
         if source_id is not _USE_CLIENT_SOURCE:
             body["source_id"] = source_id
         else:
@@ -664,7 +685,7 @@ class Plexus:
         return self._api(
             "PATCH",
             f"/api/runs/{run_id}",
-            {"status": status, "ended_at": ended_at or _utc_now_iso()},
+            {"status": status, "ended_at": ended_at or self._now_iso()},
         )["run"]
 
     @contextmanager

{plexus_python-0.11.1 → plexus_python-0.11.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plexus-python"
-version = "0.11.1"
+version = "0.11.3"
 description = "Thin Python SDK for Plexus — send telemetry in one line"
 readme = "README.md"
 license = "Apache-2.0"

plexus_python-0.11.3/tests/test_cli_diagnostics.py

@@ -0,0 +1,94 @@
+"""The CLI has to help you debug the CLI.
+
+Every case here came out of one evening of real use: a four-month-old pipx
+shim shadowing a fresh install, `plexus --version` refusing to answer, and
+`whoami` cheerfully printing a credential it had never checked.
+"""
+
+from unittest import mock
+
+import pytest
+
+from plexus import __version__
+from plexus.cli import build_parser, cmd_whoami
+
+
+def _args(**kw):
+    ns = mock.Mock()
+    ns.no_verify = kw.get("no_verify", False)
+    return ns
+
+
+def test_version_flag_answers_instead_of_demanding_a_subcommand(capsys):
+    # It used to exit 2 with "the following arguments are required: command",
+    # which is the least useful possible reply to "what version am I on".
+    with pytest.raises(SystemExit) as exc:
+        build_parser().parse_args(["--version"])
+    assert exc.value.code == 0
+    assert __version__ in capsys.readouterr().out
+
+
+def test_unknown_subcommand_names_the_version_and_the_upgrade(capsys):
+    """`invalid choice: 'skills'` sends people hunting for a typo when the real
+    cause is an old install. Say which version is running."""
+    with pytest.raises(SystemExit) as exc:
+        build_parser().parse_args(["skills-that-do-not-exist-yet"])
+    assert exc.value.code == 2
+    err = capsys.readouterr().err
+    assert __version__ in err
+    assert "pip install --upgrade" in err
+    assert "pipx upgrade" in err  # the shadowing case that caused this
+
+
+def test_whoami_reports_a_valid_key_with_its_org(monkeypatch, capsys):
+    monkeypatch.setenv("PLEXUS_API_KEY", "plx_" + "a" * 32)
+    with mock.patch(
+        "plexus.cli._verify_key",
+        return_value=(200, {"org_id": "org_abc", "scopes": ["read", "write"]}),
+    ):
+        assert cmd_whoami(_args()) == 0
+    out = capsys.readouterr().out
+    assert "org_abc" in out and "valid" in out
+
+
+def test_whoami_fails_loudly_on_a_rejected_key(monkeypatch, capsys):
+    """The whole point. A revoked key used to print a confident summary and
+    exit 0, so the 401s that followed looked unrelated."""
+    monkeypatch.setenv("PLEXUS_API_KEY", "plx_" + "b" * 32)
+    with mock.patch("plexus.cli._verify_key", return_value=(401, {})):
+        assert cmd_whoami(_args()) == 1
+    out = capsys.readouterr().out
+    assert "REJECTED" in out
+    assert "plexus init --force" in out  # tell them the fix, not just the fault
+
+
+def test_whoami_distinguishes_disabled_from_invalid(monkeypatch, capsys):
+    monkeypatch.setenv("PLEXUS_API_KEY", "plx_" + "c" * 32)
+    with mock.patch("plexus.cli._verify_key", return_value=(403, {})):
+        assert cmd_whoami(_args()) == 1
+    assert "DISABLED" in capsys.readouterr().out
+
+
+def test_unreachable_is_not_reported_as_invalid(monkeypatch, capsys):
+    """Offline is not rejected. Conflating them turns a flaky connection into
+    an afternoon spent regenerating perfectly good credentials."""
+    monkeypatch.setenv("PLEXUS_API_KEY", "plx_" + "d" * 32)
+    with mock.patch("plexus.cli._verify_key", return_value=(None, "connection refused")):
+        assert cmd_whoami(_args()) == 0  # unknown is not failure
+    out = capsys.readouterr().out
+    assert "unknown" in out
+    assert "REJECTED" not in out
+
+
+def test_no_verify_skips_the_network(monkeypatch, capsys):
+    monkeypatch.setenv("PLEXUS_API_KEY", "plx_" + "e" * 32)
+    with mock.patch("plexus.cli._verify_key") as v:
+        assert cmd_whoami(_args(no_verify=True)) == 0
+        v.assert_not_called()
+
+
+def test_whoami_without_a_key_says_what_to_run(monkeypatch, capsys):
+    monkeypatch.delenv("PLEXUS_API_KEY", raising=False)
+    with mock.patch("plexus.config.load_config", return_value={}):
+        assert cmd_whoami(_args()) == 1
+    assert "plexus init" in capsys.readouterr().out

{plexus_python-0.11.1 → plexus_python-0.11.3}/tests/test_runs.py

@@ -10,6 +10,7 @@ The HTTP layer is stubbed at `_Session.request`, so no socket is opened.
 """
 
 import json
+import time
 
 import pytest
 
@@ -72,6 +73,47 @@ def test_started_at_matches_the_shape_the_route_validates():
     datetime.fromisoformat(started.replace("Z", "+00:00"))  # parses or raises
 
 
+def test_run_boundaries_are_stamped_on_the_server_clock():
+    """The window must be measured by the same clock as the points inside it.
+
+    `_normalize_ts_ms` corrects generated timestamps by the offset the gateway
+    reports on connect. Stamping run boundaries from the local clock instead
+    leaves `ended_at` behind every point taken in the final `offset`
+    milliseconds — and those points then fall outside the window their own run
+    is evaluated over. Measured on production before the fix: a 300-point run
+    on a device 58ms behind the server was judged on 284 of them, and the
+    shortfall reads exactly like ingest lag.
+    """
+    from datetime import datetime
+
+    session = _StubSession()
+    px = _client(session)
+    px._clock_offset_ms = 5_000  # device 5s behind the server
+
+    px.start_run("run")
+    px.end_run({"id": "run_1"})
+
+    def as_ms(iso: str) -> int:
+        return int(datetime.fromisoformat(iso.replace("Z", "+00:00")).timestamp() * 1000)
+
+    local_ms = int(time.time() * 1000)
+    started = as_ms(session.calls[0][2]["started_at"])
+    ended = as_ms(session.calls[1][2]["ended_at"])
+
+    # Both carry the offset, so they bound points that also carry it.
+    assert started - local_ms > 4_000
+    assert ended - local_ms > 4_000
+
+
+def test_an_explicit_boundary_is_left_alone():
+    """A caller passing its own timestamp owns it — we do not shift it."""
+    session = _StubSession()
+    px = _client(session)
+    px._clock_offset_ms = 5_000
+    px.start_run("run", started_at="2026-09-01T10:00:00.000Z")
+    assert session.calls[0][2]["started_at"] == "2026-09-01T10:00:00.000Z"
+
+
 def test_run_defaults_to_the_clients_own_source():
     session = _StubSession()
     px = _client(session)

{plexus_python-0.11.1 → plexus_python-0.11.3}/uv.lock

@@ -425,7 +425,7 @@ wheels = [
 
 [[package]]
 name = "plexus-python"
-version = "0.11.1"
+version = "0.11.2"
 source = { editable = "." }
 dependencies = [
     { name = "websocket-client" },