Bootstrap unification, standalone bundles + messaging, local release redesign, bare-common coordinates

README.md

@@ -103,24 +103,32 @@ dependencies {
 
 ## Quickstart
 
-Bootstrap helpers are the recommended platform entry points:
+Bootstrap helpers are the recommended platform entry points. The name and data
+directory are derived from the plugin/mod metadata, so the entry points are
+consistent across platforms:
 
 - Bukkit/Paper: `BukkitBootstrap.forPlugin(this)`
-- BungeeCord: `BungeeBootstrap.forPlugin(this, "MyPlugin")`
+- BungeeCord: `BungeeBootstrap.forPlugin(this)`
+- Velocity: `VelocityBootstrap.forPlugin(proxy, this)`
 - Fabric: `FabricBootstrap.forMod("mymod", () -> server)`
-- Velocity: `VelocityBootstrap.forPlugin(proxy, this, "MyPlugin", dataDir)`
-- NeoForge: manual wiring with `NeoForgePlatformProvider` +
-  `CommandRegistry.create(...)`
+- NeoForge: `NeoForgeBootstrap.forMod("mymod", () -> server)`
+
+Every builder exposes `.withRecommendedDefaults()` (the default, every language
+and messages feature on) and `.minimal()` (opt out of the automatic language and
+messages wiring when you manage localization yourself), so you configure intent
+with one call instead of a wall of boolean toggles.
 
 If your project has a shared `common` module, let the platform layer create the
 runtime and pass `MagicRuntime` into the shared services instead of calling the
 bootstrap helpers from common code.
 
 `buildRuntime()` returns a managed `MagicRuntime` container with the platform,
-config manager, logger, language manager, and optional command registry.
-Enable diagnostics with `.enableDiagnostics()` and fetch the service from
-`runtime.requireComponent(DiagnosticsService.class)` or the bootstrap runtime
-result accessor.
+config manager, logger, language manager, and optional command registry. On
+every platform, `bootstrap.logger()` returns a typed `Logger` facade with
+`info/warn/error/...` methods, player-typed overloads, and a fluent
+`Logger#log()` builder. Enable diagnostics with `.enableDiagnostics()` and fetch
+the service from `runtime.requireComponent(DiagnosticsService.class)` or the
+bootstrap runtime result accessor.
 
 See the full setup guide in the docs:
 https://magicutils.theroer.dev/getting-started/quickstart/

build-logic/build.gradle.kts

@@ -1,5 +1,7 @@
 import org.gradle.api.tasks.compile.JavaCompile
 import org.gradle.jvm.toolchain.JavaLanguageVersion
+import java.net.HttpURLConnection
+import java.net.URI
 
 plugins {
     kotlin("jvm") version "2.2.0"
@@ -44,6 +46,30 @@ publishing {
     }
 }
 
+// -Pskip_existing makes publishing idempotent: skip a PublishToMavenRepository
+// task whose POM is already in the (immutable) repo, so a resumed release does
+// not 409 on the plugins that a prior run already uploaded. HEAD is cheap and
+// runs at execution time (skip decided per task), not at configuration.
+if (project.hasProperty("skip_existing") && project.hasProperty("publish_repo")) {
+    val repoBase = (project.property("publish_repo") as String).trimEnd('/')
+    tasks.withType<PublishToMavenRepository>().configureEach {
+        onlyIf {
+            val pub = publication as org.gradle.api.publish.maven.MavenPublication
+            val path = "${pub.groupId.replace('.', '/')}/${pub.artifactId}/${pub.version}/" +
+                "${pub.artifactId}-${pub.version}.pom"
+            val url = URI("$repoBase/$path").toURL()
+            val exists = runCatching {
+                (url.openConnection() as HttpURLConnection).run {
+                    requestMethod = "HEAD"; connectTimeout = 10000; readTimeout = 10000
+                    val code = responseCode; disconnect(); code == 200
+                }
+            }.getOrDefault(false)
+            if (exists) logger.lifecycle("skip_existing: ${pub.artifactId}:${pub.version} already published, skipping.")
+            !exists
+        }
+    }
+}
+
 
 
 dependencies {

build-logic/gradle.properties

@@ -12,4 +12,4 @@ 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.5
+pluginsVersion=0.1.8

build-logic/src/main/kotlin/dev/ua/theroer/magicutils/build/consumer/MagicUtilsConsumerBukkitPlugin.kt

@@ -26,7 +26,6 @@ class MagicUtilsConsumerBukkitPlugin : Plugin<Project> {
         project.pluginManager.apply("magicutils.target")
 
         val target = project.extensions.getByType(MagicUtilsTargetExtension::class.java)
-        val consumer = project.magicUtilsConsumerExtension()
 
         project.extensions.configure(JavaPluginExtension::class.java) { java ->
             java.toolchain.languageVersion.set(JavaLanguageVersion.of(target.java.get()))
@@ -43,53 +42,11 @@ class MagicUtilsConsumerBukkitPlugin : Plugin<Project> {
 
         project.exposeMagicUtilsTargetFacts(target)
 
-        // MagicUtils modules the consumer declared. Bukkit has no jar-in-jar, so
-        // embedMode maps onto the dependency configuration + the shadow jar:
-        //   SHADED   → api/implementation, so shadow relocates the modules into the
-        //             fat jar (a self-contained plugin). This is the Bukkit default
-        //             (AUTO resolves here), but see the SHADED note in EmbedMode:
-        //             two shaded consumers on one server load two isolated copies —
-        //             use EXTERNAL there.
-        //   EXTERNAL → compileOnly, and dev/ua/theroer/magicutils is stripped from
-        //             the shadow jar, so the built jar is thin and expects
-        //             MagicUtils installed as a separate server plugin.
-        //   JAR_IN_JAR → rejected by resolveEmbedMode (fail-fast; no JiJ on Bukkit).
-        // Resolved at afterEvaluate: the consumer sets embedMode in its DSL block,
-        // which runs after this plugin applies. Bukkit has no Loom early-observe of
-        // configurations, so a late `add` is safe (unlike the Fabric consumer).
-        project.afterEvaluate {
-            val embed = resolveEmbedMode(consumer.embedMode.get(), ConsumerLoader.BUKKIT)
-            val shaded = embed == EmbedMode.SHADED
-            val apiConfig = if (shaded) "api" else "compileOnly"
-            val implConfig = if (shaded) "implementation" else "compileOnly"
-            val base = consumer.magicutilsVersion.get()
-            consumer.apiModules.get().forEach { module ->
-                project.dependencies.add(apiConfig, magicUtilsModuleCoordinate(module, base, target))
-            }
-            consumer.implementationModules.get().forEach { module ->
-                project.dependencies.add(implConfig, magicUtilsModuleCoordinate(module, base, target))
-            }
-
-            // EXTERNAL: strip MagicUtils and its bundled libraries from the shadow
-            // jar, so this jar carries none of them and the standalone MagicUtils
-            // plugin provides the single copy at runtime. These reach the fat jar
-            // transitively via the common module (whose MagicUtils deps are `api`),
-            // so moving this module's deps to compileOnly alone does not remove
-            // them; the shadow exclude does. jackson is the config modules' only
-            // external dependency and the bundle plugin owns its own relocated
-            // copy — shipping a second here produced a ClassCastException under
-            // Paper's isolated classloaders, so it is excluded too.
-            if (!shaded) {
-                project.tasks.named("shadowJar", com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar::class.java)
-                    .configure { shadow ->
-                        // The `**/` prefix also catches multi-release copies under
-                        // META-INF/versions/<n>/, which a root-anchored pattern
-                        // (e.g. `com/fasterxml/...`) would leave behind.
-                        shadow.exclude("**/dev/ua/theroer/magicutils/**")
-                        shadow.exclude("**/com/fasterxml/jackson/**")
-                    }
-            }
-        }
+        // MagicUtils modules per embedMode + the EXTERNAL shadow-strip. Bukkit and
+        // Velocity share this exactly (flat-classpath JVM plugins, no jar-in-jar),
+        // so it lives in one helper. SHADED is the Bukkit default (AUTO); EXTERNAL
+        // makes a thin jar that expects the standalone MagicUtils bundle beside it.
+        project.configureJvmConsumerEmbed(target, ConsumerLoader.BUKKIT)
 
         // Local dev server (runPaper/runFolia), only when the consumer opted in
         // with `magicutilsConsumer { devServer { ... } }`. The Folia runner is

build-logic/src/main/kotlin/dev/ua/theroer/magicutils/build/consumer/MagicUtilsConsumerExtension.kt

@@ -394,7 +394,7 @@ internal fun magicUtilsModuleCoordinate(
     module: String,
     version: String,
     target: MagicUtilsTargetExtension,
-): String = "dev.ua.theroer:$module:${target.publishedVersion(version)}"
+): String = "dev.ua.theroer:$module:${target.publishedVersion(module, version)}"
 
 /**
  * Exposes the resolved target's facts as extra properties so consumer build
@@ -408,8 +408,9 @@ internal fun magicUtilsModuleCoordinate(
  * - `magicutilsIsDeobfuscated`   — Boolean
  * - `magicutilsClassifier`       — e.g. `mc26`
  * - `magicutilsPublishedVersion` — the base `magicutils_version` with the
- *   target's `+<minecraft>` suffix (e.g. `1.22.0+26.2`), for the rare coordinate
- *   a script must build by hand (a classifier-less bundle jar).
+ *   bundle's `+java<N>` suffix (e.g. `1.27.1+java25`), for the rare coordinate a
+ *   script must build by hand (a classifier-less bundle jar). Bundles keep the
+ *   suffix; plain modules are published bare, so this fact is bundle-shaped.
  */
 internal fun Project.exposeMagicUtilsTargetFacts(target: MagicUtilsTargetExtension) {
     val base = magicUtilsConsumerExtension().magicutilsVersion.get()
@@ -418,7 +419,9 @@ internal fun Project.exposeMagicUtilsTargetFacts(target: MagicUtilsTargetExtensi
     extensions.extraProperties.set("magicutilsJavaVersion", target.java.get())
     extensions.extraProperties.set("magicutilsIsDeobfuscated", target.isDeobfuscated)
     extensions.extraProperties.set("magicutilsClassifier", target.mcClassifier)
-    extensions.extraProperties.set("magicutilsPublishedVersion", target.publishedVersion(base))
+    // This fact is consumed only for bundle jars, which retain the +java<N>
+    // coordinate; pass a bundle-shaped name so the discriminator keeps the suffix.
+    extensions.extraProperties.set("magicutilsPublishedVersion", target.publishedVersion("magicutils-bundle", base))
     // Optional per-platform facts (not every targets.properties defines them).
     target.neoforge.orNull?.let { extensions.extraProperties.set("magicutilsNeoforgeVersion", it) }
 }
@@ -452,3 +455,51 @@ internal fun Project.addConsumerMagicUtilsModules(
     register(apiConfiguration, consumer.apiModules)
     register(implementationConfiguration, consumer.implementationModules)
 }
+
+/**
+ * Wires the consumer's MagicUtils modules onto a plain-JVM loader (Bukkit,
+ * Velocity) honouring [EmbedMode], and — for EXTERNAL — strips MagicUtils and its
+ * bundled jackson from the shadow jar so the standalone bundle owns the single
+ * runtime copy. Bukkit and Velocity are identical here (both are flat-classpath
+ * JVM plugins with no jar-in-jar), so this is the one place that logic lives;
+ * each consumer plugin just passes its [ConsumerLoader]. BungeeCord is always
+ * shaded (no EXTERNAL split) and uses [addConsumerMagicUtilsModules] instead.
+ *
+ * Runs in `afterEvaluate` because the consumer sets `embedMode` in its DSL block,
+ * which executes after the plugin applies; a plain JVM loader has no Loom
+ * early-observe of configurations, so a late `add` is safe.
+ */
+internal fun Project.configureJvmConsumerEmbed(
+    target: MagicUtilsTargetExtension,
+    loader: ConsumerLoader,
+) {
+    val consumer = magicUtilsConsumerExtension()
+    afterEvaluate {
+        val shaded = resolveEmbedMode(consumer.embedMode.get(), loader) == EmbedMode.SHADED
+        val apiConfig = if (shaded) "api" else "compileOnly"
+        val implConfig = if (shaded) "implementation" else "compileOnly"
+        val base = consumer.magicutilsVersion.get()
+        consumer.apiModules.get().forEach { module ->
+            dependencies.add(apiConfig, magicUtilsModuleCoordinate(module, base, target))
+        }
+        consumer.implementationModules.get().forEach { module ->
+            dependencies.add(implConfig, magicUtilsModuleCoordinate(module, base, target))
+        }
+
+        // EXTERNAL: the modules reach the fat jar transitively via the common
+        // module (whose MagicUtils deps are `api`), so moving this module's own
+        // deps to compileOnly doesn't remove them — the shadow exclude does. The
+        // `**/` prefix also catches multi-release copies under
+        // META-INF/versions/<n>/. jackson is the config modules' only external
+        // dependency and the bundle ships its own relocated copy; a second one
+        // here clashes under the isolated plugin/proxy classloaders, so it goes
+        // too.
+        if (!shaded) {
+            tasks.named("shadowJar", com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar::class.java)
+                .configure { shadow ->
+                    shadow.exclude("**/dev/ua/theroer/magicutils/**")
+                    shadow.exclude("**/com/fasterxml/jackson/**")
+                }
+        }
+    }
+}

build-logic/src/main/kotlin/dev/ua/theroer/magicutils/build/consumer/MagicUtilsConsumerFabricPlugin.kt

@@ -64,7 +64,7 @@ class MagicUtilsConsumerFabricPlugin : Plugin<Project> {
         // for compile/dev-runtime; on deobfuscated 26.x there is no remap, so the
         // classifier-less jar is itself the fat, self-contained artifact used for
         // both publish and dev runtime.
-        val version = target.publishedVersion(consumer.magicutilsVersion.get())
+        val version = target.publishedVersion("magicutils-fabric-bundle", consumer.magicutilsVersion.get())
         val module = "dev.ua.theroer:magicutils-fabric-bundle:$version"
         val shippedDep = module
         val fatDep = if (target.isDeobfuscated) shippedDep else "$module:dev"

build-logic/src/main/kotlin/dev/ua/theroer/magicutils/build/consumer/MagicUtilsConsumerNeoForgePlugin.kt

@@ -68,7 +68,7 @@ class MagicUtilsConsumerNeoForgePlugin : Plugin<Project> {
         val embed = resolveEmbedMode(consumer.embedMode.get(), ConsumerLoader.NEOFORGE)
         if (embed == EmbedMode.JAR_IN_JAR) {
             val bundleCoordinate = project.provider {
-                val version = target.publishedVersion(consumer.magicutilsVersion.get())
+                val version = target.publishedVersion("magicutils-neoforge-bundle", consumer.magicutilsVersion.get())
                 project.dependencies.create("dev.ua.theroer:magicutils-neoforge-bundle:$version")
             }
             // moddev registers `jarJar` at apply time, but hook it via

build-logic/src/main/kotlin/dev/ua/theroer/magicutils/build/consumer/MagicUtilsConsumerVelocityPlugin.kt

@@ -55,44 +55,11 @@ class MagicUtilsConsumerVelocityPlugin : Plugin<Project> {
 
         project.exposeMagicUtilsTargetFacts(target)
 
-        // MagicUtils modules the consumer declared, wired per embedMode. Velocity
-        // has no jar-in-jar, so this maps onto the dependency configuration + the
-        // shadow jar exactly like the Bukkit consumer. Resolved at afterEvaluate
-        // because the consumer sets embedMode in its DSL block, which runs after
-        // this plugin applies; Velocity has no Loom early-observe of
-        // configurations, so a late `add` is safe (unlike the Fabric consumer).
-        project.afterEvaluate {
-            val embed = resolveEmbedMode(consumer.embedMode.get(), ConsumerLoader.VELOCITY)
-            val shaded = embed == EmbedMode.SHADED
-            val apiConfig = if (shaded) "api" else "compileOnly"
-            val implConfig = if (shaded) "implementation" else "compileOnly"
-            val base = consumer.magicutilsVersion.get()
-            consumer.apiModules.get().forEach { module ->
-                project.dependencies.add(apiConfig, magicUtilsModuleCoordinate(module, base, target))
-            }
-            consumer.implementationModules.get().forEach { module ->
-                project.dependencies.add(implConfig, magicUtilsModuleCoordinate(module, base, target))
-            }
-
-            // EXTERNAL: strip MagicUtils and its bundled libraries from the shadow
-            // jar, so this jar carries none of them and the standalone
-            // velocity-bundle provides the single copy at runtime. They reach the
-            // fat jar transitively via the common module (whose MagicUtils deps are
-            // `api`), so moving this module's deps to compileOnly alone does not
-            // remove them; the shadow exclude does. jackson is the config modules'
-            // only external dependency and the bundle owns its own copy — shipping
-            // a second here clashes under the proxy classloader, so exclude it too.
-            if (!shaded) {
-                project.tasks.named("shadowJar", com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar::class.java)
-                    .configure { shadow ->
-                        // The `**/` prefix also catches multi-release copies under
-                        // META-INF/versions/<n>/, which a root-anchored pattern
-                        // would leave behind.
-                        shadow.exclude("**/dev/ua/theroer/magicutils/**")
-                        shadow.exclude("**/com/fasterxml/jackson/**")
-                    }
-            }
-        }
+        // MagicUtils modules per embedMode + the EXTERNAL shadow-strip — shared
+        // with the Bukkit consumer (see configureJvmConsumerEmbed). Velocity's
+        // default is SHADED (self-contained proxy plugin); EXTERNAL yields a thin
+        // jar that expects the standalone velocity-bundle beside it on the proxy.
+        project.configureJvmConsumerEmbed(target, ConsumerLoader.VELOCITY)
 
         project.afterEvaluate {
             val spec = consumer.devServerSpec.orNull ?: return@afterEvaluate