@tamagui/native-ci 1.139.0

package/README.md

@@ -0,0 +1,320 @@
+# @tamagui/native-ci
+
+Native CI/CD helpers for React Native apps with Expo. Provides fingerprint-based build caching and Detox test runners for GitHub Actions.
+
+## Features
+
+- **Fingerprint-based caching**: Uses `@expo/fingerprint` to detect when native rebuilds are needed
+- **2-level caching**: Pre-fingerprint hash (fast) + full fingerprint (accurate)
+- **KV store integration**: Optional Redis/Upstash KV for persistent fingerprint cache
+- **Detox test runners**: Clean TypeScript scripts for running Detox E2E tests
+- **Reusable GitHub Actions**: Drop-in composite actions for iOS and Android
+- **Signal handling**: Proper cleanup on CI cancellation (SIGINT/SIGTERM)
+
+## Requirements
+
+- **Bun**: The Detox runner scripts require [Bun](https://bun.sh) runtime
+- **Node.js**: >= 18 for the CLI and library functions
+
+## Installation
+
+```bash
+npm install @tamagui/native-ci
+# or
+yarn add @tamagui/native-ci
+# or
+bun add @tamagui/native-ci
+```
+
+## CLI Usage
+
+```bash
+# Generate fingerprint for a platform
+npx @tamagui/native-ci fingerprint ios
+npx @tamagui/native-ci fingerprint android
+
+# Generate pre-fingerprint hash (fast)
+npx @tamagui/native-ci pre-hash yarn.lock app.json
+
+# Generate cache key
+npx @tamagui/native-ci cache-key ios <fingerprint>
+
+# KV operations (requires env vars)
+npx @tamagui/native-ci kv-get <key>
+npx @tamagui/native-ci kv-set <key> <value>
+```
+
+### Options
+
+- `--project-root <path>` - Project root directory (default: cwd)
+- `--prefix <prefix>` - Cache key prefix (default: native-build)
+- `--github-output` - Output results for GitHub Actions
+- `--json` - Output as JSON
+
+### Environment Variables
+
+- `KV_STORE_REDIS_REST_URL` - Redis REST API URL for fingerprint caching
+- `KV_STORE_REDIS_REST_TOKEN` - Redis REST API token
+
+## Detox Test Runners
+
+Run Detox tests with Metro bundler and proper cleanup:
+
+```bash
+# iOS
+bun run node_modules/@tamagui/native-ci/src/run-detox-ios.ts \
+  --project-root ./my-app \
+  --config ios.sim.debug
+
+# Android
+bun run node_modules/@tamagui/native-ci/src/run-detox-android.ts \
+  --project-root ./my-app \
+  --config android.emu.ci.debug \
+  --headless
+```
+
+### Runner Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--config` | Detox configuration name | `ios.sim.debug` / `android.emu.ci.debug` |
+| `--project-root` | Project root directory | Current directory |
+| `--record-logs` | Log recording: none, failing, all | `all` |
+| `--retries` | Number of test retries | `0` |
+| `--headless` | Run in headless mode (Android only) | `false` |
+
+## GitHub Actions
+
+### Fingerprint Action
+
+```yaml
+- name: Generate Fingerprint
+  uses: tamagui/tamagui/code/packages/native-ci/actions/fingerprint@main
+  id: fingerprint
+  with:
+    platform: ios  # or android
+    project-root: ./my-app
+    kv-url: ${{ secrets.KV_STORE_REDIS_REST_URL }}
+    kv-token: ${{ secrets.KV_STORE_REDIS_REST_TOKEN }}
+
+- name: Use fingerprint
+  run: echo "Fingerprint: ${{ steps.fingerprint.outputs.fingerprint }}"
+```
+
+#### Inputs
+
+| Input | Description | Default |
+|-------|-------------|---------|
+| `platform` | Platform (ios or android) | Required |
+| `project-root` | Path to Expo project | `.` |
+| `cache-prefix` | Prefix for cache keys | `native-build` |
+| `kv-url` | Redis KV REST URL (optional) | - |
+| `kv-token` | Redis KV REST token (optional) | - |
+| `pre-hash-files` | Files for pre-fingerprint hash | `yarn.lock,package-lock.json,app.json` |
+
+#### Outputs
+
+| Output | Description |
+|--------|-------------|
+| `fingerprint` | Generated fingerprint hash |
+| `cache-key` | Cache key for this build |
+| `pre-fingerprint-hash` | Quick pre-fingerprint hash |
+| `cache-hit` | Whether fingerprint was cached |
+
+### iOS Detox Tests Action
+
+```yaml
+- name: Run iOS Detox Tests
+  uses: tamagui/tamagui/code/packages/native-ci/actions/test-detox-ios@main
+  with:
+    working-directory: ./my-app
+    config: ios.sim.debug
+    app-path: ${{ env.IOS_APP_PATH }}
+```
+
+#### Inputs
+
+| Input | Description | Default |
+|-------|-------------|---------|
+| `project-root` | Path to project root | `.` |
+| `working-directory` | Working directory for tests | `.` |
+| `config` | Detox configuration name | `ios.sim.debug` |
+| `record-logs` | Log recording: none, failing, all | `all` |
+| `retries` | Number of test retries | `0` |
+| `simulator` | iOS simulator device type | `iPhone 15` |
+| `app-path` | Path to built app (optional) | - |
+
+### Android Detox Tests Action
+
+```yaml
+- name: Run Android Detox Tests
+  uses: tamagui/tamagui/code/packages/native-ci/actions/test-detox-android@main
+  with:
+    working-directory: ./my-app
+    config: android.emu.ci.debug
+```
+
+#### Inputs
+
+| Input | Description | Default |
+|-------|-------------|---------|
+| `project-root` | Path to project root | `.` |
+| `working-directory` | Working directory for tests | `.` |
+| `config` | Detox configuration name | `android.emu.ci.debug` |
+| `record-logs` | Log recording: none, failing, all | `all` |
+| `retries` | Number of test retries | `0` |
+| `api-level` | Android API level | `30` |
+| `emulator-options` | Emulator options | See defaults |
+
+## Programmatic API
+
+```typescript
+import {
+  // Fingerprinting
+  generateFingerprint,
+  generatePreFingerprintHash,
+
+  // Caching
+  createCacheKey,
+  saveFingerprintToKV,
+  getFingerprintFromKV,
+
+  // Build runner
+  runWithCache,
+
+  // Metro utilities
+  withMetro,
+  waitForMetro,
+
+  // Detox utilities
+  runDetoxTests,
+  parseDetoxArgs,
+
+  // Android utilities
+  setupAndroidDevice,
+
+  // Constants
+  METRO_PORT,
+  DETOX_SERVER_PORT,
+} from '@tamagui/native-ci'
+
+// Generate fingerprint
+const { hash } = await generateFingerprint({
+  platform: 'ios',
+  projectRoot: './my-app',
+})
+
+// Run build with caching
+const result = await runWithCache({
+  platform: 'ios',
+  buildCommand: 'xcodebuild ...',
+  outputPaths: ['./ios/build'],
+})
+
+// Run tests with Metro
+const exitCode = await withMetro('ios', async () => {
+  return runDetoxTests({
+    config: 'ios.sim.debug',
+    projectRoot: './my-app',
+    recordLogs: 'failing',
+    retries: 0,
+  })
+})
+```
+
+## Example Workflow
+
+```yaml
+name: Native Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  build-ios:
+    runs-on: macos-14
+    outputs:
+      cache-key: ${{ steps.fingerprint.outputs.cache-key }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Generate Fingerprint
+        uses: tamagui/tamagui/code/packages/native-ci/actions/fingerprint@main
+        id: fingerprint
+        with:
+          platform: ios
+          project-root: ./my-app
+
+      - name: Check Build Cache
+        uses: actions/cache/restore@v4
+        id: cache
+        with:
+          path: ./my-app/ios/build
+          key: ${{ steps.fingerprint.outputs.cache-key }}
+          lookup-only: true
+
+      - name: Build iOS App
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: |
+          cd my-app
+          npx expo prebuild --platform ios
+          xcodebuild -workspace ios/*.xcworkspace ...
+
+      - name: Save Build Cache
+        if: steps.cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: ./my-app/ios/build
+          key: ${{ steps.fingerprint.outputs.cache-key }}
+
+  test-ios:
+    needs: build-ios
+    runs-on: macos-14
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Restore Build
+        uses: actions/cache/restore@v4
+        with:
+          path: ./my-app/ios/build
+          key: ${{ needs.build-ios.outputs.cache-key }}
+
+      - name: Run Tests
+        uses: tamagui/tamagui/code/packages/native-ci/actions/test-detox-ios@main
+        with:
+          working-directory: ./my-app
+```
+
+## How Fingerprinting Works
+
+1. **Pre-fingerprint hash**: Quick hash of `yarn.lock`, `app.json`, etc.
+2. **KV cache lookup**: Check if we've seen this pre-hash before
+3. **Full fingerprint**: If not cached, run `@expo/fingerprint` for accurate native dependency detection
+4. **Cache build artifacts**: Use fingerprint as cache key
+
+This 2-level approach means:
+- Cache hits are instant (no fingerprint generation needed)
+- Rebuilds only happen when native dependencies actually change
+- Works across CI runs with KV persistence
+
+## Architecture
+
+```
+src/
+├── constants.ts      # Shared constants and types
+├── fingerprint.ts    # Fingerprint generation
+├── cache.ts          # KV store and local cache
+├── runner.ts         # Build runner with caching
+├── metro.ts          # Metro bundler utilities
+├── detox.ts          # Detox test utilities
+├── android.ts        # Android-specific utilities
+├── cli.ts            # CLI entry point
+├── run-detox-ios.ts  # iOS test runner script
+└── run-detox-android.ts # Android test runner script
+```
+
+## License
+
+MIT

package/action.yml

@@ -0,0 +1,98 @@
+name: 'Native CI - Fingerprint Cache'
+description: 'Generate Expo fingerprints and manage native build caching'
+author: 'Tamagui'
+
+inputs:
+  platform:
+    description: 'Platform to generate fingerprint for (ios or android)'
+    required: true
+  project-root:
+    description: 'Path to the Expo project root'
+    required: false
+    default: '.'
+  cache-prefix:
+    description: 'Prefix for cache keys'
+    required: false
+    default: 'native-build'
+  kv-url:
+    description: 'Redis KV REST API URL for fingerprint caching'
+    required: false
+  kv-token:
+    description: 'Redis KV REST API token'
+    required: false
+  pre-hash-files:
+    description: 'Comma-separated list of files for pre-fingerprint hash'
+    required: false
+    default: 'yarn.lock,app.json'
+
+outputs:
+  fingerprint:
+    description: 'The generated fingerprint hash'
+    value: ${{ steps.fingerprint.outputs.fingerprint }}
+  cache-key:
+    description: 'The cache key to use for this build'
+    value: ${{ steps.fingerprint.outputs.cache-key }}
+  pre-fingerprint-hash:
+    description: 'Quick pre-fingerprint hash'
+    value: ${{ steps.pre-hash.outputs.pre-fingerprint-hash }}
+  cache-hit:
+    description: 'Whether the fingerprint was found in cache'
+    value: ${{ steps.check-cache.outputs.cache-hit }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Calculate Pre-Fingerprint Hash
+      id: pre-hash
+      shell: bash
+      working-directory: ${{ inputs.project-root }}
+      run: |
+        FILES="${{ inputs.pre-hash-files }}"
+        HASH=$(echo "$FILES" | tr ',' '\n' | xargs -I{} cat {} 2>/dev/null | sha256sum | cut -c1-16)
+        echo "pre-fingerprint-hash=$HASH" >> $GITHUB_OUTPUT
+
+    - name: Check KV Cache for Fingerprint
+      id: kv-lookup
+      if: inputs.kv-url != '' && inputs.kv-token != ''
+      shell: bash
+      env:
+        KV_URL: ${{ inputs.kv-url }}
+        KV_TOKEN: ${{ inputs.kv-token }}
+      run: |
+        KEY="${{ inputs.platform }}-${{ inputs.cache-prefix }}-pre-${{ steps.pre-hash.outputs.pre-fingerprint-hash }}"
+        RESULT=$(curl -s "$KV_URL/get/$KEY" -H "Authorization: Bearer $KV_TOKEN" | jq -r '.result')
+        if [ "$RESULT" != "null" ]; then
+          echo "fingerprint=$RESULT" >> $GITHUB_OUTPUT
+          echo "found=true" >> $GITHUB_OUTPUT
+          # Extend TTL
+          curl -s -X POST "$KV_URL/EXPIRE/$KEY/2592000" -H "Authorization: Bearer $KV_TOKEN" > /dev/null
+        else
+          echo "found=false" >> $GITHUB_OUTPUT
+        fi
+
+    - name: Generate Fingerprint
+      id: fingerprint
+      if: steps.kv-lookup.outputs.found != 'true'
+      shell: bash
+      working-directory: ${{ inputs.project-root }}
+      run: |
+        FINGERPRINT=$(npx @expo/fingerprint fingerprint:generate --platform ${{ inputs.platform }} | jq -r '.hash')
+        echo "fingerprint=$FINGERPRINT" >> $GITHUB_OUTPUT
+        echo "cache-key=${{ inputs.cache-prefix }}-${{ inputs.platform }}-$FINGERPRINT" >> $GITHUB_OUTPUT
+
+    - name: Use Cached Fingerprint
+      if: steps.kv-lookup.outputs.found == 'true'
+      shell: bash
+      run: |
+        echo "fingerprint=${{ steps.kv-lookup.outputs.fingerprint }}" >> $GITHUB_OUTPUT
+        echo "cache-key=${{ inputs.cache-prefix }}-${{ inputs.platform }}-${{ steps.kv-lookup.outputs.fingerprint }}" >> $GITHUB_OUTPUT
+
+    - name: Save Fingerprint to KV
+      if: inputs.kv-url != '' && inputs.kv-token != '' && steps.kv-lookup.outputs.found != 'true'
+      shell: bash
+      env:
+        KV_URL: ${{ inputs.kv-url }}
+        KV_TOKEN: ${{ inputs.kv-token }}
+      run: |
+        KEY="${{ inputs.platform }}-${{ inputs.cache-prefix }}-pre-${{ steps.pre-hash.outputs.pre-fingerprint-hash }}"
+        curl -s -X POST "$KV_URL/SETEX/$KEY/2592000/${{ steps.fingerprint.outputs.fingerprint }}" -H "Authorization: Bearer $KV_TOKEN" > /dev/null

package/actions/fingerprint/action.yml

@@ -0,0 +1,110 @@
+name: 'Native CI - Fingerprint'
+description: 'Generate Expo fingerprint with 2-level caching (pre-hash + full fingerprint)'
+author: 'Tamagui'
+
+inputs:
+  platform:
+    description: 'Platform (ios or android)'
+    required: true
+  project-root:
+    description: 'Path to the Expo project root'
+    default: '.'
+  cache-prefix:
+    description: 'Prefix for cache keys'
+    default: 'native-build'
+  kv-url:
+    description: 'Redis KV REST API URL for fingerprint caching (optional)'
+    required: false
+  kv-token:
+    description: 'Redis KV REST API token (optional)'
+    required: false
+  pre-hash-files:
+    description: 'Comma-separated list of files for pre-fingerprint hash'
+    default: 'yarn.lock,package-lock.json,app.json'
+
+outputs:
+  fingerprint:
+    description: 'The generated fingerprint hash'
+    value: ${{ steps.result.outputs.fingerprint }}
+  cache-key:
+    description: 'The cache key to use for this build'
+    value: ${{ steps.result.outputs.cache-key }}
+  pre-fingerprint-hash:
+    description: 'Quick pre-fingerprint hash'
+    value: ${{ steps.pre-hash.outputs.hash }}
+  cache-hit:
+    description: 'Whether fingerprint was found in KV cache'
+    value: ${{ steps.kv-lookup.outputs.found || 'false' }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Calculate Pre-Fingerprint Hash
+      id: pre-hash
+      shell: bash
+      working-directory: ${{ inputs.project-root }}
+      run: |
+        FILES="${{ inputs.pre-hash-files }}"
+        HASH=$(echo "$FILES" | tr ',' '\n' | while read f; do
+          [ -f "$f" ] && cat "$f"
+        done | sha256sum | cut -c1-16)
+        echo "hash=$HASH" >> $GITHUB_OUTPUT
+        echo "Pre-fingerprint hash: $HASH"
+
+    - name: Check KV Cache for Fingerprint
+      id: kv-lookup
+      if: inputs.kv-url != '' && inputs.kv-token != ''
+      shell: bash
+      env:
+        KV_URL: ${{ inputs.kv-url }}
+        KV_TOKEN: ${{ inputs.kv-token }}
+      run: |
+        KEY="${{ inputs.platform }}-${{ inputs.cache-prefix }}-pre-${{ steps.pre-hash.outputs.hash }}"
+        echo "Looking up KV key: $KEY"
+        RESULT=$(curl -s "$KV_URL/get/$KEY" -H "Authorization: Bearer $KV_TOKEN" | jq -r '.result // empty')
+        if [ -n "$RESULT" ] && [ "$RESULT" != "null" ]; then
+          echo "Found cached fingerprint: $RESULT"
+          echo "fingerprint=$RESULT" >> $GITHUB_OUTPUT
+          echo "found=true" >> $GITHUB_OUTPUT
+          # Extend TTL to 30 days
+          curl -s -X POST "$KV_URL/EXPIRE/$KEY/2592000" -H "Authorization: Bearer $KV_TOKEN" > /dev/null
+        else
+          echo "No cached fingerprint found"
+          echo "found=false" >> $GITHUB_OUTPUT
+        fi
+
+    - name: Generate Fingerprint
+      id: generate
+      if: steps.kv-lookup.outputs.found != 'true'
+      shell: bash
+      working-directory: ${{ inputs.project-root }}
+      run: |
+        echo "Generating ${{ inputs.platform }} fingerprint..."
+        FINGERPRINT=$(npx @expo/fingerprint fingerprint:generate --platform ${{ inputs.platform }} | jq -r '.hash')
+        echo "Generated fingerprint: $FINGERPRINT"
+        echo "fingerprint=$FINGERPRINT" >> $GITHUB_OUTPUT
+
+    - name: Save Fingerprint to KV
+      if: inputs.kv-url != '' && inputs.kv-token != '' && steps.kv-lookup.outputs.found != 'true' && steps.generate.outputs.fingerprint != ''
+      shell: bash
+      env:
+        KV_URL: ${{ inputs.kv-url }}
+        KV_TOKEN: ${{ inputs.kv-token }}
+      run: |
+        KEY="${{ inputs.platform }}-${{ inputs.cache-prefix }}-pre-${{ steps.pre-hash.outputs.hash }}"
+        echo "Saving fingerprint to KV: $KEY"
+        curl -s -X POST "$KV_URL/SETEX/$KEY/2592000/${{ steps.generate.outputs.fingerprint }}" -H "Authorization: Bearer $KV_TOKEN" > /dev/null
+
+    - name: Set Result
+      id: result
+      shell: bash
+      run: |
+        if [ "${{ steps.kv-lookup.outputs.found }}" = "true" ]; then
+          FP="${{ steps.kv-lookup.outputs.fingerprint }}"
+        else
+          FP="${{ steps.generate.outputs.fingerprint }}"
+        fi
+        echo "fingerprint=$FP" >> $GITHUB_OUTPUT
+        echo "cache-key=${{ inputs.cache-prefix }}-${{ inputs.platform }}-$FP" >> $GITHUB_OUTPUT
+        echo "Final fingerprint: $FP"
+        echo "Cache key: ${{ inputs.cache-prefix }}-${{ inputs.platform }}-$FP"

package/actions/test-detox-android/action.yml

@@ -0,0 +1,70 @@
+name: 'Native CI - Android Detox Tests'
+description: 'Run Detox E2E tests on Android emulator'
+author: 'Tamagui'
+
+inputs:
+  project-root:
+    description: 'Path to the project root'
+    default: '.'
+  working-directory:
+    description: 'Working directory for running tests'
+    default: '.'
+  config:
+    description: 'Detox configuration name'
+    default: 'android.emu.ci.debug'
+  record-logs:
+    description: 'Record logs mode: none, failing, all'
+    default: 'all'
+  retries:
+    description: 'Number of test retries (0 = fail fast)'
+    default: '0'
+  api-level:
+    description: 'Android API level'
+    default: '30'
+  emulator-options:
+    description: 'Emulator options'
+    default: '-no-snapshot -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none -camera-front none'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Setup Bun
+      uses: oven-sh/setup-bun@v2
+      with:
+        bun-version: latest
+
+    - name: Setup Java
+      uses: actions/setup-java@v4
+      with:
+        distribution: 'temurin'
+        java-version: '17'
+
+    - name: Install Detox CLI
+      shell: bash
+      run: npm install -g detox-cli
+
+    - name: Start Android Emulator and Run Tests
+      uses: reactivecircus/android-emulator-runner@v2
+      with:
+        api-level: ${{ inputs.api-level }}
+        target: google_apis
+        arch: x86_64
+        profile: pixel_6
+        avd-name: test
+        ram-size: 4096M
+        heap-size: 1024M
+        force-avd-creation: false
+        emulator-boot-timeout: 900
+        disable-animations: true
+        emulator-options: ${{ inputs.emulator-options }}
+        working-directory: ${{ inputs.working-directory }}
+        pre-emulator-launch-script: |
+          adb start-server
+        script: |
+          SCRIPT_PATH=$(node -e "console.log(require.resolve('@tamagui/native-ci/src/run-detox-android.ts'))")
+          bun run "$SCRIPT_PATH" \
+            --headless \
+            --project-root "$PWD" \
+            --config "${{ inputs.config }}" \
+            --record-logs "${{ inputs.record-logs }}" \
+            --retries "${{ inputs.retries }}"

package/actions/test-detox-ios/action.yml

@@ -0,0 +1,66 @@
+name: 'Native CI - iOS Detox Tests'
+description: 'Run Detox E2E tests on iOS simulator'
+author: 'Tamagui'
+
+inputs:
+  project-root:
+    description: 'Path to the project root'
+    default: '.'
+  working-directory:
+    description: 'Working directory for running tests'
+    default: '.'
+  config:
+    description: 'Detox configuration name'
+    default: 'ios.sim.debug'
+  record-logs:
+    description: 'Record logs mode: none, failing, all'
+    default: 'all'
+  retries:
+    description: 'Number of test retries (0 = fail fast)'
+    default: '0'
+  simulator:
+    description: 'iOS simulator device type'
+    default: 'iPhone 15'
+  app-path:
+    description: 'Path to the built app (optional, uses DETOX_IOS_APP_PATH env var)'
+    required: false
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Setup Bun
+      uses: oven-sh/setup-bun@v2
+      with:
+        bun-version: latest
+
+    - name: Install Detox CLI
+      shell: bash
+      run: npm install -g detox-cli
+
+    - name: Install applesimutils
+      shell: bash
+      run: |
+        brew tap wix/brew
+        brew install applesimutils
+
+    - name: Boot iOS Simulator
+      shell: bash
+      run: |
+        DEVICE_ID=$(xcrun simctl list devices available -j | jq -r '.devices | to_entries | .[] | select(.key | contains("iOS")) | .value[] | select(.name == "${{ inputs.simulator }}") | .udid' | head -1)
+        if [ -n "$DEVICE_ID" ]; then
+          echo "Booting simulator: ${{ inputs.simulator }} ($DEVICE_ID)"
+          xcrun simctl boot "$DEVICE_ID" || true
+        fi
+
+    - name: Run Detox Tests
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      env:
+        DETOX_IOS_APP_PATH: ${{ inputs.app-path }}
+      run: |
+        SCRIPT_PATH=$(node -e "console.log(require.resolve('@tamagui/native-ci/src/run-detox-ios.ts'))")
+        bun run "$SCRIPT_PATH" \
+          --project-root "$PWD" \
+          --config "${{ inputs.config }}" \
+          --record-logs "${{ inputs.record-logs }}" \
+          --retries "${{ inputs.retries }}"