Refine Makefile help and wrapper upgrade

Makefile

@@ -1,16 +1,19 @@
-.PHONY: default help clean build jar run-jar refresh versioncheck build-docker run-docker push-docker release upgrade-wrapper _require-version _require-gradle-version _require-image
+.PHONY: default help clean build jar run-jar refresh versions build-docker run-docker \
+        push-docker release upgrade-wrapper \
+        _require-version _require-gradle-version _require-image
 
-VERSION := $(shell awk -F'=' '/^version[[:space:]]*=/{gsub(/[[:space:]]/,"",$$2); print $$2; exit}' gradle.properties 2>/dev/null)
-GRADLE_VERSION := $(shell awk -F'"' '/^gradle[[:space:]]*=/{gsub(/[[:space:]]/,"",$$2); print $$2; exit}' gradle/libs.versions.toml 2>/dev/null)
+VERSION := $(shell sed -n 's/^version=\(.*\)/\1/p' gradle.properties)
+GRADLE_VERSION := $(shell sed -n 's/^gradle-wrapper = "\(.*\)"/\1/p' gradle/libs.versions.toml)
 
 # Override on the command line: `IMAGE_NAME=myorg/vapi4k-template make release`
 IMAGE_NAME ?= docker_hub_username/vapi4k-template
 PLATFORMS  := linux/amd64,linux/arm64/v8
 
 default: help
 
-help: ## Show this help message
-	@awk 'BEGIN {FS = ":.*?## "; printf "Targets (project v$(VERSION), gradle v$(GRADLE_VERSION)):\n\n"} /^[A-Za-z0-9_.-]+:.*?## / {printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+help:  ## Show this help (list of targets)
+	@awk 'BEGIN {FS = ":.*?## "; printf "Usage: make <target>\n\nTargets:\n"} \
+		/^[a-zA-Z0-9_-]+:.*?## / {printf "  \033[36m%-22s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
 
 clean: ## Remove build artifacts
 	./gradlew clean
@@ -27,7 +30,7 @@ run-jar: jar ## Build and run the fat JAR
 refresh: ## Refresh dependencies and check for updates
 	./gradlew --refresh-dependencies dependencyUpdates
 
-versioncheck: ## Check for available dependency updates
+versions: ## Check for available dependency updates
 	./gradlew dependencyUpdates --no-configuration-cache
 
 build-docker: _require-version _require-image jar ## Build a single-arch Docker image tagged with the project version
@@ -43,7 +46,11 @@ push-docker: _require-version _require-image ## Build and push a multiarch image
 
 release: push-docker ## Build and push the multiarch Docker image (single buildx pass)
 
-upgrade-wrapper: _require-gradle-version ## Upgrade the Gradle wrapper to the version pinned in libs.versions.toml
+# Gradle's documented upgrade procedure: the first run rewrites
+# gradle-wrapper.properties using the *old* wrapper jar; the second run
+# regenerates the wrapper itself with the new version.
+upgrade-wrapper: _require-gradle-version  ## Upgrade the Gradle wrapper to the version pinned in libs.versions.toml
+	./gradlew wrapper --gradle-version=$(GRADLE_VERSION) --distribution-type=bin
 	./gradlew wrapper --gradle-version=$(GRADLE_VERSION) --distribution-type=bin
 
 _require-version:

build.gradle.kts

@@ -14,25 +14,10 @@ val buildFatJarTask = "buildFatJar"
 val cleanTask = "clean"
 val stageTask = "stage"
 
-val preReleaseSuffixes = listOf("-RC", "-BETA", "-ALPHA", "-M")
-
 application {
   mainClass.set(mainClassName)
 }
 
-ktor {
-  fatJar {
-    // Change this to whatever name you want
-    // It also has to be changed in the Dockerfile
-    archiveFileName.set(fatJarName)
-  }
-}
-
-// This must match the version defined in system.properties
-kotlin {
-  jvmToolchain(jvmVersion)
-}
-
 dependencies {
   implementation(libs.vapi4k.core)
   implementation(libs.vapi4k.dbms)
@@ -51,8 +36,44 @@ tasks.named(buildFatJarTask) {
   mustRunAfter(cleanTask)
 }
 
-tasks.withType<DependencyUpdatesTask> {
-  rejectVersionIf {
-    preReleaseSuffixes.any { candidate.version.uppercase().contains(it) }
+configureKotlin()
+configureKtor()
+configureVersions()
+
+fun Project.configureKotlin() {
+// This must match the version defined in system.properties
+  kotlin {
+    jvmToolchain(jvmVersion)
+  }
+}
+
+fun Project.configureKtor() {
+  ktor {
+    fatJar {
+      // Change this to whatever name you want
+      // It also has to be changed in the Dockerfile
+      archiveFileName.set(fatJarName)
+    }
+  }
+}
+
+fun Project.configureVersions() {
+  // A pre-release qualifier is a `.` or `-` delimiter followed by a known unstable
+  // keyword. `m\d` matches milestones (`-M1`/`.M2`) without catching stable classifiers
+  // like `-macos`/`-MR1`, and the `[.-]` delimiter catches both dash-style (`-alpha`)
+  // and dot-style (Netty's `.Beta1`) qualifiers while leaving `-jre`/`.Final` stable.
+  val preReleaseQualifier =
+    Regex("""[.-](rc|beta|alpha|m\d|cr|snapshot|eap|dev|milestone|pre)""", RegexOption.IGNORE_CASE)
+
+  fun isNonStable(version: String): Boolean = preReleaseQualifier.containsMatchIn(version)
+
+  tasks.withType<DependencyUpdatesTask>().configureEach {
+    notCompatibleWithConfigurationCache("the dependency updates plugin is not compatible with the configuration cache")
+    // Reject a pre-release candidate only when the current version is stable. For
+    // dependencies we intentionally track on a pre-release line (e.g. a detekt
+    // alpha), newer pre-releases are still surfaced as available updates.
+    rejectVersionIf {
+      isNonStable(candidate.version) && !isNonStable(currentVersion)
+    }
   }
 }

gradle/libs.versions.toml

@@ -1,10 +1,10 @@
 [versions]
-gradle = "9.5.0"
+gradle-wrapper = "9.6.1"
 jvm = "21"
-kotlin = "2.3.21"
-ktor = "3.4.3"
+kotlin = "2.4.0"
+ktor = "3.5.1"
 versions = "0.54.0"
-vapi4k = "1.7.0"
+vapi4k = "1.8.0"
 
 [libraries]
 vapi4k-core = { group = "com.vapi4k", name = "vapi4k-core", version.ref = "vapi4k" }

gradle/wrapper/gradle-wrapper.properties

@@ -1,7 +1,9 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-9.5.0-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.6.1-bin.zip
 networkTimeout=10000
+retries=0
+retryBackOffMs=500
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists