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

platform_cli/commands/observability.py

@@ -0,0 +1,174 @@
+"""Observability and support-evidence commands."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+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="Inspect traces and support evidence.")
+
+
+@app.command("trace")
+def get_trace(
+    ctx: typer.Context,
+    trace_id: Annotated[str, typer.Argument(help="Trace id returned by /v1/responses.")],
+    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:
+    """Fetch one project-scoped assistant trace."""
+    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']))}/traces/"
+                f"{encode_path_segment(trace_id)}"
+            ),
+        )
+    if json_output:
+        print_json(response)
+        return
+    table(
+        "Trace",
+        ["Field", "Value"],
+        [
+            ["Trace ID", _value(response, "trace_id") or trace_id],
+            ["Response", _value(response, "id")],
+            ["User", _value(response, "user_id")],
+            ["Session", _value(response, "session_id")],
+            ["Model", _value(response, "model_used")],
+            ["Input Tokens", _value(response, "input_tokens")],
+            ["Output Tokens", _value(response, "output_tokens")],
+            ["Cost USD", _value(response, "cost_usd")],
+            ["Latency MS", _value(response, "latency_ms")],
+            ["Langfuse", _value(response, "langfuse_url")],
+        ],
+    )
+
+
+@app.command("support-bundle")
+def support_bundle(
+    ctx: typer.Context,
+    project: Annotated[str, typer.Option(help="Project id, slug, or name.")],
+    trace_id: Annotated[
+        str | None,
+        typer.Option("--trace-id", help="Filter by General Augment trace id."),
+    ] = None,
+    response_id: Annotated[
+        str | None,
+        typer.Option("--response-id", help="Filter by Responses API response id."),
+    ] = None,
+    user_id: Annotated[
+        str | None,
+        typer.Option("--user-id", help="Filter by General Augment user id."),
+    ] = None,
+    session_id: Annotated[
+        str | None,
+        typer.Option("--session-id", help="Filter by General Augment session id."),
+    ] = None,
+    feature: Annotated[
+        str | None,
+        typer.Option(help="Filter by response metadata feature."),
+    ] = None,
+    source: Annotated[
+        str | None,
+        typer.Option(help="Filter by response metadata source."),
+    ] = None,
+    status: Annotated[
+        str | None,
+        typer.Option(help="Filter by success/failure status."),
+    ] = None,
+    start: Annotated[
+        str | None,
+        typer.Option(help="Filter start timestamp, ISO 8601."),
+    ] = None,
+    end: Annotated[
+        str | None,
+        typer.Option(help="Filter end timestamp, ISO 8601."),
+    ] = None,
+    limit: Annotated[int, typer.Option(min=1, max=200, help="Maximum rows per section.")] = 50,
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", help="Write support bundle JSON to a file."),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """Export a bounded project support bundle."""
+    params = _support_params(
+        limit=limit,
+        trace_id=trace_id,
+        response_id=response_id,
+        user_id=user_id,
+        session_id=session_id,
+        feature=feature,
+        source=source,
+        status=status,
+        start=start,
+        end=end,
+    )
+    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']))}"
+                "/observability/support-bundle"
+            ),
+            params=params,
+        )
+    if output is not None:
+        output.write_text(json.dumps(response, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        print_success(f"Wrote support bundle to {output}.")
+        return
+    if json_output:
+        print_json(response)
+        return
+    metrics = response.get("metrics", {}) if isinstance(response, dict) else {}
+    table(
+        "Support bundle",
+        ["Field", "Value"],
+        [
+            ["Project", _value(response, "project_id")],
+            ["Generated At", _value(response, "generated_at")],
+            ["Traces", _metric(metrics, "trace_count")],
+            ["Logs", _metric(metrics, "log_count")],
+            ["Audit Events", _metric(metrics, "audit_event_count")],
+            ["Memory Facts", _metric(metrics, "memory_fact_count")],
+            ["Usage Events", _metric(metrics, "usage_event_count")],
+            ["Timeline Events", _metric(metrics, "timeline_event_count")],
+        ],
+    )
+
+
+def _support_params(**values: object) -> dict[str, object]:
+    """Return support-bundle query params without unset filters."""
+    return {key: value for key, value in values.items() if value is not None}
+
+
+def _metric(payload: object, key: str) -> object:
+    """Read a metric from the support-bundle metrics map."""
+    if isinstance(payload, dict):
+        return payload.get(key, 0)
+    return 0
+
+
+def _value(payload: object, key: str) -> object:
+    """Safely read a value from a response mapping."""
+    if isinstance(payload, dict):
+        return payload.get(key, "")
+    return ""

platform_cli/commands/onboarding.py

@@ -0,0 +1,72 @@
+"""App-developer onboarding commands."""
+
+from __future__ import annotations
+
+import os
+
+import typer
+
+from platform_cli.commands.verify import build_project_verification_payload
+from platform_cli.errors import CLIError
+from platform_cli.output import panel, print_json, table
+from platform_cli.runtime import Runtime
+
+app = typer.Typer(help="Verify app-developer onboarding before launch.")
+
+
+@app.command("verify")
+def verify_onboarding(
+    ctx: typer.Context,
+    project: str = typer.Option(..., help="Project id, slug, or name."),
+    message: str = typer.Option(
+        "Reply with one short sentence confirming this General Augment project works.",
+        help="Message for the hosted agent test.",
+    ),
+    user: str = typer.Option(
+        "genaug-onboarding-user",
+        help="Synthetic app user id for memory and agent checks.",
+    ),
+    phone_e164: str = typer.Option("+15550000000", help="Synthetic E.164 user identity."),
+    channel: str = typer.Option("sms", help="Synthetic channel: sms, whatsapp, ios, or telegram."),
+    dashboard_url: str = typer.Option(
+        os.getenv("GENAUG_DASHBOARD_URL", "https://app.generalaugment.com"),
+        help="Dashboard base URL for follow-up UI checks.",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
+) -> None:
+    """Run the one-command onboarding gate for an existing project."""
+
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        payload = build_project_verification_payload(
+            client,
+            project=project,
+            message=message,
+            user=user,
+            phone_e164=phone_e164,
+            channel=channel,
+            dashboard_url=dashboard_url,
+        )
+    payload["onboarding"] = {
+        "verdict": payload["verdict"],
+        "required_follow_up": [
+            "Confirm the dashboard shows the same project, tools, usage, traces, logs, and memory.",
+            "Keep project API keys server-side in the app backend.",
+            "Handle 402 and 429 responses before production traffic.",
+        ],
+    }
+    if json_output:
+        print_json(payload)
+    else:
+        table(
+            f"Onboarding Verify: {payload['project']['slug']}",
+            ["Check", "Status", "Detail"],
+            [[item["name"], item["status"], item["detail"]] for item in payload["checks"]],
+        )
+        panel(
+            "Dashboard Follow-up",
+            "\n".join(f"{key}: {value}" for key, value in payload["dashboard"].items()),
+        )
+    if payload["verdict"] != "PASS":
+        failed = ", ".join(item["name"] for item in payload["checks"] if item["status"] != "PASS")
+        raise CLIError(f"Onboarding verification failed: {failed}")

platform_cli/commands/projects.py

@@ -0,0 +1,302 @@
+"""Project management commands."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+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 projects.")
+
+
+@app.command("list")
+def list_projects(ctx: typer.Context) -> None:
+    """List visible projects."""
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        payload = client.admin("GET", "/projects")
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    rows = [
+        [item.get("name", ""), item.get("slug", ""), item.get("status", ""), item.get("id", "")]
+        for item in items
+        if isinstance(item, dict)
+    ]
+    table("Projects", ["Name", "Slug", "Status", "ID"], rows)
+
+
+@app.command("create")
+def create_project(
+    ctx: typer.Context,
+    name: str = typer.Option(..., help="Project display name."),
+    slug: str = typer.Option(..., help="Project slug."),
+    system_prompt: str = typer.Option("You are a helpful agent.", help="Initial system prompt."),
+) -> None:
+    """Create a project."""
+    runtime: Runtime = ctx.obj
+    payload = {
+        "name": name,
+        "slug": slug,
+        "system_prompt": system_prompt,
+    }
+    with runtime.client() as client:
+        project = client.admin("POST", "/projects", json=payload)
+    print_success(f"Created project {project.get('name', name)} ({project.get('id', 'unknown')}).")
+
+
+@app.command("usage")
+def project_usage(
+    ctx: typer.Context,
+    project: str = typer.Option(..., help="Project id, slug, or name."),
+    start_date: str | None = typer.Option(None, help="Inclusive start date, YYYY-MM-DD."),
+    end_date: str | None = typer.Option(None, help="Inclusive end date, YYYY-MM-DD."),
+) -> None:
+    """Show project usage and billing aggregates."""
+    runtime: Runtime = ctx.obj
+    params = {
+        key: value
+        for key, value in {"start_date": start_date, "end_date": end_date}.items()
+        if value is not None
+    }
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        usage = client.admin(
+            "GET",
+            f"/projects/{encode_path_segment(str(project_payload['id']))}/usage",
+            params=params,
+        )
+    totals = usage.get("totals", {}) if isinstance(usage, dict) else {}
+    rows: list[list[object]] = [
+        ["Agent turns", _metric(totals, "agent_turns_count")],
+        ["Stored messages", _metric(totals, "messages_count")],
+        ["Tool calls", _metric(totals, "tool_calls_count")],
+        ["Cost USD", _metric(totals, "total_cost_usd")],
+    ]
+    table(f"Usage for {project_payload.get('slug', project)}", ["Metric", "Value"], rows)
+
+    days = usage.get("days", []) if isinstance(usage, dict) else []
+    day_rows = [
+        [
+            item.get("date", item.get("day", "")),
+            _metric(item, "agent_turns_count"),
+            _metric(item, "tool_calls_count"),
+            _metric(item, "total_cost_usd"),
+        ]
+        for item in days
+        if isinstance(item, dict)
+    ]
+    if day_rows:
+        table("Daily Usage", ["Date", "Agent turns", "Tool calls", "Cost USD"], day_rows)
+
+
+@app.command("runtime-policy")
+def project_runtime_policy(
+    ctx: typer.Context,
+    project: str = typer.Option(..., help="Project id, slug, or name."),
+    json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
+) -> None:
+    """Show the tenant-governed Hermes runtime policy."""
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        policy = client.admin(
+            "GET",
+            f"/projects/{encode_path_segment(str(project_payload['id']))}/runtime-policy",
+        )
+    if json_output:
+        print_json(policy)
+        return
+    routing = policy.get("model_routing", {}) if isinstance(policy, dict) else {}
+    tiers = routing.get("tiers", {}) if isinstance(routing, dict) else {}
+    table(
+        f"Runtime Policy for {project_payload.get('slug', project)}",
+        ["Surface", "Value"],
+        [
+            ["Model routing", _model_routing_summary(routing)],
+            ["Simple model", _field(tiers, "simple")],
+            ["Balanced model", _field(tiers, "balanced")],
+            ["Complex model", _field(tiers, "complex")],
+            ["Tool discovery", _nested_metric(policy, "tool_discovery", "mode")],
+            ["Enabled platform tools", _joined(policy, "platform_tools", "enabled_tool_ids")],
+            ["MCP tools", _joined(policy, "mcp", "enabled_tool_ids")],
+            ["Skills", _joined(policy, "skills", "names")],
+        ],
+    )
+
+
+@app.command("export")
+def export_project(
+    ctx: typer.Context,
+    project: Annotated[str, typer.Option(help="Project id, slug, or name.")],
+    include: Annotated[
+        list[str] | None,
+        typer.Option("--include", help="Export section to include. Repeatable."),
+    ] = None,
+    limit: Annotated[int, typer.Option(min=1, max=500, help="Maximum rows per section.")] = 100,
+    user_id: Annotated[str | None, typer.Option("--user-id", help="Filter by user id.")] = None,
+    session_id: Annotated[
+        str | None,
+        typer.Option("--session-id", help="Filter by session id."),
+    ] = None,
+    trace_id: Annotated[str | None, typer.Option("--trace-id", help="Filter by trace id.")] = None,
+    start: Annotated[str | None, typer.Option(help="Filter start timestamp, ISO 8601.")] = None,
+    end: Annotated[str | None, typer.Option(help="Filter end timestamp, ISO 8601.")] = None,
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", help="Write export JSON to a file."),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """Export bounded project data for operator review."""
+    runtime: Runtime = ctx.obj
+    params = _export_params(
+        include=include,
+        limit=limit,
+        user_id=user_id,
+        session_id=session_id,
+        trace_id=trace_id,
+        start=start,
+        end=end,
+    )
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        response = client.admin(
+            "GET",
+            f"/projects/{encode_path_segment(str(project_payload['id']))}/export",
+            params=params,
+        )
+    if output is not None:
+        output.write_text(json.dumps(response, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        print_success(f"Wrote project export to {output}.")
+        return
+    if json_output:
+        print_json(response)
+        return
+    filters = response.get("filters", {}) if isinstance(response, dict) else {}
+    include_sections = filters.get("include", include or []) if isinstance(filters, dict) else []
+    table(
+        "Project export",
+        ["Field", "Value"],
+        [
+            ["Project", _value(response, "project_id")],
+            ["Exported At", _value(response, "exported_at")],
+            ["Sections", ", ".join(str(item) for item in include_sections)],
+            ["Logs", _section_count(response, "logs")],
+            ["Traces", _section_count(response, "traces")],
+            ["Audit Events", _section_count(response, "audit_events")],
+            ["Memory Facts", _section_count(response, "memory_facts")],
+            ["Usage Events", _section_count(response, "usage_events")],
+        ],
+    )
+
+
+@app.command("archive")
+def archive_project(
+    ctx: typer.Context,
+    project: Annotated[str, typer.Argument(help="Project id, slug, or name.")],
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", help="Confirm archiving this project."),
+    ] = False,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """Archive one project."""
+    if not yes and not typer.confirm(f"Archive project {project}?"):
+        raise typer.Exit(1)
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        response = client.admin(
+            "POST",
+            f"/projects/{encode_path_segment(str(project_payload['id']))}/archive",
+        )
+    if json_output:
+        print_json(response)
+        return
+    archived_project = response.get("slug", project) if isinstance(response, dict) else project
+    print_success(f"Archived project {archived_project}.")
+
+
+def _metric(payload: object, *keys: str) -> object:
+    """Return the first present metric value from a usage payload."""
+    if not isinstance(payload, dict):
+        return 0
+    for key in keys:
+        if key in payload:
+            return payload[key]
+    return 0
+
+
+def _nested_metric(payload: object, section: str, key: str) -> object:
+    """Return a nested field value from a JSON object."""
+
+    if not isinstance(payload, dict):
+        return ""
+    nested = payload.get(section)
+    if not isinstance(nested, dict):
+        return ""
+    return nested.get(key, "")
+
+
+def _field(payload: object, key: str) -> object:
+    """Return a field value from a JSON object."""
+
+    if not isinstance(payload, dict):
+        return ""
+    return payload.get(key, "")
+
+
+def _joined(payload: object, section: str, key: str) -> str:
+    """Return a compact joined list from a nested JSON object."""
+
+    if not isinstance(payload, dict):
+        return ""
+    nested = payload.get(section)
+    if not isinstance(nested, dict):
+        return ""
+    values = nested.get(key)
+    if not isinstance(values, list):
+        return ""
+    return ", ".join(str(item) for item in values) or "none"
+
+
+def _model_routing_summary(payload: object) -> str:
+    """Return a compact model-routing mode summary."""
+
+    if not isinstance(payload, dict):
+        return ""
+    mode = str(payload.get("mode") or "")
+    default_tier = str(payload.get("default_tier") or "")
+    parity = payload.get("channel_parity")
+    return f"{mode}, default={default_tier}, channel_parity={parity}"
+
+
+def _export_params(**values: object) -> dict[str, object]:
+    """Return project export query params without unset filters."""
+    return {key: value for key, value in values.items() if value is not None}
+
+
+def _section_count(payload: object, key: str) -> int:
+    """Return the length of a list section in a project export."""
+    if not isinstance(payload, dict):
+        return 0
+    value = payload.get(key)
+    return len(value) if isinstance(value, list) else 0
+
+
+def _value(payload: object, key: str) -> object:
+    """Safely read a value from a response mapping."""
+    if isinstance(payload, dict):
+        return payload.get(key, "")
+    return ""

platform_cli/commands/skills.py

@@ -0,0 +1,116 @@
+"""Skill management commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+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 skills.")
+
+
+@app.command("list")
+def list_skills(
+    ctx: typer.Context,
+    project: str = typer.Option(..., help="Project id, slug, or name."),
+    json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
+) -> None:
+    """List SKILL.md files registered for a tenant."""
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        payload = client.admin(
+            "GET",
+            f"/projects/{encode_path_segment(str(project_payload['id']))}/skills",
+        )
+    if json_output:
+        print_json(payload)
+        return
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    rows = [
+        [
+            item.get("name", ""),
+            item.get("description", ""),
+            item.get("version", ""),
+            ", ".join(str(tag) for tag in item.get("tags", []) or []),
+            ", ".join(str(tool) for tool in item.get("tools", []) or []),
+        ]
+        for item in items
+        if isinstance(item, dict)
+    ]
+    table(
+        f"Skills for {project_payload.get('slug', project)}",
+        ["Name", "Description", "Version", "Tags", "Tools"],
+        rows,
+    )
+
+
+@app.command("view")
+def view_skill(
+    ctx: typer.Context,
+    skill_name: str = typer.Argument(..., help="Skill name."),
+    project: str = typer.Option(..., help="Project id, slug, or name."),
+    json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
+) -> None:
+    """Show one tenant SKILL.md file."""
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        payload = client.admin(
+            "GET",
+            (
+                f"/projects/{encode_path_segment(str(project_payload['id']))}/skills/"
+                f"{encode_path_segment(skill_name)}"
+            ),
+        )
+    if json_output:
+        print_json(payload)
+        return
+    typer.echo(str(payload.get("content", "")) if isinstance(payload, dict) else "")
+
+
+@app.command("apply")
+def apply_skill(
+    ctx: typer.Context,
+    skill_file: Annotated[
+        Path,
+        typer.Argument(exists=True, dir_okay=False, help="Path to a SKILL.md file."),
+    ],
+    project: str = typer.Option(..., help="Project id, slug, or name."),
+) -> None:
+    """Create or replace one tenant skill from a local SKILL.md file."""
+    runtime: Runtime = ctx.obj
+    content = skill_file.read_text(encoding="utf-8")
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        payload = client.admin(
+            "POST",
+            f"/projects/{encode_path_segment(str(project_payload['id']))}/skills",
+            json={"content": content},
+        )
+    print_success(f"Applied skill {payload.get('name', skill_file.stem)}.")
+
+
+@app.command("delete")
+def delete_skill(
+    ctx: typer.Context,
+    skill_name: str = typer.Argument(..., help="Skill name."),
+    project: str = typer.Option(..., help="Project id, slug, or name."),
+) -> None:
+    """Delete one tenant skill."""
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        payload = client.admin(
+            "DELETE",
+            (
+                f"/projects/{encode_path_segment(str(project_payload['id']))}/skills/"
+                f"{encode_path_segment(skill_name)}"
+            ),
+        )
+    print_success(f"Deleted skill {payload.get('name', skill_name)}.")