elva-cli 0.2.0__tar.gz → 0.4.0__tar.gz

{elva_cli-0.2.0 → elva_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: elva-cli
-Version: 0.2.0
+Version: 0.4.0
 Summary: Elva - CLI for Theneo Elva
 Project-URL: Homepage, https://getelva.ai
 Project-URL: Source, https://github.com/Theneo-Inc/theneo-elva-cli
@@ -16,13 +16,17 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Documentation
 Classifier: Typing :: Typed
 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
@@ -30,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
 
@@ -73,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.2.0 → elva_cli-0.4.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.2.0 → elva_cli-0.4.0}/pyproject.toml

@@ -25,6 +25,12 @@ dependencies = [
   "typer>=0.15,<1.0",
   "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]
@@ -32,6 +38,7 @@ dev = [
   "ruff>=0.6",
   "mypy>=1.11",
   "pytest>=8.2",
+  "types-PyYAML>=6.0",
 ]
 
 [project.urls]

{elva_cli-0.2.0 → elva_cli-0.4.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.2.0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__version__ = version = '0.4.0'
+__version_tuple__ = version_tuple = (0, 4, 0)
 
 __commit_id__ = commit_id = None

elva_cli-0.4.0/src/elva_cli/auth/__init__.py

@@ -0,0 +1,49 @@
+"""Credentials and the login flow.
+
+Token storage sits behind a Protocol (keyring, with a 0600 file fallback for
+headless Linux and containers). ELVA_TOKEN overrides both in CI. A session's
+access token refreshes itself transparently on a near-expiry read; a dead
+session raises AuthError (exit code 3).
+
+The browser handoff needs a /auth/cli endpoint on the JWT side of the
+backend. The cookie-session auth used by the catalog and GitHub routes is
+deliberately out of scope: a CLI has no cookie jar.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from elva_cli.auth.models import Credentials
+
+if TYPE_CHECKING:
+    from elva_cli.auth.session import (
+        ENV_TOKEN,
+        current_identity,
+        forget_stored_credentials,
+        get_access_token,
+        logout,
+        save_login,
+        save_pat,
+    )
+
+__all__ = [
+    "ENV_TOKEN",
+    "Credentials",
+    "current_identity",
+    "forget_stored_credentials",
+    "get_access_token",
+    "logout",
+    "save_login",
+    "save_pat",
+]
+
+_LAZY = frozenset(__all__) - {"Credentials"}
+
+
+def __getattr__(name: str) -> object:
+    if name in _LAZY:
+        from elva_cli.auth import session
+
+        return getattr(session, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

elva_cli-0.4.0/src/elva_cli/auth/models.py

@@ -0,0 +1,100 @@
+"""The Credentials shape: what gets stored, and how it maps to the wire."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+TokenKind = Literal["session", "pat"]
+
+
+def _parse_expiry(value: str) -> datetime:
+    """Parse an ISO-8601 timestamp, forcing it timezone-aware.
+
+    The backend sends UTC with a `Z`, but a hand-edited credentials.json can
+    drop the offset. A naive datetime would later crash get_access_token's
+    `expires - datetime.now(UTC)` arithmetic, so assume UTC when none is
+    given."""
+    parsed = datetime.fromisoformat(value)
+    return parsed if parsed.tzinfo is not None else parsed.replace(tzinfo=UTC)
+
+
+@dataclass(frozen=True)
+class Credentials:
+    """One stored credential: either an OAuth session (JWT pair, refreshable)
+    or a Personal Access Token (opaque, long-lived, no refresh side)."""
+
+    kind: TokenKind
+    access_token: str
+    access_expires_at: datetime | None
+    refresh_token: str | None
+    refresh_expires_at: datetime | None
+
+    @classmethod
+    def from_auth_tokens(cls, tokens: dict[str, Any]) -> Credentials:
+        """Build a session credential from the backend's AuthTokens shape:
+        {"access": {"token", "expires"}, "refresh": {"token", "expires"}}.
+
+        POST /api/auth/refresh-tokens returns this shape at the top level.
+        The CLI login exchange (POST /api/auth/cli/token) nests it under a
+        "tokens" key alongside "user" — callers there go through
+        `session.save_login`, which unwraps it first."""
+        access = tokens["access"]
+        refresh = tokens["refresh"]
+        return cls(
+            kind="session",
+            access_token=access["token"],
+            access_expires_at=_parse_expiry(access["expires"]),
+            refresh_token=refresh["token"],
+            refresh_expires_at=_parse_expiry(refresh["expires"]),
+        )
+
+    @classmethod
+    def from_pat(cls, token: str) -> Credentials:
+        return cls(
+            kind="pat",
+            access_token=token,
+            access_expires_at=None,
+            refresh_token=None,
+            refresh_expires_at=None,
+        )
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "kind": self.kind,
+            "access_token": self.access_token,
+            "access_expires_at": (
+                self.access_expires_at.isoformat() if self.access_expires_at else None
+            ),
+            "refresh_token": self.refresh_token,
+            "refresh_expires_at": (
+                self.refresh_expires_at.isoformat() if self.refresh_expires_at else None
+            ),
+        }
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> Credentials:
+        kind = data["kind"]
+        if kind not in ("session", "pat"):
+            raise ValueError(f"unknown credential kind: {kind!r}")
+        creds = cls(
+            kind=kind,
+            access_token=data["access_token"],
+            access_expires_at=(
+                _parse_expiry(data["access_expires_at"]) if data.get("access_expires_at") else None
+            ),
+            refresh_token=data.get("refresh_token"),
+            refresh_expires_at=(
+                _parse_expiry(data["refresh_expires_at"])
+                if data.get("refresh_expires_at")
+                else None
+            ),
+        )
+        if creds.kind == "session" and (
+            creds.access_expires_at is None
+            or creds.refresh_token is None
+            or creds.refresh_expires_at is None
+        ):
+            raise ValueError("incomplete session credential")
+        return creds