verulla-cli 0.0.2__py3-none-any.whl

verulla_cli/__init__.py

@@ -0,0 +1,7 @@
+"""Verulla CLI.
+
+Human + agent entry point: login (OIDC device flow), dev (local Docker
+emulation via verulla_manifest), deploy, secrets, logs.
+"""
+
+__version__ = "0.0.2"

verulla_cli/apps_client.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from verulla_manifest.sketch_events import validate_sketch_event_page
+
+
+class AppsError(Exception):
+    """Raised for failures talking to the app management API."""
+
+
+def _headers(token: str) -> dict[str, str]:
+    return {"Authorization": f"Bearer {token}"}
+
+
+def _request(api_url: str, token: str, method: str, path: str, client=None, *, extra_headers=None, params=None, json_body=None, raw=False) -> Any:
+    owns = client is None
+    http = client or httpx.Client(timeout=10)
+    try:
+        headers = {**_headers(token), **(extra_headers or {})}
+        request_kwargs = {}
+        if params is not None:
+            request_kwargs["params"] = params
+        if json_body is not None:
+            request_kwargs["json"] = json_body
+        response = http.request(method, f"{api_url}{path}", headers=headers, **request_kwargs)
+        response.raise_for_status()
+        return response.text if raw else (response.json() if response.content else None)
+    except httpx.HTTPStatusError as exc:
+        detail = exc.response.text
+        try:
+            detail = exc.response.json().get("detail", detail)
+            if isinstance(detail, dict):
+                code = detail.get("code")
+                code_text = str(code) if code is not None else ""
+                message = {
+                    "insufficient_wallet_funds": "Not enough wallet funds. Top up your wallet, then run this command again.",
+                    "spend_cap_exceeded": "This would exceed your spending limit. Ask the account owner to raise the limit, then try again.",
+                    "spend_cap_required": "Set a monthly spending limit before activating Live.",
+                    "live_activation_disabled": "Live activation is not enabled yet. Contact Verulla support.",
+                }.get(code_text, detail.get("message") or str(detail))
+                detail = f"{message} (code: {code_text})" if code_text else message
+            else:
+                detail = str(detail)
+        except (ValueError, AttributeError):
+            pass
+        raise AppsError(f"request failed ({exc.response.status_code}): {detail}") from exc
+    except httpx.HTTPError as exc:
+        raise AppsError(f"could not reach {api_url}: {exc}") from exc
+    finally:
+        if owns:
+            http.close()
+
+
+def list_apps(api_url: str, token: str, client=None) -> list[dict]:
+    return _request(api_url, token, "GET", "/v1/apps", client)["apps"]
+
+
+def get_app(api_url: str, token: str, name: str, client=None) -> dict:
+    return _request(api_url, token, "GET", f"/v1/apps/{name}", client)
+
+
+def get_sketch_events(api_url: str, token: str, name: str, *, cursor: str | None = None,
+                      limit: int = 100, client=None) -> dict:
+    from urllib.parse import quote
+    params: dict[str, str | int] = {"limit": limit}
+    if cursor is not None:
+        params["cursor"] = cursor
+    response = _request(api_url, token, "GET", f"/v1/apps/{quote(name, safe='')}/events", client, params=params)
+    try:
+        return validate_sketch_event_page(response)
+    except ValueError as exc:
+        raise AppsError(f"invalid Sketch event response: {exc}") from exc
+
+def get_sketch_status(api_url: str, token: str, name: str, client=None) -> dict:
+    from urllib.parse import quote
+    return _request(api_url, token, "GET", f"/v1/apps/{quote(name, safe='')}/sketch", client)
+
+
+def issue_owner_claim(api_url: str, token: str, owner_email: str, idempotency_key: str, client=None) -> dict:
+    try:
+        return _request(api_url, token, "POST", "/v1/owner-claims", client,
+                        extra_headers={"Idempotency-Key": idempotency_key},
+                        json_body={"owner_email": owner_email})
+    except AppsError:
+        # Never let an API error echo the supplied owner email into the CLI.
+        raise AppsError("Owner claim request failed; verify authorization and try again.") from None
+
+
+def get_owner_claim_status(api_url: str, token: str, client=None) -> dict:
+    return _request(api_url, token, "GET", "/v1/owner-claims/current", client)
+
+
+def activate_app(api_url: str, token: str, name: str, idempotency_key: str, client=None) -> dict:
+    return _request(api_url, token, "POST", f"/v1/apps/{name}/activate", client,
+                    extra_headers={"Idempotency-Key": idempotency_key})
+
+
+def get_spend_summary(api_url: str, token: str, client=None) -> dict:
+    return _request(api_url, token, "GET", "/v1/wallet/spend", client)
+
+
+def get_wallet_summary(api_url: str, token: str, client=None) -> dict:
+    return _request(api_url, token, "GET", "/v1/wallet", client)
+
+
+def get_usage_summary(api_url: str, token: str, client=None, *, month: str | None = None) -> dict:
+    params = {"month": month} if month is not None else None
+    return _request(api_url, token, "GET", "/v1/usage", client, params=params)
+
+
+def get_term_usage(api_url: str, token: str, client=None, *, app: str | None = None) -> dict:
+    params = {"app": app} if app is not None else None
+    return _request(api_url, token, "GET", "/v1/usage/term", client, params=params)
+
+
+def get_pricing(api_url: str, token: str, client=None) -> dict:
+    return _request(api_url, token, "GET", "/pricing.json", client)
+
+
+def create_topup(api_url: str, token: str, amount_cents: int, currency: str = "USD", client=None) -> dict:
+    return _request(api_url, token, "POST", "/v1/wallet/topups", client,
+                    json_body={"amount_cents": amount_cents, "currency": currency})
+
+
+def get_app_logs(api_url: str, token: str, name: str, client=None) -> dict:
+    return _request(api_url, token, "GET", f"/v1/apps/{name}/logs", client)
+
+
+def delete_app(api_url: str, token: str, name: str, client=None) -> dict:
+    return _request(api_url, token, "DELETE", f"/v1/apps/{name}", client)
+
+
+def get_auth_policy(api_url: str, token: str, app: str, client=None) -> dict:
+    from urllib.parse import quote
+    return _request(api_url, token, "GET", f"/v1/apps/{quote(app, safe='')}/auth", client)
+
+
+def set_auth_policy(api_url: str, token: str, app: str, version: int, policy: dict, client=None) -> dict:
+    from urllib.parse import quote
+    return _request(api_url, token, "PUT", f"/v1/apps/{quote(app, safe='')}/auth", client,
+                    params={"version": version}, json_body={"policy": policy})
+
+
+def list_customers(api_url: str, token: str, app: str, client=None, *, search: str | None = None,
+                   limit: int = 50, offset: int = 0) -> dict:
+    from urllib.parse import quote
+    params: dict[str, int | str] = {"limit": limit, "offset": offset}
+    if search is not None:
+        params["q"] = search
+    return _request(api_url, token, "GET", f"/v1/apps/{quote(app, safe='')}/customers", client, params=params)
+
+
+def lock_customer(api_url: str, token: str, app: str, customer_id: str, client=None) -> dict:
+    from urllib.parse import quote
+    return _request(api_url, token, "POST", f"/v1/apps/{quote(app, safe='')}/customers/{quote(customer_id, safe='')}/lock", client)
+
+
+def unlock_customer(api_url: str, token: str, app: str, customer_id: str, client=None) -> dict:
+    from urllib.parse import quote
+    return _request(api_url, token, "POST", f"/v1/apps/{quote(app, safe='')}/customers/{quote(customer_id, safe='')}/unlock", client)
+
+
+def delete_customer(api_url: str, token: str, app: str, customer_id: str, client=None) -> dict | None:
+    from urllib.parse import quote
+    return _request(api_url, token, "DELETE", f"/v1/apps/{quote(app, safe='')}/customers/{quote(customer_id, safe='')}", client)
+
+
+def invite_customer(api_url: str, token: str, app: str, email: str, client=None) -> dict:
+    from urllib.parse import quote
+    return _request(api_url, token, "POST", f"/v1/apps/{quote(app, safe='')}/customers", client,
+                    json_body={"email": email})
+
+
+def rollback_app(api_url: str, token: str, name: str, client=None) -> dict:
+    return _request(api_url, token, "POST", f"/v1/apps/{name}/rollback", client)
+
+
+def export_customers(api_url: str, token: str, app: str, client=None) -> str:
+    from urllib.parse import quote
+    return _request(api_url, token, "GET", f"/v1/apps/{quote(app, safe='')}/customers/export", client, raw=True)

verulla_cli/auth.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import json
+import os
+import stat
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Optional
+
+import httpx
+
+CREDENTIALS_PATH = Path.home() / ".verulla" / "credentials.json"
+DEFAULT_SCOPES = ["openid", "profile", "email"]
+
+
+class DeviceLoginError(Exception):
+    """Raised for any failure during the device authorization login flow."""
+
+
+def fetch_auth_config(api_url: str, http_client: httpx.Client) -> dict:
+    try:
+        response = http_client.get(f"{api_url}/v1/auth/config")
+        response.raise_for_status()
+    except httpx.HTTPError as exc:
+        raise DeviceLoginError(f"could not reach {api_url}: {exc}") from exc
+    return response.json()
+
+
+def start_device_authorization(
+    device_authorization_endpoint: str,
+    client_id: str,
+    scopes: list[str],
+    http_client: httpx.Client,
+) -> dict:
+    try:
+        response = http_client.post(
+            device_authorization_endpoint,
+            data={"client_id": client_id, "scope": " ".join(scopes)},
+        )
+        response.raise_for_status()
+    except httpx.HTTPError as exc:
+        raise DeviceLoginError(f"device authorization request failed: {exc}") from exc
+    return response.json()
+
+
+_MAX_POLL_FAILURES = 5  # consecutive network/non-JSON failures before giving up
+_MAX_BACKOFF_SECONDS = 60
+
+
+def poll_for_token(
+    token_endpoint: str,
+    client_id: str,
+    device_code: str,
+    interval: int,
+    expires_in: int,
+    http_client: httpx.Client,
+    sleep_fn=time.sleep,
+) -> dict:
+    """Poll the token endpoint per RFC 8628 §3.5 until success, denial, or timeout.
+
+    Transient transport errors and non-JSON replies (e.g. a gateway 502 page) are
+    retried with exponential backoff; after ``_MAX_POLL_FAILURES`` consecutive
+    failures the login is abandoned with a clear error. Any valid reply from the
+    IdP (including ``authorization_pending``) resets the failure budget.
+    """
+    elapsed = 0
+    failures = 0
+    while elapsed < expires_in:
+        sleep_fn(interval)
+        elapsed += interval
+        try:
+            response = http_client.post(
+                token_endpoint,
+                data={
+                    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                    "device_code": device_code,
+                    "client_id": client_id,
+                },
+            )
+            body = response.json()
+            if not isinstance(body, dict):
+                raise ValueError("token endpoint returned a non-object reply")
+        except (httpx.HTTPError, ValueError) as exc:
+            failures += 1
+            if failures >= _MAX_POLL_FAILURES:
+                raise DeviceLoginError(
+                    f"could not reach the token endpoint after {failures} attempts "
+                    f"(network or invalid reply): {exc}"
+                ) from exc
+            backoff = min(2**failures, _MAX_BACKOFF_SECONDS)
+            sleep_fn(backoff)
+            elapsed += backoff
+            continue
+        failures = 0
+        if response.status_code == 200 and "access_token" in body:
+            return body
+        error = body.get("error")
+        if error == "authorization_pending":
+            continue
+        if error == "slow_down":
+            interval += 5
+            continue
+        if error == "expired_token":
+            raise DeviceLoginError("device code expired — run `verulla login` again")
+        raise DeviceLoginError(f"device authorization failed: {error or body}")
+    raise DeviceLoginError("device authorization timed out")
+
+
+def save_credentials(
+    token_response: dict, issuer: str, client_id: str, path: Path = CREDENTIALS_PATH,
+) -> None:
+    """Persist tokens atomically with 0600 permissions — never world/group readable.
+
+    Written to a private (0600, O_EXCL) temp file in the same directory, fsynced,
+    then renamed over the target, so an interrupted write leaves the old file
+    intact and a pre-existing permissive file is replaced by a 0600 one.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = {
+        "issuer": issuer,
+        "client_id": client_id,
+        "access_token": token_response.get("access_token"),
+        "id_token": token_response.get("id_token"),
+        "refresh_token": token_response.get("refresh_token"),
+        "token_type": token_response.get("token_type", "Bearer"),
+    }
+    expires_in = token_response.get("expires_in")
+    if isinstance(expires_in, (int, float)) and not isinstance(expires_in, bool):
+        data["expires_at"] = time.time() + expires_in
+    try:
+        previous = stat.S_IMODE(path.stat().st_mode)
+    except FileNotFoundError:
+        previous = None
+    fd, tmp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(data, f)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp_name, path)
+    except BaseException:
+        try:
+            os.unlink(tmp_name)
+        except FileNotFoundError:
+            pass
+        raise
+    if previous is not None and previous & 0o077:
+        print(
+            f"warning: {path} had loose permissions ({previous:04o}); tightened to 0600",
+            file=sys.stderr,
+        )
+
+
+def load_credentials(path: Path = CREDENTIALS_PATH) -> Optional[dict]:
+    """Load credentials from the credentials file, if it exists.
+
+    Returns None if the file does not exist (not an error — the caller may
+    be using VERULLA_TOKEN env var instead). A corrupt file raises
+    DeviceLoginError telling the user to log in again.
+    """
+    if not path.is_file():
+        return None
+    try:
+        with path.open() as f:
+            creds = json.load(f)
+    except (OSError, ValueError) as exc:
+        raise DeviceLoginError(
+            f"credentials file {path} is unreadable or corrupt ({exc}) — run `verulla login` again"
+        ) from exc
+    if not isinstance(creds, dict) or not creds.get("access_token"):
+        raise DeviceLoginError(
+            f"credentials file {path} is corrupt (no access token) — run `verulla login` again"
+        )
+    return creds
+
+
+def get_token() -> str:
+    """Get an authentication token, preferring VERULLA_TOKEN env var,
+    falling back to the stored credentials file.
+
+    Stored credentials past their recorded expiry are rejected with a clear
+    re-login message (the CLI does not refresh tokens itself).
+    """
+    token = os.environ.get("VERULLA_TOKEN")
+    if token:
+        return token
+    creds = load_credentials(CREDENTIALS_PATH)
+    if creds is None:
+        raise DeviceLoginError("not authenticated — run `verulla login` first or set VERULLA_TOKEN")
+    expires_at = creds.get("expires_at")
+    if isinstance(expires_at, (int, float)) and time.time() >= expires_at:
+        raise DeviceLoginError("stored credentials have expired — run `verulla login` again")
+    return creds["access_token"]
+
+
+def run_device_login(
+    api_url: str,
+    http_client: httpx.Client | None = None,
+    sleep_fn=time.sleep,
+    credentials_path: Path = CREDENTIALS_PATH,
+) -> dict:
+    """Orchestrate the full device authorization grant and persist credentials.
+
+    Returns the token response dict.
+    """
+    owns_client = http_client is None
+    client = http_client or httpx.Client(timeout=10)
+    try:
+        config = fetch_auth_config(api_url, client)
+        device = start_device_authorization(
+            config["device_authorization_endpoint"],
+            config["client_id"],
+            config.get("scopes", DEFAULT_SCOPES),
+            client,
+        )
+        verification = device.get("verification_uri_complete") or device.get("verification_uri")
+        print(f"To continue, open: {verification}")
+        if "verification_uri_complete" not in device:
+            print(f"And enter code: {device['user_code']}")
+        token = poll_for_token(
+            config["token_endpoint"],
+            config["client_id"],
+            device["device_code"],
+            device.get("interval", 5),
+            device.get("expires_in", 600),
+            client,
+            sleep_fn=sleep_fn,
+        )
+        save_credentials(token, config["issuer"], config["client_id"], path=credentials_path)
+        return token
+    finally:
+        if owns_client:
+            client.close()

verulla_cli/buildkit.py

@@ -0,0 +1,107 @@
+"""BuildKit backend for local `verulla dev` builds."""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import shlex
+import uuid
+from pathlib import Path
+
+from verulla_cli.emulate import EmulationError
+
+
+BUILDKIT_BUILD_TIMEOUT_SECONDS = 600
+
+
+def select_builder(requested: str, docker_available: bool) -> str:
+    if requested == "docker":
+        if not docker_available:
+            raise EmulationError("Docker requested but unavailable; set BUILDKIT_HOST or choose --builder buildkit")
+        return "docker"
+    if requested == "buildkit":
+        if not os.environ.get("BUILDKIT_HOST"):
+            raise EmulationError("BuildKit requested but BUILDKIT_HOST is not set")
+        return "buildkit"
+    if docker_available:
+        return "docker"
+    if os.environ.get("BUILDKIT_HOST"):
+        return "buildkit"
+    raise EmulationError("No builder available: choose --builder docker|buildkit, start Docker, or set BUILDKIT_HOST")
+
+
+class BuildKitRunner:
+    def __init__(self, address: str | None = None):
+        self.address = address or os.environ.get("BUILDKIT_HOST")
+        if not self.address:
+            raise EmulationError("BUILDKIT_HOST is not set")
+        if shutil.which("buildctl") is None:
+            raise EmulationError("buildctl not found on PATH (required with BUILDKIT_HOST)")
+
+    def build(self, context_dir: Path, dockerfile_name: str, *, check: bool = False, dockerfile_dir: Path | None = None) -> str:
+        command = [
+            "buildctl", "--addr", self.address, "build", "--frontend", "dockerfile.v0",
+            "--local", f"context={context_dir}", "--local", f"dockerfile={dockerfile_dir or context_dir}",
+            "--opt", f"filename={dockerfile_name}",
+        ]
+        tls_dir = os.environ.get("BUILDKIT_TLS_DIR", "/run/buildkit-client")
+        tls_servername = os.environ.get("BUILDKIT_TLS_SERVERNAME", "buildkitd.tools.svc.cluster.local")
+        if Path(tls_dir, "ca.crt").exists():
+            command += ["--tlsdir", tls_dir]
+        if tls_servername:
+            command += ["--tlsservername", tls_servername]
+        if check:
+            command += ["--no-cache", "--output", "type=oci,dest=/dev/null", "--progress=plain"]
+        try:
+            result = subprocess.run(
+                command,
+                text=True,
+                capture_output=True,
+                check=False,
+                timeout=BUILDKIT_BUILD_TIMEOUT_SECONDS,
+            )
+        except subprocess.TimeoutExpired:
+            raise EmulationError(
+                f"BuildKit build timed out after {BUILDKIT_BUILD_TIMEOUT_SECONDS} seconds"
+            ) from None
+        except OSError as exc:
+            raise EmulationError(f"could not execute buildctl: {exc}") from exc
+        output = result.stdout + result.stderr
+        if result.returncode and not check:
+            raise EmulationError(f"BuildKit build failed (exit {result.returncode}): {output.strip()}")
+        return output
+
+
+def check_dockerfile(function, routes, output_dir: Path | None = None) -> str:
+    """Create a BuildKit-only check Dockerfile which starts the app and probes routes."""
+    plan = function.build_plan
+    original = plan.dockerfile_path or ".verulla.Dockerfile"
+    source_path = (output_dir / original) if output_dir and (output_dir / original).is_file() else (function.src_root / original)
+    source = source_path.read_text()
+    run_cmd = plan.run_cmd
+    if run_cmd:
+        start = shlex.join(run_cmd)
+        starter = f"({start}) >/tmp/verulla-app.log 2>&1 &"
+    else:
+        starter = "(/docker-entrypoint.sh nginx -g 'daemon off;') >/tmp/verulla-app.log 2>&1 &"
+    paths = [route.path for route in routes if route.function == function.name]
+    probe = "\n".join(
+        f"code=$(wget -S -O /dev/null http://127.0.0.1:{plan.port}{shlex.quote(path)} 2>&1 | awk '{{for (i=1;i<=NF;i++) if ($i ~ /^HTTP\\//) c=$(i+1)}} END {{print c+0}}'); echo ROUTE {shlex.quote(path)} $code; test $code -ge 200 -a $code -lt 400"
+        for path in paths
+    )
+    script = f"# check-{uuid.uuid4().hex}\n{starter}\nfor i in $(seq 1 60); do wget -q -O /dev/null http://127.0.0.1:{plan.port}/ && break; sleep 1; done\n{probe}\n"
+    output_dir = output_dir or function.src_root
+    output_dir.mkdir(parents=True, exist_ok=True)
+    check_name = ".verulla.Check.Dockerfile"
+    # Python and Node slim images lack wget; install the probe dependency only
+    # in this disposable check image (the nginx static image already has it).
+    probe_setup = (
+        "USER root\n"
+        "RUN apt-get update && apt-get install -y --no-install-recommends wget && rm -rf /var/lib/apt/lists/*\n"
+        "USER 10001:10001\n"
+        if (plan.base_image or "").startswith(("python:", "node:"))
+        else ""
+    )
+    (output_dir / check_name).write_text(source + "\n" + probe_setup + "RUN --network=none " + json.dumps(["/bin/sh", "-c", script]) + "\n")
+    return check_name

verulla_cli/deploy_client.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import httpx
+
+
+class DeployError(Exception):
+    """Raised for any failure talking to the control plane's /v1/deployments API."""
+
+
+def _error_detail(exc: httpx.HTTPStatusError) -> str:
+    try:
+        body = exc.response.json()
+    except ValueError:
+        return str(exc)
+    if isinstance(body, dict) and body.get("detail"):
+        return str(body["detail"])
+    return str(exc)
+
+
+def create_deployment(
+    api_url: str,
+    access_token: str,
+    tarball: bytes,
+    http_client: httpx.Client | None = None,
+) -> dict:
+    """Upload a gzip source tarball and return the created deployment record."""
+    owns_client = http_client is None
+    client = http_client or httpx.Client(timeout=120)
+    try:
+        response = client.post(
+            f"{api_url}/v1/deployments",
+            content=tarball,
+            headers={
+                "Authorization": f"Bearer {access_token}",
+                "Content-Type": "application/gzip",
+            },
+        )
+        response.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        status = exc.response.status_code
+        raise DeployError(f"deploy failed ({status}): {_error_detail(exc)}") from exc
+    except httpx.HTTPError as exc:
+        raise DeployError(f"could not reach {api_url}: {exc}") from exc
+    finally:
+        if owns_client:
+            client.close()
+    return response.json()