hud-python 0.3.4__py3-none-any.whl → 0.4.0__py3-none-any.whl

hud/cli/tests/test_utils.py

@@ -0,0 +1,388 @@
+"""Tests for hud.cli.utils module."""
+
+from __future__ import annotations
+
+import sys
+from unittest.mock import patch
+
+import pytest
+
+from hud.cli.utils import HINT_REGISTRY, CaptureLogger, Colors, analyze_error_for_hints
+
+
+class TestColors:
+    """Test ANSI color codes."""
+
+    def test_color_constants(self) -> None:
+        """Test that color constants are defined."""
+        assert Colors.HEADER == "\033[95m"
+        assert Colors.BLUE == "\033[94m"
+        assert Colors.CYAN == "\033[96m"
+        assert Colors.GREEN == "\033[92m"
+        assert Colors.YELLOW == "\033[93m"
+        assert Colors.GOLD == "\033[33m"
+        assert Colors.RED == "\033[91m"
+        assert Colors.GRAY == "\033[90m"
+        assert Colors.ENDC == "\033[0m"
+        assert Colors.BOLD == "\033[1m"
+
+
+class TestCaptureLogger:
+    """Test CaptureLogger functionality."""
+
+    def test_logger_print_mode(self) -> None:
+        """Test logger in print mode."""
+        logger = CaptureLogger(print_output=True)
+
+        with patch("builtins.print") as mock_print:
+            logger._log("Test message", Colors.GREEN)
+            mock_print.assert_called_once_with(f"{Colors.GREEN}Test message{Colors.ENDC}")
+
+    def test_logger_capture_mode(self) -> None:
+        """Test logger in capture-only mode."""
+        logger = CaptureLogger(print_output=False)
+
+        with patch("builtins.print") as mock_print:
+            logger._log("Test message", Colors.GREEN)
+            mock_print.assert_not_called()
+
+        output = logger.get_output()
+        assert "Test message" in output
+
+    def test_strip_ansi(self) -> None:
+        """Test ANSI code stripping."""
+        logger = CaptureLogger(print_output=False)
+
+        # Test various ANSI sequences
+        text_with_ansi = (
+            f"{Colors.GREEN}Green text{Colors.ENDC} normal {Colors.BOLD}bold{Colors.ENDC}"
+        )
+        clean_text = logger._strip_ansi(text_with_ansi)
+        assert clean_text == "Green text normal bold"
+
+    def test_timestamp(self) -> None:
+        """Test timestamp generation."""
+        logger = CaptureLogger(print_output=False)
+
+        timestamp = logger.timestamp()
+        # Should be in HH:MM:SS format
+        assert len(timestamp) == 8
+        assert timestamp[2] == ":"
+        assert timestamp[5] == ":"
+
+    def test_phase_logging(self) -> None:
+        """Test phase header logging."""
+        logger = CaptureLogger(print_output=False)
+
+        logger.phase(1, "Test Phase")
+        output = logger.get_output()
+
+        assert "=" * 80 in output
+        assert "PHASE 1: Test Phase" in output
+
+    def test_command_logging(self) -> None:
+        """Test command logging."""
+        logger = CaptureLogger(print_output=False)
+
+        logger.command(["python", "script.py", "--arg", "value"])
+        output = logger.get_output()
+
+        assert "$ python script.py --arg value" in output
+
+    def test_success_logging(self) -> None:
+        """Test success message logging."""
+        logger = CaptureLogger(print_output=False)
+
+        logger.success("Operation completed")
+        output = logger.get_output()
+
+        assert "✅ Operation completed" in output
+
+    def test_error_logging(self) -> None:
+        """Test error message logging."""
+        logger = CaptureLogger(print_output=False)
+
+        logger.error("Operation failed")
+        output = logger.get_output()
+
+        assert "❌ Operation failed" in output
+
+    def test_info_logging(self) -> None:
+        """Test info message logging with timestamp."""
+        logger = CaptureLogger(print_output=False)
+
+        with patch.object(logger, "timestamp", return_value="12:34:56"):
+            logger.info("Information message")
+            output = logger.get_output()
+
+            assert "[12:34:56] Information message" in output
+
+    def test_stdio_logging(self) -> None:
+        """Test STDIO communication logging."""
+        logger = CaptureLogger(print_output=False)
+
+        logger.stdio("JSON-RPC message")
+        output = logger.get_output()
+
+        assert "[STDIO] JSON-RPC message" in output
+
+    def test_stderr_logging(self) -> None:
+        """Test STDERR output logging."""
+        logger = CaptureLogger(print_output=False)
+
+        logger.stderr("Error output from server")
+        output = logger.get_output()
+
+        assert "[STDERR] Error output from server" in output
+
+    def test_hint_logging(self) -> None:
+        """Test hint message logging."""
+        logger = CaptureLogger(print_output=False)
+
+        logger.hint("Try checking the configuration")
+        output = logger.get_output()
+
+        assert "💡 Hint: Try checking the configuration" in output
+
+    def test_progress_bar(self) -> None:
+        """Test progress bar visualization."""
+        logger = CaptureLogger(print_output=False)
+
+        # Test partial progress
+        logger.progress_bar(3, 5)
+        output = logger.get_output()
+
+        assert "Progress: [███░░] 3/5 phases (60%)" in output
+        assert "Failed at Phase 4" in output
+
+        # Test complete progress
+        logger = CaptureLogger(print_output=False)
+        logger.progress_bar(5, 5)
+        output = logger.get_output()
+
+        assert "Progress: [█████] 5/5 phases (100%)" in output
+        assert "All phases completed successfully!" in output
+
+    def test_progress_bar_failure_messages(self) -> None:
+        """Test progress bar failure messages at different phases."""
+        test_cases = [
+            (0, "Failed at Phase 1 - Server startup"),
+            (1, "Failed at Phase 2 - MCP initialization"),
+            (2, "Failed at Phase 3 - Tool discovery"),
+            (3, "Failed at Phase 4 - Remote deployment readiness"),
+            (4, "Failed at Phase 5 - Concurrent clients & resources"),
+        ]
+
+        for completed, expected_msg in test_cases:
+            logger = CaptureLogger(print_output=False)
+            logger.progress_bar(completed, 5)
+            output = logger.get_output()
+            assert expected_msg in output
+
+    def test_get_output(self) -> None:
+        """Test getting accumulated output."""
+        logger = CaptureLogger(print_output=False)
+
+        logger.info("First message")
+        logger.error("Second message")
+        logger.success("Third message")
+
+        output = logger.get_output()
+        assert "First message" in output
+        assert "Second message" in output
+        assert "Third message" in output
+
+
+class TestAnalyzeErrorForHints:
+    """Test error analysis and hint generation."""
+
+    def test_x11_display_errors(self) -> None:
+        """Test X11/display related error hints."""
+        errors = [
+            "Can't connect to display :0",
+            "X11 connection rejected",
+            "DISPLAY environment variable not set",
+            "Xlib.error.DisplayConnectionError",
+        ]
+
+        for error in errors:
+            hint = analyze_error_for_hints(error)
+            assert hint is not None
+            assert "GUI environment needs X11" in hint
+            assert "Xvfb" in hint
+
+    def test_import_errors(self) -> None:
+        """Test import/module error hints."""
+        errors = [
+            "ModuleNotFoundError: No module named 'requests'",
+            "ImportError: cannot import name 'api'",
+            "No module named numpy",
+        ]
+
+        for error in errors:
+            hint = analyze_error_for_hints(error)
+            assert hint is not None
+            assert "Missing Python dependencies" in hint
+            assert "pyproject.toml" in hint
+
+    def test_json_errors(self) -> None:
+        """Test JSON parsing error hints."""
+        errors = [
+            "json.decoder.JSONDecodeError: Expecting value",
+            "JSONDecodeError: Expecting value: line 1 column 1",
+        ]
+
+        for error in errors:
+            hint = analyze_error_for_hints(error)
+            assert hint is not None
+            assert "Invalid JSON-RPC communication" in hint
+            assert "proper JSON-RPC format" in hint
+
+    def test_permission_errors(self) -> None:
+        """Test permission error hints."""
+        errors = [
+            "Permission denied: /var/log/app.log",
+            "EACCES: permission denied",
+            "Operation not permitted",
+        ]
+
+        for error in errors:
+            hint = analyze_error_for_hints(error)
+            assert hint is not None
+            assert "Permission issues" in hint
+            assert "Check file permissions" in hint
+
+    def test_memory_errors(self) -> None:
+        """Test memory/resource error hints."""
+        errors = ["Cannot allocate memory", "Process killed", "Container OOMKilled"]
+
+        for error in errors:
+            hint = analyze_error_for_hints(error)
+            assert hint is not None
+            assert "Resource limits exceeded" in hint
+            assert "memory limits" in hint
+
+    def test_port_errors(self) -> None:
+        """Test port binding error hints."""
+        errors = [
+            "bind: address already in use",
+            "EADDRINUSE: address already in use",
+            "port 8080 already allocated",
+        ]
+
+        for error in errors:
+            hint = analyze_error_for_hints(error)
+            assert hint is not None
+            assert "Port conflict detected" in hint
+            assert "different port" in hint
+
+    def test_file_not_found_errors(self) -> None:
+        """Test file not found error hints."""
+        errors = [
+            "FileNotFoundError: [Errno 2] No such file or directory",
+            "No such file or directory: config.json",
+        ]
+
+        for error in errors:
+            hint = analyze_error_for_hints(error)
+            assert hint is not None
+            assert "File or directory missing" in hint
+            assert "required files exist" in hint
+
+    def test_traceback_errors(self) -> None:
+        """Test general traceback error hints."""
+        error = """Traceback (most recent call last):
+  File "app.py", line 10, in <module>
+    import missing_module
+ImportError: No module named missing_module"""
+
+        hint = analyze_error_for_hints(error)
+        assert hint is not None
+        # Should match both traceback and import patterns
+        # Import has higher priority
+        assert "Missing Python dependencies" in hint
+
+    def test_timeout_errors(self) -> None:
+        """Test timeout error hints."""
+        errors = ["Operation timed out after 30 seconds", "Connection timeout", "Request timed out"]
+
+        for error in errors:
+            hint = analyze_error_for_hints(error)
+            assert hint is not None
+            assert "Server taking too long to start" in hint
+            assert "slow operations" in hint
+
+    def test_no_error_text(self) -> None:
+        """Test with empty or None error text."""
+        assert analyze_error_for_hints("") is None
+        assert analyze_error_for_hints(None) is None
+
+    def test_no_matching_pattern(self) -> None:
+        """Test with error that doesn't match any pattern."""
+        hint = analyze_error_for_hints("Some random error message")
+        assert hint is None
+
+    def test_priority_ordering(self) -> None:
+        """Test that higher priority hints are returned."""
+        # This error matches both "No module" (priority 9) and "Exception" (priority 2)
+        error = "Exception: No module named requests"
+        hint = analyze_error_for_hints(error)
+        assert hint is not None
+        # Should get the higher priority hint (import error)
+        assert "Missing Python dependencies" in hint
+
+    def test_case_insensitive_matching(self) -> None:
+        """Test that pattern matching is case insensitive."""
+        errors = ["PERMISSION DENIED", "permission denied", "Permission Denied"]
+
+        for error in errors:
+            hint = analyze_error_for_hints(error)
+            assert hint is not None
+            assert "Permission issues" in hint
+
+
+class TestHintRegistry:
+    """Test the hint registry structure."""
+
+    def test_hint_registry_structure(self) -> None:
+        """Test that HINT_REGISTRY has correct structure."""
+        assert isinstance(HINT_REGISTRY, list)
+        assert len(HINT_REGISTRY) > 0
+
+        for hint_data in HINT_REGISTRY:
+            assert "patterns" in hint_data
+            assert "priority" in hint_data
+            assert "hint" in hint_data
+
+            assert isinstance(hint_data["patterns"], list)
+            assert isinstance(hint_data["priority"], int)
+            assert isinstance(hint_data["hint"], str)
+
+            # All patterns should be strings
+            for pattern in hint_data["patterns"]:
+                assert isinstance(pattern, str)
+
+    def test_hint_priorities_unique(self) -> None:
+        """Test that hint priorities are reasonable."""
+        priorities = [hint["priority"] for hint in HINT_REGISTRY]
+
+        # Priorities should be positive
+        assert all(p > 0 for p in priorities)
+
+        # Should have a range of priorities
+        assert max(priorities) > min(priorities)
+
+
+class TestWindowsSupport:
+    """Test Windows-specific functionality."""
+
+    @pytest.mark.skipif(sys.platform != "win32", reason="Windows only test")
+    def test_windows_ansi_enable(self) -> None:
+        """Test that ANSI is enabled on Windows."""
+        # The module should call os.system("") on import
+        # This is hard to test directly, but we can check platform detection
+        assert sys.platform == "win32"
+
+
+if __name__ == "__main__":
+    pytest.main([__file__])

hud/cli/utils.py

@@ -0,0 +1,263 @@
+"""CLI utilities - logging, colors, and error analysis."""
+
+from __future__ import annotations
+
+import re
+import sys
+from datetime import datetime
+from io import StringIO
+
+# Enable ANSI colors on Windows
+if sys.platform == "win32":
+    import os
+
+    os.system("")  # Enable ANSI escape sequences on Windows # noqa: S607 S605
+
+
+class Colors:
+    """ANSI color codes for terminal output."""
+
+    HEADER = "\033[95m"
+    BLUE = "\033[94m"
+    CYAN = "\033[96m"
+    GREEN = "\033[92m"
+    YELLOW = "\033[93m"
+    GOLD = "\033[33m"
+    RED = "\033[91m"
+    GRAY = "\033[90m"
+    ENDC = "\033[0m"
+    BOLD = "\033[1m"
+
+
+class CaptureLogger:
+    """Logger that can both print and capture output."""
+
+    def __init__(self, print_output: bool = True) -> None:
+        self.print_output = print_output
+        self.buffer = StringIO()
+
+    def _log(self, message: str, color: str = "") -> None:
+        """Internal log method that handles both printing and capturing."""
+        if self.print_output:
+            if color:
+                print(f"{color}{message}{Colors.ENDC}")  # noqa: T201
+            else:
+                print(message)  # noqa: T201
+
+        # Always capture (without ANSI codes)
+        clean_msg = self._strip_ansi(message)
+        self.buffer.write(clean_msg + "\n")
+
+    def _strip_ansi(self, text: str) -> str:
+        """Remove ANSI escape codes from text."""
+        ansi_escape = re.compile(r"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])")
+        return ansi_escape.sub("", text)
+
+    def timestamp(self) -> str:
+        """Get minimal timestamp HH:MM:SS."""
+        return datetime.now().strftime("%H:%M:%S")
+
+    def phase(self, phase_num: int, title: str) -> None:
+        """Log a phase header."""
+        self._log(f"\n{'=' * 80}", Colors.GOLD if self.print_output else "")
+        self._log(
+            f"PHASE {phase_num}: {title}", Colors.BOLD + Colors.GOLD if self.print_output else ""
+        )
+        self._log(f"{'=' * 80}\n", Colors.GOLD if self.print_output else "")
+
+    def command(self, cmd: list) -> None:
+        """Log the command being executed."""
+        self._log(f"$ {' '.join(cmd)}", Colors.BOLD if self.print_output else "")
+
+    def success(self, message: str) -> None:
+        """Log a success message."""
+        self._log(f"✅ {message}", Colors.GREEN if self.print_output else "")
+
+    def error(self, message: str) -> None:
+        """Log an error message."""
+        self._log(f"❌ {message}", Colors.RED if self.print_output else "")
+
+    def info(self, message: str) -> None:
+        """Log an info message."""
+        self._log(f"[{self.timestamp()}] {message}")
+
+    def stdio(self, message: str) -> None:
+        """Log STDIO communication."""
+        self._log(f"[STDIO] {message}", Colors.GOLD if self.print_output else "")
+
+    def stderr(self, message: str) -> None:
+        """Log STDERR output."""
+        self._log(f"[STDERR] {message}", Colors.GRAY if self.print_output else "")
+
+    def hint(self, hint: str) -> None:
+        """Log a hint message."""
+        self._log(f"\n💡 Hint: {hint}", Colors.YELLOW if self.print_output else "")
+
+    def progress_bar(self, completed: int, total: int) -> None:
+        """Show a visual progress bar."""
+        filled = "█" * completed
+        empty = "░" * (total - completed)
+        percentage = (completed / total) * 100
+
+        self._log(
+            f"\nProgress: [{filled}{empty}] {completed}/{total} phases ({percentage:.0f}%)",
+            Colors.BOLD if self.print_output else "",
+        )
+
+        phase_messages = {
+            0: ("Failed at Phase 1 - Server startup", Colors.RED),
+            1: ("Failed at Phase 2 - MCP initialization", Colors.YELLOW),
+            2: ("Failed at Phase 3 - Tool discovery", Colors.YELLOW),
+            3: ("Failed at Phase 4 - Remote deployment readiness", Colors.YELLOW),
+            4: ("Failed at Phase 5 - Concurrent clients & resources", Colors.YELLOW),
+            5: ("All phases completed successfully!", Colors.GREEN),
+        }
+
+        if completed in phase_messages:
+            msg, color = phase_messages[completed]
+            self._log(msg, color if self.print_output else "")
+
+    def get_output(self) -> str:
+        """Get the captured output."""
+        return self.buffer.getvalue()
+
+
+# Hint registry with patterns and priorities
+HINT_REGISTRY = [
+    {
+        "patterns": [r"Can't connect to display", r"X11", r"DISPLAY.*not set", r"Xlib.*error"],
+        "priority": 10,
+        "hint": """GUI environment needs X11. Common fixes:
+   - Start Xvfb before importing GUI libraries in your entrypoint
+   - Use a base image with X11 pre-configured (e.g., hudpython/novnc-base)
+   - Delay GUI imports until after X11 is running""",
+    },
+    {
+        "patterns": [r"ModuleNotFoundError", r"ImportError", r"No module named"],
+        "priority": 9,
+        "hint": """Missing Python dependencies. Check:
+   - Is pyproject.toml complete with all dependencies?
+   - Did 'pip install' run successfully?
+   - For editable installs, is the package structure correct?""",
+    },
+    {
+        "patterns": [r"json\.decoder\.JSONDecodeError", r"Expecting value.*line.*column"],
+        "priority": 8,
+        "hint": """Invalid JSON-RPC communication. Check:
+   - MCP server is using proper JSON-RPC format
+   - No debug prints are corrupting stdout
+   - Character encoding is UTF-8""",
+    },
+    {
+        "patterns": [r"Permission denied", r"EACCES", r"Operation not permitted"],
+        "priority": 7,
+        "hint": """Permission issues. Try:
+   - Check file permissions in container/environment
+   - Running with appropriate user
+   - Using --privileged flag if absolutely needed (Docker)""",
+    },
+    {
+        "patterns": [r"Cannot allocate memory", r"killed", r"OOMKilled"],
+        "priority": 6,
+        "hint": """Resource limits exceeded. Consider:
+   - Increasing memory limits
+   - Optimizing memory usage in your code
+   - Checking for memory leaks""",
+    },
+    {
+        "patterns": [r"bind.*address already in use", r"EADDRINUSE", r"port.*already allocated"],
+        "priority": 5,
+        "hint": """Port conflict detected. Options:
+   - Use a different port
+   - Check if another process is running
+   - Ensure proper cleanup in previous runs""",
+    },
+    {
+        "patterns": [r"FileNotFoundError", r"No such file or directory"],
+        "priority": 4,
+        "hint": """File or directory missing. Check:
+   - All required files exist
+   - Working directory is set correctly
+   - File paths are correct for the environment""",
+    },
+    {
+        "patterns": [r"Traceback.*most recent call last", r"Exception"],
+        "priority": 2,
+        "hint": """Server crashed during startup. Common causes:
+   - Missing environment variables
+   - Import errors in your module
+   - Initialization code failing""",
+    },
+    {
+        "patterns": [r"timeout", r"timed out"],
+        "priority": 1,
+        "hint": """Server taking too long to start. Consider:
+   - Using initialization wrappers for heavy setup
+   - Moving slow operations to setup() tool
+   - Checking for deadlocks or infinite loops""",
+    },
+]
+
+
+def analyze_error_for_hints(error_text: str | None) -> str | None:
+    """Analyze error text and return the highest priority matching hint."""
+    if not error_text:
+        return None
+
+    matches = []
+    for hint_data in HINT_REGISTRY:
+        for pattern in hint_data["patterns"]:
+            if re.search(pattern, error_text, re.IGNORECASE):
+                matches.append((hint_data["priority"], hint_data["hint"]))
+                break
+
+    if matches:
+        matches.sort(key=lambda x: x[0], reverse=True)
+        return matches[0][1]
+
+    return None
+
+
+def find_free_port(start_port: int = 8765, max_attempts: int = 100) -> int | None:
+    """Find a free port starting from the given port.
+
+    Args:
+        start_port: Port to start searching from
+        max_attempts: Maximum number of ports to try
+
+    Returns:
+        Available port number or None if no ports found
+    """
+    import socket
+
+    for port in range(start_port, start_port + max_attempts):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            try:
+                # Try to bind to the port
+                s.bind(("", port))
+                s.close()
+                return port
+            except OSError:
+                # Port is in use, try next one
+                continue
+    return None
+
+
+def is_port_free(port: int) -> bool:
+    """Check if a specific port is free.
+
+    Args:
+        port: Port number to check
+
+    Returns:
+        True if port is free, False otherwise
+    """
+    import socket
+
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        try:
+            s.bind(("", port))
+            s.close()
+            return True
+        except OSError:
+            return False