cardano-testnet: Add --nodes flag for per-node binary configuration

[palas]

Description

Adds a --nodes CLI flag to cardano-testnet that allows specifying the role (SPO or relay) and optionally a custom cardano-node binary for each node in the testnet. This enables running testnets with mixed node versions, which is needed for testing compatibility across node releases.

The new flag coexists with the existing --num-pool-nodes via <|> in the parser, so either can be used:

--nodes spo,spo:node-bin=/path/to/custom-node,relay,relay
--num-pool-nodes 3   # unchanged, still works

At creation time, custom binaries are validated by running --version and the result is recorded in a YAML env file (node-data/nodeN/env). At runtime, the env file is read to resolve the binary, falling back to the default resolution when no env file exists.

Base PR: #6563 (enforces SPOs come first and splits node list into SPO and relay)

Checklist

• Commit sequence broadly makes sense and commits have useful messages
• New tests are added if needed and existing tests are updated. These may include:
  • golden tests
  • property tests
  • roundtrip tests
  • integration tests
    See Running tests for more details
• Any changes are noted in the CHANGELOG.md for affected package
• The version bounds in .cabal files are updated
• CI passes. See note on CI. The following CI checks are required:
  • Code is linted with hlint. See .github/workflows/check-hlint.yml to get the hlint version
  • Code is formatted with stylish-haskell. See .github/workflows/stylish-haskell.yml to get the stylish-haskell version
  • Code builds on Linux, MacOS and Windows for ghc-9.6 and ghc-9.12
• Self-reviewed the diff

[carbolymer]

Exception handling is most important here

[Copilot]

Pull request overview

Adds per-node configuration support to cardano-testnet via a new --nodes CLI flag, allowing each node to be designated as SPO/relay and optionally pinned to a specific cardano-node binary (recorded in the generated env and reused when starting from --node-env).

Changes:

• Introduces --nodes SPEC[,SPEC...] parsing (with role ordering validation and optional node-bin= path) and updates CLI help golden files.
• Extends testnet node configuration types to carry an optional per-node binary path, and persists that choice into node-data/nodeN/env.
• Updates node startup to optionally use a custom binary via a new procCustom helper and a startNode signature change.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
cardano-testnet/test/cardano-testnet-test/Cardano/Testnet/Test/Node/Shutdown.hs	Updates test to new node options type (NodeWithOptions).
cardano-testnet/test/cardano-testnet-test/Cardano/Testnet/Test/Gov/ProposeNewConstitutionSPO.hs	Updates test to new node options type (NodeWithOptions).
cardano-testnet/test/cardano-testnet-test/Cardano/Testnet/Test/Cli/LeadershipSchedule.hs	Updates test node creation + startNode call to pass optional custom binary.
cardano-testnet/test/cardano-testnet-test/Cardano/Testnet/Test/Cli/KesPeriodInfo.hs	Updates startNode call to pass optional custom binary.
cardano-testnet/test/cardano-testnet-golden/files/golden/help/create-env.cli	Updates golden help output to document --nodes.
cardano-testnet/test/cardano-testnet-golden/files/golden/help/cardano.cli	Updates golden help output to document --nodes.
cardano-testnet/test/cardano-testnet-golden/files/golden/help.cli	Updates top-level golden help usage to show --nodes alternative.
cardano-testnet/src/Testnet/Start/Types.hs	Replaces exported node option types with NodeWithOptions/TestnetNodesWithOptions and adds nodeBin.
cardano-testnet/src/Testnet/Start/Cardano.hs	Writes/reads per-node env YAML for custom binaries; threads nodeBin into node startup.
cardano-testnet/src/Testnet/Runtime.hs	Extends startNode to accept an optional custom node binary.
cardano-testnet/src/Testnet/Process/RunIO.hs	Adds procCustom helper for running an explicitly provided binary path.
cardano-testnet/src/Parsers/Run.hs	Uses new readNodesWithOptionsFromEnv reader.
cardano-testnet/src/Parsers/Cardano.hs	Adds --nodes flag and Parsec-based parseNodeSpecs implementation.
cardano-testnet/src/Cardano/Testnet.hs	Updates re-exports to the renamed node options API.
cardano-testnet/changelog.d/20260506_035740_palas_testnet_specify_node_bin_per_node.md	Adds changelog entry for --nodes.
cardano-testnet/cardano-testnet.cabal	Adds parsec dependency for --nodes parsing.
cardano-node/src/Cardano/Node/Testnet/Paths.hs	Adds defaultNodeEnvFile path helper.
cardano-node-chairman/test/Spec/Chairman/Cardano.hs	Updates chairman test to use the new default node options value.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Jimbo4350]

LGTM; suggested some minor changes. Will have another look after changes/discussion.

[carbolymer]

Looks good to me. I'm leaving approval to @Jimbo4350

addressed major remarks

[Jimbo4350]

LGTM, one minor comment

[palas]

Backed up in: https://github.com/IntersectMBO/cardano-node/tree/backup/testnet-specify-node-bin-per-node