refactor: make range purgebonus async and confirmation-explicit

Reworks AdminRangePurgeBonusCommand so the potentially heavy island scan
no longer blocks the main thread on large servers, following the
established purge-command pattern.

- The scan that finds islands carrying the bonus id now runs off-thread
  via IslandsManager#getIslandsASync(); results are marshalled back to
  the main thread to prompt and to apply.
- Confirmation is now explicit: `/<admin> range purgebonus <id>` scans
  and reports the count, then `/<admin> range purgebonus <id> confirm`
  applies it (reusing the scanned result - no second scan). An inPurge
  guard rejects overlapping runs.
- The mutation and IslandEvent RANGE_CHANGE firing still happen on the
  main thread, on the live cached island instances (resolved by id),
  with per-island re-check in case state changed since the scan.

Adds locale keys commands.admin.range.purgebonus.{confirm,in-progress,
failed} to en-US and all 22 other locales. Rewrites the test suite (12
tests) to cover the sync seams: findIslandIds, applyPurge, the confirm
dispatch, canExecute guards and tab completion.

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

Author: tastybento

src/main/java/world/bentobox/bentobox/api/commands/admin/range/AdminRangePurgeBonusCommand.java

@@ -3,13 +3,12 @@
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
-import java.util.Objects;
 import java.util.Optional;
 
+import org.bukkit.Bukkit;
 import org.eclipse.jdt.annotation.Nullable;
 
 import world.bentobox.bentobox.api.commands.CompositeCommand;
-import world.bentobox.bentobox.api.commands.ConfirmableCommand;
 import world.bentobox.bentobox.api.events.island.IslandEvent;
 import world.bentobox.bentobox.api.localization.TextVariables;
 import world.bentobox.bentobox.api.user.User;
@@ -25,13 +24,27 @@
  * {@code uniqueId}); for example the Upgrades addon stores them under the id
  * {@code "Upgrades"}. When such an addon is removed, the bonus ranges it added
  * remain on every island it ever touched. This command purges them in one go.
+ * <p>
+ * Because a server can hold a large number of islands, the scan that finds the
+ * affected islands runs asynchronously (off the main thread). The admin is then
+ * shown the count and must re-run the command with {@code confirm} to apply it.
+ * The actual mutation and event firing happen back on the main thread, on the
+ * live cached island instances.
  *
  * @author tastybento
  * @since 3.17.1
  */
-public class AdminRangePurgeBonusCommand extends ConfirmableCommand {
+public class AdminRangePurgeBonusCommand extends CompositeCommand {
 
-    private @Nullable String bonusId;
+    /** True while an async scan is running, to prevent overlapping runs. */
+    volatile boolean inPurge;
+    /** True once a scan has found islands and is awaiting a {@code confirm}. */
+    boolean toBeConfirmed;
+    /** The bonus id the pending confirmation is for. */
+    @Nullable
+    String pendingId;
+    /** The unique ids of the islands the pending confirmation will purge. */
+    List<String> pendingIslandIds = List.of();
 
     /**
      * Admin command to remove a bonus range id from every island.
@@ -51,43 +64,87 @@ public void setup() {
 
     @Override
     public boolean canExecute(User user, String label, List<String> args) {
-        // A single bonus id is expected
-        if (args.size() != 1) {
-            showHelp(this, user);
+        if (inPurge) {
+            user.sendMessage("commands.admin.range.purgebonus.in-progress");
             return false;
         }
-        bonusId = args.get(0);
-        // There must be at least one island carrying this bonus id
-        if (islandsWithBonus(bonusId).isEmpty()) {
-            user.sendMessage("commands.admin.range.purgebonus.none", "[id]", bonusId);
+        // Expect "<id>" or "<id> confirm"
+        if (args.isEmpty() || args.size() > 2
+                || (args.size() == 2 && !args.get(1).equalsIgnoreCase("confirm"))) {
+            showHelp(this, user);
             return false;
         }
         return true;
     }
 
     @Override
     public boolean execute(User user, String label, List<String> args) {
-        Objects.requireNonNull(bonusId);
-        // Warn how many islands will be affected before the admin confirms
-        int count = islandsWithBonus(bonusId).size();
-        user.sendMessage("commands.admin.range.purgebonus.warning", "[id]", bonusId, TextVariables.NUMBER,
-                String.valueOf(count));
-        final String id = bonusId;
-        askConfirmation(user, () -> purge(user, id));
+        String id = args.get(0);
+        boolean confirm = args.size() == 2 && args.get(1).equalsIgnoreCase("confirm");
+        // Apply a pending purge if this is the matching confirmation
+        if (confirm && toBeConfirmed && id.equals(pendingId)) {
+            List<String> ids = pendingIslandIds;
+            toBeConfirmed = false;
+            pendingId = null;
+            pendingIslandIds = List.of();
+            applyPurge(user, id, ids);
+            return true;
+        }
+        // Otherwise (re)scan asynchronously and prompt for confirmation
+        inPurge = true;
+        getPlugin().getIslands().getIslandsASync().thenAccept(all -> {
+            List<String> ids = findIslandIds(all, id);
+            Bukkit.getScheduler().runTask(getPlugin(), () -> {
+                inPurge = false;
+                if (ids.isEmpty()) {
+                    user.sendMessage("commands.admin.range.purgebonus.none", "[id]", id);
+                    return;
+                }
+                pendingId = id;
+                pendingIslandIds = ids;
+                toBeConfirmed = true;
+                user.sendMessage("commands.admin.range.purgebonus.warning", "[id]", id, TextVariables.NUMBER,
+                        String.valueOf(ids.size()));
+                user.sendMessage("commands.admin.range.purgebonus.confirm");
+            });
+        }).exceptionally(ex -> {
+            getPlugin().logStacktrace(ex);
+            Bukkit.getScheduler().runTask(getPlugin(), () -> {
+                inPurge = false;
+                user.sendMessage("commands.admin.range.purgebonus.failed");
+            });
+            return null;
+        });
         return true;
     }
 
     /**
-     * Removes the bonus range id from every island that carries it, firing a range
-     * change event per island whose effective protection range changed. Each island
-     * is persisted automatically via {@code setChanged()}.
+     * @return the unique ids of the islands in this world that carry a bonus range
+     *         with the given id.
+     */
+    List<String> findIslandIds(Collection<Island> islands, String id) {
+        return islands.stream().filter(i -> getWorld().equals(i.getWorld()))
+                .filter(i -> i.getBonusRangeRecord(id).isPresent()).map(Island::getUniqueId).toList();
+    }
+
+    /**
+     * Removes the bonus range id from every still-matching island, firing a range
+     * change event per island whose effective protection range changed. Runs on the
+     * main thread and operates on the live cached island instances, which are
+     * persisted automatically via {@code setChanged()}.
      *
      * @param user the admin running the command
      * @param id   the bonus range uniqueId to purge
+     * @param ids  the unique ids of the islands found during the async scan
      */
-    void purge(User user, String id) {
-        int islandsChanged = 0;
-        for (Island island : islandsWithBonus(id)) {
+    void applyPurge(User user, String id, List<String> ids) {
+        int changed = 0;
+        for (String uid : ids) {
+            Island island = getIslands().getIslandById(uid).orElse(null);
+            // Re-check on the live instance in case it changed since the scan
+            if (island == null || island.getBonusRangeRecord(id).isEmpty()) {
+                continue;
+            }
             int oldRange = island.getProtectionRange();
             island.clearBonusRange(id);
             int newRange = island.getProtectionRange();
@@ -101,21 +158,12 @@ void purge(User user, String id) {
                         .protectionRange(newRange, oldRange)
                         .build();
             }
-            islandsChanged++;
+            changed++;
         }
-        getPlugin().log("Purged bonus range '" + id + "' from " + islandsChanged + " island(s) in "
+        getPlugin().log("Purged bonus range '" + id + "' from " + changed + " island(s) in "
                 + getWorld().getName());
         user.sendMessage("commands.admin.range.purgebonus.success", "[id]", id, TextVariables.NUMBER,
-                String.valueOf(islandsChanged));
-    }
-
-    /**
-     * @return the islands in this world that carry a bonus range with the given id.
-     *         Uses the island cache so the live, canonical instances are mutated.
-     */
-    private List<Island> islandsWithBonus(String id) {
-        return getIslands().getIslandCache().getIslands(getWorld()).stream()
-                .filter(i -> i.getBonusRangeRecord(id).isPresent()).toList();
+                String.valueOf(changed));
     }
 
     @Override
@@ -128,6 +176,8 @@ public Optional<List<String>> tabComplete(User user, String alias, List<String>
                     .flatMap(i -> i.getBonusRanges().stream()).map(BonusRangeRecord::getUniqueId).distinct().sorted()
                     .toList();
             return Optional.of(Util.tabLimit(new ArrayList<>(ids), lastArg));
+        } else if (args.size() == 2) {
+            return Optional.of(Util.tabLimit(new ArrayList<>(List.of("confirm")), args.getLast()));
         }
         return Optional.empty();
     }

src/main/resources/locales/cs.yml

@@ -254,6 +254,9 @@ commands:
         none: '<red>Žádný ostrov nemá bonusový rozsah s id </red><aqua>[id]</aqua><red>!</red>'
         warning: '<gold>Tímto odeberete bonusový rozsah </gold><aqua>[id]</aqua><gold> z </gold><aqua>[number]</aqua><gold> ostrovů.</gold>'
         success: '<green>Odebrán bonusový rozsah </green><aqua>[id]</aqua><green> z </green><aqua>[number]</aqua><green> ostrovů.</green>'
+        confirm: '<gold>Spusťte příkaz znovu s </gold><aqua>confirm</aqua><gold> pro potvrzení.</gold>'
+        in-progress: '<red>Čištění bonusových rozsahů již probíhá. Počkejte prosím.</red>'
+        failed: '<red>Skenování ostrovů selhalo. Zkontrolujte konzoli.</red>'
     register:
       parameters: <Player>
       description: registrovat hráče na nevlastněný ostrov, na kterém se nacházíš

src/main/resources/locales/de.yml

@@ -274,6 +274,9 @@ commands:
         none: '<red>Keine Insel hat einen Bonusbereich mit der id </red><aqua>[id]</aqua><red>!</red>'
         warning: '<gold>Dies entfernt den Bonusbereich </gold><aqua>[id]</aqua><gold> von </gold><aqua>[number]</aqua><gold> Insel(n).</gold>'
         success: '<green>Bonusbereich </green><aqua>[id]</aqua><green> von </green><aqua>[number]</aqua><green> Insel(n) entfernt.</green>'
+        confirm: '<gold>Führe den Befehl erneut mit </gold><aqua>confirm</aqua><gold> aus, um fortzufahren.</gold>'
+        in-progress: '<red>Eine Bonusbereich-Bereinigung läuft bereits. Bitte warten.</red>'
+        failed: '<red>Inseln konnten nicht gescannt werden. Prüfe die Konsole.</red>'
     register:
       parameters: <spieler>
       description: Spieler auf freier Insel registrieren, auf der du dich befindest

src/main/resources/locales/en-US.yml

@@ -234,6 +234,9 @@ commands:
         none: '<red>No [prefix_island] has a bonus range with id </red><aqua>[id]</aqua><red>!</red>'
         warning: '<gold>This will remove bonus range </gold><aqua>[id]</aqua><gold> from </gold><aqua>[number]</aqua><gold> island(s).</gold>'
         success: '<green>Removed bonus range </green><aqua>[id]</aqua><green> from </green><aqua>[number]</aqua><green> island(s).</green>'
+        confirm: '<gold>Run the command again with </gold><aqua>confirm</aqua><gold> to proceed.</gold>'
+        in-progress: '<red>A bonus range purge is already running. Please wait.</red>'
+        failed: '<red>Failed to scan islands. Check the console.</red>'
     register:
       parameters: <player>
       description: register player to unowned [prefix_island] you are on

src/main/resources/locales/es.yml

@@ -260,6 +260,9 @@ commands:
         none: '<red>¡Ninguna isla tiene un rango de bonificación con la id </red><aqua>[id]</aqua><red>!</red>'
         warning: '<gold>Esto eliminará el rango de bonificación </gold><aqua>[id]</aqua><gold> de </gold><aqua>[number]</aqua><gold> isla(s).</gold>'
         success: '<green>Rango de bonificación </green><aqua>[id]</aqua><green> eliminado de </green><aqua>[number]</aqua><green> isla(s).</green>'
+        confirm: '<gold>Vuelve a ejecutar el comando con </gold><aqua>confirm</aqua><gold> para continuar.</gold>'
+        in-progress: '<red>Ya hay una purga de rangos de bonificación en curso. Espera.</red>'
+        failed: '<red>No se pudieron escanear las islas. Revisa la consola.</red>'
     register:
       parameters: <jugador>
       description: registrar jugador en la isla sin dueño en la que estás

src/main/resources/locales/fr.yml

@@ -278,6 +278,9 @@ commands:
         none: '<red>Aucune île n''a de rayon bonus avec l''id </red><aqua>[id]</aqua><red>!</red>'
         warning: '<gold>Ceci supprimera le rayon bonus </gold><aqua>[id]</aqua><gold> de </gold><aqua>[number]</aqua><gold> île(s).</gold>'
         success: '<green>Rayon bonus </green><aqua>[id]</aqua><green> supprimé de </green><aqua>[number]</aqua><green> île(s).</green>'
+        confirm: '<gold>Relancez la commande avec </gold><aqua>confirm</aqua><gold> pour continuer.</gold>'
+        in-progress: '<red>Une purge des rayons bonus est déjà en cours. Veuillez patienter.</red>'
+        failed: '<red>Échec de l''analyse des îles. Consultez la console.</red>'
     register:
       parameters: <joueur>
       description: enregistrer le joueur sur une île sans propriétaire où vous êtes

src/main/resources/locales/hr.yml

@@ -262,6 +262,9 @@ commands:
         none: '<red>Nijedan otok nema bonus raspon s id-om </red><aqua>[id]</aqua><red>!</red>'
         warning: '<gold>Ovo će ukloniti bonus raspon </gold><aqua>[id]</aqua><gold> s </gold><aqua>[number]</aqua><gold> otoka.</gold>'
         success: '<green>Uklonjen bonus raspon </green><aqua>[id]</aqua><green> s </green><aqua>[number]</aqua><green> otoka.</green>'
+        confirm: '<gold>Ponovno pokrenite naredbu s </gold><aqua>confirm</aqua><gold> za potvrdu.</gold>'
+        in-progress: '<red>Čišćenje bonus raspona već je u tijeku. Pričekajte.</red>'
+        failed: '<red>Skeniranje otoka nije uspjelo. Provjerite konzolu.</red>'
     register:
       parameters: <igrač>
       description: registrirajte igrača na nevlasnički otok na kojem se nalazite

src/main/resources/locales/hu.yml

@@ -276,6 +276,9 @@ commands:
         none: '<red>Egyetlen szigetnek sincs </red><aqua>[id]</aqua><red> id-jű bónusz hatótávolsága!</red>'
         warning: '<gold>Ez eltávolítja a(z) </gold><aqua>[id]</aqua><gold> bónusz hatótávolságot </gold><aqua>[number]</aqua><gold> szigetről.</gold>'
         success: '<green>A(z) </green><aqua>[id]</aqua><green> bónusz hatótávolság eltávolítva </green><aqua>[number]</aqua><green> szigetről.</green>'
+        confirm: '<gold>Futtasd újra a parancsot a </gold><aqua>confirm</aqua><gold> kapcsolóval a megerősítéshez.</gold>'
+        in-progress: '<red>Egy bónusz hatótávolság tisztítás már fut. Kérlek várj.</red>'
+        failed: '<red>A szigetek beolvasása sikertelen. Ellenőrizd a konzolt.</red>'
     register:
       parameters: <játékos>
       description: regisztrálj játékost egy ismeretlen szigetre, amelyen tartózkodsz

src/main/resources/locales/id.yml

@@ -263,6 +263,9 @@ commands:
         none: '<red>Tidak ada pulau yang memiliki rentang bonus dengan id </red><aqua>[id]</aqua><red>!</red>'
         warning: '<gold>Ini akan menghapus rentang bonus </gold><aqua>[id]</aqua><gold> dari </gold><aqua>[number]</aqua><gold> pulau.</gold>'
         success: '<green>Rentang bonus </green><aqua>[id]</aqua><green> dihapus dari </green><aqua>[number]</aqua><green> pulau.</green>'
+        confirm: '<gold>Jalankan lagi perintah dengan </gold><aqua>confirm</aqua><gold> untuk melanjutkan.</gold>'
+        in-progress: '<red>Pembersihan rentang bonus sedang berjalan. Mohon tunggu.</red>'
+        failed: '<red>Gagal memindai pulau. Periksa konsol.</red>'
     register:
       parameters: <pemain>
       description: daftarkan pemain ke pulau tak berpemilik tempat Anda berada

src/main/resources/locales/it.yml

@@ -269,6 +269,9 @@ commands:
         none: '<red>Nessuna isola ha un raggio bonus con id </red><aqua>[id]</aqua><red>!</red>'
         warning: '<gold>Questo rimuoverà il raggio bonus </gold><aqua>[id]</aqua><gold> da </gold><aqua>[number]</aqua><gold> isola/e.</gold>'
         success: '<green>Raggio bonus </green><aqua>[id]</aqua><green> rimosso da </green><aqua>[number]</aqua><green> isola/e.</green>'
+        confirm: '<gold>Esegui di nuovo il comando con </gold><aqua>confirm</aqua><gold> per procedere.</gold>'
+        in-progress: '<red>È già in corso una rimozione dei raggi bonus. Attendi.</red>'
+        failed: '<red>Scansione delle isole non riuscita. Controlla la console.</red>'
     register:
       parameters: <giocatore>
       description: registra il giocatore nell'isola senza proprietario sulla quale sei