feat(aviator): 2287147/2453546 accept application name or id in aviator app commands and help having examples

[anishkumarnagaraj-design]

Summary

This PR contains two independent changes, one per commit, for the Aviator commands.

1. Admin app commands accept application name or ID 2287147

fcli aviator app get|update|delete|add-entitlement now accept either an application name or an ID.

• A numeric value is treated as an ID and passed straight to the server, with no extra RPC. This keeps the existing behavior unchanged.
• A non-numeric value is treated as a name and resolved client-side through the existing listApplication call. A clear error is shown if no application matches.
• User-facing --app options (audit, correlate, bulk actions, and CI actions) are not changed. They stay name-only, because those actions derive the name from the SSC application or version name and numeric names are possible.
• Help text uses a shared description that states: "numeric values are always interpreted as an application id".

Why this approach

Backward compatibility comes first, so lookup for existing inputs does not change. Making the commands consistent with the rest of fcli would require a notation or option change, for example id: / name: prefixes, which is better addressed in fcli v4.x. The considerations are documented in the decision record, which I will attach to the ticket.

2. Usage examples and required-option info in command help 2453546

Aviator command help now shows a description, syntax, required and optional parameters, and examples.

Added an Examples: section and a "Required option(s): ..." sentence to the help of all non-deprecated, runnable Aviator commands:

• admin-config
• session
• app
• connection
• token
• entitlement
• SSC commands

Examples follow the existing apply-remediations format, stay within 80 columns, and break long commands with an indented continuation line.
The deprecated entitlement list and ssc audit commands are left unchanged.

Tests

AviatorAppHelperTest and AviatorAppResolverMixinTest cover:

• Numeric IDs passing through without an RPC.
• Name resolution.
• No match scenarios.
• Ambiguous and edge-case values.

AviatorHelpExamplesTest (fcli-app) checks every non-deprecated Aviator command. It verifies that:

• An Examples: section is present.
• Every example parses against the real command definition, so wrong option names, missing required options, and invalid combinations fail.
• Example lines fit within the help width.
• Required options are mentioned in the description.

:fcli-core:fcli-aviator:test and :fcli-core:fcli-app:test pass.

Notes

• Both commits target feat/v3.x/aviator/27.1, so there is no change to the release flow.
• No proto or server changes are needed. The server RPCs take a numeric ID only, so name lookup remains client-side.
  Follow-up for fcli v4.x:
• Introduce a consistent id: / name: notation across all commands.
• Consider an optional required-option marker in help output.

[anishkumarnagaraj-design]

Tested

[anishkumarnagaraj-design]

aviator-name-or-id-decision-record.md