elva-cli 0.0.3__tar.gz → 0.1.0__tar.gz

{elva_cli-0.0.3 → elva_cli-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: elva-cli
-Version: 0.0.3
+Version: 0.1.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,6 +16,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Documentation
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: pydantic>=2.7
 Requires-Dist: typer<1.0,>=0.15
 Provides-Extra: dev
 Requires-Dist: mypy>=1.11; extra == 'dev'
@@ -71,17 +73,76 @@ powershell -c "irm https://astral.sh/uv/install.ps1|iex" # Windows
 uv tool upgrade elva-cli      # or: pipx upgrade elva-cli
 ```
 
-### Why not `pip install`?
+## Configuration
 
-On Ubuntu, Debian, Fedora and Homebrew macOS, `pip install elva-cli` fails with
-`externally-managed-environment`. Those systems reserve their Python for the OS package
-manager ([PEP 668](https://peps.python.org/pep-0668/)), and `--user` is blocked too.
+Settings can come from several places. Highest priority wins:
 
-`uv tool` and `pipx` are the supported way to install a Python command-line application:
-they give it a private environment and put just the `elva` command on your `PATH`, so it
-can never conflict with your projects' dependencies.
+1. Command flags: `--workspace`, `--collection`, `--profile`
+2. Environment: `ELVA_WORKSPACE`, `ELVA_COLLECTION`, `ELVA_PROFILE`, `ELVA_TIMEOUT`
+3. `elva.json` in your project
+4. The selected profile in your user config
+5. Your user config
+6. Built in defaults
 
-Inside an already-activated virtualenv, `pip install elva-cli` works fine.
+### Project file
+
+Commit an `elva.json` next to your spec and stop repeating flags:
+
+```json
+{
+  "workspace": "payments-team",
+  "collection": "payments-api"
+}
+```
+
+It is found by walking up from the current directory to the repo root, so it works
+from any subfolder. Keep secrets out of it, it is meant to be committed.
+
+### User config and profiles
+
+| Platform | Location |
+|---|---|
+| Linux | `~/.config/elva/config.json` |
+| macOS | `~/Library/Application Support/elva/config.json` |
+| Windows | `%LOCALAPPDATA%\elva\config.json` |
+
+A profile is a named set of defaults. Useful when you work across more than one
+workspace and do not want a project file for each:
+
+```json
+{
+  "profiles": {
+    "work": { "workspace": "work-team", "collection": "work-api" },
+    "side": { "workspace": "side-team" }
+  }
+}
+```
+
+```bash
+elva --profile work collection list
+```
+
+A project file beats a profile, so a repo with its own `elva.json` always wins over
+whichever profile you have selected.
+
+### Seeing what was resolved
+
+When something targets the wrong place, these two answer it:
+
+```bash
+elva config path    # which files were read, and whether they exist
+elva config list    # each value, and which layer set it
+```
+
+```
+$ elva --profile work config list
+collection    work-api                        profile:work
+profile       work                            flag
+timeout       30.0                            default
+workspace     work-team                       profile:work
+
+profiles      side, work
+```
 
 ## Requirements
 
@@ -92,4 +153,5 @@ Inside an already-activated virtualenv, `pip install elva-cli` works fine.
 
 - [Elva](https://getelva.ai)
 - [Issues](https://github.com/Theneo-Inc/theneo-elva-cli/issues)
+- [Exit codes](docs/exit-codes.md), for scripting and CI
 - [Contributing](CONTRIBUTING.md)

elva_cli-0.1.0/README.md

@@ -0,0 +1,130 @@
+# Elva CLI
+
+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`.
+
+## Install
+
+Requires Python 3.11 or newer.
+
+```bash
+uv tool install elva-cli
+```
+
+Or with [pipx](https://pipx.pypa.io/), if you already use it:
+
+```bash
+pipx install elva-cli
+```
+
+Either way, `elva` is then available from any directory:
+
+```bash
+elva --version
+elva --help
+```
+
+To try it without installing anything:
+
+```bash
+uvx --from elva-cli elva --version
+```
+
+Don't have `uv`? It is a single command and no prerequisites:
+
+```bash
+curl -fsSL https://astral.sh/uv/install.sh | sh          # macOS, Linux
+powershell -c "irm https://astral.sh/uv/install.ps1|iex" # Windows
+```
+
+### Upgrade
+
+```bash
+uv tool upgrade elva-cli      # or: pipx upgrade elva-cli
+```
+
+## Configuration
+
+Settings can come from several places. Highest priority wins:
+
+1. Command flags: `--workspace`, `--collection`, `--profile`
+2. Environment: `ELVA_WORKSPACE`, `ELVA_COLLECTION`, `ELVA_PROFILE`, `ELVA_TIMEOUT`
+3. `elva.json` in your project
+4. The selected profile in your user config
+5. Your user config
+6. Built in defaults
+
+### Project file
+
+Commit an `elva.json` next to your spec and stop repeating flags:
+
+```json
+{
+  "workspace": "payments-team",
+  "collection": "payments-api"
+}
+```
+
+It is found by walking up from the current directory to the repo root, so it works
+from any subfolder. Keep secrets out of it, it is meant to be committed.
+
+### User config and profiles
+
+| Platform | Location |
+|---|---|
+| Linux | `~/.config/elva/config.json` |
+| macOS | `~/Library/Application Support/elva/config.json` |
+| Windows | `%LOCALAPPDATA%\elva\config.json` |
+
+A profile is a named set of defaults. Useful when you work across more than one
+workspace and do not want a project file for each:
+
+```json
+{
+  "profiles": {
+    "work": { "workspace": "work-team", "collection": "work-api" },
+    "side": { "workspace": "side-team" }
+  }
+}
+```
+
+```bash
+elva --profile work collection list
+```
+
+A project file beats a profile, so a repo with its own `elva.json` always wins over
+whichever profile you have selected.
+
+### Seeing what was resolved
+
+When something targets the wrong place, these two answer it:
+
+```bash
+elva config path    # which files were read, and whether they exist
+elva config list    # each value, and which layer set it
+```
+
+```
+$ elva --profile work config list
+collection    work-api                        profile:work
+profile       work                            flag
+timeout       30.0                            default
+workspace     work-team                       profile:work
+
+profiles      side, work
+```
+
+## Requirements
+
+- Python 3.11 or newer (bundled automatically if you install via `uv tool`)
+- An [Elva](https://getelva.ai) account
+
+## Links
+
+- [Elva](https://getelva.ai)
+- [Issues](https://github.com/Theneo-Inc/theneo-elva-cli/issues)
+- [Exit codes](docs/exit-codes.md), for scripting and CI
+- [Contributing](CONTRIBUTING.md)

{elva_cli-0.0.3 → elva_cli-0.1.0}/pyproject.toml

@@ -23,6 +23,8 @@ classifiers = [
 
 dependencies = [
   "typer>=0.15,<1.0",
+  "platformdirs>=4.2",
+  "pydantic>=2.7",
 ]
 
 [project.optional-dependencies]
@@ -91,7 +93,7 @@ ban-relative-imports = "all"
 [tool.mypy]
 python_version = "3.11"
 strict = true
-files = ["src"]
+files = ["src", "tests"]
 warn_unreachable = true
 enable_error_code = ["ignore-without-code", "redundant-expr"]
 

{elva_cli-0.0.3 → elva_cli-0.1.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.0.3'
-__version_tuple__ = version_tuple = (0, 0, 3)
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
 
 __commit_id__ = commit_id = None

elva_cli-0.1.0/src/elva_cli/commands/config.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import typer
+
+from elva_cli.context import get_ctx
+
+app = typer.Typer(name="config", help="Inspect resolved configuration.", no_args_is_help=True)
+
+
+def _row(label: str, value: str, note: str = "") -> str:
+    return f"{label:<16}{value}{'  ' + note if note else ''}"
+
+
+@app.command("path")
+def path(click_ctx: typer.Context) -> None:
+    """Show every file the CLI reads configuration from."""
+    from elva_cli.settings import paths
+
+    ctx = get_ctx(click_ctx)
+    typer.echo(_row("config dir", str(paths.config_dir())))
+    typer.echo(_row("cache dir", str(paths.cache_dir())))
+    for file in ctx.resolution.files:
+        typer.echo(
+            _row(f"{file.kind} config", str(file.path), "(found)" if file.exists else "(absent)")
+        )
+
+
+@app.command("list")
+def list_(click_ctx: typer.Context) -> None:
+    """Show each setting, its value, and which layer set it."""
+    ctx = get_ctx(click_ctx)
+    resolution = ctx.resolution
+    settings = resolution.settings
+    for field in sorted(type(settings).model_fields):
+        value = getattr(settings, field)
+        shown = "-" if value is None else str(value)
+        typer.echo(f"{field:<14}{shown:<32}{resolution.origins[field]}")
+    if resolution.profiles:
+        typer.echo("")
+        typer.echo(f"profiles      {', '.join(resolution.profiles)}")

elva_cli-0.1.0/src/elva_cli/context.py

@@ -0,0 +1,67 @@
+"""The Ctx object, built once in the root callback and passed to every command.
+
+Commands read settings from here instead of touching the environment or the
+filesystem themselves, so configuration is resolved in exactly one place.
+
+Resolution is a cached_property because it pulls in pydantic. `elva --version`
+must not pay for that.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import cached_property
+from typing import TYPE_CHECKING
+
+from elva_cli.errors import ElvaError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+    import typer
+
+    from elva_cli.settings.loader import Resolution
+    from elva_cli.settings.models import Settings
+
+
+@dataclass(frozen=True)
+class GlobalOptions:
+    profile: str | None = None
+    base_url: str | None = None
+    workspace: str | None = None
+    collection: str | None = None
+
+
+class Ctx:
+    def __init__(self, options: GlobalOptions, *, cwd: Path, env: Mapping[str, str]) -> None:
+        self.options = options
+        self.cwd = cwd
+        self.env = env
+
+    @cached_property
+    def resolution(self) -> Resolution:
+        from elva_cli.settings.loader import resolve
+
+        return resolve(
+            overrides={
+                "profile": self.options.profile,
+                "base_url": self.options.base_url,
+                "workspace": self.options.workspace,
+                "collection": self.options.collection,
+            },
+            env=self.env,
+            cwd=self.cwd,
+        )
+
+    @property
+    def settings(self) -> Settings:
+        return self.resolution.settings
+
+
+def get_ctx(click_ctx: typer.Context) -> Ctx:
+    ctx = click_ctx.obj
+    if not isinstance(ctx, Ctx):
+        msg = "no Ctx on the context; the root callback did not run"
+        raise ElvaError(msg)
+    return ctx

elva_cli-0.1.0/src/elva_cli/errors.py

@@ -0,0 +1,90 @@
+"""Error taxonomy and the exit-code contract.
+
+Exit codes are a public API that pipelines branch on. Never renumber a shipped
+value, and never collapse VALIDATION into UNEXPECTED, callers rely on the
+difference between "your spec is wrong" and "the tool broke".
+
+Every ElvaError carries a stable machine code, a human message, and where one
+exists, the next action to take. Anything that escapes as a bare Exception is a
+"""
+
+from __future__ import annotations
+
+import enum
+
+
+class ExitCode(enum.IntEnum):
+    """Process exit statuses. Documented in docs/exit-codes.md."""
+
+    OK = 0
+    UNEXPECTED = 1
+    USAGE = 2
+    AUTH = 3
+    VALIDATION = 4
+    API = 5
+    INTERRUPTED = 130
+
+
+class ElvaError(Exception):
+    """Base class for every failure the user is meant to see."""
+
+    code: str = "ELVA_ERROR"
+    exit_code: ExitCode = ExitCode.UNEXPECTED
+    default_hint: str | None = None
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        hint: str | None = None,
+        code: str | None = None,
+        exit_code: ExitCode | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.hint = self.default_hint if hint is None else hint
+        if code is not None:
+            self.code = code
+        if exit_code is not None:
+            self.exit_code = exit_code
+
+    def __str__(self) -> str:
+        return self.message
+
+
+class UsageError(ElvaError):
+    """The command was invoked wrongly, or needs an answer it cannot ask for."""
+
+    code = "ELVA_USAGE"
+    exit_code = ExitCode.USAGE
+    default_hint = "Run 'elva --help' to see the available commands and options."
+
+
+class ConfigError(ElvaError):
+    """Configuration is missing or malformed."""
+
+    code = "ELVA_CONFIG"
+    exit_code = ExitCode.USAGE
+
+
+class AuthError(ElvaError):
+    """Not authenticated, or the stored credentials no longer work."""
+
+    code = "ELVA_AUTH"
+    exit_code = ExitCode.AUTH
+    default_hint = "Run 'elva auth login' to sign in."
+
+
+class ValidationError(ElvaError):
+    """The input spec is invalid. The CLI itself worked correctly."""
+
+    code = "ELVA_VALIDATION"
+    exit_code = ExitCode.VALIDATION
+
+
+class ApiError(ElvaError):
+    """The Elva API could not be reached, or returned a server error."""
+
+    code = "ELVA_API"
+    exit_code = ExitCode.API
+    default_hint = "Check your connection and try again."

elva_cli-0.1.0/src/elva_cli/main.py

@@ -0,0 +1,162 @@
+"""Typer root and the single error boundary."""
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from pathlib import Path
+from typing import Protocol, TypeGuard
+
+import typer
+
+from elva_cli.context import Ctx, GlobalOptions
+from elva_cli.errors import ElvaError, ExitCode
+from elva_cli.registry import LazyGroup
+
+app = typer.Typer(
+    cls=LazyGroup,
+    name="elva",
+    help="Elva - CLI for Theneo Elva.",
+    no_args_is_help=True,
+    pretty_exceptions_enable=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _version_callback(value: bool) -> None:
+    if not value:
+        return
+    from elva_cli import __version__
+
+    machine = f"{platform.system().lower()}-{platform.machine()}"
+    typer.echo(f"elva {__version__} (python {platform.python_version()}, {machine})")
+    raise typer.Exit(ExitCode.OK)
+
+
+@app.callback()
+def root(
+    click_ctx: typer.Context,
+    profile: str | None = typer.Option(
+        None, "--profile", envvar="ELVA_PROFILE", help="Named set of defaults from your config."
+    ),
+    # Internal escape hatch for Theneo development and CI against staging. Users
+    # only ever have prod, so it stays out of --help and out of the README.
+    base_url: str | None = typer.Option(None, "--base-url", envvar="ELVA_BASE_URL", hidden=True),
+    workspace: str | None = typer.Option(
+        None, "--workspace", "-w", envvar="ELVA_WORKSPACE", help="Workspace to act on."
+    ),
+    collection: str | None = typer.Option(
+        None, "--collection", "-c", envvar="ELVA_COLLECTION", help="Collection to act on."
+    ),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the current build version.",
+    ),
+) -> None:
+    click_ctx.obj = Ctx(
+        GlobalOptions(
+            profile=profile,
+            base_url=base_url,
+            workspace=workspace,
+            collection=collection,
+        ),
+        cwd=Path.cwd(),
+        env=os.environ,
+    )
+
+
+def report(error: ElvaError) -> None:
+    """Render a user-facing error to stderr as code, message, then next action."""
+    typer.secho(f"{error.code}: {error.message}", err=True, fg=typer.colors.RED)
+    if error.hint:
+        typer.secho(f"  -> {error.hint}", err=True, dim=True)
+
+
+def write_crash(exc: BaseException) -> Path | None:
+    """Persist a traceback for an unexpected failure and return its path.
+
+    Deliberately records no argv: a crash report is written to disk and kept, and
+    a mistyped secret on a command line must not outlive the process.
+    """
+    import time
+    import traceback
+
+    from elva_cli import __version__
+    from elva_cli.settings.paths import crash_dir
+
+    try:
+        directory = crash_dir()
+        directory.mkdir(parents=True, exist_ok=True)
+        target = directory / f"crash-{int(time.time())}-{os.getpid()}.log"
+        target.write_text(
+            f"elva {__version__}\n"
+            f"python {platform.python_version()} on {platform.platform()}\n\n"
+            + "".join(traceback.format_exception(exc)),
+            encoding="utf-8",
+        )
+    except OSError:
+        return None
+    return target
+
+
+class _FrameworkError(Protocol):
+    """The shape every vendored Click exception exposes."""
+
+    exit_code: int
+
+    def show(self) -> None: ...
+
+
+def _is_framework_error(exc: BaseException) -> TypeGuard[_FrameworkError]:
+    """Recognise a Typer/Click argument-parsing failure."""
+    return (
+        type(exc).__module__.startswith("typer")
+        and callable(getattr(exc, "show", None))
+        and isinstance(getattr(exc, "exit_code", None), int)
+    )
+
+
+def _run() -> int:
+    try:
+        app(standalone_mode=False)
+    except typer.Exit as exc:
+        return int(exc.exit_code)
+    except typer.Abort:
+        return int(ExitCode.INTERRUPTED)
+    except ElvaError as exc:
+        report(exc)
+        return int(exc.exit_code)
+    except KeyboardInterrupt:
+        typer.secho("interrupted", err=True, dim=True)
+        return int(ExitCode.INTERRUPTED)
+    except Exception as exc:
+        if _is_framework_error(exc):
+            exc.show()
+            return int(exc.exit_code)
+        path = write_crash(exc)
+        report(
+            ElvaError(
+                f"unexpected error: {type(exc).__name__}: {exc}",
+                code="ELVA_CRASH",
+                hint=(
+                    f"Details written to {path}. Please include that file when reporting this."
+                    if path
+                    else "Please report this, including the command you ran."
+                ),
+            )
+        )
+        return int(ExitCode.UNEXPECTED)
+    return int(ExitCode.OK)
+
+
+def main() -> None:
+    sys.exit(_run())
+
+
+if __name__ == "__main__":
+    main()

elva_cli-0.1.0/src/elva_cli/registry.py

@@ -0,0 +1,46 @@
+"""Lazy command dispatch.
+
+Only the command a user actually typed gets imported. That keeps `elva --version`
+away from pydantic, httpx and anything else a command pulls in.
+
+Adding a command means adding a line here.
+"""
+
+from __future__ import annotations
+
+import importlib
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, ClassVar
+
+from typer.core import TyperGroup
+
+if TYPE_CHECKING:
+    from typer._click.core import Command, Context
+
+
+@dataclass(frozen=True)
+class Lazy:
+    module: str
+    help: str
+
+
+class LazyGroup(TyperGroup):
+    commands_: ClassVar[dict[str, Lazy]] = {
+        "config": Lazy("elva_cli.commands.config", "Inspect resolved configuration."),
+    }
+
+    def list_commands(self, ctx: Context) -> list[str]:
+        return sorted({*super().list_commands(ctx), *self.commands_})
+
+    def get_command(self, ctx: Context, cmd_name: str) -> Command | None:
+        lazy = self.commands_.get(cmd_name)
+        if lazy is None:
+            return super().get_command(ctx, cmd_name)
+
+        import typer.main
+
+        module = importlib.import_module(lazy.module)
+        command = typer.main.get_command(module.app)
+        command.name = cmd_name
+        command.short_help = lazy.help
+        return command

elva_cli-0.1.0/src/elva_cli/settings/__init__.py

@@ -0,0 +1,6 @@
+"""Configuration schema and precedence resolution.
+
+Order, highest first: command flags, ELVA_* environment, project elva.json,
+the selected profile in the user config, user config, defaults. Resolved once in
+the root callback and frozen onto the Ctx.
+"""