codegen: honor x-cli-description for surface-specific flag help (API-488)

[somanshreddy]

Scope

Surfaces: CLI (codegen) | Module: Codegen

Description

Generated CLI flag help currently reuses the HTTP API field description verbatim. This is misleading whenever a field has a per-surface default override. The canonical case is aspect_ratio: the HTTP API default is 16:9 but the CLI default is auto (via the existing x-cli-default extension), yet --help still reads "Defaults to 16:9," misleading both humans and agents.

This teaches codegen to honor a surface-specific help override on a schema property. When the property carries the extension, codegen uses it as the flag's Help; when absent, it falls back to the existing description (current behavior, unchanged).

Extension name: x-cli-description. This mirrors the sibling x-cli-* extensions the codegen already reads (x-cli-default, x-cli-visible, x-cli-action, x-cli-category) and keeps the same x-cli-<concept> naming style. The parsing/lookup follows the exact pattern of schemaCliDefault: a small schemaCliHelp helper that reads s.Extensions["x-cli-description"], type-asserts to string, and otherwise returns s.Description. It is wired into all three flag-help sites (query params, multipart fields, JSON body fields).

The override applies only to flag help. The --request-schema / --response-schema output stays faithful to the raw API description, since those expose the actual API contract.

The production OpenAPI spec (in experiment-framework) does not yet carry x-cli-description; adding it there is a separate EF-side change. This PR is the CLI-repo half only.

Testing

• Extended the codegen golden fixture (codegen/testdata/mini_spec.json): the color property now carries both a description and an x-cli-description override. The regenerated golden (codegen/testdata/golden/widget.go) shows the flag Help using the override while RequestSchema keeps the raw API description, proving both override and faithful-schema behavior.
• Added TestSchemaCliHelp covering precedence: extension wins over description, fallback to description when absent, non-string extension falls back, and unrelated extensions are ignored.
• make build and make test (golden + unit suites) pass.

[somanshreddy]

Closing in favor of #169. We decided the API spec (EF) will not own CLI-surface descriptions: surface framing belongs to the surface, and the source of truth in EF stays the API contract. #169 implements CLI-curated description overrides as a runtime overlay in cmd/heygen (the established columns.go/poll-config pattern), which is the chosen single mechanism. The 'x-cli-description' spec-extension consumer here would have no data source, so it's being dropped to avoid maintaining a second, unused override path. The default-value divergence (e.g. aspect_ratio 16:9 vs auto) remains owned by the existing x-cli-default mechanism. Salvaging the CONTRIBUTING doc for the existing x-cli-* extensions into #169.