general-augment-cli 0.1.0__py3-none-any.whl

platform_cli/commands/smoke.py

@@ -0,0 +1,280 @@
+"""Smoke-test app-facing General Augment endpoints."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+
+from platform_cli.client import resolve_project
+from platform_cli.output import panel, print_json, table
+from platform_cli.runtime import Runtime
+
+DEFAULT_SMOKE_MESSAGE = "Reply exactly with: genaug-smoke-ok"
+DEFAULT_STRUCTURED_MESSAGE = 'Return JSON with ok=true and label="genaug-smoke-ok".'
+DEFAULT_STRUCTURED_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "additionalProperties": False,
+    "properties": {
+        "ok": {"type": "boolean"},
+        "label": {"type": "string"},
+    },
+    "required": ["ok", "label"],
+}
+
+
+def smoke(
+    ctx: typer.Context,
+    message: Annotated[
+        str,
+        typer.Option("--message", "-m", help="Responses input for the smoke turn."),
+    ] = DEFAULT_SMOKE_MESSAGE,
+    user: Annotated[str, typer.Option(help="App user id for the smoke turn.")] = "genaug-smoke",
+    idempotency_key: Annotated[
+        str | None,
+        typer.Option(help="Replay-safe key for retry/debug checks."),
+    ] = None,
+    request_id: Annotated[
+        str | None,
+        typer.Option(help="Caller request id to propagate."),
+    ] = None,
+    traceparent: Annotated[
+        str | None,
+        typer.Option(help="W3C traceparent header to propagate."),
+    ] = None,
+    metadata: Annotated[
+        list[str] | None,
+        typer.Option("--metadata", help="Metadata as key=value. Repeatable."),
+    ] = None,
+    project: Annotated[
+        str | None,
+        typer.Option(help="Project id, slug, or name when using a management key."),
+    ] = None,
+    structured: Annotated[
+        bool,
+        typer.Option("--structured", help="Request a json_schema structured-output smoke."),
+    ] = False,
+    schema_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--schema-file",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+            help="JSON Schema file for --structured smoke output.",
+        ),
+    ] = None,
+    raw: Annotated[bool, typer.Option("--json", help="Print the raw response JSON.")] = False,
+) -> None:
+    """Run health plus one `/v1/responses` smoke request."""
+    runtime: Runtime = ctx.obj
+    turn_id = uuid.uuid4().hex[:12]
+    schema = _load_schema(schema_file) if schema_file else None
+    structured = structured or schema is not None
+    if structured and message == DEFAULT_SMOKE_MESSAGE:
+        message = DEFAULT_STRUCTURED_MESSAGE
+    headers = _correlation_headers(
+        idempotency_key=idempotency_key or f"genaug-smoke-{turn_id}",
+        request_id=request_id or f"req_genaug_smoke_{turn_id}",
+        traceparent=traceparent,
+    )
+    payload = {
+        "model": "balanced",
+        "user": user,
+        "input": message,
+        "metadata": {"source": "genaug-cli-smoke", **_metadata_pairs(metadata or [])},
+    }
+    if structured:
+        payload["text"] = _structured_text_format(schema or DEFAULT_STRUCTURED_SCHEMA)
+    project_payload: dict[str, Any] | None = None
+    with runtime.client() as client:
+        ready = client.public("GET", "/health/ready")
+        if project:
+            project_payload = resolve_project(client, project)
+            headers["X-Project-ID"] = str(project_payload["id"])
+        response = client.app("POST", "/v1/responses", json=payload, headers=headers)
+
+    metadata_payload = response.get("metadata", {}) if isinstance(response, dict) else {}
+    support_receipt = _support_receipt(
+        ready=ready,
+        response=response,
+        metadata=metadata_payload,
+        project=project_payload,
+    )
+    if raw:
+        print_json(
+            {
+                "ready": ready,
+                "response": response,
+                "response_id": response.get("id") if isinstance(response, dict) else None,
+                "request_id": _metadata_value(
+                    metadata_payload,
+                    "general_augment_request_id",
+                    "request_id",
+                ),
+                "trace_id": _metadata_value(
+                    metadata_payload,
+                    "general_augment_trace_id",
+                    "trace_id",
+                ),
+                "support_receipt": support_receipt,
+            }
+        )
+        return
+
+    rows: list[list[object]] = [["Ready", _status_text(ready)]]
+    if isinstance(response, dict):
+        rows.extend(
+            [
+                ["Response ID", response.get("id", "")],
+                ["Status", response.get("status", "")],
+                ["Model", response.get("model", metadata_payload.get("general_augment_model", ""))],
+                [
+                    "Request ID",
+                    metadata_payload.get(
+                        "request_id",
+                        metadata_payload.get("general_augment_request_id", ""),
+                    ),
+                ],
+                [
+                    "Trace ID",
+                    metadata_payload.get(
+                        "trace_id",
+                        metadata_payload.get("general_augment_trace_id", ""),
+                    ),
+                ],
+            ]
+        )
+        if structured:
+            rows.append(["Output Format", "json_schema"])
+    table("Smoke", ["Check", "Value"], rows)
+    if isinstance(response, dict):
+        panel("Output", _response_output_text(response) or "<empty>")
+        panel("Support receipt", json.dumps(support_receipt, indent=2, sort_keys=True))
+
+
+def _correlation_headers(
+    *,
+    idempotency_key: str,
+    request_id: str,
+    traceparent: str | None,
+) -> dict[str, str]:
+    """Build app-facing correlation headers."""
+    headers = {
+        "X-Idempotency-Key": idempotency_key,
+        "X-Request-ID": request_id,
+    }
+    if traceparent:
+        headers["traceparent"] = traceparent
+    return headers
+
+
+def _metadata_pairs(values: list[str]) -> dict[str, str]:
+    """Parse repeated key=value metadata flags."""
+    parsed: dict[str, str] = {}
+    for item in values:
+        key, separator, value = item.partition("=")
+        if not separator or not key.strip():
+            raise typer.BadParameter("--metadata values must use key=value.")
+        parsed[key.strip()] = value
+    return parsed
+
+
+def _load_schema(path: Path) -> dict[str, Any]:
+    """Load a JSON Schema object from disk."""
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise typer.BadParameter(f"{path} is not valid JSON: {exc.msg}") from exc
+    if not isinstance(payload, dict):
+        raise typer.BadParameter("--schema-file must contain a JSON object schema.")
+    return payload
+
+
+def _structured_text_format(schema: dict[str, Any]) -> dict[str, Any]:
+    """Build a Responses json_schema text format."""
+    return {
+        "format": {
+            "type": "json_schema",
+            "name": "genaug_smoke",
+            "schema": schema,
+            "strict": True,
+        }
+    }
+
+
+def _status_text(payload: object) -> str:
+    """Return a compact status string from health JSON."""
+    if isinstance(payload, dict):
+        return str(payload.get("status") or payload)
+    return str(payload)
+
+
+def _response_output_text(response: dict[str, Any]) -> str:
+    """Extract text from the common Responses output shape."""
+    output_text = response.get("output_text")
+    if isinstance(output_text, str):
+        return output_text
+    parts: list[str] = []
+    output = response.get("output")
+    if not isinstance(output, list):
+        return ""
+    for item in output:
+        if not isinstance(item, dict) or not isinstance(item.get("content"), list):
+            continue
+        for content in item["content"]:
+            if (
+                isinstance(content, dict)
+                and content.get("type") in {"output_text", "text"}
+                and isinstance(content.get("text"), str)
+            ):
+                parts.append(content["text"])
+    return "".join(parts)
+
+
+def _metadata_value(metadata: object, *keys: str) -> object:
+    """Return the first metadata value present for any key."""
+    if not isinstance(metadata, dict):
+        return None
+    for key in keys:
+        value = metadata.get(key)
+        if value:
+            return value
+    return None
+
+
+def _support_receipt(
+    *,
+    ready: object,
+    response: object,
+    metadata: object,
+    project: dict[str, Any] | None,
+) -> dict[str, object]:
+    """Build a redacted support receipt for replay/debug handoff."""
+    response_payload = response if isinstance(response, dict) else {}
+    model = response_payload.get("model")
+    if not model:
+        model = _metadata_value(metadata, "general_augment_model", "model")
+    return {
+        "source": "genaug-cli-smoke",
+        "project_id": str(project["id"]) if project and project.get("id") else None,
+        "project_slug": str(project["slug"]) if project and project.get("slug") else None,
+        "response_id": response_payload.get("id"),
+        "request_id": _metadata_value(
+            metadata,
+            "general_augment_request_id",
+            "request_id",
+        ),
+        "trace_id": _metadata_value(
+            metadata,
+            "general_augment_trace_id",
+            "trace_id",
+        ),
+        "model": model,
+        "cost_usd": _metadata_value(metadata, "general_augment_cost_usd", "cost_usd"),
+        "ready_status": _status_text(ready),
+    }

platform_cli/commands/status.py

@@ -0,0 +1,49 @@
+"""Platform status command."""
+
+from __future__ import annotations
+
+import typer
+
+from platform_cli.client import encode_path_segment, resolve_project
+from platform_cli.output import panel, table
+from platform_cli.runtime import Runtime
+
+
+def status(
+    ctx: typer.Context,
+    project: str | None = typer.Option(None, help="Optional project id, slug, or name."),
+) -> None:
+    """Show platform health, metrics reachability, and optional project usage."""
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        live = client.public("GET", "/health/live")
+        ready = client.public("GET", "/health/ready")
+        metrics = client.public("GET", "/metrics")
+        rows: list[list[object]] = [
+            ["Live", _status_text(live)],
+            ["Ready", _status_text(ready)],
+            ["Metrics", "available" if metrics is not None else "empty"],
+        ]
+        table("Platform Status", ["Check", "State"], rows)
+        if project:
+            project_payload = resolve_project(client, project)
+            usage = client.admin(
+                "GET",
+                f"/projects/{encode_path_segment(str(project_payload['id']))}/usage",
+            )
+            totals = usage.get("totals", {}) if isinstance(usage, dict) else {}
+            agent_turns = totals.get("agent_turns_count", 0)
+            panel(
+                f"Project {project_payload.get('slug', project)}",
+                f"Agent turns: {agent_turns}\n"
+                f"Stored messages: {totals.get('messages_count', 0)}\n"
+                f"Tool calls: {totals.get('tool_calls_count', 0)}\n"
+                f"Cost: {totals.get('total_cost_usd', 0)}",
+            )
+
+
+def _status_text(payload: object) -> str:
+    """Return a compact status string from health JSON."""
+    if isinstance(payload, dict):
+        return str(payload.get("status") or payload)
+    return str(payload)

platform_cli/commands/tools.py

@@ -0,0 +1,179 @@
+"""Tool management commands."""
+
+from __future__ import annotations
+
+import typer
+
+from platform_cli.client import encode_path_segment, resolve_project
+from platform_cli.output import print_json, print_success, table
+from platform_cli.runtime import Runtime
+
+app = typer.Typer(help="Manage project tools.")
+
+TOOL_DISCOVERY_MODES = {"auto", "always", "direct"}
+DEFAULT_TOOL_DISCOVERY: dict[str, int | str] = {
+    "mode": "auto",
+    "direct_schema_tool_limit": 10,
+    "max_search_results": 5,
+}
+
+
+@app.command("list")
+def list_tools(
+    ctx: typer.Context,
+    project: str = typer.Option(..., help="Project id, slug, or name."),
+) -> None:
+    """List tools with enabled and approval state."""
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        tools_payload = client.admin("GET", "/tools")
+    enabled = set(_string_list(project_payload.get("enabled_tool_ids")))
+    tools = tools_payload if isinstance(tools_payload, list) else tools_payload.get("items", [])
+    rows = [
+        [
+            item.get("id", ""),
+            "enabled" if item.get("id") in enabled else "disabled",
+            item.get("risk_level", ""),
+            "yes" if item.get("requires_approval") else "no",
+        ]
+        for item in tools
+        if isinstance(item, dict)
+    ]
+    table("Tools", ["Tool", "State", "Risk", "Approval"], rows)
+
+
+@app.command("toggle")
+def toggle_tool(
+    ctx: typer.Context,
+    tool_id: str = typer.Argument(...),
+    project: str = typer.Option(..., help="Project id, slug, or name."),
+    enable: bool | None = typer.Option(None, "--enable/--disable", help="Force state."),
+) -> None:
+    """Enable or disable a built-in tool."""
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        enabled = set(_string_list(project_payload.get("enabled_tool_ids")))
+        next_enabled = tool_id not in enabled if enable is None else enable
+        if next_enabled:
+            enabled.add(tool_id)
+            state = "enabled"
+        else:
+            enabled.discard(tool_id)
+            state = "disabled"
+        client.admin(
+            "PUT",
+            f"/projects/{encode_path_segment(str(project_payload['id']))}/tools",
+            json={"tool_ids": sorted(enabled)},
+        )
+    print_success(f"{tool_id} {state}.")
+
+
+@app.command("discovery")
+def configure_tool_discovery(
+    ctx: typer.Context,
+    project: str = typer.Option(..., help="Project id, slug, or name."),
+    mode: str | None = typer.Option(
+        None,
+        "--mode",
+        help="Tool discovery mode: auto, always, or direct.",
+    ),
+    direct_schema_tool_limit: int | None = typer.Option(
+        None,
+        "--direct-schema-tool-limit",
+        min=1,
+        help="Direct schema limit before catalog search is used.",
+    ),
+    max_search_results: int | None = typer.Option(
+        None,
+        "--max-search-results",
+        min=1,
+        max=10,
+        help="Maximum tool schemas returned by one discovery search.",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
+) -> None:
+    """Show or update the tenant tool discovery behavior."""
+    updates: dict[str, int | str] = {}
+    if mode is not None:
+        normalized_mode = mode.strip().casefold()
+        if normalized_mode not in TOOL_DISCOVERY_MODES:
+            raise typer.BadParameter("--mode must be one of: auto, always, direct.")
+        updates["mode"] = normalized_mode
+    if direct_schema_tool_limit is not None:
+        updates["direct_schema_tool_limit"] = direct_schema_tool_limit
+    if max_search_results is not None:
+        updates["max_search_results"] = max_search_results
+
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        current = _tool_discovery(project_payload.get("tool_discovery"))
+        if updates:
+            next_config = {**current, **updates}
+            project_payload = client.admin(
+                "PATCH",
+                f"/projects/{encode_path_segment(str(project_payload['id']))}",
+                json={"tool_discovery": next_config},
+            )
+            current = _tool_discovery(project_payload.get("tool_discovery"))
+
+    if json_output:
+        print_json(current)
+        return
+    if updates:
+        print_success("Tool discovery behavior saved.")
+    table(
+        "Tool Discovery",
+        ["Field", "Value"],
+        [
+            ["Mode", current["mode"]],
+            ["Direct schema limit", current["direct_schema_tool_limit"]],
+            ["Search result limit", current["max_search_results"]],
+        ],
+    )
+
+
+def _string_list(value: object) -> list[str]:
+    """Return a string list from JSON."""
+    return [str(item) for item in value] if isinstance(value, list) else []
+
+
+def _tool_discovery(value: object) -> dict[str, int | str]:
+    """Return a normalized tool discovery config from project JSON."""
+    if not isinstance(value, dict):
+        return dict(DEFAULT_TOOL_DISCOVERY)
+    mode = str(value.get("mode") or DEFAULT_TOOL_DISCOVERY["mode"]).casefold()
+    if mode not in TOOL_DISCOVERY_MODES:
+        mode = str(DEFAULT_TOOL_DISCOVERY["mode"])
+    return {
+        "mode": mode,
+        "direct_schema_tool_limit": _positive_int(
+            value.get("direct_schema_tool_limit"),
+            default=int(DEFAULT_TOOL_DISCOVERY["direct_schema_tool_limit"]),
+        ),
+        "max_search_results": min(
+            _positive_int(
+                value.get("max_search_results"),
+                default=int(DEFAULT_TOOL_DISCOVERY["max_search_results"]),
+            ),
+            10,
+        ),
+    }
+
+
+def _positive_int(value: object, *, default: int) -> int:
+    """Return a positive integer from API JSON."""
+    if value is None:
+        return default
+    if isinstance(value, int):
+        parsed = value
+    elif isinstance(value, str):
+        try:
+            parsed = int(value)
+        except ValueError:
+            return default
+    else:
+        return default
+    return parsed if parsed >= 1 else default

platform_cli/commands/users.py

@@ -0,0 +1,150 @@
+"""Tenant user management commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from platform_cli.client import encode_path_segment, resolve_project
+from platform_cli.output import print_json, print_success, table
+from platform_cli.runtime import Runtime
+
+app = typer.Typer(help="Manage tenant users.")
+
+
+@app.command("list")
+def list_users(
+    ctx: typer.Context,
+    project: Annotated[str, typer.Option(help="Project id, slug, or name.")],
+    page: Annotated[int, typer.Option(min=1, help="Page number.")] = 1,
+    page_size: Annotated[
+        int,
+        typer.Option("--page-size", min=1, max=500, help="Users per page."),
+    ] = 50,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """List users for one project."""
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        response = client.admin(
+            "GET",
+            f"/projects/{encode_path_segment(str(project_payload['id']))}/users",
+            params={"page": page, "page_size": page_size},
+        )
+    if json_output:
+        print_json(response)
+        return
+    items = response.get("items", []) if isinstance(response, dict) else []
+    rows = [
+        [
+            item.get("id", ""),
+            item.get("phone_e164", ""),
+            item.get("display_name", ""),
+            item.get("message_count", 0),
+            item.get("last_active_at", ""),
+        ]
+        for item in items
+        if isinstance(item, dict)
+    ]
+    table("Users", ["ID", "Phone", "Name", "Messages", "Last Active"], rows)
+
+
+@app.command("detail")
+def user_detail(
+    ctx: typer.Context,
+    user_id: Annotated[str, typer.Argument(help="General Augment user id.")],
+    project: Annotated[str, typer.Option(help="Project id, slug, or name.")],
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """Show one tenant user's memory and credential summary."""
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        response = client.admin(
+            "GET",
+            (
+                f"/projects/{encode_path_segment(str(project_payload['id']))}/users/"
+                f"{encode_path_segment(user_id)}"
+            ),
+        )
+    if json_output:
+        print_json(response)
+        return
+    user = response.get("user", {}) if isinstance(response, dict) else {}
+    memory_facts = response.get("memory_facts", []) if isinstance(response, dict) else []
+    credentials = response.get("credentials", []) if isinstance(response, dict) else []
+    table(
+        "User detail",
+        ["Field", "Value"],
+        [
+            ["User ID", _value(user, "id")],
+            ["Phone", _value(user, "phone_e164")],
+            ["Display Name", _value(user, "display_name")],
+            ["Messages", _value(response, "message_count")],
+            ["Memory Facts", len(memory_facts) if isinstance(memory_facts, list) else 0],
+            ["Credentials", _credential_summary(credentials)],
+        ],
+    )
+
+
+@app.command("delete")
+def delete_user(
+    ctx: typer.Context,
+    user_id: Annotated[str, typer.Argument(help="General Augment user id.")],
+    project: Annotated[str, typer.Option(help="Project id, slug, or name.")],
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", help="Confirm deleting this user and cascaded tenant data."),
+    ] = False,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """Delete one tenant user and cascaded tenant data."""
+    if not yes and not typer.confirm(f"Delete user {user_id} and cascaded tenant data?"):
+        raise typer.Exit(1)
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        response = client.admin(
+            "DELETE",
+            (
+                f"/projects/{encode_path_segment(str(project_payload['id']))}/users/"
+                f"{encode_path_segment(user_id)}"
+            ),
+        )
+    if json_output:
+        print_json(response)
+        return
+    deleted_user_id = response.get("user_id", user_id) if isinstance(response, dict) else user_id
+    print_success(f"Deleted user {deleted_user_id}.")
+
+
+def _credential_summary(value: object) -> str:
+    """Return a compact credential summary without secret values."""
+    if not isinstance(value, list) or not value:
+        return "none"
+    labels: list[str] = []
+    for item in value:
+        if not isinstance(item, dict):
+            continue
+        provider = item.get("provider", "unknown")
+        status = item.get("status", "unknown")
+        labels.append(f"{provider}:{status}")
+    return ", ".join(labels) if labels else "none"
+
+
+def _value(payload: object, key: str) -> object:
+    """Safely read a value from a response mapping."""
+    if isinstance(payload, dict):
+        return payload.get(key, "")
+    return ""