Forge Config

Forge Config will be a Free & Open Source (Apache 2.0) configuration loading and layering library aimed at predictable, explicit environment‑aware application setup.

Purpose

Provide a small, composable abstraction for merging configuration from:

1. Defaults (embedded or code struct)
2. One or more config files (YAML / JSON / TOML—format priority TBD)
3. Environment variables (prefix + mapping)
4. CLI flags / runtime overrides (future)
5. Secret file injections (optional future hook)

Output: a strongly typed struct (in the target language implementation) with validation applied.

Core Principles

1. Deterministic layering (documented resolution order)
2. No hidden magic (explicit mapping > implicit reflection when possible)
3. Schema validation first (fail fast)
4. Clear error reporting (which key, which layer, why invalid)
5. Extensible adapters (custom sources or serializers)

Planned Feature Set (Future)

• Load sequence with per-layer provenance tracking
• Environment variable mapping with optional coercion
• Profile support (e.g., --profile staging => merges config.staging.yaml)
• Strict schema validation (required fields, type checks, enum constraints)
• Redaction helper for safe logging (mask secrets)
• Hot reload hook (optional, opt-in)
• Diff utility to show effective overrides
• Pluggable decoder interface for alternative formats
• Optional “freeze” step to lock after finalization

Example Concept (Not Implemented)

Configuration file (config.yaml):

server:
  host: 0.0.0.0
  port: 8080
database:
  url: postgres://user:pass@localhost/db
  max_connections: 10

Environment overlay:

FORGE_SERVER_PORT=9090
FORGE_DATABASE_MAX_CONNECTIONS=20

Effective (pseudo):

{
  "server": { "host": "0.0.0.0", "port": 9090 },
  "database": { "url": "...", "max_connections": 20 }
}

Roadmap Sketch (Aspirational)

1. Core file loader + base struct mapping
2. Environment overlay layer
3. Schema validation module
4. Profiles / layered includes
5. Redaction + diff printing
6. Hot reload watch (optional)
7. Plug-in format decoders
8. CLI inspect tool (maybe integrated later with Bloom CLI)

Non‑Goals (Early)

• Full-featured secret manager integration (may expose a hook later)
• Distributed configuration sync
• Dynamic remote KV backends (e.g., Consul, etcd) in first iterations

Status

Concept stage only. No implementation exists yet; this repo is a placeholder for future development.

License

Intended license: Apache License 2.0 (added prior to first code commit).

Potential Integrations

• Used by bloom-cli and future orchestration tools.
• Shared config story across the sakuraforge ecosystem.

---

“Configuration should converge—layer by layer—into clarity, not confusion.”