defmodule Planck.Agent.Team do
  @moduledoc """
  A named collection of agents that share a `team_id` and can address each
  other via the inter-agent tools.

  Teams can be hydrated from a directory on disk (static) or constructed
  in-memory by an orchestrator using `spawn_agent` (dynamic). Both paths
  produce the same struct.

  ## Directory layout

      .planck/teams/
        elixir-dev-workflow/
          TEAM.json                  # required — member list and metadata
          members/
            orchestrator.md          # system prompt for the orchestrator
            planner.md
            builder.md

  Each member's system prompt lives in `members/<name>.md` by convention, where
  `<name>` is the member's `name` (which defaults to `type` when not set).

  ## TEAM.json format

      {
        "name":        "elixir-dev-workflow",
        "description": "Plan, build, and test Elixir changes.",
        "members": [
          {
            "type":          "orchestrator",
            "provider":      "anthropic",
            "model_id":      "claude-sonnet-4-6",
            "system_prompt": "members/orchestrator.md"
          },
          {
            "type":          "builder",
            "provider":      "anthropic",
            "model_id":      "claude-sonnet-4-6",
            "system_prompt": "members/builder.md",
            "tools":         ["read", "write", "edit", "bash"],
            "skills":        ["refactor"]
          }
        ]
      }

  Member entries follow the schema documented on `Planck.Agent.AgentSpec`.
  Exactly one member must have `"type": "orchestrator"`; the rest are workers.
  All `system_prompt` file paths are resolved relative to the team directory.

  Tools and skills are global (loaded by `planck_headless` from
  `~/.planck/tools` and `~/.planck/skills`). Each member declares which of
  them it should see via the `"tools"` and `"skills"` arrays; names are
  resolved against the global pool at agent-start time.
  """

  require Logger

  alias Planck.Agent.AgentSpec

  @team_file "TEAM.json"
  @orchestrator_type "orchestrator"

  @typedoc """
  A team definition.

  - `:id` — team_id generated at materialization; `nil` before `start_session`.
  - `:alias` — folder name for static teams; `nil` for dynamic teams.
  - `:source` — `:filesystem` or `:dynamic`.
  - `:name` — informational label from TEAM.json.
  - `:description` — one-line purpose shown in team listings.
  - `:dir` — absolute path to the team directory, `nil` for dynamic teams.
  - `:members` — agent specs; exactly one has `type: "orchestrator"`.
  """
  @type t :: %__MODULE__{
          id: String.t() | nil,
          alias: String.t() | nil,
          source: :filesystem | :dynamic,
          name: String.t() | nil,
          description: String.t() | nil,
          dir: Path.t() | nil,
          members: [AgentSpec.t()]
        }

  @enforce_keys [:source, :members]
  defstruct id: nil,
            alias: nil,
            source: :filesystem,
            name: nil,
            description: nil,
            dir: nil,
            members: []

  @doc """
  Load a team from a directory containing a `TEAM.json` file.

  Resolves member `system_prompt` paths relative to the team directory.

  Returns `{:ok, team}` or `{:error, reason}`.
  """
  @spec load(Path.t()) :: {:ok, t()} | {:error, String.t()}
  def load(dir) do
    expanded = Path.expand(dir)
    team_file = Path.join(expanded, @team_file)

    with :ok <- ensure_dir(expanded),
         {:ok, content} <- read_team_file(team_file),
         {:ok, data} <- decode_json(content, team_file),
         {:ok, members_data, name, description} <- parse_team(data, team_file),
         {:ok, members} <- parse_members(members_data, expanded),
         :ok <- validate_members(members, team_file) do
      {:ok,
       %__MODULE__{
         alias: Path.basename(expanded),
         source: :filesystem,
         name: name,
         description: description,
         dir: expanded,
         members: members
       }}
    end
  end

  @doc """
  Build a dynamic team from a single orchestrator spec.

  Dynamic teams have no filesystem footprint. Workers may be added later via
  the orchestrator's `spawn_agent` tool. Used both when `start_session/1`
  runs with no `template:` (team of one) and when the orchestrator grows
  the team at runtime.
  """
  @spec dynamic(AgentSpec.t()) :: t()
  def dynamic(%AgentSpec{type: @orchestrator_type} = orchestrator) do
    %__MODULE__{source: :dynamic, members: [orchestrator]}
  end

  # ---------------------------------------------------------------------------
  # Private
  # ---------------------------------------------------------------------------

  @spec ensure_dir(Path.t()) :: :ok | {:error, String.t()}
  defp ensure_dir(dir) do
    if File.dir?(dir), do: :ok, else: {:error, "team directory not found: #{dir}"}
  end

  @spec read_team_file(Path.t()) :: {:ok, String.t()} | {:error, String.t()}
  defp read_team_file(path) do
    case File.read(path) do
      {:ok, content} -> {:ok, content}
      {:error, reason} -> {:error, "cannot read #{path}: #{:file.format_error(reason)}"}
    end
  end

  @spec decode_json(String.t(), Path.t()) :: {:ok, term()} | {:error, String.t()}
  defp decode_json(content, path) do
    case Jason.decode(content) do
      {:ok, data} ->
        {:ok, data}

      {:error, %Jason.DecodeError{} = e} ->
        {:error, "invalid JSON in #{path}: #{Exception.message(e)}"}
    end
  end

  @spec parse_team(term(), Path.t()) ::
          {:ok, [map()], String.t() | nil, String.t() | nil} | {:error, String.t()}
  defp parse_team(%{"members" => members} = data, _path)
       when is_list(members) and members != [] do
    {:ok, members, string_or_nil(data["name"]), string_or_nil(data["description"])}
  end

  defp parse_team(%{"members" => []}, path),
    do: {:error, "#{path}: members must not be empty"}

  defp parse_team(%{"members" => _}, path),
    do: {:error, "#{path}: members must be an array"}

  defp parse_team(_, path),
    do: {:error, "#{path}: missing required field 'members'"}

  @spec string_or_nil(term()) :: String.t() | nil
  defp string_or_nil(v) when is_binary(v) and v != "", do: v
  defp string_or_nil(_), do: nil

  @spec parse_members([map()], Path.t()) :: {:ok, [AgentSpec.t()]} | {:error, String.t()}
  defp parse_members(entries, base_dir) do
    case AgentSpec.from_list(entries, base_dir: base_dir) do
      [] -> {:error, "no valid members in TEAM.json at #{base_dir}"}
      specs -> {:ok, specs}
    end
  end

  @spec validate_members([AgentSpec.t()], Path.t()) :: :ok | {:error, String.t()}
  defp validate_members(members, path) do
    with :ok <- validate_single_orchestrator(members, path) do
      validate_unique_names(members, path)
    end
  end

  @spec validate_single_orchestrator([AgentSpec.t()], Path.t()) :: :ok | {:error, String.t()}
  defp validate_single_orchestrator(members, path) do
    case Enum.count(members, &(&1.type == @orchestrator_type)) do
      1 ->
        :ok

      0 ->
        {:error, "#{path}: team must have exactly one member with type \"orchestrator\""}

      n ->
        {:error, "#{path}: team must have exactly one orchestrator, found #{n}"}
    end
  end

  @spec validate_unique_names([AgentSpec.t()], Path.t()) :: :ok | {:error, String.t()}
  defp validate_unique_names(members, path) do
    names = Enum.map(members, & &1.name)
    duplicates = names -- Enum.uniq(names)

    case duplicates do
      [] ->
        :ok

      [dup | _] ->
        {:error,
         "#{path}: duplicate member name #{inspect(dup)} " <>
           "(names default to type; give explicit names to disambiguate same-type members)"}
    end
  end
end