SOLR-17697 Use picocli instead of commons-cli

[janhoy]

https://issues.apache.org/jira/browse/SOLR-17697

This PR is just a way to visualize the status of the feature branch jira/SOLR-17697-picocli.
Create PRs targeting that branch to tackle individual tasks, and then squash merge into this feature branch once done. Then at the end this branch can be merged (not-squash) into main to preserve each tool porting.

Pick a tool not yet converted from the list below. You'll find a useful LLM prompt template in the JIRA issue linked above. Feel free to link your PR number next to the tool line below to signal that you are working on it. Once merged into the feature-branch, check the checkbox.

Tasks/milestones:

• Add framework
• Implement POC for a few initial tools, in parallel with commons-cli
• Solve option inheritance / MixIn
• Solve option mutual exclusivity
• Solve value-fallback to ENV
• Document in RefGuide - see SOLR-17697 Ref-guide documentation for new picocli commands #4271
• Rework the "Control Script Reference" page
•  All tools covered
  • ApiTool
  • AssertTool
  • AuthTool - SOLR-17697: Implement picocli for auth command / AuthTool #4684
  • ClusterTool
  • ConfigSetDownloadTool
  • ConfigSetUploadTool
  • ConfigTool
  • CreateTool - SOLR-17697 Implement picocli for create and delete commands #4269
  • DeleteTool - SOLR-17697 Implement picocli for create and delete commands #4269
  • ExportTool
  • HealthcheckTool
  • PackageTool - SOLR-17697: Implement picocli for package command / PackageTool #4739
  • PostLogsTool
  • PostTool
  • RunExampleTool
  • SnapshotCreateTool
  • SnapshotDeleteTool
  • SnapshotDescribeTool
  • SnapshotExportTool
  • SnapshotListTool
  • StatusTool
  • StreamTool
  • UpdateACLTool
  • VersionTool
  • ZkCpTool
  • ZkLsTool
  • ZkMkrootTool
  • ZkMvTool
  • ZkRmTool
  • ZkToolHelp
• BATS tests green
• Proof read Usage helps
• Remove commons-cli

[xtenzQ]

Actually, I'd like to try to implement PoC for few initial tools.

upd: oh, I didnt notice there is a PR created for this

[janhoy]

upd: oh, I didnt notice there is a PR created for this

Yea, there's an in-progress exploration taking place, feel free to join the discussion about it or POC for yourself on how to solve various issues that arise. We're still trying to land on the most elegant way to introduce things, and I plan to dial down the ambitions for the other PR to do bare minimal for one or two tools, and perhaps the "start" tool. Eventually, when we start getting the grip on how things should flow, it will be easier to jump in and implement PRs for new tools, targeting this branch.

[janhoy]

This branch is now up to date with latest main (~250 commits merged in). All of precommit, the CLI unit tests (org.apache.solr.cli.*), and the create/delete/status/version/zk BATS suites pass — the BATS suites in both default commons-cli mode and with SOLR_PICOCLI=true.

What it took, beyond routine conflict resolution:

• Regenerated all gradle lockfiles (resolveAndLockAll --write-locks plus a precommit --write-locks pass for the jar-check *Copy configurations), and dropped permitUnusedDeclared from test-framework/build.gradle — replaced on main by the opt-in DAGP plugin.
• Adopted main's move away from direct ZooKeeper access: DeleteTool now resolves its target via CLIUtils.getSolrConnection and deletes configsets through the ConfigSets API (echoing "Connecting to Solr at …"); CreateTool uses the new CloudSolrClientConnection API with the isZookeeper() guard for config upload, and only takes the Solr URL from explicit connection options so the live-node fallback works as on main.
• Brought the picocli path to parity with main's --solr-connection change (-s now means --solr-connection, --solr-url is long-only) in ZkConnectionOptions, the create/delete ConnectionOptions, and StatusTool — whose picocli target options are now a mutually-exclusive group mirroring the commons-cli OptionGroup. Connection parsing is string-only; network calls happen only at tool execution time, never during picocli parsing.
• solr --version under picocli now prints Client version: … to match main's new commons-cli output (which also prints Server version: when a connection option is given).
• Small fixes along the way: defaulted picocli --max-wait-secs to 0 (NPE for plain solr status), and relaxed the test_status.bats mutual-exclusion assertion to accept both engines' error messages (same pattern as test_create.bats).

The zk→live-node URL resolution needed by StatusTool was extracted into CLIUtils.solrUrlFromConnection(), proposed separately against main in #4683 to keep non-picocli drift off this branch.

[janhoy]

Please check out #4909 which sits on top of this one. That PR intends to prepare this branch for merge to main and branch_10x already now, before all tools are converted. My motivation is to get what we have out there and simplify work on remaining tool migrations as they can happen as full-blown PRs and land in the next releaase.

As you'll see of that PR description, it is all back compat, users wont notice it is there, and the ref guide changes are moved into its own page with all the new generated man pages as children, so even the ref guide is opt-in for those interested.

[janhoy]

Merged in the other PR, and now this should be ready for inclusion in main, since picocli code is now fully opt-in and the docs are separate, add-only, not edit.

@sigram I't's up to you whether it can also land on branch_10x for 10.1. I'm happy to let it sit on main for a while and then merge to 10x after the 10.1 release.

[janhoy]

@epugh, @jaykay12 The plan now is to

• merge this PR to main (only main for now)
• rebase your in-flight packageTool PR on top of main (sorry)
• create separate JIRA issues for each group of remaining tools still open in this PR description. By group I mean that the Snapshot*Tools should be one JIRA and one PR since they will be related.