golf-mcp 0.1.11__py3-none-any.whl → 0.1.13__py3-none-any.whl

golf/auth/provider.py

@@ -4,107 +4,112 @@ This module defines the ProviderConfig class used to configure
 OAuth authentication for GolfMCP servers.
 """
 
-from typing import Dict, List, Optional, Any
+from typing import Any
+
 from pydantic import BaseModel, Field, field_validator
 
 
 class ProviderConfig(BaseModel):
     """Configuration for an OAuth2 provider.
-    
+
     This class defines the configuration for an OAuth2 provider,
     including the endpoints, credentials, and other settings needed
     to authenticate with the provider.
     """
-    
+
     # Provider identification
     provider: str = Field(
-        ..., 
-        description="Provider type (e.g., 'github', 'google', 'custom')"
+        ..., description="Provider type (e.g., 'github', 'google', 'custom')"
     )
-    
+
     # OAuth credentials - names of environment variables to read at runtime
-    client_id_env_var: str = Field(..., description="Name of environment variable for Client ID")
-    client_secret_env_var: str = Field(..., description="Name of environment variable for Client Secret")
-    
+    client_id_env_var: str = Field(
+        ..., description="Name of environment variable for Client ID"
+    )
+    client_secret_env_var: str = Field(
+        ..., description="Name of environment variable for Client Secret"
+    )
+
     # These fields will store the actual values read at runtime in dist/server.py
     # They are made optional here as they are resolved in the generated code.
-    client_id: Optional[str] = Field(None, description="OAuth client ID (resolved at runtime)")
-    client_secret: Optional[str] = Field(None, description="OAuth client secret (resolved at runtime)")
+    client_id: str | None = Field(
+        None, description="OAuth client ID (resolved at runtime)"
+    )
+    client_secret: str | None = Field(
+        None, description="OAuth client secret (resolved at runtime)"
+    )
 
     # OAuth endpoints (can be baked in)
     authorize_url: str = Field(..., description="Authorization endpoint URL")
     token_url: str = Field(..., description="Token endpoint URL")
-    userinfo_url: Optional[str] = Field(
-        None, 
-        description="User info endpoint URL (for OIDC providers)"
+    userinfo_url: str | None = Field(
+        None, description="User info endpoint URL (for OIDC providers)"
     )
-    
-    jwks_uri: Optional[str] = Field(
-        None, 
-        description="JSON Web Key Set URI (for token validation)"
+
+    jwks_uri: str | None = Field(
+        None, description="JSON Web Key Set URI (for token validation)"
     )
-    
-    scopes: List[str] = Field(
-        default_factory=list, 
-        description="OAuth scopes to request from the provider"
+
+    scopes: list[str] = Field(
+        default_factory=list, description="OAuth scopes to request from the provider"
     )
-    
-    issuer_url: Optional[str] = Field(
-        None, 
-        description="OIDC issuer URL for discovery (if using OIDC) - will be overridden by runtime value in server.py"
+
+    issuer_url: str | None = Field(
+        None,
+        description="OIDC issuer URL for discovery (if using OIDC) - will be overridden by runtime value in server.py",
     )
-    
+
     callback_path: str = Field(
-        "/auth/callback", 
-        description="Path on this server where the IdP should redirect after authentication"
+        "/auth/callback",
+        description="Path on this server where the IdP should redirect after authentication",
     )
-    
+
     # JWT configuration
-    jwt_secret_env_var: str = Field(..., description="Name of environment variable for JWT Secret")
-    jwt_secret: Optional[str] = Field(None, description="Secret key for signing JWT tokens (resolved at runtime)")
+    jwt_secret_env_var: str = Field(
+        ..., description="Name of environment variable for JWT Secret"
+    )
+    jwt_secret: str | None = Field(
+        None, description="Secret key for signing JWT tokens (resolved at runtime)"
+    )
     token_expiration: int = Field(
-        3600, 
-        description="JWT token expiration time in seconds",
-        ge=60, 
-        le=86400
+        3600, description="JWT token expiration time in seconds", ge=60, le=86400
     )
-    
-    settings: Dict[str, Any] = Field(
-        default_factory=dict,
-        description="Additional provider-specific settings"
+
+    settings: dict[str, Any] = Field(
+        default_factory=dict, description="Additional provider-specific settings"
     )
-    
-    @field_validator('provider')
+
+    @field_validator("provider")
     @classmethod
     def validate_provider(cls, value: str) -> str:
         """Validate the provider type.
-        
+
         Ensures the provider type is a valid, supported provider.
-        
+
         Args:
             value: The provider type
-            
+
         Returns:
             The validated provider type
-            
+
         Raises:
             ValueError: If the provider type is not supported
         """
-        known_providers = {'custom', 'github', 'google', 'jwks'}
-        
-        if value not in known_providers and not value.startswith('custom:'):
+        known_providers = {"custom", "github", "google", "jwks"}
+
+        if value not in known_providers and not value.startswith("custom:"):
             raise ValueError(
                 f"Unknown provider: '{value}'. Must be one of {known_providers} "
                 "or start with 'custom:'"
             )
         return value
-    
+
     def get_provider_name(self) -> str:
         """Get a clean provider name for display purposes.
-        
+
         Returns:
             A human-readable provider name
         """
-        if self.provider.startswith('custom:'):
+        if self.provider.startswith("custom:"):
             return self.provider[7:]  # Remove 'custom:' prefix
-        return self.provider.capitalize() 
+        return self.provider.capitalize()

golf/cli/__init__.py

@@ -1 +1 @@
-"""CLI package for the GolfMCP framework.""" 
+"""CLI package for the GolfMCP framework."""

golf/cli/main.py

@@ -1,17 +1,23 @@
 """CLI entry points for GolfMCP."""
 
+import atexit
 import os
 from pathlib import Path
-from typing import Optional
-import atexit
 
 import typer
 from rich.console import Console
 from rich.panel import Panel
 
 from golf import __version__
-from golf.core.config import load_settings, find_project_root
-from golf.core.telemetry import is_telemetry_enabled, shutdown, set_telemetry_enabled, track_event
+from golf.core.config import find_project_root, load_settings
+from golf.core.telemetry import (
+    is_telemetry_enabled,
+    set_telemetry_enabled,
+    shutdown,
+    track_event,
+    track_detailed_error,
+    _detect_execution_environment,
+)
 
 # Create console for rich output
 console = Console()
@@ -48,24 +54,39 @@ def callback(
         False, "--verbose", "-v", help="Increase verbosity of output."
     ),
     no_telemetry: bool = typer.Option(
-        False, "--no-telemetry", help="Disable telemetry collection (persists for future commands)."
+        False,
+        "--no-telemetry",
+        help="Disable telemetry collection (persists for future commands).",
+    ),
+    test: bool = typer.Option(
+        False,
+        "--test",
+        hidden=True,
+        help="Run in test mode (disables telemetry for this execution only).",
     ),
 ) -> None:
     """GolfMCP: A Pythonic framework for building MCP servers with zero boilerplate."""
     # Set verbosity in environment for other components to access
     if verbose:
         os.environ["GOLF_VERBOSE"] = "1"
-    
-    # Set telemetry preference if flag is used
+
+    # Set test mode if flag is used (temporary, just for this execution)
+    if test:
+        set_telemetry_enabled(False, persist=False)
+        os.environ["GOLF_TEST_MODE"] = "1"
+
+    # Set telemetry preference if flag is used (permanent)
     if no_telemetry:
         set_telemetry_enabled(False, persist=True)
-        console.print("[dim]Telemetry has been disabled. You can re-enable it with: golf telemetry enable[/dim]")
+        console.print(
+            "[dim]Telemetry has been disabled. You can re-enable it with: golf telemetry enable[/dim]"
+        )
 
 
 @app.command()
 def init(
     project_name: str = typer.Argument(..., help="Name of the project to create"),
-    output_dir: Optional[Path] = typer.Option(
+    output_dir: Path | None = typer.Option(
         None, "--output-dir", "-o", help="Directory to create the project in"
     ),
     template: str = typer.Option(
@@ -73,19 +94,21 @@ def init(
     ),
 ) -> None:
     """Initialize a new GolfMCP project.
-    
+
     Creates a new directory with the project scaffold, including
     examples for tools, resources, and prompts.
     """
     # Import here to avoid circular imports
     from golf.commands.init import initialize_project
-    
+
     # Use the current directory if no output directory is specified
     if output_dir is None:
         output_dir = Path.cwd() / project_name
-    
+
     # Execute the initialization command (it handles its own tracking)
-    initialize_project(project_name=project_name, output_dir=output_dir, template=template)
+    initialize_project(
+        project_name=project_name, output_dir=output_dir, template=template
+    )
 
 
 # Create a build group with subcommands
@@ -95,179 +118,278 @@ app.add_typer(build_app, name="build")
 
 @build_app.command("dev")
 def build_dev(
-    output_dir: Optional[str] = typer.Option(
+    output_dir: str | None = typer.Option(
         None, "--output-dir", "-o", help="Directory to output the built project"
-    )
-):
+    ),
+) -> None:
     """Build a development version with environment variables copied."""
     # Find project root directory
     project_root, config_path = find_project_root()
-    
+
     if not project_root:
-        console.print("[bold red]Error: No GolfMCP project found in the current directory or any parent directory.[/bold red]")
+        console.print(
+            "[bold red]Error: No GolfMCP project found in the current directory or any parent directory.[/bold red]"
+        )
         console.print("Run 'golf init <project_name>' to create a new project.")
-        track_event("cli_build_failed", {"success": False, "environment": "dev", "error_type": "NoProjectFound", "error_message": "No GolfMCP project found"})
+        track_event(
+            "cli_build_failed",
+            {
+                "success": False,
+                "environment": "dev",
+                "error_type": "NoProjectFound",
+                "error_message": "No GolfMCP project found",
+            },
+        )
         raise typer.Exit(code=1)
-    
+
     # Load settings from the found project
     settings = load_settings(project_root)
-    
+
     # Set default output directory if not specified
-    if output_dir is None:
-        output_dir = project_root / "dist"
-    else:
-        output_dir = Path(output_dir)
-    
+    output_dir = project_root / "dist" if output_dir is None else Path(output_dir)
+
     try:
         # Build the project with environment variables copied
         from golf.commands.build import build_project
-        build_project(project_root, settings, output_dir, build_env="dev", copy_env=True)
+
+        build_project(
+            project_root, settings, output_dir, build_env="dev", copy_env=True
+        )
         # Track successful build with environment
         track_event("cli_build_success", {"success": True, "environment": "dev"})
     except Exception as e:
-        error_type = type(e).__name__
-        error_message = str(e)
-        track_event("cli_build_failed", {"success": False, "environment": "dev", "error_type": error_type, "error_message": error_message})
+        track_detailed_error(
+            "cli_build_failed",
+            e,
+            context="Development build with environment variables",
+            operation="build_dev",
+            additional_props={"environment": "dev", "copy_env": True}
+        )
         raise
 
 
 @build_app.command("prod")
 def build_prod(
-    output_dir: Optional[str] = typer.Option(
+    output_dir: str | None = typer.Option(
         None, "--output-dir", "-o", help="Directory to output the built project"
-    )
-):
+    ),
+) -> None:
     """Build a production version without copying environment variables."""
     # Find project root directory
     project_root, config_path = find_project_root()
-    
+
     if not project_root:
-        console.print("[bold red]Error: No GolfMCP project found in the current directory or any parent directory.[/bold red]")
+        console.print(
+            "[bold red]Error: No GolfMCP project found in the current directory or any parent directory.[/bold red]"
+        )
         console.print("Run 'golf init <project_name>' to create a new project.")
-        track_event("cli_build_failed", {"success": False, "environment": "prod", "error_type": "NoProjectFound", "error_message": "No GolfMCP project found"})
+        track_event(
+            "cli_build_failed",
+            {
+                "success": False,
+                "environment": "prod",
+                "error_type": "NoProjectFound",
+                "error_message": "No GolfMCP project found",
+            },
+        )
         raise typer.Exit(code=1)
-    
+
     # Load settings from the found project
     settings = load_settings(project_root)
-    
+
     # Set default output directory if not specified
-    if output_dir is None:
-        output_dir = project_root / "dist"
-    else:
-        output_dir = Path(output_dir)
-    
+    output_dir = project_root / "dist" if output_dir is None else Path(output_dir)
+
     try:
         # Build the project without copying environment variables
         from golf.commands.build import build_project
-        build_project(project_root, settings, output_dir, build_env="prod", copy_env=False)
+
+        build_project(
+            project_root, settings, output_dir, build_env="prod", copy_env=False
+        )
         # Track successful build with environment
         track_event("cli_build_success", {"success": True, "environment": "prod"})
     except Exception as e:
-        error_type = type(e).__name__
-        error_message = str(e)
-        track_event("cli_build_failed", {"success": False, "environment": "prod", "error_type": error_type, "error_message": error_message})
+        track_detailed_error(
+            "cli_build_failed",
+            e,
+            context="Production build without environment variables",
+            operation="build_prod",
+            additional_props={"environment": "prod", "copy_env": False}
+        )
         raise
 
 
 @app.command()
 def run(
-    dist_dir: Optional[str] = typer.Option(
+    dist_dir: str | None = typer.Option(
         None, "--dist-dir", "-d", help="Directory containing the built server"
     ),
-    host: Optional[str] = typer.Option(
+    host: str | None = typer.Option(
         None, "--host", "-h", help="Host to bind to (overrides settings)"
     ),
-    port: Optional[int] = typer.Option(
+    port: int | None = typer.Option(
         None, "--port", "-p", help="Port to bind to (overrides settings)"
     ),
     build_first: bool = typer.Option(
         True, "--build/--no-build", help="Build the project before running"
     ),
-):
+) -> None:
     """Run the built FastMCP server.
-    
+
     This command runs the built server from the dist directory.
     By default, it will build the project first if needed.
     """
     # Find project root directory
     project_root, config_path = find_project_root()
-    
+
     if not project_root:
-        console.print("[bold red]Error: No GolfMCP project found in the current directory or any parent directory.[/bold red]")
+        console.print(
+            "[bold red]Error: No GolfMCP project found in the current directory or any parent directory.[/bold red]"
+        )
         console.print("Run 'golf init <project_name>' to create a new project.")
-        track_event("cli_run_failed", {"success": False, "error_type": "NoProjectFound", "error_message": "No GolfMCP project found"})
+        track_event(
+            "cli_run_failed",
+            {
+                "success": False,
+                "error_type": "NoProjectFound",
+                "error_message": "No GolfMCP project found",
+            },
+        )
         raise typer.Exit(code=1)
-    
+
     # Load settings from the found project
     settings = load_settings(project_root)
-    
+
     # Set default dist directory if not specified
-    if dist_dir is None:
-        dist_dir = project_root / "dist"
-    else:
-        dist_dir = Path(dist_dir)
-    
+    dist_dir = project_root / "dist" if dist_dir is None else Path(dist_dir)
+
     # Check if dist directory exists
     if not dist_dir.exists():
         if build_first:
-            console.print(f"[yellow]Dist directory {dist_dir} not found. Building first...[/yellow]")
+            console.print(
+                f"[yellow]Dist directory {dist_dir} not found. Building first...[/yellow]"
+            )
             try:
                 # Build the project
                 from golf.commands.build import build_project
+
                 build_project(project_root, settings, dist_dir)
             except Exception as e:
-                error_type = type(e).__name__
-                error_message = str(e)
-                console.print(f"[bold red]Error building project:[/bold red] {error_message}")
-                track_event("cli_run_failed", {"success": False, "error_type": f"BuildError.{error_type}", "error_message": error_message})
+                console.print(
+                    f"[bold red]Error building project:[/bold red] {str(e)}"
+                )
+                track_detailed_error(
+                    "cli_run_failed",
+                    e,
+                    context="Auto-build before running server",
+                    operation="auto_build_before_run",
+                    additional_props={"auto_build": True}
+                )
                 raise
         else:
-            console.print(f"[bold red]Error: Dist directory {dist_dir} not found.[/bold red]")
-            console.print("Run 'golf build' first or use --build to build automatically.")
-            track_event("cli_run_failed", {"success": False, "error_type": "DistNotFound", "error_message": "Dist directory not found"})
+            console.print(
+                f"[bold red]Error: Dist directory {dist_dir} not found.[/bold red]"
+            )
+            console.print(
+                "Run 'golf build' first or use --build to build automatically."
+            )
+            track_event(
+                "cli_run_failed",
+                {
+                    "success": False,
+                    "error_type": "DistNotFound",
+                    "error_message": "Dist directory not found",
+                },
+            )
             raise typer.Exit(code=1)
-    
+
     try:
         # Import and run the server
         from golf.commands.run import run_server
+
         return_code = run_server(
             project_path=project_root,
             settings=settings,
             dist_dir=dist_dir,
             host=host,
-            port=port
+            port=port,
         )
-        
-        # Track based on return code
+
+        # Track based on return code with better categorization
         if return_code == 0:
             track_event("cli_run_success", {"success": True})
+        elif return_code in [130, 143, 137, 2]:
+            # Intentional shutdowns (not errors):
+            # 130: Ctrl+C (SIGINT)
+            # 143: SIGTERM (graceful shutdown, e.g., Kubernetes, Docker)
+            # 137: SIGKILL (forced shutdown)
+            # 2: General interrupt/graceful shutdown
+            shutdown_type = {
+                130: "UserInterrupt",
+                143: "GracefulShutdown", 
+                137: "ForcedShutdown",
+                2: "Interrupt"
+            }.get(return_code, "GracefulShutdown")
+            
+            track_event(
+                "cli_run_shutdown",
+                {
+                    "success": True,  # Not an error
+                    "shutdown_type": shutdown_type,
+                    "exit_code": return_code,
+                },
+            )
         else:
-            track_event("cli_run_failed", {"success": False, "error_type": "NonZeroExit", "error_message": f"Server exited with code {return_code}"})
-        
+            # Actual errors (unexpected exit codes)
+            track_event(
+                "cli_run_failed",
+                {
+                    "success": False,
+                    "error_type": "UnexpectedExit",
+                    "error_message": f"Server process exited unexpectedly with code {return_code}",
+                    "exit_code": return_code,
+                    "operation": "server_process_execution",
+                    "context": "Server process terminated with unexpected exit code",
+                    # Add execution environment context
+                    "execution_env": _detect_execution_environment(),
+                },
+            )
+
         # Exit with the same code as the server
         if return_code != 0:
             raise typer.Exit(code=return_code)
     except Exception as e:
-        error_type = type(e).__name__
-        error_message = str(e)
-        track_event("cli_run_failed", {"success": False, "error_type": error_type, "error_message": error_message})
+        track_detailed_error(
+            "cli_run_failed",
+            e,
+            context="Server execution or startup failure",
+            operation="run_server_execution",
+            additional_props={"has_dist_dir": dist_dir.exists() if dist_dir else False}
+        )
         raise
 
 
 # Add telemetry command group
 @app.command()
 def telemetry(
-    action: str = typer.Argument(..., help="Action to perform: 'enable' or 'disable'")
-):
+    action: str = typer.Argument(..., help="Action to perform: 'enable' or 'disable'"),
+) -> None:
     """Manage telemetry settings."""
     if action.lower() == "enable":
         set_telemetry_enabled(True, persist=True)
-        console.print("[green]✓[/green] Telemetry enabled. Thank you for helping improve Golf!")
+        console.print(
+            "[green]✓[/green] Telemetry enabled. Thank you for helping improve Golf!"
+        )
     elif action.lower() == "disable":
         set_telemetry_enabled(False, persist=True)
-        console.print("[yellow]Telemetry disabled.[/yellow] You can re-enable it anytime with: golf telemetry enable")
+        console.print(
+            "[yellow]Telemetry disabled.[/yellow] You can re-enable it anytime with: golf telemetry enable"
+        )
     else:
-        console.print(f"[red]Unknown action '{action}'. Use 'enable' or 'disable'.[/red]")
+        console.print(
+            f"[red]Unknown action '{action}'. Use 'enable' or 'disable'.[/red]"
+        )
         raise typer.Exit(code=1)
 
 
@@ -280,13 +402,13 @@ if __name__ == "__main__":
             border_style="green",
         )
     )
-    
+
     # Add telemetry notice if enabled
     if is_telemetry_enabled():
         console.print(
             "[dim]📊 Anonymous usage data is collected to improve Golf. "
             "Disable with: golf telemetry disable[/dim]\n"
         )
-    
+
     # Run the CLI app
-    app() 
+    app()

golf/commands/__init__.py

@@ -1,3 +1,3 @@
 """GolfMCP command implementations."""
 
-from golf.commands import init, build, run 
+from golf.commands import build, init, run