${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.

Added in review

A ${VAR} reference on a list[str] field was consumed character by
character. _COERCERS covers bool/int/float, so _classify returned None
for list[str] and left the interpolated string in place for consumers to
iterate. GMAIL_ACCOUNTS=person@example.com built eighteen gmail source runners,
one per character, and never synced the account. The same shape silently disarms
sync.github.deny_repos (a plain name matches nothing, and a value containing
* denies everything), inverts allow_repos into dropping every notification,
and turns backup.workspace_excludes into one-character globs. This matters more
under lockdown, where a per-machine value has to be an env reference.

A bare string is now wrapped as one element rather than split. The old
docstring rejected the whole type on the grounds that splitting is unsafe, and it
was right — a comma is legal inside a string, and three of the four default
langfuse.redact_patterns are regexes containing {20,}. Wrapping has no such
problem. Numeric lists keep their comma split, where the separator is
unambiguous.

Six builders widened the value themselves before the decorator could intervene,
which no later check can distinguish from a genuine list; they now hand the raw
value through.

The existing sweep could not have caught this: it asks _classify which fields
to probe, so a type the coercion ignores is a type it never tests. The new guard
derives its field set from the declared annotations instead, and asserts its skip
bucket can only hold lists of dataclasses, so a new list[<scalar>] cannot land
there unprobed.

🤖 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.