fix: [FME-17257]: point fme.spec.yaml at real v4 FME endpoints by puthrayaharness · Pull Request #111 · harness/cli

puthrayaharness · 2026-08-12T21:41:16Z

Summary

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

Backend later dropped /internal/ from every FME v4 path (/fme/internal/api/v4/... → /fme/api/v4/...); this PR tracks that too.

`feature_flag` fixes

Issue	Fix
Paths used `/v3/feature-flag...`	`/fme/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/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`

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

Engine fixes (surfaced by live testing, not spec-specific)

Bug	Root cause	Fix
`execute segment:definition_keys_remove --keys k1` always errored `flag --keys is required`, even when passed	`buildctx.go`'s required-flag check called `cmdctx.GetString` on every flag regardless of type; `is_array`/`is_multi` flags are stored as `[]string`, so it always read back `""`	Branch the check on `f.IsArray \|\| f.IsMulti` (`GetStringSlice`) vs. scalar (`GetString`); regression test added
`get`/`create`/`update`/`kill`/`restore`/`reallocate` on `feature_flag:definition`, and `get`/`create`/`update` on `segment:definition`, rendered blank `Name`/`Description`/`Traffic Type`/...	These fell back to the base `feature_flag`/`segment` noun fields, which don't describe a definition's shape (only `list` had a `fields_extra` override)	Added dedicated `feature_flag_definition` / `segment_definition` nouns (mirroring the existing `segment_definition_keys` pattern) and wired all affected commands via `fields_noun`
`execute segment:definition_keys_add`/`_remove` rendered blank fields	Same cause as above	`fields_noun: segment_definition_keys`
`update feature_flag:definition --set trafficAllocation=...` → `unknown or read-only field`	Field had no `mutable_path`, and the documented flag name didn't match the field id	Added `mutable_path: trafficAllocation` to the `traffic_allocation` field; corrected the `--set` example to `traffic_allocation`

Test plan

Area	Status
`go test ./...`, `modules/har`, `check:specs:main`	✅ pass
`pkg/specloader/fme_spec_test.go`, `pkg/registry/buildctx_workflow_test.go`	✅ new/updated coverage (path prefix, `fields_noun` overrides, required+array flag)
`feature_flag` full lifecycle (create/get/update/archive/unarchive/delete)	✅ live-verified against `qa.harness.io`
`feature_flag:definition` full lifecycle (create/get/list/update/kill/restore/reallocate/delete)	✅ live-verified
`fme_environment` list/get/update	✅ live-verified. `delete` blocked by a `400 hasDependents` business rule on the account's existing test data — expected, not a spec issue
`segment` full lifecycle, `segment:definition` create/get/list/delete, `segment:definition_keys` list/add/remove	✅ live-verified
`update segment:definition`	⚠️ intermittent `500` from the backend on a minimal, correct merge-patch body (`{"description": "..."}`) — confirmed backend-side, not addressed by this PR

Note: the original 403 forbidden reported on segment:definition writes was not an RBAC gap — it was caused by hitting the (now-removed) /internal/ path variant, which was secured differently. Once switched to /fme/api/v4/..., the same calls succeed with the same PAT and no permission changes.

pkg/spec/fme.spec.yaml declared feature_flag/feature_flag:definition commands against /v3/feature-flag... paths with entity-wrapped JSON, but the live FME API is /fme/internal/api/v4/... and returns flat items with no entity wrapper. Swap the path prefix, drop every it.entity indirection, and fix the killed->isKilled and modifiedAt->createdAt field drift so list and get actually work against the real API. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> AI-Session-Id: 20b23a2d-5d3f-4d25-9879-167a341599d4 AI-Tool: claude-code AI-Model: unknown

CLAassistant · 2026-08-12T21:41:24Z

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.}

…pe flag Live verification against qa.harness.io surfaced two more real-API drifts beyond the read-path fixes in the previous commit: - POST/PATCH responses for feature_flag and feature_flag:definition wrap the resource in {"entity": {...}, "governance": {...}}, unlike the flat GET/list shape. item_expr now reads it.entity on every create/update/ archive/unarchive/kill/restore/reallocate command. - `flags.traffic-type` parsed as `flags.traffic - type` under expr-lang (hyphens aren't valid in identifiers), so create_body_init silently dropped trafficType from the POST body. Switched to bracket indexing (flags["traffic-type"]), matching the convention already used for hyphenated flags elsewhere in the codebase. Also added mutable_path to feature_flag's description field — update feature_flag had zero mutable fields declared, so `--set` always failed with "unknown or read-only field" regardless of path. Verified live: full create/update/archive/unarchive/delete lifecycle for feature_flag, and create/list/get/update/kill/restore/reallocate/delete for feature_flag:definition, against qa.harness.io project puthraya with a disposable flag (cleaned up after). go test ./... and modules/har's suite both pass. Known follow-up not fixed here: `update feature_flag:definition --set trafficAllocation=...` (the example in the command's own help text) still fails — MutableFields only reads noun.Fields, not the definition's fields_extra, so there's no way to expose a definition-specific mutable field without a registry/spec engine change. Out of scope for this mechanical spec fix. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> AI-Session-Id: 20b23a2d-5d3f-4d25-9879-167a341599d4 AI-Tool: claude-code AI-Model: unknown

…n FME v4 commands Extends the v4-shaped fme.spec.yaml with segment (CRUD), fme_environment (CRUD; named to avoid colliding with the CD module's "environment" noun), segment:definition (CRUD, scoped by --env), and segment:definition_keys (list/add/remove) commands, following the same real-API-verified approach used for feature_flag. Live-verified against qa.harness.io: fme_environment and segment full CRUD, and segment:definition list. segment:definition writes and the keys add/remove commands could not be live-verified in this session due to an in-progress backend rollout (PR #12644) causing intermittent 403/405 responses; the request shapes are believed correct based on the 403 responses matching the documented error contract. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> AI-Session-Id: 20b23a2d-5d3f-4d25-9879-167a341599d4 AI-Tool: claude-code AI-Model: unknown

…dation fields_noun belongs on CommandSpec, not nested under endpoint: — the embedded-spec loader rejected the file with strict YAML unmarshaling ("field fields_noun not found in type spec.EndpointSpec"), failing "Build, Test & Validate Specs" in CI. Also suppresses the expected "missing get_id_expr" warning on segment:definition_keys (raw string items have no id), following the same get_id_expr: "-" convention used elsewhere in the repo. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> AI-Session-Id: 20b23a2d-5d3f-4d25-9879-167a341599d4 AI-Tool: claude-code AI-Model: unknown

…ay-flag bug, blank definition fields Backend dropped /internal/ from all FME v4 endpoint paths (/fme/internal/api/v4/... -> /fme/api/v4/...); update all commands and regression tests accordingly. Live end-to-end testing against qa.harness.io surfaced two further bugs: - buildctx.go's required-flag check called cmdctx.GetString on every flag regardless of type, but is_array/is_multi flags are stored as []string in FlagValues, so GetString always returned "" and any required+is_array (or is_multi) flag was permanently rejected as missing. Only segment:definition_keys_remove's --keys combined required+is_array, so this was a latent, previously-unexercised engine bug. Fixed the check to branch on flag type, with a regression test. - get/create/update/kill/restore/reallocate feature_flag:definition and get/create/update segment:definition rendered blank fields (Name, Description, Traffic Type, ...) because they fell back to the base feature_flag/segment noun fields, which don't apply to a definition's shape. Added dedicated feature_flag_definition and segment_definition nouns (mirroring the existing segment_definition_keys pattern) and wired them via fields_noun. Also added fields_noun to segment:definition_keys_add/_remove, which had the same issue, and fixed update feature_flag:definition's --set traffic_allocation (was undocumented/unmapped, causing "unknown or read-only field"). update segment:definition still returns an intermittent 500 from the backend on a minimal, correct merge-patch body — confirmed backend-side, no CLI/spec change addresses it. AI-Session-Id: 20b23a2d-5d3f-4d25-9879-167a341599d4 AI-Tool: claude-code AI-Model: unknown

Rebased onto Deepak's latest harness#111 (public /fme/api/v4 paths, fields_noun definitions, required-array flags). Remaining CLI-only: RFC 7807 detail in API errors, MutableFields includes fields_extra, env-delete help for hasDependents/API tokens. Co-authored-by: Cursor <cursoragent@cursor.com>

puthrayaharness · 2026-08-13T22:17:23Z

@cursoragent review this PR

sawka-harness · 2026-08-17T22:35:00Z

@puthrayaharness looks good! let me know when you want this merged

puthrayaharness · 2026-08-18T02:07:38Z

Our BE changes need to be rolled out. Few of the changes are still pending. Will change from Draft to Ready to review when we are good.

Deepak Puthraya added 3 commits August 12, 2026 15:15

puthrayaharness requested a review from sawka-harness August 13, 2026 21:26

ravindraharness mentioned this pull request Aug 13, 2026

fix: [FME-17257]: public FME v4 paths and CLI gap fixes #113

Draft

2 tasks

Navigation Menu

Uh oh!

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

fix: [FME-17257]: point fme.spec.yaml at real v4 FME endpoints#111
puthrayaharness wants to merge 5 commits into
mainfrom
worktree-fme-spec-fix

puthrayaharness commented Aug 12, 2026 •

edited

Loading

Uh oh!

CLAassistant commented Aug 12, 2026

Uh oh!

puthrayaharness commented Aug 13, 2026

Uh oh!

sawka-harness commented Aug 17, 2026

Uh oh!

puthrayaharness commented Aug 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

puthrayaharness commented Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

feature_flag fixes

New resources

Engine fixes (surfaced by live testing, not spec-specific)

Test plan

Uh oh!

CLAassistant commented Aug 12, 2026

Uh oh!

puthrayaharness commented Aug 13, 2026

Uh oh!

sawka-harness commented Aug 17, 2026

Uh oh!

puthrayaharness commented Aug 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

puthrayaharness commented Aug 12, 2026 •

edited

Loading

`feature_flag` fixes