kctl-api 0.2.0__py3-none-any.whl

kctl_api/commands/shell.py

@@ -0,0 +1,197 @@
+"""Interactive shell command for kctl-api.
+
+Start a Python REPL with pre-loaded context.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from kctl_api.core.callbacks import AppContext
+
+app = typer.Typer(name="shell", help="Interactive Python REPL with API context.", no_args_is_help=False)
+
+
+# ---------------------------------------------------------------------------
+# start
+# ---------------------------------------------------------------------------
+@app.command()
+def start(ctx: typer.Context) -> None:
+    """Start an interactive Python REPL with pre-loaded API client and helpers."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    out.info("Starting interactive shell ...")
+    out.info("Available objects: client, ai_client, actx, out")
+
+    namespace = {
+        "actx": actx,
+        "client": actx.client,
+        "out": actx.output,
+    }
+
+    # Try ai_client lazily to avoid connection errors at startup
+    try:
+        namespace["ai_client"] = actx.ai_client
+    except Exception:
+        namespace["ai_client"] = None
+
+    try:
+        import IPython
+
+        IPython.start_ipython(argv=[], user_ns=namespace)
+    except ImportError:
+        import code
+
+        code.interact(
+            banner="kctl-api shell (use 'client', 'ai_client', 'actx', 'out')",
+            local=namespace,
+        )
+
+
+# ---------------------------------------------------------------------------
+# db
+# ---------------------------------------------------------------------------
+@app.command()
+def db(ctx: typer.Context) -> None:
+    """Start a Python REPL with an async SQLAlchemy DB session pre-loaded."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    db_url = actx.database_url
+    if not db_url:
+        out.error("No database_url configured.")
+        raise typer.Exit(1)
+
+    out.info("Starting DB shell ...")
+    out.info("Available: db (AsyncSession), execute_query, dispose_engine")
+
+    async def _get_session():  # type: ignore[return]
+        from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+        from sqlalchemy.orm import sessionmaker
+
+        engine = create_async_engine(db_url)
+        async_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)  # type: ignore[call-overload]
+        return async_session()
+
+    import asyncio
+
+    session = asyncio.run(_get_session())
+
+    namespace = {
+        "actx": actx,
+        "out": out,
+        "session": session,
+        "db": session,
+        "asyncio": asyncio,
+    }
+
+    banner = (
+        "kctl-api db shell\n"
+        "Available: session (AsyncSession), db (alias), asyncio\n"
+        "Example:   asyncio.run(session.execute(text('SELECT 1')))"
+    )
+
+    try:
+        import IPython
+
+        IPython.start_ipython(argv=[], user_ns=namespace)
+    except ImportError:
+        import code
+
+        code.interact(banner=banner, local=namespace)
+    finally:
+        asyncio.run(session.close())
+
+
+# ---------------------------------------------------------------------------
+# redis
+# ---------------------------------------------------------------------------
+@app.command()
+def redis(ctx: typer.Context) -> None:
+    """Start a Python REPL with a Redis async client pre-loaded."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    redis_url = actx.redis_url
+    if not redis_url:
+        out.error("No redis_url configured.")
+        raise typer.Exit(1)
+
+    out.info("Starting Redis shell ...")
+    out.info("Available: r (Redis client), asyncio")
+
+    from kctl_api.core.redis import get_redis
+
+    r = get_redis(redis_url)
+
+    import asyncio
+
+    namespace = {
+        "actx": actx,
+        "out": out,
+        "r": r,
+        "redis": r,
+        "asyncio": asyncio,
+    }
+
+    banner = "kctl-api redis shell\nAvailable: r (Redis client), asyncio\nExample:   asyncio.run(r.info())"
+
+    try:
+        import IPython
+
+        IPython.start_ipython(argv=[], user_ns=namespace)
+    except ImportError:
+        import code
+
+        code.interact(banner=banner, local=namespace)
+
+
+# ---------------------------------------------------------------------------
+# api
+# ---------------------------------------------------------------------------
+@app.command()
+def api(ctx: typer.Context) -> None:
+    """Start a Python REPL with an httpx client pre-loaded for API calls."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    out.info("Starting API shell ...")
+    out.info("Available: client (ApiClient), http (httpx), base_url")
+
+    import httpx
+
+    base_url = actx.client.base_url
+    api_key = actx.client.api_key
+
+    http = httpx.Client(
+        base_url=base_url,
+        headers={"Authorization": f"Bearer {api_key}"} if api_key else {},
+        timeout=30,
+    )
+
+    namespace = {
+        "actx": actx,
+        "client": actx.client,
+        "http": http,
+        "httpx": httpx,
+        "base_url": base_url,
+        "out": out,
+    }
+
+    banner = (
+        f"kctl-api api shell — connected to {base_url}\n"
+        "Available: client (ApiClient), http (httpx.Client), base_url\n"
+        "Example:   http.get('/api/v1/health').json()"
+    )
+
+    try:
+        import IPython
+
+        IPython.start_ipython(argv=[], user_ns=namespace)
+    except ImportError:
+        import code
+
+        code.interact(banner=banner, local=namespace)
+    finally:
+        http.close()

kctl_api/commands/skill_cmd.py

@@ -0,0 +1,58 @@
+"""Skill generation for Claude Code integration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from kctl_api.core.callbacks import AppContext
+
+app = typer.Typer(help="Claude Code skill management.")
+
+
+@app.command()
+def generate(
+    ctx: typer.Context,
+    output: Annotated[str, typer.Option("--output", "-o", help="Output directory")] = "",
+    install: Annotated[bool, typer.Option("--install", help="Install to ~/.claude/skills/")] = False,
+) -> None:
+    """Auto-generate SKILL.md from CLI command registry."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    from kctl_lib.skill_generator import generate_skill
+
+    from kctl_api.cli import app as cli_app
+
+    skill_name = "api-admin"
+    description = "FastAPI platform management via kctl-api CLI"
+
+    # Canonical in-repo skill dir — source of SKILL.extra.md regardless
+    # of where output goes. Without this, --install writes to
+    # ~/.claude/skills/ and the handwritten runbook vanishes.
+    cli_root = Path(__file__).resolve().parents[3]
+    source_dir = cli_root / "skills" / skill_name
+
+    # Determine output directory
+    if output:
+        output_dir = Path(output)
+    elif install:
+        output_dir = Path.home() / ".claude" / "skills" / skill_name
+    else:
+        output_dir = source_dir
+
+    # Extra content always lives at the in-repo location.
+    extra = source_dir / "SKILL.extra.md"
+
+    generate_skill(
+        cli_app,
+        "kctl-api",
+        skill_name,
+        description,
+        output_dir=output_dir,
+        extra_file=extra if extra.exists() else None,
+    )
+    out.success(f"Generated {output_dir / 'SKILL.md'}")
+    if install:
+        out.success(f"Installed to ~/.claude/skills/{skill_name}/")

kctl_api/commands/streams.py

@@ -0,0 +1,309 @@
+"""Redis Streams management commands for kctl-api.
+
+List, read, trim, and manage dead-letter queues.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Annotated
+
+import typer
+
+from kctl_api.core.callbacks import AppContext
+
+app = typer.Typer(name="streams", help="Redis Streams — list, read, trim, dead-letter.", no_args_is_help=True)
+
+
+# ---------------------------------------------------------------------------
+# list
+# ---------------------------------------------------------------------------
+@app.command(name="list")
+def list_streams(ctx: typer.Context) -> None:
+    """List all Redis Streams via SCAN for stream-type keys."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    redis_url = actx.redis_url
+    if not redis_url:
+        out.error("No redis_url configured.")
+        raise typer.Exit(1)
+
+    async def _run() -> list[dict]:
+        from kctl_api.core.redis import close_redis, get_redis
+
+        try:
+            client = get_redis(redis_url)
+            streams: list[dict] = []
+            async for key in client.scan_iter(match="*", count=200):
+                key_type = await client.type(key)
+                if key_type == "stream":
+                    length = await client.xlen(key)
+                    streams.append({"name": key, "length": length})
+            return streams
+        finally:
+            await close_redis()
+
+    try:
+        streams = asyncio.run(_run())
+    except ImportError as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+    except Exception as e:
+        out.error(f"Redis error: {e}")
+        raise typer.Exit(1) from None
+
+    rows = [[s["name"], str(s["length"])] for s in streams]
+
+    out.table(
+        title=f"Redis Streams ({len(streams)})",
+        columns=[("Stream", "bold"), ("Length", "")],
+        rows=rows,
+        data_for_json=streams,
+    )
+
+
+# ---------------------------------------------------------------------------
+# read
+# ---------------------------------------------------------------------------
+@app.command()
+def read(
+    ctx: typer.Context,
+    stream_name: Annotated[str, typer.Argument(help="Stream name to read from.")],
+    count: Annotated[int, typer.Option("--count", "-n", help="Number of messages to read.")] = 10,
+    start: Annotated[str, typer.Option("--start", help="Start ID (default: oldest).")] = "0-0",
+) -> None:
+    """Read messages from a Redis Stream via XRANGE."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    redis_url = actx.redis_url
+    if not redis_url:
+        out.error("No redis_url configured.")
+        raise typer.Exit(1)
+
+    async def _run() -> list[dict]:
+        from kctl_api.core.redis import close_redis, get_redis
+
+        try:
+            client = get_redis(redis_url)
+            messages = await client.xrange(stream_name, min=start, count=count)
+            return [{"id": msg_id, "data": data} for msg_id, data in messages]
+        finally:
+            await close_redis()
+
+    try:
+        messages = asyncio.run(_run())
+    except Exception as e:
+        out.error(f"Redis error: {e}")
+        raise typer.Exit(1) from None
+
+    if actx.json_mode:
+        out.raw_json(messages)
+    else:
+        for msg in messages:
+            out.text(f"[bold]{msg['id']}[/bold]")
+            for k, v in msg["data"].items():
+                out.kv(f"  {k}", str(v))
+        out.info(f"{len(messages)} message(s) read from '{stream_name}'.")
+
+
+# ---------------------------------------------------------------------------
+# trim
+# ---------------------------------------------------------------------------
+@app.command()
+def trim(
+    ctx: typer.Context,
+    stream_name: Annotated[str, typer.Argument(help="Stream name to trim.")],
+    maxlen: Annotated[int, typer.Option("--maxlen", "-n", help="Maximum stream length after trim.")] = 1000,
+    force: Annotated[bool, typer.Option("--force", "-f", help="Skip confirmation.")] = False,
+) -> None:
+    """Trim a Redis Stream to a maximum length via XTRIM."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    redis_url = actx.redis_url
+    if not redis_url:
+        out.error("No redis_url configured.")
+        raise typer.Exit(1)
+
+    if not force:
+        confirm = typer.confirm(f"Trim stream '{stream_name}' to maxlen={maxlen}?", default=False)
+        if not confirm:
+            out.info("Cancelled.")
+            raise typer.Exit(0)
+
+    async def _run() -> int:
+        from kctl_api.core.redis import close_redis, get_redis
+
+        try:
+            client = get_redis(redis_url)
+            return await client.xtrim(stream_name, maxlen=maxlen)
+        finally:
+            await close_redis()
+
+    try:
+        trimmed = asyncio.run(_run())
+    except Exception as e:
+        out.error(f"Redis error: {e}")
+        raise typer.Exit(1) from None
+
+    out.success(f"Trimmed {trimmed} message(s) from '{stream_name}'.")
+    if actx.json_mode:
+        out.raw_json({"stream": stream_name, "trimmed": trimmed, "maxlen": maxlen})
+
+
+# ---------------------------------------------------------------------------
+# dead-letter
+# ---------------------------------------------------------------------------
+@app.command(name="dead-letter")
+def dead_letter(
+    ctx: typer.Context,
+    stream_name: Annotated[str, typer.Argument(help="Dead-letter stream name.")] = "dead-letter",
+    count: Annotated[int, typer.Option("--count", "-n", help="Number of messages to read.")] = 20,
+) -> None:
+    """Read messages from the dead-letter stream."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    redis_url = actx.redis_url
+    if not redis_url:
+        out.error("No redis_url configured.")
+        raise typer.Exit(1)
+
+    async def _run() -> list[dict]:
+        from kctl_api.core.redis import close_redis, get_redis
+
+        try:
+            client = get_redis(redis_url)
+            messages = await client.xrange(stream_name, count=count)
+            return [{"id": msg_id, "data": data} for msg_id, data in messages]
+        finally:
+            await close_redis()
+
+    try:
+        messages = asyncio.run(_run())
+    except Exception as e:
+        out.error(f"Redis error: {e}")
+        raise typer.Exit(1) from None
+
+    if not messages:
+        out.info("Dead-letter stream is empty.")
+        if actx.json_mode:
+            out.raw_json([])
+        return
+
+    if actx.json_mode:
+        out.raw_json(messages)
+    else:
+        for msg in messages:
+            out.text(f"[bold red]{msg['id']}[/bold red]")
+            for k, v in msg["data"].items():
+                out.kv(f"  {k}", str(v))
+        out.warn(f"{len(messages)} dead-letter message(s).")
+
+
+# ---------------------------------------------------------------------------
+# replay
+# ---------------------------------------------------------------------------
+@app.command()
+def replay(
+    ctx: typer.Context,
+    source_stream: Annotated[str, typer.Argument(help="Source stream (dead-letter).")],
+    target_stream: Annotated[str, typer.Argument(help="Target stream to replay to.")],
+    count: Annotated[int, typer.Option("--count", "-n", help="Number of messages to replay.")] = 10,
+    force: Annotated[bool, typer.Option("--force", "-f", help="Skip confirmation.")] = False,
+) -> None:
+    """Replay messages from one stream to another via XRANGE + XADD."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    redis_url = actx.redis_url
+    if not redis_url:
+        out.error("No redis_url configured.")
+        raise typer.Exit(1)
+
+    if not force:
+        confirm = typer.confirm(f"Replay {count} messages from '{source_stream}' to '{target_stream}'?", default=False)
+        if not confirm:
+            out.info("Cancelled.")
+            raise typer.Exit(0)
+
+    async def _run() -> int:
+        from kctl_api.core.redis import close_redis, get_redis
+
+        try:
+            client = get_redis(redis_url)
+            messages = await client.xrange(source_stream, count=count)
+            replayed = 0
+            for _msg_id, data in messages:
+                await client.xadd(target_stream, data)
+                replayed += 1
+            return replayed
+        finally:
+            await close_redis()
+
+    try:
+        replayed = asyncio.run(_run())
+    except Exception as e:
+        out.error(f"Redis error: {e}")
+        raise typer.Exit(1) from None
+
+    out.success(f"Replayed {replayed} message(s) from '{source_stream}' to '{target_stream}'.")
+    if actx.json_mode:
+        out.raw_json({"source": source_stream, "target": target_stream, "replayed": replayed})
+
+
+# ---------------------------------------------------------------------------
+# consumers
+# ---------------------------------------------------------------------------
+@app.command()
+def consumers(
+    ctx: typer.Context,
+    stream_name: Annotated[str, typer.Argument(help="Stream name.")],
+    group: Annotated[str, typer.Argument(help="Consumer group name.")],
+) -> None:
+    """List consumers in a consumer group via XINFO CONSUMERS."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    redis_url = actx.redis_url
+    if not redis_url:
+        out.error("No redis_url configured.")
+        raise typer.Exit(1)
+
+    async def _run() -> list[dict]:
+        from kctl_api.core.redis import close_redis, get_redis
+
+        try:
+            client = get_redis(redis_url)
+            info = await client.xinfo_consumers(stream_name, group)
+            return [dict(c) for c in info] if info else []
+        finally:
+            await close_redis()
+
+    try:
+        consumer_list = asyncio.run(_run())
+    except Exception as e:
+        out.error(f"Redis error: {e}")
+        raise typer.Exit(1) from None
+
+    rows = [
+        [
+            str(c.get("name", "")),
+            str(c.get("pending", 0)),
+            str(c.get("idle", 0)),
+        ]
+        for c in consumer_list
+    ]
+
+    out.table(
+        title=f"Consumers: {stream_name} / {group}",
+        columns=[
+            ("Consumer", "bold"),
+            ("Pending", ""),
+            ("Idle (ms)", ""),
+        ],
+        rows=rows,
+        data_for_json=consumer_list,
+    )

kctl_api/commands/stripe_cmd.py

@@ -0,0 +1,105 @@
+"""Stripe integration commands for kctl-api.
+
+Checkout sessions, customer portal, and webhook status.
+"""
+
+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="stripe", help="Stripe integration — checkout, portal, webhooks.", no_args_is_help=True)
+
+_BASE = "/api/v1/stripe"
+
+
+# ---------------------------------------------------------------------------
+# checkout
+# ---------------------------------------------------------------------------
+@app.command()
+def checkout(
+    ctx: typer.Context,
+    price_id: Annotated[str, typer.Argument(help="Stripe Price ID.")],
+    success_url: Annotated[str, typer.Option("--success-url", help="Redirect URL on success.")] = "",
+    cancel_url: Annotated[str, typer.Option("--cancel-url", help="Redirect URL on cancel.")] = "",
+) -> None:
+    """Create a Stripe checkout session via POST /api/v1/stripe/checkout."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    payload: dict = {"price_id": price_id}
+    if success_url:
+        payload["success_url"] = success_url
+    if cancel_url:
+        payload["cancel_url"] = cancel_url
+
+    try:
+        result = actx.client.post(f"{_BASE}/checkout", json=payload)
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    checkout_url = result.get("url", "") if isinstance(result, dict) else ""
+    if checkout_url:
+        out.success(f"Checkout session created: {checkout_url}")
+    else:
+        out.success("Checkout session created.")
+    if actx.json_mode:
+        out.raw_json(result)
+
+
+# ---------------------------------------------------------------------------
+# portal
+# ---------------------------------------------------------------------------
+@app.command()
+def portal(ctx: typer.Context) -> None:
+    """Create a Stripe customer portal session via POST /api/v1/stripe/portal."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        result = actx.client.post(f"{_BASE}/portal")
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    portal_url = result.get("url", "") if isinstance(result, dict) else ""
+    if portal_url:
+        out.success(f"Portal session created: {portal_url}")
+    else:
+        out.success("Portal session created.")
+    if actx.json_mode:
+        out.raw_json(result)
+
+
+# ---------------------------------------------------------------------------
+# webhook-status
+# ---------------------------------------------------------------------------
+@app.command(name="webhook-status")
+def webhook_status(ctx: typer.Context) -> None:
+    """Check Stripe webhook endpoint status via GET /api/v1/stripe/webhook-status."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        data = actx.client.get(f"{_BASE}/webhook-status")
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    if not data:
+        out.info("No webhook status available.")
+        return
+
+    out.detail(
+        title="Stripe Webhook Status",
+        sections=[
+            ("Status", [(k, str(v)) for k, v in data.items()]),
+        ],
+        data_for_json=data,
+    )