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

elva_cli-0.2.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.5
+Name: elva-cli
+Version: 0.2.0
+Summary: Elva - CLI for Theneo Elva
+Project-URL: Homepage, https://getelva.ai
+Project-URL: Source, https://github.com/Theneo-Inc/theneo-elva-cli
+Project-URL: Issues, https://github.com/Theneo-Inc/theneo-elva-cli/issues
+Author-email: Theneo <support@theneo.io>
+Keywords: api,cli,documentation,elva,openapi,theneo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+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'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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
+```
+
+Every command also takes `--json` for scripting:
+
+```
+$ elva --profile work --json config list
+{
+  "profile": "work",
+  "settings": [
+    { "key": "collection", "value": "work-api", "origin": "profile:work" },
+    { "key": "workspace", "value": "work-team", "origin": "profile:work" }
+  ],
+  "profiles": ["side", "work"]
+}
+```
+
+Data goes to stdout and everything else to stderr, so `elva --json ... | jq` is always
+clean. `--quiet` drops hints and warnings but keeps data and errors. `--no-color` and
+`NO_COLOR` turn off styling.
+
+## 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.2.0/README.md

@@ -0,0 +1,148 @@
+# 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
+```
+
+Every command also takes `--json` for scripting:
+
+```
+$ elva --profile work --json config list
+{
+  "profile": "work",
+  "settings": [
+    { "key": "collection", "value": "work-api", "origin": "profile:work" },
+    { "key": "workspace", "value": "work-team", "origin": "profile:work" }
+  ],
+  "profiles": ["side", "work"]
+}
+```
+
+Data goes to stdout and everything else to stderr, so `elva --json ... | jq` is always
+clean. `--quiet` drops hints and warnings but keeps data and errors. `--no-color` and
+`NO_COLOR` turn off styling.
+
+## 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.2.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.2.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.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
 
 __commit_id__ = commit_id = None

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

@@ -0,0 +1,25 @@
+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)
+
+
+@app.command("path")
+def path(click_ctx: typer.Context) -> None:
+    """Show every file the CLI reads configuration from."""
+    from elva_cli.core.services.config import describe_paths
+
+    ctx = get_ctx(click_ctx)
+    ctx.out.result(describe_paths(ctx.resolution))
+
+
+@app.command("list")
+def list_(click_ctx: typer.Context) -> None:
+    """Show each setting, its value, and which layer set it."""
+    from elva_cli.core.services.config import describe_values
+
+    ctx = get_ctx(click_ctx)
+    ctx.out.result(describe_values(ctx.resolution))

elva_cli-0.2.0/src/elva_cli/context.py

@@ -0,0 +1,148 @@
+"""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
+
+import sys
+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 rich.console import Console
+
+    from elva_cli.settings.loader import Resolution
+    from elva_cli.settings.models import Settings
+    from elva_cli.ui.output import Output
+
+
+@dataclass(frozen=True)
+class GlobalOptions:
+    profile: str | None = None
+    base_url: str | None = None
+    workspace: str | None = None
+    collection: str | None = None
+    json_output: bool = False
+    quiet: bool = False
+    color: bool | None = None
+    assume_yes: bool = False
+
+
+CI_VARS = (
+    "CI",
+    "GITHUB_ACTIONS",
+    "GITLAB_CI",
+    "CIRCLECI",
+    "BUILDKITE",
+    "JENKINS_URL",
+    "TF_BUILD",
+    "TEAMCITY_VERSION",
+)
+
+_FALSEY = frozenset({"", "0", "false", "no", "off"})
+
+
+class Ctx:
+    def __init__(
+        self,
+        options: GlobalOptions,
+        *,
+        cwd: Path,
+        env: Mapping[str, str],
+        tty: bool | None = None,
+    ) -> None:
+        self.options = options
+        self.cwd = cwd
+        self.env = env
+        self._tty = tty
+
+    @property
+    def assume_yes(self) -> bool:
+        return self.options.assume_yes
+
+    @property
+    def is_ci(self) -> bool:
+        return any(self.env.get(var, "").strip().lower() not in _FALSEY for var in CI_VARS)
+
+    @property
+    def is_tty(self) -> bool:
+        """Both streams, because a prompt needs to read and to be seen."""
+        if self._tty is not None:
+            return self._tty
+        return sys.stdin.isatty() and sys.stdout.isatty()
+
+    @property
+    def interactive(self) -> bool:
+        """Whether it is safe to ask the user a question.
+
+        The single place this is decided. --json means a machine is reading, so a
+        prompt would corrupt the output as well as hang. --quiet is not included:
+        it lowers the noise floor, it does not say nobody is there.
+        """
+        if self.options.json_output or self.is_ci:
+            return False
+        return self.is_tty
+
+    @property
+    def color(self) -> bool | None:
+        """NO_COLOR wins over everything except an explicit --color."""
+        if self.options.color is None and self.env.get("NO_COLOR"):
+            return False
+        return self.options.color
+
+    @cached_property
+    def consoles(self) -> tuple[Console, Console]:
+        from elva_cli.ui.console import build_consoles
+
+        return build_consoles(color=self.color, quiet=self.options.quiet)
+
+    @cached_property
+    def out(self) -> Output:
+        from elva_cli.ui.output import Output
+
+        stdout, stderr = self.consoles
+        return Output(
+            stdout=stdout,
+            stderr=stderr,
+            json_mode=self.options.json_output,
+            quiet=self.options.quiet,
+        )
+
+    @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.2.0/src/elva_cli/core/services/config.py

@@ -0,0 +1,67 @@
+"""Use cases for inspecting configuration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from elva_cli.settings import paths
+
+if TYPE_CHECKING:
+    from elva_cli.settings.loader import Resolution
+
+
+@dataclass(frozen=True)
+class ConfigFileInfo:
+    kind: str
+    path: str
+    exists: bool
+
+
+@dataclass(frozen=True)
+class ConfigPaths:
+    config_dir: str
+    cache_dir: str
+    files: list[ConfigFileInfo] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class SettingValue:
+    key: str
+    value: Any
+    origin: str
+
+
+@dataclass(frozen=True)
+class ConfigValues:
+    profile: str
+    settings: list[SettingValue] = field(default_factory=list)
+    profiles: list[str] = field(default_factory=list)
+
+
+def describe_paths(resolution: Resolution) -> ConfigPaths:
+    """Report every location the CLI consulted, whether or not it existed."""
+    return ConfigPaths(
+        config_dir=str(paths.config_dir()),
+        cache_dir=str(paths.cache_dir()),
+        files=[
+            ConfigFileInfo(kind=f.kind, path=str(f.path), exists=f.exists) for f in resolution.files
+        ],
+    )
+
+
+def describe_values(resolution: Resolution) -> ConfigValues:
+    """Report each resolved setting alongside the layer that set it."""
+    settings = resolution.settings
+    return ConfigValues(
+        profile=settings.profile,
+        settings=[
+            SettingValue(
+                key=key,
+                value=getattr(settings, key),
+                origin=resolution.origins[key],
+            )
+            for key in sorted(type(settings).model_fields)
+        ],
+        profiles=list(resolution.profiles),
+    )

{elva_cli-0.0.4 → elva_cli-0.2.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,31 @@ 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."
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="Emit machine readable JSON instead of formatted output."
+    ),
+    quiet: bool = typer.Option(
+        False, "--quiet", "-q", help="Suppress hints and warnings. Data and errors still print."
+    ),
+    assume_yes: bool = typer.Option(
+        False, "--yes", "-y", help="Answer every confirmation with yes. Required in CI."
+    ),
+    color: bool | None = typer.Option(
+        None, "--color/--no-color", help="Force or disable colour. Honours NO_COLOR."
+    ),
     version: bool = typer.Option(
         False,
         "--version",
@@ -44,14 +70,31 @@ 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,
+            json_output=json_output,
+            quiet=quiet,
+            color=color,
+            assume_yes=assume_yes,
+        ),
+        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)
+    """Render a user-facing error to stderr.
+
+    Goes through ui/ so errors look the same wherever they come from, but does not
+    need a Ctx: the boundary has to work when building the Ctx is what failed.
+    """
+    from elva_cli.ui.output import report_error
+
+    report_error(error, color=False if os.environ.get("NO_COLOR") else None)
 
 
 def write_crash(exc: BaseException) -> Path | None: