replx-agent 2.0.0.post1__py3-none-any.whl

replx_agent/__init__.py

@@ -0,0 +1,3 @@
+__version__ = "2.0.0.post1"
+
+__all__ = ["__version__"]

replx_agent/__main__.py

@@ -0,0 +1,5 @@
+from .server.core import main
+
+
+if __name__ == "__main__":
+    main()

replx_agent/commands.py

@@ -0,0 +1,131 @@
+
+class Cmd:
+    CONNECT = 'connect'
+    DISCONNECT_PORT = 'disconnect_port'
+    SESSION_SETUP = 'session_setup'
+    SESSION_DISCONNECT = 'session_disconnect'
+    SESSION_SWITCH_FG = 'session_switch_fg'
+    SESSION_INFO = 'session_info'
+    CLIENT_DISCONNECT = 'client_disconnect'
+    SET_DEFAULT = 'set_default'
+    RELEASE = 'release'
+
+    STATUS = 'status'
+    SCAN = 'scan'
+    SHUTDOWN = 'shutdown'
+    PING = 'ping'
+    RESET = 'reset'
+
+    EXEC = 'exec'
+    RUN = 'run'
+    RUN_STOP = 'run_stop'
+    RUN_INTERACTIVE = 'run_interactive'
+
+    REPL_ENTER = 'repl_enter'
+    REPL_EXIT = 'repl_exit'
+    REPL_WRITE = 'repl_write'
+    REPL_READ = 'repl_read'
+
+    LS = 'ls'
+    LS_RECURSIVE = 'ls_recursive'
+    CAT = 'cat'
+    STAT = 'stat'
+    IS_DIR = 'is_dir'
+
+    RM = 'rm'
+    RMDIR = 'rmdir'
+    MKDIR = 'mkdir'
+    CP = 'cp'
+    MV = 'mv'
+    TOUCH = 'touch'
+    FORMAT = 'format'
+
+    GET_FILE = 'get_file'
+    GET_FILE_STREAMING = 'get_file_streaming'
+    GET_FILE_BATCH = 'get_file_batch'
+    PUT_FILE = 'put_file'
+    PUT_FILE_BATCH = 'put_file_batch'
+    TRANSFER_START = 'transfer_start'
+    FIRMWARE_STAGE = 'firmware_stage'
+    FIRMWARE_INFO = 'firmware_info'
+    FIRMWARE_FLASH = 'firmware_flash'
+    FIRMWARE_DISCARD = 'firmware_discard'
+
+    MEM = 'mem'
+    DF = 'df'
+
+    I2C_BUS_SET = 'i2c_bus_set'
+    I2C_BUS_GET = 'i2c_bus_get'
+    I2C_BUS_CLEAR = 'i2c_bus_clear'
+
+    UART_BUS_SET = 'uart_bus_set'
+    UART_BUS_GET = 'uart_bus_get'
+    UART_BUS_CLEAR = 'uart_bus_clear'
+
+    SPI_BUS_SET = 'spi_bus_set'
+    SPI_BUS_GET = 'spi_bus_get'
+    SPI_BUS_CLEAR = 'spi_bus_clear'
+
+    PKG_SEARCH = 'pkg_search'
+    PKG_DOWNLOAD = 'pkg_download'
+    PKG_INSTALL = 'pkg_install'
+    PKG_CLEAN = 'pkg_clean'
+    PKG_STORE_STATUS = 'pkg_store_status'
+    PKG_TYPEHINTS_LIST = 'pkg_typehints_list'
+    PKG_TYPEHINTS_GET = 'pkg_typehints_get'
+
+class CmdGroups:
+    NON_REPL = frozenset({
+        Cmd.CONNECT, Cmd.RELEASE, Cmd.DISCONNECT_PORT,
+        Cmd.STATUS, Cmd.SCAN, Cmd.SHUTDOWN, Cmd.PING, Cmd.RUN_STOP,
+        Cmd.SESSION_INFO, Cmd.CLIENT_DISCONNECT, Cmd.SESSION_SETUP, Cmd.SESSION_DISCONNECT,
+        Cmd.SESSION_SWITCH_FG, Cmd.SET_DEFAULT,
+        Cmd.I2C_BUS_SET, Cmd.I2C_BUS_GET, Cmd.I2C_BUS_CLEAR,
+        Cmd.UART_BUS_SET, Cmd.UART_BUS_GET, Cmd.UART_BUS_CLEAR,
+        Cmd.SPI_BUS_SET, Cmd.SPI_BUS_GET, Cmd.SPI_BUS_CLEAR,
+        Cmd.FIRMWARE_STAGE, Cmd.FIRMWARE_INFO, Cmd.FIRMWARE_FLASH,
+        Cmd.FIRMWARE_DISCARD,
+    })
+
+    READ_ONLY = frozenset({
+        Cmd.SHUTDOWN, Cmd.PING, Cmd.SESSION_INFO, Cmd.STATUS, Cmd.SCAN,
+        Cmd.EXEC, Cmd.LS, Cmd.LS_RECURSIVE, Cmd.CAT, Cmd.STAT,
+        Cmd.IS_DIR, Cmd.MEM, Cmd.DF,
+        Cmd.GET_FILE,
+        Cmd.GET_FILE_BATCH,
+        Cmd.GET_FILE_STREAMING, Cmd.FIRMWARE_INFO,
+        Cmd.I2C_BUS_GET,
+        Cmd.UART_BUS_GET,
+        Cmd.SPI_BUS_GET,
+        Cmd.PKG_SEARCH, Cmd.PKG_STORE_STATUS,
+        Cmd.PKG_TYPEHINTS_LIST, Cmd.PKG_TYPEHINTS_GET,
+    })
+
+    SESSION = frozenset({
+        Cmd.SESSION_SETUP, Cmd.SESSION_DISCONNECT, Cmd.SESSION_SWITCH_FG,
+        Cmd.CONNECT, Cmd.DISCONNECT_PORT, Cmd.CLIENT_DISCONNECT
+    })
+
+    PERSISTENT_BUSY = frozenset({
+        Cmd.RUN_INTERACTIVE, Cmd.REPL_ENTER
+    })
+
+    STREAMING = frozenset({
+        Cmd.GET_FILE_STREAMING, Cmd.TRANSFER_START,
+        Cmd.FIRMWARE_STAGE,
+        Cmd.RUN_INTERACTIVE, Cmd.RUN_STOP,
+        Cmd.PKG_DOWNLOAD, Cmd.PKG_INSTALL
+    })
+
+    REPL = frozenset({
+        Cmd.REPL_ENTER, Cmd.REPL_EXIT, Cmd.REPL_WRITE, Cmd.REPL_READ
+    })
+
+    DETACHED_ALLOW = frozenset({
+        Cmd.RUN_STOP, Cmd.RESET, Cmd.STATUS, Cmd.PING,
+        Cmd.SHUTDOWN, Cmd.SESSION_INFO,
+        Cmd.SESSION_DISCONNECT, Cmd.DISCONNECT_PORT, Cmd.RELEASE
+    })
+
+NON_REPL_COMMANDS = CmdGroups.NON_REPL
+READ_ONLY_COMMANDS = CmdGroups.READ_ONLY

replx_agent/helpers/__init__.py

@@ -0,0 +1,3 @@
+from .scanner import DeviceScanner
+
+__all__ = ["DeviceScanner"]

replx_agent/helpers/scanner.py

@@ -0,0 +1,308 @@
+import os
+import sys
+import re
+import time
+import gc
+from typing import Any, Callable, Optional, Tuple
+
+from replx_agent.utils import (
+    parse_device_banner,
+    canon_port,
+)
+from replx_agent.utils.constants import (
+    CTRL_B,
+    CTRL_C,
+    REPL_PROMPT,
+)
+
+
+class DeviceScanner:
+
+    @staticmethod
+    def port_compare_key(port: str | None) -> str:
+        normalized = canon_port(port) or ""
+        if sys.platform.startswith("win"):
+            return normalized.lower()
+        return os.path.realpath(normalized) if normalized else ""
+
+    @staticmethod
+    def _close_scanner_serial(ser) -> None:
+        if not ser:
+            return
+
+        try:
+            if getattr(ser, 'is_open', False):
+                try:
+                    ser.cancel_read()
+                except Exception:
+                    pass
+                try:
+                    ser.cancel_write()
+                except Exception:
+                    pass
+                try:
+                    ser.reset_input_buffer()
+                except Exception:
+                    pass
+                try:
+                    ser.reset_output_buffer()
+                except Exception:
+                    pass
+                ser.close()
+        except Exception:
+            pass
+        finally:
+            if sys.platform.startswith('win'):
+                gc.collect()
+                time.sleep(0.05)
+    
+    @staticmethod
+    def _probe_port(port_info, timeout: float = 3.0) -> Optional[Tuple[str, str, str, str]]:
+        from replx_agent.transport import repl_baud_candidates
+
+        rates = repl_baud_candidates()
+        deadline = time.monotonic() + timeout
+        for rate in rates:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            info = DeviceScanner.get_board_info_from_banner(
+                port_info.device, timeout=remaining, baudrate=rate
+            )
+            if info:
+                return info
+        return None
+
+    @staticmethod
+    def _probe_reserved_port(
+        port_info, timeout: float, reserve_port: Callable, release_port: Callable
+    ) -> Optional[Tuple[str, str, str, str]]:
+        reservation = reserve_port(port_info.device) if reserve_port else None
+        if reserve_port and reservation is None:
+            return None
+        try:
+            return DeviceScanner._probe_port(port_info, timeout=timeout)
+        finally:
+            if reservation is not None and release_port:
+                release_port(reservation)
+
+    @staticmethod
+    def get_board_info_from_banner(port: str, timeout: float = 2.0,
+                                   baudrate: int = 115200) -> Optional[Tuple[str, str, str, str]]:
+        try:
+            import serial
+        except ImportError as e:
+            raise RuntimeError("pyserial is required to scan serial ports") from e
+
+        ser = None
+        overall_start = time.monotonic()
+        is_windows = sys.platform.startswith("win")
+        if not is_windows and timeout > 1.5:
+            timeout = 1.5
+        try:
+            serial_timeout = 0.5 if is_windows else 0.3
+            ser = serial.Serial(port, baudrate, timeout=serial_timeout, write_timeout=serial_timeout)
+            
+            for _ in range(3):
+                if time.monotonic() - overall_start > timeout:
+                    return None
+                ser.write(CTRL_C)
+                time.sleep(0.05)
+            
+            ser.reset_input_buffer()
+            
+            if time.monotonic() - overall_start > timeout:
+                return None
+            
+            ser.write(CTRL_B)
+            time.sleep(0.1)
+            
+            response = b""
+            read_timeout = 0.5 if is_windows else 0.3
+            read_start = time.monotonic()
+            while time.monotonic() - read_start < read_timeout:
+                if time.monotonic() - overall_start > timeout:
+                    break
+                if ser.in_waiting:
+                    response += ser.read(ser.in_waiting)
+                    if REPL_PROMPT in response:
+                        break
+                time.sleep(0.01)
+            
+            response_str = response.decode(errors='ignore')
+            
+            return parse_device_banner(response_str)
+        
+        except PermissionError:
+            raise
+        except (OSError, serial.SerialException):
+            pass
+        finally:
+            DeviceScanner._close_scanner_serial(ser)
+        
+        return None
+    
+    @staticmethod
+    def scan_serial_ports(
+        max_workers: int = 5,
+        exclude_ports: list = None,
+        port_infos: list = None,
+        reserve_port: Callable[[str], Any] = None,
+        release_port: Callable[[Any], None] = None,
+    ) -> tuple:
+        from serial.tools.list_ports import comports as list_ports_comports
+        from concurrent.futures import ThreadPoolExecutor, as_completed
+        
+        if max_workers < 1:
+            raise ValueError("max_workers must be at least 1")
+        if reserve_port and not release_port:
+            raise ValueError("release_port is required when reserve_port is provided")
+
+        results = []
+        permission_denied = []
+        excluded = {
+            DeviceScanner.port_compare_key(port)
+            for port in (exclude_ports or [])
+            if port
+        }
+        
+        all_ports = list(port_infos) if port_infos is not None else list(list_ports_comports())
+        valid_ports = []
+        
+        _plat = sys.platform
+        
+        for port in all_ports:
+            if DeviceScanner.port_compare_key(port.device) in excluded:
+                continue
+            
+            if DeviceScanner.is_bluetooth_port(port):
+                continue
+            
+            if _plat == "darwin" or _plat.startswith("linux"):
+                if not DeviceScanner.is_likely_micropython_port(port):
+                    continue
+            
+            valid_ports.append(port)
+        
+        if not valid_ports:
+            return results, permission_denied
+        
+        if _plat == "darwin":
+            per_port_timeout = 2.5
+        elif _plat.startswith("linux"):
+            per_port_timeout = 2.5
+        else:
+            per_port_timeout = 3.0
+        max_workers = min(max_workers, len(valid_ports))
+        
+        with ThreadPoolExecutor(max_workers=max_workers) as executor:
+            future_to_port = {
+                executor.submit(
+                    DeviceScanner._probe_reserved_port,
+                    port,
+                    per_port_timeout,
+                    reserve_port,
+                    release_port,
+                ): port.device
+                for port in valid_ports
+            }
+            
+            for future in as_completed(future_to_port):
+                port_device = future_to_port[future]
+                try:
+                    board_info = future.result()
+                    if board_info:
+                        results.append((port_device, board_info))
+                except PermissionError:
+                    # OS denied access to the port (e.g. user not in dialout/uucp group on Linux)
+                    permission_denied.append(port_device)
+                except (OSError, IOError):
+                    # Port access error
+                    pass
+        
+        return results, permission_denied
+    
+    @staticmethod
+    def is_bluetooth_port(port_info) -> bool:
+        bt_keywords = ('bluetooth', 'bth', 'rfcomm')
+        description = str(getattr(port_info, 'description', '') or '').lower()
+        device = str(getattr(port_info, 'device', '') or '').lower()
+        
+        if any(keyword in description or keyword in device for keyword in bt_keywords):
+            return True
+        
+        if sys.platform == "darwin":
+            if "bluetooth" in device:
+                return True
+            if re.search(r'/dev/(cu|tty)\.(MALS|SOC)', device, re.IGNORECASE):
+                return True
+        
+        return False
+    
+    @staticmethod
+    def is_likely_micropython_port(port_info) -> bool:
+        device = str(getattr(port_info, 'device', '') or '').lower()
+        description = str(getattr(port_info, 'description', '') or '').lower()
+        vid = getattr(port_info, 'vid', None)
+        
+        if DeviceScanner.is_bluetooth_port(port_info):
+            return False
+
+        if vid is not None:
+            return True
+        
+        _plat = sys.platform
+        
+        if _plat == "darwin":
+            device_candidate = device.startswith((
+                '/dev/cu.usbmodem',
+                '/dev/cu.usbserial',
+                '/dev/cu.wchusbserial',
+                '/dev/cu.slab_usbto',
+                '/dev/tty.usbmodem',
+                '/dev/tty.usbserial',
+                '/dev/tty.wchusbserial',
+                '/dev/tty.slab_usbto',
+            ))
+            
+        elif _plat.startswith("linux"):
+            device_candidate = (
+                device.startswith((
+                    '/dev/ttyusb',
+                    '/dev/ttyacm',
+                    '/dev/ttyama',
+                    '/dev/ttys',
+                    '/dev/serial/by-id/',
+                    '/dev/serial/by-path/',
+                ))
+            )
+        else:
+            return True
+
+        description_candidate = any(
+            marker in description
+            for marker in ('cp210', 'ch340', 'ch341', 'ftdi', 'usb serial', 'usb to uart')
+        )
+        return device_candidate or description_candidate
+    
+    @staticmethod
+    def is_valid_serial_port(port_name: str) -> bool:
+        _plat = sys.platform
+
+        if _plat.startswith("win"):
+            return re.fullmatch(r"COM[1-9][0-9]*", port_name, re.IGNORECASE) is not None
+        elif _plat.startswith("linux"):
+            return (
+                re.fullmatch(r"/dev/tty(USB|ACM|AMA|S)[0-9]+", port_name, re.IGNORECASE) is not None or
+                port_name.startswith("/dev/serial/by-id/") or
+                port_name.startswith("/dev/serial/by-path/")
+            )
+        elif _plat == "darwin":
+            return (
+                re.fullmatch(
+                    r"/dev/(tty|cu)\.(usbmodem|usbserial|wchusbserial|slab_usbto[a-z0-9_-]+)",
+                    port_name,
+                    re.IGNORECASE,
+                ) is not None
+            )
+        return False

replx_agent/pkg/__init__.py

@@ -0,0 +1,11 @@
+from .store import StoreManager
+from .registry import InstallHelper, SearchHelper, RegistryHelper
+from .compiler import CompilerHelper
+
+__all__ = [
+    "StoreManager",
+    "InstallHelper",
+    "SearchHelper",
+    "RegistryHelper",
+    "CompilerHelper",
+]

replx_agent/pkg/compiler.py

@@ -0,0 +1,153 @@
+import os
+import hashlib
+import subprocess
+
+from replx_agent.utils.device_info import normalize_core
+from replx_agent.utils.exceptions import CompilationError, ValidationError, PkgError
+from .store import StoreManager
+
+
+class CompilerHelper:
+    _compile_cache = {}
+
+    @staticmethod
+    def _run_mpy_cross(args: list[str], source_path: str) -> None:
+        try:
+            import mpy_cross
+        except ImportError as e:
+            raise CompilationError("mpy-cross is not installed") from e
+
+        try:
+            proc = mpy_cross.run(
+                *args,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+            )
+        except Exception as e:
+            raise CompilationError(f"MPY compilation failed for {source_path}: {e}") from e
+
+        stdout = ""
+        stderr = ""
+        returncode = 0
+
+        if hasattr(proc, "communicate"):
+            stdout, stderr = proc.communicate()
+            returncode = proc.returncode or 0
+
+        if returncode != 0:
+            details = (stderr or stdout or f"mpy-cross exited with code {returncode}").strip()
+            raise CompilationError(f"MPY compilation failed for {source_path}: {details}")
+
+    @staticmethod
+    def compile_file(abs_py: str, out_mpy: str, core: str, version: str) -> str:
+        if not os.path.exists(abs_py):
+            raise ValidationError(f"Source file not found: {abs_py}")
+
+        if normalize_core(core) == "EFR32MG":
+            raise CompilationError(
+                "Digi XBee3 uses a legacy/vendor .mpy ABI. The bundled mpy-cross "
+                "cannot certify compatibility; upload .py source with put, "
+                "or use mip install --no-compile."
+            )
+
+        out_dir = os.path.dirname(out_mpy)
+        if out_dir:
+            os.makedirs(out_dir, exist_ok=True)
+
+        args = [abs_py, '-o', out_mpy]
+        args.extend(CompilerHelper._march_for_core(core, version or "1.29.0"))
+        CompilerHelper._run_mpy_cross(args, abs_py)
+
+        if os.path.exists(out_mpy) and os.path.getsize(out_mpy) > 0:
+            return out_mpy
+
+        raise CompilationError(f"Compilation failed: {out_mpy} not found or empty")
+
+    @staticmethod
+    def mpy_arch_tag(core: str) -> str:
+        if not core:
+            return "unknown"
+        if "/" in core:
+            return core.split("/", 1)[0]
+        return core
+
+    @staticmethod
+    def staging_out_for(abs_py: str, base: str, arch_tag: str) -> str:
+        rel = os.path.relpath(abs_py, base).replace("\\", "/")
+        rel_mpy = os.path.splitext(rel)[0] + ".mpy"
+        out_path = StoreManager.HOME_STAGING / arch_tag / rel_mpy
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        return str(out_path)
+
+    @staticmethod
+    def _compute_file_hash(filepath: str) -> str:
+        hash_md5 = hashlib.md5()
+        with open(filepath, "rb") as f:
+            for chunk in iter(lambda: f.read(8192), b""):
+                hash_md5.update(chunk)
+        return hash_md5.hexdigest()
+
+    @staticmethod
+    def _march_for_core(core: str, version: str) -> list[str]:
+        if not core:
+            raise PkgError("The core is unknown")
+
+        if "/" in core:
+            core = core.split("/", 1)[0]
+
+        args: list[str] = ['-msmall-int-bits=31']
+
+        if core == "EFR32MG":
+            try:
+                ver_parts = version.split('.')
+                ver_float = float(f"{ver_parts[0]}.{ver_parts[1]}" if len(ver_parts) >= 2 else version)
+            except (ValueError, IndexError):
+                ver_float = 0.0
+            if ver_float < 1.19:
+                args.append('-mno-unicode')
+            return args
+
+        if core in ("ESP32", "ESP32S2"):
+            args.append('-march=xtensa')
+            return args
+
+        if core == "ESP32S3":
+            args.append('-march=xtensawin')
+            return args
+
+        if core.startswith("ESP32C"):
+            args.append('-march=rv32imc')
+            return args
+
+        if core.startswith("ESP32P"):
+            args.append('-march=rv32imc')
+            return args
+
+        if core == "RP2350":
+            args.append('-march=armv7emsp')
+            return args
+
+        raise PkgError(f"The {core} is not supported")
+
+    @staticmethod
+    def compile_to_staging(abs_py: str, base: str, core: str, version: str) -> str:
+        if not os.path.exists(abs_py):
+            raise ValidationError(f"Source file not found: {abs_py}")
+
+        arch_tag = CompilerHelper.mpy_arch_tag(core)
+        out_mpy = CompilerHelper.staging_out_for(abs_py, base, arch_tag)
+
+        cache_key = (abs_py, arch_tag)
+        current_hash = CompilerHelper._compute_file_hash(abs_py)
+
+        if cache_key in CompilerHelper._compile_cache:
+            cached_hash, cached_out = CompilerHelper._compile_cache[cache_key]
+            if cached_hash == current_hash and os.path.exists(cached_out) and os.path.getsize(cached_out) > 0:
+                return cached_out
+
+        CompilerHelper.compile_file(abs_py, out_mpy, core, version or "1.29.0")
+        CompilerHelper._compile_cache[cache_key] = (current_hash, out_mpy)
+        return out_mpy