crackerjack 0.18.2__py3-none-any.whl → 0.45.2__py3-none-any.whl

crackerjack/mcp/websocket/websocket_handler.py

@@ -0,0 +1,276 @@
+import asyncio
+import typing as t
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path
+
+from acb import console
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+
+from crackerjack.core.timeout_manager import TimeoutStrategy, get_timeout_manager
+
+from .jobs import JobManager
+
+# console imported from acb
+
+
+# Phase 9.4: WebSocket Security Configuration
+@dataclass
+class WebSocketSecurityConfig:
+    """Security configuration for WebSocket connections.
+
+    Phase 9.4: Enhanced security hardening for MCP WebSocket server.
+    """
+
+    # Message limits
+    max_message_size: int = 1024 * 1024  # 1MB max message size
+    max_messages_per_connection: int = 10000  # Max messages before forcing reconnect
+    max_concurrent_connections: int = 100  # Limit concurrent WebSocket connections
+
+    # Origin validation (localhost only for MCP)
+    allowed_origins: set[str] | None = None  # None = allow all (default for local dev)
+
+    # Rate limiting
+    messages_per_second: int = 100  # Max messages per second per connection
+
+    def __post_init__(self) -> None:
+        """Initialize allowed origins with secure defaults."""
+        if self.allowed_origins is None:
+            # Default: only allow localhost connections
+            self.allowed_origins = {
+                "http://localhost",
+                "http://127.0.0.1",
+                "https://localhost",
+                "https://127.0.0.1",
+            }
+
+    def validate_origin(self, origin: str | None) -> bool:
+        """Validate WebSocket origin header.
+
+        Args:
+            origin: Origin header value
+
+        Returns:
+            True if origin is allowed, False otherwise
+        """
+        if not origin:
+            # Allow connections without origin (local tools)
+            return True
+
+        # Check against allowed origins
+        for allowed in self.allowed_origins or set():
+            if origin.startswith(allowed):
+                return True
+
+        console.print(
+            f"[red]Rejected WebSocket connection from unauthorized origin: {origin}[/red]"
+        )
+        return False
+
+
+class WebSocketHandler:
+    def __init__(
+        self,
+        job_manager: JobManager,
+        progress_dir: Path,
+        security_config: WebSocketSecurityConfig | None = None,
+        event_bridge: t.Any | None = None,  # EventBusWebSocketBridge from DI
+    ) -> None:
+        self.job_manager = job_manager
+        self.progress_dir = progress_dir
+        self.timeout_manager = get_timeout_manager()
+        self.security_config = security_config or WebSocketSecurityConfig()
+        self.event_bridge = event_bridge
+        self._connection_count = 0
+
+    async def handle_connection(self, websocket: WebSocket, job_id: str) -> None:
+        # Phase 9.4: Security validations
+        if not self.job_manager.validate_job_id(job_id):
+            await websocket.close(code=1008, reason="Invalid job ID")
+            return
+
+        # Check origin header
+        origin = websocket.headers.get("origin")
+        if not self.security_config.validate_origin(origin):
+            await websocket.close(code=1008, reason="Unauthorized origin")
+            return
+
+        # Check connection limit
+        if self._connection_count >= self.security_config.max_concurrent_connections:
+            await websocket.close(code=1008, reason="Connection limit reached")
+            console.print(
+                f"[yellow]Connection limit reached: {self._connection_count}[/yellow]"
+            )
+            return
+
+        try:
+            async with self.timeout_manager.timeout_context(
+                "websocket_connection",
+                timeout=3600.0,
+                strategy=TimeoutStrategy.GRACEFUL_DEGRADATION,
+            ):
+                await self._establish_connection(websocket, job_id)
+                await self._send_initial_progress(websocket, job_id)
+                await self._handle_message_loop(websocket, job_id)
+
+        except TimeoutError:
+            await self._handle_timeout_error(websocket, job_id)
+        except WebSocketDisconnect:
+            console.print(f"[yellow]WebSocket disconnected for job: {job_id}[/yellow]")
+        except Exception as e:
+            await self._handle_connection_error(websocket, job_id, e)
+        finally:
+            await self._cleanup_connection(job_id, websocket)
+
+    async def _establish_connection(self, websocket: WebSocket, job_id: str) -> None:
+        await websocket.accept()
+        self._connection_count += 1  # Phase 9.4: Track concurrent connections
+        self.job_manager.add_connection(job_id, websocket)
+
+        # Phase 7.3: Register client with event bridge for real-time updates
+        if self.event_bridge:
+            await self.event_bridge.register_client(job_id, websocket)
+
+        console.print(
+            f"[green]WebSocket connected for job: {job_id} (connections: {self._connection_count})[/green]"
+        )
+
+    async def _send_initial_progress(self, websocket: WebSocket, job_id: str) -> None:
+        try:
+            async with self.timeout_manager.timeout_context(
+                "websocket_broadcast",
+                timeout=5.0,
+                strategy=TimeoutStrategy.FAIL_FAST,
+            ):
+                initial_progress = self.job_manager.get_job_progress(job_id)
+                if initial_progress:
+                    await websocket.send_json(initial_progress)
+                else:
+                    await websocket.send_json(
+                        self._create_initial_progress_message(job_id)
+                    )
+        except Exception as e:
+            console.print(
+                f"[red]Failed to send initial progress for {job_id}: {e}[/red]"
+            )
+
+    def _create_initial_progress_message(self, job_id: str) -> dict[str, t.Any]:
+        return {
+            "job_id": job_id,
+            "status": "waiting",
+            "message": "Waiting for job to start...",
+            "overall_progress": 0,
+            "iteration": 0,
+            "max_iterations": 10,
+            "current_stage": "Initializing",
+        }
+
+    async def _handle_message_loop(self, websocket: WebSocket, job_id: str) -> None:
+        message_count = 0
+        max_messages = (
+            self.security_config.max_messages_per_connection
+        )  # Phase 9.4: Use config
+
+        while message_count < max_messages:
+            try:
+                should_continue = await self._process_single_message(
+                    websocket, job_id, message_count + 1
+                )
+                if not should_continue:
+                    break
+                message_count += 1
+            except (TimeoutError, WebSocketDisconnect, Exception):
+                break
+
+        if message_count >= max_messages:
+            console.print(
+                f"[yellow]WebSocket connection limit reached for {job_id}: {max_messages} messages[/yellow]"
+            )
+
+    async def _process_single_message(
+        self, websocket: WebSocket, job_id: str, message_count: int
+    ) -> bool:
+        try:
+            async with self.timeout_manager.timeout_context(
+                "websocket_message",
+                timeout=30.0,
+                strategy=TimeoutStrategy.FAIL_FAST,
+            ):
+                data = await asyncio.wait_for(
+                    websocket.receive_text(),
+                    timeout=25.0,
+                )
+
+                console.print(
+                    f"[blue]Received message {message_count} for {job_id}: {data[:100]}...[/blue]",
+                )
+
+                await asyncio.wait_for(
+                    websocket.send_json(
+                        {
+                            "type": "echo",
+                            "message": f"Received: {data}",
+                            "job_id": job_id,
+                            "message_count": message_count,
+                        }
+                    ),
+                    timeout=5.0,
+                )
+
+                return True
+
+        except TimeoutError:
+            console.print(
+                f"[yellow]Message timeout for {job_id} after {message_count} messages[/yellow]"
+            )
+            return False
+        except WebSocketDisconnect:
+            console.print(f"[yellow]WebSocket disconnected for job: {job_id}[/yellow]")
+            return False
+        except Exception as e:
+            console.print(f"[red]WebSocket message error for job {job_id}: {e}[/red]")
+            return False
+
+    async def _handle_timeout_error(self, websocket: WebSocket, job_id: str) -> None:
+        console.print(
+            f"[yellow]WebSocket connection timeout for job: {job_id}[/yellow]"
+        )
+        with suppress(Exception):
+            await websocket.close(code=1001, reason="Connection timeout")
+
+    async def _handle_connection_error(
+        self, websocket: WebSocket, job_id: str, error: Exception
+    ) -> None:
+        console.print(f"[red]WebSocket error for job {job_id}: {error}[/red]")
+        with suppress(Exception):
+            await websocket.close(code=1011, reason="Internal error")
+
+    async def _cleanup_connection(self, job_id: str, websocket: WebSocket) -> None:
+        try:
+            self.job_manager.remove_connection(job_id, websocket)
+
+            # Phase 7.3: Unregister client from event bridge
+            if self.event_bridge:
+                await self.event_bridge.unregister_client(job_id, websocket)
+
+            self._connection_count = max(
+                0, self._connection_count - 1
+            )  # Phase 9.4: Decrement count
+            console.print(
+                f"[yellow]WebSocket disconnected for job: {job_id} (connections: {self._connection_count})[/yellow]"
+            )
+        except Exception as e:
+            console.print(f"[red]Error removing connection for {job_id}: {e}[/red]")
+
+
+def register_websocket_routes(
+    app: FastAPI,
+    job_manager: JobManager,
+    progress_dir: Path,
+    event_bridge: t.Any | None = None,  # EventBusWebSocketBridge from DI
+) -> None:
+    handler = WebSocketHandler(job_manager, progress_dir, event_bridge=event_bridge)
+
+    @app.websocket("/ws/progress/{job_id}")
+    async def websocket_progress_endpoint(websocket: WebSocket, job_id: str) -> None:
+        await handler.handle_connection(websocket, job_id)

crackerjack/mcp/websocket_server.py

@@ -0,0 +1,10 @@
+from .websocket import WebSocketServer, main
+
+__all__ = ["WebSocketServer", "main"]
+
+
+if __name__ == "__main__":
+    import sys
+
+    port = int(sys.argv[1]) if len(sys.argv) > 1 else 8675
+    main(port)

crackerjack/models/README.md

@@ -0,0 +1,308 @@
+# Models
+
+> Crackerjack Docs: [Main](<../../README.md>) | [CLAUDE.md](../../docs/guides/CLAUDE.md) | [Models](<./README.md>)
+
+Data models, schemas, and protocol definitions for the Crackerjack architecture.
+
+## Overview
+
+The models package provides the foundational data structures and protocol-based interfaces that define Crackerjack's architecture. The **protocol-based dependency injection (DI) pattern** is the most critical architectural pattern in Crackerjack, enabling loose coupling, testability, and clean separation of concerns.
+
+## Key Components
+
+### protocols.py - THE MOST CRITICAL FILE
+
+**This is the heart of Crackerjack's architecture.** Always import protocols from here, never concrete classes.
+
+**Core Service Protocols:**
+
+- `ServiceProtocol` - Base protocol for all ACB services with lifecycle management
+- `Console` (ConsoleInterface) - Rich console output interface
+- `TestManagerProtocol` - Test execution and coverage management
+- `HookManager` / `SecurityAwareHookManager` - Pre-commit hook orchestration
+- `CoverageRatchetProtocol` - Coverage baseline tracking
+- `SecurityServiceProtocol` - Security validation and secret detection
+
+**Configuration & File System:**
+
+- `UnifiedConfigurationServiceProtocol` - Centralized configuration access
+- `FileSystemServiceProtocol` / `EnhancedFileSystemServiceProtocol` - File operations
+- `GitServiceProtocol` / `GitInterface` - Git repository interactions
+- `SmartFileFilterProtocol` - Intelligent file filtering
+
+**Quality Assurance:**
+
+- `QAAdapterProtocol` - Base protocol for all QA check adapters
+- `QAOrchestratorProtocol` - QA check coordination and execution
+
+**Hook Orchestration (Phase 3):**
+
+- `ExecutionStrategyProtocol` - Hook execution strategies (parallel/sequential/adaptive)
+- `CacheStrategyProtocol` - Result caching strategies
+- `HookOrchestratorProtocol` - Hook lifecycle and dependency resolution
+
+**Performance & Monitoring:**
+
+- `PerformanceMonitorProtocol` - Workflow performance tracking
+- `PerformanceBenchmarkProtocol` / `PerformanceBenchmarkServiceProtocol` - Benchmarking
+- `MemoryOptimizerProtocol` - Memory optimization tracking
+- `PerformanceCacheProtocol` - Performance result caching
+
+**Agent System (Phase 4):**
+
+- `AgentCoordinatorProtocol` - AI agent coordination and issue routing
+- `AgentTrackerProtocol` - Agent execution metrics tracking
+- `AgentDebuggerProtocol` - Agent debugging and activity logging
+
+**Orchestration:**
+
+- `ServiceWatchdogProtocol` - Service health monitoring and restart
+- `TimeoutManagerProtocol` - Centralized timeout management
+- `ParallelExecutorProtocol` / `ParallelHookExecutorProtocol` - Parallel task execution
+- `AsyncCommandExecutorProtocol` - Async command execution with caching
+
+**Publishing & Documentation:**
+
+- `PublishManager` - Package publishing and versioning
+- `DocumentationServiceProtocol` - Automated documentation generation
+- `APIExtractorProtocol` / `DocumentationGeneratorProtocol` / `DocumentationValidatorProtocol` - Doc tooling
+
+### Configuration Models
+
+**qa_config.py** - Quality assurance configuration:
+
+- `QACheckConfig` - Configuration for individual QA checks
+- Check-specific settings (file patterns, timeouts, retries)
+- Pydantic validation for type safety
+
+**config.py** - Core configuration models:
+
+- Project-wide configuration structures
+- ACB Settings integration
+- Environment-specific overrides
+
+**config_adapter.py** - Configuration adapters:
+
+- Bridges between different configuration formats
+- Legacy config migration support
+
+### Result Models
+
+**qa_results.py** - Quality assurance results:
+
+- `QAResult` - Individual check results
+- `QACheckType` - Enumeration of check types
+- Result aggregation structures
+
+**results.py** - Execution results:
+
+- `ExecutionResult` - Individual execution outcomes
+- `ParallelExecutionResult` - Parallel execution aggregation
+- Performance metrics and timing data
+
+**task.py** - Task and hook models:
+
+- `HookResult` - Pre-commit hook execution results
+- `SessionTracker` - Session metadata and task tracking
+- Task lifecycle management
+
+### Specialized Models
+
+**semantic_models.py** - Semantic analysis models:
+
+- Code comprehension structures
+- Semantic analysis results
+- Intelligent refactoring support
+
+**resource_protocols.py** - Resource management protocols:
+
+- Resource lifecycle interfaces
+- Resource cleanup coordination
+
+## THE MOST CRITICAL PATTERN: Protocol-Based Dependency Injection
+
+### Gold Standard Usage
+
+```python
+# ✅ CORRECT - Always import protocols from models/protocols.py
+from acb.depends import depends, Inject
+from crackerjack.models.protocols import (
+    Console,
+    TestManagerProtocol,
+    SecurityServiceProtocol,
+)
+
+
+@depends.inject
+def setup_environment(
+    console: Inject[Console] = None,
+    test_manager: Inject[TestManagerProtocol] = None,
+    security: Inject[SecurityServiceProtocol] = None,
+) -> None:
+    """All functions use @depends.inject with protocol-based dependencies."""
+    console.print("[green]Environment configured[/green]")
+    test_manager.validate_test_environment()
+    security.validate_file_safety("/path/to/file")
+
+
+class MyCoordinator:
+    @depends.inject
+    def __init__(
+        self,
+        console: Inject[Console],
+        test_manager: Inject[TestManagerProtocol],
+    ) -> None:
+        """Perfect DI integration with protocol-based dependencies."""
+        self.console = console
+        self.test_manager = test_manager
+```
+
+### Anti-Patterns to Avoid
+
+```python
+# ❌ WRONG - Direct class imports (BREAKS ARCHITECTURE)
+from crackerjack.managers.test_manager import TestManager
+from rich.console import Console as RichConsole
+
+# ❌ WRONG - Manual fallbacks bypass DI
+self.console = console or Console()
+self.cache = cache or CrackerjackCache()
+
+# ❌ WRONG - Factory functions bypass DI
+self.tracker = get_agent_tracker()
+self.timeout_manager = get_timeout_manager()
+
+# ❌ WRONG - Direct service instantiation
+self.logger = logging.getLogger(__name__)
+```
+
+## Why Protocol-Based DI?
+
+1. **Loose Coupling**: Depend on interfaces, not implementations
+1. **Testability**: Easy to mock with protocol implementations
+1. **Flexibility**: Swap implementations without changing dependents
+1. **Type Safety**: Runtime type checking via `@runtime_checkable`
+1. **Clear Contracts**: Protocol defines exact interface requirements
+1. **ACB Integration**: Seamless integration with ACB dependency injection
+
+## Usage Examples
+
+### Using Protocols for Type Hints
+
+```python
+from crackerjack.models.protocols import Console, FileSystemServiceProtocol
+
+
+def process_files(
+    console: Console,
+    fs: FileSystemServiceProtocol,
+    paths: list[Path],
+) -> bool:
+    """Process files with protocol-based dependencies."""
+    for path in paths:
+        if fs.exists(path):
+            content = fs.read_file(path)
+            console.print(f"Processing {path}")
+    return True
+```
+
+### Creating Protocol Implementations
+
+```python
+import typing as t
+from crackerjack.models.protocols import ServiceProtocol
+
+
+@t.runtime_checkable
+class MyServiceProtocol(ServiceProtocol, t.Protocol):
+    """Custom service protocol extending base ServiceProtocol."""
+
+    def custom_operation(self, data: str) -> bool:
+        """Custom operation for this service."""
+        ...
+
+
+class MyService:
+    """Concrete implementation of MyServiceProtocol."""
+
+    def initialize(self) -> None:
+        """Initialize service."""
+        pass
+
+    def cleanup(self) -> None:
+        """Cleanup resources."""
+        pass
+
+    def health_check(self) -> bool:
+        """Health check."""
+        return True
+
+    # ... implement all ServiceProtocol methods ...
+
+    def custom_operation(self, data: str) -> bool:
+        """Implementation of custom operation."""
+        return True
+```
+
+### Dependency Injection Integration
+
+```python
+from acb.depends import depends
+from crackerjack.models.protocols import Console, TestManagerProtocol
+
+# Register concrete implementation
+depends.set(Console, MyConsoleImplementation())
+depends.set(TestManagerProtocol, MyTestManager())
+
+
+# Inject in functions/classes
+@depends.inject
+def my_function(
+    console: Console = depends(),
+    test_manager: TestManagerProtocol = depends(),
+) -> None:
+    """Function with automatic dependency injection."""
+    console.print("Running tests...")
+    test_manager.run_tests(options)
+```
+
+## Configuration
+
+Models use **Pydantic** for validation and type safety:
+
+```python
+from pydantic import BaseModel, Field
+
+
+class MyConfig(BaseModel):
+    """Example configuration model."""
+
+    timeout: int = Field(default=300, gt=0, description="Timeout in seconds")
+    enabled: bool = Field(default=True, description="Enable feature")
+    patterns: list[str] = Field(default_factory=list, description="File patterns")
+```
+
+## Best Practices
+
+1. **ALWAYS Import Protocols**: Never import concrete classes for dependencies
+1. **Use @runtime_checkable**: Mark all protocols with `@runtime_checkable`
+1. **Extend ServiceProtocol**: Base all service protocols on `ServiceProtocol`
+1. **Use Inject[T]**: Use `Inject[ProtocolType]` type hints for DI parameters
+1. **Validate with Pydantic**: Use Pydantic models for configuration validation
+1. **Document Protocols**: Add comprehensive docstrings to protocol methods
+1. **Type Annotate Everything**: Use Python 3.13+ type hints (`|` unions)
+
+## Related Documentation
+
+- [CLAUDE.md](../../docs/guides/CLAUDE.md) - Architecture patterns and DI guidelines
+- [Managers](<../managers/README.md>) - Protocol implementations
+- [Services](<../services/README.md>) - Service layer implementations
+- [Core](<../core/README.md>) - Coordinators and orchestration
+- [COVERAGE_POLICY.md](<../../docs/reference/COVERAGE_POLICY.md>) - Testing requirements
+
+## Future Enhancements
+
+- Phase 5: Additional agent system protocols
+- Enhanced validation protocols for AI agent fixes
+- Extended performance monitoring protocols
+- Advanced caching strategy protocols

crackerjack/models/__init__.py

@@ -0,0 +1,40 @@
+from .config import (
+    AIConfig,
+    CleaningConfig,
+    CleanupConfig,
+    ExecutionConfig,
+    GitConfig,
+    HookConfig,
+    ProgressConfig,
+    PublishConfig,
+    TestConfig,
+    WorkflowOptions,
+)
+from .protocols import OptionsProtocol, QAAdapterProtocol, QAOrchestratorProtocol
+from .qa_config import QACheckConfig, QAOrchestratorConfig
+from .qa_results import QACheckType, QAResult, QAResultStatus
+from .task import HookResult, SessionTracker, TaskStatus
+
+__all__ = [
+    "AIConfig",
+    "CleaningConfig",
+    "CleanupConfig",
+    "ExecutionConfig",
+    "GitConfig",
+    "HookConfig",
+    "HookResult",
+    "OptionsProtocol",
+    "ProgressConfig",
+    "PublishConfig",
+    "QAAdapterProtocol",
+    "QACheckConfig",
+    "QACheckType",
+    "QAOrchestratorConfig",
+    "QAOrchestratorProtocol",
+    "QAResult",
+    "QAResultStatus",
+    "SessionTracker",
+    "TaskStatus",
+    "TestConfig",
+    "WorkflowOptions",
+]