CompatGuard

--- # 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 `` / `` 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 `` / `` 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 ` | 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 ```yaml # 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:** ---