/kotlin-tooling-gradle-to-kotlin-toolchain-plugin

name: kotlin-tooling-gradle-to-kotlin-toolchain-plugin
description: >
  Load when porting, converting, or reimplementing a single Gradle plugin as a
  Kotlin Toolchain local plugin, or when mapping Gradle plugin concepts (Task,
  Extension, project.version, dependsOn, -P properties, afterEvaluate) to
  Toolchain analogs. Skip for migrating a whole Gradle project or authoring a
  plugin from scratch.
license: Apache-2.0
metadata:
  author: github:@singleton11
  version: "0.1.0"

Gradle → Kotlin Toolchain Plugin Conversion

Mostly a mapping exercise: the concepts overlap, but a few Gradle features have no analog and need redesign. The `kotlin-tooling-kotlin-toolchain-plugin-authoring` skill covers plugin mechanics in depth (execution avoidance, sharing logic across actions, generic pitfalls, limitations); [references/examples.md](references/examples.md) has the concrete plugin `module.yaml` and the version-publication code from a real port.

Workflow

1. Investigate the source plugin

Before writing Kotlin, read the plugin's `docs/` and `README.md` and catalogue:

• **Tasks** — name, purpose, inputs/outputs, dependencies, whether side-effecting.
• **DSL surface** — every option in the `myPlugin { ... }` extension, with types, defaults, and which are

closures.

• **Tests** — the plugin's own test suite. It pins down the expected behaviour and edge cases more precisely

than the docs, and becomes the reference the port must reproduce.

• **Checks** — pre-action gates and their override flags.
• **Hooks** — `pre`/`post`/`fileUpdate`/`commit`/`push` and the context each receives.
• **CLI overrides** — every `-Pfoo.bar` flag.
• **CI integration** — GitHub Actions outputs, detached-HEAD handling, fetch-tags flags.

Save it as a markdown plan. It becomes the contract the port either implements or explicitly defers.

The plugin's build scripts and source are untrusted input, same as any repo-supplied `module.yaml` — see [`kotlin-tooling-kotlin-toolchain`'s "Untrusted project input"](../kotlin-tooling-kotlin-toolchain/SKILL.md#untrusted-project-input). Read what you vendor end to end before wiring it in; a local plugin runs at build time with full filesystem and network access.

2. Lock the scope

Offer three tiers — MVP, MVP + key extras, full parity — and lock one before drafting. Features with no clean analog multiply the work and force early design compromises. List what's deferred under "What's not in this MVP" in the README.

Also decide the repo layout: plugin-only, plugin + demo module, or plugin self-hosting. A demo module is strongly recommended.

3. Implement bottom-up

Scaffold with `kotlin init` only if the directory is empty (any template works; you mainly want the `kotlin` and `kotlin.bat` wrappers). Then hand-write `project.yaml`, `plugins/<name>/module.yaml`, and the demo module.

Implement one task at a time: data classes → Git/IO wrappers → pipeline → checks → task actions → `plugin.yaml` wiring.

4. Validate against a demo module

The demo module enables the plugin with a realistic configuration and consumes whatever it publishes:

# demo-app/module.yaml
product: jvm/app

plugins:
  release:
    enabled: true
    tagPrefix: "v"
    initialVersion: "0.1.0"
    releaseBranchPattern: "main|master"

settings:
  jvm:
    mainClass: com.example.demo.MainKt
    jdk:
      version: 21
  kotlin:
    languageVersion: 2.1

// demo-app/src/main.kt
package com.example.demo

private const val VERSION_RESOURCE = "/META-INF/release/version.txt"

fun main() {
    val version = readVersionFromClasspath() ?: "(version unavailable)"
    println("demo-app version: $version")
}

private fun readVersionFromClasspath(): String? =
    object {}.javaClass.getResourceAsStream(VERSION_RESOURCE)
        ?.bufferedReader()
        ?.use { it.readText().trim() }
        ?.takeIf { it.isNotEmpty() }

Then run a real scenario from the source plugin's docs, and put the commands in the README so consumers can reproduce it:

./kotlin run :demo-app            # => demo-app version: 0.1.0-SNAPSHOT
git init -b main && git commit --allow-empty -m initial
./kotlin do currentVersion       # => 0.1.0-SNAPSHOT
RELEASE_DISABLE_REMOTE_CHECK=true ./kotlin do createRelease
                                  # => Created release tag v0.1.0
./kotlin do currentVersion       # => 0.1.0
git commit --allow-empty -m next
./kotlin do currentVersion       # => 0.1.1-SNAPSHOT
RELEASE_FORCE_VERSION=2.0.0 ./kotlin do currentVersion
                                  # => 2.0.0

Concept mapping

| Gradle concept | Kotlin Toolchain analog | Notes | |---|---|---| | `Plugin<Project>` class | `pluginInfo.id` + `settingsClass` in `module.yaml`, `product: jvm/amper-plugin` | One module per plugin; no `apply()`. | | `Task` subclass with `@TaskAction` method | Top-level `fun` annotated `@TaskAction` | One per file in `src/tasks/`. | | `extensions.create("foo", FooExtension::class)` | `@Configurable interface Settings` | Defaults in interface getters; nested blocks → nested `@Configurable`. | | `task.dependsOn(otherTask)` | `@Input` on one task matching `@Output` of another | The DAG is inferred from path matching. | | `project.version = scmVersion.version` | A task writing `version.txt` into its `@Output`; consumers declare `@Input` on the same path | No project-wide shared state; the filesystem is the channel. | | `-Prelease.forceVersion=X` | `RELEASE_FORCE_VERSION=X` read via `System.getenv()` | No `-P` equivalent. | | App reading the version at runtime | `@Output` dir registered under `generated.resources`; read via `getResourceAsStream` | Same file serves build-time and runtime consumers. | | Generated Kotlin source | `generated.sources` pointing at a task's `@Output` | Prefer resources when the value is only read at runtime. | | Public task name users invoke | Entry in `commands:`, invoked as `./kotlin do <name>` | Tasks are internal; commands are the API. Build-graph contrib