Felis/docs/changes/2026-07-05-felis-migrate-command.md

/felis migrate in-game command (§B3 inherit, Velocity side)

• Type: feature (addition)
• Date: 2026-07-05
• Area: plugins/velocity + plugins/shared — Velocity proxy plugin (Java, compile-verified)
• Commit: c1aa38b — feat(velocity): add /felis migrate to open an account migration (§B3 inherit)
• Task: completes the code-only gap named in internal/api/handlers_account_migrate.go

What it does

Adds the in-game /felis migrate command that a player runs to open an account migration — the first step of handing their owned servers to another account (spec §B3 "inherit", scenario A). The command posts the player's Mojang-verified UUID to the backend, which puts that account into migrate mode (state=initiated). The player then finishes the migration on the web console (prove it's them, name the receiving account, redeem a one-time code).

The Go backend (handleMigrateStart and the web-driven steps 2–4) already existed and was tested; its header comment explicitly named "the /felis migrate command that calls handleMigrateStart" as the code-only gap. This change closes that gap.

Why

Without the in-game command, the migration flow had no entry point — the backend handler was reachable only in theory. /felis migrate is the trustworthy initiator: Velocity has already established the caller's online-mode UUID, so the sensitive proof can be deferred to the web step-up while the in-game command just opens the migration.

Design decisions

• Mirrors the existing command suite verbatim. doMigrate follows doClaim; migrateError follows claimError; migrateStart follows claim/opLoginApprove. No new imports, types, or idioms — every construct already appears in the same files.
• Identity-bound + out-of-limbo, but server-independent. Like claim, it requires a real player past the login limbo (requirePlayer + ensureOutOfLimbo). Unlike claim, it acts on the caller's account, not the server they stand on, so there is no registry/current-server check.
• Expects HTTP 201. migrateStart posts to /api/v1/internal/account/migrate/start and expects 201 Created (handleMigrateStart returns StatusCreated) — not 200 like the other calls. A 201 that does not affirm started:true is treated as a contract breach, not a refusal.
• Error mapping matches the handler's refusals: 404 not_linked → "Link your account on the web console before migrating"; 409 account_retired → "This account can't start a migration (already migrated or retired)"; transport (0) and default → generic retry text.
• Points the player to the console on success. The command only opens the migration, so on success it prints the player web console URL (https://console.<root_domain>, derived from config — never a hardcoded domain) and a one-line description of the remaining steps. A proxy-side logger.info records the initiating username against the UUID (the backend audit only has the UUID).

Files

File	Change
plugins/shared/.../link/FelisApiClient.java	+migrateStart(UUID) — POST mc_uuid, expect 201, affirm started:true
plugins/velocity/.../FelisVelocityPlugin.java	migrate literal in the Brigadier tree; doMigrate handler; migrateError mapper; /felis migrate help line

Verification

Java is not oracle-verifiable via the Go suite, but it is compile-verifiable via the podman gradle toolchain established in #63/#65:

podman run --rm -v plugins:/work -w /work/velocity \
  docker.io/library/gradle:jdk17 gradle --no-daemon compileJava
→ BUILD SUCCESSFUL in 19s   (compiled against real velocity-api:3.3.0-SNAPSHOT)

The change compiles clean against the real Velocity API jar (including the shared FelisApiClient compiled straight into the velocity module). The backend contract it speaks to (handleMigrateStart) is covered by handlers_account_migrate_test.go on the Go side.

Self-review outcome

• ponytail (over-engineering): lean — pure mirror of three existing, compiling methods; no speculative abstraction. Nothing cut.
• correctness: the one contract divergence (201 vs 200) was verified against the Go handler source before writing.