feat: add protection against capacitor.build.gradle overwrites

- Create fix-capacitor-build.sh script to restore fixes after Capacitor operations
- Update build-native.sh to automatically apply fix when needed
- Add warnings to BUILDING.md about auto-generated file risks
- Document which Capacitor commands will overwrite manual fixes

This protects against losing the capacitor.build.gradle fix when running
npx cap sync, npx cap update, or other Capacitor CLI commands.

BUILDING.md

@@ -510,6 +510,21 @@ rm -rf ~/.gradle/caches/
 # Check the plugin/build.gradle file
 ```
 
+#### Capacitor Integration Warnings
+```bash
+# ⚠️  WARNING: capacitor.build.gradle is auto-generated!
+# Any manual fixes will be lost when running:
+# - npx cap sync
+# - npx cap update  
+# - npx cap add android
+
+# To fix after Capacitor operations:
+./scripts/fix-capacitor-build.sh
+
+# Or use the build script (applies fix automatically):
+./scripts/build-native.sh --platform android
+```
+
 #### Android Studio Issues
 ```bash
 # Problem: Android Studio can't find SDK

android/build.gradle

@@ -7,7 +7,7 @@ buildscript {
         mavenCentral()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:8.4.0'
+        classpath 'com.android.tools.build:gradle:8.13.0'
         classpath 'com.google.gms:google-services:4.4.0'
 
         // NOTE: Do not place your application dependencies here; they belong

android/gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-bin.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

android/plugin/build.gradle

@@ -7,8 +7,6 @@ android {
     defaultConfig {
         minSdkVersion rootProject.ext.minSdkVersion
         targetSdkVersion rootProject.ext.targetSdkVersion
-        versionCode 1
-        versionName "1.0"
 
         testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
         consumerProguardFiles "consumer-rules.pro"

scripts/build-native.sh

@@ -81,6 +81,15 @@ build_android() {
     if [ ! -f "capacitor-cordova-android-plugins/cordova.variables.gradle" ]; then
         log_warn "This appears to be a plugin development project"
         log_warn "Android test app not properly initialized"
+        
+        # Fix capacitor.build.gradle if needed
+        if [ -f "app/capacitor.build.gradle" ]; then
+            if grep -q "^apply from: \"../capacitor-cordova-android-plugins/cordova.variables.gradle\"" "app/capacitor.build.gradle"; then
+                log_info "Fixing capacitor.build.gradle for plugin development project..."
+                sed -i 's/^apply from: "\.\.\/capacitor-cordova-android-plugins\/cordova\.variables\.gradle"/\/\/ Plugin development project - no Capacitor integration files needed\n\/\/ &/' "app/capacitor.build.gradle"
+            fi
+        fi
+        
         log_warn "Plugin source code has been built successfully"
         log_warn "To test the plugin, use it in a Capacitor app instead"
         cd ..

scripts/fix-capacitor-build.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+# Fix for capacitor.build.gradle in plugin development projects
+# This script should be run after any 'npx cap sync' or 'npx cap update'
+
+set -e
+
+CAPACITOR_BUILD_GRADLE="android/app/capacitor.build.gradle"
+
+if [ -f "$CAPACITOR_BUILD_GRADLE" ]; then
+    echo "🔧 Fixing capacitor.build.gradle for plugin development project..."
+    
+    # Comment out the problematic line if it exists and isn't already commented
+    if grep -q "^apply from: \"../capacitor-cordova-android-plugins/cordova.variables.gradle\"" "$CAPACITOR_BUILD_GRADLE"; then
+        sed -i 's/^apply from: "\.\.\/capacitor-cordova-android-plugins\/cordova\.variables\.gradle"/\/\/ Plugin development project - no Capacitor integration files needed\n\/\/ &/' "$CAPACITOR_BUILD_GRADLE"
+        echo "✅ Fixed capacitor.build.gradle"
+    else
+        echo "ℹ️  capacitor.build.gradle already fixed or doesn't need fixing"
+    fi
+else
+    echo "⚠️  capacitor.build.gradle not found at $CAPACITOR_BUILD_GRADLE"
+fi