From 948775968d1c5de0cd23e67fc1402ef91c41df46 Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Tue, 27 Jan 2026 22:29:19 -0700 Subject: [PATCH 01/10] Default to auto-baud detection when opening ports open_serial_port() now auto-detects baud rate when baudrate=None (default). Returns detection confidence and top candidates in response. Falls back to DEFAULT_BAUDRATE (9600) if no data received or low confidence. Optional autobaud_probe parameter for sync-based detection on echo devices. --- src/mcserial/server.py | 166 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 161 insertions(+), 5 deletions(-) diff --git a/src/mcserial/server.py b/src/mcserial/server.py index 5438b6f..057853b 100644 --- a/src/mcserial/server.py +++ b/src/mcserial/server.py @@ -28,6 +28,123 @@ class SerialConnection: # Active connections registry _connections: dict[str, SerialConnection] = {} + +def _detect_baud_rate_internal( + port: str, + probe: str | None = None, + timeout_per_rate: float = 0.3, + baudrates: list[int] | None = None, +) -> dict: + """Internal baud rate detection (not exposed as MCP tool). + + Used by open_serial_port for auto-detection. + """ + import math + import time + from collections import Counter + + # Common baud rates ordered by popularity + default_rates = [ + 115200, 9600, 57600, 38400, 19200, + 230400, 460800, 921600, + 4800, 2400, 1200, + ] + rates_to_try = baudrates or default_rates + results = [] + + def score_data(data: bytes) -> dict: + """Score data readability with sync pattern analysis.""" + if not data: + return {"score": 0, "bytes_received": 0} + + # Printable ASCII percentage + printable = sum(1 for b in data if 32 <= b <= 126 or b in (9, 10, 13)) + printable_pct = (printable / len(data)) * 100 + + # Line endings indicator + has_newlines = b'\n' in data or b'\r' in data + + # Null byte penalty + null_pct = (data.count(0x00) / len(data)) * 100 + + # 0x55 sync pattern detection + sync_count = sum(1 for b in data if b in (0x55, 0xAA)) + sync_pct = (sync_count / len(data)) * 100 + + # Bit transitions (0x55 has 7 per byte) + transitions = sum( + sum(1 for i in range(7) if ((b >> i) & 1) != ((b >> (i + 1)) & 1)) + for b in data + ) + avg_transitions = transitions / len(data) + + # Text clustering + counter = Counter(data) + text_cluster = sum(counter.get(b, 0) for b in range(0x20, 0x7F)) / len(data) * 100 + + # Entropy calculation + entropy = 0 + for count in counter.values(): + if count > 0: + p = count / len(data) + entropy -= p * math.log2(p) + norm_entropy = (entropy / 8) * 100 + + # Composite score + score = printable_pct + score += sync_pct * 0.5 + score += min(100, (avg_transitions / 7) * 100) * 0.2 if avg_transitions > 3 else 0 + score += text_cluster * 0.3 + if has_newlines: + score += 15 + if null_pct > 30: + score -= 40 + if norm_entropy > 70: + score -= 20 + + # UTF-8 bonus + try: + data.decode('utf-8') + score += 10 + except UnicodeDecodeError: + pass + + return { + "score": round(max(0, min(100, score)), 1), + "bytes_received": len(data), + } + + for rate in rates_to_try: + try: + conn = serial.Serial(port=port, baudrate=rate, timeout=timeout_per_rate) + + if probe: + conn.write(probe.encode()) + conn.flush() + time.sleep(0.05) + + time.sleep(timeout_per_rate) + available = conn.in_waiting + data = conn.read(available) if available else b"" + conn.close() + + score_result = score_data(data) + if score_result["bytes_received"] > 0: + results.append({"baudrate": rate, **score_result}) + + except serial.SerialException: + continue + + results.sort(key=lambda x: x["score"], reverse=True) + best = results[0] if results else None + + return { + "detected_baudrate": best["baudrate"] if best and best["score"] > 50 else None, + "confidence": best["score"] if best else 0, + "results": results[:5], + } + + mcp = FastMCP( name="mcserial", instructions="""Serial port MCP server. Use tools to open/close/write to serial ports. @@ -74,7 +191,7 @@ def list_serial_ports(usb_only: bool = True) -> list[dict]: @mcp.tool() def open_serial_port( port: str, - baudrate: int = DEFAULT_BAUDRATE, + baudrate: int | None = None, bytesize: Literal[5, 6, 7, 8] = 8, parity: Literal["N", "E", "O", "M", "S"] = "N", stopbits: Literal[1, 1.5, 2] = 1, @@ -85,12 +202,18 @@ def open_serial_port( rtscts: bool = False, dsrdtr: bool = False, exclusive: bool = False, + autobaud_probe: str | None = None, + autobaud_timeout: float = 0.3, ) -> dict: - """Open a serial port connection. + """Open a serial port connection with optional auto-baud detection. + + If baudrate is not specified (None), automatically detects the baud rate + by analyzing incoming data patterns. Works best when the device is actively + sending data or responds to a probe string. Args: port: Device path (e.g., '/dev/ttyUSB0', 'COM3') - baudrate: Baud rate (default from env or 9600) + baudrate: Baud rate. If None, auto-detect (recommended for unknown devices) bytesize: Data bits (5, 6, 7, or 8) parity: Parity checking (N=None, E=Even, O=Odd, M=Mark, S=Space) stopbits: Stop bits (1, 1.5, or 2) @@ -101,9 +224,11 @@ def open_serial_port( rtscts: Enable hardware RTS/CTS flow control dsrdtr: Enable hardware DSR/DTR flow control exclusive: Request exclusive access (lock port from other processes) + autobaud_probe: String to send during auto-detection (e.g., "UUUUU" for sync) + autobaud_timeout: Timeout per rate during auto-detection (default 0.3s) Returns: - Connection status and details + Connection status and details (includes auto-detection info if used) """ if port in _connections: return {"error": f"Port {port} is already open", "success": False} @@ -111,6 +236,34 @@ def open_serial_port( if len(_connections) >= MAX_CONNECTIONS: return {"error": f"Maximum connections ({MAX_CONNECTIONS}) reached", "success": False} + # Auto-detect baud rate if not specified + detected_info = None + if baudrate is None: + # Import the detect function's logic inline to avoid circular issues + detection_result = _detect_baud_rate_internal( + port=port, + probe=autobaud_probe, + timeout_per_rate=autobaud_timeout, + ) + if detection_result.get("detected_baudrate"): + baudrate = detection_result["detected_baudrate"] + detected_info = { + "auto_detected": True, + "detection_confidence": detection_result.get("confidence", 0), + "detection_candidates": [ + {"baudrate": r["baudrate"], "score": r["score"]} + for r in detection_result.get("results", [])[:3] + ], + } + else: + # Fall back to default if detection fails + baudrate = DEFAULT_BAUDRATE + detected_info = { + "auto_detected": False, + "fallback_reason": "No data received or low confidence", + "using_default": DEFAULT_BAUDRATE, + } + try: conn = serial.Serial( port=port, @@ -127,7 +280,7 @@ def open_serial_port( exclusive=exclusive, ) _connections[port] = SerialConnection(port=port, connection=conn) - return { + result = { "success": True, "port": port, "baudrate": baudrate, @@ -140,6 +293,9 @@ def open_serial_port( "exclusive": exclusive, "resource_uri": f"serial://{port}/data", } + if detected_info: + result["autobaud"] = detected_info + return result except serial.SerialException as e: return {"error": str(e), "success": False} From 974f2ee6dc16ca42ca1428bc26791bc1157862bb Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Tue, 27 Jan 2026 22:42:40 -0700 Subject: [PATCH 02/10] Add RS-485 specific tools New tools for RS-485 half-duplex communication: - check_rs485_support: Detect hardware RS-485 capability via udev/ioctl Reports driver type (FTDI/CP210x/CH340), kernel support, and recommendations - rs485_transact: Send request and receive response with automatic TX/RX turnaround timing. Handles manual RTS control when needed. - rs485_scan_addresses: Scan bus for responding devices (1-247) Useful for Modbus device discovery --- src/mcserial/server.py | 291 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 291 insertions(+) diff --git a/src/mcserial/server.py b/src/mcserial/server.py index 057853b..eae1a91 100644 --- a/src/mcserial/server.py +++ b/src/mcserial/server.py @@ -853,6 +853,297 @@ def set_rs485_mode( return {"error": str(e), "success": False} +@mcp.tool() +def check_rs485_support(port: str) -> dict: + """Check RS-485 hardware support for a serial port. + + Detects whether the port/driver supports hardware RS-485 mode + (automatic DE/RE control) or requires software emulation. + + Args: + port: Device path to check (doesn't need to be open) + + Returns: + RS-485 capability information + """ + import subprocess + + result = { + "port": port, + "driver": None, + "chip": None, + "hardware_rs485": False, + "software_fallback": True, + "notes": [], + } + + # Try to get USB device info + try: + # Get the device's parent USB info via udevadm + udev_output = subprocess.run( + ["udevadm", "info", "-a", "-n", port], + capture_output=True, + text=True, + timeout=5, + ) + udev_info = udev_output.stdout.lower() + + # Detect driver + if "ftdi" in udev_info: + result["driver"] = "ftdi_sio" + result["hardware_rs485"] = True + result["notes"].append("FTDI chips have hardware RS-485 auto-direction") + elif "cp210x" in udev_info or "silabs" in udev_info: + result["driver"] = "cp210x" + # Only some CP210x models support RS-485 + if "cp2102" in udev_info: + result["chip"] = "CP2102" + result["hardware_rs485"] = False + result["notes"].append("CP2102 lacks hardware RS-485; use software RTS control") + elif "cp2105" in udev_info or "cp2108" in udev_info: + result["chip"] = "CP2105/CP2108" + result["hardware_rs485"] = True + result["notes"].append("CP2105/CP2108 have hardware RS-485 support") + else: + result["notes"].append("CP210x detected; RS-485 support varies by model") + elif "ch341" in udev_info or "ch340" in udev_info: + result["driver"] = "ch341" + result["hardware_rs485"] = False + result["notes"].append("CH340/CH341 lacks hardware RS-485; timing may be unreliable") + elif "pl2303" in udev_info: + result["driver"] = "pl2303" + result["hardware_rs485"] = False + result["notes"].append("PL2303 lacks hardware RS-485; use software RTS control") + elif "ttyS" in port or "ttyAMA" in port: + result["driver"] = "native" + result["hardware_rs485"] = True + result["notes"].append("Native UART; check if RS-485 transceiver is connected") + + # Try to detect chip from product string + for line in udev_output.stdout.split('\n'): + if 'ATTRS{product}' in line: + result["chip"] = line.split('==')[1].strip(' "') if '==' in line else None + break + + except (subprocess.TimeoutExpired, FileNotFoundError): + result["notes"].append("Could not query udev; install udevadm for better detection") + + # Test if kernel RS-485 ioctl works + try: + import fcntl + + # TIOCSRS485 = 0x542F, TIOCGRS485 = 0x542E + TIOCGRS485 = 0x542E + + with open(port) as f: + try: + # Try to get current RS-485 settings + fcntl.ioctl(f.fileno(), TIOCGRS485, b'\x00' * 32) + result["kernel_rs485_ioctl"] = True + result["notes"].append("Kernel TIOCSRS485 ioctl supported") + except OSError: + result["kernel_rs485_ioctl"] = False + result["notes"].append("Kernel RS-485 ioctl not supported on this port") + except Exception as e: + result["kernel_rs485_ioctl"] = False + result["notes"].append(f"Could not test ioctl: {e}") + + # Recommendation + if result["hardware_rs485"]: + result["recommendation"] = "Use set_rs485_mode() for automatic DE/RE control" + else: + result["recommendation"] = "Use manual RTS control via set_modem_lines() around writes" + + result["success"] = True + return result + + +@mcp.tool() +def rs485_transact( + port: str, + data: str, + response_timeout: float = 1.0, + response_terminator: str | None = None, + response_length: int | None = None, + encoding: str = "utf-8", + turnaround_delay: float = 0.005, +) -> dict: + """Send data and receive response on RS-485 bus (half-duplex transaction). + + Handles the TX→RX turnaround timing automatically. For devices without + hardware RS-485 support, manually controls RTS around the transaction. + + Useful for request/response protocols like Modbus RTU. + + Args: + port: Device path (must be open, preferably with RS-485 mode set) + data: Data to send + response_timeout: Max time to wait for response (seconds) + response_terminator: Stop reading when this sequence is received + response_length: Expected response length in bytes (alternative to terminator) + encoding: Character encoding for data + turnaround_delay: Delay after TX before reading (seconds) + + Returns: + Transaction result with sent/received data + """ + import time + + if port not in _connections: + return {"error": f"Port {port} is not open", "success": False} + + try: + conn = _connections[port].connection + has_hw_rs485 = conn.rs485_mode is not None + + # Clear any pending data + conn.reset_input_buffer() + + # If no hardware RS-485, manually control RTS for TX + if not has_hw_rs485: + conn.rts = True # Enable driver (TX mode) + time.sleep(0.001) # Small settling time + + # Send data + encoded = data.encode(encoding) + bytes_written = conn.write(encoded) + conn.flush() + + # Wait for transmission to complete + # At slowest common rate (9600), 1 byte = ~1ms + tx_time = (bytes_written * 10) / conn.baudrate # 10 bits per byte typical + time.sleep(tx_time + turnaround_delay) + + # Switch to RX mode if manual control + if not has_hw_rs485: + conn.rts = False # Disable driver (RX mode) + time.sleep(0.001) + + # Read response + original_timeout = conn.timeout + conn.timeout = response_timeout + + try: + if response_terminator: + term_bytes = response_terminator.encode(encoding) + raw_response = conn.read_until(term_bytes) + elif response_length: + raw_response = conn.read(response_length) + else: + # Wait for data, then read all available + time.sleep(response_timeout * 0.5) + available = conn.in_waiting + raw_response = conn.read(available) if available else b"" + finally: + conn.timeout = original_timeout + + return { + "success": True, + "port": port, + "bytes_sent": bytes_written, + "data_sent": data, + "response": raw_response.decode(encoding, errors="replace"), + "response_bytes": len(raw_response), + "response_hex": raw_response.hex(), + "hardware_rs485": has_hw_rs485, + } + + except serial.SerialException as e: + return {"error": str(e), "success": False} + + +@mcp.tool() +def rs485_scan_addresses( + port: str, + start_address: int = 1, + end_address: int = 247, + probe_template: str = "{addr:02x}03000001", + response_timeout: float = 0.1, + encoding: str = "latin-1", +) -> dict: + """Scan RS-485 bus for responding devices (address discovery). + + Sends a probe message to each address and records which ones respond. + Useful for discovering Modbus or similar addressed devices on the bus. + + Args: + port: Device path (must be open with RS-485 mode) + start_address: First address to scan (default 1) + end_address: Last address to scan (default 247, Modbus max) + probe_template: Message template with {addr} placeholder. Default is + a Modbus "read holding register" frame (customize for your protocol) + response_timeout: Time to wait for response per address (seconds) + encoding: Encoding for probe (use 'latin-1' for raw bytes) + + Returns: + List of responding addresses + """ + import time + + if port not in _connections: + return {"error": f"Port {port} is not open", "success": False} + + try: + conn = _connections[port].connection + has_hw_rs485 = conn.rs485_mode is not None + + responding = [] + scanned = 0 + + for addr in range(start_address, end_address + 1): + # Format probe with address + try: + if "{addr" in probe_template: + probe = probe_template.format(addr=addr) + else: + probe = chr(addr) + probe_template + except (ValueError, KeyError): + probe = chr(addr) + probe_template + + # Clear buffers + conn.reset_input_buffer() + + # TX + if not has_hw_rs485: + conn.rts = True + time.sleep(0.001) + + conn.write(probe.encode(encoding)) + conn.flush() + + tx_time = (len(probe) * 10) / conn.baudrate + time.sleep(tx_time + 0.002) + + if not has_hw_rs485: + conn.rts = False + time.sleep(0.001) + + # Wait for response + time.sleep(response_timeout) + + if conn.in_waiting > 0: + response = conn.read(conn.in_waiting) + responding.append({ + "address": addr, + "response_length": len(response), + "response_hex": response.hex()[:32], # First 16 bytes + }) + + scanned += 1 + + return { + "success": True, + "port": port, + "addresses_scanned": scanned, + "devices_found": len(responding), + "responding_addresses": responding, + "hardware_rs485": has_hw_rs485, + } + + except serial.SerialException as e: + return {"error": str(e), "success": False} + + @mcp.tool() def set_low_latency_mode(port: str, enabled: bool = True) -> dict: """Enable or disable low-latency mode (Linux only). From fb671a7c346e72a085ae64898c4e60549bb3cdf0 Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Wed, 28 Jan 2026 12:27:48 -0700 Subject: [PATCH 03/10] Add X/Y/ZMODEM file transfer protocols with security hardening File transfer protocols: - XMODEM: 128/1024-byte blocks with checksum or CRC-16 - YMODEM: Batch transfers with file metadata in block 0 - ZMODEM: Streaming protocol with auto-resume capability Security and robustness fixes: - Atomic file creation (O_CREAT|O_EXCL) prevents TOCTOU races - Transfer size limits (100MB default) prevent memory exhaustion - Byte range validation (0-255) with clear error messages - 4GB overflow handling for ZMODEM position encoding - CRC-32 table initialized at module load for thread safety - Timeout enforcement prevents indefinite hangs Server enhancements: - file_transfer_send/receive/send_batch tools - atexit cleanup for open connections - Thread-safety documentation for _connections registry --- src/mcserial/server.py | 456 +++++++++++++++++++++-- src/mcserial/xmodem.py | 407 ++++++++++++++++++++ src/mcserial/ymodem.py | 542 +++++++++++++++++++++++++++ src/mcserial/zmodem.py | 815 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 2184 insertions(+), 36 deletions(-) create mode 100644 src/mcserial/xmodem.py create mode 100644 src/mcserial/ymodem.py create mode 100644 src/mcserial/zmodem.py diff --git a/src/mcserial/server.py b/src/mcserial/server.py index eae1a91..4c65c5b 100644 --- a/src/mcserial/server.py +++ b/src/mcserial/server.py @@ -2,6 +2,7 @@ from __future__ import annotations +import atexit import os from dataclasses import dataclass, field from typing import Literal @@ -23,12 +24,34 @@ class SerialConnection: port: str connection: serial.Serial buffer: bytes = field(default_factory=bytes) + mode: Literal["rs232", "rs485"] = "rs232" # Active connections registry +# NOTE: This dict is NOT thread-safe. The MCP server is designed for single-threaded +# async operation (FastMCP uses async/await). If you need thread-safe access, +# wrap operations with threading.Lock or use asyncio.Lock for async contexts. _connections: dict[str, SerialConnection] = {} +def _cleanup_connections() -> None: + """Close all open serial connections on exit. + + Registered with atexit to ensure ports are released when the server stops, + preventing port lockups that would require manual intervention. + """ + for _port, conn in list(_connections.items()): + try: + if conn.connection.is_open: + conn.connection.close() + except Exception: + pass # Best effort - don't raise during shutdown + _connections.clear() + + +atexit.register(_cleanup_connections) + + def _detect_baud_rate_internal( port: str, probe: str | None = None, @@ -116,21 +139,19 @@ def _detect_baud_rate_internal( for rate in rates_to_try: try: - conn = serial.Serial(port=port, baudrate=rate, timeout=timeout_per_rate) + with serial.Serial(port=port, baudrate=rate, timeout=timeout_per_rate) as conn: + if probe: + conn.write(probe.encode()) + conn.flush() + time.sleep(0.05) - if probe: - conn.write(probe.encode()) - conn.flush() - time.sleep(0.05) + time.sleep(timeout_per_rate) + available = conn.in_waiting + data = conn.read(available) if available else b"" - time.sleep(timeout_per_rate) - available = conn.in_waiting - data = conn.read(available) if available else b"" - conn.close() - - score_result = score_data(data) - if score_result["bytes_received"] > 0: - results.append({"baudrate": rate, **score_result}) + score_result = score_data(data) + if score_result["bytes_received"] > 0: + results.append({"baudrate": rate, **score_result}) except serial.SerialException: continue @@ -145,11 +166,57 @@ def _detect_baud_rate_internal( } +def _require_mode(port: str, required_mode: Literal["rs232", "rs485"]) -> dict | None: + """Check if port is in the required mode. Returns error dict if wrong mode.""" + if port not in _connections: + return {"error": f"Port {port} is not open", "success": False} + + current_mode = _connections[port].mode + if current_mode != required_mode: + other_mode = "RS-232" if required_mode == "rs485" else "RS-485" + return { + "error": f"Port {port} is in {current_mode.upper()} mode. " + f"Use set_port_mode(port='{port}', mode='{required_mode}') to switch to {required_mode.upper()} mode first.", + "success": False, + "current_mode": current_mode, + "required_mode": required_mode, + "hint": f"This tool is for {required_mode.upper()} operations. " + f"Switch modes or use {other_mode} tools instead.", + } + return None # Mode is correct + + mcp = FastMCP( name="mcserial", - instructions="""Serial port MCP server. Use tools to open/close/write to serial ports. -Use resources to read data from open ports (serial://{port}/data). -Always list_serial_ports first to discover available ports.""", + instructions="""Serial port MCP server for RS-232/RS-485 communication and file transfers. + +## Quick Start +1. list_serial_ports() - Discover available ports +2. open_serial_port(port) - Open a connection (defaults to RS-232 mode) +3. Read/write data using tools or resources + +## Modes +Ports open in RS-232 mode by default. Use set_port_mode() to switch: + +**RS-232 mode** (default): Point-to-point serial with modem control lines. + - Tools: get_modem_lines, set_modem_lines, pulse_line, send_break + +**RS-485 mode**: Half-duplex multi-drop bus communication. + - Tools: set_rs485_mode, rs485_transact, rs485_scan_addresses + +## File Transfers (X/Y/ZMODEM) +Transfer files using classic protocols. Works in both modes. + - file_transfer_send(port, file, protocol="zmodem") + - file_transfer_receive(port, save_path, protocol="zmodem") + - file_transfer_send_batch(port, files) - YMODEM/ZMODEM only + +Protocols: xmodem (128B blocks), xmodem1k, ymodem (batch), zmodem (streaming, recommended) + +## Resources +- serial://ports - List available ports +- serial://{port}/data - Read data from open port +- serial://{port}/status - Port configuration and mode +- serial://{port}/raw - Read as hex dump""", ) @@ -283,6 +350,7 @@ def open_serial_port( result = { "success": True, "port": port, + "mode": "rs232", # Default mode "baudrate": baudrate, "bytesize": bytesize, "parity": parity, @@ -292,6 +360,7 @@ def open_serial_port( "dsrdtr": dsrdtr, "exclusive": exclusive, "resource_uri": f"serial://{port}/data", + "mode_hint": "Use set_port_mode() to switch to RS-485 mode if needed.", } if detected_info: result["autobaud"] = detected_info @@ -360,6 +429,14 @@ def write_serial_bytes(port: str, data: list[int]) -> dict: if port not in _connections: return {"error": f"Port {port} is not open", "success": False} + # Validate byte range before conversion - bytes() silently truncates values > 255 + invalid_values = [b for b in data if not (0 <= b <= 255)] + if invalid_values: + return { + "error": f"Byte values must be 0-255, got invalid values: {invalid_values[:5]}{'...' if len(invalid_values) > 5 else ''}", + "success": False, + } + try: conn = _connections[port].connection raw_bytes = bytes(data) @@ -520,7 +597,7 @@ def get_connection_status() -> dict: """Get status of all open serial connections. Returns: - Dictionary of open connections with their settings + Dictionary of open connections with their settings and current mode """ status = {} for port, sc in _connections.items(): @@ -528,6 +605,7 @@ def get_connection_status() -> dict: try: status[port] = { "is_open": conn.is_open, + "mode": sc.mode, "baudrate": conn.baudrate, "bytesize": conn.bytesize, "parity": conn.parity, @@ -549,7 +627,7 @@ def get_connection_status() -> dict: "resource_uri": f"serial://{port}/data", } except serial.SerialException: - status[port] = {"is_open": False, "error": "Port disconnected"} + status[port] = {"is_open": False, "mode": sc.mode, "error": "Port disconnected"} return {"connections": status, "count": len(_connections)} @@ -579,10 +657,70 @@ def flush_serial(port: str, input_buffer: bool = True, output_buffer: bool = Tru return {"error": str(e), "success": False} +@mcp.tool() +def set_port_mode(port: str, mode: Literal["rs232", "rs485"]) -> dict: + """Switch a serial port between RS-232 and RS-485 modes. + + Mode determines which tools are available: + + RS-232 mode (default): + - Standard point-to-point serial communication + - Full modem control lines (RTS, DTR, CTS, DSR, RI, CD) + - Tools: get_modem_lines, set_modem_lines, pulse_line, send_break + + RS-485 mode: + - Half-duplex multi-drop bus communication + - Automatic or manual TX/RX direction control + - Tools: set_rs485_mode, rs485_transact, rs485_scan_addresses, check_rs485_support + + Common tools work in both modes: + - open/close, read/write, configure, flush, detect_baud_rate + + Args: + port: Device path of the port to configure + mode: Target mode ("rs232" or "rs485") + + Returns: + Mode change status with available tools for the new mode + """ + if port not in _connections: + return {"error": f"Port {port} is not open", "success": False} + + old_mode = _connections[port].mode + _connections[port].mode = mode + + mode_tools = { + "rs232": [ + "get_modem_lines", + "set_modem_lines", + "pulse_line", + "send_break", + "set_break_condition", + ], + "rs485": [ + "set_rs485_mode", + "rs485_transact", + "rs485_scan_addresses", + "check_rs485_support", + ], + } + + return { + "success": True, + "port": port, + "previous_mode": old_mode, + "current_mode": mode, + "mode_tools": mode_tools[mode], + "hint": f"Port is now in {mode.upper()} mode. Use the listed tools for {mode.upper()} operations.", + } + + @mcp.tool() def get_modem_lines(port: str) -> dict: """Get all RS-232 modem control/status line states. + **Requires RS-232 mode** (default). Use set_port_mode() to switch if needed. + Input lines (directly readable from device): - CTS: Clear To Send (device ready to receive) - DSR: Data Set Ready (device is present/powered) @@ -599,8 +737,8 @@ def get_modem_lines(port: str) -> dict: Returns: All modem line states """ - if port not in _connections: - return {"error": f"Port {port} is not open", "success": False} + if mode_error := _require_mode(port, "rs232"): + return mode_error try: conn = _connections[port].connection @@ -630,6 +768,8 @@ def set_modem_lines( ) -> dict: """Set RS-232 output control lines (RTS and DTR). + **Requires RS-232 mode** (default). Use set_port_mode() to switch if needed. + These lines can be used for: - Hardware flow control - Device reset sequences (many boards use DTR for reset) @@ -644,8 +784,8 @@ def set_modem_lines( Returns: Updated line states """ - if port not in _connections: - return {"error": f"Port {port} is not open", "success": False} + if mode_error := _require_mode(port, "rs232"): + return mode_error try: conn = _connections[port].connection @@ -673,6 +813,8 @@ def pulse_line( ) -> dict: """Pulse an RS-232 control line (useful for reset sequences). + **Requires RS-232 mode** (default). Use set_port_mode() to switch if needed. + Many devices use DTR or RTS for reset: - ESP32/ESP8266: DTR low + RTS sequence for bootloader - Arduino: DTR pulse for reset @@ -689,8 +831,8 @@ def pulse_line( """ import time - if port not in _connections: - return {"error": f"Port {port} is not open", "success": False} + if mode_error := _require_mode(port, "rs232"): + return mode_error if duration_ms < 1 or duration_ms > 5000: return {"error": "duration_ms must be between 1 and 5000", "success": False} @@ -729,6 +871,8 @@ def pulse_line( def send_break(port: str, duration_ms: int = 250) -> dict: """Send a serial break signal. + **Requires RS-232 mode** (default). Use set_port_mode() to switch if needed. + A break is a sustained low signal longer than a character frame, used to get attention of remote device or trigger special modes. @@ -739,8 +883,8 @@ def send_break(port: str, duration_ms: int = 250) -> dict: Returns: Break operation status """ - if port not in _connections: - return {"error": f"Port {port} is not open", "success": False} + if mode_error := _require_mode(port, "rs232"): + return mode_error if duration_ms < 1 or duration_ms > 5000: return {"error": "duration_ms must be between 1 and 5000", "success": False} @@ -802,7 +946,9 @@ def set_rs485_mode( rts_level_for_rx: bool = False, loopback: bool = False, ) -> dict: - """Configure RS-485 mode for half-duplex communication. + """Configure RS-485 hardware mode for half-duplex communication. + + **Requires RS-485 mode.** Use set_port_mode(port, "rs485") first. RS-485 is commonly used in industrial applications (Modbus, etc.) where multiple devices share a bus. The driver must control the @@ -820,8 +966,8 @@ def set_rs485_mode( Returns: RS-485 configuration status """ - if port not in _connections: - return {"error": f"Port {port} is not open", "success": False} + if mode_error := _require_mode(port, "rs485"): + return mode_error try: conn = _connections[port].connection @@ -970,6 +1116,8 @@ def rs485_transact( ) -> dict: """Send data and receive response on RS-485 bus (half-duplex transaction). + **Requires RS-485 mode.** Use set_port_mode(port, "rs485") first. + Handles the TX→RX turnaround timing automatically. For devices without hardware RS-485 support, manually controls RTS around the transaction. @@ -989,8 +1137,8 @@ def rs485_transact( """ import time - if port not in _connections: - return {"error": f"Port {port} is not open", "success": False} + if mode_error := _require_mode(port, "rs485"): + return mode_error try: conn = _connections[port].connection @@ -1063,6 +1211,8 @@ def rs485_scan_addresses( ) -> dict: """Scan RS-485 bus for responding devices (address discovery). + **Requires RS-485 mode.** Use set_port_mode(port, "rs485") first. + Sends a probe message to each address and records which ones respond. Useful for discovering Modbus or similar addressed devices on the bus. @@ -1080,8 +1230,8 @@ def rs485_scan_addresses( """ import time - if port not in _connections: - return {"error": f"Port {port} is not open", "success": False} + if mode_error := _require_mode(port, "rs485"): + return mode_error try: conn = _connections[port].connection @@ -1175,6 +1325,8 @@ def set_low_latency_mode(port: str, enabled: bool = True) -> dict: def set_break_condition(port: str, enabled: bool) -> dict: """Set or clear the break condition on a serial port. + **Requires RS-232 mode** (default). Use set_port_mode() to switch if needed. + Unlike send_break() which sends a timed pulse, this holds the break condition until explicitly cleared. Useful for protocols that require sustained break states. @@ -1186,8 +1338,8 @@ def set_break_condition(port: str, enabled: bool) -> dict: Returns: Break condition status """ - if port not in _connections: - return {"error": f"Port {port} is not open", "success": False} + if mode_error := _require_mode(port, "rs232"): + return mode_error try: conn = _connections[port].connection @@ -1440,6 +1592,236 @@ def detect_baud_rate( return {"error": str(e), "success": False} +# ============================================================================ +# FILE TRANSFER TOOLS - X/Y/ZMODEM protocols +# ============================================================================ + + +@mcp.tool() +def file_transfer_send( + port: str, + file_path: str, + protocol: Literal["xmodem", "xmodem1k", "ymodem", "zmodem"] = "zmodem", +) -> dict: + """Send a file over serial using X/Y/ZMODEM protocol. + + Works in both RS-232 and RS-485 modes. + + Protocols: + - xmodem: 128-byte blocks, simple but compatible (1977) + - xmodem1k: 1024-byte blocks, faster than basic XMODEM + - ymodem: Batch mode, sends filename/size (1985) + - zmodem: Streaming, auto-resume, most efficient (1986) [recommended] + + The receiver must be waiting in receive mode before calling this. + For ZMODEM, the receiver typically auto-starts when it sees the init sequence. + + Args: + port: Device path of the open serial port + file_path: Path to the file to send + protocol: Transfer protocol to use (default: zmodem) + + Returns: + Transfer statistics including bytes sent and any errors + """ + from pathlib import Path + + if port not in _connections: + return {"error": f"Port {port} is not open", "success": False} + + filepath = Path(file_path) + if not filepath.exists(): + return {"error": f"File not found: {file_path}", "success": False} + + conn = _connections[port].connection + + # Create read/write functions for the protocol handlers + def read_func(n: int) -> bytes: + return conn.read(n) + + def write_func(data: bytes) -> int: + return conn.write(data) + + try: + if protocol in ("xmodem", "xmodem1k"): + from mcserial.xmodem import XModem + + xm = XModem(read_func, write_func, mode=protocol) + with open(filepath, "rb") as f: + result = xm.send(f) + result["protocol"] = protocol + result["file"] = str(filepath) + return result + + elif protocol == "ymodem": + from mcserial.ymodem import YModem + + ym = YModem(read_func, write_func) + result = ym.send([filepath]) + result["protocol"] = "ymodem" + return result + + elif protocol == "zmodem": + from mcserial.zmodem import ZModem + + zm = ZModem(read_func, write_func) + result = zm.send([filepath]) + result["protocol"] = "zmodem" + return result + + else: + return {"error": f"Unknown protocol: {protocol}", "success": False} + + except Exception as e: + return {"error": str(e), "success": False, "protocol": protocol} + + +@mcp.tool() +def file_transfer_receive( + port: str, + save_path: str, + protocol: Literal["xmodem", "ymodem", "zmodem"] = "zmodem", + overwrite: bool = False, +) -> dict: + """Receive a file over serial using X/Y/ZMODEM protocol. + + Works in both RS-232 and RS-485 modes. + + Protocols: + - xmodem: Must specify exact filename, no metadata from sender + - ymodem: Receives filename from sender, batch capable + - zmodem: Streaming, auto-resume capable [recommended] + + For XMODEM, save_path is the full file path. + For YMODEM/ZMODEM, save_path is a directory where files will be saved. + + Args: + port: Device path of the open serial port + save_path: File path (xmodem) or directory (ymodem/zmodem) + protocol: Transfer protocol to use (default: zmodem) + overwrite: Whether to overwrite existing files + + Returns: + Transfer statistics including bytes received and file paths + """ + from pathlib import Path + + if port not in _connections: + return {"error": f"Port {port} is not open", "success": False} + + conn = _connections[port].connection + + def read_func(n: int) -> bytes: + return conn.read(n) + + def write_func(data: bytes) -> int: + return conn.write(data) + + try: + if protocol == "xmodem": + from mcserial.xmodem import XModem + + filepath = Path(save_path) + if filepath.exists() and not overwrite: + return {"error": f"File exists: {save_path}", "success": False} + + filepath.parent.mkdir(parents=True, exist_ok=True) + + xm = XModem(read_func, write_func) + with open(filepath, "wb") as f: + result = xm.receive(f) + result["protocol"] = "xmodem" + result["file"] = str(filepath) + return result + + elif protocol == "ymodem": + from mcserial.ymodem import YModem + + directory = Path(save_path) + directory.mkdir(parents=True, exist_ok=True) + + ym = YModem(read_func, write_func) + result = ym.receive(directory, overwrite=overwrite) + result["protocol"] = "ymodem" + return result + + elif protocol == "zmodem": + from mcserial.zmodem import ZModem + + directory = Path(save_path) + directory.mkdir(parents=True, exist_ok=True) + + zm = ZModem(read_func, write_func) + result = zm.receive(directory, overwrite=overwrite) + result["protocol"] = "zmodem" + return result + + else: + return {"error": f"Unknown protocol: {protocol}", "success": False} + + except Exception as e: + return {"error": str(e), "success": False, "protocol": protocol} + + +@mcp.tool() +def file_transfer_send_batch( + port: str, + file_paths: list[str], + protocol: Literal["ymodem", "zmodem"] = "zmodem", +) -> dict: + """Send multiple files in a batch transfer. + + Only YMODEM and ZMODEM support batch transfers. + + Args: + port: Device path of the open serial port + file_paths: List of file paths to send + protocol: Transfer protocol (ymodem or zmodem) + + Returns: + Transfer statistics for all files + """ + from pathlib import Path + + if port not in _connections: + return {"error": f"Port {port} is not open", "success": False} + + if protocol not in ("ymodem", "zmodem"): + return {"error": "Batch transfer requires ymodem or zmodem", "success": False} + + # Validate all files exist + paths = [] + for fp in file_paths: + p = Path(fp) + if not p.exists(): + return {"error": f"File not found: {fp}", "success": False} + paths.append(p) + + conn = _connections[port].connection + + def read_func(n: int) -> bytes: + return conn.read(n) + + def write_func(data: bytes) -> int: + return conn.write(data) + + try: + if protocol == "ymodem": + from mcserial.ymodem import YModem + ym = YModem(read_func, write_func) + result = ym.send(paths) + else: + from mcserial.zmodem import ZModem + zm = ZModem(read_func, write_func) + result = zm.send(paths) + + result["protocol"] = protocol + return result + + except Exception as e: + return {"error": str(e), "success": False, "protocol": protocol} + + # ============================================================================ # RESOURCES - Dynamic data access via URIs # ============================================================================ @@ -1493,9 +1875,11 @@ def resource_port_status(port: str) -> str: return f"Port {port} is not open." try: - conn = _connections[port].connection + sc = _connections[port] + conn = sc.connection lines = [ f"# Serial Port Status: {port}", + f"- Mode: {sc.mode.upper()}", f"- Open: {conn.is_open}", f"- Baudrate: {conn.baudrate}", f"- Bytesize: {conn.bytesize}", diff --git a/src/mcserial/xmodem.py b/src/mcserial/xmodem.py new file mode 100644 index 0000000..d58e300 --- /dev/null +++ b/src/mcserial/xmodem.py @@ -0,0 +1,407 @@ +"""XMODEM file transfer protocol implementation. + +XMODEM is the simplest serial file transfer protocol: +- 128-byte blocks (XMODEM) or 1024-byte blocks (XMODEM-1K) +- Checksum or CRC-16 error detection +- Stop-and-wait: waits for ACK after each block + +Protocol flow: + Receiver sends NAK (checksum) or 'C' (CRC) to initiate + Sender transmits: SOH + block# + ~block# + 128 bytes + check + Receiver sends ACK or NAK + Repeat until EOT +""" + +from __future__ import annotations + +import logging +import time +from collections.abc import Callable +from typing import BinaryIO + +# Protocol constants +SOH = 0x01 # Start of 128-byte header +STX = 0x02 # Start of 1024-byte header (XMODEM-1K) +EOT = 0x04 # End of transmission +ACK = 0x06 # Acknowledge +NAK = 0x15 # Negative acknowledge +CAN = 0x18 # Cancel +CRC_MODE = 0x43 # 'C' - request CRC mode + +# Default parameters +DEFAULT_RETRY_LIMIT = 16 # Max retries per block +DEFAULT_TIMEOUT = 60.0 # Total transfer timeout in seconds +READ_TIMEOUT_RETRIES = 30 # Retries when waiting for response byte +INIT_TIMEOUT_RETRIES = 10 # Retries when waiting for transfer initiation + +logger = logging.getLogger(__name__) + + +def _calc_checksum(data: bytes) -> int: + """Calculate simple 8-bit checksum.""" + return sum(data) & 0xFF + + +def _calc_crc16(data: bytes) -> int: + """Calculate CRC-16-CCITT (XMODEM variant).""" + crc = 0 + for byte in data: + crc ^= byte << 8 + for _ in range(8): + if crc & 0x8000: + crc = (crc << 1) ^ 0x1021 + else: + crc <<= 1 + crc &= 0xFFFF + return crc + + +class XModemError(Exception): + """Base exception for XMODEM errors.""" + pass + + +class XModem: + """XMODEM file transfer protocol handler. + + Args: + read_func: Callable that reads n bytes from serial, returns bytes + write_func: Callable that writes bytes to serial + mode: "xmodem" (128-byte) or "xmodem1k" (1024-byte blocks) + use_crc: Use CRC-16 instead of checksum (default True) + """ + + def __init__( + self, + read_func: Callable[[int], bytes], + write_func: Callable[[bytes], int], + mode: str = "xmodem", + use_crc: bool = True, + ): + self.read = read_func + self.write = write_func + self.mode = mode + self.use_crc = use_crc + self.block_size = 1024 if mode == "xmodem1k" else 128 + + def _read_byte(self, timeout_retries: int = INIT_TIMEOUT_RETRIES) -> int | None: + """Read a single byte with retry. + + Args: + timeout_retries: Number of read attempts before returning None + + Returns: + Byte value (0-255) or None if no data available after retries + """ + for _ in range(timeout_retries): + data = self.read(1) + if data: + return data[0] + return None + + def _make_block(self, block_num: int, data: bytes) -> bytes: + """Create a complete XMODEM block with header, data, and checksum/CRC. + + Args: + block_num: Block sequence number (0-255, wraps) + data: Payload data (will be padded to block_size with SUB chars) + + Returns: + Complete block bytes ready for transmission + """ + # Pad data to block size with SUB (0x1A) - standard XMODEM padding + if len(data) < self.block_size: + data = data + bytes([0x1A] * (self.block_size - len(data))) + + header = STX if self.block_size == 1024 else SOH + block = bytes([header, block_num & 0xFF, (255 - block_num) & 0xFF]) + data + + if self.use_crc: + crc = _calc_crc16(data) + block += bytes([crc >> 8, crc & 0xFF]) + else: + block += bytes([_calc_checksum(data)]) + + return block + + def _verify_block(self, data: bytes, check_bytes: bytes) -> bool: + """Verify block integrity using checksum or CRC. + + Args: + data: The block payload to verify + check_bytes: Received checksum (1 byte) or CRC (2 bytes) + + Returns: + True if verification passes, False otherwise + """ + if self.use_crc: + expected = _calc_crc16(data) + received = (check_bytes[0] << 8) | check_bytes[1] + return expected == received + else: + expected = _calc_checksum(data) + return expected == check_bytes[0] + + def send( + self, + stream: BinaryIO, + callback: Callable[[int, int], None] | None = None, + retry_limit: int = DEFAULT_RETRY_LIMIT, + timeout: float = DEFAULT_TIMEOUT, + ) -> dict: + """Send a file via XMODEM. + + Args: + stream: File-like object to read from + callback: Progress callback(bytes_sent, total_bytes) + retry_limit: Max retries per block + timeout: Total timeout in seconds (enforced across entire transfer) + + Returns: + Dict with transfer statistics + """ + start_time = time.monotonic() + + # Get file size for progress + stream.seek(0, 2) # Seek to end + total_size = stream.tell() + stream.seek(0) # Seek back to start + + bytes_sent = 0 + block_num = 1 + errors = 0 + + # Wait for receiver to initiate + logger.debug("Waiting for receiver initiation...") + init_byte = None + for _ in range(retry_limit * 10): + if time.monotonic() - start_time > timeout: + return {"success": False, "error": f"Timeout ({timeout}s) waiting for receiver initiation"} + + b = self._read_byte(timeout_retries=3) + if b == CRC_MODE: + self.use_crc = True + init_byte = b + logger.debug("Receiver requested CRC mode") + break + elif b == NAK: + self.use_crc = False + init_byte = b + logger.debug("Receiver requested checksum mode") + break + elif b == CAN: + return {"success": False, "error": "Transfer cancelled by receiver"} + + if init_byte is None: + return {"success": False, "error": "Timeout waiting for receiver"} + + # Send blocks + while True: + # Check timeout + if time.monotonic() - start_time > timeout: + return {"success": False, "error": f"Timeout ({timeout}s) during transfer at block {block_num}"} + + data = stream.read(self.block_size) + if not data: + break + + block = self._make_block(block_num, data) + retries = 0 + + while retries < retry_limit: + self.write(block) + logger.debug(f"Sent block {block_num}, {len(data)} bytes") + + response = self._read_byte(timeout_retries=READ_TIMEOUT_RETRIES) + + if response == ACK: + bytes_sent += len(data) + if callback: + callback(bytes_sent, total_size) + block_num = (block_num + 1) & 0xFF + break + elif response == NAK: + retries += 1 + errors += 1 + logger.debug(f"Block {block_num} NAK'd, retry {retries}") + elif response == CAN: + return {"success": False, "error": "Transfer cancelled by receiver"} + else: + retries += 1 + errors += 1 + logger.debug(f"Block {block_num} no response, retry {retries}") + else: + return {"success": False, "error": f"Max retries exceeded at block {block_num}"} + + # Send EOT + for _ in range(retry_limit): + self.write(bytes([EOT])) + response = self._read_byte(timeout_retries=10) + if response == ACK: + break + elif response == NAK: + continue # Resend EOT + + return { + "success": True, + "bytes_sent": bytes_sent, + "blocks": block_num - 1, + "errors": errors, + "mode": "crc" if self.use_crc else "checksum", + } + + def receive( + self, + stream: BinaryIO, + callback: Callable[[int], None] | None = None, + retry_limit: int = DEFAULT_RETRY_LIMIT, + timeout: float = DEFAULT_TIMEOUT, + ) -> dict: + """Receive a file via XMODEM. + + Args: + stream: File-like object to write to + callback: Progress callback(bytes_received) + retry_limit: Max retries per block + timeout: Total timeout in seconds (enforced across entire transfer) + + Returns: + Dict with transfer statistics + """ + start_time = time.monotonic() + bytes_received = 0 + expected_block = 1 + errors = 0 + + # Initiate transfer + init_char = CRC_MODE if self.use_crc else NAK + logger.debug(f"Initiating transfer with {'CRC' if self.use_crc else 'checksum'} mode") + + for attempt in range(retry_limit): + if time.monotonic() - start_time > timeout: + return {"success": False, "error": f"Timeout ({timeout}s) waiting for sender"} + + self.write(bytes([init_char])) + + # Wait for first byte + header = self._read_byte(timeout_retries=READ_TIMEOUT_RETRIES) + if header in (SOH, STX): + break + elif header == CAN: + return {"success": False, "error": "Transfer cancelled by sender"} + + # Fallback to checksum if CRC not supported + if attempt == 3 and self.use_crc: + logger.debug("CRC mode not responding, trying checksum") + self.use_crc = False + init_char = NAK + else: + return {"success": False, "error": "Timeout waiting for sender"} + + # Receive blocks + while True: + # Check timeout + if time.monotonic() - start_time > timeout: + return {"success": False, "error": f"Timeout ({timeout}s) during receive at block {expected_block}"} + + if header == EOT: + self.write(bytes([ACK])) + break + + # Determine block size from header + block_size = 1024 if header == STX else 128 + check_size = 2 if self.use_crc else 1 + + # Read block number + block_num = self._read_byte() + block_num_comp = self._read_byte() + + if block_num is None or block_num_comp is None: + errors += 1 + self.write(bytes([NAK])) + header = self._read_byte(timeout_retries=READ_TIMEOUT_RETRIES) + continue + + # Verify block number complement + if (block_num + block_num_comp) & 0xFF != 0xFF: + logger.debug(f"Block number mismatch: {block_num} vs {block_num_comp}") + errors += 1 + self.write(bytes([NAK])) + header = self._read_byte(timeout_retries=READ_TIMEOUT_RETRIES) + continue + + # Read data + data = self.read(block_size) + if len(data) != block_size: + logger.debug(f"Short block: {len(data)} bytes") + errors += 1 + self.write(bytes([NAK])) + header = self._read_byte(timeout_retries=READ_TIMEOUT_RETRIES) + continue + + # Read and verify check bytes + check_bytes = self.read(check_size) + if len(check_bytes) != check_size: + errors += 1 + self.write(bytes([NAK])) + header = self._read_byte(timeout_retries=READ_TIMEOUT_RETRIES) + continue + + if not self._verify_block(data, check_bytes): + logger.debug(f"Block {block_num} checksum/CRC error") + errors += 1 + self.write(bytes([NAK])) + header = self._read_byte(timeout_retries=READ_TIMEOUT_RETRIES) + continue + + # Check sequence + if block_num == expected_block: + stream.write(data) + bytes_received += len(data) + expected_block = (expected_block + 1) & 0xFF + if callback: + callback(bytes_received) + elif block_num == (expected_block - 1) & 0xFF: + # Duplicate block, already ACK'd + logger.debug(f"Duplicate block {block_num}") + else: + logger.debug(f"Out of sequence: expected {expected_block}, got {block_num}") + errors += 1 + self.write(bytes([NAK])) + header = self._read_byte(timeout_retries=READ_TIMEOUT_RETRIES) + continue + + self.write(bytes([ACK])) + header = self._read_byte(timeout_retries=READ_TIMEOUT_RETRIES) + + return { + "success": True, + "bytes_received": bytes_received, + "blocks": expected_block - 1, + "errors": errors, + "mode": "crc" if self.use_crc else "checksum", + } + + +def send_xmodem( + read_func: Callable[[int], bytes], + write_func: Callable[[bytes], int], + stream: BinaryIO, + mode: str = "xmodem", + callback: Callable[[int, int], None] | None = None, +) -> dict: + """Convenience function to send a file via XMODEM.""" + xm = XModem(read_func, write_func, mode=mode) + return xm.send(stream, callback) + + +def receive_xmodem( + read_func: Callable[[int], bytes], + write_func: Callable[[bytes], int], + stream: BinaryIO, + mode: str = "xmodem", + callback: Callable[[int], None] | None = None, +) -> dict: + """Convenience function to receive a file via XMODEM.""" + xm = XModem(read_func, write_func, mode=mode) + return xm.receive(stream, callback) diff --git a/src/mcserial/ymodem.py b/src/mcserial/ymodem.py new file mode 100644 index 0000000..78d007b --- /dev/null +++ b/src/mcserial/ymodem.py @@ -0,0 +1,542 @@ +"""YMODEM file transfer protocol implementation. + +YMODEM extends XMODEM-1K with: +- Batch transfers (multiple files in one session) +- File metadata in block 0 (filename, size, modification time) +- CRC-16 required (no checksum mode) + +Protocol flow: + Receiver sends 'C' to initiate + Sender sends block 0: filename + size + mtime (null-terminated strings) + Receiver ACKs, then sends 'C' again for data + Sender transmits data blocks (1024 bytes, XMODEM-1K style) + Sender sends EOT, receiver NAKs, sender sends EOT again, receiver ACKs + For batch: repeat with next file, or send empty block 0 to end session +""" + +from __future__ import annotations + +import contextlib +import logging +import os +import time +from collections.abc import Callable +from pathlib import Path + +from mcserial.xmodem import ( + ACK, + CAN, + CRC_MODE, + EOT, + NAK, + SOH, + STX, + XModemError, + _calc_crc16, +) + +logger = logging.getLogger(__name__) + +# Transfer limits +DEFAULT_MAX_TRANSFER_SIZE = 100 * 1024 * 1024 # 100MB default limit per file + + +def _sanitize_filename(filename: str) -> str: + """Remove path traversal attempts and dangerous characters from filename. + + Security: Prevents directory traversal attacks where malicious senders + could write files outside the target directory using names like + '../../../etc/passwd' or absolute paths like '/etc/cron.d/backdoor'. + """ + # Get just the basename, removing any directory components + name = Path(filename).name + + # Reject empty names + if not name: + name = "unnamed_file" + + # Prefix hidden files (starting with dot) to make them visible + if name.startswith("."): + name = "_" + name[1:] + + # Replace any remaining problematic characters + name = name.replace("\x00", "_").replace("/", "_").replace("\\", "_") + + return name + + +def _open_file_atomic(filepath: Path, overwrite: bool) -> tuple: + """Open file for writing with atomic creation to prevent TOCTOU races. + + Uses O_CREAT | O_EXCL to atomically fail if file exists (when overwrite=False), + preventing race conditions between existence check and file creation. + + Returns: + Tuple of (file_object, None) on success, or (None, error_message) on failure + """ + if overwrite: + # Overwrite mode: just open normally + return open(filepath, "wb"), None + + try: + # Atomic create: fails if file exists (O_EXCL) + fd = os.open(filepath, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644) + return os.fdopen(fd, "wb"), None + except FileExistsError: + return None, "File exists" + except OSError as e: + return None, str(e) + + +class YModemError(XModemError): + """YMODEM-specific error.""" + pass + + +class YModem: + """YMODEM batch file transfer protocol handler. + + Args: + read_func: Callable that reads n bytes from serial, returns bytes + write_func: Callable that writes bytes to serial + """ + + def __init__( + self, + read_func: Callable[[int], bytes], + write_func: Callable[[bytes], int], + ): + self.read = read_func + self.write = write_func + + def _read_byte(self, timeout_retries: int = 10) -> int | None: + """Read a single byte with retry.""" + for _ in range(timeout_retries): + data = self.read(1) + if data: + return data[0] + return None + + def _make_block(self, block_num: int, data: bytes, block_size: int = 1024) -> bytes: + """Create a YMODEM block with CRC-16.""" + # Pad data to block size + if len(data) < block_size: + data = data + bytes(block_size - len(data)) + + header = STX if block_size == 1024 else SOH + block = bytes([header, block_num & 0xFF, (255 - block_num) & 0xFF]) + data + + crc = _calc_crc16(data) + block += bytes([crc >> 8, crc & 0xFF]) + + return block + + def _make_block0(self, filename: str, filesize: int, mtime: int | None = None) -> bytes: + """Create YMODEM block 0 with file metadata. + + Block 0 format: filename\0size mtime\0 (space-separated, octal for time) + """ + # Build metadata string + if mtime is not None: + meta = f"{filename}\x00{filesize} {mtime:o}" + else: + meta = f"{filename}\x00{filesize}" + + data = meta.encode("latin-1") + return data + + def _parse_block0(self, data: bytes) -> tuple[dict | None, str]: + """Parse YMODEM block 0 metadata. + + Returns: + Tuple of (metadata_dict, status) where: + - (dict, "ok"): Successfully parsed file metadata + - (None, "end_of_batch"): Empty block 0, signals end of batch transfer + - (None, "parse_error"): Failed to parse block 0 data + """ + # Find null terminator after filename + try: + null_pos = data.index(0) + filename = data[:null_pos].decode("latin-1").strip() + + if not filename: + return None, "end_of_batch" + + # Parse size and optional mtime + rest = data[null_pos + 1:].split(b" ") + rest = [x for x in rest if x and x != b"\x00"] + + filesize = int(rest[0]) if rest else 0 + mtime = int(rest[1], 8) if len(rest) > 1 else None + + return { + "filename": filename, + "size": filesize, + "mtime": mtime, + }, "ok" + except (ValueError, IndexError): + return None, "parse_error" + + def send( + self, + files: list[str | Path], + callback: Callable[[str, int, int], None] | None = None, + retry_limit: int = 16, + ) -> dict: + """Send files via YMODEM batch transfer. + + Args: + files: List of file paths to send + callback: Progress callback(filename, bytes_sent, total_bytes) + retry_limit: Max retries per block + + Returns: + Dict with transfer statistics + """ + results = [] + total_bytes = 0 + total_errors = 0 + + for filepath in files: + filepath = Path(filepath) + if not filepath.exists(): + results.append({"file": str(filepath), "error": "File not found"}) + continue + + filesize = filepath.stat().st_size + mtime = int(filepath.stat().st_mtime) + + # Wait for receiver 'C' + logger.debug(f"Waiting for receiver to initiate {filepath.name}...") + for _ in range(retry_limit * 10): + b = self._read_byte(timeout_retries=3) + if b == CRC_MODE: + break + elif b == CAN: + return {"success": False, "error": "Transfer cancelled", "files": results} + else: + return {"success": False, "error": "Timeout waiting for receiver", "files": results} + + # Send block 0 with metadata + block0_data = self._make_block0(filepath.name, filesize, mtime) + block0 = self._make_block(0, block0_data, block_size=128) + + retries = 0 + while retries < retry_limit: + self.write(block0) + response = self._read_byte(timeout_retries=30) + if response == ACK: + break + elif response == CAN: + return {"success": False, "error": "Transfer cancelled", "files": results} + retries += 1 + else: + results.append({"file": str(filepath), "error": "Block 0 not acknowledged"}) + continue + + # Wait for second 'C' to start data + for _ in range(retry_limit * 5): + b = self._read_byte(timeout_retries=3) + if b == CRC_MODE: + break + else: + results.append({"file": str(filepath), "error": "No data initiation"}) + continue + + # Send file data + bytes_sent = 0 + block_num = 1 + errors = 0 + + with open(filepath, "rb") as f: + while True: + data = f.read(1024) + if not data: + break + + block = self._make_block(block_num, data) + retries = 0 + + while retries < retry_limit: + self.write(block) + response = self._read_byte(timeout_retries=30) + + if response == ACK: + bytes_sent += len(data) + if callback: + callback(filepath.name, bytes_sent, filesize) + block_num = (block_num + 1) & 0xFF + break + elif response == CAN: + results.append({"file": str(filepath), "error": "Cancelled"}) + break + else: + retries += 1 + errors += 1 + else: + results.append({"file": str(filepath), "error": f"Max retries at block {block_num}"}) + break + + # Send EOT sequence (NAK then ACK expected) + for _ in range(retry_limit): + self.write(bytes([EOT])) + response = self._read_byte(timeout_retries=10) + if response == NAK: + self.write(bytes([EOT])) + response = self._read_byte(timeout_retries=10) + if response == ACK: + break + elif response == ACK: + break + + results.append({ + "file": str(filepath), + "bytes_sent": bytes_sent, + "blocks": block_num - 1, + "errors": errors, + "success": True, + }) + total_bytes += bytes_sent + total_errors += errors + + # Send empty block 0 to end batch + for _ in range(retry_limit * 5): + b = self._read_byte(timeout_retries=3) + if b == CRC_MODE: + break + + empty_block0 = self._make_block(0, b"", block_size=128) + self.write(empty_block0) + self._read_byte(timeout_retries=10) # ACK + + return { + "success": all(r.get("success", False) for r in results), + "files": results, + "total_bytes": total_bytes, + "total_errors": total_errors, + } + + def receive( + self, + directory: str | Path, + callback: Callable[[str, int, int], None] | None = None, + retry_limit: int = 16, + overwrite: bool = False, + max_transfer_size: int = DEFAULT_MAX_TRANSFER_SIZE, + ) -> dict: + """Receive files via YMODEM batch transfer. + + Args: + directory: Directory to save received files + callback: Progress callback(filename, bytes_received, total_bytes) + retry_limit: Max retries per block + overwrite: Overwrite existing files + max_transfer_size: Maximum bytes to receive per file (default 100MB). + Set to 0 to disable limit. Prevents unbounded memory usage. + + Returns: + Dict with transfer statistics + """ + directory = Path(directory) + directory.mkdir(parents=True, exist_ok=True) + + results = [] + total_bytes = 0 + total_errors = 0 + + while True: + # Initiate with 'C' for CRC mode + logger.debug("Initiating YMODEM receive...") + for _attempt in range(retry_limit): + self.write(bytes([CRC_MODE])) + header = self._read_byte(timeout_retries=30) + if header in (SOH, STX): + break + elif header == CAN: + return {"success": False, "error": "Cancelled", "files": results} + else: + return {"success": False, "error": "Timeout", "files": results} + + # Receive block 0 + block_size = 1024 if header == STX else 128 + block_num = self._read_byte() + block_num_comp = self._read_byte() + + if block_num != 0: + self.write(bytes([NAK])) + continue + + data = self.read(block_size) + crc_bytes = self.read(2) + + # Verify CRC + expected_crc = _calc_crc16(data) + received_crc = (crc_bytes[0] << 8) | crc_bytes[1] + if expected_crc != received_crc: + self.write(bytes([NAK])) + continue + + # Parse metadata + meta, status = self._parse_block0(data) + if status == "end_of_batch": + self.write(bytes([ACK])) + break + elif status == "parse_error": + logger.debug("Failed to parse block 0 metadata") + self.write(bytes([NAK])) + continue + + filename = meta["filename"] + filesize = meta["size"] + logger.debug(f"Receiving: {filename} ({filesize} bytes)") + + # Security: sanitize filename to prevent path traversal attacks + safe_filename = _sanitize_filename(filename) + if safe_filename != filename: + logger.warning(f"Sanitized filename: {filename!r} -> {safe_filename!r}") + + filepath = directory / safe_filename + + # Atomic file creation to prevent TOCTOU race conditions + f, file_error = _open_file_atomic(filepath, overwrite) + if file_error: + results.append({"file": filename, "error": file_error}) + self.write(bytes([CAN, CAN])) + continue + + self.write(bytes([ACK])) + + # Send 'C' to start data transfer + self.write(bytes([CRC_MODE])) + + # Receive data blocks + bytes_received = 0 + expected_block = 1 + errors = 0 + transfer_aborted = False + + try: + while bytes_received < filesize and not transfer_aborted: + header = self._read_byte(timeout_retries=60) + + if header == EOT: + self.write(bytes([NAK])) + header = self._read_byte(timeout_retries=10) + if header == EOT: + self.write(bytes([ACK])) + break + continue + + if header not in (SOH, STX): + errors += 1 + self.write(bytes([NAK])) + continue + + block_size = 1024 if header == STX else 128 + block_num = self._read_byte() + block_num_comp = self._read_byte() + + if (block_num + block_num_comp) & 0xFF != 0xFF: + errors += 1 + self.write(bytes([NAK])) + continue + + data = self.read(block_size) + crc_bytes = self.read(2) + + if len(data) != block_size or len(crc_bytes) != 2: + errors += 1 + self.write(bytes([NAK])) + continue + + expected_crc = _calc_crc16(data) + received_crc = (crc_bytes[0] << 8) | crc_bytes[1] + if expected_crc != received_crc: + errors += 1 + self.write(bytes([NAK])) + continue + + if block_num == expected_block: + # Trim last block to actual file size + remaining = filesize - bytes_received + if remaining < block_size: + data = data[:remaining] + + f.write(data) + bytes_received += len(data) + expected_block = (expected_block + 1) & 0xFF + + # Check transfer size limit to prevent unbounded memory usage + if max_transfer_size > 0 and bytes_received > max_transfer_size: + logger.warning( + f"Transfer aborted: {filename} exceeded {max_transfer_size} byte limit " + f"(received {bytes_received} bytes)" + ) + self.write(bytes([CAN, CAN])) + transfer_aborted = True + break + + if callback: + callback(filename, bytes_received, filesize) + + self.write(bytes([ACK])) + finally: + f.close() + + if transfer_aborted: + # Transfer was aborted due to size limit + results.append({ + "file": filename, + "path": str(filepath), + "error": f"Transfer size exceeded {max_transfer_size} byte limit", + "bytes_received": bytes_received, + "success": False, + }) + # Try to clean up partial file + with contextlib.suppress(OSError): + filepath.unlink() + continue + + # Set modification time if provided + if meta.get("mtime"): + os.utime(filepath, (time.time(), meta["mtime"])) + + results.append({ + "file": filename, + "path": str(filepath), + "bytes_received": bytes_received, + "errors": errors, + "success": True, + }) + total_bytes += bytes_received + total_errors += errors + + return { + "success": all(r.get("success", False) for r in results), + "files": results, + "total_bytes": total_bytes, + "total_errors": total_errors, + } + + +def send_ymodem( + read_func: Callable[[int], bytes], + write_func: Callable[[bytes], int], + files: list[str | Path], + callback: Callable[[str, int, int], None] | None = None, +) -> dict: + """Convenience function to send files via YMODEM.""" + ym = YModem(read_func, write_func) + return ym.send(files, callback) + + +def receive_ymodem( + read_func: Callable[[int], bytes], + write_func: Callable[[bytes], int], + directory: str | Path, + callback: Callable[[str, int, int], None] | None = None, + overwrite: bool = False, +) -> dict: + """Convenience function to receive files via YMODEM.""" + ym = YModem(read_func, write_func) + return ym.receive(directory, callback, overwrite=overwrite) diff --git a/src/mcserial/zmodem.py b/src/mcserial/zmodem.py new file mode 100644 index 0000000..124fc03 --- /dev/null +++ b/src/mcserial/zmodem.py @@ -0,0 +1,815 @@ +"""ZMODEM file transfer protocol implementation. + +ZMODEM is the most sophisticated serial file transfer protocol: +- Streaming with selective retransmission (no stop-and-wait) +- CRC-16 or CRC-32 error detection +- Crash recovery (resume interrupted transfers) +- Auto-start capability +- Escape sequence encoding for 8-bit transparency + +Frame structure: + ZPAD ZPAD ZDLE frame_type [4 bytes header data] [CRC] + +Data subpacket: + [escaped data] ZDLE frame_end_type [CRC] +""" + +from __future__ import annotations + +import contextlib +import logging +import os +import time +from collections.abc import Callable +from pathlib import Path + +logger = logging.getLogger(__name__) + + +def _sanitize_filename(filename: str) -> str: + """Remove path traversal attempts and dangerous characters from filename. + + Security: Prevents directory traversal attacks where malicious senders + could write files outside the target directory. + """ + name = Path(filename).name + if not name: + name = "unnamed_file" + if name.startswith("."): + name = "_" + name[1:] + name = name.replace("\x00", "_").replace("/", "_").replace("\\", "_") + return name + + +def _open_file_atomic(filepath: Path, overwrite: bool) -> tuple: + """Open file for writing with atomic creation to prevent TOCTOU races. + + Uses O_CREAT | O_EXCL to atomically fail if file exists (when overwrite=False), + preventing race conditions between existence check and file creation. + + Returns: + Tuple of (file_object, None) on success, or (None, error_message) on failure + """ + if overwrite: + return open(filepath, "wb"), None + + try: + fd = os.open(filepath, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644) + return os.fdopen(fd, "wb"), None + except FileExistsError: + return None, "File exists" + except OSError as e: + return None, str(e) + + +# Protocol constants +ZPAD = 0x2A # '*' - Padding character + +# Transfer limits +DEFAULT_MAX_TRANSFER_SIZE = 100 * 1024 * 1024 # 100MB default limit per file +MAX_SUBPACKET_SIZE = 8192 # Per-packet size limit (sanity check) +ZDLE = 0x18 # Data Link Escape +ZDLEE = 0x58 # Escaped ZDLE (ZDLE ^ 0x40) + +# Frame types +ZBIN = 0x41 # 'A' - Binary header, CRC-16 +ZHEX = 0x42 # 'B' - Hex header, CRC-16 +ZBIN32 = 0x43 # 'C' - Binary header, CRC-32 + +# Header types +ZRQINIT = 0 # Request receive init +ZRINIT = 1 # Receive init +ZSINIT = 2 # Send init sequence +ZACK = 3 # ACK +ZFILE = 4 # File name/info +ZSKIP = 5 # Skip this file +ZNAK = 6 # Last packet was garbled +ZABORT = 7 # Abort batch transfers +ZFIN = 8 # Finish session +ZRPOS = 9 # Resume at position +ZDATA = 10 # Data packet follows +ZEOF = 11 # End of file +ZFERR = 12 # Fatal error +ZCRC = 13 # Request file CRC +ZCHALLENGE = 14 # Challenge +ZCOMPL = 15 # Request complete +ZCAN = 16 # Cancel (5 CANs) +ZFREECNT = 17 # Request free bytes +ZCOMMAND = 18 # Execute command +ZSTDERR = 19 # Output to stderr + +# Data subpacket end types +ZCRCE = 0x68 # 'h' - CRC next, end, no ACK +ZCRCG = 0x69 # 'i' - CRC next, not end, no ACK +ZCRCQ = 0x6A # 'j' - CRC next, not end, ACK requested +ZCRCW = 0x6B # 'k' - CRC next, end, ACK requested + +# Special characters to escape +ESCAPE_CHARS = {0x10, 0x11, 0x13, 0x90, 0x91, 0x93, ZDLE, 0x0D, 0x8D} + +# CRC-32 lookup table - initialized at module load for thread-safety +def _build_crc32_table() -> list[int]: + """Build CRC-32 lookup table (called once at module load).""" + table = [] + for i in range(256): + crc = i + for _ in range(8): + if crc & 1: + crc = (crc >> 1) ^ 0xEDB88320 + else: + crc >>= 1 + table.append(crc) + return table + + +_CRC32_TABLE: list[int] = _build_crc32_table() + + +def _calc_crc16(data: bytes) -> int: + """Calculate CRC-16-CCITT.""" + crc = 0 + for byte in data: + crc ^= byte << 8 + for _ in range(8): + if crc & 0x8000: + crc = (crc << 1) ^ 0x1021 + else: + crc <<= 1 + crc &= 0xFFFF + return crc + + +def _calc_crc32(data: bytes) -> int: + """Calculate CRC-32 using pre-computed lookup table.""" + crc = 0xFFFFFFFF + for byte in data: + crc = _CRC32_TABLE[(crc ^ byte) & 0xFF] ^ (crc >> 8) + return crc ^ 0xFFFFFFFF + + +def _escape_byte(b: int) -> bytes: + """Escape a byte if needed for ZMODEM transmission.""" + if b == ZDLE: + return bytes([ZDLE, ZDLEE]) + elif b in ESCAPE_CHARS: + return bytes([ZDLE, b ^ 0x40]) + else: + return bytes([b]) + + +def _escape_data(data: bytes) -> bytes: + """Escape all bytes in data that need escaping.""" + result = bytearray() + for b in data: + result.extend(_escape_byte(b)) + return bytes(result) + + +def _to_hex(value: int, digits: int = 2) -> bytes: + """Convert value to hex string bytes.""" + return f"{value:0{digits}x}".encode("ascii") + + +class ZModemError(Exception): + """ZMODEM protocol error.""" + pass + + +class ZModem: + """ZMODEM file transfer protocol handler. + + Args: + read_func: Callable that reads n bytes from serial + write_func: Callable that writes bytes to serial + use_crc32: Use CRC-32 instead of CRC-16 (default True) + """ + + def __init__( + self, + read_func: Callable[[int], bytes], + write_func: Callable[[bytes], int], + use_crc32: bool = True, + ): + self.read = read_func + self.write = write_func + self.use_crc32 = use_crc32 + self.last_sync_pos = 0 + self.tx_buffer_size = 1024 + self.rx_buffer_size = 0 + + def _read_byte(self, timeout_retries: int = 10) -> int | None: + """Read a single byte with retry.""" + for _ in range(timeout_retries): + data = self.read(1) + if data: + return data[0] + return None + + def _read_zdle_byte(self) -> int | None: + """Read a byte, handling ZDLE escaping.""" + b = self._read_byte(timeout_retries=30) + if b is None: + return None + if b == ZDLE: + b = self._read_byte(timeout_retries=30) + if b is None: + return None + if b == ZDLEE: + return ZDLE + elif b in (ZCRCE, ZCRCG, ZCRCQ, ZCRCW): + return b | 0x100 # Flag as frame end + else: + return b ^ 0x40 + return b + + def _send_cancel(self) -> None: + """Send ZMODEM cancel sequence. + + ZMODEM uses 8 CAN bytes followed by 8 backspaces to abort transfer. + This is the proper way to cancel - just sending ZCAN header may not + be recognized by all implementations. + + Note: CAN (Cancel) and ZDLE share the same byte value 0x18. In ZMODEM, + ZDLE is the escape character, but when sent 5+ times consecutively + outside of frame context, it signals abort (CAN sequence). + """ + # CAN = 0x18 (same as ZDLE) - 8 consecutive cancels + 8 backspaces + cancel_seq = bytes([0x18] * 8 + [0x08] * 8) + self.write(cancel_seq) + + def _make_hex_header(self, frame_type: int, data: bytes = b"\x00\x00\x00\x00") -> bytes: + """Create a hex-encoded ZMODEM header.""" + header = bytes([frame_type]) + data[:4].ljust(4, b"\x00") + crc = _calc_crc16(header) + + result = bytearray([ZPAD, ZPAD, ZDLE, ZHEX]) + for b in header: + result.extend(_to_hex(b)) + result.extend(_to_hex(crc >> 8)) + result.extend(_to_hex(crc & 0xFF)) + result.extend(b"\r\n") + + return bytes(result) + + def _make_bin_header(self, frame_type: int, data: bytes = b"\x00\x00\x00\x00") -> bytes: + """Create a binary ZMODEM header.""" + header = bytes([frame_type]) + data[:4].ljust(4, b"\x00") + + if self.use_crc32: + crc = _calc_crc32(header) + result = bytearray([ZPAD, ZDLE, ZBIN32]) + result.extend(_escape_data(header)) + crc_bytes = crc.to_bytes(4, "little") + result.extend(_escape_data(crc_bytes)) + else: + crc = _calc_crc16(header) + result = bytearray([ZPAD, ZDLE, ZBIN]) + result.extend(_escape_data(header)) + result.extend(_escape_data(bytes([crc >> 8, crc & 0xFF]))) + + return bytes(result) + + def _make_data_subpacket(self, data: bytes, end_type: int) -> bytes: + """Create a data subpacket with CRC.""" + result = bytearray(_escape_data(data)) + result.extend([ZDLE, end_type]) + + if self.use_crc32: + crc = _calc_crc32(data + bytes([end_type])) + crc_bytes = crc.to_bytes(4, "little") + result.extend(_escape_data(crc_bytes)) + else: + crc = _calc_crc16(data + bytes([end_type])) + result.extend(_escape_data(bytes([crc >> 8, crc & 0xFF]))) + + return bytes(result) + + def _read_hex_header(self) -> tuple[int, bytes] | None: + """Read and parse a hex-encoded header.""" + # Read hex digits: type(2) + data(8) + crc(4) = 14 hex chars + hex_data = self.read(14) + if len(hex_data) != 14: + return None + + try: + raw = bytes.fromhex(hex_data.decode("ascii")) + except (ValueError, UnicodeDecodeError): + return None + + frame_type = raw[0] + data = raw[1:5] + recv_crc = (raw[5] << 8) | raw[6] + + calc_crc = _calc_crc16(raw[:5]) + if calc_crc != recv_crc: + logger.debug(f"Hex header CRC mismatch: {calc_crc:04x} vs {recv_crc:04x}") + return None + + # Read trailing CR/LF + self.read(2) + + return frame_type, data + + def _read_bin_header(self, use_crc32: bool) -> tuple[int, bytes] | None: + """Read and parse a binary header.""" + # Read 5 bytes: type + 4 data bytes + raw = bytearray() + for _ in range(5): + b = self._read_zdle_byte() + if b is None: + return None + raw.append(b & 0xFF) + + frame_type = raw[0] + data = bytes(raw[1:5]) + + # Read CRC + crc_len = 4 if use_crc32 else 2 + crc_bytes = bytearray() + for _ in range(crc_len): + b = self._read_zdle_byte() + if b is None: + return None + crc_bytes.append(b & 0xFF) + + # Verify CRC + if use_crc32: + recv_crc = int.from_bytes(crc_bytes, "little") + calc_crc = _calc_crc32(bytes(raw)) + else: + recv_crc = (crc_bytes[0] << 8) | crc_bytes[1] + calc_crc = _calc_crc16(bytes(raw)) + + if calc_crc != recv_crc: + logger.debug("Binary header CRC mismatch") + return None + + return frame_type, data + + def _read_header(self) -> tuple[int, bytes] | None: + """Wait for and read any ZMODEM header.""" + # Look for ZPAD ZPAD ZDLE or ZPAD ZDLE + sync_count = 0 + + for _ in range(1000): + b = self._read_byte(timeout_retries=10) + if b is None: + continue + + if b == ZPAD: + sync_count += 1 + elif b == ZDLE and sync_count >= 1: + # Found sync, read frame type + frame_marker = self._read_byte(timeout_retries=10) + if frame_marker == ZHEX: + return self._read_hex_header() + elif frame_marker == ZBIN: + return self._read_bin_header(use_crc32=False) + elif frame_marker == ZBIN32: + return self._read_bin_header(use_crc32=True) + sync_count = 0 + else: + sync_count = 0 + + return None + + def _read_data_subpacket(self) -> tuple[bytes, int] | None: + """Read a data subpacket.""" + data = bytearray() + + while True: + b = self._read_zdle_byte() + if b is None: + return None + + if b & 0x100: # Frame end marker + end_type = b & 0xFF + break + + data.append(b) + if len(data) > MAX_SUBPACKET_SIZE: + logger.debug(f"Subpacket exceeded {MAX_SUBPACKET_SIZE} bytes limit") + return None + + # Read and verify CRC + crc_len = 4 if self.use_crc32 else 2 + crc_bytes = bytearray() + for _ in range(crc_len): + b = self._read_zdle_byte() + if b is None: + return None + crc_bytes.append(b & 0xFF) + + # Verify CRC + check_data = bytes(data) + bytes([end_type]) + if self.use_crc32: + recv_crc = int.from_bytes(crc_bytes, "little") + calc_crc = _calc_crc32(check_data) + else: + recv_crc = (crc_bytes[0] << 8) | crc_bytes[1] + calc_crc = _calc_crc16(check_data) + + if calc_crc != recv_crc: + logger.debug("Data subpacket CRC error") + return None + + return bytes(data), end_type + + def _pos_to_bytes(self, pos: int) -> bytes: + """Convert position to 4-byte little-endian. + + Raises: + OverflowError: If position exceeds 4GB (ZMODEM protocol limit) + """ + try: + return pos.to_bytes(4, "little") + except OverflowError: + raise OverflowError( + f"File position {pos} exceeds ZMODEM's 4GB limit (max 4,294,967,295 bytes). " + "ZMODEM uses 32-bit position encoding and cannot handle files larger than 4GB." + ) from None + + def _bytes_to_pos(self, data: bytes) -> int: + """Convert 4-byte little-endian to position.""" + return int.from_bytes(data[:4], "little") + + def send( + self, + files: list[str | Path], + callback: Callable[[str, int, int], None] | None = None, + retry_limit: int = 10, + ) -> dict: + """Send files via ZMODEM. + + Args: + files: List of file paths to send + callback: Progress callback(filename, bytes_sent, total_bytes) + retry_limit: Max retries for errors + + Returns: + Dict with transfer statistics + """ + results = [] + total_bytes = 0 + + # Send ZRQINIT to request receiver init + logger.debug("Sending ZRQINIT...") + self.write(self._make_hex_header(ZRQINIT)) + + # Wait for ZRINIT from receiver + for _ in range(retry_limit * 3): + header = self._read_header() + if header is None: + self.write(self._make_hex_header(ZRQINIT)) + continue + + frame_type, data = header + if frame_type == ZRINIT: + self.rx_buffer_size = self._bytes_to_pos(data) + logger.debug(f"Received ZRINIT, buffer={self.rx_buffer_size}") + break + elif frame_type == ZCAN: + return {"success": False, "error": "Cancelled by receiver", "files": results} + else: + return {"success": False, "error": "No response from receiver", "files": results} + + # Send each file + for filepath in files: + filepath = Path(filepath) + if not filepath.exists(): + results.append({"file": str(filepath), "error": "File not found"}) + continue + + filesize = filepath.stat().st_size + mtime = int(filepath.stat().st_mtime) + + # Send ZFILE with filename info + file_info = f"{filepath.name}\x00{filesize} {mtime:o} 0 0 0 0\x00".encode("latin-1") + + self.write(self._make_bin_header(ZFILE)) + self.write(self._make_data_subpacket(file_info, ZCRCW)) + + # Wait for ZRPOS or ZSKIP + start_pos = 0 + for _ in range(retry_limit): + header = self._read_header() + if header is None: + continue + + frame_type, data = header + if frame_type == ZRPOS: + start_pos = self._bytes_to_pos(data) + logger.debug(f"Receiver wants to start at {start_pos}") + break + elif frame_type == ZSKIP: + logger.debug(f"Receiver skipping {filepath.name}") + results.append({"file": str(filepath), "skipped": True}) + break + elif frame_type == ZCAN: + return {"success": False, "error": "Cancelled", "files": results} + else: + results.append({"file": str(filepath), "error": "No ZRPOS received"}) + continue + + if frame_type == ZSKIP: + continue + + # Send file data + bytes_sent = start_pos + errors = 0 + + with open(filepath, "rb") as f: + f.seek(start_pos) + + # Send ZDATA header with position + self.write(self._make_bin_header(ZDATA, self._pos_to_bytes(bytes_sent))) + + while bytes_sent < filesize: + chunk = f.read(min(self.tx_buffer_size, filesize - bytes_sent)) + if not chunk: + break + + # ZCRCE = end of file, ZCRCG = more data coming + end_type = ZCRCE if bytes_sent + len(chunk) >= filesize else ZCRCG + + self.write(self._make_data_subpacket(chunk, end_type)) + bytes_sent += len(chunk) + + if callback: + callback(filepath.name, bytes_sent, filesize) + + # Check for ZACK or ZRPOS occasionally + if end_type == ZCRCE or bytes_sent % (self.tx_buffer_size * 10) == 0: + header = self._read_header() + if header: + htype, hdata = header + if htype == ZRPOS: + # Receiver wants us to resend from position + new_pos = self._bytes_to_pos(hdata) + logger.debug(f"ZRPOS received, resending from {new_pos}") + f.seek(new_pos) + bytes_sent = new_pos + errors += 1 + self.write(self._make_bin_header(ZDATA, self._pos_to_bytes(bytes_sent))) + elif htype == ZCAN: + return {"success": False, "error": "Cancelled", "files": results} + + # Send ZEOF + self.write(self._make_bin_header(ZEOF, self._pos_to_bytes(bytes_sent))) + + # Wait for ZRINIT (ready for next file) + for _ in range(retry_limit): + header = self._read_header() + if header and header[0] == ZRINIT: + break + + results.append({ + "file": str(filepath), + "bytes_sent": bytes_sent, + "errors": errors, + "success": True, + }) + total_bytes += bytes_sent + + # Send ZFIN to end session + self.write(self._make_hex_header(ZFIN)) + + # Wait for ZFIN response + for _ in range(retry_limit): + header = self._read_header() + if header and header[0] == ZFIN: + # Send OO to complete + self.write(b"OO") + break + + return { + "success": all(r.get("success", False) or r.get("skipped", False) for r in results), + "files": results, + "total_bytes": total_bytes, + } + + def receive( + self, + directory: str | Path, + callback: Callable[[str, int, int], None] | None = None, + retry_limit: int = 10, + overwrite: bool = False, + max_transfer_size: int = DEFAULT_MAX_TRANSFER_SIZE, + ) -> dict: + """Receive files via ZMODEM. + + Args: + directory: Directory to save received files + callback: Progress callback(filename, bytes_received, total_bytes) + retry_limit: Max retries for errors + overwrite: Overwrite existing files + max_transfer_size: Maximum bytes to receive per file (default 100MB). + Set to 0 to disable limit. Prevents unbounded memory usage. + + Returns: + Dict with transfer statistics + """ + directory = Path(directory) + directory.mkdir(parents=True, exist_ok=True) + + results = [] + total_bytes = 0 + + # Send ZRINIT to indicate ready + buffer_size = 8192 + logger.debug("Sending ZRINIT...") + self.write(self._make_hex_header(ZRINIT, self._pos_to_bytes(buffer_size))) + + while True: + # Wait for ZFILE or ZFIN + header = None + for _ in range(retry_limit * 3): + header = self._read_header() + if header: + break + # Resend ZRINIT + self.write(self._make_hex_header(ZRINIT, self._pos_to_bytes(buffer_size))) + + if header is None: + return {"success": False, "error": "Timeout", "files": results} + + frame_type, data = header + + if frame_type == ZFIN: + # Session complete + self.write(self._make_hex_header(ZFIN)) + break + elif frame_type == ZCAN: + return {"success": False, "error": "Cancelled", "files": results} + elif frame_type != ZFILE: + continue + + # Read file info subpacket + subpacket = self._read_data_subpacket() + if subpacket is None: + self.write(self._make_hex_header(ZNAK)) + continue + + file_data, _ = subpacket + + # Parse filename and metadata + try: + null_pos = file_data.index(0) + filename = file_data[:null_pos].decode("latin-1") + rest = file_data[null_pos + 1:].split(b" ") + filesize = int(rest[0]) if rest[0] else 0 + mtime = int(rest[1], 8) if len(rest) > 1 and rest[1] else None + except (ValueError, IndexError): + filename = file_data.split(b"\x00")[0].decode("latin-1", errors="replace") + filesize = 0 + mtime = None + + logger.debug(f"Receiving: {filename} ({filesize} bytes)") + + # Security: sanitize filename to prevent path traversal attacks + safe_filename = _sanitize_filename(filename) + if safe_filename != filename: + logger.warning(f"Sanitized filename: {filename!r} -> {safe_filename!r}") + + filepath = directory / safe_filename + + # Atomic file creation to prevent TOCTOU race conditions + f, file_error = _open_file_atomic(filepath, overwrite) + if file_error: + logger.warning(f"Cannot create file {filepath}: {file_error}") + results.append({"file": filename, "error": file_error}) + self.write(self._make_hex_header(ZSKIP)) + continue + + # Check for resume (TODO: implement crash recovery using existing file size) + start_pos = 0 + + # Send ZRPOS to indicate where to start + self.write(self._make_bin_header(ZRPOS, self._pos_to_bytes(start_pos))) + + # Receive data + bytes_received = start_pos + errors = 0 + transfer_aborted = False + + try: + if start_pos > 0: + f.seek(start_pos) + + while not transfer_aborted: + # Wait for ZDATA header + header = self._read_header() + if header is None: + errors += 1 + self.write(self._make_bin_header(ZRPOS, self._pos_to_bytes(bytes_received))) + continue + + frame_type, data = header + + if frame_type == ZEOF: + eof_pos = self._bytes_to_pos(data) + logger.debug(f"ZEOF at position {eof_pos}") + break + elif frame_type == ZCAN: + results.append({"file": filename, "error": "Cancelled"}) + break + elif frame_type != ZDATA: + continue + + data_pos = self._bytes_to_pos(data) + if data_pos != bytes_received: + logger.debug(f"Position mismatch: expected {bytes_received}, got {data_pos}") + self.write(self._make_bin_header(ZRPOS, self._pos_to_bytes(bytes_received))) + continue + + # Read data subpackets + while True: + subpacket = self._read_data_subpacket() + if subpacket is None: + errors += 1 + self.write(self._make_bin_header(ZRPOS, self._pos_to_bytes(bytes_received))) + break + + chunk, end_type = subpacket + f.write(chunk) + bytes_received += len(chunk) + + # Check transfer size limit to prevent unbounded memory usage + if max_transfer_size > 0 and bytes_received > max_transfer_size: + logger.warning( + f"Transfer aborted: {filename} exceeded {max_transfer_size} byte limit " + f"(received {bytes_received} bytes)" + ) + self._send_cancel() + transfer_aborted = True + break + + if callback: + callback(filename, bytes_received, filesize) + + if end_type in (ZCRCE, ZCRCW): + # End of this ZDATA frame + if end_type == ZCRCW: + self.write(self._make_bin_header(ZACK, self._pos_to_bytes(bytes_received))) + break + finally: + f.close() + + if transfer_aborted: + # Transfer was aborted due to size limit + results.append({ + "file": filename, + "path": str(filepath), + "error": f"Transfer size exceeded {max_transfer_size} byte limit", + "bytes_received": bytes_received, + "success": False, + }) + # Try to clean up partial file + with contextlib.suppress(OSError): + filepath.unlink() + continue + + # Set modification time + if mtime: + os.utime(filepath, (time.time(), mtime)) + + # Send ZRINIT for next file + self.write(self._make_hex_header(ZRINIT, self._pos_to_bytes(buffer_size))) + + results.append({ + "file": filename, + "path": str(filepath), + "bytes_received": bytes_received, + "errors": errors, + "success": True, + }) + total_bytes += bytes_received + + return { + "success": all(r.get("success", False) for r in results), + "files": results, + "total_bytes": total_bytes, + } + + +def send_zmodem( + read_func: Callable[[int], bytes], + write_func: Callable[[bytes], int], + files: list[str | Path], + callback: Callable[[str, int, int], None] | None = None, +) -> dict: + """Convenience function to send files via ZMODEM.""" + zm = ZModem(read_func, write_func) + return zm.send(files, callback) + + +def receive_zmodem( + read_func: Callable[[int], bytes], + write_func: Callable[[bytes], int], + directory: str | Path, + callback: Callable[[str, int, int], None] | None = None, + overwrite: bool = False, +) -> dict: + """Convenience function to receive files via ZMODEM.""" + zm = ZModem(read_func, write_func) + return zm.receive(directory, callback, overwrite=overwrite) From e8a6197b8c98afa3faf265eaf16d562cfa134705 Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Wed, 28 Jan 2026 19:59:22 -0700 Subject: [PATCH 04/10] Address code review findings for file transfer protocols Critical fixes: - Add max_transfer_size (100MB default) to XMODEM receive - Validate ZMODEM position values with optional max_valid bound High priority: - Extract shared utils to _utils.py (sanitize_filename, open_file_atomic) - Document XMODEM padding behavior (protocol limitation) - Add filesize bounds checking in YMODEM (clamp to 10GB) - Increase ZMODEM subpacket limit from 8KB to 32KB Medium priority: - Add timeout parameter to YMODEM/ZMODEM send/receive methods - Narrow exception handling (SerialException, OSError, ValueError) - Make ZMODEM cancel more robust (3 retries with delays) - Add length validation in _verify_block to prevent IndexError --- src/mcserial/_utils.py | 66 +++++++++++++++++++++++++++++ src/mcserial/server.py | 24 ++++++++--- src/mcserial/xmodem.py | 29 +++++++++++++ src/mcserial/ymodem.py | 80 ++++++++++++----------------------- src/mcserial/zmodem.py | 96 ++++++++++++++++++++++-------------------- 5 files changed, 191 insertions(+), 104 deletions(-) create mode 100644 src/mcserial/_utils.py diff --git a/src/mcserial/_utils.py b/src/mcserial/_utils.py new file mode 100644 index 0000000..5a08094 --- /dev/null +++ b/src/mcserial/_utils.py @@ -0,0 +1,66 @@ +"""Shared utility functions for file transfer protocols. + +These functions provide security and robustness for file receive operations. +""" + +from __future__ import annotations + +import os +from pathlib import Path + + +def sanitize_filename(filename: str) -> str: + """Remove path traversal attempts and dangerous characters from filename. + + Security: Prevents directory traversal attacks where malicious senders + could write files outside the target directory using names like + '../../../etc/passwd' or absolute paths like '/etc/cron.d/backdoor'. + + Args: + filename: Raw filename from remote sender (untrusted input) + + Returns: + Safe filename with path components and dangerous characters removed + """ + # Get just the basename, removing any directory components + name = Path(filename).name + + # Reject empty names + if not name: + name = "unnamed_file" + + # Prefix hidden files (starting with dot) to make them visible + if name.startswith("."): + name = "_" + name[1:] + + # Replace any remaining problematic characters + name = name.replace("\x00", "_").replace("/", "_").replace("\\", "_") + + return name + + +def open_file_atomic(filepath: Path, overwrite: bool) -> tuple[object, str | None]: + """Open file for writing with atomic creation to prevent TOCTOU races. + + Uses O_CREAT | O_EXCL to atomically fail if file exists (when overwrite=False), + preventing race conditions between existence check and file creation. + + Args: + filepath: Path to the file to create/open + overwrite: If True, overwrite existing files. If False, fail if exists. + + Returns: + Tuple of (file_object, None) on success, or (None, error_message) on failure + """ + if overwrite: + # Overwrite mode: just open normally + return open(filepath, "wb"), None + + try: + # Atomic create: fails if file exists (O_EXCL) + fd = os.open(filepath, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644) + return os.fdopen(fd, "wb"), None + except FileExistsError: + return None, "File exists" + except OSError as e: + return None, str(e) diff --git a/src/mcserial/server.py b/src/mcserial/server.py index 4c65c5b..1db3a12 100644 --- a/src/mcserial/server.py +++ b/src/mcserial/server.py @@ -1672,8 +1672,12 @@ def file_transfer_send( else: return {"error": f"Unknown protocol: {protocol}", "success": False} - except Exception as e: - return {"error": str(e), "success": False, "protocol": protocol} + except serial.SerialException as e: + return {"error": f"Serial error: {e}", "success": False, "protocol": protocol} + except OSError as e: + return {"error": f"File error: {e}", "success": False, "protocol": protocol} + except (ValueError, OverflowError) as e: + return {"error": f"Protocol error: {e}", "success": False, "protocol": protocol} @mcp.tool() @@ -1759,8 +1763,12 @@ def file_transfer_receive( else: return {"error": f"Unknown protocol: {protocol}", "success": False} - except Exception as e: - return {"error": str(e), "success": False, "protocol": protocol} + except serial.SerialException as e: + return {"error": f"Serial error: {e}", "success": False, "protocol": protocol} + except OSError as e: + return {"error": f"File error: {e}", "success": False, "protocol": protocol} + except (ValueError, OverflowError) as e: + return {"error": f"Protocol error: {e}", "success": False, "protocol": protocol} @mcp.tool() @@ -1818,8 +1826,12 @@ def file_transfer_send_batch( result["protocol"] = protocol return result - except Exception as e: - return {"error": str(e), "success": False, "protocol": protocol} + except serial.SerialException as e: + return {"error": f"Serial error: {e}", "success": False, "protocol": protocol} + except OSError as e: + return {"error": f"File error: {e}", "success": False, "protocol": protocol} + except (ValueError, OverflowError) as e: + return {"error": f"Protocol error: {e}", "success": False, "protocol": protocol} # ============================================================================ diff --git a/src/mcserial/xmodem.py b/src/mcserial/xmodem.py index d58e300..71a2ad3 100644 --- a/src/mcserial/xmodem.py +++ b/src/mcserial/xmodem.py @@ -33,6 +33,7 @@ DEFAULT_RETRY_LIMIT = 16 # Max retries per block DEFAULT_TIMEOUT = 60.0 # Total transfer timeout in seconds READ_TIMEOUT_RETRIES = 30 # Retries when waiting for response byte INIT_TIMEOUT_RETRIES = 10 # Retries when waiting for transfer initiation +DEFAULT_MAX_TRANSFER_SIZE = 100 * 1024 * 1024 # 100MB default limit logger = logging.getLogger(__name__) @@ -134,6 +135,11 @@ class XModem: Returns: True if verification passes, False otherwise """ + # Validate check_bytes length before accessing indices + expected_len = 2 if self.use_crc else 1 + if len(check_bytes) < expected_len: + return False + if self.use_crc: expected = _calc_crc16(data) received = (check_bytes[0] << 8) | check_bytes[1] @@ -256,14 +262,22 @@ class XModem: callback: Callable[[int], None] | None = None, retry_limit: int = DEFAULT_RETRY_LIMIT, timeout: float = DEFAULT_TIMEOUT, + max_transfer_size: int = DEFAULT_MAX_TRANSFER_SIZE, ) -> dict: """Receive a file via XMODEM. + Note: XMODEM has no file metadata, so the exact file size is unknown. + Blocks are padded with SUB (0x1A) characters. For binary files, you may + need to know the expected size and truncate accordingly. For text files, + trailing 0x1A bytes are traditionally stripped by the receiver. + Args: stream: File-like object to write to callback: Progress callback(bytes_received) retry_limit: Max retries per block timeout: Total timeout in seconds (enforced across entire transfer) + max_transfer_size: Maximum bytes to receive (default 100MB). + Set to 0 to disable limit. Prevents disk exhaustion. Returns: Dict with transfer statistics @@ -358,7 +372,22 @@ class XModem: if block_num == expected_block: stream.write(data) bytes_received += len(data) + # Block numbers wrap at 256 (8-bit counter) expected_block = (expected_block + 1) & 0xFF + + # Check transfer size limit to prevent disk exhaustion + if max_transfer_size > 0 and bytes_received > max_transfer_size: + logger.warning( + f"Transfer aborted: exceeded {max_transfer_size} byte limit " + f"(received {bytes_received} bytes)" + ) + self.write(bytes([CAN, CAN])) + return { + "success": False, + "error": f"Transfer size exceeded {max_transfer_size} byte limit", + "bytes_received": bytes_received, + } + if callback: callback(bytes_received) elif block_num == (expected_block - 1) & 0xFF: diff --git a/src/mcserial/ymodem.py b/src/mcserial/ymodem.py index 78d007b..39269f3 100644 --- a/src/mcserial/ymodem.py +++ b/src/mcserial/ymodem.py @@ -23,6 +23,7 @@ import time from collections.abc import Callable from pathlib import Path +from mcserial._utils import open_file_atomic, sanitize_filename from mcserial.xmodem import ( ACK, CAN, @@ -37,55 +38,10 @@ from mcserial.xmodem import ( logger = logging.getLogger(__name__) -# Transfer limits +# Transfer limits and defaults DEFAULT_MAX_TRANSFER_SIZE = 100 * 1024 * 1024 # 100MB default limit per file - - -def _sanitize_filename(filename: str) -> str: - """Remove path traversal attempts and dangerous characters from filename. - - Security: Prevents directory traversal attacks where malicious senders - could write files outside the target directory using names like - '../../../etc/passwd' or absolute paths like '/etc/cron.d/backdoor'. - """ - # Get just the basename, removing any directory components - name = Path(filename).name - - # Reject empty names - if not name: - name = "unnamed_file" - - # Prefix hidden files (starting with dot) to make them visible - if name.startswith("."): - name = "_" + name[1:] - - # Replace any remaining problematic characters - name = name.replace("\x00", "_").replace("/", "_").replace("\\", "_") - - return name - - -def _open_file_atomic(filepath: Path, overwrite: bool) -> tuple: - """Open file for writing with atomic creation to prevent TOCTOU races. - - Uses O_CREAT | O_EXCL to atomically fail if file exists (when overwrite=False), - preventing race conditions between existence check and file creation. - - Returns: - Tuple of (file_object, None) on success, or (None, error_message) on failure - """ - if overwrite: - # Overwrite mode: just open normally - return open(filepath, "wb"), None - - try: - # Atomic create: fails if file exists (O_EXCL) - fd = os.open(filepath, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644) - return os.fdopen(fd, "wb"), None - except FileExistsError: - return None, "File exists" - except OSError as e: - return None, str(e) +DEFAULT_TIMEOUT = 60.0 # Total transfer timeout in seconds +DEFAULT_RETRY_LIMIT = 16 # Max retries per block class YModemError(XModemError): @@ -167,6 +123,12 @@ class YModem: rest = [x for x in rest if x and x != b"\x00"] filesize = int(rest[0]) if rest else 0 + # Clamp filesize to reasonable bounds (prevent memory issues from malicious values) + if filesize < 0: + filesize = 0 + elif filesize > 10 * 1024 * 1024 * 1024: # 10GB sanity limit + logger.warning(f"Filesize {filesize} exceeds 10GB limit, clamping") + filesize = 10 * 1024 * 1024 * 1024 mtime = int(rest[1], 8) if len(rest) > 1 else None return { @@ -181,7 +143,8 @@ class YModem: self, files: list[str | Path], callback: Callable[[str, int, int], None] | None = None, - retry_limit: int = 16, + retry_limit: int = DEFAULT_RETRY_LIMIT, + timeout: float = DEFAULT_TIMEOUT, ) -> dict: """Send files via YMODEM batch transfer. @@ -189,10 +152,12 @@ class YModem: files: List of file paths to send callback: Progress callback(filename, bytes_sent, total_bytes) retry_limit: Max retries per block + timeout: Total timeout in seconds (enforced across entire transfer) Returns: Dict with transfer statistics """ + start_time = time.monotonic() results = [] total_bytes = 0 total_errors = 0 @@ -209,6 +174,8 @@ class YModem: # Wait for receiver 'C' logger.debug(f"Waiting for receiver to initiate {filepath.name}...") for _ in range(retry_limit * 10): + if time.monotonic() - start_time > timeout: + return {"success": False, "error": f"Timeout ({timeout}s) waiting for receiver", "files": results} b = self._read_byte(timeout_retries=3) if b == CRC_MODE: break @@ -320,9 +287,10 @@ class YModem: self, directory: str | Path, callback: Callable[[str, int, int], None] | None = None, - retry_limit: int = 16, + retry_limit: int = DEFAULT_RETRY_LIMIT, overwrite: bool = False, max_transfer_size: int = DEFAULT_MAX_TRANSFER_SIZE, + timeout: float = DEFAULT_TIMEOUT, ) -> dict: """Receive files via YMODEM batch transfer. @@ -333,10 +301,12 @@ class YModem: overwrite: Overwrite existing files max_transfer_size: Maximum bytes to receive per file (default 100MB). Set to 0 to disable limit. Prevents unbounded memory usage. + timeout: Total timeout in seconds (enforced across entire transfer) Returns: Dict with transfer statistics """ + start_time = time.monotonic() directory = Path(directory) directory.mkdir(parents=True, exist_ok=True) @@ -345,9 +315,15 @@ class YModem: total_errors = 0 while True: + # Check timeout + if time.monotonic() - start_time > timeout: + return {"success": False, "error": f"Timeout ({timeout}s)", "files": results} + # Initiate with 'C' for CRC mode logger.debug("Initiating YMODEM receive...") for _attempt in range(retry_limit): + if time.monotonic() - start_time > timeout: + return {"success": False, "error": f"Timeout ({timeout}s)", "files": results} self.write(bytes([CRC_MODE])) header = self._read_byte(timeout_retries=30) if header in (SOH, STX): @@ -391,14 +367,14 @@ class YModem: logger.debug(f"Receiving: {filename} ({filesize} bytes)") # Security: sanitize filename to prevent path traversal attacks - safe_filename = _sanitize_filename(filename) + safe_filename = sanitize_filename(filename) if safe_filename != filename: logger.warning(f"Sanitized filename: {filename!r} -> {safe_filename!r}") filepath = directory / safe_filename # Atomic file creation to prevent TOCTOU race conditions - f, file_error = _open_file_atomic(filepath, overwrite) + f, file_error = open_file_atomic(filepath, overwrite) if file_error: results.append({"file": filename, "error": file_error}) self.write(bytes([CAN, CAN])) diff --git a/src/mcserial/zmodem.py b/src/mcserial/zmodem.py index 124fc03..1a72326 100644 --- a/src/mcserial/zmodem.py +++ b/src/mcserial/zmodem.py @@ -23,51 +23,19 @@ import time from collections.abc import Callable from pathlib import Path +from mcserial._utils import open_file_atomic, sanitize_filename + logger = logging.getLogger(__name__) -def _sanitize_filename(filename: str) -> str: - """Remove path traversal attempts and dangerous characters from filename. - - Security: Prevents directory traversal attacks where malicious senders - could write files outside the target directory. - """ - name = Path(filename).name - if not name: - name = "unnamed_file" - if name.startswith("."): - name = "_" + name[1:] - name = name.replace("\x00", "_").replace("/", "_").replace("\\", "_") - return name - - -def _open_file_atomic(filepath: Path, overwrite: bool) -> tuple: - """Open file for writing with atomic creation to prevent TOCTOU races. - - Uses O_CREAT | O_EXCL to atomically fail if file exists (when overwrite=False), - preventing race conditions between existence check and file creation. - - Returns: - Tuple of (file_object, None) on success, or (None, error_message) on failure - """ - if overwrite: - return open(filepath, "wb"), None - - try: - fd = os.open(filepath, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644) - return os.fdopen(fd, "wb"), None - except FileExistsError: - return None, "File exists" - except OSError as e: - return None, str(e) - - # Protocol constants ZPAD = 0x2A # '*' - Padding character # Transfer limits DEFAULT_MAX_TRANSFER_SIZE = 100 * 1024 * 1024 # 100MB default limit per file -MAX_SUBPACKET_SIZE = 8192 # Per-packet size limit (sanity check) +MAX_SUBPACKET_SIZE = 32768 # Per-packet size limit (32KB - matches common implementations) +DEFAULT_TIMEOUT = 60.0 # Total transfer timeout in seconds +MAX_HEADER_SEARCH_ITERATIONS = 1000 # Max iterations when searching for header sync ZDLE = 0x18 # Data Link Escape ZDLEE = 0x58 # Escaped ZDLE (ZDLE ^ 0x40) @@ -222,8 +190,8 @@ class ZModem: return b ^ 0x40 return b - def _send_cancel(self) -> None: - """Send ZMODEM cancel sequence. + def _send_cancel(self, retries: int = 3) -> None: + """Send ZMODEM cancel sequence with retry for reliability. ZMODEM uses 8 CAN bytes followed by 8 backspaces to abort transfer. This is the proper way to cancel - just sending ZCAN header may not @@ -232,10 +200,16 @@ class ZModem: Note: CAN (Cancel) and ZDLE share the same byte value 0x18. In ZMODEM, ZDLE is the escape character, but when sent 5+ times consecutively outside of frame context, it signals abort (CAN sequence). + + Args: + retries: Number of times to send cancel sequence for reliability """ # CAN = 0x18 (same as ZDLE) - 8 consecutive cancels + 8 backspaces cancel_seq = bytes([0x18] * 8 + [0x08] * 8) - self.write(cancel_seq) + for _ in range(retries): + self.write(cancel_seq) + # Brief delay between retries to ensure remote receives + time.sleep(0.1) def _make_hex_header(self, frame_type: int, data: bytes = b"\x00\x00\x00\x00") -> bytes: """Create a hex-encoded ZMODEM header.""" @@ -351,7 +325,7 @@ class ZModem: # Look for ZPAD ZPAD ZDLE or ZPAD ZDLE sync_count = 0 - for _ in range(1000): + for _ in range(MAX_HEADER_SEARCH_ITERATIONS): b = self._read_byte(timeout_retries=10) if b is None: continue @@ -429,15 +403,32 @@ class ZModem: "ZMODEM uses 32-bit position encoding and cannot handle files larger than 4GB." ) from None - def _bytes_to_pos(self, data: bytes) -> int: - """Convert 4-byte little-endian to position.""" - return int.from_bytes(data[:4], "little") + def _bytes_to_pos(self, data: bytes, max_valid: int | None = None) -> int: + """Convert 4-byte little-endian to position. + + Args: + data: At least 4 bytes of position data + max_valid: Optional maximum valid position (e.g., filesize). + If provided and position exceeds this, returns max_valid. + + Returns: + Position value, clamped to max_valid if specified + """ + if len(data) < 4: + return 0 + pos = int.from_bytes(data[:4], "little") + # Validate against maximum if provided (prevents seeking past EOF) + if max_valid is not None and pos > max_valid: + logger.debug(f"Position {pos} exceeds max {max_valid}, clamping") + return max_valid + return pos def send( self, files: list[str | Path], callback: Callable[[str, int, int], None] | None = None, retry_limit: int = 10, + timeout: float = DEFAULT_TIMEOUT, ) -> dict: """Send files via ZMODEM. @@ -445,10 +436,12 @@ class ZModem: files: List of file paths to send callback: Progress callback(filename, bytes_sent, total_bytes) retry_limit: Max retries for errors + timeout: Total timeout in seconds (enforced across entire transfer) Returns: Dict with transfer statistics """ + start_time = time.monotonic() results = [] total_bytes = 0 @@ -458,6 +451,8 @@ class ZModem: # Wait for ZRINIT from receiver for _ in range(retry_limit * 3): + if time.monotonic() - start_time > timeout: + return {"success": False, "error": f"Timeout ({timeout}s) waiting for receiver", "files": results} header = self._read_header() if header is None: self.write(self._make_hex_header(ZRQINIT)) @@ -595,6 +590,7 @@ class ZModem: retry_limit: int = 10, overwrite: bool = False, max_transfer_size: int = DEFAULT_MAX_TRANSFER_SIZE, + timeout: float = DEFAULT_TIMEOUT, ) -> dict: """Receive files via ZMODEM. @@ -605,10 +601,12 @@ class ZModem: overwrite: Overwrite existing files max_transfer_size: Maximum bytes to receive per file (default 100MB). Set to 0 to disable limit. Prevents unbounded memory usage. + timeout: Total timeout in seconds (enforced across entire transfer) Returns: Dict with transfer statistics """ + start_time = time.monotonic() directory = Path(directory) directory.mkdir(parents=True, exist_ok=True) @@ -621,9 +619,15 @@ class ZModem: self.write(self._make_hex_header(ZRINIT, self._pos_to_bytes(buffer_size))) while True: + # Check timeout + if time.monotonic() - start_time > timeout: + return {"success": False, "error": f"Timeout ({timeout}s)", "files": results} + # Wait for ZFILE or ZFIN header = None for _ in range(retry_limit * 3): + if time.monotonic() - start_time > timeout: + return {"success": False, "error": f"Timeout ({timeout}s)", "files": results} header = self._read_header() if header: break @@ -667,14 +671,14 @@ class ZModem: logger.debug(f"Receiving: {filename} ({filesize} bytes)") # Security: sanitize filename to prevent path traversal attacks - safe_filename = _sanitize_filename(filename) + safe_filename = sanitize_filename(filename) if safe_filename != filename: logger.warning(f"Sanitized filename: {filename!r} -> {safe_filename!r}") filepath = directory / safe_filename # Atomic file creation to prevent TOCTOU race conditions - f, file_error = _open_file_atomic(filepath, overwrite) + f, file_error = open_file_atomic(filepath, overwrite) if file_error: logger.warning(f"Cannot create file {filepath}: {file_error}") results.append({"file": filename, "error": file_error}) From b5bd2bb470843b0e1a9e43c35682e9a3d56a38d1 Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Wed, 28 Jan 2026 22:49:06 -0700 Subject: [PATCH 05/10] Update README with RS-485, file transfer, and auto-baud docs Reorganized tool tables by mode (RS-232, RS-485, file transfer) and added usage examples for Modbus bus scanning and ZMODEM transfers. --- README.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 77 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index fe25901..817b9ac 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,12 @@ FastMCP server for serial port access via Model Context Protocol. ## Features -- **Tools** for serial port control (open, close, write, configure) -- **Dynamic Resources** for reading data (`serial://{port}/data`) -- Full pyserial support (baudrate, parity, stop bits, etc.) -- Multiple concurrent port connections -- Raw byte and text modes +- **RS-232 Mode**: Full modem control (RTS, DTR, CTS, DSR, RI, CD) +- **RS-485 Mode**: Half-duplex bus communication with auto direction control +- **File Transfer**: X/Y/ZMODEM protocols for reliable file transfers +- **Auto-baud Detection**: Smart detection using 0x55 sync pattern analysis +- **Dynamic Resources**: Read data via `serial://{port}/data` +- Full pyserial support (baudrate, parity, stop bits, flow control) ## Installation @@ -27,20 +28,67 @@ uv pip install mcserial claude mcp add mcserial "uvx mcserial" ``` +## Modes + +Ports open in **RS-232 mode** by default. Switch with `set_port_mode()`: + +| Mode | Use Case | Tools | +|------|----------|-------| +| RS-232 | Point-to-point serial | `get_modem_lines`, `set_modem_lines`, `pulse_line`, `send_break` | +| RS-485 | Multi-drop bus (Modbus) | `set_rs485_mode`, `rs485_transact`, `rs485_scan_addresses` | + ## Tools +### Common (both modes) + | Tool | Description | |------|-------------| | `list_serial_ports` | Discover available serial ports | -| `open_serial_port` | Open a connection with config | +| `open_serial_port` | Open connection (auto-detects baud if not specified) | | `close_serial_port` | Close a connection | +| `set_port_mode` | Switch between RS-232 and RS-485 modes | | `write_serial` | Send text data | | `write_serial_bytes` | Send raw bytes | | `read_serial` | Read available data | | `read_serial_line` | Read until newline | +| `read_until` | Read until custom terminator | | `configure_serial` | Change port settings | | `flush_serial` | Clear buffers | -| `get_connection_status` | List open connections | +| `get_connection_status` | List open connections with mode | +| `detect_baud_rate` | Auto-detect baud rate | + +### RS-232 Mode + +| Tool | Description | +|------|-------------| +| `get_modem_lines` | Read CTS, DSR, RI, CD, RTS, DTR states | +| `set_modem_lines` | Control RTS and DTR outputs | +| `pulse_line` | Pulse RTS/DTR for reset sequences | +| `send_break` | Send timed break signal | +| `set_break_condition` | Hold/release break state | + +### RS-485 Mode + +| Tool | Description | +|------|-------------| +| `set_rs485_mode` | Configure hardware RS-485 (DE/RE control) | +| `check_rs485_support` | Detect hardware RS-485 capability | +| `rs485_transact` | Send/receive with automatic turnaround | +| `rs485_scan_addresses` | Scan bus for responding devices | + +### File Transfer + +| Tool | Description | +|------|-------------| +| `file_transfer_send` | Send file via XMODEM/YMODEM/ZMODEM | +| `file_transfer_receive` | Receive file via XMODEM/YMODEM/ZMODEM | +| `file_transfer_send_batch` | Send multiple files (YMODEM/ZMODEM) | + +**Protocols:** +- `xmodem` - 128-byte blocks, simple (1977) +- `xmodem1k` - 1024-byte blocks +- `ymodem` - Batch mode with filename/size +- `zmodem` - Streaming, auto-resume (recommended) ## Resources @@ -48,7 +96,7 @@ claude mcp add mcserial "uvx mcserial" |-----|-------------| | `serial://ports` | List available ports | | `serial://{port}/data` | Read data from open port | -| `serial://{port}/status` | Port configuration info | +| `serial://{port}/status` | Port config and mode | | `serial://{port}/raw` | Read as hex dump | ## Environment Variables @@ -59,16 +107,34 @@ claude mcp add mcserial "uvx mcserial" | `MCSERIAL_DEFAULT_TIMEOUT` | 1.0 | Read timeout (seconds) | | `MCSERIAL_MAX_CONNECTIONS` | 10 | Max concurrent ports | -## Example Workflow +## Example Workflows + +### Basic RS-232 ``` -1. list_serial_ports → find /dev/ttyUSB0 -2. open_serial_port(port="/dev/ttyUSB0", baudrate=115200) +1. list_serial_ports() → find /dev/ttyUSB0 +2. open_serial_port(port="/dev/ttyUSB0") # auto-detects baud 3. write_serial(port="/dev/ttyUSB0", data="AT\r\n") 4. Read resource: serial:///dev/ttyUSB0/data 5. close_serial_port(port="/dev/ttyUSB0") ``` +### RS-485 Modbus + +``` +1. open_serial_port(port="/dev/ttyUSB0", baudrate=9600) +2. set_port_mode(port="/dev/ttyUSB0", mode="rs485") +3. rs485_scan_addresses(port="/dev/ttyUSB0") # discover devices +4. rs485_transact(port="/dev/ttyUSB0", data="\x01\x03...") +``` + +### File Transfer + +``` +1. open_serial_port(port="/dev/ttyUSB0", baudrate=115200) +2. file_transfer_send(port="/dev/ttyUSB0", file_path="firmware.bin") +``` + ## License MIT From 5c655fe743aec1db4ef6d690bc3ceb3288e4f65a Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Sun, 1 Feb 2026 22:39:09 -0700 Subject: [PATCH 06/10] Add URL handlers, pyserial feature parity, and cp2110 extra - open_serial_port now accepts URL schemes (socket://, rfc2217://, loop://, spy://, cp2110://) via serial_for_url() - cp2110 HID-to-UART support gated behind optional [cp2110] extra - Add grep parameter to list_serial_ports for regex filtering - Add read_serial_lines for batch multi-line reads - Add cancel_read/cancel_write for pending I/O interruption - Add set_flow_control for manual XON/XOFF gating - Add break_condition to get_modem_lines response --- pyproject.toml | 3 + src/mcserial/server.py | 264 +++++++++++++++++++++++++++++++++++++---- 2 files changed, 244 insertions(+), 23 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 9b59ce4..01e0dff 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -24,6 +24,9 @@ dependencies = [ ] [project.optional-dependencies] +cp2110 = [ + "hidapi>=0.14.0", +] dev = [ "ruff>=0.9.0", "pytest>=8.0.0", diff --git a/src/mcserial/server.py b/src/mcserial/server.py index 1db3a12..98f6d36 100644 --- a/src/mcserial/server.py +++ b/src/mcserial/server.py @@ -226,21 +226,39 @@ Protocols: xmodem (128B blocks), xmodem1k, ymodem (batch), zmodem (streaming, re @mcp.tool() -def list_serial_ports(usb_only: bool = True) -> list[dict]: +def list_serial_ports(usb_only: bool = True, grep: str | None = None) -> list[dict]: """List available serial ports on the system. Args: usb_only: If True (default), only show USB serial devices. Set False to include legacy/phantom ttyS ports. + grep: Optional regex pattern to filter ports. Matches against device path, + description, hardware ID, manufacturer, product, and serial number. + Examples: "FTDI", "ttyUSB", "VID:PID=0403:6001", "CP210" Returns a list of ports with their device path, description, and hardware ID. Call this first to discover what ports are available before opening one. """ + import re + + # Compile grep pattern if provided + pattern = re.compile(grep, re.IGNORECASE) if grep else None + ports = [] for port in serial.tools.list_ports.comports(): # Filter out phantom/legacy ports if usb_only is True if usb_only and port.hwid == "n/a": continue + + # Apply grep filter across all fields + if pattern: + searchable = " ".join(str(v) for v in [ + port.device, port.description, port.hwid, + port.manufacturer, port.product, port.serial_number, + ] if v) + if not pattern.search(searchable): + continue + ports.append({ "device": port.device, "description": port.description, @@ -279,7 +297,12 @@ def open_serial_port( sending data or responds to a probe string. Args: - port: Device path (e.g., '/dev/ttyUSB0', 'COM3') + port: Device path (e.g., '/dev/ttyUSB0', 'COM3') or URL scheme: + - socket://host:port (raw TCP socket) + - rfc2217://host:port (Telnet COM Port Control) + - loop:// (loopback for testing) + - spy://device (debug wrapper, logs traffic) + - cp2110:// (Silicon Labs HID-to-UART, requires `hidapi`) baudrate: Baud rate. If None, auto-detect (recommended for unknown devices) bytesize: Data bits (5, 6, 7, or 8) parity: Parity checking (N=None, E=Even, O=Odd, M=Mark, S=Space) @@ -303,10 +326,28 @@ def open_serial_port( if len(_connections) >= MAX_CONNECTIONS: return {"error": f"Maximum connections ({MAX_CONNECTIONS}) reached", "success": False} - # Auto-detect baud rate if not specified + # Detect URL scheme vs local device path + is_url = "://" in port + _SUPPORTED_SCHEMES = ("socket", "rfc2217", "loop", "spy", "cp2110", "alt", "hwgrep") + + if is_url: + scheme = port.split("://", 1)[0].lower() + if scheme not in _SUPPORTED_SCHEMES: + return {"error": f"Unsupported URL scheme: {scheme}://", "success": False} + + if scheme == "cp2110": + try: + import hid # noqa: F401 + except ImportError: + return { + "error": "cp2110:// requires the hidapi package. " + "Install with: pip install mcserial[cp2110]", + "success": False, + } + + # Auto-detect baud rate if not specified (only for local devices) detected_info = None - if baudrate is None: - # Import the detect function's logic inline to avoid circular issues + if baudrate is None and not is_url: detection_result = _detect_baud_rate_internal( port=port, probe=autobaud_probe, @@ -323,34 +364,49 @@ def open_serial_port( ], } else: - # Fall back to default if detection fails baudrate = DEFAULT_BAUDRATE detected_info = { "auto_detected": False, "fallback_reason": "No data received or low confidence", "using_default": DEFAULT_BAUDRATE, } + elif baudrate is None: + baudrate = DEFAULT_BAUDRATE try: - conn = serial.Serial( - port=port, - baudrate=baudrate, - bytesize=bytesize, - parity=parity, - stopbits=stopbits, - timeout=timeout, - write_timeout=write_timeout, - inter_byte_timeout=inter_byte_timeout, - xonxoff=xonxoff, - rtscts=rtscts, - dsrdtr=dsrdtr, - exclusive=exclusive, - ) + if is_url: + conn = serial.serial_for_url( + port, + baudrate=baudrate, + bytesize=bytesize, + parity=parity, + stopbits=stopbits, + timeout=timeout, + write_timeout=write_timeout, + xonxoff=xonxoff, + rtscts=rtscts, + dsrdtr=dsrdtr, + ) + else: + conn = serial.Serial( + port=port, + baudrate=baudrate, + bytesize=bytesize, + parity=parity, + stopbits=stopbits, + timeout=timeout, + write_timeout=write_timeout, + inter_byte_timeout=inter_byte_timeout, + xonxoff=xonxoff, + rtscts=rtscts, + dsrdtr=dsrdtr, + exclusive=exclusive, + ) _connections[port] = SerialConnection(port=port, connection=conn) result = { "success": True, "port": port, - "mode": "rs232", # Default mode + "mode": "rs232", "baudrate": baudrate, "bytesize": bytesize, "parity": parity, @@ -358,15 +414,21 @@ def open_serial_port( "xonxoff": xonxoff, "rtscts": rtscts, "dsrdtr": dsrdtr, - "exclusive": exclusive, "resource_uri": f"serial://{port}/data", - "mode_hint": "Use set_port_mode() to switch to RS-485 mode if needed.", } + if is_url: + result["url_scheme"] = port.split("://", 1)[0].lower() + result["hint"] = "Opened via URL handler. Some features (exclusive, auto-baud) are not available." + else: + result["exclusive"] = exclusive + result["mode_hint"] = "Use set_port_mode() to switch to RS-485 mode if needed." if detected_info: result["autobaud"] = detected_info return result except serial.SerialException as e: return {"error": str(e), "success": False} + except OSError as e: + return {"error": f"Connection error: {e}", "success": False} @mcp.tool() @@ -520,6 +582,55 @@ def read_serial_line(port: str, encoding: str = "utf-8") -> dict: return {"error": str(e), "success": False} +@mcp.tool() +def read_serial_lines( + port: str, + max_lines: int = 10, + encoding: str = "utf-8", +) -> dict: + """Read multiple lines from an open serial port. + + Reads up to max_lines, stopping early if no more data is available + (readline returns empty due to timeout). Useful for draining buffered + output or reading multi-line responses. + + Args: + port: Device path of the port to read from + max_lines: Maximum number of lines to read (default: 10) + encoding: Character encoding for decoding (default: utf-8) + + Returns: + List of lines read from the port + """ + if port not in _connections: + return {"error": f"Port {port} is not open", "success": False} + + if max_lines < 1 or max_lines > 1000: + return {"error": "max_lines must be 1-1000", "success": False} + + try: + conn = _connections[port].connection + lines = [] + total_bytes = 0 + + for _ in range(max_lines): + raw = conn.readline() + if not raw: + break + total_bytes += len(raw) + lines.append(raw.decode(encoding, errors="replace").rstrip("\r\n")) + + return { + "success": True, + "lines": lines, + "count": len(lines), + "bytes_read": total_bytes, + "port": port, + } + except serial.SerialException as e: + return {"error": str(e), "success": False} + + @mcp.tool() def configure_serial( port: str, @@ -657,6 +768,112 @@ def flush_serial(port: str, input_buffer: bool = True, output_buffer: bool = Tru return {"error": str(e), "success": False} +@mcp.tool() +def cancel_read(port: str) -> dict: + """Cancel any pending read operation on a serial port. + + Interrupts a blocking read by calling cancel_read() on the underlying + pyserial connection. Only effective on platforms that support it + (POSIX with select-based reads). + + Args: + port: Device path of the port + + Returns: + Cancellation status + """ + if port not in _connections: + return {"error": f"Port {port} is not open", "success": False} + + try: + conn = _connections[port].connection + conn.cancel_read() + return {"success": True, "port": port, "cancelled": "read"} + except (serial.SerialException, AttributeError) as e: + return {"error": str(e), "success": False} + + +@mcp.tool() +def cancel_write(port: str) -> dict: + """Cancel any pending write operation on a serial port. + + Interrupts a blocking write by calling cancel_write() on the underlying + pyserial connection. Only effective on platforms that support it + (POSIX with select-based writes). + + Args: + port: Device path of the port + + Returns: + Cancellation status + """ + if port not in _connections: + return {"error": f"Port {port} is not open", "success": False} + + try: + conn = _connections[port].connection + conn.cancel_write() + return {"success": True, "port": port, "cancelled": "write"} + except (serial.SerialException, AttributeError) as e: + return {"error": str(e), "success": False} + + +@mcp.tool() +def set_flow_control( + port: str, + input_flow: bool | None = None, + output_flow: bool | None = None, +) -> dict: + """Manually gate input/output flow control on a serial port. + + When software (XON/XOFF) or hardware (RTS/CTS) flow control is enabled, + these calls manually send flow control signals: + + - input_flow=True: Send XON (allow remote to send) + - input_flow=False: Send XOFF (tell remote to stop) + - output_flow=True: Resume our outgoing data + - output_flow=False: Pause our outgoing data + + Flow control must already be enabled via configure_serial (xonxoff=True + or rtscts=True) for these to have effect. + + WARNING: Not portable across all platforms. + + Args: + port: Device path of the port + input_flow: Enable (XON) or disable (XOFF) incoming data (None = no change) + output_flow: Enable or disable outgoing data (None = no change) + + Returns: + Flow control gate status + """ + if port not in _connections: + return {"error": f"Port {port} is not open", "success": False} + + try: + conn = _connections[port].connection + changes = {} + + if input_flow is not None: + conn.set_input_flow_control(input_flow) + changes["input_flow"] = input_flow + if output_flow is not None: + conn.set_output_flow_control(output_flow) + changes["output_flow"] = output_flow + + return { + "success": True, + "port": port, + "changes": changes, + "flow_control_enabled": { + "xonxoff": conn.xonxoff, + "rtscts": conn.rtscts, + }, + } + except (serial.SerialException, AttributeError) as e: + return {"error": str(e), "success": False} + + @mcp.tool() def set_port_mode(port: str, mode: Literal["rs232", "rs485"]) -> dict: """Switch a serial port between RS-232 and RS-485 modes. @@ -755,6 +972,7 @@ def get_modem_lines(port: str) -> dict: "rts": conn.rts, "dtr": conn.dtr, }, + "break_condition": conn.break_condition, } except serial.SerialException as e: return {"error": str(e), "success": False} From dc8caddb8fcf1bfddb65655e01025b0c1c87f192 Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Mon, 2 Feb 2026 22:01:48 -0700 Subject: [PATCH 07/10] Add Starlight documentation site with full content Astro 5 + Starlight docs site with 17 pages covering all 30 mcserial tools. Structured using Diataxis framework: tutorials, guides, reference, and concepts. Includes Docker + caddy-docker-proxy deployment for mcserial.l.zmesh.systems with HMR support behind reverse proxy. Content pages: - Landing page with feature overview and quick start - Tutorials: getting started, loopback testing (loop://) - Guides: RS-232 basics, RS-485/Modbus, file transfers, network ports - Reference: common tools, RS-232 tools, RS-485 tools, file transfer tools, URL schemes, MCP resources, environment variables - Concepts: RS-232 vs RS-485, flow control --- README.md | 64 +- docs/.gitignore | 17 + docs/Dockerfile | 48 + docs/Makefile | 50 + docs/astro.config.mjs | 76 + docs/docker-compose.yml | 35 + docs/package-lock.json | 6394 +++++++++++++++++ docs/package.json | 17 + docs/public/favicon.svg | 12 + docs/src/assets/logo.svg | 17 + docs/src/content.config.ts | 7 + .../content/docs/concepts/flow-control.mdx | 192 + .../content/docs/concepts/rs232-vs-rs485.mdx | 107 + .../content/docs/guides/file-transfers.mdx | 221 + .../src/content/docs/guides/network-ports.mdx | 213 + docs/src/content/docs/guides/rs232-basics.mdx | 257 + docs/src/content/docs/guides/rs485-modbus.mdx | 277 + docs/src/content/docs/index.mdx | 80 + .../content/docs/reference/environment.mdx | 110 + docs/src/content/docs/reference/resources.mdx | 143 + .../content/docs/reference/tools-common.mdx | 455 ++ .../docs/reference/tools-file-transfer.mdx | 174 + .../content/docs/reference/tools-rs232.mdx | 170 + .../content/docs/reference/tools-rs485.mdx | 218 + .../content/docs/reference/url-handlers.mdx | 183 + .../docs/tutorials/getting-started.mdx | 269 + .../docs/tutorials/loopback-testing.mdx | 378 + docs/src/styles/custom.css | 30 + docs/tsconfig.json | 5 + 29 files changed, 10212 insertions(+), 7 deletions(-) create mode 100644 docs/.gitignore create mode 100644 docs/Dockerfile create mode 100644 docs/Makefile create mode 100644 docs/astro.config.mjs create mode 100644 docs/docker-compose.yml create mode 100644 docs/package-lock.json create mode 100644 docs/package.json create mode 100644 docs/public/favicon.svg create mode 100644 docs/src/assets/logo.svg create mode 100644 docs/src/content.config.ts create mode 100644 docs/src/content/docs/concepts/flow-control.mdx create mode 100644 docs/src/content/docs/concepts/rs232-vs-rs485.mdx create mode 100644 docs/src/content/docs/guides/file-transfers.mdx create mode 100644 docs/src/content/docs/guides/network-ports.mdx create mode 100644 docs/src/content/docs/guides/rs232-basics.mdx create mode 100644 docs/src/content/docs/guides/rs485-modbus.mdx create mode 100644 docs/src/content/docs/index.mdx create mode 100644 docs/src/content/docs/reference/environment.mdx create mode 100644 docs/src/content/docs/reference/resources.mdx create mode 100644 docs/src/content/docs/reference/tools-common.mdx create mode 100644 docs/src/content/docs/reference/tools-file-transfer.mdx create mode 100644 docs/src/content/docs/reference/tools-rs232.mdx create mode 100644 docs/src/content/docs/reference/tools-rs485.mdx create mode 100644 docs/src/content/docs/reference/url-handlers.mdx create mode 100644 docs/src/content/docs/tutorials/getting-started.mdx create mode 100644 docs/src/content/docs/tutorials/loopback-testing.mdx create mode 100644 docs/src/styles/custom.css create mode 100644 docs/tsconfig.json diff --git a/README.md b/README.md index 817b9ac..b7c5a7d 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,11 @@ FastMCP server for serial port access via Model Context Protocol. ## Features -- **RS-232 Mode**: Full modem control (RTS, DTR, CTS, DSR, RI, CD) +- **RS-232 Mode**: Full modem control (RTS, DTR, CTS, DSR, RI, CD, break condition) - **RS-485 Mode**: Half-duplex bus communication with auto direction control - **File Transfer**: X/Y/ZMODEM protocols for reliable file transfers - **Auto-baud Detection**: Smart detection using 0x55 sync pattern analysis +- **URL Handlers**: Open remote/virtual ports (`socket://`, `rfc2217://`, `loop://`, `spy://`, `cp2110://`) - **Dynamic Resources**: Read data via `serial://{port}/data` - Full pyserial support (baudrate, parity, stop bits, flow control) @@ -19,6 +20,9 @@ uvx mcserial # Or install directly uv pip install mcserial + +# With CP2110 HID-to-UART support +uv pip install mcserial[cp2110] ``` ## Usage with Claude Code @@ -43,17 +47,22 @@ Ports open in **RS-232 mode** by default. Switch with `set_port_mode()`: | Tool | Description | |------|-------------| -| `list_serial_ports` | Discover available serial ports | -| `open_serial_port` | Open connection (auto-detects baud if not specified) | +| `list_serial_ports` | Discover available ports (supports `grep` regex filtering) | +| `open_serial_port` | Open connection — local device or URL scheme (auto-detects baud if not specified) | | `close_serial_port` | Close a connection | | `set_port_mode` | Switch between RS-232 and RS-485 modes | | `write_serial` | Send text data | -| `write_serial_bytes` | Send raw bytes | +| `write_serial_bytes` | Send raw bytes (atomic single-syscall write) | | `read_serial` | Read available data | | `read_serial_line` | Read until newline | +| `read_serial_lines` | Batch read multiple lines | | `read_until` | Read until custom terminator | | `configure_serial` | Change port settings | | `flush_serial` | Clear buffers | +| `cancel_read` | Interrupt pending read operation | +| `cancel_write` | Interrupt pending write operation | +| `set_flow_control` | Manually gate XON/XOFF or RTS/CTS flow | +| `set_low_latency_mode` | Enable kernel low-latency mode (Linux) | | `get_connection_status` | List open connections with mode | | `detect_baud_rate` | Auto-detect baud rate | @@ -61,7 +70,7 @@ Ports open in **RS-232 mode** by default. Switch with `set_port_mode()`: | Tool | Description | |------|-------------| -| `get_modem_lines` | Read CTS, DSR, RI, CD, RTS, DTR states | +| `get_modem_lines` | Read CTS, DSR, RI, CD, RTS, DTR states + break condition | | `set_modem_lines` | Control RTS and DTR outputs | | `pulse_line` | Pulse RTS/DTR for reset sequences | | `send_break` | Send timed break signal | @@ -90,6 +99,22 @@ Ports open in **RS-232 mode** by default. Switch with `set_port_mode()`: - `ymodem` - Batch mode with filename/size - `zmodem` - Streaming, auto-resume (recommended) +## URL Handlers + +The `open_serial_port` tool accepts URL schemes in addition to local device paths: + +| Scheme | Description | Example | +|--------|-------------|---------| +| `socket://` | Raw TCP socket — serial-to-ethernet bridges | `socket://192.168.1.100:4001` | +| `rfc2217://` | Telnet COM Port Control — remote baud/flow config | `rfc2217://192.168.1.100:2217` | +| `loop://` | Loopback — writes echo back as reads (testing) | `loop://` | +| `spy://` | Debug wrapper — logs all traffic to stderr | `spy:///dev/ttyUSB0` | +| `cp2110://` | Silicon Labs HID-to-UART (requires `[cp2110]` extra) | `cp2110://` | +| `hwgrep://` | Open first port matching hardware pattern | `hwgrep://FTDI` | +| `alt://` | Alternate port backend | `alt:///dev/ttyUSB0` | + +URL-opened ports skip auto-baud detection and exclusive access (not applicable to virtual/network ports). + ## Resources | URI | Description | @@ -114,11 +139,19 @@ Ports open in **RS-232 mode** by default. Switch with `set_port_mode()`: ``` 1. list_serial_ports() → find /dev/ttyUSB0 2. open_serial_port(port="/dev/ttyUSB0") # auto-detects baud -3. write_serial(port="/dev/ttyUSB0", data="AT\r\n") -4. Read resource: serial:///dev/ttyUSB0/data +3. write_serial_bytes(port="/dev/ttyUSB0", data=[65, 84, 13, 10]) # AT\r\n +4. read_serial_lines(port="/dev/ttyUSB0") # batch read response 5. close_serial_port(port="/dev/ttyUSB0") ``` +### Filter Ports by Hardware + +``` +1. list_serial_ports(grep="FTDI") # find all FTDI devices +2. list_serial_ports(grep="CP210") # find Silicon Labs adapters +3. list_serial_ports(grep="VID:PID=0403:6001") # exact USB ID match +``` + ### RS-485 Modbus ``` @@ -128,6 +161,23 @@ Ports open in **RS-232 mode** by default. Switch with `set_port_mode()`: 4. rs485_transact(port="/dev/ttyUSB0", data="\x01\x03...") ``` +### Network Serial (serial-to-ethernet bridge) + +``` +1. open_serial_port(port="socket://192.168.1.100:4001", baudrate=115200) +2. write_serial(port="socket://192.168.1.100:4001", data="AT\r\n") +3. read_serial(port="socket://192.168.1.100:4001") +``` + +### Loopback Testing (no hardware needed) + +``` +1. open_serial_port(port="loop://", baudrate=9600) +2. write_serial(port="loop://", data="hello") +3. read_serial(port="loop://") # → "hello" +4. close_serial_port(port="loop://") +``` + ### File Transfer ``` diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..1c849a0 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,17 @@ +# build output +dist/ +# generated types +.astro/ + +# dependencies +node_modules/ + +# logs +npm-debug.log* + +# environment variables +.env +.env.production + +# macOS +.DS_Store diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 0000000..7818591 --- /dev/null +++ b/docs/Dockerfile @@ -0,0 +1,48 @@ +# syntax=docker/dockerfile:1 + +# ============================================ +# Base stage — Node 22 slim +# ============================================ +FROM node:22-slim AS base + +WORKDIR /app +COPY package.json package-lock.json ./ + +# ============================================ +# Development — hot reload +# ============================================ +FROM base AS dev + +RUN npm ci +COPY . . + +EXPOSE 4321 +CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0"] + +# ============================================ +# Build — static site generation +# ============================================ +FROM base AS build + +RUN npm ci +COPY . . + +ENV ASTRO_TELEMETRY_DISABLED=1 +RUN npm run build + +# ============================================ +# Production — Caddy serves static files +# ============================================ +FROM caddy:2-alpine AS prod + +COPY --from=build /app/dist /usr/share/caddy + +RUN echo ':80 { \ + root * /usr/share/caddy \ + encode gzip \ + try_files {path} {path}/ /index.html \ + file_server \ +}' > /etc/caddy/Caddyfile + +EXPOSE 80 +CMD ["caddy", "run", "--config", "/etc/caddy/Caddyfile"] diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..6d8d1b2 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,50 @@ +.PHONY: dev prod build logs stop clean restart shell local local-build + +.DEFAULT_GOAL := dev + +# Development mode with hot reload +dev: + @echo "Starting mcserial docs in development mode..." + APP_ENV=dev docker compose up -d --build + @echo "Site available at https://$(shell grep PUBLIC_DOMAIN .env | cut -d= -f2)" + @sleep 2 + docker compose logs -f + +# Production mode with static build +prod: + @echo "Starting mcserial docs in production mode..." + APP_ENV=prod docker compose up -d --build + @echo "Site available at https://$(shell grep PUBLIC_DOMAIN .env | cut -d= -f2)" + @sleep 2 + docker compose logs -f + +# Build without starting +build: + docker compose build + +# View logs +logs: + docker compose logs -f + +# Stop containers +stop: + docker compose down + +# Clean up containers, images, volumes +clean: + docker compose down -v --rmi local + +# Restart containers +restart: stop dev + +# Shell into running container +shell: + docker compose exec docs sh + +# Local development without Docker +local: + npm run dev + +# Production build locally +local-build: + npm run build && npm run preview diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs new file mode 100644 index 0000000..433ba13 --- /dev/null +++ b/docs/astro.config.mjs @@ -0,0 +1,76 @@ +// @ts-check +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + site: process.env.PUBLIC_DOMAIN + ? `https://${process.env.PUBLIC_DOMAIN}` + : 'http://localhost:4321', + + telemetry: false, + + devToolbar: { enabled: false }, + + vite: { + server: { + host: '0.0.0.0', + allowedHosts: process.env.PUBLIC_DOMAIN + ? [process.env.PUBLIC_DOMAIN, 'localhost'] + : ['localhost'], + ...(process.env.VITE_HMR_HOST && { + hmr: { + host: process.env.VITE_HMR_HOST, + protocol: 'wss', + clientPort: 443, + }, + }), + }, + }, + + integrations: [ + starlight({ + title: 'mcserial', + description: 'MCP server for serial port communication — RS-232, RS-485, and file transfers via Model Context Protocol', + + logo: { + src: './src/assets/logo.svg', + replacesTitle: false, + }, + + social: [ + { + icon: 'github', + label: 'GitHub', + href: 'https://github.com/supported-systems/mcserial', + }, + ], + + customCss: ['./src/styles/custom.css'], + + sidebar: [ + { + label: 'Overview', + items: [{ label: 'Introduction', link: '/' }], + }, + { + label: 'Tutorials', + autogenerate: { directory: 'tutorials' }, + }, + { + label: 'Guides', + autogenerate: { directory: 'guides' }, + }, + { + label: 'Reference', + autogenerate: { directory: 'reference' }, + }, + { + label: 'Concepts', + autogenerate: { directory: 'concepts' }, + }, + ], + + tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 }, + }), + ], +}); diff --git a/docs/docker-compose.yml b/docs/docker-compose.yml new file mode 100644 index 0000000..fc4f6cf --- /dev/null +++ b/docs/docker-compose.yml @@ -0,0 +1,35 @@ +services: + docs: + build: + context: . + target: ${APP_ENV:-dev} + restart: unless-stopped + environment: + - PUBLIC_DOMAIN=${PUBLIC_DOMAIN:-mcserial.l.zmesh.systems} + - VITE_HMR_HOST=${PUBLIC_DOMAIN:-mcserial.l.zmesh.systems} + - ASTRO_TELEMETRY_DISABLED=1 + volumes: + # Dev mode: mount source for hot reload + - ./src:/app/src:ro + - ./public:/app/public:ro + - ./astro.config.mjs:/app/astro.config.mjs:ro + networks: + - caddy + labels: + # Caddy reverse proxy + caddy: ${PUBLIC_DOMAIN:-mcserial.l.zmesh.systems} + caddy.reverse_proxy: "{{upstreams 4321}}" + + # WebSocket/HMR support for dev mode + caddy.reverse_proxy.flush_interval: "-1" + caddy.reverse_proxy.transport: "http" + caddy.reverse_proxy.transport.read_timeout: "0" + caddy.reverse_proxy.transport.write_timeout: "0" + caddy.reverse_proxy.transport.keepalive: "5m" + caddy.reverse_proxy.transport.keepalive_idle_conns: "10" + caddy.reverse_proxy.stream_timeout: "24h" + caddy.reverse_proxy.stream_close_delay: "5s" + +networks: + caddy: + external: true diff --git a/docs/package-lock.json b/docs/package-lock.json new file mode 100644 index 0000000..efe271b --- /dev/null +++ b/docs/package-lock.json @@ -0,0 +1,6394 @@ +{ + "name": "mcserial-docs", + "version": "0.0.1", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "mcserial-docs", + "version": "0.0.1", + "dependencies": { + "@astrojs/starlight": "^0.37.4", + "astro": "5.16.15", + "sharp": "^0.34.2" + } + }, + "node_modules/@astrojs/compiler": { + "version": "2.13.0", + "resolved": "https://registry.npmjs.org/@astrojs/compiler/-/compiler-2.13.0.tgz", + "integrity": "sha512-mqVORhUJViA28fwHYaWmsXSzLO9osbdZ5ImUfxBarqsYdMlPbqAqGJCxsNzvppp1BEzc1mJNjOVvQqeDN8Vspw==", + "license": "MIT" + }, + "node_modules/@astrojs/internal-helpers": { + "version": "0.7.5", + "resolved": "https://registry.npmjs.org/@astrojs/internal-helpers/-/internal-helpers-0.7.5.tgz", + "integrity": "sha512-vreGnYSSKhAjFJCWAwe/CNhONvoc5lokxtRoZims+0wa3KbHBdPHSSthJsKxPd8d/aic6lWKpRTYGY/hsgK6EA==", + "license": "MIT" + }, + "node_modules/@astrojs/markdown-remark": { + "version": "6.3.10", + "resolved": "https://registry.npmjs.org/@astrojs/markdown-remark/-/markdown-remark-6.3.10.tgz", + "integrity": "sha512-kk4HeYR6AcnzC4QV8iSlOfh+N8TZ3MEStxPyenyCtemqn8IpEATBFMTJcfrNW32dgpt6MY3oCkMM/Tv3/I4G3A==", + "license": "MIT", + "dependencies": { + "@astrojs/internal-helpers": "0.7.5", + "@astrojs/prism": "3.3.0", + "github-slugger": "^2.0.0", + "hast-util-from-html": "^2.0.3", + "hast-util-to-text": "^4.0.2", + "import-meta-resolve": "^4.2.0", + "js-yaml": "^4.1.1", + "mdast-util-definitions": "^6.0.0", + "rehype-raw": "^7.0.0", + "rehype-stringify": "^10.0.1", + "remark-gfm": "^4.0.1", + "remark-parse": "^11.0.0", + "remark-rehype": "^11.1.2", + "remark-smartypants": "^3.0.2", + "shiki": "^3.19.0", + "smol-toml": "^1.5.2", + "unified": "^11.0.5", + "unist-util-remove-position": "^5.0.0", + "unist-util-visit": "^5.0.0", + "unist-util-visit-parents": "^6.0.2", + "vfile": "^6.0.3" + } + }, + "node_modules/@astrojs/mdx": { + "version": "4.3.13", + "resolved": "https://registry.npmjs.org/@astrojs/mdx/-/mdx-4.3.13.tgz", + "integrity": "sha512-IHDHVKz0JfKBy3//52JSiyWv089b7GVSChIXLrlUOoTLWowG3wr2/8hkaEgEyd/vysvNQvGk+QhysXpJW5ve6Q==", + "license": "MIT", + "dependencies": { + "@astrojs/markdown-remark": "6.3.10", + "@mdx-js/mdx": "^3.1.1", + "acorn": "^8.15.0", + "es-module-lexer": "^1.7.0", + "estree-util-visit": "^2.0.0", + "hast-util-to-html": "^9.0.5", + "piccolore": "^0.1.3", + "rehype-raw": "^7.0.0", + "remark-gfm": "^4.0.1", + "remark-smartypants": "^3.0.2", + "source-map": "^0.7.6", + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.3" + }, + "engines": { + "node": "18.20.8 || ^20.3.0 || >=22.0.0" + }, + "peerDependencies": { + "astro": "^5.0.0" + } + }, + "node_modules/@astrojs/prism": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/@astrojs/prism/-/prism-3.3.0.tgz", + "integrity": "sha512-q8VwfU/fDZNoDOf+r7jUnMC2//H2l0TuQ6FkGJL8vD8nw/q5KiL3DS1KKBI3QhI9UQhpJ5dc7AtqfbXWuOgLCQ==", + "license": "MIT", + "dependencies": { + "prismjs": "^1.30.0" + }, + "engines": { + "node": "18.20.8 || ^20.3.0 || >=22.0.0" + } + }, + "node_modules/@astrojs/sitemap": { + "version": "3.7.0", + "resolved": "https://registry.npmjs.org/@astrojs/sitemap/-/sitemap-3.7.0.tgz", + "integrity": "sha512-+qxjUrz6Jcgh+D5VE1gKUJTA3pSthuPHe6Ao5JCxok794Lewx8hBFaWHtOnN0ntb2lfOf7gvOi9TefUswQ/ZVA==", + "license": "MIT", + "dependencies": { + "sitemap": "^8.0.2", + "stream-replace-string": "^2.0.0", + "zod": "^3.25.76" + } + }, + "node_modules/@astrojs/starlight": { + "version": "0.37.6", + "resolved": "https://registry.npmjs.org/@astrojs/starlight/-/starlight-0.37.6.tgz", + "integrity": "sha512-wQrKwH431q+8FsLBnNQeG+R36TMtEGxTQ2AuiVpcx9APcazvL3n7wVW8mMmYyxX0POjTnxlcWPkdMGR3Yj1L+w==", + "license": "MIT", + "dependencies": { + "@astrojs/markdown-remark": "^6.3.1", + "@astrojs/mdx": "^4.2.3", + "@astrojs/sitemap": "^3.3.0", + "@pagefind/default-ui": "^1.3.0", + "@types/hast": "^3.0.4", + "@types/js-yaml": "^4.0.9", + "@types/mdast": "^4.0.4", + "astro-expressive-code": "^0.41.1", + "bcp-47": "^2.1.0", + "hast-util-from-html": "^2.0.1", + "hast-util-select": "^6.0.2", + "hast-util-to-string": "^3.0.0", + "hastscript": "^9.0.0", + "i18next": "^23.11.5", + "js-yaml": "^4.1.0", + "klona": "^2.0.6", + "magic-string": "^0.30.17", + "mdast-util-directive": "^3.0.0", + "mdast-util-to-markdown": "^2.1.0", + "mdast-util-to-string": "^4.0.0", + "pagefind": "^1.3.0", + "rehype": "^13.0.1", + "rehype-format": "^5.0.0", + "remark-directive": "^3.0.0", + "ultrahtml": "^1.6.0", + "unified": "^11.0.5", + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.2" + }, + "peerDependencies": { + "astro": "^5.5.0" + } + }, + "node_modules/@astrojs/telemetry": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/@astrojs/telemetry/-/telemetry-3.3.0.tgz", + "integrity": "sha512-UFBgfeldP06qu6khs/yY+q1cDAaArM2/7AEIqQ9Cuvf7B1hNLq0xDrZkct+QoIGyjq56y8IaE2I3CTvG99mlhQ==", + "license": "MIT", + "dependencies": { + "ci-info": "^4.2.0", + "debug": "^4.4.0", + "dlv": "^1.1.3", + "dset": "^3.1.4", + "is-docker": "^3.0.0", + "is-wsl": "^3.1.0", + "which-pm-runs": "^1.1.0" + }, + "engines": { + "node": "18.20.8 || ^20.3.0 || >=22.0.0" + } + }, + "node_modules/@babel/helper-string-parser": { + "version": "7.27.1", + "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz", + "integrity": "sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==", + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-validator-identifier": { + "version": "7.28.5", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.28.5.tgz", + "integrity": "sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==", + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/parser": { + "version": "7.29.0", + "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.0.tgz", + "integrity": "sha512-IyDgFV5GeDUVX4YdF/3CPULtVGSXXMLh1xVIgdCgxApktqnQV0r7/8Nqthg+8YLGaAtdyIlo2qIdZrbCv4+7ww==", + "license": "MIT", + "dependencies": { + "@babel/types": "^7.29.0" + }, + "bin": { + "parser": "bin/babel-parser.js" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@babel/runtime": { + "version": "7.28.6", + "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.28.6.tgz", + "integrity": "sha512-05WQkdpL9COIMz4LjTxGpPNCdlpyimKppYNoJ5Di5EUObifl8t4tuLuUBBZEpoLYOmfvIWrsp9fCl0HoPRVTdA==", + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/types": { + "version": "7.29.0", + "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.0.tgz", + "integrity": "sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==", + "license": "MIT", + "dependencies": { + "@babel/helper-string-parser": "^7.27.1", + "@babel/helper-validator-identifier": "^7.28.5" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@capsizecss/unpack": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/@capsizecss/unpack/-/unpack-4.0.0.tgz", + "integrity": "sha512-VERIM64vtTP1C4mxQ5thVT9fK0apjPFobqybMtA1UdUujWka24ERHbRHFGmpbbhp73MhV+KSsHQH9C6uOTdEQA==", + "license": "MIT", + "dependencies": { + "fontkitten": "^1.0.0" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/@ctrl/tinycolor": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/@ctrl/tinycolor/-/tinycolor-4.2.0.tgz", + "integrity": "sha512-kzyuwOAQnXJNLS9PSyrk0CWk35nWJW/zl/6KvnTBMFK65gm7U1/Z5BqjxeapjZCIhQcM/DsrEmcbRwDyXyXK4A==", + "license": "MIT", + "engines": { + "node": ">=14" + } + }, + "node_modules/@emnapi/runtime": { + "version": "1.8.1", + "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.8.1.tgz", + "integrity": "sha512-mehfKSMWjjNol8659Z8KxEMrdSJDDot5SXMq00dM8BN4o+CLNXQ0xH2V7EchNHV4RmbZLmmPdEaXZc5H2FXmDg==", + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@esbuild/aix-ppc64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz", + "integrity": "sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==", + "cpu": [ + "ppc64" + ], + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.25.12.tgz", + "integrity": "sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg==", + "cpu": [ + "arm" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.25.12.tgz", + "integrity": "sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.25.12.tgz", + "integrity": "sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.25.12.tgz", + "integrity": "sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.25.12.tgz", + "integrity": "sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.12.tgz", + "integrity": "sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.25.12.tgz", + "integrity": "sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.25.12.tgz", + "integrity": "sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw==", + "cpu": [ + "arm" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.25.12.tgz", + "integrity": "sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ia32": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.25.12.tgz", + "integrity": "sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA==", + "cpu": [ + "ia32" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-loong64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.25.12.tgz", + "integrity": "sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng==", + "cpu": [ + "loong64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-mips64el": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.25.12.tgz", + "integrity": "sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw==", + "cpu": [ + "mips64el" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ppc64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.25.12.tgz", + "integrity": "sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA==", + "cpu": [ + "ppc64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-riscv64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.25.12.tgz", + "integrity": "sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w==", + "cpu": [ + "riscv64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-s390x": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.25.12.tgz", + "integrity": "sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg==", + "cpu": [ + "s390x" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.25.12.tgz", + "integrity": "sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.12.tgz", + "integrity": "sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.25.12.tgz", + "integrity": "sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.12.tgz", + "integrity": "sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.25.12.tgz", + "integrity": "sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openharmony-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.25.12.tgz", + "integrity": "sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/sunos-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.25.12.tgz", + "integrity": "sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.25.12.tgz", + "integrity": "sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-ia32": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.25.12.tgz", + "integrity": "sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ==", + "cpu": [ + "ia32" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.25.12.tgz", + "integrity": "sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@expressive-code/core": { + "version": "0.41.6", + "resolved": "https://registry.npmjs.org/@expressive-code/core/-/core-0.41.6.tgz", + "integrity": "sha512-FvJQP+hG0jWi/FLBSmvHInDqWR7jNANp9PUDjdMqSshHb0y7sxx3vHuoOr6SgXjWw+MGLqorZyPQ0aAlHEok6g==", + "license": "MIT", + "dependencies": { + "@ctrl/tinycolor": "^4.0.4", + "hast-util-select": "^6.0.2", + "hast-util-to-html": "^9.0.1", + "hast-util-to-text": "^4.0.1", + "hastscript": "^9.0.0", + "postcss": "^8.4.38", + "postcss-nested": "^6.0.1", + "unist-util-visit": "^5.0.0", + "unist-util-visit-parents": "^6.0.1" + } + }, + "node_modules/@expressive-code/plugin-frames": { + "version": "0.41.6", + "resolved": "https://registry.npmjs.org/@expressive-code/plugin-frames/-/plugin-frames-0.41.6.tgz", + "integrity": "sha512-d+hkSYXIQot6fmYnOmWAM+7TNWRv/dhfjMsNq+mIZz8Tb4mPHOcgcfZeEM5dV9TDL0ioQNvtcqQNuzA1sRPjxg==", + "license": "MIT", + "dependencies": { + "@expressive-code/core": "^0.41.6" + } + }, + "node_modules/@expressive-code/plugin-shiki": { + "version": "0.41.6", + "resolved": "https://registry.npmjs.org/@expressive-code/plugin-shiki/-/plugin-shiki-0.41.6.tgz", + "integrity": "sha512-Y6zmKBmsIUtWTzdefqlzm/h9Zz0Rc4gNdt2GTIH7fhHH2I9+lDYCa27BDwuBhjqcos6uK81Aca9dLUC4wzN+ng==", + "license": "MIT", + "dependencies": { + "@expressive-code/core": "^0.41.6", + "shiki": "^3.2.2" + } + }, + "node_modules/@expressive-code/plugin-text-markers": { + "version": "0.41.6", + "resolved": "https://registry.npmjs.org/@expressive-code/plugin-text-markers/-/plugin-text-markers-0.41.6.tgz", + "integrity": "sha512-PBFa1wGyYzRExMDzBmAWC6/kdfG1oLn4pLpBeTfIRrALPjcGA/59HP3e7q9J0Smk4pC7U+lWkA2LHR8FYV8U7Q==", + "license": "MIT", + "dependencies": { + "@expressive-code/core": "^0.41.6" + } + }, + "node_modules/@img/colour": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.0.0.tgz", + "integrity": "sha512-A5P/LfWGFSl6nsckYtjw9da+19jB8hkJ6ACTGcDfEJ0aE+l2n2El7dsVM7UVHZQ9s2lmYMWlrS21YLy2IR1LUw==", + "license": "MIT", + "engines": { + "node": ">=18" + } + }, + "node_modules/@img/sharp-darwin-arm64": { + "version": "0.34.5", + "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.34.5.tgz", + "integrity": "sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==", + "cpu": [ + "arm64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-darwin-arm64": "1.2.4" + } + }, + "node_modules/@img/sharp-darwin-x64": { + "version": "0.34.5", + "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.34.5.tgz", + "integrity": "sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==", + "cpu": [ + "x64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-darwin-x64": "1.2.4" + } + }, + "node_modules/@img/sharp-libvips-darwin-arm64": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.2.4.tgz", + "integrity": "sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==", + "cpu": [ + "arm64" + ], + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "darwin" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-darwin-x64": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.2.4.tgz", + "integrity": "sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==", + "cpu": [ + "x64" + ], + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "darwin" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-arm": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.2.4.tgz", + "integrity": "sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==", + "cpu": [ + "arm" + ], + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-arm64": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.2.4.tgz", + "integrity": "sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==", + "cpu": [ + "arm64" + ], + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-ppc64": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.2.4.tgz", + "integrity": "sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==", + "cpu": [ + "ppc64" + ], + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-riscv64": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.2.4.tgz", + "integrity": "sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==", + "cpu": [ + "riscv64" + ], + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-s390x": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.2.4.tgz", + "integrity": "sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==", + "cpu": [ + "s390x" + ], + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-x64": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.2.4.tgz", + "integrity": "sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==", + "cpu": [ + "x64" + ], + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linuxmusl-arm64": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.2.4.tgz", + "integrity": "sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==", + "cpu": [ + "arm64" + ], + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linuxmusl-x64": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.2.4.tgz", + "integrity": "sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==", + "cpu": [ + "x64" + ], + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-linux-arm": { + "version": "0.34.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.34.5.tgz", + "integrity": "sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==", + "cpu": [ + "arm" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-arm": "1.2.4" + } + }, + "node_modules/@img/sharp-linux-arm64": { + "version": "0.34.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.34.5.tgz", + "integrity": "sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==", + "cpu": [ + "arm64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-arm64": "1.2.4" + } + }, + "node_modules/@img/sharp-linux-ppc64": { + "version": "0.34.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.34.5.tgz", + "integrity": "sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==", + "cpu": [ + "ppc64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-ppc64": "1.2.4" + } + }, + "node_modules/@img/sharp-linux-riscv64": { + "version": "0.34.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.34.5.tgz", + "integrity": "sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==", + "cpu": [ + "riscv64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-riscv64": "1.2.4" + } + }, + "node_modules/@img/sharp-linux-s390x": { + "version": "0.34.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.34.5.tgz", + "integrity": "sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==", + "cpu": [ + "s390x" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-s390x": "1.2.4" + } + }, + "node_modules/@img/sharp-linux-x64": { + "version": "0.34.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.34.5.tgz", + "integrity": "sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==", + "cpu": [ + "x64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-x64": "1.2.4" + } + }, + "node_modules/@img/sharp-linuxmusl-arm64": { + "version": "0.34.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.34.5.tgz", + "integrity": "sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==", + "cpu": [ + "arm64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linuxmusl-arm64": "1.2.4" + } + }, + "node_modules/@img/sharp-linuxmusl-x64": { + "version": "0.34.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.34.5.tgz", + "integrity": "sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==", + "cpu": [ + "x64" + ], + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linuxmusl-x64": "1.2.4" + } + }, + "node_modules/@img/sharp-wasm32": { + "version": "0.34.5", + "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.34.5.tgz", + "integrity": "sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==", + "cpu": [ + "wasm32" + ], + "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT", + "optional": true, + "dependencies": { + "@emnapi/runtime": "^1.7.0" + }, + "engines": { + "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-win32-arm64": { + "version": "0.34.5", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.34.5.tgz", + "integrity": "sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==", + "cpu": [ + "arm64" + ], + "license": "Apache-2.0 AND LGPL-3.0-or-later", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-win32-ia32": { + "version": "0.34.5", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.34.5.tgz", + "integrity": "sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==", + "cpu": [ + "ia32" + ], + "license": "Apache-2.0 AND LGPL-3.0-or-later", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-win32-x64": { + "version": "0.34.5", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.34.5.tgz", + "integrity": "sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==", + "cpu": [ + "x64" + ], + "license": "Apache-2.0 AND LGPL-3.0-or-later", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@jridgewell/sourcemap-codec": { + "version": "1.5.5", + "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz", + "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==", + "license": "MIT" + }, + "node_modules/@mdx-js/mdx": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/@mdx-js/mdx/-/mdx-3.1.1.tgz", + "integrity": "sha512-f6ZO2ifpwAQIpzGWaBQT2TXxPv6z3RBzQKpVftEWN78Vl/YweF1uwussDx8ECAXVtr3Rs89fKyG9YlzUs9DyGQ==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdx": "^2.0.0", + "acorn": "^8.0.0", + "collapse-white-space": "^2.0.0", + "devlop": "^1.0.0", + "estree-util-is-identifier-name": "^3.0.0", + "estree-util-scope": "^1.0.0", + "estree-walker": "^3.0.0", + "hast-util-to-jsx-runtime": "^2.0.0", + "markdown-extensions": "^2.0.0", + "recma-build-jsx": "^1.0.0", + "recma-jsx": "^1.0.0", + "recma-stringify": "^1.0.0", + "rehype-recma": "^1.0.0", + "remark-mdx": "^3.0.0", + "remark-parse": "^11.0.0", + "remark-rehype": "^11.0.0", + "source-map": "^0.7.0", + "unified": "^11.0.0", + "unist-util-position-from-estree": "^2.0.0", + "unist-util-stringify-position": "^4.0.0", + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/@oslojs/encoding": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@oslojs/encoding/-/encoding-1.1.0.tgz", + "integrity": "sha512-70wQhgYmndg4GCPxPPxPGevRKqTIJ2Nh4OkiMWmDAVYsTQ+Ta7Sq+rPevXyXGdzr30/qZBnyOalCszoMxlyldQ==", + "license": "MIT" + }, + "node_modules/@pagefind/darwin-arm64": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/@pagefind/darwin-arm64/-/darwin-arm64-1.4.0.tgz", + "integrity": "sha512-2vMqkbv3lbx1Awea90gTaBsvpzgRs7MuSgKDxW0m9oV1GPZCZbZBJg/qL83GIUEN2BFlY46dtUZi54pwH+/pTQ==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@pagefind/darwin-x64": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/@pagefind/darwin-x64/-/darwin-x64-1.4.0.tgz", + "integrity": "sha512-e7JPIS6L9/cJfow+/IAqknsGqEPjJnVXGjpGm25bnq+NPdoD3c/7fAwr1OXkG4Ocjx6ZGSCijXEV4ryMcH2E3A==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@pagefind/default-ui": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/@pagefind/default-ui/-/default-ui-1.4.0.tgz", + "integrity": "sha512-wie82VWn3cnGEdIjh4YwNESyS1G6vRHwL6cNjy9CFgNnWW/PGRjsLq300xjVH5sfPFK3iK36UxvIBymtQIEiSQ==", + "license": "MIT" + }, + "node_modules/@pagefind/freebsd-x64": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/@pagefind/freebsd-x64/-/freebsd-x64-1.4.0.tgz", + "integrity": "sha512-WcJVypXSZ+9HpiqZjFXMUobfFfZZ6NzIYtkhQ9eOhZrQpeY5uQFqNWLCk7w9RkMUwBv1HAMDW3YJQl/8OqsV0Q==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ] + }, + "node_modules/@pagefind/linux-arm64": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/@pagefind/linux-arm64/-/linux-arm64-1.4.0.tgz", + "integrity": "sha512-PIt8dkqt4W06KGmQjONw7EZbhDF+uXI7i0XtRLN1vjCUxM9vGPdtJc2mUyVPevjomrGz5M86M8bqTr6cgDp1Uw==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@pagefind/linux-x64": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/@pagefind/linux-x64/-/linux-x64-1.4.0.tgz", + "integrity": "sha512-z4oddcWwQ0UHrTHR8psLnVlz6USGJ/eOlDPTDYZ4cI8TK8PgwRUPQZp9D2iJPNIPcS6Qx/E4TebjuGJOyK8Mmg==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@pagefind/windows-x64": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/@pagefind/windows-x64/-/windows-x64-1.4.0.tgz", + "integrity": "sha512-NkT+YAdgS2FPCn8mIA9bQhiBs+xmniMGq1LFPDhcFn0+2yIUEiIG06t7bsZlhdjknEQRTSdT7YitP6fC5qwP0g==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rollup/pluginutils": { + "version": "5.3.0", + "resolved": "https://registry.npmjs.org/@rollup/pluginutils/-/pluginutils-5.3.0.tgz", + "integrity": "sha512-5EdhGZtnu3V88ces7s53hhfK5KSASnJZv8Lulpc04cWO3REESroJXg73DFsOmgbU2BhwV0E20bu2IDZb3VKW4Q==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "estree-walker": "^2.0.2", + "picomatch": "^4.0.2" + }, + "engines": { + "node": ">=14.0.0" + }, + "peerDependencies": { + "rollup": "^1.20.0||^2.0.0||^3.0.0||^4.0.0" + }, + "peerDependenciesMeta": { + "rollup": { + "optional": true + } + } + }, + "node_modules/@rollup/pluginutils/node_modules/estree-walker": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-2.0.2.tgz", + "integrity": "sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==", + "license": "MIT" + }, + "node_modules/@rollup/rollup-android-arm-eabi": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.57.1.tgz", + "integrity": "sha512-A6ehUVSiSaaliTxai040ZpZ2zTevHYbvu/lDoeAteHI8QnaosIzm4qwtezfRg1jOYaUmnzLX1AOD6Z+UJjtifg==", + "cpu": [ + "arm" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ] + }, + "node_modules/@rollup/rollup-android-arm64": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.57.1.tgz", + "integrity": "sha512-dQaAddCY9YgkFHZcFNS/606Exo8vcLHwArFZ7vxXq4rigo2bb494/xKMMwRRQW6ug7Js6yXmBZhSBRuBvCCQ3w==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ] + }, + "node_modules/@rollup/rollup-darwin-arm64": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.57.1.tgz", + "integrity": "sha512-crNPrwJOrRxagUYeMn/DZwqN88SDmwaJ8Cvi/TN1HnWBU7GwknckyosC2gd0IqYRsHDEnXf328o9/HC6OkPgOg==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@rollup/rollup-darwin-x64": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.57.1.tgz", + "integrity": "sha512-Ji8g8ChVbKrhFtig5QBV7iMaJrGtpHelkB3lsaKzadFBe58gmjfGXAOfI5FV0lYMH8wiqsxKQ1C9B0YTRXVy4w==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@rollup/rollup-freebsd-arm64": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.57.1.tgz", + "integrity": "sha512-R+/WwhsjmwodAcz65guCGFRkMb4gKWTcIeLy60JJQbXrJ97BOXHxnkPFrP+YwFlaS0m+uWJTstrUA9o+UchFug==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ] + }, + "node_modules/@rollup/rollup-freebsd-x64": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.57.1.tgz", + "integrity": "sha512-IEQTCHeiTOnAUC3IDQdzRAGj3jOAYNr9kBguI7MQAAZK3caezRrg0GxAb6Hchg4lxdZEI5Oq3iov/w/hnFWY9Q==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ] + }, + "node_modules/@rollup/rollup-linux-arm-gnueabihf": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.57.1.tgz", + "integrity": "sha512-F8sWbhZ7tyuEfsmOxwc2giKDQzN3+kuBLPwwZGyVkLlKGdV1nvnNwYD0fKQ8+XS6hp9nY7B+ZeK01EBUE7aHaw==", + "cpu": [ + "arm" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-arm-musleabihf": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.57.1.tgz", + "integrity": "sha512-rGfNUfn0GIeXtBP1wL5MnzSj98+PZe/AXaGBCRmT0ts80lU5CATYGxXukeTX39XBKsxzFpEeK+Mrp9faXOlmrw==", + "cpu": [ + "arm" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-arm64-gnu": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.57.1.tgz", + "integrity": "sha512-MMtej3YHWeg/0klK2Qodf3yrNzz6CGjo2UntLvk2RSPlhzgLvYEB3frRvbEF2wRKh1Z2fDIg9KRPe1fawv7C+g==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-arm64-musl": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.57.1.tgz", + "integrity": "sha512-1a/qhaaOXhqXGpMFMET9VqwZakkljWHLmZOX48R0I/YLbhdxr1m4gtG1Hq7++VhVUmf+L3sTAf9op4JlhQ5u1Q==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-loong64-gnu": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.57.1.tgz", + "integrity": "sha512-QWO6RQTZ/cqYtJMtxhkRkidoNGXc7ERPbZN7dVW5SdURuLeVU7lwKMpo18XdcmpWYd0qsP1bwKPf7DNSUinhvA==", + "cpu": [ + "loong64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-loong64-musl": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.57.1.tgz", + "integrity": "sha512-xpObYIf+8gprgWaPP32xiN5RVTi/s5FCR+XMXSKmhfoJjrpRAjCuuqQXyxUa/eJTdAE6eJ+KDKaoEqjZQxh3Gw==", + "cpu": [ + "loong64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-ppc64-gnu": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.57.1.tgz", + "integrity": "sha512-4BrCgrpZo4hvzMDKRqEaW1zeecScDCR+2nZ86ATLhAoJ5FQ+lbHVD3ttKe74/c7tNT9c6F2viwB3ufwp01Oh2w==", + "cpu": [ + "ppc64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-ppc64-musl": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.57.1.tgz", + "integrity": "sha512-NOlUuzesGauESAyEYFSe3QTUguL+lvrN1HtwEEsU2rOwdUDeTMJdO5dUYl/2hKf9jWydJrO9OL/XSSf65R5+Xw==", + "cpu": [ + "ppc64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-riscv64-gnu": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.57.1.tgz", + "integrity": "sha512-ptA88htVp0AwUUqhVghwDIKlvJMD/fmL/wrQj99PRHFRAG6Z5nbWoWG4o81Nt9FT+IuqUQi+L31ZKAFeJ5Is+A==", + "cpu": [ + "riscv64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-riscv64-musl": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.57.1.tgz", + "integrity": "sha512-S51t7aMMTNdmAMPpBg7OOsTdn4tySRQvklmL3RpDRyknk87+Sp3xaumlatU+ppQ+5raY7sSTcC2beGgvhENfuw==", + "cpu": [ + "riscv64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-s390x-gnu": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.57.1.tgz", + "integrity": "sha512-Bl00OFnVFkL82FHbEqy3k5CUCKH6OEJL54KCyx2oqsmZnFTR8IoNqBF+mjQVcRCT5sB6yOvK8A37LNm/kPJiZg==", + "cpu": [ + "s390x" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-x64-gnu": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.57.1.tgz", + "integrity": "sha512-ABca4ceT4N+Tv/GtotnWAeXZUZuM/9AQyCyKYyKnpk4yoA7QIAuBt6Hkgpw8kActYlew2mvckXkvx0FfoInnLg==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-x64-musl": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.57.1.tgz", + "integrity": "sha512-HFps0JeGtuOR2convgRRkHCekD7j+gdAuXM+/i6kGzQtFhlCtQkpwtNzkNj6QhCDp7DRJ7+qC/1Vg2jt5iSOFw==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-openbsd-x64": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.57.1.tgz", + "integrity": "sha512-H+hXEv9gdVQuDTgnqD+SQffoWoc0Of59AStSzTEj/feWTBAnSfSD3+Dql1ZruJQxmykT/JVY0dE8Ka7z0DH1hw==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ] + }, + "node_modules/@rollup/rollup-openharmony-arm64": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.57.1.tgz", + "integrity": "sha512-4wYoDpNg6o/oPximyc/NG+mYUejZrCU2q+2w6YZqrAs2UcNUChIZXjtafAiiZSUc7On8v5NyNj34Kzj/Ltk6dQ==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ] + }, + "node_modules/@rollup/rollup-win32-arm64-msvc": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.57.1.tgz", + "integrity": "sha512-O54mtsV/6LW3P8qdTcamQmuC990HDfR71lo44oZMZlXU4tzLrbvTii87Ni9opq60ds0YzuAlEr/GNwuNluZyMQ==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rollup/rollup-win32-ia32-msvc": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.57.1.tgz", + "integrity": "sha512-P3dLS+IerxCT/7D2q2FYcRdWRl22dNbrbBEtxdWhXrfIMPP9lQhb5h4Du04mdl5Woq05jVCDPCMF7Ub0NAjIew==", + "cpu": [ + "ia32" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rollup/rollup-win32-x64-gnu": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.57.1.tgz", + "integrity": "sha512-VMBH2eOOaKGtIJYleXsi2B8CPVADrh+TyNxJ4mWPnKfLB/DBUmzW+5m1xUrcwWoMfSLagIRpjUFeW5CO5hyciQ==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rollup/rollup-win32-x64-msvc": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.57.1.tgz", + "integrity": "sha512-mxRFDdHIWRxg3UfIIAwCm6NzvxG0jDX/wBN6KsQFTvKFqqg9vTrWUE68qEjHt19A5wwx5X5aUi2zuZT7YR0jrA==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@shikijs/core": { + "version": "3.22.0", + "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-3.22.0.tgz", + "integrity": "sha512-iAlTtSDDbJiRpvgL5ugKEATDtHdUVkqgHDm/gbD2ZS9c88mx7G1zSYjjOxp5Qa0eaW0MAQosFRmJSk354PRoQA==", + "license": "MIT", + "dependencies": { + "@shikijs/types": "3.22.0", + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4", + "hast-util-to-html": "^9.0.5" + } + }, + "node_modules/@shikijs/engine-javascript": { + "version": "3.22.0", + "resolved": "https://registry.npmjs.org/@shikijs/engine-javascript/-/engine-javascript-3.22.0.tgz", + "integrity": "sha512-jdKhfgW9CRtj3Tor0L7+yPwdG3CgP7W+ZEqSsojrMzCjD1e0IxIbwUMDDpYlVBlC08TACg4puwFGkZfLS+56Tw==", + "license": "MIT", + "dependencies": { + "@shikijs/types": "3.22.0", + "@shikijs/vscode-textmate": "^10.0.2", + "oniguruma-to-es": "^4.3.4" + } + }, + "node_modules/@shikijs/engine-oniguruma": { + "version": "3.22.0", + "resolved": "https://registry.npmjs.org/@shikijs/engine-oniguruma/-/engine-oniguruma-3.22.0.tgz", + "integrity": "sha512-DyXsOG0vGtNtl7ygvabHd7Mt5EY8gCNqR9Y7Lpbbd/PbJvgWrqaKzH1JW6H6qFkuUa8aCxoiYVv8/YfFljiQxA==", + "license": "MIT", + "dependencies": { + "@shikijs/types": "3.22.0", + "@shikijs/vscode-textmate": "^10.0.2" + } + }, + "node_modules/@shikijs/langs": { + "version": "3.22.0", + "resolved": "https://registry.npmjs.org/@shikijs/langs/-/langs-3.22.0.tgz", + "integrity": "sha512-x/42TfhWmp6H00T6uwVrdTJGKgNdFbrEdhaDwSR5fd5zhQ1Q46bHq9EO61SCEWJR0HY7z2HNDMaBZp8JRmKiIA==", + "license": "MIT", + "dependencies": { + "@shikijs/types": "3.22.0" + } + }, + "node_modules/@shikijs/themes": { + "version": "3.22.0", + "resolved": "https://registry.npmjs.org/@shikijs/themes/-/themes-3.22.0.tgz", + "integrity": "sha512-o+tlOKqsr6FE4+mYJG08tfCFDS+3CG20HbldXeVoyP+cYSUxDhrFf3GPjE60U55iOkkjbpY2uC3It/eeja35/g==", + "license": "MIT", + "dependencies": { + "@shikijs/types": "3.22.0" + } + }, + "node_modules/@shikijs/types": { + "version": "3.22.0", + "resolved": "https://registry.npmjs.org/@shikijs/types/-/types-3.22.0.tgz", + "integrity": "sha512-491iAekgKDBFE67z70Ok5a8KBMsQ2IJwOWw3us/7ffQkIBCyOQfm/aNwVMBUriP02QshIfgHCBSIYAl3u2eWjg==", + "license": "MIT", + "dependencies": { + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4" + } + }, + "node_modules/@shikijs/vscode-textmate": { + "version": "10.0.2", + "resolved": "https://registry.npmjs.org/@shikijs/vscode-textmate/-/vscode-textmate-10.0.2.tgz", + "integrity": "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==", + "license": "MIT" + }, + "node_modules/@types/debug": { + "version": "4.1.12", + "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.12.tgz", + "integrity": "sha512-vIChWdVG3LG1SMxEvI/AK+FWJthlrqlTu7fbrlywTkkaONwk/UAGaULXRlf8vkzFBLVm0zkMdCquhL5aOjhXPQ==", + "license": "MIT", + "dependencies": { + "@types/ms": "*" + } + }, + "node_modules/@types/estree": { + "version": "1.0.8", + "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz", + "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==", + "license": "MIT" + }, + "node_modules/@types/estree-jsx": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/@types/estree-jsx/-/estree-jsx-1.0.5.tgz", + "integrity": "sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==", + "license": "MIT", + "dependencies": { + "@types/estree": "*" + } + }, + "node_modules/@types/hast": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.4.tgz", + "integrity": "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==", + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, + "node_modules/@types/js-yaml": { + "version": "4.0.9", + "resolved": "https://registry.npmjs.org/@types/js-yaml/-/js-yaml-4.0.9.tgz", + "integrity": "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==", + "license": "MIT" + }, + "node_modules/@types/mdast": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-4.0.4.tgz", + "integrity": "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==", + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, + "node_modules/@types/mdx": { + "version": "2.0.13", + "resolved": "https://registry.npmjs.org/@types/mdx/-/mdx-2.0.13.tgz", + "integrity": "sha512-+OWZQfAYyio6YkJb3HLxDrvnx6SWWDbC0zVPfBRzUk0/nqoDyf6dNxQi3eArPe8rJ473nobTMQ/8Zk+LxJ+Yuw==", + "license": "MIT" + }, + "node_modules/@types/ms": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/@types/ms/-/ms-2.1.0.tgz", + "integrity": "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==", + "license": "MIT" + }, + "node_modules/@types/nlcst": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/@types/nlcst/-/nlcst-2.0.3.tgz", + "integrity": "sha512-vSYNSDe6Ix3q+6Z7ri9lyWqgGhJTmzRjZRqyq15N0Z/1/UnVsno9G/N40NBijoYx2seFDIl0+B2mgAb9mezUCA==", + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, + "node_modules/@types/node": { + "version": "25.2.0", + "resolved": "https://registry.npmjs.org/@types/node/-/node-25.2.0.tgz", + "integrity": "sha512-DZ8VwRFUNzuqJ5khrvwMXHmvPe+zGayJhr2CDNiKB1WBE1ST8Djl00D0IC4vvNmHMdj6DlbYRIaFE7WHjlDl5w==", + "license": "MIT", + "dependencies": { + "undici-types": "~7.16.0" + } + }, + "node_modules/@types/sax": { + "version": "1.2.7", + "resolved": "https://registry.npmjs.org/@types/sax/-/sax-1.2.7.tgz", + "integrity": "sha512-rO73L89PJxeYM3s3pPPjiPgVVcymqU490g0YO5n5By0k2Erzj6tay/4lr1CHAAU4JyOWd1rpQ8bCf6cZfHU96A==", + "license": "MIT", + "dependencies": { + "@types/node": "*" + } + }, + "node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "license": "MIT" + }, + "node_modules/@ungap/structured-clone": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/@ungap/structured-clone/-/structured-clone-1.3.0.tgz", + "integrity": "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==", + "license": "ISC" + }, + "node_modules/acorn": { + "version": "8.15.0", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz", + "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==", + "license": "MIT", + "bin": { + "acorn": "bin/acorn" + }, + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/acorn-jsx": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/acorn-jsx/-/acorn-jsx-5.3.2.tgz", + "integrity": "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==", + "license": "MIT", + "peerDependencies": { + "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" + } + }, + "node_modules/ansi-align": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/ansi-align/-/ansi-align-3.0.1.tgz", + "integrity": "sha512-IOfwwBF5iczOjp/WeY4YxyjqAFMQoZufdQWDd19SEExbVLNXqvpzSJ/M7Za4/sCPmQ0+GRquoA7bGcINcxew6w==", + "license": "ISC", + "dependencies": { + "string-width": "^4.1.0" + } + }, + "node_modules/ansi-align/node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/ansi-align/node_modules/emoji-regex": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", + "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", + "license": "MIT" + }, + "node_modules/ansi-align/node_modules/string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "license": "MIT", + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/ansi-align/node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "license": "MIT", + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/ansi-regex": { + "version": "6.2.2", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz", + "integrity": "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==", + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-regex?sponsor=1" + } + }, + "node_modules/ansi-styles": { + "version": "6.2.3", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz", + "integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==", + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/anymatch": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/anymatch/-/anymatch-3.1.3.tgz", + "integrity": "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw==", + "license": "ISC", + "dependencies": { + "normalize-path": "^3.0.0", + "picomatch": "^2.0.4" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/anymatch/node_modules/picomatch": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", + "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", + "license": "MIT", + "engines": { + "node": ">=8.6" + }, + "funding": { + "url": "https://github.com/sponsors/jonschlinkert" + } + }, + "node_modules/arg": { + "version": "5.0.2", + "resolved": "https://registry.npmjs.org/arg/-/arg-5.0.2.tgz", + "integrity": "sha512-PYjyFOLKQ9y57JvQ6QLo8dAgNqswh8M1RMJYdQduT6xbWSgK36P/Z/v+p888pM69jMMfS8Xd8F6I1kQ/I9HUGg==", + "license": "MIT" + }, + "node_modules/argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "license": "Python-2.0" + }, + "node_modules/aria-query": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/aria-query/-/aria-query-5.3.2.tgz", + "integrity": "sha512-COROpnaoap1E2F000S62r6A60uHZnmlvomhfyT2DlTcrY1OrBKn2UhH7qn5wTC9zMvD0AY7csdPSNwKP+7WiQw==", + "license": "Apache-2.0", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/array-iterate": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/array-iterate/-/array-iterate-2.0.1.tgz", + "integrity": "sha512-I1jXZMjAgCMmxT4qxXfPXa6SthSoE8h6gkSI9BGGNv8mP8G/v0blc+qFnZu6K42vTOiuME596QaLO0TP3Lk0xg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/astring": { + "version": "1.9.0", + "resolved": "https://registry.npmjs.org/astring/-/astring-1.9.0.tgz", + "integrity": "sha512-LElXdjswlqjWrPpJFg1Fx4wpkOCxj1TDHlSV4PlaRxHGWko024xICaa97ZkMfs6DRKlCguiAI+rbXv5GWwXIkg==", + "license": "MIT", + "bin": { + "astring": "bin/astring" + } + }, + "node_modules/astro": { + "version": "5.16.15", + "resolved": "https://registry.npmjs.org/astro/-/astro-5.16.15.tgz", + "integrity": "sha512-+X1Z0NTi2pa5a0Te6h77Dgc44fYj63j1yx6+39Nvg05lExajxSq7b1Uj/gtY45zoum8fD0+h0nak+DnHighs3A==", + "license": "MIT", + "dependencies": { + "@astrojs/compiler": "^2.13.0", + "@astrojs/internal-helpers": "0.7.5", + "@astrojs/markdown-remark": "6.3.10", + "@astrojs/telemetry": "3.3.0", + "@capsizecss/unpack": "^4.0.0", + "@oslojs/encoding": "^1.1.0", + "@rollup/pluginutils": "^5.3.0", + "acorn": "^8.15.0", + "aria-query": "^5.3.2", + "axobject-query": "^4.1.0", + "boxen": "8.0.1", + "ci-info": "^4.3.1", + "clsx": "^2.1.1", + "common-ancestor-path": "^1.0.1", + "cookie": "^1.1.1", + "cssesc": "^3.0.0", + "debug": "^4.4.3", + "deterministic-object-hash": "^2.0.2", + "devalue": "^5.6.2", + "diff": "^8.0.3", + "dlv": "^1.1.3", + "dset": "^3.1.4", + "es-module-lexer": "^1.7.0", + "esbuild": "^0.25.0", + "estree-walker": "^3.0.3", + "flattie": "^1.1.1", + "fontace": "~0.4.0", + "github-slugger": "^2.0.0", + "html-escaper": "3.0.3", + "http-cache-semantics": "^4.2.0", + "import-meta-resolve": "^4.2.0", + "js-yaml": "^4.1.1", + "magic-string": "^0.30.21", + "magicast": "^0.5.1", + "mrmime": "^2.0.1", + "neotraverse": "^0.6.18", + "p-limit": "^6.2.0", + "p-queue": "^8.1.1", + "package-manager-detector": "^1.6.0", + "piccolore": "^0.1.3", + "picomatch": "^4.0.3", + "prompts": "^2.4.2", + "rehype": "^13.0.2", + "semver": "^7.7.3", + "shiki": "^3.21.0", + "smol-toml": "^1.6.0", + "svgo": "^4.0.0", + "tinyexec": "^1.0.2", + "tinyglobby": "^0.2.15", + "tsconfck": "^3.1.6", + "ultrahtml": "^1.6.0", + "unifont": "~0.7.3", + "unist-util-visit": "^5.0.0", + "unstorage": "^1.17.4", + "vfile": "^6.0.3", + "vite": "^6.4.1", + "vitefu": "^1.1.1", + "xxhash-wasm": "^1.1.0", + "yargs-parser": "^21.1.1", + "yocto-spinner": "^0.2.3", + "zod": "^3.25.76", + "zod-to-json-schema": "^3.25.1", + "zod-to-ts": "^1.2.0" + }, + "bin": { + "astro": "astro.js" + }, + "engines": { + "node": "18.20.8 || ^20.3.0 || >=22.0.0", + "npm": ">=9.6.5", + "pnpm": ">=7.1.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/astrodotbuild" + }, + "optionalDependencies": { + "sharp": "^0.34.0" + } + }, + "node_modules/astro-expressive-code": { + "version": "0.41.6", + "resolved": "https://registry.npmjs.org/astro-expressive-code/-/astro-expressive-code-0.41.6.tgz", + "integrity": "sha512-l47tb1uhmVIebHUkw+HEPtU/av0G4O8Q34g2cbkPvC7/e9ZhANcjUUciKt9Hp6gSVDdIuXBBLwJQn2LkeGMOAw==", + "license": "MIT", + "dependencies": { + "rehype-expressive-code": "^0.41.6" + }, + "peerDependencies": { + "astro": "^4.0.0-beta || ^5.0.0-beta || ^3.3.0 || ^6.0.0-beta" + } + }, + "node_modules/axobject-query": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/axobject-query/-/axobject-query-4.1.0.tgz", + "integrity": "sha512-qIj0G9wZbMGNLjLmg1PT6v2mE9AH2zlnADJD/2tC6E00hgmhUOfEB6greHPAfLRSufHqROIUTkw6E+M3lH0PTQ==", + "license": "Apache-2.0", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/bail": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/bail/-/bail-2.0.2.tgz", + "integrity": "sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/base-64": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/base-64/-/base-64-1.0.0.tgz", + "integrity": "sha512-kwDPIFCGx0NZHog36dj+tHiwP4QMzsZ3AgMViUBKI0+V5n4U0ufTCUMhnQ04diaRI8EX/QcPfql7zlhZ7j4zgg==", + "license": "MIT" + }, + "node_modules/bcp-47": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/bcp-47/-/bcp-47-2.1.0.tgz", + "integrity": "sha512-9IIS3UPrvIa1Ej+lVDdDwO7zLehjqsaByECw0bu2RRGP73jALm6FYbzI5gWbgHLvNdkvfXB5YrSbocZdOS0c0w==", + "license": "MIT", + "dependencies": { + "is-alphabetical": "^2.0.0", + "is-alphanumerical": "^2.0.0", + "is-decimal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/bcp-47-match": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/bcp-47-match/-/bcp-47-match-2.0.3.tgz", + "integrity": "sha512-JtTezzbAibu8G0R9op9zb3vcWZd9JF6M0xOYGPn0fNCd7wOpRB1mU2mH9T8gaBGbAAyIIVgB2G7xG0GP98zMAQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/boolbase": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/boolbase/-/boolbase-1.0.0.tgz", + "integrity": "sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==", + "license": "ISC" + }, + "node_modules/boxen": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/boxen/-/boxen-8.0.1.tgz", + "integrity": "sha512-F3PH5k5juxom4xktynS7MoFY+NUWH5LC4CnH11YB8NPew+HLpmBLCybSAEyb2F+4pRXhuhWqFesoQd6DAyc2hw==", + "license": "MIT", + "dependencies": { + "ansi-align": "^3.0.1", + "camelcase": "^8.0.0", + "chalk": "^5.3.0", + "cli-boxes": "^3.0.0", + "string-width": "^7.2.0", + "type-fest": "^4.21.0", + "widest-line": "^5.0.0", + "wrap-ansi": "^9.0.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/camelcase": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-8.0.0.tgz", + "integrity": "sha512-8WB3Jcas3swSvjIeA2yvCJ+Miyz5l1ZmB6HFb9R1317dt9LCQoswg/BGrmAmkWVEszSrrg4RwmO46qIm2OEnSA==", + "license": "MIT", + "engines": { + "node": ">=16" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/ccount": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/ccount/-/ccount-2.0.1.tgz", + "integrity": "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/chalk": { + "version": "5.6.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-5.6.2.tgz", + "integrity": "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==", + "license": "MIT", + "engines": { + "node": "^12.17.0 || ^14.13 || >=16.0.0" + }, + "funding": { + "url": "https://github.com/chalk/chalk?sponsor=1" + } + }, + "node_modules/character-entities": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/character-entities/-/character-entities-2.0.2.tgz", + "integrity": "sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities-html4": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/character-entities-html4/-/character-entities-html4-2.1.0.tgz", + "integrity": "sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities-legacy": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/character-entities-legacy/-/character-entities-legacy-3.0.0.tgz", + "integrity": "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-reference-invalid": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/character-reference-invalid/-/character-reference-invalid-2.0.1.tgz", + "integrity": "sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/chokidar": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-5.0.0.tgz", + "integrity": "sha512-TQMmc3w+5AxjpL8iIiwebF73dRDF4fBIieAqGn9RGCWaEVwQ6Fb2cGe31Yns0RRIzii5goJ1Y7xbMwo1TxMplw==", + "license": "MIT", + "dependencies": { + "readdirp": "^5.0.0" + }, + "engines": { + "node": ">= 20.19.0" + }, + "funding": { + "url": "https://paulmillr.com/funding/" + } + }, + "node_modules/ci-info": { + "version": "4.4.0", + "resolved": "https://registry.npmjs.org/ci-info/-/ci-info-4.4.0.tgz", + "integrity": "sha512-77PSwercCZU2Fc4sX94eF8k8Pxte6JAwL4/ICZLFjJLqegs7kCuAsqqj/70NQF6TvDpgFjkubQB2FW2ZZddvQg==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/sibiraj-s" + } + ], + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/cli-boxes": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/cli-boxes/-/cli-boxes-3.0.0.tgz", + "integrity": "sha512-/lzGpEWL/8PfI0BmBOPRwp0c/wFNX1RdUML3jK/RcSBA9T8mZDdQpqYBKtCFTOfQbwPqWEOpjqW+Fnayc0969g==", + "license": "MIT", + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/clsx": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz", + "integrity": "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==", + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/collapse-white-space": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/collapse-white-space/-/collapse-white-space-2.1.0.tgz", + "integrity": "sha512-loKTxY1zCOuG4j9f6EPnuyyYkf58RnhhWTvRoZEokgB+WbdXehfjFviyOVYkqzEWz1Q5kRiZdBYS5SwxbQYwzw==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/comma-separated-tokens": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/comma-separated-tokens/-/comma-separated-tokens-2.0.3.tgz", + "integrity": "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/commander": { + "version": "11.1.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-11.1.0.tgz", + "integrity": "sha512-yPVavfyCcRhmorC7rWlkHn15b4wDVgVmBA7kV4QVBsF7kv/9TKJAbAXVTxvTnwP8HHKjRCJDClKbciiYS7p0DQ==", + "license": "MIT", + "engines": { + "node": ">=16" + } + }, + "node_modules/common-ancestor-path": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/common-ancestor-path/-/common-ancestor-path-1.0.1.tgz", + "integrity": "sha512-L3sHRo1pXXEqX8VU28kfgUY+YGsk09hPqZiZmLacNib6XNTCM8ubYeT7ryXQw8asB1sKgcU5lkB7ONug08aB8w==", + "license": "ISC" + }, + "node_modules/cookie": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-1.1.1.tgz", + "integrity": "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/cookie-es": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/cookie-es/-/cookie-es-1.2.2.tgz", + "integrity": "sha512-+W7VmiVINB+ywl1HGXJXmrqkOhpKrIiVZV6tQuV54ZyQC7MMuBt81Vc336GMLoHBq5hV/F9eXgt5Mnx0Rha5Fg==", + "license": "MIT" + }, + "node_modules/crossws": { + "version": "0.3.5", + "resolved": "https://registry.npmjs.org/crossws/-/crossws-0.3.5.tgz", + "integrity": "sha512-ojKiDvcmByhwa8YYqbQI/hg7MEU0NC03+pSdEq4ZUnZR9xXpwk7E43SMNGkn+JxJGPFtNvQ48+vV2p+P1ml5PA==", + "license": "MIT", + "dependencies": { + "uncrypto": "^0.1.3" + } + }, + "node_modules/css-select": { + "version": "5.2.2", + "resolved": "https://registry.npmjs.org/css-select/-/css-select-5.2.2.tgz", + "integrity": "sha512-TizTzUddG/xYLA3NXodFM0fSbNizXjOKhqiQQwvhlspadZokn1KDy0NZFS0wuEubIYAV5/c1/lAr0TaaFXEXzw==", + "license": "BSD-2-Clause", + "dependencies": { + "boolbase": "^1.0.0", + "css-what": "^6.1.0", + "domhandler": "^5.0.2", + "domutils": "^3.0.1", + "nth-check": "^2.0.1" + }, + "funding": { + "url": "https://github.com/sponsors/fb55" + } + }, + "node_modules/css-selector-parser": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/css-selector-parser/-/css-selector-parser-3.3.0.tgz", + "integrity": "sha512-Y2asgMGFqJKF4fq4xHDSlFYIkeVfRsm69lQC1q9kbEsH5XtnINTMrweLkjYMeaUgiXBy/uvKeO/a1JHTNnmB2g==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/mdevils" + }, + { + "type": "patreon", + "url": "https://patreon.com/mdevils" + } + ], + "license": "MIT" + }, + "node_modules/css-tree": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/css-tree/-/css-tree-3.1.0.tgz", + "integrity": "sha512-0eW44TGN5SQXU1mWSkKwFstI/22X2bG1nYzZTYMAWjylYURhse752YgbE4Cx46AC+bAvI+/dYTPRk1LqSUnu6w==", + "license": "MIT", + "dependencies": { + "mdn-data": "2.12.2", + "source-map-js": "^1.0.1" + }, + "engines": { + "node": "^10 || ^12.20.0 || ^14.13.0 || >=15.0.0" + } + }, + "node_modules/css-what": { + "version": "6.2.2", + "resolved": "https://registry.npmjs.org/css-what/-/css-what-6.2.2.tgz", + "integrity": "sha512-u/O3vwbptzhMs3L1fQE82ZSLHQQfto5gyZzwteVIEyeaY5Fc7R4dapF/BvRoSYFeqfBk4m0V1Vafq5Pjv25wvA==", + "license": "BSD-2-Clause", + "engines": { + "node": ">= 6" + }, + "funding": { + "url": "https://github.com/sponsors/fb55" + } + }, + "node_modules/cssesc": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/cssesc/-/cssesc-3.0.0.tgz", + "integrity": "sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==", + "license": "MIT", + "bin": { + "cssesc": "bin/cssesc" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/csso": { + "version": "5.0.5", + "resolved": "https://registry.npmjs.org/csso/-/csso-5.0.5.tgz", + "integrity": "sha512-0LrrStPOdJj+SPCCrGhzryycLjwcgUSHBtxNA8aIDxf0GLsRh1cKYhB00Gd1lDOS4yGH69+SNn13+TWbVHETFQ==", + "license": "MIT", + "dependencies": { + "css-tree": "~2.2.0" + }, + "engines": { + "node": "^10 || ^12.20.0 || ^14.13.0 || >=15.0.0", + "npm": ">=7.0.0" + } + }, + "node_modules/csso/node_modules/css-tree": { + "version": "2.2.1", + "resolved": "https://registry.npmjs.org/css-tree/-/css-tree-2.2.1.tgz", + "integrity": "sha512-OA0mILzGc1kCOCSJerOeqDxDQ4HOh+G8NbOJFOTgOCzpw7fCBubk0fEyxp8AgOL/jvLgYA/uV0cMbe43ElF1JA==", + "license": "MIT", + "dependencies": { + "mdn-data": "2.0.28", + "source-map-js": "^1.0.1" + }, + "engines": { + "node": "^10 || ^12.20.0 || ^14.13.0 || >=15.0.0", + "npm": ">=7.0.0" + } + }, + "node_modules/csso/node_modules/mdn-data": { + "version": "2.0.28", + "resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-2.0.28.tgz", + "integrity": "sha512-aylIc7Z9y4yzHYAJNuESG3hfhC+0Ibp/MAMiaOZgNv4pmEdFyfZhhhny4MNiAfWdBQ1RQ2mfDWmM1x8SvGyp8g==", + "license": "CC0-1.0" + }, + "node_modules/debug": { + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", + "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", + "license": "MIT", + "dependencies": { + "ms": "^2.1.3" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/decode-named-character-reference": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.3.0.tgz", + "integrity": "sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==", + "license": "MIT", + "dependencies": { + "character-entities": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/defu": { + "version": "6.1.4", + "resolved": "https://registry.npmjs.org/defu/-/defu-6.1.4.tgz", + "integrity": "sha512-mEQCMmwJu317oSz8CwdIOdwf3xMif1ttiM8LTufzc3g6kR+9Pe236twL8j3IYT1F7GfRgGcW6MWxzZjLIkuHIg==", + "license": "MIT" + }, + "node_modules/dequal": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz", + "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==", + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/destr": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/destr/-/destr-2.0.5.tgz", + "integrity": "sha512-ugFTXCtDZunbzasqBxrK93Ik/DRYsO6S/fedkWEMKqt04xZ4csmnmwGDBAb07QWNaGMAmnTIemsYZCksjATwsA==", + "license": "MIT" + }, + "node_modules/detect-libc": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz", + "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==", + "license": "Apache-2.0", + "engines": { + "node": ">=8" + } + }, + "node_modules/deterministic-object-hash": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/deterministic-object-hash/-/deterministic-object-hash-2.0.2.tgz", + "integrity": "sha512-KxektNH63SrbfUyDiwXqRb1rLwKt33AmMv+5Nhsw1kqZ13SJBRTgZHtGbE+hH3a1mVW1cz+4pqSWVPAtLVXTzQ==", + "license": "MIT", + "dependencies": { + "base-64": "^1.0.0" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/devalue": { + "version": "5.6.2", + "resolved": "https://registry.npmjs.org/devalue/-/devalue-5.6.2.tgz", + "integrity": "sha512-nPRkjWzzDQlsejL1WVifk5rvcFi/y1onBRxjaFMjZeR9mFpqu2gmAZ9xUB9/IEanEP/vBtGeGganC/GO1fmufg==", + "license": "MIT" + }, + "node_modules/devlop": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/devlop/-/devlop-1.1.0.tgz", + "integrity": "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==", + "license": "MIT", + "dependencies": { + "dequal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/diff": { + "version": "8.0.3", + "resolved": "https://registry.npmjs.org/diff/-/diff-8.0.3.tgz", + "integrity": "sha512-qejHi7bcSD4hQAZE0tNAawRK1ZtafHDmMTMkrrIGgSLl7hTnQHmKCeB45xAcbfTqK2zowkM3j3bHt/4b/ARbYQ==", + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.3.1" + } + }, + "node_modules/direction": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/direction/-/direction-2.0.1.tgz", + "integrity": "sha512-9S6m9Sukh1cZNknO1CWAr2QAWsbKLafQiyM5gZ7VgXHeuaoUwffKN4q6NC4A/Mf9iiPlOXQEKW/Mv/mh9/3YFA==", + "license": "MIT", + "bin": { + "direction": "cli.js" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/dlv": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/dlv/-/dlv-1.1.3.tgz", + "integrity": "sha512-+HlytyjlPKnIG8XuRG8WvmBP8xs8P71y+SKKS6ZXWoEgLuePxtDoUEiH7WkdePWrQ5JBpE6aoVqfZfJUQkjXwA==", + "license": "MIT" + }, + "node_modules/dom-serializer": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/dom-serializer/-/dom-serializer-2.0.0.tgz", + "integrity": "sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg==", + "license": "MIT", + "dependencies": { + "domelementtype": "^2.3.0", + "domhandler": "^5.0.2", + "entities": "^4.2.0" + }, + "funding": { + "url": "https://github.com/cheeriojs/dom-serializer?sponsor=1" + } + }, + "node_modules/dom-serializer/node_modules/entities": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz", + "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", + "license": "BSD-2-Clause", + "engines": { + "node": ">=0.12" + }, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, + "node_modules/domelementtype": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/domelementtype/-/domelementtype-2.3.0.tgz", + "integrity": "sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/fb55" + } + ], + "license": "BSD-2-Clause" + }, + "node_modules/domhandler": { + "version": "5.0.3", + "resolved": "https://registry.npmjs.org/domhandler/-/domhandler-5.0.3.tgz", + "integrity": "sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w==", + "license": "BSD-2-Clause", + "dependencies": { + "domelementtype": "^2.3.0" + }, + "engines": { + "node": ">= 4" + }, + "funding": { + "url": "https://github.com/fb55/domhandler?sponsor=1" + } + }, + "node_modules/domutils": { + "version": "3.2.2", + "resolved": "https://registry.npmjs.org/domutils/-/domutils-3.2.2.tgz", + "integrity": "sha512-6kZKyUajlDuqlHKVX1w7gyslj9MPIXzIFiz/rGu35uC1wMi+kMhQwGhl4lt9unC9Vb9INnY9Z3/ZA3+FhASLaw==", + "license": "BSD-2-Clause", + "dependencies": { + "dom-serializer": "^2.0.0", + "domelementtype": "^2.3.0", + "domhandler": "^5.0.3" + }, + "funding": { + "url": "https://github.com/fb55/domutils?sponsor=1" + } + }, + "node_modules/dset": { + "version": "3.1.4", + "resolved": "https://registry.npmjs.org/dset/-/dset-3.1.4.tgz", + "integrity": "sha512-2QF/g9/zTaPDc3BjNcVTGoBbXBgYfMTTceLaYcFJ/W9kggFUkhxD/hMEeuLKbugyef9SqAx8cpgwlIP/jinUTA==", + "license": "MIT", + "engines": { + "node": ">=4" + } + }, + "node_modules/emoji-regex": { + "version": "10.6.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-10.6.0.tgz", + "integrity": "sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==", + "license": "MIT" + }, + "node_modules/entities": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/entities/-/entities-6.0.1.tgz", + "integrity": "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==", + "license": "BSD-2-Clause", + "engines": { + "node": ">=0.12" + }, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, + "node_modules/es-module-lexer": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-1.7.0.tgz", + "integrity": "sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==", + "license": "MIT" + }, + "node_modules/esast-util-from-estree": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/esast-util-from-estree/-/esast-util-from-estree-2.0.0.tgz", + "integrity": "sha512-4CyanoAudUSBAn5K13H4JhsMH6L9ZP7XbLVe/dKybkxMO7eDyLsT8UHl9TRNrU2Gr9nz+FovfSIjuXWJ81uVwQ==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "devlop": "^1.0.0", + "estree-util-visit": "^2.0.0", + "unist-util-position-from-estree": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/esast-util-from-js": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/esast-util-from-js/-/esast-util-from-js-2.0.1.tgz", + "integrity": "sha512-8Ja+rNJ0Lt56Pcf3TAmpBZjmx8ZcK5Ts4cAzIOjsjevg9oSXJnl6SUQ2EevU8tv3h6ZLWmoKL5H4fgWvdvfETw==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "acorn": "^8.0.0", + "esast-util-from-estree": "^2.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/esbuild": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz", + "integrity": "sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==", + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.25.12", + "@esbuild/android-arm": "0.25.12", + "@esbuild/android-arm64": "0.25.12", + "@esbuild/android-x64": "0.25.12", + "@esbuild/darwin-arm64": "0.25.12", + "@esbuild/darwin-x64": "0.25.12", + "@esbuild/freebsd-arm64": "0.25.12", + "@esbuild/freebsd-x64": "0.25.12", + "@esbuild/linux-arm": "0.25.12", + "@esbuild/linux-arm64": "0.25.12", + "@esbuild/linux-ia32": "0.25.12", + "@esbuild/linux-loong64": "0.25.12", + "@esbuild/linux-mips64el": "0.25.12", + "@esbuild/linux-ppc64": "0.25.12", + "@esbuild/linux-riscv64": "0.25.12", + "@esbuild/linux-s390x": "0.25.12", + "@esbuild/linux-x64": "0.25.12", + "@esbuild/netbsd-arm64": "0.25.12", + "@esbuild/netbsd-x64": "0.25.12", + "@esbuild/openbsd-arm64": "0.25.12", + "@esbuild/openbsd-x64": "0.25.12", + "@esbuild/openharmony-arm64": "0.25.12", + "@esbuild/sunos-x64": "0.25.12", + "@esbuild/win32-arm64": "0.25.12", + "@esbuild/win32-ia32": "0.25.12", + "@esbuild/win32-x64": "0.25.12" + } + }, + "node_modules/escape-string-regexp": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-5.0.0.tgz", + "integrity": "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==", + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/estree-util-attach-comments": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/estree-util-attach-comments/-/estree-util-attach-comments-3.0.0.tgz", + "integrity": "sha512-cKUwm/HUcTDsYh/9FgnuFqpfquUbwIqwKM26BVCGDPVgvaCl/nDCCjUfiLlx6lsEZ3Z4RFxNbOQ60pkaEwFxGw==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-util-build-jsx": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/estree-util-build-jsx/-/estree-util-build-jsx-3.0.1.tgz", + "integrity": "sha512-8U5eiL6BTrPxp/CHbs2yMgP8ftMhR5ww1eIKoWRMlqvltHF8fZn5LRDvTKuxD3DUn+shRbLGqXemcP51oFCsGQ==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "devlop": "^1.0.0", + "estree-util-is-identifier-name": "^3.0.0", + "estree-walker": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-util-is-identifier-name": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/estree-util-is-identifier-name/-/estree-util-is-identifier-name-3.0.0.tgz", + "integrity": "sha512-hFtqIDZTIUZ9BXLb8y4pYGyk6+wekIivNVTcmvk8NoOh+VeRn5y6cEHzbURrWbfp1fIqdVipilzj+lfaadNZmg==", + "license": "MIT", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-util-scope": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/estree-util-scope/-/estree-util-scope-1.0.0.tgz", + "integrity": "sha512-2CAASclonf+JFWBNJPndcOpA8EMJwa0Q8LUFJEKqXLW6+qBvbFZuF5gItbQOs/umBUkjviCSDCbBwU2cXbmrhQ==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-util-to-js": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/estree-util-to-js/-/estree-util-to-js-2.0.0.tgz", + "integrity": "sha512-WDF+xj5rRWmD5tj6bIqRi6CkLIXbbNQUcxQHzGysQzvHmdYG2G7p/Tf0J0gpxGgkeMZNTIjT/AoSvC9Xehcgdg==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "astring": "^1.8.0", + "source-map": "^0.7.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-util-visit": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/estree-util-visit/-/estree-util-visit-2.0.0.tgz", + "integrity": "sha512-m5KgiH85xAhhW8Wta0vShLcUvOsh3LLPI2YVwcbio1l7E09NTLL1EyMZFM1OyWowoH0skScNbhOPl4kcBgzTww==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-walker": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz", + "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0" + } + }, + "node_modules/eventemitter3": { + "version": "5.0.4", + "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-5.0.4.tgz", + "integrity": "sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw==", + "license": "MIT" + }, + "node_modules/expressive-code": { + "version": "0.41.6", + "resolved": "https://registry.npmjs.org/expressive-code/-/expressive-code-0.41.6.tgz", + "integrity": "sha512-W/5+IQbrpCIM5KGLjO35wlp1NCwDOOVQb+PAvzEoGkW1xjGM807ZGfBKptNWH6UECvt6qgmLyWolCMYKh7eQmA==", + "license": "MIT", + "dependencies": { + "@expressive-code/core": "^0.41.6", + "@expressive-code/plugin-frames": "^0.41.6", + "@expressive-code/plugin-shiki": "^0.41.6", + "@expressive-code/plugin-text-markers": "^0.41.6" + } + }, + "node_modules/extend": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz", + "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==", + "license": "MIT" + }, + "node_modules/fdir": { + "version": "6.5.0", + "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz", + "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==", + "license": "MIT", + "engines": { + "node": ">=12.0.0" + }, + "peerDependencies": { + "picomatch": "^3 || ^4" + }, + "peerDependenciesMeta": { + "picomatch": { + "optional": true + } + } + }, + "node_modules/flattie": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/flattie/-/flattie-1.1.1.tgz", + "integrity": "sha512-9UbaD6XdAL97+k/n+N7JwX46K/M6Zc6KcFYskrYL8wbBV/Uyk0CTAMY0VT+qiK5PM7AIc9aTWYtq65U7T+aCNQ==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/fontace": { + "version": "0.4.1", + "resolved": "https://registry.npmjs.org/fontace/-/fontace-0.4.1.tgz", + "integrity": "sha512-lDMvbAzSnHmbYMTEld5qdtvNH2/pWpICOqpean9IgC7vUbUJc3k+k5Dokp85CegamqQpFbXf0rAVkbzpyTA8aw==", + "license": "MIT", + "dependencies": { + "fontkitten": "^1.0.2" + } + }, + "node_modules/fontkitten": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/fontkitten/-/fontkitten-1.0.2.tgz", + "integrity": "sha512-piJxbLnkD9Xcyi7dWJRnqszEURixe7CrF/efBfbffe2DPyabmuIuqraruY8cXTs19QoM8VJzx47BDRVNXETM7Q==", + "license": "MIT", + "dependencies": { + "tiny-inflate": "^1.0.3" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/fsevents": { + "version": "2.3.3", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz", + "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==", + "hasInstallScript": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/get-east-asian-width": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.4.0.tgz", + "integrity": "sha512-QZjmEOC+IT1uk6Rx0sX22V6uHWVwbdbxf1faPqJ1QhLdGgsRGCZoyaQBm/piRdJy/D2um6hM1UP7ZEeQ4EkP+Q==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/github-slugger": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/github-slugger/-/github-slugger-2.0.0.tgz", + "integrity": "sha512-IaOQ9puYtjrkq7Y0Ygl9KDZnrf/aiUJYUpVf89y8kyaxbRG7Y1SrX/jaumrv81vc61+kiMempujsM3Yw7w5qcw==", + "license": "ISC" + }, + "node_modules/h3": { + "version": "1.15.5", + "resolved": "https://registry.npmjs.org/h3/-/h3-1.15.5.tgz", + "integrity": "sha512-xEyq3rSl+dhGX2Lm0+eFQIAzlDN6Fs0EcC4f7BNUmzaRX/PTzeuM+Tr2lHB8FoXggsQIeXLj8EDVgs5ywxyxmg==", + "license": "MIT", + "dependencies": { + "cookie-es": "^1.2.2", + "crossws": "^0.3.5", + "defu": "^6.1.4", + "destr": "^2.0.5", + "iron-webcrypto": "^1.2.1", + "node-mock-http": "^1.0.4", + "radix3": "^1.1.2", + "ufo": "^1.6.3", + "uncrypto": "^0.1.3" + } + }, + "node_modules/hast-util-embedded": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/hast-util-embedded/-/hast-util-embedded-3.0.0.tgz", + "integrity": "sha512-naH8sld4Pe2ep03qqULEtvYr7EjrLK2QHY8KJR6RJkTUjPGObe1vnx585uzem2hGra+s1q08DZZpfgDVYRbaXA==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "hast-util-is-element": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-format": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/hast-util-format/-/hast-util-format-1.1.0.tgz", + "integrity": "sha512-yY1UDz6bC9rDvCWHpx12aIBGRG7krurX0p0Fm6pT547LwDIZZiNr8a+IHDogorAdreULSEzP82Nlv5SZkHZcjA==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "hast-util-embedded": "^3.0.0", + "hast-util-minify-whitespace": "^1.0.0", + "hast-util-phrasing": "^3.0.0", + "hast-util-whitespace": "^3.0.0", + "html-whitespace-sensitive-tag-names": "^3.0.0", + "unist-util-visit-parents": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-from-html": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/hast-util-from-html/-/hast-util-from-html-2.0.3.tgz", + "integrity": "sha512-CUSRHXyKjzHov8yKsQjGOElXy/3EKpyX56ELnkHH34vDVw1N1XSQ1ZcAvTyAPtGqLTuKP/uxM+aLkSPqF/EtMw==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "devlop": "^1.1.0", + "hast-util-from-parse5": "^8.0.0", + "parse5": "^7.0.0", + "vfile": "^6.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-from-parse5": { + "version": "8.0.3", + "resolved": "https://registry.npmjs.org/hast-util-from-parse5/-/hast-util-from-parse5-8.0.3.tgz", + "integrity": "sha512-3kxEVkEKt0zvcZ3hCRYI8rqrgwtlIOFMWkbclACvjlDw8Li9S2hk/d51OI0nr/gIpdMHNepwgOKqZ/sy0Clpyg==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/unist": "^3.0.0", + "devlop": "^1.0.0", + "hastscript": "^9.0.0", + "property-information": "^7.0.0", + "vfile": "^6.0.0", + "vfile-location": "^5.0.0", + "web-namespaces": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-has-property": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/hast-util-has-property/-/hast-util-has-property-3.0.0.tgz", + "integrity": "sha512-MNilsvEKLFpV604hwfhVStK0usFY/QmM5zX16bo7EjnAEGofr5YyI37kzopBlZJkHD4t887i+q/C8/tr5Q94cA==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-is-body-ok-link": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/hast-util-is-body-ok-link/-/hast-util-is-body-ok-link-3.0.1.tgz", + "integrity": "sha512-0qpnzOBLztXHbHQenVB8uNuxTnm/QBFUOmdOSsEn7GnBtyY07+ENTWVFBAnXd/zEgd9/SUG3lRY7hSIBWRgGpQ==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-is-element": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/hast-util-is-element/-/hast-util-is-element-3.0.0.tgz", + "integrity": "sha512-Val9mnv2IWpLbNPqc/pUem+a7Ipj2aHacCwgNfTiK0vJKl0LF+4Ba4+v1oPHFpf3bLYmreq0/l3Gud9S5OH42g==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-minify-whitespace": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/hast-util-minify-whitespace/-/hast-util-minify-whitespace-1.0.1.tgz", + "integrity": "sha512-L96fPOVpnclQE0xzdWb/D12VT5FabA7SnZOUMtL1DbXmYiHJMXZvFkIZfiMmTCNJHUeO2K9UYNXoVyfz+QHuOw==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "hast-util-embedded": "^3.0.0", + "hast-util-is-element": "^3.0.0", + "hast-util-whitespace": "^3.0.0", + "unist-util-is": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-parse-selector": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/hast-util-parse-selector/-/hast-util-parse-selector-4.0.0.tgz", + "integrity": "sha512-wkQCkSYoOGCRKERFWcxMVMOcYE2K1AaNLU8DXS9arxnLOUEWbOXKXiJUNzEpqZ3JOKpnha3jkFrumEjVliDe7A==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-phrasing": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/hast-util-phrasing/-/hast-util-phrasing-3.0.1.tgz", + "integrity": "sha512-6h60VfI3uBQUxHqTyMymMZnEbNl1XmEGtOxxKYL7stY2o601COo62AWAYBQR9lZbYXYSBoxag8UpPRXK+9fqSQ==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "hast-util-embedded": "^3.0.0", + "hast-util-has-property": "^3.0.0", + "hast-util-is-body-ok-link": "^3.0.0", + "hast-util-is-element": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-raw": { + "version": "9.1.0", + "resolved": "https://registry.npmjs.org/hast-util-raw/-/hast-util-raw-9.1.0.tgz", + "integrity": "sha512-Y8/SBAHkZGoNkpzqqfCldijcuUKh7/su31kEBp67cFY09Wy0mTRgtsLYsiIxMJxlu0f6AA5SUTbDR8K0rxnbUw==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/unist": "^3.0.0", + "@ungap/structured-clone": "^1.0.0", + "hast-util-from-parse5": "^8.0.0", + "hast-util-to-parse5": "^8.0.0", + "html-void-elements": "^3.0.0", + "mdast-util-to-hast": "^13.0.0", + "parse5": "^7.0.0", + "unist-util-position": "^5.0.0", + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.0", + "web-namespaces": "^2.0.0", + "zwitch": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-select": { + "version": "6.0.4", + "resolved": "https://registry.npmjs.org/hast-util-select/-/hast-util-select-6.0.4.tgz", + "integrity": "sha512-RqGS1ZgI0MwxLaKLDxjprynNzINEkRHY2i8ln4DDjgv9ZhcYVIHN9rlpiYsqtFwrgpYU361SyWDQcGNIBVu3lw==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/unist": "^3.0.0", + "bcp-47-match": "^2.0.0", + "comma-separated-tokens": "^2.0.0", + "css-selector-parser": "^3.0.0", + "devlop": "^1.0.0", + "direction": "^2.0.0", + "hast-util-has-property": "^3.0.0", + "hast-util-to-string": "^3.0.0", + "hast-util-whitespace": "^3.0.0", + "nth-check": "^2.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0", + "unist-util-visit": "^5.0.0", + "zwitch": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-estree": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/hast-util-to-estree/-/hast-util-to-estree-3.1.3.tgz", + "integrity": "sha512-48+B/rJWAp0jamNbAAf9M7Uf//UVqAoMmgXhBdxTDJLGKY+LRnZ99qcG+Qjl5HfMpYNzS5v4EAwVEF34LeAj7w==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "comma-separated-tokens": "^2.0.0", + "devlop": "^1.0.0", + "estree-util-attach-comments": "^3.0.0", + "estree-util-is-identifier-name": "^3.0.0", + "hast-util-whitespace": "^3.0.0", + "mdast-util-mdx-expression": "^2.0.0", + "mdast-util-mdx-jsx": "^3.0.0", + "mdast-util-mdxjs-esm": "^2.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0", + "style-to-js": "^1.0.0", + "unist-util-position": "^5.0.0", + "zwitch": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-html": { + "version": "9.0.5", + "resolved": "https://registry.npmjs.org/hast-util-to-html/-/hast-util-to-html-9.0.5.tgz", + "integrity": "sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/unist": "^3.0.0", + "ccount": "^2.0.0", + "comma-separated-tokens": "^2.0.0", + "hast-util-whitespace": "^3.0.0", + "html-void-elements": "^3.0.0", + "mdast-util-to-hast": "^13.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0", + "stringify-entities": "^4.0.0", + "zwitch": "^2.0.4" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-jsx-runtime": { + "version": "2.3.6", + "resolved": "https://registry.npmjs.org/hast-util-to-jsx-runtime/-/hast-util-to-jsx-runtime-2.3.6.tgz", + "integrity": "sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/unist": "^3.0.0", + "comma-separated-tokens": "^2.0.0", + "devlop": "^1.0.0", + "estree-util-is-identifier-name": "^3.0.0", + "hast-util-whitespace": "^3.0.0", + "mdast-util-mdx-expression": "^2.0.0", + "mdast-util-mdx-jsx": "^3.0.0", + "mdast-util-mdxjs-esm": "^2.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0", + "style-to-js": "^1.0.0", + "unist-util-position": "^5.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-parse5": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/hast-util-to-parse5/-/hast-util-to-parse5-8.0.1.tgz", + "integrity": "sha512-MlWT6Pjt4CG9lFCjiz4BH7l9wmrMkfkJYCxFwKQic8+RTZgWPuWxwAfjJElsXkex7DJjfSJsQIt931ilUgmwdA==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "comma-separated-tokens": "^2.0.0", + "devlop": "^1.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0", + "web-namespaces": "^2.0.0", + "zwitch": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-string": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/hast-util-to-string/-/hast-util-to-string-3.0.1.tgz", + "integrity": "sha512-XelQVTDWvqcl3axRfI0xSeoVKzyIFPwsAGSLIsKdJKQMXDYJS4WYrBNF/8J7RdhIcFI2BOHgAifggsvsxp/3+A==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-text": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/hast-util-to-text/-/hast-util-to-text-4.0.2.tgz", + "integrity": "sha512-KK6y/BN8lbaq654j7JgBydev7wuNMcID54lkRav1P0CaE1e47P72AWWPiGKXTJU271ooYzcvTAn/Zt0REnvc7A==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/unist": "^3.0.0", + "hast-util-is-element": "^3.0.0", + "unist-util-find-after": "^5.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-whitespace": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/hast-util-whitespace/-/hast-util-whitespace-3.0.0.tgz", + "integrity": "sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hastscript": { + "version": "9.0.1", + "resolved": "https://registry.npmjs.org/hastscript/-/hastscript-9.0.1.tgz", + "integrity": "sha512-g7df9rMFX/SPi34tyGCyUBREQoKkapwdY/T04Qn9TDWfHhAYt4/I0gMVirzK5wEzeUqIjEB+LXC/ypb7Aqno5w==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "comma-separated-tokens": "^2.0.0", + "hast-util-parse-selector": "^4.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/html-escaper": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-3.0.3.tgz", + "integrity": "sha512-RuMffC89BOWQoY0WKGpIhn5gX3iI54O6nRA0yC124NYVtzjmFWBIiFd8M0x+ZdX0P9R4lADg1mgP8C7PxGOWuQ==", + "license": "MIT" + }, + "node_modules/html-void-elements": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/html-void-elements/-/html-void-elements-3.0.0.tgz", + "integrity": "sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/html-whitespace-sensitive-tag-names": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/html-whitespace-sensitive-tag-names/-/html-whitespace-sensitive-tag-names-3.0.1.tgz", + "integrity": "sha512-q+310vW8zmymYHALr1da4HyXUQ0zgiIwIicEfotYPWGN0OJVEN/58IJ3A4GBYcEq3LGAZqKb+ugvP0GNB9CEAA==", + "license": "MIT", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/http-cache-semantics": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/http-cache-semantics/-/http-cache-semantics-4.2.0.tgz", + "integrity": "sha512-dTxcvPXqPvXBQpq5dUr6mEMJX4oIEFv6bwom3FDwKRDsuIjjJGANqhBuoAn9c1RQJIdAKav33ED65E2ys+87QQ==", + "license": "BSD-2-Clause" + }, + "node_modules/i18next": { + "version": "23.16.8", + "resolved": "https://registry.npmjs.org/i18next/-/i18next-23.16.8.tgz", + "integrity": "sha512-06r/TitrM88Mg5FdUXAKL96dJMzgqLE5dv3ryBAra4KCwD9mJ4ndOTS95ZuymIGoE+2hzfdaMak2X11/es7ZWg==", + "funding": [ + { + "type": "individual", + "url": "https://locize.com" + }, + { + "type": "individual", + "url": "https://locize.com/i18next.html" + }, + { + "type": "individual", + "url": "https://www.i18next.com/how-to/faq#i18next-is-awesome.-how-can-i-support-the-project" + } + ], + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.23.2" + } + }, + "node_modules/import-meta-resolve": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/import-meta-resolve/-/import-meta-resolve-4.2.0.tgz", + "integrity": "sha512-Iqv2fzaTQN28s/FwZAoFq0ZSs/7hMAHJVX+w8PZl3cY19Pxk6jFFalxQoIfW2826i/fDLXv8IiEZRIT0lDuWcg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/inline-style-parser": { + "version": "0.2.7", + "resolved": "https://registry.npmjs.org/inline-style-parser/-/inline-style-parser-0.2.7.tgz", + "integrity": "sha512-Nb2ctOyNR8DqQoR0OwRG95uNWIC0C1lCgf5Naz5H6Ji72KZ8OcFZLz2P5sNgwlyoJ8Yif11oMuYs5pBQa86csA==", + "license": "MIT" + }, + "node_modules/iron-webcrypto": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/iron-webcrypto/-/iron-webcrypto-1.2.1.tgz", + "integrity": "sha512-feOM6FaSr6rEABp/eDfVseKyTMDt+KGpeB35SkVn9Tyn0CqvVsY3EwI0v5i8nMHyJnzCIQf7nsy3p41TPkJZhg==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/brc-dd" + } + }, + "node_modules/is-alphabetical": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-alphabetical/-/is-alphabetical-2.0.1.tgz", + "integrity": "sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-alphanumerical": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-alphanumerical/-/is-alphanumerical-2.0.1.tgz", + "integrity": "sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==", + "license": "MIT", + "dependencies": { + "is-alphabetical": "^2.0.0", + "is-decimal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-decimal": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-decimal/-/is-decimal-2.0.1.tgz", + "integrity": "sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-docker": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-docker/-/is-docker-3.0.0.tgz", + "integrity": "sha512-eljcgEDlEns/7AXFosB5K/2nCM4P7FQPkGc/DWLy5rmFEWvZayGrik1d9/QIY5nJ4f9YsVvBkA6kJpHn9rISdQ==", + "license": "MIT", + "bin": { + "is-docker": "cli.js" + }, + "engines": { + "node": "^12.20.0 || ^14.13.1 || >=16.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/is-hexadecimal": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-hexadecimal/-/is-hexadecimal-2.0.1.tgz", + "integrity": "sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-inside-container": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/is-inside-container/-/is-inside-container-1.0.0.tgz", + "integrity": "sha512-KIYLCCJghfHZxqjYBE7rEy0OBuTd5xCHS7tHVgvCLkx7StIoaxwNW3hCALgEUjFfeRk+MG/Qxmp/vtETEF3tRA==", + "license": "MIT", + "dependencies": { + "is-docker": "^3.0.0" + }, + "bin": { + "is-inside-container": "cli.js" + }, + "engines": { + "node": ">=14.16" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/is-plain-obj": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/is-plain-obj/-/is-plain-obj-4.1.0.tgz", + "integrity": "sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==", + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/is-wsl": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/is-wsl/-/is-wsl-3.1.0.tgz", + "integrity": "sha512-UcVfVfaK4Sc4m7X3dUSoHoozQGBEFeDC+zVo06t98xe8CzHSZZBekNXH+tu0NalHolcJ/QAGqS46Hef7QXBIMw==", + "license": "MIT", + "dependencies": { + "is-inside-container": "^1.0.0" + }, + "engines": { + "node": ">=16" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/js-yaml": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz", + "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==", + "license": "MIT", + "dependencies": { + "argparse": "^2.0.1" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/kleur": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/kleur/-/kleur-3.0.3.tgz", + "integrity": "sha512-eTIzlVOSUR+JxdDFepEYcBMtZ9Qqdef+rnzWdRZuMbOywu5tO2w2N7rqjoANZ5k9vywhL6Br1VRjUIgTQx4E8w==", + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/klona": { + "version": "2.0.6", + "resolved": "https://registry.npmjs.org/klona/-/klona-2.0.6.tgz", + "integrity": "sha512-dhG34DXATL5hSxJbIexCft8FChFXtmskoZYnoPWjXQuebWYCNkVeV3KkGegCK9CP1oswI/vQibS2GY7Em/sJJA==", + "license": "MIT", + "engines": { + "node": ">= 8" + } + }, + "node_modules/longest-streak": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/longest-streak/-/longest-streak-3.1.0.tgz", + "integrity": "sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/lru-cache": { + "version": "11.2.5", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.2.5.tgz", + "integrity": "sha512-vFrFJkWtJvJnD5hg+hJvVE8Lh/TcMzKnTgCWmtBipwI5yLX/iX+5UB2tfuyODF5E7k9xEzMdYgGqaSb1c0c5Yw==", + "license": "BlueOak-1.0.0", + "engines": { + "node": "20 || >=22" + } + }, + "node_modules/magic-string": { + "version": "0.30.21", + "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz", + "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==", + "license": "MIT", + "dependencies": { + "@jridgewell/sourcemap-codec": "^1.5.5" + } + }, + "node_modules/magicast": { + "version": "0.5.1", + "resolved": "https://registry.npmjs.org/magicast/-/magicast-0.5.1.tgz", + "integrity": "sha512-xrHS24IxaLrvuo613F719wvOIv9xPHFWQHuvGUBmPnCA/3MQxKI3b+r7n1jAoDHmsbC5bRhTZYR77invLAxVnw==", + "license": "MIT", + "dependencies": { + "@babel/parser": "^7.28.5", + "@babel/types": "^7.28.5", + "source-map-js": "^1.2.1" + } + }, + "node_modules/markdown-extensions": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/markdown-extensions/-/markdown-extensions-2.0.0.tgz", + "integrity": "sha512-o5vL7aDWatOTX8LzaS1WMoaoxIiLRQJuIKKe2wAw6IeULDHaqbiqiggmx+pKvZDb1Sj+pE46Sn1T7lCqfFtg1Q==", + "license": "MIT", + "engines": { + "node": ">=16" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/markdown-table": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/markdown-table/-/markdown-table-3.0.4.tgz", + "integrity": "sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/mdast-util-definitions": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-definitions/-/mdast-util-definitions-6.0.0.tgz", + "integrity": "sha512-scTllyX6pnYNZH/AIp/0ePz6s4cZtARxImwoPJ7kS42n+MnVsI4XbnG6d4ibehRIldYMWM2LD7ImQblVhUejVQ==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "unist-util-visit": "^5.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-directive": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/mdast-util-directive/-/mdast-util-directive-3.1.0.tgz", + "integrity": "sha512-I3fNFt+DHmpWCYAT7quoM6lHf9wuqtI+oCOfvILnoicNIqjh5E3dEJWiXuYME2gNe8vl1iMQwyUHa7bgFmak6Q==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "ccount": "^2.0.0", + "devlop": "^1.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0", + "parse-entities": "^4.0.0", + "stringify-entities": "^4.0.0", + "unist-util-visit-parents": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-find-and-replace": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/mdast-util-find-and-replace/-/mdast-util-find-and-replace-3.0.2.tgz", + "integrity": "sha512-Tmd1Vg/m3Xz43afeNxDIhWRtFZgM2VLyaf4vSTYwudTyeuTneoL3qtWMA5jeLyz/O1vDJmmV4QuScFCA2tBPwg==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "escape-string-regexp": "^5.0.0", + "unist-util-is": "^6.0.0", + "unist-util-visit-parents": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-from-markdown": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/mdast-util-from-markdown/-/mdast-util-from-markdown-2.0.2.tgz", + "integrity": "sha512-uZhTV/8NBuw0WHkPTrCqDOl0zVe1BIng5ZtHoDk49ME1qqcjYmmLmOf0gELgcRMxN4w2iuIeVso5/6QymSrgmA==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "mdast-util-to-string": "^4.0.0", + "micromark": "^4.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-decode-string": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unist-util-stringify-position": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/mdast-util-gfm/-/mdast-util-gfm-3.1.0.tgz", + "integrity": "sha512-0ulfdQOM3ysHhCJ1p06l0b0VKlhU0wuQs3thxZQagjcjPrlFRqY215uZGHHJan9GEAXd9MbfPjFJz+qMkVR6zQ==", + "license": "MIT", + "dependencies": { + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-gfm-autolink-literal": "^2.0.0", + "mdast-util-gfm-footnote": "^2.0.0", + "mdast-util-gfm-strikethrough": "^2.0.0", + "mdast-util-gfm-table": "^2.0.0", + "mdast-util-gfm-task-list-item": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-autolink-literal": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-autolink-literal/-/mdast-util-gfm-autolink-literal-2.0.1.tgz", + "integrity": "sha512-5HVP2MKaP6L+G6YaxPNjuL0BPrq9orG3TsrZ9YXbA3vDw/ACI4MEsnoDpn6ZNm7GnZgtAcONJyPhOP8tNJQavQ==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "ccount": "^2.0.0", + "devlop": "^1.0.0", + "mdast-util-find-and-replace": "^3.0.0", + "micromark-util-character": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-footnote": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-footnote/-/mdast-util-gfm-footnote-2.1.0.tgz", + "integrity": "sha512-sqpDWlsHn7Ac9GNZQMeUzPQSMzR6Wv0WKRNvQRg0KqHh02fpTz69Qc1QSseNX29bhz1ROIyNyxExfawVKTm1GQ==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "devlop": "^1.1.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-strikethrough": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-strikethrough/-/mdast-util-gfm-strikethrough-2.0.0.tgz", + "integrity": "sha512-mKKb915TF+OC5ptj5bJ7WFRPdYtuHv0yTRxK2tJvi+BDqbkiG7h7u/9SI89nRAYcmap2xHQL9D+QG/6wSrTtXg==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-table": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-table/-/mdast-util-gfm-table-2.0.0.tgz", + "integrity": "sha512-78UEvebzz/rJIxLvE7ZtDd/vIQ0RHv+3Mh5DR96p7cS7HsBhYIICDBCu8csTNWNO6tBWfqXPWekRuj2FNOGOZg==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "markdown-table": "^3.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-task-list-item": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-task-list-item/-/mdast-util-gfm-task-list-item-2.0.0.tgz", + "integrity": "sha512-IrtvNvjxC1o06taBAVJznEnkiHxLFTzgonUdy8hzFVeDun0uTjxxrRGVaNFqkU1wJR3RBPEfsxmU6jDWPofrTQ==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-mdx": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-mdx/-/mdast-util-mdx-3.0.0.tgz", + "integrity": "sha512-JfbYLAW7XnYTTbUsmpu0kdBUVe+yKVJZBItEjwyYJiDJuZ9w4eeaqks4HQO+R7objWgS2ymV60GYpI14Ug554w==", + "license": "MIT", + "dependencies": { + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-mdx-expression": "^2.0.0", + "mdast-util-mdx-jsx": "^3.0.0", + "mdast-util-mdxjs-esm": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-mdx-expression": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-mdx-expression/-/mdast-util-mdx-expression-2.0.1.tgz", + "integrity": "sha512-J6f+9hUp+ldTZqKRSg7Vw5V6MqjATc+3E4gf3CFNcuZNWD8XdyI6zQ8GqH7f8169MM6P7hMBRDVGnn7oHB9kXQ==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-mdx-jsx": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/mdast-util-mdx-jsx/-/mdast-util-mdx-jsx-3.2.0.tgz", + "integrity": "sha512-lj/z8v0r6ZtsN/cGNNtemmmfoLAFZnjMbNyLzBafjzikOM+glrjNHPlf6lQDOTccj9n5b0PPihEBbhneMyGs1Q==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "ccount": "^2.0.0", + "devlop": "^1.1.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0", + "parse-entities": "^4.0.0", + "stringify-entities": "^4.0.0", + "unist-util-stringify-position": "^4.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-mdxjs-esm": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-mdxjs-esm/-/mdast-util-mdxjs-esm-2.0.1.tgz", + "integrity": "sha512-EcmOpxsZ96CvlP03NghtH1EsLtr0n9Tm4lPUJUBccV9RwUOneqSycg19n5HGzCf+10LozMRSObtVr3ee1WoHtg==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-phrasing": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/mdast-util-phrasing/-/mdast-util-phrasing-4.1.0.tgz", + "integrity": "sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "unist-util-is": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-hast": { + "version": "13.2.1", + "resolved": "https://registry.npmjs.org/mdast-util-to-hast/-/mdast-util-to-hast-13.2.1.tgz", + "integrity": "sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "@ungap/structured-clone": "^1.0.0", + "devlop": "^1.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "trim-lines": "^3.0.0", + "unist-util-position": "^5.0.0", + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-markdown": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/mdast-util-to-markdown/-/mdast-util-to-markdown-2.1.2.tgz", + "integrity": "sha512-xj68wMTvGXVOKonmog6LwyJKrYXZPvlwabaryTjLh9LuvovB/KAH+kvi8Gjj+7rJjsFi23nkUxRQv1KqSroMqA==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "longest-streak": "^3.0.0", + "mdast-util-phrasing": "^4.0.0", + "mdast-util-to-string": "^4.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-decode-string": "^2.0.0", + "unist-util-visit": "^5.0.0", + "zwitch": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-string": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-4.0.0.tgz", + "integrity": "sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdn-data": { + "version": "2.12.2", + "resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-2.12.2.tgz", + "integrity": "sha512-IEn+pegP1aManZuckezWCO+XZQDplx1366JoVhTpMpBB1sPey/SbveZQUosKiKiGYjg1wH4pMlNgXbCiYgihQA==", + "license": "CC0-1.0" + }, + "node_modules/micromark": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/micromark/-/micromark-4.0.2.tgz", + "integrity": "sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/debug": "^4.0.0", + "debug": "^4.0.0", + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "micromark-core-commonmark": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-combine-extensions": "^2.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-encode": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-subtokenize": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-core-commonmark": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/micromark-core-commonmark/-/micromark-core-commonmark-2.0.3.tgz", + "integrity": "sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "micromark-factory-destination": "^2.0.0", + "micromark-factory-label": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-factory-title": "^2.0.0", + "micromark-factory-whitespace": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-html-tag-name": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-subtokenize": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-extension-directive": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/micromark-extension-directive/-/micromark-extension-directive-3.0.2.tgz", + "integrity": "sha512-wjcXHgk+PPdmvR58Le9d7zQYWy+vKEU9Se44p2CrCDPiLr2FMyiT4Fyb5UFKFC66wGB3kPlgD7q3TnoqPS7SZA==", + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-factory-whitespace": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "parse-entities": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm/-/micromark-extension-gfm-3.0.0.tgz", + "integrity": "sha512-vsKArQsicm7t0z2GugkCKtZehqUm31oeGBV/KVSorWSy8ZlNAv7ytjFhvaryUiCUJYqs+NoE6AFhpQvBTM6Q4w==", + "license": "MIT", + "dependencies": { + "micromark-extension-gfm-autolink-literal": "^2.0.0", + "micromark-extension-gfm-footnote": "^2.0.0", + "micromark-extension-gfm-strikethrough": "^2.0.0", + "micromark-extension-gfm-table": "^2.0.0", + "micromark-extension-gfm-tagfilter": "^2.0.0", + "micromark-extension-gfm-task-list-item": "^2.0.0", + "micromark-util-combine-extensions": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-autolink-literal": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-autolink-literal/-/micromark-extension-gfm-autolink-literal-2.1.0.tgz", + "integrity": "sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==", + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-footnote": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-footnote/-/micromark-extension-gfm-footnote-2.1.0.tgz", + "integrity": "sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==", + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-core-commonmark": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-strikethrough": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-strikethrough/-/micromark-extension-gfm-strikethrough-2.1.0.tgz", + "integrity": "sha512-ADVjpOOkjz1hhkZLlBiYA9cR2Anf8F4HqZUO6e5eDcPQd0Txw5fxLzzxnEkSkfnD0wziSGiv7sYhk/ktvbf1uw==", + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-table": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-table/-/micromark-extension-gfm-table-2.1.1.tgz", + "integrity": "sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==", + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-tagfilter": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-tagfilter/-/micromark-extension-gfm-tagfilter-2.0.0.tgz", + "integrity": "sha512-xHlTOmuCSotIA8TW1mDIM6X2O1SiX5P9IuDtqGonFhEK0qgRI4yeC6vMxEV2dgyr2TiD+2PQ10o+cOhdVAcwfg==", + "license": "MIT", + "dependencies": { + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-task-list-item": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-task-list-item/-/micromark-extension-gfm-task-list-item-2.1.0.tgz", + "integrity": "sha512-qIBZhqxqI6fjLDYFTBIa4eivDMnP+OZqsNwmQ3xNLE4Cxwc+zfQEfbs6tzAo2Hjq+bh6q5F+Z8/cksrLFYWQQw==", + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-mdx-expression": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/micromark-extension-mdx-expression/-/micromark-extension-mdx-expression-3.0.1.tgz", + "integrity": "sha512-dD/ADLJ1AeMvSAKBwO22zG22N4ybhe7kFIZ3LsDI0GlsNr2A3KYxb0LdC1u5rj4Nw+CHKY0RVdnHX8vj8ejm4Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0", + "micromark-factory-mdx-expression": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-events-to-acorn": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-extension-mdx-jsx": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/micromark-extension-mdx-jsx/-/micromark-extension-mdx-jsx-3.0.2.tgz", + "integrity": "sha512-e5+q1DjMh62LZAJOnDraSSbDMvGJ8x3cbjygy2qFEi7HCeUT4BDKCvMozPozcD6WmOt6sVvYDNBKhFSz3kjOVQ==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0", + "estree-util-is-identifier-name": "^3.0.0", + "micromark-factory-mdx-expression": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-events-to-acorn": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-mdx-md": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-mdx-md/-/micromark-extension-mdx-md-2.0.0.tgz", + "integrity": "sha512-EpAiszsB3blw4Rpba7xTOUptcFeBFi+6PY8VnJ2hhimH+vCQDirWgsMpz7w1XcZE7LVrSAUGb9VJpG9ghlYvYQ==", + "license": "MIT", + "dependencies": { + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-mdxjs": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-mdxjs/-/micromark-extension-mdxjs-3.0.0.tgz", + "integrity": "sha512-A873fJfhnJ2siZyUrJ31l34Uqwy4xIFmvPY1oj+Ean5PHcPBYzEsvqvWGaWcfEIr11O5Dlw3p2y0tZWpKHDejQ==", + "license": "MIT", + "dependencies": { + "acorn": "^8.0.0", + "acorn-jsx": "^5.0.0", + "micromark-extension-mdx-expression": "^3.0.0", + "micromark-extension-mdx-jsx": "^3.0.0", + "micromark-extension-mdx-md": "^2.0.0", + "micromark-extension-mdxjs-esm": "^3.0.0", + "micromark-util-combine-extensions": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-mdxjs-esm": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-mdxjs-esm/-/micromark-extension-mdxjs-esm-3.0.0.tgz", + "integrity": "sha512-DJFl4ZqkErRpq/dAPyeWp15tGrcrrJho1hKK5uBS70BCtfrIFg81sqcTVu3Ta+KD1Tk5vAtBNElWxtAa+m8K9A==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0", + "micromark-core-commonmark": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-events-to-acorn": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unist-util-position-from-estree": "^2.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-factory-destination": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-destination/-/micromark-factory-destination-2.0.1.tgz", + "integrity": "sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-label": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-label/-/micromark-factory-label-2.0.1.tgz", + "integrity": "sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-mdx-expression": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/micromark-factory-mdx-expression/-/micromark-factory-mdx-expression-2.0.3.tgz", + "integrity": "sha512-kQnEtA3vzucU2BkrIa8/VaSAsP+EJ3CKOvhMuJgOEGg9KDC6OAY6nSnNDVRiVNRqj7Y4SlSzcStaH/5jge8JdQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-events-to-acorn": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unist-util-position-from-estree": "^2.0.0", + "vfile-message": "^4.0.0" + } + }, + "node_modules/micromark-factory-space": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-space/-/micromark-factory-space-2.0.1.tgz", + "integrity": "sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-title": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-title/-/micromark-factory-title-2.0.1.tgz", + "integrity": "sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-whitespace": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-whitespace/-/micromark-factory-whitespace-2.0.1.tgz", + "integrity": "sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-character": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/micromark-util-character/-/micromark-util-character-2.1.1.tgz", + "integrity": "sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-chunked": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-chunked/-/micromark-util-chunked-2.0.1.tgz", + "integrity": "sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-classify-character": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-classify-character/-/micromark-util-classify-character-2.0.1.tgz", + "integrity": "sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-combine-extensions": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-combine-extensions/-/micromark-util-combine-extensions-2.0.1.tgz", + "integrity": "sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-chunked": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-decode-numeric-character-reference": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/micromark-util-decode-numeric-character-reference/-/micromark-util-decode-numeric-character-reference-2.0.2.tgz", + "integrity": "sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-decode-string": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-decode-string/-/micromark-util-decode-string-2.0.1.tgz", + "integrity": "sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-encode": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-encode/-/micromark-util-encode-2.0.1.tgz", + "integrity": "sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-events-to-acorn": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/micromark-util-events-to-acorn/-/micromark-util-events-to-acorn-2.0.3.tgz", + "integrity": "sha512-jmsiEIiZ1n7X1Rr5k8wVExBQCg5jy4UXVADItHmNk1zkwEVhBuIUKRu3fqv+hs4nxLISi2DQGlqIOGiFxgbfHg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "@types/unist": "^3.0.0", + "devlop": "^1.0.0", + "estree-util-visit": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "vfile-message": "^4.0.0" + } + }, + "node_modules/micromark-util-html-tag-name": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-html-tag-name/-/micromark-util-html-tag-name-2.0.1.tgz", + "integrity": "sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-normalize-identifier": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-normalize-identifier/-/micromark-util-normalize-identifier-2.0.1.tgz", + "integrity": "sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-resolve-all": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-resolve-all/-/micromark-util-resolve-all-2.0.1.tgz", + "integrity": "sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-sanitize-uri": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-sanitize-uri/-/micromark-util-sanitize-uri-2.0.1.tgz", + "integrity": "sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-encode": "^2.0.0", + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-subtokenize": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-subtokenize/-/micromark-util-subtokenize-2.1.0.tgz", + "integrity": "sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-symbol": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-symbol/-/micromark-util-symbol-2.0.1.tgz", + "integrity": "sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-types": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/micromark-util-types/-/micromark-util-types-2.0.2.tgz", + "integrity": "sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/mrmime": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mrmime/-/mrmime-2.0.1.tgz", + "integrity": "sha512-Y3wQdFg2Va6etvQ5I82yUhGdsKrcYox6p7FfL1LbK2J4V01F9TGlepTIhnK24t7koZibmg82KGglhA1XK5IsLQ==", + "license": "MIT", + "engines": { + "node": ">=10" + } + }, + "node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "license": "MIT" + }, + "node_modules/nanoid": { + "version": "3.3.11", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz", + "integrity": "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "bin": { + "nanoid": "bin/nanoid.cjs" + }, + "engines": { + "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1" + } + }, + "node_modules/neotraverse": { + "version": "0.6.18", + "resolved": "https://registry.npmjs.org/neotraverse/-/neotraverse-0.6.18.tgz", + "integrity": "sha512-Z4SmBUweYa09+o6pG+eASabEpP6QkQ70yHj351pQoEXIs8uHbaU2DWVmzBANKgflPa47A50PtB2+NgRpQvr7vA==", + "license": "MIT", + "engines": { + "node": ">= 10" + } + }, + "node_modules/nlcst-to-string": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/nlcst-to-string/-/nlcst-to-string-4.0.0.tgz", + "integrity": "sha512-YKLBCcUYKAg0FNlOBT6aI91qFmSiFKiluk655WzPF+DDMA02qIyy8uiRqI8QXtcFpEvll12LpL5MXqEmAZ+dcA==", + "license": "MIT", + "dependencies": { + "@types/nlcst": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/node-fetch-native": { + "version": "1.6.7", + "resolved": "https://registry.npmjs.org/node-fetch-native/-/node-fetch-native-1.6.7.tgz", + "integrity": "sha512-g9yhqoedzIUm0nTnTqAQvueMPVOuIY16bqgAJJC8XOOubYFNwz6IER9qs0Gq2Xd0+CecCKFjtdDTMA4u4xG06Q==", + "license": "MIT" + }, + "node_modules/node-mock-http": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/node-mock-http/-/node-mock-http-1.0.4.tgz", + "integrity": "sha512-8DY+kFsDkNXy1sJglUfuODx1/opAGJGyrTuFqEoN90oRc2Vk0ZbD4K2qmKXBBEhZQzdKHIVfEJpDU8Ak2NJEvQ==", + "license": "MIT" + }, + "node_modules/normalize-path": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz", + "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/nth-check": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/nth-check/-/nth-check-2.1.1.tgz", + "integrity": "sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==", + "license": "BSD-2-Clause", + "dependencies": { + "boolbase": "^1.0.0" + }, + "funding": { + "url": "https://github.com/fb55/nth-check?sponsor=1" + } + }, + "node_modules/ofetch": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/ofetch/-/ofetch-1.5.1.tgz", + "integrity": "sha512-2W4oUZlVaqAPAil6FUg/difl6YhqhUR7x2eZY4bQCko22UXg3hptq9KLQdqFClV+Wu85UX7hNtdGTngi/1BxcA==", + "license": "MIT", + "dependencies": { + "destr": "^2.0.5", + "node-fetch-native": "^1.6.7", + "ufo": "^1.6.1" + } + }, + "node_modules/ohash": { + "version": "2.0.11", + "resolved": "https://registry.npmjs.org/ohash/-/ohash-2.0.11.tgz", + "integrity": "sha512-RdR9FQrFwNBNXAr4GixM8YaRZRJ5PUWbKYbE5eOsrwAjJW0q2REGcf79oYPsLyskQCZG1PLN+S/K1V00joZAoQ==", + "license": "MIT" + }, + "node_modules/oniguruma-parser": { + "version": "0.12.1", + "resolved": "https://registry.npmjs.org/oniguruma-parser/-/oniguruma-parser-0.12.1.tgz", + "integrity": "sha512-8Unqkvk1RYc6yq2WBYRj4hdnsAxVze8i7iPfQr8e4uSP3tRv0rpZcbGUDvxfQQcdwHt/e9PrMvGCsa8OqG9X3w==", + "license": "MIT" + }, + "node_modules/oniguruma-to-es": { + "version": "4.3.4", + "resolved": "https://registry.npmjs.org/oniguruma-to-es/-/oniguruma-to-es-4.3.4.tgz", + "integrity": "sha512-3VhUGN3w2eYxnTzHn+ikMI+fp/96KoRSVK9/kMTcFqj1NRDh2IhQCKvYxDnWePKRXY/AqH+Fuiyb7VHSzBjHfA==", + "license": "MIT", + "dependencies": { + "oniguruma-parser": "^0.12.1", + "regex": "^6.0.1", + "regex-recursion": "^6.0.2" + } + }, + "node_modules/p-limit": { + "version": "6.2.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-6.2.0.tgz", + "integrity": "sha512-kuUqqHNUqoIWp/c467RI4X6mmyuojY5jGutNU0wVTmEOOfcuwLqyMVoAi9MKi2Ak+5i9+nhmrK4ufZE8069kHA==", + "license": "MIT", + "dependencies": { + "yocto-queue": "^1.1.1" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/p-queue": { + "version": "8.1.1", + "resolved": "https://registry.npmjs.org/p-queue/-/p-queue-8.1.1.tgz", + "integrity": "sha512-aNZ+VfjobsWryoiPnEApGGmf5WmNsCo9xu8dfaYamG5qaLP7ClhLN6NgsFe6SwJ2UbLEBK5dv9x8Mn5+RVhMWQ==", + "license": "MIT", + "dependencies": { + "eventemitter3": "^5.0.1", + "p-timeout": "^6.1.2" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/p-timeout": { + "version": "6.1.4", + "resolved": "https://registry.npmjs.org/p-timeout/-/p-timeout-6.1.4.tgz", + "integrity": "sha512-MyIV3ZA/PmyBN/ud8vV9XzwTrNtR4jFrObymZYnZqMmW0zA8Z17vnT0rBgFE/TlohB+YCHqXMgZzb3Csp49vqg==", + "license": "MIT", + "engines": { + "node": ">=14.16" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/package-manager-detector": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/package-manager-detector/-/package-manager-detector-1.6.0.tgz", + "integrity": "sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==", + "license": "MIT" + }, + "node_modules/pagefind": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/pagefind/-/pagefind-1.4.0.tgz", + "integrity": "sha512-z2kY1mQlL4J8q5EIsQkLzQjilovKzfNVhX8De6oyE6uHpfFtyBaqUpcl/XzJC/4fjD8vBDyh1zolimIcVrCn9g==", + "license": "MIT", + "bin": { + "pagefind": "lib/runner/bin.cjs" + }, + "optionalDependencies": { + "@pagefind/darwin-arm64": "1.4.0", + "@pagefind/darwin-x64": "1.4.0", + "@pagefind/freebsd-x64": "1.4.0", + "@pagefind/linux-arm64": "1.4.0", + "@pagefind/linux-x64": "1.4.0", + "@pagefind/windows-x64": "1.4.0" + } + }, + "node_modules/parse-entities": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/parse-entities/-/parse-entities-4.0.2.tgz", + "integrity": "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0", + "character-entities-legacy": "^3.0.0", + "character-reference-invalid": "^2.0.0", + "decode-named-character-reference": "^1.0.0", + "is-alphanumerical": "^2.0.0", + "is-decimal": "^2.0.0", + "is-hexadecimal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/parse-entities/node_modules/@types/unist": { + "version": "2.0.11", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz", + "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==", + "license": "MIT" + }, + "node_modules/parse-latin": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/parse-latin/-/parse-latin-7.0.0.tgz", + "integrity": "sha512-mhHgobPPua5kZ98EF4HWiH167JWBfl4pvAIXXdbaVohtK7a6YBOy56kvhCqduqyo/f3yrHFWmqmiMg/BkBkYYQ==", + "license": "MIT", + "dependencies": { + "@types/nlcst": "^2.0.0", + "@types/unist": "^3.0.0", + "nlcst-to-string": "^4.0.0", + "unist-util-modify-children": "^4.0.0", + "unist-util-visit-children": "^3.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/parse5": { + "version": "7.3.0", + "resolved": "https://registry.npmjs.org/parse5/-/parse5-7.3.0.tgz", + "integrity": "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==", + "license": "MIT", + "dependencies": { + "entities": "^6.0.0" + }, + "funding": { + "url": "https://github.com/inikulin/parse5?sponsor=1" + } + }, + "node_modules/piccolore": { + "version": "0.1.3", + "resolved": "https://registry.npmjs.org/piccolore/-/piccolore-0.1.3.tgz", + "integrity": "sha512-o8bTeDWjE086iwKrROaDf31K0qC/BENdm15/uH9usSC/uZjJOKb2YGiVHfLY4GhwsERiPI1jmwI2XrA7ACOxVw==", + "license": "ISC" + }, + "node_modules/picocolors": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz", + "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==", + "license": "ISC" + }, + "node_modules/picomatch": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz", + "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/jonschlinkert" + } + }, + "node_modules/postcss": { + "version": "8.5.6", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.6.tgz", + "integrity": "sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==", + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/postcss" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "nanoid": "^3.3.11", + "picocolors": "^1.1.1", + "source-map-js": "^1.2.1" + }, + "engines": { + "node": "^10 || ^12 || >=14" + } + }, + "node_modules/postcss-nested": { + "version": "6.2.0", + "resolved": "https://registry.npmjs.org/postcss-nested/-/postcss-nested-6.2.0.tgz", + "integrity": "sha512-HQbt28KulC5AJzG+cZtj9kvKB93CFCdLvog1WFLf1D+xmMvPGlBstkpTEZfK5+AN9hfJocyBFCNiqyS48bpgzQ==", + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "postcss-selector-parser": "^6.1.1" + }, + "engines": { + "node": ">=12.0" + }, + "peerDependencies": { + "postcss": "^8.2.14" + } + }, + "node_modules/postcss-selector-parser": { + "version": "6.1.2", + "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-6.1.2.tgz", + "integrity": "sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg==", + "license": "MIT", + "dependencies": { + "cssesc": "^3.0.0", + "util-deprecate": "^1.0.2" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/prismjs": { + "version": "1.30.0", + "resolved": "https://registry.npmjs.org/prismjs/-/prismjs-1.30.0.tgz", + "integrity": "sha512-DEvV2ZF2r2/63V+tK8hQvrR2ZGn10srHbXviTlcv7Kpzw8jWiNTqbVgjO3IY8RxrrOUF8VPMQQFysYYYv0YZxw==", + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/prompts": { + "version": "2.4.2", + "resolved": "https://registry.npmjs.org/prompts/-/prompts-2.4.2.tgz", + "integrity": "sha512-NxNv/kLguCA7p3jE8oL2aEBsrJWgAakBpgmgK6lpPWV+WuOmY6r2/zbAVnP+T8bQlA0nzHXSJSJW0Hq7ylaD2Q==", + "license": "MIT", + "dependencies": { + "kleur": "^3.0.3", + "sisteransi": "^1.0.5" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/property-information": { + "version": "7.1.0", + "resolved": "https://registry.npmjs.org/property-information/-/property-information-7.1.0.tgz", + "integrity": "sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/radix3": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/radix3/-/radix3-1.1.2.tgz", + "integrity": "sha512-b484I/7b8rDEdSDKckSSBA8knMpcdsXudlE/LNL639wFoHKwLbEkQFZHWEYwDC0wa0FKUcCY+GAF73Z7wxNVFA==", + "license": "MIT" + }, + "node_modules/readdirp": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-5.0.0.tgz", + "integrity": "sha512-9u/XQ1pvrQtYyMpZe7DXKv2p5CNvyVwzUB6uhLAnQwHMSgKMBR62lc7AHljaeteeHXn11XTAaLLUVZYVZyuRBQ==", + "license": "MIT", + "engines": { + "node": ">= 20.19.0" + }, + "funding": { + "type": "individual", + "url": "https://paulmillr.com/funding/" + } + }, + "node_modules/recma-build-jsx": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/recma-build-jsx/-/recma-build-jsx-1.0.0.tgz", + "integrity": "sha512-8GtdyqaBcDfva+GUKDr3nev3VpKAhup1+RvkMvUxURHpW7QyIvk9F5wz7Vzo06CEMSilw6uArgRqhpiUcWp8ew==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "estree-util-build-jsx": "^3.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/recma-jsx": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/recma-jsx/-/recma-jsx-1.0.1.tgz", + "integrity": "sha512-huSIy7VU2Z5OLv6oFLosQGGDqPqdO1iq6bWNAdhzMxSJP7RAso4fCZ1cKu8j9YHCZf3TPrq4dw3okhrylgcd7w==", + "license": "MIT", + "dependencies": { + "acorn-jsx": "^5.0.0", + "estree-util-to-js": "^2.0.0", + "recma-parse": "^1.0.0", + "recma-stringify": "^1.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + }, + "peerDependencies": { + "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" + } + }, + "node_modules/recma-parse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/recma-parse/-/recma-parse-1.0.0.tgz", + "integrity": "sha512-OYLsIGBB5Y5wjnSnQW6t3Xg7q3fQ7FWbw/vcXtORTnyaSFscOtABg+7Pnz6YZ6c27fG1/aN8CjfwoUEUIdwqWQ==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "esast-util-from-js": "^2.0.0", + "unified": "^11.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/recma-stringify": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/recma-stringify/-/recma-stringify-1.0.0.tgz", + "integrity": "sha512-cjwII1MdIIVloKvC9ErQ+OgAtwHBmcZ0Bg4ciz78FtbT8In39aAYbaA7zvxQ61xVMSPE8WxhLwLbhif4Js2C+g==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "estree-util-to-js": "^2.0.0", + "unified": "^11.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/regex": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/regex/-/regex-6.1.0.tgz", + "integrity": "sha512-6VwtthbV4o/7+OaAF9I5L5V3llLEsoPyq9P1JVXkedTP33c7MfCG0/5NOPcSJn0TzXcG9YUrR0gQSWioew3LDg==", + "license": "MIT", + "dependencies": { + "regex-utilities": "^2.3.0" + } + }, + "node_modules/regex-recursion": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/regex-recursion/-/regex-recursion-6.0.2.tgz", + "integrity": "sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==", + "license": "MIT", + "dependencies": { + "regex-utilities": "^2.3.0" + } + }, + "node_modules/regex-utilities": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/regex-utilities/-/regex-utilities-2.3.0.tgz", + "integrity": "sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng==", + "license": "MIT" + }, + "node_modules/rehype": { + "version": "13.0.2", + "resolved": "https://registry.npmjs.org/rehype/-/rehype-13.0.2.tgz", + "integrity": "sha512-j31mdaRFrwFRUIlxGeuPXXKWQxet52RBQRvCmzl5eCefn/KGbomK5GMHNMsOJf55fgo3qw5tST5neDuarDYR2A==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "rehype-parse": "^9.0.0", + "rehype-stringify": "^10.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/rehype-expressive-code": { + "version": "0.41.6", + "resolved": "https://registry.npmjs.org/rehype-expressive-code/-/rehype-expressive-code-0.41.6.tgz", + "integrity": "sha512-aBMX8kxPtjmDSFUdZlAWJkMvsQ4ZMASfee90JWIAV8tweltXLzkWC3q++43ToTelI8ac5iC0B3/S/Cl4Ql1y2g==", + "license": "MIT", + "dependencies": { + "expressive-code": "^0.41.6" + } + }, + "node_modules/rehype-format": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/rehype-format/-/rehype-format-5.0.1.tgz", + "integrity": "sha512-zvmVru9uB0josBVpr946OR8ui7nJEdzZobwLOOqHb/OOD88W0Vk2SqLwoVOj0fM6IPCCO6TaV9CvQvJMWwukFQ==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "hast-util-format": "^1.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/rehype-parse": { + "version": "9.0.1", + "resolved": "https://registry.npmjs.org/rehype-parse/-/rehype-parse-9.0.1.tgz", + "integrity": "sha512-ksCzCD0Fgfh7trPDxr2rSylbwq9iYDkSn8TCDmEJ49ljEUBxDVCzCHv7QNzZOfODanX4+bWQ4WZqLCRWYLfhag==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "hast-util-from-html": "^2.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/rehype-raw": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/rehype-raw/-/rehype-raw-7.0.0.tgz", + "integrity": "sha512-/aE8hCfKlQeA8LmyeyQvQF3eBiLRGNlfBJEvWH7ivp9sBqs7TNqBL5X3v157rM4IFETqDnIOO+z5M/biZbo9Ww==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "hast-util-raw": "^9.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/rehype-recma": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/rehype-recma/-/rehype-recma-1.0.0.tgz", + "integrity": "sha512-lqA4rGUf1JmacCNWWZx0Wv1dHqMwxzsDWYMTowuplHF3xH0N/MmrZ/G3BDZnzAkRmxDadujCjaKM2hqYdCBOGw==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "@types/hast": "^3.0.0", + "hast-util-to-estree": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/rehype-stringify": { + "version": "10.0.1", + "resolved": "https://registry.npmjs.org/rehype-stringify/-/rehype-stringify-10.0.1.tgz", + "integrity": "sha512-k9ecfXHmIPuFVI61B9DeLPN0qFHfawM6RsuX48hoqlaKSF61RskNjSm1lI8PhBEM0MRdLxVVm4WmTqJQccH9mA==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "hast-util-to-html": "^9.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-directive": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/remark-directive/-/remark-directive-3.0.1.tgz", + "integrity": "sha512-gwglrEQEZcZYgVyG1tQuA+h58EZfq5CSULw7J90AFuCTyib1thgHPoqQ+h9iFvU6R+vnZ5oNFQR5QKgGpk741A==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-directive": "^3.0.0", + "micromark-extension-directive": "^3.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-gfm": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/remark-gfm/-/remark-gfm-4.0.1.tgz", + "integrity": "sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-gfm": "^3.0.0", + "micromark-extension-gfm": "^3.0.0", + "remark-parse": "^11.0.0", + "remark-stringify": "^11.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-mdx": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/remark-mdx/-/remark-mdx-3.1.1.tgz", + "integrity": "sha512-Pjj2IYlUY3+D8x00UJsIOg5BEvfMyeI+2uLPn9VO9Wg4MEtN/VTIq2NEJQfde9PnX15KgtHyl9S0BcTnWrIuWg==", + "license": "MIT", + "dependencies": { + "mdast-util-mdx": "^3.0.0", + "micromark-extension-mdxjs": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-parse": { + "version": "11.0.0", + "resolved": "https://registry.npmjs.org/remark-parse/-/remark-parse-11.0.0.tgz", + "integrity": "sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-from-markdown": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-rehype": { + "version": "11.1.2", + "resolved": "https://registry.npmjs.org/remark-rehype/-/remark-rehype-11.1.2.tgz", + "integrity": "sha512-Dh7l57ianaEoIpzbp0PC9UKAdCSVklD8E5Rpw7ETfbTl3FqcOOgq5q2LVDhgGCkaBv7p24JXikPdvhhmHvKMsw==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "mdast-util-to-hast": "^13.0.0", + "unified": "^11.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-smartypants": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/remark-smartypants/-/remark-smartypants-3.0.2.tgz", + "integrity": "sha512-ILTWeOriIluwEvPjv67v7Blgrcx+LZOkAUVtKI3putuhlZm84FnqDORNXPPm+HY3NdZOMhyDwZ1E+eZB/Df5dA==", + "license": "MIT", + "dependencies": { + "retext": "^9.0.0", + "retext-smartypants": "^6.0.0", + "unified": "^11.0.4", + "unist-util-visit": "^5.0.0" + }, + "engines": { + "node": ">=16.0.0" + } + }, + "node_modules/remark-stringify": { + "version": "11.0.0", + "resolved": "https://registry.npmjs.org/remark-stringify/-/remark-stringify-11.0.0.tgz", + "integrity": "sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-to-markdown": "^2.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/retext": { + "version": "9.0.0", + "resolved": "https://registry.npmjs.org/retext/-/retext-9.0.0.tgz", + "integrity": "sha512-sbMDcpHCNjvlheSgMfEcVrZko3cDzdbe1x/e7G66dFp0Ff7Mldvi2uv6JkJQzdRcvLYE8CA8Oe8siQx8ZOgTcA==", + "license": "MIT", + "dependencies": { + "@types/nlcst": "^2.0.0", + "retext-latin": "^4.0.0", + "retext-stringify": "^4.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/retext-latin": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/retext-latin/-/retext-latin-4.0.0.tgz", + "integrity": "sha512-hv9woG7Fy0M9IlRQloq/N6atV82NxLGveq+3H2WOi79dtIYWN8OaxogDm77f8YnVXJL2VD3bbqowu5E3EMhBYA==", + "license": "MIT", + "dependencies": { + "@types/nlcst": "^2.0.0", + "parse-latin": "^7.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/retext-smartypants": { + "version": "6.2.0", + "resolved": "https://registry.npmjs.org/retext-smartypants/-/retext-smartypants-6.2.0.tgz", + "integrity": "sha512-kk0jOU7+zGv//kfjXEBjdIryL1Acl4i9XNkHxtM7Tm5lFiCog576fjNC9hjoR7LTKQ0DsPWy09JummSsH1uqfQ==", + "license": "MIT", + "dependencies": { + "@types/nlcst": "^2.0.0", + "nlcst-to-string": "^4.0.0", + "unist-util-visit": "^5.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/retext-stringify": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/retext-stringify/-/retext-stringify-4.0.0.tgz", + "integrity": "sha512-rtfN/0o8kL1e+78+uxPTqu1Klt0yPzKuQ2BfWwwfgIUSayyzxpM1PJzkKt4V8803uB9qSy32MvI7Xep9khTpiA==", + "license": "MIT", + "dependencies": { + "@types/nlcst": "^2.0.0", + "nlcst-to-string": "^4.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/rollup": { + "version": "4.57.1", + "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.57.1.tgz", + "integrity": "sha512-oQL6lgK3e2QZeQ7gcgIkS2YZPg5slw37hYufJ3edKlfQSGGm8ICoxswK15ntSzF/a8+h7ekRy7k7oWc3BQ7y8A==", + "license": "MIT", + "dependencies": { + "@types/estree": "1.0.8" + }, + "bin": { + "rollup": "dist/bin/rollup" + }, + "engines": { + "node": ">=18.0.0", + "npm": ">=8.0.0" + }, + "optionalDependencies": { + "@rollup/rollup-android-arm-eabi": "4.57.1", + "@rollup/rollup-android-arm64": "4.57.1", + "@rollup/rollup-darwin-arm64": "4.57.1", + "@rollup/rollup-darwin-x64": "4.57.1", + "@rollup/rollup-freebsd-arm64": "4.57.1", + "@rollup/rollup-freebsd-x64": "4.57.1", + "@rollup/rollup-linux-arm-gnueabihf": "4.57.1", + "@rollup/rollup-linux-arm-musleabihf": "4.57.1", + "@rollup/rollup-linux-arm64-gnu": "4.57.1", + "@rollup/rollup-linux-arm64-musl": "4.57.1", + "@rollup/rollup-linux-loong64-gnu": "4.57.1", + "@rollup/rollup-linux-loong64-musl": "4.57.1", + "@rollup/rollup-linux-ppc64-gnu": "4.57.1", + "@rollup/rollup-linux-ppc64-musl": "4.57.1", + "@rollup/rollup-linux-riscv64-gnu": "4.57.1", + "@rollup/rollup-linux-riscv64-musl": "4.57.1", + "@rollup/rollup-linux-s390x-gnu": "4.57.1", + "@rollup/rollup-linux-x64-gnu": "4.57.1", + "@rollup/rollup-linux-x64-musl": "4.57.1", + "@rollup/rollup-openbsd-x64": "4.57.1", + "@rollup/rollup-openharmony-arm64": "4.57.1", + "@rollup/rollup-win32-arm64-msvc": "4.57.1", + "@rollup/rollup-win32-ia32-msvc": "4.57.1", + "@rollup/rollup-win32-x64-gnu": "4.57.1", + "@rollup/rollup-win32-x64-msvc": "4.57.1", + "fsevents": "~2.3.2" + } + }, + "node_modules/sax": { + "version": "1.4.4", + "resolved": "https://registry.npmjs.org/sax/-/sax-1.4.4.tgz", + "integrity": "sha512-1n3r/tGXO6b6VXMdFT54SHzT9ytu9yr7TaELowdYpMqY/Ao7EnlQGmAQ1+RatX7Tkkdm6hONI2owqNx2aZj5Sw==", + "license": "BlueOak-1.0.0", + "engines": { + "node": ">=11.0.0" + } + }, + "node_modules/semver": { + "version": "7.7.3", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz", + "integrity": "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==", + "license": "ISC", + "bin": { + "semver": "bin/semver.js" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/sharp": { + "version": "0.34.5", + "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.34.5.tgz", + "integrity": "sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==", + "hasInstallScript": true, + "license": "Apache-2.0", + "dependencies": { + "@img/colour": "^1.0.0", + "detect-libc": "^2.1.2", + "semver": "^7.7.3" + }, + "engines": { + "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-darwin-arm64": "0.34.5", + "@img/sharp-darwin-x64": "0.34.5", + "@img/sharp-libvips-darwin-arm64": "1.2.4", + "@img/sharp-libvips-darwin-x64": "1.2.4", + "@img/sharp-libvips-linux-arm": "1.2.4", + "@img/sharp-libvips-linux-arm64": "1.2.4", + "@img/sharp-libvips-linux-ppc64": "1.2.4", + "@img/sharp-libvips-linux-riscv64": "1.2.4", + "@img/sharp-libvips-linux-s390x": "1.2.4", + "@img/sharp-libvips-linux-x64": "1.2.4", + "@img/sharp-libvips-linuxmusl-arm64": "1.2.4", + "@img/sharp-libvips-linuxmusl-x64": "1.2.4", + "@img/sharp-linux-arm": "0.34.5", + "@img/sharp-linux-arm64": "0.34.5", + "@img/sharp-linux-ppc64": "0.34.5", + "@img/sharp-linux-riscv64": "0.34.5", + "@img/sharp-linux-s390x": "0.34.5", + "@img/sharp-linux-x64": "0.34.5", + "@img/sharp-linuxmusl-arm64": "0.34.5", + "@img/sharp-linuxmusl-x64": "0.34.5", + "@img/sharp-wasm32": "0.34.5", + "@img/sharp-win32-arm64": "0.34.5", + "@img/sharp-win32-ia32": "0.34.5", + "@img/sharp-win32-x64": "0.34.5" + } + }, + "node_modules/shiki": { + "version": "3.22.0", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-3.22.0.tgz", + "integrity": "sha512-LBnhsoYEe0Eou4e1VgJACes+O6S6QC0w71fCSp5Oya79inkwkm15gQ1UF6VtQ8j/taMDh79hAB49WUk8ALQW3g==", + "license": "MIT", + "dependencies": { + "@shikijs/core": "3.22.0", + "@shikijs/engine-javascript": "3.22.0", + "@shikijs/engine-oniguruma": "3.22.0", + "@shikijs/langs": "3.22.0", + "@shikijs/themes": "3.22.0", + "@shikijs/types": "3.22.0", + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4" + } + }, + "node_modules/sisteransi": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/sisteransi/-/sisteransi-1.0.5.tgz", + "integrity": "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==", + "license": "MIT" + }, + "node_modules/sitemap": { + "version": "8.0.2", + "resolved": "https://registry.npmjs.org/sitemap/-/sitemap-8.0.2.tgz", + "integrity": "sha512-LwktpJcyZDoa0IL6KT++lQ53pbSrx2c9ge41/SeLTyqy2XUNA6uR4+P9u5IVo5lPeL2arAcOKn1aZAxoYbCKlQ==", + "license": "MIT", + "dependencies": { + "@types/node": "^17.0.5", + "@types/sax": "^1.2.1", + "arg": "^5.0.0", + "sax": "^1.4.1" + }, + "bin": { + "sitemap": "dist/cli.js" + }, + "engines": { + "node": ">=14.0.0", + "npm": ">=6.0.0" + } + }, + "node_modules/sitemap/node_modules/@types/node": { + "version": "17.0.45", + "resolved": "https://registry.npmjs.org/@types/node/-/node-17.0.45.tgz", + "integrity": "sha512-w+tIMs3rq2afQdsPJlODhoUEKzFP1ayaoyl1CcnwtIlsVe7K7bA1NGm4s3PraqTLlXnbIN84zuBlxBWo1u9BLw==", + "license": "MIT" + }, + "node_modules/smol-toml": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.6.0.tgz", + "integrity": "sha512-4zemZi0HvTnYwLfrpk/CF9LOd9Lt87kAt50GnqhMpyF9U3poDAP2+iukq2bZsO/ufegbYehBkqINbsWxj4l4cw==", + "license": "BSD-3-Clause", + "engines": { + "node": ">= 18" + }, + "funding": { + "url": "https://github.com/sponsors/cyyynthia" + } + }, + "node_modules/source-map": { + "version": "0.7.6", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.7.6.tgz", + "integrity": "sha512-i5uvt8C3ikiWeNZSVZNWcfZPItFQOsYTUAOkcUPGd8DqDy1uOUikjt5dG+uRlwyvR108Fb9DOd4GvXfT0N2/uQ==", + "license": "BSD-3-Clause", + "engines": { + "node": ">= 12" + } + }, + "node_modules/source-map-js": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz", + "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==", + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/space-separated-tokens": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/space-separated-tokens/-/space-separated-tokens-2.0.2.tgz", + "integrity": "sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/stream-replace-string": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/stream-replace-string/-/stream-replace-string-2.0.0.tgz", + "integrity": "sha512-TlnjJ1C0QrmxRNrON00JvaFFlNh5TTG00APw23j74ET7gkQpTASi6/L2fuiav8pzK715HXtUeClpBTw2NPSn6w==", + "license": "MIT" + }, + "node_modules/string-width": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-7.2.0.tgz", + "integrity": "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==", + "license": "MIT", + "dependencies": { + "emoji-regex": "^10.3.0", + "get-east-asian-width": "^1.0.0", + "strip-ansi": "^7.1.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/stringify-entities": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/stringify-entities/-/stringify-entities-4.0.4.tgz", + "integrity": "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==", + "license": "MIT", + "dependencies": { + "character-entities-html4": "^2.0.0", + "character-entities-legacy": "^3.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/strip-ansi": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.1.2.tgz", + "integrity": "sha512-gmBGslpoQJtgnMAvOVqGZpEz9dyoKTCzy2nfz/n8aIFhN/jCE/rCmcxabB6jOOHV+0WNnylOxaxBQPSvcWklhA==", + "license": "MIT", + "dependencies": { + "ansi-regex": "^6.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/strip-ansi?sponsor=1" + } + }, + "node_modules/style-to-js": { + "version": "1.1.21", + "resolved": "https://registry.npmjs.org/style-to-js/-/style-to-js-1.1.21.tgz", + "integrity": "sha512-RjQetxJrrUJLQPHbLku6U/ocGtzyjbJMP9lCNK7Ag0CNh690nSH8woqWH9u16nMjYBAok+i7JO1NP2pOy8IsPQ==", + "license": "MIT", + "dependencies": { + "style-to-object": "1.0.14" + } + }, + "node_modules/style-to-object": { + "version": "1.0.14", + "resolved": "https://registry.npmjs.org/style-to-object/-/style-to-object-1.0.14.tgz", + "integrity": "sha512-LIN7rULI0jBscWQYaSswptyderlarFkjQ+t79nzty8tcIAceVomEVlLzH5VP4Cmsv6MtKhs7qaAiwlcp+Mgaxw==", + "license": "MIT", + "dependencies": { + "inline-style-parser": "0.2.7" + } + }, + "node_modules/svgo": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/svgo/-/svgo-4.0.0.tgz", + "integrity": "sha512-VvrHQ+9uniE+Mvx3+C9IEe/lWasXCU0nXMY2kZeLrHNICuRiC8uMPyM14UEaMOFA5mhyQqEkB02VoQ16n3DLaw==", + "license": "MIT", + "dependencies": { + "commander": "^11.1.0", + "css-select": "^5.1.0", + "css-tree": "^3.0.1", + "css-what": "^6.1.0", + "csso": "^5.0.5", + "picocolors": "^1.1.1", + "sax": "^1.4.1" + }, + "bin": { + "svgo": "bin/svgo.js" + }, + "engines": { + "node": ">=16" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/svgo" + } + }, + "node_modules/tiny-inflate": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/tiny-inflate/-/tiny-inflate-1.0.3.tgz", + "integrity": "sha512-pkY1fj1cKHb2seWDy0B16HeWyczlJA9/WW3u3c4z/NiWDsO3DOU5D7nhTLE9CF0yXv/QZFY7sEJmj24dK+Rrqw==", + "license": "MIT" + }, + "node_modules/tinyexec": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.0.2.tgz", + "integrity": "sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg==", + "license": "MIT", + "engines": { + "node": ">=18" + } + }, + "node_modules/tinyglobby": { + "version": "0.2.15", + "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.15.tgz", + "integrity": "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==", + "license": "MIT", + "dependencies": { + "fdir": "^6.5.0", + "picomatch": "^4.0.3" + }, + "engines": { + "node": ">=12.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/SuperchupuDev" + } + }, + "node_modules/trim-lines": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/trim-lines/-/trim-lines-3.0.1.tgz", + "integrity": "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/trough": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/trough/-/trough-2.2.0.tgz", + "integrity": "sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/tsconfck": { + "version": "3.1.6", + "resolved": "https://registry.npmjs.org/tsconfck/-/tsconfck-3.1.6.tgz", + "integrity": "sha512-ks6Vjr/jEw0P1gmOVwutM3B7fWxoWBL2KRDb1JfqGVawBmO5UsvmWOQFGHBPl5yxYz4eERr19E6L7NMv+Fej4w==", + "license": "MIT", + "bin": { + "tsconfck": "bin/tsconfck.js" + }, + "engines": { + "node": "^18 || >=20" + }, + "peerDependencies": { + "typescript": "^5.0.0" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + } + } + }, + "node_modules/tslib": { + "version": "2.8.1", + "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz", + "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==", + "license": "0BSD", + "optional": true + }, + "node_modules/type-fest": { + "version": "4.41.0", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-4.41.0.tgz", + "integrity": "sha512-TeTSQ6H5YHvpqVwBRcnLDCBnDOHWYu7IvGbHT6N8AOymcr9PJGjc1GTtiWZTYg0NCgYwvnYWEkVChQAr9bjfwA==", + "license": "(MIT OR CC0-1.0)", + "engines": { + "node": ">=16" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "license": "Apache-2.0", + "peer": true, + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/ufo": { + "version": "1.6.3", + "resolved": "https://registry.npmjs.org/ufo/-/ufo-1.6.3.tgz", + "integrity": "sha512-yDJTmhydvl5lJzBmy/hyOAA0d+aqCBuwl818haVdYCRrWV84o7YyeVm4QlVHStqNrrJSTb6jKuFAVqAFsr+K3Q==", + "license": "MIT" + }, + "node_modules/ultrahtml": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/ultrahtml/-/ultrahtml-1.6.0.tgz", + "integrity": "sha512-R9fBn90VTJrqqLDwyMph+HGne8eqY1iPfYhPzZrvKpIfwkWZbcYlfpsb8B9dTvBfpy1/hqAD7Wi8EKfP9e8zdw==", + "license": "MIT" + }, + "node_modules/uncrypto": { + "version": "0.1.3", + "resolved": "https://registry.npmjs.org/uncrypto/-/uncrypto-0.1.3.tgz", + "integrity": "sha512-Ql87qFHB3s/De2ClA9e0gsnS6zXG27SkTiSJwjCc9MebbfapQfuPzumMIUMi38ezPZVNFcHI9sUIepeQfw8J8Q==", + "license": "MIT" + }, + "node_modules/undici-types": { + "version": "7.16.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz", + "integrity": "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==", + "license": "MIT" + }, + "node_modules/unified": { + "version": "11.0.5", + "resolved": "https://registry.npmjs.org/unified/-/unified-11.0.5.tgz", + "integrity": "sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "bail": "^2.0.0", + "devlop": "^1.0.0", + "extend": "^3.0.0", + "is-plain-obj": "^4.0.0", + "trough": "^2.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unifont": { + "version": "0.7.3", + "resolved": "https://registry.npmjs.org/unifont/-/unifont-0.7.3.tgz", + "integrity": "sha512-b0GtQzKCyuSHGsfj5vyN8st7muZ6VCI4XD4vFlr7Uy1rlWVYxC3npnfk8MyreHxJYrz1ooLDqDzFe9XqQTlAhA==", + "license": "MIT", + "dependencies": { + "css-tree": "^3.1.0", + "ofetch": "^1.5.1", + "ohash": "^2.0.11" + } + }, + "node_modules/unist-util-find-after": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/unist-util-find-after/-/unist-util-find-after-5.0.0.tgz", + "integrity": "sha512-amQa0Ep2m6hE2g72AugUItjbuM8X8cGQnFoHk0pGfrFeT9GZhzN5SW8nRsiGKK7Aif4CrACPENkA6P/Lw6fHGQ==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-is": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-6.0.1.tgz", + "integrity": "sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-modify-children": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/unist-util-modify-children/-/unist-util-modify-children-4.0.0.tgz", + "integrity": "sha512-+tdN5fGNddvsQdIzUF3Xx82CU9sMM+fA0dLgR9vOmT0oPT2jH+P1nd5lSqfCfXAw+93NhcXNY2qqvTUtE4cQkw==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "array-iterate": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-position": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/unist-util-position/-/unist-util-position-5.0.0.tgz", + "integrity": "sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-position-from-estree": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/unist-util-position-from-estree/-/unist-util-position-from-estree-2.0.0.tgz", + "integrity": "sha512-KaFVRjoqLyF6YXCbVLNad/eS4+OfPQQn2yOd7zF/h5T/CSL2v8NpN6a5TPvtbXthAGw5nG+PuTtq+DdIZr+cRQ==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-remove-position": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/unist-util-remove-position/-/unist-util-remove-position-5.0.0.tgz", + "integrity": "sha512-Hp5Kh3wLxv0PHj9m2yZhhLt58KzPtEYKQQ4yxfYFEO7EvHwzyDYnduhHnY1mDxoqr7VUwVuHXk9RXKIiYS1N8Q==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-visit": "^5.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-stringify-position": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-4.0.0.tgz", + "integrity": "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-5.1.0.tgz", + "integrity": "sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0", + "unist-util-visit-parents": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit-children": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/unist-util-visit-children/-/unist-util-visit-children-3.0.0.tgz", + "integrity": "sha512-RgmdTfSBOg04sdPcpTSD1jzoNBjt9a80/ZCzp5cI9n1qPzLZWF9YdvWGN2zmTumP1HWhXKdUWexjy/Wy/lJ7tA==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit-parents": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-6.0.2.tgz", + "integrity": "sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unstorage": { + "version": "1.17.4", + "resolved": "https://registry.npmjs.org/unstorage/-/unstorage-1.17.4.tgz", + "integrity": "sha512-fHK0yNg38tBiJKp/Vgsq4j0JEsCmgqH58HAn707S7zGkArbZsVr/CwINoi+nh3h98BRCwKvx1K3Xg9u3VV83sw==", + "license": "MIT", + "dependencies": { + "anymatch": "^3.1.3", + "chokidar": "^5.0.0", + "destr": "^2.0.5", + "h3": "^1.15.5", + "lru-cache": "^11.2.0", + "node-fetch-native": "^1.6.7", + "ofetch": "^1.5.1", + "ufo": "^1.6.3" + }, + "peerDependencies": { + "@azure/app-configuration": "^1.8.0", + "@azure/cosmos": "^4.2.0", + "@azure/data-tables": "^13.3.0", + "@azure/identity": "^4.6.0", + "@azure/keyvault-secrets": "^4.9.0", + "@azure/storage-blob": "^12.26.0", + "@capacitor/preferences": "^6 || ^7 || ^8", + "@deno/kv": ">=0.9.0", + "@netlify/blobs": "^6.5.0 || ^7.0.0 || ^8.1.0 || ^9.0.0 || ^10.0.0", + "@planetscale/database": "^1.19.0", + "@upstash/redis": "^1.34.3", + "@vercel/blob": ">=0.27.1", + "@vercel/functions": "^2.2.12 || ^3.0.0", + "@vercel/kv": "^1 || ^2 || ^3", + "aws4fetch": "^1.0.20", + "db0": ">=0.2.1", + "idb-keyval": "^6.2.1", + "ioredis": "^5.4.2", + "uploadthing": "^7.4.4" + }, + "peerDependenciesMeta": { + "@azure/app-configuration": { + "optional": true + }, + "@azure/cosmos": { + "optional": true + }, + "@azure/data-tables": { + "optional": true + }, + "@azure/identity": { + "optional": true + }, + "@azure/keyvault-secrets": { + "optional": true + }, + "@azure/storage-blob": { + "optional": true + }, + "@capacitor/preferences": { + "optional": true + }, + "@deno/kv": { + "optional": true + }, + "@netlify/blobs": { + "optional": true + }, + "@planetscale/database": { + "optional": true + }, + "@upstash/redis": { + "optional": true + }, + "@vercel/blob": { + "optional": true + }, + "@vercel/functions": { + "optional": true + }, + "@vercel/kv": { + "optional": true + }, + "aws4fetch": { + "optional": true + }, + "db0": { + "optional": true + }, + "idb-keyval": { + "optional": true + }, + "ioredis": { + "optional": true + }, + "uploadthing": { + "optional": true + } + } + }, + "node_modules/util-deprecate": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz", + "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==", + "license": "MIT" + }, + "node_modules/vfile": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/vfile/-/vfile-6.0.3.tgz", + "integrity": "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/vfile-location": { + "version": "5.0.3", + "resolved": "https://registry.npmjs.org/vfile-location/-/vfile-location-5.0.3.tgz", + "integrity": "sha512-5yXvWDEgqeiYiBe1lbxYF7UMAIm/IcopxMHrMQDq3nvKcjPKIhZklUKL+AE7J7uApI4kwe2snsK+eI6UTj9EHg==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/vfile-message": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-4.0.3.tgz", + "integrity": "sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-stringify-position": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/vite": { + "version": "6.4.1", + "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.1.tgz", + "integrity": "sha512-+Oxm7q9hDoLMyJOYfUYBuHQo+dkAloi33apOPP56pzj+vsdJDzr+j1NISE5pyaAuKL4A3UD34qd0lx5+kfKp2g==", + "license": "MIT", + "dependencies": { + "esbuild": "^0.25.0", + "fdir": "^6.4.4", + "picomatch": "^4.0.2", + "postcss": "^8.5.3", + "rollup": "^4.34.9", + "tinyglobby": "^0.2.13" + }, + "bin": { + "vite": "bin/vite.js" + }, + "engines": { + "node": "^18.0.0 || ^20.0.0 || >=22.0.0" + }, + "funding": { + "url": "https://github.com/vitejs/vite?sponsor=1" + }, + "optionalDependencies": { + "fsevents": "~2.3.3" + }, + "peerDependencies": { + "@types/node": "^18.0.0 || ^20.0.0 || >=22.0.0", + "jiti": ">=1.21.0", + "less": "*", + "lightningcss": "^1.21.0", + "sass": "*", + "sass-embedded": "*", + "stylus": "*", + "sugarss": "*", + "terser": "^5.16.0", + "tsx": "^4.8.1", + "yaml": "^2.4.2" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + }, + "jiti": { + "optional": true + }, + "less": { + "optional": true + }, + "lightningcss": { + "optional": true + }, + "sass": { + "optional": true + }, + "sass-embedded": { + "optional": true + }, + "stylus": { + "optional": true + }, + "sugarss": { + "optional": true + }, + "terser": { + "optional": true + }, + "tsx": { + "optional": true + }, + "yaml": { + "optional": true + } + } + }, + "node_modules/vitefu": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/vitefu/-/vitefu-1.1.1.tgz", + "integrity": "sha512-B/Fegf3i8zh0yFbpzZ21amWzHmuNlLlmJT6n7bu5e+pCHUKQIfXSYokrqOBGEMMe9UG2sostKQF9mml/vYaWJQ==", + "license": "MIT", + "workspaces": [ + "tests/deps/*", + "tests/projects/*", + "tests/projects/workspace/packages/*" + ], + "peerDependencies": { + "vite": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0-beta.0" + }, + "peerDependenciesMeta": { + "vite": { + "optional": true + } + } + }, + "node_modules/web-namespaces": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/web-namespaces/-/web-namespaces-2.0.1.tgz", + "integrity": "sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/which-pm-runs": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/which-pm-runs/-/which-pm-runs-1.1.0.tgz", + "integrity": "sha512-n1brCuqClxfFfq/Rb0ICg9giSZqCS+pLtccdag6C2HyufBrh3fBOiy9nb6ggRMvWOVH5GrdJskj5iGTZNxd7SA==", + "license": "MIT", + "engines": { + "node": ">=4" + } + }, + "node_modules/widest-line": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/widest-line/-/widest-line-5.0.0.tgz", + "integrity": "sha512-c9bZp7b5YtRj2wOe6dlj32MK+Bx/M/d+9VB2SHM1OtsUHR0aV0tdP6DWh/iMt0kWi1t5g1Iudu6hQRNd1A4PVA==", + "license": "MIT", + "dependencies": { + "string-width": "^7.0.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/wrap-ansi": { + "version": "9.0.2", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-9.0.2.tgz", + "integrity": "sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==", + "license": "MIT", + "dependencies": { + "ansi-styles": "^6.2.1", + "string-width": "^7.0.0", + "strip-ansi": "^7.1.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, + "node_modules/xxhash-wasm": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/xxhash-wasm/-/xxhash-wasm-1.1.0.tgz", + "integrity": "sha512-147y/6YNh+tlp6nd/2pWq38i9h6mz/EuQ6njIrmW8D1BS5nCqs0P6DG+m6zTGnNz5I+uhZ0SHxBs9BsPrwcKDA==", + "license": "MIT" + }, + "node_modules/yargs-parser": { + "version": "21.1.1", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz", + "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==", + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/yocto-queue": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-1.2.2.tgz", + "integrity": "sha512-4LCcse/U2MHZ63HAJVE+v71o7yOdIe4cZ70Wpf8D/IyjDKYQLV5GD46B+hSTjJsvV5PztjvHoU580EftxjDZFQ==", + "license": "MIT", + "engines": { + "node": ">=12.20" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/yocto-spinner": { + "version": "0.2.3", + "resolved": "https://registry.npmjs.org/yocto-spinner/-/yocto-spinner-0.2.3.tgz", + "integrity": "sha512-sqBChb33loEnkoXte1bLg45bEBsOP9N1kzQh5JZNKj/0rik4zAPTNSAVPj3uQAdc6slYJ0Ksc403G2XgxsJQFQ==", + "license": "MIT", + "dependencies": { + "yoctocolors": "^2.1.1" + }, + "engines": { + "node": ">=18.19" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/yoctocolors": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/yoctocolors/-/yoctocolors-2.1.2.tgz", + "integrity": "sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/zod": { + "version": "3.25.76", + "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", + "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + }, + "node_modules/zod-to-json-schema": { + "version": "3.25.1", + "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.1.tgz", + "integrity": "sha512-pM/SU9d3YAggzi6MtR4h7ruuQlqKtad8e9S0fmxcMi+ueAK5Korys/aWcV9LIIHTVbj01NdzxcnXSN+O74ZIVA==", + "license": "ISC", + "peerDependencies": { + "zod": "^3.25 || ^4" + } + }, + "node_modules/zod-to-ts": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/zod-to-ts/-/zod-to-ts-1.2.0.tgz", + "integrity": "sha512-x30XE43V+InwGpvTySRNz9kB7qFU8DlyEy7BsSTCHPH1R0QasMmHWZDCzYm6bVXtj/9NNJAZF3jW8rzFvH5OFA==", + "peerDependencies": { + "typescript": "^4.9.4 || ^5.0.2", + "zod": "^3" + } + }, + "node_modules/zwitch": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-2.0.4.tgz", + "integrity": "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + } + } +} diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 0000000..5719739 --- /dev/null +++ b/docs/package.json @@ -0,0 +1,17 @@ +{ + "name": "mcserial-docs", + "type": "module", + "version": "0.0.1", + "scripts": { + "dev": "astro dev", + "start": "astro dev", + "build": "astro build", + "preview": "astro preview", + "astro": "astro" + }, + "dependencies": { + "@astrojs/starlight": "^0.37.4", + "astro": "5.16.15", + "sharp": "^0.34.2" + } +} diff --git a/docs/public/favicon.svg b/docs/public/favicon.svg new file mode 100644 index 0000000..9efdc10 --- /dev/null +++ b/docs/public/favicon.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/docs/src/assets/logo.svg b/docs/src/assets/logo.svg new file mode 100644 index 0000000..9f0fa3d --- /dev/null +++ b/docs/src/assets/logo.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + diff --git a/docs/src/content.config.ts b/docs/src/content.config.ts new file mode 100644 index 0000000..6a7b7a0 --- /dev/null +++ b/docs/src/content.config.ts @@ -0,0 +1,7 @@ +import { defineCollection } from 'astro:content'; +import { docsLoader } from '@astrojs/starlight/loaders'; +import { docsSchema } from '@astrojs/starlight/schema'; + +export const collections = { + docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }), +}; diff --git a/docs/src/content/docs/concepts/flow-control.mdx b/docs/src/content/docs/concepts/flow-control.mdx new file mode 100644 index 0000000..214103f --- /dev/null +++ b/docs/src/content/docs/concepts/flow-control.mdx @@ -0,0 +1,192 @@ +--- +title: Flow Control +description: Understanding software and hardware flow control for serial communication +--- + +import { Aside } from '@astrojs/starlight/components'; + +Flow control prevents data loss when one side of a serial connection sends data faster than the other side can process it. Without flow control, the receiver's buffer fills up, and incoming bytes are silently dropped. + +There are two approaches: software flow control using in-band control characters, and hardware flow control using dedicated signal lines. + +## Software flow control (XON/XOFF) + +Software flow control uses two special byte values embedded in the data stream: + +| Character | Hex | ASCII | Meaning | +|-----------|-----|-------|---------| +| XON | `0x11` | Ctrl-Q | "Resume sending -- I can accept data" | +| XOFF | `0x13` | Ctrl-S | "Stop sending -- my buffer is full" | + +When the receiver's buffer fills up, it sends XOFF to the sender. The sender pauses until it receives XON, then resumes transmission. + +### Enabling XON/XOFF + +Enable it when opening a port: + +```json +// open_serial_port(port="/dev/ttyUSB0", baudrate=9600, xonxoff=true) +``` + +Or toggle it on an open port: + +```json +// configure_serial(port="/dev/ttyUSB0", xonxoff=true) +{ + "success": true, + "port": "/dev/ttyUSB0", + "xonxoff": true, + "rtscts": false, + "dsrdtr": false +} +``` + +### Manual flow gating + +The `set_flow_control` tool lets you manually send XON/XOFF signals or pause/resume your own output: + +```json +// Tell the remote device to stop sending +// set_flow_control(port="/dev/ttyUSB0", input_flow=false) +{ + "success": true, + "port": "/dev/ttyUSB0", + "changes": {"input_flow": false}, + "flow_control_enabled": {"xonxoff": true, "rtscts": false} +} + +// Tell the remote device to resume sending +// set_flow_control(port="/dev/ttyUSB0", input_flow=true) +``` + +- `input_flow=true` sends XON (allow the remote device to send to us) +- `input_flow=false` sends XOFF (tell the remote device to pause) +- `output_flow=true` resumes our outgoing data +- `output_flow=false` pauses our outgoing data + +Flow control must already be enabled (via `xonxoff=true` or `rtscts=true`) for these signals to have effect. + +### Advantages and limitations + +**Advantages:** +- Works on any serial connection, including 3-wire (TX, RX, GND) cables with no additional signal lines +- Works over network serial connections (`socket://`, `rfc2217://`) +- No extra hardware required + + + +## Hardware flow control (RTS/CTS) + +Hardware flow control uses dedicated signal lines rather than in-band bytes. The most common pair is **RTS** (Request To Send) and **CTS** (Clear To Send). + +When the receiver's buffer is getting full, it deasserts CTS. The sender watches CTS and pauses transmission until CTS is asserted again. Because the signaling happens on separate wires, it works with any data content -- there are no reserved byte values. + +### Enabling RTS/CTS + +Enable it when opening a port: + +```json +// open_serial_port(port="/dev/ttyUSB0", baudrate=115200, rtscts=true) +``` + +Or toggle it on an open port: + +```json +// configure_serial(port="/dev/ttyUSB0", rtscts=true) +{ + "success": true, + "port": "/dev/ttyUSB0", + "xonxoff": false, + "rtscts": true, + "dsrdtr": false +} +``` + +### Advantages and limitations + +**Advantages:** +- Works with binary data -- no reserved byte values +- Faster response than XON/XOFF (hardware signal vs. byte transmission delay) +- Handled by the UART hardware, not software + +**Limitations:** +- Requires a cable with RTS and CTS lines connected (some cheap cables omit them) +- Not available on 3-wire serial connections +- Not meaningful on `socket://` network connections (no physical lines to assert) + +## Hardware flow control (DSR/DTR) + +An alternative hardware flow control pair. DSR (Data Set Ready) and DTR (Data Terminal Ready) can serve as flow control signals when RTS/CTS is unavailable or already used for another purpose. + +```json +// open_serial_port(port="/dev/ttyUSB0", baudrate=9600, dsrdtr=true) +``` + +DSR/DTR flow control is less common than RTS/CTS. Most devices that support hardware flow control use RTS/CTS. + + + +## Choosing the right flow control + +| Scenario | Recommended | Reason | +|----------|-------------|--------| +| Text/ASCII protocols (AT commands, console) | XON/XOFF | Simple, no extra wires needed | +| Binary protocols (Modbus RTU, firmware transfer) | RTS/CTS | No byte value conflicts | +| Network serial (`socket://`) | None | TCP handles flow control at the transport layer | +| High-speed transfers (115200+) | RTS/CTS | Faster response, less latency than XON/XOFF | +| 3-wire cable (TX, RX, GND only) | XON/XOFF | RTS/CTS lines not available | +| RS-485 bus | XON/XOFF or None | RTS is used for direction control | +| Unknown device | Start with None | Add flow control if you see buffer overruns | + +## Flow control in mcserial + +All flow control options are available in two places: + +**At open time:** + +```json +// open_serial_port( +// port="/dev/ttyUSB0", +// baudrate=9600, +// xonxoff=false, +// rtscts=false, +// dsrdtr=false +// ) +``` + +**On an already-open port:** + +```json +// configure_serial( +// port="/dev/ttyUSB0", +// xonxoff=true, +// rtscts=false, +// dsrdtr=false +// ) +``` + +You can enable multiple flow control methods simultaneously, though this is unusual. The most common configurations are: + +- **No flow control** (all false) -- suitable when you control the data rate, or when using protocols that handle their own flow management +- **XON/XOFF only** -- text terminals, console access, simple ASCII protocols +- **RTS/CTS only** -- binary transfers, high-speed communication, GPS receivers + +### Detecting flow control problems + +If you suspect flow control issues, look for these symptoms: + +- **Missing data in the middle of a transfer**: the receiver's buffer overflowed and bytes were dropped. Enable flow control. +- **Data stops flowing and never resumes**: the sender received XOFF but never got XON (or CTS was deasserted and never reasserted). Check cable connections and remote device state. +- **Corrupted binary data with 0x11 or 0x13 bytes missing**: XON/XOFF is enabled on a binary stream. Switch to RTS/CTS or disable flow control. + +Use `get_connection_status` to check the current flow control configuration and modem line states for all open ports. diff --git a/docs/src/content/docs/concepts/rs232-vs-rs485.mdx b/docs/src/content/docs/concepts/rs232-vs-rs485.mdx new file mode 100644 index 0000000..c6400d6 --- /dev/null +++ b/docs/src/content/docs/concepts/rs232-vs-rs485.mdx @@ -0,0 +1,107 @@ +--- +title: RS-232 vs RS-485 +description: Understanding the differences between RS-232 and RS-485 serial communication +--- + +import { Aside } from '@astrojs/starlight/components'; + +RS-232 and RS-485 are two serial communication standards that solve different problems. RS-232 connects one device to another over short distances. RS-485 connects many devices on a shared bus over long distances. Understanding when to use each one determines which mcserial tools you reach for. + +## Physical layer + +The fundamental difference is how voltage signals are represented on the wire. + +**RS-232** uses single-ended signaling: each signal is measured as a voltage relative to ground. A logic HIGH is -3V to -15V, and a logic LOW is +3V to +15V (inverted from what you might expect). This means every signal needs its own wire plus a shared ground, and the voltage swings are large. + +**RS-485** uses differential signaling: each signal is carried on a pair of wires (typically labeled A and B). The receiver reads the voltage *difference* between the two wires, ignoring any common-mode noise that affects both wires equally. This is what gives RS-485 its noise immunity. + +| Property | RS-232 | RS-485 | +|----------|--------|--------| +| Signaling | Single-ended (voltage to ground) | Differential (voltage between A and B) | +| Voltage levels | +/-3V to +/-15V | +/-1.5V to +/-6V differential | +| Max cable length | ~15 meters (50 feet) | ~1200 meters (4000 feet) | +| Max devices | 2 (point-to-point) | 32 standard, 256 with high-impedance receivers | +| Duplex | Full-duplex (separate TX and RX lines) | Half-duplex on 2 wires, full-duplex on 4 wires | +| Noise immunity | Low (susceptible to ground loops) | High (differential rejection of common-mode noise) | +| Typical connectors | DB-9, DB-25 | Screw terminals, RJ-45, DB-9 (repurposed) | + +## Communication models + +### RS-232: point-to-point + +RS-232 is always a conversation between two devices. One device (the DTE, Data Terminal Equipment -- originally a terminal or computer) talks to another device (the DCE, Data Communications Equipment -- originally a modem). They have separate transmit and receive lines, so both can send data simultaneously (full-duplex). + +RS-232 also defines modem control lines -- dedicated signals for hardware flow control, device presence, and status: + +- **DTR / DSR**: "I'm here and ready" handshake +- **RTS / CTS**: "I want to send" / "Go ahead" flow control +- **RI**: "There's an incoming call" (modems) +- **CD**: "I have a connection" (modems) + +These extra lines are what make RS-232 useful for tasks beyond raw data transfer: you can detect whether a device is connected, pause data flow when a buffer fills up, or pulse DTR to reset a microcontroller. + +### RS-485: multi-drop bus + +RS-485 is a shared bus. Multiple devices connect to the same pair of wires. Only one device transmits at a time while all others listen. This requires a protocol layer on top of the electrical standard to manage who talks when -- Modbus RTU being the most common example. + +Because the bus is shared, RS-485 devices need a way to switch between transmitting and receiving. The transceiver chip has a Driver Enable (DE) and Receiver Enable (RE) pin. When a device wants to transmit, it asserts DE to drive the bus, sends its data, then deasserts DE to go back to listening. Some adapters handle this toggling in hardware; others require software control via the RTS line. + +## When to use RS-232 + +RS-232 is the right choice when: + +- **You are connecting directly to a single device** -- a sensor, a microcontroller, a modem, or a piece of lab equipment. +- **You need modem control lines** -- DTR for resetting an Arduino, CTS for hardware flow control, DSR for detecting device presence. +- **Cable runs are short** -- within the same desk, rack, or room (under 15 meters). +- **You are using a USB-serial adapter** -- the vast majority default to RS-232 behavior. + + + +## When to use RS-485 + +RS-485 is the right choice when: + +- **Multiple devices share one bus** -- sensor networks, building automation, industrial control. RS-485 supports up to 32 devices (standard) or 256 (with high-impedance receivers) on a single pair of wires. +- **Long cable runs** -- RS-485's differential signaling works reliably over 1200 meters. RS-232 becomes unreliable beyond 15 meters. +- **Industrial environments** -- factories, power plants, and outdoor installations where electrical noise from motors, inverters, and power supplies would corrupt RS-232 signals. Differential signaling rejects common-mode noise. +- **Industrial protocols** -- Modbus RTU, PROFIBUS, and DMX-512 all run over RS-485. +- **Noisy environments** -- even in non-industrial settings, long cable runs near power wiring benefit from differential signaling. + +## How mcserial handles the difference + +mcserial tracks which mode each port is in and restricts tools accordingly. This prevents accidentally sending RS-232 modem control commands on an RS-485 bus (which would disrupt communication by toggling the direction control line). + +### Default: RS-232 mode + +Every port opens in RS-232 mode. The following tools are available: + +- `get_modem_lines` -- read CTS, DSR, RI, CD, RTS, DTR +- `set_modem_lines` -- set RTS and DTR +- `pulse_line` -- pulse RTS or DTR for reset sequences +- `send_break` -- send a timed break signal +- `set_break_condition` -- hold or release sustained break + +### After switching: RS-485 mode + +Call `set_port_mode(port, "rs485")` to switch. The RS-232 tools become unavailable and these tools become available: + +- `set_rs485_mode` -- configure hardware DE/RE direction control +- `rs485_transact` -- send data and receive response with automatic turnaround +- `rs485_scan_addresses` -- discover devices on the bus +- `check_rs485_support` -- determine hardware capabilities + +### Shared tools + +These tools work in both modes: + +- `open_serial_port` / `close_serial_port` +- `read_serial` / `write_serial` / `write_serial_bytes` +- `read_serial_line` / `read_serial_lines` / `read_until` +- `configure_serial` / `flush_serial` +- `detect_baud_rate` +- `set_flow_control` / `set_low_latency_mode` +- `file_transfer_send` / `file_transfer_receive` / `file_transfer_send_batch` + +You can switch modes on an open port at any time with `set_port_mode`. No reconnection is needed. diff --git a/docs/src/content/docs/guides/file-transfers.mdx b/docs/src/content/docs/guides/file-transfers.mdx new file mode 100644 index 0000000..342cc11 --- /dev/null +++ b/docs/src/content/docs/guides/file-transfers.mdx @@ -0,0 +1,221 @@ +--- +title: File Transfers +description: Sending and receiving files over serial using X/Y/ZMODEM protocols +--- + +import { Steps, Aside } from '@astrojs/starlight/components'; + +Serial file transfers are useful when you need to move files to or from devices that lack network connectivity: embedded systems running a bootloader, legacy industrial equipment, air-gapped machines, or remote hardware accessed through a serial console. + +mcserial implements four protocol variants, all built in without external dependencies. + +## Protocol comparison + +| Protocol | Block Size | Batch | Resume | Error Detection | Best For | +|----------|-----------|-------|--------|-----------------|----------| +| XMODEM | 128 bytes | No | No | Checksum or CRC-16 | Legacy compatibility, simple devices | +| XMODEM-1K | 1024 bytes | No | No | CRC-16 | Faster XMODEM with wider block size | +| YMODEM | 1024 bytes | Yes | No | CRC-16 | Multiple files, preserves filenames | +| ZMODEM | Streaming | Yes | Yes | CRC-32 | Everything else (recommended) | + +**ZMODEM** is the recommended protocol in nearly all cases. It streams data without waiting for per-block acknowledgment, supports batch transfers, can resume interrupted transfers, and uses 32-bit CRC for reliable error detection. + +Use XMODEM only when the remote device does not support anything newer -- some bootloaders and legacy equipment only speak XMODEM. + +## Sending a file + +Use `file_transfer_send` to transmit a file to the remote device. + +```json +// file_transfer_send( +// port="/dev/ttyUSB0", +// file_path="/home/user/firmware.bin", +// protocol="zmodem" +// ) +{ + "success": true, + "protocol": "zmodem", + "file": "/home/user/firmware.bin", + "bytes_sent": 65536, + "blocks_sent": 64 +} +``` + + + +## Receiving a file + +Use `file_transfer_receive` to download a file from the remote device. + +The meaning of `save_path` depends on the protocol: + +- **XMODEM**: `save_path` is the full file path (e.g., `/tmp/received.bin`). XMODEM does not transmit filenames. +- **YMODEM / ZMODEM**: `save_path` is a directory. The filename comes from the sender's metadata. + +```json +// Receiving with XMODEM (save_path is a file path) +// file_transfer_receive( +// port="/dev/ttyUSB0", +// save_path="/tmp/received.bin", +// protocol="xmodem" +// ) +{ + "success": true, + "protocol": "xmodem", + "file": "/tmp/received.bin", + "bytes_received": 8192 +} + +// Receiving with ZMODEM (save_path is a directory) +// file_transfer_receive( +// port="/dev/ttyUSB0", +// save_path="/tmp/downloads/", +// protocol="zmodem" +// ) +{ + "success": true, + "protocol": "zmodem", + "files_received": 1, + "bytes_received": 65536 +} +``` + +Set `overwrite=true` if you want to replace existing files at the destination. By default, the transfer fails if a file already exists. + +## Batch transfers + +YMODEM and ZMODEM support sending multiple files in a single session. Use `file_transfer_send_batch`: + +```json +// file_transfer_send_batch( +// port="/dev/ttyUSB0", +// file_paths=[ +// "/home/user/firmware.bin", +// "/home/user/config.json", +// "/home/user/certs/device.pem" +// ], +// protocol="zmodem" +// ) +{ + "success": true, + "protocol": "zmodem", + "files_sent": 3, + "total_bytes": 98304 +} +``` + +XMODEM does not support batch transfers -- it has no concept of filenames or session boundaries. If you try to use `file_transfer_send_batch` with XMODEM, you will get an error. + +## Security + +mcserial validates all file paths during transfers: + +- **Directory traversal prevention**: Filenames received from the remote side are sanitized. Paths containing `..` or absolute path components are rejected. +- **Overwrite protection**: By default, receiving a file that already exists on disk returns an error. Pass `overwrite=true` to allow replacement. +- **Parent directory creation**: When receiving, mcserial creates parent directories as needed using `mkdir -p` behavior. + +## Practical example: uploading firmware + +This example walks through uploading a firmware binary to an embedded device over its serial debug port. + + + +1. **Open the serial port at the bootloader's baud rate** + + Most bootloaders use 115200 baud. Check your device's documentation. + + ```json + // open_serial_port(port="/dev/ttyUSB0", baudrate=115200) + { + "success": true, + "port": "/dev/ttyUSB0", + "baudrate": 115200 + } + ``` + +2. **Reset the device into bootloader mode** + + For an Arduino-style device, pulse DTR. For other devices, you may need to hold a specific button or send a command. + + ```json + // pulse_line(port="/dev/ttyUSB0", line="dtr", duration_ms=100, active_low=true) + ``` + +3. **Wait for the bootloader prompt** + + Read lines until you see the bootloader's ready message. + + ```json + // read_serial_lines(port="/dev/ttyUSB0", max_lines=10) + { + "success": true, + "lines": [ + "Bootloader v2.1", + "Waiting for XMODEM transfer..." + ], + "count": 2 + } + ``` + +4. **Send the firmware file** + + Match the protocol to what the bootloader expects. Many embedded bootloaders support XMODEM; more capable ones may support YMODEM or ZMODEM. + + ```json + // file_transfer_send( + // port="/dev/ttyUSB0", + // file_path="/home/user/build/firmware.bin", + // protocol="xmodem" + // ) + { + "success": true, + "protocol": "xmodem", + "file": "/home/user/build/firmware.bin", + "bytes_sent": 32768, + "blocks_sent": 256 + } + ``` + +5. **Verify the device booted with the new firmware** + + After the transfer completes, the bootloader typically flashes the firmware and reboots. Read the startup output to confirm. + + ```json + // read_serial_lines(port="/dev/ttyUSB0", max_lines=10) + { + "success": true, + "lines": [ + "Firmware v3.0.1 loaded", + "CRC OK", + "Booting..." + ], + "count": 3 + } + ``` + + + +## Protocol details + +### XMODEM + +The oldest and simplest protocol (1977). Data is sent in 128-byte blocks with a 1-byte checksum or 16-bit CRC. The receiver must acknowledge each block before the next is sent, which makes it slow on high-latency connections. + +**XMODEM-1K** is identical except it uses 1024-byte blocks, reducing overhead. + +### YMODEM + +An extension of XMODEM that adds batch capability. The first block of each file contains the filename and size as metadata. After all files are sent, a null filename block signals the end of the batch. + +### ZMODEM + +A streaming protocol that does not wait for per-block acknowledgments. It sends data continuously and only pauses if the receiver reports an error. Features include: + +- **Auto-start**: receivers detect the ZMODEM init sequence and begin automatically +- **Resume**: interrupted transfers can pick up where they left off +- **CRC-32**: stronger error detection than XMODEM/YMODEM's CRC-16 +- **Variable block size**: adapts to line quality diff --git a/docs/src/content/docs/guides/network-ports.mdx b/docs/src/content/docs/guides/network-ports.mdx new file mode 100644 index 0000000..b11da8b --- /dev/null +++ b/docs/src/content/docs/guides/network-ports.mdx @@ -0,0 +1,213 @@ +--- +title: Network Serial Ports +description: Connecting to serial devices over TCP, RFC 2217, and other network protocols +--- + +import { Tabs, TabItem, Aside } from '@astrojs/starlight/components'; + +Serial devices are not always physically attached to the machine running mcserial. Serial device servers, terminal servers, and networked test equipment expose serial ports over TCP. mcserial supports these through URL schemes passed to `open_serial_port` -- the same read, write, configure, and file transfer tools work regardless of how the port is connected. + +## Why network serial + +- **Serial device servers** (Digi, Moxa, Lantronix) bridge RS-232/RS-485 ports to your LAN +- **Remote equipment** in server rooms, factory floors, or field sites +- **Terminal servers** providing shared console access to routers, switches, and PDUs +- **Virtual serial ports** for testing and development without physical hardware + +## URL schemes + +All URL schemes are passed directly to `open_serial_port` in the `port` parameter. Once opened, the connection is used identically to a local serial port. + +### Raw TCP socket -- `socket://` + +The simplest network serial option. Bytes are forwarded as-is between the TCP socket and your tools, with no protocol framing, baud rate control, or flow control signals. + +### RFC 2217 -- `rfc2217://` + +Full serial port emulation over a Telnet connection (RFC 2217 / Telnet COM Port Control). The remote device server translates baud rate changes, flow control, and modem line signals into commands that control the physical serial port. + + + + +```json +// Connect to a Digi PortServer on port 4001 +// open_serial_port( +// port="socket://192.168.1.100:4001", +// baudrate=115200 +// ) +{ + "success": true, + "port": "socket://192.168.1.100:4001", + "mode": "rs232", + "baudrate": 115200, + "url_scheme": "socket", + "hint": "Opened via URL handler. Some features (exclusive, auto-baud) are not available." +} +``` + +**Characteristics:** +- No baud rate negotiation -- the device server must be pre-configured to match +- No flow control or modem line signals +- Lowest overhead; good for simple byte-stream forwarding +- Works with any serial-to-ethernet bridge + + + + +```json +// Connect to a device server with full serial emulation +// open_serial_port( +// port="rfc2217://192.168.1.100:2217", +// baudrate=9600 +// ) +{ + "success": true, + "port": "rfc2217://192.168.1.100:2217", + "mode": "rs232", + "baudrate": 9600, + "url_scheme": "rfc2217", + "hint": "Opened via URL handler. Some features (exclusive, auto-baud) are not available." +} +``` + +**Characteristics:** +- Baud rate, data bits, parity, and stop bits can be changed remotely via `configure_serial` +- Flow control (RTS/CTS, XON/XOFF) is supported and forwarded to the physical port +- Modem line states (DTR, RTS, CTS, DSR) can be read and set +- Higher overhead than raw TCP due to Telnet negotiation +- Requires a device server that implements RFC 2217 + + + + +After opening, all tools work the same way: + +```json +// write_serial(port="socket://192.168.1.100:4001", data="AT\r\n") +{ + "success": true, + "bytes_written": 4, + "port": "socket://192.168.1.100:4001" +} + +// read_serial_lines(port="socket://192.168.1.100:4001", max_lines=5) +{ + "success": true, + "lines": ["OK"], + "count": 1, + "port": "socket://192.168.1.100:4001" +} +``` + +## Debug wrapper -- `spy://` + + + +The `spy://` scheme wraps another serial connection and logs all traffic. It works with local ports and other URL schemes. + +```json +// Debug a local serial port +// open_serial_port(port="spy:///dev/ttyUSB0", baudrate=9600) +{ + "success": true, + "port": "spy:///dev/ttyUSB0", + "baudrate": 9600, + "url_scheme": "spy" +} + +// Debug a network connection +// open_serial_port(port="spy://socket://192.168.1.100:4001", baudrate=115200) +``` + +All reads and writes are logged to stderr in the mcserial server process. Check the server's stderr output to see the traffic. + +## HID-to-UART -- `cp2110://` + +Silicon Labs CP2110 chips present as USB HID devices rather than standard serial ports. They do not appear as `/dev/ttyUSB*` devices, so normal serial access does not work. + +```json +// open_serial_port(port="cp2110://", baudrate=9600) +{ + "success": true, + "port": "cp2110://", + "baudrate": 9600, + "url_scheme": "cp2110" +} +``` + +This requires the `hidapi` package. Install it with the optional extra: + +```bash +uv pip install mcserial[cp2110] +``` + +If `hidapi` is not installed and you try to open a `cp2110://` port, mcserial returns a clear error: + +```json +{ + "error": "cp2110:// requires the hidapi package. Install with: pip install mcserial[cp2110]", + "success": false +} +``` + +## Hardware grep -- `hwgrep://` + +`hwgrep://` opens the first serial port whose hardware information matches a pattern. This is useful when device paths change between reboots or when multiple adapters are connected. + +```json +// Find and open an FTDI device by USB VID:PID +// open_serial_port(port="hwgrep://VID:PID=0403:6001", baudrate=115200) +{ + "success": true, + "port": "hwgrep://VID:PID=0403:6001", + "baudrate": 115200, + "url_scheme": "hwgrep" +} + +// Find by description string +// open_serial_port(port="hwgrep://FTDI", baudrate=9600) + +// Find by manufacturer +// open_serial_port(port="hwgrep://Silicon Labs", baudrate=9600) +``` + +The pattern is matched against the port's device path, description, hardware ID, manufacturer, product, and serial number. The first matching port is opened. + + + +## Loopback -- `loop://` + +The `loop://` scheme creates a virtual loopback port where everything written is immediately available to read. No hardware is needed. This is useful for testing and development. + +```json +// open_serial_port(port="loop://", baudrate=9600) +// write_serial(port="loop://", data="hello") +// read_serial(port="loop://") +{ + "success": true, + "data": "hello", + "bytes_read": 5, + "port": "loop://" +} +``` + +## Limitations of URL-opened ports + +URL-opened ports differ from local device ports in a few ways: + +| Feature | Local port | URL port | +|---------|-----------|----------| +| Auto-baud detection | Yes | No (not applicable) | +| Exclusive access lock | Yes | No | +| Low-latency mode | Yes (Linux) | No | +| `set_rs485_mode` hardware ioctl | Yes | No | +| Read/write/configure | Yes | Yes | +| File transfers | Yes | Yes | + +Baud rate auto-detection is skipped for URL ports because it requires reopening the port at different speeds, which does not apply to TCP or virtual connections. For `socket://`, the baud rate parameter is informational only -- the device server must be configured separately. + +For `rfc2217://`, baud rate and serial parameters are sent to the remote device server, which applies them to the physical port. diff --git a/docs/src/content/docs/guides/rs232-basics.mdx b/docs/src/content/docs/guides/rs232-basics.mdx new file mode 100644 index 0000000..86ccab9 --- /dev/null +++ b/docs/src/content/docs/guides/rs232-basics.mdx @@ -0,0 +1,257 @@ +--- +title: RS-232 Communication +description: Working with modem control lines, break signals, and device resets +--- + +import { Steps, Aside } from '@astrojs/starlight/components'; + +RS-232 is the default mode when you open a port with mcserial. It provides point-to-point serial communication with modem control lines -- the signals that let you detect device presence, manage hardware flow control, and trigger resets. + +Every port opens in RS-232 mode automatically. No additional configuration is needed unless you want to switch to RS-485. + +## Modem control lines + +RS-232 defines six modem control lines. Four are **inputs** (read from the remote device) and two are **outputs** (set by you). + +### Input lines + +These reflect the state of the remote device. Read them with `get_modem_lines`: + +| Line | Full Name | What it means | +|------|-----------|---------------| +| CTS | Clear To Send | Remote device is ready to receive data | +| DSR | Data Set Ready | Remote device is powered and present | +| RI | Ring Indicator | Incoming call (modems) or attention signal | +| CD | Carrier Detect | Active connection established | + +```json +// get_modem_lines(port="/dev/ttyUSB0") +{ + "success": true, + "port": "/dev/ttyUSB0", + "input_lines": { + "cts": true, + "dsr": true, + "ri": false, + "cd": false + }, + "output_lines": { + "rts": true, + "dtr": true + }, + "break_condition": false +} +``` + +### Output lines + +These are signals you send to the remote device. Set them with `set_modem_lines`: + +| Line | Full Name | Common uses | +|------|-----------|-------------| +| RTS | Request To Send | Hardware flow control, TX enable for RS-485 converters | +| DTR | Data Terminal Ready | Signal our presence, trigger device reset | + +```json +// set_modem_lines(port="/dev/ttyUSB0", rts=true, dtr=true) +{ + "success": true, + "port": "/dev/ttyUSB0", + "rts": true, + "dtr": true +} +``` + +You can set one or both lines in a single call. Pass `null` (omit the parameter) to leave a line unchanged. + +## Device reset sequences + +Many development boards use DTR or RTS to trigger a hardware reset. The `pulse_line` tool handles the timing for you. + +### Arduino reset + +Arduino boards use DTR to reset the microcontroller. When DTR goes low, the reset capacitor pulls the RESET pin low briefly, rebooting the chip. + +```json +// pulse_line(port="/dev/ttyUSB0", line="dtr", duration_ms=100, active_low=true) +{ + "success": true, + "port": "/dev/ttyUSB0", + "line": "dtr", + "duration_ms": 100, + "active_low": true +} +``` + +The `active_low=true` parameter (the default) means the line pulses LOW then returns HIGH -- exactly what Arduino expects. + + + +### Practical example: connect to Arduino, reset, read boot output + + + +1. **Open the serial port** + + Open the port at 115200 baud (common for Arduino). If you are unsure of the baud rate, omit it and mcserial will attempt auto-detection. + + ```json + // open_serial_port(port="/dev/ttyACM0", baudrate=115200) + { + "success": true, + "port": "/dev/ttyACM0", + "mode": "rs232", + "baudrate": 115200, + "resource_uri": "serial:///dev/ttyACM0/data" + } + ``` + +2. **Flush any stale data in the buffer** + + Clear out anything sitting in the receive buffer from before the reset. + + ```json + // flush_serial(port="/dev/ttyACM0") + { + "success": true, + "port": "/dev/ttyACM0", + "flushed_input": true, + "flushed_output": true + } + ``` + +3. **Pulse DTR to reset the Arduino** + + A 100ms DTR pulse is enough for any Arduino board. + + ```json + // pulse_line(port="/dev/ttyACM0", line="dtr", duration_ms=100, active_low=true) + { + "success": true, + "port": "/dev/ttyACM0", + "line": "dtr", + "duration_ms": 100, + "active_low": true + } + ``` + +4. **Read the bootloader and startup output** + + After reset, the Arduino bootloader prints a brief message, then your sketch starts. Read multiple lines to capture everything. + + ```json + // read_serial_lines(port="/dev/ttyACM0", max_lines=20) + { + "success": true, + "lines": [ + "", + "Sketch starting...", + "Initializing sensors...", + "Ready." + ], + "count": 4, + "bytes_read": 52, + "port": "/dev/ttyACM0" + } + ``` + +5. **Interact with the running sketch** + + Send commands and read responses as needed. + + ```json + // write_serial(port="/dev/ttyACM0", data="STATUS\r\n") + { + "success": true, + "bytes_written": 8, + "port": "/dev/ttyACM0" + } + ``` + + + +## Break signals + +A break signal is a sustained LOW state on the TX line that lasts longer than a normal character frame. Some devices use break signals to enter configuration mode, trigger a reset, or synchronize communication. + +mcserial provides two ways to send breaks: + +### send_break -- timed pulse + +`send_break` holds the line LOW for a fixed duration, then releases it. This is the most common usage. + +```json +// send_break(port="/dev/ttyUSB0", duration_ms=250) +{ + "success": true, + "port": "/dev/ttyUSB0", + "duration_ms": 250 +} +``` + +The default duration is 250ms, which is long enough for most devices. The valid range is 1ms to 5000ms. + +### set_break_condition -- sustained hold + +`set_break_condition` holds the TX line LOW indefinitely until you explicitly release it. Use this when a protocol requires a sustained break state. + +```json +// Assert break (hold TX low) +// set_break_condition(port="/dev/ttyUSB0", enabled=true) +{ + "success": true, + "port": "/dev/ttyUSB0", + "break_condition": true +} + +// Release break (return to normal) +// set_break_condition(port="/dev/ttyUSB0", enabled=false) +{ + "success": true, + "port": "/dev/ttyUSB0", + "break_condition": false +} +``` + +The current break state is also reported in the `get_modem_lines` response under `break_condition`. + + + +## Checking line states + +You can verify the state of all modem lines at any time with `get_modem_lines`. This is useful for: + +- **Detecting device presence** -- check DSR before attempting communication +- **Debugging connections** -- verify CTS is asserted if hardware flow control is in use +- **Monitoring** -- poll RI or CD for incoming events on modem-style devices + +```json +// get_modem_lines(port="/dev/ttyUSB0") +{ + "success": true, + "port": "/dev/ttyUSB0", + "input_lines": { + "cts": true, + "dsr": false, + "ri": false, + "cd": false + }, + "output_lines": { + "rts": true, + "dtr": true + }, + "break_condition": false +} +``` + +In this example, CTS is asserted (the device can receive data) but DSR is low (the device may not be powered or connected). This is a common state for USB-serial adapters that loop CTS back internally but do not connect DSR. diff --git a/docs/src/content/docs/guides/rs485-modbus.mdx b/docs/src/content/docs/guides/rs485-modbus.mdx new file mode 100644 index 0000000..99f01f8 --- /dev/null +++ b/docs/src/content/docs/guides/rs485-modbus.mdx @@ -0,0 +1,277 @@ +--- +title: RS-485 and Modbus +description: Multi-drop bus communication, address scanning, and request-response transactions +--- + +import { Steps, Aside } from '@astrojs/starlight/components'; + +RS-485 uses a shared differential bus where multiple devices communicate over two wires. Unlike RS-232's point-to-point model, RS-485 is half-duplex -- only one device transmits at a time while all others listen. This makes it the standard for industrial protocols like Modbus RTU. + +## Switching to RS-485 mode + +Ports open in RS-232 mode by default. Switch to RS-485 mode before using any RS-485 tools. + +```json +// open_serial_port(port="/dev/ttyUSB0", baudrate=9600) +{ + "success": true, + "port": "/dev/ttyUSB0", + "mode": "rs232", + "baudrate": 9600 +} + +// set_port_mode(port="/dev/ttyUSB0", mode="rs485") +{ + "success": true, + "port": "/dev/ttyUSB0", + "previous_mode": "rs232", + "current_mode": "rs485", + "mode_tools": [ + "set_rs485_mode", + "rs485_transact", + "rs485_scan_addresses", + "check_rs485_support" + ] +} +``` + +Once in RS-485 mode, the RS-232-specific tools (`get_modem_lines`, `pulse_line`, etc.) are unavailable. Common tools like `read_serial`, `write_serial`, and `configure_serial` work in both modes. + +## Configuring RS-485 hardware + +If your USB-serial adapter or UART has hardware RS-485 support, `set_rs485_mode` configures the driver to automatically toggle the TX enable (DE/RE) line during transmission. This eliminates the need for manual RTS toggling. + +```json +// set_rs485_mode( +// port="/dev/ttyUSB0", +// enabled=true, +// rts_level_for_tx=true, +// rts_level_for_rx=false, +// delay_before_tx=0.0, +// delay_before_rx=0.0 +// ) +{ + "success": true, + "port": "/dev/ttyUSB0", + "rs485_enabled": true, + "rts_level_for_tx": true, + "rts_level_for_rx": false, + "delay_before_tx": 0.0, + "delay_before_rx": 0.0, + "loopback": false +} +``` + +**Parameters explained:** + +| Parameter | Default | Purpose | +|-----------|---------|---------| +| `rts_level_for_tx` | `true` | RTS state when transmitting (HIGH enables the driver on most RS-485 transceivers) | +| `rts_level_for_rx` | `false` | RTS state when receiving (LOW disables the driver, allows listening) | +| `delay_before_tx` | `0.0` | Seconds to wait after asserting TX enable before sending data | +| `delay_before_rx` | `0.0` | Seconds to wait after transmission before switching to receive | +| `loopback` | `false` | Echo transmitted data back (for testing) | + +## Checking hardware support + +Not all USB-serial adapters support hardware RS-485. Use `check_rs485_support` to find out what your hardware can do before configuring. + +```json +// check_rs485_support(port="/dev/ttyUSB0") +{ + "success": true, + "port": "/dev/ttyUSB0", + "driver": "ftdi_sio", + "chip": "FT232R", + "hardware_rs485": true, + "software_fallback": true, + "kernel_rs485_ioctl": true, + "notes": [ + "FTDI chips have hardware RS-485 auto-direction", + "Kernel TIOCSRS485 ioctl supported" + ], + "recommendation": "Use set_rs485_mode() for automatic DE/RE control" +} +``` + +This tool queries the kernel driver and USB device information to determine: + +- Which driver is loaded (ftdi_sio, cp210x, ch341, pl2303) +- Whether the chip supports hardware DE/RE toggling +- Whether the kernel TIOCSRS485 ioctl is available +- A recommendation for how to proceed + +### Hardware support by adapter + +| Chip | Hardware RS-485 | Notes | +|------|----------------|-------| +| FTDI (FT232R, FT2232, etc.) | Yes | Automatic direction control via driver | +| CP2105 / CP2108 | Yes | Hardware support in these models | +| CP2102 | No | Software RTS control required | +| CH340 / CH341 | No | Timing may be unreliable at high baud rates | +| PL2303 | No | Software RTS control required | +| Native UART (ttyS, ttyAMA) | Depends | Check if RS-485 transceiver is connected | + +## Half-duplex transactions + +The `rs485_transact` tool handles the complete send-then-receive cycle that RS-485 communication requires. It manages TX/RX turnaround timing automatically, whether your hardware supports it natively or needs software RTS toggling. + +```json +// rs485_transact( +// port="/dev/ttyUSB0", +// data="\x01\x03\x00\x00\x00\x01\x84\x0A", +// response_timeout=1.0, +// response_length=7 +// ) +{ + "success": true, + "port": "/dev/ttyUSB0", + "bytes_sent": 8, + "data_sent": "\u0001\u0003\u0000\u0000\u0000\u0001\u0084\n", + "response": "\u0001\u0003\u0002\u0000\u0005\u0085\u0085", + "response_bytes": 7, + "response_hex": "01030200058585", + "hardware_rs485": true +} +``` + +When hardware RS-485 is **not** configured, `rs485_transact` falls back to manual RTS control: + +1. Asserts RTS HIGH (enable driver / TX mode) +2. Sends the data and waits for transmission to complete +3. Drops RTS LOW (disable driver / RX mode) +4. Waits for the turnaround delay +5. Reads the response + +The `turnaround_delay` parameter (default 5ms) controls the pause between sending and listening. Increase it for slow devices or long cable runs. + +## Scanning for devices + +`rs485_scan_addresses` probes a range of addresses and reports which ones respond. This is the fastest way to discover what is connected to a bus. + +```json +// rs485_scan_addresses( +// port="/dev/ttyUSB0", +// start_address=1, +// end_address=30, +// probe_template="{addr:02x}03000001", +// response_timeout=0.1 +// ) +{ + "success": true, + "port": "/dev/ttyUSB0", + "addresses_scanned": 30, + "devices_found": 3, + "responding_addresses": [ + {"address": 1, "response_length": 7, "response_hex": "01030200058585"}, + {"address": 5, "response_length": 7, "response_hex": "05030200124478"}, + {"address": 16, "response_length": 7, "response_hex": "10030200009930"} + ], + "hardware_rs485": true +} +``` + +The `probe_template` uses Python's string formatting. The placeholder `{addr}` is replaced with the current address being scanned. The default template `{addr:02x}03000001` formats the address as a two-character hex string followed by a Modbus "read holding register" frame. + + + +## Practical Modbus RTU workflow + +This example walks through a complete Modbus RTU session: discovering devices, then reading a holding register. + + + +1. **Open the port and switch to RS-485 mode** + + Modbus RTU typically runs at 9600 baud with 8N1 framing. + + ```json + // open_serial_port(port="/dev/ttyUSB0", baudrate=9600) + // set_port_mode(port="/dev/ttyUSB0", mode="rs485") + ``` + +2. **Configure hardware RS-485 (if supported)** + + If your adapter supports hardware direction control, enable it. If not, `rs485_transact` handles RTS toggling in software. + + ```json + // set_rs485_mode(port="/dev/ttyUSB0", enabled=true, rts_level_for_tx=true, rts_level_for_rx=false) + ``` + +3. **Scan the bus for responding devices** + + Scan addresses 1 through 247 (the Modbus valid range). Use a short timeout per address to keep the scan fast. + + ```json + // rs485_scan_addresses( + // port="/dev/ttyUSB0", + // start_address=1, + // end_address=247, + // response_timeout=0.1 + // ) + { + "success": true, + "addresses_scanned": 247, + "devices_found": 2, + "responding_addresses": [ + {"address": 1, "response_length": 7, "response_hex": "01030200058585"}, + {"address": 10, "response_length": 7, "response_hex": "0a030200003071"} + ] + } + ``` + +4. **Read a holding register from a device** + + Construct a Modbus RTU "Read Holding Registers" frame for address 1, register 0, quantity 1. The frame format is: `[address][function 0x03][start_hi][start_lo][qty_hi][qty_lo][CRC_lo][CRC_hi]`. + + ```json + // rs485_transact( + // port="/dev/ttyUSB0", + // data="\x01\x03\x00\x00\x00\x01\x84\x0A", + // response_length=7, + // encoding="latin-1" + // ) + { + "success": true, + "bytes_sent": 8, + "response_hex": "01030200058585", + "response_bytes": 7, + "hardware_rs485": true + } + ``` + + The response `01 03 02 00 05 85 85` decodes as: address 1, function 3, 2 bytes of data, value 0x0005 (decimal 5), followed by a CRC. + +5. **Close the port when finished** + + ```json + // close_serial_port(port="/dev/ttyUSB0") + ``` + + + +### Understanding probe_template format + +The `probe_template` parameter in `rs485_scan_addresses` is a Python format string. It supports the `{addr}` placeholder with standard format specifiers: + +| Template | Address 16 becomes | Use case | +|----------|-------------------|----------| +| `{addr:02x}03000001` | `1003000001` | Modbus-style hex address prefix | +| `{addr:d}` | `16` | Decimal address prefix | +| `{addr:c}` | (ASCII char 16) | Single-byte binary address | + +If the template does **not** contain `{addr`, the raw address byte is prepended automatically. This means a template of `03000001` with address 16 sends byte 0x10 followed by `03000001`. + +## Software vs hardware RS-485 + +When `check_rs485_support` reports that your adapter lacks hardware RS-485, mcserial uses **software emulation**: + +- Before transmitting, RTS is asserted HIGH to enable the transceiver's driver +- After transmission completes, RTS is dropped LOW to switch back to receive mode +- A configurable turnaround delay prevents missed response bytes + +Software emulation works reliably at baud rates up to about 115200. At higher speeds, the timing of the RTS toggle may not be precise enough, causing the first byte of a response to be corrupted or missed. If you need high-speed RS-485, use an adapter with hardware support (FTDI-based adapters are widely available and well-supported). diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx new file mode 100644 index 0000000..8b362aa --- /dev/null +++ b/docs/src/content/docs/index.mdx @@ -0,0 +1,80 @@ +--- +title: mcserial +description: MCP server for serial port communication -- RS-232, RS-485, and file transfers via Model Context Protocol. +template: splash +hero: + tagline: Serial ports meet the Model Context Protocol. Discover, configure, read, write, and transfer files -- RS-232, RS-485, and 7 URL schemes, all callable as MCP tools. + image: + file: ../../assets/logo.svg + actions: + - text: Get Started + link: /tutorials/getting-started/ + icon: right-arrow + variant: primary + - text: Tool Reference + link: /reference/tools-common/ + variant: minimal +--- + +import { Card, CardGrid, Aside } from '@astrojs/starlight/components'; + +## What mcserial does + + + + Full RS-232 modem line control -- RTS, DTR, CTS, DSR, break signals, device reset pulses. Switch to RS-485 mode for half-duplex bus communication with automatic TX/RX direction, device scanning, and Modbus transactions. + + + Send and receive files over serial using XMODEM (128B blocks), XMODEM-1K, YMODEM (batch mode), or ZMODEM (streaming with auto-resume). Batch transfers supported for YMODEM and ZMODEM. + + + Connect to serial-over-ethernet bridges via `socket://`, configure remote ports with `rfc2217://`, test without hardware on `loop://`, or debug traffic with `spy://`. Seven URL schemes total. + + + Omit the baud rate when opening a port and mcserial will detect it automatically by analyzing data patterns, sync bytes, and byte distributions. Returns a confidence score and ranked candidates. + + + +## Quick start + +```bash +# Add to Claude Code +claude mcp add mcserial -- uvx mcserial +``` + +Then use the tools in a natural sequence -- discover, open, read/write, close: + +``` +list_serial_ports() # find available ports +open_serial_port(port="loop://", baudrate=9600) # open (loop:// = no hardware needed) +write_serial(port="loop://", data="hello\n") # send data +read_serial(port="loop://") # read response +close_serial_port(port="loop://") # release the port +``` + +See the [Getting Started tutorial](/tutorials/getting-started/) for the full walkthrough with example responses. + +## Supported URL schemes + +In addition to local device paths (`/dev/ttyUSB0`, `COM3`), `open_serial_port` accepts these URL schemes: + +| Scheme | Description | Example | +|--------|-------------|---------| +| `loop://` | In-memory loopback -- writes echo back as reads | `loop://` | +| `socket://` | Raw TCP socket for serial-to-ethernet bridges | `socket://192.168.1.100:4001` | +| `rfc2217://` | Telnet COM Port Control with remote baud/flow config | `rfc2217://192.168.1.100:2217` | +| `spy://` | Debug wrapper that logs all traffic to stderr | `spy:///dev/ttyUSB0` | +| `hwgrep://` | Open first port matching a hardware pattern | `hwgrep://FTDI` | +| `cp2110://` | Silicon Labs HID-to-UART (requires `[cp2110]` extra) | `cp2110://` | +| `alt://` | Alternate port backend | `alt:///dev/ttyUSB0` | + +## 30 tools across 4 categories + +mcserial is a [FastMCP](https://gofastmcp.com) server wrapping [pyserial](https://pyserial.readthedocs.io/) into organized tool groups: + +- **[Common tools](/reference/tools-common/)** (18) -- port discovery, open/close, read/write, configuration, baud detection +- **[RS-232 tools](/reference/tools-rs232/)** (5) -- modem line control, break signals, reset pulses +- **[RS-485 tools](/reference/tools-rs485/)** (4) -- bus configuration, transactions, address scanning +- **[File transfer tools](/reference/tools-file-transfer/)** (3) -- X/Y/ZMODEM send, receive, batch send + +Ports open in RS-232 mode by default. Use `set_port_mode()` to switch to RS-485 when working with multi-drop buses. Common tools work in both modes. diff --git a/docs/src/content/docs/reference/environment.mdx b/docs/src/content/docs/reference/environment.mdx new file mode 100644 index 0000000..a3947cd --- /dev/null +++ b/docs/src/content/docs/reference/environment.mdx @@ -0,0 +1,110 @@ +--- +title: Environment Variables +description: Configuration via environment variables +sidebar: + order: 7 +--- + +import { Aside } from '@astrojs/starlight/components'; + +mcserial reads configuration from environment variables at startup. These variables set server-wide defaults that apply to all connections unless overridden by tool parameters. + +--- + +## Server Configuration + +### MCSERIAL_DEFAULT_BAUDRATE + +Default baud rate used when `open_serial_port` is called without a `baudrate` parameter and auto-detection either fails or is not applicable (e.g., URL-based connections). + +| | | +|---|---| +| **Default** | `9600` | +| **Type** | Integer | +| **Example** | `MCSERIAL_DEFAULT_BAUDRATE=115200` | + +```bash +# Set a higher default for modern devices +export MCSERIAL_DEFAULT_BAUDRATE=115200 +``` + +### MCSERIAL_DEFAULT_TIMEOUT + +Default read timeout in seconds for new connections. Applied as the `timeout` parameter when `open_serial_port` is called without an explicit timeout. + +| | | +|---|---| +| **Default** | `1.0` | +| **Type** | Float (seconds) | +| **Example** | `MCSERIAL_DEFAULT_TIMEOUT=2.0` | + +```bash +# Longer timeout for slow devices +export MCSERIAL_DEFAULT_TIMEOUT=5.0 +``` + +### MCSERIAL_MAX_CONNECTIONS + +Maximum number of simultaneously open serial port connections. Attempts to open more ports than this limit return an error. + +| | | +|---|---| +| **Default** | `10` | +| **Type** | Integer | +| **Example** | `MCSERIAL_MAX_CONNECTIONS=20` | + +```bash +# Allow more concurrent connections +export MCSERIAL_MAX_CONNECTIONS=20 +``` + + + +--- + +## Setting Environment Variables + + + +For other MCP clients, consult their documentation for how to pass environment variables to server processes. + +--- + +## Installation Extras + +mcserial supports optional dependency groups for specialized hardware. + +### mcserial[cp2110] + +Adds the `hidapi` package for Silicon Labs CP2110 HID-to-UART bridge support. Required to use the `cp2110://` URL scheme with `open_serial_port`. + +```bash +# Install with CP2110 support +uv pip install mcserial[cp2110] + +# Or with uvx +uvx --with hidapi mcserial +``` + +Without this extra installed, attempting to open a `cp2110://` URL returns an error: + +``` +cp2110:// requires the hidapi package. Install with: pip install mcserial[cp2110] +``` + + diff --git a/docs/src/content/docs/reference/resources.mdx b/docs/src/content/docs/reference/resources.mdx new file mode 100644 index 0000000..eb37de2 --- /dev/null +++ b/docs/src/content/docs/reference/resources.mdx @@ -0,0 +1,143 @@ +--- +title: MCP Resources +description: Read-only data endpoints exposed as MCP resources +sidebar: + order: 6 +--- + +import { Aside } from '@astrojs/starlight/components'; + +MCP resources are read-only data endpoints that clients can access without calling tools. They provide a way to passively observe port state and data, separate from the action-oriented tool interface. + + + +--- + +## serial://ports + +List all available serial ports on the system. Returns a Markdown-formatted list with device paths, descriptions, and open/closed status. + +**URI:** `serial://ports` + +**Example output:** +```markdown +# Available Serial Ports + +- /dev/ttyUSB0 [OPEN]: USB-Serial Controller D +- /dev/ttyUSB1 [closed]: FT232R USB UART +- /dev/ttyACM0 [closed]: Arduino Mega 2560 +``` + +This resource calls `list_serial_ports()` internally with default parameters (`usb_only=True`). For filtered results, use the `list_serial_ports` tool directly with the `grep` parameter. + +--- + +## `serial://{port}/data` + +Read available data from an open serial port. Returns the data decoded as UTF-8 with a byte count prefix. + +**URI pattern:** `serial://{port}/data` + +**Example URIs:** +``` +serial:///dev/ttyUSB0/data +serial://COM3/data +serial://loop:///data +``` + +**Example output:** +``` +[42 bytes from /dev/ttyUSB0] +AT+GMR +OK +ESP8266 firmware v2.1 +``` + +If no data is available in the port's input buffer, returns: +``` +[No data available on /dev/ttyUSB0] +``` + +If the port is not open, returns an error message prompting you to use `open_serial_port` first. + + + +--- + +## `serial://{port}/status` + +Get the current configuration and connection status for an open serial port. Returns a Markdown-formatted status report. + +**URI pattern:** `serial://{port}/status` + +**Example URIs:** +``` +serial:///dev/ttyUSB0/status +serial://COM3/status +``` + +**Example output:** +```markdown +# Serial Port Status: /dev/ttyUSB0 +- Mode: RS232 +- Open: True +- Baudrate: 115200 +- Bytesize: 8 +- Parity: N +- Stopbits: 1 +- Timeout: 1.0s +- Bytes waiting (in): 0 +- Bytes waiting (out): 0 +- CTS: True +- DSR: True +- RI: False +- CD: False +- RTS: True +- DTR: True +``` + +This resource provides a snapshot of all port settings, buffer counts, and modem line states in a single read. Useful for diagnostics without calling multiple tools. + +--- + +## `serial://{port}/raw` + +Read available data from an open serial port as a hex dump. Same as `serial://{port}/data` but returns raw bytes in hexadecimal format instead of decoded text. + +**URI pattern:** `serial://{port}/raw` + +**Example URIs:** +``` +serial:///dev/ttyUSB0/raw +serial://COM3/raw +``` + +**Example output:** +``` +[8 bytes from /dev/ttyUSB0] +01 03 04 00 64 00 c8 fa +``` + +Use this resource when working with binary protocols (Modbus, proprietary framing) where hex representation is more useful than decoded text. + + + +--- + +## URI Encoding + +The `{port}` segment in resource URIs uses the device path directly. For paths containing special characters (like forward slashes in Linux device paths), the MCP client handles URL encoding: + +| Device Path | Resource URI | +|-------------|-------------| +| `/dev/ttyUSB0` | `serial:///dev/ttyUSB0/data` | +| `COM3` | `serial://COM3/data` | +| `loop://` | `serial://loop:///data` | + +The server URL-decodes the port parameter internally, so both encoded and unencoded paths work correctly. diff --git a/docs/src/content/docs/reference/tools-common.mdx b/docs/src/content/docs/reference/tools-common.mdx new file mode 100644 index 0000000..51802f8 --- /dev/null +++ b/docs/src/content/docs/reference/tools-common.mdx @@ -0,0 +1,455 @@ +--- +title: Common Tools +description: Core serial port tools available in all modes +sidebar: + order: 1 +--- + +import { Aside } from '@astrojs/starlight/components'; + +These 18 tools work in both RS-232 and RS-485 modes. They cover port discovery, connection management, reading and writing data, configuration, flow control, and diagnostics. + +--- + +## Port Discovery + +### list_serial_ports + +List available serial ports on the system. Call this first to discover what ports are available before opening one. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `usb_only` | `bool` | `True` | Only show USB serial devices. Set `False` to include legacy/phantom ttyS ports. | +| `grep` | `str \| None` | `None` | Regex pattern to filter ports. Matches against device path, description, hardware ID, manufacturer, product, and serial number. | + +**Returns:** List of port objects with `device`, `description`, `hwid`, `manufacturer`, `product`, `serial_number`, and `is_open` fields. Sorted with USB ports (ttyUSB, ttyACM) first. + +```python +# List all USB serial devices +list_serial_ports() + +# Include legacy ttyS ports +list_serial_ports(usb_only=False) + +# Find FTDI adapters +list_serial_ports(grep="FTDI") + +# Match specific USB VID:PID +list_serial_ports(grep="VID:PID=0403:6001") +``` + +--- + +## Connection Management + +### open_serial_port + +Open a serial port connection with optional auto-baud detection. If `baudrate` is not specified, the server automatically detects the baud rate by analyzing incoming data patterns. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path (`/dev/ttyUSB0`, `COM3`) or URL scheme (`socket://`, `rfc2217://`, `loop://`, `spy://`, `cp2110://`). See [URL Schemes](/reference/url-handlers/) for details. | +| `baudrate` | `int \| None` | `None` | Baud rate. If `None`, auto-detect is attempted (recommended for unknown devices). Falls back to `MCSERIAL_DEFAULT_BAUDRATE` if detection fails. | +| `bytesize` | `Literal[5, 6, 7, 8]` | `8` | Number of data bits. | +| `parity` | `Literal["N", "E", "O", "M", "S"]` | `"N"` | Parity checking: None, Even, Odd, Mark, or Space. | +| `stopbits` | `Literal[1, 1.5, 2]` | `1` | Number of stop bits. | +| `timeout` | `float` | `1.0` | Read timeout in seconds. Default comes from `MCSERIAL_DEFAULT_TIMEOUT`. | +| `write_timeout` | `float \| None` | `None` | Write timeout in seconds. `None` means blocking writes. | +| `inter_byte_timeout` | `float \| None` | `None` | Timeout between bytes during read. `None` disables inter-byte timeout. | +| `xonxoff` | `bool` | `False` | Enable software flow control (XON/XOFF). | +| `rtscts` | `bool` | `False` | Enable hardware RTS/CTS flow control. | +| `dsrdtr` | `bool` | `False` | Enable hardware DSR/DTR flow control. | +| `exclusive` | `bool` | `False` | Request exclusive access (lock port from other processes). | +| `autobaud_probe` | `str \| None` | `None` | String to send during auto-detection (e.g., `"UUUUU"` for sync). | +| `autobaud_timeout` | `float` | `0.3` | Timeout per rate during auto-detection in seconds. | + +**Returns:** Connection status dict with `success`, `port`, `mode`, `baudrate`, `bytesize`, `parity`, `stopbits`, flow control settings, and `resource_uri`. When auto-baud is used, includes an `autobaud` object with detection details. + + + +```python +# Auto-detect baud rate +open_serial_port(port="/dev/ttyUSB0") + +# Explicit baud rate with 8N1 (most common settings) +open_serial_port(port="/dev/ttyUSB0", baudrate=115200) + +# RS-232 with hardware flow control +open_serial_port(port="/dev/ttyUSB0", baudrate=9600, rtscts=True) + +# Exclusive access prevents other processes from using the port +open_serial_port(port="/dev/ttyUSB0", baudrate=9600, exclusive=True) + +# Auto-detect with sync probe +open_serial_port(port="/dev/ttyUSB0", autobaud_probe="UUUUU") + +# Open a network serial port +open_serial_port(port="socket://192.168.1.100:4001", baudrate=115200) + +# Loopback for testing (no hardware needed) +open_serial_port(port="loop://", baudrate=9600) +``` + + + +### close_serial_port + +Close an open serial port connection and release it for other processes. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port to close. | + +**Returns:** Status dict with `success`, `port`, and `message` fields. + +```python +close_serial_port(port="/dev/ttyUSB0") +``` + +### set_port_mode + +Switch a serial port between RS-232 and RS-485 modes. Mode determines which mode-specific tools are available. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port to configure. | +| `mode` | `Literal["rs232", "rs485"]` | required | Target mode. | + +**Returns:** Status dict with `success`, `previous_mode`, `current_mode`, and `mode_tools` (list of tools available in the new mode). + +```python +# Switch to RS-485 mode for Modbus communication +set_port_mode(port="/dev/ttyUSB0", mode="rs485") + +# Switch back to RS-232 +set_port_mode(port="/dev/ttyUSB0", mode="rs232") +``` + + + +### get_connection_status + +Get status of all open serial connections. Takes no parameters. + +**Returns:** Dict with `connections` (map of port to status details) and `count`. Each connection includes `is_open`, `mode`, `baudrate`, `bytesize`, `parity`, `stopbits`, `timeout`, `write_timeout`, `inter_byte_timeout`, flow control flags, buffer counts (`in_waiting`, `out_waiting`), modem line states (`cts`, `dsr`, `ri`, `cd`, `rts`, `dtr`), and `resource_uri`. + +```python +get_connection_status() +``` + +--- + +## Writing Data + +### write_serial + +Write string data to an open serial port. Data is encoded using the specified encoding before sending. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port to write to. | +| `data` | `str` | required | String data to send. | +| `encoding` | `str` | `"utf-8"` | Character encoding for the data. | + +**Returns:** Dict with `success`, `bytes_written`, and `port`. + +```python +# Send an AT command +write_serial(port="/dev/ttyUSB0", data="AT\r\n") + +# Send with specific encoding +write_serial(port="/dev/ttyUSB0", data="Hello", encoding="ascii") +``` + +### write_serial_bytes + +Write raw bytes to an open serial port. Use this when you need to send binary data or specific byte sequences. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port to write to. | +| `data` | `list[int]` | required | List of byte values (0-255). Values outside this range return an error. | + +**Returns:** Dict with `success`, `bytes_written`, and `port`. + +```python +# Send AT\r\n as raw bytes +write_serial_bytes(port="/dev/ttyUSB0", data=[65, 84, 13, 10]) + +# Send a Modbus frame +write_serial_bytes(port="/dev/ttyUSB0", data=[0x01, 0x03, 0x00, 0x00, 0x00, 0x01, 0x84, 0x0A]) +``` + + + +--- + +## Reading Data + +### read_serial + +Read data from an open serial port. Returns both decoded text and raw hex representation. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port to read from. | +| `size` | `int \| None` | `None` | Maximum bytes to read. `None` reads all available data. | +| `encoding` | `str` | `"utf-8"` | Character encoding for decoding. | +| `timeout` | `float \| None` | `None` | Override the port's read timeout for this call. `None` uses the port default. | + +**Returns:** Dict with `success`, `data` (decoded string), `bytes_read`, `raw_hex`, and `port`. Decoding errors are replaced rather than raising exceptions. + +```python +# Read all available data +read_serial(port="/dev/ttyUSB0") + +# Read exactly 10 bytes +read_serial(port="/dev/ttyUSB0", size=10) + +# Read with a longer timeout +read_serial(port="/dev/ttyUSB0", timeout=5.0) +``` + +### read_serial_line + +Read a single line (until newline character) from an open serial port. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port to read from. | +| `encoding` | `str` | `"utf-8"` | Character encoding for decoding. | + +**Returns:** Dict with `success`, `line` (decoded string with trailing CR/LF stripped), `bytes_read`, and `port`. + +```python +read_serial_line(port="/dev/ttyUSB0") +``` + +### read_serial_lines + +Read multiple lines from an open serial port. Reads up to `max_lines`, stopping early if no more data is available (readline returns empty due to timeout). + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port to read from. | +| `max_lines` | `int` | `10` | Maximum number of lines to read. Must be 1-1000. | +| `encoding` | `str` | `"utf-8"` | Character encoding for decoding. | + +**Returns:** Dict with `success`, `lines` (list of decoded strings), `count`, `bytes_read`, and `port`. + +```python +# Read up to 10 lines (default) +read_serial_lines(port="/dev/ttyUSB0") + +# Read up to 50 lines of buffered output +read_serial_lines(port="/dev/ttyUSB0", max_lines=50) +``` + +### read_until + +Read data until a specific terminator sequence is received. More flexible than `read_serial_line` because it supports any terminator string, not just newline. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port to read from. | +| `terminator` | `str` | `"\n"` | Byte sequence to stop at. | +| `size` | `int \| None` | `None` | Maximum bytes to read. `None` means no limit (uses timeout). | +| `encoding` | `str` | `"utf-8"` | Character encoding for the terminator and result. | + +**Returns:** Dict with `success`, `data` (decoded string), `bytes_read`, `raw_hex`, `port`, and `terminator_found` (bool indicating whether the terminator was actually found or the read timed out). + +```python +# Read until "OK\r\n" +read_until(port="/dev/ttyUSB0", terminator="OK\r\n") + +# Read until a prompt character +read_until(port="/dev/ttyUSB0", terminator=">") + +# Read until terminator with a size limit +read_until(port="/dev/ttyUSB0", terminator="\r\n", size=256) +``` + +--- + +## Configuration + +### configure_serial + +Modify settings on an already-open serial port. Only the parameters you provide are changed; everything else stays the same. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port to configure. | +| `baudrate` | `int \| None` | `None` | New baud rate. `None` = no change. | +| `timeout` | `float \| None` | `None` | New read timeout in seconds. `None` = no change. | +| `write_timeout` | `float \| None` | `None` | New write timeout in seconds. `None` = no change. | +| `inter_byte_timeout` | `float \| None` | `None` | Timeout between bytes. `None` = no change. | +| `xonxoff` | `bool \| None` | `None` | Software flow control XON/XOFF. `None` = no change. | +| `rtscts` | `bool \| None` | `None` | Hardware RTS/CTS flow control. `None` = no change. | +| `dsrdtr` | `bool \| None` | `None` | Hardware DSR/DTR flow control. `None` = no change. | +| `rts` | `bool \| None` | `None` | Set RTS line state. `None` = no change. | +| `dtr` | `bool \| None` | `None` | Set DTR line state. `None` = no change. | + +**Returns:** Dict with `success`, `port`, and all current settings (`baudrate`, `timeout`, `write_timeout`, `inter_byte_timeout`, `xonxoff`, `rtscts`, `dsrdtr`, `rts`, `dtr`). + +```python +# Change baud rate on the fly +configure_serial(port="/dev/ttyUSB0", baudrate=115200) + +# Increase read timeout +configure_serial(port="/dev/ttyUSB0", timeout=5.0) + +# Enable hardware flow control +configure_serial(port="/dev/ttyUSB0", rtscts=True) + +# Set DTR low (useful for reset sequences) +configure_serial(port="/dev/ttyUSB0", dtr=False) +``` + +### flush_serial + +Clear serial port input and/or output buffers. Discards any pending data. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port to flush. | +| `input_buffer` | `bool` | `True` | Clear the input/receive buffer. | +| `output_buffer` | `bool` | `True` | Clear the output/transmit buffer. | + +**Returns:** Dict with `success`, `port`, `flushed_input`, and `flushed_output`. + +```python +# Flush both buffers (default) +flush_serial(port="/dev/ttyUSB0") + +# Flush only the input buffer +flush_serial(port="/dev/ttyUSB0", input_buffer=True, output_buffer=False) +``` + +--- + +## Flow Control + +### set_flow_control + +Manually gate input/output flow control signals on a serial port. Flow control must already be enabled via `configure_serial` (set `xonxoff=True` or `rtscts=True`) for these signals to have effect. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port. | +| `input_flow` | `bool \| None` | `None` | `True` sends XON (allow remote to send), `False` sends XOFF (tell remote to stop). `None` = no change. | +| `output_flow` | `bool \| None` | `None` | `True` resumes outgoing data, `False` pauses it. `None` = no change. | + +**Returns:** Dict with `success`, `port`, `changes` (what was set), and `flow_control_enabled` (current `xonxoff` and `rtscts` state). + + + +```python +# Pause incoming data (send XOFF) +set_flow_control(port="/dev/ttyUSB0", input_flow=False) + +# Resume incoming data (send XON) +set_flow_control(port="/dev/ttyUSB0", input_flow=True) +``` + +### cancel_read + +Cancel any pending read operation on a serial port. Interrupts a blocking read by calling `cancel_read()` on the underlying pyserial connection. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port. | + +**Returns:** Dict with `success`, `port`, and `cancelled`. + + + +```python +cancel_read(port="/dev/ttyUSB0") +``` + +### cancel_write + +Cancel any pending write operation on a serial port. Interrupts a blocking write by calling `cancel_write()` on the underlying pyserial connection. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port. | + +**Returns:** Dict with `success`, `port`, and `cancelled`. + + + +```python +cancel_write(port="/dev/ttyUSB0") +``` + +--- + +## Diagnostics + +### set_low_latency_mode + +Enable or disable low-latency mode on a serial port. Reduces latency by changing how the kernel buffers data. Linux only. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port. | +| `enabled` | `bool` | `True` | Enable or disable low latency mode. | + +**Returns:** Dict with `success`, `port`, and `low_latency`. + + + +```python +# Enable low latency for time-critical communication +set_low_latency_mode(port="/dev/ttyUSB0", enabled=True) +``` + +### detect_baud_rate + +Auto-detect baud rate using multiple heuristics: 0x55 sync pattern analysis, byte distribution analysis, ASCII readability scoring, and framing indicators. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path. Opened temporarily if not already open. If open, the baud rate is changed during testing and restored afterward. | +| `probe` | `str \| None` | `None` | String to send to trigger a response. Use `"U"` or `"UUUUU"` for sync-based detection on echo-enabled devices. | +| `timeout_per_rate` | `float` | `0.5` | Seconds to wait for data at each baud rate. | +| `baudrates` | `list[int] \| None` | `None` | Custom list of rates to try. Default tries common rates: 115200, 9600, 57600, 38400, 19200, 230400, 460800, 921600, 4800, 2400, 1200, 300, 500000, 576000, 1000000, 1500000. | +| `use_sync_pattern` | `bool` | `True` | Analyze 0x55 sync patterns for improved detection accuracy. | + +**Returns:** Dict with `success`, `port`, `detected_baudrate` (or `None` if confidence is below 50), `confidence` (0-100 score), `results` (top 5 candidates with detailed scoring), and `rates_tested`. + + + +```python +# Detect baud rate on an active device +detect_baud_rate(port="/dev/ttyUSB0") + +# Use a sync probe for echo devices +detect_baud_rate(port="/dev/ttyUSB0", probe="UUUUU") + +# Test only common embedded rates +detect_baud_rate(port="/dev/ttyUSB0", baudrates=[9600, 115200, 57600]) + +# Longer wait time for slow devices +detect_baud_rate(port="/dev/ttyUSB0", timeout_per_rate=1.0) +``` diff --git a/docs/src/content/docs/reference/tools-file-transfer.mdx b/docs/src/content/docs/reference/tools-file-transfer.mdx new file mode 100644 index 0000000..227c2d6 --- /dev/null +++ b/docs/src/content/docs/reference/tools-file-transfer.mdx @@ -0,0 +1,174 @@ +--- +title: File Transfer Tools +description: Send and receive files using X/Y/ZMODEM protocols +sidebar: + order: 4 +--- + +import { Aside } from '@astrojs/starlight/components'; + +Transfer files over serial connections using classic X/Y/ZMODEM protocols. These tools work in both RS-232 and RS-485 modes. + +## Protocol Comparison + +| Protocol | Block Size | Batch | Resume | Error Correction | Recommended | +|----------|-----------|-------|--------|------------------|-------------| +| XMODEM | 128B | No | No | Checksum/CRC | Legacy only | +| XMODEM-1K| 1024B | No | No | CRC-16 | - | +| YMODEM | 1024B | Yes | No | CRC-16 | Batch needs | +| ZMODEM | Streaming | Yes | Yes | CRC-32 | Yes | + + + +--- + +## file_transfer_send + +Send a single file over serial using a selected protocol. The receiver must be waiting in receive mode before calling this tool. ZMODEM receivers typically auto-start when they detect the init sequence. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the open serial port. | +| `file_path` | `str` | required | Path to the file to send. | +| `protocol` | `Literal["xmodem", "xmodem1k", "ymodem", "zmodem"]` | `"zmodem"` | Transfer protocol to use. | + +**Returns:** Transfer statistics dict with protocol-specific details including bytes sent and any errors. The dict also includes `protocol` and `file` fields. + +```python +# Send a firmware file using ZMODEM (default) +file_transfer_send(port="/dev/ttyUSB0", file_path="/home/user/firmware.bin") + +# Send using XMODEM for legacy compatibility +file_transfer_send( + port="/dev/ttyUSB0", + file_path="/home/user/config.txt", + protocol="xmodem", +) + +# XMODEM-1K for faster transfers on legacy systems +file_transfer_send( + port="/dev/ttyUSB0", + file_path="/home/user/data.bin", + protocol="xmodem1k", +) + +# YMODEM preserves filename and size metadata +file_transfer_send( + port="/dev/ttyUSB0", + file_path="/home/user/update.bin", + protocol="ymodem", +) +``` + + + +--- + +## file_transfer_receive + +Receive a file over serial using a selected protocol. The behavior of `save_path` depends on the protocol. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the open serial port. | +| `save_path` | `str` | required | For XMODEM: full file path. For YMODEM/ZMODEM: directory where received files are saved. | +| `protocol` | `Literal["xmodem", "ymodem", "zmodem"]` | `"zmodem"` | Transfer protocol to use. | +| `overwrite` | `bool` | `False` | Whether to overwrite existing files. | + +**Returns:** Transfer statistics dict with protocol-specific details including bytes received and file paths. Includes the `protocol` field. + + + +```python +# Receive via ZMODEM into a directory +file_transfer_receive( + port="/dev/ttyUSB0", + save_path="/home/user/downloads/", +) + +# Receive a single file via XMODEM +file_transfer_receive( + port="/dev/ttyUSB0", + save_path="/home/user/received_file.bin", + protocol="xmodem", +) + +# Receive via YMODEM, allowing overwrite +file_transfer_receive( + port="/dev/ttyUSB0", + save_path="/home/user/downloads/", + protocol="ymodem", + overwrite=True, +) +``` + + + +--- + +## file_transfer_send_batch + +Send multiple files in a single batch transfer. Only YMODEM and ZMODEM support batch mode. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the open serial port. | +| `file_paths` | `list[str]` | required | List of file paths to send. | +| `protocol` | `Literal["ymodem", "zmodem"]` | `"zmodem"` | Transfer protocol. Must be `ymodem` or `zmodem`. | + +**Returns:** Transfer statistics dict covering all files, including the `protocol` field. + + + +```python +# Batch send with ZMODEM (default) +file_transfer_send_batch( + port="/dev/ttyUSB0", + file_paths=[ + "/home/user/config.json", + "/home/user/firmware.bin", + "/home/user/README.txt", + ], +) + +# Batch send with YMODEM +file_transfer_send_batch( + port="/dev/ttyUSB0", + file_paths=["/home/user/file1.txt", "/home/user/file2.txt"], + protocol="ymodem", +) +``` + +--- + +## Typical Workflow + +A complete file transfer session looks like this: + +```python +# 1. Open the port at a suitable baud rate +open_serial_port(port="/dev/ttyUSB0", baudrate=115200) + +# 2. Send a file +file_transfer_send(port="/dev/ttyUSB0", file_path="/home/user/firmware.bin") + +# 3. Or receive a file +file_transfer_receive(port="/dev/ttyUSB0", save_path="/home/user/downloads/") + +# 4. Close when done +close_serial_port(port="/dev/ttyUSB0") +``` + + diff --git a/docs/src/content/docs/reference/tools-rs232.mdx b/docs/src/content/docs/reference/tools-rs232.mdx new file mode 100644 index 0000000..8b44fd3 --- /dev/null +++ b/docs/src/content/docs/reference/tools-rs232.mdx @@ -0,0 +1,170 @@ +--- +title: RS-232 Tools +description: Modem control lines, break signals, and RS-232 specific operations +sidebar: + order: 2 +--- + +import { Aside } from '@astrojs/starlight/components'; + +RS-232 is the default mode for all newly opened ports. These five tools provide control over modem signal lines and break conditions -- the hardware handshaking and signaling layer of point-to-point serial communication. + + + + + +--- + +## get_modem_lines + +Read all RS-232 modem control and status line states, including the current break condition. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port to query. | + +**Returns:** Dict with `success`, `port`, `input_lines` (object with `cts`, `dsr`, `ri`, `cd`), `output_lines` (object with `rts`, `dtr`), and `break_condition` (bool). + +```python +get_modem_lines(port="/dev/ttyUSB0") + +# Example response: +# { +# "success": true, +# "port": "/dev/ttyUSB0", +# "input_lines": {"cts": true, "dsr": true, "ri": false, "cd": false}, +# "output_lines": {"rts": true, "dtr": true}, +# "break_condition": false +# } +``` + +--- + +## set_modem_lines + +Set the RS-232 output control lines (RTS and DTR). Only the lines you specify are changed; pass `None` (or omit the parameter) to leave a line unchanged. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port. | +| `rts` | `bool \| None` | `None` | Set RTS (Request To Send) state. `None` = no change. | +| `dtr` | `bool \| None` | `None` | Set DTR (Data Terminal Ready) state. `None` = no change. | + +**Returns:** Dict with `success`, `port`, `rts`, and `dtr` (current states after change). + +These lines are commonly used for: +- Hardware flow control +- Device reset sequences (many boards use DTR for reset) +- Power control on some devices +- Custom signaling protocols + +```python +# Assert DTR to signal "terminal ready" +set_modem_lines(port="/dev/ttyUSB0", dtr=True) + +# Drop RTS to signal "stop sending" +set_modem_lines(port="/dev/ttyUSB0", rts=False) + +# Set both lines at once +set_modem_lines(port="/dev/ttyUSB0", rts=True, dtr=True) +``` + +--- + +## pulse_line + +Pulse an RS-232 control line high-then-low or low-then-high. Commonly used for device reset sequences. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port. | +| `line` | `Literal["rts", "dtr"]` | required | Which line to pulse. | +| `duration_ms` | `int` | `100` | Pulse duration in milliseconds. Must be 1-5000. | +| `active_low` | `bool` | `True` | If `True`, pulse LOW then HIGH. If `False`, pulse HIGH then LOW. | + +**Returns:** Dict with `success`, `port`, `line`, `duration_ms`, and `active_low`. + +The line is set to its initial state, held for `duration_ms`, pulsed to the active state for `duration_ms`, then restored to its original value. + +Typical reset sequences: +- **Arduino**: DTR pulse triggers auto-reset +- **ESP32/ESP8266**: DTR + RTS sequence enters bootloader +- **Custom hardware**: Various reset/trigger signals + +```python +# Arduino-style reset (DTR pulse, active low) +pulse_line(port="/dev/ttyUSB0", line="dtr", duration_ms=100) + +# Active-high pulse on RTS +pulse_line(port="/dev/ttyUSB0", line="rts", duration_ms=200, active_low=False) + +# Short trigger pulse +pulse_line(port="/dev/ttyUSB0", line="dtr", duration_ms=10) +``` + +--- + +## send_break + +Send a timed serial break signal -- a sustained low state on the TX line longer than a character frame. Used to get the attention of a remote device or trigger special modes. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port. | +| `duration_ms` | `int` | `250` | Break duration in milliseconds. Must be 1-5000. | + +**Returns:** Dict with `success`, `port`, and `duration_ms`. + +```python +# Standard break signal +send_break(port="/dev/ttyUSB0") + +# Short break (100ms) +send_break(port="/dev/ttyUSB0", duration_ms=100) + +# Long break to force attention +send_break(port="/dev/ttyUSB0", duration_ms=1000) +``` + +--- + +## set_break_condition + +Set or clear the break condition on a serial port. Unlike `send_break()` which sends a timed pulse, this holds the break condition indefinitely until explicitly cleared. Useful for protocols that require sustained break states. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port. | +| `enabled` | `bool` | required | `True` to assert break (hold TX low), `False` to release. | + +**Returns:** Dict with `success`, `port`, and `break_condition`. + + + +```python +# Assert break condition +set_break_condition(port="/dev/ttyUSB0", enabled=True) + +# ... wait for device to respond ... + +# Release break +set_break_condition(port="/dev/ttyUSB0", enabled=False) +``` diff --git a/docs/src/content/docs/reference/tools-rs485.mdx b/docs/src/content/docs/reference/tools-rs485.mdx new file mode 100644 index 0000000..6c0671d --- /dev/null +++ b/docs/src/content/docs/reference/tools-rs485.mdx @@ -0,0 +1,218 @@ +--- +title: RS-485 Tools +description: Half-duplex bus communication, transactions, and address scanning +sidebar: + order: 3 +--- + +import { Aside } from '@astrojs/starlight/components'; + +RS-485 enables half-duplex multi-drop bus communication where multiple devices share a single pair of wires. These tools handle direction control, request/response transactions, and bus scanning. + + + +--- + +## set_rs485_mode + +Configure the hardware RS-485 settings for half-duplex communication. This sets up automatic TX/RX direction switching via the RTS line (DE/RE control) on hardware that supports it. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path of the port. | +| `enabled` | `bool` | `True` | Enable or disable RS-485 hardware mode. | +| `delay_before_tx` | `float` | `0.0` | Delay in seconds before enabling TX. Allows bus settling time. | +| `delay_before_rx` | `float` | `0.0` | Delay in seconds before enabling RX after TX completes. | +| `rts_level_for_tx` | `bool` | `True` | RTS level when transmitting. `True` = high. | +| `rts_level_for_rx` | `bool` | `False` | RTS level when receiving. `True` = high. | +| `loopback` | `bool` | `False` | Enable RS-485 loopback mode (see your own transmissions). | + +**Returns:** Dict with `success`, `port`, `rs485_enabled`, and the configured settings (`rts_level_for_tx`, `rts_level_for_rx`, `delay_before_tx`, `delay_before_rx`, `loopback`). Settings are `None` when RS-485 is disabled. + + + +```python +# Enable hardware RS-485 with defaults +set_rs485_mode(port="/dev/ttyUSB0") + +# Add bus settling delays for long cable runs +set_rs485_mode( + port="/dev/ttyUSB0", + delay_before_tx=0.001, + delay_before_rx=0.001, +) + +# Inverted RTS polarity +set_rs485_mode( + port="/dev/ttyUSB0", + rts_level_for_tx=False, + rts_level_for_rx=True, +) + +# Disable hardware RS-485 (revert to software control) +set_rs485_mode(port="/dev/ttyUSB0", enabled=False) +``` + +--- + +## check_rs485_support + +Detect whether a serial port's hardware and driver support automatic RS-485 direction control, or whether software RTS toggling is needed. This tool queries `udevadm` for USB device information and tests the kernel RS-485 ioctl. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path to check. The port does not need to be open. | + +**Returns:** Dict with `success`, `port`, `driver` (e.g., `ftdi_sio`, `cp210x`, `ch341`), `chip` (product string if detected), `hardware_rs485` (bool), `software_fallback` (bool), `kernel_rs485_ioctl` (bool), `notes` (list of informational strings), and `recommendation`. + +Known hardware support: + +| Driver | Chip | Hardware RS-485 | +|--------|------|-----------------| +| `ftdi_sio` | FT232, FT2232, etc. | Yes -- auto-direction control | +| `cp210x` | CP2105, CP2108 | Yes | +| `cp210x` | CP2102 | No -- use software RTS control | +| `ch341` | CH340, CH341 | No -- timing may be unreliable | +| `pl2303` | PL2303 | No -- use software RTS control | +| native | ttyS, ttyAMA | Yes -- check transceiver wiring | + +```python +check_rs485_support(port="/dev/ttyUSB0") + +# Example response: +# { +# "success": true, +# "port": "/dev/ttyUSB0", +# "driver": "ftdi_sio", +# "chip": "FT232R", +# "hardware_rs485": true, +# "software_fallback": true, +# "kernel_rs485_ioctl": true, +# "notes": ["FTDI chips have hardware RS-485 auto-direction"], +# "recommendation": "Use set_rs485_mode() for automatic DE/RE control" +# } +``` + + + +--- + +## rs485_transact + +Send data and receive a response on the RS-485 bus in a single half-duplex transaction. Handles TX-to-RX turnaround timing automatically, including manual RTS control when hardware RS-485 is not available. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path (must be open in RS-485 mode). | +| `data` | `str` | required | Data string to send. | +| `response_timeout` | `float` | `1.0` | Maximum time in seconds to wait for a response. | +| `response_terminator` | `str \| None` | `None` | Stop reading when this sequence is received. | +| `response_length` | `int \| None` | `None` | Expected response length in bytes. Alternative to `response_terminator`. | +| `encoding` | `str` | `"utf-8"` | Character encoding for send and receive data. | +| `turnaround_delay` | `float` | `0.005` | Delay in seconds after TX completes before switching to RX. | + +**Returns:** Dict with `success`, `port`, `bytes_sent`, `data_sent`, `response` (decoded string), `response_bytes`, `response_hex`, and `hardware_rs485` (whether hardware RS-485 was used). + +The transaction flow: +1. Clear the input buffer +2. Assert RTS for TX (if no hardware RS-485) +3. Send encoded data and flush +4. Wait for TX completion + turnaround delay +5. De-assert RTS for RX (if no hardware RS-485) +6. Read response using terminator, length, or timeout + +```python +# Simple query with timeout-based response +rs485_transact(port="/dev/ttyUSB0", data="?ID\r\n") + +# Modbus-style with known response length +rs485_transact( + port="/dev/ttyUSB0", + data="\x01\x03\x00\x00\x00\x01", + response_length=7, + encoding="latin-1", +) + +# Wait for a specific terminator +rs485_transact( + port="/dev/ttyUSB0", + data="READ\r\n", + response_terminator="\r\n", +) + +# Adjust turnaround for slow devices +rs485_transact( + port="/dev/ttyUSB0", + data="PING", + turnaround_delay=0.01, + response_timeout=2.0, +) +``` + + + +--- + +## rs485_scan_addresses + +Scan the RS-485 bus for responding devices by sending a probe message to each address in a range. Useful for discovering Modbus or similar addressed devices. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `port` | `str` | required | Device path (must be open in RS-485 mode). | +| `start_address` | `int` | `1` | First address to scan. | +| `end_address` | `int` | `247` | Last address to scan. Default 247 is the Modbus maximum. | +| `probe_template` | `str` | `"{addr:02x}03000001"` | Message template with `{addr}` placeholder for the address. Default is a Modbus "read holding register" frame. Customize for your protocol. | +| `response_timeout` | `float` | `0.1` | Time in seconds to wait for a response per address. | +| `encoding` | `str` | `"latin-1"` | Encoding for the probe string. Use `latin-1` for raw byte protocols. | + +**Returns:** Dict with `success`, `port`, `addresses_scanned`, `devices_found`, `responding_addresses` (list of objects with `address`, `response_length`, `response_hex`), and `hardware_rs485`. + + + +```python +# Scan the full Modbus range +rs485_scan_addresses(port="/dev/ttyUSB0") + +# Scan a known range of addresses +rs485_scan_addresses( + port="/dev/ttyUSB0", + start_address=1, + end_address=10, +) + +# Custom probe template for a different protocol +rs485_scan_addresses( + port="/dev/ttyUSB0", + probe_template="{addr:c}ID?\r\n", + response_timeout=0.2, + encoding="ascii", +) + +# Faster scan with short timeout +rs485_scan_addresses( + port="/dev/ttyUSB0", + start_address=1, + end_address=32, + response_timeout=0.05, +) +``` + + diff --git a/docs/src/content/docs/reference/url-handlers.mdx b/docs/src/content/docs/reference/url-handlers.mdx new file mode 100644 index 0000000..afc90cc --- /dev/null +++ b/docs/src/content/docs/reference/url-handlers.mdx @@ -0,0 +1,183 @@ +--- +title: URL Schemes +description: Serial port URL schemes for physical, network, and virtual connections +sidebar: + order: 5 +--- + +import { Aside } from '@astrojs/starlight/components'; + +The `port` parameter of `open_serial_port` accepts both local device paths and URL schemes. URL schemes let you connect to network serial devices, virtual loopbacks, debug wrappers, and specialized hardware without changing your read/write workflow. + + + +--- + +## Device Paths + +Standard local serial port paths. These are the most common way to connect to physical hardware. + +**Linux:** +``` +/dev/ttyUSB0 -- USB-to-serial adapter (FTDI, CP210x, CH340) +/dev/ttyACM0 -- USB CDC ACM device (Arduino, STM32) +/dev/ttyS0 -- Built-in UART (motherboard, Raspberry Pi) +/dev/ttyAMA0 -- ARM UART (Raspberry Pi primary UART) +``` + +**Windows:** +``` +COM3 -- USB-to-serial or built-in COM port +COM12 -- Higher-numbered ports +``` + +**macOS:** +``` +/dev/tty.usbserial-1420 -- USB-to-serial adapter +/dev/tty.usbmodem14201 -- USB CDC ACM device +``` + +```python +open_serial_port(port="/dev/ttyUSB0", baudrate=115200) +``` + +--- + +## socket:// + +Raw TCP socket connection. Connects to serial-to-Ethernet bridges, terminal servers, and networked serial devices that expose a plain TCP port. + +**Format:** `socket://host:port` + +Data sent to the socket appears on the remote serial port and vice versa. No protocol negotiation occurs -- the connection is a raw byte stream. + +**When to use:** Serial-to-Ethernet bridges (Moxa, Digi, Lantronix), ESP32/ESP8266 with TCP server firmware, or any device that bridges serial to a TCP socket. + +```python +open_serial_port(port="socket://192.168.1.100:4001", baudrate=115200) +``` + + + +--- + +## rfc2217:// + +Telnet COM Port Control per RFC 2217. Extends the Telnet protocol to configure remote serial port settings (baud rate, data bits, parity, flow control) over the network. + +**Format:** `rfc2217://host:port` + +Unlike `socket://`, this scheme negotiates serial parameters with the remote device. When you set `baudrate=115200`, that setting is transmitted to and applied by the remote server. + +**When to use:** Remote serial port servers that implement RFC 2217, such as ser2net, or commercial terminal servers with Telnet COM Port support. + +```python +# Remote serial with full parameter control +open_serial_port(port="rfc2217://192.168.1.100:2217", baudrate=115200) +``` + + + +--- + +## loop:// + +Loopback virtual port. Everything written is echoed back as readable data. No hardware required. + +**Format:** `loop://` + +**When to use:** Testing, development, CI/CD pipelines, or verifying tool behavior without physical serial hardware. + +```python +open_serial_port(port="loop://", baudrate=9600) +write_serial(port="loop://", data="hello") +read_serial(port="loop://") # Returns "hello" +close_serial_port(port="loop://") +``` + +--- + +## spy:// + +Debug wrapper that logs all serial traffic to stderr while passing data through to the underlying port. Wraps a real device path. + +**Format:** `spy://device_path` + +All bytes read and written are printed to stderr in a human-readable format. The underlying serial connection works exactly as if you opened the device directly. + +**When to use:** Debugging communication issues, reverse-engineering protocols, or logging traffic for analysis. + +```python +# Wraps /dev/ttyUSB0 with traffic logging +open_serial_port(port="spy:///dev/ttyUSB0", baudrate=9600) +``` + + + +--- + +## cp2110:// + +Silicon Labs CP2110 HID-to-UART bridge. Connects to CP2110 devices via the USB HID interface rather than a traditional serial driver. + +**Format:** `cp2110://` + +**When to use:** Devices using the Silicon Labs CP2110 chip that present as HID devices rather than standard serial ports. + + + +```python +open_serial_port(port="cp2110://", baudrate=9600) +``` + +--- + +## hwgrep:// + +Hardware grep -- opens the first serial port matching a hardware description pattern. Searches across device path, description, hardware ID, manufacturer, product, and serial number fields. + +**Format:** `hwgrep://pattern` + +**When to use:** When you know the type of device but not the exact port assignment. Useful for scripts that need to find a specific adapter regardless of which USB port it is plugged into. + +```python +# Open the first FTDI adapter found +open_serial_port(port="hwgrep://FTDI", baudrate=115200) + +# Match by USB VID:PID +open_serial_port(port="hwgrep://VID:PID=0403:6001", baudrate=9600) +``` + + + +--- + +## Summary + +| Scheme | Use Case | Remote Config | Hardware Required | +|--------|----------|---------------|-------------------| +| Device path | Local serial hardware | N/A | Yes | +| `socket://` | Serial-to-Ethernet bridges | No (configure bridge separately) | Network bridge | +| `rfc2217://` | Remote serial with parameter control | Yes (via Telnet negotiation) | RFC 2217 server | +| `loop://` | Testing and development | N/A | None | +| `spy://` | Traffic debugging | N/A | Underlying device | +| `cp2110://` | Silicon Labs HID-to-UART | N/A | CP2110 chip | +| `hwgrep://` | Auto-detect by hardware description | N/A | Matched device | diff --git a/docs/src/content/docs/tutorials/getting-started.mdx b/docs/src/content/docs/tutorials/getting-started.mdx new file mode 100644 index 0000000..ee54361 --- /dev/null +++ b/docs/src/content/docs/tutorials/getting-started.mdx @@ -0,0 +1,269 @@ +--- +title: Getting Started +description: Install mcserial and make your first serial connection. +--- + +import { Steps, Tabs, TabItem, Aside, Card, CardGrid } from '@astrojs/starlight/components'; + +mcserial is a FastMCP server that gives MCP clients full serial port access -- discovery, configuration, read/write, modem control, and file transfers. This tutorial walks you through installation and your first connection. + +## Prerequisites + +- **Python 3.10+** (check with `python --version`) +- **uv** (recommended) or pip for package management +- A serial device, or nothing at all -- `loop://` lets you test without hardware + +## Install mcserial + + + + ```bash + # Run directly -- no install step needed + uvx mcserial + ``` + + `uvx` fetches and runs the latest version in an isolated environment. Nothing is installed globally. + + + ```bash + pip install mcserial + ``` + + If you need CP2110 HID-to-UART support: + + ```bash + pip install mcserial[cp2110] + ``` + + + +## Add to your MCP client + +mcserial runs over stdio, so you register it with your MCP client and the client launches it on demand. + + + + ```bash + claude mcp add mcserial -- uvx mcserial + ``` + + That's it. Claude Code will start mcserial automatically when serial tools are needed. + + + Add this to your `claude_desktop_config.json`: + + ```json + { + "mcpServers": { + "mcserial": { + "command": "uvx", + "args": ["mcserial"] + } + } + } + ``` + + On macOS, the config file is at `~/Library/Application Support/Claude/claude_desktop_config.json`. On Windows, it's at `%APPDATA%\Claude\claude_desktop_config.json`. + + + Any MCP client that supports stdio transport can run mcserial. The command is: + + ```bash + uvx mcserial + ``` + + Pass this as the server command in your client's MCP configuration. Consult your client's documentation for the exact format. + + + + + +## Your first connection + +The natural workflow is: **discover** available ports, **open** one, **read/write** data, then **close** when done. + +This walkthrough uses `loop://` so you can follow along without any hardware. Everything written to a loopback port is immediately available to read back. + + + +1. **Discover available ports** + + Call `list_serial_ports` to see what's connected: + + ``` + list_serial_ports(usb_only=False) + ``` + + Response: + + ```json + [ + { + "device": "/dev/ttyUSB0", + "description": "FT232R USB UART", + "hwid": "USB VID:PID=0403:6001", + "manufacturer": "FTDI", + "product": "FT232R USB UART", + "serial_number": "A50285BI", + "is_open": false + } + ] + ``` + + Set `usb_only=False` to include built-in serial ports. Use `grep` to filter by hardware: `list_serial_ports(grep="FTDI")`. + + + +2. **Open a connection** + + Open the loopback port (or a real device path from step 1): + + ``` + open_serial_port(port="loop://", baudrate=9600) + ``` + + Response: + + ```json + { + "success": true, + "port": "loop://", + "mode": "rs232", + "baudrate": 9600, + "bytesize": 8, + "parity": "N", + "stopbits": 1, + "xonxoff": false, + "rtscts": false, + "dsrdtr": false, + "resource_uri": "serial://loop:///data", + "url_scheme": "loop", + "hint": "Opened via URL handler. Some features (exclusive, auto-baud) are not available." + } + ``` + + The port is now open in RS-232 mode with 8N1 framing (8 data bits, no parity, 1 stop bit) -- the most common configuration. + +3. **Write data** + + Send a string to the port: + + ``` + write_serial(port="loop://", data="Hello, serial world!\n") + ``` + + Response: + + ```json + { + "success": true, + "bytes_written": 21, + "port": "loop://" + } + ``` + +4. **Read data back** + + Read whatever is waiting in the receive buffer: + + ``` + read_serial(port="loop://") + ``` + + Response: + + ```json + { + "success": true, + "data": "Hello, serial world!\n", + "bytes_read": 21, + "raw_hex": "48656c6c6f2c2073657269616c20776f726c64210a", + "port": "loop://" + } + ``` + + Since this is a loopback, you get back exactly what you wrote. With a real device, you'd see the device's response instead. + +5. **Close the connection** + + Always close ports when you're done to release the resource: + + ``` + close_serial_port(port="loop://") + ``` + + Response: + + ```json + { + "success": true, + "port": "loop://", + "message": "Port closed" + } + ``` + + + +## Reading tools at a glance + +mcserial provides several ways to read data, each suited to different situations: + +| Tool | When to use | +|------|-------------| +| `read_serial` | Read whatever bytes are available right now | +| `read_serial_line` | Read one line (up to `\n`) | +| `read_serial_lines` | Drain multi-line responses (up to `max_lines`) | +| `read_until` | Read until a custom terminator (e.g., `>` prompt) | + +## Auto-baud detection + +When opening a real device, you can omit `baudrate` and mcserial will attempt to detect it automatically: + +``` +open_serial_port(port="/dev/ttyUSB0") +``` + +The response includes detection details: + +```json +{ + "success": true, + "port": "/dev/ttyUSB0", + "baudrate": 115200, + "autobaud": { + "auto_detected": true, + "detection_confidence": 87.3, + "detection_candidates": [ + {"baudrate": 115200, "score": 87.3}, + {"baudrate": 9600, "score": 12.1} + ] + } +} +``` + +Auto-detection works best when the device is actively sending data. You can also pass `autobaud_probe="UUUUU"` to send a sync string that triggers a response. + + + +## What's next + + + + Practice read/write patterns, encodings, and flow control without hardware using [loop:// virtual ports](/tutorials/loopback-testing/). + + + Learn modem line control, device resets, and break signals in the [RS-232 guide](/guides/rs232-basics/). + + + Set up multi-drop bus communication and device scanning in the [RS-485 guide](/guides/rs485-modbus/). + + + Full parameter details for all 30 tools in the [reference section](/reference/tools-common/). + + diff --git a/docs/src/content/docs/tutorials/loopback-testing.mdx b/docs/src/content/docs/tutorials/loopback-testing.mdx new file mode 100644 index 0000000..6b0016c --- /dev/null +++ b/docs/src/content/docs/tutorials/loopback-testing.mdx @@ -0,0 +1,378 @@ +--- +title: Loopback Testing +description: Test serial communication without any hardware using loop:// virtual ports. +--- + +import { Steps, Tabs, TabItem, Aside } from '@astrojs/starlight/components'; + +pyserial provides a built-in `loop://` URL scheme that creates a virtual serial port. Everything written to it is immediately available to read back -- no cables, no adapters, no hardware at all. This makes it ideal for testing tool workflows, validating encodings, and running automated checks in CI/CD. + +## Why use loopback + +- **No hardware required** -- test serial workflows on any machine, including headless CI runners +- **Deterministic** -- what you write is exactly what you read, making assertions straightforward +- **Fast** -- no real baud rate delays; data transfers are instantaneous in memory +- **Safe** -- no risk of misconfiguring or locking a real device + +## Basic round-trip + +The simplest test: write a string and read it back. + + + +1. **Open the loopback port** + + ``` + open_serial_port(port="loop://", baudrate=9600) + ``` + + ```json + { + "success": true, + "port": "loop://", + "mode": "rs232", + "baudrate": 9600, + "bytesize": 8, + "parity": "N", + "stopbits": 1, + "resource_uri": "serial://loop:///data", + "url_scheme": "loop" + } + ``` + + The `baudrate` parameter is accepted but has no effect on loopback -- data moves at memory speed regardless of the value. Setting it still validates that the parameter is handled correctly throughout the tool chain. + +2. **Write a message** + + ``` + write_serial(port="loop://", data="AT+VERSION\r\n") + ``` + + ```json + { + "success": true, + "bytes_written": 12, + "port": "loop://" + } + ``` + +3. **Read it back** + + ``` + read_serial(port="loop://") + ``` + + ```json + { + "success": true, + "data": "AT+VERSION\r\n", + "bytes_read": 12, + "raw_hex": "41542b56455253494f4e0d0a", + "port": "loop://" + } + ``` + + The `raw_hex` field confirms the exact bytes on the wire -- useful for verifying that line endings and control characters are correct. + +4. **Close the port** + + ``` + close_serial_port(port="loop://") + ``` + + + +## Testing line-oriented reads + +Many serial devices send responses as lines terminated with `\r\n` or `\n`. Use `read_serial_line` and `read_serial_lines` to handle these. + + + +1. **Open and write multi-line data** + + ``` + open_serial_port(port="loop://", baudrate=115200) + ``` + + ``` + write_serial(port="loop://", data="OK\r\nERROR 42\r\nDONE\r\n") + ``` + +2. **Read one line at a time** + + ``` + read_serial_line(port="loop://") + ``` + + ```json + { + "success": true, + "line": "OK", + "bytes_read": 4, + "port": "loop://" + } + ``` + + The `line` field strips trailing `\r\n` automatically. The `bytes_read` count includes the line ending bytes. + +3. **Drain remaining lines in one call** + + ``` + read_serial_lines(port="loop://", max_lines=10) + ``` + + ```json + { + "success": true, + "lines": ["ERROR 42", "DONE"], + "count": 2, + "bytes_read": 16, + "port": "loop://" + } + ``` + + `read_serial_lines` stops early when no more data is available, so setting `max_lines` higher than expected is fine. + +4. **Close the port** + + ``` + close_serial_port(port="loop://") + ``` + + + +## Testing custom terminators + +Not every protocol uses newlines. Some devices use `>` as a prompt, `\x00` as a null terminator, or multi-byte sequences. Use `read_until` for these. + + + +1. **Open and write prompt-terminated data** + + ``` + open_serial_port(port="loop://", baudrate=9600) + ``` + + ``` + write_serial(port="loop://", data="ELM327 v1.5>") + ``` + +2. **Read until the `>` prompt** + + ``` + read_until(port="loop://", terminator=">") + ``` + + ```json + { + "success": true, + "data": "ELM327 v1.5>", + "bytes_read": 12, + "raw_hex": "454c4d33323720312e353e", + "port": "loop://", + "terminator_found": true + } + ``` + + The `terminator_found` field confirms whether the terminator was actually received or whether the read timed out first. + +3. **Close the port** + + ``` + close_serial_port(port="loop://") + ``` + + + +## Testing encodings + +Serial devices don't always speak UTF-8. Industrial equipment, legacy systems, and some sensors use Latin-1 or other single-byte encodings. mcserial's `encoding` parameter handles the translation. + + + +1. **Open the port** + + ``` + open_serial_port(port="loop://", baudrate=9600) + ``` + +2. **Write with Latin-1 encoding** + + Latin-1 maps bytes 0x00--0xFF directly, which makes it useful for binary-safe text: + + ``` + write_serial(port="loop://", data="Temp: 23\xb0C", encoding="latin-1") + ``` + + The `\xb0` byte is the degree symbol in Latin-1. + +3. **Read with matching encoding** + + ``` + read_serial(port="loop://", encoding="latin-1") + ``` + + ```json + { + "success": true, + "data": "Temp: 23\u00b0C", + "bytes_read": 10, + "raw_hex": "54656d703a203233b043", + "port": "loop://" + } + ``` + + The `b0` byte in `raw_hex` confirms the degree symbol was sent correctly. + +4. **Close the port** + + ``` + close_serial_port(port="loop://") + ``` + + + + + +## Testing raw byte writes + +For binary protocols (Modbus RTU, custom framing, firmware uploads), use `write_serial_bytes` to send exact byte sequences: + + + +1. **Open the port** + + ``` + open_serial_port(port="loop://", baudrate=9600) + ``` + +2. **Write raw bytes** + + Send a Modbus-style query (address 0x01, function 0x03, register 0x0000, count 0x0001): + + ``` + write_serial_bytes(port="loop://", data=[1, 3, 0, 0, 0, 1]) + ``` + + ```json + { + "success": true, + "bytes_written": 6, + "port": "loop://" + } + ``` + +3. **Read back and verify hex** + + ``` + read_serial(port="loop://", encoding="latin-1") + ``` + + ```json + { + "success": true, + "data": "\u0001\u0003\u0000\u0000\u0000\u0001", + "bytes_read": 6, + "raw_hex": "010300000001", + "port": "loop://" + } + ``` + + The `raw_hex` field is the most reliable way to verify binary data -- it shows the exact bytes without encoding ambiguity. + +4. **Close the port** + + ``` + close_serial_port(port="loop://") + ``` + + + +## Testing port configuration changes + +You can reconfigure an open port without closing and reopening it. This is useful for testing parameter changes or simulating baud rate switching: + + + +1. **Open at 9600 baud** + + ``` + open_serial_port(port="loop://", baudrate=9600) + ``` + +2. **Change to 115200 baud with hardware flow control** + + ``` + configure_serial(port="loop://", baudrate=115200, rtscts=true) + ``` + + ```json + { + "success": true, + "port": "loop://", + "baudrate": 115200, + "timeout": 1.0, + "write_timeout": null, + "inter_byte_timeout": null, + "xonxoff": false, + "rtscts": true, + "dsrdtr": false, + "rts": true, + "dtr": true + } + ``` + + The response shows the full port state after the change, making it easy to confirm the new settings. + +3. **Verify the connection status** + + ``` + get_connection_status() + ``` + + This returns all open connections with their current settings, including the updated baud rate and flow control flags. + +4. **Close the port** + + ``` + close_serial_port(port="loop://") + ``` + + + +## Testing buffer management + +When building protocol handlers, you sometimes need to clear stale data before sending a new command. Use `flush_serial` to reset the buffers: + +``` +flush_serial(port="loop://", input_buffer=true, output_buffer=true) +``` + +This discards any unread data in the input buffer and any unsent data in the output buffer. Call it before sending a command when you want a clean slate. + + + +## Using loopback in CI/CD + +Since `loop://` requires no hardware or special permissions, it works in any CI environment. A typical test pattern: + +1. Start mcserial as a subprocess +2. Connect via MCP client +3. Open `loop://` +4. Write known data, read it back, assert equality +5. Test edge cases: empty writes, large payloads, encoding boundaries +6. Close the port + +This validates that your MCP tool chain works end-to-end without needing a physical device in the test runner. diff --git a/docs/src/styles/custom.css b/docs/src/styles/custom.css new file mode 100644 index 0000000..af02459 --- /dev/null +++ b/docs/src/styles/custom.css @@ -0,0 +1,30 @@ +/* mcserial docs — teal accent theme */ +:root { + --sl-color-accent-low: #042f2e; + --sl-color-accent: #0d9488; + --sl-color-accent-high: #99f6e4; + + --sl-color-white: #f0fdfa; + --sl-color-gray-1: #ccfbf1; + --sl-color-gray-2: #5eead4; + --sl-color-gray-3: #2dd4bf; + --sl-color-gray-4: #14b8a6; + --sl-color-gray-5: #0f766e; + --sl-color-gray-6: #115e59; + --sl-color-gray-7: #134e4a; +} + +:root[data-theme='light'] { + --sl-color-accent-low: #ccfbf1; + --sl-color-accent: #0d9488; + --sl-color-accent-high: #042f2e; + + --sl-color-white: #134e4a; + --sl-color-gray-1: #115e59; + --sl-color-gray-2: #0f766e; + --sl-color-gray-3: #14b8a6; + --sl-color-gray-4: #2dd4bf; + --sl-color-gray-5: #99f6e4; + --sl-color-gray-6: #ccfbf1; + --sl-color-gray-7: #f0fdfa; +} diff --git a/docs/tsconfig.json b/docs/tsconfig.json new file mode 100644 index 0000000..8bf91d3 --- /dev/null +++ b/docs/tsconfig.json @@ -0,0 +1,5 @@ +{ + "extends": "astro/tsconfigs/strict", + "include": [".astro/types.d.ts", "**/*"], + "exclude": ["dist"] +} From 38a33e38b15cc5b3c4f16018ac6529113afda83e Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Mon, 2 Feb 2026 22:42:48 -0700 Subject: [PATCH 08/10] Fix DE-9 logo accuracy and reframe docs for MCP client perspective Logo/favicon: Replace crude rectangle with proper DE-9 connector geometry derived from EIA/TIA-574 specs (D-shaped shell, 5-over-4 pin layout, hex standoff mounting posts). Documentation: Rewrite all code examples from the MCP client perspective. Remove Python syntax highlighting, use JSON boolean conventions (true/false instead of True/False), and add framing notes explaining tool-call notation. Tutorials now guide users through natural language interaction with the assistant rather than direct function calls. --- docs/public/favicon.svg | 24 ++++---- docs/src/assets/logo.svg | 40 ++++++++----- .../content/docs/concepts/flow-control.mdx | 2 +- .../content/docs/concepts/rs232-vs-rs485.mdx | 6 +- .../content/docs/guides/file-transfers.mdx | 2 + .../src/content/docs/guides/network-ports.mdx | 2 + docs/src/content/docs/guides/rs232-basics.mdx | 2 + docs/src/content/docs/guides/rs485-modbus.mdx | 2 + docs/src/content/docs/index.mdx | 8 ++- .../content/docs/reference/tools-common.mdx | 58 ++++++++++--------- .../docs/reference/tools-file-transfer.mdx | 14 +++-- .../content/docs/reference/tools-rs232.mdx | 26 +++++---- .../content/docs/reference/tools-rs485.mdx | 20 ++++--- .../content/docs/reference/url-handlers.mdx | 14 ++--- .../docs/tutorials/getting-started.mdx | 24 ++++---- .../docs/tutorials/loopback-testing.mdx | 36 +++++++++--- 16 files changed, 171 insertions(+), 109 deletions(-) diff --git a/docs/public/favicon.svg b/docs/public/favicon.svg index 9efdc10..95b2d2d 100644 --- a/docs/public/favicon.svg +++ b/docs/public/favicon.svg @@ -1,12 +1,16 @@ - - - - - - - - - - + + + + + + + + + + + + + diff --git a/docs/src/assets/logo.svg b/docs/src/assets/logo.svg index 9f0fa3d..621bf3c 100644 --- a/docs/src/assets/logo.svg +++ b/docs/src/assets/logo.svg @@ -1,17 +1,27 @@ - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/src/content/docs/concepts/flow-control.mdx b/docs/src/content/docs/concepts/flow-control.mdx index 214103f..e11e6a3 100644 --- a/docs/src/content/docs/concepts/flow-control.mdx +++ b/docs/src/content/docs/concepts/flow-control.mdx @@ -7,7 +7,7 @@ import { Aside } from '@astrojs/starlight/components'; Flow control prevents data loss when one side of a serial connection sends data faster than the other side can process it. Without flow control, the receiver's buffer fills up, and incoming bytes are silently dropped. -There are two approaches: software flow control using in-band control characters, and hardware flow control using dedicated signal lines. +There are two approaches: software flow control using in-band control characters, and hardware flow control using dedicated signal lines. mcserial provides tools for enabling and managing both types -- your MCP assistant configures flow control when opening a port or via `configure_serial` on an already-open port. ## Software flow control (XON/XOFF) diff --git a/docs/src/content/docs/concepts/rs232-vs-rs485.mdx b/docs/src/content/docs/concepts/rs232-vs-rs485.mdx index c6400d6..c74593e 100644 --- a/docs/src/content/docs/concepts/rs232-vs-rs485.mdx +++ b/docs/src/content/docs/concepts/rs232-vs-rs485.mdx @@ -5,7 +5,7 @@ description: Understanding the differences between RS-232 and RS-485 serial comm import { Aside } from '@astrojs/starlight/components'; -RS-232 and RS-485 are two serial communication standards that solve different problems. RS-232 connects one device to another over short distances. RS-485 connects many devices on a shared bus over long distances. Understanding when to use each one determines which mcserial tools you reach for. +RS-232 and RS-485 are two serial communication standards that solve different problems. RS-232 connects one device to another over short distances. RS-485 connects many devices on a shared bus over long distances. Understanding when to use each one determines which mcserial tools your MCP assistant will reach for. ## Physical layer @@ -71,7 +71,7 @@ RS-485 is the right choice when: ## How mcserial handles the difference -mcserial tracks which mode each port is in and restricts tools accordingly. This prevents accidentally sending RS-232 modem control commands on an RS-485 bus (which would disrupt communication by toggling the direction control line). +mcserial tracks which mode each port is in and restricts tools accordingly. This prevents accidentally sending RS-232 modem control commands on an RS-485 bus (which would disrupt communication by toggling the direction control line). Your MCP assistant uses the `set_port_mode` tool to switch between modes on an open port. ### Default: RS-232 mode @@ -85,7 +85,7 @@ Every port opens in RS-232 mode. The following tools are available: ### After switching: RS-485 mode -Call `set_port_mode(port, "rs485")` to switch. The RS-232 tools become unavailable and these tools become available: +Ask the assistant to call `set_port_mode` with `mode="rs485"` to switch. The RS-232 tools become unavailable and these tools become available: - `set_rs485_mode` -- configure hardware DE/RE direction control - `rs485_transact` -- send data and receive response with automatic turnaround diff --git a/docs/src/content/docs/guides/file-transfers.mdx b/docs/src/content/docs/guides/file-transfers.mdx index 342cc11..3912d20 100644 --- a/docs/src/content/docs/guides/file-transfers.mdx +++ b/docs/src/content/docs/guides/file-transfers.mdx @@ -7,6 +7,8 @@ import { Steps, Aside } from '@astrojs/starlight/components'; Serial file transfers are useful when you need to move files to or from devices that lack network connectivity: embedded systems running a bootloader, legacy industrial equipment, air-gapped machines, or remote hardware accessed through a serial console. +All of the operations described in this guide are performed through your MCP client. Ask the assistant to send or receive files, and it will call the appropriate mcserial transfer tools on your behalf. The tool call notation below shows exactly what the assistant invokes. + mcserial implements four protocol variants, all built in without external dependencies. ## Protocol comparison diff --git a/docs/src/content/docs/guides/network-ports.mdx b/docs/src/content/docs/guides/network-ports.mdx index b11da8b..01d115a 100644 --- a/docs/src/content/docs/guides/network-ports.mdx +++ b/docs/src/content/docs/guides/network-ports.mdx @@ -7,6 +7,8 @@ import { Tabs, TabItem, Aside } from '@astrojs/starlight/components'; Serial devices are not always physically attached to the machine running mcserial. Serial device servers, terminal servers, and networked test equipment expose serial ports over TCP. mcserial supports these through URL schemes passed to `open_serial_port` -- the same read, write, configure, and file transfer tools work regardless of how the port is connected. +All of the operations described in this guide are performed through your MCP client. Ask the assistant to open a network serial port by providing the URL scheme, and all subsequent tool calls work identically to a local port. + ## Why network serial - **Serial device servers** (Digi, Moxa, Lantronix) bridge RS-232/RS-485 ports to your LAN diff --git a/docs/src/content/docs/guides/rs232-basics.mdx b/docs/src/content/docs/guides/rs232-basics.mdx index 86ccab9..b9e099c 100644 --- a/docs/src/content/docs/guides/rs232-basics.mdx +++ b/docs/src/content/docs/guides/rs232-basics.mdx @@ -7,6 +7,8 @@ import { Steps, Aside } from '@astrojs/starlight/components'; RS-232 is the default mode when you open a port with mcserial. It provides point-to-point serial communication with modem control lines -- the signals that let you detect device presence, manage hardware flow control, and trigger resets. +All of the operations described in this guide are performed through your MCP client -- ask the assistant to open ports, read modem lines, pulse reset signals, and so on. The tool call notation below shows exactly what the assistant calls on your behalf. + Every port opens in RS-232 mode automatically. No additional configuration is needed unless you want to switch to RS-485. ## Modem control lines diff --git a/docs/src/content/docs/guides/rs485-modbus.mdx b/docs/src/content/docs/guides/rs485-modbus.mdx index 99f01f8..97a48ac 100644 --- a/docs/src/content/docs/guides/rs485-modbus.mdx +++ b/docs/src/content/docs/guides/rs485-modbus.mdx @@ -7,6 +7,8 @@ import { Steps, Aside } from '@astrojs/starlight/components'; RS-485 uses a shared differential bus where multiple devices communicate over two wires. Unlike RS-232's point-to-point model, RS-485 is half-duplex -- only one device transmits at a time while all others listen. This makes it the standard for industrial protocols like Modbus RTU. +All of the operations described in this guide are performed through your MCP client. Ask the assistant to open ports, switch modes, scan for devices, and transact on the bus. The tool call notation below shows exactly what the assistant calls on your behalf. + ## Switching to RS-485 mode Ports open in RS-232 mode by default. Switch to RS-485 mode before using any RS-485 tools. diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 8b362aa..9dd70ff 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -37,12 +37,14 @@ import { Card, CardGrid, Aside } from '@astrojs/starlight/components'; ## Quick start +Install mcserial and register it with your MCP client: + ```bash -# Add to Claude Code +# Add to Claude Code (one-time setup) claude mcp add mcserial -- uvx mcserial ``` -Then use the tools in a natural sequence -- discover, open, read/write, close: +Then ask your assistant to work with serial ports. It calls the tools behind the scenes: ``` list_serial_ports() # find available ports @@ -52,7 +54,7 @@ read_serial(port="loop://") # read response close_serial_port(port="loop://") # release the port ``` -See the [Getting Started tutorial](/tutorials/getting-started/) for the full walkthrough with example responses. +You interact in natural language -- "list my serial ports," "open the loopback port at 9600 baud," "send hello." See the [Getting Started tutorial](/tutorials/getting-started/) for the full walkthrough with example responses. ## Supported URL schemes diff --git a/docs/src/content/docs/reference/tools-common.mdx b/docs/src/content/docs/reference/tools-common.mdx index 51802f8..c5ceebe 100644 --- a/docs/src/content/docs/reference/tools-common.mdx +++ b/docs/src/content/docs/reference/tools-common.mdx @@ -9,6 +9,10 @@ import { Aside } from '@astrojs/starlight/components'; These 18 tools work in both RS-232 and RS-485 modes. They cover port discovery, connection management, reading and writing data, configuration, flow control, and diagnostics. + + --- ## Port Discovery @@ -24,12 +28,12 @@ List available serial ports on the system. Call this first to discover what port **Returns:** List of port objects with `device`, `description`, `hwid`, `manufacturer`, `product`, `serial_number`, and `is_open` fields. Sorted with USB ports (ttyUSB, ttyACM) first. -```python +``` # List all USB serial devices list_serial_ports() # Include legacy ttyS ports -list_serial_ports(usb_only=False) +list_serial_ports(usb_only=false) # Find FTDI adapters list_serial_ports(grep="FTDI") @@ -69,7 +73,7 @@ Open a serial port connection with optional auto-baud detection. If `baudrate` i When `baudrate` is `None` and the port is a local device (not a URL scheme), auto-baud detection runs automatically. For best results with devices that only respond to input, pass an `autobaud_probe` string like `"UUUUU"` or `"AT\r\n"`. -```python +``` # Auto-detect baud rate open_serial_port(port="/dev/ttyUSB0") @@ -77,10 +81,10 @@ open_serial_port(port="/dev/ttyUSB0") open_serial_port(port="/dev/ttyUSB0", baudrate=115200) # RS-232 with hardware flow control -open_serial_port(port="/dev/ttyUSB0", baudrate=9600, rtscts=True) +open_serial_port(port="/dev/ttyUSB0", baudrate=9600, rtscts=true) # Exclusive access prevents other processes from using the port -open_serial_port(port="/dev/ttyUSB0", baudrate=9600, exclusive=True) +open_serial_port(port="/dev/ttyUSB0", baudrate=9600, exclusive=true) # Auto-detect with sync probe open_serial_port(port="/dev/ttyUSB0", autobaud_probe="UUUUU") @@ -106,7 +110,7 @@ Close an open serial port connection and release it for other processes. **Returns:** Status dict with `success`, `port`, and `message` fields. -```python +``` close_serial_port(port="/dev/ttyUSB0") ``` @@ -121,7 +125,7 @@ Switch a serial port between RS-232 and RS-485 modes. Mode determines which mode **Returns:** Status dict with `success`, `previous_mode`, `current_mode`, and `mode_tools` (list of tools available in the new mode). -```python +``` # Switch to RS-485 mode for Modbus communication set_port_mode(port="/dev/ttyUSB0", mode="rs485") @@ -139,7 +143,7 @@ Get status of all open serial connections. Takes no parameters. **Returns:** Dict with `connections` (map of port to status details) and `count`. Each connection includes `is_open`, `mode`, `baudrate`, `bytesize`, `parity`, `stopbits`, `timeout`, `write_timeout`, `inter_byte_timeout`, flow control flags, buffer counts (`in_waiting`, `out_waiting`), modem line states (`cts`, `dsr`, `ri`, `cd`, `rts`, `dtr`), and `resource_uri`. -```python +``` get_connection_status() ``` @@ -159,7 +163,7 @@ Write string data to an open serial port. Data is encoded using the specified en **Returns:** Dict with `success`, `bytes_written`, and `port`. -```python +``` # Send an AT command write_serial(port="/dev/ttyUSB0", data="AT\r\n") @@ -178,7 +182,7 @@ Write raw bytes to an open serial port. Use this when you need to send binary da **Returns:** Dict with `success`, `bytes_written`, and `port`. -```python +``` # Send AT\r\n as raw bytes write_serial_bytes(port="/dev/ttyUSB0", data=[65, 84, 13, 10]) @@ -207,7 +211,7 @@ Read data from an open serial port. Returns both decoded text and raw hex repres **Returns:** Dict with `success`, `data` (decoded string), `bytes_read`, `raw_hex`, and `port`. Decoding errors are replaced rather than raising exceptions. -```python +``` # Read all available data read_serial(port="/dev/ttyUSB0") @@ -229,7 +233,7 @@ Read a single line (until newline character) from an open serial port. **Returns:** Dict with `success`, `line` (decoded string with trailing CR/LF stripped), `bytes_read`, and `port`. -```python +``` read_serial_line(port="/dev/ttyUSB0") ``` @@ -245,7 +249,7 @@ Read multiple lines from an open serial port. Reads up to `max_lines`, stopping **Returns:** Dict with `success`, `lines` (list of decoded strings), `count`, `bytes_read`, and `port`. -```python +``` # Read up to 10 lines (default) read_serial_lines(port="/dev/ttyUSB0") @@ -266,7 +270,7 @@ Read data until a specific terminator sequence is received. More flexible than ` **Returns:** Dict with `success`, `data` (decoded string), `bytes_read`, `raw_hex`, `port`, and `terminator_found` (bool indicating whether the terminator was actually found or the read timed out). -```python +``` # Read until "OK\r\n" read_until(port="/dev/ttyUSB0", terminator="OK\r\n") @@ -300,7 +304,7 @@ Modify settings on an already-open serial port. Only the parameters you provide **Returns:** Dict with `success`, `port`, and all current settings (`baudrate`, `timeout`, `write_timeout`, `inter_byte_timeout`, `xonxoff`, `rtscts`, `dsrdtr`, `rts`, `dtr`). -```python +``` # Change baud rate on the fly configure_serial(port="/dev/ttyUSB0", baudrate=115200) @@ -308,10 +312,10 @@ configure_serial(port="/dev/ttyUSB0", baudrate=115200) configure_serial(port="/dev/ttyUSB0", timeout=5.0) # Enable hardware flow control -configure_serial(port="/dev/ttyUSB0", rtscts=True) +configure_serial(port="/dev/ttyUSB0", rtscts=true) # Set DTR low (useful for reset sequences) -configure_serial(port="/dev/ttyUSB0", dtr=False) +configure_serial(port="/dev/ttyUSB0", dtr=false) ``` ### flush_serial @@ -326,12 +330,12 @@ Clear serial port input and/or output buffers. Discards any pending data. **Returns:** Dict with `success`, `port`, `flushed_input`, and `flushed_output`. -```python +``` # Flush both buffers (default) flush_serial(port="/dev/ttyUSB0") # Flush only the input buffer -flush_serial(port="/dev/ttyUSB0", input_buffer=True, output_buffer=False) +flush_serial(port="/dev/ttyUSB0", input_buffer=true, output_buffer=false) ``` --- @@ -354,12 +358,12 @@ Manually gate input/output flow control signals on a serial port. Flow control m This function is not portable across all platforms. Behavior depends on the OS and driver support. -```python +``` # Pause incoming data (send XOFF) -set_flow_control(port="/dev/ttyUSB0", input_flow=False) +set_flow_control(port="/dev/ttyUSB0", input_flow=false) # Resume incoming data (send XON) -set_flow_control(port="/dev/ttyUSB0", input_flow=True) +set_flow_control(port="/dev/ttyUSB0", input_flow=true) ``` ### cancel_read @@ -376,7 +380,7 @@ Cancel any pending read operation on a serial port. Interrupts a blocking read b Only effective on platforms that support it (POSIX with select-based reads). -```python +``` cancel_read(port="/dev/ttyUSB0") ``` @@ -394,7 +398,7 @@ Cancel any pending write operation on a serial port. Interrupts a blocking write Only effective on platforms that support it (POSIX with select-based writes). -```python +``` cancel_write(port="/dev/ttyUSB0") ``` @@ -417,9 +421,9 @@ Enable or disable low-latency mode on a serial port. Reduces latency by changing This is a Linux-specific feature. It may not be available on all hardware or kernel versions. Returns an error on unsupported systems rather than silently failing. -```python +``` # Enable low latency for time-critical communication -set_low_latency_mode(port="/dev/ttyUSB0", enabled=True) +set_low_latency_mode(port="/dev/ttyUSB0", enabled=true) ``` ### detect_baud_rate @@ -440,7 +444,7 @@ Auto-detect baud rate using multiple heuristics: 0x55 sync pattern analysis, byt Detection works best when the remote device is actively sending data. For devices that only respond to input, use the `probe` parameter to send a string that triggers a response at each candidate baud rate. -```python +``` # Detect baud rate on an active device detect_baud_rate(port="/dev/ttyUSB0") diff --git a/docs/src/content/docs/reference/tools-file-transfer.mdx b/docs/src/content/docs/reference/tools-file-transfer.mdx index 227c2d6..cb0bce5 100644 --- a/docs/src/content/docs/reference/tools-file-transfer.mdx +++ b/docs/src/content/docs/reference/tools-file-transfer.mdx @@ -9,6 +9,10 @@ import { Aside } from '@astrojs/starlight/components'; Transfer files over serial connections using classic X/Y/ZMODEM protocols. These tools work in both RS-232 and RS-485 modes. + + ## Protocol Comparison | Protocol | Block Size | Batch | Resume | Error Correction | Recommended | @@ -36,7 +40,7 @@ Send a single file over serial using a selected protocol. The receiver must be w **Returns:** Transfer statistics dict with protocol-specific details including bytes sent and any errors. The dict also includes `protocol` and `file` fields. -```python +``` # Send a firmware file using ZMODEM (default) file_transfer_send(port="/dev/ttyUSB0", file_path="/home/user/firmware.bin") @@ -85,7 +89,7 @@ Receive a file over serial using a selected protocol. The behavior of `save_path XMODEM does not transmit the filename -- the sender and receiver must agree on it beforehand. Pass the full destination file path as `save_path`. YMODEM and ZMODEM carry the filename in the protocol, so `save_path` should be a directory. -```python +``` # Receive via ZMODEM into a directory file_transfer_receive( port="/dev/ttyUSB0", @@ -104,7 +108,7 @@ file_transfer_receive( port="/dev/ttyUSB0", save_path="/home/user/downloads/", protocol="ymodem", - overwrite=True, + overwrite=true, ) ``` @@ -130,7 +134,7 @@ Send multiple files in a single batch transfer. Only YMODEM and ZMODEM support b All files are validated before the transfer begins. If any file in the list does not exist, the entire batch is rejected with an error identifying the missing file. -```python +``` # Batch send with ZMODEM (default) file_transfer_send_batch( port="/dev/ttyUSB0", @@ -155,7 +159,7 @@ file_transfer_send_batch( A complete file transfer session looks like this: -```python +``` # 1. Open the port at a suitable baud rate open_serial_port(port="/dev/ttyUSB0", baudrate=115200) diff --git a/docs/src/content/docs/reference/tools-rs232.mdx b/docs/src/content/docs/reference/tools-rs232.mdx index 8b44fd3..55a48b6 100644 --- a/docs/src/content/docs/reference/tools-rs232.mdx +++ b/docs/src/content/docs/reference/tools-rs232.mdx @@ -9,6 +9,10 @@ import { Aside } from '@astrojs/starlight/components'; RS-232 is the default mode for all newly opened ports. These five tools provide control over modem signal lines and break conditions -- the hardware handshaking and signaling layer of point-to-point serial communication. + + @@ -41,7 +45,7 @@ Read all RS-232 modem control and status line states, including the current brea **Returns:** Dict with `success`, `port`, `input_lines` (object with `cts`, `dsr`, `ri`, `cd`), `output_lines` (object with `rts`, `dtr`), and `break_condition` (bool). -```python +``` get_modem_lines(port="/dev/ttyUSB0") # Example response: @@ -74,15 +78,15 @@ These lines are commonly used for: - Power control on some devices - Custom signaling protocols -```python +``` # Assert DTR to signal "terminal ready" -set_modem_lines(port="/dev/ttyUSB0", dtr=True) +set_modem_lines(port="/dev/ttyUSB0", dtr=true) # Drop RTS to signal "stop sending" -set_modem_lines(port="/dev/ttyUSB0", rts=False) +set_modem_lines(port="/dev/ttyUSB0", rts=false) # Set both lines at once -set_modem_lines(port="/dev/ttyUSB0", rts=True, dtr=True) +set_modem_lines(port="/dev/ttyUSB0", rts=true, dtr=true) ``` --- @@ -107,12 +111,12 @@ Typical reset sequences: - **ESP32/ESP8266**: DTR + RTS sequence enters bootloader - **Custom hardware**: Various reset/trigger signals -```python +``` # Arduino-style reset (DTR pulse, active low) pulse_line(port="/dev/ttyUSB0", line="dtr", duration_ms=100) # Active-high pulse on RTS -pulse_line(port="/dev/ttyUSB0", line="rts", duration_ms=200, active_low=False) +pulse_line(port="/dev/ttyUSB0", line="rts", duration_ms=200, active_low=false) # Short trigger pulse pulse_line(port="/dev/ttyUSB0", line="dtr", duration_ms=10) @@ -131,7 +135,7 @@ Send a timed serial break signal -- a sustained low state on the TX line longer **Returns:** Dict with `success`, `port`, and `duration_ms`. -```python +``` # Standard break signal send_break(port="/dev/ttyUSB0") @@ -159,12 +163,12 @@ Set or clear the break condition on a serial port. Unlike `send_break()` which s The break condition holds the TX line low continuously. The remote device will not receive valid data while break is asserted. Always clear the condition with `enabled=False` when done. -```python +``` # Assert break condition -set_break_condition(port="/dev/ttyUSB0", enabled=True) +set_break_condition(port="/dev/ttyUSB0", enabled=true) # ... wait for device to respond ... # Release break -set_break_condition(port="/dev/ttyUSB0", enabled=False) +set_break_condition(port="/dev/ttyUSB0", enabled=false) ``` diff --git a/docs/src/content/docs/reference/tools-rs485.mdx b/docs/src/content/docs/reference/tools-rs485.mdx index 6c0671d..0e3b553 100644 --- a/docs/src/content/docs/reference/tools-rs485.mdx +++ b/docs/src/content/docs/reference/tools-rs485.mdx @@ -9,10 +9,14 @@ import { Aside } from '@astrojs/starlight/components'; RS-485 enables half-duplex multi-drop bus communication where multiple devices share a single pair of wires. These tools handle direction control, request/response transactions, and bus scanning. + + -```python +``` # Enable hardware RS-485 with defaults set_rs485_mode(port="/dev/ttyUSB0") @@ -54,12 +58,12 @@ set_rs485_mode( # Inverted RTS polarity set_rs485_mode( port="/dev/ttyUSB0", - rts_level_for_tx=False, - rts_level_for_rx=True, + rts_level_for_tx=false, + rts_level_for_rx=true, ) # Disable hardware RS-485 (revert to software control) -set_rs485_mode(port="/dev/ttyUSB0", enabled=False) +set_rs485_mode(port="/dev/ttyUSB0", enabled=false) ``` --- @@ -85,7 +89,7 @@ Known hardware support: | `pl2303` | PL2303 | No -- use software RTS control | | native | ttyS, ttyAMA | Yes -- check transceiver wiring | -```python +``` check_rs485_support(port="/dev/ttyUSB0") # Example response: @@ -132,7 +136,7 @@ The transaction flow: 5. De-assert RTS for RX (if no hardware RS-485) 6. Read response using terminator, length, or timeout -```python +``` # Simple query with timeout-based response rs485_transact(port="/dev/ttyUSB0", data="?ID\r\n") @@ -185,7 +189,7 @@ Scan the RS-485 bus for responding devices by sending a probe message to each ad Scanning 247 addresses at 0.1s per address takes approximately 25 seconds. Narrow the address range when possible, or reduce `response_timeout` for faster scans on responsive buses. -```python +``` # Scan the full Modbus range rs485_scan_addresses(port="/dev/ttyUSB0") diff --git a/docs/src/content/docs/reference/url-handlers.mdx b/docs/src/content/docs/reference/url-handlers.mdx index afc90cc..cc90559 100644 --- a/docs/src/content/docs/reference/url-handlers.mdx +++ b/docs/src/content/docs/reference/url-handlers.mdx @@ -39,7 +39,7 @@ COM12 -- Higher-numbered ports /dev/tty.usbmodem14201 -- USB CDC ACM device ``` -```python +``` open_serial_port(port="/dev/ttyUSB0", baudrate=115200) ``` @@ -55,7 +55,7 @@ Data sent to the socket appears on the remote serial port and vice versa. No pro **When to use:** Serial-to-Ethernet bridges (Moxa, Digi, Lantronix), ESP32/ESP8266 with TCP server firmware, or any device that bridges serial to a TCP socket. -```python +``` open_serial_port(port="socket://192.168.1.100:4001", baudrate=115200) ``` @@ -75,7 +75,7 @@ Unlike `socket://`, this scheme negotiates serial parameters with the remote dev **When to use:** Remote serial port servers that implement RFC 2217, such as ser2net, or commercial terminal servers with Telnet COM Port support. -```python +``` # Remote serial with full parameter control open_serial_port(port="rfc2217://192.168.1.100:2217", baudrate=115200) ``` @@ -94,7 +94,7 @@ Loopback virtual port. Everything written is echoed back as readable data. No ha **When to use:** Testing, development, CI/CD pipelines, or verifying tool behavior without physical serial hardware. -```python +``` open_serial_port(port="loop://", baudrate=9600) write_serial(port="loop://", data="hello") read_serial(port="loop://") # Returns "hello" @@ -113,7 +113,7 @@ All bytes read and written are printed to stderr in a human-readable format. The **When to use:** Debugging communication issues, reverse-engineering protocols, or logging traffic for analysis. -```python +``` # Wraps /dev/ttyUSB0 with traffic logging open_serial_port(port="spy:///dev/ttyUSB0", baudrate=9600) ``` @@ -142,7 +142,7 @@ uv pip install mcserial[cp2110] Without this extra, opening a `cp2110://` URL returns an error explaining the missing dependency. -```python +``` open_serial_port(port="cp2110://", baudrate=9600) ``` @@ -156,7 +156,7 @@ Hardware grep -- opens the first serial port matching a hardware description pat **When to use:** When you know the type of device but not the exact port assignment. Useful for scripts that need to find a specific adapter regardless of which USB port it is plugged into. -```python +``` # Open the first FTDI adapter found open_serial_port(port="hwgrep://FTDI", baudrate=115200) diff --git a/docs/src/content/docs/tutorials/getting-started.mdx b/docs/src/content/docs/tutorials/getting-started.mdx index ee54361..bad00e7 100644 --- a/docs/src/content/docs/tutorials/getting-started.mdx +++ b/docs/src/content/docs/tutorials/getting-started.mdx @@ -5,7 +5,11 @@ description: Install mcserial and make your first serial connection. import { Steps, Tabs, TabItem, Aside, Card, CardGrid } from '@astrojs/starlight/components'; -mcserial is a FastMCP server that gives MCP clients full serial port access -- discovery, configuration, read/write, modem control, and file transfers. This tutorial walks you through installation and your first connection. +mcserial is a FastMCP server that gives MCP clients full serial port access -- discovery, configuration, read/write, modem control, and file transfers. You use it through your MCP client (Claude Code, Claude Desktop, or any other MCP-compatible client) by talking to your assistant in natural language. This tutorial walks you through installation, client configuration, and your first serial connection. + + ## Prerequisites @@ -82,18 +86,18 @@ mcserial runs over stdio, so you register it with your MCP client and the client ## Your first connection -The natural workflow is: **discover** available ports, **open** one, **read/write** data, then **close** when done. +The natural workflow is: **discover** available ports, **open** one, **read/write** data, then **close** when done. You ask the assistant to do each step, and it calls the appropriate mcserial tools. This walkthrough uses `loop://` so you can follow along without any hardware. Everything written to a loopback port is immediately available to read back. -1. **Discover available ports** +1. **Ask the assistant to list available ports** - Call `list_serial_ports` to see what's connected: + The assistant calls `list_serial_ports` to see what's connected: ``` - list_serial_ports(usb_only=False) + list_serial_ports(usb_only=false) ``` Response: @@ -112,7 +116,7 @@ This walkthrough uses `loop://` so you can follow along without any hardware. Ev ] ``` - Set `usb_only=False` to include built-in serial ports. Use `grep` to filter by hardware: `list_serial_ports(grep="FTDI")`. + Set `usb_only=false` to include built-in serial ports. Use `grep` to filter by hardware: `list_serial_ports(grep="FTDI")`.