DAOS-19440 ddb: Fix --db_path/--vos_path placement inconsistency

[knard38]

Description

The ddb CLI requires --db_path/--vos_path to be placed before the subcommand name for most subcommands (ls, rm, value_dump, etc.), but after the subcommand name for pool-lifecycle subcommands (rm_pool, open, feature, dev_list, dev_replace, prov_mem). For example:

# Pool-content command: flags go before the subcommand.
ddb --db_path /path/to/sys/db --vos_path /path/to/vos-0 ls

# Pool-lifecycle command: flags go after the subcommand instead.
ddb rm_pool --db_path /path/to/sys/db /path/to/vos-0

This asymmetry is confusing to users and adds unnecessary special-casing to test code that drives ddb (raised independently by @makito while investigating rm_pool usage in MD-on-SSD recovery tests).

dev_list, dev_replace, prov_mem, and smd_sync had a second, related inconsistency: db_path was declared as a positional argument rather than a flag, unlike open/feature/rm_pool.

This is a distinct, follow-up design/UX issue from DAOS-19122 / #18466, which fixed a crash caused by the same underlying flag-name collision but left the resulting per-subcommand placement rules in place.

Solution

1. Normalize db_path to a -p/--db_path flag for dev_list, dev_replace, prov_mem, and smd_sync, matching the flag already used by open/feature/rm_pool. This is an intentional, breaking CLI change for these four commands: the old positional syntax now fails with a clear grumble usage error instead of silently misinterpreting arguments. No C-layer changes are needed — the Go wrapper functions in commands_wrapper.go already take dbPath as a plain string regardless of whether the caller reads it from a flag or a positional argument.

2. Reject --vos_path/--db_path outright (instead of silently ignoring them, which is what happens today) when a pool-lifecycle command (open, close, feature, rm_pool, dev_list, dev_replace, prov_mem, smd_sync) is given as a single bare command directly on the CLI. These commands manage their own pool open/close/remove/replace lifecycle and take their own path argument/flag directly, so silently ignoring the top-level flags left users wondering why they had no effect:

   # Rejected: rm_pool manages its own pool lifecycle and does not accept the top-level flags
   # as a bare command.
   ddb --db_path /path/to/sys/db --vos_path /path/to/vos-0 rm_pool
   # ERROR: ddb: "rm_pool" manages its own pool lifecycle and does not accept
   # --vos_path/--db_path as a single bare command; provide its path directly to "rm_pool"
   # (see 'ddb rm_pool --help'), or use --vos_path/--db_path only in interactive or -f
   # command-file mode to pre-open a pool
   
   # Works: provide rm_pool's own db_path flag and path argument directly.
   ddb rm_pool --db_path /path/to/sys/db /path/to/vos-0

   close is included in the rejection with no exception: an "open+close health check" use case was considered but found redundant with the existing pool-content auto-open/auto-close behavior (ddb --vos_path X ls already performs an equivalent open-then-close, with more useful output).

Pool-content commands (ls, rm, value_dump, ...), interactive mode, and -f command-file mode are unchanged: the top-level --vos_path/--db_path continue to auto-open the pool before the command runs, exactly as before.

Documentation

• ddbLongDescription (general --help) and each pool-lifecycle command's LongHelp now document the pool-content vs. pool-lifecycle distinction and the new rejection rule.
• A new POOL-CONTENT VS. POOL-LIFECYCLE COMMANDS section was added to the ddb man page (see attached ddb-manpage.pdf), alongside the existing MD-ON-SSD MODE section.
• README.md was updated with the same explanation and a rejected/works example.

Testing

• Full src/control/run_go_tests.sh suite (-race -cover -tags fault_injection,test_stubs,spdk).
• main_test.go/ddb_commands_test.go extended/reworked to cover: pool-content commands still auto-opening (regression), all 8 pool-lifecycle commands rejecting the top-level flags with the new error as a bare command, pool-lifecycle commands using their own arguments directly still working unchanged, and -f command-file mode still accepting the top-level flags without triggering the new rejection.
• Live end-to-end testing on a DAOS cluster (MD-on-SSD config), covering the same four behavior points against the built binary.
• ddb_utils.py's DdbCommand.prov_mem() updated to the new --db_path flag syntax — the only ftest/Python caller of any of the four converted commands.

Steps for the author:

• Commit message follows the guidelines.
• Appropriate Features or Test-tag pragmas were used.
• Appropriate Functional Test Stages were run.
• At least two positive code reviews including at least one code owner from each category referenced in the PR.
• Testing is complete. If necessary, forced-landing label added and a reason added in a comment.

After all prior steps are complete:

• Gatekeeper requested (daos-gatekeeper added as a reviewer).

[github-actions]

Ticket title is 'ddb: --db_path flag placement is inconsistent across subcommands'
Status is 'In Progress'
https://daosio.atlassian.net/browse/DAOS-19440

[daosbuild3]

Test stage Functional Hardware Medium MD on SSD completed with status FAILURE. https://jenkins-3.daos.hpc.amslabs.hpecorp.net//job/daos-stack/job/daos/view/change-requests/job/PR-18862/2/execution/node/1757/log