CompatGuard

The intelligent plugin manager for Paper 1.21.x servers.

CompatGuard helps server administrators instantly see which plugins are outdated or incompatible — with zero configuration required. It auto-detects update sources, estimates compatibility risk, and lets you update plugins with a single click, right from the game.

✨ Features

🔍 Plugin Compatibility Scanning

Scans every installed plugin's metadata on startup (or on demand)
Classifies each plugin into five risk levels:
- ✅ SAFE — current api-version, no issues detected
- 🟩 LIKELY SAFE — slightly old api-version but stable
- 🟡 REVIEW NEEDED — old api-version or missing metadata
- 🟠 HIGH RISK — very old api-version, high incompatibility chance
- 🔴 FAILED / DISABLED — plugin failed to load
Configurable scoring rules in rules.yml
Detailed per-plugin reports with /cg report <name>

🔄 Intelligent Auto-Update Detection

Zero manual configuration — automatically finds update sources:
1. Parses the plugin's website field for a GitHub URL
2. Searches Modrinth by plugin name (fuzzy match)
3. Searches Spiget (SpigotMC) by plugin name
4. Probes common GitHub release filename patterns as a fallback
Manual overrides available via sources.yml for niche or private plugins

⬆️ Safe In-Game Updates

Clickable [✔ Update Now] / [✘ Skip] buttons when you join (if updates exist)
Updates are staged in plugins/update/ — the running server JAR is never touched
Applied on the next server restart via Paper's built-in update mechanism
Clickable [✔ Restart Now] / [✘ Later] prompt after staging
Backup old JAR to plugins/backup/ before downloading (configurable, on by default)

🤖 Auto-Update on Startup

Enable auto-update: true to automatically download all available updates on startup
Optional auto-restart-after-update: true for fully hands-off update cycles
Configurable delay so async checks complete before downloads begin

🔔 Discord Webhook Notifications

Posts a rich embed to your Discord channel when updates are found
Colour-coded: 🟠 orange for updates, 🟢 green for all-clear
Lists each outdated plugin with old → new version and source type
Configurable per-server name in footer

📋 Admin Tools

Command	Description
`/cg`	Open paginated GUI or console summary
`/cg scan`	Re-scan all plugins immediately
`/cg checkupdates`	Check updates (async) and print results
`/cg update <name>`	Download & stage update for a specific plugin
`/cg debug <name>`	Full update status: version, source, URL, JAR path
`/cg report [name]`	Server-wide or per-plugin report + JSON export
`/cg reload`	Reload all config files

📁 Reports

JSON reports saved to plugins/CompatGuard/reports/
Includes version, status, score, warnings, and update result per plugin

⚙️ Configuration Highlights

# Auto-detect sources (GitHub, Modrinth, Spiget) — no manual setup needed
auto-detect-sources: true

# Plugins to exclude from all checks
ignore:
  - SomePrivatePlugin

# Download updates automatically on startup
auto-update: false

# Notify OPs with clickable update prompts when they join
notify-ops-on-join: true

# Backup old JAR before staging new version (strongly recommended)
backup-before-update: true

# Re-scan every N hours automatically (0 = off)
auto-scan-interval-hours: 0

# Discord webhook for update reports
discord:
  enabled: false
  webhook-url: ""
  server-name: "My Server"

🛡️ Safety Guarantees

Read-only by default — no files are touched unless you use the update feature
HTTPS-only downloads — HTTP URLs are refused
50 MB download cap — prevents accidental large file downloads
Atomic staging — files are written to a temp file then renamed, preventing corruption
Backup before update — old JAR saved to plugins/backup/ for easy rollback

📋 Requirements

Paper 1.21.x (Purpur should work too)
Java 21+

🤝 Contributing & Support

Discord: [https://discord.com/invite/pDPJ92VVv8]