🚀 [Feature]: Merge-Toml combines TOML documents into one

[Marius Storhaug (MariusStorhaug)]

Merge-Toml combines two or more TOML documents into one, so layered configuration — defaults plus environment overrides, or a base file plus a local override file — no longer needs ad-hoc hashtable-merging loops.

New: Merge-Toml

Merge-Toml accepts either two TOML strings, or a list of file paths merged in order:

Merge-Toml -BaseObject $defaults -OverrideObject $overrides
Merge-Toml -Path 'defaults.toml', 'local.toml'
Merge-Toml -LiteralPath 'defaults.toml', 'local.toml'

Nested tables are always deep-merged recursively, and arrays of tables ([[...]]) are always concatenated, base entries first. Scalar key conflicts (including inline arrays, treated as scalars) are resolved with -Strategy:

• LastWins (default) — the override value replaces the base value
• FirstWins — the base value is kept
• ErrorOnConflict — throws on any duplicate scalar key

The result is always a [string] of canonical TOML, parseable by ConvertFrom-Toml.

---

Technical details

• Added src/functions/public/Merge-Toml.ps1 with three parameter sets: Default (-BaseObject/-OverrideObject), Path, and LiteralPath.
• Added private recursive helper src/functions/private/Merge-TomlTableObject.ps1 that walks override keys against a base OrderedDictionary, deep-merging nested tables, concatenating ArrayList array-of-tables, and applying -Strategy to remaining scalar conflicts.
• Implementation reuses ConvertFrom-Toml/ConvertTo-Toml for parsing and serialization — no new parsing logic.
• Added Pester coverage in tests/Toml.Tests.ps1 for all parameter sets, all three strategies, deep-merge, AoT concatenation, file input, and idempotency.
• Updated README.md with a usage example and added Merge-Toml to the command table.
• Verified: Invoke-ScriptAnalyzer -Path src/ -Recurse clean (no new findings), 135/135 Pester tests passing.
• Implementation plan progress: all tasks in Add Merge-Toml function to combine TOML documents #19 completed (helper, function, tests, README).

Relevant issues (or links)

• Closes Add Merge-Toml function to combine TOML documents #19