"""UTF-8 text I/O and EOL helpers (Windows dev → Linux deploy safe).

Use for config files (.env, .json, shell scripts) written on the Nexus host or
by the install wizard — never rely on platform-default encodings or CRLF from
the OS.
"""

from __future__ import annotations

from pathlib import Path
from typing import Literal

EolKind = Literal["LF", "CRLF", "CR"]


def normalize_text_eol(text: str) -> str:
    """Normalize any common EOL to LF for internal processing."""
    return text.replace("\r\n", "\n").replace("\r", "\n")


def detect_text_eol(text: str) -> EolKind:
    """Detect dominant line ending style (for API / editor round-trip)."""
    if "\r\n" in text:
        return "CRLF"
    if "\r" in text:
        return "CR"
    return "LF"


def read_utf8_text(path: Path) -> str:
    """Read UTF-8 text; strip BOM; do not alter EOL (for round-trip edits)."""
    return path.read_text(encoding="utf-8-sig")


def read_utf8_lf(path: Path) -> str:
    """Read UTF-8 and normalize line endings to LF."""
    return normalize_text_eol(read_utf8_text(path))


def write_utf8_lf(path: Path, content: str) -> None:
    """Write UTF-8 with LF newlines only (safe on Windows dev, required on Ubuntu)."""
    path.write_text(normalize_text_eol(content), encoding="utf-8", newline="\n")


def write_utf8_lf_lines(path: Path, lines: list[str]) -> None:
    """Write lines joined with LF (no trailing newline unless last line is empty)."""
    body = "\n".join(lines)
    if body and not body.endswith("\n"):
        write_utf8_lf(path, body + "\n")
    else:
        write_utf8_lf(path, body)
