@zigrivers/scaffold 3.6.0 → 3.8.0

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

@@ -0,0 +1,180 @@
+---
+name: mobile-app-conventions
+description: Platform naming conventions, accessibility patterns, navigation patterns, and code style for iOS and Android mobile apps
+topics: [mobile-app, conventions, swift, kotlin, naming, accessibility, navigation]
+---
+
+Mobile platform conventions exist for consistency across the ecosystem, toolchain compatibility, and team readability. iOS and Android have distinct naming conventions, navigation paradigms, and accessibility implementation patterns. Mixing conventions or importing web/backend naming styles into mobile code creates cognitive friction and breaks tooling assumptions (SwiftUI previews, Android Studio refactoring, lint rules).
+
+## Summary
+
+iOS conventions use PascalCase for types and camelCase for everything else; Swift files are one type per file named identically to the type. Android uses PascalCase for classes and camelCase for members, with XML resource names in snake_case. Navigation uses UINavigationController/Coordinator (iOS) or Navigation Component with NavGraph (Android). Accessibility labels follow platform semantics: VoiceOver on iOS, TalkBack on Android. Follow these patterns consistently — tooling and platform reviewers expect them.
+
+## Deep Guidance
+
+### iOS Naming Conventions (Swift)
+
+**Types (classes, structs, enums, protocols)**
+- PascalCase: `UserProfileViewController`, `AuthenticationService`, `PaymentStatus`
+- Protocols: prefer noun or adjective+able naming. `Codable`, `Equatable`, `DataSource`, `Delegate`
+- Protocol conformances add a semantic suffix: `UITableViewDataSource`, `URLSessionDelegate`
+- Generic type parameters: single uppercase letter for simple cases (`T`, `U`), descriptive names for constrained types (`Element`, `Key`, `Value`)
+
+**Properties, methods, and variables**
+- camelCase: `firstName`, `isAuthenticated`, `fetchUserProfile()`
+- Boolean properties: use `is`, `has`, `should`, `can` prefix: `isLoading`, `hasUnreadMessages`, `canSubmit`
+- Avoid abbreviations except widely established ones: `url`, `id`, `api` are acceptable; `usrNm` is not
+
+**File naming**
+- One primary type per file, filename matches type exactly: `UserProfileViewController.swift`, `AuthenticationService.swift`
+- Extensions can live in separate files: `User+Codable.swift`, `View+Accessibility.swift`
+- Protocol conformances in extension files when they're substantial: `UserProfileViewController+TableViewDelegate.swift`
+
+**View naming (UIKit)**
+- ViewControllers always end in `ViewController`: `LoginViewController`, `SettingsViewController`
+- Views end in `View`: `ProfileHeaderView`, `EmptyStateView`
+- Cells end in `Cell`: `ProductListCell`, `MessageBubbleCell`
+- Reuse identifiers match class names: `tableView.register(ProductListCell.self, forCellReuseIdentifier: "ProductListCell")`
+
+**SwiftUI naming**
+- Views are structs with descriptive names: `UserProfileView`, `LoginForm`, `SettingsRow`
+- ViewModels are `@Observable` classes or ObservableObjects ending in `ViewModel`: `UserProfileViewModel`
+- Preview providers: `#Preview { UserProfileView() }`
+
+**Constants**
+- Use `enum` as a namespace (no-case enums cannot be instantiated): `enum APIConstants { static let baseURL = "..." }`
+- `static let` on structs/classes for type-level constants
+- Avoid global `let` at file scope except for truly global constants
+
+### Android Naming Conventions (Kotlin)
+
+**Classes and interfaces**
+- PascalCase: `UserProfileFragment`, `AuthRepository`, `PaymentUseCase`
+- Activities: end in `Activity` — `MainActivity`, `LoginActivity`
+- Fragments: end in `Fragment` — `UserProfileFragment`, `SettingsFragment`
+- ViewModels: end in `ViewModel` — `UserProfileViewModel`, `HomeViewModel`
+- Repositories: end in `Repository` — `UserRepository`, `ProductRepository`
+- Use cases: verb phrase — `GetUserProfileUseCase`, `UpdateSettingsUseCase`
+
+**Properties and functions**
+- camelCase: `firstName`, `isAuthenticated`, `fetchUserProfile()`
+- Boolean properties: `is`, `has`, `should` prefix — `isLoading`, `hasError`, `shouldShowEmpty`
+- Extension functions follow the same rules: fun `String.isValidEmail()`, fun `View.setVisible(Boolean)`
+
+**XML resource naming (snake_case always)**
+- Layouts: `{type}_{name}.xml` — `activity_main.xml`, `fragment_profile.xml`, `item_product.xml`, `view_empty_state.xml`
+- IDs: `{type}_{name}` — `@id/button_submit`, `@id/text_username`, `@id/recycler_products`
+- Drawables: `ic_{name}.xml` for icons, `bg_{name}.xml` for backgrounds, `shape_{name}.xml` for shapes
+- Colors: descriptive names in `colors.xml` (`color_primary`, `color_surface`), semantic names in theme (`colorPrimary`, `colorSurface`)
+- Strings: `{screen}_{element}_{type}` — `login_email_hint`, `profile_name_label`, `error_network_message`
+- Dimensions: `{component}_{property}` — `button_corner_radius`, `card_elevation`, `spacing_large`
+
+**Compose naming**
+- Composables: PascalCase like types: `UserProfileScreen`, `ProductCard`, `EmptyState`
+- State holders ending in `State`: `LoginUiState`, `ProfileUiState`
+- Preview functions: `@Preview @Composable fun UserProfileScreenPreview()`
+
+### Navigation Patterns — iOS
+
+**UIKit navigation patterns**
+
+*UINavigationController (hierarchical)*
+- Push/pop model for drill-down navigation: settings list → individual setting
+- `navigationController?.pushViewController(vc, animated: true)` / `.popViewController(animated: true)`
+- Always use `navigationItem.title` and `navigationItem.backButtonTitle` for VoiceOver accessibility
+
+*UITabBarController (top-level)*
+- Manage 2–5 coordinate sibling views; do not nest tab bars
+- Each tab owns its own `UINavigationController` — this is the standard pattern
+- Tab bar items need `title` and `image` (SF Symbol): `UITabBarItem(title: "Home", image: UIImage(systemName: "house"), tag: 0)`
+
+*Modal presentations*
+- `.present(_:animated:completion:)` for modals
+- Always provide a dismissal mechanism (button or swipe-down) — never trap the user in a modal
+- `UISheetPresentationController` for bottom sheets (iOS 15+): `detents: [.medium(), .large()]`
+
+*Coordinator pattern*
+- Extract navigation logic from ViewControllers into Coordinator objects
+- Each Coordinator owns a `UINavigationController` and creates/presents child ViewControllers
+- Child Coordinators are stored in a `childCoordinators` array — release them in the finish callback to prevent leaks
+- Delegate back to parent Coordinator for cross-boundary navigation
+
+**SwiftUI navigation**
+- `NavigationStack` (iOS 16+) for hierarchical navigation: `NavigationStack(path: $path) { ... }`
+- `NavigationPath` for type-erased programmatic navigation
+- `.navigationDestination(for:)` to register destination views for path types
+- `TabView` with `tabItem` modifier for tab navigation
+- `.sheet`, `.fullScreenCover`, `.popover` for modal presentation
+- Pass navigation state via bindings or a `NavigationRouter` observable object — do not use environment objects for navigation state in deep hierarchies
+
+### Navigation Patterns — Android
+
+**Navigation Component (Jetpack)**
+- Define navigation graph in `nav_graph.xml` or `NavHost` composable
+- Fragments connect via Actions defined in the nav graph
+- Pass arguments with Safe Args plugin — type-safe navigation prevents bundle key typos
+- Deep links registered in nav graph enable external app navigation
+
+**Compose Navigation**
+- `NavHost` with `composable` routes: `NavHost(navController, startDestination = "home") { composable("home") { HomeScreen(navController) } }`
+- Route strings are stringly-typed — define as constants in a `Screen` sealed class or object
+- Pass data via route arguments (`/{userId}`) or ViewModel shared across the back stack
+- `rememberNavController()` at the top of the composition; pass `NavController` down as a lambda (`onNavigate: () -> Unit`) rather than passing the controller itself
+
+**Back stack management**
+- `popBackStack()` for simple back navigation
+- `navigate("destination") { popUpTo("home") { inclusive = false } }` to clear the back stack when navigating to a top-level destination
+- `launchSingleTop = true` to prevent duplicate destinations in the back stack
+
+### Accessibility Conventions
+
+**iOS VoiceOver implementation**
+
+Labels vs. hints:
+- `accessibilityLabel`: what the element is — "Profile photo for Jane Smith"
+- `accessibilityHint`: what happens when activated — "Double-tap to view full profile"
+- Never include the element type in the label (VoiceOver announces it separately): say "Submit" not "Submit button"
+
+Grouping:
+- Use `accessibilityElements` to define a custom element order within a container
+- `UIAccessibilityElement` with `isAccessibilityElement = true` for custom drawing views
+- `accessibilityActivate()` override for complex controls with custom activation behavior
+
+SwiftUI accessibility:
+- `.accessibilityLabel("Submit order")` overrides the computed label
+- `.accessibilityHint("Processes payment and places order")` adds the activation hint
+- `.accessibilityAddTraits(.isButton)` when a custom view should be announced as a button
+- `.accessibilityRemoveTraits(.isImage)` when an image is decorative
+- `.accessibilityElement(children: .combine)` to merge a container's children into one accessible element
+
+**Android TalkBack implementation**
+
+View system:
+- `android:contentDescription="@string/submit_button_label"` on all non-text interactive views
+- `android:importantForAccessibility="no"` for decorative views (icons that duplicate adjacent text)
+- `android:labelFor="@id/edit_text_email"` on Label TextViews — associates the label with the input for TalkBack
+- `ViewCompat.setAccessibilityDelegate()` for advanced semantic customization
+
+Compose semantics:
+- `Modifier.semantics { contentDescription = "Submit order" }` for custom content descriptions
+- `Modifier.semantics { role = Role.Button }` for role announcement
+- `Modifier.clearAndSetSemantics { ... }` to replace inherited semantics entirely
+- `Modifier.semantics(mergeDescendants = true) { ... }` to merge a group of elements
+
+### Code Style Conventions
+
+**Swift**
+- `guard` for early returns over nested `if` statements
+- `let` by default; `var` only when mutation is necessary
+- Trailing closures when the last parameter is a closure: `array.filter { $0.isActive }`
+- `@discardableResult` on functions when the return value may intentionally be ignored
+- Mark protocol methods with default implementations in extensions
+- Avoid `!` force-unwrap; use `guard let` or `if let` with meaningful error handling
+
+**Kotlin**
+- `val` by default; `var` only when mutation is required
+- Data classes for value types that need `equals`/`hashCode`/`copy`: `data class User(val id: String, val name: String)`
+- Sealed classes for exhaustive state modeling: `sealed class UiState { data class Success(...); data object Loading; data class Error(...) }`
+- Extension functions over utility classes: `fun String.isValidEmail()` not `EmailUtils.isValidEmail(string)`
+- Coroutines over threads/callbacks; `suspend` functions for async operations
+- `Flow` for reactive streams; `StateFlow` for UI state; `SharedFlow` for events

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

@@ -0,0 +1,298 @@
+---
+name: mobile-app-deployment
+description: App store submission, code signing, provisioning profiles, CI/CD with Fastlane, and release management for iOS and Android
+topics: [mobile-app, deployment, app-store, google-play, code-signing, fastlane, ci-cd, release-management]
+---
+
+Mobile app deployment is significantly more complex than web deployment: code signing creates a cryptographic chain of trust, app store review is a human process with 24–48 hour latency, and binary deployment means bugs cannot be hot-patched without a full submission cycle. Automate as much of this as possible with Fastlane — manual signing and upload processes are error-prone and do not scale to frequent releases.
+
+## Summary
+
+iOS deployment requires Apple Developer account, code signing (certificates + provisioning profiles), App Store Connect submission, and 24–48 hour review. Android deployment requires a Google Play Developer account, APK/AAB signing with a release keystore, and Play Store submission. Both platforms support CI/CD automation via Fastlane lanes. Code signing is the most failure-prone step — use Fastlane Match (iOS) or a secrets-managed keystore (Android) to make it reproducible. Automate the full pipeline from test → build → sign → upload.
+
+## Deep Guidance
+
+### iOS Code Signing
+
+**Concepts**
+- **Certificate**: A key pair issued by Apple. Two types relevant to development: Apple Distribution (for App Store) and Apple Development (for device testing).
+- **App ID**: A unique identifier (`com.example.myapp`) registered in the Apple Developer portal.
+- **Provisioning Profile**: A file that binds an App ID to a certificate and, for development, to specific device UDIDs. Must be re-downloaded when devices are added.
+- **Entitlements**: Capabilities your app uses (push notifications, in-app purchases, Sign in with Apple) — must match between app target and provisioning profile.
+
+**Automatic vs. manual signing**
+- Automatic (Xcode manages signing): fine for individual developers, unreliable in CI — Xcode modifies the project file.
+- Manual signing: specify `CODE_SIGN_IDENTITY`, `PROVISIONING_PROFILE_SPECIFIER` explicitly in xcconfig or build settings. Required for reliable CI.
+
+**Fastlane Match for team signing**
+Match stores certificates and profiles in a git repository (or S3/Google Cloud), encrypted with a passphrase. Every team member and CI runner fetches from the same source:
+
+```ruby
+# Matchfile
+git_url("https://github.com/example/certificates")
+storage_mode("git")
+type("appstore")  # or "development", "adhoc"
+app_identifier("com.example.myapp")
+
+# Fastfile
+lane :sync_signing do
+  match(type: "appstore", readonly: is_ci)
+end
+
+lane :build_release do
+  sync_signing
+  gym(
+    scheme: "MyApp",
+    configuration: "Release",
+    export_method: "app-store",
+    output_directory: "./build"
+  )
+end
+```
+
+**Match setup workflow**
+```bash
+# First time: create certificates repo and generate certs
+fastlane match init
+fastlane match appstore   # generates Distribution cert + App Store profile
+fastlane match development  # generates Development cert + profile
+
+# Subsequent: sync to CI or new dev machine
+MATCH_PASSWORD=<passphrase> fastlane match appstore --readonly
+```
+
+**CI signing setup**
+- Store `MATCH_PASSWORD` as a CI secret variable — never commit it
+- Use `readonly: true` in CI (`is_ci` returns true in most CI environments) — CI should never regenerate certificates
+- For GitHub Actions: store the certificates git repo URL and match password as repository secrets
+
+### iOS App Store Submission
+
+**App Store Connect setup**
+1. Create the app record in App Store Connect (appstoreconnect.apple.com)
+2. Configure capabilities in the Apple Developer portal (push notifications, Sign in with Apple, etc.)
+3. Create App Store listing: screenshots (required for each device size), description, keywords, privacy policy URL
+4. Configure pricing and availability
+
+**Required screenshots (2024)**
+- iPhone: 6.9" display (iPhone 16 Pro Max), 6.5" display (iPhone 14 Plus)
+- iPad (if universal): 12.9" iPad Pro, 11" iPad Pro
+- Screenshots generated programmatically with `fastlane snapshot` + `fastlane frameit`
+
+**Fastlane deliver for metadata + upload**
+```ruby
+lane :release do
+  # Build
+  gym(scheme: "MyApp", configuration: "Release")
+
+  # Upload to App Store Connect
+  deliver(
+    submit_for_review: false,   # set true to auto-submit
+    automatic_release: false,   # set true to auto-release after approval
+    force: true,                # skip HTML report generation
+    metadata_path: "./fastlane/metadata",
+    screenshots_path: "./fastlane/screenshots"
+  )
+end
+```
+
+**App Store review guidelines (commonly rejected items)**
+- Crashy builds: any crash during review results in immediate rejection
+- Incomplete functionality: demo/placeholder screens visible to reviewers
+- Login-gated apps: must provide reviewer credentials in App Store Connect
+- Guideline 4.2.2: apps must be more than a repackaged website
+- Push notification permission: must explain usage before prompting
+- Privacy labels must accurately describe all data collected
+
+**TestFlight for pre-release distribution**
+```ruby
+lane :beta do
+  gym(scheme: "MyApp", configuration: "Release")
+  pilot(
+    app_identifier: "com.example.myapp",
+    changelog: "Bug fixes and improvements",
+    distribute_external: false,  # true for external testers
+    notify_external_testers: false
+  )
+end
+```
+
+### Android Code Signing
+
+**Release keystore**
+```bash
+# Generate a release keystore (do this once; store securely)
+keytool -genkey -v \
+  -keystore release.keystore \
+  -alias myapp \
+  -keyalg RSA \
+  -keysize 2048 \
+  -validity 10000
+
+# Never commit release.keystore to git
+```
+
+**Signing configuration in Gradle**
+```kotlin
+// app/build.gradle.kts
+android {
+    signingConfigs {
+        create("release") {
+            storeFile = file(System.getenv("KEYSTORE_PATH") ?: "release.keystore")
+            storePassword = System.getenv("KEYSTORE_PASSWORD")
+            keyAlias = System.getenv("KEY_ALIAS")
+            keyPassword = System.getenv("KEY_PASSWORD")
+        }
+    }
+    buildTypes {
+        release {
+            signingConfig = signingConfigs.getByName("release")
+            isMinifyEnabled = true
+            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
+        }
+    }
+}
+```
+
+**CI keystore management**
+- Store keystore as a base64-encoded CI secret: `base64 release.keystore | pbcopy`
+- In CI: decode and write to disk: `echo $KEYSTORE_BASE64 | base64 -d > release.keystore`
+- Store `KEYSTORE_PASSWORD`, `KEY_ALIAS`, `KEY_PASSWORD` as separate CI secrets
+- Never print these values in CI logs — mask secrets in CI configuration
+
+**Google Play App Signing**
+Enable Google Play App Signing: Google manages the release signing key, you upload with an upload key. Benefits: Google can re-sign if your upload key is lost; protects against keystore loss (catastrophic for Android apps — if you lose the keystore, you cannot update the app).
+
+### Android Play Store Submission
+
+**App Bundle (AAB) vs APK**
+- Always submit AAB (`.aab`) to Play Store — it enables Play Feature Delivery, dynamic delivery, and smaller installs
+- APK is for direct distribution only (enterprise, sideloading)
+- Build AAB: `./gradlew bundleRelease`
+
+**Fastlane supply for Android**
+```ruby
+lane :deploy_production do
+  gradle(task: "bundle", build_type: "Release")
+  supply(
+    track: "production",
+    aab: "app/build/outputs/bundle/release/app-release.aab",
+    package_name: "com.example.myapp"
+  )
+end
+
+lane :deploy_internal do
+  gradle(task: "bundle", build_type: "Release")
+  supply(
+    track: "internal",
+    aab: "app/build/outputs/bundle/release/app-release.aab"
+  )
+end
+```
+
+**Play Console tracks**
+- Internal testing: up to 100 testers, immediate availability
+- Closed testing (Alpha): specific Google Groups, same-day availability
+- Open testing (Beta): public opt-in, same-day availability
+- Production: staged rollout available (1% → 5% → 20% → 100%)
+
+**ProGuard / R8 rules**
+```proguard
+# Keep data classes used by Gson/Moshi/Retrofit
+-keep class com.example.myapp.data.model.** { *; }
+
+# Keep Retrofit service interfaces
+-keep interface com.example.myapp.data.network.** { *; }
+
+# Keep Parcelable implementations
+-keep class * implements android.os.Parcelable {
+    public static final android.os.Parcelable$Creator *;
+}
+```
+
+Always build and test the release APK/AAB locally before submitting — R8 obfuscation can break reflection-dependent code (Gson, Retrofit, Hilt) that works fine in debug builds.
+
+### CI/CD Pipeline
+
+**GitHub Actions — iOS**
+```yaml
+name: iOS Release
+on:
+  push:
+    tags: ['v*']
+jobs:
+  release:
+    runs-on: macos-14
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - name: Install dependencies
+        run: bundle exec pod install
+      - name: Sync signing
+        env:
+          MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}
+          MATCH_GIT_URL: ${{ secrets.MATCH_GIT_URL }}
+        run: bundle exec fastlane sync_signing
+      - name: Build and upload
+        env:
+          APP_STORE_CONNECT_API_KEY_ID: ${{ secrets.ASC_KEY_ID }}
+          APP_STORE_CONNECT_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}
+          APP_STORE_CONNECT_API_KEY: ${{ secrets.ASC_PRIVATE_KEY }}
+        run: bundle exec fastlane release
+```
+
+**GitHub Actions — Android**
+```yaml
+name: Android Release
+on:
+  push:
+    tags: ['v*']
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+      - name: Decode keystore
+        env:
+          KEYSTORE_BASE64: ${{ secrets.KEYSTORE_BASE64 }}
+        run: echo $KEYSTORE_BASE64 | base64 -d > release.keystore
+      - name: Build release
+        env:
+          KEYSTORE_PASSWORD: ${{ secrets.KEYSTORE_PASSWORD }}
+          KEY_ALIAS: ${{ secrets.KEY_ALIAS }}
+          KEY_PASSWORD: ${{ secrets.KEY_PASSWORD }}
+        run: ./gradlew bundleRelease
+      - name: Upload to Play Store
+        uses: r0adkll/upload-google-play@v1
+        with:
+          serviceAccountJsonPlainText: ${{ secrets.SERVICE_ACCOUNT_JSON }}
+          packageName: com.example.myapp
+          releaseFiles: app/build/outputs/bundle/release/*.aab
+          track: internal
+```
+
+### Version Management
+
+**iOS versioning**
+- `CFBundleShortVersionString` (Marketing version): user-visible version (`1.2.3`)
+- `CFBundleVersion` (Build number): must increase monotonically for each App Store submission
+- Automate build number increment: `fastlane run increment_build_number`
+- Automate version: `fastlane run increment_version_number bump_type:minor`
+
+**Android versioning**
+```kotlin
+android {
+    defaultConfig {
+        versionCode = 42        // Must increase on every Play Store submission
+        versionName = "1.2.3"   // User-visible version string
+    }
+}
+```
+
+Automate versionCode in CI: read from git tag, CI build number, or a `version.properties` file.