dataspring-cli 0.5.0__tar.gz → 0.5.1__tar.gz

{dataspring_cli-0.5.0 → dataspring_cli-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dataspring-cli
-Version: 0.5.0
+Version: 0.5.1
 Summary: DataSpring CLI - Query metrics and manage dashboards from the terminal
 Project-URL: Homepage, https://dataspring.app
 Project-URL: Documentation, https://dataspring.app/docs

{dataspring_cli-0.5.0 → dataspring_cli-0.5.1}/cli/auth.py

@@ -52,6 +52,8 @@ import httpx
 
 from cli import forspring
 from cli.forspring import CredentialStore, OAuthError
+from cli import transport
+from cli.runtime import API_TIMEOUT
 from cli.refusals import (
     EN,
     EXIT_FAILURE,
@@ -517,7 +519,18 @@ class CLIAuthManager:
     def _key_org(self, key: str) -> str | None:
         """The org a key not stored here belongs to, as the server says.
         Synchronous: :meth:`resolve` runs inside the async commands too."""
-        r = httpx.get(f"{_host()}/api/me", headers={"Authorization": f"Bearer {key}"}, timeout=15.0)
+        with transport.ColdStartIndicator() as indicator:
+            for attempt in range(2):  # a GET: one retry on what a cold start looks like
+                try:
+                    r = httpx.get(f"{_host()}/api/me", headers={"Authorization": f"Bearer {key}"}, timeout=API_TIMEOUT)
+                    break
+                except transport.RETRYABLE as e:
+                    if attempt == 0:
+                        indicator.mark_retrying()
+                        continue
+                    raise transport.unreachable(e, _host(), API_TIMEOUT) from e
+                except httpx.TransportError as e:
+                    raise transport.unreachable(e, _host(), API_TIMEOUT) from e
         return self._me_answer(r).get("org_id")
 
     def resolved_org(self) -> str | None:
@@ -653,8 +666,22 @@ class CLIAuthManager:
         return self.resolve().key
 
     async def _me(self, key: str) -> dict:
-        async with httpx.AsyncClient(timeout=15.0) as client:
-            r = await client.get(f"{_host()}/api/me", headers={"Authorization": f"Bearer {key}"})
+        """``GET /api/me``: the first request of nearly every command, so the
+        one a cold backend meets first (`cli.transport`): the "waking up"
+        status while it waits, one retry, `ApiUnreachable` if no answer."""
+        with transport.ColdStartIndicator() as indicator:
+            async with httpx.AsyncClient(timeout=API_TIMEOUT) as client:
+                for attempt in range(2):
+                    try:
+                        r = await client.get(f"{_host()}/api/me", headers={"Authorization": f"Bearer {key}"})
+                        break
+                    except transport.RETRYABLE as e:
+                        if attempt == 0:
+                            indicator.mark_retrying()
+                            continue
+                        raise transport.unreachable(e, _host(), API_TIMEOUT) from e
+                    except httpx.TransportError as e:
+                        raise transport.unreachable(e, _host(), API_TIMEOUT) from e
         return self._me_answer(r)
 
     @staticmethod
@@ -810,7 +837,7 @@ class CLIAuthManager:
         detail = ""
         try:
             r = httpx.delete(f"{_host()}/api/keys/{p['key_id']}",
-                             headers={"Authorization": f"Bearer {key}"}, timeout=10.0)
+                             headers={"Authorization": f"Bearer {key}"}, timeout=API_TIMEOUT)
         except httpx.HTTPError as e:
             r = None
             reason, exit_code, detail = "server_unreachable", EXIT_FAILURE, f"DataSpring did not answer ({type(e).__name__})"

{dataspring_cli-0.5.0 → dataspring_cli-0.5.1}/cli/main.py

@@ -40,7 +40,9 @@ from cli.output import (
     OutputFormat,
 )
 from cli.refusals import EXIT_CODES, EXIT_USAGE, NAME_AN_ORG, classify, from_body
-from cli.runtime import call_tool
+from cli import transport
+from cli.runtime import API_TIMEOUT, call_tool
+from cli.transport import ApiUnreachable
 from typer.core import TyperGroup
 
 
@@ -80,7 +82,13 @@ class DataSpringGroup(TyperGroup):
     standards §6; a D-99 refusal's), never a traceback."""
 
     def parse_args(self, ctx, args):
-        return super().parse_args(ctx, hoist_org(list(args)))
+        args = hoist_org(list(args))
+        # `--org` is set here, before Click runs any option: `--version` is
+        # eager and runs its callback during parsing, before the root callback
+        # (which sets it again), so `dataspring --version --org noon` must not
+        # depend on the order Click processes the two in.
+        set_org_flag(args[1] if args[:1] == ["--org"] and len(args) > 1 else None)
+        return super().parse_args(ctx, args)
 
     def invoke(self, ctx):
         try:
@@ -190,6 +198,9 @@ def require_auth():
         return run_async(auth.get_user())
     except AuthenticationError as e:
         auth_failed(e)
+    except ApiUnreachable as e:
+        print_error(str(e), hint=e.hint)
+        raise typer.Exit(e.exit_code)
 
 
 def auth_failed(e: AuthenticationError) -> NoReturn:
@@ -210,50 +221,54 @@ def get_api_base() -> str:
     return base.removesuffix("/api")
 
 
-def api_get(path: str, token: str, timeout: float = 60.0) -> dict:
-    """Make an authenticated GET request to the backend API."""
-    import httpx
+def _request(method: str, path: str, token: str, *, body: dict | None = None, timeout: float, retry: bool) -> dict:
+    """One authenticated call to the backend API; every ``api_*`` function
+    below is this with its verb fixed (`cli.transport` has the why).
 
-    url = f"{get_api_base()}{path}"
-    with httpx.Client(timeout=timeout) as client:
-        response = client.get(
-            url,
-            headers={"Authorization": f"Bearer {token}"},
-        )
-        response.raise_for_status()
-        return response.json()
-
-
-def api_delete(path: str, token: str, timeout: float = 60.0) -> dict:
-    """Make an authenticated DELETE request to the backend API."""
+    Shows the "waking up" status while the request is slow; turns a request
+    that got no answer into `ApiUnreachable`, never a raw httpx exception.
+    ``retry`` allows one automatic retry on a timeout or a failed connection,
+    for an idempotent request only (``api_get``); a dispatch call is a POST
+    and may write, so it reaches the server at most once.
+    """
     import httpx
 
     url = f"{get_api_base()}{path}"
-    with httpx.Client(timeout=timeout) as client:
-        response = client.delete(
-            url,
-            headers={"Authorization": f"Bearer {token}"},
-        )
-        response.raise_for_status()
-        return response.json()
+    headers = {"Authorization": f"Bearer {token}"}
+    attempts = 2 if retry else 1
+    with transport.ColdStartIndicator() as indicator, httpx.Client(timeout=timeout) as client:
+        for attempt in range(attempts):
+            try:
+                response = client.request(method, url, headers=headers, json=body)
+                break
+            except transport.RETRYABLE as e:
+                if attempt + 1 < attempts:
+                    indicator.mark_retrying()
+                    continue
+                raise transport.unreachable(e, get_api_base(), timeout) from e
+            except httpx.TransportError as e:
+                raise transport.unreachable(e, get_api_base(), timeout) from e
+    response.raise_for_status()
+    return response.json()
+
+
+def api_get(path: str, token: str, timeout: float = API_TIMEOUT) -> dict:
+    """Make an authenticated GET request to the backend API (idempotent:
+    retried once on a timeout or a failed connection)."""
+    return _request("GET", path, token, timeout=timeout, retry=True)
+
+
+def api_delete(path: str, token: str, timeout: float = API_TIMEOUT) -> dict:
+    """Make an authenticated DELETE request to the backend API."""
+    return _request("DELETE", path, token, timeout=timeout, retry=False)
 
 
-def api_put(path: str, body: dict, token: str, timeout: float = 60.0) -> dict:
+def api_put(path: str, body: dict, token: str, timeout: float = API_TIMEOUT) -> dict:
     """Make an authenticated PUT request to the backend API."""
-    import httpx
+    return _request("PUT", path, token, body=body, timeout=timeout, retry=False)
 
-    url = f"{get_api_base()}{path}"
-    with httpx.Client(timeout=timeout) as client:
-        response = client.put(
-            url,
-            headers={"Authorization": f"Bearer {token}"},
-            json=body,
-        )
-        response.raise_for_status()
-        return response.json()
 
-
-def api_post(path: str, body: dict, token: str, timeout: float = 60.0) -> dict:
+def api_post(path: str, body: dict, token: str, timeout: float = API_TIMEOUT) -> dict:
     """Make an authenticated POST request to the backend API.
 
     Args:
@@ -266,18 +281,11 @@ def api_post(path: str, body: dict, token: str, timeout: float = 60.0) -> dict:
 
     Raises:
         Exception: On HTTP or connection errors
-    """
-    import httpx
 
-    url = f"{get_api_base()}{path}"
-    with httpx.Client(timeout=timeout) as client:
-        response = client.post(
-            url,
-            headers={"Authorization": f"Bearer {token}"},
-            json=body,
-        )
-        response.raise_for_status()
-        return response.json()
+    Never retried: every write goes through here (``api_dispatch``), and a
+    dispatch call must reach the server at most once.
+    """
+    return _request("POST", path, token, body=body, timeout=timeout, retry=False)
 
 
 class DispatchToolError(Exception):
@@ -298,14 +306,15 @@ class DispatchToolError(Exception):
         super().__init__(str(payload.get("error")))
 
 
-def api_dispatch(tool_key: str, body: dict, token: str, timeout: float = 60.0) -> dict:
+def api_dispatch(tool_key: str, body: dict, token: str, timeout: float = API_TIMEOUT) -> dict:
     """``POST /api/dispatch/{tool_key}`` and unwrap the handler's answer.
 
     Action families take ``{"action": {"action": "<verb>", ...}}``; flat tools
     take their keyword arguments as the body. A ``{"error": ...}`` answer
     becomes `DispatchToolError`; HTTP 400/403/404 arrive as
-    ``httpx.HTTPStatusError`` from `api_post`. `format_api_error` turns either
-    into a message the user can act on.
+    ``httpx.HTTPStatusError``, and a connect/timeout failure as
+    `ApiUnreachable`, both from `api_post`. `format_api_error` turns any of
+    these into a message the user can act on.
     """
     result = api_post(f"/api/dispatch/{tool_key}", body, token, timeout=timeout)
     if isinstance(result, dict) and result.get("error"):
@@ -357,13 +366,18 @@ def format_api_error(exc: Exception, role_action: str | None = None) -> tuple[st
     ``role_action`` hint (e.g. ``"delete metrics"``) is only attached to 403
     responses; on other failures the hint is omitted so we don't gaslight the
     user into thinking it's a permission problem. A `DispatchToolError` carries
-    the handler's own message and, when it offered one, its suggestion.
+    the handler's own message and, when it offered one, its suggestion; an
+    `ApiUnreachable` (a connect or timeout failure in ``_request``) carries
+    its own message and hint the same way.
     """
     import httpx
 
     if isinstance(exc, DispatchToolError):
         return str(exc), exc.hint
 
+    if isinstance(exc, transport.ApiUnreachable):
+        return str(exc), exc.hint
+
     if isinstance(exc, httpx.HTTPStatusError):
         status = exc.response.status_code
         refusal = _response_refusal(exc.response)
@@ -486,15 +500,35 @@ def load_definition_file(file: Path) -> dict:
 # ============================================================================
 
 
+def _version_token() -> tuple[str | None, str | None]:
+    """The credential ``--version`` compares the server with, or why there is none.
+
+    A version needs no org. The comparison is advisory, so it uses an org
+    only when one is unambiguous (``--org``, ``DATASPRING_ORG``/``FORSPRING_ORG``,
+    ``.forspring.json``, the only sign-in, or ``DATASPRING_API_KEY``) and
+    otherwise says why it skipped. Nothing here may raise: before 0.5.1,
+    several sign-ins and no org named made ``dataspring --version`` end in an
+    ``org_required`` traceback (the eager option runs outside the root
+    command's refusal handling).
+    """
+    try:
+        if not auth.is_logged_in():
+            return None, "log in to compare with the server"
+        return auth.get_access_token(), None
+    except Refused as e:
+        if e.reason == "org_required":
+            return None, "server not compared (several orgs signed in; pass --org)"
+        return None, f"server not compared ({e.reason})"
+    except Exception as e:  # advisory: a version prints whatever else is wrong
+        return None, f"server not compared ({type(e).__name__})"
+
+
 def _print_version_report() -> None:
-    """The version, and the manifest skew against the server when logged in."""
+    """The version, and the manifest skew against the server when an org is unambiguous."""
     from cli.version import version_report
 
-    token = auth.get_access_token() if auth.is_logged_in() else None
-    try:
-        lines = version_report(base=get_api_base(), token=token)
-    except AuthenticationError:
-        lines = version_report(base=get_api_base(), token=None)
+    token, note = _version_token()
+    lines = version_report(base=get_api_base(), token=token, note=note)
     console.print(f"[bold]DataSpring CLI[/] v{lines[0].split(' ', 1)[1]}")
     for line in lines[1:]:
         console.print(line)
@@ -528,7 +562,7 @@ def _root(
 
 @app.command()
 def version():
-    """Show the CLI version and, when logged in, its skew against the server."""
+    """Show the CLI version and, when an org is unambiguous, its skew against the server."""
     _print_version_report()
 
 
@@ -789,6 +823,12 @@ def whoami(
         auth_failed(e)
     except AuthenticationError as e:
         auth_failed(e)
+    except ApiUnreachable as e:
+        if as_json:
+            typer.echo(json.dumps({"ok": False, "reason": "server_unreachable", "note": str(e), "fix": e.hint}))
+        else:
+            print_error(str(e), hint=e.hint)
+        raise typer.Exit(e.exit_code)
     if as_json:
         typer.echo(json.dumps(me))
         return
@@ -857,7 +897,7 @@ def report(
                 "source": "cli",
             },
             token=token,
-            timeout=15.0,
+            timeout=API_TIMEOUT,
         )
         print_success(f"Error report submitted (ID: {result['id']})")
         print_info("Thank you for the feedback.")
@@ -2595,8 +2635,8 @@ def secret_set_cmd(
         raise typer.Exit(2)
 
     try:
-        minted = call_tool("secret_edit", "set", {"name": name}, token=token, timeout=30.0)
-        result = api_post(f"/api/secret-links/{_link_nonce(minted['link'])}", {"value": value}, token, timeout=60.0)
+        minted = call_tool("secret_edit", "set", {"name": name}, token=token, timeout=API_TIMEOUT)
+        result = api_post(f"/api/secret-links/{_link_nonce(minted['link'])}", {"value": value}, token, timeout=API_TIMEOUT)
     except Exception as e:
         fail(e, role_action="set secrets", prefix="Failed to set the secret")
 
@@ -2623,7 +2663,7 @@ def airbyte_credentials(
     require_auth()
     token = auth.get_access_token()
     try:
-        minted = call_tool("secret_edit", "reveal", {}, token=token, timeout=30.0)
+        minted = call_tool("secret_edit", "reveal", {}, token=token, timeout=API_TIMEOUT)
     except Exception as e:
         fail(e, role_action="reveal issued credentials", prefix="Failed to mint a reveal link")
 
@@ -2632,7 +2672,7 @@ def airbyte_credentials(
         print_info(f"Shows {minted.get('secret')} once, valid until {minted.get('expires_at')}; never paste it into a chat.")
         return
     try:
-        result = api_post(f"/api/secret-links/{_link_nonce(minted['link'])}/reveal", {}, token, timeout=30.0)
+        result = api_post(f"/api/secret-links/{_link_nonce(minted['link'])}/reveal", {}, token, timeout=API_TIMEOUT)
     except Exception as e:
         fail(e, prefix="Failed to read the key through the link")
     sys.stdout.write(result["value"])
@@ -3624,7 +3664,7 @@ def _fetch_skill_markdown(path: str) -> str:
 
     url = _skill_url(path)
     try:
-        response = httpx.get(url, timeout=30.0)
+        response = httpx.get(url, timeout=API_TIMEOUT)
         response.raise_for_status()
         return response.text
     except httpx.HTTPStatusError as e:

{dataspring_cli-0.5.0 → dataspring_cli-0.5.1}/cli/output.py

@@ -16,6 +16,11 @@ from rich.table import Table
 # Shared console instance
 console = Console()
 
+#: A second console bound to stderr, for what must never land in stdout's data
+#: stream (a table, JSON, CSV): the transient "waking up" status
+#: (`cli.transport.ColdStartIndicator`) while a request is pending.
+stderr_console = Console(stderr=True)
+
 OutputFormat = Literal["table", "json", "yaml", "csv"]
 
 

{dataspring_cli-0.5.0 → dataspring_cli-0.5.1}/cli/runtime.py

@@ -41,6 +41,14 @@ EXIT_USAGE = 2
 #: the slow ones, and a query has its own byte and time caps on the server.
 DEFAULT_TIMEOUT = 180.0
 
+#: Seconds any other call to the DataSpring backend waits before it gives up.
+#: A Cloud Run instance that is starting (after a deploy, or after idling to
+#: zero) takes about 30s to answer its first request, and the Hosting proxy
+#: in front of it cuts a request off at 60s, so less than 60 turns a cold
+#: start into an error and more buys nothing. The account (forspring.py) and
+#: PyPI are not behind Cloud Run and keep their own, shorter timeouts.
+API_TIMEOUT = 60.0
+
 
 # ---------------------------------------------------------------------------
 # Values

{dataspring_cli-0.5.0 → dataspring_cli-0.5.1}/cli/skills_commands.py

@@ -29,6 +29,7 @@ import typer
 
 from cli import skilltree
 from cli.output import console, print_error, print_warning
+from cli.runtime import API_TIMEOUT
 
 EXIT_GENERIC = 1
 EXIT_USAGE = 2
@@ -60,7 +61,7 @@ def _api_base() -> str:
 
 def _get_json(path: str) -> dict:
     url = f"{_api_base()}{path}"
-    with httpx.Client(timeout=30.0, **CLIENT_OPTIONS) as client:
+    with httpx.Client(timeout=API_TIMEOUT, **CLIENT_OPTIONS) as client:
         response = client.get(url)
     if response.status_code == 404:
         detail = response.json().get("detail", "not found") if response.headers.get("content-type", "").startswith(

dataspring_cli-0.5.1/cli/transport.py

@@ -0,0 +1,143 @@
+"""What the CLI does while the DataSpring backend is slow to answer, and when
+it does not answer at all.
+
+Cloud Run scales the backend to zero, and a starting instance takes about 30s
+to answer its first request (the Hosting proxy in front of it cuts a request
+off at 60s). Every call to the backend goes through here - `cli.main._request`
+for the API and dispatch calls, `cli.auth` for ``GET /api/me`` - so all of them
+behave the same way on a cold start:
+
+- `ColdStartIndicator`: once a request has been pending for
+  `STATUS_THRESHOLD_SECONDS`, a transient "Waking up DataSpring… 7s" status on
+  stderr, cleared the moment the answer (or the failure) is in hand. Only on an
+  interactive stderr and never with ``CI`` set, so a pipe, a log or a redirected
+  stderr sees nothing; stdout is never touched. A fast answer shows nothing and
+  makes no extra request.
+- `RETRYABLE`: the failures a cold start looks like (a timeout, a refused or
+  dropped connection). An idempotent request (a ``GET``) is retried once on
+  these; a ``POST`` never is.
+- `unreachable`: what a request that never got an answer becomes - an
+  `ApiUnreachable` with one line and a hint, printed as ``✗ Error: ...`` and
+  exiting 1, never an httpx traceback.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+
+import httpx
+
+from cli.output import stderr_console
+
+#: Seconds a request may be pending before the status shows. A warm backend
+#: answers well inside this; only a request that outlasts it looks like a cold
+#: start. Tests shrink it instead of sleeping.
+STATUS_THRESHOLD_SECONDS = 2.5
+
+#: Failures that may be a cold start, and so are worth one retry of a GET.
+RETRYABLE: tuple[type[Exception], ...] = (httpx.TimeoutException, httpx.ConnectError)
+
+HINT = "The service may be starting up; try again in a moment."
+
+
+class ApiUnreachable(Exception):
+    """No answer came back at all: a timeout, or a connection that failed or
+    dropped (any ``httpx.TransportError``). Carries one line and a hint;
+    `cli.main.format_api_error` prints it like any other failure (exit 1)."""
+
+    exit_code = 1
+
+    def __init__(self, message: str, hint: str = HINT):
+        self.hint = hint
+        super().__init__(message)
+
+
+def unreachable(exc: Exception, base: str, timeout: float) -> ApiUnreachable:
+    """The message for a transport failure, saying whether the server did
+    not answer in time or the connection itself failed."""
+    if isinstance(exc, httpx.TimeoutException):
+        return ApiUnreachable(f"Could not reach DataSpring at {base} (timed out after {timeout:g}s).")
+    if isinstance(exc, httpx.ConnectError):
+        return ApiUnreachable(f"Could not reach DataSpring at {base}: connection failed.")
+    return ApiUnreachable(f"Could not reach DataSpring at {base}: {type(exc).__name__}.")
+
+
+def _stderr_is_a_tty() -> bool:
+    """Whether stderr is interactive; a seam the tests patch."""
+    try:
+        return sys.stderr.isatty()
+    except Exception:
+        return False
+
+
+def status_allowed() -> bool:
+    """A status line is for a person watching: an interactive stderr, not CI.
+    Anywhere else its redraws would only leave escape codes in a log."""
+    if os.environ.get("CI"):
+        return False
+    return _stderr_is_a_tty()
+
+
+class ColdStartIndicator:
+    """The "waking up" status for one request, across its retry if it has
+    one. Use as a context manager: the status starts lazily on a daemon
+    thread after `STATUS_THRESHOLD_SECONDS` and is always stopped on exit,
+    whether the request answered, raised, or was interrupted (Ctrl-C).
+    Works around sync and async requests alike, since it never blocks them.
+    """
+
+    def __init__(self) -> None:
+        self._enabled = status_allowed()
+        self._stop = threading.Event()
+        self._lock = threading.Lock()
+        self._status = None
+        self._thread: threading.Thread | None = None
+        self._started_at = 0.0
+        self._retrying = False
+
+    def __enter__(self) -> "ColdStartIndicator":
+        if self._enabled:
+            self._started_at = time.monotonic()
+            self._thread = threading.Thread(target=self._run, daemon=True)
+            self._thread.start()
+        return self
+
+    def __exit__(self, *exc_info) -> None:
+        self.stop()
+
+    def mark_retrying(self) -> None:
+        """Switch the wording for the retry, keeping the clock running."""
+        self._retrying = True
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=1.0)
+        with self._lock:
+            status, self._status = self._status, None
+        if status is not None:
+            status.stop()
+
+    def _run(self) -> None:
+        # Nothing renders before the threshold: a request that answers first
+        # sets the event and this returns having shown nothing.
+        if self._stop.wait(STATUS_THRESHOLD_SECONDS):
+            return
+        with self._lock:
+            if self._stop.is_set():
+                return
+            self._status = stderr_console.status(self._text(), spinner="dots")
+            self._status.start()
+        while not self._stop.wait(1.0):
+            with self._lock:
+                if self._status is not None:
+                    self._status.update(self._text())
+
+    def _text(self) -> str:
+        elapsed = int(time.monotonic() - self._started_at)
+        if self._retrying:
+            return f"Still waking up DataSpring… retrying ({elapsed}s)"
+        return f"Waking up DataSpring… (the server is starting, this can take up to ~30s) {elapsed}s"

{dataspring_cli-0.5.0 → dataspring_cli-0.5.1}/cli/version.py

@@ -4,8 +4,8 @@ The wheel is built against one dispatch manifest (``cli/bundled_manifest.py``
 carries its hash). A deployed server may be newer: it then has operations or
 fields this CLI does not know, and the only way the CLI learns that is by
 comparing hashes with ``GET /api/dispatch`` (decision D19). Not logged in,
-or the server unreachable: the version still prints; the comparison is a
-note, never a failure.
+or the server unreachable, or several orgs signed in and none named: the
+version still prints; the comparison is a note, never a failure.
 """
 
 from __future__ import annotations
@@ -27,6 +27,9 @@ UPGRADE_HINT = "run `dataspring upgrade`"
 CACHE_FILE = Path.home() / ".dataspring" / "manifest-check.json"
 CACHE_TTL_SECONDS = 3600
 
+#: Seconds the manifest-skew check waits; see `fetch_server_hash`.
+SKEW_CHECK_TIMEOUT = 5.0
+
 
 def cli_version() -> str:
     try:
@@ -45,7 +48,11 @@ def bundled_hash() -> str | None:
 
 def fetch_server_hash(base: str, token: str) -> str:
     """The manifest hash ``GET /api/dispatch`` answers, bearer-authenticated."""
-    with httpx.Client(timeout=15.0) as client:
+    # Advisory (the skew hint, never the command's answer), so it is kept
+    # short: on a cold backend it gives up after 5s, says nothing, and is
+    # tried again by the next command, rather than holding the real request
+    # back for a whole cold start with no status on screen.
+    with httpx.Client(timeout=SKEW_CHECK_TIMEOUT) as client:
         response = client.get(f"{base}/api/dispatch", headers={"Authorization": f"Bearer {token}"})
     response.raise_for_status()
     return response.json()["hash"]
@@ -107,16 +114,18 @@ def skew_lines(server: str | None, bundled: str | None, *, server_note: str | No
     ]
 
 
-def version_report(*, base: str, token: str | None) -> list[str]:
-    """Everything ``--version`` prints, one entry per line."""
+def version_report(*, base: str, token: str | None, note: str | None = None) -> list[str]:
+    """Everything ``--version`` prints, one entry per line. Without a token
+    the comparison is skipped with ``note`` (why there is none); the first
+    line, the CLI's own version, is always there and never needs the server."""
     lines = [f"{DIST} {cli_version()}"]
     bundled = bundled_hash()
     if token is None:
-        lines += skew_lines(None, bundled, server_note="log in to compare with the server")
+        lines += skew_lines(None, bundled, server_note=note or "log in to compare with the server")
         return lines
     try:
         server = fetch_server_hash(base, token)
-    except (httpx.HTTPError, KeyError, ValueError) as e:
+    except (httpx.HTTPError, KeyError, ValueError, TypeError) as e:
         lines += skew_lines(None, bundled, server_note=f"server not compared ({type(e).__name__})")
         return lines
     lines += skew_lines(server, bundled)

{dataspring_cli-0.5.0 → dataspring_cli-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dataspring-cli"
-version = "0.5.0"
+version = "0.5.1"
 description = "DataSpring CLI - Query metrics and manage dashboards from the terminal"
 readme = "README.md"
 requires-python = ">=3.12"