@1aboveio/app-dev-skills 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/README.md +30 -2
  2. package/package.json +34 -4
  3. package/skills/airflow/LICENSE +3 -0
  4. package/skills/airflow/SKILL.md +199 -0
  5. package/skills/airflow/release-check.mjs +93 -0
  6. package/skills/android-foundation/LICENSE +3 -0
  7. package/skills/android-foundation/SKILL.md +192 -0
  8. package/skills/android-foundation/assets/android-ci-job.yml +217 -0
  9. package/skills/android-foundation/references/ci.md +87 -0
  10. package/skills/android-foundation/references/gotchas.md +221 -0
  11. package/skills/android-foundation/references/setup.md +164 -0
  12. package/skills/android-foundation/release-check.mjs +93 -0
  13. package/skills/android-foundation/scripts/device-run.sh +176 -0
  14. package/skills/android-foundation/scripts/device-run.test.mjs +172 -0
  15. package/skills/app-debug/LICENSE +3 -0
  16. package/skills/app-debug/SKILL.md +110 -0
  17. package/skills/app-debug/references/common-errors.md +128 -0
  18. package/skills/app-debug/release-check.mjs +93 -0
  19. package/skills/better-auth/LICENSE +3 -0
  20. package/skills/better-auth/SKILL.md +598 -0
  21. package/skills/better-auth/references/feishu-api.md +270 -0
  22. package/skills/better-auth/release-check.mjs +93 -0
  23. package/skills/data-catalog/LICENSE +3 -0
  24. package/skills/data-catalog/SKILL.md +207 -0
  25. package/skills/data-catalog/agents/openai.yaml +3 -0
  26. package/skills/data-catalog/references/data-catalog-conventions.md +76 -0
  27. package/skills/data-catalog/references/field-definitions.md +123 -0
  28. package/skills/data-catalog/references/format.md +130 -0
  29. package/skills/data-catalog/release-check.mjs +93 -0
  30. package/skills/data-catalog/scripts/data-catalog.test.mjs +36 -0
  31. package/skills/data-catalog/scripts/data_catalog.py +1435 -0
  32. package/skills/data-catalog/scripts/persist-conventions-core.mjs +117 -0
  33. package/skills/data-catalog/scripts/persist-conventions.mjs +17 -0
  34. package/skills/data-catalog/scripts/test_data_catalog.py +603 -0
  35. package/skills/ios-foundation/LICENSE +3 -0
  36. package/skills/ios-foundation/SKILL.md +184 -0
  37. package/skills/ios-foundation/references/setup.md +243 -0
  38. package/skills/ios-foundation/release-check.mjs +93 -0
  39. package/skills/monorepo/LICENSE +3 -0
  40. package/skills/monorepo/SKILL.md +462 -0
  41. package/skills/monorepo/release-check.mjs +93 -0
  42. package/skills/nextjs-fullstack/LICENSE +3 -0
  43. package/skills/nextjs-fullstack/SKILL.md +211 -0
  44. package/skills/nextjs-fullstack/conventions.md +318 -0
  45. package/skills/nextjs-fullstack/frontend-conventions.md +61 -0
  46. package/skills/nextjs-fullstack/nextjs16.md +287 -0
  47. package/skills/nextjs-fullstack/release-check.mjs +93 -0
  48. package/skills/nextjs-fullstack/server-actions.md +409 -0
  49. package/skills/prisma-setup/LICENSE +3 -0
  50. package/skills/prisma-setup/SKILL.md +181 -0
  51. package/skills/prisma-setup/nextjs.md +258 -0
  52. package/skills/prisma-setup/release-check.mjs +93 -0
  53. package/skills/prisma-setup/turborepo.md +301 -0
  54. package/skills/pyspark/LICENSE +3 -0
  55. package/skills/pyspark/SKILL.md +127 -0
  56. package/skills/pyspark/assets/templates/etl.py +748 -0
  57. package/skills/pyspark/assets/templates/utils/__init__.py +1 -0
  58. package/skills/pyspark/assets/templates/utils/hudi_metadata.py +14 -0
  59. package/skills/pyspark/references/diagnosis-and-profiling.md +169 -0
  60. package/skills/pyspark/references/etl-contract.md +129 -0
  61. package/skills/pyspark/references/production-validation.md +131 -0
  62. package/skills/pyspark/references/reconciliation.md +38 -0
  63. package/skills/pyspark/references/transformation-design.md +190 -0
  64. package/skills/pyspark/references/velocity-feature-calculation.md +193 -0
  65. package/skills/pyspark/release-check.mjs +93 -0
  66. package/skills/pyspark/scripts/spark_eventlog_summary.py +223 -0
  67. package/skills/python-backend/LICENSE +3 -0
  68. package/skills/python-backend/SKILL.md +325 -0
  69. package/skills/python-backend/assets/uv-install.sh +48 -0
  70. package/skills/python-backend/references/uv-installs.md +83 -0
  71. package/skills/python-backend/release-check.mjs +93 -0
  72. package/skills/shadcn/LICENSE +3 -0
  73. package/skills/shadcn/SKILL.md +120 -0
  74. package/skills/shadcn/assets/shadcn-small.png +0 -0
  75. package/skills/shadcn/assets/shadcn.png +0 -0
  76. package/skills/shadcn/cli.md +411 -0
  77. package/skills/shadcn/customization.md +224 -0
  78. package/skills/shadcn/mcp.md +101 -0
  79. package/skills/shadcn/release-check.mjs +93 -0
  80. package/skills/shadcn/rules/base-vs-radix.md +323 -0
  81. package/skills/shadcn/rules/component-selection.md +67 -0
  82. package/skills/shadcn/rules/composition.md +195 -0
  83. package/skills/shadcn/rules/data-table.md +201 -0
  84. package/skills/shadcn/rules/forms.md +255 -0
  85. package/skills/shadcn/rules/icons.md +103 -0
  86. package/skills/shadcn/rules/styling.md +167 -0
  87. package/skills/zod-v4/LICENSE +3 -0
  88. package/skills/zod-v4/SKILL.md +286 -0
  89. package/skills/zod-v4/release-check.mjs +93 -0
@@ -0,0 +1,217 @@
1
+ # Android job for the repo's ci.yml. Merge these pieces into the existing workflow:
2
+ # 1. the `android` filter into the `changes` job (and its output),
3
+ # 2. the `android` job,
4
+ # 3. the `android` lines into `gate`.
5
+ # Replace every <placeholder>. See references/ci.md.
6
+
7
+ jobs:
8
+ changes:
9
+ # ...existing changes job...
10
+ outputs:
11
+ android: ${{ steps.filter.outputs.android }}
12
+ steps:
13
+ - uses: actions/checkout@v4
14
+ - id: filter
15
+ uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
16
+ with:
17
+ filters: |
18
+ shared: &shared
19
+ - 'package.json'
20
+ - 'pnpm-lock.yaml'
21
+ - '.github/workflows/ci.yml'
22
+ android:
23
+ - *shared
24
+ - '<android-workspace>/**'
25
+ - '<backend-paths-the-journey-drives>/**'
26
+ - '<device-harness-and-journey-scripts>'
27
+
28
+ android:
29
+ name: Android foundation (APK + device journey)
30
+ needs: changes
31
+ # Fork guard: fork code must never reach the self-hosted Android runners.
32
+ if: >-
33
+ needs.changes.outputs.android == 'true' &&
34
+ (github.event_name != 'pull_request' ||
35
+ github.event.pull_request.head.repo.full_name == github.repository)
36
+ runs-on: [<self-hosted-android-runner-labels>]
37
+ timeout-minutes: 60
38
+ services:
39
+ postgres:
40
+ image: postgres:<major>
41
+ env:
42
+ POSTGRES_USER: postgres
43
+ POSTGRES_PASSWORD: postgres
44
+ POSTGRES_DB: <ci-db-name>
45
+ ports: ['5432/tcp']
46
+ options: >-
47
+ --health-cmd "pg_isready -U postgres"
48
+ --health-interval 10s --health-timeout 5s --health-retries 5
49
+ steps:
50
+ - uses: actions/checkout@v4
51
+ with:
52
+ persist-credentials: false
53
+ - uses: actions/setup-node@v4
54
+ with:
55
+ node-version: '<node-major>'
56
+ - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
57
+ with:
58
+ version: '<pnpm-version>'
59
+ run_install: false
60
+ - uses: actions/setup-java@v4
61
+ with:
62
+ distribution: temurin
63
+ java-version: '17'
64
+
65
+ - name: Preflight Android runner
66
+ run: |
67
+ echo "runner=$RUNNER_NAME nproc=$(nproc)"
68
+ test -c /dev/kvm || { echo "runner has no /dev/kvm device" >&2; exit 1; }
69
+ test -r /dev/kvm
70
+ test -w /dev/kvm
71
+ node -e 'const fs = require("node:fs"); fs.accessSync("/dev/kvm", fs.constants.R_OK | fs.constants.W_OK)'
72
+ for component in platform-tools/adb platforms/android-<api> build-tools/<build-tools> \
73
+ ndk/<ndk> cmake/<cmake> emulator system-images/android-<emulator-api>/<target>/x86_64; do
74
+ test -e "$ANDROID_SDK_ROOT/$component" || { echo "runner image lacks $component" >&2; exit 1; }
75
+ done
76
+
77
+ - name: Allocate per-slot Android ports
78
+ run: |
79
+ if [[ "$RUNNER_NAME" =~ -([0-9]+)$ ]]; then slot=$((10#${BASH_REMATCH[1]})); else
80
+ echo "cannot derive a slot from $RUNNER_NAME" >&2; exit 2; fi
81
+ (( slot >= 1 && slot <= 15 )) || { echo "slot out of range: $slot" >&2; exit 2; }
82
+ emulator_port=$((5554 + 2 * slot))
83
+ {
84
+ echo "ANDROID_ADB_SERVER_PORT=$((5037 + slot))"
85
+ echo "ANDROID_EMULATOR_PORT=$emulator_port"
86
+ echo "ANDROID_EMULATOR_SERIAL=emulator-$emulator_port"
87
+ echo "ANDROID_BACKEND_PORT=$((<backend-base-port> + 10 * slot))"
88
+ echo "ANDROID_METRO_PORT=$((<metro-base-port> + 10 * slot))"
89
+ } | tee -a "$GITHUB_ENV"
90
+
91
+ # Optional: only on runners with a Gradle distribution mirror.
92
+ - name: Route the Gradle wrapper through the mirror
93
+ run: |
94
+ mirror="${GRADLE_DISTRIBUTIONS_MIRROR:?runner must set GRADLE_DISTRIBUTIONS_MIRROR}"
95
+ props=<android-project>/gradle/wrapper/gradle-wrapper.properties
96
+ node -e '
97
+ const fs = require("node:fs")
98
+ const [file, raw] = process.argv.slice(1)
99
+ const mirror = raw.replace(/\/?$/, "/")
100
+ const text = fs.readFileSync(file, "utf8")
101
+ const next = text.replace(
102
+ /^distributionUrl=https\\:\/\/services\.gradle\.org\/distributions\//m,
103
+ "distributionUrl=" + mirror.replace(/:/g, "\\:"),
104
+ )
105
+ if (next === text) throw new Error("distributionUrl was not rewritten")
106
+ fs.writeFileSync(file, next)
107
+ ' "$props" "$mirror"
108
+ grep '^distributionUrl=' "$props"
109
+
110
+ - name: Install dependencies
111
+ timeout-minutes: 12
112
+ run: pnpm install --frozen-lockfile
113
+
114
+ - name: Native tests and typecheck
115
+ run: |
116
+ pnpm --filter <android-workspace-package> test
117
+ pnpm --filter <android-workspace-package> typecheck
118
+
119
+ - name: Relax durability on the disposable Postgres
120
+ env:
121
+ PG_CONTAINER: ${{ job.services.postgres.id }}
122
+ run: |
123
+ docker exec "$PG_CONTAINER" psql -U postgres -v ON_ERROR_STOP=1 \
124
+ -c "ALTER SYSTEM SET synchronous_commit = off" -c "ALTER SYSTEM SET fsync = off" \
125
+ -c "SELECT pg_reload_conf()"
126
+
127
+ - name: Native auth against real PostgreSQL
128
+ env:
129
+ DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:${{ job.services.postgres.ports['5432'] }}/<ci-db-name>
130
+ run: <native-auth-integration-test-command>
131
+
132
+ - name: Bundle Android JavaScript
133
+ env:
134
+ EXPO_PUBLIC_API_URL: https://app.invalid
135
+ run: pnpm --filter <android-workspace-package> exec expo export --platform android
136
+
137
+ - name: Build x86_64 debug APK
138
+ timeout-minutes: 30
139
+ env:
140
+ EXPO_PUBLIC_API_URL: https://app.invalid
141
+ ANDROID_USER_HOME: ${{ github.workspace }}/.cache/android-user
142
+ run: |
143
+ mkdir -p "$ANDROID_USER_HOME"
144
+ cpus="$(nproc)"
145
+ if [ -r /sys/fs/cgroup/cpu.max ]; then
146
+ read -r quota period < /sys/fs/cgroup/cpu.max
147
+ if [ "$quota" != max ]; then cpus=$(( (quota + period - 1) / period )); fi
148
+ fi
149
+ echo "gradle max-workers=$cpus (nproc=$(nproc))"
150
+ <android-project>/gradlew --project-dir <android-project> :app:assembleDebug --no-daemon \
151
+ -PreactNativeArchitectures=x86_64 --max-workers="$cpus"
152
+
153
+ - uses: actions/setup-python@v5
154
+ with:
155
+ python-version: '3.12'
156
+
157
+ - name: Test device orchestration
158
+ run: <orchestration-unit-test-commands>
159
+
160
+ - name: Install UI automation
161
+ run: |
162
+ # Create the venv where the journey wrapper looks for it.
163
+ python3 -m venv <venv-dir-the-wrapper-reads>
164
+ <venv-dir-the-wrapper-reads>/bin/python3 -m pip install uiautomator2==<harness-pinned-version>
165
+
166
+ - name: Start the slot's ADB server
167
+ run: |
168
+ adb="$ANDROID_SDK_ROOT/platform-tools/adb"
169
+ "$adb" -P "$ANDROID_ADB_SERVER_PORT" start-server
170
+ "$adb" -P "$ANDROID_ADB_SERVER_PORT" version | head -1
171
+
172
+ - name: Device journey
173
+ uses: reactivecircus/android-emulator-runner@a421e43855164a8197daf9d8d40fe71c6996bb0d # v2.38.0
174
+ env:
175
+ SHARD_ADMIN_URL: postgresql://postgres:postgres@127.0.0.1:${{ job.services.postgres.ports['5432'] }}/postgres
176
+ SHARD_DB_NAME: <ci-db-name>
177
+ with:
178
+ api-level: <emulator-api>
179
+ arch: x86_64
180
+ target: <target>
181
+ disable-animations: true
182
+ enable-hw-keyboard: true
183
+ emulator-port: ${{ env.ANDROID_EMULATOR_PORT }}
184
+ cores: 4
185
+ # At 2 GB (the usual AVD value) the guest kernel's vsock allocations fail and adb drops
186
+ # mid-journey, taking every adb reverse with it (references/gotchas.md).
187
+ ram-size: 4096M
188
+ disable-linux-hw-accel: false
189
+ script: bash <path/to/foundation-journey-wrapper.sh>
190
+
191
+ # The sanitized capture (screenshots, UI dumps, backend and Metro logs; no auth codes,
192
+ # cookies or payment payloads), so a failure is diagnosed from the run, not the runner.
193
+ # <device-capture-dir> must be the directory the journey wrapper actually writes.
194
+ - uses: actions/upload-artifact@v4
195
+ if: always()
196
+ with:
197
+ name: android-device-capture
198
+ path: <device-capture-dir>/
199
+ if-no-files-found: warn
200
+ retention-days: 7
201
+ - uses: actions/upload-artifact@v4
202
+ with:
203
+ name: android-debug-apk
204
+ path: <android-project>/app/build/outputs/apk/debug/*.apk
205
+ if-no-files-found: error
206
+ retention-days: 7
207
+
208
+ gate:
209
+ # ...existing gate job; add:
210
+ needs: [changes, android] # plus the existing jobs
211
+ steps:
212
+ - env:
213
+ ANDROID: ${{ needs.changes.outputs.android }}
214
+ ANDROID_RESULT: ${{ needs.android.result }}
215
+ run: |
216
+ # inside the existing check script:
217
+ check android "$ANDROID_RESULT" "$ANDROID"
@@ -0,0 +1,87 @@
1
+ # Android CI
2
+
3
+ Add an Android job to the repo's one `ci.yml`: build the debug APK and run the foundation
4
+ journey on an emulator. Copy [assets/android-ci-job.yml](../assets/android-ci-job.yml) and
5
+ fill every `<placeholder>`. Follow the `github-actions` skill for the `changes` job, the
6
+ `gate` job, runner labels, pinning and hardening; this file covers only what is Android-
7
+ specific.
8
+
9
+ ## Wire it in
10
+
11
+ 1. Add an `android` filter to the `changes` job: the app workspace, the native project,
12
+ the backend code the journey drives, the device harness and journey scripts, the
13
+ lockfile, and `ci.yml`. Leave docs out.
14
+ 2. Add the `android` job with `needs: changes` and
15
+ `if: needs.changes.outputs.android == 'true'` plus the fork guard: fork pull requests
16
+ never run on the self-hosted Android runners.
17
+ 3. Add `android` to `gate`'s `needs:` and a `check android "$ANDROID_RESULT" "$ANDROID"`
18
+ line. Require only `gate`.
19
+ 4. Before merging, open one Android-only PR and one docs-only PR. Confirm the job runs on
20
+ the first, is skipped on the second, and `gate` passes on both.
21
+
22
+ ## Runner
23
+
24
+ - Run on a self-hosted Linux x64 runner class that has `/dev/kvm` mapped in and the SDK
25
+ preinstalled: platform-tools, the platform, build-tools, NDK, CMake, emulator and the
26
+ x86_64 system image the job boots. Never download SDK components in the job.
27
+ - Preflight before any slow step: assert `/dev/kvm` is a character device, readable and
28
+ writable, and check it with Node's `fs.accessSync(R_OK | W_OK)`. The emulator action uses
29
+ that check; a host where `test -r/-w` passes but `accessSync` fails boots the emulator in
30
+ software for 10+ minutes. Assert each SDK component path exists.
31
+ - Never let the emulator fall back to software: set `disable-linux-hw-accel: false`.
32
+ - Derive per-slot ports from the runner's slot number when slots share a host network:
33
+ ADB server, emulator console (even port, 5554–5584), backend and Metro. Export them to
34
+ `$GITHUB_ENV` and start the ADB server on its own port.
35
+ - Size Gradle from the cgroup CPU quota (`/sys/fs/cgroup/cpu.max`), not `nproc`. `nproc`
36
+ reports every host core and thrashes the native build.
37
+ - Route the Gradle wrapper distribution and Maven repositories through the runner's
38
+ dependency proxy when it has one. Fail when the proxy variable is missing; never fall
39
+ back to direct downloads.
40
+
41
+ ## Build
42
+
43
+ - Build `x86_64` only (`-PreactNativeArchitectures=x86_64`), with `--no-daemon`. Report
44
+ this APK as emulator evidence only. The all-ABI build stays a local or release step.
45
+ - Bundle the JavaScript with `expo export --platform android` before the native build so
46
+ bundling errors fail fast.
47
+ - Give the job `timeout-minutes: 60`, the install step its own short timeout, and the
48
+ APK build `timeout-minutes: 30`.
49
+
50
+ ## Database and journey
51
+
52
+ - Run PostgreSQL as a job service on a random host port, with a health check. Turn off
53
+ `fsync` and `synchronous_commit` on it: the database is disposable.
54
+ - Run the native auth/integration tests against that service before the device journey.
55
+ - Unit-test the device orchestration scripts (journey wrapper, slot allocator, code
56
+ lookup) before booting the emulator.
57
+ - Pin the UI automation package in a venv at the path the journey wrapper reads; use the
58
+ Python version the harness supports (3.12 on CI).
59
+ - Boot the emulator with the SHA-pinned `reactivecircus/android-emulator-runner`, or the
60
+ runner's preinstalled emulator under an owned process group. Use the API level, target
61
+ and ABI of the preinstalled image, `disable-animations: true`, `ram-size: 4096M` (or
62
+ `-memory 4096` when launching the emulator directly), and the slot's console port. Run
63
+ the journey wrapper as its `script`. At 2 GB, the usual `avdmanager` value, adb drops
64
+ mid-journey
65
+ ([gotchas](gotchas.md#the-adb-transport-drops-mid-journey)).
66
+
67
+ ## Evidence
68
+
69
+ - Upload the sanitized device capture (screenshots, UI dumps, backend and Metro logs) with
70
+ `if: always()` and a 7-day retention, from the directory the journey wrapper actually
71
+ writes. Sanitize before upload: no authentication codes, session cookies, customer data or
72
+ payment payloads. Diagnose a CI failure from this artifact; never require runner access.
73
+ - Print enough to name the cause from the log alone: the message of the wait that timed
74
+ out (not only its exception class), the screen size and orientation, the labels on screen
75
+ and whether it scrolls, and the runner's free disk at preflight. A repo that uploads no
76
+ capture needs these in the log.
77
+ - Upload the APK with `if-no-files-found: error`.
78
+ - Treat one green run as one run. Fix flaky device failures at their cause instead of
79
+ rerunning, and do not change product code for them. An adb drop after boot means guest
80
+ RAM ([gotchas](gotchas.md#the-adb-transport-drops-mid-journey)). A `RemoteDisconnected`
81
+ with the adb transport still up means the uiautomator2 server was relaunched
82
+ ([gotchas](gotchas.md#remotedisconnected-right-after-a-new-process-connects)).
83
+
84
+ ## Traps
85
+
86
+ Known CI symptoms and their fixes are in [gotchas.md](gotchas.md#ci-runners), along with
87
+ the emulator and adb traps that also hit CI.
@@ -0,0 +1,221 @@
1
+ # Android foundation gotchas
2
+
3
+ Known traps, each as signal, cause and fix. Match the signal before you dig. If none
4
+ matches, [confirm the suspected cause](#confirm-a-suspected-cause) before changing code.
5
+
6
+ ## Emulator and AVD
7
+
8
+ ### A hand-written AVD misses the screen
9
+
10
+ - **Signal:** taps or swipes land nowhere, or a control below the fold never scrolls into
11
+ view, though the same journey passes elsewhere. The device reports `Physical size:
12
+ 320x480`.
13
+ - **Cause:** `config.ini` was written from scratch without the hardware keys. Without
14
+ `hw.lcd.*` the emulator defaults to 320x480, so a journey's display override and fixed
15
+ coordinates no longer match.
16
+ - **Fix:** copy the hardware keys from an `avdmanager`-made AVD on the same runner:
17
+ `hw.lcd.width`, `hw.lcd.height`, `hw.lcd.density` and `disk.dataPartition.size`. Set
18
+ `hw.ramSize=4096` instead of copying its value; see
19
+ [adb transport drops](#the-adb-transport-drops-mid-journey).
20
+
21
+ ### `avdmanager` cannot see an installed image
22
+
23
+ - **Signal:** `avdmanager create avd --package …` fails with `Package path is not valid` and
24
+ lists only the images under its own SDK.
25
+ - **Cause:** `avdmanager` derives its SDK root from its own install location. It ignores
26
+ `ANDROID_SDK_ROOT` and `ANDROID_HOME`, so an image under another root (a slot-local
27
+ overlay, for example) is invisible to it.
28
+ - **Fix:** write the AVD's `.ini` and `config.ini` yourself, with `image.sysdir.1` relative
29
+ to the SDK root the emulator uses. Then apply
30
+ [the hardware keys](#a-hand-written-avd-misses-the-screen). An image that ships a `data/`
31
+ tree instead of `userdata.img` is fine: the emulator seeds userdata from it on first
32
+ boot.
33
+
34
+ ### The emulator boots in software
35
+
36
+ - **Signal:** boot takes 10+ minutes.
37
+ - **Cause:** KVM is unusable to the emulator. A host where `test -r/-w /dev/kvm` passes but
38
+ Node's `fs.accessSync(R_OK | W_OK)` fails still falls back to software.
39
+ - **Fix:** check KVM with `accessSync` in the preflight, and set
40
+ `disable-linux-hw-accel: false`.
41
+
42
+ ### Two jobs fight over `emulator-5554` or Metro's port
43
+
44
+ - **Cause:** runner slots share the host network, and the ports are not slot-derived.
45
+ - **Fix:** derive the ADB server, emulator console, backend and Metro ports from the slot
46
+ number ([ci.md](ci.md#runner)).
47
+
48
+ ## Metro and adb
49
+
50
+ ### Lost `adb reverse`
51
+
52
+ - **Signal:** earlier steps passed, then a screen's first Metro asset fails: `Unable to
53
+ download asset from url: http://127.0.0.1:8081/assets/…`, often an icon font. With
54
+ `expo-font`/`expo-asset`, every mounted icon reports a rejection (a burst of a dozen or
55
+ more). API calls on the same screen still succeed.
56
+ - **Cause:** an adb transport reconnect keeps the emulator in `device` state but deletes
57
+ every `adb reverse` mapping; `adb reverse --list` comes back empty. UI automation
58
+ recovers, Metro becomes unreachable, and a debug build loads assets from Metro. A
59
+ backend reached at `10.0.2.2` does not use adb, so it keeps working. The usual trigger is
60
+ an [adb transport drop](#the-adb-transport-drops-mid-journey); fix that first.
61
+ - **Fix:** re-prove the bridge before every step whose screen is the first to load a Metro
62
+ asset: re-apply the reverse and check, from inside the device, that Metro answers. Doing
63
+ it only at app launch is not enough. Release builds embed their assets, so this is a
64
+ harness failure, not a product failure.
65
+
66
+ ### The adb transport drops mid-journey
67
+
68
+ - **Signal:** the host adb server's transport trace (`ADB_TRACE=transport`) shows
69
+ `remote local: terminated (data)` then `emulator-NNNN: connection terminated: read
70
+ failed` after boot, while the emulator stays up. About 0.5 s later the device is back
71
+ in `device` state, but [every `adb reverse` is gone](#lost-adb-reverse). Steps fail at
72
+ random, often during bursts of guest-to-host data (`dumpsys`, hierarchy dumps,
73
+ logcat). A drop during boot, before `sys.boot_completed`, is normal: adbd restarts once.
74
+ - **Cause:** guest memory, seen on x86_64 API 35/36 images with `android15-6.6` kernels
75
+ 6.6.50 and 6.6.66. GKI `android15-6.6-2025-09` and later cap these pieces at about
76
+ 28 KiB, which should avoid it, but no emulator image with such a kernel was tested. The guest kernel sends adb
77
+ data over virtio-vsock in pieces of up to 64 KiB, each needing one contiguous 128 KiB
78
+ allocation. At 2 GB (the usual AVD value), a busy journey fragments guest memory until that
79
+ allocation fails. adbd's `write()` gets `ENOMEM` (`error 12: Out of memory`), adbd
80
+ treats it as fatal, logs `connection terminated: write failed` and closes the transport
81
+ itself, so the host side is not the cause. In the traced runs only the job's own adb
82
+ server was connected to the emulator.
83
+ - **Fix:** give the guest 4 GB: `hw.ramSize=4096` in the AVD's `config.ini`, replacing any
84
+ existing value. At 4 GB the guest kept 127+ free blocks of 128 KiB or larger, with no
85
+ allocation stalls and no drops; at 2 GB it fell to 1 such block, with hundreds of
86
+ stalls. Keep re-proving `adb reverse` before Metro-dependent steps as a safety net.
87
+ - **Confirm:** with `adb root`, set `persist.adb.trace_mask=rwx,transport`, restart
88
+ adbd, and look for `writex: fd=N error 12` in `/data/adb/adb-*`. Guest tracepoints
89
+ `vsock/virtio_transport_{alloc,recv}_pkt` show adbd's own `SHUTDOWN` going out first;
90
+ `/proc/buddyinfo` shows order-5 and larger blocks (128 KiB+ contiguous) near zero.
91
+ - **Dead ends:**
92
+ - `-feature -VirtioVsockPipe`: adb stays `offline` forever on API 35.
93
+ - adb over TCP through the emulator console's `redir`: works only on boots where guest
94
+ `eth0` gets `10.0.2.15`.
95
+ - A newer emulator or platform-tools: no relevant fix in their release notes.
96
+
97
+ ### `RemoteDisconnected` right after a new process connects
98
+
99
+ - **Signal:** the first uiautomator2 RPC in a newly started Python process raises
100
+ `RemoteDisconnected`. The adb transport stays registered: the trace shows `tcp:9008`
101
+ refused (`OPEN` then immediate `CLSE`), then a single stream `CLSE` with no response,
102
+ and no `connection terminated`.
103
+ - **Cause:** uiautomator2 keeps its on-device server inside an adb shell session owned by
104
+ the Python process that started it. When that process exits the server dies, and the
105
+ next process relaunches it. An RPC sent while it starts gets cut off, especially with
106
+ uiautomator2's own restart and retry bypassed.
107
+ - **Fix:** drive the whole journey from one process, or wait until the server answers
108
+ `/ping` before the first RPC. This is not an [adb drop](#the-adb-transport-drops-mid-journey).
109
+
110
+ ## Journey harness
111
+
112
+ ### A navigation check passes on the previous screen
113
+
114
+ - **Signal:** intermittently, a wait right after the next tap times out even though the
115
+ app works. The screen at failure is the destination of the previous navigation, often
116
+ scrolled by the harness's own swipes, and the app records no navigation for that tap.
117
+ - **Cause:** the check that should confirm arrival also matches text on the origin
118
+ screen, so it passes before the new screen lands. The next tap then hits the screen
119
+ mid-transition and is sometimes lost.
120
+ - **Fix:** after a navigation, wait for something only the destination shows, such as its
121
+ own record ID next to its label, never a value the origin also displays. To prove it,
122
+ make the unit tests' fake UI (the scripted hierarchy the harness tests read) keep the
123
+ origin on screen for a few reads and drop taps in that window; the test must fail
124
+ without the fix.
125
+ - **Example:** after `Original Payment Transaction` on a refund, the check waited for the
126
+ original's Provider Reference, which the refund also shows as `Parent Provider
127
+ Reference`. `Back to History` landed about 75 ms into the transition, and about one
128
+ cold run in three failed with `Timed out: return to History list`. Waiting for the
129
+ original's `Payment Transaction ID` fixed it.
130
+
131
+ ### A wait never scrolls to its label
132
+
133
+ - **Signal:** a wait for a label times out only on a short or landscape screen (812x360,
134
+ for example) and passes on the phone. The screen at failure shows the content above the
135
+ label.
136
+ - **Cause:** UiAutomator lists only nodes that are on screen, and the wait checks the
137
+ hierarchy without scrolling. On a short screen the label sits below the fold.
138
+ - **First:** check `adb shell wm size`. A 320x480 screen is
139
+ [a hand-written AVD](#a-hand-written-avd-misses-the-screen), not this.
140
+ - **Fix:** scroll toward the label before or while waiting. To prove it, make the harness
141
+ test's fake UI keep the label off screen until a scroll; the test must fail without the
142
+ fix.
143
+
144
+ ### A harness test fails on the runner's real state
145
+
146
+ - **Signal:** a harness unit test fails before the APK builds with a host-resource message
147
+ (`Retained native owner requires 2 GiB reserve`), and passes on a developer machine.
148
+ - **Cause:** the code under test reads real host state (free disk, SDK paths) that the
149
+ fixture does not fake, and the runner's state differs from the developer's.
150
+ - **Fix:** fake that state in the fixture. Then check the runner itself: a slot below the
151
+ threshold fails the real journey too.
152
+
153
+ ### A new journey fails in the commit that adds it
154
+
155
+ - **Signal:** a journey added or changed in this commit fails waiting for a screen (`Select
156
+ your Store`) that the app no longer shows; the screen at failure shows the current app.
157
+ - **Cause:** often the journey was written against the old screen. A product regression
158
+ that only this journey exercises shows the same signal.
159
+ - **Fix:** read the screen at failure and the commit's product diff before choosing. If the
160
+ app shows the intended screen, update the journey; never change product code to match
161
+ a journey.
162
+
163
+ ## CI runners
164
+
165
+ ### The Android check is cancelled on the exact head
166
+
167
+ - **Signal:** the queue reads the cancelled check as failing.
168
+ - **Cause:** GitHub can deliver one push as two identical `pull_request` events.
169
+ - **Fix:** if Android has its own workflow, key `concurrency.group` on `github.run_id`
170
+ with `cancel-in-progress: false`.
171
+
172
+ ### The native build takes ~20 minutes on an 8-CPU slot
173
+
174
+ - **Cause:** Gradle saw every host core.
175
+ - **Fix:** size `--max-workers` from the cgroup quota (`/sys/fs/cgroup/cpu.max`), not
176
+ `nproc`.
177
+
178
+ ### Postgres setup hooks time out
179
+
180
+ - **Cause:** durability is on.
181
+ - **Fix:** disable `fsync` and `synchronous_commit` on the disposable service.
182
+
183
+ ### The job never starts
184
+
185
+ - **Cause:** no online runner carries the label set.
186
+ - **Fix:** see the `github-actions` runner guide.
187
+
188
+ ### `setup-java` or `setup-python` takes 10+ minutes on a new runner slot
189
+
190
+ - **Cause:** the slot's tool cache is empty, so the JDK or Python downloads from the
191
+ internet.
192
+ - **Fix:** seed the runner's `_tool/` directory from a sibling slot with the same image.
193
+
194
+ ### A Backend call fails only in CI: the runner lacks a tool the app launches
195
+
196
+ - **Signal:** the journey passes locally but in CI a step that reaches the Backend
197
+ (receipt email, PDF share, export) gets a 5xx, and the backend log names a missing
198
+ program, e.g. `Receipt PDF generation failed: Browser was not found at the configured
199
+ executablePath`.
200
+ - **Cause:** the journey's Backend runs on the runner itself, and the self-hosted runner
201
+ image has no browser (or other app-launched tool). A developer machine does, so it only
202
+ fails in CI.
203
+ - **Fix:** don't install it on the runner, and don't treat it as a product bug. Point the
204
+ app's browser variable (`CHROMIUM_PATH`) at a wrapper that runs the pinned Playwright
205
+ image's browser: `github-actions` → `references/runners.md`, "A host process that needs
206
+ a browser binary". Prove it in CI; Docker Desktop on macOS cannot reach the wrapper's
207
+ host-network port.
208
+
209
+ ### A failed run's Metro log is gone
210
+
211
+ - **Cause:** the journey writes raw service logs under the checkout (`test-results/`), and
212
+ the next job's checkout removes them.
213
+ - **Fix:** for a diagnosis, copy the Metro log and a full `adb logcat` to persistent
214
+ storage outside the checkout. Keep them off uploaded artifacts: they are unsanitized.
215
+
216
+ ## Confirm a suspected cause
217
+
218
+ Inject the suspected cause on purpose, for example `adb reverse --remove tcp:8081` right
219
+ before the failing step, and check that it reproduces the exact failure signature: the same
220
+ step, error and error count. Then show that the fix passes the same injection. A cause that
221
+ does not reproduce its signature is a guess, and a fix for a guess is not proof.