hud-python 0.4.11__py3-none-any.whl → 0.4.12__py3-none-any.whl

hud/cli/build.py

@@ -17,18 +17,18 @@ from hud.clients import MCPClient
 from hud.utils.design import HUDDesign
 from hud.version import __version__ as hud_version
 
-from .registry import save_to_registry
+from .utils.registry import save_to_registry
 
 
 def parse_version(version_str: str) -> tuple[int, int, int]:
     """Parse version string like '1.0.0' or '1.0' into tuple of integers."""
     # Remove 'v' prefix if present
-    version_str = version_str.lstrip('v')
-    
+    version_str = version_str.lstrip("v")
+
     # Split by dots and pad with zeros if needed
-    parts = version_str.split('.')
-    parts.extend(['0'] * (3 - len(parts)))  # Ensure we have at least 3 parts
-    
+    parts = version_str.split(".")
+    parts.extend(["0"] * (3 - len(parts)))  # Ensure we have at least 3 parts
+
     try:
         return (int(parts[0]), int(parts[1]), int(parts[2]))
     except (ValueError, IndexError):
@@ -39,7 +39,7 @@ def parse_version(version_str: str) -> tuple[int, int, int]:
 def increment_version(version_str: str, increment_type: str = "patch") -> str:
     """Increment version string. increment_type can be 'major', 'minor', or 'patch'."""
     major, minor, patch = parse_version(version_str)
-    
+
     if increment_type == "major":
         return f"{major + 1}.0.0"
     elif increment_type == "minor":
@@ -52,11 +52,11 @@ def get_existing_version(lock_path: Path) -> str | None:
     """Get the internal version from existing lock file if it exists."""
     if not lock_path.exists():
         return None
-        
+
     try:
         with open(lock_path) as f:
             lock_data = yaml.safe_load(f)
-            
+
         # Look for internal version in build metadata
         build_data = lock_data.get("build", {})
         return build_data.get("version", None)
@@ -81,7 +81,7 @@ def get_docker_image_digest(image: str) -> str | None:
             if digest_list:
                 # Return full image reference with digest
                 return digest_list[0]
-    except Exception:
+    except Exception:  # noqa: S110
         # Don't print error here, let calling code handle it
         pass
     return None
@@ -113,30 +113,60 @@ def extract_env_vars_from_dockerfile(dockerfile_path: Path) -> tuple[list[str],
     if not dockerfile_path.exists():
         return required, optional
 
-    # Simple parsing - look for ENV directives
-    # This is a basic implementation - could be enhanced
+    # Parse both ENV and ARG directives
     content = dockerfile_path.read_text()
+    arg_vars = set()  # Track ARG variables
+
     for line in content.splitlines():
         line = line.strip()
-        if line.startswith("ENV "):
-            # Basic parsing - this could be more sophisticated
+
+        # Look for ARG directives (build-time variables)
+        if line.startswith("ARG "):
             parts = line[4:].strip().split("=", 1)
-            if len(parts) == 2 and not parts[1].strip():
+            var_name = parts[0].strip()
+            if len(parts) == 1 or not parts[1].strip():
                 # No default value = required
-                required.append(parts[0])
+                arg_vars.add(var_name)
+                if var_name not in required:
+                    required.append(var_name)
+
+        # Look for ENV directives (runtime variables)
+        elif line.startswith("ENV "):
+            parts = line[4:].strip().split("=", 1)
+            var_name = parts[0].strip()
+
+            # Check if it references an ARG variable (e.g., ENV MY_VAR=$MY_VAR)
+            if len(parts) == 2 and parts[1].strip().startswith("$"):
+                ref_var = parts[1].strip()[1:]
+                if ref_var in arg_vars and var_name not in required:
+                    required.append(var_name)
+            elif len(parts) == 2 and not parts[1].strip():
+                # No default value = required
+                if var_name not in required:
+                    required.append(var_name)
             elif len(parts) == 1:
                 # No equals sign = required
-                required.append(parts[0])
+                if var_name not in required:
+                    required.append(var_name)
 
     return required, optional
 
 
-async def analyze_mcp_environment(image: str, verbose: bool = False) -> dict[str, Any]:
+async def analyze_mcp_environment(
+    image: str, verbose: bool = False, env_vars: dict[str, str] | None = None
+) -> dict[str, Any]:
     """Analyze an MCP environment to extract metadata."""
     design = HUDDesign()
+    env_vars = env_vars or {}
 
     # Build Docker command to run the image
-    docker_cmd = ["docker", "run", "--rm", "-i", image]
+    docker_cmd = ["docker", "run", "--rm", "-i"]
+
+    # Add environment variables
+    for key, value in env_vars.items():
+        docker_cmd.extend(["-e", f"{key}={value}"])
+
+    docker_cmd.append(image)
 
     # Create MCP config
     config = {
@@ -209,10 +239,15 @@ async def analyze_mcp_environment(image: str, verbose: bool = False) -> dict[str
 
 
 def build_docker_image(
-    directory: Path, tag: str, no_cache: bool = False, verbose: bool = False
+    directory: Path,
+    tag: str,
+    no_cache: bool = False,
+    verbose: bool = False,
+    build_args: dict[str, str] | None = None,
 ) -> bool:
     """Build a Docker image from a directory."""
     design = HUDDesign()
+    build_args = build_args or {}
 
     # Check if Dockerfile exists
     dockerfile = directory / "Dockerfile"
@@ -224,39 +259,35 @@ def build_docker_image(
     cmd = ["docker", "build", "-t", tag]
     if no_cache:
         cmd.append("--no-cache")
+
+    # Add build args
+    for key, value in build_args.items():
+        cmd.extend(["--build-arg", f"{key}={value}"])
+
     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
+        # Use Docker's native output formatting - no capture, let Docker handle display
+        result = subprocess.run(cmd, check=False)  # noqa: S603
+        return result.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
+    directory: str = ".",
+    tag: str | None = None,
+    no_cache: bool = False,
+    verbose: bool = False,
+    env_vars: dict[str, str] | None = None,
 ) -> None:
     """Build a HUD environment and generate lock file."""
     design = HUDDesign()
+    env_vars = env_vars or {}
     design.header("HUD Environment Build")
 
     # Resolve directory
@@ -292,7 +323,7 @@ def build_environment(
 
     design.progress_message(f"Building Docker image: {temp_tag}")
 
-    # Build the image
+    # Build the image (env vars are for runtime, not build time)
     if not build_docker_image(env_dir, temp_tag, no_cache, verbose):
         design.error("Docker build failed")
         raise typer.Exit(1)
@@ -305,7 +336,7 @@ def build_environment(
     loop = asyncio.new_event_loop()
     asyncio.set_event_loop(loop)
     try:
-        analysis = loop.run_until_complete(analyze_mcp_environment(temp_tag, verbose))
+        analysis = loop.run_until_complete(analyze_mcp_environment(temp_tag, verbose, env_vars))
     finally:
         loop.close()
 
@@ -316,9 +347,9 @@ def build_environment(
 
         # Provide helpful debugging tips
         design.section_title("Debugging Tips")
-        design.info("1. Test your server directly:")
-        design.command_example(f"docker run --rm -it {temp_tag}")
-        design.dim_info("   Expected output", "MCP initialization messages")
+        design.info("1. Debug your environment build:")
+        design.command_example("hud debug . --build")
+        design.dim_info("   This will", "test MCP server connection and show detailed logs")
         design.info("")
         design.info("2. Check for common issues:")
         design.info("   - Server crashes on startup")
@@ -336,10 +367,28 @@ def build_environment(
     dockerfile_path = env_dir / "Dockerfile"
     required_env, optional_env = extract_env_vars_from_dockerfile(dockerfile_path)
 
+    # Merge user-provided env vars with detected ones
+    provided_env_vars = {}
+    missing_required = []
+    if env_vars:
+        provided_env_vars = env_vars.copy()
+        # Track which required vars are still missing
+        missing_required = [e for e in required_env if e not in env_vars]
+
+        # Show what env vars were provided
+        design.success(f"Using provided environment variables: {', '.join(env_vars.keys())}")
+    else:
+        missing_required = required_env[:]
+
+    # Warn about missing required variables
+    if missing_required:
+        design.warning(f"Missing required environment variables: {', '.join(missing_required)}")
+        design.info("These can be added to the lock file after build or provided with -e flags")
+
     # Check for existing version and increment
     lock_path = env_dir / "hud.lock.yaml"
     existing_version = get_existing_version(lock_path)
-    
+
     if existing_version:
         # Increment existing version
         new_version = increment_version(existing_version)
@@ -365,11 +414,20 @@ def build_environment(
         },
     }
 
-    # Only add environment variables if they exist
-    if required_env or optional_env:
+    # Add environment variables section if any exist
+    if missing_required or optional_env or provided_env_vars:
         lock_content["environment"]["variables"] = {}
-        if required_env:
-            lock_content["environment"]["variables"]["required"] = required_env
+
+        # Add note about editing environment variables
+        lock_content["environment"]["variables"]["_note"] = (
+            "You can edit this section to add or modify environment variables. "
+            "Provided variables will be used when running the environment."
+        )
+
+        if provided_env_vars:
+            lock_content["environment"]["variables"]["provided"] = provided_env_vars
+        if missing_required:
+            lock_content["environment"]["variables"]["required"] = missing_required
         if optional_env:
             lock_content["environment"]["variables"]["optional"] = optional_env
 
@@ -399,7 +457,7 @@ def build_environment(
     # Also tag with version
     base_name = tag.split(":")[0] if tag and ":" in tag else tag
     version_tag = f"{base_name}:{new_version}"
-    
+
     label_cmd = [
         "docker",
         "build",
@@ -411,30 +469,21 @@ def build_environment(
         tag,
         "-t",
         version_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
+    label_cmd.append(str(env_dir))
+
+    # Run rebuild using Docker's native output formatting
     if verbose:
-        for line in process.stdout or []:
-            design.info(line.rstrip())
+        # Show Docker's native output when verbose
+        result = subprocess.run(label_cmd, check=False)  # noqa: S603
     else:
-        # Just consume output to avoid blocking
-        process.stdout.read()  # type: ignore
-
-    process.wait()
+        # Hide output when not verbose
+        result = subprocess.run(  # noqa: S603
+            label_cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False
+        )
 
-    if process.returncode != 0:
+    if result.returncode != 0:
         design.error("Failed to rebuild with label")
         raise typer.Exit(1)
 
@@ -475,8 +524,8 @@ def build_environment(
         design.status_item("Also tagged", tag)
     design.status_item("Version", new_version)
     design.status_item("Lock file", "hud.lock.yaml")
-    design.status_item("Tools found", str(analysis['toolCount']))
-    
+    design.status_item("Tools found", str(analysis["toolCount"]))
+
     # Show the digest info separately if we have it
     if image_id:
         design.dim_info("\nImage digest", image_id)
@@ -500,6 +549,7 @@ def build_command(
     ),
     no_cache: bool = typer.Option(False, "--no-cache", help="Build without Docker cache"),
     verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output"),
+    env_vars: dict[str, str] | None = None,
 ) -> None:
     """Build a HUD environment and generate lock file."""
-    build_environment(directory, tag, no_cache, verbose)
+    build_environment(directory, tag, no_cache, verbose, env_vars)

hud/cli/debug.py

@@ -14,7 +14,7 @@ from rich.console import Console
 from hud.clients import MCPClient
 from hud.utils.design import HUDDesign
 
-from .utils import CaptureLogger, Colors, analyze_error_for_hints
+from .utils.logging import CaptureLogger, Colors, analyze_error_for_hints
 
 console = Console()
 
@@ -167,7 +167,7 @@ async def debug_mcp_stdio(command: list[str], logger: CaptureLogger, max_phase:
                         break
                 except Exception as e:
                     logger.error(f"Failed to parse MCP response: {e}")
-                    logger.error(f"Raw output that caused the error: {repr(line)}")
+                    logger.error(f"Raw output that caused the error: {line!r}")
                     logger.hint("This usually means non-JSON output is being sent to STDOUT")
                     logger.hint("Common causes:")
                     logger.hint("  - Print statements in your server code")

hud/cli/{mcp_server.py → dev.py}

@@ -9,12 +9,17 @@ import subprocess
 from pathlib import Path
 
 import click
-import toml
 from fastmcp import FastMCP
 
 from hud.utils.design import HUDDesign
-from .docker_utils import get_docker_cmd, inject_supervisor
-from .env_utils import get_image_name, update_pyproject_toml, build_environment, image_exists
+
+from .utils.docker import get_docker_cmd, inject_supervisor
+from .utils.environment import (
+    build_environment,
+    get_image_name,
+    image_exists,
+    update_pyproject_toml,
+)
 
 # Global design instance
 design = HUDDesign()
@@ -97,6 +102,12 @@ def create_proxy_server(
             design.info("Container will run without hot-reload")
         design.command_example(f"docker logs -f {container_name}", "View container logs")
 
+        # Show the full Docker command if there are environment variables
+        if docker_args and any(arg == "-e" or arg.startswith("--env") for arg in docker_args):
+            design.info("")
+            design.info("Docker command with environment variables:")
+            design.info(" ".join(docker_cmd))
+
     # Create the HTTP proxy server using config
     try:
         proxy = FastMCP.as_proxy(config, name=f"HUD Dev Proxy - {image_name}")
@@ -127,10 +138,9 @@ async def start_mcp_proxy(
     import asyncio
     import logging
     import os
-    import subprocess
     import sys
 
-    from .utils import find_free_port
+    from .utils.logging import find_free_port
 
     # Always disable the banner - we have our own output
     os.environ["FASTMCP_DISABLE_BANNER"] = "1"
@@ -207,15 +217,15 @@ async def start_mcp_proxy(
 
     # Remove any existing container with the same name (silently)
     # Note: The proxy creates containers on-demand when clients connect
-    try:
+    try:  # noqa: SIM105
         subprocess.run(  # noqa: S603, ASYNC221
             ["docker", "rm", "-f", container_name],  # noqa: S607
             stdout=subprocess.DEVNULL,
             stderr=subprocess.DEVNULL,
             check=False,  # Don't raise error if container doesn't exist
         )
-    except Exception:
-        pass  # Silent failure, container might not exist
+    except Exception:  # noqa: S110
+        pass
 
     if transport == "stdio":
         if verbose:
@@ -281,13 +291,11 @@ async def start_mcp_proxy(
                     design.error("Failed to launch inspector")
 
             # Launch inspector asynchronously so it doesn't block
-            asyncio.create_task(launch_inspector())
+            asyncio.create_task(launch_inspector())  # noqa: RUF006
 
         # Launch interactive mode if requested
         if interactive:
             if transport != "http":
-                from hud.utils.design import HUDDesign
-
                 design.warning("Interactive mode only works with HTTP transport")
             else:
                 server_url = f"http://localhost:{actual_port}/mcp"
@@ -306,7 +314,7 @@ async def start_mcp_proxy(
                         design.info("Press Ctrl+C in the interactive session to exit")
 
                         # Import and run interactive mode in a new event loop
-                        from .interactive import run_interactive_mode
+                        from .utils.interactive import run_interactive_mode
 
                         # Create a new event loop for the thread
                         loop = asyncio.new_event_loop()
@@ -329,7 +337,11 @@ async def start_mcp_proxy(
 
     # Function to stream Docker logs
     async def stream_docker_logs() -> None:
-        """Stream Docker container logs asynchronously."""
+        """Stream Docker container logs asynchronously.
+
+        Note: The Docker container is created on-demand when the first client connects.
+        Any environment variables passed via -e flags are included when the container starts.
+        """
         log_design = design
 
         # Always show waiting message
@@ -505,9 +517,7 @@ async def start_mcp_proxy(
             design.info("")
             design.info("Then you can:")
             design.info("  • Test locally: [cyan]hud run <image>[/cyan]")
-            design.info(
-                "  • Push to registry: [cyan]hud push --image <registry/name>[/cyan]"
-            )
+            design.info("  • Push to registry: [cyan]hud push --image <registry/name>[/cyan]")
     except Exception as e:
         # Suppress the graceful shutdown error and other FastMCP/uvicorn internal errors
         error_msg = str(e)
@@ -527,7 +537,7 @@ async def start_mcp_proxy(
             try:
                 await log_task
             except asyncio.CancelledError:
-                pass  # Log streaming cancelled, normal shutdown
+                contextlib.suppress(asyncio.CancelledError)
 
 
 def run_mcp_dev_server(
@@ -588,7 +598,7 @@ def run_mcp_dev_server(
     # For HTTP transport, find available port first
     actual_port = port
     if transport == "http":
-        from .utils import find_free_port
+        from .utils.logging import find_free_port
 
         actual_port = find_free_port(port)
         if actual_port is None:
@@ -600,8 +610,13 @@ def run_mcp_dev_server(
     # Create config
     if transport == "stdio":
         server_config = {"command": "hud", "args": ["dev", directory, "--transport", "stdio"]}
+        # For stdio, include docker args in the command
+        if docker_args:
+            server_config["args"].extend(docker_args)
     else:
         server_config = {"url": f"http://localhost:{actual_port}/mcp"}
+        # Note: Environment variables are passed to the Docker container via the proxy,
+        # not included in the client configuration
 
     # For the deeplink, we only need the server config
     server_config_json = json.dumps(server_config, indent=2)
@@ -627,7 +642,27 @@ def run_mcp_dev_server(
     else:
         design.info(f"🐳 {resolved_image}")
 
-    design.progress_message(f"❗ If any issues arise, run `hud debug {resolved_image}` to debug the container")
+    design.progress_message(
+        f"❗ If any issues arise, run `hud debug {resolved_image}` to debug the container"
+    )
+
+    # Show environment variables if provided
+    if docker_args and any(arg == "-e" or arg.startswith("--env") for arg in docker_args):
+        design.section_title("Environment Variables")
+        design.info("The following environment variables will be passed to the Docker container:")
+        i = 0
+        while i < len(docker_args):
+            if docker_args[i] == "-e" and i + 1 < len(docker_args):
+                design.info(f"  • {docker_args[i + 1]}")
+                i += 2
+            elif docker_args[i].startswith("--env="):
+                design.info(f"  • {docker_args[i][6:]}")
+                i += 1
+            elif docker_args[i] == "--env" and i + 1 < len(docker_args):
+                design.info(f"  • {docker_args[i + 1]}")
+                i += 2
+            else:
+                i += 1
 
     # Show hints about inspector and interactive mode
     if transport == "http":
@@ -679,10 +714,10 @@ def run_mcp_dev_server(
             )
         )
     except Exception as e:
-        d.error(f"Failed to start MCP server: {e}")
-        d.info("")
-        d.info("💡 Tip: Run the following command to debug the container:")
-        d.info(f"   hud debug {resolved_image}")
-        d.info("")
-        d.info("This will help identify connection issues or initialization failures.")
+        design.error(f"Failed to start MCP server: {e}")
+        design.info("")
+        design.info("💡 Tip: Run the following command to debug the container:")
+        design.info(f"   hud debug {resolved_image}")
+        design.info("")
+        design.info("This will help identify connection issues or initialization failures.")
         raise