build: Kotlin DSL target matrix + Minecraft 26.2 support

.github/workflows/ci-dev.yml

@@ -18,7 +18,6 @@ jobs:
         with:
           distribution: 'temurin'
           java-version: '25'
-          cache: 'gradle'
       - uses: gradle/actions/setup-gradle@v3
       - id: matrix
         run: |
@@ -38,7 +37,6 @@ jobs:
         with:
           distribution: 'temurin'
           java-version: '25'
-          cache: 'gradle'
       - uses: gradle/actions/setup-gradle@v3
       - run: chmod +x ./gradlew
       - run: ./gradlew buildScenario checkScenario -Ptarget=${{ matrix.target }}

.github/workflows/ci.yml

@@ -18,14 +18,19 @@ jobs:
         with:
           distribution: 'temurin'
           java-version: '25'
-          cache: 'gradle'
+      # Gradle caching is owned by setup-gradle alone. Letting setup-java also
+      # cache 'gradle' had both actions restore ~/.gradle, layering a stale
+      # Kotlin incremental/compiled-classes state from other branches over this
+      # checkout — which surfaced as bogus "unresolved reference"/type-mismatch
+      # errors in build-logic that never reproduce on a clean build.
       - uses: gradle/actions/setup-gradle@v3
       - run: chmod +x ./gradlew
       # Run inside the included build so only build-logic is configured — running
       # `:build-logic:test` from the root configures every module (incl. the
       # Fabric/Loom ones), which needlessly fetches Minecraft and flakes on the
-      # Loom cache/checksum in CI.
-      - run: ./gradlew -p build-logic test
+      # Loom cache/checksum in CI. `clean` first so no cross-branch incremental
+      # Kotlin state is reused.
+      - run: ./gradlew -p build-logic clean test
 
   # Single source of truth: the target list comes from targets.properties
   # via printBuildMatrix — never hardcoded here.
@@ -39,7 +44,7 @@ jobs:
         with:
           distribution: 'temurin'
           java-version: '25'
-          cache: 'gradle'
+      # Gradle caching is owned by setup-gradle alone (see build-logic-test).
       - uses: gradle/actions/setup-gradle@v3
       - id: matrix
         run: |
@@ -59,7 +64,7 @@ jobs:
         with:
           distribution: 'temurin'
           java-version: '25'
-          cache: 'gradle'
+      # Gradle caching is owned by setup-gradle alone (see build-logic-test).
       - uses: gradle/actions/setup-gradle@v3
       - run: chmod +x ./gradlew
       - run: ./gradlew buildScenario checkScenario -Ptarget=${{ matrix.target }}

.github/workflows/publish-javadoc.yml

@@ -0,0 +1,67 @@
+name: publish-javadoc
+
+on:
+  # Dispatched by release.yml after the tag is created (alongside publish-maven),
+  # and runnable manually. Generates the aggregated, themed Javadoc for the
+  # common modules and uploads it to the self-hosted Reposilite as a single zip
+  # at a stable, version-independent path. The docs site (MagicUtilsWebsite)
+  # downloads that zip during its Docker build and serves it under /javadoc.
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version being published (informational)"
+        required: false
+        default: ""
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-javadoc
+  cancel-in-progress: true
+
+jobs:
+  publish-javadoc:
+    runs-on: ubuntu-latest
+    env:
+      PUBLISH_USER: ${{ secrets.MAVEN_PUBLISH_USER }}
+      PUBLISH_TOKEN: ${{ secrets.MAVEN_PUBLISH_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.sha }}
+      - uses: actions/setup-java@v5
+        with:
+          distribution: 'temurin'
+          java-version: '25'
+      - uses: gradle/actions/setup-gradle@v3
+
+      - name: Generate aggregated Javadoc zip
+        run: |
+          chmod +x ./gradlew
+          ./gradlew aggregatedJavadocZip
+
+      - name: Resolve upload URL
+        id: coords
+        run: |
+          REPO_URL=$(grep -E '^repo\.url=' gradle/publishing.properties | head -n1 | cut -d= -f2- | tr -d '[:space:]')
+          # Stable path: the docs build always fetches the latest published tree.
+          # A versioned copy is kept too, for reference/rollback.
+          echo "latest_url=${REPO_URL}/dev/ua/theroer/magicutils-javadoc/latest/magicutils-javadoc.zip" >> "$GITHUB_OUTPUT"
+          VERSION="${{ inputs.version }}"
+          if [ -n "$VERSION" ]; then
+            echo "version_url=${REPO_URL}/dev/ua/theroer/magicutils-javadoc/${VERSION}/magicutils-javadoc.zip" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Upload to Reposilite
+        run: |
+          ZIP=build/docs/magicutils-javadoc.zip
+          test -f "$ZIP" || { echo "Javadoc zip not found at $ZIP"; exit 1; }
+          echo "Uploading to ${{ steps.coords.outputs.latest_url }}"
+          curl --fail-with-body -sS -u "$PUBLISH_USER:$PUBLISH_TOKEN" \
+            -T "$ZIP" "${{ steps.coords.outputs.latest_url }}"
+          if [ -n "${{ steps.coords.outputs.version_url }}" ]; then
+            echo "Uploading versioned copy to ${{ steps.coords.outputs.version_url }}"
+            curl --fail-with-body -sS -u "$PUBLISH_USER:$PUBLISH_TOKEN" \
+              -T "$ZIP" "${{ steps.coords.outputs.version_url }}"
+          fi

.github/workflows/publish-maven.yml

@@ -3,8 +3,15 @@ name: publish-maven
 on:
   # Dispatched by release.yml after the tag is created (documentation moved to
   # the separate MagicUtilsWebsite project, so there is no docs workflow to chain
-  # from anymore). Also runnable manually.
+  # from anymore). Also runnable manually. The version is resolved from the
+  # checked-out gradle.properties; the input exists only so release.yml can pass
+  # it through for traceability without a dispatch error.
   workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version being published (informational)"
+        required: false
+        default: ""
 
 # Publishing targets the self-hosted Reposilite (maven.theroer.dev) over HTTPS,
 # so no repository write access to this GitHub repo is needed anymore.
@@ -32,7 +39,6 @@ jobs:
         with:
           distribution: 'temurin'
           java-version: '25'
-          cache: 'gradle'
       - uses: gradle/actions/setup-gradle@v3
       - id: matrix
         run: |
@@ -65,7 +71,6 @@ jobs:
         with:
           distribution: 'temurin'
           java-version: '25'
-          cache: 'gradle'
       - uses: gradle/actions/setup-gradle@v3
       - name: Publish ${{ matrix.unit.target }}
         run: |
@@ -92,7 +97,6 @@ jobs:
         with:
           distribution: 'temurin'
           java-version: '25'
-          cache: 'gradle'
       - uses: gradle/actions/setup-gradle@v3
       - name: Publish build-logic plugins
         run: |

.github/workflows/release.yml

@@ -28,7 +28,6 @@ jobs:
         with:
           distribution: 'temurin'
           java-version: '25'
-          cache: 'gradle'
 
       - uses: gradle/actions/setup-gradle@v3
 
@@ -101,3 +100,14 @@ jobs:
           gh workflow run publish-maven.yml --repo "$GITHUB_REPOSITORY" --ref "$TAG" \
             -f version="$VERSION"
           echo "Dispatched publish-maven.yml for $TAG"
+      - name: Dispatch Javadoc publish
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ needs.resolve.outputs.version }}"
+          TAG="${{ needs.resolve.outputs.tag }}"
+          # Aggregated, themed Javadoc for the common modules is generated and
+          # uploaded to Reposilite; the docs site pulls it in at Docker build time.
+          gh workflow run publish-javadoc.yml --repo "$GITHUB_REPOSITORY" --ref "$TAG" \
+            -f version="$VERSION"
+          echo "Dispatched publish-javadoc.yml for $TAG"

.gitignore

@@ -123,6 +123,9 @@ venv/
 
 # Maven (if used alongside Gradle)
 target/
+# but not the build-logic source package that happens to be named target/
+!build-logic/src/main/kotlin/dev/ua/theroer/magicutils/build/target/
+!build-logic/src/main/kotlin/dev/ua/theroer/magicutils/build/target/**
 pom.xml.tag
 pom.xml.releaseBackup
 pom.xml.versionsBackup

build-logic/build.gradle.kts

@@ -57,6 +57,23 @@ dependencies {
     implementation("fabric-loom:fabric-loom.gradle.plugin:${project.property("fabricLoomVersion")}")
     implementation("net.fabricmc.fabric-loom:net.fabricmc.fabric-loom.gradle.plugin:${project.property("fabricLoomVersion")}")
 
+    // jpenilla run-* task plugins, applied by the consumer-* plugins only when a
+    // consumer opts into `devServer {}`. run-paper carries the Paper+Folia
+    // runners; run-velocity/run-waterfall carry the proxy runners. Applied via
+    // their plugin *marker* artifacts (same mechanism as Loom above) so
+    // `pluginManager.apply(id)` resolves them; their task types are configured
+    // by name, with no compile-time API import into build-logic.
+    val runPaperVersion = project.property("runPaperVersion")
+    val runProxyVersion = project.property("runProxyVersion")
+    implementation("xyz.jpenilla.run-paper:xyz.jpenilla.run-paper.gradle.plugin:$runPaperVersion")
+    implementation("xyz.jpenilla.run-velocity:xyz.jpenilla.run-velocity.gradle.plugin:$runPaperVersion")
+    implementation("xyz.jpenilla.run-waterfall:xyz.jpenilla.run-waterfall.gradle.plugin:$runProxyVersion")
+
+    // ModDevGradle marker, applied by consumer-neoforge via pluginManager.apply(id).
+    // Its API is not imported into build-logic; the neoForge extension is reached
+    // reflectively so only the marker (not moddev's types) is needed here.
+    implementation("net.neoforged.moddev:net.neoforged.moddev.gradle.plugin:${project.property("neoForgeModdevVersion")}")
+
     testImplementation(platform("org.junit:junit-bom:5.11.3"))
     testImplementation("org.junit.jupiter:junit-jupiter")
     testRuntimeOnly("org.junit.platform:junit-platform-launcher")
@@ -82,59 +99,85 @@ gradlePlugin {
     plugins {
         register("magicutilsTarget") {
             id = "magicutils.target"
-            implementationClass = "MagicUtilsTargetPlugin"
+            implementationClass = "dev.ua.theroer.magicutils.build.matrix.MagicUtilsTargetPlugin"
         }
         register("magicutilsMatrixSettings") {
             id = "magicutils.matrix-settings"
-            implementationClass = "MagicUtilsMatrixSettingsPlugin"
+            implementationClass = "dev.ua.theroer.magicutils.build.matrix.MagicUtilsMatrixSettingsPlugin"
         }
         register("magicutilsMatrixRoot") {
             id = "magicutils.matrix-root"
-            implementationClass = "MagicUtilsMatrixRootPlugin"
+            implementationClass = "dev.ua.theroer.magicutils.build.matrix.MagicUtilsMatrixRootPlugin"
         }
         register("magicutilsRepositories") {
             id = "magicutils.repositories"
-            implementationClass = "MagicUtilsRepositoriesPlugin"
+            implementationClass = "dev.ua.theroer.magicutils.build.support.MagicUtilsRepositoriesPlugin"
         }
         register("magicutilsCommon") {
             id = "magicutils.common"
-            implementationClass = "MagicUtilsCommonPlugin"
+            implementationClass = "dev.ua.theroer.magicutils.build.module.MagicUtilsCommonPlugin"
         }
         register("magicutilsJavaLibrary") {
             id = "magicutils.java-library"
-            implementationClass = "MagicUtilsJavaLibraryPlugin"
+            implementationClass = "dev.ua.theroer.magicutils.build.module.MagicUtilsJavaLibraryPlugin"
         }
         register("magicutilsAnnotationProcessing") {
             id = "magicutils.annotation-processing"
-            implementationClass = "MagicUtilsAnnotationProcessingPlugin"
+            implementationClass = "dev.ua.theroer.magicutils.build.module.MagicUtilsAnnotationProcessingPlugin"
         }
         register("magicutilsShadow") {
             id = "magicutils.shadow"
-            implementationClass = "MagicUtilsShadowPlugin"
+            implementationClass = "dev.ua.theroer.magicutils.build.module.MagicUtilsShadowPlugin"
         }
         register("magicutilsShadedModule") {
             id = "magicutils.shaded-module"
-            implementationClass = "MagicUtilsShadedModulePlugin"
+            implementationClass = "dev.ua.theroer.magicutils.build.module.MagicUtilsShadedModulePlugin"
         }
         register("magicutilsPublishing") {
             id = "magicutils.publishing"
-            implementationClass = "MagicUtilsPublishingPlugin"
+            implementationClass = "dev.ua.theroer.magicutils.build.publish.MagicUtilsPublishingPlugin"
         }
         register("magicutilsFabricModule") {
             id = "magicutils.fabric-module"
-            implementationClass = "MagicUtilsFabricModulePlugin"
+            implementationClass = "dev.ua.theroer.magicutils.build.module.MagicUtilsFabricModulePlugin"
         }
         register("magicutilsFabricBundle") {
             id = "magicutils.fabric-bundle"
-            implementationClass = "MagicUtilsFabricBundlePlugin"
+            implementationClass = "dev.ua.theroer.magicutils.build.module.MagicUtilsFabricBundlePlugin"
         }
         register("magicutilsBukkitBundle") {
             id = "magicutils.bukkit-bundle"
-            implementationClass = "MagicUtilsBukkitBundlePlugin"
+            implementationClass = "dev.ua.theroer.magicutils.build.module.MagicUtilsBukkitBundlePlugin"
+        }
+        // Consumer-facing plugins for downstream plugins/mods (not MagicUtils'
+        // own library modules): hide Loom/obf/classifier/toolchain selection.
+        register("magicutilsConsumerCommon") {
+            id = "magicutils.consumer-common"
+            implementationClass = "dev.ua.theroer.magicutils.build.consumer.MagicUtilsConsumerCommonPlugin"
+        }
+        register("magicutilsConsumerBukkit") {
+            id = "magicutils.consumer-bukkit"
+            implementationClass = "dev.ua.theroer.magicutils.build.consumer.MagicUtilsConsumerBukkitPlugin"
+        }
+        register("magicutilsConsumerFabric") {
+            id = "magicutils.consumer-fabric"
+            implementationClass = "dev.ua.theroer.magicutils.build.consumer.MagicUtilsConsumerFabricPlugin"
+        }
+        register("magicutilsConsumerVelocity") {
+            id = "magicutils.consumer-velocity"
+            implementationClass = "dev.ua.theroer.magicutils.build.consumer.MagicUtilsConsumerVelocityPlugin"
+        }
+        register("magicutilsConsumerBungee") {
+            id = "magicutils.consumer-bungee"
+            implementationClass = "dev.ua.theroer.magicutils.build.consumer.MagicUtilsConsumerBungeePlugin"
+        }
+        register("magicutilsConsumerNeoForge") {
+            id = "magicutils.consumer-neoforge"
+            implementationClass = "dev.ua.theroer.magicutils.build.consumer.MagicUtilsConsumerNeoForgePlugin"
         }
         register("magicutilsNeoForgeBundle") {
             id = "magicutils.neoforge-bundle"
-            implementationClass = "MagicUtilsNeoForgeBundlePlugin"
+            implementationClass = "dev.ua.theroer.magicutils.build.module.MagicUtilsNeoForgeBundlePlugin"
         }
     }
 }

build-logic/gradle.properties

@@ -1,7 +1,15 @@
 shadowVersion=9.3.1
 fabricLoomVersion=1.17.13
 
+# jpenilla run-* task plugins, applied by the consumer-* plugins on devServer{}
+# opt-in. run-paper/run-velocity share a version line; run-waterfall lags.
+runPaperVersion=3.0.2
+runProxyVersion=2.3.1
+
+# ModDevGradle, applied by consumer-neoforge (moddev provides the NeoForge run).
+neoForgeModdevVersion=2.0.139
+
 # Coordinates for publishing the build-logic plugins as a reusable tool.
 # Independent of the MagicUtils library version (root gradle.properties).
 pluginsGroup=dev.ua.theroer.magicutils.build
-pluginsVersion=0.1.0
+pluginsVersion=0.1.5