kollabor 0.4.9__py3-none-any.whl

core/config/service.py

@@ -0,0 +1,399 @@
+"""Configuration service providing high-level configuration operations."""
+
+import asyncio
+import logging
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional, Callable
+
+try:
+    from watchdog.observers import Observer
+    from watchdog.events import FileSystemEventHandler
+    WATCHDOG_AVAILABLE = True
+except ImportError:
+    WATCHDOG_AVAILABLE = False
+    Observer = None
+    FileSystemEventHandler = None
+
+from .manager import ConfigManager
+from .loader import ConfigLoader
+
+logger = logging.getLogger(__name__)
+
+
+if WATCHDOG_AVAILABLE:
+    class ConfigFileWatcher(FileSystemEventHandler):
+        """File system event handler for configuration file changes."""
+
+        def __init__(self, config_service: 'ConfigService'):
+            super().__init__()
+            self.config_service = config_service
+            self.last_modified = 0
+            self.debounce_delay = 0.5  # 500ms debounce
+
+        def on_modified(self, event):
+            """Handle file modification events."""
+            if event.is_directory:
+                return
+
+            if event.src_path == str(self.config_service.config_manager.config_path):
+                current_time = time.time()
+
+                # Debounce rapid file changes
+                if current_time - self.last_modified > self.debounce_delay:
+                    self.last_modified = current_time
+                    logger.info("Configuration file changed, triggering reload")
+                    # Schedule the reload in a thread-safe way
+                    try:
+                        loop = asyncio.get_running_loop()
+                        loop.call_soon_threadsafe(
+                            lambda: asyncio.create_task(self.config_service._handle_file_change())
+                        )
+                    except RuntimeError:
+                        # No event loop running, fall back to sync reload
+                        logger.warning("No event loop available, performing synchronous reload")
+                        self.config_service.reload()
+else:
+    class ConfigFileWatcher:
+        """Stub class when watchdog is not available."""
+        def __init__(self, config_service: 'ConfigService'):
+            pass
+
+
+class ConfigService:
+    """High-level configuration service providing a clean API.
+    
+    This service coordinates between the file-based ConfigManager and
+    the plugin-aware ConfigLoader to provide a simple interface for
+    all configuration operations.
+    """
+    
+    def __init__(self, config_path: Path, plugin_registry=None):
+        """Initialize the configuration service.
+
+        Args:
+            config_path: Path to the configuration file.
+            plugin_registry: Optional plugin registry for plugin configs.
+        """
+        self.config_manager = ConfigManager(config_path)
+        self.config_loader = ConfigLoader(self.config_manager, plugin_registry)
+        self.plugin_registry = plugin_registry
+
+        # Cached configuration for fallback
+        self._cached_config = None
+        self._config_error = None
+        self._reload_callbacks = []
+
+        # File watching setup
+        self._file_watcher = None
+        self._observer = None
+
+        # Load initial configuration
+        self._initialize_config()
+
+        # Start file watching if successful
+        self._start_file_watching()
+
+        logger.info(f"Configuration service initialized: {config_path}")
+    
+    def _initialize_config(self) -> None:
+        """Initialize configuration on service startup."""
+        try:
+            if self.config_manager.config_path.exists():
+                # Load existing config and merge with defaults
+                complete_config = self.config_loader.load_complete_config()
+                self.config_manager.config = complete_config
+                self._cached_config = complete_config.copy()
+                self._config_error = None
+                logger.info("Loaded and merged existing configuration")
+            else:
+                # Create new config with defaults and plugin configs
+                complete_config = self.config_loader.load_complete_config()
+                self.config_manager.config = complete_config
+                self._cached_config = complete_config.copy()
+                self.config_loader.save_merged_config(complete_config)
+                self._config_error = None
+                logger.info("Created new configuration file")
+        except Exception as e:
+            self._config_error = str(e)
+            logger.error(f"Failed to initialize configuration: {e}")
+            if self._cached_config:
+                logger.warning("Using cached configuration as fallback")
+                self.config_manager.config = self._cached_config
+            else:
+                # Use minimal base config as last resort
+                base_config = self.config_loader.get_base_config()
+                self.config_manager.config = base_config
+                self._cached_config = base_config.copy()
+                logger.warning("Using base configuration as fallback")
+    
+    def get(self, key_path: str, default: Any = None) -> Any:
+        """Get a configuration value using dot notation.
+        
+        Args:
+            key_path: Dot-separated path to the config value.
+            default: Default value if key not found.
+            
+        Returns:
+            Configuration value or default.
+        """
+        return self.config_manager.get(key_path, default)
+    
+    def set(self, key_path: str, value: Any) -> bool:
+        """Set a configuration value using dot notation.
+        
+        Args:
+            key_path: Dot-separated path to the config value.
+            value: Value to set.
+            
+        Returns:
+            True if set successful, False otherwise.
+        """
+        success = self.config_manager.set(key_path, value)
+        if success:
+            logger.debug(f"Configuration updated: {key_path}")
+        return success
+    
+    def reload(self) -> bool:
+        """Reload configuration from file and plugins.
+
+        Returns:
+            True if reload successful, False otherwise.
+        """
+        try:
+            complete_config = self.config_loader.load_complete_config()
+
+            # Validate the new configuration
+            old_config = self.config_manager.config
+            self.config_manager.config = complete_config
+            validation_result = self.validate_config()
+
+            if validation_result["valid"]:
+                # Success - update cache and clear error
+                self._cached_config = complete_config.copy()
+                self._config_error = None
+                logger.info("Configuration reloaded successfully")
+                self._notify_reload_callbacks()
+                return True
+            else:
+                # Validation failed - revert to cached config
+                self.config_manager.config = old_config
+                error_msg = f"Invalid configuration: {validation_result['errors']}"
+                self._config_error = error_msg
+                logger.error(error_msg)
+                return False
+
+        except Exception as e:
+            error_msg = f"Failed to reload configuration: {e}"
+            self._config_error = error_msg
+            logger.error(error_msg)
+
+            # Fallback to cached config if available
+            if self._cached_config:
+                logger.warning("Using cached configuration as fallback")
+                self.config_manager.config = self._cached_config
+
+            return False
+    
+    def update_from_plugins(self) -> bool:
+        """Update configuration with newly discovered plugins.
+        
+        Returns:
+            True if update successful, False otherwise.
+        """
+        return self.config_loader.update_with_plugins()
+    
+    def get_config_summary(self) -> Dict[str, Any]:
+        """Get a summary of the current configuration.
+        
+        Returns:
+            Dictionary with configuration metadata.
+        """
+        config = self.config_manager.config
+        plugin_count = len(self.plugin_registry.list_plugins()) if self.plugin_registry else 0
+        
+        return {
+            "config_file": str(self.config_manager.config_path),
+            "file_exists": self.config_manager.config_path.exists(),
+            "plugin_count": plugin_count,
+            "config_sections": list(config.keys()) if config else [],
+            "total_keys": self._count_keys(config),
+        }
+    
+    def _count_keys(self, config: Dict[str, Any]) -> int:
+        """Recursively count all keys in configuration."""
+        count = 0
+        for key, value in config.items():
+            count += 1
+            if isinstance(value, dict):
+                count += self._count_keys(value)
+        return count
+    
+    def validate_config(self) -> Dict[str, Any]:
+        """Validate current configuration structure.
+        
+        Returns:
+            Dictionary with validation results.
+        """
+        validation_result = {
+            "valid": True,
+            "errors": [],
+            "warnings": []
+        }
+        
+        config = self.config_manager.config
+        
+        # Check for required sections
+        required_sections = ["terminal", "input", "logging", "application"]
+        for section in required_sections:
+            if section not in config:
+                validation_result["errors"].append(f"Missing required section: {section}")
+                validation_result["valid"] = False
+        
+        # Check for required terminal settings
+        if "terminal" in config:
+            required_terminal_keys = ["render_fps", "thinking_effect"]
+            for key in required_terminal_keys:
+                if key not in config["terminal"]:
+                    validation_result["warnings"].append(f"Missing terminal.{key}, using default")
+        
+        # Check for valid FPS value
+        fps = self.get("terminal.render_fps")
+        if fps is not None and (not isinstance(fps, int) or fps <= 0 or fps > 120):
+            validation_result["warnings"].append(f"Invalid render_fps: {fps}, should be 1-120")
+        
+        logger.debug(f"Configuration validation: {validation_result}")
+        return validation_result
+    
+    def backup_config(self, backup_suffix: str = ".backup") -> Optional[Path]:
+        """Create a backup of the current configuration file.
+        
+        Args:
+            backup_suffix: Suffix to add to backup filename.
+            
+        Returns:
+            Path to backup file if successful, None otherwise.
+        """
+        if not self.config_manager.config_path.exists():
+            logger.warning("Cannot backup non-existent config file")
+            return None
+        
+        try:
+            backup_path = self.config_manager.config_path.with_suffix(
+                self.config_manager.config_path.suffix + backup_suffix
+            )
+            
+            import shutil
+            shutil.copy2(self.config_manager.config_path, backup_path)
+            
+            logger.info(f"Configuration backed up to: {backup_path}")
+            return backup_path
+            
+        except Exception as e:
+            logger.error(f"Failed to backup configuration: {e}")
+            return None
+    
+    def restore_from_backup(self, backup_path: Path) -> bool:
+        """Restore configuration from a backup file.
+        
+        Args:
+            backup_path: Path to backup file.
+            
+        Returns:
+            True if restore successful, False otherwise.
+        """
+        if not backup_path.exists():
+            logger.error(f"Backup file does not exist: {backup_path}")
+            return False
+        
+        try:
+            import shutil
+            shutil.copy2(backup_path, self.config_manager.config_path)
+            
+            # Reload configuration after restore
+            return self.reload()
+            
+        except Exception as e:
+            logger.error(f"Failed to restore from backup: {e}")
+            return False
+
+    def _start_file_watching(self) -> None:
+        """Start watching the configuration file for changes."""
+        if not WATCHDOG_AVAILABLE:
+            logger.debug("Watchdog not available, file watching disabled")
+            return
+
+        # Prevent duplicate watchers
+        if self._observer is not None:
+            logger.debug("File watcher already running, skipping initialization")
+            return
+
+        try:
+            self._file_watcher = ConfigFileWatcher(self)
+            self._observer = Observer()
+            self._observer.schedule(
+                self._file_watcher,
+                str(self.config_manager.config_path.parent),
+                recursive=False
+            )
+            self._observer.start()
+            logger.debug("Configuration file watcher started")
+        except RuntimeError as e:
+            if "already scheduled" in str(e):
+                logger.debug("File watcher path already being watched by another instance")
+            else:
+                logger.warning(f"Could not start configuration file watcher: {e}")
+        except Exception as e:
+            logger.warning(f"Could not start configuration file watcher: {e}")
+
+    def _stop_file_watching(self) -> None:
+        """Stop watching the configuration file."""
+        if self._observer:
+            self._observer.stop()
+            self._observer.join()
+            self._observer = None
+            self._file_watcher = None
+            logger.debug("Configuration file watcher stopped")
+
+    async def _handle_file_change(self) -> None:
+        """Handle configuration file changes with hot reload."""
+        success = self.reload()
+        if not success:
+            logger.warning("Configuration reload failed, using cached fallback")
+
+    def register_reload_callback(self, callback: Callable[[], None]) -> None:
+        """Register a callback to be notified when configuration reloads.
+
+        Args:
+            callback: Function to call after successful configuration reload.
+        """
+        self._reload_callbacks.append(callback)
+
+    def _notify_reload_callbacks(self) -> None:
+        """Notify all registered callbacks about configuration reload."""
+        for callback in self._reload_callbacks:
+            try:
+                callback()
+            except Exception as e:
+                logger.error(f"Config reload callback failed: {e}")
+
+    def get_config_error(self) -> Optional[str]:
+        """Get the current configuration error, if any.
+
+        Returns:
+            Error message string if there's a config error, None otherwise.
+        """
+        return self._config_error
+
+    def has_config_error(self) -> bool:
+        """Check if there's a current configuration error.
+
+        Returns:
+            True if there's an error, False otherwise.
+        """
+        return self._config_error is not None
+
+    def shutdown(self) -> None:
+        """Shutdown the configuration service and file watcher."""
+        self._stop_file_watching()
+        logger.info("Configuration service shutdown")

core/effects/__init__.py

@@ -0,0 +1 @@
+"""Visual effects module for special animations and displays."""

core/events/__init__.py

@@ -0,0 +1,12 @@
+"""Event system subsystem for Kollabor CLI."""
+
+from .bus import EventBus
+from .models import Event, EventType, Hook, HookStatus, HookPriority
+from .registry import HookRegistry
+from .executor import HookExecutor
+from .processor import EventProcessor
+
+__all__ = [
+    'EventBus', 'Event', 'EventType', 'Hook', 'HookStatus', 'HookPriority',
+    'HookRegistry', 'HookExecutor', 'EventProcessor'
+]

core/events/bus.py

@@ -0,0 +1,129 @@
+"""Event system for plugin communication."""
+
+import logging
+from typing import Any, Dict
+
+from .models import EventType, Hook
+from .registry import HookRegistry
+from .executor import HookExecutor
+from .processor import EventProcessor
+
+logger = logging.getLogger(__name__)
+
+
+class EventBus:
+    """Simplified event bus system for plugin communication.
+    
+    Coordinates between specialized components for hook registration
+    and event processing with clean separation of concerns.
+    """
+    
+    def __init__(self) -> None:
+        """Initialize the event bus with specialized components."""
+        self.hook_registry = HookRegistry()
+        self.hook_executor = HookExecutor()
+        self.event_processor = EventProcessor(self.hook_registry, self.hook_executor)
+        logger.info("Event bus initialized with specialized components")
+    
+    async def register_hook(self, hook: Hook) -> bool:
+        """Register a hook with the event bus.
+        
+        Args:
+            hook: The hook to register.
+            
+        Returns:
+            True if registration successful, False otherwise.
+        """
+        success = self.hook_registry.register_hook(hook)
+        if success:
+            logger.debug(f"Successfully registered hook: {hook.plugin_name}.{hook.name}")
+        else:
+            logger.error(f"Failed to register hook: {hook.plugin_name}.{hook.name}")
+        return success
+    
+    async def unregister_hook(self, plugin_name: str, hook_name: str) -> bool:
+        """Unregister a hook from the event bus.
+        
+        Args:
+            plugin_name: Name of the plugin that owns the hook.
+            hook_name: Name of the hook.
+            
+        Returns:
+            True if unregistration successful, False otherwise.
+        """
+        return self.hook_registry.unregister_hook(plugin_name, hook_name)
+    
+    async def emit_with_hooks(self, event_type: EventType, data: Dict[str, Any], source: str) -> Dict[str, Any]:
+        """Emit an event with pre/post hook processing.
+        
+        Args:
+            event_type: Type of event to emit.
+            data: Event data.
+            source: Source of the event.
+            
+        Returns:
+            Results from hook processing.
+        """
+        return await self.event_processor.process_event_with_phases(event_type, data, source)
+    
+    def get_hook_status(self) -> Dict[str, Any]:
+        """Get current status of all registered hooks.
+        
+        Returns:
+            Dictionary with hook status information.
+        """
+        return self.hook_registry.get_hook_status_summary()
+    
+    def get_registry_stats(self) -> Dict[str, Any]:
+        """Get comprehensive registry statistics.
+        
+        Returns:
+            Dictionary with detailed registry statistics.
+        """
+        return self.hook_registry.get_registry_stats()
+    
+    def enable_hook(self, plugin_name: str, hook_name: str) -> bool:
+        """Enable a registered hook.
+        
+        Args:
+            plugin_name: Name of the plugin that owns the hook.
+            hook_name: Name of the hook.
+            
+        Returns:
+            True if hook was enabled, False otherwise.
+        """
+        return self.hook_registry.enable_hook(plugin_name, hook_name)
+    
+    def disable_hook(self, plugin_name: str, hook_name: str) -> bool:
+        """Disable a registered hook.
+        
+        Args:
+            plugin_name: Name of the plugin that owns the hook.
+            hook_name: Name of the hook.
+            
+        Returns:
+            True if hook was disabled, False otherwise.
+        """
+        return self.hook_registry.disable_hook(plugin_name, hook_name)
+    
+    def get_hooks_for_event(self, event_type: EventType) -> int:
+        """Get the number of hooks registered for an event type.
+        
+        Args:
+            event_type: The event type to check.
+            
+        Returns:
+            Number of hooks registered for the event type.
+        """
+        hooks = self.hook_registry.get_hooks_for_event(event_type)
+        return len(hooks)
+    
+    def add_event_type_mapping(self, main_event: EventType, pre_event: EventType, post_event: EventType) -> None:
+        """Add a new event type mapping for pre/post processing.
+        
+        Args:
+            main_event: The main event type.
+            pre_event: The pre-processing event type.
+            post_event: The post-processing event type.
+        """
+        self.event_processor.add_event_type_mapping(main_event, pre_event, post_event)

core/events/executor.py

@@ -0,0 +1,154 @@
+"""Hook executor for individual hook execution with error handling."""
+
+import asyncio
+import logging
+import time
+from typing import Any, Dict, List
+
+from .models import Event, Hook, HookStatus
+from ..utils.error_utils import log_and_continue
+
+logger = logging.getLogger(__name__)
+
+
+class HookExecutor:
+    """Executes individual hooks with timeout and error handling.
+    
+    This class is responsible for the safe execution of a single hook,
+    including timeout management, error handling, and status tracking.
+    """
+    
+    def __init__(self):
+        """Initialize the hook executor."""
+        logger.debug("HookExecutor initialized")
+    
+    async def execute_hook(self, hook: Hook, event: Event) -> Dict[str, Any]:
+        """Execute a single hook with error handling and timeout.
+        
+        Args:
+            hook: The hook to execute.
+            event: The event being processed.
+            
+        Returns:
+            Dictionary with execution result and metadata.
+        """
+        hook_key = f"{hook.plugin_name}.{hook.name}"
+        result_metadata = {
+            "hook_key": hook_key,
+            "success": False,
+            "result": None,
+            "error": None,
+            "duration_ms": 0
+        }
+        
+        if not hook.enabled:
+            result_metadata["error"] = "hook_disabled"
+            logger.debug(f"Skipping disabled hook: {hook_key}")
+            return result_metadata
+        
+        if event.cancelled:
+            result_metadata["error"] = "event_cancelled"
+            logger.debug(f"Skipping hook due to cancelled event: {hook_key}")
+            return result_metadata
+        
+        # Track execution time
+        start_time = time.time()
+        
+        try:
+            # Update hook status to working
+            hook.status = HookStatus.WORKING
+            
+            # Execute hook with timeout
+            result = await asyncio.wait_for(
+                hook.callback(event.data, event),
+                timeout=hook.timeout
+            )
+            
+            # Calculate execution time
+            end_time = time.time()
+            result_metadata["duration_ms"] = max(1, int((end_time - start_time) * 1000))
+            
+            # Mark as successful
+            hook.status = HookStatus.COMPLETED
+            result_metadata["success"] = True
+            result_metadata["result"] = result
+            # Handle data transformation if hook returns modified data
+            if isinstance(result, dict) and "data" in result:
+                self._apply_data_transformation(event, result["data"])
+                logger.debug(f"Hook {hook_key} modified event data")
+                
+        except asyncio.TimeoutError:
+            end_time = time.time()
+            result_metadata["duration_ms"] = max(1, int((end_time - start_time) * 1000))
+            result_metadata["error"] = "timeout"
+            
+            hook.status = HookStatus.TIMEOUT
+            logger.warning(f"Hook {hook_key} timed out after {hook.timeout}s")
+            
+            # Handle timeout based on error action
+            if hook.error_action == "stop":
+                event.cancelled = True
+                logger.info(f"Event cancelled due to hook timeout: {hook_key}")
+                
+        except Exception as e:
+            end_time = time.time()
+            result_metadata["duration_ms"] = max(1, int((end_time - start_time) * 1000))
+            result_metadata["error"] = str(e)
+            
+            hook.status = HookStatus.FAILED
+            log_and_continue(logger, f"executing hook {hook_key}", e)
+            
+            # Handle error based on error action
+            if hook.error_action == "stop":
+                event.cancelled = True
+                logger.info(f"Event cancelled due to hook error: {hook_key}")
+        
+        return result_metadata
+    
+    def _apply_data_transformation(self, event: Event, hook_data: Dict[str, Any]) -> None:
+        """Apply data transformation from hook result to event.
+        
+        Args:
+            event: The event to modify.
+            hook_data: Data transformation from hook.
+        """
+        try:
+            if isinstance(hook_data, dict):
+                event.data.update(hook_data)
+            else:
+                logger.warning(f"Hook returned non-dict data transformation: {type(hook_data)}")
+        except Exception as e:
+            log_and_continue(logger, "applying hook data transformation", e)
+    
+    def get_execution_stats(self, results: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Get execution statistics from a list of hook results.
+        
+        Args:
+            results: List of hook execution results.
+            
+        Returns:
+            Dictionary with execution statistics.
+        """
+        if not results:
+            return {
+                "total_hooks": 0,
+                "successful": 0,
+                "failed": 0,
+                "timed_out": 0,
+                "total_duration_ms": 0,
+                "avg_duration_ms": 0
+            }
+        
+        successful = sum(1 for r in results if r.get("success", False))
+        failed = sum(1 for r in results if r.get("error") and r["error"] not in ["timeout", "hook_disabled", "event_cancelled"])
+        timed_out = sum(1 for r in results if r.get("error") == "timeout")
+        total_duration = sum(r.get("duration_ms", 0) for r in results)
+        
+        return {
+            "total_hooks": len(results),
+            "successful": successful,
+            "failed": failed,
+            "timed_out": timed_out,
+            "total_duration_ms": total_duration,
+            "avg_duration_ms": int(total_duration / len(results)) if results else 0
+        }