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

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 (77) hide show
  1. package/README.md +29 -2
  2. package/package.json +33 -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/ios-foundation/LICENSE +3 -0
  24. package/skills/ios-foundation/SKILL.md +184 -0
  25. package/skills/ios-foundation/references/setup.md +243 -0
  26. package/skills/ios-foundation/release-check.mjs +93 -0
  27. package/skills/monorepo/LICENSE +3 -0
  28. package/skills/monorepo/SKILL.md +462 -0
  29. package/skills/monorepo/release-check.mjs +93 -0
  30. package/skills/nextjs-fullstack/LICENSE +3 -0
  31. package/skills/nextjs-fullstack/SKILL.md +211 -0
  32. package/skills/nextjs-fullstack/conventions.md +318 -0
  33. package/skills/nextjs-fullstack/frontend-conventions.md +61 -0
  34. package/skills/nextjs-fullstack/nextjs16.md +287 -0
  35. package/skills/nextjs-fullstack/release-check.mjs +93 -0
  36. package/skills/nextjs-fullstack/server-actions.md +409 -0
  37. package/skills/prisma-setup/LICENSE +3 -0
  38. package/skills/prisma-setup/SKILL.md +181 -0
  39. package/skills/prisma-setup/nextjs.md +258 -0
  40. package/skills/prisma-setup/release-check.mjs +93 -0
  41. package/skills/prisma-setup/turborepo.md +301 -0
  42. package/skills/pyspark/LICENSE +3 -0
  43. package/skills/pyspark/SKILL.md +127 -0
  44. package/skills/pyspark/assets/templates/etl.py +748 -0
  45. package/skills/pyspark/assets/templates/utils/__init__.py +1 -0
  46. package/skills/pyspark/assets/templates/utils/hudi_metadata.py +14 -0
  47. package/skills/pyspark/references/diagnosis-and-profiling.md +169 -0
  48. package/skills/pyspark/references/etl-contract.md +129 -0
  49. package/skills/pyspark/references/production-validation.md +131 -0
  50. package/skills/pyspark/references/reconciliation.md +38 -0
  51. package/skills/pyspark/references/transformation-design.md +190 -0
  52. package/skills/pyspark/references/velocity-feature-calculation.md +193 -0
  53. package/skills/pyspark/release-check.mjs +93 -0
  54. package/skills/pyspark/scripts/spark_eventlog_summary.py +223 -0
  55. package/skills/python-backend/LICENSE +3 -0
  56. package/skills/python-backend/SKILL.md +325 -0
  57. package/skills/python-backend/assets/uv-install.sh +48 -0
  58. package/skills/python-backend/references/uv-installs.md +83 -0
  59. package/skills/python-backend/release-check.mjs +93 -0
  60. package/skills/shadcn/LICENSE +3 -0
  61. package/skills/shadcn/SKILL.md +120 -0
  62. package/skills/shadcn/assets/shadcn-small.png +0 -0
  63. package/skills/shadcn/assets/shadcn.png +0 -0
  64. package/skills/shadcn/cli.md +411 -0
  65. package/skills/shadcn/customization.md +224 -0
  66. package/skills/shadcn/mcp.md +101 -0
  67. package/skills/shadcn/release-check.mjs +93 -0
  68. package/skills/shadcn/rules/base-vs-radix.md +323 -0
  69. package/skills/shadcn/rules/component-selection.md +67 -0
  70. package/skills/shadcn/rules/composition.md +195 -0
  71. package/skills/shadcn/rules/data-table.md +201 -0
  72. package/skills/shadcn/rules/forms.md +255 -0
  73. package/skills/shadcn/rules/icons.md +103 -0
  74. package/skills/shadcn/rules/styling.md +167 -0
  75. package/skills/zod-v4/LICENSE +3 -0
  76. package/skills/zod-v4/SKILL.md +286 -0
  77. package/skills/zod-v4/release-check.mjs +93 -0
package/README.md CHANGED
@@ -1,3 +1,30 @@
1
- # Temporary Holding Version
1
+ # @1aboveio/app-dev-skills
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Next.js, React Native, auth, Prisma, shadcn, Python backends, Airflow and PySpark.
4
+
5
+ ## Install
6
+
7
+ Pi:
8
+
9
+ ```sh
10
+ pi install npm:@1aboveio/app-dev-skills
11
+ ```
12
+
13
+ ## Skills
14
+
15
+ - `airflow`
16
+ - `android-foundation`
17
+ - `app-debug`
18
+ - `better-auth`
19
+ - `ios-foundation`
20
+ - `monorepo`
21
+ - `nextjs-fullstack`
22
+ - `prisma-setup`
23
+ - `pyspark`
24
+ - `python-backend`
25
+ - `shadcn`
26
+ - `zod-v4`
27
+
28
+ Not included (external sources, install with the Skills CLI): impeccable.
29
+
30
+ Generated from [1aboveio/ai](https://github.com/1aboveio/ai) `skills/distribution/packages/`. Do not edit.
package/package.json CHANGED
@@ -1,6 +1,35 @@
1
1
  {
2
2
  "name": "@1aboveio/app-dev-skills",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Next.js, React Native, auth, Prisma, shadcn, Python backends, Airflow and PySpark.",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/1aboveio/ai.git",
9
+ "directory": "skills/distribution/packages"
10
+ },
11
+ "keywords": [
12
+ "pi-package",
13
+ "agent-skills",
14
+ "skills"
15
+ ],
16
+ "files": [
17
+ "skills",
18
+ "README.md"
19
+ ],
20
+ "publishConfig": {
21
+ "registry": "https://registry.npmjs.org/",
22
+ "access": "public"
23
+ },
24
+ "pi": {
25
+ "skills": [
26
+ "./skills"
27
+ ]
28
+ },
29
+ "skillsPackage": {
30
+ "id": "app-dev",
31
+ "core": "@1aboveio/core-skills",
32
+ "coreSkills": [],
33
+ "digest": "e656c7cd36fb0ab894e8d83e96a745eab36d78402348e0e2dcb591a12e4270a2"
34
+ }
35
+ }
@@ -0,0 +1,3 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 1AboveIO
@@ -0,0 +1,199 @@
1
+ ---
2
+ name: airflow
3
+ description: Airflow DAG architecture and conventions. Use when designing, writing, reviewing, testing, or debugging Airflow DAGs and tasks, including TaskGroups, data intervals, timezone-aware date parameters, CLI validation, environment-based scheduling, and pytest integrity tests.
4
+ user-invocable: true
5
+ release-version: 0.36.0
6
+ ---
7
+ **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
8
+ # Airflow DAG Development Patterns
9
+
10
+ ## 1. Organize Data Pipelines with TaskGroups
11
+
12
+ Use `TaskGroup` to make meaningful pipeline stages visible in the Airflow graph. For data warehouse pipelines, group tasks by warehouse layer such as `stg`, `ods`, `dwd`, `dws`, and `ads`. For other pipelines, use domain-specific groups such as `features`, `exports`, `quality_checks`, or `notifications`.
13
+
14
+ Keep groups aligned with real ownership or dependency boundaries; do not create a group solely to wrap one trivial task. Express dependencies between groups so the graph communicates the pipeline's high-level flow.
15
+
16
+ ```python
17
+ from airflow.decorators import dag
18
+ from airflow.utils.task_group import TaskGroup
19
+
20
+
21
+ @dag(...)
22
+ def customer_metrics():
23
+ with TaskGroup(group_id="stg") as stg:
24
+ load_stg_customers()
25
+ load_stg_orders()
26
+
27
+ with TaskGroup(group_id="dwd") as dwd:
28
+ build_dwd_customers()
29
+ build_dwd_orders()
30
+
31
+ with TaskGroup(group_id="ads") as ads:
32
+ build_ads_customer_metrics()
33
+
34
+ stg >> dwd >> ads
35
+
36
+
37
+ customer_metrics()
38
+ ```
39
+
40
+ ## 2. Use Timezone-Aware Data Intervals
41
+
42
+ Prefer Airflow's `data_interval_start` and `data_interval_end` as task date-range inputs. They are timezone-aware logical boundaries and behave correctly for scheduled runs, catchup, and daylight-saving transitions. Treat `data_interval_end` as an exclusive boundary.
43
+
44
+ Prepare one shared set of templated date variables for the whole DAG, converting the interval boundaries to the DAG's business timezone. Pass those variables to every task that reads or writes partitioned data. Keep the conversion in Jinja so it happens for each DAG run, not while the scheduler parses the DAG file.
45
+
46
+ ```python
47
+ import pendulum
48
+ from airflow.decorators import dag, task
49
+ from airflow.utils.task_group import TaskGroup
50
+
51
+ LOCAL_TIMEZONE = "Asia/Shanghai"
52
+
53
+ # These values are rendered separately for every DAG run. The end is exclusive.
54
+ DATE_RANGE = {
55
+ "start_date": (
56
+ f"{{{{ data_interval_start.in_timezone('{LOCAL_TIMEZONE}') | ds }}}}"
57
+ ),
58
+ "end_date": (
59
+ f"{{{{ data_interval_end.in_timezone('{LOCAL_TIMEZONE}') | ds }}}}"
60
+ ),
61
+ }
62
+
63
+
64
+ @dag(
65
+ schedule="0 2 * * *",
66
+ start_date=pendulum.datetime(2024, 1, 1, tz=LOCAL_TIMEZONE),
67
+ catchup=True,
68
+ )
69
+ def daily_warehouse():
70
+ @task
71
+ def load_partition(start_date: str, end_date: str) -> None:
72
+ # Read records in the half-open range [start_date, end_date).
73
+ ...
74
+
75
+ with TaskGroup(group_id="stg"):
76
+ load_partition(**DATE_RANGE)
77
+
78
+
79
+ daily_warehouse()
80
+ ```
81
+
82
+ Use timestamps instead of dates when a task needs sub-day precision:
83
+
84
+ ```python
85
+ INTERVAL_RANGE = {
86
+ "interval_start": "{{ data_interval_start.in_timezone('Asia/Shanghai').to_iso8601_string() }}",
87
+ "interval_end": "{{ data_interval_end.in_timezone('Asia/Shanghai').to_iso8601_string() }}",
88
+ }
89
+ ```
90
+
91
+ ## 3. Operations: Wait for DAG Auto-Reload
92
+
93
+ Airflow periodically scans the DAG directory and automatically reloads changed DAG files. The refresh cadence depends on the deployment's scheduler and DAG-processing configuration, and commonly takes a few minutes.
94
+
95
+ After updating a DAG file, do not restart the Airflow services by default. Watch for the DAG to refresh in the Airflow UI or CLI after the configured scan interval. Investigate import errors or deployment synchronization only if the update does not appear after a reasonable interval.
96
+
97
+ ## 4. Quick DAG Validation with Airflow CLI
98
+
99
+ Use these commands for fast feedback during development:
100
+
101
+ ```bash
102
+ # List import errors (fastest check - catches syntax and import issues)
103
+ airflow dags list-import-errors
104
+
105
+ # Full lint check (comprehensive - catches best practice violations)
106
+ airflow dags lint
107
+ ```
108
+
109
+ **When to use:**
110
+ - `list-import-errors`: During active development for quick syntax/import validation
111
+ - `lint`: Before commits to catch style and best practice issues
112
+
113
+ ## 5. Environment-Based Schedule Override
114
+
115
+ Disable schedules in local development to prevent accidental runs:
116
+
117
+ ```python
118
+ import os
119
+ from datetime import datetime
120
+ from airflow import DAG
121
+
122
+ def get_schedule(production_schedule: str) -> str | None:
123
+ """Return None for local dev, actual schedule for deployed environments.
124
+
125
+ Set AIRFLOW_ENV=local in .env for local development.
126
+ Cloud Run deployments set AIRFLOW_ENV=dev|staging|prod.
127
+ """
128
+ env = os.getenv("AIRFLOW_ENV", "local")
129
+ if env == "local":
130
+ return None
131
+ return production_schedule
132
+ ```
133
+
134
+ **Usage in DAG:**
135
+ ```python
136
+ with DAG(
137
+ dag_id="my_dag",
138
+ schedule=get_schedule("0 4 * * *"), # Daily 4 AM in prod, None locally
139
+ start_date=datetime(2024, 1, 1),
140
+ catchup=False,
141
+ ) as dag:
142
+ ...
143
+ ```
144
+
145
+ **Environment setup:**
146
+ - **Local:** Add `AIRFLOW_ENV=local` to `.env`
147
+ - **Cloud Run:** Set via cloudbuild.yaml substitutions (`_AIRFLOW_ENV: dev|staging|prod`)
148
+
149
+ ## 6. Pytest DAG Integrity Tests
150
+
151
+ Standard pytest patterns for validating DAG quality:
152
+
153
+ ```python
154
+ # tests/test_dag_integrity.py
155
+ import pytest
156
+ from airflow.models import DagBag
157
+
158
+ @pytest.fixture(scope="session")
159
+ def dagbag():
160
+ return DagBag(dag_folder="dags/", include_examples=False)
161
+
162
+ def test_no_import_errors(dagbag):
163
+ """Verify all DAGs load without import errors."""
164
+ assert not dagbag.import_errors, f"DAG import errors: {dagbag.import_errors}"
165
+
166
+ def test_dags_have_tags(dagbag):
167
+ """Verify all DAGs have at least one tag for organization."""
168
+ for dag_id, dag in dagbag.dags.items():
169
+ assert dag.tags, f"DAG {dag_id} has no tags"
170
+
171
+ def test_dags_have_owner(dagbag):
172
+ """Verify all DAGs have an owner in default_args."""
173
+ for dag_id, dag in dagbag.dags.items():
174
+ assert dag.default_args.get("owner"), f"DAG {dag_id} missing owner"
175
+
176
+ def test_no_cycles(dagbag):
177
+ """Verify DAGs don't have circular dependencies."""
178
+ for dag_id, dag in dagbag.dags.items():
179
+ # DagBag already validates this, but explicit test for clarity
180
+ assert dag.topo_sort(), f"DAG {dag_id} has cycles"
181
+ ```
182
+
183
+ **Run tests:**
184
+ ```bash
185
+ # Run all DAG tests
186
+ pytest tests/test_dag_integrity.py -v
187
+
188
+ # Run specific test
189
+ pytest tests/test_dag_integrity.py::test_no_import_errors -v
190
+ ```
191
+
192
+ ## Quick Reference
193
+
194
+ | Task | Command |
195
+ |------|---------|
196
+ | Check import errors | `airflow dags list-import-errors` |
197
+ | Lint DAGs | `airflow dags lint` |
198
+ | Run integrity tests | `pytest tests/test_dag_integrity.py -v` |
199
+ | Trigger manual run | `airflow dags trigger <dag_id>` |
@@ -0,0 +1,93 @@
1
+ #!/usr/bin/env node
2
+ import { spawnSync } from 'node:child_process';
3
+ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
4
+ import { homedir } from 'node:os';
5
+ import { dirname, join } from 'node:path';
6
+ import { fileURLToPath } from 'node:url';
7
+
8
+ const DAY_MS = 24 * 60 * 60 * 1000;
9
+ const WEEK_MS = 7 * DAY_MS;
10
+ const here = dirname(fileURLToPath(import.meta.url));
11
+
12
+ function readJson(path, fallback = {}) {
13
+ try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
14
+ }
15
+
16
+ function frontmatterValue(text, key) {
17
+ const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
18
+ const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
19
+ return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
20
+ }
21
+
22
+ function repositoryOf(source) {
23
+ const value = String(source ?? '').trim();
24
+ const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
25
+ return match?.[1] ?? null;
26
+ }
27
+
28
+ function stableVersion(value) {
29
+ const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
30
+ return match ? match.slice(1).map(Number) : null;
31
+ }
32
+
33
+ function newer(left, right) {
34
+ for (let index = 0; index < 3; index += 1) {
35
+ if (left[index] !== right[index]) return left[index] > right[index];
36
+ }
37
+ return false;
38
+ }
39
+
40
+ function writeCache(path, value) {
41
+ try {
42
+ mkdirSync(dirname(path), { recursive: true });
43
+ writeFileSync(path, JSON.stringify(value));
44
+ } catch { /* A read-only cache must not block skill use. */ }
45
+ }
46
+
47
+ function main(now = Date.now()) {
48
+ if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
49
+ const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
50
+ const name = frontmatterValue(skill, 'name');
51
+ const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
52
+ if (!name || !localVersion) return;
53
+
54
+ const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
55
+ const entry = lock.skills?.[name];
56
+ const repository = repositoryOf(entry?.sourceUrl || entry?.source);
57
+ if (!repository) return;
58
+
59
+ const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
60
+ const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
61
+ const all = readJson(cachePath);
62
+ const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
63
+
64
+ if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
65
+ const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
66
+ encoding: 'utf8',
67
+ stdio: ['ignore', 'pipe', 'ignore'],
68
+ timeout: 1500,
69
+ });
70
+ cache.lastCheck = now;
71
+ if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
72
+ else delete cache.latestTag;
73
+ all[repository] = cache;
74
+ writeCache(cachePath, all);
75
+ }
76
+
77
+ const latestVersion = stableVersion(cache.latestTag);
78
+ if (!latestVersion || !newer(latestVersion, localVersion)) return;
79
+ if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
80
+
81
+ cache.notifiedTag = cache.latestTag;
82
+ cache.notifiedAt = now;
83
+ all[repository] = cache;
84
+ writeCache(cachePath, all);
85
+ const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
86
+ process.stdout.write(
87
+ `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
88
+ + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
89
+ + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
90
+ );
91
+ }
92
+
93
+ try { main(); } catch { /* Update checks are advisory and always fail silent. */ }
@@ -0,0 +1,3 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 1AboveIO
@@ -0,0 +1,192 @@
1
+ ---
2
+ name: android-foundation
3
+ description: "Prove an Expo / React Native app on a native Android emulator, and fix it when that proof fails. Use before you fix and re-run or re-dispatch a failed Android CI job (`gh workflow run android.yml`, `gh run rerun`): a re-run is not a debugger, so reproduce the failing journey checkpoint off CI first. Also use when a UiAutomator journey or its Python harness tests fail (a CHECK/FAIL line, a wait that timed out, a control not found, adb offline, a lost Metro bridge, a fixture failing on the runner), to build the debug APK and run the device journey, to set up a fresh Android workspace (SDK/NDK/JDK, Gradle caches, private AVD, disposable PostgreSQL), or to add the emulator job to CI. NOT for workflow YAML, CI speed or runner design (github-actions), browser tests (e2e-test), iOS (ios-foundation), plain Jest component tests, or signing and store release."
4
+ release-version: 0.36.0
5
+ ---
6
+ **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
+ # Android foundation
8
+
9
+ Take a native Expo / React Native Android workspace from a fresh checkout to a passing
10
+ device journey, then record the evidence. Use the repo's existing build scripts, native
11
+ project, device harness and journey wrapper. For CI, add one job to the repo's `ci.yml`
12
+ from the template; do not write a separate release runbook.
13
+
14
+ Pick the mode first:
15
+
16
+ - **Setup proof:** a new workspace or CI job, a toolchain, dependency, native or harness
17
+ change, or a broken build-to-device path. Run every stage and write the
18
+ [evidence record](#evidence-record).
19
+ - **Feature work:** proving a product change on the emulator in a workspace already set
20
+ up. Follow [Feature work](#feature-work) and report only the journey result.
21
+
22
+ ## Routing
23
+
24
+ | Step | Read |
25
+ | --- | --- |
26
+ | Shell snippets for every stage below | [references/setup.md](references/setup.md) |
27
+ | Stages 6–8 in one command | [scripts/device-run.sh](scripts/device-run.sh) |
28
+ | Adding the Android job to CI | [references/ci.md](references/ci.md), template [assets/android-ci-job.yml](assets/android-ci-job.yml) |
29
+ | Proving a product change on the emulator | [Feature work](#feature-work) |
30
+ | A stage failed | [Triage](#triage), then [references/gotchas.md](references/gotchas.md) |
31
+ | Writing up setup proof | [Evidence record](#evidence-record) |
32
+
33
+ ## Rules
34
+
35
+ - Work in a dedicated worktree on a new branch from `origin/main`. Never overwrite or reuse
36
+ another checkout, and never symlink another worktree's `node_modules`.
37
+ - Tool shells keep no variables, functions or traps between calls. Write the environment
38
+ to `.cache/android-env.sh` once and source it at the start of every command. Run stages
39
+ 6–8 as one `scripts/device-run.sh` command, never as separate calls.
40
+ - Keep every cache private to the worktree under `.cache/`: Gradle home, Android user home,
41
+ AVD home, `TMPDIR`, npm, node-gyp and pnpm store. Keep them between runs.
42
+ - Read toolchain versions from the repo: the root `packageManager` and `engines`, the
43
+ native Gradle config, and the CI preflight. The repo is the source of truth, not this skill.
44
+ - Check that every required SDK component (platform, build-tools, NDK, CMake,
45
+ platform-tools, emulator, system image) is already installed. If one is missing, stop and
46
+ provision it separately. Never upgrade or install into a shared SDK during a journey;
47
+ build with `-Pandroid.builder.sdkDownload=false`.
48
+ - Install with `--frozen-lockfile`. Do not routinely run `clean`, reinstall dependencies or
49
+ run `expo prebuild`. The native project is tracked, and prebuild needs a reviewed native
50
+ change.
51
+ - Build every configured ABI for setup proof and release acceptance. An x86_64-only CI
52
+ APK only proves the emulator ABI. For feature work, the emulator ABI is enough unless the
53
+ change touches native code or ABI configuration.
54
+ - A debug APK needs Metro. A successful export or build does not prove the app works on
55
+ a device. Only the device journey does.
56
+
57
+ ## Stages
58
+
59
+ Run them in this order. Stop at the first failure and triage it.
60
+
61
+ 1. **Checkout and environment.** Add the worktree and export the private cache paths,
62
+ `JAVA_HOME` (JDK 17), `ANDROID_HOME` and `ANDROID_SDK_ROOT`. Print the versions of
63
+ node, pnpm, java, python3, adb and the emulator. Assert that each SDK component
64
+ directory exists. Read the journey wrapper and device harness for the names they expect:
65
+ the venv path, the port variables, the database variables and the database-name prefix
66
+ the harness accepts.
67
+ 2. **Install and check.** Run a frozen install, the app's unit tests, typecheck, and
68
+ `expo export --platform android` with a placeholder `EXPO_PUBLIC_API_URL`. Create a
69
+ Python venv for UI automation at the path the journey wrapper reads, and pin the
70
+ `uiautomator2` version the harness expects.
71
+ 3. **Gradle dependencies.** Pick one:
72
+ - Seed: `rsync --ignore-existing` only `caches/modules-2/files-2.1/` from a trusted
73
+ Gradle home, excluding `*.lock`, `*.lck` and `*.tmp`. Never share writable caches,
74
+ metadata, credentials or APKs.
75
+ - Proxy: a private Gradle home does not inherit `~/.gradle/init.d`. Install the proxy's
76
+ init script into `$GRADLE_USER_HOME/init.d/` and export a route for every repository
77
+ the build uses, JitPack included. Ping the proxy first.
78
+ - Neither: build against upstream and expect a long cold build.
79
+ If the opted-in proxy fails, treat it as an error. Never fall back to direct downloads
80
+ and never disable TLS checks. The proxy covers Gradle Maven repositories only. Route the
81
+ Gradle wrapper ZIP and pnpm as the repo's CONTRIBUTING says.
82
+ 4. **Build.** Run the repo's Android build script with `--max-workers=2
83
+ -Dorg.gradle.parallel=false -Pandroid.builder.sdkDownload=false --console=plain
84
+ --info`, keeping the log. For setup proof, hash the APK and list its `lib/<abi>/`
85
+ entries.
86
+ 5. **Owned emulator.** Create a new private AVD in `$ANDROID_AVD_HOME` by copying only
87
+ `config.ini` from an installed AVD. Never copy its user data or snapshots. Check that
88
+ `image.sysdir.1` points to an installed, host-compatible image, and set `target` to
89
+ match it. Writing `config.ini` from scratch needs the hardware keys:
90
+ [gotchas](references/gotchas.md#a-hand-written-avd-misses-the-screen). Give the guest
91
+ 4 GB: replace any `hw.ramSize` with `hw.ramSize=4096` (`device-run.sh` also passes
92
+ `-memory 4096`). At 2 GB, the usual `avdmanager` value, adb drops mid-journey ([gotchas](references/gotchas.md#the-adb-transport-drops-mid-journey)).
93
+ 6. **Register cleanup before starting anything.** `device-run.sh` installs the `EXIT`
94
+ trap and the `INT`/`TERM` handlers first.
95
+ 7. **Start resources.** The script refuses an emulator console port outside 5554–5584
96
+ (adb scans only that range) and any busy port, starts the ADB server, then the emulator
97
+ (PID recorded) and `postgres` (`--cidfile`, random loopback port), and waits for
98
+ `sys.boot_completed=1` and `pg_isready` with a time limit on every command.
99
+ 8. **Journey.** The script hands the harness a database named with its accepted prefix and
100
+ runs the journey wrapper. Expect every scenario's `PASS` marker, plus screenshots, the
101
+ backend log and the Metro log.
102
+
103
+ ## Owned-resource cleanup
104
+
105
+ - Clean up only what this run started: the emulator child PID, the container ID from the
106
+ CID file, and the named database. Signal the PID with `TERM`, wait up to 10 seconds, then
107
+ `KILL`. Then `wait` for it and confirm nothing is left. Count wait status 0 or 143 (ended
108
+ by your `TERM`) as a clean stop; count a needed `KILL` or any other status as a failure.
109
+ - Never use `adb kill-server`, `adb -s <serial> emu kill`, broad `pkill`, or
110
+ `docker system prune`. An ADB serial can be reused by another process; a PID you own
111
+ cannot.
112
+ - Give every startup, readiness and cleanup command a 30-second limit that kills the
113
+ command's whole process group. Treat exit 124 (timeout) as a terminal failure, not as
114
+ "not ready yet".
115
+ - Preserve the stage's original non-zero exit status even when cleanup succeeds. Print
116
+ `original_stage_exit=<n> cleanup_exit=<n>`.
117
+ - After a `SIGKILL` or a host crash, the trap cannot run. Remove only this run's recorded
118
+ PID and container ID by hand, and keep the failure logs.
119
+ - Point the database URL only at the disposable loopback container. Never at development,
120
+ production or another worker's database.
121
+ - Expo may rewrite `android/tsconfig.json` or delete `android/expo-env.d.ts` while it runs.
122
+ Inspect those changes and restore them before you commit.
123
+
124
+ ## Triage
125
+
126
+ Name the earliest stage that failed. In CI, that is the first failed step. If the same
127
+ journey passed on another run of the same commit, suspect the run or the journey before
128
+ the product.
129
+
130
+ | Stage | Typical signal |
131
+ | --- | --- |
132
+ | Prerequisites / install | missing SDK directory, wrong JDK, lockfile drift |
133
+ | Harness unit tests (CI, before the APK) | a harness test fails on host state its fixture should fake (`requires 2 GiB reserve`) |
134
+ | Export / APK | Metro bundling error, Gradle compile or dependency-resolution error |
135
+ | Gradle network | Maven download or TLS-handshake errors on a cold build: fix routing, not code |
136
+ | Emulator boot / ADB | `sys.boot_completed` never reaches 1, device offline, exit 124 |
137
+ | Device to Metro | red box, "unable to load script", missing `adb reverse` mapping |
138
+ | Device to Metro, mid-journey | a screen's first Metro asset fails (`Unable to download asset from url: http://127.0.0.1:8081/assets/…`) while API calls still succeed |
139
+ | Backend / Login | backend log errors, verification code not found in the database |
140
+ | Backend tool, CI only | a Backend-backed step gets a 5xx in CI only; the log names a missing program (`Browser was not found at the configured executablePath`) |
141
+ | adb transport, mid-journey | `connection terminated: read failed` in the adb trace after boot, then lost `adb reverse`: usually guest RAM |
142
+ | UiAutomator server | `RemoteDisconnected` while the adb transport stays up: the on-device server was relaunched |
143
+ | Journey harness | a wait right after a navigation times out while the destination is on screen |
144
+ | Journey harness, short screen | a wait for a label times out only on a short or landscape screen, which shows the content above it |
145
+ | Product assertion | a screen or state mismatch with a screenshot |
146
+
147
+ Then match the signal against [references/gotchas.md](references/gotchas.md). If nothing
148
+ matches, [confirm the suspected cause](references/gotchas.md#confirm-a-suspected-cause)
149
+ before changing code.
150
+
151
+ Preserve the failure evidence. Do not blindly replay steps that send codes, verify sessions
152
+ or charge payments just to get a passing screenshot. One passing run does not prove the
153
+ build is reliable.
154
+
155
+ ## Feature work
156
+
157
+ - Reuse the workspace's caches, venv and AVD configuration. Rerun a setup stage only when
158
+ the change touches what it proves (toolchain, dependencies, native code, harness).
159
+ - Build the emulator ABI and run `scripts/device-run.sh` once per candidate HEAD.
160
+ - After a failed journey, local or a CI dispatch, reproduce the failing checkpoint off CI
161
+ before you run it again: in the harness unit tests with the fake UI scripted to the
162
+ failing screen, or on the owned emulator. Show the fix passes there, then run the journey
163
+ once to confirm. Never send a guessed fix to CI to see whether it passes; a failure you
164
+ cannot reproduce earns one more run, with added diagnostics, then goes in the report as
165
+ unreproduced.
166
+ - Report the source SHA, the journey command, its `PASS` markers or the failing stage,
167
+ and the cleanup exit. Nothing else: no APK hash, version inventory, screenshots, copied
168
+ logs or earlier attempts.
169
+ - Integrated device acceptance (all ABIs, tablet, TalkBack, physical devices, a release
170
+ device campaign) runs at the release or campaign gate the spec or repo assigns it. Do
171
+ not recreate it per feature. Record it once, as pending, in its owning issue, never as
172
+ passed.
173
+
174
+ ## Evidence record
175
+
176
+ For setup proof only. Record:
177
+
178
+ - Source SHA, host OS and architecture, the Expo SDK, and the node, pnpm, JDK, Python and
179
+ emulator versions.
180
+ - System image API, image type and ABI. The AVD name, serial and ports are run
181
+ identifiers, not shared resources.
182
+ - Each stage's exit status and duration.
183
+ - The APK's SHA-256 (`shasum -a 256` or `sha256sum`) and its per-ABI `lib/` entries
184
+ (`unzip -l`), checked on the APK itself rather than inferred from Gradle flags.
185
+ - The journey's `PASS` markers and the cleanup results: database dropped, emulator exited,
186
+ container removed, no listeners left on the backend or Metro ports.
187
+ - Earlier failed or incomplete attempts. A later pass does not erase them.
188
+
189
+ State what the run does not prove: tablet, accessibility (TalkBack), physical devices,
190
+ signing, distribution, and any feature acceptance beyond the journey. Publish only
191
+ sanitized evidence: no authentication codes, session cookies, customer data or raw
192
+ payment payloads.