voidremote 1.0.0__py3-none-any.whl

voidremote/ui/widgets/metric_gauge.py

@@ -0,0 +1,90 @@
+"""Circular gauge widget for CPU/RAM/Battery monitoring."""
+
+from __future__ import annotations
+
+import math
+from typing import Optional
+
+from PySide6.QtCore import Qt, QRectF
+from PySide6.QtGui import QColor, QPainter, QPen, QFont, QBrush
+from PySide6.QtWidgets import QWidget
+
+from voidremote.ui.theme import Colors
+
+
+class MetricGauge(QWidget):
+    """
+    Circular progress gauge for displaying a percentage metric.
+
+    Shows value, label, and color-coded arc.
+    """
+
+    def __init__(
+        self,
+        label: str = "",
+        color: str = Colors.ACCENT,
+        parent: Optional[QWidget] = None,
+    ) -> None:
+        super().__init__(parent)
+        self._label = label
+        self._color = color
+        self._value = 0.0
+        self._suffix = "%"
+        self.setMinimumSize(100, 100)
+
+    def set_value(self, value: float) -> None:
+        self._value = max(0.0, min(100.0, value))
+        self.update()
+
+    def set_label(self, label: str) -> None:
+        self._label = label
+        self.update()
+
+    def set_suffix(self, suffix: str) -> None:
+        self._suffix = suffix
+        self.update()
+
+    def paintEvent(self, event: object) -> None:  # type: ignore[override]
+        painter = QPainter(self)
+        painter.setRenderHint(QPainter.RenderHint.Antialiasing)
+
+        w = self.width()
+        h = self.height()
+        size = min(w, h)
+        margin = size * 0.1
+        arc_rect = QRectF(margin, margin, size - 2 * margin, size - 2 * margin)
+
+        # Background track
+        pen = QPen(QColor(Colors.BG_ELEVATED))
+        pen.setWidth(int(size * 0.08))
+        pen.setCapStyle(Qt.PenCapStyle.RoundCap)
+        painter.setPen(pen)
+        painter.drawArc(arc_rect, 225 * 16, -270 * 16)
+
+        # Value arc
+        if self._value > 0:
+            val_color = QColor(self._color)
+            val_pen = QPen(val_color)
+            val_pen.setWidth(int(size * 0.08))
+            val_pen.setCapStyle(Qt.PenCapStyle.RoundCap)
+            painter.setPen(val_pen)
+            span = int(-270 * 16 * self._value / 100.0)
+            painter.drawArc(arc_rect, 225 * 16, span)
+
+        # Center text — value
+        painter.setPen(QPen(QColor(Colors.TEXT_PRIMARY)))
+        value_font = QFont("Inter, Segoe UI", int(size * 0.2), QFont.Weight.Bold)
+        painter.setFont(value_font)
+        center_rect = QRectF(0, h * 0.3, w, h * 0.3)
+        painter.drawText(
+            center_rect,
+            Qt.AlignmentFlag.AlignCenter,
+            f"{self._value:.0f}{self._suffix}",
+        )
+
+        # Label below value
+        painter.setPen(QPen(QColor(Colors.TEXT_MUTED)))
+        label_font = QFont("Inter, Segoe UI", int(size * 0.1))
+        painter.setFont(label_font)
+        label_rect = QRectF(0, h * 0.58, w, h * 0.2)
+        painter.drawText(label_rect, Qt.AlignmentFlag.AlignCenter, self._label)

voidremote/utils/__init__.py

@@ -0,0 +1,28 @@
+"""VoidRemote utility modules."""
+
+from voidremote.utils.logging import get_logger, setup_logging
+from voidremote.utils.security import (
+    sanitize_shell_arg,
+    sanitize_shell_args,
+    validate_device_path,
+    validate_host,
+    validate_ip_address,
+    validate_local_path,
+    validate_package_name,
+    validate_pairing_code,
+    validate_port,
+)
+
+__all__ = [
+    "get_logger",
+    "setup_logging",
+    "sanitize_shell_arg",
+    "sanitize_shell_args",
+    "validate_device_path",
+    "validate_host",
+    "validate_ip_address",
+    "validate_local_path",
+    "validate_package_name",
+    "validate_pairing_code",
+    "validate_port",
+]

voidremote/utils/logging.py

@@ -0,0 +1,120 @@
+"""
+Structured logging setup for VoidRemote.
+
+Configures rotating file logs and colored console output with
+consistent formatting across the entire application.
+"""
+
+from __future__ import annotations
+
+import logging
+import logging.handlers
+import sys
+from pathlib import Path
+from typing import Optional
+
+# ANSI color codes for terminal output
+COLORS = {
+    "RESET": "\033[0m",
+    "BOLD": "\033[1m",
+    "DIM": "\033[2m",
+    "RED": "\033[91m",
+    "GREEN": "\033[92m",
+    "YELLOW": "\033[93m",
+    "BLUE": "\033[94m",
+    "MAGENTA": "\033[95m",
+    "CYAN": "\033[96m",
+    "WHITE": "\033[97m",
+    "GREY": "\033[90m",
+}
+
+LEVEL_COLORS: dict[int, str] = {
+    logging.DEBUG: COLORS["CYAN"],
+    logging.INFO: COLORS["GREEN"],
+    logging.WARNING: COLORS["YELLOW"],
+    logging.ERROR: COLORS["RED"],
+    logging.CRITICAL: COLORS["MAGENTA"] + COLORS["BOLD"],
+}
+
+
+class ColoredFormatter(logging.Formatter):
+    """Log formatter that adds ANSI color to console output."""
+
+    def __init__(self, fmt: Optional[str] = None, use_color: bool = True) -> None:
+        super().__init__(fmt)
+        self.use_color = use_color and sys.stdout.isatty()
+
+    def format(self, record: logging.LogRecord) -> str:
+        original_levelname = record.levelname
+        if self.use_color:
+            color = LEVEL_COLORS.get(record.levelno, COLORS["RESET"])
+            record.levelname = f"{color}{record.levelname:<8}{COLORS['RESET']}"
+            record.name = f"{COLORS['BLUE']}{record.name}{COLORS['RESET']}"
+        result = super().format(record)
+        record.levelname = original_levelname
+        return result
+
+
+def setup_logging(
+    level: str = "INFO",
+    log_file: Optional[Path] = None,
+    max_bytes: int = 10 * 1024 * 1024,
+    backup_count: int = 5,
+    console: bool = True,
+    console_color: bool = True,
+    fmt: Optional[str] = None,
+) -> None:
+    """
+    Configure application-wide logging.
+
+    Args:
+        level: Log level string (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+        log_file: Optional path to write rotating log file.
+        max_bytes: Max size of each log file before rotation.
+        backup_count: Number of backup log files to keep.
+        console: Whether to output logs to stderr.
+        console_color: Whether to colorize console output.
+        fmt: Custom log format string.
+    """
+    root = logging.getLogger()
+    root.setLevel(getattr(logging, level.upper(), logging.INFO))
+
+    # Remove existing handlers to avoid duplicates on re-init
+    root.handlers.clear()
+
+    log_format = fmt or "%(asctime)s | %(levelname)-8s | %(name)-30s | %(message)s"
+    date_format = "%Y-%m-%d %H:%M:%S"
+
+    if console:
+        console_handler = logging.StreamHandler(sys.stderr)
+        console_handler.setFormatter(
+            ColoredFormatter(fmt=log_format, use_color=console_color)
+        )
+        root.addHandler(console_handler)
+
+    if log_file is not None:
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        file_handler = logging.handlers.RotatingFileHandler(
+            log_file,
+            maxBytes=max_bytes,
+            backupCount=backup_count,
+            encoding="utf-8",
+        )
+        file_handler.setFormatter(
+            logging.Formatter(fmt=log_format, datefmt=date_format)
+        )
+        root.addHandler(file_handler)
+
+    # Silence noisy third-party loggers
+    logging.getLogger("PIL").setLevel(logging.WARNING)
+    logging.getLogger("urllib3").setLevel(logging.WARNING)
+    logging.getLogger("adb_shell").setLevel(logging.WARNING)
+
+    logging.getLogger(__name__).debug(
+        "Logging configured: level=%s, file=%s", level, log_file
+    )
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a logger for the given module name."""
+    return logging.getLogger(name)

voidremote/utils/security.py

@@ -0,0 +1,216 @@
+"""
+Security utilities for VoidRemote.
+
+Input validation, command injection prevention, and safe operations.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+import shlex
+from pathlib import Path
+from typing import Optional
+
+
+# Characters that must not appear in ADB shell arguments
+_SHELL_INJECTION_PATTERN = re.compile(r"[;&|`$<>\\]")
+_SAFE_PACKAGE_PATTERN = re.compile(r"^[a-zA-Z][a-zA-Z0-9._]{1,255}$")
+_SAFE_FILENAME_PATTERN = re.compile(r'^[a-zA-Z0-9_\-. ()]+$')
+_PORT_RE = re.compile(r"^\d{1,5}$")
+
+
+def validate_ip_address(address: str) -> str:
+    """
+    Validate that a string is a valid IPv4 or IPv6 address.
+
+    Args:
+        address: IP address string to validate.
+
+    Returns:
+        The validated address string.
+
+    Raises:
+        ValueError: If the address is not valid.
+    """
+    try:
+        parsed = ipaddress.ip_address(address)
+        return str(parsed)
+    except ValueError as exc:
+        raise ValueError(f"Invalid IP address: {address!r}") from exc
+
+
+def validate_host(host: str) -> str:
+    """
+    Validate a host (IP or hostname) for use in ADB connections.
+
+    Args:
+        host: Hostname or IP address.
+
+    Returns:
+        Stripped, validated host string.
+
+    Raises:
+        ValueError: If host is empty or contains invalid characters.
+    """
+    host = host.strip()
+    if not host:
+        raise ValueError("Host cannot be empty")
+    if len(host) > 253:
+        raise ValueError("Hostname too long")
+    # Try IP address first
+    try:
+        return validate_ip_address(host)
+    except ValueError:
+        pass
+    # Validate hostname (RFC 1123)
+    hostname_re = re.compile(
+        r"^(?:[a-zA-Z0-9]"
+        r"(?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?"
+        r"(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*)?$"
+    )
+    if not hostname_re.match(host):
+        raise ValueError(f"Invalid hostname: {host!r}")
+    return host
+
+
+def validate_port(port: int | str) -> int:
+    """
+    Validate a network port number.
+
+    Args:
+        port: Port as integer or string.
+
+    Returns:
+        Validated port as integer.
+
+    Raises:
+        ValueError: If port is out of range.
+    """
+    try:
+        p = int(port)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"Port must be an integer, got: {port!r}") from exc
+    if not (1 <= p <= 65535):
+        raise ValueError(f"Port must be 1-65535, got: {p}")
+    return p
+
+
+def validate_pairing_code(code: str) -> str:
+    """
+    Validate an ADB wireless pairing code.
+
+    Pairing codes are typically 6 digits.
+
+    Args:
+        code: Pairing code string.
+
+    Returns:
+        Validated code (stripped).
+
+    Raises:
+        ValueError: If code format is invalid.
+    """
+    code = code.strip()
+    if not code:
+        raise ValueError("Pairing code cannot be empty")
+    if not re.match(r"^\d{6}$", code):
+        raise ValueError("Pairing code must be exactly 6 digits")
+    return code
+
+
+def sanitize_shell_arg(arg: str) -> str:
+    """
+    Sanitize a single argument intended for ADB shell execution.
+
+    Raises ValueError if the argument contains injection characters.
+
+    Args:
+        arg: Shell argument to sanitize.
+
+    Returns:
+        Shell-quoted safe string.
+
+    Raises:
+        ValueError: If arg contains shell metacharacters.
+    """
+    if _SHELL_INJECTION_PATTERN.search(arg):
+        raise ValueError(
+            f"Shell argument contains forbidden characters: {arg!r}"
+        )
+    return shlex.quote(arg)
+
+
+def sanitize_shell_args(args: list[str]) -> list[str]:
+    """Sanitize a list of shell arguments."""
+    return [sanitize_shell_arg(a) for a in args]
+
+
+def validate_package_name(package: str) -> str:
+    """
+    Validate an Android package name.
+
+    Args:
+        package: Android package name (e.g. com.example.app).
+
+    Returns:
+        Validated package name.
+
+    Raises:
+        ValueError: If package name is invalid.
+    """
+    package = package.strip()
+    if not _SAFE_PACKAGE_PATTERN.match(package):
+        raise ValueError(f"Invalid Android package name: {package!r}")
+    return package
+
+
+def validate_device_path(path: str) -> str:
+    """
+    Validate a path on the Android device.
+
+    Ensures it's an absolute path without null bytes or parent traversal tricks.
+
+    Args:
+        path: Absolute device path.
+
+    Returns:
+        Validated path string.
+
+    Raises:
+        ValueError: If path is unsafe.
+    """
+    if not path.startswith("/"):
+        raise ValueError(f"Device path must be absolute, got: {path!r}")
+    if "\x00" in path:
+        raise ValueError("Device path contains null byte")
+    # Normalize to remove // or trailing /
+    p = Path(path)
+    normalized = str(p)
+    if ".." in normalized.split("/"):
+        raise ValueError(f"Device path contains parent traversal: {path!r}")
+    return normalized
+
+
+def validate_local_path(path: Path) -> Path:
+    """
+    Validate a local file system path.
+
+    Args:
+        path: Local path to validate.
+
+    Returns:
+        Resolved path.
+
+    Raises:
+        ValueError: If path is unsafe or doesn't exist for reading.
+    """
+    resolved = path.resolve()
+    if "\x00" in str(resolved):
+        raise ValueError("Path contains null byte")
+    return resolved
+
+
+def is_safe_filename(name: str) -> bool:
+    """Return True if name is safe for use as a file/directory name."""
+    return bool(_SAFE_FILENAME_PATTERN.match(name)) and ".." not in name