Refactor CLI Tools to be independent of commons-cli

[janhoy]

As a praparatory step before porting the remaining CLI tools to picocli (SOLR-17697), this PR refactors some tools to not depend on commons-cli specific method arguments, e.g. CommandLine. This also typically factors out business logic in separate methods, which is a best practice regardless.

This PR will land on main and branch_10x, and then the work to implment picocli support for them in the picocli feature-branch will become much more targeted.

This PR covers the tools not already refactored as part of #3254. Each tool has its own commit in this PR. All unit tests and existing BATS tests pass.

Disclosure: The code is developed by Claude Code with Fable 5 model. Ran one pass of self-code-review with a few findings before commit.

[Copilot]

Pull request overview

This PR refactors several bin/solr CLI tools to reduce direct dependence on commons-cli-specific APIs (e.g., CommandLine) by introducing parser-independent parameter records and extracting business logic into methods that accept those params. This supports the ongoing effort to port remaining tools to picocli (SOLR-17697) by making the eventual parser swap more localized.

Changes:

• Introduce *Params records (and related helper methods) to decouple command execution logic from commons-cli parsing.
• Refactor multiple tools to build params in runImpl(...) and delegate to parser-independent methods (e.g., snapshot tools, post, run_example, healthcheck, api).
• Adjust StreamTool field parsing API and update its unit test accordingly.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
solr/core/src/test/org/apache/solr/cli/StreamToolTest.java	Updates test to use the new StreamTool.getOutputFields(String) signature.
solr/core/src/java/org/apache/solr/cli/StreamTool.java	Introduces StreamParams, extracts expression reading/validation, and removes CommandLine coupling from output-field parsing.
solr/core/src/java/org/apache/solr/cli/SnapshotListTool.java	Adds SnapshotListParams and delegates to a params-based method.
solr/core/src/java/org/apache/solr/cli/SnapshotExportTool.java	Adds SnapshotExportParams and delegates to a params-based export method.
solr/core/src/java/org/apache/solr/cli/SnapshotDescribeTool.java	Adds SnapshotDescribeParams and delegates to a params-based describe method.
solr/core/src/java/org/apache/solr/cli/SnapshotDeleteTool.java	Adds SnapshotDeleteParams and delegates to a params-based delete method.
solr/core/src/java/org/apache/solr/cli/SnapshotCreateTool.java	Adds SnapshotCreateParams and delegates to a params-based create method.
solr/core/src/java/org/apache/solr/cli/RunExampleTool.java	Adds RunExampleParams, extracts directory initialization, and routes execution via params-based methods.
solr/core/src/java/org/apache/solr/cli/PostTool.java	Adds PostToolParams and delegates posting logic via a params-based method.
solr/core/src/java/org/apache/solr/cli/PostLogsTool.java	Adds PostLogsParams and delegates to a params-based runCommand.
solr/core/src/java/org/apache/solr/cli/PackageTool.java	Refactors subcommand dispatch into parser-independent methods per subcommand.
solr/core/src/java/org/apache/solr/cli/HealthcheckTool.java	Adds HealthcheckParams and delegates cloud execution via params.
solr/core/src/java/org/apache/solr/cli/ExportTool.java	Adds ExportParams and delegates export logic via a params-based method.
solr/core/src/java/org/apache/solr/cli/ConfigTool.java	Adds ConfigParams and delegates config update logic via params.
solr/core/src/java/org/apache/solr/cli/ClusterTool.java	Adds ClusterParams and delegates property setting via params.
solr/core/src/java/org/apache/solr/cli/AssertTool.java	Replaces static mutable state with instance state and adds AssertParams for parser-independent execution.
solr/core/src/java/org/apache/solr/cli/ApiTool.java	Adds ApiParams and delegates API call execution via params.

---

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

[epugh]

I think copilot things are legit. Best part of this is that it establishes a single strong pattern across ALL tools, espeically if we tweak PackageTool a bit!

[epugh]

I asked Github Copilot "are there any other standardizations that can be made across all the various *Tools so they work the same? I know PackageTool for example has a unique printGreen method that we can migrate to just echoIfVerbose or another shared method. How can we make all the Tools follow the same patterns?" and it gave me quite a few things that could be done to make all the tools work the same. Maybe for a seperate PR....

[dsmiley]

As a praparatory step before porting the remaining CLI tools to picocli (SOLR-17697), this PR refactors some tools to not depend on commons-cli specific method arguments, e.g. CommandLine.

I'm missing the point/value of this PR. Why is it worthwhile to decouple the tool from the CLI framework? They live very much together.

I see some use of records here containing lots of values, which means calling a record constructor with very high "arity". The reader (me) has to take it on faith that Xth argument is what we think it is. Ah a string... surely that can't be confused with any other string ;-) Unfortunately java doesn't suppoert naming the parameter at the call-site.

[janhoy]

I'm missing the point/value of this PR

See description. Instead of blowing up the picocli PR with all this mechanical restructuring of tools, the picocli migration will be much cleaner to review when done on top of this one.

We'll end up with only one CLI framework, as commons-cli will go away eventually, but the value is not supporting more than one cli framework at the same time, but making the tools better structured and easier to follow. Many tools have a huge method doing all the work which was never a good design.

Yea, wish java had named args already. Perhaps we could revisit some of the larger records here, split by usecase or revisit types?

[janhoy]

Addressed the arity concerns in some records in the three latest commits, taking different approaches depending on the tool:

• AssertTool (13 → 5 args): the nine assertion flags are now a List<Assertion> — a sealed interface with one small record per assertion kind, run via an exhaustive switch. Call-sites read new Assertion.DirExists(dir) etc.
• RunExampleTool (12 → 7/4/5): split into mode-specific RunExampleParams / CloudExampleParams, both embedding a shared StartSolrParams with the fields startSolr actually uses.
• PostTool (13 → 8): grouped into smaller self-describing records: ContentOptions, CrawlOptions, UpdateOptions.

The remaining records are ≤8 components of mostly independent options, left as-is.

[janhoy]

@dsmiley tagged you for review since you commented on the usability of the records. I believe the latest improvement gives more maintainable code.