sovaria-cli 0.2.0__py3-none-any.whl

apps/cli/src/main.py

@@ -0,0 +1,169 @@
+"""apps.cli.src.main — ``sov`` CLI entrypoint.
+
+The CLI is a platform tool for Sovaria customers on plans that unlock CLI
+access (``ultra`` and ``enterprise`` by default — see plan_service in axis).
+It authenticates against the platform console lane and never against
+project end-user credentials.
+
+Top-level commands cover the day-to-day operations a platform user runs:
+
+    sov auth sessions             List/revoke login sessions
+    sov auth mfa-enroll           Enroll TOTP MFA
+    sov fn logs|get|delete        Function logs and lifecycle
+    sov logout                    Revoke and clear local tokens
+    sov whoami                    Show current user
+    sov auth-product ...          Manage product users (project scope)
+    sov scope ...                 Manage default org/project/env scope
+    sov project ...               Scaffold + manage projects
+    sov init                      Interactive project bootstrap wizard
+    sov shell                     Interactive REPL (SQL, sim, keys, policy)
+    sov sim ...                   Simulation discover / runs / compare
+    sov keys ...                  Project API keys
+    sov iam ...                   Organisations, members, settings
+    sov org ...                   Organisation membership / create
+    sov db ...                    Atlas-Rel SQL operations
+    sov db tx begin|commit|rollback
+    sov db migrations push|pull|list
+    sov db column add|drop
+    sov db fk add|drop
+    sov data ...                  Atlas-Doc + Atlas-Rel data plane
+    sov storage ...               Vault buckets/objects
+    sov fn ...                    Forge function management
+    sov chrono ...                Timelines + snapshots
+    sov audit ...                 Echo audit trail + simulations
+    sov policy ...                Guard policy admin
+    sov realtime ...              Pulse channels + E2EE keys
+    sov api ...                   Raw gateway API call (escape hatch)
+"""
+
+import typer
+
+from apps.cli.src.commands import api as api_mod
+from apps.cli.src.commands import admin as admin_mod
+from apps.cli.src.commands import audit as audit_mod
+from apps.cli.src.commands import auth_product as auth_product_mod
+from apps.cli.src.commands import billing as billing_mod
+from apps.cli.src.commands import chrono as chrono_mod
+from apps.cli.src.commands import context as context_mod
+from apps.cli.src.commands import data as data_mod
+from apps.cli.src.commands import db as db_mod
+from apps.cli.src.commands import deploy as deploy_mod
+from apps.cli.src.commands import governance as governance_mod
+from apps.cli.src.commands import iam as iam_mod
+from apps.cli.src.commands import init_cmd as init_mod
+from apps.cli.src.commands import keys as keys_mod
+from apps.cli.src.commands import login as login_mod
+from apps.cli.src.commands import org as org_mod
+from apps.cli.src.commands import policy as policy_mod
+from apps.cli.src.commands import project as project_mod
+from apps.cli.src.commands import realtime as realtime_mod
+from apps.cli.src.commands import scope as scope_mod
+from apps.cli.src.commands import shell as shell_mod
+from apps.cli.src.commands import sim as sim_mod
+from apps.cli.src.commands import storage as storage_mod
+from apps.cli.src.commands import vector as vector_mod
+from apps.cli.src.utils.config import write_default_config
+
+app = typer.Typer(
+    name="sov",
+    help="Sovaria BaaS command-line interface",
+    add_completion=True,
+    pretty_exceptions_enable=False,  # let Python print raw tracebacks in dev
+)
+
+# ── Sub-app registration ──────────────────────────────────────────────────────
+app.add_typer(login_mod.app, name="auth", help="Authentication commands")
+app.add_typer(auth_product_mod.app, name="auth-product", help="Product auth admin commands")
+app.add_typer(context_mod.app, name="context", help="Context and identity commands")
+app.add_typer(scope_mod.app, name="scope", help="Manage default org/project/env scope")
+app.add_typer(project_mod.app, name="project", help="Project scaffold commands")
+app.add_typer(org_mod.app, name="org", help="Organisation management")
+app.add_typer(db_mod.app, name="db", help="Database (SQL) management")
+app.add_typer(data_mod.app, name="data", help="Atlas-Doc and Atlas-Rel data plane")
+app.add_typer(storage_mod.app, name="storage", help="Object storage management")
+app.add_typer(deploy_mod.app, name="fn", help="Cloud function management")
+app.add_typer(chrono_mod.app, name="chrono", help="Timeline and snapshot operations")
+app.add_typer(audit_mod.app, name="audit", help="Echo audit trail and simulations")
+app.add_typer(policy_mod.app, name="policy", help="Guard policy engine commands")
+app.add_typer(realtime_mod.app, name="realtime", help="Realtime stream and E2EE")
+app.add_typer(billing_mod.app, name="billing", help="Billing plans, subscriptions, and usage")
+app.add_typer(governance_mod.app, name="governance", help="Platform governance and tenant databases")
+app.add_typer(admin_mod.app, name="admin", help="Platform admin: error traces and usage")
+app.add_typer(vector_mod.app, name="vector", help="Vector embeddings and semantic search")
+app.add_typer(sim_mod.app, name="sim", help="Scenario discovery, runs, and comparisons")
+app.add_typer(keys_mod.app, name="keys", help="Project API keys")
+app.add_typer(iam_mod.app, name="iam", help="Organisations, members, and project settings")
+app.add_typer(api_mod.app, name="api", help="Raw gateway API calls")
+
+# Top-level interactive / bootstrap commands
+app.add_typer(init_mod.app, name="init", help="Interactive project bootstrap")
+app.add_typer(shell_mod.app, name="shell", help="Interactive Sovaria REPL")
+
+# Convenience top-level aliases for the most common verbs.
+app.command("login")(login_mod.login)
+app.command("logout")(login_mod.logout)
+app.command("whoami")(context_mod.whoami)
+app.command("context")(context_mod.context)
+app.command("deploy")(deploy_mod.deploy)
+
+
+# ── Version flag ──────────────────────────────────────────────────────────────
+def _version_callback(value: bool) -> None:
+    if value:
+        from apps.cli.src import __version__
+
+        typer.echo(f"sov version {__version__}")
+        raise typer.Exit()
+
+
+_PLAN_GATE_BYPASS_COMMANDS = frozenset(
+    {"login", "auth", "logout", "scope", "whoami", "context", "init", "project", None}
+)
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False, "--version", "-V", callback=_version_callback, is_eager=True
+    ),
+) -> None:
+    """Sovaria BaaS CLI — manage your identity graph, deploy functions, and more."""
+    # Ensure ~/.sovaria/config.yaml exists on first run
+    write_default_config()
+
+    invoked = ctx.invoked_subcommand
+    if invoked is None:
+        typer.echo(ctx.get_help())
+        return
+
+    # Plan-gate every command that actually talks to the API, except the
+    # auth-bootstrap commands themselves (you can't check your plan before
+    # you've logged in) and the version flag.
+    if invoked not in _PLAN_GATE_BYPASS_COMMANDS:
+        from apps.cli.src.utils.api_client import (
+            CLIPlanError,
+            CLIRequestError,
+            assert_cli_access,
+        )
+        from apps.cli.src.utils.auth_store import load_tokens
+
+        if load_tokens():
+            try:
+                assert_cli_access()
+            except CLIPlanError as exc:
+                typer.echo(typer.style(str(exc), fg=typer.colors.RED), err=True)
+                raise typer.Exit(2) from exc
+            except CLIRequestError:
+                # Network/auth errors are not fatal here — the actual command
+                # will surface a more actionable error if relevant.
+                pass
+
+
+def cli_entry() -> None:
+    """Console script entry point for the ``sov`` command."""
+    app()
+
+
+if __name__ == "__main__":
+    cli_entry()

apps/cli/src/utils/__init__.py

@@ -0,0 +1 @@
+"""CLI utilities package."""

apps/cli/src/utils/api_client.py

@@ -0,0 +1,329 @@
+"""Shared HTTP helpers for CLI commands."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from typing import Any
+
+import httpx
+
+from apps.cli.src.utils.auth_store import load_mfa_pending, load_tokens, save_tokens
+from apps.cli.src.utils.config import get_api_url, get_scope
+from apps.cli.src.utils.project_context import resolve_scope as resolve_project_scope
+
+_MUTATING_METHODS = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+_REFRESH_MARGIN_SECONDS = 60
+
+
+class CLIRequestError(RuntimeError):
+    """Raised when a CLI API request fails."""
+
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class CLIPlanError(CLIRequestError):
+    """Raised when the user's plan does not unlock CLI access."""
+
+
+class CLIMfaRequiredError(CLIRequestError):
+    """Raised when login returned a pre-MFA challenge instead of a full session."""
+
+
+def _plan_check_enabled() -> bool:
+    """Return True if the CLI should enforce plan-gating before commands run."""
+    return (os.getenv("SOV_DISABLE_PLAN_CHECK", "") or "").strip().lower() not in {
+        "1",
+        "true",
+        "yes",
+    }
+
+
+def assert_cli_access(profile: str | None = None) -> dict[str, Any]:
+    """Fetch /auth/me, return the response, and refuse if cli_access is False."""
+    me = call_api(method="GET", path="/api/v1/auth/me", profile=profile, _skip_plan_check=True)
+    if not isinstance(me, dict):
+        return {}
+    if not _plan_check_enabled():
+        return me
+    plan = str(me.get("plan") or "").strip().lower() or "free"
+    features = me.get("plan_features") or {}
+    if isinstance(features, dict) and not features.get("cli_access", False):
+        raise CLIPlanError(
+            f"Your '{plan}' plan does not include CLI access. "
+            "Upgrade to 'ultra' or 'enterprise' to use the Sovaria CLI: "
+            "https://sovaria.in/pricing"
+        )
+    return me
+
+
+def _resolve_scope(
+    *,
+    profile: str | None,
+    org_id: str | None,
+    project_id: str | None,
+    env_id: str | None,
+    require_scope: bool = False,
+) -> tuple[str, str, str]:
+    try:
+        return resolve_project_scope(
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require=require_scope,
+        )
+    except ValueError as exc:
+        raise CLIRequestError(str(exc)) from exc
+
+
+def _scope_headers(org_id: str, project_id: str, env_id: str) -> dict[str, str]:
+    headers: dict[str, str] = {}
+    if org_id:
+        headers["X-Sovaria-Org-ID"] = org_id
+    if project_id:
+        headers["X-Sovaria-Project-ID"] = project_id
+    if env_id:
+        headers["X-Sovaria-Env-ID"] = env_id
+    return headers
+
+
+def _token_needs_refresh(tokens: dict[str, Any]) -> bool:
+    refresh_token = str(tokens.get("refresh_token") or "").strip()
+    if not refresh_token:
+        return False
+    expires_at = tokens.get("expires_at")
+    if expires_at is None:
+        return False
+    try:
+        return time.time() >= float(expires_at) - _REFRESH_MARGIN_SECONDS
+    except (TypeError, ValueError):
+        return False
+
+
+def _refresh_access_token(profile: str | None) -> dict[str, Any]:
+    tokens = load_tokens(profile=profile) or {}
+    refresh_token = str(tokens.get("refresh_token") or "").strip()
+    if not refresh_token:
+        return tokens
+
+    api_url = get_api_url(profile).rstrip("/")
+    try:
+        response = httpx.post(
+            f"{api_url}/api/v1/auth/refresh",
+            json={"refresh_token": refresh_token},
+            timeout=15,
+        )
+        response.raise_for_status()
+    except httpx.HTTPError as exc:
+        raise CLIRequestError(
+            "Session expired and refresh failed. Run: sov auth login",
+            status_code=getattr(getattr(exc, "response", None), "status_code", None),
+        ) from exc
+
+    data = response.json()
+    access_token = str(data.get("access_token") or "").strip()
+    new_refresh = str(data.get("refresh_token") or refresh_token).strip()
+    expires_in = int(data.get("expires_in") or 3600)
+    if not access_token:
+        raise CLIRequestError("Refresh response did not include an access token")
+    save_tokens(access_token, new_refresh, profile=profile, expires_in=expires_in)
+    return load_tokens(profile=profile) or {}
+
+
+def _ensure_fresh_tokens(profile: str | None) -> dict[str, Any]:
+    tokens = load_tokens(profile=profile) or {}
+    if _token_needs_refresh(tokens):
+        tokens = _refresh_access_token(profile)
+    return tokens
+
+
+def _apply_login_response(data: dict[str, Any], *, profile: str | None) -> None:
+    if data.get("mfa_required"):
+        access_token = str(data.get("access_token") or "").strip()
+        if not access_token:
+            raise CLIRequestError("MFA required but gateway did not return a challenge token")
+        expires_in = int(data.get("expires_in") or 300)
+        from apps.cli.src.utils.auth_store import save_mfa_pending
+
+        save_mfa_pending(access_token, profile=profile, expires_in=expires_in)
+        raise CLIMfaRequiredError(
+            "Multi-factor authentication required. Complete login with: "
+            "sov auth mfa-verify --code <totp-or-backup-code>"
+        )
+
+    access_token = str(data.get("access_token") or "").strip()
+    refresh_token = str(data.get("refresh_token") or "").strip()
+    if not access_token or not refresh_token:
+        raise CLIRequestError("Login response did not include a full token pair")
+    expires_in = int(data.get("expires_in") or 3600)
+    save_tokens(access_token, refresh_token, profile=profile, expires_in=expires_in)
+
+
+def call_api(
+    *,
+    method: str,
+    path: str,
+    profile: str | None = None,
+    body: dict[str, Any] | list[Any] | None = None,
+    params: dict[str, str] | None = None,
+    require_auth: bool = True,
+    require_scope: bool = False,
+    org_id: str | None = None,
+    project_id: str | None = None,
+    env_id: str | None = None,
+    extra_headers: dict[str, str] | None = None,
+    timeout: float = 30.0,
+    _skip_plan_check: bool = False,
+    _allow_mfa_token: bool = False,
+) -> Any:
+    """Execute an API request against the configured gateway endpoint."""
+    normalized_method = method.upper()
+    url = get_api_url(profile).rstrip("/") + (path if path.startswith("/") else f"/{path}")
+    headers: dict[str, str] = {"Content-Type": "application/json"}
+
+    access_token = ""
+    if require_auth:
+        tokens = _ensure_fresh_tokens(profile)
+        access_token = str(tokens.get("access_token") or "").strip()
+        if not access_token:
+            pending = load_mfa_pending(profile=profile)
+            if pending and _allow_mfa_token:
+                access_token = str(pending.get("access_token") or "").strip()
+            if not access_token:
+                if pending:
+                    raise CLIMfaRequiredError(
+                        "MFA verification pending. Run: sov auth mfa-verify --code <totp>"
+                    )
+                raise CLIRequestError("Not logged in. Run: sov auth login")
+        headers["Authorization"] = f"Bearer {access_token}"
+
+    resolved_org, resolved_project, resolved_env = _resolve_scope(
+        profile=profile,
+        org_id=org_id,
+        project_id=project_id,
+        env_id=env_id,
+        require_scope=require_scope,
+    )
+    if require_scope and (not resolved_org or not resolved_project):
+        raise CLIRequestError(
+            "Missing required scope. Set org/project using --org/--project or: "
+            "sov scope set <org_id> <project_id>"
+        )
+    headers.update(_scope_headers(resolved_org, resolved_project, resolved_env))
+
+    if extra_headers:
+        headers.update(extra_headers)
+
+    if normalized_method in _MUTATING_METHODS and "Idempotency-Key" not in headers:
+        headers["Idempotency-Key"] = str(uuid.uuid4())
+
+    def _execute(auth_header: str | None = None) -> httpx.Response:
+        request_headers = dict(headers)
+        if auth_header is not None:
+            request_headers["Authorization"] = f"Bearer {auth_header}"
+        return httpx.request(
+            method=normalized_method,
+            url=url,
+            headers=request_headers,
+            json=body,
+            params=params,
+            timeout=timeout,
+        )
+
+    try:
+        response = _execute()
+        if response.status_code == 401 and require_auth and not _allow_mfa_token:
+            refreshed = _refresh_access_token(profile)
+            retry_token = str(refreshed.get("access_token") or "").strip()
+            if retry_token and retry_token != access_token:
+                response = _execute(retry_token)
+        response.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        detail: Any
+        try:
+            detail = exc.response.json()
+        except Exception:  # noqa: BLE001
+            detail = exc.response.text
+        raise CLIRequestError(
+            f"{normalized_method} {path} failed ({exc.response.status_code}): {detail}",
+            status_code=exc.response.status_code,
+        ) from exc
+    except httpx.RequestError as exc:
+        raise CLIRequestError(f"Network error while calling {path}: {exc}") from exc
+
+    if response.status_code == 204:
+        return {"status": "ok"}
+
+    content_type = (response.headers.get("content-type") or "").lower()
+    if "application/json" in content_type:
+        return response.json()
+
+    text = response.text.strip()
+    return {"text": text} if text else {"status": "ok"}
+
+
+def parse_json_arg(value: str | None, *, label: str) -> dict[str, Any] | list[Any] | None:
+    """Parse a JSON CLI argument and raise a readable error when invalid."""
+    if value is None:
+        return None
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise CLIRequestError(f"Invalid JSON for {label}: {exc}") from exc
+    if not isinstance(parsed, dict | list):
+        raise CLIRequestError(f"{label} must be a JSON object or array")
+    return parsed
+
+
+def print_json(payload: Any) -> str:
+    """Return pretty JSON text for terminal output."""
+    return json.dumps(payload, indent=2, sort_keys=True, default=str)
+
+
+def build_request_context(
+    *,
+    profile: str | None = None,
+    org_id: str | None = None,
+    project_id: str | None = None,
+    env_id: str | None = None,
+    require_scope: bool = False,
+    require_auth: bool = True,
+    extra_headers: dict[str, str] | None = None,
+) -> tuple[str, dict[str, str]]:
+    """Return (api_base_url, headers) for raw httpx calls with refresh + scope."""
+    api_url = get_api_url(profile).rstrip("/")
+    headers: dict[str, str] = {}
+
+    if require_auth:
+        tokens = _ensure_fresh_tokens(profile)
+        access_token = str(tokens.get("access_token") or "").strip()
+        if not access_token:
+            pending = load_mfa_pending(profile=profile)
+            if pending:
+                raise CLIMfaRequiredError(
+                    "MFA verification pending. Run: sov auth mfa-verify --code <totp>"
+                )
+            raise CLIRequestError("Not logged in. Run: sov auth login")
+        headers["Authorization"] = f"Bearer {access_token}"
+
+    resolved_org, resolved_project, resolved_env = _resolve_scope(
+        profile=profile,
+        org_id=org_id,
+        project_id=project_id,
+        env_id=env_id,
+        require_scope=require_scope,
+    )
+    if require_scope and (not resolved_org or not resolved_project):
+        raise CLIRequestError(
+            "Missing required scope. Set org/project using --org/--project or: "
+            "sov project link"
+        )
+    headers.update(_scope_headers(resolved_org, resolved_project, resolved_env))
+    if extra_headers:
+        headers.update(extra_headers)
+    return api_url, headers