Initial commit

src/main/scala/summer/compass/Compass.scala

@@ -0,0 +1,49 @@
+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