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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: elva-cli
-Version: 0.0.4
+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
@@ -17,6 +17,7 @@ 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'
@@ -72,6 +73,77 @@ powershell -c "irm https://astral.sh/uv/install.ps1|iex" # Windows
 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`)
@@ -81,4 +153,5 @@ uv tool upgrade elva-cli      # or: pipx upgrade elva-cli
 
 - [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.4 → elva_cli-0.1.0}/pyproject.toml

@@ -24,6 +24,7 @@ classifiers = [
 dependencies = [
   "typer>=0.15,<1.0",
   "platformdirs>=4.2",
+  "pydantic>=2.7",
 ]
 
 [project.optional-dependencies]

{elva_cli-0.0.4 → 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.4'
-__version_tuple__ = version_tuple = (0, 0, 4)
+__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.0.4 → elva_cli-0.1.0}/src/elva_cli/main.py

@@ -5,16 +5,17 @@ from __future__ import annotations
 import os
 import platform
 import sys
-from typing import TYPE_CHECKING, Protocol, TypeGuard
+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
-
-if TYPE_CHECKING:
-    from pathlib import Path
+from elva_cli.registry import LazyGroup
 
 app = typer.Typer(
+    cls=LazyGroup,
     name="elva",
     help="Elva - CLI for Theneo Elva.",
     no_args_is_help=True,
@@ -35,6 +36,19 @@ def _version_callback(value: bool) -> None:
 
 @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",
@@ -44,7 +58,16 @@ def root(
         help="Show the current build version.",
     ),
 ) -> None:
-    pass
+    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:

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.
+"""

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

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from pydantic import ValidationError as PydanticValidationError
+
+from elva_cli.errors import ConfigError
+from elva_cli.settings import paths
+from elva_cli.settings.models import Settings
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+ENV_PREFIX = "ELVA_"
+
+_ENV_KEYS = {
+    "ELVA_BASE_URL": "base_url",
+    "ELVA_PROFILE": "profile",
+    "ELVA_WORKSPACE": "workspace",
+    "ELVA_COLLECTION": "collection",
+    "ELVA_TIMEOUT": "timeout",
+}
+
+DEFAULT_PROFILE = "default"
+
+
+@dataclass(frozen=True)
+class ConfigFile:
+    kind: str
+    path: Path
+    exists: bool
+
+
+@dataclass(frozen=True)
+class Resolution:
+    settings: Settings
+    origins: dict[str, str]
+    files: tuple[ConfigFile, ...]
+    profiles: tuple[str, ...]
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ConfigError(f"cannot read {path}: {exc}") from exc
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"{path} is not valid JSON: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path} must contain a JSON object")
+    return data
+
+
+def _coerce(field: str, raw: str, source: str) -> Any:
+    if field == "timeout":
+        try:
+            return float(raw)
+        except ValueError:
+            raise ConfigError(f"{source} must be a number, got {raw!r}") from None
+    return raw
+
+
+def _split_profiles(data: dict[str, Any], path: Path) -> tuple[dict[str, Any], dict[str, Any]]:
+    profiles = data.pop("profiles", {})
+    if not isinstance(profiles, dict):
+        raise ConfigError(f'"profiles" in {path} must be an object')
+    return data, profiles
+
+
+def resolve(
+    *,
+    overrides: Mapping[str, Any] | None = None,
+    env: Mapping[str, str],
+    cwd: Path,
+) -> Resolution:
+    """Merge every configuration source into one frozen Settings.
+
+    Highest precedence first, and the first layer carrying a field wins.
+    """
+    flags = {k: v for k, v in (overrides or {}).items() if v is not None}
+
+    env_layer: dict[str, Any] = {}
+    for key, field in _ENV_KEYS.items():
+        raw = env.get(key)
+        if raw:
+            env_layer[field] = _coerce(field, raw, key)
+
+    user_path = paths.user_config_file()
+    user_layer, profiles = (
+        _split_profiles(_read_json(user_path), user_path) if user_path.is_file() else ({}, {})
+    )
+
+    project_path = paths.find_project_file(cwd)
+    project_layer = _read_json(project_path) if project_path else {}
+    project_layer.pop("profiles", None)
+
+    selected = (
+        flags.get("profile")
+        or env_layer.get("profile")
+        or project_layer.get("profile")
+        or user_layer.get("profile")
+        or DEFAULT_PROFILE
+    )
+    overlay = profiles.get(selected, {})
+    if not isinstance(overlay, dict):
+        raise ConfigError(f'profile "{selected}" must be an object')
+    if selected != DEFAULT_PROFILE and selected not in profiles:
+        raise ConfigError(
+            f'unknown profile "{selected}"',
+            hint=f"Profiles defined in {user_path}: {', '.join(sorted(profiles)) or 'none'}",
+        )
+
+    layers: list[tuple[str, Mapping[str, Any]]] = [
+        ("flag", flags),
+        ("env", env_layer),
+        ("project", project_layer),
+        (f"profile:{selected}", overlay),
+        ("user", user_layer),
+    ]
+
+    merged: dict[str, Any] = {}
+    origins: dict[str, str] = {}
+    for name, layer in layers:
+        for field, value in layer.items():
+            if field not in merged:
+                merged[field] = value
+                origins[field] = name
+
+    try:
+        settings = Settings(**merged)
+    except PydanticValidationError as exc:
+        first = exc.errors()[0]
+        field = str(first["loc"][0]) if first["loc"] else "config"
+        where = origins.get(field, "default")
+        raise ConfigError(f"invalid setting {field!r} from {where}: {first['msg']}") from exc
+
+    for field in Settings.model_fields:
+        origins.setdefault(field, "default")
+
+    files = (
+        ConfigFile("project", project_path or cwd / paths.PROJECT_FILE, project_path is not None),
+        ConfigFile("user", user_path, user_path.is_file()),
+    )
+    return Resolution(
+        settings=settings,
+        origins=origins,
+        files=files,
+        profiles=tuple(sorted(profiles)),
+    )

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

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+DEFAULT_BASE_URL = "https://api.getelva.ai"
+
+
+class Settings(BaseModel):
+    """Every setting the CLI has.
+
+    Adding a field here is the only way to add a setting: the loader derives its
+    precedence handling and `elva config list` derives its output. Unknown keys in
+    a config file are an error rather than a silent typo.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    base_url: str = DEFAULT_BASE_URL
+    profile: str = "default"
+    workspace: str | None = None
+    collection: str | None = None
+    timeout: float = 30.0
+
+    @field_validator("base_url")
+    @classmethod
+    def _must_be_http(cls, value: str) -> str:
+        if not value.startswith(("http://", "https://")):
+            msg = "must start with http:// or https://"
+            raise ValueError(msg)
+        return value.rstrip("/")
+
+    @field_validator("timeout")
+    @classmethod
+    def _must_be_positive(cls, value: float) -> float:
+        if value <= 0:
+            msg = "must be greater than 0"
+            raise ValueError(msg)
+        return value

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

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import platformdirs
+
+APP_NAME = "elva"
+PROJECT_FILE = "elva.json"
+USER_CONFIG_FILE = "config.json"
+
+
+def config_dir() -> Path:
+    return Path(platformdirs.user_config_dir(APP_NAME, appauthor=False))
+
+
+def cache_dir() -> Path:
+    return Path(platformdirs.user_cache_dir(APP_NAME, appauthor=False))
+
+
+def crash_dir() -> Path:
+    return cache_dir() / "crashes"
+
+
+def user_config_file() -> Path:
+    return config_dir() / USER_CONFIG_FILE
+
+
+def find_project_file(start: Path) -> Path | None:
+    """Walk up from start looking for elva.json, stopping at the repo root.
+
+    The directory holding .git is checked and then the search ends, so a stray
+    elva.json above someone's checkout is never picked up.
+    """
+    for directory in [start, *start.parents]:
+        candidate = directory / PROJECT_FILE
+        if candidate.is_file():
+            return candidate
+        if (directory / ".git").exists():
+            break
+    return None

elva_cli-0.1.0/tests/cli/test_config_command.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def run(
+    *args: str, cwd: Path, env: dict[str, str] | None = None
+) -> subprocess.CompletedProcess[str]:
+    import os
+
+    full = {**os.environ, "XDG_CONFIG_HOME": str(cwd / "xdgconfig")}
+    full.update(env or {})
+    return subprocess.run(
+        [sys.executable, "-m", "elva_cli", *args],
+        capture_output=True,
+        text=True,
+        check=False,
+        cwd=cwd,
+        env=full,
+    )
+
+
+def project(tmp_path: Path, data: dict[str, object] | None = None) -> Path:
+    root = tmp_path / "repo"
+    root.mkdir()
+    (root / ".git").mkdir()
+    if data is not None:
+        (root / "elva.json").write_text(json.dumps(data), encoding="utf-8")
+    return root
+
+
+def test_config_path_lists_every_file_even_when_absent(tmp_path: Path) -> None:
+    root = project(tmp_path)
+    result = run("config", "path", cwd=root)
+    assert result.returncode == 0
+    assert "project config" in result.stdout
+    assert "user config" in result.stdout
+    assert "(absent)" in result.stdout
+
+
+def test_config_path_marks_an_existing_project_file(tmp_path: Path) -> None:
+    root = project(tmp_path, {"workspace": "payments"})
+    result = run("config", "path", cwd=root)
+    assert "(found)" in result.stdout
+    assert "elva.json" in result.stdout
+
+
+def test_config_list_shows_value_and_origin(tmp_path: Path) -> None:
+    root = project(tmp_path, {"workspace": "payments"})
+    result = run("config", "list", cwd=root)
+    assert result.returncode == 0
+    lines = {line.split()[0]: line for line in result.stdout.splitlines() if line.strip()}
+    assert "project" in lines["workspace"]
+    assert "payments" in lines["workspace"]
+    assert "default" in lines["base_url"]
+
+
+def test_config_list_reflects_a_flag(tmp_path: Path) -> None:
+    root = project(tmp_path, {"workspace": "payments"})
+    result = run("--workspace", "other", "config", "list", cwd=root)
+    assert "other" in result.stdout
+    assert "flag" in result.stdout
+
+
+def test_config_list_reflects_env(tmp_path: Path) -> None:
+    root = project(tmp_path)
+    result = run("config", "list", cwd=root, env={"ELVA_BASE_URL": "https://env.example.com"})
+    assert "https://env.example.com" in result.stdout
+    assert "env" in result.stdout
+
+
+def test_bad_config_reports_a_coded_error(tmp_path: Path) -> None:
+    root = project(tmp_path)
+    (root / "elva.json").write_text("{oops", encoding="utf-8")
+    result = run("config", "list", cwd=root)
+    assert result.returncode == 2
+    assert "ELVA_CONFIG" in result.stderr
+    assert "Traceback" not in result.stderr

elva_cli-0.1.0/tests/cli/test_lazy_imports.py

@@ -0,0 +1,45 @@
+"""Guards the startup cost of `elva --version`.
+
+pydantic and httpx are only needed once a command touches settings or the API.
+If they ever get imported at module scope, every invocation pays for them.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+PROBE = """
+import sys
+sys.argv = ["elva", "{args}"]
+from elva_cli import main
+main._run()
+print("pydantic:", "pydantic" in sys.modules)
+print("httpx:", "httpx" in sys.modules)
+"""
+
+
+def probe(args: str) -> str:
+    result = subprocess.run(
+        [sys.executable, "-c", PROBE.format(args=args)],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return result.stdout
+
+
+def test_version_does_not_import_pydantic_or_httpx() -> None:
+    out = probe("--version")
+    assert "pydantic: False" in out
+    assert "httpx: False" in out
+
+
+def test_importing_main_alone_does_not_import_pydantic() -> None:
+    result = subprocess.run(
+        [sys.executable, "-c", "import elva_cli.main, sys; print('pydantic' in sys.modules)"],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert result.stdout.strip() == "False"

elva_cli-0.1.0/tests/unit/test_context.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+import typer
+
+from elva_cli.context import Ctx, GlobalOptions, get_ctx
+from elva_cli.errors import ElvaError
+
+
+def test_flags_reach_the_resolver(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setattr("elva_cli.settings.paths.config_dir", lambda: tmp_path)
+    (tmp_path / ".git").mkdir()
+    ctx = Ctx(GlobalOptions(workspace="payments"), cwd=tmp_path, env={})
+    assert ctx.settings.workspace == "payments"
+    assert ctx.resolution.origins["workspace"] == "flag"
+
+
+def test_resolution_is_computed_once(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setattr("elva_cli.settings.paths.config_dir", lambda: tmp_path)
+    (tmp_path / ".git").mkdir()
+    calls = 0
+    real = __import__("elva_cli.settings.loader", fromlist=["resolve"]).resolve
+
+    def counting(**kwargs: object) -> object:
+        nonlocal calls
+        calls += 1
+        return real(**kwargs)
+
+    monkeypatch.setattr("elva_cli.settings.loader.resolve", counting)
+    ctx = Ctx(GlobalOptions(), cwd=tmp_path, env={})
+    assert ctx.resolution is ctx.resolution
+    assert ctx.settings is not None
+    assert calls == 1
+
+
+def _bare_context() -> typer.Context:
+    """A click Context with nothing on obj, as if the root callback never ran."""
+    dummy = typer.Typer()
+
+    @dummy.command()
+    def noop() -> None: ...
+
+    return typer.Context(typer.main.get_command(dummy))
+
+
+def test_get_ctx_returns_what_the_callback_stored() -> None:
+    ctx = Ctx(GlobalOptions(), cwd=Path("/"), env={})
+    click_ctx = _bare_context()
+    click_ctx.obj = ctx
+    assert get_ctx(click_ctx) is ctx
+
+
+def test_get_ctx_fails_loudly_when_the_callback_did_not_run() -> None:
+    with pytest.raises(ElvaError, match="root callback"):
+        get_ctx(_bare_context())

elva_cli-0.1.0/tests/unit/test_settings_loader.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+import pytest
+
+from elva_cli.errors import ConfigError
+from elva_cli.settings.loader import resolve
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@pytest.fixture
+def home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path:
+    """Point the user config at a temp dir and give us an isolated project root."""
+    config = tmp_path / "config"
+    config.mkdir()
+    monkeypatch.setattr("elva_cli.settings.paths.config_dir", lambda: config)
+    project = tmp_path / "project"
+    project.mkdir()
+    (project / ".git").mkdir()
+    return project
+
+
+def write(path: Path, data: dict[str, Any]) -> None:
+    path.write_text(json.dumps(data), encoding="utf-8")
+
+
+def test_defaults_when_nothing_is_configured(home: Path) -> None:
+    result = resolve(env={}, cwd=home)
+    assert result.settings.base_url == "https://api.getelva.ai"
+    assert result.settings.workspace is None
+    assert result.origins["base_url"] == "default"
+
+
+def test_flag_beats_env(home: Path) -> None:
+    result = resolve(
+        overrides={"workspace": "from-flag"}, env={"ELVA_WORKSPACE": "from-env"}, cwd=home
+    )
+    assert result.settings.workspace == "from-flag"
+    assert result.origins["workspace"] == "flag"
+
+
+def test_env_beats_project_file(home: Path) -> None:
+    write(home / "elva.json", {"workspace": "from-project"})
+    result = resolve(env={"ELVA_WORKSPACE": "from-env"}, cwd=home)
+    assert result.settings.workspace == "from-env"
+    assert result.origins["workspace"] == "env"
+
+
+def test_project_file_beats_user_config(home: Path, tmp_path: Path) -> None:
+    write(tmp_path / "config" / "config.json", {"workspace": "from-user"})
+    write(home / "elva.json", {"workspace": "from-project"})
+    result = resolve(env={}, cwd=home)
+    assert result.settings.workspace == "from-project"
+    assert result.origins["workspace"] == "project"
+
+
+def test_user_config_beats_defaults(home: Path, tmp_path: Path) -> None:
+    write(tmp_path / "config" / "config.json", {"base_url": "https://staging.example.com"})
+    result = resolve(env={}, cwd=home)
+    assert result.settings.base_url == "https://staging.example.com"
+    assert result.origins["base_url"] == "user"
+
+
+def test_project_file_is_found_by_walking_up(home: Path) -> None:
+    write(home / "elva.json", {"workspace": "root-level"})
+    nested = home / "a" / "b"
+    nested.mkdir(parents=True)
+    result = resolve(env={}, cwd=nested)
+    assert result.settings.workspace == "root-level"
+
+
+def test_search_stops_at_the_repo_root(home: Path, tmp_path: Path) -> None:
+    write(tmp_path / "elva.json", {"workspace": "outside-the-repo"})
+    result = resolve(env={}, cwd=home)
+    assert result.settings.workspace is None
+
+
+def test_selected_profile_overrides_user_defaults(home: Path, tmp_path: Path) -> None:
+    write(
+        tmp_path / "config" / "config.json",
+        {
+            "base_url": "https://api.getelva.ai",
+            "profiles": {"staging": {"base_url": "https://api-staging.getelva.ai"}},
+        },
+    )
+    result = resolve(overrides={"profile": "staging"}, env={}, cwd=home)
+    assert result.settings.base_url == "https://api-staging.getelva.ai"
+    assert result.origins["base_url"] == "profile:staging"
+    assert result.profiles == ("staging",)
+
+
+def test_profile_can_be_selected_by_env(home: Path, tmp_path: Path) -> None:
+    write(tmp_path / "config" / "config.json", {"profiles": {"prod": {"timeout": 5.0}}})
+    result = resolve(env={"ELVA_PROFILE": "prod"}, cwd=home)
+    assert result.settings.timeout == 5.0
+
+
+def test_unknown_profile_is_an_error(home: Path, tmp_path: Path) -> None:
+    write(tmp_path / "config" / "config.json", {"profiles": {"prod": {}}})
+    with pytest.raises(ConfigError, match="unknown profile"):
+        resolve(overrides={"profile": "nope"}, env={}, cwd=home)
+
+
+def test_files_are_reported_whether_or_not_they_exist(home: Path) -> None:
+    result = resolve(env={}, cwd=home)
+    kinds = {f.kind: f.exists for f in result.files}
+    assert kinds == {"project": False, "user": False}
+
+    write(home / "elva.json", {})
+    result = resolve(env={}, cwd=home)
+    assert {f.kind: f.exists for f in result.files}["project"] is True
+
+
+def test_every_field_has_an_origin(home: Path) -> None:
+    result = resolve(env={}, cwd=home)
+    assert set(result.origins) == set(type(result.settings).model_fields)
+
+
+def test_malformed_json_is_an_error(home: Path) -> None:
+    (home / "elva.json").write_text("{not json", encoding="utf-8")
+    with pytest.raises(ConfigError, match="not valid JSON"):
+        resolve(env={}, cwd=home)
+
+
+def test_unknown_key_is_an_error(home: Path) -> None:
+    write(home / "elva.json", {"nope": 1})
+    with pytest.raises(ConfigError, match="invalid setting"):
+        resolve(env={}, cwd=home)
+
+
+def test_bad_base_url_names_the_layer_that_set_it(home: Path) -> None:
+    with pytest.raises(ConfigError, match="from env"):
+        resolve(env={"ELVA_BASE_URL": "ftp://nope"}, cwd=home)
+
+
+def test_bad_timeout_from_env_is_an_error(home: Path) -> None:
+    with pytest.raises(ConfigError, match="must be a number"):
+        resolve(env={"ELVA_TIMEOUT": "soon"}, cwd=home)
+
+
+def test_settings_are_frozen(home: Path) -> None:
+    settings = resolve(env={}, cwd=home).settings
+    with pytest.raises(Exception, match=r"frozen|immutable"):
+        settings.base_url = "https://elsewhere.example.com"

elva_cli-0.0.4/README.md

@@ -1,58 +0,0 @@
-# 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
-```
-
-## 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)
-- [Contributing](CONTRIBUTING.md)

elva_cli-0.0.4/src/elva_cli/context.py

@@ -1,5 +0,0 @@
-"""The Ctx object, built once in the root callback and injected into every command.
-
-Carries resolved settings, the API client, output and logging. Commands never
-import global state, which is what makes them testable. Everything expensive is a
-cached_property so `elva --version` pays for none of it."""

elva_cli-0.0.4/src/elva_cli/registry.py

@@ -1,5 +0,0 @@
-"""Lazy command dispatch.
-
-Maps command name to module path so that the command a user typed is the only
-command module imported. Declaring a command here is the only way to add one, so
-the startup cost of the tree stays visible in one file."""

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

@@ -1,5 +0,0 @@
-"""Configuration schema and precedence resolution.
-
-Order, highest first: command flags, ELVA_* environment, project elva.toml, user
-config.toml, defaults. Resolved once in the root callback and frozen onto the Ctx;
-nothing downstream re-reads the environment or the filesystem."""

elva_cli-0.0.4/src/elva_cli/settings/paths.py

@@ -1,16 +0,0 @@
-from __future__ import annotations
-
-from pathlib import Path
-
-import platformdirs
-
-APP_NAME = "elva"
-
-
-def cache_dir() -> Path:
-    """Per-user cache location: XDG on Linux, ~/Library on macOS, %LOCALAPPDATA% on Windows."""
-    return Path(platformdirs.user_cache_dir(APP_NAME, appauthor=False))
-
-
-def crash_dir() -> Path:
-    return cache_dir() / "crashes"