Add staff command to give completed mage weapons

[XxFran10xX]

Adds /magic weapon give <player> <staff|wand|sword> <element> <aura> <part> [part...] to deliver a finished mage weapon with attunement and finalized sockets. The command validates enabled parts, archetype compatibility, required categories, positive tier-reaching aura and inventory space, and records zero crafting cost.

give-permission defaults to magic.weapon.give and can use a custom staff node independently of magic.admin; blank disables spawning. Includes permission-aware completion and usage documentation.

Validation: full unit suite plus targeted command tests pass; JaCoCo reports zero missed instructions, branches or lines and the configured coverage check passes. CI clean verify passed.

On TFMCDev01 (Paper 1.21.10 / Java 21), CI artifact DEV-20261004-0804 loaded successfully. In-game smoke checks passed permission denial, give permission without admin permission, invalid part rejection and delivery of Staff, Wand and Sword. Inspected item data includes attunement, locked sockets and zero-cost provenance. Test items and temporary permission grants were removed.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 76751f95-a26d-4de2-821c-3ab915d0f7dd

📥 Commits

Reviewing files that changed from the base of the PR and between d089e13 and cfba827.

📒 Files selected for processing (8)

• README.md
• src/main/java/net/tfminecraft/magic/Cache.java
• src/main/java/net/tfminecraft/magic/command/MagicCommand.java
• src/main/java/net/tfminecraft/magic/command/WeaponGiveCommand.java
• src/main/java/net/tfminecraft/magic/loader/ConfigLoader.java
• src/main/resources/config.yml
• src/main/resources/plugin.yml
• src/test/java/net/tfminecraft/magic/WeaponGiveTest.java

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

---

📝 Summary

Summary by CodeRabbit

• New Features
  • Added /magic weapon give for staff to provide completed weapons to online players, with validation for weapon type, attunement, aura, parts and available inventory space.
  • Added configurable permission for the command, defaulting to operators. Eligible staff can access weapon usage and tab completion.
• Documentation
  • Documented the command, its arguments, requirements, permission setting and reload command in the README.

Walkthrough

Adds /magic weapon give with configurable permission checks, input validation, weapon preparation, inventory handling, and tab completion. Adds tests and documentation for the command.

Changes

Staff weapon give command

Layer / File(s)	Summary
Give permission configuration src/main/java/net/tfminecraft/magic/Cache.java, src/main/java/net/tfminecraft/magic/loader/ConfigLoader.java, src/main/resources/config.yml, src/main/resources/plugin.yml	Adds the give-permission setting, trims its configured value, and declares the permission with an operator default.
Command routing and weapon delivery src/main/java/net/tfminecraft/magic/command/MagicCommand.java, src/main/java/net/tfminecraft/magic/command/WeaponGiveCommand.java, src/main/resources/plugin.yml, src/test/java/net/tfminecraft/magic/WeaponGiveTest.java, README.md	Routes weapon commands and tab completion to WeaponGiveCommand. The handler validates command inputs, prepares a weapon, and gives it to the recipient when an inventory slot is available. Tests cover validation, permissions, item preparation, inventory handling, and completion. The README documents command arguments and requirements.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant CommandSender
  participant MagicCommand
  participant WeaponGiveCommand
  participant RecipientInventory
  CommandSender->>MagicCommand: Invoke /magic weapon give
  MagicCommand->>WeaponGiveCommand: Route command and arguments
  WeaponGiveCommand->>WeaponGiveCommand: Validate arguments and prepare weapon
  WeaponGiveCommand->>RecipientInventory: Check for an empty slot
  WeaponGiveCommand->>RecipientInventory: Give prepared weapon

Loading

Suggested reviewers: drefvelin

Merge Risk: ⚪ Minimal · up to cfba8

No actionable issue remains in the supplied review evidence. The change is mergeable after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to cfba8

The new permission grants substantial weapon-spawning authority, but execution and completion consistently enforce it, and other administrative commands retain their existing checks. No introduced authorization bypass was established. Runtime integration and failure handling remain only partially verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• observed — A sender holding the configured node can grant validated completed weapons to any exact-name online player. The sender need not be a player, and the command imposes no recipient ownership check or cumulative grant quota.

Trust Boundaries and Controls

• observed — Sender-controlled grant arguments reach construction and inventory insertion only after the dedicated permission check and weapon validation. Weapon completion independently checks the same permission; top-level completion advertises the capability only to authorized senders. Separate administrative actions retain their admin gate.

Resilience and Maintainability Implications

• observed — The command rejects a full inventory before building and finalizes item metadata before insertion. It nevertheless discards addItem leftovers and reports success unconditionally after insertion; actual recovery from an unexpected insertion failure is not implemented in this path.

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}