portacode 0.3.19.dev4__py3-none-any.whl → 1.4.11.dev1__py3-none-any.whl

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,
@@ -29,16 +32,33 @@ from .handlers import (
     TerminalListHandler,
     SystemInfoHandler,
     FileReadHandler,
-    FileWriteHandler,
     DirectoryListHandler,
     FileInfoHandler,
     FileDeleteHandler,
+    FileSearchHandler,
+    FileRenameHandler,
+    ContentRequestHandler,
+    FileApplyDiffHandler,
+    FilePreviewDiffHandler,
     ProjectStateFolderExpandHandler,
     ProjectStateFolderCollapseHandler,
     ProjectStateFileOpenHandler,
     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
 
@@ -74,21 +94,36 @@ class ClientSessionManager:
             logger.info(f"Newly added sessions: {newly_added_sessions}")
         if disconnected_sessions:
             logger.info(f"Disconnected sessions: {disconnected_sessions}")
-            # Trigger cleanup for disconnected sessions
-            self._cleanup_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
     
-    def _cleanup_disconnected_sessions(self, disconnected_sessions: List[str]):
-        """Clean up resources for disconnected client sessions."""
-        logger.info("Cleaning up resources for %d disconnected sessions", len(disconnected_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
-        # We need to get the context from the terminal manager
         if hasattr(self, '_terminal_manager') and self._terminal_manager:
             context = getattr(self._terminal_manager, '_context', {})
             if context:
@@ -96,17 +131,116 @@ class ClientSessionManager:
                 control_channel = getattr(self._terminal_manager, '_control_channel', None)
                 if control_channel:
                     project_manager = _get_or_create_project_state_manager(context, control_channel)
-                    
-                    # Clean up project states for each disconnected session
-                    for client_session_id in disconnected_sessions:
-                        logger.info("Cleaning up project states for disconnected session: %s", client_session_id)
-                        project_manager.cleanup_projects_by_client_session(client_session_id)
+                    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."""
@@ -277,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,
         }
         
@@ -294,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())
@@ -307,10 +450,17 @@ class TerminalManager:
         self._command_registry.register(SystemInfoHandler)
         # File operation handlers
         self._command_registry.register(FileReadHandler)
-        self._command_registry.register(FileWriteHandler)
+        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)
@@ -318,6 +468,15 @@ class TerminalManager:
         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
@@ -363,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
@@ -381,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.
         
@@ -489,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}")
@@ -503,11 +678,13 @@ 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_tabs": [manager._serialize_tab_info(tab) for tab in project_state.open_tabs],
+                        "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(),
@@ -601,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
@@ -621,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."""
@@ -681,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 "$@"

portacode/link_capture/bin/kde-open

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

portacode/link_capture/bin/kfmclient

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

portacode/link_capture/bin/link_capture_exec.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+COMMAND_NAME="$1"
+shift
+
+if [ -z "$COMMAND_NAME" ]; then
+  echo "link_capture: missing command name" >&2
+  exit 1
+fi
+
+exec "$SCRIPT_DIR/link_capture_wrapper.py" "$COMMAND_NAME" "$@"

portacode/link_capture/bin/link_capture_wrapper.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Simple link capture wrapper that never executes a native browser."""
+
+import json
+import os
+import sys
+import time
+import uuid
+from pathlib import Path
+from urllib.parse import urlparse
+
+LINK_CHANNEL_ENV = "PORTACODE_LINK_CHANNEL"
+TERMINAL_ID_ENV = "PORTACODE_TERMINAL_ID"
+
+
+def _find_link_argument(args):
+    for arg in args:
+        if not isinstance(arg, str):
+            continue
+        parsed = urlparse(arg)
+        if parsed.scheme and parsed.netloc:
+            return arg
+        if arg.startswith("file://"):
+            return arg
+    return None
+
+
+def _write_capture_event(cmd_name, args, link):
+    channel = os.environ.get(LINK_CHANNEL_ENV)
+    terminal_id = os.environ.get(TERMINAL_ID_ENV)
+    if not channel or not link:
+        return
+    payload = {
+        "terminal_id": terminal_id,
+        "command": cmd_name,
+        "args": args,
+        "url": link,
+        "timestamp": time.time(),
+    }
+    directory = Path(channel)
+    try:
+        directory.mkdir(parents=True, exist_ok=True)
+    except Exception:
+        return
+    temp_file = directory / f".{uuid.uuid4().hex}.tmp"
+    term_label = terminal_id or "unknown"
+    base_name = f"{int(time.time() * 1000)}-{term_label}"
+    final_file = directory / f"{base_name}.json"
+    suffix = 0
+    while final_file.exists():
+        suffix += 1
+        final_file = directory / f"{base_name}-{suffix}.json"
+    try:
+        temp_file.write_text(json.dumps(payload), encoding="utf-8")
+        temp_file.replace(final_file)
+    except Exception:
+        if temp_file.exists():
+            temp_file.unlink(missing_ok=True)
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        sys.stderr.write("link_capture: missing target command name\n")
+        sys.exit(1)
+    cmd_name = sys.argv[1]
+    cmd_args = sys.argv[2:]
+    link = _find_link_argument(cmd_args)
+    if link:
+        _write_capture_event(cmd_name, cmd_args, link)
+    # Never run a real browser; capture and exit successfully.
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

portacode/link_capture/bin/links

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

portacode/link_capture/bin/links2

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

portacode/link_capture/bin/lynx

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

portacode/link_capture/bin/mate-open

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

portacode/link_capture/bin/netsurf

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

portacode/link_capture/bin/sensible-browser

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

portacode/link_capture/bin/w3m

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

portacode/link_capture/bin/x-www-browser

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

portacode/link_capture/bin/xdg-open

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