"""Import-path helpers for the web API entrypoint."""

from __future__ import annotations

import sys
from pathlib import Path


def ensure_project_root_on_sys_path(
    current_file: str | Path,
    path_entries: list[str] | None = None,
) -> Path:
    """Ensure the repository root is available on ``sys.path`` for imports."""
    if path_entries is None:
        path_entries = sys.path

    project_root = Path(current_file).resolve().parents[2]
    project_root_str = str(project_root)

    if project_root_str not in path_entries:
        path_entries.insert(0, project_root_str)

    return project_root


__all__ = ["ensure_project_root_on_sys_path"]