defmodule Orchid do
  @moduledoc """
  The core entry point for the Orchid workflow engine.

  This module provides the primary interface (`run/3`) to execute defined Recipes.
  It is designed to be a flexible and extensible framework for task orchestration.
  """
  alias Orchid.{Recipe, Step, Pipeline, Scheduler, WorkflowCtx}
  alias Orchid.Operon.{Request, Response, Execute}

  @allow_config_keys [
    :return_response,
    :operons_stack,
    :global_hooks_stack,
    :executor_and_opts,
    :core_hook
  ]

  @doc """
  Executes a workflow Recipe.

  It initializes the pipeline, injects any configured middleware (Operons), and
  starts the execution process.

  ### Options

  * `:return_response` - (boolean) If `true`, returns the full `Orchid.Operon.Response` struct
    (which includes assigns and metadata) instead of just the result payload. Defaults to `false`.
  * `:operons_stack` - (list) A list of additional middleware modules (Recipe-level hooks)
    to run before the execution phase. They are executed in the order provided.
  * `:global_hooks_stack` - (list)
  * `:executor_and_opts` - (tuple) Executor module and its options.
  * `:core_hook` - (module) A Module for execute step.
  * `:baggage` - (enumerable) Custom options used by user/custome operons/hooks/etc.

  ### Examples

      # Normal execution returning {:ok, results}
      Orchid.run(my_recipe, initial_params)

      # Execution returning the full Response struct
      Orchid.run(my_recipe, initial_params, return_response: true)
  """
  @spec run(Recipe.t() | [Step.t()], Scheduler.initial_params(), keyword()) ::
          Response.payload() | Response.t()
  def run(recipe_or_steps, input_params, opts \\ []) do
    initial_config = Keyword.filter(opts, fn {k, _v} -> k in @allow_config_keys end)

    ctx =
      WorkflowCtx.new()
      |> WorkflowCtx.merge_config(initial_config)
      |> WorkflowCtx.merge_baggage(Keyword.get(opts, :baggage, []))

    run_with_ctx(recipe_or_steps, input_params, ctx)
  end

  @doc "Run with explicit WorkflowContext struct."
  @spec run_with_ctx(Recipe.t() | [Step.t()], Scheduler.initial_params(), WorkflowCtx.t()) ::
          Response.payload() | Response.t()
  def run_with_ctx(steps, input_params, workflow_ctx) when is_list(steps) do
    run_with_ctx(Recipe.new(steps), input_params, workflow_ctx)
  end
  def run_with_ctx(recipe, input_params, workflow_ctx) do
    response? = WorkflowCtx.get_config(workflow_ctx, :return_response, false)
    operons_stack = WorkflowCtx.get_config(workflow_ctx, :operons_stack, [])

    initial_request = %Request{
      recipe: recipe,
      initial_params: input_params,
      workflow_ctx: workflow_ctx
    }

    response = Pipeline.run(operons_stack ++ [Execute], initial_request)

    if response?, do: response, else: response.payload
  end
end