commands-api-ADR-001 — Brigadier Bridge via commands-api Adapter Layer¶
(Renumbered from project-wide ADR-014 on 2026-05-05 when subproject ADRs were given per-directory numbering. Prior commits and historical references may still say "ADR-014".)
Status: Accepted Date: 2026-04-17
Context¶
RTP's command tree is defined once in commands-api and executed on Bukkit-family platforms via a Bukkit command dispatcher. Fabric uses Minecraft's native Brigadier command system.
Duplicating the command structure in Brigadier terms across platforms forces any change to the command tree (new subcommand, renamed argument, permission change) to be applied in multiple places. This causes divergence. The commands-api module shall be the unified, platform-agnostic command framework and the single source of truth.
Decision¶
A BrigadierCommandAdapter inside commands-api shall be provided to convert the commands-api tree into Brigadier nodes. Platform adapters (e.g., rtp-fabric) shall be thin registration shims that delegate to this adapter. The adapter shall carry a compileOnly dependency on Brigadier and shall not load on Bukkit platforms.
For implementation and code-level details, see DESIGN.md — Brigadier Bridge.
Consequences¶
-
Positive:
- Single source of truth for the RTP command tree across all platforms.
- Adding a new subcommand or changing permissions requires one edit in
commands-api, automatically reflected on both Bukkit and Fabric. rtp-fabric's command registration code is reduced to a few lines.- Brigadier's client-side tab completion is available for free since the adapter produces correct argument nodes.
-
Negative / Trade-offs:
commands-apicarries acompileOnlydependency on Brigadier. This is acceptable because Brigadier is a stable, MIT-licensed library bundled with every Minecraft server; it does not add a runtime dependency for Bukkit users.- The adapter maps
commands-apiargument types (string, player, integer, etc.) to Brigadier argument types. This mapping is updated ascommands-apievolves. - Brigadier's
CommandContextandcommands-api's execution context are different types; the adapter bridges them without leaking Brigadier types intocommands-apicore interfaces.
References¶
commands-api/src/main/— command tree definitionplatforms/rtp-fabric/src/main/java/.../fabric/commands/RTPCmdFabric.java— registration shim- MULTI_PLATFORM_PLAN.md section Phase 3
- ARCHITECTURE.md — dependency rule:
rtp-coreandrtp-apido not import platform-specific classes (ArchUnit-enforced)
Addendum — 2026-05-06: Recursion contract, sibling chaining, and suggestion-relevance split¶
The original adapter walked sub-commands recursively but treated parameters as
leaves. On Brigadier (Fabric, planned Velocity) that is insufficient: Brigadier
needs an explicit graph edge for every reachable token, so anything past the
first parameter (/rtp region <r> shape <s> vert <v>, sibling parameters,
nested CommandParameter.subParams) was unreachable for tab-completion. The
Bukkit dispatcher is unaffected because it parses the wire format itself rather
than walking a node graph.
Source: docs/dev/scratch/CHECKLIST-fabric-tabcompletion-audit.md (delete on
merge).
Recursion contract¶
After building each RequiredArgumentBuilder for parameter paramName,
BrigadierCommandAdapter.attachChildren shall additionally attach two kinds of
children to that argument node before returning it to the parent builder:
- Nested parameters — every entry in
CommandParameter.subParams(paramName)shall be attached as a furtherRequiredArgumentBuilderchild of the current node, with the same suggestion / permission plumbing as a top-level parameter. - Sibling parameters — every other entry in the current
TreeCommand'sgetParameterLookup()shall be attached as a further child, mirroring Bukkit's free-token wire format (/rtp region:R biome:B world:Waccepted in any order).
Both forms recurse through the shared attachParameterChildren helper.
Cycle guard¶
Sibling-chaining is naturally cyclic (region → world → region → …). The
adapter carries a path-local Set<String> paramsSeen and excludes any
parameter whose name is already in the set. This bounds Brigadier-tree fanout
at O(N!) for N distinct parameter names on a single tree, which for the
production RTPCmdFabricRoot (4 top-level params + 5 nested under region)
stays well under the 64-node bound asserted by BrigadierTreeShapeTest.
Non-goal: sub-commands after parameters¶
Sub-commands shall not be attached as children of an argument node.
Bukkit semantics treat sub-commands as positional literals at the head of
args[], and the wire format reconstructed by reconstructArgs reflects that.
The adapter mirrors the Bukkit contract by attaching sub-commands only when
paramsSeen.isEmpty(). BrigadierTreeShapeTest#subCommandNotReachableAfterParameter
pins this.
Suggestion-relevance split¶
CommandParameter#isRelevant doubles as both the execute-time validator and
the suggestion filter via relevantValues(UUID). On Fabric pre-fabric-permissions-api
(FabricRTPPlayer.hasPermission falls back to op-level≥2), a non-op caller's
isRelevant returns false for every per-value permission check
(rtp.regions.<r>, rtp.worlds.<w>, rtp.biome.<b>), so suggestion lists go
empty even though the node is reachable through the permissive
BrigadierBridgeContext.
The addendum splits the two roles:
- A new protected hook
CommandParameter#isSuggestionRelevant(UUID, String), default-permissive (returnstrue), drivesrelevantValues(UUID). Subclasses that want permission-filtered suggestions on Bukkit shall override it to delegate toisRelevant. - Execute-time validation continues to flow through
isRelevantviaTreeCommand.onCommand's parameter-value gate. This is an unchanged authorisation contract. TreeCommand.expandRegexTokenshall filter throughisRelevantdirectly (notrelevantValues), preserving the security invariant pinned byRegexParameterSecurityTest(S-INJ-1 .. S-INJ-18). Mixing the suggestion hook into regex expansion would let areg:.*token surface unauthorised values.
Information-disclosure trade-off¶
A non-op Fabric player will see region / world / biome names they cannot teleport
to. This is acceptable for the Step F window (smoke-testing, op-only servers)
and is revisited when fabric-permissions-api lands and FabricRTPPlayer.hasPermission
becomes reliable. Validation on execute is unaffected — typing an unauthorised
value still routes through msgBadParameter.
Test coverage¶
commands-api/src/test/java/.../brigadier/BrigadierTreeShapeTest.java— asserts: sub-command-with-param reachable; sibling chain reachable; nestedsubParamschain reachable; cycle guard rejects repeated parameter on any path; sub-command not attached after a parameter; total node count bounded.rtp-core/src/test/java/.../commands/RegexParameterSecurityTest.java— unchanged tests; still green after theexpandRegexTokenreroute throughisRelevant.commands-api/src/test/java/.../brigadier/ReqApiArch005BrigadierBridgeTest.java— unchanged; verifies the Bukkit-parity wire-format reconstruction.
Silent failure isolation (2026-05-06 follow-up)¶
Field report from a Fabric 1.21.11 op-only test server: even with the
recursion / sibling-chain / suggestion-relevance fixes above, the base
/rtp was rendering with no tab-completion in-game. Root cause: the
adapter walked the whole tree under a single try/catch-free traversal,
so any throw inside one subcommand's lookup, parameter setup, suggestion
provider, or requires() predicate aborted the entire toBrigadier
call — leaving the dispatcher with a partially-built (often empty) tree
and no log line to attribute the failure.
The adapter now isolates each "attach" site:
- Per-subcommand attach —
attachChildren's sub-command loop wraps the body intry/catch(Throwable). A throwing subcommand is logged atWARNING(withparentandkey) and skipped; siblings + the base literal still register. - Per-parameter attach — same envelope around the top-level
parameter loop in
attachChildrenand the recursiveattachParameterChildrenhelper. - Suggestion provider — the lambda returned by
suggestionsFromwrapsparam.relevantValues(callerId)intry/catch(Throwable). Brigadier silently swallows exceptions from suggestion futures, so without this guard a single throwingvalues()(e.g. NPE becauseRTP.serverAccessoris not yet bound on early init, or a Bukkit-only call sneaking into a platform-neutral override) deletes the suggestion list with no diagnostic. The catch logs atWARNINGand returns the partial builder. requires()predicate —applyRequireswraps theBrigadierBridgeContext#permissionCheckinvocation intry/catch(Throwable). A throwing predicate (e.g. a fabric-permissions-api lookup that NPEs on the integrated-server console source) now denies the node (matching Brigadier's "requires fail = node hidden" semantics) and logs, instead of propagating out of the dispatcher's tree-walk and corrupting later nodes.
The contract is: a throw in any one subtree must not strip a sibling
subtree, must not strip the base literal, and must always leave a log
trail. BrigadierTreeShapeTest adds three regressions:
throwingSubcommandIsIsolated, throwingParameterIsIsolated, and
throwingSuggestionProviderIsIsolated.
Cross-references¶
docs/dev/MULTI_PLATFORM_PLAN.md— Step G2 ticked when this addendum lands.docs/dev/TRACEABILITY.md— new row referencingBrigadierTreeShapeTest.