@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.
- package/README.md +29 -2
- package/package.json +33 -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/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
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
# Feishu OAuth API Reference
|
|
2
|
+
|
|
3
|
+
Load this file when implementing Feishu OAuth or troubleshooting auth issues.
|
|
4
|
+
|
|
5
|
+
## OAuth Flow Endpoints
|
|
6
|
+
|
|
7
|
+
### Authorization
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
GET https://accounts.feishu.cn/open-apis/authen/v1/authorize
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
| Parameter | Required | Description |
|
|
14
|
+
|-----------|----------|-------------|
|
|
15
|
+
| `client_id` | Yes | Feishu App ID (`cli_xxx`) |
|
|
16
|
+
| `redirect_uri` | Yes | Must match registered URI exactly |
|
|
17
|
+
| `response_type` | Yes | Always `code` |
|
|
18
|
+
| `state` | Yes | CSRF token (managed by Better Auth) |
|
|
19
|
+
| `scope` | No | Space-separated scopes |
|
|
20
|
+
|
|
21
|
+
### Token Exchange
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
POST https://open.feishu.cn/open-apis/authen/v2/oauth/token
|
|
25
|
+
Content-Type: application/json
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
**Request body:**
|
|
29
|
+
```json
|
|
30
|
+
{
|
|
31
|
+
"grant_type": "authorization_code",
|
|
32
|
+
"code": "<auth_code>",
|
|
33
|
+
"client_id": "cli_xxx",
|
|
34
|
+
"client_secret": "xxx"
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
**Response:**
|
|
39
|
+
```json
|
|
40
|
+
{
|
|
41
|
+
"access_token": "u-xxxxxxxx",
|
|
42
|
+
"token_type": "Bearer",
|
|
43
|
+
"expires_in": 7200,
|
|
44
|
+
"refresh_token": "ur-xxxxxxxx",
|
|
45
|
+
"refresh_expires_in": 2592000
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
> Note: v2 token endpoint returns flat JSON (no `data` wrapper). v1 used `data` wrapper.
|
|
50
|
+
|
|
51
|
+
### User Info
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
GET https://open.feishu.cn/open-apis/authen/v1/user_info
|
|
55
|
+
Authorization: Bearer <access_token>
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**Response:**
|
|
59
|
+
```json
|
|
60
|
+
{
|
|
61
|
+
"code": 0,
|
|
62
|
+
"msg": "success",
|
|
63
|
+
"data": {
|
|
64
|
+
"open_id": "ou_xxxxxxxxxxxxxxxxxxxxxxxx",
|
|
65
|
+
"union_id": "on_xxxxxxxxxxxxxxxxxxxxxxxx",
|
|
66
|
+
"name": "张三",
|
|
67
|
+
"en_name": "John Zhang",
|
|
68
|
+
"email": "john@company.com",
|
|
69
|
+
"avatar_url": "https://internal-api-lark-file.feishu.cn/...",
|
|
70
|
+
"tenant_key": "xxxxxxxx",
|
|
71
|
+
"employee_no": ""
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
> ⚠️ User data is nested under `data` — must unwrap once. Do NOT double-unwrap.
|
|
77
|
+
|
|
78
|
+
### 1. Authorization (redirect user)
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
GET https://accounts.feishu.cn/open-apis/authen/v1/authorize
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
| Parameter | Required | Description |
|
|
85
|
+
|-----------|----------|-------------|
|
|
86
|
+
| `client_id` | Yes | Feishu App ID (`cli_xxx`) |
|
|
87
|
+
| `redirect_uri` | Yes | Must match registered URI exactly |
|
|
88
|
+
| `response_type` | Yes | Always `code` |
|
|
89
|
+
| `state` | Yes | CSRF token (managed by Better Auth) |
|
|
90
|
+
| `scope` | No | Space-separated scopes |
|
|
91
|
+
|
|
92
|
+
### 2. Token Exchange
|
|
93
|
+
|
|
94
|
+
```
|
|
95
|
+
POST https://open.feishu.cn/open-apis/authen/v2/oauth/token
|
|
96
|
+
Content-Type: application/json
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
**Request body:**
|
|
100
|
+
```json
|
|
101
|
+
{
|
|
102
|
+
"grant_type": "authorization_code",
|
|
103
|
+
"code": "<auth_code>",
|
|
104
|
+
"client_id": "cli_xxx",
|
|
105
|
+
"client_secret": "xxx"
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
**Response:**
|
|
110
|
+
```json
|
|
111
|
+
{
|
|
112
|
+
"access_token": "u-xxxxxxxx",
|
|
113
|
+
"token_type": "Bearer",
|
|
114
|
+
"expires_in": 7200,
|
|
115
|
+
"refresh_token": "ur-xxxxxxxx",
|
|
116
|
+
"refresh_expires_in": 2592000
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
> Note: v2 token endpoint returns flat JSON (no `data` wrapper). v1 used `data` wrapper.
|
|
121
|
+
|
|
122
|
+
### 3. User Info
|
|
123
|
+
|
|
124
|
+
```
|
|
125
|
+
GET https://open.feishu.cn/open-apis/authen/v1/user_info
|
|
126
|
+
Authorization: Bearer <access_token>
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
**Response:**
|
|
130
|
+
```json
|
|
131
|
+
{
|
|
132
|
+
"code": 0,
|
|
133
|
+
"msg": "success",
|
|
134
|
+
"data": {
|
|
135
|
+
"open_id": "ou_xxxxxxxxxxxxxxxxxxxxxxxx",
|
|
136
|
+
"union_id": "on_xxxxxxxxxxxxxxxxxxxxxxxx",
|
|
137
|
+
"name": "张三",
|
|
138
|
+
"en_name": "John Zhang",
|
|
139
|
+
"email": "john@company.com",
|
|
140
|
+
"avatar_url": "https://internal-api-lark-file.feishu.cn/...",
|
|
141
|
+
"tenant_key": "xxxxxxxx",
|
|
142
|
+
"employee_no": ""
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
> ⚠️ User data is nested under `data` — must unwrap once. Do NOT double-unwrap.
|
|
148
|
+
|
|
149
|
+
## User Info Fields
|
|
150
|
+
|
|
151
|
+
| Field | Type | Notes |
|
|
152
|
+
|-------|------|-------|
|
|
153
|
+
| `open_id` | string | Unique per user per app — changes if app changes |
|
|
154
|
+
| `union_id` | string | Unique per user across same developer's apps |
|
|
155
|
+
| `name` | string | Display name (often Chinese) |
|
|
156
|
+
| `en_name` | string | English name (may be empty) |
|
|
157
|
+
| `email` | string | **Empty string if scope not approved** (not null, not omitted) |
|
|
158
|
+
| `avatar_url` | string | Profile picture |
|
|
159
|
+
| `tenant_key` | string | Organization identifier |
|
|
160
|
+
| `employee_no` | string | Employee number (if configured) |
|
|
161
|
+
|
|
162
|
+
## Scopes & Permissions
|
|
163
|
+
|
|
164
|
+
| Scope | Level | Admin Approval |
|
|
165
|
+
|-------|-------|----------------|
|
|
166
|
+
| (none — basic profile) | Basic | Auto |
|
|
167
|
+
| `contact:user.email:readonly` | Advanced (高级权限) | **Required** |
|
|
168
|
+
| `contact:user.phone:readonly` | Advanced | **Required** |
|
|
169
|
+
| `contact:user.employee_id:readonly` | Advanced | **Required** |
|
|
170
|
+
|
|
171
|
+
### Activating Advanced Permissions
|
|
172
|
+
|
|
173
|
+
1. Open app in [Feishu Dev Console](https://open.feishu.cn/app)
|
|
174
|
+
2. Permissions → find the scope → **Enable**
|
|
175
|
+
3. App Release → **Create Version** → **Submit for Review**
|
|
176
|
+
4. Admin approves in Admin Console
|
|
177
|
+
5. Permission status changes to **Active**
|
|
178
|
+
|
|
179
|
+
Until approved: the field returns empty string `""`.
|
|
180
|
+
|
|
181
|
+
## Error Codes
|
|
182
|
+
|
|
183
|
+
| Code | Meaning | Fix |
|
|
184
|
+
|------|---------|-----|
|
|
185
|
+
| 0 | Success | — |
|
|
186
|
+
| 10003 | Invalid app_id | Check credentials |
|
|
187
|
+
| 10012 | App not released | Publish a version |
|
|
188
|
+
| 10014 | Scope not approved | Request admin approval |
|
|
189
|
+
| 20028 | Invalid code / expired | Code was reused or expired (10 min TTL) |
|
|
190
|
+
| 20029 | Redirect URI mismatch | Add exact URL in Feishu app settings |
|
|
191
|
+
|
|
192
|
+
## Prisma Schema
|
|
193
|
+
|
|
194
|
+
Better Auth with genericOAuth requires these models:
|
|
195
|
+
|
|
196
|
+
```prisma
|
|
197
|
+
model User {
|
|
198
|
+
id String @id @default(cuid())
|
|
199
|
+
name String?
|
|
200
|
+
email String? @unique
|
|
201
|
+
emailVerified Boolean @default(false) @map("email_verified")
|
|
202
|
+
image String?
|
|
203
|
+
createdAt DateTime @default(now()) @map("created_at")
|
|
204
|
+
updatedAt DateTime @updatedAt @map("updated_at")
|
|
205
|
+
sessions Session[]
|
|
206
|
+
accounts Account[]
|
|
207
|
+
@@map("users")
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
model Session {
|
|
211
|
+
id String @id @default(cuid())
|
|
212
|
+
expiresAt DateTime @map("expires_at")
|
|
213
|
+
token String @unique @default(cuid())
|
|
214
|
+
ipAddress String? @map("ip_address")
|
|
215
|
+
userAgent String? @map("user_agent")
|
|
216
|
+
userId String @map("user_id")
|
|
217
|
+
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
|
|
218
|
+
createdAt DateTime @default(now()) @map("created_at")
|
|
219
|
+
updatedAt DateTime @updatedAt @map("updated_at")
|
|
220
|
+
@@map("sessions")
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
model Account {
|
|
224
|
+
id String @id @default(cuid())
|
|
225
|
+
userId String @map("user_id")
|
|
226
|
+
accountId String @map("account_id")
|
|
227
|
+
providerId String @map("provider_id")
|
|
228
|
+
accessToken String? @map("access_token")
|
|
229
|
+
refreshToken String? @map("refresh_token")
|
|
230
|
+
idToken String? @map("id_token")
|
|
231
|
+
accessTokenExpiresAt DateTime? @map("access_token_expires_at")
|
|
232
|
+
refreshTokenExpiresAt DateTime? @map("refresh_token_expires_at")
|
|
233
|
+
scope String?
|
|
234
|
+
password String?
|
|
235
|
+
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
|
|
236
|
+
createdAt DateTime @default(now()) @map("created_at")
|
|
237
|
+
updatedAt DateTime @updatedAt @map("updated_at")
|
|
238
|
+
@@unique([providerId, accountId])
|
|
239
|
+
@@map("accounts")
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
// Required by genericOAuth plugin for CSRF state
|
|
243
|
+
model Verification {
|
|
244
|
+
id String @id @default(cuid())
|
|
245
|
+
identifier String
|
|
246
|
+
value String
|
|
247
|
+
expiresAt DateTime @map("expires_at")
|
|
248
|
+
createdAt DateTime @default(now()) @map("created_at")
|
|
249
|
+
updatedAt DateTime @updatedAt @map("updated_at")
|
|
250
|
+
@@map("verification")
|
|
251
|
+
}
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
### Schema Gotchas
|
|
255
|
+
|
|
256
|
+
- **`emailVerified` must be `Boolean`**, not `DateTime` — Better Auth writes `true`/`false`, not timestamps
|
|
257
|
+
- **Account columns need `At` suffix** — `accessTokenExpiresAt` / `refreshTokenExpiresAt` (Prisma adapter uses camelCase field names)
|
|
258
|
+
- **`@map()` for snake_case columns** — Prisma field names are camelCase; use `@map` for DB column names
|
|
259
|
+
- **`verification` table is mandatory** — genericOAuth stores OAuth state here; missing table = 500 on sign-in
|
|
260
|
+
|
|
261
|
+
## International (Lark) vs China (Feishu)
|
|
262
|
+
|
|
263
|
+
| | China | International |
|
|
264
|
+
|---|-------|---------------|
|
|
265
|
+
| Base domain | `feishu.cn` | `larksuite.com` |
|
|
266
|
+
| Auth URL | `accounts.feishu.cn` | `accounts.larksuite.com` |
|
|
267
|
+
| API URL | `open.feishu.cn` | `open.larksuite.com` |
|
|
268
|
+
| Dev Console | `open.feishu.cn/app` | `open.larksuite.com/app` |
|
|
269
|
+
|
|
270
|
+
Use `FEISHU_BASE_URL` env var to switch between them.
|
|
@@ -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,184 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ios-foundation
|
|
3
|
+
description: "Set up and prove an Expo / React Native native iOS workspace from a clean checkout to a manual Login smoke on an owned iOS Simulator: isolated worktree and private caches, Xcode/runtime/CocoaPods preflight, frozen install with `pod install --deployment`, platform-scoped prebuild, an ad-hoc-signed Debug simulator build, a private simulator by exact UDID, Metro on a free port, a disposable PostgreSQL backend with owned cleanup, and the evidence record (setup proof only; feature work reports the smoke result). Use for 'set up iOS', 'build the iOS app', 'run the app on the iOS simulator', 'add iOS to the React Native app', 'prove the iOS build', or when a pod install, xcodebuild, simulator boot, Metro connection or Keychain session fails. NOT for Android (android-foundation), signing, TestFlight or App Store release, or general workflow YAML (github-actions)."
|
|
4
|
+
release-version: 0.36.0
|
|
5
|
+
---
|
|
6
|
+
**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
|
|
7
|
+
# iOS foundation
|
|
8
|
+
|
|
9
|
+
Take a native Expo / React Native iOS workspace from a fresh checkout to a passing manual
|
|
10
|
+
Login smoke on a simulator this run owns, then record the evidence. Use the repo's existing
|
|
11
|
+
build script, native project, device harness and code-reading helper. This is a development
|
|
12
|
+
foundation: not a signed release, not physical-device QA, and not iOS feature parity.
|
|
13
|
+
|
|
14
|
+
Pick the mode first:
|
|
15
|
+
|
|
16
|
+
- **Setup proof:** a new workspace, a toolchain, Pod, native or harness change, or a broken
|
|
17
|
+
build-to-simulator path. Run every stage and write the [evidence record](#evidence-record).
|
|
18
|
+
- **Feature work:** proving a product change on the simulator in a workspace already set
|
|
19
|
+
up. Follow [Feature work](#feature-work) and report only the smoke result.
|
|
20
|
+
|
|
21
|
+
## Routing
|
|
22
|
+
|
|
23
|
+
| Step | Read |
|
|
24
|
+
| --- | --- |
|
|
25
|
+
| Shell snippets for every stage below | [references/setup.md](references/setup.md) |
|
|
26
|
+
| Proving a product change on the simulator | [Feature work](#feature-work) |
|
|
27
|
+
| A stage failed | [Triage](#triage) |
|
|
28
|
+
| Writing up setup proof | [Evidence record](#evidence-record) |
|
|
29
|
+
|
|
30
|
+
## Rules
|
|
31
|
+
|
|
32
|
+
- Work in a dedicated worktree on a new branch from `origin/main`. Never overwrite or reuse
|
|
33
|
+
another checkout, and never symlink another worktree's `node_modules`, `Pods` or
|
|
34
|
+
DerivedData.
|
|
35
|
+
- Tool shells keep no variables, functions or traps between calls. Write the environment
|
|
36
|
+
to `.cache/ios-env.sh` once and source it at the start of every command. Run the
|
|
37
|
+
disposable database and backend as one long-running command so its cleanup trap holds.
|
|
38
|
+
- Keep every cache private to the worktree under `.cache/`: pnpm store and cache, npm,
|
|
39
|
+
`TMPDIR`, CocoaPods cache and home, DerivedData. Keep them between runs. No routine
|
|
40
|
+
`pod update`, `expo prebuild --clean`, reinstall or DerivedData deletion.
|
|
41
|
+
- Read toolchain versions from the repo: the root `packageManager` and `engines`, the
|
|
42
|
+
Podfile and `Podfile.lock`, the iOS deployment target, and CONTRIBUTING. The repo is the
|
|
43
|
+
source of truth, not this skill.
|
|
44
|
+
- Check that full Xcode is selected, its license is accepted, and a matching iOS Simulator
|
|
45
|
+
**runtime** is installed (`xcrun simctl list runtimes`). The SDK alone may give no
|
|
46
|
+
eligible simulator destination. If the runtime is missing, stop: installing it changes
|
|
47
|
+
shared CoreSimulator state and needs the workstation owner's permission. Never let a
|
|
48
|
+
build download it implicitly.
|
|
49
|
+
- Install with `--frozen-lockfile` and `pod install --deployment`, which refuses Podfile or
|
|
50
|
+
lock changes. Plain `pod install` is only for a reviewed native change that writes a new
|
|
51
|
+
`Podfile.lock`. Open the `.xcworkspace`, not the `.xcodeproj`.
|
|
52
|
+
- Native source is tracked. Regenerate only for a reviewed config or dependency change, and
|
|
53
|
+
only with `expo prebuild --platform ios`. Platformless prebuild can rewrite the Android
|
|
54
|
+
project. Review the diff to the app config, package manifest and `ios/`.
|
|
55
|
+
- Keep the Podfile's reviewed download routing (for example React Native's
|
|
56
|
+
`ENTERPRISE_REPOSITORY`) after prebuild. Keep TLS verification on. Report a failed
|
|
57
|
+
download; never silently change dependency versions or global tool config. An Android
|
|
58
|
+
Maven proxy does not route CocoaPods, Git, React Native prebuilt archives or Apple
|
|
59
|
+
downloads.
|
|
60
|
+
- Build Debug for a generic iOS Simulator destination with **ad-hoc signing**
|
|
61
|
+
(`CODE_SIGN_IDENTITY=-`, `CODE_SIGNING_ALLOWED=YES`) and private DerivedData. Never use
|
|
62
|
+
`CODE_SIGNING_ALLOWED=NO`: SecureStore needs a signing context for Keychain, and an
|
|
63
|
+
unsigned build fails at its first authenticated request.
|
|
64
|
+
- A debug app needs Metro. A successful export or `xcodebuild` does not prove Login works.
|
|
65
|
+
Only the simulator smoke does.
|
|
66
|
+
|
|
67
|
+
## Stages
|
|
68
|
+
|
|
69
|
+
Run them in this order. Stop at the first failure and triage it.
|
|
70
|
+
|
|
71
|
+
1. **Checkout and environment.** Add the worktree and export the private cache paths,
|
|
72
|
+
`CP_CACHE_DIR`, `CP_HOME_DIR` and the DerivedData path. Print `xcode-select -p`,
|
|
73
|
+
`xcodebuild -version`, `xcodebuild -showsdks`, `xcrun simctl list runtimes` and
|
|
74
|
+
`devicetypes`, and the node, pnpm, ruby and pod versions. Check that `pod --version`
|
|
75
|
+
matches the `COCOAPODS:` line in `Podfile.lock`. Read the repo's build script
|
|
76
|
+
and device harness for the names they expect: the scheme, the `.app` output path, the
|
|
77
|
+
bundle identifier, the database variables and the database-name prefix the harness
|
|
78
|
+
accepts.
|
|
79
|
+
2. **Install.** Frozen pnpm install, then `pod install --deployment` in the iOS directory.
|
|
80
|
+
3. **Runtime.** Confirm an installed runtime matches the Xcode SDK. If it does not, stop
|
|
81
|
+
and ask the workstation owner. With permission, `xcodebuild -downloadPlatform iOS`
|
|
82
|
+
(multi-GB). If `simctl list runtimes` still does not show it, import the exported image
|
|
83
|
+
with `xcodebuild -importPlatform <absolute .dmg>`. Never remove a shared runtime.
|
|
84
|
+
4. **Check and build.** Run the app's unit tests, typecheck, any build-script tests,
|
|
85
|
+
`expo export --platform ios` with a placeholder `EXPO_PUBLIC_API_URL`, then the repo's iOS
|
|
86
|
+
build script (or the `xcodebuild` command in the reference) with `-jobs 2`. Keep the log and confirm the `.app` exists.
|
|
87
|
+
5. **Owned simulator.** Pick an installed runtime and a compatible device type, then
|
|
88
|
+
`simctl create` a new simulator and keep the exact returned UDID. Boot it, wait with
|
|
89
|
+
`bootstatus -b`, and install the `.app`. Never use `booted` or pick an existing simulator.
|
|
90
|
+
6. **Disposable backend.** In its own background shell, one command registers cleanup,
|
|
91
|
+
starts `postgres` with `--cidfile` on a random loopback port, waits for `pg_isready`,
|
|
92
|
+
seeds through the repo's device harness with a database named by its accepted prefix,
|
|
93
|
+
writes the connection to `.cache/ios-db-env.sh` for the code helper, and runs the
|
|
94
|
+
backend on its reserved port as a child it `wait`s on. Stopping the command stops the
|
|
95
|
+
backend and removes the container.
|
|
96
|
+
7. **Metro and launch.** Use a free port; never stop another worker's Metro to free 8081.
|
|
97
|
+
In its own background shell, start Metro with `--localhost --port <port>` and
|
|
98
|
+
`EXPO_PUBLIC_API_URL=http://127.0.0.1:<backend-port>`. The simulator shares the Mac's
|
|
99
|
+
loopback, so use `127.0.0.1`, not Android's `10.0.2.2`. Set `RCT_jsLocation` on the owned
|
|
100
|
+
UDID only, then launch the bundle identifier. Do not use `expo run:ios` or the repo's
|
|
101
|
+
interactive `dev:ios` command: they may pick a shared simulator.
|
|
102
|
+
8. **Manual Login smoke.** Send the authentication code to the fixture user's email, read
|
|
103
|
+
the code from the disposable database with the repo's helper, and enter it. Then run
|
|
104
|
+
the checks the repo's foundation journey lists (for example store or organization
|
|
105
|
+
switching without leaked context), sign out, terminate and relaunch (it must stay at
|
|
106
|
+
Login), and restart while signed in (the session must revalidate online). Do not submit
|
|
107
|
+
live payments.
|
|
108
|
+
|
|
109
|
+
## Owned-resource cleanup
|
|
110
|
+
|
|
111
|
+
- Clean up only what this run started: the simulator by its exact UDID
|
|
112
|
+
(`simctl shutdown`, then `simctl delete`), the container by the ID in its CID file, and
|
|
113
|
+
the backend and Metro by stopping their own commands.
|
|
114
|
+
- Never use `simctl erase all`, `simctl shutdown all`, `killall Simulator`, broad `pkill`,
|
|
115
|
+
or `docker system prune`.
|
|
116
|
+
- Give every Docker startup, readiness and cleanup command a 30-second limit. Treat exit
|
|
117
|
+
124 (timeout) as a terminal failure, not as "not ready yet". Retry with a new owned
|
|
118
|
+
container, never an application database.
|
|
119
|
+
- Preserve the stage's original non-zero exit status even when cleanup succeeds.
|
|
120
|
+
- After a `SIGKILL` or a host crash, the trap cannot run. Remove only this run's recorded
|
|
121
|
+
container ID and simulator UDID by hand, and keep the failure logs.
|
|
122
|
+
- Point the database URL only at the disposable loopback container. Never at development,
|
|
123
|
+
production or another worker's database.
|
|
124
|
+
- SecureStore uses the iOS Keychain. Entries can survive uninstall and reinstall with the
|
|
125
|
+
same bundle identifier, so uninstall is not sign-out. Use a newly created simulator for
|
|
126
|
+
clean-state proof.
|
|
127
|
+
- Keep private dependency and build caches. Expo may rewrite `tsconfig.json` or
|
|
128
|
+
`expo-env.d.ts` while it runs; inspect and restore those changes before you commit.
|
|
129
|
+
Never commit the machine-specific `.xcode.env.local` or a loopback mirror URL.
|
|
130
|
+
|
|
131
|
+
## Triage
|
|
132
|
+
|
|
133
|
+
Name the earliest stage that failed:
|
|
134
|
+
|
|
135
|
+
| Stage | Typical signal |
|
|
136
|
+
| --- | --- |
|
|
137
|
+
| Prerequisites | Xcode not selected or license not accepted, no runtime matching the SDK |
|
|
138
|
+
| Install | lockfile drift, `pod install --deployment` refuses a Podfile/lock change, Ruby/CocoaPods mismatch |
|
|
139
|
+
| Network | CocoaPods, Git or React Native archive download / TLS errors: fix routing, not code |
|
|
140
|
+
| Export / build | Metro bundling error, `xcodebuild` compile, signing or "no eligible destination" error |
|
|
141
|
+
| Simulator | `simctl create` rejects the runtime/device-type pair, `bootstatus` never completes, install fails |
|
|
142
|
+
| App to Metro | red box, "No script URL provided", wrong `RCT_jsLocation` port |
|
|
143
|
+
| Backend / Login | backend log errors, verification code not found in the database |
|
|
144
|
+
| Keychain / session | session lost or kept unexpectedly: check ad-hoc signing and a fresh simulator |
|
|
145
|
+
| Product assertion | a screen or state mismatch with a screenshot |
|
|
146
|
+
|
|
147
|
+
Preserve the failure evidence. Do not repeatedly Send, Verify or Charge to turn an
|
|
148
|
+
incomplete attempt into a passing screenshot. One passing run does not prove the build is
|
|
149
|
+
reliable.
|
|
150
|
+
|
|
151
|
+
## Feature work
|
|
152
|
+
|
|
153
|
+
- Reuse the workspace's caches, Pods and DerivedData. Rerun a setup stage only when the
|
|
154
|
+
change touches what it proves (toolchain, Pods, native code, harness).
|
|
155
|
+
- Build and run the smoke checks the change affects once per candidate HEAD. Rerun only
|
|
156
|
+
after a correction that affects them, or for a specific unresolved defect or uncertainty
|
|
157
|
+
that could change the delivery decision.
|
|
158
|
+
- Report the source SHA, each smoke check run and its outcome or the failing stage, and the
|
|
159
|
+
cleanup result. Nothing else: no version inventory, screenshots, copied logs or earlier
|
|
160
|
+
attempts.
|
|
161
|
+
- Integrated device acceptance (iPad, VoiceOver, physical devices, signing, a release device
|
|
162
|
+
campaign) runs at the release or campaign gate the spec or repo assigns it. Do not
|
|
163
|
+
recreate it per feature. Record it once, as pending, in its owning issue, never as
|
|
164
|
+
passed.
|
|
165
|
+
|
|
166
|
+
## Evidence record
|
|
167
|
+
|
|
168
|
+
For setup proof only. Record:
|
|
169
|
+
|
|
170
|
+
- Source SHA, host OS and architecture, and the Xcode, iOS SDK, CocoaPods, Ruby, node and
|
|
171
|
+
pnpm versions.
|
|
172
|
+
- The simulator runtime, device type and exact UDID (a run identifier, not a shared
|
|
173
|
+
resource), and the bundle identifier.
|
|
174
|
+
- The exit status of pod install, tests, typecheck, export and the native build.
|
|
175
|
+
- Each manual smoke check and its outcome.
|
|
176
|
+
- The cleanup results: simulator deleted, container removed, backend and Metro stopped.
|
|
177
|
+
- Earlier failed or incomplete attempts. A later pass does not erase them.
|
|
178
|
+
|
|
179
|
+
State what the run does not prove: iPad layout (test an owned iPad simulator as a separate
|
|
180
|
+
run; `supportsTablet` is not proof), accessibility (VoiceOver), physical devices and their
|
|
181
|
+
network/TLS/signing path, auto-lock, payment recovery and browser handoffs, signing,
|
|
182
|
+
TestFlight/App Store, production icons, privacy declarations and export compliance.
|
|
183
|
+
Compilation is not Login evidence. Publish only sanitized evidence: no authentication codes,
|
|
184
|
+
session cookies, verification rows, customer data or raw payment payloads.
|