${ENV_VAR} interpolation in config loading (2/13)

[alex-clickhouse]

What

${VAR} (required — loading fails, listing every unresolved name) and ${VAR:-default} (optional, shell :- semantics) in any string value in any config layer. Interpolation runs once, after all layers are merged. Only the braced form is touched, so bcrypt hashes ($2b$...) and connection strings are safe as-is.

Because interpolation is string substitution, an interpolated value arrives as str. Fields declared int, float or bool — including X | None and list[X] — are converted back to their declared type when the config object is built. Booleans are parsed, not tested for truthiness, and an unparseable value keeps the field's documented default with a log line naming Class.field.

Why

Secrets should be suppliable from the environment or a secret store rather than written into a file, especially once a config layer is git-tracked and meant to be committed.

The type conversion is what makes that usable rather than a trap. Without it, port: ${PORT} arrives as "8900" and raises at its first arithmetic or socket.bind. Worse, enabled: ${FLAG} with FLAG=false is a non-empty string and therefore on — a flag that reads as disabled and behaves as enabled. A quoted YAML scalar (enabled: "false") reaches the same code path with no environment variable involved at all.

Lockdown makes this load-bearing rather than a convenience: it discards the machine-local layers, so every per-machine value has to be an environment reference in the tracked settings. That is exactly the shape that breaks without conversion.

Parsing rather than guessing matters in both directions. An empty variable (FLAG=) and a bare enabled: are both off, so blanking a variable reliably disables a feature instead of falling back to whatever the tracked config said; an unrecognised value falls back to the declared default rather than flipping the flag to the opposite of both what it says and what the config declares.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds ${ENV_VAR} / ${ENV_VAR:-default} interpolation to config loading (post-merge across layers), plus scalar re-coercion so interpolated values behave like literal YAML types (e.g., enabled: ${FLAG} with FLAG=false disables).

Changes:

• Introduces recursive env-var interpolation with required/optional semantics and $$ escaping, applied after deep-merge during config load.
• Adds a scalar coercion layer (@coerced) so declared bool/int/float (incl. Optional and list[...]) fields are normalized after interpolation.
• Improves CLI UX by rendering config-load failures (e.g., missing required env vars) as clean Click errors; adds extensive tests and documentation.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_config_env.py	New end-to-end and unit tests covering env interpolation + scalar coercion behavior.
nerve/config.py	Implements env interpolation, wires it into load_config/load_mcp_servers, and applies @coerced across config from_dict builders.
nerve/coerce.py	New module providing lenient scalar coercion and the @coerced decorator for config builders.
nerve/cli.py	Converts ConfigError during config load into a clean ClickException (no traceback).
docs/config.md	Documents env references, escaping, and post-interpolation scalar coercion semantics.
config.example.yaml	Adds comments documenting env-var reference support and escaping.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.