hud-python 0.4.52__py3-none-any.whl → 0.4.53__py3-none-any.whl

hud/cli/utils/docker.py

@@ -1,4 +1,9 @@
-"""Docker utilities for HUD CLI."""
+"""Docker utilities for HUD CLI.
+
+This module centralizes helpers for constructing Docker commands and
+standardizes environment variable handling for "folder mode" (environment
+directories that include a `.env` file and/or `hud.lock.yaml`).
+"""
 
 from __future__ import annotations
 
@@ -6,6 +11,12 @@ import json
 import platform
 import shutil
 import subprocess
+from pathlib import Path
+
+from .config import parse_env_file
+
+# Note: we deliberately avoid the stricter is_environment_directory() check here
+# to allow folder mode with only a Dockerfile or only a pyproject.toml.
 
 
 def get_docker_cmd(image: str) -> list[str] | None:
@@ -103,6 +114,114 @@ def build_run_command(image: str, docker_args: list[str] | None = None) -> list[
     ]
 
 
+def detect_environment_dir(start_dir: Path | None = None) -> Path | None:
+    """Detect an environment directory for folder mode.
+
+    Detection order:
+    - Current directory containing `hud.lock.yaml`
+    - Parent directory containing `hud.lock.yaml`
+    - Current directory that looks like an environment if it has either a
+      `Dockerfile` or a `pyproject.toml` (looser than `is_environment_directory`).
+
+    Returns the detected directory path or None if not found.
+    """
+    base = (start_dir or Path.cwd()).resolve()
+
+    # Check current then parent for lock file
+    for candidate in [base, base.parent]:
+        if (candidate / "hud.lock.yaml").exists():
+            return candidate
+
+    # Fallback: treat as env if it has Dockerfile OR pyproject.toml
+    if (base / "Dockerfile").exists() or (base / "pyproject.toml").exists():
+        return base
+
+    return None
+
+
+def load_env_vars_for_dir(env_dir: Path) -> dict[str, str]:
+    """Load KEY=VALUE pairs from `<env_dir>/.env` if present.
+
+    Returns an empty dict if no file is found or parsing fails.
+    """
+    env_file = env_dir / ".env"
+    if not env_file.exists():
+        return {}
+    try:
+        contents = env_file.read_text(encoding="utf-8")
+        return parse_env_file(contents)
+    except Exception:
+        return {}
+
+
+def build_env_flags(env_vars: dict[str, str]) -> list[str]:
+    """Convert an env dict into a flat list of `-e KEY=VALUE` flags."""
+    flags: list[str] = []
+    for key, value in env_vars.items():
+        flags.extend(["-e", f"{key}={value}"])
+    return flags
+
+
+def create_docker_run_command(
+    image: str,
+    docker_args: list[str] | None = None,
+    env_dir: Path | str | None = None,
+    extra_env: dict[str, str] | None = None,
+    name: str | None = None,
+    interactive: bool = True,
+    remove: bool = True,
+) -> list[str]:
+    """Create a standardized `docker run` command with folder-mode envs.
+
+    - If `env_dir` is provided (or auto-detected), `.env` entries are injected as
+      `-e KEY=VALUE` flags before the image.
+    - `extra_env` allows callers to provide additional env pairs that override
+      variables from `.env`.
+
+    Args:
+        image: Docker image to run
+        docker_args: Additional docker args (volumes, ports, etc.)
+        env_dir: Environment directory to load `.env` from; if None, auto-detect
+        extra_env: Additional env variables to inject (takes precedence)
+        name: Optional container name
+        interactive: Include `-i` flag (default True)
+        remove: Include `--rm` flag (default True)
+
+    Returns:
+        Fully constructed docker run command
+    """
+    cmd: list[str] = ["docker", "run"]
+    if remove:
+        cmd.append("--rm")
+    if interactive:
+        cmd.append("-i")
+    if name:
+        cmd.extend(["--name", name])
+
+    # Load env from `.env` in detected env directory
+    env_dir_path: Path | None = (
+        Path(env_dir).resolve() if isinstance(env_dir, (str, Path)) else detect_environment_dir()
+    )
+
+    merged_env: dict[str, str] = {}
+    if env_dir_path is not None:
+        merged_env.update(load_env_vars_for_dir(env_dir_path))
+    if extra_env:
+        # Caller-provided values override .env
+        merged_env.update(extra_env)
+
+    # Insert env flags before other args
+    if merged_env:
+        cmd.extend(build_env_flags(merged_env))
+
+    # Add remaining args (volumes, ports, etc.)
+    if docker_args:
+        cmd.extend(docker_args)
+
+    cmd.append(image)
+    return cmd
+
+
 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/runner.py

@@ -16,7 +16,7 @@ def run_stdio_server(image: str, docker_args: list[str], verbose: bool) -> None:
     """Run Docker image as stdio MCP server (direct passthrough)."""
     hud_console = HUDConsole()  # Use stderr for stdio mode
 
-    # Build docker command
+    # Build docker command (image-only mode: do not auto-inject local .env)
     docker_cmd = ["docker", "run", "--rm", "-i", *docker_args, image]
 
     if verbose:

hud/cli/utils/tests/test_config.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hud.cli.utils.config import (
+    ensure_config_dir,
+    get_config_dir,
+    get_user_env_path,
+    load_env_file,
+    parse_env_file,
+    render_env_file,
+    save_env_file,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def test_parse_env_file_basic():
+    contents = """
+# comment
+KEY=VALUE
+EMPTY=
+NOEQ
+ SPACED = v 
+"""  # noqa: W291
+    data = parse_env_file(contents)
+    assert data["KEY"] == "VALUE"
+    assert data["EMPTY"] == ""
+    assert data["SPACED"] == "v"
+    assert "NOEQ" not in data
+
+
+def test_render_and_load_roundtrip(tmp_path: Path):
+    env = {"A": "1", "B": "2"}
+    file_path = tmp_path / ".env"
+    rendered = render_env_file(env)
+    file_path.write_text(rendered, encoding="utf-8")
+    loaded = load_env_file(file_path)
+    assert loaded == env
+
+
+def test_get_paths(monkeypatch, tmp_path: Path):
+    from pathlib import Path as _Path
+
+    monkeypatch.setattr(_Path, "home", lambda: tmp_path)
+    cfg = get_config_dir()
+    assert str(cfg).replace("\\", "/").endswith("/.hud")
+    assert str(get_user_env_path()).replace("\\", "/").endswith("/.hud/.env")
+
+
+def test_ensure_and_save(tmp_path: Path, monkeypatch):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    cfg = ensure_config_dir()
+    assert cfg.exists()
+    out = save_env_file({"K": "V"})
+    assert out.exists()
+    assert load_env_file(out) == {"K": "V"}

hud/cli/utils/tests/test_docker.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from hud.cli.utils.docker import (
+    build_run_command,
+    generate_container_name,
+    get_docker_cmd,
+    image_exists,
+    remove_container,
+    require_docker_running,
+)
+
+
+def test_build_run_command_basic():
+    cmd = build_run_command("my-image:latest")
+    assert cmd[:4] == ["docker", "run", "--rm", "-i"]
+    assert cmd[-1] == "my-image:latest"
+
+
+def test_build_run_command_with_args():
+    cmd = build_run_command("img", ["-e", "K=V", "-p", "8080:8080"])
+    assert "-e" in cmd and "K=V" in cmd
+    assert "-p" in cmd and "8080:8080" in cmd
+    assert cmd[-1] == "img"
+
+
+def test_generate_container_name():
+    assert generate_container_name("repo/name:tag") == "hud-repo-name-tag"
+    assert generate_container_name("a/b:c", prefix="x") == "x-a-b-c"
+
+
+@patch("subprocess.run")
+def test_image_exists_true(mock_run):
+    mock_run.return_value = MagicMock(returncode=0)
+    assert image_exists("any") is True
+
+
+@patch("subprocess.run")
+def test_image_exists_false(mock_run):
+    mock_run.return_value = MagicMock(returncode=1)
+    assert image_exists("any") is False
+
+
+@patch("subprocess.run")
+def test_get_docker_cmd_success(mock_run):
+    mock_run.return_value = MagicMock(
+        stdout='[{"Config": {"Cmd": ["python", "-m", "app"]}}]', returncode=0
+    )
+    assert get_docker_cmd("img") == ["python", "-m", "app"]
+
+
+@patch("subprocess.run")
+def test_get_docker_cmd_none(mock_run):
+    mock_run.return_value = MagicMock(stdout="[]", returncode=0)
+    assert get_docker_cmd("img") is None
+
+
+@patch("subprocess.run")
+def test_remove_container_ok(mock_run):
+    mock_run.return_value = MagicMock(returncode=0)
+    assert remove_container("x") is True
+
+
+@patch("shutil.which", return_value=None)
+def test_require_docker_running_no_cli(_which):
+    import typer
+
+    with pytest.raises(typer.Exit):
+        require_docker_running()
+
+
+@patch("shutil.which", return_value="docker")
+@patch("subprocess.run")
+def test_require_docker_running_ok(mock_run, _which):
+    mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+    require_docker_running()  # should not raise
+
+
+@patch("shutil.which", return_value="docker")
+@patch("subprocess.run")
+def test_require_docker_running_error_emits_hints(mock_run, _which):
+    import typer
+
+    mock_run.return_value = MagicMock(
+        returncode=1,
+        stdout="Cannot connect to the Docker daemon",
+        stderr="",
+    )
+    with pytest.raises(typer.Exit):
+        require_docker_running()

hud/cli/utils/tests/test_docker_hints.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import sys
+
+import pytest
+
+from hud.cli.utils import docker as mod
+
+pytestmark = pytest.mark.skipif(sys.platform == "win32", reason="Prefers Linux")
+
+
+def test_emit_docker_hints_windows(monkeypatch):
+    # Patch the global hud_console used by hint printing
+
+    fake = type(
+        "C",
+        (),
+        {
+            "error": lambda *a, **k: None,
+            "hint": lambda *a, **k: None,
+            "dim_info": lambda *a, **k: None,
+        },
+    )()
+    monkeypatch.setattr("hud.utils.hud_console.hud_console", fake, raising=False)
+    monkeypatch.setattr(mod.platform, "system", lambda: "Windows")
+    mod._emit_docker_hints("cannot connect to the docker daemon")
+
+
+def test_emit_docker_hints_linux(monkeypatch):
+    fake = type(
+        "C",
+        (),
+        {
+            "error": lambda *a, **k: None,
+            "hint": lambda *a, **k: None,
+            "dim_info": lambda *a, **k: None,
+        },
+    )()
+    monkeypatch.setattr("hud.utils.hud_console.hud_console", fake, raising=False)
+    monkeypatch.setattr(mod.platform, "system", lambda: "Linux")
+    mod._emit_docker_hints("Cannot connect to the Docker daemon")
+
+
+def test_emit_docker_hints_darwin(monkeypatch):
+    fake = type(
+        "C",
+        (),
+        {
+            "error": lambda *a, **k: None,
+            "hint": lambda *a, **k: None,
+            "dim_info": lambda *a, **k: None,
+        },
+    )()
+    monkeypatch.setattr("hud.utils.hud_console.hud_console", fake, raising=False)
+    monkeypatch.setattr(mod.platform, "system", lambda: "Darwin")
+    mod._emit_docker_hints("error during connect: is the docker daemon running")
+
+
+def test_emit_docker_hints_generic(monkeypatch):
+    fake = type(
+        "C",
+        (),
+        {
+            "error": lambda *a, **k: None,
+            "hint": lambda *a, **k: None,
+            "dim_info": lambda *a, **k: None,
+        },
+    )()
+    monkeypatch.setattr("hud.utils.hud_console.hud_console", fake, raising=False)
+    monkeypatch.setattr(mod.platform, "system", lambda: "Other")
+    mod._emit_docker_hints("some unrelated error")

hud/cli/utils/tests/test_env_check.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING
+from unittest.mock import patch
+
+from hud.cli.utils.env_check import (
+    _collect_source_diffs,
+    _parse_generated_at,
+    ensure_built,
+    find_environment_dir,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def test_parse_generated_at_variants():
+    ts = _parse_generated_at({"build": {"generatedAt": datetime.now(UTC).isoformat()}})
+    assert isinstance(ts, float)
+    assert _parse_generated_at({}) is None
+
+
+def test_collect_source_diffs_basic(tmp_path: Path):
+    env = tmp_path / "env"
+    env.mkdir()
+    # simulate files
+    (env / "Dockerfile").write_text("FROM python:3.11")
+    (env / "pyproject.toml").write_text("[tool.hud]")
+    (env / "a.txt").write_text("x")
+
+    # stored file list includes a non-existent file and old time
+    built_time = (datetime.now(UTC) - timedelta(days=1)).isoformat()
+    lock = {"build": {"sourceFiles": ["a.txt", "b.txt"], "generatedAt": built_time}}
+
+    # Patch list_source_files to return current env files
+    with patch("hud.cli.utils.env_check.list_source_files") as mock_list:
+        mock_list.return_value = [env / "a.txt", env / "Dockerfile"]
+        diffs = _collect_source_diffs(env, lock)
+    assert "Dockerfile" in diffs["added"]
+    assert "b.txt" in diffs["removed"]
+    assert "a.txt" in diffs["modified"] or "a.txt" in diffs["added"]
+
+
+def test_find_environment_dir_prefers_lock(tmp_path: Path):
+    # Create env as a sibling to tasks, so it will be in the candidates list
+    parent = tmp_path / "parent"
+    parent.mkdir()
+    tasks = parent / "tasks.json"
+    tasks.write_text("[]")
+    env = tmp_path / "env"
+    env.mkdir()
+    (env / "hud.lock.yaml").write_text("version: 1.0")
+    # Set cwd to env so it's in the candidate list
+    with patch("pathlib.Path.cwd", return_value=env):
+        found = find_environment_dir(tasks)
+    # Should find env because cwd returns env and it has hud.lock.yaml
+    assert found == env
+
+
+def test_ensure_built_no_lock_noninteractive(tmp_path: Path):
+    env = tmp_path / "e"
+    env.mkdir()
+    # Non-interactive: returns empty dict and does not raise
+    result = ensure_built(env, interactive=False)
+    assert result == {}
+
+
+def test_ensure_built_interactive_build(tmp_path: Path):
+    env = tmp_path / "e"
+    env.mkdir()
+    # Simulate interactive=False path avoids prompts
+    result = ensure_built(env, interactive=False)
+    assert result == {}

hud/cli/utils/tests/test_environment.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from unittest.mock import MagicMock, patch
+
+from hud.cli.utils.environment import get_image_name, image_exists, is_environment_directory
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def test_get_image_name_override():
+    name, source = get_image_name(".", image_override="custom:dev")
+    assert name == "custom:dev" and source == "override"
+
+
+def test_get_image_name_auto(tmp_path: Path):
+    env = tmp_path / "my_env"
+    env.mkdir()
+    # Provide Dockerfile and pyproject to pass directory check later if used
+    (env / "Dockerfile").write_text("FROM python:3.11")
+    (env / "pyproject.toml").write_text("[tool.hud]\nimage='x'")
+    name, source = get_image_name(env)
+    # Because pyproject exists with image key, source should be cache
+    assert source == "cache"
+    assert name == "x"
+
+
+def test_is_environment_directory(tmp_path: Path):
+    d = tmp_path / "env"
+    d.mkdir()
+    assert is_environment_directory(d) is False
+    (d / "Dockerfile").write_text("FROM python:3.11")
+    assert is_environment_directory(d) is False
+    (d / "pyproject.toml").write_text("[tool.hud]")
+    assert is_environment_directory(d) is True
+
+
+@patch("subprocess.run")
+def test_image_exists_true(mock_run):
+    mock_run.return_value = MagicMock(returncode=0)
+    assert image_exists("img") is True

hud/cli/utils/tests/test_interactive_module.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from hud.cli.utils.interactive import InteractiveMCPTester
+
+
+@pytest.mark.asyncio
+@patch("hud.cli.utils.interactive.MCPClient")
+async def test_connect_and_disconnect(MockClient):
+    client = AsyncMock()
+    client.initialize.return_value = None
+    client.list_tools.return_value = []
+    client.shutdown.return_value = None
+    MockClient.return_value = client
+
+    tester = InteractiveMCPTester("http://localhost:8765/mcp", verbose=False)
+    ok = await tester.connect()
+    assert ok is True
+    assert tester.tools == []
+    await tester.disconnect()
+
+
+def test_display_tools_handles_empty(capfd):
+    tester = InteractiveMCPTester("http://x")
+    tester.tools = []
+    tester.display_tools()  # prints warning
+
+
+@pytest.mark.asyncio
+@patch("hud.cli.utils.interactive.questionary")
+async def test_select_tool_quit(mock_questionary):
+    tester = InteractiveMCPTester("http://x")
+    tester.tools = [SimpleNamespace(name="a", description="")]
+    # Simulate ESC/quit
+    mock_questionary.select.return_value.unsafe_ask_async.return_value = "❌ Quit"
+    sel = await tester.select_tool()
+    assert sel is None
+
+
+@pytest.mark.asyncio
+@patch("hud.cli.utils.interactive.console")
+async def test_get_tool_arguments_no_schema(mock_console):
+    tester = InteractiveMCPTester("http://x")
+    args = await tester.get_tool_arguments(SimpleNamespace(name="t", inputSchema=None))
+    assert args == {}
+
+
+@pytest.mark.asyncio
+@patch("hud.cli.utils.interactive.console")
+async def test_call_tool_success(mock_console):
+    tester = InteractiveMCPTester("http://x")
+    fake_result = SimpleNamespace(isError=False, content=[SimpleNamespace(text="ok")])
+    tester.client = AsyncMock()
+    tester.client.call_tool.return_value = fake_result
+    await tester.call_tool(SimpleNamespace(name="t"), {"a": 1})
+    assert tester.client.call_tool.awaited

hud/cli/utils/tests/test_local_runner.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import sys
+from unittest import mock
+
+import pytest
+
+from hud.cli.utils.local_runner import run_local_server, run_with_reload
+
+pytestmark = pytest.mark.skipif(
+    sys.platform == "win32", reason="Prefers Linux (signal/stdio nuances)"
+)
+
+
+@mock.patch("subprocess.run")
+def test_run_local_server_no_reload_http(mock_run, monkeypatch):
+    mock_run.return_value = mock.Mock(returncode=0)
+    # Ensure sys.exit is raised with code 0
+    with pytest.raises(SystemExit) as exc:
+        run_local_server("server:app", transport="http", port=8765, verbose=True, reload=False)
+    assert exc.value.code == 0
+    # Verify the command contained port and no-banner
+    args = mock_run.call_args[0][0]
+    assert "--port" in args and "--no-banner" in args
+
+
+@mock.patch("hud.cli.utils.local_runner.run_with_reload")
+def test_run_local_server_reload_calls_reload(mock_reload):
+    run_local_server("server:app", transport="stdio", port=None, verbose=False, reload=True)
+    mock_reload.assert_called_once()
+
+
+@pytest.mark.asyncio
+async def test_run_with_reload_import_error(monkeypatch):
+    # Force ImportError for watchfiles
+    import builtins as _builtins
+
+    real_import = _builtins.__import__
+
+    def _imp(name, *args, **kwargs):
+        if name == "watchfiles":
+            raise ImportError("nope")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(_builtins, "__import__", _imp)
+
+    with pytest.raises(SystemExit) as exc:
+        # run_with_reload is async in this module; await it
+        await run_with_reload("server:app", transport="stdio", verbose=False)
+    assert exc.value.code == 1

hud/cli/utils/tests/test_logging_utils.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from hud.cli.utils.logging import CaptureLogger, analyze_error_for_hints, is_port_free
+
+
+def test_capture_logger_basic(capfd):
+    logger = CaptureLogger(print_output=True)
+    logger.success("done")
+    logger.error("oops")
+    logger.info("info")
+    out = logger.get_output()
+    assert "done" in out and "oops" in out and "info" in out
+
+
+def test_analyze_error_for_hints_matches():
+    hint = analyze_error_for_hints("ModuleNotFoundError: x")
+    assert hint and "dependencies" in hint
+
+
+def test_is_port_free_returns_bool():
+    # Probe a high port; we only assert the function returns a boolean
+    free = is_port_free(65500)
+    assert isinstance(free, bool)

hud/cli/utils/tests/test_metadata.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from hud.cli.utils.metadata import (
+    analyze_from_metadata,
+    check_local_cache,
+    fetch_lock_from_registry,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@patch("hud.cli.utils.metadata.settings")
+@patch("requests.get")
+def test_fetch_lock_from_registry_success(mock_get, mock_settings):
+    mock_settings.hud_telemetry_url = "https://api.example.com"
+    mock_settings.api_key = None
+    resp = MagicMock(status_code=200)
+    resp.json.return_value = {"lock": "image: img\n"}
+    mock_get.return_value = resp
+    lock = fetch_lock_from_registry("org/name:tag")
+    assert lock is not None and lock["image"] == "img"
+
+
+def test_check_local_cache_not_found(tmp_path: Path, monkeypatch):
+    # Point registry to empty dir
+    from hud.cli.utils import registry as reg
+
+    monkeypatch.setattr(reg, "get_registry_dir", lambda: tmp_path)
+    assert check_local_cache("org/name:tag") is None
+
+
+@pytest.mark.asyncio
+@patch("hud.cli.utils.metadata.console")
+@patch("hud.cli.utils.metadata.list_registry_entries")
+@patch("hud.cli.utils.metadata.load_from_registry")
+@patch("hud.cli.utils.metadata.extract_digest_from_image")
+async def test_analyze_from_metadata_local(mock_extract, mock_load, mock_list, mock_console):
+    mock_extract.return_value = "abcd"
+    mock_load.return_value = {"image": "img", "environment": {"toolCount": 0}}
+    mock_list.return_value = []
+    await analyze_from_metadata("img@sha256:abcd", "json", verbose=False)
+    # Should print JSON
+    assert mock_console.print_json.called