fix(handlers): standardize mutual flag parsing behavior

[Hweinstock]

Problem

CLI handlers hand-roll "mutually exclusive" and "specify exactly one of" flag checks with at least three message formats, so identical failures read differently across commands.

Solution

• Replace assertMutuallyExclusiveInputs with assertMutuallyExclusiveFlags that is general enough to handle all of the mutually exclusive checks we make today.
• Migrate handlers with mutually-exclusive checks onto the shared utility.

Verification

• All handler tests green; changed lines have explicit coverage.

manually tested a migrated case:

$ agentcore  identity api-key-credential-provider create --name x --region us-west-2
Error: specify exactly one of --api-key, --api-key-secret-reference

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

Nice consolidation of scattered "at most/exactly one of these flags" checks into a single assertMutuallyExclusiveFlags helper. I traced each converted call site and the semantics are preserved:

• The old callers of assertMutuallyExclusiveInputs were manually converting false booleans to undefined (e.g., flags["clear-description"] || undefined). The new helper treats both undefined and false as "not set", so the behavior matches without callers needing to normalize.
• The exactlyOne: true option correctly replaces the previous "both required OR both forbidden" branches (e.g., in online-eval/create, online-insight/create, api-key/oauth2 create+update, sessionSource, harness export, payment-connector, gateway-target add). The "required" side is now folded into the same error path (specify exactly one of ...), which is a small user-visible message change already reflected in the updated test regexes.
• The variables hasApiKey/hasSecretRef/hasClientSecret/hasAgent/hasDataSource left behind after the removed branches are still used downstream — no dead code.
• Because the exactlyOne branch fires whenever definedFlags.length !== 1, the "mutually exclusive" branch is unreachable when exactlyOne is set. That's the intended design (produces the specify exactly one message in both the 0-set and >1-set cases), and the unit tests in utils.test.tsx pin that behavior.

The direct unit tests for the helper cover the interesting cases (empty, single set, false-boolean, exactlyOne with 0/1/many, listing only the offending flags in the "mutually exclusive" message). No new telemetry is warranted for a pure refactor.

No changes required.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.05%. Comparing base (4fe2c10) to head (8edd7cb).
⚠️ Report is 1 commits behind head on refactor.

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2263      +/-   ##
============================================
+ Coverage     97.04%   97.05%   +0.01%     
============================================
  Files           566      566              
  Lines         39353    39228     -125     
============================================
- Hits          38190    38073     -117     
+ Misses         1163     1155       -8     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[nborges-aws]

LGTM clean PR