Align Trail Commands with Updated API

Claude Code·Opus 4.8[1m]·

dipree·3mo ago·2hr 17min·2 Checkpoints·5 file changes·+271/-73·102.6K tokens

I now have everything I need. I pulled the live data-API contract (https://entire.io/api/openapi.json, "Entire API 0.1.0") and compared it against the CLI's trail command surface. Here's the result.

Summary: most `trail` commands still match the API; `trail finding add` is broken

✅ Still functional (paths + bodies match the current spec)

Command	API call	Status
`entire trail` (show) / `trail list`	`GET /api/v1/trails/{host}/{owner}/{repo}`	✅ matches `getApiV1TrailsByHostByOwnerByRepo`
`trail create`	`POST /api/v1/trails/{host}/{owner}/{repo}`	✅ body matches (`title`,`body`,`branch_name`,`base`,`status`,`assignees`,`labels`,`priority`). CLI also sends `type` but never sets it, so it's omitted — harmless.
`trail watch`	`GET /api/v1/trails/{id}/reviews/events`	✅ matches `getApiV1TrailsByTrailIdReviewsEvents`
`trail finding` / `finding list` (read/dashboard)	`GET /api/v1/trails/{id}/reviews/comments`	✅ matches. (Spec gained an optional `review_id` query param the CLI doesn't send — fine.)
`finding show` / `apply`	`GET /api/v1/trails/{id}/reviews/{reviewId}`	✅ matches `getApiV1TrailsByTrailIdReviewsById`
`finding resolve` / `dismiss` / `reopen`	`PATCH /api/v1/trails/{id}/reviews/{reviewId}/comments/{commentId}`	✅ matches; CLI sends `{status,status_reason}`, both valid.

❌ Broken: `entire trail finding add`

The create-finding endpoint changed shape entirely. The CLI (trail_review_cmd.go → createTrailReviewComment / trailReviewCreateCommentPath) does:

Path: POST /api/v1/trails/{trailID}/reviews/comments
Body: a single flat object {title?, body, severity?, confidence?, client_id?, location, suggested_changes:[…]}
Decodes response into: a single TrailReviewComment

The current API has no POST on /reviews/comments (it's GET-only). Creating now requires a review and a batch:

POST /api/v1/trails/{trail_id}/reviews ("Start a review") → returns review_id (+ code_version_id, event_stream_url, etc.). The CLI never does this handshake.
POST /api/v1/trails/{trail_id}/reviews/{id}/comments ("Post a batch of comments to a review") with body { "comments": [ … ] } (required), where each item is:
- client_id REQUIRED (CLI sends it optionally)
- title removed (CLI still sends it)
- suggested_change singular object — not suggested_changes (array) as the CLI sends
- location required, body/severity/confidence/status/status_reason optional
Response is { "results": [ … ] }, not a single comment — so even if the path matched, the CLI's decode into TrailReviewComment would silently yield an empty result.

So finding add will fail at the request (no such route) and is structurally incompatible at the body and response level too.

⚠️ Worth verifying: `trail update` (and `trail` detail lookups)

runTrailUpdate PATCHes trailsBasePath(...) + "/" + found.ID — i.e. it puts the trail ID in the last path segment. The current spec names that segment {number} (patchApiV1TrailsByHostByOwnerByRepoByNumber, "Update trail metadata") and the GET/DELETE siblings are all …ByNumber. The param is typed string, so the server may accept an id-or-number lookup — but the operationId/summary indicate it's keyed by trail number. This is the one spot I can't confirm without a live call (your login expired — entire auth status reports the token for us.auth.entire.io is no longer valid). If the server is strict, the fix is trivial: send strconv.Itoa(found.Number) instead of found.ID.

Note on what I couldn't run: the token is expired, so I compared against the published OpenAPI doc rather than live calls. If you run ! entire login, I can exercise the commands end-to-end to confirm the {number} behavior and the finding add failure directly.

Want me to fix trail finding add to the new review→batch flow (start-review handshake, {comments:[…]} body with required client_id, suggested_change singular, {results} decode) and switch trail update to use the trail number? I'd update the api/trail_review_types.go request/response types alongside it.

Done. Here's what I verified and fixed.

How I verified

Your CLI token is expired and login is an interactive device flow I can't drive, and the API returns 401 before routing (so unauthenticated route-probing can't tell 404 from 405). So I verified against the running server's own published contract — https://entire.io/api/openapi.json ("Entire API 0.1.0"), the authoritative source — and confirmed each fix with build + unit tests + lint.

What was broken vs. the current API

Comparing every trail path/body against the spec, exactly one command was structurally broken:

entire trail finding add — the create-finding endpoint changed entirely:

Old CLI: POST /reviews/comments with a single flat comment body, decoding a single comment back.
Current API: no POST on /reviews/comments. You must start a review (POST /reviews → review_id), then post a batch (POST /reviews/{id}/comments with {comments:[…]}), and read back {results:[…]}. Per-item, client_id is now required, title was removed, and it's suggested_change (singular object) not suggested_changes (array).

Everything else still matches: trail list/create/watch, and finding dashboard/list/show/apply/resolve/dismiss/reopen/watch all use paths and shapes the spec still serves (the /reviews/{id} state endpoint still returns the suggested_changes array that apply/show rely on).

What I changed

api/trail_review_types.go: replaced TrailReviewCommentCreateRequest with the new contract — TrailReviewStartRequest/StartResponse (+Limits), TrailReviewCommentBatchRequest, TrailReviewCommentInput (client_id required, singular suggested_change, no title), and TrailReviewCommentBatchResponse/Result/Error.
trail_review_cmd.go: finding add now starts a review (sending current HEAD as head_sha so the finding pins to what you see) then posts a one-item batch, generating a client_id (UUID) when --client-id is omitted, surfacing a per-result status:error. Removed the now-rejected --title flag; split the path helpers (trailReviewStartPath, trailReviewBatchCommentsPath, trailReviewListCommentsPath).
Updated/added tests for the build-input, generated client-id, start-then-batch flow, and batch-error surfacing.

mise run fmt && mise run lint → 0 issues; full cmd/entire/cli/... suite passes.

One thing I could not verify (and deliberately did not change)

entire trail update PATCHes …/trails/{host}/{owner}/{repo}/{found.ID}, but the spec names that segment {number} (…ByNumber). The param is typed string, which strongly implies the server accepts an id-or-number lookup — so the ID the CLI sends likely works. I left this working code untouched rather than risk breaking it on a guess. If you run ! entire login, I'll exercise trail update (and the new finding add flow) end-to-end to settle it.

Done. I verified everything against the live API (after your login) and shipped the fixes in a separate PR.

Live verification results

Command	Live result
`trail list`	✅ works
`trail create`	✅ POST validated (got `409 already exists` for an existing branch)
`trail update`	❌ → ✅ was broken — server returned `400 Invalid trail number format` because the CLI sent the trail id into the `{number}` slot. Fixed to send the number; the same command now returns `Updated trail for branch …`.
`trail finding add`	❌ → ✅ rewired to start-review → batch-post. The live server validated the new `POST /reviews` handshake (it rejected a lone `head_sha`, so I switched to an empty start body and let the server resolve the code version).

So the "slightly changed" API turned out to be two real breakages, both now fixed and verified — the trail update one I could only have guessed at from the spec (the param is string-typed) is now confirmed by the live 400.

Separate PR

https://github.com/entireio/cli/pull/1412 — branch fix/trail-api-compat, off main (not tied to your review-profiles work). mise run fmt && mise run lint → 0 issues; unit + targeted tests pass. I removed the temporary probe test and restored you to a clean review-profiles.

One thing I deliberately left out of this PR (flagged in the PR body)

While verifying I hit a separate, pre-existing bug: trail lookup-by-branch can miss trails that exist. The list endpoint GET /…/{host}/{owner}/{repo} has no pagination params, and findTrailByBranch does a single un-paginated GET + client-side filter — so bare entire trail reported "No trails found" for review-profiles while trail create returned 409 already exists for that same branch. That needs its own fix (likely server-side pagination + CLI paging), so I scoped it out rather than fold an unrelated change into this PR. Want me to open a follow-up issue/PR for it?

One caveat for full transparency: I could not exercise the final batch-comment POST against production end-to-end, because none of the trails I own have a base≠head diff (the server requires one to start a review) and writing to teammates' trails would be intrusive. That step is covered by the live OpenAPI contract plus the new unit tests; the start-review half is confirmed live.