Refine Authenticator App opt-in documentation and add fail-fast check…, Fixes AB#3579566

README.md

@@ -91,46 +91,32 @@ For MSAuthenticator, please use "devDebug" to test against PROD, and "integratio
 
 ## Authenticator App (Opt-in)
 
-Authenticator modules are **excluded by default** to keep Gradle sync/build fast for developers who don't work on Authenticator. To enable them, set `includeAuthenticatorApp=true` in one of these locations (highest priority wins):
-
-| Priority | Location | Scope | Committed? |
-|----------|----------|-------|------------|
-| 1 (highest) | `./gradlew -PincludeAuthenticatorApp=true` | Single invocation | No |
-| 2 | `~/.gradle/gradle.properties` | All projects on your machine | No |
-| 3 | `gradle.properties` | Everyone who clones the repo | Yes |
-| 4 (lowest) | `local.properties` | This checkout only (gitignored) | No |
-
-**Recommended for most developers** — add to `local.properties` (create it if it doesn't exist):
+Authenticator modules are **excluded by default** so Gradle sync/build stays fast for developers who don't work on Authenticator. To enable them, edit the **root `gradle.properties`** — not the one in `authenticator/` but the one at the root of the repo. Turn these two lines ON:
 
 ```properties
 includeAuthenticatorApp=true
 android.enableJetifier=true
 ```
 
-> **Jetifier is required.** Some Authenticator dependencies (e.g. Samsung Knox supportlib, MsaSdk .aar) use the legacy Android Support Library. `android.enableJetifier=true` rewrites their bytecode to AndroidX at build time. Without it you'll get `ClassNotFoundException` at runtime.
+Then re-sync Gradle in Android Studio. That's it — one file, two lines.
 
-### How it works
+#### If `authenticator/` isn't on disk yet
 
-- **Gradle** (`settings.gradle` / `build.gradle`): The flag gates the AuthApp Maven feed registration and all Authenticator module includes.
-- **Git aliases** (`.gitconfig`): The `droid*` commands (e.g. `droidSetup`, `droidNewFeature`, `droidPull`) use `scripts/resolve-include-authenticator.sh` to check the same flag with the same priority order. When enabled, they clone/pull/push the authenticator repo alongside the other repos.
-
-### Quick reference
+Flipping the flag to `true` in a checkout where `droidSetup` was previously run with Authenticator disabled will cause Gradle sync to fail fast with a clear message. The fix is:
 
 ```bash
-# Enable for this checkout only
-echo "includeAuthenticatorApp=true" >> local.properties
-echo "android.enableJetifier=true" >> local.properties
-
-# Enable globally (all android-complete checkouts)
-echo "includeAuthenticatorApp=true" >> ~/.gradle/gradle.properties
+git droidSetup    # idempotent — clones only what's missing
+```
 
-# One-off build with Authenticator
-./gradlew -PincludeAuthenticatorApp=true :MSAuthenticator:assembleDevDebug
+If `authenticator/` exists but looks partial (e.g. `authenticator/PhoneFactor/` is missing), remove it first:
 
-# One-off build WITHOUT Authenticator (overrides gradle.properties default)
-./gradlew -PincludeAuthenticatorApp=false assembleLocalDebug
+```bash
+rm -rf authenticator && git droidSetup
 ```
 
+#### To opt back out
+
+Flip both flags back to `false` in `gradle.properties` and re-sync. The `authenticator/` checkout can stay on disk — Gradle simply won't include it.
 ## Projects Properties (Command Line Build flags)
 
 We support a number of different project properties as command line flags across some of our modules. Please read the doc on [Gradle Project Properties](./docs/ProjectBuild/gradle_project_properties.md) to learn more about them.

gradle.properties

@@ -17,22 +17,21 @@ org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemor
 # This the TSL versionName...
 versionName=1.5.9
 
-# Authenticator App opt-in flag (default: false).
-# When false, all Authenticator modules are excluded from the build, giving a
-# leaner and faster Gradle sync/build for developers who don't work on Authenticator.
-# To enable, set to true in one of the following (highest priority wins):
-#   1. Command line:        ./gradlew -PincludeAuthenticatorApp=true ...
-#   2. ~/.gradle/gradle.properties  (per-user, never committed)
-#   3. local.properties             (per-checkout, gitignored)
-#   4. This file                    (committed default for everyone)
+# Authenticator App opt-in switch.
 #
-# IMPORTANT: When enabling Authenticator, you must ALSO set android.enableJetifier=true.
-# Some Authenticator dependencies (e.g. Samsung Knox supportlib, MsaSdk .aar blobs) were
-# compiled against the legacy Android Support Library. Jetifier rewrites their bytecode to
-# use AndroidX at build time. Without it, you will get ClassNotFoundException at runtime.
-# Add both flags to your local.properties or ~/.gradle/gradle.properties:
-#   includeAuthenticatorApp=true
-#   android.enableJetifier=true
+# This file is the single source of truth for toggling the Authenticator app
+# sub-project on/off for your local build. Flip the two lines below:
+#
+#   includeAuthenticatorApp=true    ? includes all Authenticator modules
+#   includeAuthenticatorApp=false   ? excludes them (leaner, faster sync)
+#
+#
+# IMPORTANT ? Jetifier pairing:
+# When includeAuthenticatorApp=true, android.enableJetifier MUST also be true.
+# Some Authenticator dependencies (Samsung Knox supportlib, MsaSdk .aar blobs)
+# were compiled against the legacy Android Support Library; Jetifier rewrites
+# their bytecode to AndroidX at build time. Without it you'll hit
+# ClassNotFoundException at runtime. Always flip both flags together.
 includeAuthenticatorApp=false
 android.enableJetifier=false
 

settings.gradle

@@ -100,6 +100,32 @@ pluginManagement {
 // local variable so the module-include section below reads naturally.
 def includeAuthenticatorApp = settings.ext.includeAuthenticatorApp
 
+// Fail fast when the opt-in flag is set but the authenticator/ checkout is missing
+// or incomplete. Without this, Gradle would emit a confusing cascade of "project
+// directory does not exist" errors deep in the include() calls below.
+def __authenticatorDir = new File(settings.rootDir, 'authenticator')
+def __authenticatorPhoneFactorDir = new File(__authenticatorDir, 'PhoneFactor')
+if (includeAuthenticatorApp && !__authenticatorPhoneFactorDir.isDirectory()) {
+    def __msg
+    if (!__authenticatorDir.exists()) {
+        // Case 1: nothing cloned yet.
+        __msg = "includeAuthenticatorApp=true but authenticator/ is not checked out.\n" +
+                "  Fix:  re-run  git droidSetup  (clones only what's missing)."
+    } else {
+        // Case 2: authenticator/ exists but is empty / partial / wrong contents.
+        // git clone refuses to write into a non-empty directory, so droidSetup alone
+        // won't recover — the stale folder has to be removed first.
+        __msg = "includeAuthenticatorApp=true and authenticator/ exists, but " +
+                "authenticator/PhoneFactor/ is missing (partial or stale checkout).\n" +
+                "  Fix:  delete the folder and re-run droidSetup:\n" +
+                "          rm -rf authenticator && git droidSetup"
+    }
+    throw new GradleException(
+            __msg + "\n" +
+            "  To build without Authenticator instead, set includeAuthenticatorApp=false " +
+            "in gradle.properties (or ~/.gradle/gradle.properties).")
+}
+
 rootProject.name = 'android_auth'
 
 // Android DevX Projects