nerve config validate — CI-ready config bundle validation (7/13)

[alex-clickhouse]

What

nerve config validate checks a whole config bundle and exits non-zero on any error, so it drops straight into CI on a config repo. It covers unknown keys, cron job and gate parsing, source sanity, ${VAR} resolvability, and schedules the scheduler would not actually run as written.

--portable-only drops the machine-local layers and judges the tracked layer alone. --strict-keys and --strict-env promote warnings to errors. It runs even when the config cannot otherwise load, which is the point.

Why

Every class of error here was previously found by a daemon at start-up, after the change had already merged and synced — leaving the instance on its old config with a log line nobody was reading. Moving the check before the merge is the whole value.

Schedules are the clearest case. A 5-field crontab the scheduler rejects (99 * * * *) is refused at run time and logged. A schedule that is neither a crontab nor an interval (hourly, @daily) is never complained about at run time at all — it silently never fires.

--portable-only exists because a machine-local override can mask an invalid shared value, and, more commonly, a broken local file condemns a shared bundle with nothing wrong with it. Validating the tracked layer on its own is the only question whose answer does not depend on which host ran the check.

Validation reads and parses; it does not execute candidate gate-plugin code. "An invalid bundle is refused" is not a guarantee you can make about code you had to run in order to judge it, so an unrecognised gate type is reported as unverified rather than accepted or rejected. Testing a plugin is the author's job.

Added in review

The validator rejected blank path values that the loader accepts. It refused
a blank workspace, cron.jobs_file, cron.system_file or
cron.gate_plugins_dir on the stated premise that Path("") is Path("."), so
a blank "means the directory the daemon happened to be started in". It does not:
_expand_path maps blank to None before it can become Path("."), and the
field takes its documented default. A single validator run showed both halves —
the log line resolving the blank to the default, then the error saying it
resolved to the working directory.

The shape that hits it is jobs_file: ${CRON_JOBS_FILE:-}, and the docs promote
${VAR:-default} as the fleet idiom. docs/config.md carried both readings in
two places, and the suite pinned both contracts with TestBlankPathSettingsMeanUnset
and TestWorkingDirectoryPaths green side by side.

Blank is no longer reported. An explicit . / ./ / ./. stays a hard error,
because those do survive the loader as the path they are.

The rule was also a hand-written four-key literal against fourteen path settings,
so gateway.ssl.cert accepted a dot that switches TLS on with a directory as the
certificate. The keys are now derived from the config dataclasses: one test walks
every Path-annotated field and fails if it is neither covered nor exempted with
a reason, a second fails if the rule names a field the config does not declare,
and a third asserts each covered key actually produces an error — so a key cannot
be listed and never read. Six settings that check turned up are now covered.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds CI-friendly configuration bundle validation (nerve config validate) and supporting validation primitives to hard-fail on structurally invalid config bundles (cron schedules, gate specs, wrong-shaped layers, unsafe cwd-resolving paths), while remaining intentionally lenient about unset ${ENV_VAR} secrets unless explicitly requested.

Changes:

• Introduces validate_config_bundle() with detailed reporting and a new nerve config validate CLI command.
• Tightens cron schedule and gate-spec validation (including new interval parsing semantics and gate spec field allowlists via spec_keys).
• Expands test coverage and documentation for validation behavior, strictness flags, and plugin non-execution guarantees.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_cron_gates.py	Adds regression tests for gate-shape normalization/logging behavior.
tests/test_config_validate.py	Adds comprehensive tests for config-bundle validation semantics and CLI behavior.
tests/test_config_sources.py	Ensures CLI emits clean errors for config mistakes (including bad backend) while preserving tracebacks for internal defects.
nerve/cron/service.py	Splits interval parsing to expose _interval_seconds() for validation without changing daemon fallback behavior.
nerve/cron/jobs.py	Prevents accidental normalization of wrong-shaped run_if/skip_when_idle, and logs+ignores invalid shapes instead of raising.
nerve/cron/gates.py	Adds spec_keys allowlists and improves build_gate() robustness for non-string/unhashable type.
nerve/config_validate.py	New validation module: layer reading, cwd-path footgun checks, cron/gate/schedule validation, and reporting.
nerve/cli.py	Adds nerve config validate command and refines “clean error vs traceback” behavior in the CLI group callback.
docs/cron.md	Documents schedule fallback vs validation behavior, and clarifies that validation does not execute plugin gates.
docs/config.md	Adds a full “Validating Configuration” section including CI guidance and flags.
config.example.yaml	Updates cron comments and documents cron.auto_reload example.

---

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