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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: elva-cli
-Version: 0.1.0
+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
@@ -136,14 +136,32 @@ 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
+collection  work-api    profile:work
+profile     work        flag
+timeout     30.0        default
+workspace   work-team   profile:work
 
-profiles      side, 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`)

{elva_cli-0.1.0 → elva_cli-0.2.0}/README.md

@@ -109,14 +109,32 @@ 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
+collection  work-api    profile:work
+profile     work        flag
+timeout     30.0        default
+workspace   work-team   profile:work
 
-profiles      side, 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`)

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

@@ -49,6 +49,18 @@ def root(
     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",
@@ -64,6 +76,10 @@ def root(
             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,
@@ -71,10 +87,14 @@ def root(
 
 
 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:

elva_cli-0.2.0/src/elva_cli/ui/console.py

@@ -0,0 +1,33 @@
+"""Two consoles: data on stdout, everything else on stderr.
+
+That split is what keeps `elva pull spec | jq` clean. Spinners, hints, warnings
+and errors must never land in the stream a caller is parsing.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from rich.console import Console
+
+from elva_cli.ui.theme import ELVA_THEME
+
+
+def build_consoles(*, color: bool | None, quiet: bool) -> tuple[Console, Console]:
+    out = Console(
+        file=sys.stdout,
+        theme=ELVA_THEME,
+        highlight=False,
+        no_color=color is False,
+        force_terminal=True if color else None,
+    )
+    err = Console(
+        file=sys.stderr,
+        stderr=True,
+        theme=ELVA_THEME,
+        highlight=False,
+        quiet=quiet,
+        no_color=color is False,
+        force_terminal=True if color else None,
+    )
+    return out, err

elva_cli-0.2.0/src/elva_cli/ui/output.py

@@ -0,0 +1,65 @@
+"""The single place a Result turns into bytes on a stream.
+
+Commands hand their Result here and stop. The human/JSON branch happens once, at
+the last moment, so --json costs nothing per command and can never drift from
+what a person sees.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from typing import TYPE_CHECKING, Any
+
+from elva_cli.ui.renderables import render
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+    from elva_cli.errors import ElvaError
+
+
+def as_data(result: object) -> Any:
+    if dataclasses.is_dataclass(result) and not isinstance(result, type):
+        return dataclasses.asdict(result)
+    msg = f"Results must be dataclasses, got {type(result).__name__}"
+    raise TypeError(msg)
+
+
+class Output:
+    def __init__(self, *, stdout: Console, stderr: Console, json_mode: bool, quiet: bool) -> None:
+        self._out = stdout
+        self._err = stderr
+        self.json_mode = json_mode
+        self.quiet = quiet
+
+    def result(self, result: object) -> None:
+        """Emit a command's payload. Exactly one call per command."""
+        if self.json_mode:
+            self._out.file.write(json.dumps(as_data(result), indent=2, default=str) + "\n")
+            self._out.file.flush()
+            return
+        self._out.print(render(result), soft_wrap=True)
+
+    def hint(self, message: str) -> None:
+        self._err.print(message, style="elva.dim")
+
+    def warn(self, message: str) -> None:
+        self._err.print(f"warning: {message}", style="elva.warn")
+
+    def error(self, error: ElvaError) -> None:
+        write_error(self._err, error)
+
+
+def write_error(console: Console, error: ElvaError) -> None:
+    console.print(f"{error.code}: {error.message}", style="elva.error", soft_wrap=True)
+    if error.hint:
+        console.print(f"  -> {error.hint}", style="elva.dim", soft_wrap=True)
+
+
+def report_error(error: ElvaError, *, color: bool | None = None) -> None:
+    """Render an error when no Ctx exists, which is the case in the boundary."""
+    from elva_cli.ui.console import build_consoles
+
+    _, err = build_consoles(color=color, quiet=False)
+    write_error(err, error)

elva_cli-0.2.0/src/elva_cli/ui/prompts.py

@@ -0,0 +1,91 @@
+"""Prompts that always have a non-interactive equivalent.
+
+Every helper takes the flag value first. If it was supplied, nothing is asked. If
+it was not and there is nobody to ask, the result is a usage error rather than a
+hang, because a CLI that blocks waiting for input in CI is the worst failure mode
+there is.
+
+These live in ui/ so nothing under core/ can reach them.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from elva_cli.errors import UsageError
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from elva_cli.context import Ctx
+
+
+def _refuse(flag: str) -> UsageError:
+    return UsageError(
+        f"{flag} is required when there is no terminal to prompt on",
+        hint=f"Pass {flag} on the command line, or run this in an interactive shell.",
+    )
+
+
+def text(
+    value: str | None,
+    *,
+    prompt: str,
+    flag: str,
+    ctx: Ctx,
+    default: str | None = None,
+) -> str:
+    if value is not None:
+        return value
+    if not ctx.interactive:
+        raise _refuse(flag)
+
+    import questionary
+
+    return str(questionary.text(prompt, default=default or "").unsafe_ask())
+
+
+def select(
+    value: str | None,
+    *,
+    prompt: str,
+    choices: Sequence[str],
+    flag: str,
+    ctx: Ctx,
+) -> str:
+    if value is not None:
+        if value not in choices:
+            raise UsageError(
+                f"{value!r} is not a valid value for {flag}",
+                hint=f"Choose one of: {', '.join(choices)}",
+            )
+        return value
+    if not ctx.interactive:
+        raise _refuse(flag)
+
+    import questionary
+
+    return str(questionary.select(prompt, choices=list(choices)).unsafe_ask())
+
+
+def confirm(
+    value: bool | None,
+    *,
+    prompt: str,
+    ctx: Ctx,
+    default: bool = False,
+) -> bool:
+    """Ask for a yes or no. --yes answers every one of these without asking."""
+    if value is not None:
+        return value
+    if ctx.assume_yes:
+        return True
+    if not ctx.interactive:
+        raise UsageError(
+            f"cannot ask for confirmation: {prompt}",
+            hint="Pass --yes to confirm without prompting.",
+        )
+
+    import questionary
+
+    return bool(questionary.confirm(prompt, default=default).unsafe_ask())

elva_cli-0.2.0/src/elva_cli/ui/renderables/__init__.py

@@ -0,0 +1,12 @@
+"""Rich renderers for Result objects, dispatched on type.
+
+Keeping the data to presentation mapping here is what stops --json from drifting
+from human output: both start from the same dataclass.
+"""
+
+from __future__ import annotations
+
+from elva_cli.ui.renderables import config as _config  # noqa: F401  registers renderers
+from elva_cli.ui.renderables.base import render
+
+__all__ = ["render"]

elva_cli-0.2.0/src/elva_cli/ui/renderables/base.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from functools import singledispatch
+from typing import TYPE_CHECKING
+
+from rich.text import Text
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from rich.console import RenderableType
+
+
+@singledispatch
+def render(result: object) -> RenderableType:
+    msg = f"no renderer registered for {type(result).__name__}"
+    raise NotImplementedError(msg)
+
+
+def aligned_rows(entries: Sequence[tuple[str, Text, Text]]) -> Text:
+    """Lay out rows as aligned plain lines."""
+    if not entries:
+        return Text("")
+
+    label_width = max(len(label) for label, _, _ in entries) + 2
+    value_width = max(value.cell_len for _, value, _ in entries) + 2
+
+    lines: list[Text] = []
+    for label, value, note in entries:
+        line = Text()
+        line.append(label.ljust(label_width), style="elva.key")
+        line.append_text(value)
+        if note.plain:
+            line.append(" " * max(1, value_width - value.cell_len))
+            line.append_text(note)
+        lines.append(line)
+    return Text("\n").join(lines)

elva_cli-0.2.0/src/elva_cli/ui/renderables/config.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from rich.console import Group
+from rich.text import Text
+
+# Imported at runtime, not under TYPE_CHECKING: singledispatch resolves the
+# annotation when register() runs, so the class has to actually exist.
+from elva_cli.core.services.config import ConfigPaths, ConfigValues  # noqa: TC001
+from elva_cli.ui.renderables.base import aligned_rows, render
+
+
+@render.register
+def _(result: ConfigPaths) -> Text:
+    entries = [
+        ("config dir", Text(result.config_dir), Text("")),
+        ("cache dir", Text(result.cache_dir), Text("")),
+    ]
+    for file in result.files:
+        state = Text("found", style="elva.ok") if file.exists else Text("absent", style="elva.dim")
+        entries.append((f"{file.kind} config", Text(file.path), state))
+    return aligned_rows(entries)
+
+
+@render.register
+def _(result: ConfigValues) -> Group:
+    entries = []
+    for setting in result.settings:
+        if setting.value is None:
+            value = Text("-", style="elva.dim")
+        elif setting.value is True:
+            value = Text("true")
+        elif setting.value is False:
+            value = Text("false")
+        else:
+            value = Text(str(setting.value))
+        entries.append((setting.key, value, Text(setting.origin, style="elva.origin")))
+
+    table = aligned_rows(entries)
+    if not result.profiles:
+        return Group(table)
+    return Group(table, Text(""), Text(f"profiles: {', '.join(result.profiles)}", style="elva.dim"))

elva_cli-0.2.0/src/elva_cli/ui/theme.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from rich.theme import Theme
+
+ELVA_THEME = Theme(
+    {
+        "elva.key": "bold",
+        "elva.dim": "dim",
+        "elva.accent": "cyan",
+        "elva.ok": "green",
+        "elva.warn": "yellow",
+        "elva.error": "bold red",
+        "elva.origin": "dim",
+    }
+)