@spec detect_host() :: {:ok, erts_target()} | {:error, String.t()}

Detects the host platform and returns the matching ERTS target.

Delegates to Batamanta.ERTS.Fetcher.detect_host_target/0.

iex> Batamanta.Target.detect_host()
{:ok, :ubuntu_22_04_x86_64}

@spec detect_libc() :: :gnu | :musl | :unknown

Detects the libc type of the current Linux system.

Delegates to Batamanta.ERTS.LibcDetector.detect/0.

iex> Batamanta.Target.detect_libc()
:gnu

iex> Batamanta.Target.detect_libc()
:musl

@spec erts_target_to_binary_suffix(erts_target()) :: String.t()

Gets the OS string for binary naming (e.g., "x86_64-linux").

@spec erts_target_to_display(erts_target()) :: String.t()

Converts an ERTS target atom to a user-friendly binary name.

iex> Batamanta.Target.erts_target_to_display(:ubuntu_22_04_x86_64)
"Linux x86_64 (glibc)"

@spec erts_target_to_rust(erts_target()) :: rust_target()

Converts an ERTS target atom to a Rust target triple.

iex> Batamanta.Target.erts_target_to_rust(:ubuntu_22_04_x86_64)
"x86_64-unknown-linux-gnu"

iex> Batamanta.Target.erts_target_to_rust(:alpine_3_19_x86_64)
"x86_64-unknown-linux-musl"

@spec from_legacy(String.t() | :auto, String.t() | :auto) :: erts_target()

Legacy compatibility: converts old target_os/target_arch to new erts_target.

iex> Batamanta.Target.from_legacy("linux", "x86_64")
:ubuntu_22_04_x86_64

@spec get_target_info(erts_target()) :: map() | nil

Gets the target info map for a given target atom.

iex> Batamanta.Target.get_target_info(:ubuntu_22_04_x86_64)
%{os: "linux", arch: "x86_64", libc: "gnu", ...}

@spec resolve(erts_target()) :: {:ok, target_info()} | {:error, String.t()}

Resolves an ERTS target atom to comprehensive target information.

• erts_target - Target atom (e.g., :ubuntu_22_04_x86_64)

{:ok, target_info_map} or {:error, reason}

iex> Batamanta.Target.resolve(:ubuntu_22_04_x86_64)
{:ok, %{os: "linux", arch: "x86_64", libc: "gnu", ...}}

@spec resolve_auto(atom() | String.t() | nil, map()) ::
  {:ok, erts_target()} | {:error, String.t()}

Resolves :auto or string/atom target to a concrete ERTS target atom.

• target - :auto, atom, or string
• config - Optional config map with :force_os, :force_arch, :force_libc

{:ok, erts_target_atom} or {:error, reason}

iex> Batamanta.Target.resolve_auto(:auto, %{})
{:ok, :ubuntu_22_04_x86_64}

iex> Batamanta.Target.resolve_auto(:alpine_3_19_x86_64, %{})
{:ok, :alpine_3_19_x86_64}

@spec valid_targets() :: [atom()]

Lists all valid ERTS target atoms.

@spec validate_libc!(erts_target()) :: :ok

Validates that the detected libc matches an expected target.

Shows a warning if there's a mismatch but doesn't fail.

iex> Batamanta.Target.validate_libc!(:ubuntu_22_04_x86_64)
:ok