sovaria-cli 0.2.0__tar.gz

sovaria_cli-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install SDK + CLI
+        run: |
+          set -euo pipefail
+          if [ -f ../sovaria-sdk/apps/sdk/python/pyproject.toml ]; then
+            pip install -e ../sovaria-sdk/apps/sdk/python
+          elif [ -f sovaria-sdk/apps/sdk/python/pyproject.toml ]; then
+            pip install -e sovaria-sdk/apps/sdk/python
+          else
+            pip install "sovaria-sdk>=0.2.0"
+          fi
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest apps/cli/tests -q
+
+      - name: Build wheel
+        run: python -m build
+
+      - name: Validate wheel metadata
+        run: python -m twine check dist/*

sovaria_cli-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish CLI
+
+on:
+  workflow_dispatch:
+    inputs:
+      confirm:
+        description: 'Type "publish" to upload sovaria-cli to PyPI'
+        required: true
+
+jobs:
+  publish:
+    if: github.event.inputs.confirm == 'publish'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build wheel
+        run: |
+          pip install build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

sovaria_cli-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+.venv/
+.ruff_cache/
+.mypy_cache/
+dist/
+*.egg-info/

sovaria_cli-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12.11

sovaria_cli-0.2.0/Makefile

@@ -0,0 +1,44 @@
+.PHONY: help install test lint format run smoke clean build publish-check
+
+PYTHON ?= python3
+PIP ?= pip
+SDK_ROOT ?= ../sovaria-sdk
+
+BLUE := \033[0;34m
+GREEN := \033[0;32m
+NC := \033[0m
+
+help: ## Show this help message
+	@echo '$(BLUE)Sovaria CLI - Available Commands:$(NC)'
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[0;32m%-20s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install CLI in editable mode with local SDK
+	@if [ -d "$(SDK_ROOT)/apps/sdk/python" ]; then \
+		$(PIP) install -e "$(SDK_ROOT)/apps/sdk/python"; \
+	fi
+	$(PIP) install -e ".[dev]"
+
+test: ## Run CLI tests
+	$(PYTHON) -m pytest apps/cli/tests
+
+lint: ## Run Python linters for CLI
+	@ruff check apps/cli || true
+
+format: ## Format CLI Python code
+	@ruff format apps/cli
+
+run: ## Show CLI help
+	@$(PYTHON) -m apps.cli.src.main --help
+
+smoke: ## Run CLI/SDK happy path smoke test
+	@bash scripts/cli_sdk_happy_path.sh
+
+build: ## Build installable wheel
+	$(PYTHON) -m build
+
+publish-check: build ## Validate wheel metadata before PyPI upload
+	$(PYTHON) -m twine check dist/*
+
+clean: ## Remove local generated Python artifacts
+	@find . -type d \( -name "__pycache__" -o -name ".pytest_cache" -o -name ".ruff_cache" -o -name "dist" -o -name "build" -o -name "*.egg-info" \) -prune -exec rm -rf {} +
+	@echo '$(GREEN)✓ Cleaned CLI repo$(NC)'

sovaria_cli-0.2.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.5
+Name: sovaria-cli
+Version: 0.2.0
+Summary: Sovaria BaaS command-line interface (sov)
+Project-URL: Homepage, https://sovaria.in
+Project-URL: Documentation, https://docs.sovaria.in/cli
+Project-URL: Repository, https://github.com/sovaria/sovaria-cli
+Author: Sovaria Team
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: keyring>=25.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: sovaria-sdk>=0.2.0
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: typer>=0.17.4
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Sovaria CLI
+
+Operator CLI for gateway-backed Sovaria project and platform workflows.
+
+## Run
+
+Examples below use `sov ...` command syntax.
+
+If `sov` is installed on your PATH:
+
+```bash
+sov --help
+```
+
+From repo root without installation:
+
+```bash
+python -m apps.cli.src.main --help
+```
+
+## Cross-SDK Happy Path Smoke
+
+Use the repository smoke script to validate one shared happy path across:
+
+- CLI auth + scoped SQL call
+- TypeScript SDK SQL + engine health
+- Python SDK SQL + engine health
+
+```bash
+SOVARIA_URL=http://localhost:8000 \
+SOVARIA_ORG_ID=<org_uuid> \
+SOVARIA_PROJECT_ID=<project_uuid> \
+SOVARIA_EMAIL=<owner_email> \
+SOVARIA_PASSWORD='<owner_password>' \
+scripts/cli_sdk_happy_path.sh
+```
+
+If you already have valid CLI tokens, omit `SOVARIA_EMAIL` and `SOVARIA_PASSWORD`.
+
+## Core Command Groups
+
+- `sov auth ...` auth login/logout
+- `sov scope ...` default org/project/env scope
+- `sov data ...` Atlas-Doc and Atlas-Rel
+- `sov realtime ...` Pulse realtime and e2ee
+- `sov policy ...` Guard policy management
+- `sov audit ...` Echo audit and simulation
+- `sov chrono ...` Chrono timeline/snapshot operations
+- `sov fn ...` Forge function deploy/status/invoke
+- `sov project ...` project config template + scaffold creation
+- `sov api call ...` raw gateway API request
+
+## Project Bootstrap (Config JSON)
+
+Create a template config file:
+
+```bash
+sov project init-config my-app --output sovaria.config.json
+```
+
+Then scaffold a project from that config:
+
+```bash
+sov project create --config sovaria.config.json --dir .
+```
+
+## Function Sandbox Flow
+
+Deploy a function bundle (zipped from local folder):
+
+```bash
+sov fn deploy ./my-function --name hello --project <project_id> --note "add audit logging"
+```
+
+Poll deployment status:
+
+```bash
+sov fn status <deploy_id> --project <project_id>
+```
+
+Invoke the deployed function in its project sandbox:
+
+```bash
+sov fn invoke hello --project <project_id> --data '{"message":"hi"}'
+```
+
+Run a simulation invocation (tracked separately from normal invoke):
+
+```bash
+sov fn invoke hello --project <project_id> --simulate --data '{"message":"dry-run"}'
+```
+
+Queue heavy async invocation and wait for completion:
+
+```bash
+sov fn invoke hello --project <project_id> --execution-profile heavy --async --wait --data-file payload.json
+```
+
+List function versions:
+
+```bash
+sov fn versions hello --project <project_id>
+```
+
+List functions with active versions + queue depth:
+
+```bash
+sov fn functions --project <project_id>
+```
+
+List invocation history:
+
+```bash
+sov fn history hello --project <project_id> --mode invoke
+```
+
+List durable async jobs:
+
+```bash
+sov fn jobs hello --project <project_id> --status QUEUED
+```
+
+Promote a specific function version:
+
+```bash
+sov fn promote hello --project <project_id> --version 3 --reason "promote stable release"
+```
+
+Rollback to previous active version:
+
+```bash
+sov fn rollback hello --project <project_id> --reason "rollback regression"
+```
+
+Diff two simulation invocations:
+
+```bash
+sov fn sim-diff hello <left_invocation_id> <right_invocation_id> --project <project_id>
+```
+
+## Scope Requirement
+
+Realtime and relational routes require org/project scope. You can pass scope per command (`--org --project --env`) or set defaults:
+
+```bash
+sov scope set <org_id> <project_id> --env <env_id>
+```

sovaria_cli-0.2.0/apps/cli/README.md

@@ -0,0 +1,147 @@
+# Sovaria CLI
+
+Operator CLI for gateway-backed Sovaria project and platform workflows.
+
+## Run
+
+Examples below use `sov ...` command syntax.
+
+If `sov` is installed on your PATH:
+
+```bash
+sov --help
+```
+
+From repo root without installation:
+
+```bash
+python -m apps.cli.src.main --help
+```
+
+## Cross-SDK Happy Path Smoke
+
+Use the repository smoke script to validate one shared happy path across:
+
+- CLI auth + scoped SQL call
+- TypeScript SDK SQL + engine health
+- Python SDK SQL + engine health
+
+```bash
+SOVARIA_URL=http://localhost:8000 \
+SOVARIA_ORG_ID=<org_uuid> \
+SOVARIA_PROJECT_ID=<project_uuid> \
+SOVARIA_EMAIL=<owner_email> \
+SOVARIA_PASSWORD='<owner_password>' \
+scripts/cli_sdk_happy_path.sh
+```
+
+If you already have valid CLI tokens, omit `SOVARIA_EMAIL` and `SOVARIA_PASSWORD`.
+
+## Core Command Groups
+
+- `sov auth ...` auth login/logout
+- `sov scope ...` default org/project/env scope
+- `sov data ...` Atlas-Doc and Atlas-Rel
+- `sov realtime ...` Pulse realtime and e2ee
+- `sov policy ...` Guard policy management
+- `sov audit ...` Echo audit and simulation
+- `sov chrono ...` Chrono timeline/snapshot operations
+- `sov fn ...` Forge function deploy/status/invoke
+- `sov project ...` project config template + scaffold creation
+- `sov api call ...` raw gateway API request
+
+## Project Bootstrap (Config JSON)
+
+Create a template config file:
+
+```bash
+sov project init-config my-app --output sovaria.config.json
+```
+
+Then scaffold a project from that config:
+
+```bash
+sov project create --config sovaria.config.json --dir .
+```
+
+## Function Sandbox Flow
+
+Deploy a function bundle (zipped from local folder):
+
+```bash
+sov fn deploy ./my-function --name hello --project <project_id> --note "add audit logging"
+```
+
+Poll deployment status:
+
+```bash
+sov fn status <deploy_id> --project <project_id>
+```
+
+Invoke the deployed function in its project sandbox:
+
+```bash
+sov fn invoke hello --project <project_id> --data '{"message":"hi"}'
+```
+
+Run a simulation invocation (tracked separately from normal invoke):
+
+```bash
+sov fn invoke hello --project <project_id> --simulate --data '{"message":"dry-run"}'
+```
+
+Queue heavy async invocation and wait for completion:
+
+```bash
+sov fn invoke hello --project <project_id> --execution-profile heavy --async --wait --data-file payload.json
+```
+
+List function versions:
+
+```bash
+sov fn versions hello --project <project_id>
+```
+
+List functions with active versions + queue depth:
+
+```bash
+sov fn functions --project <project_id>
+```
+
+List invocation history:
+
+```bash
+sov fn history hello --project <project_id> --mode invoke
+```
+
+List durable async jobs:
+
+```bash
+sov fn jobs hello --project <project_id> --status QUEUED
+```
+
+Promote a specific function version:
+
+```bash
+sov fn promote hello --project <project_id> --version 3 --reason "promote stable release"
+```
+
+Rollback to previous active version:
+
+```bash
+sov fn rollback hello --project <project_id> --reason "rollback regression"
+```
+
+Diff two simulation invocations:
+
+```bash
+sov fn sim-diff hello <left_invocation_id> <right_invocation_id> --project <project_id>
+```
+
+## Scope Requirement
+
+Realtime and relational routes require org/project scope. You can pass scope per command (`--org --project --env`) or set defaults:
+
+```bash
+sov scope set <org_id> <project_id> --env <env_id>
+```

sovaria_cli-0.2.0/apps/cli/src/__init__.py

@@ -0,0 +1,3 @@
+"""Sovaria CLI — sov command."""
+
+__version__ = "0.2.0"

sovaria_cli-0.2.0/apps/cli/src/commands/__init__.py

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

sovaria_cli-0.2.0/apps/cli/src/commands/admin.py

@@ -0,0 +1,160 @@
+"""Platform admin commands (error traces, usage overview, transparency)."""
+
+from __future__ import annotations
+
+from urllib.parse import quote, urlencode
+
+import typer
+
+from apps.cli.src.utils.api_client import CLIRequestError, call_api
+from apps.cli.src.utils.display import print_json
+
+app = typer.Typer(help="Platform admin: error traces, usage, transparency")
+
+error_traces_app = typer.Typer(help="Error trace inspection and resolution")
+transparency_app = typer.Typer(help="Access transparency audit log")
+
+app.add_typer(error_traces_app, name="error-traces")
+app.add_typer(transparency_app, name="transparency")
+
+
+@error_traces_app.command("list")
+def error_traces_list(
+    service: str | None = typer.Option(None, "--service"),
+    project_id: str | None = typer.Option(None, "--project"),
+    error_class: str | None = typer.Option(None, "--error-class"),
+    severity: str | None = typer.Option(None, "--severity"),
+    resolved: bool | None = typer.Option(None, "--resolved/--unresolved"),
+    since: str | None = typer.Option(None, "--since", help="ISO-8601 lower bound"),
+    limit: int = typer.Option(50, "--limit", min=1, max=200),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """List recent platform error traces."""
+    params: dict[str, str] = {"limit": str(limit)}
+    if service:
+        params["service"] = service
+    if project_id:
+        params["project_id"] = project_id
+    if error_class:
+        params["error_class"] = error_class
+    if severity:
+        params["severity"] = severity
+    if resolved is not None:
+        params["resolved"] = str(resolved).lower()
+    if since:
+        params["since"] = since
+    try:
+        result = call_api(
+            method="GET",
+            path="/api/v1/error-traces",
+            profile=profile,
+            require_scope=False,
+            params=params,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    print_json(result)
+
+
+@error_traces_app.command("get")
+def error_traces_get(
+    trace_id: str = typer.Argument(..., help="Error trace ID"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Fetch one error trace with ordered hops."""
+    try:
+        result = call_api(
+            method="GET",
+            path=f"/api/v1/error-traces/{quote(trace_id, safe='')}",
+            profile=profile,
+            require_scope=False,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    print_json(result)
+
+
+@error_traces_app.command("resolve")
+def error_traces_resolve(
+    trace_id: str = typer.Argument(..., help="Error trace ID"),
+    resolved: bool = typer.Option(True, "--resolved/--unresolved"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Mark an error trace resolved or unresolved."""
+    try:
+        result = call_api(
+            method="PATCH",
+            path=f"/api/v1/error-traces/{quote(trace_id, safe='')}/resolved",
+            profile=profile,
+            require_scope=False,
+            body={"resolved": resolved},
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    print_json(result)
+
+
+@app.command("usage-overview")
+def usage_overview(
+    period: str | None = typer.Option(None, "--period", help="Billing period YYYY-MM"),
+    limit: int = typer.Option(100, "--limit", min=1, max=500),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Fetch cross-tenant usage overview (platform admin)."""
+    params: dict[str, str] = {}
+    if period:
+        params["period"] = period
+    if limit != 100:
+        params["limit"] = str(limit)
+    try:
+        result = call_api(
+            method="GET",
+            path="/api/v1/admin/usage/overview",
+            profile=profile,
+            require_scope=False,
+            params=params or None,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    print_json(result)
+
+
+@transparency_app.command("list")
+def transparency_list(
+    org_id: str = typer.Option(..., "--org", help="Organisation ID"),
+    project_id: str | None = typer.Option(None, "--project"),
+    event_type: str | None = typer.Option(None, "--event-type"),
+    since: str | None = typer.Option(None, "--since", help="ISO-8601 lower bound"),
+    limit: int = typer.Option(50, "--limit", min=1, max=200),
+    offset: int = typer.Option(0, "--offset", min=0),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """List tenant-visible staff access transparency events."""
+    query: dict[str, str] = {
+        "org_id": org_id,
+        "limit": str(limit),
+        "offset": str(offset),
+    }
+    if project_id:
+        query["project_id"] = project_id
+    if event_type:
+        query["event_type"] = event_type
+    if since:
+        query["since"] = since
+    path = f"/api/v1/access-transparency?{urlencode(query)}"
+    try:
+        result = call_api(
+            method="GET",
+            path=path,
+            profile=profile,
+            org_id=org_id,
+            require_scope=False,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    print_json(result)

sovaria_cli-0.2.0/apps/cli/src/commands/api.py

@@ -0,0 +1,48 @@
+"""Raw API passthrough commands."""
+
+from __future__ import annotations
+
+import typer
+
+from apps.cli.src.utils.api_client import CLIRequestError, call_api, parse_json_arg, print_json
+
+app = typer.Typer(help="Raw gateway API calls")
+
+
+@app.command("call")
+def call_command(
+    method: str = typer.Argument(..., help="HTTP method, e.g. GET/POST"),
+    path: str = typer.Argument(..., help="Gateway path, e.g. /api/v1/system/engines/health"),
+    body: str | None = typer.Option(None, "--body", help="JSON request body"),
+    query: str | None = typer.Option(None, "--query", help="JSON object query params"),
+    profile: str | None = typer.Option(None, "--profile"),
+    no_auth: bool = typer.Option(False, "--no-auth", help="Do not send Authorization header"),
+    require_scope: bool = typer.Option(False, "--require-scope"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+) -> None:
+    """Call any gateway endpoint directly."""
+    try:
+        parsed_body = parse_json_arg(body, label="--body")
+        parsed_query = parse_json_arg(query, label="--query")
+        if parsed_query is not None and not isinstance(parsed_query, dict):
+            raise CLIRequestError("--query must be a JSON object")
+
+        result = call_api(
+            method=method,
+            path=path,
+            profile=profile,
+            body=parsed_body,
+            params={str(k): str(v) for k, v in (parsed_query or {}).items()},
+            require_auth=not no_auth,
+            require_scope=require_scope,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(print_json(result))