feat: [FME-19299]: FME CLI — segment_definition membership keys

[apetruccelli]

Description

Adds membership-key management for segment:definition, against the v4 /fme/api/v4/segment-definitions/{name}/keys API.

• list segment:definition:keys <segment-name> --env <env-id> — paginated (offset/limit, max 100), wraps the endpoint's bare string array into {key: ...} for field rendering. The ticket names this execute segment:definition:list-keys, but execute in this CLI never wires up --offset/--limit/--all (only the list verb handler does), and the established feature_flag:definition convention already keeps sub-resource reads on their natural CRUD verb rather than wrapping them in execute. Kept list here to preserve pagination and match that precedent.
• execute segment:definition:add-keys <segment-name> --env <env-id> [--key ...] [--keys-file <path>] [--replace] [--comment] [--title] — POST with repeatable --key, --keys-file, or both, sent as a single request (up to 10000 keys). An optional --replace swaps the whole membership instead of appending (only sent when set, since the endpoint already defaults replace=false), and optional audit --comment/--title are sent only when passed (absent, not null, when omitted).
• execute segment:definition:remove-keys <segment-name> --env <env-id> [--key ...] [--keys-file <path>] — POST to .../keys/remove (not DELETE: the keys travel in a body, and DELETE with a body is unreliable across HTTP clients). Accepts the same --key and --keys-file inputs.
• --keys-file <path> — loads keys from a file, or from stdin with -. Every cell is a key, so one key per line, a single comma-separated row, and multi-column CSVs all work; quoted cells may contain commas. Whitespace is trimmed, blank cells are skipped, and duplicates are dropped (first-seen order kept). A UTF-8 BOM and CRLF line endings are handled. The file must contain only keys (no header row). An empty file is an error, and so is a request with neither --key nor --keys-file (unless --replace is set); more than 10000 keys is rejected before the request is sent.
• Help text — add-keys and remove-keys carry a long: description of the --keys-file format, so harness execute segment:definition:add-keys --help documents it for users and agents.
• Both mutations set no_fields: true — the response is the submitted keys plus a governance result, not a segment, so rendering the segment noun's fields against it previously printed a block of blank labels. The success line reports the number of keys sent.

Covered by unit tests in pkg/specloader/fme_spec_test.go (TestFMESpec_ListSegmentKeys, TestFMESpec_AddSegmentKeys, TestFMESpec_SegmentKeysMutation_NoFields, TestFMESpec_RemoveSegmentKeys, TestFMESpec_AddKeys_MergesKeyAndKeysFile, TestFMESpec_RemoveKeys_KeysFileOnly, TestFMESpec_AddKeys_NoKeysRejected, TestFMESpec_AddKeys_HeaderCountsAllKeys) and in modules/fme/segment_keys_test.go for file parsing, resolution and validation.

Commands

• harness list segment:definition:keys <segment-name> --env <env-id>
• harness execute segment:definition:add-keys <segment-name> --env <env-id> --key <key> [--key <key> ...] [--replace] [--comment <text>] [--title <text>]
• harness execute segment:definition:add-keys <segment-name> --env <env-id> --keys-file keys.csv [--replace] [--comment <text>] [--title <text>]
• harness execute segment:definition:remove-keys <segment-name> --env <env-id> --key <key> [--key <key> ...] [--comment <text>] [--title <text>]
• harness execute segment:definition:remove-keys <segment-name> --env <env-id> --keys-file keys.csv [--comment <text>] [--title <text>]

Testing

Verified live end-to-end against a real qa0 project:

• Add keys with repeatable --key, list reflects them, remove one key, list reflects the removal, and a --replace pass swaps the whole membership.
• --keys-file with a 100-key one-per-line CSV, the same keys as a single comma-separated row, and a file with blank cells, duplicates and a quoted comma: the segment holds each key once and user,with,commas is stored as one key.
• --keys-file - from stdin, --key combined with --keys-file, remove-keys --keys-file, and --replace with a file.
• Empty file, missing file, and no keys given each fail with a clear error and send no request.
• The comment+title requirement is workspace-specific policy (not a general contract): qa0 requires both, while a prod profile accepts the calls with no audit fields.

Acceptance Criteria

• List membership keys for a segment definition, paginated
• Add membership keys, with an optional full-replace mode
• Add and remove many keys from a file (one per line or comma-separated)
• Remove membership keys
• Audit --comment/--title supported and omitted (not null) when not passed
• Unit tests for each operation, verified live end-to-end

Extra test coverage

segment:definition had unit tests for List and Delete but not Get/Create/Update. Added TestFMESpec_GetSegmentDefinition, TestFMESpec_CreateSegmentDefinition, and TestFMESpec_UpdateSegmentDefinition, following the same patterns already used for the segment noun's CRUD tests. No spec changes — test-only addition.