Swap magic_args for CLI11: bind options directly to the settings struct

Addresses review feedback that the magic_args version duplicated the
settings into a parallel PluginvalCliArgs struct plus manual CLI->JSON
and ENV->JSON bridges (5-6 edit sites per new option), and forced
cxx_std_23 + a macOS 13.3 deployment target (std::format).

CLI11 binds each option directly to a PluginvalSettings member, with the
environment variable on the same line via ->envname(). Adding an option
is now three edits: a struct member, a nlohmann macro entry, and one
add_option(...) line. No parallel struct, no cliArgsToJson, no envLayer.

- SettingsParser: rewritten on CLI11; comma lists via ->delimiter(','),
  enum via CheckedTransformer, hex/int seed via a small callback. --config
  seeds the struct before parse so precedence stays defaults<config<env<CLI.
  --help/--version handled by CLI11 (auto usage + footer).
- SettingsSerializer: dropped the comma/JSON-array coercions; kept the hex
  seed + disabled-tests(file-or-list) helpers and JSON load/save.
- Child-process base64 JSON handoff (--config-base64) unchanged.
- CommandLineTests: env tests now use setenv/unsetenv (CLI11 reads the real
  environment); all other cases unchanged. All --run-tests pass.
- CMake: magic_args -> CLI11 2.6.2; revert cxx_std_23 -> cxx_std_20 and
  CMAKE_OSX_DEPLOYMENT_TARGET 13.3 -> 10.11.
- Docs/CLAUDE.md updated.

Verified: full build (validator ON, C++20, macOS 10.11), --run-tests pass,
real --validate SUCCESS, --config precedence covered by tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: drowaudio

CLAUDE.md

@@ -7,7 +7,7 @@
 - **Version**: 1.0.4 (see `VERSION` file)
 - **License**: GPLv3
 - **Framework**: Built on JUCE (v8.0.x)
-- **Language**: C++23
+- **Language**: C++20
 
 ### Key Features
 - Tests VST/VST2/VST3/AU/LV2/LADSPA plugins
@@ -125,7 +125,7 @@ pluginval/
 
 ### Prerequisites
 - CMake 3.15+
-- C++23 compatible compiler
+- C++20 compatible compiler
 - Git (for submodules)
 
 ### Building
@@ -159,7 +159,7 @@ VST2_SDK_DIR=/path/to/vst2sdk cmake -B Builds/Debug .
 ```
 
 ### Target Platforms
-- **macOS**: 13.3+ (deployment target — required by std::format used in magic_args), supports Apple Silicon via universal binary
+- **macOS**: 10.11+ (deployment target), supports Apple Silicon via universal binary
 - **Windows**: MSVC with static runtime linking
 - **Linux**: Ubuntu 22.04+, statically links libstdc++
 
@@ -193,26 +193,30 @@ VST2_SDK_DIR=/path/to/vst2sdk cmake -B Builds/Debug .
 
 ### CLI Settings Pipeline
 
-Command-line parsing is a layered JSON-merge pipeline rather than a bespoke
-parser. The flow (in `SettingsParser`):
+Command-line parsing centres on one plain settings struct (`PluginvalSettings`)
+that CLI11 binds to directly. The flow (in `SettingsParser`):
 
 1. **preprocess** the raw command line — rewrite the deprecated `strictnessLevel`,
    strip the macOS `-NSDocumentRevisionsDebugMode YES` flag, and insert an
    implicit `--validate` when the last argument is a bare plugin path.
-2. Build a **sparse `nlohmann::json` per layer**: `--config` file, environment
-   variables, and the CLI options (parsed with **magic_args** into a struct of
-   `std::optional` fields, then coerced — comma lists → arrays, hex/int seed →
-   number, etc. via `SettingsSerializer`).
-3. **Merge** with `merge_patch` in precedence order (defaults < config < env <
-   CLI; **CLI wins**), then deserialise into `PluginvalSettings`
-   (`NLOHMANN_DEFINE_TYPE..._WITH_DEFAULT` fills missing keys from defaults).
+2. If `--config <file.json>` is present, **seed** the struct from that JSON first.
+3. **CLI11** binds each `add_option`/`add_flag` straight to a `PluginvalSettings`
+   member, with the environment variable on the same line via `->envname()`.
+   Because CLI11 only overwrites a member when its flag/env was actually provided,
+   precedence is **defaults < config < env < CLI** (CLI wins) with no manual
+   layering. Comma lists use `->delimiter(',')`, the enum uses a
+   `CheckedTransformer`, and the hex/int seed is a small callback.
 4. `PluginvalSettings::toPluginTestOptions()` converts to the JUCE-flavoured
    `PluginTests::Options` at the boundary.
 
+Adding a new option is three edits: a struct member, an entry in the nlohmann
+macro list, and one `add_option(...)` line. `SettingsSerializer` handles JSON
+load/save plus the two remaining conversions (hex seed, disabled-tests file).
+
 The child validation process receives a fully-resolved, **authoritative**
 settings set via a base64-encoded JSON argument (`--config-base64`), avoiding
 per-flag re-serialisation and command-line quoting hazards. `--help`/`--version`
-are handled by magic_args (auto usage + an appended env-var trailer).
+are handled by CLI11 (auto usage + a footer with the env-var/commands notes).
 
 ### Test Framework
 
@@ -401,7 +405,7 @@ add_pluginval_tests(MyPluginTarget
 ### External
 - **JUCE** (v8.0.x) - Audio application framework (git submodule)
 - **magic_enum** (v0.9.7) - Enum reflection (fetched via CPM)
-- **magic_args** (v0.2.1) - C++23 CLI argument parsing, header-only (fetched via CPM); requires macOS 13.3+ due to std::format
+- **CLI11** (v2.6.2) - CLI argument parsing, header-only (fetched via CPM)
 - **nlohmann/json** (3.12.0) - JSON settings layering/serialisation (fetched via CPM)
 - **rtcheck** (optional, macOS) - Real-time safety checking (fetched via CPM)
 - **VST3 SDK** (v3.7.x) - Steinberg VST3 SDK for embedded validator (fetched via CPM, optional)

CMakeLists.txt

@@ -6,9 +6,8 @@ project(pluginval VERSION ${CURRENT_VERSION})
 # Just compliing pluginval
 if (pluginval_IS_TOP_LEVEL)
     if (APPLE)
-        # Target OS versions down to 13.3. std::format (used by magic_args) pulls in
-        # libc++'s floating-point formatter, whose to_chars is only available on 13.3+.
-        set (CMAKE_OSX_DEPLOYMENT_TARGET "13.3" CACHE INTERNAL "")
+        # Target OS versions down to 10.11
+        set (CMAKE_OSX_DEPLOYMENT_TARGET "10.11" CACHE INTERNAL "")
 
         # Uncomment to produce a universal binary
         # set(CMAKE_OSX_ARCHITECTURES arm64 x86_64)
@@ -62,7 +61,7 @@ option(JUCE_ENABLE_MODULE_SOURCE_GROUPS "Enable Module Source Groups" ON)
 
 include(cmake/CPM.cmake)
 CPMAddPackage("gh:Neargye/magic_enum#v0.9.7")
-CPMAddPackage("gh:fredemmott/magic_args#v0.2.1")
+CPMAddPackage("gh:CLIUtils/CLI11@2.6.2")
 CPMAddPackage("gh:nlohmann/json@3.12.0")
 
 if(PLUGINVAL_ENABLE_RTCHECK)
@@ -112,7 +111,7 @@ juce_add_gui_app(pluginval
 
 juce_generate_juce_header(pluginval)
 
-target_compile_features(pluginval PRIVATE cxx_std_23)
+target_compile_features(pluginval PRIVATE cxx_std_20)
 
 set_target_properties(pluginval PROPERTIES
     C_VISIBILITY_PRESET hidden
@@ -185,7 +184,7 @@ target_link_libraries(pluginval PRIVATE
     juce::juce_audio_utils
     juce::juce_recommended_warning_flags
     magic_enum
-    magic_args::magic_args
+    CLI11::CLI11
     nlohmann_json::nlohmann_json)
 
 if (${CMAKE_SYSTEM_NAME} MATCHES "Linux")

Source/CommandLine.cpp

@@ -196,20 +196,6 @@ void performCommandLine (CommandLineValidator& validator, const juce::String& co
     auto& app = *juce::JUCEApplication::getInstance();
     const auto tokens = settings_parser::preprocess (commandLine);
 
-    if (tokens.contains ("--help") || tokens.contains ("-h"))
-    {
-        settings_parser::printHelp (app.getApplicationName());
-        app.quit();
-        return;
-    }
-
-    if (tokens.contains ("--version"))
-    {
-        std::cout << settings_parser::getVersionString() << std::endl;
-        app.quit();
-        return;
-    }
-
     if (tokens.contains ("--run-tests"))
     {
         runUnitTests();
@@ -230,10 +216,20 @@ void performCommandLine (CommandLineValidator& validator, const juce::String& co
         return;
     }
 
-    // Otherwise this is a validation run (explicit or implicit --validate)
+    // Otherwise this is a validation run (explicit or implicit --validate).
+    // CLI11 handles --help/--version and parse errors.
     try
     {
-        auto [fileOrID, options] = parseCommandLine (commandLine);
+        const auto result = settings_parser::parseTokens (tokens);
+
+        if (result.handled)
+        {
+            app.setApplicationReturnValue (result.exitCode);
+            app.quit();
+            return;
+        }
+
+        const auto fileOrID = juce::String (result.settings.validatePath);
 
         if (fileOrID.isEmpty())
         {
@@ -242,7 +238,7 @@ void performCommandLine (CommandLineValidator& validator, const juce::String& co
         }
 
         // --validate runs async so will quit itself when done
-        validator.validate (fileOrID, options);
+        validator.validate (fileOrID, result.settings.toPluginTestOptions());
     }
     catch (const std::exception& e)
     {