klavex 0.1.0__py3-none-any.whl

klavex/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

klavex/__main__.py

@@ -0,0 +1,4 @@
+from klavex.cli import app
+
+if __name__ == "__main__":
+    app()

klavex/api.py

@@ -0,0 +1,166 @@
+"""Backend HTTP client.
+
+Endpoints used by v0.1:
+  POST /cli/device-code      (login --device)
+  POST /cli/token            (login: exchange code for cli_token)
+  DELETE /cli/tokens/me      (logout, server-side revoke)
+  GET  /auth/me              (whoami)
+
+Endpoints used by later versions:
+  GET  /projects                                (v0.2)
+  GET  /projects/{id}/environments              (v0.2)
+  GET  /environments/{id}/variables             (v0.2 — names only client-side)
+  POST /environments/{id}/variables:reveal      (v0.3 — does not exist yet)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from . import __version__
+from .errors import (
+    NetworkError,
+    NotAuthenticated,
+    NotFound,
+    PermissionDenied,
+    KlavexError,
+)
+
+
+@dataclass
+class CliTokenResponse:
+    cli_token: str
+    expires_at: str | None
+    user: dict[str, Any]
+
+
+@dataclass
+class DeviceCodeResponse:
+    device_code: str
+    user_code: str
+    verification_uri: str
+    interval: int  # seconds between polls
+    expires_in: int
+
+
+class ApiClient:
+    def __init__(self, base_url: str, token: str | None = None, timeout: float = 10.0) -> None:
+        headers = {"User-Agent": f"klavex-cli/{__version__}"}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers=headers,
+            timeout=httpx.Timeout(timeout, connect=5.0),
+        )
+
+    def __enter__(self) -> ApiClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self._client.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    # ---- request helpers --------------------------------------------------
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        try:
+            response = self._client.request(method, path, **kwargs)
+        except httpx.HTTPError as exc:
+            raise NetworkError(f"Could not reach {self._client.base_url}: {exc}") from exc
+
+        if response.status_code == 401:
+            raise NotAuthenticated()
+        if response.status_code == 403:
+            raise PermissionDenied(_extract_detail(response) or "Permission denied")
+        if response.status_code == 404:
+            raise NotFound(_extract_detail(response) or "Not found")
+        if response.status_code >= 400:
+            raise KlavexError(
+                _extract_detail(response) or f"HTTP {response.status_code} from {path}"
+            )
+        return response
+
+    # ---- v0.1 endpoints ---------------------------------------------------
+
+    def exchange_cli_code(self, code: str, code_verifier: str) -> CliTokenResponse:
+        r = self._request(
+            "POST",
+            "/cli/token",
+            json={"code": code, "code_verifier": code_verifier},
+        )
+        data = r.json()
+        return CliTokenResponse(
+            cli_token=data["cli_token"],
+            expires_at=data.get("expires_at"),
+            user=data.get("user", {}),
+        )
+
+    def request_device_code(self, device_name: str) -> DeviceCodeResponse:
+        r = self._request("POST", "/cli/device-code", json={"device_name": device_name})
+        data = r.json()
+        return DeviceCodeResponse(
+            device_code=data["device_code"],
+            user_code=data["user_code"],
+            verification_uri=data["verification_uri"],
+            interval=int(data.get("interval", 5)),
+            expires_in=int(data.get("expires_in", 600)),
+        )
+
+    def poll_device_code(self, device_code: str) -> CliTokenResponse | None:
+        """Returns the token once approved, or None if still pending."""
+        r = self._client.post("/cli/token", json={"device_code": device_code})
+        if r.status_code == 202:  # still pending
+            return None
+        if r.status_code >= 400:
+            raise KlavexError(_extract_detail(r) or f"Device polling failed: {r.status_code}")
+        data = r.json()
+        return CliTokenResponse(
+            cli_token=data["cli_token"],
+            expires_at=data.get("expires_at"),
+            user=data.get("user", {}),
+        )
+
+    def revoke_current_token(self) -> None:
+        self._request("DELETE", "/cli/tokens/me")
+
+    def me(self) -> dict[str, Any]:
+        data: dict[str, Any] = self._request("GET", "/auth/me").json()
+        return data
+
+    # ---- v0.2 / v0.3 read endpoints ----
+
+    def list_projects(self) -> list[dict[str, Any]]:
+        data: list[dict[str, Any]] = self._request("GET", "/projects").json()
+        return data
+
+    def list_environments(self, project_id: str) -> list[dict[str, Any]]:
+        data: list[dict[str, Any]] = self._request(
+            "GET", f"/projects/{project_id}/environments"
+        ).json()
+        return data
+
+    def list_variables(self, environment_id: str) -> list[dict[str, Any]]:
+        """Returns variables INCLUDING values. Caller must avoid leaking values."""
+        data: list[dict[str, Any]] = self._request(
+            "GET", f"/environments/{environment_id}/variables"
+        ).json()
+        return data
+
+
+def _extract_detail(response: httpx.Response) -> str | None:
+    try:
+        body = response.json()
+    except ValueError:
+        return response.text or None
+    if isinstance(body, dict):
+        for key in ("detail", "message", "error"):
+            value = body.get(key)
+            if isinstance(value, str):
+                return value
+    return None

klavex/auth.py

@@ -0,0 +1,211 @@
+"""Browser-callback and device-code login flows.
+
+Browser flow (primary):
+  1. Bind 127.0.0.1:<random_port>. Mint state + PKCE verifier.
+  2. Open browser to <dashboard>/cli/authorize?callback=...&state=...&code_challenge=...
+  3. User approves in dashboard. Dashboard mints a one-shot code, redirects to callback.
+  4. We verify state, exchange code+verifier at POST /cli/token, get back a long-lived cli_token.
+  5. Token goes into the OS keychain. Browser tab shows "you can close this tab".
+
+Device-code flow (--device, for headless boxes):
+  Standard OAuth 2.0 device authorization grant. Poll /cli/token until approved.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import http.server
+import secrets
+import socket
+import threading
+import time
+import urllib.parse
+import webbrowser
+from dataclasses import dataclass
+from typing import Any
+
+from .api import ApiClient, CliTokenResponse, DeviceCodeResponse
+from .errors import AuthFlowError, AuthTimeout, StateMismatch
+
+# ---------- PKCE -----------------------------------------------------------
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def make_pkce_pair() -> tuple[str, str]:
+    """(verifier, challenge) — verifier stays in this process; challenge goes to the dashboard."""
+    verifier = _b64url(secrets.token_bytes(32))
+    challenge = _b64url(hashlib.sha256(verifier.encode("ascii")).digest())
+    return verifier, challenge
+
+
+# ---------- Loopback HTTP server ------------------------------------------
+
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        port: int = s.getsockname()[1]
+        return port
+
+
+_SUCCESS_HTML = b"""<!doctype html>
+<html><head><meta charset="utf-8"><title>Klavex CLI</title>
+<style>
+  body { font-family: -apple-system, system-ui, sans-serif; padding: 4rem; max-width: 32rem; margin: 0 auto; }
+  h1 { font-size: 1.25rem; }
+  p { color: #555; }
+</style></head>
+<body><h1>You're signed in.</h1><p>You can close this tab and return to your terminal.</p></body></html>
+"""
+
+_ERROR_HTML = b"""<!doctype html>
+<html><head><meta charset="utf-8"><title>Klavex CLI</title></head>
+<body><h1>Login failed.</h1><p>Return to your terminal for details.</p></body></html>
+"""
+
+
+@dataclass
+class _CallbackResult:
+    code: str | None = None
+    state: str | None = None
+    error: str | None = None
+
+
+class _CallbackServer(http.server.HTTPServer):
+    """One-shot HTTP server. Records the first /callback hit, then stops accepting requests."""
+
+    def __init__(self, port: int) -> None:
+        self.result = _CallbackResult()
+        self.received = threading.Event()
+        super().__init__(("127.0.0.1", port), _CallbackHandler)
+
+
+class _CallbackHandler(http.server.BaseHTTPRequestHandler):
+    server: _CallbackServer
+
+    def do_GET(self) -> None:
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path != "/callback":
+            self.send_response(404)
+            self.end_headers()
+            return
+
+        if self.server.received.is_set():
+            self.send_response(409)
+            self.end_headers()
+            return
+
+        params = urllib.parse.parse_qs(parsed.query)
+        result = self.server.result
+        result.code = _first(params.get("code"))
+        result.state = _first(params.get("state"))
+        result.error = _first(params.get("error"))
+
+        if result.error or not result.code:
+            self.send_response(400)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(_ERROR_HTML)
+        else:
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(_SUCCESS_HTML)
+
+        self.server.received.set()
+
+    def log_message(self, format: str, *args: Any) -> None:
+        # Silence the default stderr access log.
+        return
+
+
+def _first(values: list[str] | None) -> str | None:
+    return values[0] if values else None
+
+
+# ---------- Browser flow ---------------------------------------------------
+
+
+def browser_login(
+    api: ApiClient,
+    dashboard_url: str,
+    timeout_seconds: int = 120,
+    open_browser: bool = True,
+) -> CliTokenResponse:
+    """Run the browser-callback login flow. Returns a CLI token response on success."""
+    state = secrets.token_urlsafe(32)
+    verifier, challenge = make_pkce_pair()
+    port = _free_port()
+    callback = f"http://127.0.0.1:{port}/callback"
+
+    authorize_url = (
+        dashboard_url.rstrip("/")
+        + "/cli/authorize?"
+        + urllib.parse.urlencode(
+            {
+                "callback": callback,
+                "state": state,
+                "code_challenge": challenge,
+                "code_challenge_method": "S256",
+                "device_name": socket.gethostname(),
+            }
+        )
+    )
+
+    server = _CallbackServer(port)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        browser_opened = webbrowser.open(authorize_url) if open_browser else False
+        if not browser_opened:
+            print(f"Open this URL to continue:\n  {authorize_url}")
+
+        if not server.received.wait(timeout=timeout_seconds):
+            raise AuthTimeout(timeout_seconds)
+    finally:
+        server.shutdown()
+        thread.join(timeout=2)
+        server.server_close()
+
+    result = server.result
+    if result.error:
+        raise AuthFlowError(f"Login failed: {result.error}")
+    if not result.code:
+        raise AuthFlowError("Login failed: no code in callback")
+    if result.state != state:
+        raise StateMismatch()
+
+    return api.exchange_cli_code(code=result.code, code_verifier=verifier)
+
+
+# ---------- Device-code flow ----------------------------------------------
+
+
+def device_login(
+    api: ApiClient,
+    open_browser: bool = True,
+    poll_max_seconds: int | None = None,
+) -> CliTokenResponse:
+    """Run the device-code login flow. Polls until approved or expiry."""
+    device: DeviceCodeResponse = api.request_device_code(device_name=socket.gethostname())
+
+    print(f"Visit: {device.verification_uri}")
+    print(f"Code:  {device.user_code}")
+    print()
+    if open_browser:
+        webbrowser.open(device.verification_uri)
+
+    deadline = time.time() + min(device.expires_in, poll_max_seconds or device.expires_in)
+    interval = max(1, device.interval)
+
+    while time.time() < deadline:
+        token = api.poll_device_code(device.device_code)
+        if token is not None:
+            return token
+        time.sleep(interval)
+
+    raise AuthTimeout(device.expires_in)

klavex/cli.py

@@ -0,0 +1,98 @@
+"""Top-level Typer app. Maps custom exceptions to deterministic exit codes."""
+
+from __future__ import annotations
+
+import sys
+import traceback
+
+import typer
+
+from . import __version__
+from .commands.envs import envs
+from .commands.login import login
+from .commands.logout import logout
+from .commands.projects import projects
+from .commands.run import run
+from .commands.status import status
+from .commands.vars import list_vars
+from .commands.whoami import whoami
+from .errors import KlavexError
+
+app = typer.Typer(
+    name="klavex",
+    help="Pull environment variables into a process without writing secrets to disk.",
+    no_args_is_help=True,
+    add_completion=True,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"klavex {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: bool | None = typer.Option(
+        None, "--version", callback=_version_callback, is_eager=True, help="Show version and exit."
+    ),
+    debug: bool = typer.Option(False, "--debug", help="Print full tracebacks on errors."),
+) -> None:
+    """Root options. --debug is read from sys.argv by the error handler."""
+    return
+
+
+# Register commands — keep the binding here, not in the command modules,
+# so `cli.py` is the one place that lists what's exposed.
+app.command("login")(login)
+app.command("logout")(logout)
+app.command("whoami")(whoami)
+app.command("status")(status)
+app.command("projects")(projects)
+app.command("envs")(envs)
+app.command("vars")(list_vars)
+# `run` needs `allow_extra_args` so Typer hands us argv after `--`.
+app.command(
+    "run",
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)(run)
+
+
+def _entrypoint() -> None:
+    """Wraps the Typer app to map KlavexError -> typed exit code + clean message."""
+    try:
+        app(standalone_mode=False)
+    except KlavexError as exc:
+        typer.secho(exc.user_message(), err=True, fg=typer.colors.RED)
+        if _wants_debug():
+            traceback.print_exc()
+        sys.exit(exc.exit_code)
+    except KeyboardInterrupt:
+        typer.echo("", err=True)
+        sys.exit(130)
+    except typer.Exit as exc:
+        sys.exit(exc.exit_code)
+    except SystemExit:
+        raise
+    except Exception:
+        typer.secho("Unexpected error.", err=True, fg=typer.colors.RED)
+        traceback.print_exc()
+        sys.exit(1)
+
+
+def _wants_debug() -> bool:
+    # Read --debug flag without going through Typer's context, since the exception
+    # may have escaped before the context was populated.
+    return "--debug" in sys.argv
+
+
+# Console-script entry: pyproject.toml points `klavex` and `kx` here.
+def main() -> None:
+    _entrypoint()
+
+
+# Backwards-compat: `python -m klavex` (and the pyproject entry-points that
+# reference `klavex.cli:app`) both work.
+if __name__ == "__main__":
+    main()

klavex/commands/envs.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import typer
+
+from .. import tokens
+from ..api import ApiClient
+from ..config import UserConfig
+from ..errors import NotAuthenticated
+
+
+def envs(project_id: str = typer.Argument(..., help="Project ID, e.g. proj_abc123")) -> None:
+    """List environments in a project."""
+    token = tokens.load()
+    if not token:
+        raise NotAuthenticated()
+
+    cfg = UserConfig.load()
+    with ApiClient(cfg.api_url, token=token) as api:
+        rows = api.list_environments(project_id)
+
+    if not rows:
+        typer.echo("No environments found.")
+        return
+
+    width_id = max((len(r.get("id", "")) for r in rows), default=4)
+    width_name = max((len(r.get("name", "")) for r in rows), default=4)
+    typer.echo(f"{'ID'.ljust(width_id)}  {'NAME'.ljust(width_name)}")
+    for r in rows:
+        typer.echo(f"{r.get('id', '').ljust(width_id)}  {r.get('name', '').ljust(width_name)}")

klavex/commands/login.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import typer
+
+from .. import tokens
+from ..api import ApiClient
+from ..auth import browser_login, device_login
+from ..config import UserConfig
+
+
+def login(
+    device: bool = typer.Option(False, "--device", help="Use device-code flow (no browser open)."),
+    no_browser: bool = typer.Option(
+        False, "--no-browser", help="Print the URL instead of opening a browser."
+    ),
+    timeout: int = typer.Option(120, "--timeout", help="Seconds to wait for the browser callback."),
+) -> None:
+    """Log in to Klavex. Opens your browser for authentication."""
+    cfg = UserConfig.load()
+
+    with ApiClient(cfg.api_url) as api:
+        if device:
+            response = device_login(api, open_browser=not no_browser)
+        else:
+            response = browser_login(
+                api,
+                dashboard_url=cfg.dashboard_url,
+                timeout_seconds=timeout,
+                open_browser=not no_browser,
+            )
+
+    tokens.store(response.cli_token)
+
+    user_name = response.user.get("name") or response.user.get("email") or "you"
+    typer.echo(f"Logged in as {user_name}.")

klavex/commands/logout.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import typer
+
+from .. import tokens
+from ..api import ApiClient
+from ..config import UserConfig
+from ..errors import NetworkError, NotAuthenticated
+
+
+def logout(
+    keep_remote: bool = typer.Option(
+        False,
+        "--keep-remote",
+        help="Only delete the local token, don't revoke server-side.",
+    ),
+) -> None:
+    """Log out of Klavex. Deletes the local token and revokes it server-side."""
+    token = tokens.load()
+    if not token:
+        typer.echo("Already logged out.")
+        return
+
+    if not keep_remote:
+        cfg = UserConfig.load()
+        try:
+            with ApiClient(cfg.api_url, token=token) as api:
+                api.revoke_current_token()
+        except (NetworkError, NotAuthenticated):
+            # If the server is unreachable or the token is already invalid, the
+            # local delete still matters. Don't block the user on it.
+            pass
+
+    tokens.delete()
+    typer.echo("Logged out.")

klavex/commands/projects.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import typer
+
+from .. import tokens
+from ..api import ApiClient
+from ..config import UserConfig
+from ..errors import NotAuthenticated
+
+
+def projects() -> None:
+    """List projects in your team."""
+    token = tokens.load()
+    if not token:
+        raise NotAuthenticated()
+
+    cfg = UserConfig.load()
+    with ApiClient(cfg.api_url, token=token) as api:
+        rows = api.list_projects()
+
+    if not rows:
+        typer.echo("No projects found.")
+        return
+
+    width_id = max((len(r.get("id", "")) for r in rows), default=4)
+    width_name = max((len(r.get("name", "")) for r in rows), default=4)
+    typer.echo(f"{'ID'.ljust(width_id)}  {'NAME'.ljust(width_name)}")
+    for r in rows:
+        typer.echo(f"{r.get('id', '').ljust(width_id)}  {r.get('name', '').ljust(width_name)}")

klavex/commands/run.py

@@ -0,0 +1,65 @@
+"""klavex run -e <env_id> -- <cmd...>
+
+Pulls variables for the env, spawns <cmd> with them in its environment.
+The parent shell never sees the secrets; nothing is written to disk.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from .. import tokens
+from ..api import ApiClient
+from ..config import ProjectPin, UserConfig
+from ..errors import NotAuthenticated, UsageError
+from ..inject import run as inject_run
+
+
+def run(
+    ctx: typer.Context,
+    env: str | None = typer.Option(
+        None,
+        "-e",
+        "--env",
+        help="Environment ID. Falls back to default_env in .klavex.",
+    ),
+    no_inherit: bool = typer.Option(
+        False,
+        "--no-inherit",
+        help="Don't inherit the parent shell's env. Only the fetched vars are passed in.",
+    ),
+) -> None:
+    """Run a command with vars from an environment injected into its process env.
+
+    Example:  klavex run -e env_dev_abc -- npm start
+    """
+    token = tokens.load()
+    if not token:
+        raise NotAuthenticated()
+
+    argv = list(ctx.args)
+    if not argv:
+        raise UsageError("Nothing to run. Pass a command after `--`.")
+
+    env_id = env
+    if not env_id:
+        pin = ProjectPin.find()
+        if pin and pin.default_env:
+            env_id = pin.default_env
+    if not env_id:
+        raise UsageError(
+            "No environment specified. Pass -e <env_id> or set default_env in a .klavex file."
+        )
+
+    cfg = UserConfig.load()
+    with ApiClient(cfg.api_url, token=token) as api:
+        rows = api.list_variables(env_id)
+
+    env_vars: dict[str, str] = {}
+    for r in rows:
+        key = r.get("key")
+        value = r.get("value")
+        if isinstance(key, str) and isinstance(value, str):
+            env_vars[key] = value
+
+    raise typer.Exit(code=inject_run(env_vars, argv, inherit_parent=not no_inherit))

klavex/commands/status.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import typer
+
+from .. import tokens
+from ..config import ProjectPin, UserConfig
+
+
+def status() -> None:
+    """Show local CLI state — login, project pin, API URL — without hitting the network."""
+    cfg = UserConfig.load()
+    has_token = tokens.load() is not None
+
+    typer.echo(f"API URL:        {cfg.api_url}")
+    typer.echo(f"Dashboard URL:  {cfg.dashboard_url}")
+    typer.echo(f"Logged in:      {'yes' if has_token else 'no'}")
+
+    pin = ProjectPin.find()
+    if pin:
+        typer.echo(f"Project pin:    {pin.project} (from {pin.path})")
+        if pin.default_env:
+            typer.echo(f"Default env:    {pin.default_env}")
+    else:
+        typer.echo("Project pin:    none (no .klavex file in cwd or parents)")

klavex/commands/vars.py

@@ -0,0 +1,36 @@
+"""List variable NAMES in an environment.
+
+Values are never printed by this command — that's what `run` is for.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from .. import tokens
+from ..api import ApiClient
+from ..config import UserConfig
+from ..errors import NotAuthenticated
+
+
+def list_vars(
+    env: str = typer.Option(..., "-e", "--env", help="Environment ID"),
+) -> None:
+    """List variable names in an environment (values are never shown)."""
+    token = tokens.load()
+    if not token:
+        raise NotAuthenticated()
+
+    cfg = UserConfig.load()
+    with ApiClient(cfg.api_url, token=token) as api:
+        rows = api.list_variables(env)
+
+    if not rows:
+        typer.echo("No variables in this environment.")
+        return
+
+    keys = sorted(r.get("key", "") for r in rows)
+    is_secret_by_key = {r.get("key", ""): r.get("is_secret", False) for r in rows}
+    for k in keys:
+        marker = " (secret)" if is_secret_by_key.get(k) else ""
+        typer.echo(f"{k}{marker}")

klavex/commands/whoami.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import typer
+
+from .. import tokens
+from ..api import ApiClient
+from ..config import UserConfig
+from ..errors import NotAuthenticated
+
+
+def whoami() -> None:
+    """Show the currently logged-in user and team."""
+    token = tokens.load()
+    if not token:
+        raise NotAuthenticated()
+
+    cfg = UserConfig.load()
+    with ApiClient(cfg.api_url, token=token) as api:
+        me = api.me()
+
+    user = me.get("user", me) if isinstance(me, dict) else {}
+    name = user.get("name") or user.get("email") or "?"
+    email = user.get("email", "?")
+    role = me.get("role") if isinstance(me, dict) else None
+
+    typer.echo(f"User:  {name} <{email}>")
+    if role:
+        typer.echo(f"Role:  {role}")

klavex/config.py

@@ -0,0 +1,109 @@
+"""Non-secret configuration.
+
+Two scopes:
+- User config:  ~/.config/klavex/config.toml — API URL override, telemetry opt-out.
+- Project pin: .klavex — committed to the project; pins project_id + default_env.
+
+Tokens never live here. Tokens go in the OS keychain (see tokens.py).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+import tomli_w
+from platformdirs import user_config_path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[import-not-found]
+
+DEFAULT_API_URL = "https://api.klavex.dev/api"
+DEFAULT_DASHBOARD_URL = "https://app.klavex.dev"
+
+PIN_FILENAME = ".klavex"
+
+
+def _user_config_path() -> Path:
+    return user_config_path("klavex") / "config.toml"
+
+
+@dataclass
+class UserConfig:
+    api_url: str = DEFAULT_API_URL
+    dashboard_url: str = DEFAULT_DASHBOARD_URL
+    telemetry: bool = True
+
+    @classmethod
+    def load(cls) -> UserConfig:
+        path = _user_config_path()
+        data: dict[str, object] = {}
+        if path.exists():
+            with path.open("rb") as f:
+                data = tomllib.load(f)
+
+        # Env overrides win over file config.
+        api_url = os.environ.get("KLAVEX_API_URL") or data.get("api_url") or DEFAULT_API_URL
+        dashboard_url = (
+            os.environ.get("KLAVEX_DASHBOARD_URL")
+            or data.get("dashboard_url")
+            or DEFAULT_DASHBOARD_URL
+        )
+        telemetry = bool(data.get("telemetry", True))
+        if os.environ.get("KLAVEX_NO_TELEMETRY"):
+            telemetry = False
+        return cls(api_url=str(api_url), dashboard_url=str(dashboard_url), telemetry=telemetry)
+
+    def save(self) -> None:
+        path = _user_config_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("wb") as f:
+            tomli_w.dump(
+                {
+                    "api_url": self.api_url,
+                    "dashboard_url": self.dashboard_url,
+                    "telemetry": self.telemetry,
+                },
+                f,
+            )
+
+
+@dataclass
+class ProjectPin:
+    project: str
+    default_env: str | None = None
+    path: Path | None = None  # the .klavex file we read it from
+
+    @classmethod
+    def find(cls, start: Path | None = None) -> ProjectPin | None:
+        """Walk up from `start` (default cwd) looking for a .klavex file."""
+        cur = (start or Path.cwd()).resolve()
+        for d in (cur, *cur.parents):
+            candidate = d / PIN_FILENAME
+            if candidate.is_file():
+                with candidate.open("rb") as f:
+                    data = tomllib.load(f)
+                project = data.get("project")
+                if not isinstance(project, str):
+                    return None
+                default_env = data.get("default_env")
+                return cls(
+                    project=project,
+                    default_env=str(default_env) if isinstance(default_env, str) else None,
+                    path=candidate,
+                )
+        return None
+
+    @classmethod
+    def write(cls, project: str, default_env: str | None, dest: Path | None = None) -> Path:
+        path = (dest or Path.cwd()) / PIN_FILENAME
+        payload: dict[str, object] = {"project": project}
+        if default_env:
+            payload["default_env"] = default_env
+        with path.open("wb") as f:
+            tomli_w.dump(payload, f)
+        return path

klavex/errors.py

@@ -0,0 +1,61 @@
+"""Typed exceptions mapped to deterministic CLI exit codes."""
+
+from __future__ import annotations
+
+
+class KlavexError(Exception):
+    """Base error. Each subclass owns one exit code."""
+
+    exit_code: int = 1
+
+    def user_message(self) -> str:
+        return str(self)
+
+
+class UsageError(KlavexError):
+    exit_code = 2
+
+
+class NotAuthenticated(KlavexError):
+    exit_code = 3
+
+    def user_message(self) -> str:
+        return "Not logged in. Run `klavex login` first."
+
+
+class NetworkError(KlavexError):
+    exit_code = 4
+
+
+class PermissionDenied(KlavexError):
+    exit_code = 5
+
+
+class NotFound(KlavexError):
+    exit_code = 6
+
+
+class AuthFlowError(KlavexError):
+    """Anything that goes wrong during the browser/device-code flow."""
+
+    exit_code = 3
+
+
+class StateMismatch(AuthFlowError):
+    def user_message(self) -> str:
+        return "Login aborted: state parameter did not match. Try again."
+
+
+class AuthTimeout(AuthFlowError):
+    def __init__(self, seconds: int) -> None:
+        super().__init__(f"Login timed out after {seconds} seconds")
+
+
+class TokenStoreUnavailable(KlavexError):
+    exit_code = 1
+
+    def user_message(self) -> str:
+        return (
+            "No OS keychain backend is available, so the CLI token cannot be stored "
+            "securely. Install a keyring backend (e.g. `secretstorage` on Linux) and retry."
+        )

klavex/inject.py

@@ -0,0 +1,28 @@
+"""The headline mechanism: spawn a child process with secrets in its env,
+and never write them to disk.
+
+This is twelve lines and the entire reason the product exists.
+
+Hard rules:
+  - NEVER use shell=True (turns unescaped values into shell injection).
+  - NEVER write env values to a log, telemetry payload, or temp file.
+  - NEVER mutate os.environ in the parent — secrets only exist in the child.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+
+from .errors import UsageError
+
+
+def run(env_vars: dict[str, str], argv: list[str], inherit_parent: bool = True) -> int:
+    """Run argv with `env_vars` injected into its environment. Returns exit code."""
+    if not argv:
+        raise UsageError("Nothing to run. Pass a command after `--`.")
+
+    base = dict(os.environ) if inherit_parent else {}
+    child_env = {**base, **env_vars}
+    proc = subprocess.run(argv, env=child_env)
+    return proc.returncode

klavex/tokens.py

@@ -0,0 +1,42 @@
+"""CLI token storage in the OS keychain.
+
+We refuse to fall back to a plaintext file. The whole product premise is
+"no plaintext secrets on disk", and that has to apply to our own auth too.
+"""
+
+from __future__ import annotations
+
+import keyring
+import keyring.errors
+from keyring.backends.fail import Keyring as FailKeyring
+
+from .errors import TokenStoreUnavailable
+
+SERVICE = "klavex"
+DEFAULT_PROFILE = "default"
+
+
+def _ensure_backend() -> None:
+    if isinstance(keyring.get_keyring(), FailKeyring):
+        raise TokenStoreUnavailable()
+
+
+def store(token: str, profile: str = DEFAULT_PROFILE) -> None:
+    _ensure_backend()
+    keyring.set_password(SERVICE, profile, token)
+
+
+def load(profile: str = DEFAULT_PROFILE) -> str | None:
+    try:
+        return keyring.get_password(SERVICE, profile)
+    except keyring.errors.KeyringError:
+        return None
+
+
+def delete(profile: str = DEFAULT_PROFILE) -> bool:
+    """Returns True if a token was removed, False if there was nothing to remove."""
+    try:
+        keyring.delete_password(SERVICE, profile)
+        return True
+    except keyring.errors.PasswordDeleteError:
+        return False

klavex-0.1.0.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: klavex
+Version: 0.1.0
+Summary: Klavex CLI — pull environment variables into a process without writing secrets to disk.
+Author: Klavex
+License: Proprietary
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: keyring<26,>=24
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: tomli-w<2.0,>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer<1.0,>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# klavex
+
+CLI for [Klavex](https://klavex.dev). Pulls environment variables from your team's vault and injects them into a child process — secrets never touch disk.
+
+```bash
+pip install klavex
+klavex login
+klavex run -- npm start
+```
+
+See [IMPLEMENTATION.md](./IMPLEMENTATION.md) for the design.
+
+## Commands
+
+| Command | Status |
+| --- | --- |
+| `klavex login` | v0.1 |
+| `klavex logout` | v0.1 |
+| `klavex whoami` | v0.1 |
+| `klavex status` | v0.1 |
+| `klavex projects` | v0.2 |
+| `klavex envs <project>` | v0.2 |
+| `klavex vars -e <env>` | v0.2 |
+| `klavex run -e <env> -- <cmd>` | v0.3 (blocked on backend reveal endpoint) |
+| `klavex export -e <env>` | v0.4 |
+| `klavex use -p <project> -e <env>` | v0.4 |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+klavex --version
+pytest
+ruff check .
+mypy
+```
+
+Override the API URL for staging or local:
+
+```bash
+export KLAVEX_API_URL=http://localhost:8000
+```

klavex-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+klavex/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+klavex/__main__.py,sha256=cXCL1fiQxRjqFbb1L5R1cmFa8T95gAuJBMFLEOFGnUw,65
+klavex/api.py,sha256=TKGeGlzREaIuhwIP-Is8rmlDIStRX6PX8O5kbuKAhTA,5516
+klavex/auth.py,sha256=5y77Lc4qimvEFm4Vje_XtT9m8Yq_rjYdayFzqNp0mho,6746
+klavex/cli.py,sha256=DMTygeIWDEKd2hVHH92Zo5u7GG6WIQPP2MXjfIXbPQ8,2849
+klavex/config.py,sha256=1YFHy6PVfo-rOVYafp_YRov-XLp6aejG-WDAUtIc578,3456
+klavex/errors.py,sha256=BDt5v-AYkPBnNOwtixXCDd8Wyoho1P_FNIF8k2iegFI,1362
+klavex/inject.py,sha256=6ApAbsccvsPRz_3vRtP5OBS8-gOydvyyB3GIVqvv5Bk,932
+klavex/tokens.py,sha256=xz2SbZtLQIlsG5V0_vCbpmItINq3p_lT2e9T4pvdTKM,1146
+klavex/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+klavex/commands/envs.py,sha256=UyI4VQ09NxJlRvmtuMrJCsH2NxQgUiGQIM2d7jXQgwA,920
+klavex/commands/login.py,sha256=pjJ8gklfS71UKRh3v3fi9X1msc8zCFgN3_xNY5TnK08,1142
+klavex/commands/logout.py,sha256=1Q0ekSzsgsLUfAsQ0DqnBOrHtlMZ8aQfhfyHMhfYFvo,988
+klavex/commands/projects.py,sha256=km6MNEYqfXvoHjiHBQ3WL7Nn-4nqKFbDTdZdYiPwGsc,828
+klavex/commands/run.py,sha256=Cc26CD2O9NyYi6LUbv7qNOcgn0qF_guDPPwpuxma2LE,1840
+klavex/commands/status.py,sha256=XoaiB1gjg8217USQqvHos6wdI8KxPsG3Ep3h2PBB1iI,767
+klavex/commands/vars.py,sha256=1SOOpjdhpYLGb78j4O9u-JcO3wkiz4OGMgtVR0A4oh4,1002
+klavex/commands/whoami.py,sha256=9dRB24d8xhFDO2adkwl_69qjg-qpUCJzcIfjL7zdwss,737
+klavex-0.1.0.dist-info/METADATA,sha256=So-mgIigU7R8y6mbgNMiEcdMVpy7fNpzY47KbAMYQ3Y,2066
+klavex-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+klavex-0.1.0.dist-info/entry_points.txt,sha256=9kKuhD7EfWiHS8NF_RPMfvUBCbUZIOISXe7oGNblUY4,64
+klavex-0.1.0.dist-info/RECORD,,

klavex-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

klavex-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+klavex = klavex.cli:main
+kx = klavex.cli:main