5.0.2

Full Changelog: 5.0.0...5.0.2

5.0.0

CommandsAPI v5.0.0

🚨 Breaking Changes

• Repository Migration: JitPack → repo.groupez.dev
• GroupId Change: com.github.Traqueur-dev.CommandsAPI → fr.traqueur.commands
• Java 21 Required
• Removed deprecated getAsInt(), getAsDouble() methods → Use args.<T>get() or args.<T>getOptional()

✨ New Features

Annotations Addon

New optional module for declarative command definition using annotations.

@CommandContainer
public class MyCommands {
@Command(name = "heal", permission = "admin.heal")
@Alias({"h", "health"})
public void heal(Player sender, @Arg("target") Optional<Player> target) {
    Player toHeal = target.orElse(sender);
    toHeal.setHealth(20);
}

@Command(name = "admin.reload")  // Hierarchical via dot notation
public void reload(CommandSender sender) { }

@TabComplete(command = "heal", arg = "target")
public List<String> completeTarget(Player sender, String current) {
    return Bukkit.getOnlinePlayers().stream()
        .map(Player::getName)
        .filter(n -> n.startsWith(current))
        .toList();
}

}

Annotations: @CommandContainer, @Command, @Arg, @Infinite, @Alias, @TabComplete

CommandBuilder - Fluent API

Create commands without subclassing:

manager.command("hello")
    .description("Say hello")
    .permission("myplugin.hello")
    .arg("player", Player.class)
    .optionalArg("message", String.class)
    .executor((sender, args) -> {
        Player target = args.get("player");
        sender.sendMessage("Hello " + target.getName());
    })
    .register();

SenderResolver

Automatic sender type resolution for annotations. Each platform provides its own resolver:

• Bukkit: CommandSender, Player, ConsoleCommandSender
• Velocity: CommandSource, Player, ConsoleCommandSource
• JDA: SlashCommandInteractionEvent, User, Member

ArgumentParser System

New extensible parsing system with typed error handling:

• ParseResult with success/error states
• ParseError with types: MISSING_REQUIRED, TYPE_NOT_FOUND, CONVERSION_FAILED

⚡ Performance Improvements

• Player/OfflinePlayer argument caching - Tab completion cached with 1s/5s TTL
• CommandTree optimizations - Precompiled patterns, HashMap lookups
• Async version checker - Non-blocking update check with 5s timeout

🔧 Improvements

• Sealed ArgumentType interface (Simple | Infinite)
• Better label validation (max 64 chars/segment, max 10 depth)
• Improved Javadoc across all modules
• Code cleanup and formatting

📦 Installation

<repository>
    <id>groupez-releases</id>
    <url>https://repo.groupez.dev/releases</url>
</repository>
<dependency>

<groupId>fr.traqueur.commands</groupId>

<artifactId>platform-spigot</artifactId> <!-- or platform-velocity, platform-jda -->

<version>5.0.0</version>

</dependency>
<!-- Optional: Annotations Addon -->

<dependency>

<groupId>fr.traqueur.commands</groupId>

<artifactId>annotations-addon</artifactId>

<version>5.0.0</version>

</dependency>

repositories {
    maven { url 'https://repo.groupez.dev/releases' }
}

dependencies {
    implementation 'fr.traqueur.commands:platform-spigot:5.0.0'
    implementation 'fr.traqueur.commands:annotations-addon:5.0.0' // Optional
}

🎯 3 Ways to Create Commands

Method	Style	Best For
Inheritance	extends Command<T,S>	Complex commands, full control
Builder	manager.command()	Quick inline commands
Annotations	@ Command	Clean, declarative style

---

Full Changelog: See MIGRATION_v4_to_v5.md for detailed migration guide.

Full Changelog: 4.3.1...5.0.0

4.3.1

📦 Changelog – Version 4.3.0

This minor release introduces full JDA (Java Discord API) support for Discord bots, improves error handling, and includes several bug fixes.

---

✨ New Features

Full JDA (Discord) Support

• New jda module: Native support for Discord bots with JDA 6.1.2
  • Command<T>: Base class for Discord slash commands
  • JDAPlatform<T>: CommandPlatform implementation for Discord
  • JDAExecutor: Event handler for Discord interactions
  • JDAArguments: Extension of Arguments with Discord-specific methods (getUser, getChannel, etc.)
  • RoleRequirement: Discord role validation system for commands

New jda-test-bot module

• Demo Discord bot including:
  • PingCommand: Latency test command
  • MathCommand: Command with subcommands (add, subtract, multiply, divide)
  • UserInfoCommand: User information display with embeds

---

🔧 Improvements

Exception Handling

• New custom exceptions:
  • CommandRegistrationException: Dedicated exception for command registration errors
  • UpdaterInitializationException: Exception for updater initialization errors
• Replaced generic RuntimeException:
  • In CommandManager: Using CommandRegistrationException with contextual messages
  • In SpigotPlatform: More explicit error messages during registration

Arguments API Improvements

• Visibility changes:
  • arguments and logger are now protected instead of private
  • Allows extension by classes like JDAArguments
• New utility methods:
  • has(String key): Check if an argument exists
  • getLogger(): Protected access to the logger

CommandInvoker Optimization

• Improved support for commands without arguments
• Better execution context handling

Bug Fixes

• Fixed name duplication: Corrected alias addition logic in registerSubCommands and unregisterSubCommands
  • getAliases() already returns [name, ...aliases], no need to add the name manually
  • Prevents command name duplication in the alias list

---

🏗️ Infrastructure & Configuration

Java 21 Migration

• GitHub Actions: Updated test workflow to Java 21
• JDA Module: Java 21 compatibility (sourceCompatibility and targetCompatibility)

Gradle Configuration

• Added JDA module in settings.gradle and jitpack.yml
• Workflow simplification: Removed redundant test task in CI workflow (keeps only testAll)

---

📂 Architecture

New Modules

• jda/: Discord/JDA support
  • Main classes: Command, JDAPlatform, JDAExecutor, JDAArguments, RoleRequirement
• jda-test-bot/: Demo bot
  • Classes: TestBot, PingCommand, MathCommand, UserInfoCommand

New Core Classes

• CommandRegistrationException
• UpdaterInitializationException

---

📝 Migration Notes

For API Users

• No breaking changes: All modifications are backward compatible
• Classes inheriting from Arguments can now access arguments and logger as protected members

For New Discord Projects

• Add the platform-jda dependency to use CommandsAPI with Discord
• Check the jda-test-bot module for implementation examples

Java Requirements

• JDA module requires Java 21 minimum
• Other modules remain compatible with their previous Java versions

---

Full Changelog: 4.2.3...4.3.1

4.2.3

📦 Changelog – Version 4.2.3

This patch release updates project dependencies and improves module configuration for better API exposure.

---

🔧 Improvements

Gradle & Build System Updates

• Upgraded Gradle wrapper from 8.7 to 8.14
• Enhanced module dependencies: Changed implementation to api for core module in both spigot and velocity subprojects
  • This ensures transitive dependencies are properly exposed to consumers
• Java compatibility update for Velocity module:
  • Set sourceCompatibility to Java 21
  • Set targetCompatibility to Java 21

Documentation Updates

• Updated installation examples to use [version] placeholder instead of hardcoded version numbers
• Fixed Gradle publish command in README: corrected module names from platform-spigot/platform-velocity to spigot/velocity

---

📝 Migration Notes

• Non-breaking patch release
• Projects depending on spigot or velocity modules will now automatically receive core module dependencies
• Velocity module now requires Java 21 (previously unspecified)

---

Full Changelog: 4.2.2...4.2.3

4.2.2

📦 Changelog – Version 4.2.2

This patch release fixes generic type declarations in the EnumArgument class for better type safety.

🐛 Bug Fixes

🔧 Fixed Enum Argument Type Safety

• Updated EnumArgument<T, S> generic types:
  • Changed ArgumentConverter<Enum<T>> to ArgumentConverter<T>
  • Updated apply() method return type from Enum<T> to T

---

📝 Migration Notes

• Non-breaking patch release
• No API changes or migration required

Full Changelog: 4.2.1...4.2.2

4.2.1

📦 Changelog – Version 4.2.1

This patch release fixes edge cases in tab-completion behavior for hierarchical commands registered via CommandTree.
It ensures suggestions are accurate and context-aware based on cursor position and partially typed input.

---

🐛 Bug Fixes

🎯 Improved Tab-Completion Suggestions

• Fixed incorrect suggestions when the cursor is placed immediately after a valid argument without a trailing space (e.g. /test sub<CURSOR>):

  • Suggestions now differentiate between:

    • Cursor at end of argument ➜ sibling and matching suggestions.
    • Cursor after space ➜ child/subcommand suggestions.

• Handled partial alias paths consistently:

  • Suggestions work correctly for commands registered under aliases (e.g. "parent.child") and their subcommands.

---

🔧 Internal Improvements

• Refactored fallback suggestion logic in CommandInvoker#suggest(...):
  • Clean separation of "argument-in-progress" vs "ready for next argument" cases.

---

📝 Migration Notes

This is a non-breaking patch release:

• No API changes.
• No migration required.

Full Changelog: 4.2.0...4.2.1

4.2.0

📦 Changelog – Version 4.2.0

This release adds a hierarchical command tree, improves default usage formatting, and lays the groundwork for more flexible subcommand management. It remains backward-compatible with 4.1.x.

---

🚨 Major Changes

🌲 Prefix-Tree Command Registry

• Replaced the flat Map<String, Command> with a new CommandTree<T, S> data structure.

  • Commands and subcommands are now stored in a trie, keyed by dot-separated paths (e.g. "base.sub.subsub").
  • Lookup via findNode(base, rawArgs) returns the most specific matching node plus any leftover arguments.
  • Removal via removeCommand(label, prune) can either clear a single node or prune an entire subtree.

• Introduced CommandNode<T, S> to represent each segment in the tree, with optional command payload and child-tracking (hadChildren) flags.

🔄 Refactored Default Usage Generation

• Overhauled generateDefaultUsage(...) to show only one level of subcommands, then required and optional arguments.

  • Usage now prints:

    1. Full command path (/parent child …)
    2. First-level subcommand choices (<sub1|sub2>)
    3. Required args (<arg>…) and optional args ([opt]…)

• Backward-compatible: existing explicit setUsage(...) overrides still apply.

---

✨ New Features

🔍 Improved Lookup & Autocomplete

• Subcommands are no longer flat—autocomplete and invocation automatically traverse the tree.
• Arguments fallback correctly when a node has no children but still accepts parameters.

🧪 Expanded Test Coverage

• Added unit tests for CommandTree and CommandNode covering:

  • Adding and finding nested commands
  • Matching with extra args and partial paths
  • Removing nodes with both prune and “clear only” semantics

• Updated existing CommandInvoker tests to work against the new tree-based lookup.

---

🐛 Bug Fixes & Tweaks

• Fixed edge cases in removeCommand:

  • Pruning a branch now properly removes children and resets parent flags.
  • Clearing a command on a leaf node without children now unregisters that node.

• Cleaned up legacy methods that referenced the old flat map.

---

🧹 General Improvements

• Simplified the addCommand(label, command) API to accept full paths directly.
• Streamlined tree traversal code with clearer branch and command-presence checks.
• Minor logging enhancements when adding or removing commands from the tree.

---

⚠️ Migration Guide

1. Update your dependency to 4.2.0:

   implementation "com.github.Traqueur-dev:core:4.2.0"
   implementation "com.github.Traqueur-dev:CommandsAPI-platform-<your-platform>:4.2.0"

2. Review any custom invocation code: switch from manager.getCommands().get(label) to manager.getCommands().findNode(base, rawArgs) in CommandInvoker.

3. Adjust tests or tooling that assumed a flat map of labels. All lookups now go through CommandTree.

4. Verify your usage messages: autogenerated usage strings now show only one subcommand level; if you relied on deeper nesting, update your custom setUsage(...) or test expectations.

Full Changelog: 4.1.0...4.2.0

4.1.0

📦 Changelog – Version 4.1.0

This release focuses on refactoring invocation logic, improving testability, and expanding converter functionality. It remains backward-compatible with 4.0.x.

---

🚨 Major Changes

🔄 Centralized Command Invocation

• Introduced a new CommandInvoker<T, S> class to encapsulate the shared “execute” and “suggest” flows.
• All platform executors (Spigot, Velocity) now delegate to CommandInvoker, eliminating duplicate code and simplifying maintenance.

🛠️ Updater Testability Enhancements

• Made the GitHub-releases URL and logger instance in Updater configurable via setUrlLatestRelease(URL) and setLogger(Logger) so you can mock HTTP calls and logging in tests.
• Refactored fetchLatestVersion() and getString() to use the injected URL, streamlining the code and removing hard-coded values.

---

✨ New Features

🧪 Comprehensive Test Suite

• Added unit tests for core classes: Arguments, CommandManager, and the new CommandInvoker.
• Platform adapters (Spigot & Velocity) now have integration tests covering end-to-end parsing, permission checks, and tab-completion.
• Converter tests for Boolean, Integer, Double, Long, Short, Byte, Character, and the brand-new EnumArgument.of(...) helper (#34).

🔤 Improved Argument Converters

• BooleanArgument now explicitly returns null on empty/null input, matching the behavior of other numeric converters.
• Introduced EnumArgument to parse enums by name and supply their constants for tab-completion.

---

🐛 Bug Fixes

• Suppressed warnings in platform code (e.g. discarded Bukkit.getServer() results).
• Fixed Updater.getVersion() to consistently load from the VERSION_PROPERTY_FILE constant.
• Handled the edge case where infinite arguments consume all remaining tokens, with added tests to verify behavior.

---

🧹 General Improvements

• Smoothed out error-handling paths: non-existent types now log a clear message and return false rather than throwing unchecked exceptions.
• Reduced cyclomatic complexity in invoke(...) and suggest(...) by factoring out shared steps into CommandInvoker.
• Enhanced log messages for better developer diagnostics when argument parsing or permission checks fail.

---

⚠️ Migration Guide

This minor bump (4.1.0) is fully backward-compatible. To upgrade:

1. Update your dependency:

   implementation "com.github.Traqueur-dev:core:4.1.0"
   implementation "com.github.Traqueur-dev:CommandsAPI-platform-<your-platform>:4.1.0"

2. If you have custom tests that stub Updater, switch to the new Updater.setUrlLatestRelease(...) / Updater.setLogger(...) hooks.

3. Take advantage of the new EnumArgument.of(MyEnum.class) for enum-typed parameters.

---

Full Diff: v4.0.0...v4.1.0

4.0.0

📦 Changelog – Version 4.0.0

This version introduces a full modular refactor, enabling multi-platform support and significantly improving flexibility, scalability, and maintainability of the API.
⚠️ This update is NOT backward compatible.

---

🚨 Major Changes

🧱 Modular Platform Architecture

• The codebase has been restructured into multiple modules:

  • core: platform-agnostic logic (commands, arguments, permissions, etc.)
  • platform-spigot: implementation for Spigot/Bukkit
  • platform-velocity: initial implementation for Velocity support

• The new structure allows platform-specific adapters to be plugged into the same command core engine.

🔁 New CommandPlatform Abstraction

• Introduced CommandPlatform<T, S> interface to isolate platform-specific behavior (e.g. permissions, sender types).
• Makes the core engine reusable for other platforms such as Fabric or BungeeCord.

⚙️ CommandManager is now fully generic

• Signature changed to CommandManager<T, S> for better type safety and separation between plugin and sender.
• Requires platform adapters to inject the plugin and sender types explicitly.

📦 Platform-specific artifacts

• Each platform has its own artifact:

  com.github.Traqueur-dev.CommandsAPI:platform-<platform>:4.0.0
  

  e.g. platform-spigot, platform-velocity

---

✨ New Features

📖 Usage Message Auto-Generation

• If no usage is explicitly defined, a usage string is generated dynamically based on the command's structure and sender permissions.

🧠 Multi-Platform Ready

• Developers can now implement their own adapters to support new environments.
• Velocity support is scaffolded and can be extended using the core system.

---

🐛 Bug Fixes

✅ In-Game Only Enforcement

• Improved player-only command handling.
• Commands can now reliably prevent execution from the console using in-game checks.

---

🧹 General Improvements

• Cleaner separation of concerns: core vs. platform logic
• Improved internal logging via injected Logger
• Better extensibility and type safety
• Codebase modernization (Java 21 features, stricter nullability, etc.)
• Tab-completion and argument parsing have been made more robust and flexible

---

⚠️ Migration Guide

This update is not backward compatible with v3.x.

You must:

• Replace your dependency with:

  com.github.Traqueur-dev.CommandsAPI:platform-spigot:4.0.0
  

• Relocate CommandsAPI when shading to avoid classpath conflicts

• Replace any platform-bound logic with core + platform adapter model

• Update CommandManager usage to use the new generic format

• Migrate any custom message handling, requirements, or command registration accordingly

---

🛣️ Next Steps

Update your plugin(s) to the new modular structure to take advantage of:

• Cleaner API boundaries
• Better testability
• Support for multiple platforms in a single codebase

Full Changelog: 3.0.1...4.0.0

3.0.1

Changelog – Version 3.0.1

Bugs Fixs

• Fix bug when addition of aliases creating autocompletion failure and miss registeration