feat(android): ship the app and plugin gradle files with the CLI

The gradle build scripts used to live only in the android runtime, so any
fix to them had to wait for a runtime release. This bundles the app-level
gradle files in `vendor/gradle-app` and copies them over the ones the
runtime lays down when the platform is added, the same way the plugin
build already uses `vendor/gradle-plugin`.

- `vendor/gradle-app` holds `build.gradle`, `settings.gradle`,
  `app/build.gradle`, `app/gradle.properties` and the `app/gradle-helpers`.
  They are copied on top of the runtime files in `createProject`, so the
  runtime keeps providing everything that is not part of the overlay.
- `--no-override-runtime-gradle-files` opts out and keeps the runtime files.
- The directory the files come from is resolved through
  `getGradleFilesPath`, which already understands an
  `android.gradleFilesPackageName` config key so the files can later be
  provided by an npm package instead of the bundled copy.
- The CLI now interpolates `__PACKAGE__` (android namespace) and
  `USER_PROJECT_ROOT` in the copied files, and honours
  `android.gradleVersion` by rewriting the gradle wrapper.
- `--gradleArgs` becomes an array option, so it can be passed several
  times, and a single value may hold several space separated arguments.
  Arguments listed in `android.gradleArgs` are passed too, before the
  command line ones. Both app and plugin builds go through the same merge.
- Both app and plugin gradle invocations now get `-PcompileSdk`,
  `-PtargetSdk`, `-PbuildToolsVersion`, `-PgenerateTypings`, `-PprojectRoot`
  and `-PappBuildPath` (the last two also as `-D` so `settings.gradle` can
  read them before project properties exist).
- A debug build is signed when the `--key-store-*` options are passed,
  which is needed for system app builds.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: farfromrefug

docs/man_pages/project/testing/build-android.md

@@ -35,6 +35,8 @@ General | `$ ns build android [--compileSdk <API Level>] [--key-store-path <File
     *   `--env.hiddenSourceMap` - creates sources maps in the root folder (useful for Crashlytics usage with bundled app in release).
 * `--aab` - Specifies that the build will produce an Android App Bundle(`.aab`) file.
 * `--gradleFlavor` - Builds the given product flavor, when the app declares any. `--gradleFlavor foo` runs the `assembleFooDebug`/`assembleFooRelease` gradle task instead of `assembleDebug`/`assembleRelease`.
+* `--gradleArgs` - Passes additional arguments to gradle. Can be passed multiple times, and a single value may hold several space separated arguments. Use the `=` form so the value is not mistaken for another flag, for example `--gradleArgs="-PsomeProperty=value"`. Arguments listed under `android.gradleArgs` in `nativescript.config` are passed too, before these ones.
+* `--no-override-runtime-gradle-files` - If set, keeps the gradle files coming from the android runtime instead of the ones shipped with the CLI.
 * `--force` - If set, skips the application compatibility checks and forces `npm i` to ensure all dependencies are installed. Otherwise, the command will check the application compatibility with the current CLI version and could fail requiring `ns migrate`.
 * `--path <Directory>` - Specifies the directory that contains the project. If not set, the project is searched for in the current directory and all directories above it.
 

docs/man_pages/project/testing/debug-android.md

@@ -39,6 +39,8 @@ Attach the debug tools to a running app in the native emulator | `$ ns debug and
     *   `--env.hiddenSourceMap` - creates sources maps in the root folder (useful for Crashlytics usage with bundled app in release).
 * `--aab` - Specifies that the command will produce and deploy an Android App Bundle.
 * `--gradleFlavor` - Builds the given product flavor, when the app declares any. `--gradleFlavor foo` runs the `assembleFooDebug`/`assembleFooRelease` gradle task instead of `assembleDebug`/`assembleRelease`.
+* `--gradleArgs` - Passes additional arguments to gradle. Can be passed multiple times, and a single value may hold several space separated arguments. Use the `=` form so the value is not mistaken for another flag, for example `--gradleArgs="-PsomeProperty=value"`. Arguments listed under `android.gradleArgs` in `nativescript.config` are passed too, before these ones.
+* `--no-override-runtime-gradle-files` - If set, keeps the gradle files coming from the android runtime instead of the ones shipped with the CLI.
 * `--force` - If set, skips the application compatibility checks and forces `npm i` to ensure all dependencies are installed. Otherwise, the command will check the application compatibility with the current CLI version and could fail requiring `ns migrate`.
 
 <% if(isHtml) { %>

docs/man_pages/project/testing/run-android.md

@@ -44,6 +44,8 @@ Start a default emulator if none are running, or run application on all connecte
     *   `--env.hiddenSourceMap` - creates sources maps in the root folder (useful for Crashlytics usage with bundled app in release).
 * `--aab` - Specifies that the command will produce and deploy an Android App Bundle.
 * `--gradleFlavor` - Builds the given product flavor, when the app declares any. `--gradleFlavor foo` runs the `assembleFooDebug`/`assembleFooRelease` gradle task instead of `assembleDebug`/`assembleRelease`.
+* `--gradleArgs` - Passes additional arguments to gradle. Can be passed multiple times, and a single value may hold several space separated arguments. Use the `=` form so the value is not mistaken for another flag, for example `--gradleArgs="-PsomeProperty=value"`. Arguments listed under `android.gradleArgs` in `nativescript.config` are passed too, before these ones.
+* `--no-override-runtime-gradle-files` - If set, keeps the gradle files coming from the android runtime instead of the ones shipped with the CLI.
 * `--force` - If set, skips the application compatibility checks and forces `npm i` to ensure all dependencies are installed. Otherwise, the command will check the application compatibility with the current CLI version and could fail requiring `ns migrate`.
 
 <% if(isHtml) { %>

lib/data/build-data.ts

@@ -53,7 +53,7 @@ export class AndroidBuildData extends BuildData {
 	public androidBundle: boolean;
 	public gradleFlavor: string;
 	public gradlePath: string;
-	public gradleArgs: string;
+	public gradleArgs: string[];
 	public hostProjectPath: string;
 
 	constructor(projectDir: string, platform: string, data: any) {

lib/declarations.d.ts

@@ -578,7 +578,13 @@ interface IAndroidOptions extends IEmbedOptions {
 	 */
 	gradleFlavor: string;
 	gradlePath: string;
-	gradleArgs: string;
+	gradleArgs: string[];
+	/**
+	 * When true (the default) the gradle files bundled with the CLI are copied
+	 * over the ones shipped by the android runtime. Pass `--no-override-runtime-gradle-files`
+	 * to keep the runtime files untouched.
+	 */
+	overrideRuntimeGradleFiles: boolean;
 }
 
 interface IIOSOptions extends IEmbedOptions {}

lib/definitions/android-plugin-migrator.d.ts

@@ -11,7 +11,7 @@ interface IAndroidBuildOptions {
 	aarOutputDir: string;
 	tempPluginDirPath: string;
 	gradlePath?: string;
-	gradleArgs?: string;
+	gradleArgs?: string[];
 }
 
 interface IAndroidPluginBuildService {
@@ -48,5 +48,5 @@ interface IBuildAndroidPluginData extends Partial<IProjectDir> {
 	/**
 	 * Optional custom Gradle arguments.
 	 */
-	gradleArgs?: string;
+	gradleArgs?: string[];
 }

lib/definitions/build.d.ts

@@ -33,7 +33,7 @@ interface IAndroidBuildData
 		IHasAndroidBundle {
 	gradleFlavor?: string;
 	gradlePath?: string;
-	gradleArgs?: string;
+	gradleArgs?: string[];
 }
 
 interface IAndroidSigningData {

lib/definitions/gradle.d.ts

@@ -30,4 +30,5 @@ interface IGradleBuildService {
 interface IGradleBuildArgsService {
 	getBuildTaskArgs(buildData: IAndroidBuildData): Promise<string[]>;
 	getCleanTaskArgs(buildData: IAndroidBuildData): string[];
+	getBuildLoggingArgs(): string[];
 }

lib/definitions/project.d.ts

@@ -179,6 +179,25 @@ interface INsConfigAndroid extends INsConfigPlaform {
 	 * Custom runtime package name
 	 */
 	runtimePackageName?: string;
+
+	/**
+	 * Pin the gradle wrapper to a specific gradle version, overriding the one
+	 * shipped by the android runtime.
+	 */
+	gradleVersion?: string;
+
+	/**
+	 * Additional arguments passed to every gradle invocation (app and plugin
+	 * builds). Merged with the ones passed on the command line through
+	 * `--gradleArgs`.
+	 */
+	gradleArgs?: string[];
+
+	/**
+	 * Package providing the gradle files copied over the ones shipped by the
+	 * android runtime. Defaults to the files bundled with the CLI.
+	 */
+	gradleFilesPackageName?: string;
 }
 
 interface INsConfigHooks {

lib/options.ts

@@ -221,7 +221,12 @@ export class Options {
 			},
 			gradleFlavor: { type: OptionType.String, hasSensitiveValue: false },
 			gradlePath: { type: OptionType.String, hasSensitiveValue: false },
-			gradleArgs: { type: OptionType.String, hasSensitiveValue: false },
+			gradleArgs: { type: OptionType.Array, hasSensitiveValue: false },
+			overrideRuntimeGradleFiles: {
+				type: OptionType.Boolean,
+				default: true,
+				hasSensitiveValue: false,
+			},
 			hostProjectPath: { type: OptionType.String, hasSensitiveValue: false },
 			hostProjectModuleName: {
 				type: OptionType.String,