@zigrivers/scaffold 3.6.0 → 3.8.0

package/content/knowledge/mobile-app/mobile-app-dev-environment.md

@@ -0,0 +1,257 @@
+---
+name: mobile-app-dev-environment
+description: Simulator and emulator setup, physical device testing, hot reload, debugging tools, and developer toolchain for iOS and Android
+topics: [mobile-app, dev-environment, simulator, emulator, debugging, xcode, android-studio, hot-reload]
+---
+
+Mobile development environments are significantly more complex than web development: two IDEs, two simulators, hardware-specific debugging, code signing requirements, and platform SDK updates that break builds. A well-configured dev environment reduces friction by 50% — standardize tool versions, automate simulator setup, and document the steps from clean machine to first successful build.
+
+## Summary
+
+iOS development requires Xcode (macOS only) with simulators managed via `xcodebuild` or Xcode's device window. Android development uses Android Studio with AVD Manager for emulators and ADB for device management. Both platforms support hot reload (SwiftUI previews, Compose previews, Metro bundler for React Native). Debugging tools include LLDB (iOS), Android Studio debugger, and Instruments/Android Profiler for performance analysis. Standardize SDK versions in `.tool-versions` or `mise.toml` to prevent team drift.
+
+## Deep Guidance
+
+### iOS Toolchain Setup
+
+**Required tools**
+- Xcode: install from the Mac App Store or `xcodes` CLI — not from third-party sources
+- Command Line Tools: `xcode-select --install`
+- Simulators: downloaded on demand within Xcode or via `xcodebuild -downloadPlatform iOS`
+- CocoaPods (if used): `gem install cocoapods` (prefer rbenv/mise to manage Ruby version)
+- Bundler for Ruby tools: `gem install bundler && bundle install` (locks CocoaPods/Fastlane versions)
+- Mint for Swift CLI tools: `brew install mint` — pin versions in `Mintfile`
+
+**Version pinning**
+```
+# .tool-versions (asdf/mise)
+xcode 15.4
+ruby 3.3.0
+node 20.18.0     # if using React Native
+```
+
+**Simulator management**
+```bash
+# List available simulators
+xcrun simctl list devices
+
+# Boot a simulator
+xcrun simctl boot "iPhone 16 Pro"
+
+# Open Simulator app (required to see the UI)
+open -a Simulator
+
+# Install app on booted simulator
+xcrun simctl install booted path/to/MyApp.app
+
+# Launch app
+xcrun simctl launch booted com.example.myapp
+
+# Take screenshot
+xcrun simctl io booted screenshot screenshot.png
+
+# Trigger push notification (iOS 16+)
+xcrun simctl push booted com.example.myapp payload.json
+
+# Reset simulator (clears all data)
+xcrun simctl erase "iPhone 16 Pro"
+```
+
+**Useful Xcode settings for development velocity**
+- Enable "Show build durations": Preferences > Behaviors > Build (custom)
+- Increase build parallelism: `defaults write com.apple.dt.Xcode IDEBuildOperationMaxNumberOfConcurrentCompileTasks $(sysctl -n hw.ncpu)`
+- Enable address sanitizer and thread sanitizer for debug builds to catch memory issues early
+- Explicit modules: set `SWIFT_ENABLE_EXPLICIT_MODULES = YES` for faster incremental builds (Xcode 16+)
+
+**SwiftUI Previews for hot-reload-like iteration**
+```swift
+#Preview {
+    UserProfileView(viewModel: UserProfileViewModel.preview)
+}
+
+extension UserProfileViewModel {
+    static var preview: UserProfileViewModel {
+        let vm = UserProfileViewModel(repository: MockUserRepository())
+        vm.user = User(id: "1", name: "Jane Smith", email: "jane@example.com")
+        return vm
+    }
+}
+```
+
+Previews require a `PreviewProvider`-compatible data setup. Use protocol-based fakes rather than mocks — they compile faster and work in both tests and previews.
+
+**Physical device setup (iOS)**
+- Developer account: free account allows device testing; paid account required for distribution
+- Device registration: Settings > Privacy > Developer Mode (iOS 16+) must be enabled
+- Add device UDID to provisioning profile in Apple Developer portal, or use Automatic Signing in Xcode
+- Trust the developer certificate on device: Settings > General > VPN & Device Management
+
+### Android Toolchain Setup
+
+**Required tools**
+- Android Studio: install from developer.android.com — includes the Android SDK, build tools, and AVD Manager
+- JDK: Android Studio bundles its own JDK; for CLI builds, use JDK 17 (Gradle 8.x requirement)
+- ADB (Android Debug Bridge): included in Android SDK Platform Tools — add to PATH
+- Bundletool: for testing AAB files locally
+
+**SDK and build tools versions**
+```kotlin
+// app/build.gradle.kts
+android {
+    compileSdk = 35
+    defaultConfig {
+        minSdk = 26
+        targetSdk = 35
+    }
+}
+```
+
+Pin build tools in `gradle/wrapper/gradle-wrapper.properties`:
+```
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip
+```
+
+**AVD (Android Virtual Device) management**
+```bash
+# List available AVDs
+emulator -list-avds
+
+# Start emulator
+emulator -avd Pixel_9_API_35
+
+# Or via avdmanager
+avdmanager list avd
+
+# Create an AVD
+avdmanager create avd -n "Pixel_9_API_35" -k "system-images;android-35;google_apis_playstore;x86_64"
+```
+
+**ADB commands for development**
+```bash
+# List connected devices/emulators
+adb devices
+
+# Install APK
+adb install -r app-debug.apk
+
+# View logs filtered by tag
+adb logcat -s MyApp:V
+
+# Open app
+adb shell am start -n com.example.myapp/.MainActivity
+
+# Input text (useful for automation)
+adb shell input text "testpassword"
+
+# Tap coordinates
+adb shell input tap 540 960
+
+# Take screenshot
+adb exec-out screencap -p > screenshot.png
+
+# Enable WiFi debugging (Android 11+)
+adb pair <ip>:<port>  # pair first
+adb connect <ip>:<port>
+```
+
+**Physical device setup (Android)**
+- Enable Developer Options: Settings > About Phone > tap Build Number 7 times
+- Enable USB Debugging: Developer Options > USB Debugging
+- For Android 11+: enable Wireless Debugging for cable-free development
+- Trust the computer when prompted on first connection
+
+**Compose hot reload**
+Android Studio's "Apply Code Changes" and "Apply Changes and Restart Activity" provide incremental deployment:
+- Apply Code Changes (lightning bolt icon): deploys changed Kotlin bytecode without restarting the app — works for logic changes
+- Apply Changes and Restart Activity: restarts the current activity with new code — works for UI composition changes
+- Full rebuild is still required for resource changes (strings, drawables, manifest)
+
+Compose interactive preview:
+```kotlin
+@Preview(showBackground = true, name = "Light mode")
+@Preview(uiMode = Configuration.UI_MODE_NIGHT_YES, name = "Dark mode")
+@Composable
+fun UserCardPreview() {
+    MyAppTheme {
+        UserCard(user = previewUser)
+    }
+}
+```
+
+### Debugging Tools
+
+**iOS debugging**
+
+*LLDB in Xcode*
+- Set breakpoints by clicking line numbers or: `breakpoint set --name viewDidLoad`
+- Print expressions: `po viewModel.user` (prints object description), `p viewModel.isLoading` (prints value)
+- Memory graph: Debug > View Memory Graph Hierarchy to inspect object retain counts
+- View hierarchy debugger: Debug > View Debugging > Capture View Hierarchy — visualize the full UIView/SwiftUI layer tree in 3D
+
+*Instruments*
+- Time Profiler: find CPU hotspots, identify methods consuming > 5% of CPU time
+- Allocations: track heap memory growth, identify retain cycles via backtraces
+- Leaks: automated memory leak detection
+- Network: inspect HTTP requests, timing, and response bodies
+- Energy Log: identify battery-draining background work
+- Core Animation: frame rendering performance, identifies GPU-bound vs CPU-bound jank
+
+*Console.app / os_log*
+```swift
+import OSLog
+private let logger = Logger(subsystem: "com.example.myapp", category: "Auth")
+logger.debug("Login attempt for user: \(userId)")
+logger.error("Network error: \(error.localizedDescription)")
+```
+Filter in Console.app by subsystem/category. OSLog is zero-cost when logging is disabled.
+
+**Android debugging**
+
+*Android Studio debugger*
+- Breakpoints with conditions: right-click breakpoint > Condition
+- Evaluate expression: Debug > Evaluate Expression (or Alt+F8) while paused
+- Frame variable inspection: Variables pane shows all locals and fields
+- LogCat: filter by package name, tag, or regex. Color-coded by severity level.
+
+*Android Studio Profiler*
+- CPU Profiler: record method traces or sample CPU usage; identify ANR-prone operations
+- Memory Profiler: heap dump, allocation tracking, GC event visualization
+- Network Profiler: request/response inspection, payload viewer
+- Energy Profiler: battery usage breakdown by CPU, network, and GPS
+
+*Debugging Compose*
+- Layout Inspector (Android Studio Electric Eel+): live inspection of Compose tree with recomposition counts
+- Recomposition highlighter: `Modifier.debugInspectorInfo` or Android Studio's built-in recomposition overlay
+- `@Preview` parameter combinations to test edge cases without running the app
+
+### Team Environment Standardization
+
+**Mise/asdf for tool version consistency**
+```toml
+# .mise.toml (or .tool-versions for asdf)
+[tools]
+java = "17.0.12"
+node = "20.18.0"
+ruby = "3.3.0"
+```
+
+Commit `.mise.toml` to git — every team member and CI runner uses the same tool versions.
+
+**Fastlane for build automation**
+```ruby
+# Fastfile
+lane :build_debug do
+  gradle(task: "assembleDebug")
+end
+
+lane :build_ios do
+  gym(scheme: "MyApp", configuration: "Debug")
+end
+```
+
+Document the minimum `make setup` or `./scripts/bootstrap.sh` that gets a new developer from clean machine to running app in under 10 minutes. Include:
+1. Install Xcode/Android Studio (with version pinned)
+2. Install system dependencies (`brew install ...`)
+3. Install project dependencies (pods, SPM packages, Gradle sync)
+4. Create local config files from templates
+5. Run on simulator to verify

package/content/knowledge/mobile-app/mobile-app-distribution.md

@@ -0,0 +1,264 @@
+---
+name: mobile-app-distribution
+description: TestFlight and Google Play internal track, enterprise MDM distribution, staged rollouts, beta testing programs, and OTA updates for mobile apps
+topics: [mobile-app, distribution, testflight, google-play, enterprise-mdm, staged-rollout, beta-testing, ota]
+---
+
+Mobile app distribution has more complexity than web deployment: app store review introduces unpredictable latency, staged rollouts require monitoring and rollback planning, enterprise distribution requires MDM infrastructure, and React Native/Expo apps have limited OTA update options for business logic. Design the distribution pipeline before writing code — it affects app architecture (feature flags, forced update logic) and CI/CD setup.
+
+## Summary
+
+iOS pre-release distribution uses TestFlight (internal team up to 100 testers, external up to 10,000). Android uses Google Play's internal testing, closed testing (alpha), and open testing (beta) tracks. Enterprise apps distribute via MDM (Jamf, Microsoft Intune, VMware Workspace ONE) or in-house provisioning. Staged rollouts (production track, percentage-based) allow monitoring before full release. Forced update patterns prevent users from running critically broken versions. React Native apps can deliver business logic updates OTA via Expo Updates or CodePush within platform policy limits.
+
+## Deep Guidance
+
+### TestFlight (iOS)
+
+**Internal testing**
+- Up to 100 internal testers (must be App Store Connect users in your team)
+- Available within minutes of upload — no Apple review required
+- Access via TestFlight app on device; invitations via email
+- 90-day expiration per build; can be extended
+
+**External testing**
+- Up to 10,000 testers (external — no App Store Connect account required)
+- Requires Apple review for first submission to a group (24–48 hours); subsequent builds with same metadata are faster
+- Tester groups allow segmented beta access (e.g., "power users", "partners")
+- Feedback is collected via TestFlight screenshot feedback feature
+
+**Fastlane Pilot for automated TestFlight upload**
+```ruby
+lane :beta do
+  # Build
+  gym(
+    scheme: "MyApp",
+    configuration: "Release",
+    export_method: "app-store"
+  )
+
+  # Upload to TestFlight
+  pilot(
+    app_identifier: "com.example.myapp",
+    changelog: ENV["CHANGELOG"] || git_commit_message,
+    distribute_external: false,
+    notify_external_testers: false,
+    skip_waiting_for_build_processing: false  # wait for processing before distributing
+  )
+end
+```
+
+**App Store Connect API key for CI**
+```ruby
+# Authenticate with API key (no 2FA required — safe for CI)
+app_store_connect_api_key(
+    key_id: ENV["ASC_KEY_ID"],
+    issuer_id: ENV["ASC_ISSUER_ID"],
+    key_content: ENV["ASC_PRIVATE_KEY"],
+    is_key_content_base64: true,
+    in_house: false
+)
+```
+
+Generate the API key in App Store Connect > Users and Access > Keys. Store as CI secrets — this key has broad permissions.
+
+**TestFlight build metadata**
+- `What to Test` field: mandatory for external testing review; tells reviewers what to focus on
+- Build version must be higher than any previously uploaded build — automate with Fastlane's `increment_build_number`
+- Keep a changelog per build: git commit summaries work for internal; user-friendly summaries for external
+
+**Crash-free rate monitoring**
+Monitor TestFlight crash-free rate in Xcode Organizer or App Store Connect. Set a threshold (e.g., < 99% crash-free is a blocker) before promoting a TestFlight build to App Store production.
+
+### Google Play Distribution Tracks
+
+**Track hierarchy**
+```
+Internal testing → Closed testing (alpha) → Open testing (beta) → Production
+```
+
+Each track has its own review requirements and rollout speed:
+- Internal: up to 100 testers, available in minutes, no review
+- Closed (alpha): invite-only Google Groups, available in hours, Google review required
+- Open (beta): public opt-in, available in days, Google review required
+- Production: public, subject to full review
+
+**Track promotion strategy**
+```
+CI/CD → Internal testing (every PR merge)
+     → Closed alpha (every weekly release candidate)
+     → Open beta (after 3 days crash-free in alpha)
+     → Production 10% (staged rollout start)
+     → Production 100% (after 48 hours monitoring)
+```
+
+**Fastlane Supply for Play Store**
+```ruby
+lane :deploy_internal do
+  gradle(task: "bundle", build_type: "Release")
+  supply(
+    track: "internal",
+    aab: "app/build/outputs/bundle/release/app-release.aab",
+    package_name: "com.example.myapp",
+    json_key_data: ENV["PLAY_STORE_SERVICE_ACCOUNT_JSON"]
+  )
+end
+
+lane :promote_to_beta do
+  supply(
+    track: "alpha",
+    track_promote_to: "beta",
+    package_name: "com.example.myapp"
+  )
+end
+```
+
+**Service account authentication**
+- Create a service account in Google Play Console: Setup > API access
+- Grant the service account "Release Manager" role
+- Download the JSON key file — store as a CI secret (`PLAY_STORE_SERVICE_ACCOUNT_JSON`)
+- Rotate the service account key annually
+
+### Staged Rollouts
+
+**iOS: Phased Release**
+App Store Connect supports phased release for iOS apps:
+- Day 1: 1% of eligible users
+- Day 2: 2%
+- Day 3–6: doubling per day to 5%, 10%, 20%, 50%
+- Day 7: 100%
+
+Pause the rollout if crash rate spikes. Resume manually when stable. This is a 7-day automatic progression — you cannot customize the percentages on iOS.
+
+**Android: Staged Production Rollout**
+Google Play provides fine-grained percentage control:
+```kotlin
+// Via Fastlane
+supply(
+    track: "production",
+    rollout: "0.1",  // 10% rollout
+    aab: "app-release.aab"
+)
+
+// Increase rollout after monitoring
+supply(
+    track: "production",
+    rollout: "0.5"  // promote to 50%
+)
+```
+
+**Rollout monitoring checklist**
+Before increasing rollout percentage:
+- Crash-free users rate > 99.5% (Firebase Crashlytics / Play Console)
+- ANR (Application Not Responding) rate < 0.25% (Android Play Console)
+- Network error rate stable (Firebase Performance / custom dashboard)
+- Revenue/conversion metrics not regressing (analytics)
+- No P0 support tickets or social media reports
+
+**Rollback strategy**
+iOS: halt phased release in App Store Connect; users who already updated cannot be rolled back (no downgrade mechanism). Prepare a hotfix release and fast-track it through the queue.
+
+Android: halt staged rollout and set rollout to 0%. Users who already updated are on the new version. Prepare a hotfix and expedite through the Play review queue.
+
+### Enterprise MDM Distribution
+
+**iOS: In-House (Apple Developer Enterprise Program)**
+- Requires Apple Developer Enterprise Program ($299/year)
+- Apps distributed via a hosted IPA with a distribution manifest plist
+- Install via Safari on device: `itms-services://?action=download-manifest&url=https://example.com/manifest.plist`
+- No App Store review — responsibility for content is entirely the enterprise's
+- Provisioning profiles expire annually — plan renewal in advance
+
+**iOS: MDM-managed distribution**
+- Push apps to enrolled devices via MDM (Jamf, Microsoft Intune, Mosyle)
+- Apps can be silently installed on managed devices without user interaction
+- VPP (Volume Purchase Program) for App Store apps; custom B2B apps for private distribution
+- Device enrollment: Device Enrollment Program (DEP/ABM) for zero-touch setup
+
+**Android: Enterprise distribution**
+- Google Play managed: publish to a private Google Play track visible only to enrolled organization devices
+- APK sideloading via MDM: push APK directly to managed devices
+- Android Enterprise fully managed device profile for dedicated devices (kiosks, logistics scanners)
+- `android:sharedUserId` removed in API 29+ — do not rely on shared user IDs for enterprise app families
+
+**MDM lifecycle events**
+Apps distributed via MDM receive signals for:
+- Device enrollment/unenrollment: handle data wipe
+- Policy changes: respond to new restrictions (camera, clipboard, screen capture)
+- Managed app configuration: receive key-value configuration from MDM without hardcoding server URLs
+
+### Forced Update Patterns
+
+**Remote config-driven forced update**
+```swift
+// iOS: Firebase Remote Config
+let remoteConfig = RemoteConfig.remoteConfig()
+remoteConfig.fetchAndActivate { status, error in
+    let minVersion = remoteConfig.configValue(forKey: "min_required_version").stringValue
+    let currentVersion = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "0.0.0"
+
+    if currentVersion.isOlderThan(minVersion) {
+        // Show forced update modal — no dismissal
+        ForceUpdateViewController.show(on: rootViewController)
+    }
+}
+```
+
+```kotlin
+// Android: Firebase Remote Config
+remoteConfig.fetchAndActivate().addOnCompleteListener { task ->
+    val minVersion = remoteConfig.getString("min_required_version")
+    val currentVersion = BuildConfig.VERSION_NAME
+
+    if (currentVersion.isOlderThan(minVersion)) {
+        startActivity(Intent(Intent.ACTION_VIEW, Uri.parse("market://details?id=$packageName")))
+        finish()
+    }
+}
+```
+
+**Forced update design principles**
+- Show the forced update screen only for critical security fixes or data-breaking changes — not convenience
+- Always provide context: "This update is required to keep your account secure"
+- Deep link to the App Store / Play Store update page
+- Never block the update prompt — no dismiss button for forced updates
+- For soft updates (recommended but not required), show a dismissable banner with a "Update now" action
+
+### OTA (Over-the-Air) Updates for React Native / Expo
+
+**Expo Updates**
+```json
+// app.json
+{
+  "expo": {
+    "updates": {
+      "enabled": true,
+      "checkAutomatically": "ON_LOAD",
+      "fallbackToCacheTimeout": 0
+    }
+  }
+}
+```
+
+```typescript
+import * as Updates from 'expo-updates';
+
+async function checkForUpdate() {
+    try {
+        const update = await Updates.checkForUpdateAsync();
+        if (update.isAvailable) {
+            await Updates.fetchUpdateAsync();
+            // Prompt user or reload silently
+            await Updates.reloadAsync();
+        }
+    } catch (error) {
+        // Update check failure should not affect UX
+    }
+}
+```
+
+**OTA update constraints (platform policy)**
+- iOS: OTA updates may only deliver JavaScript and asset changes — cannot modify native modules, add permissions, or change app metadata
+- Android: same restrictions — OTA cannot add new native capabilities
+- Both platforms: OTA updates that change app behavior to circumvent App Store / Play Store policies result in account termination
+- Safe to OTA: bug fixes in JS logic, UI changes, copy changes, non-native feature additions
+- Requires native build: new permissions, new native modules, SDK upgrades, binary dependencies