@spec container_logs(String.t(), Req.Request.t(), keyword()) ::
  {:ok, map()} | {:ok, reference() | pid()} | {:error, term()}

Fetches container logs.

@spec exec(String.t(), [String.t()], Req.Request.t()) ::
  {:ok, String.t()} | {:error, term()}

Executes a command inside a container.

@spec inspect_container(String.t(), Req.Request.t()) ::
  {:ok, TestcontainerEx.Container.Config.t()} | {:error, term()}

Inspects a container by ID.

@spec monitor_container(
  String.t(),
  (TestcontainerEx.Container.Config.t() -> {:ok, term()} | {:error, term()}),
  Req.Request.t(),
  keyword()
) :: {:ok, term()} | {:error, term()}

Monitors a container until a predicate succeeds or the timeout elapses.

@spec start_container(struct(), Req.Request.t(), map()) ::
  {:ok, TestcontainerEx.Container.Config.t()} | {:error, term()}

Creates and starts a container, applying wait strategies.

Steps:

1. Build config with labels (via BuilderHelper)
2. Check for reusable container or create new one
3. Pull image if needed
4. Copy files into container
5. Start container
6. Apply wait strategies
7. Call after_start hook

@spec start_containers([struct()], Req.Request.t(), map()) ::
  {:ok, [TestcontainerEx.Container.Config.t()]} | {:error, [term()]}

Creates and starts multiple containers.

Returns {:ok, containers} when every container starts. If one or more containers fail, returns {:error, results} where results keeps the input order and contains either {:ok, container} or {:error, reason}.

@spec stop_container(String.t(), Req.Request.t()) :: :ok | {:error, term()}

Stops a container by ID.

@spec stop_containers([String.t()], Req.Request.t()) ::
  {:ok, [term()]} | {:error, [term()]}

Stops multiple containers.