geolens-cli 1.0.0__py3-none-any.whl

geolens_cli/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: Apache-2.0
+"""GeoLens CLI.
+
+Hand-maintained — NOT regenerated. Version is sourced from package metadata
+so cli/pyproject.toml is the single source of truth for the version string.
+"""
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("geolens")
+except PackageNotFoundError:
+    # Local dev tree before `pip install -e .` — fall back to a sentinel.
+    __version__ = "0.0.0+dev"
+
+__all__ = ["__version__"]

geolens_cli/_sdk_helpers.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: Apache-2.0
+"""SDK call helpers — Response → T translator + httpx-error → exit-code mapper.
+
+Hand-maintained — NOT regenerated. Centralizes the SDK call boundary so each
+command's body is free of error-mapping noise (CONTEXT.md D-32, D-33).
+
+Note on httpx import: this module imports httpx ONLY for exception types
+used in error mapping. The httpx instance comes from the SDK
+(client.get_httpx_client()); the CLI never constructs an httpx.Client.
+OCCLI-06 enforcement is on the dep list (cli/pyproject.toml has no httpx
+direct dep — it's transitive via the geolens SDK). The `cli-lint` grep gate
+in Plan 06 is scoped to `^(import|from) (httpx|requests)` lines that
+construct clients; httpx exception imports here are explicitly allowed.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, TypeVar
+
+import typer
+
+T = TypeVar("T")
+
+# Exit codes per CONTEXT.md D-32
+EXIT_OK = 0
+EXIT_GENERIC = 1
+EXIT_USAGE = 2
+EXIT_AUTH = 3
+EXIT_NETWORK = 4
+EXIT_SERVER = 5
+
+
+def unwrap(resp: Any, *, expected: int = 200) -> Any:
+    """Translate an SDK Response into either parsed model or typer.Exit.
+
+    Maps HTTP status to exit codes:
+      expected (default 200) → return resp.parsed
+      401, 403 → exit 3 (EXIT_AUTH)
+      5xx      → exit 5 (EXIT_SERVER)
+      other    → exit 1 (EXIT_GENERIC)
+    """
+    from geolens.models.problem_detail import ProblemDetail  # lazy
+
+    sc = int(resp.status_code)
+    if sc == expected:
+        if isinstance(resp.parsed, ProblemDetail):
+            typer.secho(f"Error: {resp.parsed.detail}", fg="red", err=True)
+            raise typer.Exit(EXIT_SERVER if sc >= 500 else EXIT_GENERIC)
+        return resp.parsed
+
+    detail = ""
+    if isinstance(resp.parsed, ProblemDetail):
+        detail = f": {resp.parsed.detail}"
+
+    if sc == 401:
+        typer.secho(f"Authentication required{detail}. Run `geolens login` first.", fg="red", err=True)
+        raise typer.Exit(EXIT_AUTH)
+    if sc == 403:
+        typer.secho(f"Permission denied{detail}", fg="red", err=True)
+        raise typer.Exit(EXIT_AUTH)
+    if 500 <= sc <= 599:
+        typer.secho(f"Server error ({sc}){detail}", fg="red", err=True)
+        raise typer.Exit(EXIT_SERVER)
+    typer.secho(f"Request failed ({sc}){detail}", fg="red", err=True)
+    raise typer.Exit(EXIT_GENERIC)
+
+
+def call_sdk(fn: Callable[..., Any], **kwargs: Any) -> Any:
+    """Run a sync_detailed call, mapping httpx exceptions to exit codes."""
+    import httpx  # lazy — only for exception types
+
+    try:
+        return fn(**kwargs)
+    except httpx.TimeoutException:
+        typer.secho("Request timed out", fg="red", err=True)
+        raise typer.Exit(EXIT_NETWORK)
+    except httpx.NetworkError as exc:
+        typer.secho(f"Network error: {exc}", fg="red", err=True)
+        raise typer.Exit(EXIT_NETWORK)

geolens_cli/auth.py

@@ -0,0 +1,225 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Credential storage — OS keyring with credentials.toml fallback.
+
+Hand-maintained — NOT regenerated. Mirrors sdks/python/geolens/auth.py's
+"configure exactly one" discipline for BearerToken vs ApiKey.
+
+Backend storage precedence (matches CONTEXT.md D-35):
+    CLI flag (handled in main.py)
+    > GEOLENS_TOKEN env var
+    > credentials.toml
+    > OS keyring
+
+Storage backends:
+    Default: OS keyring via `keyring` (service="geolens", account=<instance_url>)
+    Fallback: ~/.config/geolens/credentials.toml (mode 0600)
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import keyring
+import structlog
+import tomli_w
+import tomllib
+from keyring.errors import KeyringError
+
+from . import config as _config
+
+log = structlog.get_logger()
+SERVICE = "geolens"
+
+
+@dataclass(frozen=True)
+class BearerToken:
+    value: str
+
+
+@dataclass(frozen=True)
+class ApiKey:
+    value: str
+
+
+# ---------- Internal helpers ----------
+
+def _keyring_account_token(instance: str) -> str:
+    return instance
+
+
+def _keyring_account_refresh(instance: str) -> str:
+    return f"{instance}:refresh"
+
+
+def _keyring_account_api_key(instance: str) -> str:
+    return f"{instance}:api_key"
+
+
+def _read_credentials_file() -> dict:
+    path = _config.credentials_path()
+    if not path.is_file():
+        return {}
+    try:
+        return tomllib.loads(path.read_text())
+    except tomllib.TOMLDecodeError:
+        return {}
+
+
+def _write_credentials_file(data: dict) -> None:
+    _config.atomic_write_text(
+        _config.credentials_path(),
+        tomli_w.dumps(data),
+        mode=0o600,
+    )
+
+
+def _set_credential_field(instance: str, field: str, value: str) -> None:
+    data = _read_credentials_file()
+    data.setdefault(instance, {})[field] = value
+    _write_credentials_file(data)
+
+
+def _clear_credential_section(instance: str) -> None:
+    data = _read_credentials_file()
+    data.pop(instance, None)
+    if data:
+        _write_credentials_file(data)
+    else:
+        # Empty -> remove the file entirely so `geolens logout` leaves no trace.
+        path = _config.credentials_path()
+        if path.exists():
+            path.unlink()
+
+
+# ---------- Store ----------
+
+def store_bearer_token(instance: str, token: str, *, no_keyring: bool = False) -> str:
+    """Store the access token. Returns 'keyring' or 'file'."""
+    if not no_keyring:
+        try:
+            keyring.set_password(SERVICE, _keyring_account_token(instance), token)
+            return "keyring"
+        except KeyringError as exc:
+            log.warning("keyring_unavailable_falling_back_to_file", error=str(exc))
+    _set_credential_field(instance, "bearer_token", token)
+    return "file"
+
+
+def store_api_key(instance: str, api_key: str, *, no_keyring: bool = False) -> str:
+    """Store an API key. Returns 'keyring' or 'file'."""
+    if not no_keyring:
+        try:
+            keyring.set_password(SERVICE, _keyring_account_api_key(instance), api_key)
+            return "keyring"
+        except KeyringError as exc:
+            log.warning("keyring_unavailable_falling_back_to_file", error=str(exc))
+    _set_credential_field(instance, "api_key", api_key)
+    return "file"
+
+
+def store_refresh_token(instance: str, refresh: str, *, no_keyring: bool = False) -> str:
+    if not no_keyring:
+        try:
+            keyring.set_password(SERVICE, _keyring_account_refresh(instance), refresh)
+            return "keyring"
+        except KeyringError as exc:
+            log.warning("keyring_unavailable_falling_back_to_file", error=str(exc))
+    _set_credential_field(instance, "refresh_token", refresh)
+    return "file"
+
+
+# ---------- Load ----------
+
+def load_bearer_token(instance: str) -> Optional[BearerToken]:
+    """Return the active bearer token per the D-35 precedence."""
+    env_token = _config.get_token_from_env()
+    if env_token:
+        return BearerToken(env_token)
+    # credentials.toml > keyring (file is explicit; keyring is fallback)
+    data = _read_credentials_file().get(instance, {})
+    token = data.get("bearer_token")
+    if token:
+        return BearerToken(token)
+    try:
+        kr_token = keyring.get_password(SERVICE, _keyring_account_token(instance))
+    except KeyringError:
+        return None
+    return BearerToken(kr_token) if kr_token else None
+
+
+def load_api_key(instance: str) -> Optional[ApiKey]:
+    data = _read_credentials_file().get(instance, {})
+    key = data.get("api_key")
+    if key:
+        return ApiKey(key)
+    try:
+        kr_key = keyring.get_password(SERVICE, _keyring_account_api_key(instance))
+    except KeyringError:
+        return None
+    return ApiKey(kr_key) if kr_key else None
+
+
+def load_refresh_token(instance: str) -> Optional[str]:
+    data = _read_credentials_file().get(instance, {})
+    refresh = data.get("refresh_token")
+    if refresh:
+        return refresh
+    try:
+        return keyring.get_password(SERVICE, _keyring_account_refresh(instance))
+    except KeyringError:
+        return None
+
+
+# ---------- Delete ----------
+
+def delete_credentials(instance: str) -> None:
+    """Remove all three keyring entries AND the credentials.toml section.
+
+    Missing entries are silently ignored — logout is idempotent.
+    """
+    for account in (
+        _keyring_account_token(instance),
+        _keyring_account_refresh(instance),
+        _keyring_account_api_key(instance),
+    ):
+        try:
+            keyring.delete_password(SERVICE, account)
+        except Exception:
+            # PasswordDeleteError + KeyringError + missing entries all swallowed.
+            pass
+    _clear_credential_section(instance)
+
+
+# ---------- Refresh ----------
+
+def try_refresh(instance: str) -> Optional[str]:
+    """Attempt a single refresh; return new access token or None on failure.
+
+    Per CONTEXT D-13, this is called once on a 401. If it fails, the caller
+    prints "Session expired" and exits with EXIT_AUTH (3).
+    """
+    refresh = load_refresh_token(instance)
+    if not refresh:
+        return None
+    from geolens import GeolensClient
+    from geolens.api.auth import refresh_auth_refresh_post
+    from geolens.models.refresh_request import RefreshRequest
+
+    try:
+        sdk = GeolensClient(base_url=instance)
+        body = RefreshRequest(refresh_token=refresh)
+        resp = refresh_auth_refresh_post.sync_detailed(client=sdk.client, body=body)
+    except Exception as exc:  # network or unexpected SDK error
+        log.warning("refresh_failed", error=str(exc))
+        return None
+    if int(resp.status_code) != 200:
+        return None
+    parsed = resp.parsed
+    if parsed is None or not getattr(parsed, "access_token", None):
+        return None
+    new_access = parsed.access_token
+    store_bearer_token(instance, new_access, no_keyring=False)
+    new_refresh = getattr(parsed, "refresh_token", None)
+    if new_refresh:
+        store_refresh_token(instance, new_refresh, no_keyring=False)
+    return new_access

geolens_cli/config.py

@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: Apache-2.0
+"""XDG-compliant config + atomic TOML I/O for the GeoLens CLI.
+
+Hand-maintained — NOT regenerated. config.toml stores the active instance
+URL and username; credentials.toml stores tokens (only when --no-keyring
+is set or the keyring is unavailable). Per CONTEXT.md D-11, tokens NEVER
+appear in config.toml.
+"""
+from __future__ import annotations
+
+import os
+import tempfile
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import tomli_w
+from platformdirs import user_config_dir
+
+APP_NAME = "geolens"
+
+
+def _config_dir() -> Path:
+    # platformdirs honors XDG_CONFIG_HOME on Linux, AppData on Windows.
+    # appauthor=False so the path is ~/.config/geolens (not ~/.config/geolens/geolens).
+    return Path(user_config_dir(APP_NAME, appauthor=False))
+
+
+def config_path() -> Path:
+    return _config_dir() / "config.toml"
+
+
+def credentials_path() -> Path:
+    return _config_dir() / "credentials.toml"
+
+
+@dataclass
+class AppConfig:
+    instance: Optional[str] = None
+    username: Optional[str] = None
+
+    @classmethod
+    def load(cls) -> "AppConfig":
+        path = config_path()
+        if not path.is_file():
+            return cls()
+        try:
+            data = tomllib.loads(path.read_text())
+        except tomllib.TOMLDecodeError:
+            return cls()
+        default = data.get("default", {})
+        return cls(
+            instance=default.get("instance"),
+            username=default.get("username"),
+        )
+
+
+def load_config() -> AppConfig:
+    return AppConfig.load()
+
+
+def write_default_instance(instance: str, username: Optional[str]) -> None:
+    """Write the active instance URL + username to config.toml.
+
+    Does NOT write tokens (D-11). Tokens go to keyring or credentials.toml.
+    """
+    section: dict[str, str] = {"instance": instance}
+    if username is not None:
+        section["username"] = username
+    payload = {"default": section}
+    atomic_write_text(config_path(), tomli_w.dumps(payload), mode=0o600)
+
+
+def atomic_write_text(path: Path, content: str, *, mode: int = 0o600) -> None:
+    """Write content to path atomically with the given file mode.
+
+    Per RESEARCH Pattern 4: tempfile in same dir + chmod + os.replace. Parent
+    directory is created at 0o700 if missing. On any failure the tempfile is
+    removed before the exception propagates.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    # Tighten parent dir mode in case it pre-existed at a different mode.
+    try:
+        os.chmod(path.parent, 0o700)
+    except OSError:
+        # On some platforms (Windows) chmod is a no-op; not fatal.
+        pass
+    fd, tmp_path = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        os.write(fd, content.encode("utf-8"))
+        os.close(fd)
+        os.chmod(tmp_path, mode)
+        os.replace(tmp_path, path)
+    except Exception:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
+
+
+def get_instance_from_env() -> Optional[str]:
+    return os.environ.get("GEOLENS_INSTANCE")
+
+
+def get_token_from_env() -> Optional[str]:
+    return os.environ.get("GEOLENS_TOKEN")
+
+
+def normalize_instance_url(url: str) -> str:
+    """Strip trailing slash; reject non-http(s) schemes via ValueError."""
+    url = url.strip()
+    if not url:
+        raise ValueError("Instance URL must not be empty")
+    if not url.startswith(("http://", "https://")):
+        raise ValueError(f"Instance URL must use http or https scheme: got {url!r}")
+    return url.rstrip("/")

geolens_cli/export_stac.py

@@ -0,0 +1,143 @@
+# SPDX-License-Identifier: Apache-2.0
+"""STAC export — fetch a STAC 1.1 item for a raster dataset and render it.
+
+Hand-maintained — NOT regenerated. Pure SDK pass-through (D-25, D-28). The
+backend at ``backend/app/standards/stac/router.py`` already produces
+conformant STAC 1.1; the CLI is a pretty-printer. Vector datasets are
+rejected pre-flight (D-26) so users see a clear message rather than a
+confusing 404 or 422 from ``GET /stac/items/{id}``.
+
+OCCLI-06 invariant: zero direct ``httpx`` / ``requests`` imports here —
+every HTTP call goes through the generated SDK functions.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from . import config as _config
+from ._sdk_helpers import call_sdk, unwrap
+
+
+def fetch_record_type(client: Any, dataset_id: str) -> str:
+    """Pre-flight check: return the dataset's ``record_type``.
+
+    Per D-26: STAC export is raster-only. We GET ``/datasets/{id}`` first
+    to avoid a confusing error from ``/stac/items/{id}`` when the dataset
+    is vector-typed.
+
+    Returns:
+        The literal string ``"not_found"`` on a 404 (so the caller can
+        emit a friendly "Dataset not found" message and exit 1). For all
+        other non-200 statuses, ``unwrap`` translates to the appropriate
+        ``typer.Exit`` (auth/server/generic). On success, returns the
+        ``record_type`` string from ``DatasetResponse``
+        (e.g., ``"raster_dataset"``, ``"vector_dataset"``).
+    """
+    from geolens.api.datasets import (
+        get_single_dataset_datasets_dataset_id_get,
+    )
+
+    resp = call_sdk(
+        get_single_dataset_datasets_dataset_id_get.sync_detailed,
+        dataset_id=dataset_id,
+        client=client,
+    )
+    sc = int(resp.status_code)
+    if sc == 404:
+        return "not_found"
+    if sc != 200:
+        # Let unwrap() translate the error → exit code (401/403/5xx/etc.)
+        unwrap(resp, expected=200)
+
+    rec = getattr(resp.parsed, "record_type", None)
+    if rec is None:
+        # Defensive: try alternate field names if the OpenAPI shape changes.
+        rec = (
+            getattr(resp.parsed, "type", None)
+            or getattr(resp.parsed, "dataset_type", None)
+        )
+    return str(rec) if rec else "unknown"
+
+
+def is_raster(record_type: str) -> bool:
+    """True iff ``record_type`` looks like a raster dataset.
+
+    Defensive: backend may use ``raster_dataset``, ``RasterDataset``, or
+    bare ``raster``. We accept any of these so a future rename of the
+    enum doesn't silently break the CLI guard.
+    """
+    if not record_type:
+        return False
+    return record_type.lower().startswith("raster")
+
+
+def fetch_stac_item(client: Any, dataset_id: str) -> dict:
+    """Fetch the STAC item dict for a dataset.
+
+    Caller pre-checks ``record_type`` via :func:`fetch_record_type` so
+    this function assumes the dataset is raster-typed.
+
+    The SDK's ``get_item_stac`` is generated with ``Any`` as the 200
+    response type (the OpenAPI schema declares the response as a free-
+    form dict). The parsed body is therefore the STAC item dict directly
+    — no ``.to_dict()`` needed.
+
+    Defensive shape handling (in case future SDK regen wraps the body
+    in a generated model):
+      * If ``parsed`` is None, json-load ``resp.content``.
+      * If ``parsed`` has ``.to_dict()``, call it.
+      * If ``parsed`` is already a dict, return it.
+    """
+    from geolens.api.stac import get_item_stac_items_item_id_get
+
+    resp = call_sdk(
+        get_item_stac_items_item_id_get.sync_detailed,
+        item_id=dataset_id,
+        client=client,
+    )
+    item = unwrap(resp, expected=200)
+    if item is None:
+        return json.loads(resp.content.decode("utf-8"))
+    if isinstance(item, dict):
+        return item
+    if hasattr(item, "to_dict"):
+        return item.to_dict()
+    # Unknown shape — best-effort fall back to the raw response body.
+    return json.loads(resp.content.decode("utf-8"))
+
+
+def render_stac_json(item: dict, *, compact: bool = False) -> str:
+    """Format a STAC dict as JSON.
+
+    Default (D-27): pretty-printed, ``indent=2``, sorted keys, trailing
+    newline — produces diff-stable output.
+
+    Compact: single-line JSON with no whitespace separators — for piping
+    into ``jq`` or ``curl --data``.
+    """
+    if compact:
+        return json.dumps(item, sort_keys=True, separators=(",", ":"))
+    return json.dumps(item, indent=2, sort_keys=True) + "\n"
+
+
+def write_stac_to_file(item: dict, path: Path, *, compact: bool = False) -> None:
+    """Atomically write the rendered STAC JSON to ``path``.
+
+    Mode 0o644 — STAC payloads are not secrets. The atomic ``tempfile +
+    os.replace`` write prevents half-written files on Ctrl+C (D-27).
+    """
+    _config.atomic_write_text(
+        path,
+        render_stac_json(item, compact=compact),
+        mode=0o644,
+    )
+
+
+def vector_rejection_message(record_type: str) -> str:
+    """User-facing rejection message for non-raster datasets (D-26)."""
+    return (
+        "STAC export is supported for raster datasets only — "
+        f"got record_type={record_type}"
+    )