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

crackerjack/mcp/websocket/server.py

@@ -8,15 +8,13 @@ import typing as t
 from pathlib import Path
 
 import uvicorn
-from rich.console import Console
+from acb import console
 
 from crackerjack.core.timeout_manager import get_timeout_manager
 
 from .app import create_websocket_app
 from .jobs import JobManager
 
-console = Console()
-
 
 class WebSocketServer:
     def __init__(self, port: int = 8675) -> None:

crackerjack/mcp/websocket/websocket_handler.py

@@ -1,29 +1,108 @@
 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 rich.console import Console
 
 from crackerjack.core.timeout_manager import TimeoutStrategy, get_timeout_manager
 
 from .jobs import JobManager
 
-console = Console()
+# 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) -> None:
+    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",
@@ -45,8 +124,16 @@ class WebSocketHandler:
 
     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)
-        console.print(f"[green]WebSocket connected for job: {job_id}[/green]")
+
+        # 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:
@@ -80,7 +167,9 @@ class WebSocketHandler:
 
     async def _handle_message_loop(self, websocket: WebSocket, job_id: str) -> None:
         message_count = 0
-        max_messages = 10000
+        max_messages = (
+            self.security_config.max_messages_per_connection
+        )  # Phase 9.4: Use config
 
         while message_count < max_messages:
             try:
@@ -159,6 +248,17 @@ class WebSocketHandler:
     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]")
 
@@ -167,8 +267,9 @@ 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)
+    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:

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

@@ -10,7 +10,9 @@ from .config import (
     TestConfig,
     WorkflowOptions,
 )
-from .protocols import OptionsProtocol
+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__ = [
@@ -24,6 +26,13 @@ __all__ = [
     "OptionsProtocol",
     "ProgressConfig",
     "PublishConfig",
+    "QAAdapterProtocol",
+    "QACheckConfig",
+    "QACheckType",
+    "QAOrchestratorConfig",
+    "QAOrchestratorProtocol",
+    "QAResult",
+    "QAResultStatus",
     "SessionTracker",
     "TaskStatus",
     "TestConfig",