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

platform_cli/commands/doctor.py

@@ -0,0 +1,170 @@
+"""CLI environment and platform preflight checks."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+import typer
+
+from platform_cli.errors import CLIError
+from platform_cli.output import print_json, table
+from platform_cli.runtime import Runtime
+
+
+def doctor(
+    ctx: typer.Context,
+    raw: Annotated[bool, typer.Option("--json", help="Print machine-readable results.")] = False,
+) -> None:
+    """Check local CLI config, API reachability, and auth."""
+    runtime: Runtime = ctx.obj
+    checks: list[dict[str, str]] = []
+
+    checks.append(_config_check(runtime))
+    checks.append(_base_url_check(runtime))
+    checks.append(_api_key_check(runtime))
+
+    with runtime.client() as client:
+        try:
+            ready = client.public("GET", "/health/ready")
+            checks.append(
+                _check(
+                    "api_ready",
+                    "PASS",
+                    _status_detail(ready),
+                    "The platform API answered /health/ready.",
+                )
+            )
+        except CLIError as exc:
+            checks.append(
+                _check(
+                    "api_ready",
+                    "FAIL",
+                    str(exc),
+                    "Check --base-url or GENAUG_ADMIN_BASE_URL, then retry.",
+                )
+            )
+
+        if runtime.config.api_key:
+            try:
+                identity = client.admin("GET", "/me")
+                project_ids = identity.get("project_ids", []) if isinstance(identity, dict) else []
+                detail = (
+                    f"auth_method={identity.get('auth_method', 'unknown')}, "
+                    f"projects={len(project_ids or [])}"
+                    if isinstance(identity, dict)
+                    else "authenticated"
+                )
+                checks.append(
+                    _check(
+                        "auth",
+                        "PASS",
+                        detail,
+                        "The configured key can call the admin API.",
+                    )
+                )
+            except CLIError as exc:
+                checks.append(
+                    _check(
+                        "auth",
+                        "FAIL",
+                        str(exc),
+                        "Run genaug auth login with a valid key or fix API key env overrides.",
+                    )
+                )
+        else:
+            checks.append(
+                _check(
+                    "auth",
+                    "FAIL",
+                    "No API key configured.",
+                    "Run genaug auth login or set GENAUG_ADMIN_API_KEY.",
+                )
+            )
+
+    summary = {"verdict": _verdict(checks), "checks": checks}
+    if raw:
+        print_json(summary)
+    else:
+        table(
+            "General Augment Doctor",
+            ["Check", "Status", "Detail", "Next action"],
+            [
+                [item["name"], item["status"], item["detail"], item["next_action"]]
+                for item in checks
+            ],
+        )
+
+    if summary["verdict"] == "FAIL":
+        raise typer.Exit(1)
+
+
+def _config_check(runtime: Runtime) -> dict[str, str]:
+    """Return the config-file check."""
+    if runtime.loaded_config_path.exists():
+        return _check(
+            "config",
+            "PASS",
+            f"loaded={runtime.loaded_config_path}",
+            "No action needed.",
+        )
+    return _check(
+        "config",
+        "WARN",
+        f"no saved config at {runtime.loaded_config_path}",
+        "Run genaug auth login to persist config, or keep using env overrides.",
+    )
+
+
+def _base_url_check(runtime: Runtime) -> dict[str, str]:
+    """Return a base URL sanity check."""
+    base_url = runtime.config.base_url.rstrip("/")
+    if base_url.startswith(("http://", "https://")):
+        return _check("base_url", "PASS", base_url, "No action needed.")
+    return _check(
+        "base_url",
+        "FAIL",
+        base_url or "<empty>",
+        "Set --base-url or GENAUG_ADMIN_BASE_URL to an http(s) URL.",
+    )
+
+
+def _api_key_check(runtime: Runtime) -> dict[str, str]:
+    """Return an API-key presence check without printing the key."""
+    if runtime.config.api_key:
+        return _check("api_key", "PASS", "configured", "No action needed.")
+    return _check(
+        "api_key",
+        "FAIL",
+        "missing",
+        "Run genaug auth login or set GENAUG_ADMIN_API_KEY.",
+    )
+
+
+def _status_detail(payload: Any) -> str:
+    """Format a compact health-check detail."""
+    if isinstance(payload, dict):
+        status = payload.get("status") or payload.get("state") or "unknown"
+        db = payload.get("db")
+        redis = payload.get("redis")
+        dependencies = ", ".join(str(item) for item in (db, redis) if item)
+        return f"status={status}" + (f", {dependencies}" if dependencies else "")
+    return str(payload)
+
+
+def _check(name: str, status: str, detail: str, next_action: str) -> dict[str, str]:
+    """Return one doctor check row."""
+    return {
+        "name": name,
+        "status": status,
+        "detail": detail,
+        "next_action": next_action,
+    }
+
+
+def _verdict(checks: list[dict[str, str]]) -> str:
+    """Return the aggregate doctor verdict."""
+    if any(item["status"] == "FAIL" for item in checks):
+        return "FAIL"
+    if any(item["status"] == "WARN" for item in checks):
+        return "WARN"
+    return "PASS"

platform_cli/commands/identity.py

@@ -0,0 +1,433 @@
+"""Tenant identity-link management commands."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+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 identity links.")
+
+
+@app.command("list")
+def list_identity_links(
+    ctx: typer.Context,
+    project: Annotated[str, typer.Option(help="Project id, slug, or name.")],
+    limit: Annotated[int, typer.Option(min=1, max=1000, help="Maximum links to return.")] = 100,
+    offset: Annotated[int, typer.Option(min=0, help="Pagination offset.")] = 0,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """List verified and pending identity links 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']))}/identity-links",
+            params={"limit": limit, "offset": offset},
+        )
+    if json_output:
+        print_json(response)
+        return
+    items = response.get("items", []) if isinstance(response, dict) else []
+    rows = [_identity_row(item) for item in items if isinstance(item, dict)]
+    table(
+        "Identity links",
+        ["Phone", "Provider", "Provider User", "Verified", "Linked At"],
+        rows,
+    )
+
+
+@app.command("create-test")
+def create_test_identity_link(
+    ctx: typer.Context,
+    project: Annotated[str, typer.Option(help="Project id, slug, or name.")],
+    phone: Annotated[str, typer.Option("--phone", help="Phone number to link.")],
+    provider_user_id: Annotated[
+        str,
+        typer.Option("--provider-user-id", help="Tenant app user id for this link."),
+    ],
+    provider_name: Annotated[
+        str,
+        typer.Option("--provider-name", help="Tenant identity provider name."),
+    ] = "app",
+    metadata: Annotated[
+        list[str] | None,
+        typer.Option("--metadata", help="Metadata as key=value. Repeatable."),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """Create or update one verified test identity link."""
+    payload = {
+        "phone_e164": phone,
+        "provider_user_id": provider_user_id,
+        "provider_name": provider_name,
+        "metadata": _metadata_pairs(metadata or []),
+    }
+    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']))}/identity-links/test",
+            json=payload,
+        )
+    if json_output:
+        print_json(response)
+        return
+    table(
+        "Created test identity link",
+        ["Field", "Value"],
+        [
+            ["Phone", _value(response, "phone_e164") or phone],
+            ["Provider", _value(response, "provider_name") or provider_name],
+            ["Provider User", _value(response, "provider_user_id") or provider_user_id],
+            ["Verified", _value(response, "verified")],
+            ["Linked At", _value(response, "linked_at")],
+        ],
+    )
+
+
+@app.command("link-user")
+def link_user(
+    ctx: typer.Context,
+    project: Annotated[str, typer.Option(help="Project id, slug, or name.")],
+    phone: Annotated[str, typer.Option("--phone", help="Phone number to link.")],
+    provider_user_id: Annotated[
+        str,
+        typer.Option("--provider-user-id", help="Tenant app user id for this link."),
+    ],
+    provider_name: Annotated[
+        str,
+        typer.Option("--provider-name", help="Tenant identity provider name."),
+    ] = "app",
+    metadata: Annotated[
+        list[str] | None,
+        typer.Option("--metadata", help="Metadata as key=value. Repeatable."),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """Create an app-initiated OTP identity-link challenge."""
+    response = _identity_challenge(
+        ctx,
+        project=project,
+        endpoint="link-user",
+        payload={
+            "phone_e164": phone,
+            "provider_user_id": provider_user_id,
+            "provider_name": provider_name,
+            "metadata": _metadata_pairs(metadata or []),
+        },
+    )
+    _print_challenge(
+        response,
+        title="Identity link challenge",
+        fallback_phone=phone,
+        fallback_provider=provider_name,
+        fallback_provider_user_id=provider_user_id,
+        json_output=json_output,
+    )
+
+
+@app.command("verification-code")
+def verification_code(
+    ctx: typer.Context,
+    project: Annotated[str, typer.Option(help="Project id, slug, or name.")],
+    phone: Annotated[str, typer.Option("--phone", help="Phone number to link.")],
+    provider_user_id: Annotated[
+        str,
+        typer.Option("--provider-user-id", help="Tenant app user id for this link."),
+    ],
+    provider_name: Annotated[
+        str,
+        typer.Option("--provider-name", help="Tenant identity provider name."),
+    ] = "app",
+    metadata: Annotated[
+        list[str] | None,
+        typer.Option("--metadata", help="Metadata as key=value. Repeatable."),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """Create a code that the tenant app can show to the user."""
+    response = _identity_challenge(
+        ctx,
+        project=project,
+        endpoint="verification-code",
+        payload={
+            "phone_e164": phone,
+            "provider_user_id": provider_user_id,
+            "provider_name": provider_name,
+            "metadata": _metadata_pairs(metadata or []),
+        },
+    )
+    _print_challenge(
+        response,
+        title="Identity verification code",
+        fallback_phone=phone,
+        fallback_provider=provider_name,
+        fallback_provider_user_id=provider_user_id,
+        json_output=json_output,
+    )
+
+
+@app.command("magic-link")
+def magic_link(
+    ctx: typer.Context,
+    project: Annotated[str, typer.Option(help="Project id, slug, or name.")],
+    phone: Annotated[str, typer.Option("--phone", help="Phone number to link.")],
+    user_identifier: Annotated[
+        str,
+        typer.Option("--user-identifier", help="Email or app username to prefill."),
+    ],
+    provider_name: Annotated[
+        str,
+        typer.Option("--provider-name", help="Tenant identity provider name."),
+    ] = "app",
+    channel: Annotated[
+        str,
+        typer.Option("--channel", help="Delivery channel: whatsapp, sms, or telegram."),
+    ] = "whatsapp",
+    metadata: Annotated[
+        list[str] | None,
+        typer.Option("--metadata", help="Metadata as key=value. Repeatable."),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """Create and optionally deliver an agent-initiated magic-link challenge."""
+    response = _identity_challenge(
+        ctx,
+        project=project,
+        endpoint="magic-link",
+        payload={
+            "phone_e164": phone,
+            "user_identifier": user_identifier,
+            "provider_name": provider_name,
+            "channel": channel,
+            "metadata": _metadata_pairs(metadata or []),
+        },
+    )
+    _print_challenge(
+        response,
+        title="Identity magic link",
+        fallback_phone=phone,
+        fallback_provider=provider_name,
+        fallback_provider_user_id=user_identifier,
+        json_output=json_output,
+    )
+
+
+@app.command("verify")
+def verify_identity(
+    ctx: typer.Context,
+    project: Annotated[str, typer.Option(help="Project id, slug, or name.")],
+    phone: Annotated[str, typer.Option("--phone", help="Phone number to verify.")],
+    code: Annotated[str, typer.Option("--code", help="OTP, texted code, or magic-link state.")],
+    provider_name: Annotated[
+        str,
+        typer.Option("--provider-name", help="Tenant identity provider name."),
+    ] = "app",
+    provider_user_id: Annotated[
+        str | None,
+        typer.Option("--provider-user-id", help="Override app user id after Auth0 callback."),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """Verify a pending identity-link challenge."""
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        payload = {
+            "phone_e164": phone,
+            "provider_name": provider_name,
+            "code": code,
+        }
+        if provider_user_id:
+            payload["provider_user_id"] = provider_user_id
+        response = client.integrations(
+            "POST",
+            f"/{encode_path_segment(str(project_payload['id']))}/verify",
+            json=payload,
+        )
+    _print_resolution(response, json_output=json_output, success_message="Identity verified")
+
+
+@app.command("resolve")
+def resolve_identity(
+    ctx: typer.Context,
+    project: Annotated[str, typer.Option(help="Project id, slug, or name.")],
+    phone: Annotated[str, typer.Option("--phone", help="Phone number to resolve.")],
+    provider_name: Annotated[
+        str | None,
+        typer.Option("--provider-name", help="Optional tenant identity provider name."),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """Resolve a verified phone-to-app-account identity link."""
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        params = {"provider_name": provider_name} if provider_name else None
+        response = client.integrations(
+            "GET",
+            f"/{encode_path_segment(str(project_payload['id']))}/resolve/{encode_path_segment(phone)}",
+            params=params,
+        )
+    _print_resolution(response, json_output=json_output, success_message="Identity resolved")
+
+
+@app.command("unlink")
+def unlink_identity(
+    ctx: typer.Context,
+    project: Annotated[str, typer.Option(help="Project id, slug, or name.")],
+    phone: Annotated[str, typer.Option("--phone", help="Phone number to unlink.")],
+    provider_name: Annotated[
+        str,
+        typer.Option("--provider-name", help="Tenant identity provider name."),
+    ],
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", help="Confirm unlinking this identity mapping."),
+    ] = False,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """Remove one phone-to-app-account identity link."""
+    if not yes and not typer.confirm(f"Unlink {phone} from {provider_name}?"):
+        raise typer.Exit(1)
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        response = client.integrations(
+            "DELETE",
+            f"/{encode_path_segment(str(project_payload['id']))}/unlink/{encode_path_segment(phone)}",
+            params={"provider_name": provider_name},
+        )
+    if json_output:
+        print_json(response)
+        return
+    message = "Identity unlinked" if _value(response, "unlinked") else "Identity link not found"
+    print_success(message)
+
+
+def _identity_row(link: dict[str, Any]) -> list[object]:
+    """Return a table row for one identity link."""
+    return [
+        link.get("phone_e164", ""),
+        link.get("provider_name", ""),
+        link.get("provider_user_id", ""),
+        "yes" if link.get("verified") else "no",
+        link.get("linked_at", ""),
+    ]
+
+
+def _identity_challenge(
+    ctx: typer.Context,
+    *,
+    project: str,
+    endpoint: str,
+    payload: dict[str, Any],
+) -> object:
+    """Create one identity challenge through the integration API."""
+    runtime: Runtime = ctx.obj
+    with runtime.client() as client:
+        project_payload = resolve_project(client, project)
+        return client.integrations(
+            "POST",
+            f"/{encode_path_segment(str(project_payload['id']))}/{endpoint}",
+            json=payload,
+        )
+
+
+def _print_challenge(
+    response: object,
+    *,
+    title: str,
+    fallback_phone: str,
+    fallback_provider: str,
+    fallback_provider_user_id: str,
+    json_output: bool,
+) -> None:
+    """Print an identity challenge response."""
+    if json_output:
+        print_json(response)
+        return
+    table(
+        title,
+        ["Field", "Value"],
+        [
+            ["Phone", _value(response, "phone_e164") or fallback_phone],
+            ["Provider", _value(response, "provider_name") or fallback_provider],
+            ["Provider User", _value(response, "provider_user_id") or fallback_provider_user_id],
+            ["Expires", _value(response, "verification_expires_at")],
+            ["Magic Link", _value(response, "magic_link")],
+            ["Debug Code", _value(response, "debug_verification_code")],
+        ],
+    )
+
+
+def _print_resolution(
+    response: object,
+    *,
+    json_output: bool,
+    success_message: str,
+) -> None:
+    """Print an identity resolution response."""
+    if json_output:
+        print_json(response)
+        return
+    print_success(success_message)
+    table(
+        "Identity resolution",
+        ["Field", "Value"],
+        [
+            ["Phone", _value(response, "phone_e164")],
+            ["Provider", _value(response, "provider_name")],
+            ["Provider User", _value(response, "provider_user_id")],
+            ["Linked At", _value(response, "linked_at")],
+        ],
+    )
+
+
+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 _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/init.py

@@ -0,0 +1,55 @@
+"""Starter agent scaffold command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from platform_cli.errors import CLIError
+from platform_cli.openapi import scaffold_basic_agent
+from platform_cli.output import print_success, print_warning, table
+
+
+def init(
+    name: Annotated[str, typer.Argument(help="Agent/project name, such as dayplan.")],
+    output_dir: Annotated[Path | None, typer.Option(help="Output directory.")] = None,
+    display_name: Annotated[str | None, typer.Option(help="Tenant-facing display name.")] = None,
+    description: Annotated[
+        str | None,
+        typer.Option(help="Agent purpose shown in SOUL.md and the handoff prompt."),
+    ] = None,
+    tool: Annotated[
+        list[str] | None,
+        typer.Option("--tool", help="Builtin tool ID to enable, for example web_search."),
+    ] = None,
+    force: Annotated[bool, typer.Option(help="Overwrite existing starter files.")] = False,
+) -> None:
+    """Create a starter genaug-agent.yaml workspace without an OpenAPI spec."""
+    try:
+        result = scaffold_basic_agent(
+            name=name,
+            output_dir=output_dir,
+            display_name=display_name,
+            description=description,
+            builtin_tools=tool,
+            force=force,
+        )
+    except FileExistsError as exc:
+        raise CLIError(str(exc)) from exc
+    rows: list[list[object]] = [
+        ["Manifest", result.config_path],
+        ["Personality", result.soul_path],
+        ["Skills", result.skills_dir],
+        ["Tools", result.tools_dir],
+        ["Handoff", result.agent_prompt_path],
+    ]
+    table("Starter agent scaffold", ["File", "Path"], rows)
+    print_success(f"Generated starter agent in {result.root}")
+    if result.builtin_tools:
+        print_success(f"Enabled builtin tools: {', '.join(result.builtin_tools)}")
+    else:
+        print_warning("No builtin tools enabled yet. Use --tool or genaug tools toggle later.")
+    typer.echo(f"Next: genaug dev {result.config_path} --message \"What can you help me with?\"")
+    typer.echo(f"Then: genaug deploy {result.config_path}")