package configuration import ( "fmt" "log/slog" "os" "path/filepath" "sort" "github.com/samcharles93/archie-core/internal/config" ) // Document is the decoded external configuration together with a record of // where it came from. type Document struct { // Config is the translated settings. // // TEMPORARY. docs/architecture/configuration.md requires this to become // typed per-domain sections that never expose a whole-application model. // It stays for now so this package can own loading without every // consumer changing at once. Delete when internal/config is dissolved. Config config.Config // Scheduling is the decoded [scheduling] input. Application composition // translates it into domain-owned scheduling.EngineConfig. Scheduling SchedulingInput // Provenance lists the files that produced Config, in precedence order. Provenance Provenance // UnknownKeys lists dotted TOML key paths present in a loaded file that // no decode target consumed (e.g. "containers.max_concurrancy" for a // misspelled max_concurrency) -- present so a typo'd key is visible // instead of silently parsing, validating and doing nothing. Sorted // and de-duplicated. A missing key that a YAML config source carries // is not yet detected here (plan-config-drift.md step 1 note); this // is TOML-only for now. UnknownKeys []string } // Loader reads configuration from files. The zero value is not usable; call // [New]. type Loader struct { log *slog.Logger // dataHomeFn resolves the base directory for derived paths. Injected so // tests can exercise defaulting without depending on the environment -- // the previous package-level dataHome() read XDG_DATA_HOME directly and // discarded the error from os.UserHomeDir. dataHomeFn func() string } // New returns a Loader. A nil logger discards output. func New(log *slog.Logger) *Loader { if log == nil { log = slog.New(slog.DiscardHandler) } return &Loader{log: log, dataHomeFn: xdgDataHome} } // dataHome resolves the base directory for derived paths. func (l *Loader) dataHome() string { if l.dataHomeFn == nil { return xdgDataHome() } return l.dataHomeFn() } // xdgDataHome returns $XDG_DATA_HOME, falling back to ~/.local/share, and // finally to a relative path when the home directory is unknowable. func xdgDataHome() string { if dir := os.Getenv("XDG_DATA_HOME"); dir != "" { return dir } home, err := os.UserHomeDir() if err != nil { return filepath.Join(".local", "share") } return filepath.Join(home, ".local", "share") } // File loads a single configuration file. TOML remains supported for existing // deployments; YAML files use the same defaults and validation path. func (l *Loader) File(path string) (*Document, error) { return l.Resolve(path, "") } // Resolve selects the configuration source from its filesystem type: a TOML // or YAML file, or a feature-config directory. This is the production entry // point. Keeping selection here ensures command-line loading and operator // tooling share the exact same precedence and validation rules. func (l *Loader) Resolve(basePath, overlayPath string) (*Document, error) { info, err := os.Stat(basePath) if err != nil { return nil, fmt.Errorf("%w: config source %s: %w", ErrUnreadable, basePath, err) } if err := validateOverlayPath(overlayPath, basePath, info.IsDir()); err != nil { return nil, err } if info.IsDir() { return l.Dir(basePath, overlayPath) } return l.overlayFile(basePath, overlayPath) } // validateOverlayPath checks that overlayPath, when non-empty, exists and has // the same filesystem kind as basePath: a directory overlay for a directory // source and a file overlay for a file source. func validateOverlayPath(overlayPath, basePath string, baseIsDir bool) error { if overlayPath == "" { return nil } overlayInfo, err := os.Stat(overlayPath) if err != nil { return fmt.Errorf("%w: config overlay %s: %w", ErrUnreadable, overlayPath, err) } if overlayInfo.IsDir() != baseIsDir { if baseIsDir { return fmt.Errorf("config overlay %s must be a directory when config source %s is a directory", overlayPath, basePath) } return fmt.Errorf("config overlay %s must be a file when config source %s is a file", overlayPath, basePath) } return nil } // Overlay loads basePath, then decodes overlayPath into the same value so // only the fields the overlay sets are replaced -- every field it omits keeps // the base value. This lets a deployment-specific file (config.docker.toml) // declare only what differs instead of restating the whole schema. An empty // overlayPath is equivalent to [Loader.File]. func (l *Loader) Overlay(basePath, overlayPath string) (*Document, error) { return l.overlayFile(basePath, overlayPath) } // ApplyOverlay decodes the runtime config overlay (a nested map of // dotted-path values from the overlay store) into a copy of doc with the // same field-level precedence as a file overlay, records the overlay // origin, then applies defaults and validates. It is used at boot and on // reload to layer dashboard-edited overrides over the file config. // // ApplyOverlay never mutates its input: the returned Document owns fresh // copies of the Config and the provenance chain, so a decode or // validation failure leaves the caller's document (and whatever it was // published from) exactly as it was. func (l *Loader) ApplyOverlay(doc *Document, overrides map[string]any) (*Document, error) { next := *doc next.Config = doc.Config.Clone() next.Provenance.Origins = append([]Origin(nil), doc.Provenance.Origins...) if len(overrides) == 0 { return l.finalize(&next) } if err := ApplyOverlayValues(&next.Config, overrides); err != nil { return nil, err } if err := applySchedulingOverlay(&next.Scheduling, overrides); err != nil { return nil, err } next.Provenance.record(Origin{Path: "config_overlay (runtime)", Role: RoleMain, Layer: LayerOverlay}) return l.finalize(&next) } func (l *Loader) overlayFile(basePath, overlayPath string) (*Document, error) { doc := &Document{} cfgKeys, err := decodeConfigFileKeys(basePath, &doc.Config) if err != nil { return nil, err } schedKeys, err := decodeSchedulingFileKeys(basePath, &doc.Scheduling) if err != nil { return nil, err } doc.UnknownKeys = append(doc.UnknownKeys, unknownKeys(cfgKeys, schedKeys)...) doc.Provenance.record(Origin{Path: basePath, Role: RoleMain, Layer: LayerBase}) if overlayPath != "" { cfgKeys, err = decodeConfigFileKeys(overlayPath, &doc.Config) if err != nil { return nil, err } schedKeys, err = decodeSchedulingFileKeys(overlayPath, &doc.Scheduling) if err != nil { return nil, err } doc.UnknownKeys = append(doc.UnknownKeys, unknownKeys(cfgKeys, schedKeys)...) doc.Provenance.record(Origin{Path: overlayPath, Role: RoleMain, Layer: LayerOverlay}) } return l.finalize(doc) } // unknownKeys returns the keys present in both a and b: one config file // feeds more than one decode target (&doc.Config and &doc.Scheduling), so // a key legitimately owned by one target decodes cleanly there and only // shows up in the other target's undecoded set. Only a key neither target // consumed is a real unknown key (Hazard 1, plan-config-drift.md). func unknownKeys(a, b []string) []string { if len(a) == 0 || len(b) == 0 { return nil } inB := make(map[string]bool, len(b)) for _, k := range b { inB[k] = true } var out []string for _, k := range a { if inB[k] { out = append(out, k) } } return out } // sortedUnique returns keys sorted and de-duplicated, so Document.UnknownKeys // is deterministic across a base+overlay load that happens to name the same // stray key in both files. func sortedUnique(keys []string) []string { if len(keys) == 0 { return nil } seen := make(map[string]bool, len(keys)) out := make([]string, 0, len(keys)) for _, k := range keys { if !seen[k] { seen[k] = true out = append(out, k) } } sort.Strings(out) return out } // Dir loads configuration from a directory tree: // // config.yaml daemon-level settings // config.gateway.yaml chat channels and platforms // config.tools.yaml MCP servers and tool policy // config.memory.yaml memory provider settings // config.models.yaml LLM providers and models // config.identities.yaml identity settings // conf.d/*.yaml additional feature files // // A missing feature file means the feature is absent, not an error. Legacy // config.toml is the fallback when config.yaml is absent; YAML wins when // both exist. // // When overlayDir is non-empty its files are applied on top of baseDir, with // the same field-level precedence as [Loader.Overlay]. The overlay directory // need not contain a main config. func (l *Loader) Dir(baseDir, overlayDir string) (*Document, error) { doc := &Document{} if err := l.loadDir(doc, baseDir, LayerBase); err != nil { return nil, err } if overlayDir != "" { if err := l.loadDir(doc, overlayDir, LayerOverlay); err != nil { return nil, err } } return l.finalize(doc) } // loadDir discovers and decodes one directory into doc. The base layer must // supply a main config; an overlay may contribute feature files alone. func (l *Loader) loadDir(doc *Document, dir string, layer Layer) error { files, err := discover(dir) if err != nil { return err } switch path, isYAMLFile, ok := files.main(); { case ok: if err := l.decodeMain(doc, path, isYAMLFile); err != nil { return err } doc.Provenance.record(Origin{Path: path, Role: RoleMain, Layer: layer}) case layer == LayerBase: return fmt.Errorf("%w: no config.yaml or config.toml in %s", ErrNoConfigFile, dir) } for _, feature := range files.sortedFeatures() { path := files.features[feature] if err := decodeFeature(&doc.Config, feature, path); err != nil { return err } doc.Provenance.record(Origin{Path: path, Role: RoleFeature, Layer: layer, Feature: feature}) } for _, name := range files.sortedExtras() { path := files.extras[name] if err := decodeExtra(&doc.Config, name, path); err != nil { return err } doc.Provenance.record(Origin{Path: path, Role: RoleExtra, Layer: layer, Feature: Feature(name)}) } return nil } // decodeMain decodes the daemon-level file in whichever format it uses. func (l *Loader) decodeMain(doc *Document, path string, isYAMLFile bool) error { if isYAMLFile { if err := decodeYAML(path, &doc.Config); err != nil { return err } return decodeSchedulingFile(path, &doc.Scheduling) } cfgKeys, err := decodeTOMLKeys(path, &doc.Config) if err != nil { return err } schedKeys, err := decodeSchedulingFileKeys(path, &doc.Scheduling) if err != nil { return err } doc.UnknownKeys = append(doc.UnknownKeys, unknownKeys(cfgKeys, schedKeys)...) return nil } // finalize applies defaults, then validates. The order matters: validation // judges the effective configuration, including values the operator never // wrote. func (l *Loader) finalize(doc *Document) (*Document, error) { doc.UnknownKeys = sortedUnique(doc.UnknownKeys) l.applyDefaults(&doc.Config) if err := Validate(&doc.Config); err != nil { return nil, err } l.log.Debug("configuration loaded", "sources", doc.Provenance.String()) return doc, nil }