reis-mobile 0.9.0 → 0.10.0

package/skills/mobile-auth/references/android.md

@@ -0,0 +1,10 @@
+# Authentication on Android
+
+- Inspect the identity provider and resolved Credential Manager dependencies before choosing a sign-in API. Verify credential type and provider support on the app's OS/device range.
+- Passkey registration/authentication exchanges server-generated request data and sends the response back for server verification. Validate the relying-party/domain association; a credential selector is not backend authorization.
+- Give UI-bound credential/browser operations a valid host lifetime. Preserve attempt state across recreation as the SDK prescribes and distinguish user cancellation from invalid credentials.
+- Coordinate logout with SDK credential/session state and the backend. Clearing a local credential preference does not revoke a remote session.
+- Check [identity guides](../../mobile-android/references/identity.md) when restoring credentials or retrieving verified email; these features are separate from account merging.
+- Test cancellation, no credential, provider unavailability, process recreation and account switching, including cached data isolation.
+
+Official reference: [Credential Manager](https://developer.android.com/identity/credential-manager).

package/skills/mobile-auth/references/flutter.md

@@ -0,0 +1,9 @@
+# Authentication in Flutter
+
+- Inspect the installed provider plugin and the app's session state owner. Use its auth-state stream once at the appropriate lifetime; avoid separate login state in each screen.
+- Verify native callback configuration on Android and iOS alongside Dart routing. A successful provider callback is not evidence the backend session was established.
+- Restore secure credentials before making account-scoped requests; do not show another account's cached content while restoration is unresolved.
+- Passkey support depends on the actual plugin and host versions. Trace its registration/assertion response to backend verification; do not replace this with a local biometric boolean.
+- Cancel/dispose listeners and invalidate in-flight refresh/login results on logout. Test the session state owner separately from widget navigation, then test the native callback in a device build.
+
+Reuse [Firebase Auth guidance](../../mobile-firebase/references/flutter/auth.md) when installed and [secure token storage](../../mobile-security/references/flutter/secure-token-store.md). Official reference: [Flutter app links](https://docs.flutter.dev/cookbook/navigation/set-up-app-links).

package/skills/mobile-auth/references/ios.md

@@ -0,0 +1,10 @@
+# Authentication on iOS
+
+- Use the provider-supported AuthenticationServices flow. For browser login, verify `ASWebAuthenticationSession` ownership, presentation context and callback configuration for the installed SDK/deployment target.
+- For passkeys, configure the associated domain/relying party and verify responses on the server. Model cancellation, missing credentials and recovery explicitly.
+- Treat Sign in with Apple identifiers and credentials through the provider contract. Do not depend on receiving profile fields on every sign-in, or equate a relay email with authority to merge accounts.
+- Inspect Keychain accessibility and access groups against foreground/background needs. Keychain presence alone does not prove the server session is valid; define behavior across reinstall/account change.
+- Guard shared refresh state across suspension points; invalidate late completions when the account changes.
+- Test cancellation, return from browser, restored session, unavailable credentials and reauthentication with a configured test account.
+
+Official references: [AuthenticationServices](https://developer.apple.com/documentation/authenticationservices), [ASWebAuthenticationSession](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession).

package/skills/mobile-auth/references/kotlin-multiplatform.md

@@ -0,0 +1,9 @@
+# Authentication in Kotlin Multiplatform
+
+- Share session models and backend exchanges where appropriate; host apps own browser presentation, credential prompts, secure storage and callback registration.
+- Define typed results for success, cancellation, reauthentication and failure at the host boundary. A shared caller must not infer success because a native sheet closed.
+- Use one session coordinator across shared callers. An actor/mutex boundary still needs session-generation checks after suspended backend operations.
+- Never put a client secret or native UI dependency in `commonMain`. Passkeys still require backend challenges and verification; expose platform ceremonies through interfaces/target implementations.
+- Test shared transition/race logic in `commonTest`; verify Android credential and iOS browser/passkey flows separately using [Android](android.md) and [iOS](ios.md).
+
+Official reference: [Kotlin platform-specific declarations](https://kotlinlang.org/docs/multiplatform/multiplatform-expect-actual.html).

package/skills/mobile-auth/references/react-native.md

@@ -0,0 +1,9 @@
+# Authentication in React Native and Expo
+
+- Reuse the existing provider/auth library and secure native storage. Check callback schemes, app links and build configuration in both hosts, including Expo config plugins where used.
+- In Expo, check the installed AuthSession/provider integration and test in a development build with the actual redirect. Do not assume Expo Go reproduces production schemes or native passkey support.
+- Let the session owner coordinate refresh; a component remount must not start a second independent renewal. Abort or invalidate the old account's requests before clearing query caches and exposing another account.
+- Native passkey APIs need a supported bridge and a server ceremony. JS token parsing or a biometric result cannot substitute for server verification.
+- Test cancellation and linking conflicts in state logic, then callback routing and secure storage in a native build. Check startup before the navigation container becomes ready.
+
+Official references: [Expo authentication](https://docs.expo.dev/guides/authentication/), [React Native security](https://reactnative.dev/docs/security). Reuse [Firebase Auth](../../mobile-firebase/references/react-native/auth.md) when that provider is installed.

package/skills/mobile-billing/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: mobile-billing
+description: Implements and reviews in-app purchases and subscriptions across Flutter, Android, iOS, React Native and Kotlin Multiplatform. Use for product catalogs, purchase and restore flows, pending or interrupted purchases, server-side verification, acknowledgement, account binding, plan changes and store sandbox tests. Store submission belongs to mobile-release; account deletion to mobile-privacy.
+intents: [billing]
+stacks: ["*"]
+---
+
+# Mobile Billing
+
+Trace each purchase from the product query to the entitlement your backend records. Reuse the [project brief](../../docs/agent-context.md), then inspect the billing client setup, the purchase listener, the backend verification endpoint and every screen that reads entitlement before changing a flow. The store-side lifecycle (subscription states, server notifications, acknowledgement deadlines, sandbox tools) is in the [billing lifecycle reference](../mobile-release/references/billing.md); this skill applies it to the app's code.
+
+## Pick the reference
+
+| Project | Read |
+|---|---|
+| Flutter | [references/flutter.md](references/flutter.md) |
+| Android | [references/android.md](references/android.md) |
+| iOS | [references/ios.md](references/ios.md) |
+| React Native / Expo | [references/react-native.md](references/react-native.md) |
+| Kotlin Multiplatform | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
+
+Flutter and React Native apps also need the Android and iOS references for store configuration and native behavior. Confirm the billing library version from the lock file; client APIs change across major versions.
+
+## Build the purchase inventory
+
+Record for each product: store product id, type (consumable, non-consumable, auto-renewable or non-renewing subscription), base plans and offers or subscription group, the call that starts the purchase, the listener that receives results, the backend endpoint that verifies, the code that reads entitlement and the acknowledge, consume or finish call. Mark store console and backend evidence you cannot read as unknown.
+
+## The purchase is a state machine
+
+- Register the purchase listener at startup, before any purchase UI, for the life of the process. Results arrive outside the paywall: renewals, deferred payments, Ask to Buy approvals, purchases from another device and purchases interrupted by process death.
+- Model idle, purchasing, pending, verifying, granted, failed and cancelled. A user cancellation is a normal outcome: no error dialog and no retry.
+- A pending purchase grants nothing. Show it as pending and grant only after the store reports the payment completed.
+- Send the purchase token or signed transaction to the backend with the app account id. The backend verifies it with the store and records the entitlement idempotently, keyed by the store's purchase identifier (`purchaseToken` on Google Play, `transactionId` and `originalTransactionId` on the App Store), so a purchase delivered again by the listener, a restore or the next launch grants once.
+- Acknowledge, consume or finish only after the backend confirms the record. On the next launch, query unfinished or unacknowledged purchases and resume verification; this is the recovery path for a crash between payment and record.
+- Bind the purchase to the account that started it with the store's account field (`obfuscatedAccountId` on Google Play, `appAccountToken` on the App Store). A result that arrives after sign-out or an account switch is reconciled by the backend, never attached to whoever is signed in now.
+
+## Entitlement and catalog
+
+- Screens read entitlement from the backend. Cache the last known state for offline use with its timestamp, and decide explicitly what an expired cache allows.
+- Display prices, currencies and offers only from the store's product details. Handle products missing from the current storefront.
+- Upgrades, downgrades and plan changes follow each store's rules (replacement modes on Google Play, subscription group levels on the App Store). The backend links the replaced purchase to the new one.
+- Provide restore: a visible restore action on iOS and a purchase query on launch and resume on Android. Refunds and revocations arrive through server notifications; the app shows the backend state and does not revoke on its own.
+
+## Failure scenarios to test
+
+Purchase interrupted by process death; verification failing on a network error and retried with the same token; the same purchase delivered twice; a pending purchase completed days later while the app is closed; user cancellation; a product id not found; an account switch during a purchase; a refund notification; access kept during a grace period or billing retry; restore on a fresh install.
+
+## Verify and deliver
+
+Use each store's sandbox: Google Play license testers on a testing track, StoreKit configuration files in Xcode and Sandbox accounts. Test the backend by replaying server notification payloads. Unit-test the purchase state machine against a fake billing client.
+
+Return the purchase inventory with `path:symbol` evidence, the implemented transitions, test results and any unverified store console or backend configuration. Whether digital goods must use store billing depends on the market and changes often: check the current store policy instead of designing from memory. Use [mobile-release](../mobile-release/SKILL.md) for submission, [mobile-privacy](../mobile-privacy/SKILL.md) for account deletion versus cancellation, [mobile-security](../mobile-security/SKILL.md) for tampered clients and [mobile-analytics](../mobile-analytics/SKILL.md) for conversion events.
+
+## Official sources
+
+- [Google Play Billing integration](https://developer.android.com/google/play/billing/integrate)
+- [StoreKit in-app purchase](https://developer.apple.com/documentation/storekit/in-app-purchase)
+- [App Store Server Notifications](https://developer.apple.com/documentation/appstoreservernotifications)

package/skills/mobile-billing/references/android.md

@@ -0,0 +1,11 @@
+# Billing on Android
+
+- Read the Play Billing Library version from the version catalog or Gradle files. Version upgrades and their removed APIs are in the [Play guides](../../mobile-android/references/play.md).
+- Build one `BillingClient` with a `PurchasesUpdatedListener` and pending purchases enabled through `PendingPurchasesParams`. Play Billing Library 8 adds `enableAutoServiceReconnection()`; with it enabled, do not call `startConnection()` again from `onBillingServiceDisconnected`. Without it, reconnect before the next call.
+- Query products with `queryProductDetailsAsync`. A subscription purchase needs the `offerToken` of the chosen offer in `BillingFlowParams`; set `setObfuscatedAccountId` with the app account id.
+- Grant only when `getPurchaseState()` is `PURCHASED` and the backend has verified the `purchaseToken`. `PENDING` purchases complete later and arrive through the listener or the next query.
+- After the backend records the purchase, call `acknowledgePurchase` for non-consumables and subscriptions or `consumeAsync` for consumables. Purchases not acknowledged within three days are refunded.
+- Call `queryPurchasesAsync` on startup and on resume to recover purchases completed while the app was closed or killed.
+- Test with license testers and a build uploaded to a testing track with the release package name and signing key.
+
+Official references: [integrate the library](https://developer.android.com/google/play/billing/integrate), [test billing](https://developer.android.com/google/play/billing/test).

package/skills/mobile-billing/references/flutter.md

@@ -0,0 +1,11 @@
+# Billing in Flutter
+
+- Confirm the plugin in `pubspec.lock`: `in_app_purchase` with its Android and StoreKit implementations, or a vendor SDK. Read that version's documentation; the APIs below are from `in_app_purchase`.
+- Listen to `InAppPurchase.instance.purchaseStream` from an app-level owner created at startup, not from the paywall widget. Cancel that `StreamSubscription` only when the owner is disposed.
+- Check `isAvailable()` before `queryProductDetails()`, and handle the ids returned in `notFoundIDs`.
+- Handle every `PurchaseStatus`: `pending`, `purchased`, `restored`, `error` and `canceled`. Send `verificationData.serverVerificationData` to the backend for purchased and restored items, then call `completePurchase` when `pendingCompletePurchase` is true.
+- For consumables, pass `autoConsume: false` to `buyConsumable`: the default consumes the product right after a successful purchase, without waiting for your backend. On Android, consume after the backend records the purchase through `InAppPurchaseAndroidPlatformAddition.consumePurchase`.
+- Pass the account identifier through `PurchaseParam.applicationUserName`, and confirm how the installed platform implementation forwards it to each store.
+- Put the plugin behind an app interface so unit and widget tests can drive every purchase status with a fake stream. Store behavior needs device builds against the sandboxes in [Android](android.md) and [iOS](ios.md).
+
+Official reference: [in_app_purchase](https://pub.dev/packages/in_app_purchase).

package/skills/mobile-billing/references/ios.md

@@ -0,0 +1,11 @@
+# Billing on iOS
+
+- Use StoreKit 2 unless the deployment target or an existing integration requires the original API. The basic purchase call is in the [StoreKit section](../../mobile-ios/references/platform-features.md).
+- Start a long-lived task over `Transaction.updates` at launch, before any purchase UI. It delivers renewals, Ask to Buy approvals, refunds and purchases made on other devices.
+- Purchase with `product.purchase(options:)` including `.appAccountToken(_:)` set to the account's UUID. Handle `.success`, `.pending` and `.userCancelled`; grant only a `.verified` transaction.
+- Send the signed transaction (`jwsRepresentation`) to the backend and call `transaction.finish()` after the backend records it. Iterate `Transaction.unfinished` at launch to resume interrupted verifications.
+- Read `Transaction.currentEntitlements` and the subscription `status` to display state, but let the backend decide access. Distinguish `inGracePeriod` and `inBillingRetryPeriod` from `expired` and `revoked`.
+- Offer restore through `AppStore.sync()` behind an explicit user action; it can prompt for the Apple Account.
+- Test with a StoreKit configuration file in the scheme, then Sandbox and TestFlight.
+
+Official references: [In-App Purchase](https://developer.apple.com/documentation/storekit/in-app-purchase), [StoreKit testing in Xcode](https://developer.apple.com/documentation/xcode/setting-up-storekit-testing-in-xcode).

package/skills/mobile-billing/references/kotlin-multiplatform.md

@@ -0,0 +1,9 @@
+# Billing in Kotlin Multiplatform
+
+- Keep product ids, the purchase state machine, the entitlement model and backend verification calls in `commonMain` when the project shares that logic. Keep `BillingClient` in Android code and StoreKit in the iOS app.
+- StoreKit 2 is a Swift-only API, so Kotlin/Native cannot call it through Objective-C interop. Implement the iOS store client in Swift and inject it into shared code through an interface the shared module exports.
+- Define one shared result type for purchased, pending, cancelled and failed, and map each host's results into it without losing the store purchase identifier.
+- Start each host's listener at app launch and forward results to the shared owner. Each host keeps its own acknowledge or finish call, made after the backend confirms the record.
+- Test the shared state machine in `commonTest` with a fake store client. Test each host against its store sandbox separately; an Android pass does not prove StoreKit behavior.
+
+Official references: [platform-specific declarations](https://kotlinlang.org/docs/multiplatform/multiplatform-expect-actual.html), [Swift and Objective-C interop](https://kotlinlang.org/docs/native-objc-interop.html).

package/skills/mobile-billing/references/react-native.md

@@ -0,0 +1,10 @@
+# Billing in React Native and Expo
+
+- Confirm the library in `package.json` and the lockfile (`react-native-iap`, a vendor SDK such as RevenueCat's, or native modules). Check its support for the installed React Native version and the New Architecture.
+- In-app purchases need native code: Expo Go cannot run them, so use a development build. Add store capabilities and permissions through the library's config plugin or the native project files.
+- Open the store connection and register purchase listeners in an app-root owner, not in the paywall screen, and remove them only when that owner unmounts. Keep listener callbacks idempotent: React Strict Mode runs effects twice in development.
+- Send the purchase token or signed transaction to the backend. Call the library's finish or acknowledge function only after the backend records it, marking consumables as such.
+- Ignore late results for an account generation that is no longer active, and let the backend reconcile them.
+- Test the purchase state machine in Jest with the native module mocked. Store behavior needs native builds against the [Android](android.md) and [iOS](ios.md) sandboxes.
+
+Official reference: [Expo development builds](https://docs.expo.dev/develop/development-builds/introduction/). Store rules for digital goods are in the [platform guide](../../mobile-rn/references/platform-features.md).

package/skills/mobile-ci/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: mobile-ci
+description: Sets up and reviews mobile CI/CD and fastlane automation across Flutter, Android, iOS, React Native and Kotlin Multiplatform. Use for Fastfile lanes, Match signing, TestFlight beta uploads, App Store submission, Snapshot screenshots, Xcode Cloud or build and deployment pipelines.
+intents: [deployment]
+stacks: ["*"]
+---
+
+# Mobile CI
+
+Connect the app's existing build, test, signing and distribution steps into a reproducible pipeline. Use [mobile-release](../mobile-release/SKILL.md) for release readiness and rollout decisions.
+
+## Choose the references
+
+Load the app's stack reference, then only the fastlane guide needed for the task. Cross-platform apps also need the reference for each native target being shipped.
+
+| Need | Read |
+|---|---|
+| Flutter | [references/flutter.md](references/flutter.md) |
+| Android, including a cross-platform Android host | [references/android.md](references/android.md) |
+| iOS, including a cross-platform iOS host | [references/ios.md](references/ios.md) |
+| React Native or Expo | [references/react-native.md](references/react-native.md) |
+| Kotlin Multiplatform | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
+| Pipeline jobs, caches, credentials and artifact retention | [Shared CI/CD guide](../mobile-release/references/ci-cd.md) |
+| Initialize fastlane and define iOS lanes | [Setup](references/fastlane/setup-fastlane.md) |
+| iOS certificates and provisioning profiles | [Match](references/fastlane/match.md) |
+| TestFlight internal and external testing | [Beta](references/fastlane/beta.md) |
+| App Store submission and metadata | [Release](references/fastlane/release.md) |
+| Capture, frame and upload App Store screenshots | [Snapshot](references/fastlane/snapshot.md) |
+| Xcode Cloud workflow integration | [Xcode Cloud](references/fastlane/xcode-cloud.md) |
+
+## Workflow
+
+1. Inspect existing workflows, Fastfile, Appfile, Matchfile, Gemfile.lock, platform lock files, schemes, flavors and environment configuration. Identify working directories and actual artifact paths before writing commands.
+2. Establish the requested scope: pipeline setup, local verification, beta upload or production submission. Preserve existing lanes and signing conventions; do not replace the whole Fastfile with an example.
+3. Separate validation from signed builds and uploads. Use pinned toolchains, lock-file-based caches, protected release jobs, secret storage and retained symbols as described in the shared CI/CD guide.
+4. Adapt the selected reference to the detected platform. The imported fastlane guides describe iOS workflows; Android needs its own Gradle tasks, keystore and Play destination.
+5. Check lane definitions, dependencies, action parameters and workflow syntax before execution. Run the project's relevant local checks, then report what was verified locally and what still needs a CI or store run. A configured pipeline is not evidence of a successful upload.
+
+## Applying the upstream examples
+
+The fastlane references preserve the instructions from `greenstevester/fastlane-skill`; their frontmatter was removed and the Xcode Cloud link relocated. Read them as examples, with these integration rules:
+
+- Use the project's Ruby/Bundler/fastlane versions and `bundle exec fastlane` when a Gemfile exists. Verify compatibility from the lock file and current fastlane documentation rather than applying the upstream blanket claim about Bundler 4 or replacing the installation with Homebrew.
+- Resolve `/setup-fastlane` and references to the `match`, `beta`, `release` and `snapshot` skills through the table above. These are references, not separately installed commands. Embedded `!` shell snippets and `${ARGUMENTS}` placeholders are upstream notation, not automatic preflight results.
+- Inspect each lane before invoking it: the setup and Match examples define different `release` behavior. Confirm the exact tested build rather than submitting whichever build is newest. Existing session authorization determines whether builds, uploads, store submission or automatic release are in scope.
+- Keep Match read-only in CI. Certificate revocation (`match nuke`), simulator erasure, package removal and screenshot-directory replacement are destructive recovery examples, not routine setup steps; diagnose first and require explicit authorization for those actions.
+- Verify action options with the installed version's help or official documentation. In particular, check the `app_store_connect_api_key` action's content parameter rather than copying the Xcode Cloud example's `key:` blindly. Never print private keys or passwords.
+- Confirm current screenshot dimensions and accepted devices with Apple's linked specifications and installed simulators. Treat processing/review times and StoreKit storefront behavior as claims to verify, not guarantees. Screenshot fixtures must represent the product accurately.
+- The Xcode Cloud guide describes lifecycle scripts but does not ship them. Create or inspect those scripts for the actual project; do not assume the setup guide generated them. Follow the team's configured triggers and managed signing, and avoid rebuilding or uploading the same artifact twice.

package/skills/mobile-ci/references/android.md

@@ -0,0 +1,8 @@
+# Android CI
+
+Read the [shared pipeline guide](../../mobile-release/references/ci-cd.md) and [Android release reference](../../mobile-release/references/android.md).
+
+- Resolve the Gradle wrapper, JDK, module, variant and signing configuration from the project. Run its existing lint and test tasks before the release bundle task.
+- Keep the upload keystore and Play credentials in CI secrets; untrusted pull requests must not receive them. Preserve the distinction between the upload key and Play App Signing.
+- Use the actual AAB path and package identifier in the Android lane. The imported iOS `gym`, `pilot`, `match` and `snapshot` examples do not implement Android builds or uploads.
+- Upload through the project's fastlane Play lane with an explicit track and release status. Retain the exact AAB, mapping and native symbols. Coordinate version codes across concurrent runs and retries.

package/skills/mobile-ci/references/fastlane/beta.md

@@ -0,0 +1,75 @@
+> Adapted from the `beta` skill in [greenstevester/fastlane-skill](https://github.com/greenstevester/fastlane-skill) (MIT).
+
+## TestFlight Beta Release
+
+Build and upload the iOS app to TestFlight for beta testing.
+
+### Pre-flight Checks
+- Fastlane installed: !`fastlane --version 2>/dev/null | grep "fastlane " | head -1 || echo "✗ Not installed - run: brew install fastlane"`
+- Fastfile exists: !`ls fastlane/Fastfile 2>/dev/null && echo "✓ Found" || echo "✗ Not found - run /setup-fastlane first"`
+- App-specific password: !`[ -n "$FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD" ] && echo "✓ Set" || echo "⚠️ Not set - export FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD='xxxx-xxxx-xxxx-xxxx'"`
+
+### Arguments: ${ARGUMENTS:-none}
+
+---
+
+## What This Does
+
+1. **Syncs certificates** via Match (appstore type) — *only once you've run the `match` skill; the base `setup-fastlane` lane skips this*
+2. **Increments build number** (unless `--skip-build-increment`)
+3. **Builds release archive** with gym
+4. **Uploads to TestFlight** via pilot
+5. **Optionally distributes to external testers** (via the separate `beta_external` lane)
+
+---
+
+## Commands
+
+### Standard Beta (Internal Testers)
+Run from your project directory (where `fastlane/` lives):
+```bash
+fastlane beta
+```
+
+### Skip Build Number Increment
+```bash
+fastlane beta skip_build_increment:true
+```
+
+### External Testers (with changelog)
+```bash
+fastlane beta_external changelog:"Bug fixes and performance improvements"
+```
+
+---
+
+## Troubleshooting
+
+### "No value found for 'username'"
+Set your Apple ID in `fastlane/Appfile`:
+```ruby
+apple_id("your@email.com")
+```
+
+### "Please sign in with an app-specific password"
+1. Go to https://account.apple.com → Sign-In & Security → App-Specific Passwords
+2. Generate a password named "Fastlane"
+3. Export it:
+```bash
+export FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD='xxxx-xxxx-xxxx-xxxx'
+```
+
+### rsync error during export
+If you see `--extended-attributes: unknown option`, Homebrew rsync conflicts with Xcode:
+```bash
+brew uninstall rsync  # Use system rsync
+```
+
+---
+
+## After Upload
+
+- Build will appear in TestFlight within 1-5 minutes
+- Internal testers are notified automatically
+- External testers require `beta_external` lane or manual distribution in App Store Connect
+

package/skills/mobile-ci/references/fastlane/match.md

@@ -0,0 +1,288 @@
+> Adapted from the `match` skill in [greenstevester/fastlane-skill](https://github.com/greenstevester/fastlane-skill) (MIT).
+
+## Code Signing with Match
+
+Set up Fastlane Match to manage iOS code signing certificates and provisioning profiles in a shared Git repository.
+
+### Pre-flight Checks
+- Fastlane installed: !`fastlane --version 2>/dev/null | grep "fastlane " | head -1 || echo "✗ Not installed - run: brew install fastlane"`
+- Fastfile exists: !`ls fastlane/Fastfile 2>/dev/null && echo "✓ Found" || echo "✗ Not found - run /setup-fastlane first"`
+- Existing Matchfile: !`ls fastlane/Matchfile 2>/dev/null && echo "✓ Already configured" || echo "○ Not configured yet"`
+- Git available: !`git --version 2>/dev/null | head -1 || echo "✗ Git not installed"`
+
+### Arguments: ${ARGUMENTS:-setup}
+
+---
+
+## What is Match?
+
+Match stores your iOS certificates and provisioning profiles in a **private Git repository**, encrypted with a passphrase. Benefits:
+
+- **Team sharing**: Everyone uses the same certificates (no more "works on my machine")
+- **CI/CD ready**: Clone the repo in your pipeline, no manual cert management
+- **Revoke protection**: Prevents accidental certificate revocation
+- **Audit trail**: Git history shows who changed what and when
+
+---
+
+## Step 1: Create a Private Git Repository
+
+Create a **private** repository to store your encrypted certificates:
+
+```bash
+# GitHub CLI (recommended)
+gh repo create certificates --private
+
+# Or manually at github.com/new (select Private)
+```
+
+**Repository naming conventions:**
+- `certificates` or `ios-certificates`
+- `fastlane-certs`
+- `{company}-signing`
+
+> **Security**: This repo will contain encrypted certificates. Keep it private and limit access to team members who need to build the app.
+
+---
+
+## Step 2: Initialize Match
+
+Run match init to create your Matchfile:
+
+```bash
+fastlane match init
+```
+
+When prompted:
+1. **Storage mode**: Select `git`
+2. **Git URL**: Enter your private repo URL (e.g., `git@github.com:yourorg/certificates.git`)
+
+This creates `fastlane/Matchfile`:
+
+```ruby
+git_url("git@github.com:yourorg/certificates.git")
+
+storage_mode("git")
+
+type("development") # Default type, can be overridden per-lane
+
+# app_identifier(["com.yourcompany.app"])  # Optional: limit to specific apps
+# username("user@example.com")              # Optional: Apple ID
+```
+
+---
+
+## Step 3: Generate Certificates
+
+Generate certificates for each distribution type:
+
+### Development (for debugging on devices)
+```bash
+fastlane match development
+```
+
+### App Store (for TestFlight and App Store)
+```bash
+fastlane match appstore
+```
+
+### Ad Hoc (for direct device distribution)
+```bash
+fastlane match adhoc
+```
+
+**First run prompts:**
+1. **Apple ID**: Your Apple Developer account email
+2. **Passphrase**: Create a strong passphrase to encrypt certificates (save this securely!)
+
+> **Important**: Save the passphrase in a password manager. You'll need it for CI/CD and new team members.
+
+---
+
+## Step 4: Integrate with Fastfile
+
+Update your lanes to use Match before building:
+
+```ruby
+default_platform(:ios)
+
+platform :ios do
+  desc "Sync all certificates"
+  lane :sync_signing do
+    match(type: "development")
+    match(type: "appstore")
+  end
+
+  desc "Install signing assets on CI (read-only)"
+  lane :certificates do
+    setup_ci                                 # temp keychain on CI; no-op locally
+    match(type: "appstore", readonly: true)
+  end
+
+  desc "Build for TestFlight"
+  lane :beta do |options|
+    setup_ci                                 # temp keychain on CI; no-op locally
+    match(type: "appstore", readonly: true)
+    increment_build_number unless options[:skip_build_increment]
+    gym(scheme: "YourApp", export_method: "app-store")
+    pilot(skip_waiting_for_build_processing: true)
+  end
+
+  desc "Build for App Store"
+  lane :release do
+    setup_ci                                 # temp keychain on CI; no-op locally
+    match(type: "appstore", readonly: true)
+    increment_build_number
+    gym(scheme: "YourApp", export_method: "app-store")
+    deliver(submit_for_review: false, force: true)
+  end
+end
+```
+
+**Key pattern**: Use `readonly: true` in build lanes to prevent accidental certificate regeneration.
+
+**CI keychain**: `setup_ci` creates a temporary keychain on CI runners (and is a no-op locally) so `match` can import certs without keychain-permission errors. Call it before `match` in any lane that runs on CI.
+
+---
+
+## Step 5: Onboard Team Members
+
+New team members run:
+
+```bash
+# Clone and decrypt existing certificates (readonly)
+fastlane match development --readonly
+fastlane match appstore --readonly
+```
+
+They'll need:
+1. Access to the private certificates repository
+2. The Match passphrase
+3. Apple Developer team membership
+
+**Readonly mode** ensures they can't accidentally revoke or regenerate certificates.
+
+---
+
+## Step 6: CI/CD Setup
+
+Set these environment variables in your CI/CD system:
+
+```bash
+# Required
+MATCH_PASSWORD="your-match-passphrase"
+MATCH_GIT_URL="git@github.com:yourorg/certificates.git"
+
+# For App Store Connect (choose one method)
+# Method 1: App-specific password
+FASTLANE_USER="your@appleid.com"
+FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"
+
+# Method 2: API Key (recommended for CI)
+APP_STORE_CONNECT_API_KEY_KEY_ID="ABC123"
+APP_STORE_CONNECT_API_KEY_ISSUER_ID="xyz-xyz-xyz"
+APP_STORE_CONNECT_API_KEY_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
+```
+
+### GitHub Actions Example
+
+```yaml
+- name: Install certificates
+  run: fastlane ios certificates   # runs setup_ci + match(readonly: true)
+  env:
+    MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}
+    MATCH_GIT_URL: ${{ secrets.MATCH_GIT_URL }}
+```
+
+### Xcode Cloud
+
+Add to `ci_scripts/ci_post_clone.sh`:
+```bash
+# Install Fastlane and sync certificates
+brew install fastlane
+fastlane ios certificates   # setup_ci + match(readonly: true)
+```
+
+Set `MATCH_PASSWORD` in Xcode Cloud environment variables.
+
+---
+
+## Troubleshooting
+
+### "Couldn't decrypt the repo"
+Wrong passphrase. Verify `MATCH_PASSWORD` is correct.
+
+### "Code signing error: No provisioning profiles"
+Run `fastlane match appstore` (without `--readonly`) to generate profiles.
+
+### "Your certificate has been revoked"
+Someone revoked certs in Apple Developer portal. Regenerate:
+```bash
+fastlane match nuke development  # Removes all development certs
+fastlane match development       # Regenerates
+```
+
+### "Multiple teams found"
+Specify team in Matchfile:
+```ruby
+team_id("ABCD1234")
+```
+
+### "Unable to find app with bundle identifier"
+Register the app first (SKU and username are required):
+```bash
+fastlane produce create -u your@appleid.com -a com.yourcompany.app -n "Your App Name" --sku YOUR_SKU
+```
+
+---
+
+## Match Commands Reference
+
+```bash
+# Setup
+fastlane match init                    # Create Matchfile
+fastlane match development             # Generate dev certs
+fastlane match appstore                # Generate App Store certs
+fastlane match adhoc                   # Generate Ad Hoc certs
+
+# Team use (readonly - won't modify certs)
+fastlane match development --readonly
+fastlane match appstore --readonly
+
+# Maintenance
+fastlane match nuke development        # Revoke all dev certs
+fastlane match nuke distribution       # Revoke all dist certs
+fastlane match change_password         # Change encryption passphrase
+
+# Debugging
+fastlane match development --verbose   # Detailed output
+```
+
+---
+
+## Security Best Practices
+
+1. **Private repository**: Never make the certificates repo public
+2. **Strong passphrase**: Use 20+ characters, store in password manager
+3. **Limit access**: Only team members who build should have repo access
+4. **Rotate periodically**: Change passphrase annually with `match change_password`
+5. **API keys over passwords**: Use App Store Connect API keys for CI/CD
+
+---
+
+## Files Created
+
+```
+fastlane/
+└── Matchfile          # Match configuration
+
+# In your certificates repo:
+certs/
+├── development/       # Development certificates
+└── distribution/      # App Store/Ad Hoc certificates
+profiles/
+├── development/       # Development provisioning profiles
+├── appstore/          # App Store provisioning profiles
+└── adhoc/             # Ad Hoc provisioning profiles
+```
+