Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
bb4815f
feat(cli): support nested maps in rc config file
lodekeeper Jul 2, 2026
5684d86
docs(cli): add rcConfig example to CLI reference
lodekeeper Jul 2, 2026
7f8349a
fix(cli): harden flattenObject against non-plain and prototype-pollut…
lodekeeper Jul 2, 2026
6900079
docs(cli): note rcConfig flag+prefix nesting caveat
lodekeeper Jul 2, 2026
54b1316
docs(cli): clarify rcConfig flag+prefix caveat with a concrete example
lodekeeper Jul 4, 2026
c2828d4
feat(cli): accept nested `enabled` for on/off flags in rcConfig
lodekeeper Jul 4, 2026
d7943c4
docs(cli): trim rcConfig example per review
lodekeeper Jul 4, 2026
440318e
fix(cli): repair rcConfig docs rendering, keep example minimal
lodekeeper Jul 4, 2026
2f496f0
docs(cli): render rcConfig example as a bare yaml block
lodekeeper Jul 4, 2026
a4db343
docs(cli): keep rcConfig example inline, drop docsgen change
lodekeeper Jul 4, 2026
5307c3e
docs(cli): use beacon-config.yaml in rcConfig example
lodekeeper Jul 4, 2026
c8a47f1
docs(cli): drop "example:" label from rcConfig docs, keep command
lodekeeper Jul 4, 2026
f801040
docs(cli): keep "example:" label, revert docsgen tweak
lodekeeper Jul 4, 2026
5f96ad3
docs(cli): drop command from rcConfig example, keep "example:" label
lodekeeper Jul 4, 2026
60b6648
docs(cli): use command-agnostic options in rcConfig example
lodekeeper Jul 4, 2026
bf161a1
refactor(cli): drop unused command from option examples
lodekeeper Jul 4, 2026
b5b9c93
docs(cli): show dotted-key form in rcConfig example
lodekeeper Jul 5, 2026
f035e9d
Apply suggestion from @nflaig
nflaig Jul 5, 2026
657b5c5
Merge branch 'unstable' into feat/nested-rc-config
nflaig Jul 5, 2026
b151a88
chore: re-trigger CI
lodekeeper Jul 5, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions packages/cli/docsgen/markdown.ts
Original file line number Diff line number Diff line change
Expand Up @@ -138,8 +138,8 @@ function renderOption(optionName: string, option: CliOptionDefinition): string |
commandOption.push(`default: \`${defaultValue}\``);
}

if (option.example) {
commandOption.push(`example: ${renderExampleBody(option.example)}`);
if (option.example?.description) {
Comment thread
nflaig marked this conversation as resolved.
Resolved
commandOption.push(`example: ${sanitizeDescription(option.example.description)}`);
}

return commandOption.join(DEFAULT_SEPARATOR).concat(LINE_BREAK);
Expand Down
16 changes: 14 additions & 2 deletions packages/cli/src/options/globalOptions.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import {ACTIVE_PRESET} from "@lodestar/params";
import {CliCommandOptions} from "@lodestar/utils";
import {NetworkName, networkNames} from "../networks/index.js";
import {readFile} from "../util/index.js";
import {flattenObject, readFile, translateEnabledKeys} from "../util/index.js";
import {IParamsArgs, paramsOptions} from "./paramsOptions.js";

type GlobalSingleArgs = {
Expand Down Expand Up @@ -51,6 +51,17 @@ const globalSingleOptions: CliCommandOptions<GlobalSingleArgs> = {
rcConfig: {
description: "RC file to supplement command line args, accepted formats: .yml, .yaml, .json",
type: "string",
example: {
description: `Options can be written as nested maps or dotted keys

\`\`\`yaml
network: hoodi
logLevel: debug
metrics:
enabled: true
port: 8008
\`\`\``,
},
Comment thread
nflaig marked this conversation as resolved.
Resolved
},

supernode: {
Expand All @@ -70,7 +81,8 @@ const globalSingleOptions: CliCommandOptions<GlobalSingleArgs> = {
export const rcConfigOption: [string, string, (configPath: string) => Record<string, unknown>] = [
"rcConfig",
globalSingleOptions.rcConfig.description as string,
(configPath: string): Record<string, unknown> => readFile(configPath, ["json", "yml", "yaml"]),
(configPath: string): Record<string, unknown> =>
translateEnabledKeys(flattenObject(readFile(configPath, ["json", "yml", "yaml"]))),
];

export type GlobalArgs = GlobalSingleArgs & IParamsArgs;
Expand Down
73 changes: 72 additions & 1 deletion packages/cli/src/util/object.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import {RecursivePartial} from "@lodestar/utils";
import {RecursivePartial, isPlainObject} from "@lodestar/utils";

/**
* Removes (mutates) all properties with a value === undefined, recursively
Expand All @@ -13,3 +13,74 @@ export function removeUndefinedRecursive<T extends {[key: string]: any}>(obj: T)
}
return obj as RecursivePartial<T>;
}

/**
* Flattens a nested object into a single-level object with dot-notation keys.
*
* Allows the rc config file to be written with either nested maps or dotted keys, e.g.
* `{rest: {address: "0.0.0.0"}}` and `{"rest.address": "0.0.0.0"}` both flatten to
* `{"rest.address": "0.0.0.0"}`, matching how CLI options are registered (`dot-notation`
* is disabled in yargs). Arrays are preserved as values (not flattened by index) so
* array options like `rest.namespace` or `bootnodes` keep working.
*
* If the same option is provided in both nested and dotted form, the value that appears
* last in the file wins.
*/
export function flattenObject(obj: Record<string, unknown>, parentKey?: string): Record<string, unknown> {
// Guard non-plain input: an empty or scalar rc config file makes `readFile` return `undefined`
// or a primitive, which would otherwise throw on `Object.entries`. `isPlainObject` also rejects
// arrays and class instances (Date, Buffer, typed arrays); those are handled as leaf values below.
if (!isPlainObject(obj)) {
return {};
}
const flattened: Record<string, unknown> = {};
for (const [key, value] of Object.entries(obj)) {
// Skip prototype-polluting keys as defense-in-depth (config files can be semi-trusted).
if (key === "__proto__") {
continue;
}
const prefixedKey = parentKey ? `${parentKey}.${key}` : key;
// Only recurse into plain objects; arrays and class instances (e.g. Date) are kept as leaf
// values — recursing into them would silently drop or mis-flatten them.
if (isPlainObject(value)) {
Object.assign(flattened, flattenObject(value as Record<string, unknown>, prefixedKey));
} else {
flattened[prefixedKey] = value;
}
}
return flattened;
}
Comment thread
nflaig marked this conversation as resolved.
Resolved

/**
* Rewrites `{prefix}.enabled` keys to the bare `{prefix}` flag.
*
* Some options are exposed as an on/off boolean flag (`--metrics`, `--rest`, `--builder`) whose
* internal config shape nests the toggle under `.enabled` (e.g. `{metrics: {enabled, port}}`). This
* lets an rc config file be written in the natural nested form:
*
* ```yaml
* metrics:
* enabled: true
* port: 8008
* ```
*
* which {@link flattenObject} turns into `{"metrics.enabled": true, "metrics.port": 8008}`. The CLI
* registers the toggle as the bare `metrics` flag (there is no `metrics.enabled` option), so rewrite
* `{prefix}.enabled` -> `{prefix}` to match a registered option. No CLI option is registered with an
* `.enabled` suffix, so this is unambiguous. If the bare `{prefix}` key is already set (e.g. mixed
* dotted and nested forms), the `.enabled` key is left untouched so the conflict surfaces as an
* "unknown argument" error rather than being silently overridden.
*/
export function translateEnabledKeys(flattened: Record<string, unknown>): Record<string, unknown> {
const suffix = ".enabled";
const translated: Record<string, unknown> = {};
for (const [key, value] of Object.entries(flattened)) {
const prefix = key.endsWith(suffix) ? key.slice(0, -suffix.length) : "";
if (prefix && !(prefix in flattened)) {
translated[prefix] = value;
} else {
translated[key] = value;
}
}
return translated;
}
136 changes: 136 additions & 0 deletions packages/cli/test/unit/util/object.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
import {describe, expect, it} from "vitest";
import {flattenObject, translateEnabledKeys} from "../../../src/util/object.js";

describe("util / flattenObject", () => {
it("flattens nested maps into dot-notation keys", () => {
expect(flattenObject({rest: {address: "0.0.0.0", port: 9596}})).toEqual({
"rest.address": "0.0.0.0",
"rest.port": 9596,
});
});

it("leaves already-dotted keys unchanged (backwards compatible)", () => {
expect(flattenObject({"rest.address": "0.0.0.0", "rest.port": 9596})).toEqual({
"rest.address": "0.0.0.0",
"rest.port": 9596,
});
});

it("preserves arrays as values instead of flattening them by index", () => {
expect(flattenObject({rest: {namespace: ["beacon", "config"]}, bootnodes: ["enr:-a", "enr:-b"]})).toEqual({
"rest.namespace": ["beacon", "config"],
bootnodes: ["enr:-a", "enr:-b"],
});
});

it("preserves primitive value types (boolean, number, null)", () => {
expect(flattenObject({metrics: {enabled: true, port: 8008, host: null}})).toEqual({
"metrics.enabled": true,
"metrics.port": 8008,
"metrics.host": null,
});
});

it("supports nested and dotted keys mixed in the same object", () => {
expect(flattenObject({rest: {address: "0.0.0.0"}, "rest.port": 9596, network: "hoodi"})).toEqual({
"rest.address": "0.0.0.0",
"rest.port": 9596,
network: "hoodi",
});
});

it("flattens arbitrarily deep nesting", () => {
expect(flattenObject({a: {b: {c: 1}}})).toEqual({"a.b.c": 1});
});

it("returns top-level scalars untouched", () => {
expect(flattenObject({network: "hoodi", port: 9000, rest: true})).toEqual({
network: "hoodi",
port: 9000,
rest: true,
});
});

it("last definition wins when a key is given in both nested and dotted form", () => {
expect(flattenObject({"rest.address": "first", rest: {address: "second"}})).toEqual({
"rest.address": "second",
});
});

it("keeps arrays of objects intact as a single value", () => {
expect(flattenObject({chain: {trustedSetup: [{index: 0}, {index: 1}]}})).toEqual({
"chain.trustedSetup": [{index: 0}, {index: 1}],
});
});

it("drops empty nested maps and keeps sibling keys", () => {
expect(flattenObject({rest: {}, network: "hoodi"})).toEqual({network: "hoodi"});
});

it("returns an empty object for non-plain input instead of throwing", () => {
// e.g. an empty or scalar rc config file makes readFile return undefined / a primitive
expect(flattenObject(undefined as unknown as Record<string, unknown>)).toEqual({});
expect(flattenObject(null as unknown as Record<string, unknown>)).toEqual({});
expect(flattenObject("network: hoodi" as unknown as Record<string, unknown>)).toEqual({});
expect(flattenObject(42 as unknown as Record<string, unknown>)).toEqual({});
});

it("skips the __proto__ key and does not pollute Object.prototype", () => {
const malicious = JSON.parse('{"__proto__": {"polluted": true}, "network": "hoodi"}');
expect(flattenObject(malicious)).toEqual({network: "hoodi"});
expect(({} as Record<string, unknown>).polluted).toBeUndefined();
});

it("keeps non-plain object values (e.g. Date) as leaves instead of dropping them", () => {
const genesisTime = new Date("2024-01-01T00:00:00Z");
expect(flattenObject({chain: {genesisTime}})).toEqual({"chain.genesisTime": genesisTime});
});
});

describe("util / translateEnabledKeys", () => {
it("rewrites `{prefix}.enabled` to the bare `{prefix}` flag", () => {
expect(translateEnabledKeys({"metrics.enabled": true, "metrics.port": 8008})).toEqual({
metrics: true,
"metrics.port": 8008,
});
});

it("translates the nested form produced by flattenObject (metrics: {enabled, port})", () => {
expect(translateEnabledKeys(flattenObject({metrics: {enabled: true, port: 8008}}))).toEqual({
metrics: true,
"metrics.port": 8008,
});
});

it("handles multiple prefixes independently", () => {
expect(
translateEnabledKeys({"metrics.enabled": true, "builder.enabled": false, "builder.url": "http://localhost"})
).toEqual({
metrics: true,
builder: false,
"builder.url": "http://localhost",
});
});

it("leaves `{prefix}.enabled` untouched when the bare `{prefix}` is already set (conflict surfaces later)", () => {
expect(translateEnabledKeys({metrics: false, "metrics.enabled": true})).toEqual({
metrics: false,
"metrics.enabled": true,
});
});

it("is a no-op when there are no `.enabled` keys", () => {
expect(translateEnabledKeys({"rest.port": 9596, network: "hoodi"})).toEqual({
"rest.port": 9596,
network: "hoodi",
});
});

it("does not translate a top-level key literally named `enabled`", () => {
expect(translateEnabledKeys({enabled: true})).toEqual({enabled: true});
});

it("strips `.enabled` from a deeply-prefixed key", () => {
expect(translateEnabledKeys({"a.b.enabled": true})).toEqual({"a.b": true});
});
});
3 changes: 2 additions & 1 deletion packages/utils/src/command.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ export interface CliExample {

// biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here
export interface CliOptionDefinition<T = any> extends Options {
example?: Omit<CliExample, "title">;
// Option examples are a description block only (e.g. an rc config snippet); no command line
example?: Omit<CliExample, "title" | "command">;
// Ensure `type` property matches type of `T`
type: T extends string
? "string"
Expand Down
Loading