SLNE-Development · Keviro · May 25, 2026 · May 25, 2026 · May 25, 2026 · May 25, 2026
diff --git a/.github/workflows/verify.yml b/.github/workflows/verify.yml
@@ -0,0 +1,55 @@
+name: Verify
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: verify-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          fetch-depth: 0
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 25
+
+      - uses: gradle/actions/setup-gradle@v4
+
+      # gitpatcher commits every patch into the generated target repository, which git refuses to do
+      # without an identity.
+      - name: Configure git identity
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Apply patches
+        run: ./gradlew applyPatches --stacktrace
+
+      # shadowJar as well as the tests: `test` never builds the artifacts that actually ship, so a break in
+      # the javadoc or shadow configuration would otherwise only surface in the release job on master.
+      # spotless stays out while palantir-java-format is broken on JDK 25.
+      - name: Test and assemble
+        run: ./gradlew testPatched shadowJar --stacktrace
+
+      # A patch that no longer round-trips is the fork's easiest mistake: hand-editing patches/, or editing
+      # the target repository without regenerating. Both produce a tree that builds locally and cannot be
+      # reproduced from the committed patches.
+      - name: Check that the patches are up to date
+        run: |
+          ./gradlew makePatches --stacktrace
+          # Compared against HEAD, not the index: makePatches stages the patches it regenerates, so a plain
+          # `git diff -- patches` compares them against themselves and can never fail.
+          if ! git diff --quiet HEAD -- patches; then
+            echo "::error::patches/ is out of sync with the target repository. Run './gradlew makePatches' and commit the result."
+            git diff --stat HEAD -- patches
+            exit 1
+          fi
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,9 @@
 .gradle
 build/
+
+# The target repository applyPatches generates from upstream + patches/. It carries its own .git, so a
+# `git add -A` here does not skip it - it adds it as a gitlink, with a warning and successfully.
+/inventory-framework/
 !gradle/wrapper/gradle-wrapper.jar
 !**/src/main/**/build/
 !**/src/test/**/build/

diff --git a/build.gradle.kts b/build.gradle.kts
@@ -30,16 +30,32 @@ val isWindows = System.getProperty("os.name")
     .lowercase()
     .contains("windows")
 
-val gradlew = if (isWindows) "gradlew.bat" else "./gradlew"
+// The wrapper is addressed by absolute path: `cmd /c gradlew.bat` resolves against PATH rather than the
+// task's workingDir and fails with "gradlew.bat is either misspelled or could not be found".
+val targetDir = layout.projectDirectory.dir("inventory-framework")
+val gradlew = targetDir.file(if (isWindows) "gradlew.bat" else "gradlew").asFile.absolutePath
 
-listOf("shadowJar", "publish").forEach { taskName ->
+// `test` is already taken by the `java` plugin on this project, so the delegating task carries a distinct
+// name. It is what CI runs to verify a pull request.
+val delegatedTasks = mapOf(
+    "shadowJar" to "shadowJar",
+    "publish" to "publish",
+    "publishToMavenLocal" to "publishToMavenLocal",
+    "testPatched" to "test",
+)
+
+delegatedTasks.forEach { (taskName, delegate) ->
     tasks.register<Exec>(taskName) {
-        group = if (taskName == "shadowJar") "build" else "publishing"
-        description = "Runs './gradlew $taskName' inside inventory-framework."
+        group = when (taskName) {
+            "shadowJar" -> "build"
+            "testPatched" -> "verification"
+            else -> "publishing"
+        }
+        description = "Runs './gradlew $delegate' inside inventory-framework."
 
         dependsOn("applyPatches")
-        workingDir = layout.projectDirectory.dir("inventory-framework").asFile
-        val args = listOf(taskName)
+        workingDir = targetDir.asFile
+        val args = listOf(delegate)
 
         if (isWindows) {
             commandLine("cmd", "/c", gradlew, *args.toTypedArray())

diff --git a/docs/packet-gui-backend.md b/docs/packet-gui-backend.md
diff --git a/docs/testing-with-surf-api.md b/docs/testing-with-surf-api.md
@@ -0,0 +1,113 @@
+# Einen Branch-Build in surf-api testen
+
+`surf-inventory-framework` wird nicht direkt deployed — surf-api zieht es als Maven-Dependency und shaded es
+beim `shadowJar` nach `dev.slne.surf.api.libs.devnatan.inventoryframework`. Um einen Branch dieses Forks auf
+einem Server zu testen, muss er also erst als Artefakt vorliegen, das surf-api auflösen kann.
+
+```
+surf-inventory-framework          surf-api
+  7 Module, group                   Katalog: inventory-framework = "1.0.4"
+  dev.slne.forks.inventoryframework   → inventory-framework-platform-paper
+  Version aus root gradle.properties  → inventory-framework-platform-bukkit
+        │                                        │
+        │  publishToMavenLocal                   │  shadowJar relocated
+        ▼                                        ▼
+      ~/.m2  ──────────────────────────►  surf-api-paper-server-*-all.jar
+```
+
+## Ablauf
+
+**1. Fork lokal publizieren**
+
+`gradle.properties` im Fork-Root trägt die Version. Für Branch-Tests eine SNAPSHOT-Version verwenden —
+Gradle cached Release-Versionen aus mavenLocal und würde beim zweiten Durchlauf das alte Jar nehmen.
+
+```properties
+version=1.0.5-packet-guis-SNAPSHOT
+```
+
+Dann vom Fork-Root aus:
+
+```bash
+./gradlew publishToMavenLocal
+```
+
+Das führt intern `applyPatches` aus und publiziert alle sieben Module nach `~/.m2`. Prüfen:
+
+```bash
+ls ~/.m2/repository/dev/slne/forks/inventoryframework/inventory-framework-platform-bukkit/
+```
+
+**2. surf-api dagegen bauen**
+
+```bash
+cd ../surf-api
+./gradlew :surf-api-paper:surf-api-paper-server:shadowJar \
+  -PinventoryFramework.localVersion=1.0.5-packet-guis-SNAPSHOT
+```
+
+Die Property schaltet in `buildSrc/src/main/kotlin/core-convention.gradle.kts` zwei Dinge frei:
+`mavenLocal()` als Repository und eine `resolutionStrategy`, die jede Dependency der Gruppe
+`dev.slne.forks.inventoryframework` auf diese Version zwingt. Der Katalogeintrag bleibt unangetastet.
+Ohne die Property ist der Block inert — die Änderung ist also commit-fähig und beeinflusst CI nicht.
+
+Zur Kontrolle loggt jedes Projekt beim Konfigurieren:
+
+```
+[surf] :surf-api-paper:surf-api-paper-server: resolving dev.slne.forks.inventoryframework
+       from mavenLocal at 1.0.5-packet-guis-SNAPSHOT
+```
+
+Das fertige Jar liegt unter `surf-api-paper/surf-api-paper-server/build/libs/`.
+
+Wer die Property nicht jedes Mal tippen will, legt sie in eine lokale, nicht eingecheckte
+`gradle.properties` in surf-api.
+
+**3. Auf dem Server aktivieren**
+
+Das Packet-Backend ist opt-in:
+
+```
+-Dinventory-framework.gui-backend=packet
+```
+
+PacketEvents muss installiert sein und vor InventoryFramework laden. Details und die
+Verifikations-Checkliste stehen in `docs/packet-gui-backend.md`.
+
+## Iterieren
+
+Nach jeder Codeänderung im Fork. **Zuerst `makePatches`** — `publishToMavenLocal` hängt an `applyPatches`,
+und das setzt das generierte Repository hart auf die *committeten* Patches zurück. Eine Änderung, die nur im
+generierten Repo committet und noch nicht in einen Patch geschrieben wurde, geht dabei verloren, und der Build
+läuft grün durch, weil er die alten Quellen baut. Nicht committete Änderungen im Arbeitsverzeichnis lassen
+`applyPatches` dagegen mit einem Checkout-Fehler abbrechen.
+
+```bash
+cd surf-inventory-framework
+# Änderung in den Ziel-Commit falten und den Patch neu schreiben:
+(cd inventory-framework && git add -A && git commit --amend --no-edit --author="Keviro <keviro@slne.dev>")
+./gradlew makePatches
+perl -i -pe 's/\r\n/\n/g' patches/0006-*.patch   # makePatches schreibt unter Windows CRLF
+
+./gradlew publishToMavenLocal
+cd ../surf-api && ./gradlew :surf-api-paper:surf-api-paper-server:shadowJar \
+  -PinventoryFramework.localVersion=1.0.5-packet-guis-SNAPSHOT
+```
+
+Weil die Version ein SNAPSHOT ist, zieht Gradle das neu publizierte Jar ohne
+`--refresh-dependencies`.
+
+## Vor dem Merge zurückdrehen
+
+- `gradle.properties` im Fork: SNAPSHOT-Suffix entfernen, also zurück auf eine Release-Version.
+- Die surf-api-Änderung kann bleiben (ohne Property inert) oder wird zurückgenommen.
+- Der Katalogeintrag `inventory-framework` in surf-api wird erst auf die neue Version gehoben, wenn der
+  Fork regulär nach `reposilite.slne.dev/releases` publiziert wurde.
+
+## Warum kein Composite Build
+
+`includeBuild("../surf-inventory-framework/inventory-framework")` mit Dependency-Substitution wäre schneller
+zu iterieren, würde aber das Projekt statt des publizierten Artefakts einbinden. Das Paper-Modul shaded beim
+Publizieren das Bukkit-Modul mit hinein; eine Substitution umgeht das und baut damit etwas anderes als das,
+was produktiv ausgeliefert wird. Für einen Test, der genau die produktive Artefaktform prüfen soll, ist der
+mavenLocal-Umweg das ehrlichere Verfahren.
diff --git a/gradle.properties b/gradle.properties
@@ -1,3 +1,3 @@
 kotlin.code.style=official
 group=dev.slne.forks.inventoryframework
-version=1.0.4
+version=1.0.5
diff --git a/gradlew b/gradlew