feat(harvest): migrate distribution to Java 25 and Purpur

BREAKING CHANGE: New releases require Java 25/Purpur 26.2 and use purpur-harvest-<version>.jar. Runtime SpigotHarvest identity, data folders and crop progression remain unchanged. Replace the old JAR instead of installing both distributions.

.gitea/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
         uses: actions/setup-java@v4
         with:
           distribution: temurin
-          java-version: 17
+          java-version: 25
           cache: gradle
 
       - name: Validate conventional commits
@@ -35,6 +35,6 @@ jobs:
       - name: Upload development artifact
         uses: actions/upload-artifact@v3
         with:
-          name: spigot-harvest-${{ github.sha }}
+          name: purpur-harvest-${{ github.sha }}
           path: build/libs/*.jar
           if-no-files-found: error

.gitea/workflows/release.yml

@@ -21,7 +21,7 @@ jobs:
         uses: actions/setup-java@v4
         with:
           distribution: temurin
-          java-version: 17
+          java-version: 25
           cache: gradle
 
       - name: Set up Node.js
@@ -86,8 +86,8 @@ jobs:
         if: steps.release.outputs.created == 'true'
         uses: actions/upload-artifact@v3
         with:
-          name: spigot-harvest-${{ steps.release.outputs.version }}
+          name: purpur-harvest-${{ steps.release.outputs.version }}
-          path: build/libs/spigot-harvest-${{ steps.release.outputs.version }}.jar
+          path: build/libs/purpur-harvest-${{ steps.release.outputs.version }}.jar
           if-no-files-found: error
 
       - name: Create Gitea release and upload plugin
@@ -101,7 +101,7 @@ jobs:
           PREVIOUS_TAG: ${{ steps.previous_tag.outputs.value }}
         run: |
           api_url="${GITEA_SERVER_URL}/api/v1"
-          jar="build/libs/spigot-harvest-${VERSION}.jar"
+          jar="build/libs/purpur-harvest-${VERSION}.jar"
           export RELEASE_BODY
           if [ -n "$PREVIOUS_TAG" ]; then
             RELEASE_BODY=$(git log --pretty='format:- %s (%h)' "${PREVIOUS_TAG}..HEAD")
@@ -138,4 +138,4 @@ jobs:
             -H "Authorization: token ${GITEA_TOKEN}" \
             -H "Content-Type: application/octet-stream" \
             --data-binary "@${jar}" \
-            "${api_url}/repos/${REPOSITORY}/releases/${release_id}/assets?name=spigot-harvest-${VERSION}.jar"
+            "${api_url}/repos/${REPOSITORY}/releases/${release_id}/assets?name=purpur-harvest-${VERSION}.jar"

AGENTS.md

@@ -0,0 +1,9 @@
+# purpur-harvest agent entrypoint
+
+The canonical stories, engineering guidance, and **all process documents** are in the private [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/index.md).
+
+Before work, read the sibling `../somc-okf/index.md`, `../somc-okf/processes/index.md`, `../somc-okf/projects/purpur-harvest/index.md`, `engineering.md` in that project section, and relevant `../somc-okf/user-stories/purpur-harvest/` stories. Also follow the parent workspace `AGENTS.md` when present.
+
+For standalone checkouts, start at the [project page](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/purpur-harvest/index.md) and [shared process](https://git.garvis.dev/dmg/somc-okf/src/branch/main/processes/development.md). Obtain wiki access before feature work; do not recreate a local knowledge bundle. Source builds do not require private wiki access.
+
+Development follows [Development cycle](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/development-cycle.md): approved stories, failing tests, passing implementation, verification, then source/wiki commit and push. GitOps updates are committed locally **without pushing**; only [Do release](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/do-release.md) authorizes a reviewed GitOps push.

README.md

@@ -1,13 +1,17 @@
-# Spigot Harvest
+# Purpur Harvest
 
-A Spigot 26.2 plugin providing progression-gated, connected crop harvesting and automatic replanting.
+A Purpur 26.2 plugin providing progression-gated, connected crop harvesting and automatic replanting.
 
-The approved behavior is specified in the [OKF design bundle](design/index.md).
+The approved behavior is specified in the [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/purpur-harvest/index.md).
 
 ## Requirements
 
-- Spigot 26.2
+- Purpur 26.2 build 2618
-- Java 17 or newer
+- Java 25
+
+## Distribution migration
+
+New repositories/checkouts/artifacts use `purpur-harvest`; runtime `SpigotHarvest`, Java entrypoints/packages, data folders, commands, permissions and crop progression remain unchanged. New releases no longer support Java 17. Replace the old JAR rather than installing both distributions. Historical tags and `spigot-harvest-*` assets are retained; the prior v1.0.1 download was checked for identical bytes after renaming.
 
 ## Build
 
@@ -15,7 +19,7 @@ The approved behavior is specified in the [OKF design bundle](design/index.md).
 ./gradlew clean check jar
 ```
 
-The plugin JAR is written to `build/libs/`.
+The plugin JAR is written to `build/libs/`. `check` includes `nativeHarvestTest`: it downloads SHA-256-verified Purpur 2618 under `build/harvest-runtime/`, loads native registry/service providers, and runs real item-stack/drop/replant regressions without starting a listening server. Those tests are not replaced by item mocks or excluded from verification.
 
 ## Commands
 

build.gradle.kts

@@ -1,3 +1,6 @@
+import java.net.URI
+import java.security.MessageDigest
+
 plugins {
     java
 }
@@ -9,23 +12,24 @@ version = providers.gradleProperty("releaseVersion")
 
 repositories {
     mavenCentral()
-    maven("https://hub.spigotmc.org/nexus/content/repositories/snapshots/")
+    maven("https://repo.purpurmc.org/snapshots/")
 }
 
 java {
     toolchain {
-        languageVersion = JavaLanguageVersion.of(17)
+        languageVersion = JavaLanguageVersion.of(25)
     }
 }
 
 tasks.withType<JavaCompile>().configureEach {
-    options.compilerArgs.addAll(listOf("-Xlint:all", "-Werror"))
+    // Retain supported legacy Bukkit APIs while preserving runtime compatibility.
+    options.compilerArgs.addAll(listOf("-Xlint:all,-deprecation,-removal", "-Werror"))
 }
 
 dependencies {
-    compileOnly("org.spigotmc:spigot-api:26.2-R0.1-SNAPSHOT")
+    compileOnly("org.purpurmc.purpur:purpur-api:26.2.build.2618-stable")
 
-    testImplementation("org.spigotmc:spigot-api:26.2-R0.1-SNAPSHOT")
+    testImplementation("org.purpurmc.purpur:purpur-api:26.2.build.2618-stable")
     testImplementation(platform("org.junit:junit-bom:5.13.4"))
     testImplementation("org.junit.jupiter:junit-jupiter")
     testImplementation("org.mockito:mockito-core:5.18.0")
@@ -35,8 +39,64 @@ dependencies {
 
 tasks.test {
     useJUnitPlatform()
+    dependsOn(tasks.jar)
+    systemProperty("distribution.jar", tasks.jar.get().archiveFile.get().asFile.absolutePath)
+    systemProperty("distribution.version", project.version.toString())
 }
 
+// Real ItemStack/drop/replant regressions require the declared runtime's registry and service providers.
+val harvestRuntime = layout.buildDirectory.dir("harvest-runtime")
+val downloadHarvestRuntime = tasks.register("downloadHarvestRuntime") {
+    val launcher = harvestRuntime.map { it.file("purpur-26.2-2618.jar") }
+    outputs.file(launcher)
+    doLast {
+        val file = launcher.get().asFile
+        file.parentFile.mkdirs()
+        val connection = URI("https://api.purpurmc.org/v2/purpur/26.2/2618/download").toURL().openConnection()
+        connection.connectTimeout = 30_000
+        connection.readTimeout = 120_000
+        val bytes = connection.getInputStream().use { it.readBytes() }
+        val digest = MessageDigest.getInstance("SHA-256").digest(bytes).joinToString("") { "%02x".format(it) }
+        check(digest == "4a32d046a118804d89ca74ba89b798c98f6d8d1f310c18077ac573597049de31") {
+            "Purpur 2618 checksum mismatch"
+        }
+        file.writeBytes(bytes)
+    }
+}
+val prepareHarvestRuntime = tasks.register<JavaExec>("prepareHarvestRuntime") {
+    dependsOn(downloadHarvestRuntime)
+    javaLauncher = javaToolchains.launcherFor { languageVersion = JavaLanguageVersion.of(25) }
+    classpath = files(harvestRuntime.map { it.file("purpur-26.2-2618.jar") })
+    mainClass = "io.papermc.paperclip.Main"
+    jvmArgs("-Dpaperclip.patchonly=true")
+    workingDir(harvestRuntime)
+    outputs.dir(harvestRuntime.map { it.dir("versions") })
+    outputs.dir(harvestRuntime.map { it.dir("libraries") })
+}
+val nativeTest = sourceSets.create("nativeTest")
+dependencies {
+    add(nativeTest.implementationConfigurationName, platform("org.junit:junit-bom:5.13.4"))
+    add(nativeTest.implementationConfigurationName, "org.junit.jupiter:junit-jupiter")
+    add(nativeTest.implementationConfigurationName, "org.mockito:mockito-core:5.18.0")
+    add(nativeTest.compileOnlyConfigurationName, "org.jetbrains:annotations:26.0.2")
+    add(nativeTest.compileOnlyConfigurationName, "org.checkerframework:checker-qual:3.49.2")
+    add(nativeTest.runtimeOnlyConfigurationName, "org.junit.platform:junit-platform-launcher")
+}
+val nativeRuntimeJars = files(fileTree(harvestRuntime) {
+    include("versions/**/*.jar", "libraries/**/*.jar")
+}).builtBy(prepareHarvestRuntime)
+nativeTest.compileClasspath += sourceSets.main.get().output + nativeRuntimeJars
+nativeTest.runtimeClasspath += sourceSets.main.get().output + nativeRuntimeJars
+val nativeHarvestTest = tasks.register<Test>("nativeHarvestTest") {
+    description = "Runs real item/drop/replant regressions without starting a server"
+    testClassesDirs = nativeTest.output.classesDirs
+    classpath = nativeTest.runtimeClasspath
+    useJUnitPlatform()
+    maxHeapSize = "1G"
+    workingDir(harvestRuntime)
+}
+tasks.check { dependsOn(nativeHarvestTest) }
+
 val pluginVersion = version
 
 tasks.processResources {

design/index.md

@@ -1,15 +0,0 @@
----
-type: Index
-title: Spigot Harvest Design
-description: Entry point for the Spigot Harvest OKF knowledge bundle.
-okf_version: "0.1"
----
-
-# Spigot Harvest Design
-
-This bundle documents per-crop progression, animated connected harvesting, automatic replanting, player feedback, administration, persistence, configuration, and delivery requirements for the Spigot Harvest plugin.
-
-## Explore
-
-- [User stories](user-stories/index.md)
-- [Design log](log.md)

design/log.md

@@ -1,39 +0,0 @@
----
-type: Log
-title: Spigot Harvest Design Log
-description: Chronological record of material decisions affecting the Spigot Harvest design.
----
-
-# Spigot Harvest Design Log
-
-## 2026-08-14 — Initial harvesting progression design
-
-- Initial crop support includes wheat, carrots, potatoes, and beetroot, with an independent Level 0–X progression path for each crop.
-- Normal crop breaking triggers auto-harvest, while sneaking bypasses auto-harvest without preventing the manually broken mature crop from contributing progress.
-- Connected crops may be adjacent in any of the eight horizontal directions and differ by no more than one Y level for each connection.
-- The total operation cap includes the triggering crop and doubles from 4 at Level I through 2,048 at Level X.
-- Level requirements are incremental rather than cumulative and are based on the preceding level's harvest cap: a multiplier of 100 through Level V, 200 for Levels VI–VIII, 300 for Level IX, and 400 for Level X.
-- Automated harvests contribute progression, execute at one crop per server tick by default, and permit only one active auto-harvest operation per player.
-- Qualifying progress displays a player-toggleable boss bar that is enabled by default, persists its preference, and remains visible for five seconds after its latest update by default.
-- Harvested crops are automatically replanted, remaining drops go to the player's inventory, and inventory overflow drops near the player.
-- The project and delivery pipeline will follow the neighboring Spigot Base project where applicable.
-
-## 2026-08-14 — Build and release foundation completed
-
-- Added the Java 17 Gradle/Spigot foundation, strict compiler linting, JUnit 5 lifecycle, plugin metadata, and initial documentation.
-- Added Gitea CI and semantic-release workflows with development and versioned JAR artifacts.
-- Verified the foundation with `./gradlew clean check jar`.
-
-## 2026-08-14 — Initial plugin scope completed
-
-- Implemented independent Level 0–X progression for wheat, carrots, potatoes, and beetroot with validated configuration and atomic UUID-keyed YAML state.
-- Implemented deterministic connected-crop traversal, one-operation-per-player scheduling, one-crop-per-tick harvesting, protection-event checks, automatic replanting, inventory delivery, and overflow drops.
-- Added player status and boss-bar controls, five-second idle progress presentation, unlock titles, administrative inspection and mutations, offline-player lookup, and safe confirmed resets.
-- Developed the progression, traversal, drops, persistence, settings, status, and administration behavior through failing-first automated tests.
-
-## 2026-08-14 — Triggering crop replant fix
-
-- Changed auto-harvest to process and replant the manually broken triggering crop immediately before animating connected crops.
-- Kept the triggering crop inside the level cap, so Level I processes the trigger and at most three connected crops.
-- Added regression coverage for triggering-crop execution, replanting, and operation-cap accounting.
-- Verified the fix with `./gradlew clean check jar`.

design/user-stories/index.md

@@ -1,16 +0,0 @@
----
-type: Index
-title: Spigot Harvest User Stories
-description: Catalog of user stories for the Spigot Harvest plugin.
----
-
-# Spigot Harvest User Stories
-
-1. [US-001: Track crop harvesting progression](us-001-track-crop-harvesting-progression.md)
-2. [US-002: Unlock crop auto-harvest levels](us-002-unlock-crop-auto-harvest-levels.md)
-3. [US-003: Harvest connected mature crops](us-003-harvest-connected-mature-crops.md)
-4. [US-004: Replant crops and distribute drops](us-004-replant-crops-and-distribute-drops.md)
-5. [US-005: View crop progress and notifications](us-005-view-crop-progress-and-notifications.md)
-6. [US-006: Administer player harvest progression](us-006-administer-player-harvest-progression.md)
-7. [US-007: Configure and persist harvesting behavior](us-007-configure-and-persist-harvesting-behavior.md)
-8. [US-008: Build and release the plugin](us-008-build-and-release-plugin.md)

design/user-stories/us-001-track-crop-harvesting-progression.md

@@ -1,27 +0,0 @@
----
-type: User Story
-title: "US-001: Track crop harvesting progression"
-description: Track qualifying harvest activity independently for each player and supported crop.
-status: done
----
-
-# US-001: Track crop harvesting progression
-
-As a **player**, I want my mature crop harvests tracked separately by crop so that my experience with each crop unlocks its own harvesting benefits.
-
-## Acceptance criteria
-
-- [x] Initial progression paths exist independently for wheat, carrots, potatoes, and beetroot.
-- [x] A crop contributes progress only when it is fully grown at the time a player harvests it.
-- [x] Only crops harvested by a player in Survival mode contribute progress by default.
-- [x] A manually broken mature crop contributes one unit to its matching crop path.
-- [x] Each mature crop collected by an auto-harvest operation contributes one unit to the player who started that operation.
-- [x] Sneaking prevents a manual break from starting auto-harvest but does not prevent the mature triggering crop from contributing progress.
-- [x] Immature crops, unsupported crops, and non-harvest block changes do not contribute progress.
-- [x] Progress is associated with the player's UUID and survives reconnects and server restarts.
-
-## Related
-
-- [US-002: Unlock crop auto-harvest levels](us-002-unlock-crop-auto-harvest-levels.md)
-- [US-003: Harvest connected mature crops](us-003-harvest-connected-mature-crops.md)
-- [US-007: Configure and persist harvesting behavior](us-007-configure-and-persist-harvesting-behavior.md)

design/user-stories/us-002-unlock-crop-auto-harvest-levels.md

@@ -1,36 +0,0 @@
----
-type: User Story
-title: "US-002: Unlock crop auto-harvest levels"
-description: Let players earn ten independently configured auto-harvest levels for every supported crop.
-status: done
----
-
-# US-002: Unlock crop auto-harvest levels
-
-As a **player**, I want increasingly large auto-harvest limits as I gain experience with a crop so that repeated farming becomes progressively more efficient.
-
-## Acceptance criteria
-
-- [x] Every supported crop has independent levels from Level 0 through Level X.
-- [x] Level 0 provides normal harvesting without connected auto-harvest.
-- [x] Progress toward a level is incremental and resets to zero when that level is earned.
-- [x] Excess progress from a single progression update carries into the next level rather than being discarded.
-- [x] The default Level 0 to I requirement is 100 mature crops and Level I permits an operation containing at most 4 crops.
-- [x] The default Level I to II requirement is 400 mature crops and Level II permits at most 8 crops.
-- [x] The default Level II to III requirement is 800 mature crops and Level III permits at most 16 crops.
-- [x] The default Level III to IV requirement is 1,600 mature crops and Level IV permits at most 32 crops.
-- [x] The default Level IV to V requirement is 3,200 mature crops and Level V permits at most 64 crops.
-- [x] The default Level V to VI requirement is 12,800 mature crops and Level VI permits at most 128 crops.
-- [x] The default Level VI to VII requirement is 25,600 mature crops and Level VII permits at most 256 crops.
-- [x] The default Level VII to VIII requirement is 51,200 mature crops and Level VIII permits at most 512 crops.
-- [x] The default Level VIII to IX requirement is 153,600 mature crops and Level IX permits at most 1,024 crops.
-- [x] The default Level IX to X requirement is 409,600 mature crops and Level X permits at most 2,048 crops.
-- [x] Each requirement and operation cap can be configured independently without changing another crop's earned player state.
-- [x] An auto-harvest operation uses the cap held when the operation starts; unlocking a level during that operation does not enlarge the operation already in progress.
-- [x] Reaching Level X stops further level progression without preventing harvesting or status display.
-
-## Related
-
-- [US-001: Track crop harvesting progression](us-001-track-crop-harvesting-progression.md)
-- [US-003: Harvest connected mature crops](us-003-harvest-connected-mature-crops.md)
-- [US-005: View crop progress and notifications](us-005-view-crop-progress-and-notifications.md)

design/user-stories/us-003-harvest-connected-mature-crops.md

@@ -1,35 +0,0 @@
----
-type: User Story
-title: "US-003: Harvest connected mature crops"
-description: Animate bounded harvesting across connected mature crops when a player performs a normal crop break.
-status: done
----
-
-# US-003: Harvest connected mature crops
-
-As a **player**, I want one normal crop break to harvest a connected area at a visible pace so that unlocked farming feels powerful and satisfying without harming server performance.
-
-## Acceptance criteria
-
-- [x] Normally breaking a fully grown supported crop starts auto-harvest when the player has at least Level I for that crop.
-- [x] Breaking while sneaking performs normal single-crop harvesting and never starts auto-harvest.
-- [x] The manually broken triggering crop is included in the operation's maximum crop count, so Level I processes the trigger plus no more than three connected crops.
-- [x] Auto-harvest traverses only fully grown crops of the same type as the triggering crop.
-- [x] A crop is connected when its horizontal position touches the current crop in any of the eight directions and its Y coordinate differs from the current crop by no more than one block.
-- [x] Connectivity is evaluated per link, allowing a connected operation to follow gradual rises and drops.
-- [x] Traversal is deterministic and never processes the same block more than once in an operation.
-- [x] The operation stops when it reaches the player's crop-level cap or no eligible connected crop remains.
-- [x] Auto-harvest processes a configurable number of crops per server tick, defaulting to one.
-- [x] A player can have no more than one active auto-harvest operation at a time.
-- [x] A normal crop broken while that player already has an active operation is harvested normally and may contribute progress, but it does not start or join another operation.
-- [x] Auto-harvest does not force-load chunks or continue into unloaded chunks.
-- [x] A crop that is no longer mature or matching when its turn arrives is skipped safely.
-- [x] Crop breaks denied by the server or another protection plugin are left unchanged, yield no drops, and contribute no progress.
-- [x] An operation ends safely when exhausted, cancelled, the player disconnects, or the plugin disables.
-- [x] Separate players may run independent auto-harvest operations concurrently.
-
-## Related
-
-- [US-002: Unlock crop auto-harvest levels](us-002-unlock-crop-auto-harvest-levels.md)
-- [US-004: Replant crops and distribute drops](us-004-replant-crops-and-distribute-drops.md)
-- [US-007: Configure and persist harvesting behavior](us-007-configure-and-persist-harvesting-behavior.md)

design/user-stories/us-004-replant-crops-and-distribute-drops.md

@@ -1,30 +0,0 @@
----
-type: User Story
-title: "US-004: Replant crops and distribute drops"
-description: Automatically replant harvested crops and deliver their remaining drops safely to the player.
-status: done
----
-
-# US-004: Replant crops and distribute drops
-
-As a **player**, I want harvested crops replanted and their useful drops delivered to me so that auto-harvest saves repetitive work without duplicating or losing items.
-
-## Acceptance criteria
-
-- [x] The manually broken crop that starts auto-harvest is harvested and replanted exactly once as the first crop in the operation.
-- [x] Automated regression tests cover the triggering-crop planning, cap accounting, and replant path.
-- [x] Every crop successfully harvested by an auto-harvest operation is immediately replanted as the same crop at its minimum growth stage.
-- [x] Replanting consumes one appropriate planting item from that crop's generated drops before remaining drops are delivered.
-- [x] Wheat consumes one wheat seed, carrots consume one carrot, potatoes consume one potato, and beetroot consumes one beetroot seed when replanted.
-- [x] A crop is not auto-harvested when its generated drops cannot supply the item required to replant it.
-- [x] Drop quantities follow normal server crop-drop behavior and applicable tool enchantments where supported by the Spigot API.
-- [x] Replanting does not consume an additional item from the player's existing inventory.
-- [x] Remaining planting items, produce, and other generated drops are inserted into the initiating player's inventory.
-- [x] Items that do not fit in the inventory are dropped safely near the initiating player rather than at every harvested crop.
-- [x] No crop harvest duplicates or silently discards generated items.
-- [x] If the initiating player becomes unavailable, the operation ends without harvesting further crops.
-
-## Related
-
-- [US-003: Harvest connected mature crops](us-003-harvest-connected-mature-crops.md)
-- [US-007: Configure and persist harvesting behavior](us-007-configure-and-persist-harvesting-behavior.md)

design/user-stories/us-005-view-crop-progress-and-notifications.md

@@ -1,33 +0,0 @@
----
-type: User Story
-title: "US-005: View crop progress and notifications"
-description: Give players command and boss-bar feedback about each crop's current progression.
-status: done
----
-
-# US-005: View crop progress and notifications
-
-As a **player**, I want to inspect crop progression and see recent progress updates so that I understand my current benefits and next unlock.
-
-## Acceptance criteria
-
-- [x] `/harvest` and `/harvest status` display a concise summary of all supported crop paths and the player's current boss-bar preference.
-- [x] `/harvest status <crop>` displays that crop's earned level, current level-local progress, next requirement, and current and next operation caps.
-- [x] Level X status clearly reports that the crop path is complete.
-- [x] `/harvest bossbar enable` enables progress boss bars idempotently, and `/harvest bossbar disable` disables them idempotently.
-- [x] Boss bars are enabled by default.
-- [x] Disabling boss bars does not affect progression, unlock notifications, or command-based status display.
-- [x] Crop names and boss-bar modes are offered through autocomplete, and invalid or extra arguments show friendly usage guidance.
-- [x] Every qualifying manual or automated harvest updates a crop-specific progress boss bar for the initiating player when boss bars are enabled.
-- [x] Boss-bar text identifies the crop and accurately displays current level-local progress and its requirement.
-- [x] Boss-bar fill never falls below zero or exceeds 100 percent.
-- [x] The boss bar remains visible for a configurable duration after the latest progress update, defaulting to five seconds.
-- [x] A new qualifying update resets the boss bar's disappearance timer.
-- [x] Unlocking a crop level displays a prominent one-time notification identifying the crop, new level, and new operation cap.
-- [x] Unlock notifications do not repeat after reconnecting or restarting.
-
-## Related
-
-- [US-001: Track crop harvesting progression](us-001-track-crop-harvesting-progression.md)
-- [US-002: Unlock crop auto-harvest levels](us-002-unlock-crop-auto-harvest-levels.md)
-- [US-006: Administer player harvest progression](us-006-administer-player-harvest-progression.md)

design/user-stories/us-006-administer-player-harvest-progression.md

@@ -1,30 +0,0 @@
----
-type: User Story
-title: "US-006: Administer player harvest progression"
-description: Let administrators inspect, correct, and reset player crop progression safely through commands.
-status: done
----
-
-# US-006: Administer player harvest progression
-
-As a **server administrator**, I want command-based controls for crop progression so that I can inspect players and correct their state safely.
-
-## Acceptance criteria
-
-- [x] Administrative commands require `spigotharvest.admin`, which server operators receive by default.
-- [x] Administrative player arguments safely resolve online players and previously known offline players.
-- [x] Player state remains keyed by UUID while retaining the latest known name for lookup and display.
-- [x] `/harvestadmin status <player> [crop]` displays the selected player's crop levels, level-local progress, and any active operation.
-- [x] `/harvestadmin setlevel <player> <crop> <0|I|II|III|IV|V|VI|VII|VIII|IX|X>` sets that crop's level and resets its level-local progress.
-- [x] `/harvestadmin setprogress <player> <crop> <amount>` sets level-local progress and consistently evaluates any reached levels, carrying excess progress forward.
-- [x] `/harvestadmin reset <player> <crop>` resets only the selected crop to Level 0 with zero progress.
-- [x] `/harvestadmin reset <player> all confirm` resets all crop progression only after explicit confirmation.
-- [x] A reset or level reduction cancels the player's active operation when that operation would exceed the resulting entitlement.
-- [x] Every successful mutation reports exactly what changed.
-- [x] Invalid requests make no partial changes and provide friendly usage guidance.
-- [x] Permission-aware autocomplete offers subcommands, online and known offline players, supported crops, valid levels, and reset confirmation.
-
-## Related
-
-- [US-005: View crop progress and notifications](us-005-view-crop-progress-and-notifications.md)
-- [US-007: Configure and persist harvesting behavior](us-007-configure-and-persist-harvesting-behavior.md)

design/user-stories/us-007-configure-and-persist-harvesting-behavior.md

@@ -1,33 +0,0 @@
----
-type: User Story
-title: "US-007: Configure and persist harvesting behavior"
-description: Give operators validated configuration and durable storage for crop progression and harvesting behavior.
-status: done
----
-
-# US-007: Configure and persist harvesting behavior
-
-As a **server operator**, I want harvesting behavior to be configurable and player progression to be durable so that the plugin remains predictable across restarts and server changes.
-
-## Acceptance criteria
-
-- [x] Configuration defines supported crops and the block material, maturity rule, and planting item for each crop.
-- [x] Configuration defines every level-local requirement and operation cap independently for each supported crop.
-- [x] Configuration defines eligible game modes, crops processed per tick, boss-bar idle duration, and unlock-notification timing.
-- [x] Defaults match the crops, requirements, caps, one-crop-per-tick pace, Survival-only progression, and five-second boss-bar duration documented by related stories.
-- [x] Requirements and caps are positive, representable, and sequentially coherent.
-- [x] Processing rates and notification durations reject unsafe or nonsensical values.
-- [x] Invalid required configuration prevents partial plugin initialization and produces a clear server log message.
-- [x] UUID-keyed state persists latest known player names, each crop's earned level and level-local progress, and the player's boss-bar preference.
-- [x] Existing player records without a boss-bar preference safely default to enabled.
-- [x] Active auto-harvest operations are transient and do not resume after a restart or reconnect.
-- [x] State is saved safely so a failed write does not replace valid persisted state with a partial document.
-- [x] Corrupt or invalid records are handled defensively and cannot silently grant progression or larger operation caps.
-- [x] Unknown forward-compatible configuration and state fields are preserved where practical.
-
-## Related
-
-- [US-001: Track crop harvesting progression](us-001-track-crop-harvesting-progression.md)
-- [US-003: Harvest connected mature crops](us-003-harvest-connected-mature-crops.md)
-- [US-006: Administer player harvest progression](us-006-administer-player-harvest-progression.md)
-- [US-008: Build and release the plugin](us-008-build-and-release-plugin.md)

design/user-stories/us-008-build-and-release-plugin.md

@@ -1,27 +0,0 @@
----
-type: User Story
-title: "US-008: Build and release the plugin"
-description: Give maintainers repeatable Spigot builds, automated verification, and versioned Gitea releases.
-status: done
----
-
-# US-008: Build and release the plugin
-
-As a **plugin maintainer**, I want automated builds and releases modeled on Spigot Base so that tested, correctly versioned artifacts can be distributed consistently.
-
-## Acceptance criteria
-
-- [x] The Gradle project compiles against Spigot API `26.2-R0.1-SNAPSHOT` using a Java 17 toolchain.
-- [x] Compiler lint warnings fail the build.
-- [x] Automated JUnit 5 tests run as part of the Gradle check lifecycle.
-- [x] Pushes and pull requests build and test the plugin in Gitea Actions.
-- [x] Pull requests validate conventional commit messages.
-- [x] CI stores a development JAR as a workflow artifact.
-- [x] Main-branch conventional commits drive semantic versioning.
-- [x] A successful release builds a versioned JAR and attaches it to the corresponding Gitea release.
-- [x] Build files, Gradle wrapper, workflows, and release behavior follow `../spigot-base/` where applicable while using Spigot Harvest names and identifiers.
-
-## Related
-
-- [US-007: Configure and persist harvesting behavior](us-007-configure-and-persist-harvesting-behavior.md)
-- [User-story catalog](index.md)

settings.gradle.kts

@@ -1 +1 @@
-rootProject.name = "spigot-harvest"
+rootProject.name = "purpur-harvest"

src/nativeTest/java/games/dmg/spigotharvest/CropDropPlanTest.java

@@ -9,6 +9,9 @@ import org.bukkit.inventory.ItemStack;
 import org.junit.jupiter.api.Test;
 
 final class CropDropPlanTest {
+    @org.junit.jupiter.api.BeforeAll
+    static void bootstrap() throws Exception { NativeRuntime.bootstrap(); }
+
     @Test
     void consumesExactlyOnePlantingItemAndKeepsRemainingDrops() {
         CropDropPlan plan = CropDropPlan.create(

src/nativeTest/java/games/dmg/spigotharvest/NativeRuntime.java

@@ -0,0 +1,61 @@
+package games.dmg.spigotharvest;
+
+import java.util.List;
+import java.util.stream.Stream;
+import net.minecraft.SharedConstants;
+import net.minecraft.commands.Commands;
+import net.minecraft.core.HolderLookup;
+import net.minecraft.core.LayeredRegistryAccess;
+import net.minecraft.core.Registry;
+import net.minecraft.core.RegistryAccess;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.RegistryDataLoader;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.server.MinecraftServer;
+import net.minecraft.server.RegistryLayer;
+import net.minecraft.server.ReloadableServerResources;
+import net.minecraft.server.packs.PackType;
+import net.minecraft.server.packs.repository.ServerPacksSource;
+import net.minecraft.server.packs.resources.MultiPackResourceManager;
+import net.minecraft.server.permissions.LevelBasedPermissionSet;
+import net.minecraft.tags.TagLoader;
+import net.minecraft.util.Util;
+import net.minecraft.world.flag.FeatureFlags;
+import net.minecraft.world.level.DataPackConfig;
+import net.minecraft.world.level.WorldDataConfiguration;
+import org.bukkit.craftbukkit.CraftRegistry;
+
+/** Loads vanilla registries/tags/components using the same path as the server's own tests. */
+final class NativeRuntime {
+    private NativeRuntime() {}
+    private static boolean ready;
+
+    static synchronized void bootstrap() throws Exception {
+        if (ready) { return; }
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+        var flags = FeatureFlags.VANILLA_SET;
+        var packs = ServerPacksSource.createVanillaTrustedRepository();
+        MinecraftServer.configurePackRepository(packs, new WorldDataConfiguration(new DataPackConfig(
+                FeatureFlags.REGISTRY.toNames(flags).stream().map(Identifier::getPath).toList(), List.of()), flags), true, false);
+        try (var resources = new MultiPackResourceManager(PackType.SERVER_DATA, packs.openAllSelected())) {
+            LayeredRegistryAccess<RegistryLayer> layers = RegistryLayer.createRegistryAccess();
+            List<Registry.PendingTags<?>> tags = TagLoader.loadTagsForExistingRegistries(resources, layers.getLayer(RegistryLayer.STATIC));
+            List<HolderLookup.RegistryLookup<?>> lookups = TagLoader.buildUpdatedLookups(layers.getAccessForLoading(RegistryLayer.WORLDGEN), tags);
+            RegistryAccess.Frozen worldgen = RegistryDataLoader.load(resources, lookups,
+                    RegistryDataLoader.WORLDGEN_REGISTRIES, Util.backgroundExecutor()).join();
+            layers = layers.replaceFrom(RegistryLayer.WORLDGEN, worldgen);
+            RegistryAccess.Frozen dimensions = RegistryDataLoader.load(resources,
+                    Stream.concat(lookups.stream(), worldgen.listRegistries()).toList(),
+                    RegistryDataLoader.DIMENSION_REGISTRIES, Util.backgroundExecutor()).join();
+            layers = layers.replaceFrom(RegistryLayer.DIMENSIONS, dimensions);
+            Class.forName(org.bukkit.Registry.class.getName());
+            var datapack = ReloadableServerResources.loadResources(resources, layers, tags, flags,
+                    Commands.CommandSelection.DEDICATED, LevelBasedPermissionSet.ALL_PERMISSIONS,
+                    Util.backgroundExecutor(), Runnable::run).join();
+            datapack.updateComponentsAndStaticRegistryTags();
+            CraftRegistry.setMinecraftRegistry(layers.compositeAccess().freeze());
+        }
+        ready = true;
+    }
+}

src/nativeTest/java/games/dmg/spigotharvest/TriggerCropReplantTest.java

@@ -20,6 +20,9 @@ import org.bukkit.scheduler.BukkitTask;
 import org.junit.jupiter.api.Test;
 
 final class TriggerCropReplantTest {
+    @org.junit.jupiter.api.BeforeAll
+    static void bootstrap() throws Exception { NativeRuntime.bootstrap(); }
+
     @Test
     void startImmediatelyHarvestsAndReplantsTriggerExactlyOnce() {
         HarvestProgressService progress = mock(HarvestProgressService.class);

src/test/java/games/dmg/spigotharvest/PurpurDistributionTest.java

@@ -0,0 +1,53 @@
+package games.dmg.spigotharvest;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.io.DataInputStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Map;
+import java.util.jar.JarFile;
+import org.junit.jupiter.api.Test;
+import org.yaml.snakeyaml.Yaml;
+
+class PurpurDistributionTest {
+    @Test
+    void packagesNewNameWithoutChangingRuntimeIdentityOrBundlingTheApi() throws Exception {
+        Path artifact = Path.of(System.getProperty("distribution.jar"));
+        String version = System.getProperty("distribution.version");
+        assertEquals("purpur-harvest-" + version + ".jar", artifact.getFileName().toString());
+        try (var jar = new JarFile(artifact.toFile())) {
+            Map<?, ?> metadata = new Yaml().load(jar.getInputStream(jar.getJarEntry("plugin.yml")));
+            assertEquals(version, metadata.get("version"));
+            assertEquals("SpigotHarvest", metadata.get("name"), "Retain the data directory and persistent namespace");
+            assertEquals("games.dmg.spigotharvest.SpigotHarvestPlugin", metadata.get("main"));
+            assertTrue(((Map<?, ?>) metadata.get("permissions")).containsKey("spigotharvest.admin"));
+            assertFalse(jar.stream().anyMatch(entry -> entry.getName().startsWith("org/bukkit/")
+                || entry.getName().startsWith("org/purpurmc/") || entry.getName().endsWith("Test.class")));
+        }
+    }
+
+    @Test
+    void pluginBytecodeTargetsJava25() throws Exception {
+        try (var jar = new JarFile(System.getProperty("distribution.jar"));
+             var bytecode = new DataInputStream(jar.getInputStream(
+                 jar.getJarEntry("games/dmg/spigotharvest/SpigotHarvestPlugin.class")))) {
+            assertEquals(0xCAFEBABE, bytecode.readInt());
+            bytecode.readUnsignedShort();
+            assertEquals(69, bytecode.readUnsignedShort());
+        }
+    }
+
+    @Test
+    void releaseAndCiAgreeWithThePurpurDistributionNameAndToolchain() throws Exception {
+        String build = Files.readString(Path.of("build.gradle.kts"));
+        assertTrue(build.contains("purpur-api:26.2.build.2618-stable"));
+        assertFalse(build.contains("org.spigotmc:spigot-api"));
+        for (String workflow : new String[] {"ci.yml", "release.yml"}) {
+            String content = Files.readString(Path.of(".gitea/workflows", workflow));
+            assertTrue(content.contains("java-version: 25"));
+            assertTrue(content.contains("purpur-harvest-"), workflow);
+            assertFalse(content.contains("spigot-harvest-"), workflow);
+        }
+    }
+}