kctl-api 0.2.0__py3-none-any.whl

kctl_api/commands/routes_cmd.py

@@ -0,0 +1,277 @@
+"""Route introspection commands for kctl-api.
+
+Inspect endpoints, auth requirements, and middleware chains from the OpenAPI spec.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_api.core.callbacks import AppContext
+
+app = typer.Typer(
+    name="routes", help="Endpoint introspection — list, auth, middleware, unprotected.", no_args_is_help=True
+)
+
+_AUTH_KEYWORDS = ("bearer", "api_key", "apikey", "oauth", "security", "authorization")
+
+
+def _fetch_spec(actx: AppContext) -> dict:
+    data = actx.client.get("/openapi.json")
+    if not data:
+        raise RuntimeError("Empty response from /openapi.json")
+    return data
+
+
+def _is_protected(operation: dict) -> bool:
+    """Return True if the operation has a security requirement."""
+    security = operation.get("security")
+    if security is not None:
+        return bool(security)  # empty list [] means explicitly no auth
+    return False
+
+
+def _extract_routes(spec: dict) -> list[dict]:
+    """Extract all routes from an OpenAPI spec."""
+    routes = []
+    for path, path_item in spec.get("paths", {}).items():
+        for method, operation in path_item.items():
+            if method not in ("get", "post", "put", "patch", "delete", "head", "options"):
+                continue
+            routes.append(
+                {
+                    "method": method.upper(),
+                    "path": path,
+                    "operation_id": operation.get("operationId", ""),
+                    "summary": operation.get("summary", ""),
+                    "tags": operation.get("tags", []),
+                    "protected": _is_protected(operation),
+                    "security": operation.get("security", []),
+                    "deprecated": operation.get("deprecated", False),
+                }
+            )
+    return routes
+
+
+# ---------------------------------------------------------------------------
+# list
+# ---------------------------------------------------------------------------
+@app.command(name="list")
+def list_routes(ctx: typer.Context) -> None:
+    """List all API endpoints with methods, paths, and auth status."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        spec = _fetch_spec(actx)
+    except Exception as e:
+        out.error(f"Failed to fetch spec: {e}")
+        raise typer.Exit(1) from None
+
+    routes = _extract_routes(spec)
+
+    rows = [
+        [
+            r["method"],
+            r["path"],
+            "[green]yes[/green]" if r["protected"] else "[yellow]no[/yellow]",
+            "[red]deprecated[/red]" if r["deprecated"] else "",
+            ", ".join(r["tags"]),
+            r["summary"][:60],
+        ]
+        for r in routes
+    ]
+
+    out.table(
+        title=f"API Routes ({len(routes)})",
+        columns=[
+            ("Method", "bold"),
+            ("Path", ""),
+            ("Auth", ""),
+            ("Status", ""),
+            ("Tags", ""),
+            ("Summary", ""),
+        ],
+        rows=rows,
+        data_for_json=routes,
+    )
+
+
+# ---------------------------------------------------------------------------
+# auth
+# ---------------------------------------------------------------------------
+@app.command()
+def auth(ctx: typer.Context) -> None:
+    """Group endpoints by authentication requirement."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        spec = _fetch_spec(actx)
+    except Exception as e:
+        out.error(f"Failed to fetch spec: {e}")
+        raise typer.Exit(1) from None
+
+    routes = _extract_routes(spec)
+    protected = [r for r in routes if r["protected"]]
+    unprotected = [r for r in routes if not r["protected"]]
+
+    # Get security scheme names from components
+    security_schemes = list(spec.get("components", {}).get("securitySchemes", {}).keys())
+
+    out.header(f"Authentication Summary ({len(routes)} total routes)")
+    out.text("")
+    out.text(f"  Protected:   [green]{len(protected)}[/green]")
+    out.text(f"  Unprotected: [yellow]{len(unprotected)}[/yellow]")
+    if security_schemes:
+        out.text(f"  Schemes:     {', '.join(security_schemes)}")
+    out.text("")
+
+    if protected:
+        rows = [[r["method"], r["path"], ", ".join(str(s) for s in r["security"])] for r in protected]
+        out.table(
+            title=f"Protected Endpoints ({len(protected)})",
+            columns=[("Method", "bold"), ("Path", ""), ("Security", "green")],
+            rows=rows,
+            data_for_json=protected,
+        )
+
+    if actx.json_mode:
+        out.raw_json({"protected": protected, "unprotected": unprotected, "schemes": security_schemes})
+
+
+# ---------------------------------------------------------------------------
+# middleware
+# ---------------------------------------------------------------------------
+@app.command()
+def middleware(
+    ctx: typer.Context,
+    path: Annotated[str, typer.Argument(help="Endpoint path to inspect (e.g. /api/v1/users).")],
+) -> None:
+    """Describe the middleware chain for a specific endpoint path."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        spec = _fetch_spec(actx)
+    except Exception as e:
+        out.error(f"Failed to fetch spec: {e}")
+        raise typer.Exit(1) from None
+
+    paths = spec.get("paths", {})
+    matched = {k: v for k, v in paths.items() if path in k}
+
+    if not matched:
+        out.warn(f"No endpoints matching '{path}' found in spec.")
+        raise typer.Exit(1)
+
+    # Infer middleware from path patterns and security
+    chain: list[dict] = []
+
+    # CORS — always present
+    chain.append({"middleware": "CORS", "status": "enabled", "note": "All origins policy from config"})
+
+    # Auth middleware
+    for _ep_path, path_item in matched.items():
+        for method, operation in path_item.items():
+            if method not in ("get", "post", "put", "patch", "delete"):
+                continue
+            if _is_protected(operation):
+                chain.append({"middleware": "JWT Auth", "status": "enabled", "note": "Bearer token required"})
+                break
+
+    # Rate limiting — always present
+    chain.append(
+        {
+            "middleware": "Rate Limit",
+            "status": "enabled",
+            "note": "Tier-based: free=30, user=100, premium=300, admin=600 req/min",
+        }
+    )
+
+    # Request validation
+    chain.append(
+        {"middleware": "Request Validation", "status": "enabled", "note": "Pydantic body + query param validation"}
+    )
+
+    rows = [[c["middleware"], c["status"], c["note"]] for c in chain]
+    out.table(
+        title=f"Middleware Chain: {path}",
+        columns=[("Middleware", "bold"), ("Status", "green"), ("Note", "")],
+        rows=rows,
+        data_for_json={"path": path, "chain": chain},
+    )
+
+
+# ---------------------------------------------------------------------------
+# unprotected
+# ---------------------------------------------------------------------------
+@app.command()
+def unprotected(ctx: typer.Context) -> None:
+    """Find endpoints without authentication requirements."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        spec = _fetch_spec(actx)
+    except Exception as e:
+        out.error(f"Failed to fetch spec: {e}")
+        raise typer.Exit(1) from None
+
+    routes = _extract_routes(spec)
+    unprotected_routes = [r for r in routes if not r["protected"]]
+
+    # Filter out common public endpoints
+    public_patterns = ("/health", "/openapi", "/docs", "/redoc", "/metrics")
+    flagged = [r for r in unprotected_routes if not any(r["path"].startswith(p) for p in public_patterns)]
+
+    if not flagged:
+        out.success(
+            f"All non-public endpoints require authentication. ({len(unprotected_routes)} public endpoints skipped)"
+        )
+        return
+
+    rows = [[r["method"], r["path"], ", ".join(r["tags"]), r["summary"][:60]] for r in flagged]
+    out.table(
+        title=f"Potentially Unprotected Endpoints ({len(flagged)})",
+        columns=[("Method", "bold"), ("Path", "yellow"), ("Tags", ""), ("Summary", "")],
+        rows=rows,
+        data_for_json=flagged,
+    )
+    out.warn(f"{len(flagged)} endpoints may be missing authentication.")
+
+
+# ---------------------------------------------------------------------------
+# graph
+# ---------------------------------------------------------------------------
+@app.command()
+def graph(ctx: typer.Context) -> None:
+    """Show route count per tag/module/router."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        spec = _fetch_spec(actx)
+    except Exception as e:
+        out.error(f"Failed to fetch spec: {e}")
+        raise typer.Exit(1) from None
+
+    routes = _extract_routes(spec)
+
+    # Count by tag
+    tag_counts: dict[str, int] = {}
+    for route in routes:
+        for tag in route["tags"] or ["(untagged)"]:
+            tag_counts[tag] = tag_counts.get(tag, 0) + 1
+
+    sorted_tags = sorted(tag_counts.items(), key=lambda x: -x[1])
+
+    rows = [[tag, str(count), "#" * min(count, 40)] for tag, count in sorted_tags]
+    out.table(
+        title=f"Routes per Module ({len(routes)} total)",
+        columns=[("Module/Tag", "bold"), ("Count", ""), ("Bar", "green")],
+        rows=rows,
+        data_for_json=[{"tag": t, "count": c} for t, c in sorted_tags],
+    )

kctl_api/commands/saas.py

@@ -0,0 +1,145 @@
+"""SaaS management commands for kctl-api.
+
+Create tenants, check status, and manage plans.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_api.core.callbacks import AppContext
+from kctl_api.core.exceptions import APIError, AuthenticationError
+from kctl_api.core.exceptions import ConnectionError as KctlConnectionError
+
+app = typer.Typer(name="saas", help="SaaS tenant management — create, status, plans.", no_args_is_help=True)
+
+_BASE = "/api/v1/saas"
+
+
+# ---------------------------------------------------------------------------
+# create
+# ---------------------------------------------------------------------------
+@app.command()
+def create(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Option("--name", "-n", help="Tenant name.")],
+    plan: Annotated[str, typer.Option("--plan", "-p", help="Plan ID or slug.")] = "free",
+) -> None:
+    """Create a new SaaS tenant via POST /api/v1/saas/tenants."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        result = actx.client.post(f"{_BASE}/tenants", json={"name": name, "plan": plan})
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    out.success(f"Tenant created: {name}")
+    if actx.json_mode:
+        out.raw_json(result)
+
+
+# ---------------------------------------------------------------------------
+# status
+# ---------------------------------------------------------------------------
+@app.command()
+def status(
+    ctx: typer.Context,
+    tenant_id: Annotated[str, typer.Argument(help="Tenant ID.")],
+) -> None:
+    """Get tenant provisioning status via GET /api/v1/saas/tenants/{slug}/status."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        data = actx.client.get(f"{_BASE}/tenants/{tenant_id}/status")
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    if not data:
+        out.error(f"Tenant not found: {tenant_id}")
+        raise typer.Exit(1)
+
+    out.detail(
+        title=f"Tenant: {data.get('name', tenant_id)}",
+        sections=[
+            ("Details", [(k, str(v)) for k, v in data.items()]),
+        ],
+        data_for_json=data,
+    )
+
+
+# ---------------------------------------------------------------------------
+# select-plan
+# ---------------------------------------------------------------------------
+@app.command(name="select-plan")
+def select_plan(
+    ctx: typer.Context,
+    tenant_id: Annotated[str, typer.Argument(help="Tenant ID.")],
+    plan: Annotated[str, typer.Argument(help="Plan ID or slug to switch to.")],
+) -> None:
+    """Change tenant plan via POST /api/v1/saas/tenants/{slug}/select-plan."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        result = actx.client.post(f"{_BASE}/tenants/{tenant_id}/select-plan", json={"plan": plan})
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    out.success(f"Tenant {tenant_id} plan changed to {plan}.")
+    if actx.json_mode:
+        out.raw_json(result)
+
+
+# ---------------------------------------------------------------------------
+# list
+# ---------------------------------------------------------------------------
+@app.command(name="list")
+def list_tenants(
+    ctx: typer.Context,
+    page: Annotated[int, typer.Option("--page", "-p", help="Page number.")] = 1,
+    per_page: Annotated[int, typer.Option("--per-page", "-n", help="Items per page.")] = 20,
+) -> None:
+    """List SaaS tenants via GET /api/v1/saas/tenants."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        data = actx.client.get(f"{_BASE}/tenants", params={"page": page, "per_page": per_page})
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    items = data.get("items", []) if isinstance(data, dict) else []
+    total = data.get("total", len(items)) if isinstance(data, dict) else len(items)
+
+    rows: list[list[str]] = []
+    for t in items:
+        rows.append(
+            [
+                str(t.get("id", "")),
+                t.get("name", ""),
+                t.get("plan", ""),
+                t.get("status", ""),
+                str(t.get("created_at", "")),
+            ]
+        )
+
+    out.table(
+        title=f"SaaS Tenants (page {page}, {total} total)",
+        columns=[
+            ("ID", "bold"),
+            ("Name", ""),
+            ("Plan", ""),
+            ("Status", ""),
+            ("Created", "dim"),
+        ],
+        rows=rows,
+        data_for_json=items,
+    )