mirror of
https://github.com/block/buzz.git
synced 2026-08-18 06:50:31 +02:00
**Category:** improvement **User Impact:** Developers can identify which worktree produced a mobile debug app, keep a bounded set of worktree builds installed side by side, and preserve each worktree app's login and local state while switching branches. **Problem:** Mobile debug builds from every checkout currently appear as the same “Buzz” app and share one application identity, so the running source is ambiguous and one worktree build replaces another. A branch-keyed identity would avoid replacement but create stale installs and fresh app state on every branch switch. **Solution:** Give each linked worktree a stable Debug-only application identity derived from its sanitized directory name. Show the sanitized branch name (or short commit SHA when detached) in the display label, persist generated native overrides for direct IDE builds, and leave Release/Profile identities unchanged. Worktree defaults remain lower precedence than a developer's iOS `AppOverrides.xcconfig`. `just mobile-clean` provides a safe cleanup path for suffixed worktree installs while preserving production Buzz. <details> <summary>File changes</summary> **.github/workflows/ci.yml** Runs the expanded worktree override contract when relevant mobile or native configuration changes. **AGENTS.md** Documents worktree-aware mobile development and cleanup for contributors and agents. **Justfile** Generates overrides before mobile development and Android debug builds, and exposes `just mobile-clean`. **mobile/README.md** Explains stable per-worktree identities, branch/SHA labels, direct IDE usage, cleanup, and Release/Profile guarantees. **mobile/android/.gitignore** Ignores generated worktree properties. **mobile/android/app/build.gradle.kts** Loads and validates generated properties, then applies the application ID suffix and display label to Android Debug only. **mobile/android/app/src/main/AndroidManifest.xml** Resolves the Android app label through an overridable string resource. **mobile/ios/.gitignore** Ignores generated iOS worktree settings. **mobile/ios/Flutter/Debug.xcconfig** Loads generated worktree defaults before developer `AppOverrides`, so personal signing overrides retain precedence. **mobile/ios/Flutter/Release.xcconfig** Pins the production display name and bundle identifier for Release/Profile builds. **mobile/ios/Runner/Info.plist** Resolves the visible iOS app name from build settings. **scripts/mobile-worktree-overrides.sh** Detects linked worktrees, derives a stable directory-keyed identity, sanitizes branch/SHA display context, writes native Debug overrides, and removes stale overrides in the main checkout. **scripts/mobile-worktree-clean.sh** Lists or removes suffixed Buzz worktree installs from booted iOS simulators and connected Android emulators without matching production IDs; supports `--dry-run`. **scripts/test-mobile-worktree-overrides.sh** Covers worktree detection, branch-switch identity stability, detached HEAD fallback, special-character sanitization, iOS override precedence, brace-aware Release/Profile purity, cleanup safety, ignores, and command integration. </details> ## Reproduction steps 1. From a linked worktree, activate the repository toolchain and run `just mobile-dev`. 2. Inspect the running app: its label should be `Buzz (<sanitized-branch>)`, while its application ID suffix is derived from the worktree directory. 3. Switch branches in the same worktree, rerun the override script, and confirm the application ID remains stable while the display label updates. In detached HEAD, confirm the label uses a short SHA. 4. Build Debug from a second worktree and confirm both apps remain installed side by side with independent state. 5. Build from Xcode after setting `AppOverrides.xcconfig` and confirm developer overrides still win over generated worktree defaults. 6. Run `just mobile-clean --dry-run`, then `just mobile-clean`, and confirm suffixed worktree installs are targeted while the production app is preserved. 7. Build Release/Profile and confirm the production name and application identity remain unchanged. 8. Run `scripts/test-mobile-worktree-overrides.sh`, `just mobile-check`, `just mobile-test`, and `just mobile-build-android`. ## Screenshots / demos | iOS — labeled app switcher | iOS — side-by-side installs | | --- | --- | | <img width="360" alt="Buzz worktree label in the iOS app switcher" src="https://github.com/user-attachments/assets/4bcae067-7ce5-4333-bb11-2803c4107663" /> | <img width="360" alt="Buzz production and worktree debug apps installed side by side on iOS" src="https://github.com/user-attachments/assets/08a107b5-fdf2-463a-8a4c-81d41d7bf5e7" /> | | Android — side-by-side installs | Android — labeled app switcher | | --- | --- | | <img width="360" alt="Buzz production and worktree debug apps installed side by side on Android" src="https://github.com/user-attachments/assets/4f5841a1-adae-42da-ae84-47c09ec85fb9" /> | <img width="360" alt="Buzz worktree label in the Android app switcher" src="https://github.com/user-attachments/assets/0546ff51-efcc-4cb6-a4bd-2a3af26cd60f" /> | --------- Signed-off-by: Taylor Ho <taylorkmho@gmail.com> Co-authored-by: npub1223z34hd7vtwc6qj4s7flsxkj644nlre2nthu7lrrmkumhu3xddsrx9r6w <52a228d6edf316ec6812ac3c9fc0d696ab59fc7954d77e7be31eedcddf91335b@buzz.block.builderlab.xyz>
177 lines
6.9 KiB
Kotlin
177 lines
6.9 KiB
Kotlin
import java.util.Properties
|
|
|
|
plugins {
|
|
id("com.android.application")
|
|
id("kotlin-android")
|
|
// The Flutter Gradle Plugin must be applied after the Android and Kotlin Gradle plugins.
|
|
id("dev.flutter.flutter-gradle-plugin")
|
|
}
|
|
|
|
val uploadKeystorePath = providers.environmentVariable("BUZZ_ANDROID_UPLOAD_KEYSTORE_PATH").orNull
|
|
val uploadKeystorePassword = providers.environmentVariable("BUZZ_ANDROID_UPLOAD_KEYSTORE_PASSWORD").orNull
|
|
val uploadKeyAlias = providers.environmentVariable("BUZZ_ANDROID_UPLOAD_KEY_ALIAS").orNull
|
|
val uploadKeyPassword = providers.environmentVariable("BUZZ_ANDROID_UPLOAD_KEY_PASSWORD").orNull
|
|
val uploadSigningValues =
|
|
mapOf(
|
|
"BUZZ_ANDROID_UPLOAD_KEYSTORE_PATH" to uploadKeystorePath,
|
|
"BUZZ_ANDROID_UPLOAD_KEYSTORE_PASSWORD" to uploadKeystorePassword,
|
|
"BUZZ_ANDROID_UPLOAD_KEY_ALIAS" to uploadKeyAlias,
|
|
"BUZZ_ANDROID_UPLOAD_KEY_PASSWORD" to uploadKeyPassword,
|
|
)
|
|
val missingUploadSigningValues = uploadSigningValues.filterValues { it.isNullOrBlank() }.keys
|
|
val hasUploadSigning = missingUploadSigningValues.isEmpty()
|
|
|
|
// Worktree-aware debug identity (gitignored, written by
|
|
// scripts/mobile-worktree-overrides.sh): debug builds from a git worktree get a
|
|
// branch-labelled app name and a unique applicationId suffix so builds from
|
|
// multiple worktrees install side by side. Release builds never read this.
|
|
val worktreePropsFile = rootProject.file("worktree.properties")
|
|
val worktreeProps =
|
|
Properties().apply {
|
|
if (worktreePropsFile.isFile) worktreePropsFile.inputStream().use { load(it) }
|
|
}
|
|
val worktreeLabel = worktreeProps.getProperty("label")?.takeIf { it.isNotBlank() }
|
|
if (worktreeLabel != null && !worktreeLabel.matches(Regex("""[A-Za-z0-9._-]+"""))) {
|
|
throw GradleException(
|
|
"worktree.properties label must match [A-Za-z0-9._-]+ (safe for string " +
|
|
"resources), got: " + worktreeLabel,
|
|
)
|
|
}
|
|
val worktreeIdSuffix =
|
|
worktreeProps.getProperty("applicationIdSuffix")?.takeIf { it.isNotBlank() }
|
|
if (worktreeIdSuffix != null && !worktreeIdSuffix.matches(Regex("""\.[a-z][a-z0-9_]*"""))) {
|
|
throw GradleException(
|
|
"worktree.properties applicationIdSuffix must match \\.[a-z][a-z0-9_]*, got: " +
|
|
worktreeIdSuffix,
|
|
)
|
|
}
|
|
|
|
// Release signing modes:
|
|
// - "upload-keystore" (default): sign with the CI-vended upload keystore;
|
|
// release builds fail loudly when any credential is missing.
|
|
// - "external": deliberately produce an UNSIGNED release bundle for a
|
|
// pipeline that signs through the central APK Signer service (Cashkite,
|
|
// BOT-1234). No keystore material may be present in this mode.
|
|
val releaseSigningMode =
|
|
providers.environmentVariable("BUZZ_ANDROID_RELEASE_SIGNING").orNull ?: "upload-keystore"
|
|
val externalReleaseSigning = releaseSigningMode == "external"
|
|
if (releaseSigningMode !in setOf("upload-keystore", "external")) {
|
|
throw GradleException(
|
|
"BUZZ_ANDROID_RELEASE_SIGNING must be \"upload-keystore\" or \"external\", got: " +
|
|
releaseSigningMode,
|
|
)
|
|
}
|
|
if (externalReleaseSigning && uploadSigningValues.values.any { !it.isNullOrBlank() }) {
|
|
throw GradleException(
|
|
"BUZZ_ANDROID_RELEASE_SIGNING=external must not be combined with " +
|
|
"BUZZ_ANDROID_UPLOAD_* credentials; unset one of them.",
|
|
)
|
|
}
|
|
|
|
android {
|
|
namespace = "xyz.block.buzz.mobile"
|
|
compileSdk = flutter.compileSdkVersion
|
|
ndkVersion = flutter.ndkVersion
|
|
|
|
compileOptions {
|
|
sourceCompatibility = JavaVersion.VERSION_17
|
|
targetCompatibility = JavaVersion.VERSION_17
|
|
}
|
|
|
|
kotlinOptions {
|
|
jvmTarget = JavaVersion.VERSION_17.toString()
|
|
}
|
|
|
|
defaultConfig {
|
|
applicationId = "xyz.block.buzz.mobile"
|
|
// You can update the following values to match your application needs.
|
|
// For more information, see: https://flutter.dev/to/review-gradle-config.
|
|
minSdk = flutter.minSdkVersion
|
|
targetSdk = flutter.targetSdkVersion
|
|
versionCode = flutter.versionCode
|
|
versionName = flutter.versionName
|
|
testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
|
|
resValue("string", "app_name", "Buzz")
|
|
}
|
|
|
|
signingConfigs {
|
|
if (hasUploadSigning) {
|
|
create("upload") {
|
|
storeFile = file(requireNotNull(uploadKeystorePath))
|
|
storePassword = uploadKeystorePassword
|
|
keyAlias = uploadKeyAlias
|
|
keyPassword = uploadKeyPassword
|
|
}
|
|
}
|
|
}
|
|
|
|
buildTypes {
|
|
debug {
|
|
// Only debug builds take the worktree identity; release/profile
|
|
// keep the production applicationId and label.
|
|
if (worktreeIdSuffix != null) {
|
|
applicationIdSuffix = worktreeIdSuffix
|
|
}
|
|
if (worktreeLabel != null) {
|
|
resValue("string", "app_name", "Buzz ($worktreeLabel)")
|
|
}
|
|
}
|
|
release {
|
|
if (hasUploadSigning) {
|
|
signingConfig = signingConfigs.getByName("upload")
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
dependencies {
|
|
testImplementation(kotlin("test"))
|
|
|
|
androidTestImplementation(kotlin("test"))
|
|
androidTestImplementation("androidx.test.ext:junit:1.3.0")
|
|
androidTestImplementation("androidx.test:runner:1.7.0")
|
|
}
|
|
|
|
gradle.taskGraph.whenReady {
|
|
val buildsRelease = allTasks.any { task ->
|
|
task.project == project && task.name in setOf("assembleRelease", "bundleRelease")
|
|
}
|
|
if (buildsRelease && externalReleaseSigning) {
|
|
// External signing: the unsigned bundle goes to the central APK
|
|
// Signer. All keystore checks are intentionally skipped; the
|
|
// guard above already rejected any BUZZ_ANDROID_UPLOAD_* values.
|
|
return@whenReady
|
|
}
|
|
if (buildsRelease && !hasUploadSigning) {
|
|
throw GradleException(
|
|
"Release builds require Android upload signing credentials. Missing: " +
|
|
missingUploadSigningValues.sorted().joinToString(", ") +
|
|
". For central APK Signer pipelines set BUZZ_ANDROID_RELEASE_SIGNING=external.",
|
|
)
|
|
}
|
|
if (buildsRelease) {
|
|
val configuredKeystore = File(requireNotNull(uploadKeystorePath))
|
|
if (!configuredKeystore.isAbsolute) {
|
|
throw GradleException(
|
|
"BUZZ_ANDROID_UPLOAD_KEYSTORE_PATH must be absolute: $configuredKeystore",
|
|
)
|
|
}
|
|
val keystore = file(configuredKeystore)
|
|
val repositoryRoot = rootProject.projectDir.parentFile.parentFile.canonicalFile
|
|
if (keystore.canonicalFile.toPath().startsWith(repositoryRoot.toPath())) {
|
|
throw GradleException(
|
|
"BUZZ_ANDROID_UPLOAD_KEYSTORE_PATH must be outside the repository: $keystore",
|
|
)
|
|
}
|
|
if (!keystore.isFile || !keystore.canRead()) {
|
|
throw GradleException(
|
|
"BUZZ_ANDROID_UPLOAD_KEYSTORE_PATH is not a readable file: $keystore",
|
|
)
|
|
}
|
|
}
|
|
}
|
|
|
|
flutter {
|
|
source = "../.."
|
|
}
|