defmodule Omni.Tools.Bash.Runner do
  @moduledoc """
  Executes shell commands via a Port and returns captured output.

  Each invocation spawns a new shell process, captures merged stdout/stderr,
  and returns the output alongside the exit code. No state carries over
  between calls.

      Runner.run("echo hello", {"/bin/bash", ["-c"]}, dir: "/tmp")
      #=> {:ok, %{output: "hello\\n", exit_code: 0}}

      Runner.run("exit 1", {"/bin/bash", ["-c"]}, dir: "/tmp")
      #=> {:error, :nonzero, %{output: "", exit_code: 1}}

  The runner executes arbitrary shell commands with full system access. It is
  not a security boundary — OS-level sandboxing (containers, restricted users)
  is the caller's responsibility.

  ## Options

    * `:dir` (required) — working directory for the command
    * `:env` — extra environment variables as `[{String.t(), String.t()}]`,
      merged additively with the inherited environment. Default `[]`
    * `:timeout` — execution timeout in milliseconds. Default `30_000`
    * `:max_output` — output truncation limit in bytes. Tail-biased, snapped
      to line boundaries. Default `50_000`
    * `:command_prefix` — string prepended to every command. Default `nil`

  ## Return values

      {:ok, %{output: "hello\\n", exit_code: 0}}
      {:error, :nonzero, %{output: "error msg\\n", exit_code: 1}}
      {:error, :timeout, %{output: "partial..."}}

  On success, `exit_code` is always `0`. On a non-zero exit, the output
  captured up to that point is included. On timeout, partial output
  collected before the deadline is returned.
  """

  @default_timeout 30_000
  @default_max_output 50_000

  @typedoc "Result of a command execution — success, non-zero exit, or timeout."
  @type result ::
          {:ok, %{output: String.t(), exit_code: 0}}
          | {:error, :nonzero, %{output: String.t(), exit_code: pos_integer()}}
          | {:error, :timeout, %{output: String.t()}}

  @doc """
  Executes `command` in the given `shell` and returns captured output.

  The `shell` argument is a `{executable, args}` tuple — the command string
  is appended to `args` when spawning the port.
  """
  @spec run(String.t(), {String.t(), [String.t()]}, keyword()) :: result()
  def run(command, {shell_exe, shell_args}, opts \\ []) do
    dir = Keyword.fetch!(opts, :dir)
    env = opts |> Keyword.get(:env, []) |> to_port_env()
    timeout = Keyword.get(opts, :timeout, @default_timeout)
    max_output = Keyword.get(opts, :max_output, @default_max_output)
    prefix = Keyword.get(opts, :command_prefix)

    full_command = build_command(command, prefix)

    port =
      Port.open({:spawn_executable, shell_exe}, [
        :binary,
        :exit_status,
        :stderr_to_stdout,
        {:args, shell_args ++ [full_command]},
        {:cd, dir},
        {:env, env}
      ])

    deadline = System.monotonic_time(:millisecond) + timeout

    case collect(port, deadline, []) do
      {:ok, output, exit_code} ->
        output = truncate_tail(output, max_output)

        if exit_code == 0 do
          {:ok, %{output: output, exit_code: 0}}
        else
          {:error, :nonzero, %{output: output, exit_code: exit_code}}
        end

      {:timeout, acc} ->
        close_port(port)
        remaining = drain_port(port, [])
        all = Enum.reverse(acc) ++ remaining
        output = IO.iodata_to_binary(all)
        output = truncate_tail(output, max_output)
        {:error, :timeout, %{output: output}}
    end
  end

  @doc """
  Resolves the shell to use for command execution.

  Checks in order: explicit `:shell` option, `/bin/bash`, `/bin/sh`.
  Returns a `{executable, args}` tuple suitable for `Port.open/2`.

  Raises `ArgumentError` if no usable shell is found or the option is invalid.

      Runner.resolve_shell([])
      #=> {"/bin/bash", ["-c"]}

      Runner.resolve_shell(shell: {"/bin/zsh", ["-c"]})
      #=> {"/bin/zsh", ["-c"]}
  """
  @spec resolve_shell(keyword()) :: {String.t(), [String.t()]}
  def resolve_shell(opts) do
    case Keyword.get(opts, :shell) do
      {exe, args} when is_binary(exe) and is_list(args) ->
        {exe, args}

      nil ->
        cond do
          File.exists?("/bin/bash") -> {"/bin/bash", ["-c"]}
          File.exists?("/bin/sh") -> {"/bin/sh", ["-c"]}
          true -> raise ArgumentError, "no shell found: /bin/bash and /bin/sh both missing"
        end

      other ->
        raise ArgumentError,
              "invalid :shell option: expected {executable, args} tuple, got: #{inspect(other)}"
    end
  end

  # ── Port communication ───────────────────────────────────────────

  defp collect(port, deadline, acc) do
    remaining = max(deadline - System.monotonic_time(:millisecond), 0)

    receive do
      {^port, {:data, chunk}} ->
        collect(port, deadline, [chunk | acc])

      {^port, {:exit_status, code}} ->
        output = acc |> Enum.reverse() |> IO.iodata_to_binary()
        {:ok, output, code}
    after
      remaining ->
        {:timeout, acc}
    end
  end

  defp drain_port(port, acc) do
    receive do
      {^port, {:data, chunk}} -> drain_port(port, [chunk | acc])
      {^port, {:exit_status, _}} -> acc |> Enum.reverse()
    after
      0 -> acc |> Enum.reverse()
    end
  end

  defp close_port(port) do
    Port.close(port)
  catch
    :error, :badarg -> :ok
  end

  # ── Command building ─────────────────────────────────────────────

  defp build_command(command, nil), do: command
  defp build_command(command, prefix), do: prefix <> "\n" <> command

  defp to_port_env(env) do
    Enum.map(env, fn {k, v} -> {String.to_charlist(k), String.to_charlist(v)} end)
  end

  # ── Output truncation ───────────────────────────────────────────

  defp truncate_tail(output, :infinity), do: output
  defp truncate_tail(output, max) when byte_size(output) <= max, do: output

  defp truncate_tail(output, max) do
    total = byte_size(output)
    skip = total - max
    tail = binary_part(output, skip, max)

    snapped =
      case :binary.match(tail, "\n") do
        {pos, 1} -> binary_part(tail, pos + 1, byte_size(tail) - pos - 1)
        :nomatch -> tail
      end

    "...(truncated, showing last #{format_bytes(byte_size(snapped))} of #{format_bytes(total)})\n#{snapped}"
  end

  defp format_bytes(bytes) when bytes < 1_024, do: "#{bytes}B"

  defp format_bytes(bytes) when bytes < 1_048_576 do
    kb = Float.round(bytes / 1_024, 1)
    "#{kb}KB"
  end

  defp format_bytes(bytes) do
    mb = Float.round(bytes / 1_048_576, 1)
    "#{mb}MB"
  end
end