feat(cli): add CLI-GUI coexistence with server proxy and port lock

When WebServer is running, CLI now auto-detects it and forwards device
operations (info/inject/unpatch/mem-read/mem-write) via HTTP API proxy
instead of opening a competing serial connection.

When WebServer is offline, CLI falls back to direct serial mode with
file-based port locking (fcntl/msvcrt) to prevent multi-instance
conflicts.

New modules:
- cli/server_proxy.py: HTTP proxy forwarding to WebServer API
- utils/port_lock.py: cross-platform file-based serial port lock

New CLI flags:
- --direct: skip proxy detection, force direct serial access
- --server-url: specify non-default WebServer address

Tests: 57 new tests (port_lock, server_proxy, cli_coexistence)
Docs: docs/cli-gui-coexistence-plan.md with full analysis and roadmap

Author: FASTSHIFT

Tools/WebServer/cli/fpb_cli.py

@@ -28,6 +28,8 @@
 # Import from existing WebServer modules
 sys.path.insert(0, str(Path(__file__).parent))
 from fpb_inject import FPBInject  # noqa: E402
+from utils.port_lock import PortLock  # noqa: E402
+from cli.server_proxy import ServerProxy, DEFAULT_SERVER_URL  # noqa: E402
 
 try:
     import serial
@@ -101,6 +103,8 @@ def __init__(
         tx_chunk_size: int = 0,
         tx_chunk_delay: float = 0.002,
         max_retries: int = 10,
+        direct: bool = False,
+        server_url: str = DEFAULT_SERVER_URL,
     ):
         self.verbose = verbose
         self.setup_logging()
@@ -113,8 +117,33 @@ def __init__(
         self._device_state.transfer_max_retries = max_retries
         self._fpb = FPBInject(self._device_state)
 
+        # Proxy and lock state
+        self._proxy = None
+        self._port_lock = None
+
         # Connect to serial if port specified
         if port:
+            if not direct:
+                # Try proxy mode first
+                proxy = ServerProxy(base_url=server_url)
+                if proxy.is_server_running() and proxy.is_device_connected():
+                    self._proxy = proxy
+                    self._device_state.connected = True
+                    if self.verbose:
+                        logging.info(f"Using WebServer proxy mode ({server_url})")
+                    return
+
+            # Direct mode: acquire port lock then connect
+            lock = PortLock(port)
+            if not lock.acquire():
+                owner = lock.get_owner_pid()
+                raise FPBCLIError(
+                    f"Serial port {port} is locked by another process "
+                    f"(PID: {owner}). "
+                    f"Stop the other process or use a different port."
+                )
+            self._port_lock = lock
+
             self._device_state.connect(port, baudrate)
             if self.verbose:
                 logging.info(f"Connected to {port}")
@@ -355,6 +384,19 @@ def inject(
             if not source_path.exists():
                 raise FPBCLIError(f"Source file not found: {source_file}")
 
+            # Proxy mode: forward to WebServer
+            if self._proxy:
+                result = self._proxy.inject(
+                    target_func=target_func,
+                    source_file=source_file,
+                    elf_path=elf_path,
+                    compile_commands=compile_commands,
+                    patch_mode=patch_mode,
+                    comp=comp,
+                )
+                self.output_json(result)
+                return
+
             # Check if device is connected
             if not self._device_state.connected:
                 # Still provide useful info even without connection
@@ -433,6 +475,11 @@ def inject(
     def unpatch(self, comp: int = 0, all_patches: bool = False) -> None:
         """Remove patch from device"""
         try:
+            if self._proxy:
+                result = self._proxy.unpatch(comp=comp, all_patches=all_patches)
+                self.output_json(result)
+                return
+
             if not self._device_state.connected:
                 raise FPBCLIError(
                     "No device connected. Use --port to specify serial port."
@@ -454,6 +501,11 @@ def unpatch(self, comp: int = 0, all_patches: bool = False) -> None:
     def info(self) -> None:
         """Get device FPB info"""
         try:
+            if self._proxy:
+                result = self._proxy.info()
+                self.output_json(result)
+                return
+
             if not self._device_state.connected:
                 raise FPBCLIError(
                     "No device connected. Use --port to specify serial port."
@@ -599,6 +651,11 @@ def file_download(self, remote_path: str, local_path: str) -> None:
     def mem_read(self, addr: int, length: int, fmt: str = "hex") -> None:
         """Read memory from device"""
         try:
+            if self._proxy:
+                result = self._proxy.mem_read(addr, length, fmt)
+                self.output_json(result)
+                return
+
             if not self._device_state.connected:
                 raise FPBCLIError(
                     "No device connected. Use --port to specify serial port."
@@ -648,6 +705,11 @@ def mem_read(self, addr: int, length: int, fmt: str = "hex") -> None:
     def mem_write(self, addr: int, data_hex: str) -> None:
         """Write memory to device"""
         try:
+            if self._proxy:
+                result = self._proxy.mem_write(addr, data_hex)
+                self.output_json(result)
+                return
+
             if not self._device_state.connected:
                 raise FPBCLIError(
                     "No device connected. Use --port to specify serial port."
@@ -721,6 +783,9 @@ def mem_dump(self, addr: int, length: int, output_file: str) -> None:
     def cleanup(self):
         """Cleanup resources"""
         self._device_state.disconnect()
+        if self._port_lock:
+            self._port_lock.release()
+            self._port_lock = None
 
 
 def main():
@@ -792,6 +857,17 @@ def main():
         default=10,
         help="Maximum retry attempts for file transfer operations (default: 10).",
     )
+    parser.add_argument(
+        "--direct",
+        action="store_true",
+        help="Force direct serial connection (skip WebServer proxy detection).",
+    )
+    parser.add_argument(
+        "--server-url",
+        type=str,
+        default=DEFAULT_SERVER_URL,
+        help=f"WebServer URL for proxy mode (default: {DEFAULT_SERVER_URL}).",
+    )
 
     subparsers = parser.add_subparsers(dest="command", help="Command to execute")
 
@@ -957,6 +1033,8 @@ def main():
         tx_chunk_size=args.tx_chunk_size,
         tx_chunk_delay=args.tx_chunk_delay,
         max_retries=args.max_retries,
+        direct=args.direct,
+        server_url=args.server_url,
     )
 
     try:

Tools/WebServer/cli/server_proxy.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+
+# MIT License
+# Copyright (c) 2025 - 2026 _VIFEXTech
+
+"""
+WebServer proxy for CLI coexistence.
+
+When the WebServer is running, CLI device operations are forwarded
+via HTTP API instead of opening a second serial connection.
+"""
+
+import json
+import logging
+import os
+from typing import Any, Dict, Optional
+from urllib.request import Request, urlopen
+
+logger = logging.getLogger(__name__)
+
+# Default WebServer URL
+DEFAULT_SERVER_URL = "http://127.0.0.1:5500"
+
+# Timeout for probe / API calls (seconds)
+_PROBE_TIMEOUT = 2
+_API_TIMEOUT = 30
+
+
+class ServerProxy:
+    """Proxy device operations through the running WebServer HTTP API."""
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_SERVER_URL,
+        token: Optional[str] = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+
+    # ------------------------------------------------------------------
+    # Low-level HTTP helpers (stdlib only, no requests dependency)
+    # ------------------------------------------------------------------
+
+    def _build_url(self, path: str) -> str:
+        url = f"{self.base_url}{path}"
+        if self.token:
+            sep = "&" if "?" in url else "?"
+            url += f"{sep}token={self.token}"
+        return url
+
+    def _get(self, path: str, timeout: float = _API_TIMEOUT) -> dict:
+        url = self._build_url(path)
+        req = Request(url, method="GET")
+        req.add_header("Accept", "application/json")
+        with urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read().decode())
+
+    def _post(
+        self, path: str, data: Optional[dict] = None, timeout: float = _API_TIMEOUT
+    ) -> dict:
+        url = self._build_url(path)
+        body = json.dumps(data or {}).encode()
+        req = Request(url, data=body, method="POST")
+        req.add_header("Content-Type", "application/json")
+        req.add_header("Accept", "application/json")
+        with urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read().decode())
+
+    # ------------------------------------------------------------------
+    # Server detection
+    # ------------------------------------------------------------------
+
+    def is_server_running(self) -> bool:
+        """Check if the WebServer is reachable."""
+        try:
+            resp = self._get("/api/status", timeout=_PROBE_TIMEOUT)
+            return resp.get("success", False)
+        except Exception:
+            return False
+
+    def is_device_connected(self) -> bool:
+        """Check if the WebServer has an active device connection."""
+        try:
+            resp = self._get("/api/status", timeout=_PROBE_TIMEOUT)
+            return resp.get("connected", False)
+        except Exception:
+            return False
+
+    def get_status(self) -> dict:
+        """Get full WebServer status."""
+        return self._get("/api/status")
+
+    # ------------------------------------------------------------------
+    # Device operations (proxied to WebServer)
+    # ------------------------------------------------------------------
+
+    def info(self) -> dict:
+        """Get device FPB info via WebServer."""
+        return self._get("/api/fpb/info")
+
+    def inject(
+        self,
+        target_func: str,
+        source_file: str,
+        elf_path: Optional[str] = None,
+        compile_commands: Optional[str] = None,
+        patch_mode: str = "trampoline",
+        comp: int = -1,
+    ) -> dict:
+        """Inject a patch via WebServer."""
+        # Read source content to send
+        source_content = ""
+        source_ext = ".c"
+        if os.path.exists(source_file):
+            with open(source_file, "r", encoding="utf-8") as f:
+                source_content = f.read()
+            source_ext = os.path.splitext(source_file)[1]
+
+        payload: Dict[str, Any] = {
+            "target_func": target_func,
+            "source_content": source_content,
+            "patch_mode": patch_mode,
+            "comp": comp,
+            "source_ext": source_ext,
+            "original_source_file": os.path.abspath(source_file),
+        }
+        if elf_path:
+            payload["elf_path"] = elf_path
+        if compile_commands:
+            payload["compile_commands_path"] = compile_commands
+
+        return self._post("/api/fpb/inject", payload)
+
+    def unpatch(self, comp: int = 0, all_patches: bool = False) -> dict:
+        """Remove a patch via WebServer."""
+        return self._post("/api/fpb/unpatch", {"comp": comp, "all": all_patches})
+
+    def mem_read(self, addr: int, length: int, fmt: str = "hex") -> dict:
+        """Read device memory via WebServer."""
+        return self._post(
+            "/api/fpb/mem-read",
+            {"addr": addr, "length": length, "fmt": fmt},
+        )
+
+    def mem_write(self, addr: int, data_hex: str) -> dict:
+        """Write device memory via WebServer."""
+        return self._post(
+            "/api/fpb/mem-write",
+            {"addr": addr, "data": data_hex},
+        )