@spec build_env(Path.t()) :: [{binary(), binary()}]

Returns the environment for running mix release / mix escript.build during the batamanta build phase.

Why not erts_env/1?

System.cmd with the env: option uses Port.open underneath, which replaces the child process environment entirely with the given list — it does not merge. erts_env/1 starts from base_environment/0, a whitelist of only 7 variables (HOME, USER, LANG, …). That strips elixir, mix, MIX_HOME, HEX_HOME, MIX_REBAR3, etc., making mix release fail with "elixir: No such file or directory".

What this function does

Starts from the full current process environment (System.get_env()), then applies surgical overrides:

1. Prepends the downloaded ERTS bin/ to PATH so erlexec / erl from the bundled ERTS win over any asdf/mise/kerl shim.
2. Sets ROOTDIR, BINDIR, ERL_ROOTDIR to the bundled ERTS so OTP locates its own libs from the right place.
3. Clears ERL_FLAGS, ERL_AFLAGS, ERL_ZFLAGS so no stale shell flags bleed into the compilation BEAM.
4. Clears ASDF_ERLANG_VERSION and MISE_ERLANG_VERSION so that even if asdf/mise shims are still on PATH (needed for elixir/mix), they forward erl calls to whichever erl is first on PATH — which is our bundled one.

elixir, mix, MIX_HOME, HEX_HOME, hex cache, rebar, and every other build tool remain accessible because the full env is inherited.

@spec clean_env() :: %{optional(binary()) => binary() | nil}

Returns a clean environment map that excludes asdf/mise/kerl paths.

This function:

• Preserves essential system variables (HOME, USER, etc.)
• Removes asdf/mise/kerl from PATH
• Returns a map suitable for System.cmd/3

@spec clean_env_map() :: %{optional(binary()) => binary() | nil}

Returns a clean environment as a map.

@spec clean_env_tuples() :: [{binary(), binary() | nil}]

Returns a clean environment as a list of tuples for System.cmd/3.

@spec erts_env(Path.t(), boolean()) :: [{binary(), binary() | nil}]

Returns a clean environment that uses the specified ERTS bin directory.

This is the PREFERRED method for batamanta builds - it ensures the build uses exactly the same ERTS version that will be embedded in the final binary.

Parameters

• erts_path: Path to the cached ERTS directory
• include_mix: If true, also tries to find mix in the ERTS path

Returns

Environment list tuples with:

• PATH prepended with ERTS bin
• ERL_AFLAGS set for proper startup
• All version manager paths removed

@spec system_elixir_path() :: binary() | nil

Returns the path to system Elixir executable, ignoring version managers.

@spec system_erlang_path() :: binary() | nil

Returns the path to system Erlang executable, ignoring version managers.

@spec system_mix_path() :: binary() | nil

Returns the path to system mix executable, ignoring version managers.