[Spec] Migrate Gradle build to Kotlin DSL and complete configuration

[michael-newsrx]

Overview

Migrate the GitBucket MCP plugin build from Gradle Groovy DSL to Kotlin DSL, and complete the Gradle configuration for proper GitBucket plugin development.

Background

The project currently has:

• Gradle wrapper files (untracked)
• build.gradle (Groovy DSL)
• settings.gradle (Groovy DSL)
• Shadow JAR configuration producing fat JAR with dependencies

We need to migrate to Kotlin DSL for better IDE support, type safety, and alignment with modern Gradle best practices.

Requirements

1. File Structure Changes

Convert to Kotlin DSL:

• build.gradle → build.gradle.kts
• settings.gradle → settings.gradle.kts

Add to version control:

• gradlew (Unix executable)
• gradlew.bat (Windows batch script)
• gradle/wrapper/gradle-wrapper.jar
• gradle/wrapper/gradle-wrapper.properties

Remove after migration:

• build.gradle (old Groovy file)
• settings.gradle (old Groovy file)

2. Plugin Management

settings.gradle.kts:

pluginManagement {
    plugins {
        id("scala") version "8.7.0"
        id("com.gradleup.shadow") version "8.3.5"
    }
}

rootProject.name = "gitbucket-mcp-plugin"

Plugin versions are centralized in settings.gradle.kts for easier management and reproducibility.

3. Build Configuration

build.gradle.kts:

plugins {
    scala
    id("com.gradleup.shadow")
}

group = "com.newsrx"
version = "0.1.0"

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(21))
    }
}

tasks.withType<JavaCompile>().configureEach {
    sourceCompatibility = "17"
    targetCompatibility = "17"
}

repositories {
    mavenCentral()
    maven { url = uri("https://oss.sonatype.org/content/repositories/releases/") }
}

dependencies {
    implementation("org.scala-lang:scala-library:2.13.18")
    compileOnly("io.github.gitbucket:gitbucket_2.13:4.46.0")
    compileOnly("org.scalatra:scalatra-javax_2.13:3.1.2")
    compileOnly("io.github.json4s:json4s-jackson_2.13:4.1.0")
    compileOnly("javax.servlet:javax.servlet-api:3.1.0")
    
    testImplementation("org.scalatest:scalatest_2.13:3.2.18")
}

scala {
    scalaVersion = "2.13.18"
}

sourceSets {
    main {
        scala {
            setSrcDirs(listOf("src/main/scala", "src/main/java"))
        }
        java {
            setSrcDirs(emptyList<String>())
        }
    }
}

tasks.shadowJar {
    archiveClassifier.set("")
    exclude("META-INF/*.RSA")
    exclude("META-INF/*.SF")
    exclude("META-INF/*.DSA")
}

tasks.build {
    dependsOn(tasks.shadowJar)
}

4. .gitignore Updates

Add Gradle-specific entries to .gitignore:

# Gradle
.gradle/
build/
!gradle/wrapper/gradle-wrapper.jar
!gradle/wrapper/gradle-wrapper.properties

5. Build Verification

The build must:

• Successfully compile Scala sources (when added)
• Produce a fat JAR at build/libs/gitbucket-mcp-plugin-0.1.0.jar
• Include gitbucket-plugin.properties in the JAR
• Target Java 17 (GitBucket 4.42.0+ requirement)
• Use Java 21 toolchain for development

Technical Details

Why Kotlin DSL?

1. Type Safety: Compile-time checking of build scripts
2. IDE Support: Better autocomplete, refactoring, navigation
3. Consistency: Matches Gradle's modern best practices
4. Error Detection: Errors caught at script compile time, not runtime

Why Shadow Plugin 8.3.5?

• Compatible with Gradle 9.x
• Fixes META-INF handling issues from older versions
• Produces proper fat JAR for GitBucket plugin deployment

Why Java 21 Toolchain with Java 17 Target?

• Toolchain 21: Latest LTS for development environment
• Target 17: GitBucket 4.42.0+ minimum requirement
• Ensures compatibility while using modern JDK features

Why Compile-Only Dependencies?

GitBucket provides these at runtime:

• gitbucket_2.13 - Core GitBucket
• scalatra-javax_2.13 - Web framework
• json4s-jackson_2.13 - JSON processing
• javax.servlet-api - Servlet API

Only scala-library is included in the fat JAR.

Acceptance Criteria

• build.gradle.kts exists and is valid Kotlin DSL
• settings.gradle.kts exists with plugin management
• Old Groovy files removed
• Gradle wrapper files tracked in git
• Build succeeds with ./gradlew build
• Fat JAR produced at build/libs/gitbucket-mcp-plugin-0.1.0.jar
• .gitignore includes Gradle exclusions
• README.md updated with build instructions

Out of Scope

• Writing plugin implementation code
• Setting up CI/CD
• Publishing to plugin repository
• Testing the plugin in GitBucket

Dependencies

• None (this is foundational work)

Risks

Risk	Mitigation
Kotlin DSL syntax errors	Use IDE validation before committing
Gradle version incompatibility	Wrapper ensures Gradle 9.3.0 is used
Missing dependencies	Compile-only pattern matches GitBucket plugin requirements

[michael-newsrx]

Implementation plan: #8

[michael-newsrx]

Pull request created: #9

[michael-conrad]

Superseded by #12 (Testing Pipeline spec) and #14 (Overview). The Kotlin DSL migration is a prerequisite for the testing pipeline but is tracked separately — this spec can be closed once that migration is complete.