@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.
- package/README.md +30 -2
- package/package.json +34 -4
- package/skills/airflow/LICENSE +3 -0
- package/skills/airflow/SKILL.md +199 -0
- package/skills/airflow/release-check.mjs +93 -0
- package/skills/android-foundation/LICENSE +3 -0
- package/skills/android-foundation/SKILL.md +192 -0
- package/skills/android-foundation/assets/android-ci-job.yml +217 -0
- package/skills/android-foundation/references/ci.md +87 -0
- package/skills/android-foundation/references/gotchas.md +221 -0
- package/skills/android-foundation/references/setup.md +164 -0
- package/skills/android-foundation/release-check.mjs +93 -0
- package/skills/android-foundation/scripts/device-run.sh +176 -0
- package/skills/android-foundation/scripts/device-run.test.mjs +172 -0
- package/skills/app-debug/LICENSE +3 -0
- package/skills/app-debug/SKILL.md +110 -0
- package/skills/app-debug/references/common-errors.md +128 -0
- package/skills/app-debug/release-check.mjs +93 -0
- package/skills/better-auth/LICENSE +3 -0
- package/skills/better-auth/SKILL.md +598 -0
- package/skills/better-auth/references/feishu-api.md +270 -0
- package/skills/better-auth/release-check.mjs +93 -0
- package/skills/data-catalog/LICENSE +3 -0
- package/skills/data-catalog/SKILL.md +207 -0
- package/skills/data-catalog/agents/openai.yaml +3 -0
- package/skills/data-catalog/references/data-catalog-conventions.md +76 -0
- package/skills/data-catalog/references/field-definitions.md +123 -0
- package/skills/data-catalog/references/format.md +130 -0
- package/skills/data-catalog/release-check.mjs +93 -0
- package/skills/data-catalog/scripts/data-catalog.test.mjs +36 -0
- package/skills/data-catalog/scripts/data_catalog.py +1435 -0
- package/skills/data-catalog/scripts/persist-conventions-core.mjs +117 -0
- package/skills/data-catalog/scripts/persist-conventions.mjs +17 -0
- package/skills/data-catalog/scripts/test_data_catalog.py +603 -0
- package/skills/ios-foundation/LICENSE +3 -0
- package/skills/ios-foundation/SKILL.md +184 -0
- package/skills/ios-foundation/references/setup.md +243 -0
- package/skills/ios-foundation/release-check.mjs +93 -0
- package/skills/monorepo/LICENSE +3 -0
- package/skills/monorepo/SKILL.md +462 -0
- package/skills/monorepo/release-check.mjs +93 -0
- package/skills/nextjs-fullstack/LICENSE +3 -0
- package/skills/nextjs-fullstack/SKILL.md +211 -0
- package/skills/nextjs-fullstack/conventions.md +318 -0
- package/skills/nextjs-fullstack/frontend-conventions.md +61 -0
- package/skills/nextjs-fullstack/nextjs16.md +287 -0
- package/skills/nextjs-fullstack/release-check.mjs +93 -0
- package/skills/nextjs-fullstack/server-actions.md +409 -0
- package/skills/prisma-setup/LICENSE +3 -0
- package/skills/prisma-setup/SKILL.md +181 -0
- package/skills/prisma-setup/nextjs.md +258 -0
- package/skills/prisma-setup/release-check.mjs +93 -0
- package/skills/prisma-setup/turborepo.md +301 -0
- package/skills/pyspark/LICENSE +3 -0
- package/skills/pyspark/SKILL.md +127 -0
- package/skills/pyspark/assets/templates/etl.py +748 -0
- package/skills/pyspark/assets/templates/utils/__init__.py +1 -0
- package/skills/pyspark/assets/templates/utils/hudi_metadata.py +14 -0
- package/skills/pyspark/references/diagnosis-and-profiling.md +169 -0
- package/skills/pyspark/references/etl-contract.md +129 -0
- package/skills/pyspark/references/production-validation.md +131 -0
- package/skills/pyspark/references/reconciliation.md +38 -0
- package/skills/pyspark/references/transformation-design.md +190 -0
- package/skills/pyspark/references/velocity-feature-calculation.md +193 -0
- package/skills/pyspark/release-check.mjs +93 -0
- package/skills/pyspark/scripts/spark_eventlog_summary.py +223 -0
- package/skills/python-backend/LICENSE +3 -0
- package/skills/python-backend/SKILL.md +325 -0
- package/skills/python-backend/assets/uv-install.sh +48 -0
- package/skills/python-backend/references/uv-installs.md +83 -0
- package/skills/python-backend/release-check.mjs +93 -0
- package/skills/shadcn/LICENSE +3 -0
- package/skills/shadcn/SKILL.md +120 -0
- package/skills/shadcn/assets/shadcn-small.png +0 -0
- package/skills/shadcn/assets/shadcn.png +0 -0
- package/skills/shadcn/cli.md +411 -0
- package/skills/shadcn/customization.md +224 -0
- package/skills/shadcn/mcp.md +101 -0
- package/skills/shadcn/release-check.mjs +93 -0
- package/skills/shadcn/rules/base-vs-radix.md +323 -0
- package/skills/shadcn/rules/component-selection.md +67 -0
- package/skills/shadcn/rules/composition.md +195 -0
- package/skills/shadcn/rules/data-table.md +201 -0
- package/skills/shadcn/rules/forms.md +255 -0
- package/skills/shadcn/rules/icons.md +103 -0
- package/skills/shadcn/rules/styling.md +167 -0
- package/skills/zod-v4/LICENSE +3 -0
- package/skills/zod-v4/SKILL.md +286 -0
- package/skills/zod-v4/release-check.mjs +93 -0
package/README.md
CHANGED
|
@@ -1,3 +1,31 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @1aboveio/app-dev-skills
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
- `data-catalog`
|
|
20
|
+
- `ios-foundation`
|
|
21
|
+
- `monorepo`
|
|
22
|
+
- `nextjs-fullstack`
|
|
23
|
+
- `prisma-setup`
|
|
24
|
+
- `pyspark`
|
|
25
|
+
- `python-backend`
|
|
26
|
+
- `shadcn`
|
|
27
|
+
- `zod-v4`
|
|
28
|
+
|
|
29
|
+
Not included (external sources, install with the Skills CLI): impeccable.
|
|
30
|
+
|
|
31
|
+
Generated from [1aboveio/ai](https://github.com/1aboveio/ai) `skills/distribution/packages/`. Do not edit.
|
package/package.json
CHANGED
|
@@ -1,6 +1,36 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@1aboveio/app-dev-skills",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
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
|
+
"homepage": "https://github.com/1aboveio/ai/releases?q=%401aboveio%2Fapp-dev-skills&expanded=true",
|
|
12
|
+
"keywords": [
|
|
13
|
+
"pi-package",
|
|
14
|
+
"agent-skills",
|
|
15
|
+
"skills"
|
|
16
|
+
],
|
|
17
|
+
"files": [
|
|
18
|
+
"skills",
|
|
19
|
+
"README.md"
|
|
20
|
+
],
|
|
21
|
+
"pi": {
|
|
22
|
+
"skills": [
|
|
23
|
+
"./skills"
|
|
24
|
+
]
|
|
25
|
+
},
|
|
26
|
+
"skillsPackage": {
|
|
27
|
+
"id": "app-dev",
|
|
28
|
+
"core": "@1aboveio/core-skills",
|
|
29
|
+
"coreSkills": [],
|
|
30
|
+
"digest": "9d998b32d00efcf94a8fd20756a8acf62064226329e05fc9d23f4e68b5cc548b"
|
|
31
|
+
},
|
|
32
|
+
"publishConfig": {
|
|
33
|
+
"registry": "https://registry.npmjs.org/",
|
|
34
|
+
"access": "public"
|
|
35
|
+
}
|
|
36
|
+
}
|
|
@@ -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.38.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,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.38.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.
|