portacode 0.3.16.dev10__py3-none-any.whl → 1.4.11.dev1__py3-none-any.whl

portacode/connection/handlers/update_handler.py

@@ -0,0 +1,61 @@
+"""Update handler for Portacode CLI."""
+
+import subprocess
+import sys
+import logging
+from typing import Any, Dict
+from .base import AsyncHandler
+
+logger = logging.getLogger(__name__)
+
+
+class UpdatePortacodeHandler(AsyncHandler):
+    """Handler for updating Portacode CLI."""
+    
+    @property
+    def command_name(self) -> str:
+        return "update_portacode_cli"
+    
+    async def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """Update Portacode package and restart process."""
+        try:
+            logger.info("Starting Portacode CLI update...")
+            
+            # Update the package
+            result = subprocess.run([
+                sys.executable, "-m", "pip", "install", "--upgrade", "portacode"
+            ], capture_output=True, text=True, timeout=120)
+            
+            if result.returncode != 0:
+                logger.error("Update failed: %s", result.stderr)
+                return {
+                    "event": "update_portacode_response",
+                    "success": False,
+                    "error": f"Update failed: {result.stderr}"
+                }
+            
+            logger.info("Update successful, restarting process...")
+            
+            # Send success response before exit
+            await self.send_response({
+                "event": "update_portacode_response",
+                "success": True,
+                "message": "Update completed. Process restarting..."
+            })
+            
+            # Exit with special code to trigger restart
+            sys.exit(42)
+            
+        except subprocess.TimeoutExpired:
+            return {
+                "event": "update_portacode_response",
+                "success": False,
+                "error": "Update timed out after 120 seconds"
+            }
+        except Exception as e:
+            logger.exception("Update failed with exception")
+            return {
+                "event": "update_portacode_response",
+                "success": False,
+                "error": str(e)
+            }

portacode/connection/multiplex.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
+import time
 from asyncio import Queue
 from typing import Any, Dict, Union
 
@@ -49,8 +50,65 @@ class Multiplexer:
         return self._channels[channel_id]
 
     async def _send_on_channel(self, channel_id: Union[int, str], payload: Any) -> None:
-        frame = json.dumps({"channel": channel_id, "payload": payload})
-        await self._send_func(frame)
+        # Start timing the serialization and sending
+        start_time = time.time()
+        
+        try:
+            # Serialize the frame
+            serialization_start = time.time()
+            frame = json.dumps({"channel": channel_id, "payload": payload})
+            serialization_time = time.time() - serialization_start
+            
+            # Calculate message size
+            frame_size_bytes = len(frame.encode('utf-8'))
+            frame_size_kb = frame_size_bytes / 1024
+            
+            # Log warnings for large messages
+            if frame_size_kb > 500:  # Warn for messages > 500KB
+                logger.warning("🚨 LARGE WEBSOCKET MESSAGE: %.1f KB on channel %s (event: %s)", 
+                              frame_size_kb, channel_id, payload.get('event', 'unknown'))
+                
+                # Log additional details for very large messages
+                if frame_size_kb > 1000:  # > 1MB
+                    logger.warning("🚨 VERY LARGE MESSAGE: %.1f KB - This may cause connection drops!", frame_size_kb)
+                    
+                    # Try to identify what's making the message large
+                    if isinstance(payload, dict):
+                        large_fields = []
+                        for key, value in payload.items():
+                            if isinstance(value, (str, list, dict)):
+                                field_size = len(json.dumps(value).encode('utf-8')) / 1024
+                                if field_size > 100:  # Fields > 100KB
+                                    large_fields.append(f"{key}: {field_size:.1f}KB")
+                        if large_fields:
+                            logger.warning("🚨 Large fields detected: %s", ", ".join(large_fields))
+            
+            elif frame_size_kb > 100:  # Info for messages > 100KB
+                logger.info("📦 Large websocket message: %.1f KB on channel %s (event: %s)", 
+                           frame_size_kb, channel_id, payload.get('event', 'unknown'))
+            
+            # Send the frame
+            send_start = time.time()
+            await self._send_func(frame)
+            send_time = time.time() - send_start
+            
+            total_time = time.time() - start_time
+            
+            # Log performance metrics for large messages or slow operations
+            if frame_size_kb > 50 or total_time > 0.1:  # Log for messages > 50KB or operations > 100ms
+                logger.info("📊 WebSocket send performance: %.1f KB in %.3fs (serialize: %.3fs, send: %.3fs) - channel %s", 
+                           frame_size_kb, total_time, serialization_time, send_time, channel_id)
+            
+            # Log detailed timing for very large messages
+            if frame_size_kb > 200:
+                logger.info("🔍 Detailed timing - Channel: %s, Event: %s, Size: %.1f KB, Total: %.3fs", 
+                           channel_id, payload.get('event', 'unknown'), frame_size_kb, total_time)
+                
+        except Exception as e:
+            total_time = time.time() - start_time
+            logger.error("❌ Failed to send websocket message on channel %s after %.3fs: %s", 
+                        channel_id, total_time, e)
+            raise
 
     async def on_raw_message(self, raw: str) -> None:
         try:

portacode/connection/terminal.py

@@ -18,8 +18,11 @@ import json
 import logging
 import os
 import time
+from dataclasses import asdict
 from typing import Any, Dict, Optional, List
 
+from websockets.exceptions import ConnectionClosedError
+
 from .multiplex import Multiplexer, Channel
 from .handlers import (
     CommandRegistry,
@@ -28,12 +31,34 @@ from .handlers import (
     TerminalStopHandler,
     TerminalListHandler,
     SystemInfoHandler,
+    FileReadHandler,
     DirectoryListHandler,
+    FileInfoHandler,
+    FileDeleteHandler,
+    FileSearchHandler,
+    FileRenameHandler,
+    ContentRequestHandler,
+    FileApplyDiffHandler,
+    FilePreviewDiffHandler,
     ProjectStateFolderExpandHandler,
     ProjectStateFolderCollapseHandler,
     ProjectStateFileOpenHandler,
-    ProjectStateFileCloseHandler,
-    ProjectStateSetActiveFileHandler,
+    ProjectStateTabCloseHandler,
+    ProjectStateSetActiveTabHandler,
+    ProjectStateDiffOpenHandler,
+    ProjectStateDiffContentHandler,
+    ProjectStateGitStageHandler,
+    ProjectStateGitUnstageHandler,
+    ProjectStateGitRevertHandler,
+    ProjectStateGitCommitHandler,
+    UpdatePortacodeHandler,
+    ConfigureProxmoxInfraHandler,
+    RevertProxmoxInfraHandler,
+)
+from .handlers.project_aware_file_handlers import (
+    ProjectAwareFileWriteHandler,
+    ProjectAwareFileCreateHandler,
+    ProjectAwareFolderCreateHandler,
 )
 from .handlers.session import SessionManager
 
@@ -62,14 +87,165 @@ class ClientSessionManager:
         
         new_sessions = set(self._client_sessions.keys())
         newly_added_sessions = list(new_sessions - old_sessions)
+        disconnected_sessions = list(old_sessions - new_sessions)
         
-        logger.info(f"Updated client sessions: {len(self._client_sessions)} sessions, {len(newly_added_sessions)} newly added")
+        logger.info(f"Updated client sessions: {len(self._client_sessions)} sessions, {len(newly_added_sessions)} newly added, {len(disconnected_sessions)} disconnected")
         if newly_added_sessions:
             logger.info(f"Newly added sessions: {newly_added_sessions}")
+        if disconnected_sessions:
+            logger.info(f"Disconnected sessions: {disconnected_sessions}")
+            # NOTE: Not automatically cleaning up project states for disconnected sessions
+            # to handle temporary disconnections gracefully. Project states will be cleaned
+            # up only when explicitly notified by the server of permanent disconnection.
+            logger.info("Project states preserved for potential reconnection of these sessions")
+        
+        # Handle project state management based on session changes
+        if newly_added_sessions or disconnected_sessions:
+            # Schedule project state management to run asynchronously
+            import asyncio
+            try:
+                loop = asyncio.get_event_loop()
+                if loop.is_running():
+                    # Schedule both cleanup and initialization
+                    loop.create_task(self._manage_project_states_for_session_changes(newly_added_sessions, sessions))
+                else:
+                    logger.debug("No event loop running, skipping project state management")
+            except Exception as e:
+                logger.debug("Could not schedule project state management: %s", e)
         
         self._write_debug_file()
         return newly_added_sessions
     
+    async def cleanup_client_session_explicitly(self, client_session_id: str):
+        """Explicitly clean up resources for a client session when notified by server."""
+        logger.info("Explicitly cleaning up resources for client session: %s", client_session_id)
+        
+        # Import here to avoid circular imports
+        from .handlers.project_state_handlers import _get_or_create_project_state_manager
+        
+        # Get the project state manager from context if it exists
+        if hasattr(self, '_terminal_manager') and self._terminal_manager:
+            context = getattr(self._terminal_manager, '_context', {})
+            if context:
+                # Get or create the project state manager
+                control_channel = getattr(self._terminal_manager, '_control_channel', None)
+                if control_channel:
+                    project_manager = _get_or_create_project_state_manager(context, control_channel)
+                    logger.info("Cleaning up project state for client session: %s", client_session_id)
+                    await project_manager.cleanup_projects_by_client_session(client_session_id)
+                else:
+                    logger.warning("No control channel available for project state cleanup")
+            else:
+                logger.warning("No context available for project state cleanup")
+        else:
+            logger.warning("No terminal manager available for project state cleanup")
+            
+    async def _manage_project_states_for_session_changes(self, newly_added_sessions: List[str], all_sessions: List[Dict]):
+        """Comprehensive project state management for session changes."""
+        try:
+            # Import here to avoid circular imports
+            from .handlers.project_state_handlers import _get_or_create_project_state_manager
+            
+            if not hasattr(self, '_terminal_manager') or not self._terminal_manager:
+                logger.warning("No terminal manager available for project state management")
+                return
+            
+            context = getattr(self._terminal_manager, '_context', {})
+            if not context:
+                logger.warning("No context available for project state management")
+                return
+            
+            control_channel = getattr(self._terminal_manager, '_control_channel', None)
+            if not control_channel:
+                logger.warning("No control channel available for project state management")
+                return
+            
+            project_manager = _get_or_create_project_state_manager(context, control_channel)
+            
+            # Convert sessions list to dict for easier lookup
+            sessions_dict = {session.get('channel_name'): session for session in all_sessions if session.get('channel_name')}
+            
+            # First, clean up project states for sessions that are no longer project sessions or don't exist
+            current_project_sessions = set()
+            for session in all_sessions:
+                channel_name = session.get('channel_name')
+                project_id = session.get('project_id')
+                project_folder_path = session.get('project_folder_path')
+                
+                if channel_name and project_id is not None and project_folder_path:
+                    current_project_sessions.add(channel_name)
+                    logger.debug(f"Active project session: {channel_name} -> {project_folder_path} (project_id: {project_id})")
+            
+            # Clean up project states that don't match current project sessions
+            existing_project_states = list(project_manager.projects.keys())
+            for session_id in existing_project_states:
+                if session_id not in current_project_sessions:
+                    logger.info(f"Cleaning up project state for session {session_id} (no longer a project session)")
+                    await project_manager.cleanup_project(session_id)
+            
+            # Initialize project states for new project sessions
+            for session_name in newly_added_sessions:
+                session = sessions_dict.get(session_name)
+                if not session:
+                    continue
+                
+                project_id = session.get('project_id')
+                project_folder_path = session.get('project_folder_path')
+                
+                if project_id is not None and project_folder_path:
+                    if session_name in project_manager.projects:
+                        logger.info("Project state already exists for session %s, skipping re-init", session_name)
+                        continue
+                    logger.info(f"Initializing project state for new project session {session_name}: {project_folder_path}")
+                    
+                    try:
+                        # Initialize project state (this includes migration logic)
+                        project_state = await project_manager.initialize_project_state(session_name, project_folder_path)
+                        logger.info(f"Successfully initialized project state for {session_name}")
+                        
+                        # Send initial project state to the client
+                        # (implementation can be added here if needed)
+                        
+                    except Exception as e:
+                        logger.error(f"Failed to initialize project state for {session_name}: {e}")
+        except Exception as e:
+            logger.error("Error managing project states for session changes: %s", e)
+    
+    async def _cleanup_orphaned_project_states(self):
+        """Clean up project states that don't match any current client session."""
+        try:
+            # Import here to avoid circular imports
+            from .handlers.project_state_handlers import _get_or_create_project_state_manager
+            
+            # Get current client session IDs
+            current_sessions = list(self._client_sessions.keys())
+            
+            if hasattr(self, '_terminal_manager') and self._terminal_manager:
+                context = getattr(self._terminal_manager, '_context', {})
+                if context:
+                    control_channel = getattr(self._terminal_manager, '_control_channel', None)
+                    if control_channel:
+                        project_manager = _get_or_create_project_state_manager(context, control_channel)
+                        await project_manager.cleanup_orphaned_project_states(current_sessions)
+                    else:
+                        logger.warning("No control channel available for orphaned project state cleanup")
+                else:
+                    logger.warning("No context available for orphaned project state cleanup")
+            else:
+                logger.warning("No terminal manager available for orphaned project state cleanup")
+                
+        except Exception as e:
+            logger.error("Error cleaning up orphaned project states: %s", e)
+    
+    def _cleanup_disconnected_sessions(self, disconnected_sessions: List[str]):
+        """Legacy method - now just logs disconnections without cleanup."""
+        logger.info("Sessions disconnected (but preserving project states): %s", disconnected_sessions)
+        # Project states are preserved to handle reconnections gracefully
+    
+    def set_terminal_manager(self, terminal_manager):
+        """Set reference to terminal manager for cleanup purposes."""
+        self._terminal_manager = terminal_manager
+    
     def get_sessions(self) -> Dict[str, Dict]:
         """Get all current client sessions."""
         return self._client_sessions.copy()
@@ -191,6 +367,7 @@ class TerminalManager:
         self.debug = debug
         self._session_manager = None  # Initialize as None first
         self._client_session_manager = ClientSessionManager()  # Initialize client session manager
+        self._client_session_manager.set_terminal_manager(self)  # Set reference for cleanup
         self._set_mux(mux, is_initial=True)
 
     # ------------------------------------------------------------------
@@ -234,6 +411,7 @@ class TerminalManager:
             "session_manager": self._session_manager,
             "client_session_manager": self._client_session_manager,
             "mux": mux,
+            "use_content_caching": True,  # Enable content caching optimization
             "debug": self.debug,
         }
         
@@ -251,6 +429,14 @@ class TerminalManager:
                 pass
         self._ctl_task = asyncio.create_task(self._control_loop())
         
+        # Start periodic system info sender
+        if getattr(self, "_system_info_task", None):
+            try:
+                self._system_info_task.cancel()
+            except Exception:
+                pass
+        self._system_info_task = asyncio.create_task(self._periodic_system_info())
+        
         # For initial connections, request client sessions after control loop starts
         if is_initial:
             asyncio.create_task(self._initial_connection_setup())
@@ -262,13 +448,35 @@ class TerminalManager:
         self._command_registry.register(TerminalStopHandler)
         self._command_registry.register(TerminalListHandler)
         self._command_registry.register(SystemInfoHandler)
+        # File operation handlers
+        self._command_registry.register(FileReadHandler)
+        self._command_registry.register(ProjectAwareFileWriteHandler)  # Use project-aware version
         self._command_registry.register(DirectoryListHandler)
+        self._command_registry.register(FileInfoHandler)
+        self._command_registry.register(FileDeleteHandler)
+        self._command_registry.register(ProjectAwareFileCreateHandler)  # Use project-aware version
+        self._command_registry.register(ProjectAwareFolderCreateHandler)  # Use project-aware version
+        self._command_registry.register(FileRenameHandler)
+        self._command_registry.register(FileSearchHandler)
+        self._command_registry.register(ContentRequestHandler)
+        self._command_registry.register(FileApplyDiffHandler)
+        self._command_registry.register(FilePreviewDiffHandler)
         # Project state handlers
         self._command_registry.register(ProjectStateFolderExpandHandler)
         self._command_registry.register(ProjectStateFolderCollapseHandler)
         self._command_registry.register(ProjectStateFileOpenHandler)
-        self._command_registry.register(ProjectStateFileCloseHandler)
-        self._command_registry.register(ProjectStateSetActiveFileHandler)
+        self._command_registry.register(ProjectStateTabCloseHandler)
+        self._command_registry.register(ProjectStateSetActiveTabHandler)
+        self._command_registry.register(ProjectStateDiffOpenHandler)
+        self._command_registry.register(ProjectStateDiffContentHandler)
+        self._command_registry.register(ProjectStateGitStageHandler)
+        self._command_registry.register(ProjectStateGitUnstageHandler)
+        self._command_registry.register(ProjectStateGitRevertHandler)
+        self._command_registry.register(ProjectStateGitCommitHandler)
+        # System management handlers
+        self._command_registry.register(ConfigureProxmoxInfraHandler)
+        self._command_registry.register(RevertProxmoxInfraHandler)
+        self._command_registry.register(UpdatePortacodeHandler)
 
     # ---------------------------------------------------------------------
     # Control loop – receives commands from gateway
@@ -314,9 +522,10 @@ class TerminalManager:
                     logger.info("terminal_manager: ✅ Updated client sessions (%d sessions)", len(sessions))
                     
                     # Auto-send initial data only to newly added clients
+                    # Create a background task so it doesn't block the control loop
                     if newly_added_sessions:
-                        logger.info("terminal_manager: 🚀 Triggering auto-send of initial data to newly added clients")
-                        await self._send_initial_data_to_clients(newly_added_sessions)
+                        logger.info("terminal_manager: 🚀 Triggering auto-send of initial data to newly added clients (non-blocking)")
+                        asyncio.create_task(self._send_initial_data_to_clients(newly_added_sessions))
                     else:
                         logger.info("terminal_manager: ℹ️ No new sessions to send data to")
                     continue
@@ -332,6 +541,20 @@ class TerminalManager:
                 # Continue processing other messages
                 continue
 
+    async def _periodic_system_info(self) -> None:
+        """Send system_info event every 10 seconds when clients are connected."""
+        while True:
+            try:
+                await asyncio.sleep(10)
+                if self._client_session_manager.has_interested_clients():
+                    from .handlers.system_handlers import SystemInfoHandler
+                    handler = SystemInfoHandler(self._control_channel, self._context)
+                    system_info = handler.execute({})
+                    await self._send_session_aware(system_info)
+            except Exception as exc:
+                logger.exception("Error in periodic system info: %s", exc)
+                continue
+
     async def _send_initial_data_to_clients(self, newly_added_sessions: List[str] = None):
         """Send initial system info and terminal list to connected clients.
         
@@ -440,9 +663,10 @@ class TerminalManager:
                 if not session:
                     continue
                 
+                project_id = session.get("project_id")
                 project_folder_path = session.get("project_folder_path")
-                if not project_folder_path:
-                    logger.debug(f"terminal_manager: 🌳 Session {session_name} has no project_folder_path, skipping")
+                if project_id is None or not project_folder_path:
+                    logger.debug(f"terminal_manager: 🌳 Session {session_name} has no project_id or project_folder_path, skipping")
                     continue
                 
                 logger.info(f"terminal_manager: 🌳 Initializing project state for session {session_name} with folder: {project_folder_path}")
@@ -454,12 +678,14 @@ class TerminalManager:
                     # Send initial project state to the client
                     initial_state_payload = {
                         "event": "project_state_initialized",
+                        "project_id": project_state.client_session_id,  # Add missing project_id field
                         "project_folder_path": project_state.project_folder_path,
                         "is_git_repo": project_state.is_git_repo,
                         "git_branch": project_state.git_branch,
                         "git_status_summary": project_state.git_status_summary,
-                        "open_files": list(project_state.open_files),
-                        "active_file": project_state.active_file,
+                        "git_detailed_status": asdict(project_state.git_detailed_status) if project_state.git_detailed_status and hasattr(project_state.git_detailed_status, '__dataclass_fields__') else None,  # Add missing git_detailed_status field
+                        "open_tabs": [manager._serialize_tab_info(tab) for tab in project_state.open_tabs.values()],  # Fix to use .values() for dict
+                        "active_tab": manager._serialize_tab_info(project_state.active_tab) if project_state.active_tab else None,
                         "items": [manager._serialize_file_item(item) for item in project_state.items],
                         "timestamp": time.time(),
                         "client_sessions": [session_name]  # Target this specific session
@@ -552,15 +778,17 @@ class TerminalManager:
             payload: The message payload to send
             project_id: Optional project filter for targeting specific sessions
         """
+        event_type = payload.get("event", "unknown")
+        
         # Check if there are any interested clients
         if not self._client_session_manager.has_interested_clients():
-            logger.debug("terminal_manager: No interested clients, skipping message send")
+            logger.info("terminal_manager: No interested clients for %s event, skipping send", event_type)
             return
         
         # Get target sessions
         target_sessions = self._client_session_manager.get_target_sessions(project_id)
         if not target_sessions:
-            logger.debug("terminal_manager: No target sessions found, skipping message send")
+            logger.info("terminal_manager: No target sessions found for %s event (project_id=%s), skipping send", event_type, project_id)
             return
         
         # Add session targeting information
@@ -572,10 +800,21 @@ class TerminalManager:
         if reply_channel and "reply_channel" not in enhanced_payload:
             enhanced_payload["reply_channel"] = reply_channel
         
-        logger.debug("terminal_manager: Sending to %d client sessions: %s", 
-                    len(target_sessions), target_sessions)
+        # Log all event dispatches at INFO level, with data size for terminal_data
+        if event_type == "terminal_data":
+            data_size = len(payload.get("data", ""))
+            terminal_id = payload.get("channel", "unknown")
+            logger.info("terminal_manager: Dispatching %s event (terminal_id=%s, data_size=%d bytes) to %d client sessions", 
+                       event_type, terminal_id, data_size, len(target_sessions))
+        # else:
+        #     logger.info("terminal_manager: Dispatching %s event to %d client sessions", 
+        #                event_type, len(target_sessions))
         
-        await self._control_channel.send(enhanced_payload)
+        try:
+            await self._control_channel.send(enhanced_payload)
+        except ConnectionClosedError as exc:
+            logger.warning("terminal_manager: Connection closed (%s); skipping %s event", exc, event_type)
+            return
 
     async def _send_terminal_list(self) -> None:
         """Send terminal list for reconnection reconciliation."""
@@ -632,4 +871,4 @@ class TerminalManager:
             await self._request_client_sessions()
             logger.info("Client session request sent after reconnection")
         except Exception as exc:
-            logger.error("Failed to handle reconnection: %s", exc) 
+            logger.error("Failed to handle reconnection: %s", exc) 

portacode/keypair.py

@@ -98,4 +98,66 @@ def fingerprint_public_key(pem: bytes) -> str:
     """Return a short fingerprint for display purposes (SHA-256)."""
     digest = hashes.Hash(hashes.SHA256())
     digest.update(pem)
-    return digest.finalize().hex()[:16] 
+    return digest.finalize().hex()[:16]
+
+
+class InMemoryKeyPair:
+    """Keypair kept purely in memory until explicitly persisted."""
+
+    def __init__(self, private_pem: bytes, public_pem: bytes, key_dir: Path):
+        self._private_pem = private_pem
+        self._public_pem = public_pem
+        self._key_dir = key_dir
+        self._is_new = True
+
+    @property
+    def private_key_pem(self) -> bytes:
+        return self._private_pem
+
+    @property
+    def public_key_pem(self) -> bytes:
+        return self._public_pem
+
+    def sign_challenge(self, challenge: str) -> bytes:
+        private_key = serialization.load_pem_private_key(self._private_pem, password=None)
+        return private_key.sign(
+            challenge.encode(),
+            padding.PKCS1v15(),
+            hashes.SHA256(),
+        )
+
+    def public_key_der_b64(self) -> str:
+        pubkey = serialization.load_pem_public_key(self._public_pem)
+        der = pubkey.public_bytes(
+            encoding=serialization.Encoding.DER,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+        return base64.b64encode(der).decode()
+
+    def persist(self) -> KeyPair:
+        """Write the keypair to disk and return a regular KeyPair."""
+        key_dir = self._key_dir
+        key_dir.mkdir(parents=True, exist_ok=True)
+        priv_path = key_dir / PRIVATE_KEY_FILE
+        pub_path = key_dir / PUBLIC_KEY_FILE
+        priv_path.write_bytes(self._private_pem)
+        pub_path.write_bytes(self._public_pem)
+        keypair = KeyPair(priv_path, pub_path)
+        keypair._is_new = True  # type: ignore[attr-defined]
+        keypair._key_dir = key_dir  # type: ignore[attr-defined]
+        return keypair
+
+
+def generate_in_memory_keypair() -> InMemoryKeyPair:
+    """Generate a new keypair but keep it in memory until pairing succeeds."""
+    private_pem, public_pem = _generate_keypair()
+    key_dir = get_key_dir()
+    return InMemoryKeyPair(private_pem, public_pem, key_dir)
+
+
+def keypair_files_exist() -> bool:
+    """Return True if the persisted keypair already exists on disk."""
+    key_dir = get_key_dir()
+    priv_path = key_dir / PRIVATE_KEY_FILE
+    pub_path = key_dir / PUBLIC_KEY_FILE
+    return priv_path.exists() and pub_path.exists()

portacode/link_capture/__init__.py

@@ -0,0 +1,38 @@
+"""Helpers for the link capture wrapper scripts."""
+
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+try:
+    # Use the stdlib helpers when they are available (Python ≥3.9).
+    from importlib.resources import as_file, files
+except ImportError:  # pragma: no cover
+    # Fall back to the backport for older Python 3.x runtimes (>=3.6).
+    from importlib_resources import as_file, files
+
+_LINK_CAPTURE_TEMP_DIR: Optional[Path] = None
+
+
+def prepare_link_capture_bin() -> Optional[Path]:
+    """Extract the packaged link capture wrappers into a temporary dir and return it."""
+    global _LINK_CAPTURE_TEMP_DIR
+    if _LINK_CAPTURE_TEMP_DIR:
+        return _LINK_CAPTURE_TEMP_DIR
+
+    bin_source = files(__package__) / "bin"
+    if not bin_source.is_dir():
+        return None
+
+    temp_dir = Path(tempfile.mkdtemp(prefix="portacode-link-capture-"))
+    for entry in bin_source.iterdir():
+        if not entry.is_file():
+            continue
+        with as_file(entry) as file_path:
+            dest = temp_dir / entry.name
+            shutil.copyfile(file_path, dest)
+            dest.chmod(dest.stat().st_mode | 0o111)
+
+    _LINK_CAPTURE_TEMP_DIR = temp_dir
+    return _LINK_CAPTURE_TEMP_DIR

portacode/link_capture/bin/elinks

@@ -0,0 +1,3 @@
+#!/bin/sh
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+exec "$SCRIPT_DIR/link_capture_exec.sh" elinks "$@"

portacode/link_capture/bin/gio-open

@@ -0,0 +1,3 @@
+#!/bin/sh
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+exec "$SCRIPT_DIR/link_capture_exec.sh" gio-open "$@"

portacode/link_capture/bin/gnome-open

@@ -0,0 +1,3 @@
+#!/bin/sh
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+exec "$SCRIPT_DIR/link_capture_exec.sh" gnome-open "$@"

portacode/link_capture/bin/gvfs-open

@@ -0,0 +1,3 @@
+#!/bin/sh
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+exec "$SCRIPT_DIR/link_capture_exec.sh" gvfs-open "$@"