kctl-api 0.2.0__py3-none-any.whl

kctl_api/commands/tenant_ai.py

@@ -0,0 +1,169 @@
+"""Tenant AI commands for kctl-api.
+
+Per-tenant AI chat, streaming, history, and usage tracking.
+"""
+
+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="tenant-ai", help="Tenant AI — chat, stream, history, usage.", no_args_is_help=True)
+
+_BASE = "/api/v1/tenant-ai"
+
+
+# ---------------------------------------------------------------------------
+# chat
+# ---------------------------------------------------------------------------
+@app.command()
+def chat(
+    ctx: typer.Context,
+    message: Annotated[str, typer.Argument(help="Message to send.")],
+    tenant_id: Annotated[str | None, typer.Option("--tenant", "-t", help="Tenant ID.")] = None,
+) -> None:
+    """Send a chat message to the tenant AI via POST /api/v1/tenant-ai/chat."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    payload: dict = {"message": message}
+    if tenant_id:
+        payload["tenant_id"] = tenant_id
+
+    try:
+        result = actx.client.post(f"{_BASE}/chat", json=payload)
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    if actx.json_mode:
+        out.raw_json(result)
+    else:
+        reply = result.get("reply", result.get("message", "")) if isinstance(result, dict) else str(result)
+        out.text(reply)
+
+
+# ---------------------------------------------------------------------------
+# stream
+# ---------------------------------------------------------------------------
+@app.command()
+def stream(
+    ctx: typer.Context,
+    message: Annotated[str, typer.Argument(help="Message to send.")],
+    tenant_id: Annotated[str | None, typer.Option("--tenant", "-t", help="Tenant ID.")] = None,
+) -> None:
+    """Stream a chat response from the tenant AI via POST /api/v1/tenant-ai/chat/stream.
+
+    Note: Currently sends a blocking request. True SSE streaming will be added in a future version.
+    """
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    payload: dict = {"message": message}
+    if tenant_id:
+        payload["tenant_id"] = tenant_id
+
+    try:
+        result = actx.client.post(f"{_BASE}/chat/stream", json=payload)
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    if actx.json_mode:
+        out.raw_json(result)
+    else:
+        reply = result.get("reply", result.get("message", "")) if isinstance(result, dict) else str(result)
+        out.text(reply)
+
+
+# ---------------------------------------------------------------------------
+# history
+# ---------------------------------------------------------------------------
+@app.command()
+def history(
+    ctx: typer.Context,
+    tenant_id: Annotated[str | None, typer.Option("--tenant", "-t", help="Tenant ID.")] = None,
+    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 tenant AI conversation history via GET /api/v1/tenant-ai/history."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    params: dict[str, str | int] = {"page": page, "per_page": per_page}
+    if tenant_id:
+        params["tenant_id"] = tenant_id
+
+    try:
+        data = actx.client.get(f"{_BASE}/history", params=params)
+    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 h in items:
+        rows.append(
+            [
+                str(h.get("id", "")),
+                h.get("tenant_id", ""),
+                str(h.get("message_count", "")),
+                str(h.get("tokens_used", "")),
+                str(h.get("created_at", "")),
+            ]
+        )
+
+    out.table(
+        title=f"Tenant AI History (page {page}, {total} total)",
+        columns=[
+            ("ID", "bold"),
+            ("Tenant", ""),
+            ("Messages", ""),
+            ("Tokens", ""),
+            ("Created", "dim"),
+        ],
+        rows=rows,
+        data_for_json=items,
+    )
+
+
+# ---------------------------------------------------------------------------
+# usage
+# ---------------------------------------------------------------------------
+@app.command()
+def usage(
+    ctx: typer.Context,
+    tenant_id: Annotated[str | None, typer.Option("--tenant", "-t", help="Tenant ID.")] = None,
+) -> None:
+    """Get tenant AI usage statistics via GET /api/v1/tenant-ai/usage."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    params: dict[str, str] = {}
+    if tenant_id:
+        params["tenant_id"] = tenant_id
+
+    try:
+        data = actx.client.get(f"{_BASE}/usage", params=params)
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    if not data:
+        out.info("No usage data available.")
+        return
+
+    out.detail(
+        title="Tenant AI Usage",
+        sections=[
+            ("Usage", [(k, str(v)) for k, v in data.items()]),
+        ],
+        data_for_json=data,
+    )

kctl_api/commands/test_cmd.py

@@ -0,0 +1,95 @@
+"""Test runner commands for kctl-api.
+
+Run pytest for specific apps or the entire workspace.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Annotated
+
+import typer
+
+from kctl_api.core.callbacks import AppContext
+from kctl_api.core.utils import find_project_root
+
+app = typer.Typer(name="test", help="Test runner — run, coverage, watch.", no_args_is_help=True)
+
+
+# ---------------------------------------------------------------------------
+# run
+# ---------------------------------------------------------------------------
+@app.command()
+def run(
+    ctx: typer.Context,
+    app_name: Annotated[str, typer.Argument(help="App name or 'all'.")] = "all",
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Verbose output.")] = False,
+    marker: Annotated[str | None, typer.Option("--marker", "-m", help="Pytest marker expression.")] = None,
+    keyword: Annotated[str | None, typer.Option("--keyword", "-k", help="Pytest keyword expression.")] = None,
+) -> None:
+    """Run tests via scripts/test."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    root = find_project_root()
+    cmd = [str(root / "scripts" / "test"), app_name]
+    if verbose:
+        cmd.append("-v")
+    if marker:
+        cmd.extend(["-m", marker])
+    if keyword:
+        cmd.extend(["-k", keyword])
+
+    out.info(f"Running tests for: {app_name}")
+    result = subprocess.run(cmd, cwd=str(root), capture_output=False)
+    if result.returncode != 0:
+        out.error("Tests failed.")
+        raise typer.Exit(result.returncode)
+    out.success("Tests passed.")
+
+
+# ---------------------------------------------------------------------------
+# coverage
+# ---------------------------------------------------------------------------
+@app.command()
+def coverage(
+    ctx: typer.Context,
+    app_name: Annotated[str, typer.Argument(help="App name or 'all'.")] = "all",
+) -> None:
+    """Run tests with coverage report via scripts/test --cov."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    root = find_project_root()
+    cmd = [str(root / "scripts" / "test"), app_name, "--cov"]
+
+    out.info(f"Running tests with coverage for: {app_name}")
+    result = subprocess.run(cmd, cwd=str(root), capture_output=False)
+    if result.returncode != 0:
+        out.error("Tests failed.")
+        raise typer.Exit(result.returncode)
+    out.success("Coverage report generated.")
+
+
+# ---------------------------------------------------------------------------
+# watch
+# ---------------------------------------------------------------------------
+@app.command()
+def watch(
+    ctx: typer.Context,
+    app_name: Annotated[str, typer.Argument(help="App name or 'all'.")] = "all",
+) -> None:
+    """Run tests in watch mode (requires pytest-watch)."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    root = find_project_root()
+
+    out.info(f"Starting test watcher for: {app_name}")
+    app_dir = root / "apps" / app_name if app_name != "all" else root
+    cmd = ["ptw", "--", str(app_dir)]
+    try:
+        subprocess.run(cmd, cwd=str(root), capture_output=False)
+    except FileNotFoundError:
+        out.error("pytest-watch (ptw) not found. Install with: uv pip install pytest-watch")
+        raise typer.Exit(1) from None

kctl_api/commands/users.py

@@ -0,0 +1,302 @@
+"""User management commands for kctl-api.
+
+CRUD operations on users, role and tier assignment.
+"""
+
+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
+from kctl_api.core.resolve import resolve_user, resolve_user_id
+from kctl_api.core.utils import role_color, tier_color
+
+app = typer.Typer(
+    name="users", help="User management — list, create, update, delete, roles, tiers.", no_args_is_help=True
+)
+
+
+# ---------------------------------------------------------------------------
+# list
+# ---------------------------------------------------------------------------
+@app.command(name="list")
+def list_users(
+    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,
+    search: Annotated[str | None, typer.Option("--search", "-s", help="Search by name or email.")] = None,
+) -> None:
+    """List users with pagination and optional search."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        params: dict[str, str | int] = {"page": page, "per_page": per_page}
+        if search:
+            params["search"] = search
+        data = actx.client.get("/api/v1/users", params=params)
+    except AuthenticationError as e:
+        out.error(f"Auth failed: {e}")
+        raise typer.Exit(1) from None
+    except KctlConnectionError as e:
+        out.error(f"Connection failed: {e}")
+        raise typer.Exit(1) from None
+    except APIError as e:
+        out.error(f"API error: {e.detail}")
+        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 u in items:
+        rows.append(
+            [
+                str(u.get("id", "")),
+                u.get("email", ""),
+                u.get("name", u.get("full_name", "")),
+                role_color(u.get("role", "")),
+                tier_color(u.get("tier", "")),
+                "[green]yes[/green]" if u.get("is_active") else "[red]no[/red]",
+            ]
+        )
+
+    out.table(
+        title=f"Users (page {page}, {total} total)",
+        columns=[
+            ("ID", "bold"),
+            ("Email", ""),
+            ("Name", ""),
+            ("Role", ""),
+            ("Tier", ""),
+            ("Active", ""),
+        ],
+        rows=rows,
+        data_for_json=items,
+    )
+
+
+# ---------------------------------------------------------------------------
+# get
+# ---------------------------------------------------------------------------
+@app.command()
+def get(
+    ctx: typer.Context,
+    identifier: Annotated[str, typer.Argument(help="User ID or email.")],
+) -> None:
+    """Get detailed user information by ID or email."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        user = resolve_user(actx.client, identifier)
+    except typer.Exit:
+        raise
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    role = user.get("role", "unknown")
+    tier = user.get("tier", "unknown")
+
+    out.detail(
+        title=f"User: {user.get('email', identifier)}",
+        sections=[
+            (
+                "Identity",
+                [
+                    ("ID", str(user.get("id", ""))),
+                    ("Email", user.get("email", "")),
+                    ("Name", user.get("name", user.get("full_name", ""))),
+                ],
+            ),
+            (
+                "Access",
+                [
+                    ("Role", role_color(role)),
+                    ("Tier", tier_color(tier)),
+                    ("Active", str(user.get("is_active", ""))),
+                ],
+            ),
+            (
+                "Timestamps",
+                [
+                    ("Created", str(user.get("created_at", ""))),
+                    ("Updated", str(user.get("updated_at", ""))),
+                ],
+            ),
+        ],
+        data_for_json=user,
+    )
+
+
+# ---------------------------------------------------------------------------
+# create
+# ---------------------------------------------------------------------------
+@app.command()
+def create(
+    ctx: typer.Context,
+    email: Annotated[str, typer.Option("--email", "-e", help="User email.")],
+    name: Annotated[str, typer.Option("--name", "-n", help="User full name.")],
+    password: Annotated[
+        str | None, typer.Option("--password", help="Password (prompted if omitted).", hide_input=True)
+    ] = None,
+) -> None:
+    """Create a new user via POST /api/v1/auth/register."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    if not password:
+        password = typer.prompt("Password", hide_input=True)
+
+    try:
+        result = actx.client.post(
+            "/api/v1/auth/register",
+            json={"email": email, "name": name, "password": password},
+        )
+    except AuthenticationError as e:
+        out.error(f"Auth failed: {e}")
+        raise typer.Exit(1) from None
+    except KctlConnectionError as e:
+        out.error(f"Connection failed: {e}")
+        raise typer.Exit(1) from None
+    except APIError as e:
+        out.error(f"API error: {e.detail}")
+        raise typer.Exit(1) from None
+
+    out.success(f"User created: {email}")
+    if actx.json_mode:
+        out.raw_json(result)
+
+
+# ---------------------------------------------------------------------------
+# update
+# ---------------------------------------------------------------------------
+@app.command()
+def update(
+    ctx: typer.Context,
+    identifier: Annotated[str, typer.Argument(help="User ID or email.")],
+    name: Annotated[str | None, typer.Option("--name", "-n", help="New name.")] = None,
+    email: Annotated[str | None, typer.Option("--email", "-e", help="New email.")] = None,
+) -> None:
+    """Update user fields via PATCH /api/v1/users/{id}."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    user_id = resolve_user_id(actx.client, identifier)
+    payload: dict[str, str] = {}
+    if name:
+        payload["name"] = name
+    if email:
+        payload["email"] = email
+
+    if not payload:
+        out.warn("No fields to update. Use --name or --email.")
+        raise typer.Exit(0)
+
+    try:
+        result = actx.client.patch(f"/api/v1/users/{user_id}", json=payload)
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    out.success(f"User {user_id} updated.")
+    if actx.json_mode:
+        out.raw_json(result)
+
+
+# ---------------------------------------------------------------------------
+# delete
+# ---------------------------------------------------------------------------
+@app.command()
+def delete(
+    ctx: typer.Context,
+    identifier: Annotated[str, typer.Argument(help="User ID or email.")],
+    force: Annotated[bool, typer.Option("--force", "-f", help="Skip confirmation.")] = False,
+) -> None:
+    """Soft-delete a user via DELETE /api/v1/users/{id}."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    user_id = resolve_user_id(actx.client, identifier)
+
+    if not force:
+        confirm = typer.confirm(f"Delete user {identifier} (id={user_id})?", default=False)
+        if not confirm:
+            out.info("Cancelled.")
+            raise typer.Exit(0)
+
+    try:
+        result = actx.client.delete(f"/api/v1/users/{user_id}")
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    out.success(f"User {user_id} deleted.")
+    if actx.json_mode:
+        out.raw_json(result)
+
+
+# ---------------------------------------------------------------------------
+# set-role
+# ---------------------------------------------------------------------------
+@app.command(name="set-role")
+def set_role(
+    ctx: typer.Context,
+    identifier: Annotated[str, typer.Argument(help="User ID or email.")],
+    role: Annotated[str, typer.Argument(help="Role: user or admin.")],
+) -> None:
+    """Set user role via PATCH /api/v1/users/{id}."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    if role not in ("user", "admin"):
+        out.error(f"Invalid role '{role}'. Must be 'user' or 'admin'.")
+        raise typer.Exit(1)
+
+    user_id = resolve_user_id(actx.client, identifier)
+
+    try:
+        result = actx.client.patch(f"/api/v1/users/{user_id}", json={"role": role})
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    out.success(f"User {user_id} role set to {role}.")
+    if actx.json_mode:
+        out.raw_json(result)
+
+
+# ---------------------------------------------------------------------------
+# set-tier
+# ---------------------------------------------------------------------------
+@app.command(name="set-tier")
+def set_tier(
+    ctx: typer.Context,
+    identifier: Annotated[str, typer.Argument(help="User ID or email.")],
+    tier: Annotated[str, typer.Argument(help="Tier: free, user, premium, admin.")],
+) -> None:
+    """Set user tier via PATCH /api/v1/users/{id}."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    valid_tiers = ("free", "user", "premium", "admin")
+    if tier not in valid_tiers:
+        out.error(f"Invalid tier '{tier}'. Must be one of: {', '.join(valid_tiers)}")
+        raise typer.Exit(1)
+
+    user_id = resolve_user_id(actx.client, identifier)
+
+    try:
+        result = actx.client.patch(f"/api/v1/users/{user_id}", json={"tier": tier})
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    out.success(f"User {user_id} tier set to {tier}.")
+    if actx.json_mode:
+        out.raw_json(result)

kctl_api/commands/webhooks.py

@@ -0,0 +1,56 @@
+"""Webhook management commands for kctl-api.
+
+View recent webhooks, replay, and verify signatures.
+Note: These commands require webhook audit endpoints on api-main (not yet implemented).
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_api.core.callbacks import AppContext
+
+app = typer.Typer(name="webhooks", help="Webhook management — recent, replay, verify.", no_args_is_help=True)
+
+
+# ---------------------------------------------------------------------------
+# recent
+# ---------------------------------------------------------------------------
+@app.command()
+def recent(
+    ctx: typer.Context,
+    limit: Annotated[int, typer.Option("--limit", "-n", help="Number of recent webhooks.")] = 20,
+    source: Annotated[str | None, typer.Option("--source", "-s", help="Filter by source (github, chatwoot).")] = None,
+) -> None:
+    """List recent webhook deliveries (requires webhook audit API — not yet available)."""
+    actx: AppContext = ctx.obj
+    actx.output.warn("Webhook audit endpoints are not yet implemented on api-main.")
+    actx.output.info("Available webhook endpoints: POST /webhooks/mattermost, /telegram, /generic/{source}")
+
+
+# ---------------------------------------------------------------------------
+# replay
+# ---------------------------------------------------------------------------
+@app.command()
+def replay(
+    ctx: typer.Context,
+    webhook_id: Annotated[str, typer.Argument(help="Webhook delivery ID to replay.")],
+) -> None:
+    """Replay a webhook delivery (requires webhook audit API — not yet available)."""
+    actx: AppContext = ctx.obj
+    actx.output.warn("Webhook replay is not yet implemented on api-main.")
+
+
+# ---------------------------------------------------------------------------
+# verify
+# ---------------------------------------------------------------------------
+@app.command()
+def verify(
+    ctx: typer.Context,
+    source: Annotated[str, typer.Argument(help="Webhook source to verify (github, chatwoot).")],
+) -> None:
+    """Verify webhook signature configuration (requires webhook audit API — not yet available)."""
+    actx: AppContext = ctx.obj
+    actx.output.warn("Webhook verification is not yet implemented on api-main.")