PyPI - kater-cli - Versions diffs - 0.1.0__py3-none-any.whl - Mend

kater-cli 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

kater_cli/.gitkeep +0 -0
kater_cli/auth/__init__.py +6 -0
kater_cli/auth/oauth.py +211 -0
kater_cli/auth/token_manager.py +338 -0
kater_cli/client.py +82 -0
kater_cli/commands/.gitkeep +0 -0
kater_cli/commands/__init__.py +6 -0
kater_cli/commands/_shared.py +281 -0
kater_cli/commands/auth.py +78 -0
kater_cli/commands/compile.py +379 -0
kater_cli/commands/config/__init__.py +10 -0
kater_cli/commands/config/app.py +40 -0
kater_cli/commands/config/default_connection.py +202 -0
kater_cli/commands/dev.py +382 -0
kater_cli/commands/import_/__init__.py +6 -0
kater_cli/commands/import_/app.py +16 -0
kater_cli/commands/import_/tenants.py +520 -0
kater_cli/commands/install.py +212 -0
kater_cli/commands/run.py +335 -0
kater_cli/commands/scaffold/__init__.py +0 -0
kater_cli/commands/scaffold/app.py +17 -0
kater_cli/commands/scaffold/topic.py +85 -0
kater_cli/commands/validate.py +381 -0
kater_cli/config.py +39 -0
kater_cli/main.py +48 -0
kater_cli/preferences/__init__.py +5 -0
kater_cli/preferences/preference_manager.py +75 -0
kater_cli/prompts.py +89 -0
kater_cli/repo.py +101 -0
kater_cli/services/__init__.py +12 -0
kater_cli/services/dev_file_watcher.py +232 -0
kater_cli/services/file_sync.py +238 -0
kater_cli/services/ws_dev_client.py +410 -0
kater_cli-0.1.0.dist-info/METADATA +14 -0
kater_cli-0.1.0.dist-info/RECORD +42 -0
kater_cli-0.1.0.dist-info/WHEEL +4 -0
kater_cli-0.1.0.dist-info/entry_points.txt +2 -0
kater_utils/__init__.py +37 -0
kater_utils/file_utils.py +72 -0
kater_utils/logging.py +159 -0
kater_utils/repo.py +77 -0
kater_utils/scaffold_templates.py +398 -0

kater_cli/.gitkeep ADDED Viewed

File without changes

kater_cli/auth/__init__.py ADDED Viewed

@@ -0,0 +1,6 @@
+"""Authentication module for the Kater CLI."""
+from kater_cli.auth.oauth import run_oauth_flow
+from kater_cli.auth.token_manager import TokenManager
+__all__ = ["TokenManager", "run_oauth_flow"]

kater_cli/auth/oauth.py ADDED Viewed

@@ -0,0 +1,211 @@
+"""OAuth 2.0 Authorization Code flow with PKCE for CLI authentication."""
+import base64
+import hashlib
+import secrets
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from threading import Thread
+from urllib.parse import parse_qs, urlencode, urlparse
+import httpx
+from rich.console import Console
+from kater_cli.auth.token_manager import TokenManager
+from kater_cli.config import get_settings
+console = Console()
+class OAuthCallbackHandler(BaseHTTPRequestHandler):
+    """HTTP handler for OAuth callback."""
+    authorization_code: str | None = None
+    state: str | None = None
+    error: str | None = None
+    def log_message(self, format: str, *args: object) -> None:
+        """Suppress server logs."""
+        pass
+    def do_GET(self) -> None:
+        """Handle GET request from OAuth callback."""
+        parsed = urlparse(self.path)
+        if parsed.path != "/callback":
+            self.send_response(404)
+            self.end_headers()
+            return
+        params = parse_qs(parsed.query)
+        if "error" in params:
+            OAuthCallbackHandler.error = params["error"][0]
+            self._send_error_response(params.get("error_description", ["Unknown error"])[0])
+            return
+        if "code" not in params or "state" not in params:
+            OAuthCallbackHandler.error = "missing_params"
+            self._send_error_response("Missing authorization code or state")
+            return
+        OAuthCallbackHandler.authorization_code = params["code"][0]
+        OAuthCallbackHandler.state = params["state"][0]
+        self._send_success_response()
+    def _send_success_response(self) -> None:
+        """Send success HTML response."""
+        self.send_response(200)
+        self.send_header("Content-type", "text/html")
+        self.end_headers()
+        html = """
+        <!DOCTYPE html>
+        <html>
+        <head><title>Login Successful</title></head>
+        <body style="font-family: system-ui; text-align: center; padding: 50px;">
+            <h1>Login Successful!</h1>
+            <p>You can close this window and return to the terminal.</p>
+        </body>
+        </html>
+        """
+        self.wfile.write(html.encode())
+    def _send_error_response(self, message: str) -> None:
+        """Send error HTML response."""
+        self.send_response(400)
+        self.send_header("Content-type", "text/html")
+        self.end_headers()
+        html = f"""
+        <!DOCTYPE html>
+        <html>
+        <head><title>Login Failed</title></head>
+        <body style="font-family: system-ui; text-align: center; padding: 50px;">
+            <h1>Login Failed</h1>
+            <p>{message}</p>
+            <p>Please try again from the terminal.</p>
+        </body>
+        </html>
+        """
+        self.wfile.write(html.encode())
+def _generate_pkce_pair() -> tuple[str, str]:
+    """Generate PKCE code verifier and challenge.
+    Returns:
+        Tuple of (code_verifier, code_challenge)
+    """
+    code_verifier = secrets.token_urlsafe(32)
+    code_challenge_bytes = hashlib.sha256(code_verifier.encode()).digest()
+    code_challenge = base64.urlsafe_b64encode(code_challenge_bytes).rstrip(b"=").decode()
+    return code_verifier, code_challenge
+def _generate_state() -> str:
+    """Generate random state parameter for CSRF protection."""
+    return secrets.token_urlsafe(16)
+def run_oauth_flow() -> bool:
+    """Run the OAuth 2.0 authorization code flow with PKCE.
+    Opens browser for user authentication and captures the callback.
+    Returns:
+        True if login successful, False otherwise.
+    """
+    settings = get_settings()
+    if not settings.oauth_client_id:
+        console.print("[red]Error: KATER_OAUTH_CLIENT_ID environment variable is not set.[/red]")
+        console.print("Please set it to your PropelAuth OAuth client ID.")
+        return False
+    # Reset handler state
+    OAuthCallbackHandler.authorization_code = None
+    OAuthCallbackHandler.state = None
+    OAuthCallbackHandler.error = None
+    # Generate PKCE pair and state
+    code_verifier, code_challenge = _generate_pkce_pair()
+    state = _generate_state()
+    # Build authorization URL
+    redirect_uri = f"http://localhost:{settings.oauth_callback_port}/callback"
+    auth_params = {
+        "client_id": settings.oauth_client_id,
+        "response_type": "code",
+        "redirect_uri": redirect_uri,
+        "scope": "openid email profile",
+        "state": state,
+        "code_challenge": code_challenge,
+        "code_challenge_method": "S256",
+    }
+    auth_url = f"{settings.oauth_auth_url}?{urlencode(auth_params)}"
+    # Start local callback server
+    server = HTTPServer(("localhost", settings.oauth_callback_port), OAuthCallbackHandler)
+    def handle_request() -> None:
+        server.handle_request()
+    server_thread = Thread(target=handle_request)
+    server_thread.start()
+    # Open browser for authentication
+    console.print("Opening browser for authentication...")
+    console.print(f"[dim]If browser doesn't open, visit: {auth_url}[/dim]")
+    webbrowser.open(auth_url)
+    # Wait for callback
+    console.print("Waiting for authentication...")
+    server_thread.join(timeout=120)
+    server.server_close()
+    # Check for errors
+    if OAuthCallbackHandler.error:
+        console.print(f"[red]Authentication failed: {OAuthCallbackHandler.error}[/red]")
+        return False
+    if not OAuthCallbackHandler.authorization_code:
+        console.print("[red]Authentication timed out. Please try again.[/red]")
+        return False
+    received_state = OAuthCallbackHandler.state
+    if received_state is None or received_state != state:
+        console.print("[red]Invalid state parameter. Possible CSRF attack.[/red]")
+        return False
+    # Exchange code for tokens
+    try:
+        response = httpx.post(
+            settings.oauth_token_url,
+            data={
+                "grant_type": "authorization_code",
+                "code": OAuthCallbackHandler.authorization_code,
+                "redirect_uri": redirect_uri,
+                "client_id": settings.oauth_client_id,
+                "code_verifier": code_verifier,
+            },
+            timeout=30.0,
+        )
+        if response.status_code != 200:
+            console.print(f"[red]Token exchange failed: {response.text}[/red]")
+            return False
+        data = response.json()
+        # Store tokens
+        token_manager = TokenManager()
+        token_manager.store_tokens(
+            access_token=data["access_token"],
+            refresh_token=data["refresh_token"],
+            expires_in=data["expires_in"],
+        )
+        console.print("[green]Successfully logged in![/green]")
+        return True
+    except httpx.RequestError as e:
+        console.print(f"[red]Network error during token exchange: {e}[/red]")
+        return False

kater_cli/auth/token_manager.py ADDED Viewed

@@ -0,0 +1,338 @@
+"""Token management using system keyring for secure storage."""
+from __future__ import annotations
+import asyncio
+import json
+import secrets
+import time
+from collections.abc import Callable, Generator
+from dataclasses import dataclass
+import httpx
+import keyring
+from kater_cli.config import get_settings
+class _TokenRefreshRejected(Exception):
+    """Auth server definitively rejected the refresh token (401/403)."""
+# CLI Identity key for keyring storage
+CLI_ID_KEY = "cli_id"
+def get_or_create_cli_id() -> str:
+    """Get existing cli_id from keyring or generate a new one.
+    The cli_id is a persistent identifier stored in the system keyring
+    that uniquely identifies a developer's machine. It is used as the
+    HTTP header X-Kater-CLI-ID to route API requests to the correct
+    Virtual Filesystem (VFS).
+    Returns:
+        The cli_id string (format: cli_ + 12-char hex)
+    """
+    settings = get_settings()
+    # Try to get existing cli_id
+    cli_id = keyring.get_password(settings.keyring_service, CLI_ID_KEY)
+    if cli_id is not None:
+        return cli_id
+    # Generate new cli_id: cli_ prefix + 12 hex characters
+    cli_id = f"cli_{secrets.token_hex(6)}"
+    keyring.set_password(settings.keyring_service, CLI_ID_KEY, cli_id)
+    return cli_id
+@dataclass
+class TokenData:
+    """Stored token data."""
+    access_token: str
+    refresh_token: str
+    expires_at: float  # Unix timestamp
+class TokenManager:
+    """Manages OAuth tokens with secure keyring storage and automatic refresh."""
+    KEYRING_USERNAME = "oauth_tokens"
+    REFRESH_BUFFER_SECONDS = 300  # Refresh 5 minutes before expiration
+    def __init__(self) -> None:
+        self._settings = get_settings()
+        self._service = self._settings.keyring_service
+        self._background_task: asyncio.Task[None] | None = None
+        self._cached_tokens: TokenData | None = None
+        self._cache_loaded: bool = False
+    def _get_stored_tokens(self) -> TokenData | None:
+        """Retrieve tokens, using in-memory cache to avoid repeated keyring prompts."""
+        if self._cache_loaded:
+            return self._cached_tokens
+        data = keyring.get_password(self._service, self.KEYRING_USERNAME)
+        if not data:
+            self._cached_tokens = None
+            self._cache_loaded = True
+            return None
+        try:
+            parsed = json.loads(data)
+            self._cached_tokens = TokenData(
+                access_token=parsed["access_token"],
+                refresh_token=parsed["refresh_token"],
+                expires_at=parsed["expires_at"],
+            )
+        except (json.JSONDecodeError, KeyError):
+            self._cached_tokens = None
+        self._cache_loaded = True
+        return self._cached_tokens
+    def store_tokens(
+        self,
+        access_token: str,
+        refresh_token: str,
+        expires_in: int,
+    ) -> None:
+        """Store tokens in keyring.
+        Args:
+            access_token: The OAuth access token
+            refresh_token: The OAuth refresh token
+            expires_in: Token lifetime in seconds
+        """
+        expires_at = time.time() + expires_in
+        data = json.dumps(
+            {
+                "access_token": access_token,
+                "refresh_token": refresh_token,
+                "expires_at": expires_at,
+            }
+        )
+        keyring.set_password(self._service, self.KEYRING_USERNAME, data)
+        # Update in-memory cache so subsequent reads skip the keyring
+        self._cached_tokens = TokenData(
+            access_token=access_token,
+            refresh_token=refresh_token,
+            expires_at=expires_at,
+        )
+        self._cache_loaded = True
+    def clear_tokens(self) -> None:
+        """Remove tokens from keyring."""
+        self._cached_tokens = None
+        self._cache_loaded = True
+        try:
+            keyring.delete_password(self._service, self.KEYRING_USERNAME)
+        except Exception:
+            # Password may not exist, which is fine
+            pass
+    def _is_token_expired(self, token_data: TokenData) -> bool:
+        """Check if token is expired or will expire soon."""
+        return time.time() >= (token_data.expires_at - self.REFRESH_BUFFER_SECONDS)
+    def _refresh_tokens(self, refresh_token: str) -> TokenData | None:
+        """Exchange refresh token for new access token.
+        Returns:
+            TokenData on success, None on failure.
+        Raises:
+            _TokenRefreshRejected: When the auth server definitively rejects the
+                refresh token (401/403), meaning the token is permanently invalid.
+        """
+        try:
+            response = httpx.post(
+                self._settings.oauth_token_url,
+                data={
+                    "grant_type": "refresh_token",
+                    "refresh_token": refresh_token,
+                    "client_id": self._settings.oauth_client_id,
+                },
+                timeout=30.0,
+            )
+            if response.status_code in (401, 403):
+                raise _TokenRefreshRejected
+            if response.status_code != 200:
+                return None
+            data = response.json()
+            self.store_tokens(
+                access_token=data["access_token"],
+                refresh_token=data.get("refresh_token", refresh_token),
+                expires_in=data["expires_in"],
+            )
+            return self._cached_tokens
+        except httpx.RequestError:
+            return None
+    def get_access_token(self) -> str | None:
+        """Get a valid access token, refreshing if needed.
+        Returns:
+            The access token if valid/refreshable, None if not authenticated.
+        """
+        token_data = self._get_stored_tokens()
+        if not token_data:
+            return None
+        if self._is_token_expired(token_data):
+            try:
+                refreshed = self._refresh_tokens(token_data.refresh_token)
+            except _TokenRefreshRejected:
+                # Refresh token is permanently invalid — clear and require re-login
+                self.clear_tokens()
+                return None
+            if not refreshed:
+                # Transient failure (network, 500, etc.) — return the expired
+                # token rather than nuking the keyring. The caller or background
+                # refresh can retry later.
+                return token_data.access_token
+            token_data = refreshed
+        return token_data.access_token
+    def has_tokens(self) -> bool:
+        """Check if tokens are stored (may be expired)."""
+        return self._get_stored_tokens() is not None
+    def get_token_status(self) -> tuple[bool, float | None]:
+        """Get authentication status.
+        Returns:
+            Tuple of (is_authenticated, expires_at_timestamp or None)
+        """
+        token_data = self._get_stored_tokens()
+        if not token_data:
+            return False, None
+        return True, token_data.expires_at
+    def get_token_data(self) -> TokenData | None:
+        """Get current token data (for auth flow use).
+        Returns:
+            TokenData if tokens are stored, None otherwise.
+        """
+        return self._get_stored_tokens()
+    def refresh_tokens(self, refresh_token: str) -> TokenData | None:
+        """Attempt to refresh tokens using the provided refresh token.
+        This is the public interface for token refresh, used by
+        TokenRefreshAuth for 401 retry flow.
+        Args:
+            refresh_token: The refresh token to exchange for new tokens.
+        Returns:
+            TokenData with new tokens if successful, None if refresh failed.
+        """
+        return self._refresh_tokens(refresh_token)
+    def start_background_refresh(
+        self, callback: Callable[[], None] | None = None
+    ) -> asyncio.Task[None]:
+        """Start background token refresh timer.
+        Proactively refreshes tokens before they expire to ensure
+        uninterrupted WebSocket connections.
+        Args:
+            callback: Optional callback invoked after successful refresh.
+        Returns:
+            The asyncio Task running the refresh loop.
+        """
+        self._background_task = asyncio.create_task(self._refresh_loop(callback))
+        return self._background_task
+    def stop_background_refresh(self) -> None:
+        """Stop the background refresh timer."""
+        if self._background_task is not None:
+            self._background_task.cancel()
+            self._background_task = None
+    async def _refresh_loop(self, callback: Callable[[], None] | None = None) -> None:
+        """Background loop that checks and refreshes tokens before expiry.
+        Args:
+            callback: Optional callback invoked after successful refresh.
+        """
+        check_interval = 60  # Check every 60 seconds
+        try:
+            while True:
+                token_data = self._get_stored_tokens()
+                if token_data and self._is_token_expired(token_data):
+                    try:
+                        # Run the blocking HTTP call in a thread to avoid freezing the event loop
+                        refreshed = await asyncio.to_thread(
+                            self._refresh_tokens, token_data.refresh_token
+                        )
+                    except _TokenRefreshRejected:
+                        # Auth server definitively rejected the refresh token — clear and stop
+                        self.clear_tokens()
+                        return
+                    if refreshed and callback:
+                        callback()
+                    # None means transient failure; will retry next interval
+                await asyncio.sleep(check_interval)
+        except asyncio.CancelledError:
+            # Clean shutdown
+            pass
+class TokenRefreshAuth(httpx.Auth):
+    """httpx Auth class that handles automatic token refresh on 401.
+    This auth class:
+    1. Sets the Authorization header with the current access token
+    2. If a 401 response is received, attempts to refresh the token
+    3. If refresh succeeds, retries the request with the new token
+    4. If refresh fails, clears tokens and returns the 401 response
+    """
+    def __init__(self, token_manager: TokenManager) -> None:
+        """Initialize with a TokenManager instance.
+        Args:
+            token_manager: The TokenManager to use for token operations.
+        """
+        self._token_manager = token_manager
+    def auth_flow(self, request: httpx.Request) -> Generator[httpx.Request, httpx.Response, None]:
+        """Implement the httpx auth flow with 401 retry.
+        Args:
+            request: The outgoing request.
+        Yields:
+            The request (possibly retried with new token).
+        """
+        # Get current token and set auth header
+        token = self._token_manager.get_access_token()
+        if token:
+            request.headers["Authorization"] = f"Bearer {token}"
+        # Send the request
+        response = yield request
+        # Handle 401 - attempt refresh and retry
+        if response.status_code == 401:
+            token_data = self._token_manager.get_token_data()
+            if token_data:
+                try:
+                    refreshed = self._token_manager.refresh_tokens(token_data.refresh_token)
+                except _TokenRefreshRejected:
+                    self._token_manager.clear_tokens()
+                    return
+                if refreshed:
+                    # Update header with new token and retry
+                    request.headers["Authorization"] = f"Bearer {refreshed.access_token}"
+                    yield request
+                # Transient failure — don't clear tokens

kater_cli/client.py ADDED Viewed

@@ -0,0 +1,82 @@
+"""Authenticated API client factory for the Kater CLI."""
+from collections.abc import Callable
+from functools import wraps
+from typing import ParamSpec, TypeVar
+import typer
+from kater import DefaultHttpxClient, Kater
+from rich.console import Console
+from kater_cli.auth.token_manager import TokenManager, TokenRefreshAuth
+from kater_cli.config import get_settings
+console = Console()
+P = ParamSpec("P")
+R = TypeVar("R")
+def get_authenticated_client() -> Kater:
+    """Get an authenticated API client.
+    Retrieves a valid access token (refreshing if needed) and creates
+    a Kater client configured for the API with automatic token
+    refresh on 401 responses.
+    Raises:
+        typer.Exit: If not logged in or token refresh failed.
+    Returns:
+        Configured Kater client instance.
+    """
+    token_manager = TokenManager()
+    # Check if we have any tokens before creating the client
+    if not token_manager.has_tokens():
+        console.print("[red]Not logged in. Run `kater login` to authenticate.[/red]")
+        raise typer.Exit(1)
+    settings = get_settings()
+    # Get the current access token for SDK header validation.
+    # TokenRefreshAuth also sets the header at the httpx layer and
+    # automatically refreshes the token on 401 responses.
+    access_token = token_manager.get_access_token()
+    if not access_token:
+        console.print("[red]Session expired. Run `kater login` to re-authenticate.[/red]")
+        raise typer.Exit(1)
+    return Kater(
+        base_url=settings.api_url,
+        auth_token=access_token,
+        http_client=DefaultHttpxClient(auth=TokenRefreshAuth(token_manager)),
+    )
+def require_auth(func: Callable[P, R]) -> Callable[P, R]:
+    """Decorator for commands that require authentication.
+    Checks for a valid token before running the command. If the token
+    is missing or invalid, displays an error and exits.
+    Usage:
+        @app.command()
+        @require_auth
+        def my_command():
+            client = get_authenticated_client()
+            ...
+    """
+    @wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        token_manager = TokenManager()
+        token = token_manager.get_access_token()
+        if not token:
+            console.print("[red]Not logged in. Run `kater login` to authenticate.[/red]")
+            raise typer.Exit(1)
+        return func(*args, **kwargs)
+    return wrapper

kater_cli/commands/.gitkeep ADDED Viewed

File without changes

kater_cli/commands/__init__.py ADDED Viewed

@@ -0,0 +1,6 @@
+"""CLI commands for Kater."""
+from kater_cli.commands import dev
+from kater_cli.commands.auth import login, logout, status
+__all__ = ["dev", "login", "logout", "status"]