sovaria-cli 0.2.0__py3-none-any.whl

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>
+```

apps/cli/src/__init__.py

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

apps/cli/src/commands/__init__.py

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

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)

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))

apps/cli/src/commands/audit.py

@@ -0,0 +1,181 @@
+"""Echo audit and simulation 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="Echo audit trail and simulation operations")
+
+
+@app.command("append")
+def append_audit(
+    event_type: str = typer.Option(..., "--event-type"),
+    actor_id: str = typer.Option(..., "--actor-id"),
+    source: str = typer.Option(..., "--source"),
+    action: str = typer.Option(..., "--action"),
+    resource_id: str | None = typer.Option(None, "--resource-id"),
+    metadata: str | None = typer.Option(None, "--metadata", help="JSON object"),
+    ip_address: str | None = typer.Option(None, "--ip-address"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Append an immutable audit entry."""
+    try:
+        parsed_metadata = parse_json_arg(metadata, label="--metadata") if metadata else {}
+        if parsed_metadata is not None and not isinstance(parsed_metadata, dict):
+            raise CLIRequestError("--metadata must be a JSON object")
+        result = call_api(
+            method="POST",
+            path="/api/v1/audit/",
+            profile=profile,
+            body={
+                "event_type": event_type,
+                "actor_id": actor_id,
+                "resource_id": resource_id,
+                "source": source,
+                "action": action,
+                "metadata": parsed_metadata or {},
+                "ip_address": ip_address,
+            },
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(print_json(result))
+
+
+@app.command("list")
+def list_audit(
+    actor_id: str | None = typer.Option(None, "--actor-id"),
+    event_type: str | None = typer.Option(None, "--event-type"),
+    source: str | None = typer.Option(None, "--source"),
+    resource_id: str | None = typer.Option(None, "--resource-id"),
+    limit: int = typer.Option(50, "--limit"),
+    offset: int = typer.Option(0, "--offset"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Query audit log entries."""
+    params = {
+        "limit": str(limit),
+        "offset": str(offset),
+    }
+    if actor_id:
+        params["actor_id"] = actor_id
+    if event_type:
+        params["event_type"] = event_type
+    if source:
+        params["source"] = source
+    if resource_id:
+        params["resource_id"] = resource_id
+
+    try:
+        result = call_api(
+            method="GET",
+            path="/api/v1/audit/",
+            profile=profile,
+            params=params,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(print_json(result))
+
+
+@app.command("verify")
+def verify_chain(profile: str | None = typer.Option(None, "--profile")) -> None:
+    """Verify audit hash-chain integrity."""
+    try:
+        result = call_api(method="GET", path="/api/v1/audit/verify", profile=profile)
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(print_json(result))
+
+
+@app.command("count")
+def audit_count(profile: str | None = typer.Option(None, "--profile")) -> None:
+    """Return audit log entry count."""
+    try:
+        result = call_api(method="GET", path="/api/v1/audit/count", profile=profile)
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(print_json(result))
+
+
+@app.command("sim-run")
+def sim_run(
+    simulation_name: str = typer.Argument(...),
+    operations: str = typer.Argument(..., help="JSON array operations"),
+    context: str | None = typer.Option(None, "--context", help="JSON object"),
+    include_execution_tree: bool = typer.Option(False, "--include-execution-tree"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Run an Echo phantom simulation."""
+    try:
+        parsed_ops = parse_json_arg(operations, label="operations")
+        if not isinstance(parsed_ops, list):
+            raise CLIRequestError("operations must be a JSON array")
+
+        parsed_context = parse_json_arg(context, label="--context") if context else {}
+        if parsed_context is not None and not isinstance(parsed_context, dict):
+            raise CLIRequestError("--context must be a JSON object")
+
+        result = call_api(
+            method="POST",
+            path="/api/v1/sim/run",
+            profile=profile,
+            body={
+                "simulation_name": simulation_name,
+                "operations": parsed_ops,
+                "echo_flag": True,
+                "include_execution_tree": include_execution_tree,
+                "context": parsed_context or {},
+            },
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(print_json(result))
+
+
+@app.command("sim-plan")
+def sim_plan(
+    simulation_name: str = typer.Argument(...),
+    operations: str = typer.Argument(..., help="JSON array operations"),
+    context: str | None = typer.Option(None, "--context", help="JSON object"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Preview an Echo simulation plan."""
+    try:
+        parsed_ops = parse_json_arg(operations, label="operations")
+        if not isinstance(parsed_ops, list):
+            raise CLIRequestError("operations must be a JSON array")
+
+        parsed_context = parse_json_arg(context, label="--context") if context else {}
+        if parsed_context is not None and not isinstance(parsed_context, dict):
+            raise CLIRequestError("--context must be a JSON object")
+
+        result = call_api(
+            method="POST",
+            path="/api/v1/sim/plan",
+            profile=profile,
+            body={
+                "simulation_name": simulation_name,
+                "operations": parsed_ops,
+                "echo_flag": True,
+                "include_execution_tree": True,
+                "context": parsed_context or {},
+            },
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(print_json(result))