feat: Beacon deploy automation with server name resolution

[DIodide]

Summary

Replaces the manual "build JAR → open panel → upload → restart" workflow with a single command: npm run deploy:beacon.

• Adds scripts/deploy-beacon.mjs — builds the Beacon JAR, uploads it to a Pterodactyl-managed server via the client API, backs up the existing plugin, syncs config, and restarts the server
• Adds --server-name / PTERODACTYL_SERVER_NAME so each developer can target their own Fast Dev server by name instead of memorizing UUIDs
• Adds --list-servers to discover which servers are available to your API key
• Syncs config.yml on the server with your CONVEX_SITE_URL and CONVEX_HTTP_SECRET so the plugin connects to the right Convex deployment
• Bumps .nvmrc from 20.9.0 to 20.19.0 (fixes CI — @noble/ciphers@2.0.1 requires >= 20.19.0)

How to use

1. Get a Pterodactyl Client API Key

1. Log in to https://mcpanel.blockwarriors.ai
2. Click your avatar → Account Settings → API Credentials
3. Create a new key — it will start with ptlc_
4. Important: ptla_ keys (application/admin) will not work — you need a ptlc_ (client) key

2. Get the Convex settings

• CONVEX_SITE_URL — the Convex site URL (e.g., https://abundant-ferret-667.convex.site). Check packages/backend/.env.local if you already have the backend set up.
• CONVEX_HTTP_SECRET — the shared auth secret. Must match the CONVEX_HTTP_SECRET in your Convex deployment. Ask your team lead if you don't have it.

3. Create .env.local at the repo root

cp .env.example .env.local

Fill in:

PTERODACTYL_PANEL_URL=https://mcpanel.blockwarriors.ai
PTERODACTYL_API_KEY=ptlc_your_client_api_key
PTERODACTYL_SERVER_NAME=Fast Dev - YourName
CONVEX_SITE_URL=https://abundant-ferret-667.convex.site
CONVEX_HTTP_SECRET=your-convex-http-secret

4. Find your server

npm run deploy:beacon -- --list-servers

Set PTERODACTYL_SERVER_NAME to match your Fast Dev instance exactly.

5. Deploy

npm run deploy:beacon          # build, upload, sync config, restart
npm run deploy:beacon:dry-run  # preview without touching the server

The script will:

1. Build the shaded Beacon JAR
2. Back up the existing beacon.jar on the server (timestamped rename)
3. Upload the new JAR as beacon.jar
4. Write config.yml with your Convex settings (if CONVEX_SITE_URL/CONVEX_HTTP_SECRET are set)
5. Restart the server and wait for it to come back online

Additional flags

Flag	Purpose
--skip-build	Reuse an already-built local JAR
--skip-restart	Upload only, don't restart
--no-backup	Skip the backup rename step
--jar-path PATH	Override which local JAR to upload
--artifact-url URL	Tell the server to pull a remote URL instead of uploading
--server UUID	Target a server by UUID directly
--server-name NAME	Resolve by name (supports partial match)
--list-servers	Show all servers for your API key

Required panel permissions

file.read, file.create, file.update, control.restart

Test plan

• --list-servers shows all servers for the API key
• --server-name "Fast Dev - Ibraheem" resolves to the correct server UUID
• Ambiguous name match lists candidates and errors clearly
• No-match errors with suggestion to use --list-servers
• Dry run prints plan (including Convex config) and exits without contacting the server
• Full deploy builds, uploads, backs up existing plugin, syncs config.yml, restarts, and waits for running state
• Config.yml on server verified to have correct Convex values after deploy
• CI passes with bumped Node version (20.19.0)

🤖 Generated with Claude Code