package summer.compass

import machinespir.it.jig.ConfigReader
import java.nio.file.Path

/**
 * Public API for configuration management.
 *
 * Compass is the CMS orchestration layer on top of Jig (HOCON parsing).
 * It handles file discovery, environment layering, plugin namespacing,
 * and runtime overrides — similar to Laravel's Illuminate\Config.
 */
trait Compass:

  // --- String-path access (dot-notation, dynamic) ---

  def getString(key: String, default: String = ""): String
  def getInt(key: String, default: Int = 0): Int
  def getBoolean(key: String, default: Boolean = false): Boolean
  def getOption(key: String): Option[String]
  def has(key: String): Boolean

  // --- Typed access via Jig ConfigReader ---

  /** Load a config section into a typed case class. */
  def load[T: ConfigReader](section: String): Either[String, T]

  // --- Plugin config registration ---

  /** Register a plugin namespace with its config directory path. */
  def addNamespace(namespace: String, path: Path): Unit

  // --- Runtime overrides ---

  /** Set a runtime config override (highest priority, in-memory). */
  def set(key: String, value: String): Unit

  /** Persist runtime overrides to config/env/{env}/overrides.conf. */
  def persist(): Either[String, Unit]

  // --- Environment ---

  def environment: String
  def configPath: Path

  // --- Lifecycle ---

  /** Reload all config from disk, clearing caches and runtime overrides. */
  def reload(): Unit