kollabor 0.4.9__py3-none-any.whl

core/fullscreen/manager.py

@@ -0,0 +1,302 @@
+"""Full-screen manager for plugin coordination and modal integration."""
+
+import asyncio
+import logging
+from typing import Dict, List, Optional, Any
+
+from ..events.models import EventType
+from .plugin import FullScreenPlugin, PluginMetadata
+from .session import FullScreenSession
+
+logger = logging.getLogger(__name__)
+
+
+class FullScreenManager:
+    """Manages full-screen plugins and their integration with the modal system.
+
+    This class coordinates between plugins, the event bus, and the modal system
+    to provide seamless full-screen experiences that properly pause the main
+    application interface.
+    """
+
+    def __init__(self, event_bus, terminal_renderer):
+        """Initialize the full-screen manager.
+
+        Args:
+            event_bus: Event bus for modal system integration.
+            terminal_renderer: Main terminal renderer (for compatibility).
+        """
+        self.event_bus = event_bus
+        self.terminal_renderer = terminal_renderer
+
+        # Plugin registry
+        self.plugins: Dict[str, FullScreenPlugin] = {}
+        self.plugin_aliases: Dict[str, str] = {}
+
+        # Session management
+        self.current_session: Optional[FullScreenSession] = None
+        self.session_history: List[Dict[str, Any]] = []
+
+        logger.info("FullScreenManager initialized")
+
+    def register_plugin(self, plugin: FullScreenPlugin) -> bool:
+        """Register a full-screen plugin.
+
+        Args:
+            plugin: The plugin to register.
+
+        Returns:
+            True if registration was successful, False otherwise.
+        """
+        try:
+            if plugin.name in self.plugins:
+                logger.warning(f"Plugin {plugin.name} already registered, overriding")
+
+            # Register main name
+            self.plugins[plugin.name] = plugin
+
+            # Register aliases
+            for alias in plugin.metadata.aliases:
+                if alias in self.plugin_aliases:
+                    logger.warning(f"Alias {alias} already registered, overriding")
+                self.plugin_aliases[alias] = plugin.name
+
+            logger.info(f"Registered plugin: {plugin.name} with {len(plugin.metadata.aliases)} aliases")
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to register plugin {plugin.name}: {e}")
+            return False
+
+    def unregister_plugin(self, name: str) -> bool:
+        """Unregister a plugin.
+
+        Args:
+            name: Name of the plugin to unregister.
+
+        Returns:
+            True if unregistration was successful, False otherwise.
+        """
+        try:
+            if name not in self.plugins:
+                logger.warning(f"Plugin {name} not found for unregistration")
+                return False
+
+            plugin = self.plugins[name]
+
+            # Remove aliases
+            for alias in plugin.metadata.aliases:
+                if alias in self.plugin_aliases:
+                    del self.plugin_aliases[alias]
+
+            # Remove main registration
+            del self.plugins[name]
+
+            logger.info(f"Unregistered plugin: {name}")
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to unregister plugin {name}: {e}")
+            return False
+
+    def get_plugin(self, name: str) -> Optional[FullScreenPlugin]:
+        """Get a plugin by name or alias.
+
+        Args:
+            name: Plugin name or alias.
+
+        Returns:
+            Plugin instance if found, None otherwise.
+        """
+        # Check direct name first
+        if name in self.plugins:
+            return self.plugins[name]
+
+        # Check aliases
+        if name in self.plugin_aliases:
+            actual_name = self.plugin_aliases[name]
+            return self.plugins.get(actual_name)
+
+        return None
+
+    def list_plugins(self) -> List[PluginMetadata]:
+        """List all registered plugins.
+
+        Returns:
+            List of plugin metadata.
+        """
+        return [plugin.metadata for plugin in self.plugins.values()]
+
+    async def launch_plugin(self, name: str, **kwargs) -> bool:
+        """Launch a full-screen plugin with modal integration.
+
+        Args:
+            name: Plugin name or alias to launch.
+            **kwargs: Additional arguments for plugin configuration.
+
+        Returns:
+            True if plugin launched successfully, False otherwise.
+        """
+        try:
+            # Check if session is already active
+            if self.current_session and self.current_session.running:
+                logger.warning("Cannot launch plugin - session already active")
+                return False
+
+            # Get plugin
+            plugin = self.get_plugin(name)
+            if not plugin:
+                logger.error(f"Plugin not found: {name}")
+                return False
+
+            logger.info(f"Launching full-screen plugin: {plugin.name}")
+
+            # Enter modal mode using the proven modal system
+            await self._enter_modal_mode(plugin)
+
+            try:
+                # Create and run session
+                logger.info(f"Creating session for plugin: {plugin.name}")
+                self.current_session = FullScreenSession(plugin, self.event_bus, **kwargs)
+                logger.info(f"Running session for plugin: {plugin.name}")
+                success = await self.current_session.run()
+                logger.info(f"Session completed with success: {success}")
+
+                # Record session in history
+                self._record_session(plugin, success)
+
+                return success
+
+            finally:
+                # Always exit modal mode
+                await self._exit_modal_mode(plugin)
+                self.current_session = None
+
+        except Exception as e:
+            logger.error(f"Failed to launch plugin {name}: {e}")
+            return False
+
+    async def stop_current_session(self) -> bool:
+        """Stop the currently running session.
+
+        Returns:
+            True if session was stopped, False if no session active.
+        """
+        if not self.current_session:
+            return False
+
+        try:
+            self.current_session.stop()
+            return True
+        except Exception as e:
+            logger.error(f"Error stopping session: {e}")
+            return False
+
+    def is_session_active(self) -> bool:
+        """Check if a full-screen session is currently active.
+
+        Returns:
+            True if session is active, False otherwise.
+        """
+        return (self.current_session is not None and
+                self.current_session.running)
+
+    def get_current_plugin(self) -> Optional[FullScreenPlugin]:
+        """Get the currently running plugin.
+
+        Returns:
+            Current plugin if session is active, None otherwise.
+        """
+        if self.current_session:
+            return self.current_session.plugin
+        return None
+
+    async def _enter_modal_mode(self, plugin: FullScreenPlugin):
+        """Enter modal mode for full-screen plugin.
+
+        Uses the same modal system as /config command for consistent behavior.
+
+        Args:
+            plugin: The plugin being launched.
+        """
+        try:
+            # Emit MODAL_TRIGGER event (same as Matrix effect)
+            await self.event_bus.emit_with_hooks(
+                EventType.MODAL_TRIGGER,
+                {
+                    "trigger_source": "fullscreen_plugin",
+                    "plugin_name": plugin.name,
+                    "mode": "fullscreen",
+                    "fullscreen_plugin": True
+                },
+                "fullscreen_manager"
+            )
+            logger.info(f"🎯 Entered modal mode for plugin: {plugin.name}")
+
+        except Exception as e:
+            logger.error(f"Failed to enter modal mode for {plugin.name}: {e}")
+            raise
+
+    async def _exit_modal_mode(self, plugin: FullScreenPlugin):
+        """Exit modal mode after plugin finishes.
+
+        Args:
+            plugin: The plugin that finished.
+        """
+        try:
+            # Emit MODAL_HIDE event
+            await self.event_bus.emit_with_hooks(
+                EventType.MODAL_HIDE,
+                {
+                    "source": "fullscreen_plugin",
+                    "plugin_name": plugin.name,
+                    "completed": True
+                },
+                "fullscreen_manager"
+            )
+            logger.info(f"🔄 Exited modal mode for plugin: {plugin.name}")
+
+        except Exception as e:
+            logger.error(f"Failed to exit modal mode for {plugin.name}: {e}")
+
+    def _record_session(self, plugin: FullScreenPlugin, success: bool):
+        """Record session in history.
+
+        Args:
+            plugin: The plugin that ran.
+            success: Whether the session completed successfully.
+        """
+        session_record = {
+            "plugin_name": plugin.name,
+            "success": success,
+            "stats": self.current_session.get_stats() if self.current_session else None,
+            "timestamp": asyncio.get_event_loop().time()
+        }
+        self.session_history.append(session_record)
+
+        # Keep only last 100 sessions
+        if len(self.session_history) > 100:
+            self.session_history = self.session_history[-100:]
+
+    def get_session_history(self) -> List[Dict[str, Any]]:
+        """Get session execution history.
+
+        Returns:
+            List of session records.
+        """
+        return self.session_history.copy()
+
+    def get_manager_stats(self) -> Dict[str, Any]:
+        """Get manager statistics.
+
+        Returns:
+            Dictionary with manager statistics.
+        """
+        return {
+            "plugins_registered": len(self.plugins),
+            "aliases_registered": len(self.plugin_aliases),
+            "session_active": self.is_session_active(),
+            "current_plugin": self.get_current_plugin().name if self.get_current_plugin() else None,
+            "total_sessions": len(self.session_history),
+            "successful_sessions": sum(1 for s in self.session_history if s["success"])
+        }

core/fullscreen/plugin.py

@@ -0,0 +1,204 @@
+"""Base class for full-screen plugins."""
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional
+from dataclasses import dataclass, field
+
+from ..io.key_parser import KeyPress
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PluginMetadata:
+    """Metadata for a full-screen plugin."""
+    name: str
+    description: str = ""
+    version: str = "1.0.0"
+    author: str = ""
+    category: str = "general"
+    icon: str = ""
+    aliases: list = field(default_factory=list)
+    settings: Dict[str, Any] = field(default_factory=dict)
+
+
+class FullScreenPlugin(ABC):
+    """Base class for all full-screen plugins.
+
+    This class provides the standard interface that all full-screen plugins
+    must implement. It handles the lifecycle, rendering, and input management
+    for plugins that take complete terminal control.
+    """
+
+    def __init__(self, metadata: PluginMetadata):
+        """Initialize the full-screen plugin.
+
+        Args:
+            metadata: Plugin metadata including name, description, etc.
+        """
+        self.metadata = metadata
+        self.renderer: Optional['FullScreenRenderer'] = None
+        self.running = False
+        self.initialized = False
+
+        # Plugin state
+        self.start_time = 0.0
+        self.frame_count = 0
+        self.last_frame_time = 0.0
+
+        logger.info(f"Initialized full-screen plugin: {metadata.name}")
+
+    @property
+    def name(self) -> str:
+        """Get the plugin name."""
+        return self.metadata.name
+
+    @property
+    def description(self) -> str:
+        """Get the plugin description."""
+        return self.metadata.description
+
+    async def initialize(self, renderer: 'FullScreenRenderer') -> bool:
+        """Initialize the plugin with a renderer.
+
+        This method is called once when the plugin is loaded. Override
+        this method to set up any resources your plugin needs.
+
+        Args:
+            renderer: The full-screen renderer instance.
+
+        Returns:
+            True if initialization was successful, False otherwise.
+        """
+        try:
+            self.renderer = renderer
+            self.initialized = True
+            logger.info(f"Plugin {self.name} initialized successfully")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to initialize plugin {self.name}: {e}")
+            return False
+
+    @abstractmethod
+    async def render_frame(self, delta_time: float) -> bool:
+        """Render a single frame.
+
+        This method is called every frame while the plugin is active.
+        Override this method to implement your plugin's visual output.
+
+        Args:
+            delta_time: Time elapsed since last frame in seconds.
+
+        Returns:
+            True to continue running, False to exit the plugin.
+        """
+        pass
+
+    @abstractmethod
+    async def handle_input(self, key_press: KeyPress) -> bool:
+        """Handle user input.
+
+        This method is called whenever the user presses a key while
+        your plugin is active. Override this method to handle input.
+
+        Args:
+            key_press: The key that was pressed.
+
+        Returns:
+            True to exit the plugin, False to continue running.
+        """
+        pass
+
+    async def on_start(self):
+        """Called when the plugin starts running.
+
+        Override this method to perform any setup that should happen
+        when the plugin begins execution (after initialization).
+        """
+        self.running = True
+        self.start_time = asyncio.get_event_loop().time()
+        self.frame_count = 0
+        logger.info(f"Plugin {self.name} started")
+
+    async def on_stop(self):
+        """Called when the plugin stops running.
+
+        Override this method to perform any cleanup that should happen
+        when the plugin finishes execution.
+        """
+        self.running = False
+        logger.info(f"Plugin {self.name} stopped")
+
+    async def cleanup(self):
+        """Clean up plugin resources.
+
+        This method is called when the plugin is being unloaded.
+        Override this method to clean up any resources your plugin allocated.
+        """
+        self.initialized = False
+        self.renderer = None
+        logger.info(f"Plugin {self.name} cleaned up")
+
+    def get_runtime_stats(self) -> Dict[str, Any]:
+        """Get runtime statistics for the plugin.
+
+        Returns:
+            Dictionary with runtime statistics.
+        """
+        current_time = asyncio.get_event_loop().time()
+        runtime = current_time - self.start_time if self.running else 0
+
+        return {
+            "name": self.name,
+            "running": self.running,
+            "initialized": self.initialized,
+            "runtime_seconds": runtime,
+            "frame_count": self.frame_count,
+            "fps": self.frame_count / runtime if runtime > 0 else 0
+        }
+
+    def update_frame_stats(self):
+        """Update frame statistics. Called by the framework."""
+        self.frame_count += 1
+        self.last_frame_time = asyncio.get_event_loop().time()
+
+
+class ExamplePlugin(FullScreenPlugin):
+    """Example plugin implementation for reference."""
+
+    def __init__(self):
+        """Initialize the example plugin."""
+        metadata = PluginMetadata(
+            name="example",
+            description="Example full-screen plugin for demonstration",
+            author="Framework",
+            category="demo"
+        )
+        super().__init__(metadata)
+
+    async def render_frame(self, delta_time: float) -> bool:
+        """Render example content."""
+        if not self.renderer:
+            return False
+
+        # Clear screen and show example content
+        self.renderer.clear_screen()
+
+        # Center message
+        width, height = self.renderer.get_terminal_size()
+        message = f"Example Plugin - Frame {self.frame_count}"
+        x = (width - len(message)) // 2
+        y = height // 2
+
+        self.renderer.write_at(x, y, message)
+        self.renderer.write_at(x - 5, y + 2, "Press 'q' or ESC to exit")
+
+        self.update_frame_stats()
+        return True
+
+    async def handle_input(self, key_press: KeyPress) -> bool:
+        """Handle input for example plugin."""
+        # Exit on 'q' or ESC
+        return key_press.char in ['q', '\x1b'] or key_press.name == "Escape"