elva-cli 0.3.0__tar.gz → 0.5.0__tar.gz

elva_cli-0.5.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## Unreleased
+
+### Added
+- **Identify as a first-class refresh client (ELVA-200).** Every request now
+  sends `X-Elva-Client: cli` and a `User-Agent: elva-cli/<version>`. The refresh
+  and CLI-login exchanges carry the marker so the backend routes them on the
+  body-token path and, once its compatibility flag is turned off, does not
+  reject the CLI as an unmarked client.
+- **Refresh-and-retry on 401.** An idempotent request (GET/HEAD) that returns
+  401 on a token that looked valid now forces one refresh and retries once.
+  Non-idempotent requests (the spec upload) are never auto-replayed.
+- **Backoff on transient refresh failures.** A refresh that hits 429/5xx or a
+  network error is retried with backoff (1s/2s/4s) before surfacing as a
+  transient `ApiError` (exit 5); it never forces a re-login.
+
+### Changed
+- Refresh continues to happen proactively ~60s before the access token expires
+  and to persist the rotated token atomically (temp file + rename, 0600) before
+  the response is used — unchanged, but now covered by explicit tests.
+
+### Compatibility
+This version works with **both** the flagged and the unflagged backend:
+- While the backend keeps `AUTH_ALLOW_BODY_REFRESH_TOKEN` on, unmarked body
+  refreshes still work, so **older CLI versions keep working** too.
+- Once the backend turns that flag off (this CLI version being the minimum
+  supported), the server rejects unmarked and legacy ("family-less") refresh
+  tokens with `401 REFRESH_TOKEN_LEGACY`. This CLI maps that to
+  *"Your session has expired. Run `elva auth login` to sign in again."*
+  (exit code 3). **Older CLI versions stop working at that point** and users
+  must upgrade and re-login once.

{elva_cli-0.3.0 → elva_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: elva-cli
-Version: 0.3.0
+Version: 0.5.0
 Summary: Elva - CLI for Theneo Elva
 Project-URL: Homepage, https://getelva.ai
 Project-URL: Source, https://github.com/Theneo-Inc/theneo-elva-cli
@@ -19,11 +19,14 @@ Requires-Python: >=3.11
 Requires-Dist: keyring>=25
 Requires-Dist: platformdirs>=4.2
 Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.0
 Requires-Dist: typer<1.0,>=0.15
 Provides-Extra: dev
 Requires-Dist: mypy>=1.11; extra == 'dev'
 Requires-Dist: pytest>=8.2; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # Elva CLI
@@ -31,8 +34,7 @@ Description-Content-Type: text/markdown
 Manage your [Elva](https://getelva.ai) API projects from the terminal: import specs,
 inspect collections, and generate MCP servers without opening a browser.
 
-> **Early alpha.** The command surface is still taking shape. This release ships
-> `--version` and `--help` only; the first working commands land in `0.1.0`.
+> **Early alpha.** The command surface is still taking shape.
 
 ## Install
 
@@ -74,6 +76,120 @@ powershell -c "irm https://astral.sh/uv/install.ps1|iex" # Windows
 uv tool upgrade elva-cli      # or: pipx upgrade elva-cli
 ```
 
+## Importing a spec
+
+Create a collection from an OpenAPI document:
+
+```bash
+elva import spec openapi.yaml
+```
+
+```
+Created Payments Platform API from openapi.yaml.
+
+workspace      Theneo
+format         openapi
+title          Payments Platform API
+version        2.4.1
+endpoints      17
+collection id  6aa1322d7ef06cc8f9017460
+url            https://app.getelva.ai/collections?selected=6aa1322d7ef06cc8f9017460
+```
+
+The collection is named after the spec's `info.title`. Override it with `--name`, which
+is also what you will be asked for if the spec has no title:
+
+```bash
+elva import spec openapi.yaml --name "Payments v2"
+```
+
+### Where the spec comes from
+
+A path, a URL Elva fetches itself, or stdin:
+
+```bash
+elva import spec openapi.yaml
+```
+
+```bash
+elva import spec --url https://example.com/openapi.yaml --name Payments
+```
+
+```bash
+curl -s https://example.com/openapi.yaml | elva import spec - --name Payments
+```
+
+A URL is fetched server-side, so nothing is read locally -- which is why `--name` cannot
+be defaulted from it. Files must be `.json`, `.yaml` or `.yml`, and 10 MB or smaller.
+
+### Updating an existing collection
+
+Importing never overwrites. Replacing the spec of a collection that already exists is a
+separate, explicit action:
+
+```bash
+elva -c payments-api import spec openapi.yaml --update
+```
+
+The previous spec is kept as a restorable version. `--collection` takes a name or an id,
+and `--workspace` picks which workspace to look that name up in; an account with a single
+workspace needs neither. Both are global flags, so they go before the subcommand, and both
+can live in `elva.json` instead.
+
+### Checking first
+
+`--dry-run` reports what would happen and sends nothing at all -- it works signed out:
+
+```bash
+elva import spec openapi.yaml --dry-run
+```
+
+```
+Would create Payments Platform API from openapi.yaml.
+
+format     openapi
+title      Payments Platform API
+version    2.4.1
+endpoints  17
+size       11.3 KB
+
+Nothing was sent. Drop --dry-run to do it.
+```
+
+### Postman
+
+Postman collections are not supported here. Elva reads operations out of an uploaded file
+as OpenAPI, so a Postman collection would import successfully and produce an empty
+collection -- `elva` refuses it rather than let that happen. Export to OpenAPI first, or
+use the Postman integration in the web app.
+
+### In CI
+
+The exit code is the whole interface:
+
+```bash
+elva import spec openapi.yaml
+case $? in
+  0) echo "imported" ;;
+  2) echo "bad invocation - wrong name, missing file, name already taken"; exit 1 ;;
+  3) echo "not signed in"; exit 1 ;;
+  4) echo "the spec was rejected"; exit 1 ;;
+  5) echo "Elva unreachable"; exit 0 ;;
+esac
+```
+
+Note what `0` does and does not mean. Elva stores the file and extracts what it can, so a
+spec it cannot parse imports *successfully* with no endpoints in it rather than failing.
+The CLI says so plainly in that case, but the exit code still comes from the server. A
+pipeline that cares should check the count:
+
+```bash
+count=$(elva --json import spec openapi.yaml | jq '.endpoints // 0')
+[ "$count" -gt 0 ] || { echo "spec produced no endpoints"; exit 1; }
+```
+
+See [exit codes](docs/exit-codes.md) for the full table.
+
 ## Configuration
 
 Settings can come from several places. Highest priority wins:

{elva_cli-0.3.0 → elva_cli-0.5.0}/README.md

@@ -3,8 +3,7 @@
 Manage your [Elva](https://getelva.ai) API projects from the terminal: import specs,
 inspect collections, and generate MCP servers without opening a browser.
 
-> **Early alpha.** The command surface is still taking shape. This release ships
-> `--version` and `--help` only; the first working commands land in `0.1.0`.
+> **Early alpha.** The command surface is still taking shape.
 
 ## Install
 
@@ -46,6 +45,120 @@ powershell -c "irm https://astral.sh/uv/install.ps1|iex" # Windows
 uv tool upgrade elva-cli      # or: pipx upgrade elva-cli
 ```
 
+## Importing a spec
+
+Create a collection from an OpenAPI document:
+
+```bash
+elva import spec openapi.yaml
+```
+
+```
+Created Payments Platform API from openapi.yaml.
+
+workspace      Theneo
+format         openapi
+title          Payments Platform API
+version        2.4.1
+endpoints      17
+collection id  6aa1322d7ef06cc8f9017460
+url            https://app.getelva.ai/collections?selected=6aa1322d7ef06cc8f9017460
+```
+
+The collection is named after the spec's `info.title`. Override it with `--name`, which
+is also what you will be asked for if the spec has no title:
+
+```bash
+elva import spec openapi.yaml --name "Payments v2"
+```
+
+### Where the spec comes from
+
+A path, a URL Elva fetches itself, or stdin:
+
+```bash
+elva import spec openapi.yaml
+```
+
+```bash
+elva import spec --url https://example.com/openapi.yaml --name Payments
+```
+
+```bash
+curl -s https://example.com/openapi.yaml | elva import spec - --name Payments
+```
+
+A URL is fetched server-side, so nothing is read locally -- which is why `--name` cannot
+be defaulted from it. Files must be `.json`, `.yaml` or `.yml`, and 10 MB or smaller.
+
+### Updating an existing collection
+
+Importing never overwrites. Replacing the spec of a collection that already exists is a
+separate, explicit action:
+
+```bash
+elva -c payments-api import spec openapi.yaml --update
+```
+
+The previous spec is kept as a restorable version. `--collection` takes a name or an id,
+and `--workspace` picks which workspace to look that name up in; an account with a single
+workspace needs neither. Both are global flags, so they go before the subcommand, and both
+can live in `elva.json` instead.
+
+### Checking first
+
+`--dry-run` reports what would happen and sends nothing at all -- it works signed out:
+
+```bash
+elva import spec openapi.yaml --dry-run
+```
+
+```
+Would create Payments Platform API from openapi.yaml.
+
+format     openapi
+title      Payments Platform API
+version    2.4.1
+endpoints  17
+size       11.3 KB
+
+Nothing was sent. Drop --dry-run to do it.
+```
+
+### Postman
+
+Postman collections are not supported here. Elva reads operations out of an uploaded file
+as OpenAPI, so a Postman collection would import successfully and produce an empty
+collection -- `elva` refuses it rather than let that happen. Export to OpenAPI first, or
+use the Postman integration in the web app.
+
+### In CI
+
+The exit code is the whole interface:
+
+```bash
+elva import spec openapi.yaml
+case $? in
+  0) echo "imported" ;;
+  2) echo "bad invocation - wrong name, missing file, name already taken"; exit 1 ;;
+  3) echo "not signed in"; exit 1 ;;
+  4) echo "the spec was rejected"; exit 1 ;;
+  5) echo "Elva unreachable"; exit 0 ;;
+esac
+```
+
+Note what `0` does and does not mean. Elva stores the file and extracts what it can, so a
+spec it cannot parse imports *successfully* with no endpoints in it rather than failing.
+The CLI says so plainly in that case, but the exit code still comes from the server. A
+pipeline that cares should check the count:
+
+```bash
+count=$(elva --json import spec openapi.yaml | jq '.endpoints // 0')
+[ "$count" -gt 0 ] || { echo "spec produced no endpoints"; exit 1; }
+```
+
+See [exit codes](docs/exit-codes.md) for the full table.
+
 ## Configuration
 
 Settings can come from several places. Highest priority wins:

{elva_cli-0.3.0 → elva_cli-0.5.0}/pyproject.toml

@@ -26,6 +26,11 @@ dependencies = [
   "platformdirs>=4.2",
   "pydantic>=2.7",
   "keyring>=25",
+  # Reads info.title out of a spec so --name can default to it, and backs
+  # --dry-run's report. Parses JSON too, so one parser covers both formats.
+  "pyyaml>=6.0",
+  # ui/prompts.py has always imported this; it was simply never declared.
+  "questionary>=2.0",
 ]
 
 [project.optional-dependencies]
@@ -33,6 +38,7 @@ dev = [
   "ruff>=0.6",
   "mypy>=1.11",
   "pytest>=8.2",
+  "types-PyYAML>=6.0",
 ]
 
 [project.urls]

{elva_cli-0.3.0 → elva_cli-0.5.0}/src/elva_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.0'
-__version_tuple__ = version_tuple = (0, 3, 0)
+__version__ = version = '0.5.0'
+__version_tuple__ = version_tuple = (0, 5, 0)
 
 __commit_id__ = commit_id = None

{elva_cli-0.3.0 → elva_cli-0.5.0}/src/elva_cli/auth/__init__.py

@@ -17,9 +17,28 @@ from typing import TYPE_CHECKING
 from elva_cli.auth.models import Credentials
 
 if TYPE_CHECKING:
-    from elva_cli.auth.session import ENV_TOKEN, get_access_token, logout, save_login, save_pat
-
-__all__ = ["ENV_TOKEN", "Credentials", "get_access_token", "logout", "save_login", "save_pat"]
+    from elva_cli.auth.session import (
+        ENV_TOKEN,
+        current_identity,
+        forget_stored_credentials,
+        get_access_token,
+        logout,
+        refresh_now,
+        save_login,
+        save_pat,
+    )
+
+__all__ = [
+    "ENV_TOKEN",
+    "Credentials",
+    "current_identity",
+    "forget_stored_credentials",
+    "get_access_token",
+    "logout",
+    "refresh_now",
+    "save_login",
+    "save_pat",
+]
 
 _LAZY = frozenset(__all__) - {"Credentials"}
 

{elva_cli-0.3.0 → elva_cli-0.5.0}/src/elva_cli/auth/session.py

@@ -20,18 +20,20 @@ import contextlib
 import json
 import logging
 import os
+import time
 from datetime import UTC, datetime, timedelta
 from typing import TYPE_CHECKING, Any
 
 from elva_cli.auth.models import Credentials
 from elva_cli.auth.store import FileStore, KeyringStore, StoreUnavailableError, TokenStore
+from elva_cli.core.api.identity import client_headers
 from elva_cli.core.services.auth_result import LogoutResult as LogoutResult
 from elva_cli.core.services.auth_result import LogoutStatus as LogoutStatus
 from elva_cli.errors import ApiError, AuthError
 from elva_cli.settings import paths
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Callable, Iterator
 
 _logger = logging.getLogger(__name__)
 
@@ -41,6 +43,16 @@ _LOCK_FILE = "refresh.lock"
 _HTTP_TIMEOUT = 10
 _LOGOUT_TIMEOUT = 5
 
+# Backoff for a transiently-failing refresh (429 / 5xx / network): the initial
+# attempt plus retries sleeping these seconds between them, then give up with an
+# ApiError (transient, exit 5) - never a forced re-login.
+_REFRESH_BACKOFF_SECONDS = (1.0, 2.0, 4.0)
+
+# Distinct backend code (ELVA-200) meaning the refresh token predates the
+# current format and the user must sign in again - purely informational here,
+# since every 401/403 already routes to a re-login.
+_LEGACY_REFRESH_CODE = "REFRESH_TOKEN_LEGACY"
+
 
 class RefreshFailedError(Exception):
     """The backend positively rejected this refresh token (401/403) — the
@@ -151,26 +163,70 @@ def _refresh_lock() -> Iterator[None]:
             os.close(fd)
 
 
-def _refresh(refresh_token: str, *, base_url: str, timeout: float = _HTTP_TIMEOUT) -> Credentials:
+def _refresh(
+    refresh_token: str,
+    *,
+    base_url: str,
+    timeout: float = _HTTP_TIMEOUT,
+    sleep: Callable[[float], None] = time.sleep,
+) -> Credentials:
+    """Spend the refresh token for a fresh pair.
+
+    Sends X-Elva-Client: cli so the backend answers on the body path and, once
+    its compat flag is off, doesn't reject us as an unmarked client. A 401/403
+    is terminal (RefreshFailedError -> re-login); 429/5xx and network failures
+    are transient and retried with backoff before surfacing as ApiError."""
     import urllib.error
     import urllib.request
 
-    request = urllib.request.Request(
-        f"{base_url}/api/auth/refresh-tokens",
-        data=json.dumps({"refreshToken": refresh_token}).encode("utf-8"),
-        headers={"Content-Type": "application/json"},
-        method="POST",
-    )
+    last_transient: Exception | None = None
+    # Initial attempt (delay 0), then one retry per backoff delay.
+    for delay in (0.0, *_REFRESH_BACKOFF_SECONDS):
+        if delay:
+            sleep(delay)
+        request = urllib.request.Request(
+            f"{base_url}/api/auth/refresh-tokens",
+            data=json.dumps({"refreshToken": refresh_token}).encode("utf-8"),
+            headers={"Content-Type": "application/json", **client_headers()},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                raw = response.read()
+        except urllib.error.HTTPError as exc:
+            if exc.code in (401, 403):
+                # Terminal: the token is dead (expired, rotated away, revoked,
+                # or legacy). Note the backend code when it says so, then
+                # re-login. Not retried.
+                code = _error_code(exc)
+                detail = " (legacy token)" if code == _LEGACY_REFRESH_CODE else ""
+                raise RefreshFailedError(
+                    f"backend rejected refresh token (HTTP {exc.code}){detail}"
+                ) from exc
+            if exc.code == 429 or exc.code >= 500:
+                last_transient = exc
+                continue  # transient - back off and retry
+            raise ApiError(f"Refreshing your session failed (HTTP {exc.code}).") from exc
+        except (urllib.error.URLError, TimeoutError) as exc:
+            last_transient = exc
+            continue  # transient - back off and retry
+        else:
+            return _parse_refresh_body(raw)
+
+    raise ApiError("Could not reach the server to refresh your session.") from last_transient
+
+
+def _error_code(exc: Any) -> str | None:
+    """The backend's machine-readable error code (`data`), if it sent one."""
     try:
-        with urllib.request.urlopen(request, timeout=timeout) as response:
-            raw = response.read()
-    except urllib.error.HTTPError as exc:
-        if exc.code in (401, 403):
-            raise RefreshFailedError(f"backend rejected refresh token (HTTP {exc.code})") from exc
-        raise ApiError(f"Refreshing your session failed (HTTP {exc.code}).") from exc
-    except (urllib.error.URLError, TimeoutError) as exc:
-        raise ApiError("Could not reach the server to refresh your session.") from exc
+        payload = json.loads(exc.read())
+    except (OSError, ValueError):
+        return None
+    code = payload.get("data") if isinstance(payload, dict) else None
+    return code if isinstance(code, str) else None
+
 
+def _parse_refresh_body(raw: bytes) -> Credentials:
     unexpected = "The server returned an unexpected response while refreshing your session."
     try:
         body = json.loads(raw)
@@ -259,6 +315,58 @@ def _refresh_session(*, base_url: str) -> str:
         return refreshed.access_token
 
 
+def refresh_now(*, base_url: str, stale_access_token: str) -> str:
+    """Force a refresh after a request 401'd on a token that looked valid by
+    expiry (the server rejected it early - password change, inactivity, etc.).
+
+    Bounded to sessions. Under the cross-process lock we re-read the store: if
+    another process already rotated (the stored access token differs from the
+    one that 401'd), return that instead of spending a second refresh - the
+    double-spend is exactly what would trip the backend's reuse detection.
+    Raises AuthError if there's no usable session to refresh."""
+    with _refresh_lock():
+        creds, _ = _load_from_first_available_store()
+        if (
+            creds is None
+            or creds.kind != "session"
+            or creds.refresh_token is None
+            or creds.refresh_expires_at is None
+        ):
+            raise AuthError("Your session has expired.")
+
+        if creds.access_token != stale_access_token:
+            # A sibling process refreshed while we held the stale token.
+            return creds.access_token
+
+        if creds.refresh_expires_at <= datetime.now(UTC):
+            _clear_all_stores()
+            raise AuthError("Your session has expired.")
+
+        try:
+            refreshed = _refresh(creds.refresh_token, base_url=base_url)
+        except RefreshFailedError as exc:
+            _clear_all_stores()
+            raise AuthError("Your session has expired.") from exc
+
+        _persist_refreshed(refreshed)
+        return refreshed.access_token
+
+
+def current_identity() -> str:
+    """Where get_access_token(base_url=...) would source its token right now:
+    'env' (ELVA_TOKEN), 'pat' (a stored personal access token), 'session' (a
+    stored browser session), or 'none'."""
+    if os.environ.get(ENV_TOKEN):
+        return "env"
+    creds, _ = _load_from_first_available_store()
+    return "none" if creds is None else creds.kind
+
+
+def forget_stored_credentials() -> None:
+    """Drop whatever the TokenStores hold."""
+    _clear_all_stores()
+
+
 def save_login(payload: dict[str, Any]) -> None:
     """Persist a fresh OAuth session from the CLI login exchange.
 
@@ -284,7 +392,7 @@ def _revoke_server_side(
     request = urllib.request.Request(
         f"{base_url}/api/auth/logout",
         data=b"",
-        headers={"Authorization": f"Bearer {access_token}"},
+        headers={"Authorization": f"Bearer {access_token}", **client_headers()},
         method="POST",
     )
     try:

elva_cli-0.5.0/src/elva_cli/commands/import_.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from pathlib import Path  # noqa: TC003
+
+import typer
+
+from elva_cli.context import get_ctx
+
+app = typer.Typer(
+    name="import",
+    help="Import an API spec into a collection.",
+    no_args_is_help=True,
+)
+
+STDIN = "-"
+
+
+@app.callback()
+def main() -> None:
+    """Keeps `import` a command group for future `import github` subcommands."""
+
+
+@app.command("spec")
+def spec(
+    click_ctx: typer.Context,
+    file: Path | None = typer.Argument(
+        None,
+        metavar="[FILE]",
+        help="OpenAPI document to upload, or - to read one from stdin.",
+    ),
+    url: str | None = typer.Option(
+        None, "--url", metavar="URL", help="Have Elva fetch the spec from here instead."
+    ),
+    name: str | None = typer.Option(
+        None,
+        "--name",
+        metavar="NAME",
+        help="Name for the new collection. Defaults to the spec's info.title.",
+    ),
+    update: bool = typer.Option(
+        False,
+        "--update",
+        help="Replace the spec of the existing --collection instead of creating one.",
+    ),
+    format_: str | None = typer.Option(
+        None,
+        "--format",
+        metavar="FORMAT",
+        help="Skip detection and say what the file is: openapi or postman.",
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Report what would be imported without sending anything."
+    ),
+) -> None:
+    """Create a collection from an OpenAPI document.
+
+    Reads a local file, stdin, or a URL Elva fetches itself. Creating is the
+    default; --update replaces the spec of the collection named by --collection.
+    """
+    from elva_cli.core.services.import_spec import import_spec
+    from elva_cli.ui import prompts
+
+    ctx = get_ctx(click_ctx)
+
+    stdin: bytes | None = None
+    path: Path | None = file
+    if file is not None and str(file) == STDIN:
+        path = None
+        stdin = read_stdin()
+
+    result = import_spec(
+        base_url=ctx.settings.base_url,
+        workspace=ctx.settings.workspace,
+        path=path,
+        stdin=stdin,
+        spec_url=url,
+        name=name,
+        prompt_for_name=lambda: prompts.text(
+            None, prompt="Name for the new collection", flag="--name", ctx=ctx
+        ),
+        collection=ctx.settings.collection,
+        update=update,
+        spec_format=format_,
+        dry_run=dry_run,
+    )
+    ctx.out.result(result)
+
+
+def read_stdin() -> bytes:
+    """The spec piped in. Commands own the stdin boundary; nothing below them
+    reads a stream."""
+    import sys
+
+    return sys.stdin.buffer.read()

elva_cli-0.5.0/src/elva_cli/commands/whoami.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import typer
+
+from elva_cli.context import get_ctx
+
+app = typer.Typer(name="whoami", help="Show who you're signed in as.", add_completion=False)
+
+
+@app.command()
+def whoami(click_ctx: typer.Context) -> None:
+    """Show the email (and, for a personal access token, the scoped company)
+    the current credentials belong to."""
+    from elva_cli.core.services.whoami import whoami as whoami_service
+
+    ctx = get_ctx(click_ctx)
+    result = whoami_service(base_url=ctx.settings.base_url)
+    ctx.out.result(result)