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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: elva-cli
-Version: 0.3.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
@@ -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.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.3.0 → elva_cli-0.4.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.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.3.0'
-__version_tuple__ = version_tuple = (0, 3, 0)
+__version__ = version = '0.4.0'
+__version_tuple__ = version_tuple = (0, 4, 0)
 
 __commit_id__ = commit_id = None

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

@@ -17,9 +17,26 @@ 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,
+        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"}
 

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

@@ -259,6 +259,21 @@ def _refresh_session(*, base_url: str) -> str:
         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.
 

elva_cli-0.4.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.4.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)

elva_cli-0.4.0/src/elva_cli/core/api/http.py

@@ -0,0 +1,213 @@
+"""The HTTP calls the CLI makes, and the one place a status becomes an error.
+
+Not the generated client this package's docstring describes -- that arrives
+with its own ticket. This is the minimum that stops every new command
+hand-rolling urllib and its own status mapping.
+
+Callers get HttpError for a rejected request and map the codes they have
+something specific to say about; `default_error` handles the rest.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from elva_cli.errors import ApiError, AuthError, ElvaError
+
+if TYPE_CHECKING:
+    import urllib.error
+    from collections.abc import Mapping
+
+DEFAULT_TIMEOUT = 30.0
+UNEXPECTED_RESPONSE = "The server returned an unexpected response."
+REDIRECTED = "The server redirected the request. Check the configured base URL."
+_REDIRECT_CODES = frozenset({301, 302, 303, 307, 308})
+
+
+class HttpError(Exception):
+    """A non-2xx response, with whatever explanation the server sent."""
+
+    def __init__(self, status: int, detail: str | None) -> None:
+        super().__init__(f"HTTP {status}")
+        self.status = status
+        self.detail = detail
+
+
+def default_error(error: HttpError, *, action: str) -> ElvaError:
+    """The mapping every caller shares. `action` completes "... failed"."""
+    if error.status in (401, 403):
+        return AuthError("Your credentials are no longer valid.")
+    return ApiError(f"{action} failed (HTTP {error.status}).")
+
+
+def get_json(url: str, *, token: str, timeout: float = DEFAULT_TIMEOUT) -> Any:
+    return _send(url, token=token, method="GET", timeout=timeout)
+
+
+def send_json(
+    url: str,
+    *,
+    token: str,
+    method: str,
+    payload: Mapping[str, Any],
+    timeout: float = DEFAULT_TIMEOUT,
+) -> Any:
+    return _send(
+        url,
+        token=token,
+        method=method,
+        body=json.dumps(payload).encode("utf-8"),
+        content_type="application/json",
+        timeout=timeout,
+    )
+
+
+def send_form(
+    url: str,
+    *,
+    token: str,
+    method: str,
+    fields: Mapping[str, str],
+    field: str | None = None,
+    filename: str | None = None,
+    data: bytes | None = None,
+    content_type: str | None = None,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> Any:
+    """A multipart/form-data request: text fields, plus at most one file."""
+    body, boundary_type = _multipart(
+        fields=fields,
+        field=field,
+        filename=filename,
+        data=data,
+        content_type=content_type,
+    )
+    return _send(
+        url, token=token, method=method, body=body, content_type=boundary_type, timeout=timeout
+    )
+
+
+def _multipart(
+    *,
+    fields: Mapping[str, str],
+    field: str | None,
+    filename: str | None,
+    data: bytes | None,
+    content_type: str | None,
+) -> tuple[bytes, str]:
+    """Body and Content-Type header for a multipart form.
+
+    Hand-rolled to keep the dependency list flat. If this ever needs more than
+    one file part, or streaming, reach for httpx instead of growing it.
+    """
+    import secrets
+
+    boundary = f"----elva{secrets.token_hex(16)}"
+    parts: list[bytes] = []
+
+    for name, value in fields.items():
+        parts += [
+            f"--{boundary}".encode(),
+            f'Content-Disposition: form-data; name="{_header_safe(name)}"'.encode(),
+            b"",
+            value.encode("utf-8"),
+        ]
+
+    if field is not None and data is not None:
+        parts += [
+            f"--{boundary}".encode(),
+            (
+                f'Content-Disposition: form-data; name="{_header_safe(field)}"; '
+                f'filename="{_header_safe(filename or "spec")}"'
+            ).encode(),
+            f"Content-Type: {content_type or 'application/octet-stream'}".encode(),
+            b"",
+            data,
+        ]
+
+    parts += [f"--{boundary}--".encode(), b""]
+    return b"\r\n".join(parts), f"multipart/form-data; boundary={boundary}"
+
+
+def _header_safe(value: str) -> str:
+    """A quote or newline would otherwise break out of the part header."""
+    return value.translate({ord(c): "_" for c in '"\\\r\n'})
+
+
+_OPENER: Any = None
+
+
+def _opener() -> Any:
+    """An opener that refuses redirects instead of following them.
+
+    urllib's default handler would replay the request at the new location with
+    our `Authorization: Bearer` still attached -- to another host, if that is
+    where it points -- and on 301/302/303 it rewrites POST/PATCH to GET, which
+    drops the upload body and surfaces only as an unexpected response. Neither
+    is ours to do on the caller's behalf, so a redirect becomes an error.
+    """
+    global _OPENER
+    if _OPENER is None:
+        import urllib.request
+
+        class _NoRedirect(urllib.request.HTTPRedirectHandler):
+            def redirect_request(self, *args: Any, **kwargs: Any) -> None:
+                return None
+
+        _OPENER = urllib.request.build_opener(_NoRedirect)
+    return _OPENER
+
+
+def _send(
+    url: str,
+    *,
+    token: str,
+    method: str,
+    body: bytes | None = None,
+    content_type: str | None = None,
+    timeout: float,
+) -> Any:
+    import urllib.error
+    import urllib.request
+
+    headers = {"Authorization": f"Bearer {token}"}
+    if content_type is not None:
+        headers["Content-Type"] = content_type
+
+    request = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with _opener().open(request, timeout=timeout) as response:
+            raw = response.read()
+    except urllib.error.HTTPError as exc:
+        if exc.code in _REDIRECT_CODES:
+            raise ApiError(REDIRECTED) from exc
+        raise HttpError(exc.code, _detail(exc)) from exc
+    except OSError as exc:
+        # URLError and TimeoutError are both OSError, but a connection reset
+        # part-way through reading the response is neither -- it arrives raw
+        # from the socket, and catching only those two lets it out as an
+        # unhandled traceback under exit 1 instead of a reachability failure.
+        raise ApiError("Could not reach the server.") from exc
+
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ApiError(UNEXPECTED_RESPONSE) from exc
+
+
+def _detail(exc: urllib.error.HTTPError) -> str | None:
+    """The server's own explanation, when it sends one worth showing."""
+    try:
+        payload = json.loads(exc.read())
+    except (OSError, ValueError):
+        return None
+    if not isinstance(payload, dict):
+        return None
+    for key in ("message", "error", "detail"):
+        value = payload.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None