feat(cli): support nested maps in rc config file

[lodekeeper]

Motivation

Lodestar's --rcConfig file currently requires nested options to be written as dotted keys:

rest.address: "0.0.0.0"
rest.port: 9596

This surprised a user who expected the idiomatic nested YAML form (rest: → address:). The nested form is nicer, but we don't want to break existing dotted configs — so this PR supports both.

Description

Nested maps → dotted keys

Nested maps in the config file are flattened to dotted keys before being handed to yargs, so both of these produce identical results:

# dotted (still works)
rest.address: "0.0.0.0"
rest.port: 9596

# nested (now works too)
rest:
  address: "0.0.0.0"
  port: 9596

Why flattening: cli.ts sets parserConfiguration({"dot-notation": false}) (needed so .strict() keeps working with dotted option names), so options are registered as literal dotted keys ("rest.address") and yargs .config() only matches literal dotted keys from the file — nested maps are silently ignored today. Flattening the parsed file in the rcConfig read callback bridges the gap without touching parser config or the strictness guarantees.

• Arrays are preserved as values (not flattened by index) so array options (rest.namespace, bootnodes, …) keep working.
• Already-dotted keys pass through unchanged → fully backward compatible.
• Prototype-pollution safe: __proto__ is skipped and non-plain input returns {}.
• If an option is given in both nested and dotted form, the value appearing last in the file wins.
• Applies to every command that shares the global --rcConfig option (beacon / validator / bootnode).

.enabled → bare on/off flag

On/off options are registered as a bare boolean flag (e.g. --metrics), which reads awkwardly as a nested map. After flattening, {prefix}.enabled is rewritten to the bare {prefix} flag so the natural nested form works:

metrics:
  enabled: true   # → the --metrics flag
  port: 8008

metrics.enabled: true → metrics: true. If both {prefix} and {prefix}.enabled are present, .enabled is left as-is so the conflict surfaces at yargs' strict check instead of being silently swallowed.

Testing

• flattenObject — 13 unit tests: nested → dotted, dotted pass-through, mixed nested+dotted, array preservation, arrays-of-objects, primitive/null values, deep nesting, top-level scalars, empty-map elision, nested/dotted collision precedence, __proto__ guard, non-plain input, and non-plain object leaves (Date).
• translateEnabledKeys — 7 unit tests: .enabled → bare flag, the nested metrics: {enabled, port} form, multiple prefixes, the already-set conflict case, no-op when absent, a top-level enabled is not translated, and deeply-prefixed keys.
• check-types, biome lint, full build, and the existing cli util / options / beacon unit suites pass — no regressions.

Docs

Adds a compact example to the --rcConfig option showing both forms (a nested map and a dotted key), so it renders in the generated CLI reference (beacon-cli#--rcconfig). Because --rcConfig is a global option, its example renders in every command's docs, so it uses options common to all of them (network / logLevel / metrics) rather than a beacon-only option.

Rendering an option example that's a config snippet (no shell command) needed a small docsgen change: renderOption renders the example description directly, and CliOptionDefinition.example becomes description-only (Omit<CliExample, "title" | "command">). The example is docs-only (yargs ignores it, so --help is unchanged) and the generated *-cli.md files are gitignored.

This supersedes the dedicated docs page in #9574 (now closed) — a whole page was overkill; an inline example is enough.

---

🤖 Generated with AI assistance

[gemini-code-assist]

Code Review

This pull request introduces a flattenObject utility to flatten nested configuration objects into dot-notation keys, enabling CLI configuration files to support both nested and dotted formats. The review feedback highlights critical security and robustness issues in the implementation, specifically pointing out a prototype pollution vulnerability, incorrect handling of non-plain objects (like Date or RegExp), and potential runtime errors if the input is not a plain object. A revised implementation with an isPlainObject helper is suggested to resolve these concerns.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bb4815f069

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[nflaig]

@lodekeeper please take a look at the bot reviews

[lodekeeper]

Addressed the bot reviews on #9578:

• Gemini (prototype pollution / robustness): hardened flattenObject with isPlainObject (reused from @lodestar/utils) — non-object input returns {} instead of throwing, non-plain objects (Date/Buffer/etc.) are kept as leaves, and __proto__ is skipped. +3 regression tests (7f8349a).
• Codex (prefix collisions): not a flattenObject bug — it faithfully flattens valid input and never drops a provided value; the nested form just can't express both a scalar and its sub-options for flag/prefix options (network/metrics/builder), which is inherent to YAML. Documented the caveat on the --rcConfig example (6900079), pointing to the dotted form for those.

Green locally: biome, check-types, 13/13 flattenObject tests.

[nflaig]

@lodekeeper see my comments

[nflaig]

@lodekeeper it's really messed up now

please just keep this PR minimal...

[nflaig]

@lodekeeper

[lodekeeper]

Fixed in 440318e.

Root cause: the trimmed example started with a ```yaml fence, but docsgen renders the example inline after example: , so it came out as example: ```yaml (fence mid-line) → MDX stopped parsing the page and everything below --rcConfig rendered as raw source.

Fix: a one-line lead-in before the yaml so the fence starts at line-start (verified with docs:build), restored the command, and reverted the renderExampleBody / CliExample changes from the previous push — not needed with the command back, so the diff is down to just the feature + the example (docsgen + utils untouched).

[nflaig]

@lodekeeper few more comments, otherwise looks good, please once you applied the remaining changes, push another update to your github pages and verify it looks good on the rendered docs

[wemeetagain]

🎉 This PR is included in v1.45.0 🎉