fix: [FME-17257]: point fme.spec.yaml at real v4 FME endpoints

[puthrayaharness]

Summary

fme.spec.yaml pointed every FME command at the wrong API (/v3/..., entity-wrapped responses). Fixed feature_flag against the real /fme/internal/api/v4/... API, then extended the spec with segment, fme_environment, segment:definition, segment:definition_keys using the same pattern.

feature_flag fixes

Issue	Fix
Paths used /v3/feature-flag...	/fme/internal/api/v4/...
GET/list assumed entity-wrapped	Dropped .entity (it.entity.X → it.X)
POST/PATCH responses are entity-wrapped ({"entity":..., "governance":...})	item_expr: it.entity on mutation commands
flags["traffic-type"] parsed as flags.traffic - type under expr-lang	Bracket access
Field drift: killed→isKilled, no modifiedAt on definitions	it.isKilled; created reads it.createdAt
update feature_flag --set description=... had no mutable field	Added mutable_path: description

New resources

Noun	Commands	Notes
segment	list/get/create/update/delete	Addressed by name, like feature_flag
fme_environment	list/get/create/update/delete	Named fme_environment, not environment — that noun/alias belongs to the CD module. Addressed by UUID (it.id), not name
segment:definition	list/get/create/update/delete	Scoped by --env; list has no parent-id requirement (env-scoped, not segment-scoped)
segment:definition_keys	list, execute ...:definition_keys_add/_remove	Response is {"keys": [...], "governance": ...} (no entity) → item_expr: it.keys. Dedicated fields_noun: segment_definition_keys for raw string items

Soft-archive delete confirmed live: DELETE returns 200 with no body; subsequent GET on an archived segment/segment_definition returns 404.

Test plan

Area	Status
go test ./..., modules/har, check:specs:main	✅ pass
pkg/specloader/fme_spec_test.go	✅ new coverage: list/get feature_flag/fme_environment/segment, list segment:definition/segment:definition_keys (incl. --env→environment_id, fields_noun override)
feature_flag full lifecycle, fme_environment CRUD, segment CRUD, segment:definition list	✅ live-verified against qa.harness.io
segment:definition create/update/delete, definition_keys_add/_remove	⚠️ request shape confirmed correct against the merged backend route/DTOs, but blocked by RBAC (403 forbidden) on the test PAT — not exercised end-to-end

Caveats

• segment:definition writes: confirmed against the backend repo that the route (POST/PATCH/DELETE .../segment-definitions/{name}, environment_id query param, keys/keys/remove body/response shapes) matches this spec exactly. The 403s are legitimate RBAC (CREATE/EDIT/DELETE permission on segment-definitions for that project/environment), not a spec or rollout issue — the qa test account needs a role grant to exercise these live.
• Pre-existing gap, not fixed here: update feature_flag:definition --set trafficAllocation=... fails "unknown or read-only field" — MutableFields only reads noun-level fields, not a noun-variant's fields_extra. Needs a registry/spec engine change; out of scope.

Manual verification

harness list feature_flag --profile qa
harness create feature_flag cli-smoke-test --traffic-type user --profile qa
harness execute feature_flag:archive cli-smoke-test --profile qa
harness delete feature_flag cli-smoke-test --force --profile qa

harness list fme_environment --profile qa
harness create fme_environment cli-smoke-env --profile qa
harness update fme_environment <env-uuid> --set production=true --profile qa
harness delete fme_environment <env-uuid> --force --profile qa

harness create segment cli-smoke-segment --traffic-type user --profile qa
harness list segment:definition --env <env-uuid> --profile qa
harness delete segment cli-smoke-segment --force --profile qa

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

Deepak Puthraya seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}