feat: add @context annotation for CommandContext injection

Adds support for injecting the Brigadier CommandContext as a command
parameter by annotating it with @context. This allows access to
lower-level command execution details such as input parsing,
argument nodes, and the command source.

Example usage:
```java
@executes
void execute(CommandSender sender, @context CommandContext<?> ctx, int amount);
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: AlexProgrammerDE

annotations-common/src/main/java/net/strokkur/commands/Context.java

@@ -0,0 +1,42 @@
+/*
+ * StrokkCommands - A super simple annotation based zero-shade Paper command API library.
+ * Copyright (C) 2025 Strokkur24
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, see <https://www.gnu.org/licenses/>.
+ */
+package net.strokkur.commands;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/// Declares that a parameter should be injected with the Brigadier
+/// {@code CommandContext} instead of being interpreted as a command argument.
+///
+/// This annotation can be applied to any parameter of type {@code CommandContext<?>}
+/// in a method annotated with {@link Executes} or {@link DefaultExecutes}.
+///
+/// Example usage:
+/// ```java
+/// @Executes
+/// void execute(CommandSender sender, @Context CommandContext<?> ctx, int amount);
+/// ```
+///
+/// The annotated parameter will receive the raw Brigadier {@code CommandContext} at runtime,
+/// allowing access to lower-level command execution details such as input parsing,
+/// argument nodes, and the command source.
+@Retention(RetentionPolicy.SOURCE)
+@Target(ElementType.PARAMETER)
+public @interface Context {}

processor-common/src/main/java/net/strokkur/commands/internal/NodeUtils.java

@@ -17,6 +17,7 @@
  */
 package net.strokkur.commands.internal;
 
+import net.strokkur.commands.Context;
 import net.strokkur.commands.Literal;
 import net.strokkur.commands.UnsetExecutorWrapper;
 import net.strokkur.commands.internal.abstraction.AnnotationsHolder;
@@ -26,6 +27,7 @@
 import net.strokkur.commands.internal.arguments.BrigadierArgumentConverter;
 import net.strokkur.commands.internal.arguments.BrigadierArgumentType;
 import net.strokkur.commands.internal.arguments.CommandArgument;
+import net.strokkur.commands.internal.arguments.ContextCommandArgument;
 import net.strokkur.commands.internal.arguments.LiteralCommandArgument;
 import net.strokkur.commands.internal.arguments.MultiLiteralCommandArgument;
 import net.strokkur.commands.internal.arguments.RequiredCommandArgument;
@@ -76,6 +78,13 @@ public List<CommandArgument> parseArguments(final List<? extends SourceVariable>
     for (final SourceVariable parameter : variables) {
       debug("| Parsing parameter: " + parameter.getName());
 
+      // Handle @Context annotation - inject CommandContext directly
+      if (parameter.getAnnotation(Context.class) != null) {
+        debug("  | Found @Context annotation, adding ContextCommandArgument");
+        arguments.add(new ContextCommandArgument(parameter));
+        continue;
+      }
+
       final Literal literal = parameter.getAnnotation(Literal.class);
       if (literal != null) {
         final String[] declared = literal.value();

processor-common/src/main/java/net/strokkur/commands/internal/arguments/ContextCommandArgument.java

@@ -0,0 +1,34 @@
+/*
+ * StrokkCommands - A super simple annotation based zero-shade Paper command API library.
+ * Copyright (C) 2025 Strokkur24
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, see <https://www.gnu.org/licenses/>.
+ */
+package net.strokkur.commands.internal.arguments;
+
+import net.strokkur.commands.internal.abstraction.SourceElement;
+
+/// Represents a parameter annotated with {@code @Context} that should be injected
+/// with the Brigadier {@code CommandContext} at runtime.
+///
+/// Unlike other argument types, context arguments do not represent actual command
+/// arguments from the user input. Instead, they are injected directly from the
+/// execution context.
+public record ContextCommandArgument(SourceElement element) implements CommandArgument {
+
+  @Override
+  public String argumentName() {
+    return "ctx";
+  }
+}

processor-common/src/main/java/net/strokkur/commands/internal/printer/TreePrinter.java

@@ -22,6 +22,7 @@
 import net.strokkur.commands.internal.abstraction.SourceParameter;
 import net.strokkur.commands.internal.abstraction.SourceType;
 import net.strokkur.commands.internal.arguments.CommandArgument;
+import net.strokkur.commands.internal.arguments.ContextCommandArgument;
 import net.strokkur.commands.internal.arguments.LiteralCommandArgument;
 import net.strokkur.commands.internal.arguments.MultiLiteralCommandArgument;
 import net.strokkur.commands.internal.arguments.RequiredCommandArgument;
@@ -270,6 +271,7 @@ private void printArguments(final List<? extends CommandArgument> arguments) thr
         case RequiredCommandArgument req -> req.argumentType().retriever();
         case MultiLiteralCommandArgument ignored -> '"' + nextLiteral() + '"';
         case LiteralCommandArgument lit -> '"' + lit.literal() + '"';
+        case ContextCommandArgument ignored -> "ctx";
         default -> throw new IllegalArgumentException("Unknown argument class: " + argument.getClass());
       });