import os
import re

_TEMPLATE_PATTERN = re.compile(r"\$\{([^}:]+)(?::-(.*))?\}")


def resolve_env_vars(env_dict: dict[str, str]) -> dict[str, str]:
    """
    Resolve environment variable templates in a dictionary.

    Templates like "${VAR_NAME}" are replaced with values from os.environ.
    Use "${VAR_NAME:-default}" to provide a default when the variable is unset.
    Literal values are passed through unchanged.

    Args:
        env_dict: Dictionary with potentially templated values

    Returns:
        Dictionary with resolved values

    Raises:
        ValueError: If a required environment variable is not found and no default
    """
    resolved = {}

    for key, value in env_dict.items():
        match = _TEMPLATE_PATTERN.fullmatch(value)
        if match:
            var_name = match.group(1)
            default = match.group(2)
            if var_name in os.environ:
                resolved[key] = os.environ[var_name]
            elif default is not None:
                resolved[key] = default
            else:
                raise ValueError(
                    f"Environment variable '{var_name}' not found in host environment"
                )
        else:
            # Literal value
            resolved[key] = value

    return resolved


def get_required_host_vars(
    env_dict: dict[str, str],
) -> list[tuple[str, str | None]]:
    """Extract host environment variable names referenced by templates.

    Returns a list of (var_name, default_or_None) for each ``${VAR}`` or
    ``${VAR:-default}`` entry.  Literal values are excluded.

    Args:
        env_dict: Dictionary with potentially templated values

    Returns:
        List of (var_name, default_value_or_None) tuples
    """
    result: list[tuple[str, str | None]] = []

    for value in env_dict.values():
        match = _TEMPLATE_PATTERN.fullmatch(value)
        if match:
            var_name = match.group(1)
            default = match.group(2)  # None when no :- clause
            result.append((var_name, default))

    return result
