hud-python 0.3.5__py3-none-any.whl → 0.4.1__py3-none-any.whl

hud/cli/build.py

@@ -0,0 +1,427 @@
+"""Build HUD environments and generate lock files."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import subprocess
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import typer
+import yaml
+from rich.console import Console
+
+from hud.clients import MCPClient
+from hud.utils.design import HUDDesign
+from hud.version import __version__ as hud_version
+
+console = Console()
+
+
+def get_docker_image_digest(image: str) -> str | None:
+    """Get the digest of a Docker image."""
+    try:
+        result = subprocess.run(  # noqa: S603
+            ["docker", "inspect", "--format", "{{.RepoDigests}}", image],  # noqa: S607
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        # Parse the output - it's in format [repo@sha256:digest]
+        digests = result.stdout.strip()
+        if digests and digests != "[]":
+            # Extract the first digest
+            digest_list = eval(digests)  # noqa: S307 # Safe since it's from docker
+            if digest_list:
+                # Return full image reference with digest
+                return digest_list[0]
+    except Exception:
+        console.print("Failed to get Docker image digest")
+    return None
+
+
+def get_docker_image_id(image: str) -> str | None:
+    """Get the ID of a Docker image."""
+    try:
+        result = subprocess.run(  # noqa: S603
+            ["docker", "inspect", "--format", "{{.Id}}", image],  # noqa: S607
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        image_id = result.stdout.strip()
+        if image_id:
+            return image_id
+        return None
+    except Exception:
+        # Don't log here to avoid import issues
+        return None
+
+
+def extract_env_vars_from_dockerfile(dockerfile_path: Path) -> tuple[list[str], list[str]]:
+    """Extract required and optional environment variables from Dockerfile."""
+    required = []
+    optional = []
+
+    if not dockerfile_path.exists():
+        return required, optional
+
+    # Simple parsing - look for ENV directives
+    # This is a basic implementation - could be enhanced
+    content = dockerfile_path.read_text()
+    for line in content.splitlines():
+        line = line.strip()
+        if line.startswith("ENV "):
+            # Basic parsing - this could be more sophisticated
+            parts = line[4:].strip().split("=", 1)
+            if len(parts) == 2 and not parts[1].strip():
+                # No default value = required
+                required.append(parts[0])
+            elif len(parts) == 1:
+                # No equals sign = required
+                required.append(parts[0])
+
+    return required, optional
+
+
+async def analyze_mcp_environment(image: str, verbose: bool = False) -> dict[str, Any]:
+    """Analyze an MCP environment to extract metadata."""
+    design = HUDDesign()
+
+    # Build Docker command to run the image
+    docker_cmd = ["docker", "run", "--rm", "-i", image]
+
+    # Create MCP config
+    config = {
+        "server": {"command": docker_cmd[0], "args": docker_cmd[1:] if len(docker_cmd) > 1 else []}
+    }
+
+    # Initialize client and measure timing
+    start_time = time.time()
+    client = MCPClient(mcp_config=config, verbose=verbose, auto_trace=False)
+    initialized = False
+
+    try:
+        if verbose:
+            design.info(f"Initializing MCP client with command: {' '.join(docker_cmd)}")
+
+        await client.initialize()
+        initialized = True
+        initialize_ms = int((time.time() - start_time) * 1000)
+
+        # Get tools
+        tools = await client.list_tools()
+
+        # Extract tool information
+        tool_info = []
+        for tool in tools:
+            tool_dict = {"name": tool.name, "description": tool.description}
+            if hasattr(tool, "inputSchema") and tool.inputSchema:
+                tool_dict["inputSchema"] = tool.inputSchema
+            tool_info.append(tool_dict)
+
+        return {
+            "initializeMs": initialize_ms,
+            "toolCount": len(tools),
+            "tools": tool_info,
+            "success": True,
+        }
+    except Exception as e:
+        import traceback
+
+        error_msg = str(e)
+        if verbose:
+            design.error(f"Failed to analyze environment: {error_msg}")
+            design.error(f"Traceback:\n{traceback.format_exc()}")
+
+        # Common issues
+        if "Connection reset" in error_msg or "EOF" in error_msg:
+            design.warning(
+                "The MCP server may have crashed on startup. Check your server.py for errors."
+            )
+        elif "timeout" in error_msg:
+            design.warning(
+                "The MCP server took too long to initialize. It might need more startup time."
+            )
+
+        return {
+            "initializeMs": 0,
+            "toolCount": 0,
+            "tools": [],
+            "success": False,
+            "error": error_msg,
+        }
+    finally:
+        # Only shutdown if we successfully initialized
+        if initialized:
+            try:
+                await client.shutdown()
+            except Exception:
+                # Ignore shutdown errors
+                design.warning("Failed to shutdown MCP client")
+
+
+def build_docker_image(
+    directory: Path, tag: str, no_cache: bool = False, verbose: bool = False
+) -> bool:
+    """Build a Docker image from a directory."""
+    design = HUDDesign()
+
+    # Check if Dockerfile exists
+    dockerfile = directory / "Dockerfile"
+    if not dockerfile.exists():
+        design.error(f"No Dockerfile found in {directory}")
+        return False
+
+    # Build command
+    cmd = ["docker", "build", "-t", tag]
+    if no_cache:
+        cmd.append("--no-cache")
+    cmd.append(str(directory))
+
+    # Always show build output
+    design.info(f"Running: {' '.join(cmd)}")
+
+    try:
+        # Run with real-time output, handling encoding issues on Windows
+        process = subprocess.Popen(  # noqa: S603
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            encoding="utf-8",
+            errors="replace",  # Replace invalid chars instead of failing
+        )
+
+        # Stream output
+        for line in process.stdout or []:
+            design.info(line.rstrip())
+
+        process.wait()
+
+        return process.returncode == 0
+    except Exception as e:
+        design.error(f"Build error: {e}")
+        return False
+
+
+def build_environment(
+    directory: str = ".", tag: str | None = None, no_cache: bool = False, verbose: bool = False
+) -> None:
+    """Build a HUD environment and generate lock file."""
+    design = HUDDesign()
+    design.header("HUD Environment Build")
+
+    # Resolve directory
+    env_dir = Path(directory).resolve()
+    if not env_dir.exists():
+        design.error(f"Directory not found: {directory}")
+        raise typer.Exit(1)
+
+    # Check for pyproject.toml
+    pyproject_path = env_dir / "pyproject.toml"
+    if not pyproject_path.exists():
+        design.error(f"No pyproject.toml found in {directory}")
+        raise typer.Exit(1)
+
+    # Read pyproject.toml to get image name
+    try:
+        import toml
+
+        pyproject = toml.load(pyproject_path)
+        default_image = pyproject.get("tool", {}).get("hud", {}).get("image", None)
+        if not default_image:
+            # Generate default from directory name
+            default_image = f"{env_dir.name}:dev"
+    except Exception:
+        default_image = f"{env_dir.name}:dev"
+
+    # Use provided tag or default
+    if not tag:
+        tag = default_image
+
+    # Build temporary image first
+    temp_tag = f"hud-build-temp:{int(time.time())}"
+
+    design.progress_message(f"Building Docker image: {temp_tag}")
+
+    # Build the image
+    if not build_docker_image(env_dir, temp_tag, no_cache, verbose):
+        design.error("Docker build failed")
+        raise typer.Exit(1)
+
+    design.success(f"Built temporary image: {temp_tag}")
+
+    # Analyze the environment
+    design.progress_message("Analyzing MCP environment...")
+
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    try:
+        analysis = loop.run_until_complete(analyze_mcp_environment(temp_tag, verbose))
+    finally:
+        loop.close()
+
+    if not analysis["success"]:
+        design.error("Failed to analyze MCP environment")
+        if "error" in analysis:
+            design.error(f"Error: {analysis['error']}")
+
+        # Provide helpful debugging tips
+        design.section_title("Debugging Tips")
+        console.print("1. Test your server directly:")
+        console.print(f"   [cyan]docker run --rm -it {temp_tag}[/cyan]")
+        console.print("   (Should see MCP initialization output)")
+        console.print("")
+        console.print("2. Check for common issues:")
+        console.print("   - Server crashes on startup")
+        console.print("   - Missing dependencies")
+        console.print("   - Syntax errors in server.py")
+        console.print("")
+        console.print("3. Run with verbose mode:")
+        console.print("   [cyan]hud build . --verbose[/cyan]")
+
+        raise typer.Exit(1)
+
+    design.success(f"Analyzed environment: {analysis['toolCount']} tools found")
+
+    # Extract environment variables from Dockerfile
+    dockerfile_path = env_dir / "Dockerfile"
+    required_env, optional_env = extract_env_vars_from_dockerfile(dockerfile_path)
+
+    # Create lock file content - minimal and useful
+    lock_content = {
+        "version": "1.0",  # Lock file format version
+        "image": tag,  # Will be updated with ID/digest later
+        "build": {
+            "generatedAt": datetime.utcnow().isoformat() + "Z",
+            "hudVersion": hud_version,
+            "directory": str(env_dir.name),
+        },
+        "environment": {
+            "initializeMs": analysis["initializeMs"],
+            "toolCount": analysis["toolCount"],
+        },
+    }
+
+    # Only add environment variables if they exist
+    if required_env or optional_env:
+        lock_content["environment"]["variables"] = {}
+        if required_env:
+            lock_content["environment"]["variables"]["required"] = required_env
+        if optional_env:
+            lock_content["environment"]["variables"]["optional"] = optional_env
+
+    # Add tool summary (not full schemas to keep it concise)
+    if analysis["tools"]:
+        lock_content["tools"] = [
+            {"name": tool["name"], "description": tool.get("description", "")}
+            for tool in analysis["tools"]
+        ]
+
+    # Write lock file
+    lock_path = env_dir / "hud.lock.yaml"
+    with open(lock_path, "w") as f:
+        yaml.dump(lock_content, f, default_flow_style=False, sort_keys=False)
+
+    design.success("Created lock file: hud.lock.yaml")
+
+    # Calculate lock file hash
+    lock_content_str = yaml.dump(lock_content, default_flow_style=False, sort_keys=True)
+    lock_hash = hashlib.sha256(lock_content_str.encode()).hexdigest()
+    lock_size = len(lock_content_str)
+
+    # Rebuild with label containing lock file hash
+    design.progress_message("Rebuilding with lock file metadata...")
+
+    # Build final image with label (uses cache from first build)
+    label_cmd = [
+        "docker",
+        "build",
+        "--label",
+        f"org.hud.manifest.head={lock_hash}:{lock_size}",
+        "-t",
+        tag,
+        str(env_dir),
+    ]
+
+    # Run rebuild with proper encoding
+    process = subprocess.Popen(  # noqa: S603
+        label_cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+
+    # Stream output if verbose
+    if verbose:
+        for line in process.stdout or []:
+            design.info(line.rstrip())
+    else:
+        # Just consume output to avoid blocking
+        process.stdout.read()  # type: ignore
+
+    process.wait()
+
+    if process.returncode != 0:
+        design.error("Failed to rebuild with label")
+        raise typer.Exit(1)
+
+    design.success("Built final image with lock file metadata")
+
+    # NOW get the image ID after the final build
+    image_id = get_docker_image_id(tag)  # type: ignore
+    if image_id:
+        # For local builds, store the image ID
+        # Docker IDs come as sha256:hash, we want tag@sha256:hash
+        if image_id.startswith("sha256:"):
+            lock_content["image"] = f"{tag}@{image_id}"
+        else:
+            lock_content["image"] = f"{tag}@sha256:{image_id}"
+
+        # Update the lock file with the new image reference
+        with open(lock_path, "w") as f:
+            yaml.dump(lock_content, f, default_flow_style=False, sort_keys=False)
+
+        design.success("Updated lock file with image ID")
+    else:
+        design.warning("Could not retrieve image ID for lock file")
+
+    # Remove temp image after we're done
+    subprocess.run(["docker", "rmi", temp_tag], capture_output=True)  # noqa: S603, S607
+
+    # Print summary
+    design.section_title("Build Complete")
+
+    # Show the actual image reference from the lock file
+    final_image_ref = lock_content.get("image", tag)
+    console.print(f"[green]✓[/green] Local image  : {final_image_ref}")
+    console.print("[green]✓[/green] Lock file    : hud.lock.yaml")
+    console.print(f"[green]✓[/green] Tools found  : {analysis['toolCount']}")
+
+    design.section_title("Next Steps")
+    console.print("Test locally:")
+    console.print("  [cyan]hud dev[/cyan]           # Hot-reload development")
+    console.print(f"  [cyan]hud run {tag}[/cyan]  # Run the built image")
+    console.print("")
+    console.print("Publish to registry:")
+    console.print(f"  [cyan]hud push --image <registry>/{tag}[/cyan]")
+    console.print("")
+    console.print("The lock file can be used to reproduce this exact environment.")
+
+
+def build_command(
+    directory: str = typer.Argument(".", help="Environment directory to build"),
+    tag: str | None = typer.Option(
+        None, "--tag", "-t", help="Docker image tag (default: from pyproject.toml)"
+    ),
+    no_cache: bool = typer.Option(False, "--no-cache", help="Build without Docker cache"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output"),
+) -> None:
+    """Build a HUD environment and generate lock file."""
+    build_environment(directory, tag, no_cache, verbose)

hud/cli/clone.py

@@ -0,0 +1,185 @@
+"""Git clone wrapper with quiet mode and rich output.
+
+This module provides a CLI command that wraps 'git clone' to provide a better user experience:
+- Runs git clone quietly (no verbose output)
+- Displays a rich formatted success message
+- Shows optional tutorial/getting started messages from the cloned repository
+
+Usage:
+    hud clone https://github.com/user/repo.git
+
+The clone command will look for a [tool.hud.clone] section in the cloned repository's
+pyproject.toml file. If found, it will display the configured message after cloning.
+
+Configuration in pyproject.toml:
+    [tool.hud.clone]
+    title = "🚀 My Project"  # Optional title for the message panel
+    style = "blue"           # Optional border style (any Rich color)
+
+    # Option 1: Plain text message with Rich markup support
+    message = "[bold]Welcome![/bold] Run [cyan]pip install -e .[/cyan] to start."
+
+    # Option 2: Markdown formatted message
+    markdown = "## Welcome\\n\\nThis supports **markdown** formatting."
+
+    # Option 3: Step-by-step instructions
+    steps = [
+        "Install dependencies: [green]pip install -e .[/green]",
+        "Run tests: [green]pytest[/green]",
+        "Start coding!"
+    ]
+
+Rich Markup Examples:
+    - Colors: [red]text[/red], [green]text[/green], [blue]text[/blue], [cyan]text[/cyan]
+    - Styles: [bold]text[/bold], [italic]text[/italic], [underline]text[/underline]
+    - Combined: [bold cyan]text[/bold cyan]
+    - Background: [on red]text[/on red]
+    - Links: [link=https://example.com]clickable[/link]
+
+See Rich documentation for more markup options: https://rich.readthedocs.io/en/stable/markup.html
+"""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.text import Text
+
+logger = logging.getLogger(__name__)
+
+console = Console()
+
+
+def clone_repository(url: str) -> tuple[bool, str]:
+    """
+    Clone a git repository quietly and return status.
+
+    Args:
+        url: Git repository URL
+
+    Returns:
+        Tuple of (success, directory_path or error_message)
+    """
+    # Extract repo name from URL
+    repo_name = Path(url).stem
+    if repo_name.endswith(".git"):
+        repo_name = repo_name[:-4]
+
+    # Build git clone command (simple, no options)
+    cmd = ["git", "clone", "--quiet", url]
+
+    try:
+        # Run git clone with quiet flag
+        subprocess.run(  # noqa: S603
+            cmd,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+
+        # Get the absolute path of the cloned directory
+        clone_path = Path(repo_name).resolve()
+
+        return True, str(clone_path)
+
+    except subprocess.CalledProcessError as e:
+        error_msg = (
+            e.stderr.strip() if e.stderr else f"Git clone failed with exit code {e.returncode}"
+        )
+        return False, error_msg
+    except Exception as e:
+        return False, f"Unexpected error: {e!s}"
+
+
+def get_clone_message(clone_path: str) -> dict[str, Any] | None:
+    """
+    Look for a clone message configuration in the repository's pyproject.toml or .hud.toml.
+
+    Checks for:
+    1. [tool.hud.clone] section in pyproject.toml
+    2. [clone] section in .hud.toml
+
+    Args:
+        clone_path: Path to the cloned repository
+
+    Returns:
+        Dictionary with message configuration or None
+    """
+    repo_path = Path(clone_path)
+
+    # Check pyproject.toml first
+    pyproject_path = repo_path / "pyproject.toml"
+    if pyproject_path.exists():
+        try:
+            with open(pyproject_path, "rb") as f:
+                data = tomllib.load(f)
+                if "tool" in data and "hud" in data["tool"] and "clone" in data["tool"]["hud"]:
+                    return data["tool"]["hud"]["clone"]
+        except Exception:
+            logger.warning("Failed to load clone config from %s", pyproject_path)
+
+    # Check .hud.toml as fallback
+    hud_toml_path = repo_path / ".hud.toml"
+    if hud_toml_path.exists():
+        try:
+            with open(hud_toml_path, "rb") as f:
+                data = tomllib.load(f)
+                if "clone" in data:
+                    return data["clone"]
+        except Exception:
+            logger.warning("Failed to load clone config from %s", hud_toml_path)
+
+    return None
+
+
+def print_tutorial(clone_config: dict[str, Any] | None = None) -> None:
+    """Print a rich formatted success message with optional tutorial."""
+    # Display custom message if configured
+    if clone_config:
+        # Handle different message formats
+        if "message" in clone_config:
+            # Message with Rich markup support
+            console.print(
+                Panel(
+                    clone_config["message"],  # Rich will parse markup automatically
+                    title=clone_config.get("title", "📋 Getting Started"),
+                    border_style=clone_config.get("style", "blue"),
+                    padding=(1, 2),
+                )
+            )
+        elif "markdown" in clone_config:
+            # Markdown message
+            console.print(
+                Panel(
+                    Markdown(clone_config["markdown"]),
+                    title=clone_config.get("title", "📋 Getting Started"),
+                    border_style=clone_config.get("style", "blue"),
+                    padding=(1, 2),
+                )
+            )
+        elif "steps" in clone_config:
+            # Step-by-step instructions
+            title = clone_config.get("title", "📋 Getting Started")
+            console.print(f"\n[bold]{title}[/bold]\n")
+            for i, step in enumerate(clone_config["steps"], 1):
+                console.print(f"  {i}. {step}")
+            console.print()
+
+
+def print_error(error_msg: str) -> None:
+    """Print a rich formatted error message."""
+    console.print(
+        Panel(
+            Text(f"❌ {error_msg}", style="red"),
+            title="[bold red]Clone Failed[/bold red]",
+            border_style="red",
+            padding=(1, 2),
+        )
+    )

hud/cli/cursor.py

@@ -0,0 +1,92 @@
+"""Cursor config parsing utilities."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+
+def parse_cursor_config(server_name: str) -> tuple[list[str] | None, str | None]:
+    """
+    Parse cursor config to get command for a server.
+
+    Args:
+        server_name: Name of the server in Cursor config
+
+    Returns:
+        Tuple of (command_list, error_message). If successful, error_message is None.
+        If failed, command_list is None and error_message contains the error.
+    """
+    # Find cursor config
+    cursor_config_path = Path.home() / ".cursor" / "mcp.json"
+    if not cursor_config_path.exists():
+        # Try Windows path
+        cursor_config_path = Path(os.environ.get("USERPROFILE", "")) / ".cursor" / "mcp.json"
+
+    if not cursor_config_path.exists():
+        return None, f"Cursor config not found at {cursor_config_path}"
+
+    try:
+        with open(cursor_config_path) as f:
+            config = json.load(f)
+
+        servers = config.get("mcpServers", {})
+        if server_name not in servers:
+            available = ", ".join(servers.keys())
+            return None, f"Server '{server_name}' not found. Available: {available}"
+
+        server_config = servers[server_name]
+        command = server_config.get("command", "")
+        args = server_config.get("args", [])
+        _ = server_config.get("env", {})
+
+        # Combine command and args
+        full_command = [command, *args]
+
+        # Handle reloaderoo wrapper
+        if command == "npx" and "reloaderoo" in args and "--" in args:
+            # Extract the actual command after --
+            dash_index = args.index("--")
+            full_command = args[dash_index + 1 :]
+
+        return full_command, None
+
+    except Exception as e:
+        return None, f"Error reading config: {e}"
+
+
+def list_cursor_servers() -> tuple[list[str] | None, str | None]:
+    """
+    List all available servers in Cursor config.
+
+    Returns:
+        Tuple of (server_list, error_message). If successful, error_message is None.
+    """
+    # Find cursor config
+    cursor_config_path = Path.home() / ".cursor" / "mcp.json"
+    if not cursor_config_path.exists():
+        # Try Windows path
+        cursor_config_path = Path(os.environ.get("USERPROFILE", "")) / ".cursor" / "mcp.json"
+
+    if not cursor_config_path.exists():
+        return None, f"Cursor config not found at {cursor_config_path}"
+
+    try:
+        with open(cursor_config_path) as f:
+            config = json.load(f)
+
+        servers = config.get("mcpServers", {})
+        return list(servers.keys()), None
+
+    except Exception as e:
+        return None, f"Error reading config: {e}"
+
+
+def get_cursor_config_path() -> Path:
+    """Get the path to Cursor's MCP config file."""
+    cursor_config_path = Path.home() / ".cursor" / "mcp.json"
+    if not cursor_config_path.exists():
+        # Try Windows path
+        cursor_config_path = Path(os.environ.get("USERPROFILE", "")) / ".cursor" / "mcp.json"
+    return cursor_config_path