cli: entire change command tree (trail → change rename) by khaong · Pull Request #2116 · entireio/cli

khaong · 2026-08-24T17:20:44Z

https://entire.io/gh/entireio/cli/trails/1135

ENT-1890, slice 1 of the trail-containers program. Draft until entire-api #832 (the /changes API surface) merges and deploys — this CLI codes against that surface (verified against its delivered diff, cited as the wire-contract pin in api/change_thread_types_test.go).

entire trail ... → entire change ..., no alias — the trail name is reserved for the container commands shipping with slice 2.
Client paths → /api/v1/changes; response structs use the new JSON spellings (changeId/changeNumber/change).
--target accepts both /changes/ (canonical) and /trails/ (legacy — old URLs live in PR bodies forever), with a round-trip regression test.
TrailsEnabled probe falls back to the legacy path on 404 (TODO ENT-1891), so a CLI released before the server deploy cannot silently self-disable.
Kept deliberately: the internal trail domain package (import-aliased), the --source trail runner vocabulary (dual-read protected upstream), --output trail flag value.

Release order: entire-api #831 → #832 deploy first, then this releases in the same window as entire.io's rename.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JwmZfdSH1YTzB5vmH8RSfL

Note

Medium Risk
Large rename across CLI commands and API wiring with rollout dependency on entire-api #832; the legacy 404 fallback reduces self-disable risk but wrong ordering or incomplete renames could break repo-scoped change workflows until server and client align.

Overview
Renames the user-facing entire trail surface to entire change with no trail alias (the name is reserved for a later container slice). HTTP client code, typed API models, and tests move from /api/v1/trails and Trail* types to /api/v1/changes and Change* types, including ID-based route rewriting via SetChangeRoute.

agent-help and CLAUDE.md now classify and advertise change (still gated on trails enablement for the repo). The enablement probe hits the canonical changes list first and falls back to the legacy trails path on 404 so a newer CLI is not cached as disabled before the API deploy (TODO ENT-1891).

Approval, checkout, and related helpers/tests are renamed to the change vocabulary; the internal trail domain package and some upstream-facing flags (e.g. --source trail) stay as-is per the PR notes.

^{Reviewed by Cursor Bugbot for commit b77e137. Configure here.}

ENT-1890: rename the CLI's `entire trail` command family to `entire change`, matching the client-side half of the trail->change rename (no alias — `trail` is reserved for the slice-2 container commands). Renames trail_*_cmd.go -> change_*_cmd.go (and the api package's wire types trail_types.go/trail_review_types.go/trail_thread_types.go -> change_*.go), the command constructors and their user-facing Use/Short/ Long/error text, and the API path/JSON-field spellings that move with it: /api/v1/trails/... -> /api/v1/changes/..., trailId/trailNumber -> changeId/changeNumber, and the browser link the CLI prints -> /{owner}/{repo}/changes/{n}. The shared cmd/entire/cli/trail domain package (trail.Metadata, trail.Status, ...) is intentionally NOT renamed — it is internal representation, not part of the command's user-facing name, and stays out of this file-rename's scope; the two files that reference it (change_cmd.go, api/change_types.go) import it under a `change` alias so the renamed code reads consistently. This is atomic by necessity (same rationale as the entire-api trail->change PRs): a partial rename leaves half the command tree calling functions the other half just renamed, so it lands as one large, mechanical diff rather than several small ones. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JwmZfdSH1YTzB5vmH8RSfL

Registers newChangeCmd() on root instead of newTrailCmd(), and fixes the handful of call sites in adjacent files that referenced the command tree's now-renamed identifiers: review_bridge.go/runner_gather.go (SetChangeRoute, changeNumberPath, listChangeResources, the ChangeReviewCommentInput/ChangeReviewLocationCreateRequest wire types), review_target.go and resume*.go (resolveChangeBySelector, describeChangeRef, runAuthenticatedChangeAPI, the restored-session helpers), and agent_help_cmd.go's command classification table and "drill into a live command" example, which is keyed by literal command name and so goes stale the moment the name changes underneath it. These files' own local vocabulary (e.g. review_bridge.go's `postReviewToTrail`/`reviewTrailGranularity*`, runner_gather.go's `--source trail` runner-history vocabulary) is intentionally left alone — it names a different, adjacent concept and is out of this rename's scope. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JwmZfdSH1YTzB5vmH8RSfL

Renames the hidden detached-refresh command per the spec (trail is reserved for slice 2's container commands, so nothing named after it should linger, including the hidden ones), and touches up doc/error comments across the tree that named `entire trail ...` as an example of the command family that's now `entire change ...`. trail_context_cache.go's own vocabulary (trailEnablementScope, TrailsEnabled caching, etc.) is deliberately left alone — it is the "are trails enabled for this repo" capability flag shared by several unrelated subsystems (doctor, mcp, setup, agent-help), not part of the `entire trail` command tree, and out of this rename's scope. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JwmZfdSH1YTzB5vmH8RSfL

…change text Review findings on the trail->change rename: - CRITICAL: normalizeReviewTargetSelector (review_target.go) required the URL's 4th path segment to be exactly "trails", but the CLI's own trailReviewWebURL now prints /changes/... links — copy-pasting the CLI's own output back into `--target` was rejected as an "invalid Entire trail URL". Now accepts both "changes" (canonical) and "trails" (legacy spelling that lives in existing GitHub PR bodies forever; entire.io only redirects /trails/ to /changes/ in the browser, never through this parser). Error text and the --target help/flag prose now say "change URL"/"change ID". - MINOR: trail_checkout_worktree.go's cd-hint comment referenced the retired `entire trail checkout`; now `entire change checkout`. - MINOR: review_bridge.go's postReviewToTrail display strings ("Posted the review verdict to trail #%d", "View the trail:") now say "change" (the --output trail flag value itself is untouched, per the review's own scoping). Tests: review_target_test.go gets fixture cases for both URL spellings (TestNormalizeReviewTargetSelector) and a new round-trip test, TestNormalizeReviewTargetSelector_AcceptsGeneratedChangeURL, that builds a URL via trailReviewWebURL and asserts the --target parser accepts it back — the regression pin the review flagged as missing. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JwmZfdSH1YTzB5vmH8RSfL

entire-api's 1b surface (entireio/entire-api#832) confirmed our wire assumptions exactly — /api/v1/changes, changeId/changeNumber tags, {"change": ...} envelopes all match. Final touch-up wave: - api/trails.go: TrailsEnabled cached a 404 from /api/v1/changes as a definitive "disabled" for ~1h (settings.ClonePreferences. TrailsEnabledCheckedAt's TTL). A CLI released ahead of entire-api's 1b deploy would hit exactly that 404 on a repo that actually has trails enabled, and silently self-disable the whole family for an hour. Added a transitional fallback: a 404 from the canonical path now retries the legacy /api/v1/trails path before concluding disabled, marked // TODO(ENT-1891): remove once 1b is deployed everywhere. 403/410 stay definitive negatives with no fallback (a route that exists and says no is not the same as a route that doesn't exist yet). - CLAUDE.md (symlinked from AGENTS.md): the agentHelpAnnotation and hidden-infrastructure-commands examples still named `trail`; now `change`. - runner_gather.go:294's tuning-signal line said "recent trails" over the (already renamed) list.Changes; now "recent changes". - agent_help_cmd_test.go: reworded the GatesTrailOnTrailsEnabled failure message so "change" and "trails enabled" don't read as a naming inconsistency. - api/change_thread_types_test.go: labeled its hand-written wire fixture as the pin for entire-api's delivered 1b contract (PR #832) — the only cross-repo contract fixture in this repo — so it isn't reshaped casually. Tests: api/trails_test.go's TestClient_TrailsEnabled table now tracks every request TrailsEnabled makes (not just the last), covering the 404-then-404 fallback order; new TestClient_TrailsEnabled_FallsBackToLegacyPathOn404 covers the other order (canonical 404s, legacy still serves). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JwmZfdSH1YTzB5vmH8RSfL Entire-Checkpoint: 01M0TCKDSTZB9RDNA7AZ2KSC1P

Copilot

Pull request overview

Renames the CLI “trail” command tree to “change” (reserving trail for upcoming container-focused commands) and updates the CLI’s entire-api integration to use the new /api/v1/changes surface while preserving compatibility with legacy /trails URLs and server rollouts.

Changes:

Replaces entire trail ... with entire change ... across command wiring, help/agent-help classification, and user-facing docs.
Migrates entire-api request paths and wire types from “trail” to “change” (including SSE watch, approvals, threads, reviews, and route rewriting).
Adds compatibility behaviors/tests: accept legacy /trails/ URLs for --target, and fallback probing from /changes → /trails on 404 for enablement detection.

Reviewed changes

Copilot reviewed 53 out of 55 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/architecture/agent-guide.md	Updates agent guide references from `trail` to `change` in context injection behavior text.
cmd/entire/cli/trail_context_cache.go	Renames detached enablement refresh command and routes enablement probing through the change client path.
cmd/entire/cli/trail_collaboration_cmd_test.go	Removes trail-thread collaboration tests (superseded by change equivalents).
cmd/entire/cli/trail_checkout_worktree.go	Updates checkout worktree help text to reference `entire change checkout`.
cmd/entire/cli/trail_approval_cmd.go	Removes trail approvals commands implementation (superseded by change equivalents).
cmd/entire/cli/testutil/testutil.go	Updates testutil commentary to reference `entire change` as the forge-detection example.
cmd/entire/cli/setup_report_enabled_test.go	Updates comments around enablement probe routing to `/api/v1/changes`.
cmd/entire/cli/session/state.go	Updates context injection comment to reference `entire change` pointer.
cmd/entire/cli/runner_gather.go	Switches runner “trails” gather logic to use change APIs and types.
cmd/entire/cli/root.go	Wires `newChangeCmd()` instead of `newTrailCmd()` in the root command.
cmd/entire/cli/review/profile.go	Updates review output documentation to reference `entire change finding`.
cmd/entire/cli/review/cmd.go	Updates `--target` help text to reference change IDs/URLs instead of trail IDs/URLs.
cmd/entire/cli/review_target.go	Updates `--target` URL parsing to accept `/changes/` and legacy `/trails/`.
cmd/entire/cli/review_target_test.go	Updates selector normalization tests and adds round-trip test for generated change URLs.
cmd/entire/cli/review_bridge.go	Updates review web URL generation to the `/changes/` browser path for change targets.
cmd/entire/cli/review_bridge_test.go	Updates review web URL tests to expect `/changes/` URLs and change target types.
cmd/entire/cli/resume.go	Updates restored-session continuation hooks from trail to change variants.
cmd/entire/cli/resume_continue.go	Updates default restore-session prompt/launch helpers to change variants.
cmd/entire/cli/lifecycle_test.go	Updates background refresh command name expectations to `__refresh_change_enablement`.
cmd/entire/cli/checkpoint_policy_warning.go	Excludes `__refresh_change_enablement` from checkpoint policy warnings.
cmd/entire/cli/checkpoint_policy_warning_test.go	Updates tests for the renamed hidden refresh command.
cmd/entire/cli/change_watch_cmd.go	Renames watch command wiring and updates SSE stream path/payload fields to change IDs.
cmd/entire/cli/change_watch_cmd_test.go	Updates SSE tests to use `/changes/` paths and `changeId` payloads.
cmd/entire/cli/change_review_patch.go	Renames patch-anchor/target parsing helpers to change equivalents and updates object-format lookup usage.
cmd/entire/cli/change_repo_flag_test.go	Updates repo-flag parsing and authenticated API routing tests to change equivalents.
cmd/entire/cli/change_helpers_test.go	Updates helper tests for change naming, statuses, and selector parsing.
cmd/entire/cli/change_collaboration_cmd_test.go	Adds change-thread collaboration tests (path builders + output includes IDs).
cmd/entire/cli/change_checkout_cmd_test.go	Updates selector resolution and display tests to change equivalents; updates checkout flag tests.
cmd/entire/cli/change_approval_cmd.go	Adds change approvals commands implementation (approve/request-changes/list).
cmd/entire/cli/change_approval_cmd_test.go	Adds/updates tests for change approvals paths, flags, and rendering.
cmd/entire/cli/cell_target.go	Updates inline docs to reference `entire change` instead of `entire trail`.
cmd/entire/cli/cell_target_test.go	Updates test commentary references from trail to change.
cmd/entire/cli/api/trails.go	Updates enablement probe to prefer `/api/v1/changes` with 404 fallback to legacy `/trails`.
cmd/entire/cli/api/trails_test.go	Updates tests for new probing behavior, route rewriting, and request casing against `/changes`.
cmd/entire/cli/api/trail_types.go	Removes trail resource/approval/types (replaced by change equivalents).
cmd/entire/cli/api/trail_thread_types.go	Removes trail thread wire types (replaced by change equivalents).
cmd/entire/cli/api/trail_review_types.go	Removes trail review wire types (replaced by change equivalents).
cmd/entire/cli/api/client.go	Renames per-resource route rewriting from trailRoutes/SetTrailRoute to changeRoutes/SetChangeRoute.
cmd/entire/cli/api/change_types.go	Adds change resource/list/create/update/body/approval wire types (mapping onto internal `trail` domain types as intended).
cmd/entire/cli/api/change_types_test.go	Updates contract tests to validate change wire types and casing.
cmd/entire/cli/api/change_thread_types.go	Adds change thread wire types.
cmd/entire/cli/api/change_thread_types_test.go	Adds contract-pinning fixtures for change thread payload decoding and update marshaling.
cmd/entire/cli/api/change_review_types.go	Adds change review wire types (state, comments, batches, suggested changes).
cmd/entire/cli/api_client.go	Renames the repo-routed entire-api client seam to `newChangeAPIClient`.
cmd/entire/cli/agent_help_cmd.go	Updates agent-help classification and top-level drill example from trail to change.
cmd/entire/cli/agent_help_cmd_test.go	Updates agent-help gating/advertising expectations from trail to change.
CLAUDE.md	Updates documentation references for hidden command annotation examples and infra command list.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Rename trailReviewWebURL -> changeReviewWebURL and switch the tuning-brief and review-posting output to "change". The --source trails selector, the --output trail mode and the trails-enablement wording stay as they are. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JwmZfdSH1YTzB5vmH8RSfL

khaong · 2026-08-24T17:31:55Z

bugbot run

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 4fde176. Configure here.}

The `api` guidance listed `trail` among the purpose-built commands to prefer. That command no longer exists on this branch and the name is reserved, so an agent following the advice would reach for a command that is not there. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JwmZfdSH1YTzB5vmH8RSfL

khaong · 2026-08-24T18:35:58Z

bugbot run

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit b77e137. Configure here.}

khaong · 2026-08-25T22:57:35Z

HOLD — do not merge, and apologies for handing this over prematurely. The trail→change rename has been reverted in entire-api (3c6cb7bd5, 5f52256f0) and entire.io (beb6c70e8d). /api/v1/changes/... no longer exists on the producer, so this PR's client would target routes that are gone. Back to draft pending a decision on the new vocabulary — steer is trails/subtrails or renaming the container instead.

khaong · 2026-08-25T23:01:47Z

Closing: the entire change command tree targeted /api/v1/changes/..., which no longer exists after the rename revert (entire-api 3c6cb7bd5 / 5f52256f0). Apologies for handing this over for review on a premise that was already being reversed. The CLI's existing trail commands and /trails client paths are correct as they stand. Branch retained.

khaong and others added 5 commits August 25, 2026 02:02

Copilot AI lite review requested due to automatic review settings August 24, 2026 17:20

Copilot started reviewing on behalf of khaong August 24, 2026 17:21 View session

Copilot AI reviewed Aug 24, 2026

View reviewed changes

Comment thread cmd/entire/cli/runner_gather.go Outdated

Comment thread cmd/entire/cli/review_bridge.go Outdated

cursor Bot reviewed Aug 24, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into change-commands

89adf22

khaong marked this pull request as ready for review August 25, 2026 07:31

khaong requested a review from a team as a code owner August 25, 2026 07:31

khaong marked this pull request as draft August 25, 2026 22:57

khaong closed this Aug 25, 2026

Navigation Menu

Uh oh!

cli: entire change command tree (trail → change rename) - #2116

cli: entire change command tree (trail → change rename)#2116
khaong wants to merge 8 commits into
mainfrom
change-commands

khaong commented Aug 24, 2026 •

edited by cursor Bot

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

khaong commented Aug 24, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

khaong commented Aug 24, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

khaong commented Aug 25, 2026

Uh oh!

khaong commented Aug 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

khaong commented Aug 24, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

khaong commented Aug 24, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

khaong commented Aug 24, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

khaong commented Aug 25, 2026

Uh oh!

khaong commented Aug 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

khaong commented Aug 24, 2026 •

edited by cursor Bot

Loading