defmodule Argos do
  @moduledoc """
  Núcleo de Argos. Expone tres bloques funcionales:

  - Command: ejecución de comandos del sistema con resultados estructurados
  - Parallel: orquestación de workers concurrentes con agregación de estado
  - Log: capa de conveniencia sobre `Logger` con backend de Aurora

  Ejemplos rápidos:

      iex> result = Argos.exec("echo hi")
      iex> result.success?
      true

      iex> specs = [Argos.Parallel.create_worker_spec(:w1, [fn -> :ok end])]
      iex> Argos.start_workers(specs)
  """
  require Logger

  alias Argos.Command
  alias Argos.Parallel

  @doc """
  Saludo de comprobación.

  ## Examples

      iex> Argos.hello()
      "Hello, Argos!"
  """
  def hello do
    "Hello, Argos!"
  end

  @spec exec(String.t() | [String.t()], keyword) :: Argos.CommandResult.t()
  defdelegate exec(command, opts \\ []), to: Command
  @spec exec_raw(String.t() | [String.t()], keyword) :: {binary, non_neg_integer}
  defdelegate exec_raw(command, opts \\ []), to: Command
  @spec exec_silent(String.t() | [String.t()], keyword) :: non_neg_integer
  defdelegate exec_silent(command, opts \\ []), to: Command
  @spec exec_interactive(String.t(), keyword) :: Argos.CommandResult.t()
  defdelegate exec_interactive(command, opts \\ []), to: Command
  @spec exec_sudo(String.t(), keyword) :: Argos.CommandResult.t()
  defdelegate exec_sudo(command, opts \\ []), to: Command
  @spec kill_process(String.t()) :: Argos.CommandResult.t()
  defdelegate kill_process(process_name), to: Command
  @spec kill_processes_by_name([String.t()]) :: [{String.t(), :killed | :not_found | {:error, term}}]
  defdelegate kill_processes_by_name(process_names), to: Command

  @spec start_workers([map | {any, [function]}]) :: list
  defdelegate start_workers(worker_specs), to: Parallel
  @spec subscribe() :: :ok
  defdelegate subscribe, to: Parallel
  @spec unsubscribe() :: :ok
  defdelegate unsubscribe, to: Parallel
  @spec get_state() :: map
  defdelegate get_state, to: Parallel
  @spec stop() :: :ok
  defdelegate stop, to: Parallel

  @doc """
  Función de conveniencia para logging.
  """
  @spec log(Logger.level(), String.t(), keyword) :: :ok
  def log(level, message, metadata \\ []) do
    Logger.log(level, message, metadata)
  end
end