hud-python 0.4.35__py3-none-any.whl → 0.4.37__py3-none-any.whl

hud/cli/utils/config.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def get_config_dir() -> Path:
+    """Return the base HUD config directory in the user's home.
+
+    Uses ~/.hud across platforms for consistency with existing registry data.
+    """
+    return Path.home() / ".hud"
+
+
+def get_user_env_path() -> Path:
+    """Return the path to the persistent user-level env file (~/.hud/.env)."""
+    return get_config_dir() / ".env"
+
+
+def ensure_config_dir() -> Path:
+    """Ensure the HUD config directory exists and return it."""
+    config_dir = get_config_dir()
+    config_dir.mkdir(parents=True, exist_ok=True)
+    return config_dir
+
+
+def parse_env_file(contents: str) -> dict[str, str]:
+    """Parse simple KEY=VALUE lines into a dict.
+
+    - Ignores blank lines and lines starting with '#'.
+    - Does not perform variable substitution or quoting.
+    """
+    data: dict[str, str] = {}
+    for raw_line in contents.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        if key:
+            data[key] = value
+    return data
+
+
+def render_env_file(env: dict[str, str]) -> str:
+    """Render a dict of env values to KEY=VALUE lines with a header."""
+    header = [
+        "# HUD CLI persistent environment file",
+        "# Keys set via `hud set KEY=VALUE`",
+        "# This file is read after process env and project .env",
+        "# so project overrides take precedence over these defaults.",
+        "",
+    ]
+    body = [f"{key}={env[key]}" for key in sorted(env.keys())]
+    return "\n".join([*header, *body, ""])
+
+
+def load_env_file(path: Path | None = None) -> dict[str, str]:
+    """Load env assignments from the given path (defaults to ~/.hud/.env)."""
+    env_path = path or get_user_env_path()
+    if not env_path.exists():
+        return {}
+    try:
+        contents = env_path.read_text(encoding="utf-8")
+    except Exception:
+        return {}
+    return parse_env_file(contents)
+
+
+def save_env_file(env: dict[str, str], path: Path | None = None) -> Path:
+    """Write env assignments to the given path and return the path."""
+    ensure_config_dir()
+    env_path = path or get_user_env_path()
+    rendered = render_env_file(env)
+    env_path.write_text(rendered, encoding="utf-8")
+    return env_path
+
+
+def set_env_values(values: dict[str, str]) -> Path:
+    """Persist provided KEY=VALUE pairs into ~/.hud/.env and return the path."""
+    current = load_env_file()
+    current.update(values)
+    return save_env_file(current)

hud/cli/utils/docker.py

@@ -36,45 +36,6 @@ def get_docker_cmd(image: str) -> list[str] | None:
         return None
 
 
-def inject_supervisor(cmd: list[str]) -> list[str]:
-    """
-    Inject watchfiles CLI supervisor into a Docker CMD.
-
-    For shell commands, we inject before the last exec command.
-    For direct commands, we wrap the entire command.
-
-    Args:
-        cmd: Original Docker CMD
-
-    Returns:
-        Modified CMD with watchfiles supervisor injected
-    """
-    if not cmd:
-        return cmd
-
-    # Handle shell commands that might have background processes
-    if cmd[0] in ["sh", "bash"] and len(cmd) >= 3 and cmd[1] == "-c":
-        shell_cmd = cmd[2]
-
-        # Look for 'exec' in the shell command - this is the last command
-        if " exec " in shell_cmd:
-            # Replace only the exec'd command with watchfiles
-            parts = shell_cmd.rsplit(" exec ", 1)
-            if len(parts) == 2:
-                # Extract the actual command after exec
-                last_cmd = parts[1].strip()
-                # Use watchfiles with logs redirected to stderr (which won't interfere with MCP on stdout)  # noqa: E501
-                new_shell_cmd = f"{parts[0]} exec watchfiles --verbose '{last_cmd}' /app/src"
-                return [cmd[0], cmd[1], new_shell_cmd]
-        else:
-            # No exec, the whole thing is the command
-            return ["sh", "-c", f"watchfiles --verbose '{shell_cmd}' /app/src"]
-
-    # Direct command - wrap with watchfiles
-    watchfiles_cmd = " ".join(cmd)
-    return ["sh", "-c", f"watchfiles --verbose '{watchfiles_cmd}' /app/src"]
-
-
 def image_exists(image_name: str) -> bool:
     """Check if a Docker image exists locally."""
     result = subprocess.run(  # noqa: S603
@@ -121,6 +82,27 @@ def generate_container_name(identifier: str, prefix: str = "hud") -> str:
     return f"{prefix}-{safe_name}"
 
 
+def build_run_command(image: str, docker_args: list[str] | None = None) -> list[str]:
+    """Construct a standard docker run command used across CLI commands.
+
+    Args:
+        image: Docker image name to run
+        docker_args: Additional docker args to pass before the image
+
+    Returns:
+        The docker run command list
+    """
+    args = docker_args or []
+    return [
+        "docker",
+        "run",
+        "--rm",
+        "-i",
+        *args,
+        image,
+    ]
+
+
 def _emit_docker_hints(error_text: str) -> None:
     """Parse common Docker connectivity errors and print platform-specific hints."""
     from hud.utils.hud_console import hud_console

hud/cli/utils/env_check.py

@@ -0,0 +1,196 @@
+"""Environment build checks and discovery helpers.
+
+Shared utilities to:
+- locate an environment directory related to a tasks file
+- ensure the environment is built and up-to-date via source hash comparison
+"""
+
+from __future__ import annotations
+
+import contextlib
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import typer
+import yaml
+
+from hud.utils.hud_console import hud_console
+
+from .docker import require_docker_running
+from .source_hash import compute_source_hash, list_source_files
+
+
+def _parse_generated_at(lock_data: dict[str, Any]) -> float | None:
+    """Parse build.generatedAt into a POSIX timestamp (seconds).
+
+    Returns None if missing or unparsable.
+    """
+    try:
+        generated_at = (lock_data.get("build") or {}).get("generatedAt")
+        if not isinstance(generated_at, str):
+            return None
+        # Support ...Z and offsets
+        iso = generated_at.replace("Z", "+00:00")
+        dt = datetime.fromisoformat(iso)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=UTC)
+        return dt.timestamp()
+    except Exception:
+        return None
+
+
+def _collect_source_diffs(env_dir: Path, lock_data: dict[str, Any]) -> dict[str, list[str]]:
+    """Compute added/removed/modified files since last build using names + mtimes.
+
+    - added/removed are based on the stored build.sourceFiles list vs current file list
+    - modified is based on mtime newer than build.generatedAt for files present now
+    """
+    try:
+        stored_files = (
+            (lock_data.get("build") or {}).get("sourceFiles") if isinstance(lock_data, dict) else []
+        )
+        stored_set = set(str(p) for p in (stored_files or []))
+    except Exception:
+        stored_set = set()
+
+    current_paths = list_source_files(env_dir)
+    # Normalize to POSIX-style relative strings
+    current_list = [str(p.resolve().relative_to(env_dir)).replace("\\", "/") for p in current_paths]
+    current_set = set(current_list)
+
+    added = sorted(current_set - stored_set)
+    removed = sorted(stored_set - current_set)
+
+    # Modified: mtime newer than build.generatedAt
+    modified: list[str] = []
+    built_ts = _parse_generated_at(lock_data)
+    if built_ts is not None:
+        for rel in sorted(current_set & (stored_set or current_set)):
+            with contextlib.suppress(Exception):
+                p = env_dir / rel
+                if p.exists() and p.stat().st_mtime > built_ts:
+                    modified.append(rel)
+
+    return {"added": added, "removed": removed, "modified": modified}
+
+
+def find_environment_dir(tasks_path: Path) -> Path | None:
+    """Best-effort discovery of a nearby environment directory.
+
+    Preference order:
+    - directory with hud.lock.yaml
+    - directory that looks like an environment (Dockerfile + pyproject.toml)
+    - searches tasks dir, CWD, and a couple of parents
+    """
+    from .environment import is_environment_directory  # local import to avoid cycles
+
+    candidates: list[Path] = []
+    cwd = Path.cwd()
+    candidates.extend([tasks_path.parent, cwd])
+
+    # Add parents (up to 2 levels for each)
+    for base in list(candidates):
+        p = base
+        for _ in range(2):
+            p = p.parent
+            if p not in candidates:
+                candidates.append(p)
+
+    # Prefer those with hud.lock.yaml
+    for d in candidates:
+        if (d / "hud.lock.yaml").exists():
+            return d
+
+    # Otherwise, find a plausible environment dir
+    for d in candidates:
+        try:
+            if is_environment_directory(d):
+                return d
+        except Exception as e:
+            hud_console.debug(f"Skipping path {d}: {e}")
+            continue
+
+    return None
+
+
+def ensure_built(env_dir: Path, *, interactive: bool = True) -> dict[str, Any]:
+    """Ensure env has a lock and matches current sources via source hash.
+
+    If interactive is True, prompts to build/rebuild as needed. If False, only warns.
+    Returns the loaded lock data (empty dict if unreadable/missing).
+    """
+    from hud.cli.build import build_environment  # local import to avoid import cycles
+
+    lock_path = env_dir / "hud.lock.yaml"
+    if not lock_path.exists():
+        if interactive:
+            hud_console.warning("No hud.lock.yaml found. The environment hasn't been built.")
+            ok = hud_console.confirm("Build the environment now (runs 'hud build')?", default=True)
+            if not ok:
+                raise typer.Exit(1)
+            require_docker_running()
+            build_environment(str(env_dir), platform="linux/amd64")
+        else:
+            hud_console.dim_info(
+                "Info",
+                "No hud.lock.yaml found nearby; skipping environment change checks.",
+            )
+            return {}
+
+    # Load lock file
+    try:
+        with open(lock_path) as f:
+            lock_data: dict[str, Any] = yaml.safe_load(f) or {}
+    except Exception:
+        lock_data = {}
+
+    # Fast change detection: recompute source hash and compare
+    try:
+        current_hash = compute_source_hash(env_dir)
+        stored_hash = (
+            (lock_data.get("build") or {}).get("sourceHash")
+            if isinstance(lock_data, dict)
+            else None
+        )
+        if stored_hash and current_hash and stored_hash != current_hash:
+            hud_console.warning("Environment sources changed since last build.")
+
+            # Show a brief diff summary to help users understand changes
+            diffs = _collect_source_diffs(env_dir, lock_data)
+
+            def _print_section(name: str, items: list[str]) -> None:
+                if not items:
+                    return
+                # Limit output to avoid flooding the console
+                preview = items[:20]
+                more = len(items) - len(preview)
+                hud_console.section_title(name)
+                for rel in preview:
+                    hud_console.dim_info("", rel)
+                if more > 0:
+                    hud_console.dim_info("", f"... and {more} more")
+
+            _print_section("Modified files", diffs.get("modified", []))
+            _print_section("Added files", diffs.get("added", []))
+            _print_section("Removed files", diffs.get("removed", []))
+
+            if interactive:
+                if hud_console.confirm("Rebuild now (runs 'hud build')?", default=True):
+                    require_docker_running()
+                    build_environment(str(env_dir), platform="linux/amd64")
+                    with open(lock_path) as f:
+                        lock_data = yaml.safe_load(f) or {}
+                else:
+                    hud_console.hint("Continuing without rebuild; this may use an outdated image.")
+            else:
+                hud_console.hint("Run 'hud build' to update the image before proceeding.")
+        elif not stored_hash:
+            hud_console.dim_info(
+                "Info",
+                "No source hash in lock; rebuild to enable change checks.",
+            )
+    except Exception as e:
+        hud_console.debug(f"Source hash check skipped: {e}")
+
+    return lock_data

hud/cli/utils/environment.py

@@ -33,14 +33,15 @@ def get_image_name(directory: str | Path, image_override: str | None = None) ->
         except Exception:
             hud_console.error("Error loading pyproject.toml")
 
-    # Auto-generate with :dev tag
+    # Auto-generate with :dev tag (replace underscores with hyphens)
     dir_path = Path(directory).resolve()  # Get absolute path first
     dir_name = dir_path.name
     if not dir_name or dir_name == ".":
         # If we're in root or have empty name, use parent directory
         dir_name = dir_path.parent.name
-    clean_name = dir_name.replace("_", "-")
-    return f"hud-{clean_name}:dev", "auto"
+    # Replace underscores with hyphens for Docker image names
+    dir_name = dir_name.replace("_", "-")
+    return f"{dir_name}:dev", "auto"
 
 
 def update_pyproject_toml(directory: str | Path, image_name: str, silent: bool = False) -> None:

hud/cli/utils/interactive.py

@@ -39,7 +39,8 @@ class InteractiveMCPTester:
         """Connect to the MCP server."""
         try:
             # Create MCP config for HTTP transport
-            config = {"server": {"url": self.server_url}}
+            # Note: We explicitly set auth to None to prevent OAuth discovery attempts
+            config = {"server": {"url": self.server_url, "auth": None}}
 
             self.client = MCPClient(
                 mcp_config=config,

hud/cli/utils/local_runner.py

@@ -0,0 +1,204 @@
+"""Run local Python files as MCP servers with reload support."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import os
+import signal
+import subprocess
+import sys
+from pathlib import Path
+
+from hud.utils.hud_console import HUDConsole
+
+hud_console = HUDConsole()
+
+
+async def run_with_reload(
+    server_file: str,
+    transport: str = "stdio",
+    port: int | None = None,
+    verbose: bool = False,
+    extra_args: list[str] | None = None,
+) -> None:
+    """Run Python server with auto-reload functionality."""
+    try:
+        import watchfiles
+    except ImportError:
+        hud_console.error(
+            "watchfiles is required for --reload. Install with: pip install watchfiles"
+        )
+        sys.exit(1)
+
+    # Parse server file path
+    if ":" in server_file:
+        file_path, _ = server_file.split(":", 1)
+    else:
+        file_path = server_file
+
+    file_path = Path(file_path).resolve()
+    if not file_path.exists():
+        hud_console.error(f"Server file not found: {file_path}")
+        sys.exit(1)
+
+    # Watch the directory containing the server file (like uvicorn)
+    watch_dir = file_path.parent
+
+    # Build command
+    cmd = [sys.executable, "-m", "fastmcp.cli", "run", server_file]
+    if transport:
+        cmd.extend(["--transport", transport])
+    if port and transport == "http":
+        cmd.extend(["--port", str(port)])
+    cmd.append("--no-banner")
+    if verbose:
+        cmd.extend(["--log-level", "DEBUG"])
+    if extra_args:
+        cmd.append("--")
+        cmd.extend(extra_args)
+
+    # Filter for Python files and important config files
+    def should_reload(change: watchfiles.Change, path: str) -> bool:
+        path_obj = Path(path)
+        # Ignore common non-code files
+        if any(part.startswith(".") for part in path_obj.parts):
+            return False
+        if "__pycache__" in path_obj.parts:
+            return False
+        return path_obj.suffix in {".py", ".json", ".toml", ".yaml", ".yml"}
+
+    process = None
+
+    async def run_server() -> int:
+        """Run the server process."""
+        nonlocal process
+
+        # For stdio transport, we need special handling to preserve stdout
+        if transport == "stdio":
+            # All server logs must go to stderr
+            env = os.environ.copy()
+            env["PYTHONUNBUFFERED"] = "1"
+
+            process = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdin=sys.stdin,
+                stdout=sys.stdout,  # Direct passthrough for MCP
+                stderr=sys.stderr,  # Logs and errors
+                env=env,
+            )
+        else:
+            # For HTTP transport, normal subprocess
+            process = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdin=sys.stdin,
+                stdout=sys.stdout,
+                stderr=sys.stderr,
+            )
+
+        return await process.wait()
+
+    async def stop_server() -> None:
+        """Stop the server process gracefully."""
+        if process and process.returncode is None:
+            if sys.platform == "win32":
+                # Windows: terminate directly
+                process.terminate()
+            else:
+                # Unix: send SIGINT for hot reload
+                process.send_signal(signal.SIGINT)
+
+            # Wait for graceful shutdown
+            try:
+                await asyncio.wait_for(process.wait(), timeout=5.0)
+            except TimeoutError:
+                # Force kill if not responding
+                if verbose:
+                    hud_console.warning("Server didn't stop gracefully, forcing shutdown...")
+                process.kill()
+                await process.wait()
+
+    # Initial server start
+    server_task = asyncio.create_task(run_server())
+
+    try:
+        # Watch for file changes
+        async for changes in watchfiles.awatch(watch_dir):
+            # Check if any change should trigger reload
+            if any(should_reload(change, path) for change, path in changes):
+                changed_files = [
+                    path for _, path in changes if should_reload(watchfiles.Change.modified, path)
+                ]
+                if verbose:
+                    for file in changed_files[:3]:  # Show first 3 files
+                        hud_console.info(f"File changed: {Path(file).relative_to(watch_dir)}")
+                    if len(changed_files) > 3:
+                        hud_console.info(f"... and {len(changed_files) - 3} more files")
+
+                hud_console.info("🔄 Reloading server...")
+
+                # Stop current server
+                await stop_server()
+
+                # Small delay to ensure clean restart
+                await asyncio.sleep(0.1)
+
+                # Start new server
+                server_task = asyncio.create_task(run_server())
+
+    except KeyboardInterrupt:
+        hud_console.info("\n👋 Shutting down...")
+        await stop_server()
+    except Exception as e:
+        if verbose:
+            hud_console.error(f"Reload error: {e}")
+        await stop_server()
+        raise
+    finally:
+        # Ensure server is stopped
+        if server_task and not server_task.done():
+            server_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await server_task
+
+
+def run_local_server(
+    server_file: str,
+    transport: str = "stdio",
+    port: int | None = None,
+    verbose: bool = False,
+    reload: bool = False,
+    extra_args: list[str] | None = None,
+) -> None:
+    """Run a local Python file as an MCP server."""
+    if reload:
+        # Run with reload support
+        asyncio.run(
+            run_with_reload(
+                server_file,
+                transport=transport,
+                port=port,
+                verbose=verbose,
+                extra_args=extra_args,
+            )
+        )
+    else:
+        # Run directly without reload
+        cmd = [sys.executable, "-m", "fastmcp.cli", "run", server_file]
+        if transport:
+            cmd.extend(["--transport", transport])
+        if port and transport == "http":
+            cmd.extend(["--port", str(port)])
+        cmd.append("--no-banner")
+        if verbose:
+            cmd.extend(["--log-level", "DEBUG"])
+        if extra_args:
+            cmd.append("--")
+            cmd.extend(extra_args)
+
+        try:
+            result = subprocess.run(cmd)  # noqa: S603
+            sys.exit(result.returncode)
+        except KeyboardInterrupt:
+            hud_console.info("\n👋 Shutting down...")
+            sys.exit(0)

hud/cli/utils/metadata.py

@@ -161,7 +161,9 @@ async def analyze_from_metadata(reference: str, output_format: str, verbose: boo
         console.print(f"  1. Pull it first: [cyan]hud pull {reference}[/cyan]")
         console.print(f"  2. Run live analysis: [cyan]hud analyze {reference} --live[/cyan]")
         if not settings.api_key:
-            console.print("  3. Set HUD_API_KEY for private environments")
+            console.print(
+                "  3. Set HUD_API_KEY in your environment or run: hud set HUD_API_KEY=your-key-here"
+            )
         return
 
     # Convert lock data to analysis format