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.

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