deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/client.py

@@ -0,0 +1,503 @@
+"""HTTP client with automatic token refresh and error handling."""
+
+from __future__ import annotations
+
+import random
+import time
+import uuid
+from typing import Any, Callable
+
+import httpx
+
+from deepcell_cli.config import (
+    client_headers,
+    get_access_token,
+    get_api_url,
+    get_client_surface,
+    get_refresh_token,
+    load_credentials,
+    save_credentials,
+    warn_if_insecure,
+)
+from deepcell_cli.errors import APIError, AuthError, EmailVerificationRequired
+from deepcell_cli.errors import ConnectionError as CLIConnectionError
+
+_TIMEOUT = 30.0
+_REFRESH_BUFFER = 60  # refresh token 60s before expiry
+
+# ── Load-shed retry ─────────────────────────────────────────
+# One `deepcell` invocation is one process and one blocking request, so N
+# concurrent commands are N independent clients that coordinate through nothing.
+# Whatever sheds them — nginx's per-IP limiters, the API's own rate limiter —
+# rejects the overflow all at once, and without a retry here that arrives as N
+# hard failures rather than as backpressure. The requests were never proxied to
+# the app (limit_req/limit_conn reject before proxy_pass), so replaying them
+# cannot double-apply anything.
+_MAX_SHED_RETRIES = 4
+_SHED_BACKOFF_BASE = 0.25
+# Also the longest server-requested wait we will sit through. Past this a retry
+# is worse than the error: the caller blocks with no output while the message we
+# already have ("Try again in 47s") is the actionable answer.
+_SHED_BACKOFF_CAP = 8.0
+
+
+def _is_shed(resp: httpx.Response) -> bool:
+    """True when ``resp`` is load-shedding rather than an answer.
+
+    429 is unambiguous — both nginx's limiters (``limit_req_status`` /
+    ``limit_conn_status`` in docker/nginx.conf) and the API's rate limiter mean
+    "come back later" by it.
+
+    503 is not. nginx sheds with 503 in older configurations and behind other
+    proxies, but the application also returns a genuine 503 that must reach the
+    caller unretried — ``POST /demo/session`` with anonymous sessions disabled
+    is the one the CLI hits routinely. The two are told apart by the body: a
+    FastAPI error carries JSON, an nginx shed page carries HTML.
+    """
+    if resp.status_code == 429:
+        return True
+    if resp.status_code != 503:
+        return False
+    return "json" not in resp.headers.get("content-type", "").lower()
+
+
+def _shed_delay(resp: httpx.Response, attempt: int) -> float | None:
+    """Seconds to wait before replaying a shed request, or None to give up.
+
+    Jitter is load-bearing, not a refinement. The failure this retry exists to
+    fix is N clients shed at the same instant; on a fixed backoff schedule they
+    wake at the same instant too and collide again, so a deterministic retry
+    mostly moves the pile-up one second later. Full jitter (uniform over the
+    whole window, not window ± a bit) is what actually spreads them.
+    """
+    retry_after = resp.headers.get("Retry-After")
+    if retry_after:
+        try:
+            requested = float(retry_after)
+        except ValueError:
+            # The HTTP-date form. Rare from these servers, and parsing it buys
+            # nothing over the jittered backoff below.
+            requested = None
+        if requested is not None:
+            if requested > _SHED_BACKOFF_CAP:
+                return None
+            # Honor the server's floor, then jitter above it — an identical
+            # Retry-After handed to every client is itself a synchronizer.
+            return requested + random.uniform(0, _SHED_BACKOFF_BASE)
+    ceiling = min(_SHED_BACKOFF_CAP, _SHED_BACKOFF_BASE * (2**attempt))
+    return random.uniform(0, ceiling)
+
+# Opt-out for the zero-login anonymous bootstrap (set to any non-empty value).
+ANON_OPT_OUT_ENV = "DEEPCELL_NO_ANON"
+
+
+class DeepCellClient:
+    """Thin sync wrapper around httpx with auto-auth.
+
+    The client resolves the access token from:
+    1. ``DEEPCELL_ACCESS_TOKEN`` env var (highest priority)
+    2. ``~/.deepcell/credentials.json``
+
+    Token refresh is transparent — if the stored token is near expiry,
+    the client calls ``POST /auth/refresh`` automatically.
+    """
+
+    def __init__(self, *, verbose: bool = False, command: str | None = None) -> None:
+        self._verbose = verbose
+        self._command = command
+        self._operation_id = str(uuid.uuid4())
+        # Client-level headers, so the surface rides on EVERY request this
+        # object makes — including the anonymous mint and the token refresh,
+        # which build their own per-request headers and would otherwise be the
+        # two calls a new user makes before anything else. httpx merges these
+        # with per-request headers rather than replacing them.
+        self._http = httpx.Client(timeout=_TIMEOUT, headers=client_headers())
+
+    # ── Helpers ─────────────────────────────────────────────
+
+    def _log(self, msg: str) -> None:
+        if self._verbose:
+            import sys
+
+            print(f"[debug] {msg}", file=sys.stderr)
+
+    def _mint_anon_session(self, device_id: str | None) -> str | None:
+        """Mint (or re-mint) an anonymous demo session. Returns the token or None.
+
+        This is the CLI variant of ``POST /demo/session``: the identity travels
+        as ``device_id`` in the body (no cookie jar) and the server echoes the
+        UUID to persist. Failures (flag off → 503, rate-limited, offline) all
+        degrade to ``None`` so the caller falls back to the plain login error.
+        """
+        import os
+
+        if os.environ.get(ANON_OPT_OUT_ENV):
+            return None
+        self._log("No credentials — requesting anonymous demo session…")
+        try:
+            resp = self._http.post(
+                f"{get_api_url()}/demo/session",
+                # The real surface, not a hardcoded "cli": the MCP server runs
+                # this code in-process, and the server reads this field both to
+                # pick the cookie-free identity flow AND (historically) to tag
+                # the session. Sending "cli" from MCP recorded the funnel's
+                # stage-1 entry under the wrong client.
+                json={"client": get_client_surface(), "device_id": device_id},
+            )
+        except Exception as e:
+            self._log(f"Anonymous session mint failed: {e}")
+            return None
+        if resp.status_code != 200:
+            self._log(f"Anonymous session mint failed ({resp.status_code})")
+            return None
+        data = resp.json()
+        save_credentials(
+            {
+                "access_token": data["access_token"],
+                "expires_at": time.time() + data["expires_in"],
+                "anonymous": True,
+                "device_id": data.get("device_id") or device_id,
+            }
+        )
+        return data["access_token"]
+
+    def _maybe_refresh(self) -> None:
+        """Refresh access token if it's about to expire."""
+        import os
+
+        # Skip if token comes from env var (user manages it)
+        if os.environ.get("DEEPCELL_ACCESS_TOKEN"):
+            return
+
+        creds = load_credentials()
+        expires_at = creds.get("expires_at", 0)
+        if time.time() < expires_at - _REFRESH_BUFFER:
+            return  # still valid
+
+        if creds.get("anonymous"):
+            # Anonymous sessions have no refresh token — re-mint with the
+            # stored device identity instead.
+            self._mint_anon_session(creds.get("device_id"))
+            return
+
+        refresh_tok = creds.get("refresh_token")
+        if not refresh_tok:
+            return  # nothing to refresh with
+
+        self._log("Access token near expiry — refreshing…")
+        try:
+            resp = self._http.post(
+                f"{get_api_url()}/auth/refresh",
+                json={"refresh_token": refresh_tok},
+            )
+            if resp.status_code == 200:
+                data = resp.json()
+                updated = {
+                    **creds,
+                    "access_token": data["access_token"],
+                    "expires_at": time.time() + data["expires_in"],
+                }
+                # Rotate refresh token when the server provides a new one
+                if data.get("refresh_token"):
+                    updated["refresh_token"] = data["refresh_token"]
+                save_credentials(updated)
+                self._log("Token refreshed successfully")
+            else:
+                self._log(f"Token refresh failed ({resp.status_code})")
+        except Exception as e:
+            self._log(f"Token refresh error: {e}")
+
+    def _headers(self) -> dict[str, str]:
+        self._maybe_refresh()
+        token = get_access_token()
+        if not token:
+            # Zero-login path: bootstrap an anonymous demo session so a new
+            # user can try the product before registering. Falls back to the
+            # login hint when the server has anonymous sessions disabled, the
+            # user opted out (DEEPCELL_NO_ANON), or the mint fails.
+            token = self._mint_anon_session(load_credentials().get("device_id"))
+        if not token:
+            raise AuthError()
+        warn_if_insecure(get_api_url())
+        from deepcell_cli import __version__
+
+        headers = {
+            "Authorization": f"Bearer {token}",
+            # `X-DeepCell-Client` is NOT set here. It is a client-level header
+            # (see __init__) carrying `<surface>/<version>`, so it rides on the
+            # unauthenticated calls too — and, unlike a literal "cli", it says
+            # `mcp` when the MCP server is the caller. Setting it per-request
+            # would override that and silently re-tag every MCP write.
+            "X-DeepCell-Client-Version": __version__,
+            "X-DeepCell-Operation-Id": self._operation_id,
+        }
+        if self._command:
+            headers["X-DeepCell-Command"] = self._command
+        return headers
+
+    @staticmethod
+    def _format_detail(detail: Any) -> str:
+        """Render FastAPI's error ``detail`` for a human/agent reader.
+
+        A 422 ``detail`` is a LIST OF DICTS (pydantic errors). ``str()`` on it
+        produces a raw Python repr — the surface an agent sees for every
+        constraint the CLI does not mirror (op-count caps, length limits,
+        numeric ranges), with no indication of which field or rule failed.
+        """
+        if not isinstance(detail, list):
+            return str(detail)
+        lines: list[str] = []
+        for item in detail:
+            if not isinstance(item, dict):
+                lines.append(f"  - {item}")
+                continue
+            loc = item.get("loc") or []
+            # Drop the leading "body"/"query" frame — it is noise to the caller.
+            parts = [str(p) for p in loc if str(p) not in ("body", "query", "path")]
+            field = ".".join(parts) if parts else "request"
+            msg = item.get("msg") or item.get("type") or "invalid"
+            lines.append(f"  - {field}: {msg}")
+        if not lines:
+            return str(detail)
+        return "request validation failed:\n" + "\n".join(lines)
+
+    def _handle_response(self, resp: httpx.Response, *, auth: bool = True) -> httpx.Response:
+        if resp.status_code >= 400:
+            try:
+                body = resp.json()
+                detail = body.get("detail", resp.text)
+            except Exception:
+                detail = resp.text
+            detail_str = self._format_detail(detail)
+            if resp.status_code == 403 and "email verification required" in detail_str.lower():
+                raise EmailVerificationRequired(detail_str)
+            payload = detail if isinstance(detail, (dict, list)) else None
+            headers = dict(resp.headers)
+            if resp.status_code in (401, 403):
+                from deepcell_cli.config import is_anonymous_session
+                from deepcell_cli.errors import AccountRequiredError, SessionExpiredError
+
+                if is_anonymous_session():
+                    # Anonymous sessions hitting a full-account surface get
+                    # the upgrade path, not a dead-end permission error.
+                    raise AccountRequiredError(resp.status_code, detail_str, payload=payload)
+                if resp.status_code == 401 and auth:
+                    # A 401 only gets here after _force_refresh has already had
+                    # its turn, so the credentials are genuinely dead. 403 is
+                    # left alone: that is a real permissions answer from a
+                    # session that worked.
+                    import os
+
+                    from deepcell_cli.config import ENV_ACCESS_TOKEN
+
+                    raise SessionExpiredError(
+                        resp.status_code,
+                        detail_str,
+                        payload=payload,
+                        from_env=bool(os.environ.get(ENV_ACCESS_TOKEN)),
+                    )
+            raise APIError(
+                resp.status_code, detail_str, payload=payload, headers=headers
+            )
+        return resp
+
+    def _force_refresh(self) -> bool:
+        """Force a token refresh. Returns True if successful."""
+        import os
+
+        if os.environ.get("DEEPCELL_ACCESS_TOKEN"):
+            return False
+
+        creds = load_credentials()
+        if creds.get("anonymous"):
+            self._log("401 received — re-minting anonymous session…")
+            return self._mint_anon_session(creds.get("device_id")) is not None
+
+        refresh_tok = creds.get("refresh_token")
+        if not refresh_tok:
+            return False
+
+        self._log("401 received — forcing token refresh…")
+        try:
+            resp = self._http.post(
+                f"{get_api_url()}/auth/refresh",
+                json={"refresh_token": refresh_tok},
+            )
+            if resp.status_code == 200:
+                data = resp.json()
+                updated = {
+                    **creds,
+                    "access_token": data["access_token"],
+                    "expires_at": time.time() + data["expires_in"],
+                }
+                if data.get("refresh_token"):
+                    updated["refresh_token"] = data["refresh_token"]
+                save_credentials(updated)
+                self._log("Token refreshed successfully (retry)")
+                return True
+            self._log(f"Token refresh failed ({resp.status_code})")
+        except Exception as e:
+            self._log(f"Token refresh error: {e}")
+        return False
+
+    def _retry_on_shed(self, send: Callable[[], httpx.Response]) -> httpx.Response:
+        """Replay ``send`` while the server is shedding load.
+
+        Returns the last response either way — a shed that outlives the retry
+        budget is still handed to :meth:`_handle_response`, so the caller sees
+        the server's own message rather than a substitute invented here.
+
+        Connection errors are deliberately not retried. ``send`` raises
+        :class:`CLIConnectionError` for those, and "the API is unreachable" is
+        a different problem with a different fix than "the API is busy".
+        """
+        for attempt in range(_MAX_SHED_RETRIES + 1):
+            resp = send()
+            if attempt == _MAX_SHED_RETRIES or not _is_shed(resp):
+                return resp
+            delay = _shed_delay(resp, attempt)
+            if delay is None:
+                return resp
+            self._log(
+                f"Server shed the request ({resp.status_code}) — "
+                f"retrying in {delay:.2f}s (attempt {attempt + 1}/{_MAX_SHED_RETRIES})"
+            )
+            time.sleep(delay)
+        return resp  # pragma: no cover — the loop always returns
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict | None = None,
+        json: Any = None,
+        auth: bool = True,
+        timeout: float | None = None,
+    ) -> httpx.Response:
+        """Send a request with automatic retry on 401 after token refresh.
+
+        ``timeout`` overrides the client default for long-running calls
+        (e.g. exports that recalculate and render server-side).
+
+        Load-shed responses are retried with jittered backoff underneath the
+        401 handling, so a refreshed token gets the same backpressure treatment
+        as the first attempt.
+        """
+        headers = self._headers() if auth else {}
+        url = get_api_url()
+        request_timeout = timeout if timeout is not None else httpx.USE_CLIENT_DEFAULT
+
+        def send() -> httpx.Response:
+            self._log(f"{method} {url}{path}")
+            try:
+                return self._http.request(
+                    method, f"{url}{path}", headers=headers, params=params, json=json,
+                    timeout=request_timeout,
+                )
+            except (httpx.ConnectError, httpx.TimeoutException, httpx.NetworkError) as exc:
+                raise CLIConnectionError(url, exc) from exc
+
+        resp = self._retry_on_shed(send)
+
+        # On 401, try refreshing the token and retry once
+        if resp.status_code == 401 and auth and self._force_refresh():
+            headers = self._headers()
+            resp = self._retry_on_shed(send)
+
+        return self._handle_response(resp, auth=auth)
+
+    # ── Public API ──────────────────────────────────────────
+
+    def get(self, path: str, *, params: dict | None = None, auth: bool = True) -> Any:
+        """Send GET request and return parsed JSON."""
+        return self._request("GET", path, params=params, auth=auth).json()
+
+    def get_with_revision(
+        self, path: str, *, params: dict | None = None, auth: bool = True
+    ) -> tuple[Any, str | None]:
+        """GET a workspace file and return ``(json, revision)``.
+
+        The revision travels as the ``X-DeepCell-Revision`` response header, not
+        in the body, so a plain :meth:`get` throws it away. Any command that
+        does fetch → transform → write back needs it: without it the write is
+        unguarded and silently clobbers whatever landed in between (#1122).
+        ``None`` when the server did not report one — callers then write
+        unguarded, exactly as before.
+        """
+        resp = self._request("GET", path, params=params, auth=auth)
+        return resp.json(), resp.headers.get("X-DeepCell-Revision")
+
+    def post(self, path: str, *, json: Any = None, auth: bool = True) -> Any:
+        """Send POST request and return parsed JSON."""
+        return self._request("POST", path, json=json, auth=auth).json()
+
+    def post_raw(
+        self, path: str, *, json: Any = None, auth: bool = True,
+        timeout: float | None = None,
+    ) -> httpx.Response:
+        """Send POST and return the raw httpx.Response (for binary)."""
+        return self._request("POST", path, json=json, auth=auth, timeout=timeout)
+
+    def put(self, path: str, *, json: Any = None, auth: bool = True) -> Any:
+        return self._request("PUT", path, json=json, auth=auth).json()
+
+    def delete(
+        self, path: str, *, json: Any = None, auth: bool = True
+    ) -> httpx.Response:
+        """Send DELETE and return the raw response.
+
+        ``json`` carries a body — unusual for DELETE, but ``/auth/me`` requires
+        typed confirmation and those fields must not travel in a query string
+        (access logs, shell history).
+        """
+        return self._request("DELETE", path, json=json, auth=auth)
+
+    def post_multipart(
+        self,
+        path: str,
+        *,
+        file_path: str | None = None,
+        file_data: bytes | None = None,
+        file_name: str = "upload",
+        fields: dict[str, str] | None = None,
+        auth: bool = True,
+    ) -> Any:
+        """Send a multipart/form-data POST with a file and form fields."""
+        headers = self._headers() if auth else {}
+        url = get_api_url()
+        self._log(f"POST (multipart) {url}{path}")
+
+        if file_data is None and file_path is not None:
+            import pathlib
+            file_data = pathlib.Path(file_path).read_bytes()
+            if not file_name or file_name == "upload":
+                file_name = pathlib.Path(file_path).name
+
+        files = {"file": (file_name, file_data, "application/octet-stream")}
+        data = fields or {}
+
+        # Safe to replay: the payload is already in memory as bytes, so a retry
+        # re-reads nothing from disk and cannot send a half-changed file.
+        def send() -> httpx.Response:
+            try:
+                return self._http.post(
+                    f"{url}{path}", headers=headers, files=files, data=data,
+                )
+            except (httpx.ConnectError, httpx.TimeoutException, httpx.NetworkError) as exc:
+                raise CLIConnectionError(url, exc) from exc
+
+        resp = self._retry_on_shed(send)
+
+        if resp.status_code == 401 and auth and self._force_refresh():
+            headers = self._headers()
+            resp = self._retry_on_shed(send)
+
+        return self._handle_response(resp, auth=auth).json()
+
+    def post_no_content(self, path: str, *, json: Any = None, auth: bool = True) -> None:
+        """POST expecting 204 No Content."""
+        self._request("POST", path, json=json, auth=auth)
+
+    def close(self) -> None:
+        self._http.close()

deepcell_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules."""

deepcell_cli/commands/_batch_input.py

@@ -0,0 +1,29 @@
+"""Shared ``--batch`` payload reader.
+
+Lives in its own module because both ``edit`` and ``replace`` take a
+``--batch`` argument in the same three forms, and ``edit`` imports ``replace``
+for the deprecated ``edit --replace`` alias — a helper owned by either one
+would close the import cycle.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def read_batch_payload(batch_arg: str) -> str:
+    """Return the raw JSON text for a ``--batch`` argument.
+
+    Accepts three forms:
+      - inline JSON — the value starts with ``[`` or ``{`` (agents / MCP,
+        where a local file path or stdin is unavailable);
+      - ``-`` — read from stdin;
+      - anything else — a local JSON file path.
+    """
+    stripped = batch_arg.strip()
+    if stripped.startswith(("[", "{")):
+        return stripped
+    if batch_arg == "-":
+        return sys.stdin.read()
+    with open(batch_arg) as fh:
+        return fh.read()

deepcell_cli/commands/_datatypes.py

@@ -0,0 +1,56 @@
+"""Shared `--data-type` recognition for the CLI.
+
+The defs item ops store data types verbatim, so a typo such as
+`--data-type moneytary` would otherwise make downstream formatters fall back
+to their default without a word.
+
+The vocabulary is not formally closed (documents legitimately carry `text`,
+`date`, and other author-chosen types), so an unrecognized value is a
+**warning**, not a rejection — the same call the file validator makes for
+undeclared custom dimensions.
+"""
+
+from __future__ import annotations
+
+# The types that actually drive rendering. A local copy on purpose: this
+# warning fires before the request goes out, so it cannot ask the server. The
+# authored answer — what each type MEANS and what it drives — lives in
+# `backend/src/core/ref/namespaces/datatypes.py` and is read with
+# `deepcell ref datatype`; keep the two in step, and put any explanation
+# there rather than here.
+RECOGNIZED_DATA_TYPES = frozenset({
+    "monetary",
+    "percentage",
+    "ratio",
+    "quantity",
+    "count",
+    "number",
+    "text",
+    "date",
+})
+
+
+def warn_unrecognized_data_type(data_type: str | None) -> str | None:
+    """Return a warning message for an unrecognized *data_type*, else None."""
+    if not data_type:
+        return None
+    if data_type.lower() in RECOGNIZED_DATA_TYPES:
+        return None
+    known = ", ".join(sorted(RECOGNIZED_DATA_TYPES))
+    suggestion = ""
+    try:
+        import difflib
+
+        close = difflib.get_close_matches(
+            data_type.lower(), sorted(RECOGNIZED_DATA_TYPES), n=1, cutoff=0.6
+        )
+        if close:
+            suggestion = f" Did you mean '{close[0]}'?"
+    except Exception:  # pragma: no cover - difflib is stdlib
+        pass
+    return (
+        f"'{data_type}' is not a recognized data type.{suggestion} "
+        f"It will be stored verbatim, but number formatting will fall back to "
+        f"the default. Recognized: {known}. "
+        f"What each one means: deepcell ref datatype"
+    )