0.0.9-alpha, more dev tools...

 T-T

Author: jonagamerpro1234

README.md

@@ -1,20 +1,30 @@
 # CommandAPI
 
+
+
+A lightweight and extensible command framework for Bukkit / Spigot plugins, designed to simplify command handling, subcommands, tab completion, and debugging.
+
+CommandAPI focuses on clean structure, developer ergonomics, and future scalability.
+
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/jonagamerpro1234/CommandAPI)
 
-A flexible Bukkit/Spigot command system with built-in subcommands, permissions, and tab completion.
+### ✨ Features
+
+✅ Clean BaseCommand system
+
+✅ Modular SubCommand architecture
 
-Features
+✅ Built-in tab completion
 
-Define a main command with optional custom logic.
+✅ Optional main command logic (no subcommand required)
 
-Add subcommands with their own permissions, console rules, and tab completion.
+✅ Centralized debug & logging system
 
-Automatic tab suggestions for main commands and subcommands.
+✅ Execution and performance logging
 
-Easy registration via your JavaPlugin.
+✅ Easy to extend and maintain
 
-Quick Example
+### Quick Example
 ```java
 new BaseCommand() {
     {
@@ -36,7 +46,7 @@ new BaseCommand() {
 }.register(this); // automatically registers the command
 ```
 
-How it works
+###  How it works
 
 /mycommand → runs onCommandMain.
 
@@ -46,7 +56,7 @@ Tab completion works automatically for both main command and subcommands.
 
 Each subcommand can define permissions, console access, and custom tab lists.
 
-##Maven
+### Maven
 ```xml
 <dependency>
   <groupId>jss.commandapi</groupId>
@@ -55,16 +65,117 @@ Each subcommand can define permissions, console access, and custom tab lists.
 </dependency>
 ```
 
-## Gradle (Groovy DSL)
+###  Gradle (Groovy DSL)
 ```groovy
 dependencies {
     implementation 'jss.commandapi:command-api:0.0.8-alpha'
 }
 ```
 
-## Gradle (Kotlin DSL)
+### Gradle (Kotlin DSL)
 ```kotlin
 dependencies {
     implementation("jss.commandapi:command-api:0.0.8-alpha")
 }
 ```
+
+## 🚀 Getting Started
+1️⃣ Initialize CommandAPI
+Call this once in your plugin onEnable():
+
+``` java
+@Override
+public void onEnable() {
+CommandApi.init(this);
+CommandApi.setDebug(true);
+CommandApi.setLogExecution(true);
+CommandApi.setLogPerformance(true);
+}
+```
+2️⃣ Create a Base Command
+``` java
+public class MainCommand extends BaseCommand {
+
+    public MainCommand() {
+        name("example")
+                .addSubCommand(new HelpSubCommand())
+                .addSubCommand(new ReloadSubCommand());
+    }
+
+    @Override
+    public boolean onCommandMain(CommandSender sender, String[] args) {
+        sender.sendMessage("§eUse /example help");
+        return true;
+    }
+}
+```
+3️⃣ Register the Command
+```java
+@Override
+public void onEnable() {
+new MainCommand().register(this);
+}
+```
+⚠️ The command must exist in plugin.yml.
+
+4️⃣ Create a SubCommand
+``` java
+public class HelpSubCommand extends SubCommand {
+
+    @Override
+    public String name() {
+        return "help";
+    }
+
+    @Override
+    public boolean onCommand(CommandSender sender, String[] args) {
+        sender.sendMessage("§aThis is the help command!");
+        return true;
+    }
+}
+```
+
+## 🧩 SubCommand Capabilities
+Each SubCommand can define:
+
+- Permissions
+- Aliases
+- Tab completion
+- Console usage
+- Player-only restriction
+- Usage & description
+- Enable / disable logic
+
+Example:
+```java
+@Override
+public List<String> aliases() {
+return List.of("h", "?");
+}
+```
+
+### 🛠 Debug & Logging
+- CommandAPI includes a built-in utility for debugging and logging:
+- Command execution logs
+- Sender type (Player / Console)
+- Execution time
+- Error handling with stack traces (debug mode)
+
+This helps a lot during development and production debugging.
+
+## 🧪 Current Status
+- Version: 0.0.x-alpha
+- API is stable for testing
+- Breaking changes may occur until 1.0.0
+
+## 🔮 Roadmap
+- Command execution hooks
+- Context-based command handling
+- Better permission resolvers
+- Metrics & analytics
+- Optional annotations support
+
+## 📜 License
+MIT License – free to use, modify, and distribute.
+
+

src/main/java/jss/commandapi/BaseCommand.java

@@ -20,7 +20,7 @@
  * 3. Tab completion for both subcommands and the main command.
  *
  * @author jonagamerpro1234
- * @version 0.0.7-alpha
+ * @version 0.0.9-alpha
  */
 public abstract class BaseCommand implements TabExecutor {
 
@@ -29,11 +29,6 @@ public abstract class BaseCommand implements TabExecutor {
 
     /**
      * Registers this command automatically using the provided JavaPlugin.
-     * <p>
-     * This method sets this BaseCommand instance as both the executor and
-     * the tab completer for the command defined in the plugin's plugin.yml.
-     * It will log a warning if the command is not defined in plugin.yml.
-     * </p>
      *
      * @param plugin the JavaPlugin instance used to register the command
      * @throws IllegalStateException if the command name has not been set or is empty
@@ -43,16 +38,18 @@ public void register(@NotNull JavaPlugin plugin) {
         if (name == null || name.isEmpty()) {
             throw new IllegalStateException("Command name cannot be null or empty!");
         }
+
         PluginCommand command = plugin.getCommand(name);
         if (command == null) {
-            plugin.getLogger().warning("Command '" + name + "' is not defined in plugin.yml!");
+            CommandApi.log("Command '" + name + "' is not defined in plugin.yml!");
             return;
         }
+
         command.setExecutor(this);
         command.setTabCompleter(this);
-        plugin.getLogger().info("Registered command: " + name);
-    }
 
+        CommandApi.log("Registered command: " + name);
+    }
 
     /**
      * Sets the main command name.
@@ -92,7 +89,6 @@ public BaseCommand addSubCommand(SubCommand... subCommands) {
 
     /**
      * Logic executed when no subcommand is provided.
-     * Override this in the concrete class if needed.
      *
      * @param sender the CommandSender executing the command
      * @param args the command arguments
@@ -105,8 +101,7 @@ public boolean onCommandMain(@NotNull CommandSender sender, String[] args) {
     }
 
     /**
-     * Tab completion suggestions for the main command
-     * (when not completing a subcommand)
+     * Tab completion suggestions for the main command.
      *
      * @param sender the CommandSender requesting tab completion
      * @param args the command arguments
@@ -118,84 +113,93 @@ public List<String> onTabMain(@NotNull CommandSender sender, String[] args) {
     }
 
     /**
-     * Handles command execution.
-     * Routes to subcommands if one matches, otherwise calls onCommandMain.
-     *
-     * @param sender the CommandSender executing the command
-     * @param command the Command object
-     * @param label the command label
-     * @param args the command arguments
-     * @return true if execution was handled
-     * @since 0.0.7-alpha
+     * Handles command execution with debug, logging, and performance tracking.
+     * @since 0.0.8-alpha
      */
     @Override
-    public boolean onCommand(@NotNull CommandSender sender, @NotNull Command command, @NotNull String label, String @NotNull [] args) {
-        if (args.length < 1) {
-            return onCommandMain(sender, args);
-        }
+    public boolean onCommand(
+            @NotNull CommandSender sender,
+            @NotNull Command command,
+            @NotNull String label,
+            String @NotNull [] args
+    ) {
+        long startTime = System.nanoTime();
+
+        try {
+
+            if (args.length < 1) {
+                return onCommandMain(sender, args);
+            }
 
-        String subName = args[0];
-        for (SubCommand sub : subCommands) {
-            if (subName.equalsIgnoreCase(sub.name()) || sub.aliases().contains(subName)) {
+            String subName = args[0];
 
-                if (!sub.isEnabled()) {
-                    sender.sendMessage(sub.disabledMessage());
-                    return true;
-                }
+            for (SubCommand sub : subCommands) {
+                if (subName.equalsIgnoreCase(sub.name()) || sub.aliases().contains(subName)) {
 
-                if (sub.requiresPermission() && !sender.hasPermission("plugin." + sub.permission())) {
-                    sender.sendMessage("§cYou do not have permission to execute this command!");
-                    return true;
-                }
+                    if (!sub.isEnabled()) {
+                        sender.sendMessage(sub.disabledMessage());
+                        return true;
+                    }
 
-                if (!sub.allowConsole() && !(sender instanceof Player)) {
-                    sender.sendMessage("§cThis command cannot be executed from console!");
-                    return true;
-                }
+                    if (sub.requiresPermission() && !sender.hasPermission("plugin." + sub.permission())) {
+                        sender.sendMessage("§cYou do not have permission to execute this command!");
+                        return true;
+                    }
 
-                return sub.onCommand(sender, args);
+                    if (!sub.allowConsole() && !(sender instanceof Player)) {
+                        sender.sendMessage("§cThis command cannot be executed from console!");
+                        return true;
+                    }
+
+                    return sub.onCommand(sender, args);
+                }
             }
-        }
 
-        return onCommandMain(sender, args);
+            return onCommandMain(sender, args);
+
+        } catch (Exception exception) {
+
+            CommandApi.handleError(name, sender, exception);
+            return true;
+
+        } finally {
+
+            long executionTimeMs = (System.nanoTime() - startTime) / 1_000_000;
+            CommandApi.logCommandExecution(name, sender, executionTimeMs);
+        }
     }
 
     /**
      * Handles tab completion for the main command and its subcommands.
      *
-     * @param sender the CommandSender requesting tab completion
-     * @param command the Command object
-     * @param alias the command alias
-     * @param args the command arguments
-     * @return a list of tab completion suggestions
      * @since 0.0.7-alpha
      */
     @Override
-    public List<String> onTabComplete(@NotNull CommandSender sender, @NotNull Command command, @NotNull String alias, String @NotNull [] args) {
+    public List<String> onTabComplete(
+            @NotNull CommandSender sender,
+            @NotNull Command command,
+            @NotNull String alias,
+            String @NotNull [] args
+    ) {
 
         List<String> suggestions = new ArrayList<>();
 
         if (args.length == 1) {
             String start = args[0].toLowerCase();
 
-            // Subcommand suggestions
             List<String> subNames = subCommands.stream()
                     .map(SubCommand::name)
                     .filter(n -> n.toLowerCase().startsWith(start))
                     .collect(Collectors.toList());
 
-            // Main command suggestions
-            List<String> mainSuggestions = onTabMain(sender, args);
-
-            subNames.addAll(mainSuggestions);
+            subNames.addAll(onTabMain(sender, args));
             suggestions.addAll(subNames);
 
         } else if (args.length > 1) {
             for (SubCommand sub : subCommands) {
                 if (args[0].equalsIgnoreCase(sub.name()) || sub.aliases().contains(args[0])) {
                     List<String> tab = sub.onTabList(sender, args);
-                    if (tab != null) return tab;
-                    return new ArrayList<>();
+                    return tab != null ? tab : new ArrayList<>();
                 }
             }
 
@@ -205,22 +209,10 @@ public List<String> onTabComplete(@NotNull CommandSender sender, @NotNull Comman
         return suggestions;
     }
 
-    /**
-     * Returns the list of registered subcommands.
-     *
-     * @return the list of subcommands
-     * @since 0.0.7-alpha
-     */
     public List<SubCommand> getSubCommands() {
         return subCommands;
     }
 
-    /**
-     * Returns the name of the main command.
-     *
-     * @return the command name
-     * @since 0.0.7-alpha
-     */
     public String getName() {
         return name;
     }