diff --git a/packages/cli/docsgen/markdown.ts b/packages/cli/docsgen/markdown.ts index a83397a01482..2edb72f5af61 100644 --- a/packages/cli/docsgen/markdown.ts +++ b/packages/cli/docsgen/markdown.ts @@ -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) { + commandOption.push(`example: ${sanitizeDescription(option.example.description)}`); } return commandOption.join(DEFAULT_SEPARATOR).concat(LINE_BREAK); diff --git a/packages/cli/src/options/globalOptions.ts b/packages/cli/src/options/globalOptions.ts index 795b4417e235..082a841822df 100644 --- a/packages/cli/src/options/globalOptions.ts +++ b/packages/cli/src/options/globalOptions.ts @@ -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 = { @@ -51,6 +51,17 @@ const globalSingleOptions: CliCommandOptions = { 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 +\`\`\``, + }, }, supernode: { @@ -70,7 +81,8 @@ const globalSingleOptions: CliCommandOptions = { export const rcConfigOption: [string, string, (configPath: string) => Record] = [ "rcConfig", globalSingleOptions.rcConfig.description as string, - (configPath: string): Record => readFile(configPath, ["json", "yml", "yaml"]), + (configPath: string): Record => + translateEnabledKeys(flattenObject(readFile(configPath, ["json", "yml", "yaml"]))), ]; export type GlobalArgs = GlobalSingleArgs & IParamsArgs; diff --git a/packages/cli/src/util/object.ts b/packages/cli/src/util/object.ts index efd9bcfd4977..d77380407978 100644 --- a/packages/cli/src/util/object.ts +++ b/packages/cli/src/util/object.ts @@ -1,4 +1,4 @@ -import {RecursivePartial} from "@lodestar/utils"; +import {RecursivePartial, isPlainObject} from "@lodestar/utils"; /** * Removes (mutates) all properties with a value === undefined, recursively @@ -13,3 +13,74 @@ export function removeUndefinedRecursive(obj: T) } return obj as RecursivePartial; } + +/** + * 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, parentKey?: string): Record { + // 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 = {}; + 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, prefixedKey)); + } else { + flattened[prefixedKey] = value; + } + } + return flattened; +} + +/** + * 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): Record { + const suffix = ".enabled"; + const translated: Record = {}; + 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; +} diff --git a/packages/cli/test/unit/util/object.test.ts b/packages/cli/test/unit/util/object.test.ts new file mode 100644 index 000000000000..59de9bc85b36 --- /dev/null +++ b/packages/cli/test/unit/util/object.test.ts @@ -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)).toEqual({}); + expect(flattenObject(null as unknown as Record)).toEqual({}); + expect(flattenObject("network: hoodi" as unknown as Record)).toEqual({}); + expect(flattenObject(42 as unknown as Record)).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).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}); + }); +}); diff --git a/packages/utils/src/command.ts b/packages/utils/src/command.ts index 497dd72a225e..423a188832f3 100644 --- a/packages/utils/src/command.ts +++ b/packages/utils/src/command.ts @@ -8,7 +8,8 @@ export interface CliExample { // biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here export interface CliOptionDefinition extends Options { - example?: Omit; + // Option examples are a description block only (e.g. an rc config snippet); no command line + example?: Omit; // Ensure `type` property matches type of `T` type: T extends string ? "string"