ADFA-2602: Correct version references in plugin docs and metadata comments (#1648)

* ADFA-2602: Correct version references in plugin docs and metadata comments

PLUGIN_AUTHORING.md told plugin authors to request AGP 8.11.0 and Kotlin
1.9.22 for an on-device build. The harvested localMvnRepository now ships
AGP 9.3.1 and Kotlin 2.3.21, so those instructions produced an
unresolvable build.

The apiVersion/languageVersion pins in common, eventbus-events,
idetooltips and plugin-api stay at 2.0. Their comments named 1.9.22 as the
reason, which no longer holds; the real invariant is that the jar must stay
readable by every supported on-device compiler, including a device still on
an older bundled toolchain after a KOTLIN_VERSION bump. Reworded to say
that instead of naming a version that will keep going stale.

* ADFA-2602: Point plugin docs at org.adfa.constants for on-device versions

The on-device localMvnRepository ships AGP 9.3.1, Gradle 9.6.1 and Kotlin 2.3.21,
not AGP 8.13.1 / Kotlin 2.3.0. AGP 9 also refuses org.jetbrains.kotlin.android and
takes its compiler from the kotlin-gradle-plugin jar on the root buildscript
classpath, so the documented root snippet would have failed to configure.

Name the constants that pin these versions, so the doc stops going stale on every
bump rather than being corrected after the fact.

* ADFA-2602: Point the on-device SDK at build-tools 36.0.0

AGP 9.3.1 hard-requires build-tools >= 36.0.0, so `BUILD_TOOLS_VERSION` moves to
36.0.0. This drives `BUILD_TOOLS_DIR` and therefore the
`android.aapt2FromMavenOverride` path that GradleBuildService passes to every
build.

This must land together with an asset that actually contains
`build-tools/36.0.0`; on its own it points the IDE at a directory that does not
exist yet. The matching dev-assets pipeline change and the platform-tools port
that builds those binaries from android-16.0.0_r4 are the other two pieces.

Also drop the build-tools version from the suppressed aapt2 warning. That entry
is matched with `contains()` against the full override path, so pinning 35.0.0
meant the bump would silently stop matching and resurface an experimental-option
warning in Build Output on every user build.

Claude-Session: https://claude.ai/code/session_017HGpMsUzZ5wxCfMtDZ2HGP

* ADFA-3078: Search the on-device Maven repo before the remote ones

Offline builds failed unless the user turned on the --offline flag, which
defeats the point of an offline-first IDE.

The on-device repo was registered last. Templates declare gradlePluginPortal(),
google() and mavenCentral() first, and this plugin appended with
`maven { it.url = uri }`. With no network, dl.google.com fails DNS, and Gradle
treats a repository *error* as fatal rather than falling through to the next
repository the way it does for a 404. Resolution therefore died at google() and
never reached the local repo. --offline worked only because it skips remote
repositories entirely.

The artifacts were never missing: the AGP plugin marker,
kotlin-build-tools-compat and kotlin-build-tools-impl are all present in
localMvnRepository on device.

Inserting at index 0 instead of appending fixes all four injection points
(pluginManagement, dependencyResolutionManagement, and the settings and project
buildscript blocks).

Verified on a Pixel 9 Pro emulator in airplane mode with offlineMode=false, the
Gradle modules-2 cache deleted, and a brand new Empty Activity Kotlin project
whose settings.gradle.kts was left untouched: sync reaches "Project initialized"
and the build produces app-debug.apk. Both failed under identical conditions
before this change. A warm module cache masks the bug, so retests need the cache
cleared.

Ships in the APK, not the assets zip, so no asset rebuild is required.

Claude-Session: https://claude.ai/code/session_017HGpMsUzZ5wxCfMtDZ2HGP

---------

Co-authored-by: Daniel Alome <astrocoder007@gmail.com>

Author: Daniel-ADFA

app/src/main/java/com/itsaky/androidide/ui/EditorBottomSheet.kt

@@ -518,7 +518,10 @@ class EditorBottomSheet
 
 		private val suppressedGradleWarnings =
 			listOf(
-				"The option setting 'android.aapt2FromMavenOverride=/data/data/com.itsaky.androidide/files/home/android-sdk/build-tools/35.0.0/aapt2' is experimental",
+				// Matched with contains(), so the build-tools version is deliberately left
+				// out: the path moves with Environment.BUILD_TOOLS_VERSION and a hardcoded
+				// version silently stops matching, resurfacing the warning to users.
+				"The option setting 'android.aapt2FromMavenOverride=",
 				"The org.gradle.api.plugins.BasePluginConvention type has been deprecated.",
 				"The org.gradle.api.plugins.Convention type has been deprecated.",
 				"The BasePluginExtension.archivesBaseName property has been deprecated.",

common/build.gradle.kts

@@ -12,7 +12,7 @@ android {
 kotlin {
 	compilerOptions {
 		// This module's classes ship in the plugin-api coordinate that on-device plugins
-		// compile against, so emit metadata the on-device Kotlin (1.9.22) can read (<= 2.0.0).
+		// compile against, so emit metadata every supported on-device Kotlin can read (<= 2.0.0).
 		apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
 		languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
 	}

common/src/main/java/com/itsaky/androidide/utils/Environment.java

@@ -46,7 +46,7 @@ public final class Environment {
 	private static final String ANDROIDIDE_PROJECT_CACHE_DIR = SharedEnvironment.PROJECT_CACHE_DIR_NAME;
 	private static final String DATABASE_NAME = "documentation.db";
 
-	public static final String BUILD_TOOLS_VERSION = "35.0.0";
+	public static final String BUILD_TOOLS_VERSION = "36.0.0";
 
 	public static final String PLUGIN_API_JAR_RELATIVE_PATH = "libs/plugin-api.jar";
 

docs/PLUGIN_AUTHORING.md

@@ -39,7 +39,7 @@ in `build.gradle.kts`:
 ```kotlin
 plugins {
     id("com.android.application") version "8.8.2"
-    id("org.jetbrains.kotlin.android") version "2.1.21"
+    id("org.jetbrains.kotlin.android") version "2.3.0"
     id("com.itsaky.androidide.plugins.build")
 }
 
@@ -66,21 +66,31 @@ against — the `:plugin-api` module plus `common`, `eventbus-events`, and
 `idetooltips`. The builder plugin applied above resolves the same way, from the
 injected `com.itsaky.androidide.plugins.build` `1.0.0` marker.
 
-#### Building on-device (offline) pins the AGP/Kotlin versions
+#### Building on-device (offline) pins the AGP/Kotlin/Gradle versions
 
-The `plugins {}` example above uses AGP `8.8.2` / Kotlin `2.1.21` — the versions the
-dev/CI repo resolves online. A plugin built **on-device** resolves AGP and the Kotlin
-Gradle plugin from the harvested on-device `localMvnRepository`, which currently ships
-only **AGP `8.11.0`** and **Kotlin `1.9.22`**. Request those versions for an on-device
-build, or offline resolution of the build plugins fails.
+The `plugins {}` example above uses AGP `8.8.2` / Kotlin `2.3.0` — the versions the
+dev/CI repo resolves online. A plugin built **on-device** resolves its build plugins from
+the harvested on-device `localMvnRepository`, which ships only the versions pinned in
+`org.adfa.constants` — `ANDROID_GRADLE_PLUGIN_VERSION`, `KOTLIN_VERSION` and
+`GRADLE_DISTRIBUTION_VERSION`, currently **AGP `9.3.1`**, **Kotlin `2.3.21`** and
+**Gradle `9.6.1`**. Request those, or offline resolution of the build plugins fails. That
+constants file is authoritative; the numbers here are a snapshot of it.
 
-Also declare AGP `apply false` in the **root** `build.gradle.kts` (as the standard CoGo
-project template does):
+AGP 9 compiles Kotlin itself and **refuses** the `org.jetbrains.kotlin.android` plugin, so
+an on-device build drops it and pins Kotlin through the `kotlin-gradle-plugin` jar on the
+**root** buildscript classpath, which is where AGP 9 takes its compiler from. Declare AGP
+`apply false` in the same root file (as the standard CoGo project template does):
 
 ```kotlin
+buildscript {
+    dependencies {
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:2.3.21")
+    }
+}
+
 plugins {
-    id("com.android.application") apply false version "8.11.0"
-    id("com.android.library") apply false version "8.11.0"
+    id("com.android.application") apply false version "9.3.1"
+    id("com.android.library") apply false version "9.3.1"
 }
 ```
 

eventbus-events/build.gradle.kts

@@ -29,7 +29,7 @@ android {
 kotlin {
 	compilerOptions {
 		// This module's classes ship in the plugin-api coordinate that on-device plugins
-		// compile against, so emit metadata the on-device Kotlin (1.9.22) can read (<= 2.0.0).
+		// compile against, so emit metadata every supported on-device Kotlin can read (<= 2.0.0).
 		apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
 		languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
 	}

gradle-plugin/src/main/java/com/itsaky/androidide/gradle/COTGSettingsPlugin.kt

@@ -116,8 +116,13 @@ private fun RepositoryHandler.addMavenRepoIfMissing(
 	logger: Logger,
 	uri: URI,
 ) {
-	if (none { it is MavenArtifactRepository && it.url == uri }) {
-		logger.info("Adding maven repository: $uri")
-		maven { it.url = uri }
+	if (any { it is MavenArtifactRepository && it.url == uri }) {
+		return
 	}
+
+	logger.info("Adding maven repository: $uri")
+	val repo = maven { it.url = uri }
+
+	remove(repo)
+	add(0, repo)
 }

idetooltips/build.gradle.kts

@@ -12,7 +12,7 @@ android {
 kotlin {
 	compilerOptions {
 		// This module's classes ship in the plugin-api coordinate that on-device plugins
-		// compile against, so emit metadata the on-device Kotlin (1.9.22) can read (<= 2.0.0).
+		// compile against, so emit metadata every supported on-device Kotlin can read (<= 2.0.0).
 		apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
 		languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
 	}

plugin-api/build.gradle.kts

@@ -22,7 +22,8 @@ android {
 kotlin {
 	compilerOptions {
 		jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
-		// Emit metadata the on-device Kotlin compiler (1.9.22) can read (<= 2.0.0).
+		// Emit metadata every supported on-device Kotlin compiler can read (<= 2.0.0), so a
+		// device still on an older bundled toolchain keeps working after a KOTLIN_VERSION bump.
 		// This jar ships in the plugin-api coordinate on-device plugins compile against.
 		apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
 		languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)