Extract PluginHookMeta to shared surf-api-common module

settings.gradle.kts

@@ -24,6 +24,7 @@ include(":surf-api-velocity:surf-api-velocity-api")
 include(":surf-api-velocity:surf-api-velocity-server")
 
 include("surf-api-standalone")
+include("surf-api-common")
 include("surf-api-gradle-plugin")
 include("surf-api-gradle-plugin:surf-api-processor")
 

surf-api-common/README.md

@@ -0,0 +1,27 @@
+# surf-api-common
+
+This module contains common data structures and models that are shared between multiple surf-api modules, particularly between the annotation processor (surf-api-processor) and the runtime modules (surf-api-core).
+
+## Purpose
+
+The primary purpose of this module is to provide a single source of truth for data structures that are used for serialization contracts between compile-time processing and runtime execution. This prevents schema drift and runtime decode failures that could occur when maintaining duplicate copies of the same data structures in different modules.
+
+## Current Contents
+
+### Hook Metadata (`dev.slne.surf.surfapi.common.hook`)
+
+- **PluginHookMeta**: Data class representing the metadata for plugin hooks, serialized to `surf-hooks.json` by the annotation processor and read at runtime by the hook service.
+
+## Usage
+
+This module is automatically included as a dependency in:
+- `surf-api-processor` (for generating metadata during compilation)
+- `surf-api-core-server` (for reading metadata at runtime)
+
+## Adding New Common Structures
+
+When you need to add a new data structure that must be shared between the processor and runtime:
+
+1. Add the class to an appropriate package under `dev.slne.surf.surfapi.common`
+2. Annotate it with `@Serializable` if it needs to be serialized/deserialized
+3. Update the modules that need to use it to depend on `surf-api-common`

surf-api-common/build.gradle.kts

@@ -0,0 +1,24 @@
+// region properties
+val mcVersion: String by project
+val groupId = findProperty("group") as String
+val snapshot = (findProperty("snapshot") as String).toBooleanStrict()
+// endregion
+
+plugins {
+    kotlin("jvm")
+    kotlin("plugin.serialization")
+    `publish-convention`
+}
+
+group = groupId
+version = buildString {
+    append(mcVersion)
+    append("-1.0.0")
+    if (snapshot) append("-SNAPSHOT")
+}
+
+dependencies {
+    implementation(libs.kotlin.serialization.json)
+}
+
+description = "surf-api-common"

surf-api-gradle-plugin/surf-api-processor/src/main/kotlin/dev/slne/surf/surfapi/processor/hook/PluginHookMeta.kt → surf-api-common/src/main/kotlin/dev/slne/surf/surfapi/common/hook/PluginHookMeta.kt

@@ -1,4 +1,4 @@
-package dev.slne.surf.surfapi.processor.hook
+package dev.slne.surf.surfapi.common.hook
 
 import kotlinx.serialization.Serializable
 

surf-api-core/surf-api-core-server/build.gradle.kts

@@ -4,6 +4,7 @@ plugins {
 
 dependencies {
     api(project(":surf-api-core:surf-api-core-api"))
+    implementation(project(":surf-api-common"))
     compileOnly(libs.packetevents.netty.common)
 }
 

surf-api-core/surf-api-core-server/src/main/kotlin/dev/slne/surf/surfapi/core/server/hook/HookService.kt

@@ -1,6 +1,7 @@
 package dev.slne.surf.surfapi.core.server.hook
 
 import com.github.benmanes.caffeine.cache.Caffeine
+import dev.slne.surf.surfapi.common.hook.PluginHookMeta
 import dev.slne.surf.surfapi.core.api.hook.AbstractHook
 import dev.slne.surf.surfapi.core.api.util.mutableObject2ObjectMapOf
 import dev.slne.surf.surfapi.core.api.util.mutableObjectListOf

surf-api-gradle-plugin/surf-api-processor/build.gradle.kts

@@ -18,6 +18,7 @@ version = buildString {
 }
 
 dependencies {
+    implementation(project(":surf-api-common"))
     implementation(libs.ksp.api)
     implementation(libs.auto.service.annotations)
     implementation(libs.kotlin.serialization.json)

surf-api-gradle-plugin/surf-api-processor/src/main/kotlin/dev/slne/surf/surfapi/processor/hook/HookSymbolProcessor.kt

@@ -9,6 +9,7 @@ import com.google.devtools.ksp.symbol.KSAnnotated
 import com.google.devtools.ksp.symbol.KSAnnotation
 import com.google.devtools.ksp.symbol.KSClassDeclaration
 import com.google.devtools.ksp.symbol.KSType
+import dev.slne.surf.surfapi.common.hook.PluginHookMeta
 import dev.slne.surf.surfapi.processor.util.toBinaryName
 import kotlinx.serialization.json.Json
 import java.io.IOException