agentic-mobile-kit 0.5.4 → 0.6.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 (56) hide show
  1. package/README.md +6 -1
  2. package/bin/cli.js +1 -1
  3. package/lib/doctor.js +26 -5
  4. package/lib/init.js +235 -49
  5. package/package.json +4 -2
  6. package/stacks/react-native/expo/.agents/skills/LICENSE-expo +21 -0
  7. package/stacks/react-native/expo/.agents/skills/THIRD_PARTY.md +11 -0
  8. package/stacks/react-native/expo/.agents/skills/expo-module/SKILL.md +151 -0
  9. package/stacks/react-native/expo/.agents/skills/expo-module/agents/openai.yaml +4 -0
  10. package/stacks/react-native/expo/.agents/skills/expo-module/references/config-plugin.md +90 -0
  11. package/stacks/react-native/expo/.agents/skills/expo-module/references/create-expo-module.md +206 -0
  12. package/stacks/react-native/expo/.agents/skills/expo-module/references/lifecycle.md +127 -0
  13. package/stacks/react-native/expo/.agents/skills/expo-module/references/module-config.md +48 -0
  14. package/stacks/react-native/expo/.agents/skills/expo-module/references/native-module.md +286 -0
  15. package/stacks/react-native/expo/.agents/skills/expo-module/references/native-view.md +171 -0
  16. package/stacks/react-native/expo/.agents/skills/expo-router/SKILL.md +240 -0
  17. package/stacks/react-native/expo/.agents/skills/expo-router/agents/openai.yaml +4 -0
  18. package/stacks/react-native/expo/.agents/skills/expo-router/references/form-sheet.md +253 -0
  19. package/stacks/react-native/expo/.agents/skills/expo-router/references/route-structure.md +229 -0
  20. package/stacks/react-native/expo/.agents/skills/expo-router/references/search.md +248 -0
  21. package/stacks/react-native/expo/.agents/skills/expo-router/references/tabs.md +433 -0
  22. package/stacks/react-native/expo/.agents/skills/expo-router/references/toolbar-and-headers.md +284 -0
  23. package/stacks/react-native/expo/.agents/skills/expo-router/references/zoom-transitions.md +158 -0
  24. package/stacks/react-native/expo/.agents/skills/expo-upgrade/SKILL.md +150 -0
  25. package/stacks/react-native/expo/.agents/skills/expo-upgrade/agents/openai.yaml +4 -0
  26. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/expo-av-to-audio.md +132 -0
  27. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/expo-av-to-video.md +160 -0
  28. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/native-tabs.md +124 -0
  29. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/new-architecture.md +79 -0
  30. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/react-19.md +79 -0
  31. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/react-compiler.md +59 -0
  32. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/react-navigation-to-expo-router.md +61 -0
  33. package/stacks/react-native/expo/.rulesync/permissions.jsonc +40 -0
  34. package/stacks/react-native/expo/AGENTS.md +52 -0
  35. package/stacks/react-native/expo/docs/ai/expo.md +35 -0
  36. package/stacks/react-native/expo/docs/ai/known-issues.md +32 -0
  37. package/stacks/react-native/template/.agents/skills/m-release/SKILL.md +5 -4
  38. package/stacks/react-native/template/.githooks/pre-commit +7 -2
  39. package/stacks/react-native/template/.github/workflows/e2e.yml +2 -0
  40. package/stacks/react-native/template/.github/workflows/ios.yml +3 -5
  41. package/stacks/react-native/template/AGENTS.md +4 -4
  42. package/stacks/react-native/template/codemagic.yaml +2 -1
  43. package/stacks/react-native/template/docs/ai/known-issues.md +12 -2
  44. package/stacks/react-native/template/docs/ai/react-native.md +5 -4
  45. package/stacks/react-native/template/scripts/ai/android-flavors.js +41 -0
  46. package/stacks/react-native/template/scripts/ai/case-check.js +35 -0
  47. package/stacks/react-native/template/scripts/ai/install-deps.sh +4 -1
  48. package/stacks/react-native/template/scripts/ai/ios-build.sh +10 -3
  49. package/stacks/react-native/template/scripts/ai/pm-run.sh +12 -0
  50. package/stacks/react-native/template/scripts/ai/pod-install.sh +12 -0
  51. package/stacks/react-native/template/scripts/ai/prebuild.sh +28 -0
  52. package/stacks/react-native/template/scripts/ai/release-build.sh +32 -8
  53. package/stacks/react-native/template/scripts/ai/release-check.js +98 -18
  54. package/stacks/react-native/template/scripts/ai/set-version.sh +19 -1
  55. package/stacks/react-native/template/scripts/ai/verify.sh +69 -16
  56. package/stacks/react-native/template/specs/_templates/flow.yaml +9 -0
@@ -0,0 +1,40 @@
1
+ // Per-tool permission rules, generated by rulesync. A second layer: git hooks and CI are the real backstop,
2
+ // and Phase 0 showed Codex and the Antigravity CLI can still read .env, so keep real secrets out of the repo.
3
+ // Expo apps: ios/ and android/ are generated by `expo prebuild`, so they're never edited by hand.
4
+ {
5
+ "permission": {
6
+ "bash": {
7
+ "rm -rf*": "deny",
8
+ "git reset --hard*": "deny",
9
+ "git push --force*": "deny",
10
+ "git push -f*": "deny",
11
+ "git clean -f*": "deny",
12
+ "git commit --no-verify*": "deny",
13
+ "xcrun simctl erase*": "deny",
14
+ "npm install *": "ask",
15
+ "yarn add*": "ask",
16
+ "pnpm add*": "ask",
17
+ "npx expo install *": "ask",
18
+ "eas *": "ask",
19
+ "npx eas-cli*": "ask"
20
+ },
21
+ "read": {
22
+ ".env": "deny",
23
+ ".env.*": "deny",
24
+ "**/*.keystore": "deny",
25
+ "**/*.jks": "deny",
26
+ "**/*.p8": "deny",
27
+ "**/*.p12": "deny",
28
+ "**/*.mobileprovision": "deny"
29
+ },
30
+ "edit": {
31
+ "ios/**": "deny",
32
+ "android/**": "deny",
33
+ "package.json": "ask",
34
+ "app.json": "ask",
35
+ "app.config.*": "ask",
36
+ "eas.json": "ask",
37
+ ".github/workflows/**": "ask"
38
+ }
39
+ }
40
+ }
@@ -0,0 +1,52 @@
1
+ <!-- KIT:START agentic-mobile-kit {{KIT_VERSION}} ci={{KIT_CI}} stack={{KIT_STACK}} (edit outside these markers; the kit updates what's inside) -->
2
+ # {{APP_NAME}}: instructions for AI agents
3
+
4
+ Read by Claude Code (through CLAUDE.md), Codex, Cursor, OpenCode, Kiro and Antigravity. Keep it short; details live in `docs/ai/`.
5
+
6
+ This project may also use other AI workflow frameworks (for example Superpowers, BMAD or proAgents). They keep working for everything else. When the user starts a task with an `m-` skill (`/m-feature`, `$m-feature`, …), follow that skill's steps for the whole task; where another framework's instructions differ, the `m-` skill wins.
7
+
8
+ ## Project
9
+
10
+ - Expo SDK {{EXPO_SDK}}, React Native {{RN_VERSION}} ({{RN_ARCH}}), React {{REACT_VERSION}}, TypeScript {{TS_VERSION}}, Node {{NODE_VERSION}}. Package manager: {{PM}}.
11
+ - `ios/` and `android/` are generated by `npx expo prebuild` and aren't in git (Continuous Native Generation). The kit's scripts generate them when they need them.
12
+ - What the app does: `docs/ai/product.md`, and requirement by requirement, as it works now: `specs/current/`. Stack and services: `docs/ai/tech.md`. Folders and layers: `docs/ai/structure.md`. Code style: `docs/ai/conventions.md`.
13
+
14
+ ## Commands
15
+
16
+ | Task | Command |
17
+ |---|---|
18
+ | Install dependencies | `sh scripts/ai/install-deps.sh` |
19
+ | Add a library (ask first) | `npx expo install <package>`: the version that matches the SDK |
20
+ | Lint, typecheck, test (each skips what the app doesn't have yet) | `sh scripts/ai/pm-run.sh lint`, `sh scripts/ai/pm-run.sh typecheck`, `sh scripts/ai/pm-run.sh test` |
21
+ | Check dependency versions and the app config | `npx expo install --check`, `npx expo-doctor` |
22
+ | Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/ai/verify.sh all --spec <id>`; another iOS scheme: `--scheme <name>` |
23
+ | Specs: progress, format check, fold a finished feature into the living spec | `node scripts/ai/spec.js status`, `node scripts/ai/spec.js check`, `node scripts/ai/spec.js merge <id>` |
24
+ | Check a release before tagging it (versions, permission texts, debug leftovers) | `node scripts/ai/release-check.js` |
25
+ | Signed release builds (a person runs them: they use the signing keys) | `sh scripts/ai/release-build.sh android`, `sh scripts/ai/release-build.sh ios` |
26
+
27
+ ## Definition of done
28
+
29
+ A task is done only when:
30
+ 1. lint, typecheck and tests pass, and you show the command output from this session;
31
+ 2. UI changes were checked with `sh scripts/ai/verify.sh all --spec <id>` on both iOS and Android, and you looked at the screenshots. On Windows or Linux, that covers Android only: write in `progress.md` and the PR that iOS still needs checking on a Mac, and the PR isn't merged until a teammate with a Mac has done it;
32
+ 3. the change stays inside the task's scope;
33
+ 4. `specs/<id>/progress.md` is updated, when working from a spec.
34
+
35
+ Never say a check passed unless you ran it in this session.
36
+
37
+ ## Rules
38
+
39
+ - Stay inside the task. Ask before touching unrelated files.
40
+ - Ask before adding or upgrading dependencies, and before editing `package.json`, lockfiles, `app.json`, `app.config.*`, `eas.json` or `.github/workflows/`.
41
+ - Never edit `ios/` or `android/`: the next prebuild overwrites them. Native settings go in `app.json` or `app.config.*`, through config plugins; native code goes in an Expo module (`expo-module` skill). Ask before adding a config plugin.
42
+ - Never run `eas build`, `eas submit` or `eas update`: they build, ship or publish with the team's accounts, so a person runs them.
43
+ - Never read, print or commit `.env` files, keystores or signing files. Secrets don't belong in this repo.
44
+ - Never use `git commit --no-verify`, `git push --force`, `git reset --hard` or `rm -rf`.
45
+ - After 2 failed attempts at the same fix, stop and report what you found.
46
+ - Chat is not memory: write decisions into the spec or `docs/ai/decisions.md` straight away.
47
+ - Follow `docs/ai/expo.md`. Before fixing a build error, check `docs/ai/known-issues.md`.
48
+
49
+ ## Skills
50
+
51
+ `expo-router`, `expo-upgrade`, `expo-module` (from Expo), `react-native-best-practices`, `react-navigation` (from Callstack), in `.agents/skills/`.
52
+ <!-- KIT:END agentic-mobile-kit -->
@@ -0,0 +1,35 @@
1
+ # Expo rules
2
+
3
+ Rules for things AI agents commonly get wrong in Expo apps. Each one comes from a documented platform change.
4
+
5
+ ## Expo changes with every SDK
6
+
7
+ - Expo APIs are renamed and moved between SDKs, so don't write them from memory. Use the docs for this app's SDK (the version is in `AGENTS.md`): `https://docs.expo.dev/versions/v<SDK>.0.0/`. `https://docs.expo.dev/llms.txt` indexes all of Expo's docs.
8
+ - Add libraries with `npx expo install <package>`: it picks the version that matches the SDK. `npx expo install --check` lists the ones that don't match.
9
+ - Upgrade the SDK as a whole with the `expo-upgrade` skill, never one Expo package at a time.
10
+ - Without an ESLint config (`eslint.config.js`), the first `npx expo lint` installs ESLint and writes one, changing `package.json`. Ask before running it then.
11
+
12
+ ## Native projects
13
+
14
+ - `ios/` and `android/` are generated by `npx expo prebuild` and aren't in git. Never edit them: the next prebuild overwrites the change.
15
+ - Native settings (permissions and their texts, bundle ID, entitlements) go in `app.json` or `app.config.*`. Libraries with native setup bring a config plugin; add it to `plugins`.
16
+ - Native code of the app's own goes in an Expo module (`expo-module` skill), not into the generated folders.
17
+ - A library with native code needs a new native build: Expo Go doesn't include it. `sh scripts/ai/verify.sh` makes release builds with the current native code.
18
+
19
+ ## Architecture
20
+
21
+ - React Native 0.82 and later run only the New Architecture, and so does Expo. Libraries must support it.
22
+
23
+ ## Screens and layout
24
+
25
+ - Use Expo Router for navigation (`expo-router` skill). Every file in the routes folder is a screen; keep components, hooks and utilities outside it.
26
+ - Use `react-native-safe-area-context` for safe areas. React Native's built-in `SafeAreaView` is deprecated and iOS-only.
27
+ - Android draws edge to edge (Android 15 and later), so handle top and bottom insets on every screen.
28
+ - For apps targeting Android 16 (API 36), `onBackPressed` is no longer called. Handle back with `BackHandler` in JS.
29
+ - Check every UI change on both iOS and Android; behavior differs (keyboard, insets, fonts, permissions).
30
+ - Give every interactive element a `testID` (kebab-case, for example `dark-mode-switch`). End-to-end tools tap by `testID`. On iOS, React Native exposes a label and its control as duplicate accessibility elements, so tapping by text can hit the label: nothing happens, yet the tool reports success.
31
+
32
+ ## Performance and libraries
33
+
34
+ - Prefer Expo's own modules (`expo-image`, `expo-file-system`, `expo-secure-store`, …) when one fits.
35
+ - Follow the `react-native-best-practices` skill for lists, re-renders, startup time and bundle size.
@@ -0,0 +1,32 @@
1
+ # Known issues
2
+
3
+ Recurring errors and their fixes. Check here before debugging a build error. Remove entries that no longer apply.
4
+
5
+ ## Format
6
+
7
+ ### <short error text>
8
+ - **Cause:**
9
+ - **Fix:**
10
+ - **Prevention:**
11
+
12
+ ## Entries
13
+
14
+ ### A native change doesn't show up in the build
15
+ - **Cause:** the kit's scripts regenerate `ios/` and `android/` only when Expo's fingerprint changes. It covers the app config, config plugins and native libraries, but not, for example, a file that a config plugin reads.
16
+ - **Fix:** delete `ios/.amk-fingerprint` and `android/.amk-fingerprint`, then check again. The next build regenerates both folders and takes longer.
17
+ - **Prevention:** none needed for app config, plugin and library changes.
18
+
19
+ ### Expo SDK 55: the Android release build fails with "libworklets.so … missing and no known rule to make it"
20
+ - **Cause:** SDK 55's `expo-modules-core` looks for `libworklets.so` in an older build-output folder (`node_modules/react-native-worklets/android/build/intermediates/cmake/release/obj/<abi>/`). `react-native-worklets` 0.7 builds it into `intermediates/cxx/RelWithDebInfo/<hash>/obj/<abi>/`. It fails without the kit too.
21
+ - **Fix:** move to a later Expo SDK (SDK 57 builds). Until then: build worklets once (`cd android && ./gradlew :react-native-worklets:assembleRelease`), copy each `libworklets.so` from `cxx/RelWithDebInfo/*/obj/<abi>/` to `cmake/release/obj/<abi>/`, and build again. The copy stays until `node_modules` is reinstalled.
22
+ - **Prevention:** upgrade the SDK.
23
+
24
+ ### A library fails at build or run time right after it was added
25
+ - **Cause:** it was added with `npm install` or `yarn add`, so its version may not match the Expo SDK.
26
+ - **Fix:** `npx expo install --fix`, then `npx expo-doctor`.
27
+ - **Prevention:** add libraries with `npx expo install <package>`.
28
+
29
+ ### "Unable to resolve module ./Name" in CI or a fresh clone, while it builds on your machine
30
+ - **Cause:** a file was renamed only in letter case (for example `storage.ts` to `Storage.ts`). macOS and Windows treat both names as the same file, so git kept the old name; Metro and Linux CI machines don't.
31
+ - **Fix:** rename it through git in two steps, then commit: `git mv src/utils/storage.ts src/utils/tmp.ts && git mv src/utils/tmp.ts src/utils/Storage.ts`.
32
+ - **Prevention:** rename files with `git mv`, not only in Finder or the editor.
@@ -21,11 +21,12 @@ Input: $ARGUMENTS (the new version such as 1.4.0, or patch, minor or major; whic
21
21
  - `client.md`: for the client or product owner. Cover what's new, what's fixed, what they should test or do, and known issues.
22
22
 
23
23
  Show all three files to the user and wait for their approval.
24
- 5. **Version and build numbers:** `sh scripts/ai/set-version.sh <version>` sets the iOS and Android version names. If the script stops because the project ships several apps, ask the user which version each app gets, and set them after they confirm.
25
- - When `codemagic.yaml` sets build numbers, leave them alone.
26
- - Otherwise every store upload needs a higher build number. Ask before changing native files. Then raise Android's `versionCode` in `android/app/build.gradle`, and set iOS with `cd ios && agvtool new-version -all <number>`. Never edit `project.pbxproj` by hand. iOS may keep its build number when the version name changes, if that's how the team works.
24
+ 5. **Version and build numbers:** `sh scripts/ai/set-version.sh <version>` sets the iOS and Android version names; in Expo apps without native folders, `expo.version` in `app.json`. If the script stops because the project ships several apps, or computes its config in `app.config.*`, ask the user how to set each version, and set them after they confirm.
25
+ - When CI, fastlane or EAS sets the build numbers at build time (`release-check.js` in step 6 says so), leave them alone.
26
+ - Otherwise every store upload needs a higher build number. Ask before changing native files. Then raise Android's `versionCode` in `android/app/build.gradle`, and set iOS with `cd ios && agvtool new-version -all <number>`. Never edit `project.pbxproj` by hand. In Expo apps without native folders, raise `expo.ios.buildNumber` and `expo.android.versionCode` in `app.json` instead. iOS may keep its build number when the version name changes, if that's how the team works.
27
27
  6. **Release check:** `node scripts/ai/release-check.js`. Show the output. Fix each ✗, asking first when the fix touches native config. List each ! for the user to decide.
28
28
  7. **Release PR:** commit as `chore(release): <version>` (so the next changelog leaves it out), with `Assisted-by: <tool>/<model>`. Ask before pushing. Open a PR titled `Release <version>` with the changelog and the release-check output.
29
29
  8. **Tag and build, after the merge.** Once the PR is merged, ask the user before tagging. Then run `git switch main && git pull && git tag v<version> && git push origin v<version>`.
30
30
  - With Codemagic (`codemagic.yaml`; see `docs/ai/codemagic.md`), the tag starts the signed builds.
31
- - Without CI, the user builds signed apps on their Mac, because signing keys stay with people. Tell them to run `sh scripts/ai/release-build.sh android [flavor]` and `sh scripts/ai/release-build.sh ios [scheme]`, and to upload the results from `.ai/release/` (Play Console, and Xcode's Organizer or Transporter). Never run these yourself or ask for the keys.
31
+ - With the team's own release tooling (fastlane lanes in `fastlane/`, `ios/fastlane/` or `android/fastlane/`, EAS builds set up in `eas.json`, or release scripts in `package.json`), the user runs the lane, `eas build` and `eas submit`, or the script that builds and uploads the release, instead of `release-build.sh`. Tell them which one; if it isn't clear, ask.
32
+ - Without CI, the user builds signed apps on their Mac, because signing keys stay with people. Tell them to run `sh scripts/ai/release-build.sh android [flavor]` and `sh scripts/ai/release-build.sh ios [scheme]`, and to upload the results from `.ai/release/` (Play Console, and Xcode's Organizer or Transporter). In Expo apps the script generates the native projects first, and iOS signing needs the Apple team in `app.json` (`expo.ios.appleTeamId`). Never run these yourself or ask for the keys.
@@ -1,6 +1,6 @@
1
1
  #!/bin/sh
2
2
  # agentic-mobile-kit pre-commit: runs for every commit, whichever person or AI tool makes it.
3
- # Blocks secrets and broken Xcode project files, and lints the staged JS/TS files.
3
+ # Blocks secrets, broken Xcode project files and case-only renames git missed, and lints the staged JS/TS files.
4
4
  set -eu
5
5
 
6
6
  staged=$(git diff --cached --name-only --diff-filter=ACMR)
@@ -47,7 +47,12 @@ if [ -n "$specs" ] && [ -f scripts/ai/spec.js ]; then
47
47
  node scripts/ai/spec.js check --skip-drafts $specs || fail "fix the spec format above (format: specs/current/README.md)"
48
48
  fi
49
49
 
50
- # 6. warn about large commits (the PR size check in CI is the hard limit)
50
+ # 6. files renamed only in letter case on macOS or Windows: git still has the old name, so other machines can't find them
51
+ if [ -f scripts/ai/case-check.js ]; then
52
+ node scripts/ai/case-check.js || fail "rename them through git as shown above"
53
+ fi
54
+
55
+ # 7. warn about large commits (the PR size check in CI is the hard limit)
51
56
  lines=$(git diff --cached --numstat -- . ':(exclude)*.lock' ':(exclude)package-lock.json' ':(exclude)pnpm-lock.yaml' ':(exclude)*.snap' |
52
57
  awk '{ s += $1 + $2 } END { print s + 0 }')
53
58
  [ "$lines" -le 400 ] || echo "pre-commit: warning: $lines changed lines; consider smaller commits" >&2
@@ -43,6 +43,8 @@ jobs:
43
43
  echo "$MAESTRO_SHA256 maestro.zip" | sha256sum -c -
44
44
  unzip -q maestro.zip -d "$HOME" && rm maestro.zip
45
45
  echo "$HOME/maestro/bin" >> "$GITHUB_PATH"
46
+ - name: Generate the native project (Expo apps without android/ in git)
47
+ run: sh scripts/ai/prebuild.sh android
46
48
  - name: Build release APK
47
49
  working-directory: android
48
50
  run: ./gradlew assembleRelease --no-daemon
@@ -33,11 +33,9 @@ jobs:
33
33
  with:
34
34
  node-version: 24
35
35
  - run: sh scripts/ai/install-deps.sh
36
- - name: Generate the native project (Expo apps without ios/)
37
- if: hashFiles('ios/Podfile') == ''
38
- run: npx expo prebuild --platform ios --no-install
36
+ - name: Generate the native project (Expo apps without ios/ in git)
37
+ run: sh scripts/ai/prebuild.sh ios
39
38
  - name: Install pods
40
- working-directory: ios
41
- run: pod install
39
+ run: sh scripts/ai/pod-install.sh
42
40
  - name: Build for the simulator (no signing)
43
41
  run: sh scripts/ai/ios-build.sh
@@ -1,4 +1,4 @@
1
- <!-- KIT:START agentic-mobile-kit {{KIT_VERSION}} ci={{KIT_CI}} (edit outside these markers; the kit updates what's inside) -->
1
+ <!-- KIT:START agentic-mobile-kit {{KIT_VERSION}} ci={{KIT_CI}} stack={{KIT_STACK}} (edit outside these markers; the kit updates what's inside) -->
2
2
  # {{APP_NAME}}: instructions for AI agents
3
3
 
4
4
  Read by Claude Code (through CLAUDE.md), Codex, Cursor, OpenCode, Kiro and Antigravity. Keep it short; details live in `docs/ai/`.
@@ -7,7 +7,7 @@ This project may also use other AI workflow frameworks (for example Superpowers,
7
7
 
8
8
  ## Project
9
9
 
10
- - Bare React Native {{RN_VERSION}} (New Architecture), React {{REACT_VERSION}}, TypeScript {{TS_VERSION}}, Node {{NODE_VERSION}}. Package manager: {{PM}}.
10
+ - Bare React Native {{RN_VERSION}} ({{RN_ARCH}}), React {{REACT_VERSION}}, TypeScript {{TS_VERSION}}, Node {{NODE_VERSION}}. Package manager: {{PM}}.
11
11
  - What the app does: `docs/ai/product.md`, and requirement by requirement, as it works now: `specs/current/`. Stack and services: `docs/ai/tech.md`. Folders and layers: `docs/ai/structure.md`. Code style: `docs/ai/conventions.md`.
12
12
 
13
13
  ## Commands
@@ -16,10 +16,10 @@ This project may also use other AI workflow frameworks (for example Superpowers,
16
16
  |---|---|
17
17
  | Install dependencies | `sh scripts/ai/install-deps.sh` |
18
18
  | Lint, typecheck, test | `{{PM_RUN}} lint`, `{{PM_RUN}} typecheck`, `{{PM_RUN}} test` |
19
- | iOS pods (after native dependency changes) | `cd ios && pod install` |
19
+ | iOS pods (after native dependency changes) | `sh scripts/ai/pod-install.sh` |
20
20
  | iOS build (simulator, no signing) | `sh scripts/ai/ios-build.sh` |
21
21
  | Android build | `cd android && ./gradlew assembleDebug` |
22
- | Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/ai/verify.sh all --spec <id>` |
22
+ | Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/ai/verify.sh all --spec <id>`; with product flavors it checks the first unless `--flavor <name>`; another iOS scheme: `--scheme <name>` |
23
23
  | Specs: progress, format check, fold a finished feature into the living spec | `node scripts/ai/spec.js status`, `node scripts/ai/spec.js check`, `node scripts/ai/spec.js merge <id>` |
24
24
  | Check a release before tagging it (versions, permission texts, debug leftovers) | `node scripts/ai/release-check.js` |
25
25
  | Signed release builds (a person runs them: they use the signing keys) | `sh scripts/ai/release-build.sh android [flavor]`, `sh scripts/ai/release-build.sh ios [scheme]` |
@@ -27,6 +27,7 @@ workflows:
27
27
  script: cp "release-notes/${CM_TAG#v}/play-store.txt" release_notes.txt 2>/dev/null || true
28
28
  - name: Build the signed app bundle
29
29
  script: |
30
+ sh scripts/ai/prebuild.sh android # Expo apps without android/ in git
30
31
  echo "sdk.dir=$ANDROID_SDK_ROOT" > android/local.properties
31
32
  package=$(sed -n -E 's/.*applicationId( =)? "([^"]+)".*/\2/p' android/app/build.gradle* | head -1)
32
33
  if last=$(google-play get-latest-build-number --package-name "$package") && [ -n "$last" ]; then code=$((last + 1)); else code=$BUILD_NUMBER; fi
@@ -66,7 +67,7 @@ workflows:
66
67
  - name: Release check
67
68
  script: node scripts/ai/release-check.js
68
69
  - name: Install dependencies
69
- script: sh scripts/ai/install-deps.sh && cd ios && pod install
70
+ script: sh scripts/ai/install-deps.sh && sh scripts/ai/prebuild.sh ios && sh scripts/ai/pod-install.sh
70
71
  - name: Store release notes
71
72
  script: |
72
73
  notes="release-notes/${CM_TAG#v}/app-store.txt"
@@ -13,5 +13,15 @@ Recurring errors and their fixes. Check here before debugging a build error. Rem
13
13
 
14
14
  ### iOS build fails right after a native dependency was added or removed
15
15
  - **Cause:** `ios/Pods` is out of date.
16
- - **Fix:** `cd ios && pod install`, then rebuild.
17
- - **Prevention:** run `pod install` in the same change that edits `package.json`.
16
+ - **Fix:** `sh scripts/ai/pod-install.sh`, then rebuild.
17
+ - **Prevention:** run `sh scripts/ai/pod-install.sh` in the same change that edits `package.json`.
18
+
19
+ ### `./gradlew` fails with "no main manifest attribute, in …/gradle-wrapper.jar"
20
+ - **Cause:** a React Native upgrade updated `android/gradlew` (which now runs `java -jar gradle-wrapper.jar`) but not `android/gradle/wrapper/gradle-wrapper.jar`. The upgrade diff doesn't carry binary files.
21
+ - **Fix:** copy `android/gradle/wrapper/gradle-wrapper.jar` from the React Native template of your new version (or run `gradle wrapper` with the version in `gradle-wrapper.properties`).
22
+ - **Prevention:** when upgrading, also copy the binary files the upgrade helper lists.
23
+
24
+ ### "Unable to resolve module ./Name" in CI or a fresh clone, while it builds on your machine
25
+ - **Cause:** a file was renamed only in letter case (for example `storage.ts` to `Storage.ts`). macOS and Windows treat both names as the same file, so git kept the old name; Metro and Linux CI machines don't.
26
+ - **Fix:** rename it through git in two steps, then commit: `git mv src/utils/storage.ts src/utils/tmp.ts && git mv src/utils/tmp.ts src/utils/Storage.ts`.
27
+ - **Prevention:** rename files with `git mv`, not only in Finder or the editor.
@@ -1,11 +1,12 @@
1
- # React Native rules (bare, New Architecture)
1
+ # React Native rules (bare)
2
2
 
3
3
  Rules for things AI agents commonly get wrong in current React Native. Each one comes from a documented platform change.
4
4
 
5
5
  ## Architecture
6
6
 
7
- - The New Architecture is the only architecture since React Native 0.82. Never set `newArchEnabled=false`; it's ignored.
8
- - Write native modules as Turbo Modules and native views as Fabric components, with TypeScript codegen specs. Don't use the old bridge APIs (`NativeModules`, `requireNativeComponent`) in new code.
7
+ - `AGENTS.md` says which architecture this app runs.
8
+ - New Architecture (the only one since React Native 0.82): write native modules as Turbo Modules and native views as Fabric components, with TypeScript codegen specs. Don't use the old bridge APIs (`NativeModules`, `requireNativeComponent`) in new code. From 0.82, `newArchEnabled=false` is ignored.
9
+ - Old Architecture (`newArchEnabled=false`): before adding a library, check that it still supports the Old Architecture; Reanimated 4 and FlashList 2, for example, don't. Moving to the New Architecture is a task of its own, needed before React Native 0.82; don't mix it into other work.
9
10
 
10
11
  ## Screens and layout
11
12
 
@@ -17,7 +18,7 @@ Rules for things AI agents commonly get wrong in current React Native. Each one
17
18
 
18
19
  ## Native changes
19
20
 
20
- - After adding or removing a native dependency: `cd ios && pod install`, then rebuild both apps. Restart Metro with `--reset-cache` if the bundle looks stale.
21
+ - After adding or removing a native dependency: `sh scripts/ai/pod-install.sh`, then rebuild both apps. Restart Metro with `--reset-cache` if the bundle looks stale.
21
22
  - Don't hand-edit `project.pbxproj`. Let CocoaPods or Xcode change it.
22
23
  - Don't bump the Android Gradle Plugin, Gradle, Kotlin or the iOS deployment target one by one. Upgrade React Native as a whole with the `upgrading-react-native` skill and the React Native Upgrade Helper.
23
24
 
@@ -0,0 +1,41 @@
1
+ #!/usr/bin/env node
2
+ // Lists the Android app's product flavors, one per line, from android/app/build.gradle (or .kts).
3
+ // No output: the app has no flavors. Exit 2: it has several flavor dimensions, so a build variant
4
+ // has to be named in full (for example devFree).
5
+ 'use strict';
6
+ const fs = require('fs');
7
+
8
+ const file = ['android/app/build.gradle', 'android/app/build.gradle.kts'].find(f => fs.existsSync(f));
9
+ const text = (file ? fs.readFileSync(file, 'utf8') : '').replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '');
10
+
11
+ // the body of `name { … }`, found by matching braces (Gradle blocks nest)
12
+ function block(t, name) {
13
+ const m = new RegExp(`(^|\\W)${name}\\s*\\{`).exec(t);
14
+ if (!m) return null;
15
+ let depth = 0;
16
+ for (let i = m.index + m[0].length - 1; i < t.length; i++) {
17
+ if (t[i] === '{') depth++;
18
+ else if (t[i] === '}' && --depth === 0) return t.slice(m.index + m[0].length, i);
19
+ }
20
+ return null;
21
+ }
22
+
23
+ const body = block(text, 'productFlavors');
24
+ if (body === null) process.exit(0);
25
+
26
+ const dimensions = (text.match(/flavorDimensions[^\n]*/g) || []).join(' ').match(/["'][^"']+["']/g) || [];
27
+ if (dimensions.length > 1) {
28
+ console.error(`several flavor dimensions (${dimensions.join(', ')}): name the build variant in full, for example devFree`);
29
+ process.exit(2);
30
+ }
31
+
32
+ // the blocks directly inside: `dev {` (Groovy) or `create("dev") {` (Kotlin)
33
+ const names = [];
34
+ let depth = 0;
35
+ const token = /(?:create|register|maybeCreate)\(\s*["']([\w-]+)["']\s*\)\s*\{|([A-Za-z_]\w*)\s*\{|\{|\}/g;
36
+ for (let m; (m = token.exec(body));) {
37
+ if (m[0] === '}') { depth--; continue; }
38
+ if (depth === 0 && (m[1] || m[2])) names.push(m[1] || m[2]);
39
+ depth++;
40
+ }
41
+ if (names.length) console.log(names.join('\n'));
@@ -0,0 +1,35 @@
1
+ #!/usr/bin/env node
2
+ // Finds files and folders that git tracks under a name differing from the disk only in letter case.
3
+ // macOS and Windows treat both names as one file, so a rename such as storage.ts to Storage.ts never reaches git:
4
+ // the app builds on that machine and fails in CI and on every fresh clone. Exits 1 when it finds any.
5
+ 'use strict';
6
+ const fs = require('fs');
7
+ const { execFileSync } = require('child_process');
8
+
9
+ const tracked = execFileSync('git', ['ls-files', '-z'], { encoding: 'utf8', maxBuffer: 1 << 30 }).split('\0').filter(Boolean);
10
+ const listings = new Map();
11
+ const names = dir => {
12
+ if (!listings.has(dir)) { try { listings.set(dir, new Set(fs.readdirSync(dir || '.'))); } catch { listings.set(dir, null); } }
13
+ return listings.get(dir);
14
+ };
15
+
16
+ const wrong = new Map(); // git's path -> the path on disk
17
+ for (const file of tracked) {
18
+ const parts = file.split('/');
19
+ for (let i = 0; i < parts.length; i++) {
20
+ const dir = parts.slice(0, i).join('/');
21
+ const here = names(dir);
22
+ if (here && here.has(parts[i])) continue;
23
+ const disk = here && [...here].find(n => n.toLowerCase() === parts[i].toLowerCase());
24
+ if (disk) wrong.set(parts.slice(0, i + 1).join('/'), [dir, disk].filter(Boolean).join('/'));
25
+ break; // deleted, or reported: nothing to check below it
26
+ }
27
+ }
28
+
29
+ if (wrong.size) {
30
+ console.error('Git has these under a different letter case than the disk:');
31
+ for (const [inGit, onDisk] of wrong) console.error(` ${inGit} (on disk: ${onDisk})`);
32
+ const [inGit, onDisk] = wrong.entries().next().value;
33
+ console.error(`Rename each through git in two steps, for example: git mv "${inGit}" "${inGit}.tmp" && git mv "${inGit}.tmp" "${onDisk}"`);
34
+ process.exit(1);
35
+ }
@@ -10,5 +10,8 @@ elif [ -f pnpm-lock.yaml ]; then
10
10
  elif [ -f bun.lock ] || [ -f bun.lockb ]; then
11
11
  bun install --frozen-lockfile # ponytail: CI needs a setup-bun step for this branch
12
12
  else
13
- npm ci
13
+ npm ci || {
14
+ echo "install-deps: npm ci failed. If it's a peer-dependency conflict (ERESOLVE) and your team installs with --legacy-peer-deps, commit legacy-peer-deps=true in .npmrc so every install, and CI, does the same." >&2
15
+ exit 1
16
+ }
14
17
  fi
@@ -1,12 +1,19 @@
1
1
  #!/bin/sh
2
2
  # Builds the iOS app for the simulator without code signing (CI and local checks).
3
- # CONFIGURATION=Release builds a self-contained app (JS bundled; no Metro needed).
3
+ # CONFIGURATION=Release builds a self-contained app (JS bundled; no Metro needed), with the configuration the scheme
4
+ # archives with: apps with one per environment (for example "Release Staging") get theirs.
5
+ # AMK_IOS_SCHEME picks the scheme (default: the one named like the workspace).
4
6
  # Output goes to ios/DerivedData: ios/build holds React Native codegen files from pod install.
5
7
  set -eu
6
8
  config=${CONFIGURATION:-Debug}
7
9
  workspace=$(ls -d ios/*.xcworkspace 2>/dev/null | head -n 1)
8
- [ -n "$workspace" ] || { echo "No ios/*.xcworkspace found. Run pod install in ios/ first."; exit 1; }
9
- scheme=$(basename "$workspace" .xcworkspace)
10
+ [ -n "$workspace" ] || { echo "No ios/*.xcworkspace found. Run sh scripts/ai/pod-install.sh first."; exit 1; }
11
+ scheme=${AMK_IOS_SCHEME:-$(basename "$workspace" .xcworkspace)}
12
+ if [ "$config" = Release ]; then
13
+ file=$(ls ios/*.xcodeproj/xcshareddata/xcschemes/"$scheme".xcscheme ios/*.xcworkspace/xcshareddata/xcschemes/"$scheme".xcscheme 2> /dev/null | head -n 1)
14
+ [ -z "$file" ] || config=$(awk '/<ArchiveAction/ { a = 1 } a && /buildConfiguration/ { split($0, q, "\""); print q[2]; exit }' "$file")
15
+ [ -n "$config" ] || config=Release
16
+ fi
10
17
 
11
18
  xcodebuild -workspace "$workspace" -scheme "$scheme" -configuration "$config" \
12
19
  -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' \
@@ -9,6 +9,18 @@ if ! node -e "process.exit(require('./package.json').scripts?.[process.argv[1]]
9
9
  exit 0
10
10
  fi
11
11
 
12
+ # Expo apps: the first `expo lint` installs ESLint and changes package.json, which is the team's decision, not a check
13
+ if [ "$script" = lint ] && node -e "process.exit(/^expo lint/.test(require('./package.json').scripts.lint) ? 0 : 1)" &&
14
+ [ -z "$(ls eslint.config.* .eslintrc* 2> /dev/null)" ]; then
15
+ echo "skip: lint: ESLint isn't set up yet. Run npx expo lint once (it installs ESLint) and commit what it adds"
16
+ exit 0
17
+ fi
18
+ # Expo apps: `expo start` writes expo-env.d.ts (gitignored) with the types of Expo's CSS and asset imports.
19
+ # Fresh clones and CI haven't run it, so write the same file.
20
+ if [ "$script" = typecheck ] && [ ! -f expo-env.d.ts ] && grep -q 'expo-env\.d\.ts' tsconfig.json 2> /dev/null; then
21
+ printf '/// <reference types="expo/types" />\n\n// NOTE: This file should not be edited and should be in your git ignore' > expo-env.d.ts
22
+ fi
23
+
12
24
  if [ -f yarn.lock ]; then yarn run "$script" "$@" # works on Yarn 1 and Yarn Berry
13
25
  elif [ -f pnpm-lock.yaml ]; then pnpm -s "$script" "$@"
14
26
  elif [ -f bun.lock ] || [ -f bun.lockb ]; then bun run "$script" "$@"
@@ -0,0 +1,12 @@
1
+ #!/bin/sh
2
+ # Installs the iOS pods. With a Gemfile (React Native's template has one), it uses the CocoaPods version pinned there,
3
+ # so Podfile.lock doesn't change just because machines have different CocoaPods versions.
4
+ # Usage: sh scripts/ai/pod-install.sh [pod install options]
5
+ set -eu
6
+ cd ios
7
+ if [ -f ../Gemfile ] && command -v bundle > /dev/null && bundle check > /dev/null 2>&1; then
8
+ bundle exec pod install "$@"
9
+ else
10
+ [ ! -f ../Gemfile ] || echo "pod-install: the Gemfile's gems aren't installed (run: bundle install), so this uses the CocoaPods on PATH" >&2
11
+ pod install "$@"
12
+ fi
@@ -0,0 +1,28 @@
1
+ #!/bin/sh
2
+ # Expo apps whose ios/ and android/ aren't in git (Continuous Native Generation): generates the platform's native
3
+ # project with `expo prebuild`, so release builds can run. Does nothing for apps that keep the folders in git.
4
+ # Usage: sh scripts/ai/prebuild.sh ios|android
5
+ set -eu
6
+ platform=$1
7
+ [ -z "$(git ls-files -- "$platform")" ] || exit 0
8
+ node -e "const p = require('./package.json'); process.exit({ ...p.dependencies, ...p.devDependencies }.expo ? 0 : 1)" 2> /dev/null || exit 0
9
+
10
+ # prebuild recreates the folder, which throws away its pods and build caches. Expo's fingerprint covers everything
11
+ # the native project is generated from (app config, config plugins, native libraries): while it's unchanged since
12
+ # the last prebuild, the generated project is still right and the next build stays incremental.
13
+ stamp="$platform/.amk-fingerprint"
14
+ hash=$(node node_modules/expo/bin/fingerprint fingerprint:generate --platform "$platform" 2> /dev/null |
15
+ node -e 'try { console.log(JSON.parse(require("fs").readFileSync(0, "utf8")).hash) } catch {}') || hash=""
16
+ if [ -n "$hash" ] && [ "$(cat "$stamp" 2> /dev/null)" = "$hash" ]; then
17
+ echo "prebuild: $platform/ already matches the app config"
18
+ exit 0
19
+ fi
20
+
21
+ # the first prebuild also writes into package.json (run scripts) and app.json (a placeholder bundle ID):
22
+ # put those files back, unless they already had changes of the team's
23
+ clean=$(for f in package.json app.json; do
24
+ if git ls-files --error-unmatch "$f" > /dev/null 2>&1 && git diff --quiet HEAD -- "$f"; then echo "$f"; fi
25
+ done)
26
+ CI=1 npx expo prebuild --platform "$platform" --no-install
27
+ for f in $clean; do git checkout -q HEAD -- "$f"; done
28
+ [ -z "$hash" ] || echo "$hash" > "$stamp"
@@ -3,14 +3,19 @@
3
3
  # A person runs it, because it uses the signing keys, which agents must never handle.
4
4
  #
5
5
  # sh scripts/ai/release-build.sh android [flavor] signed app bundle (.aab) for Google Play
6
- # sh scripts/ai/release-build.sh ios [scheme] signed .ipa for App Store Connect (TestFlight)
6
+ # sh scripts/ai/release-build.sh ios [scheme] signed .ipa for App Store Connect, or as ios/ExportOptions.plist says
7
+ # Defaults: AMK_ANDROID_FLAVOR and AMK_IOS_SCHEME. An app with product flavors must name the one to build.
7
8
  #
8
9
  # Android signs with your upload key. Set its path in your shell, never in the repo:
9
10
  # export AMK_UPLOAD_KEYSTORE=~/keys/myapp-upload.jks AMK_UPLOAD_KEY_ALIAS=upload
10
11
  # The passwords are asked for, unless AMK_UPLOAD_STORE_PASSWORD and AMK_UPLOAD_KEY_PASSWORD are set.
11
12
  # Without AMK_UPLOAD_KEYSTORE it uses the app's own signing setup, and stops if that's the debug key.
12
- # iOS signs with the Apple account in Xcode (Settings > Accounts) and automatic signing; Xcode may
13
+ # iOS archives with the scheme's archive configuration and exports with the project's ios/ExportOptions.plist
14
+ # (or the one AMK_IOS_EXPORT_OPTIONS names): manual signing, ad hoc or enterprise. Without one, it exports for
15
+ # App Store Connect with automatic signing, using the Apple account in Xcode (Settings > Accounts); Xcode may
13
16
  # create a distribution certificate or profile in that team if one is missing.
17
+ # Expo apps without native folders in git: it generates them first (expo prebuild). iOS signing then needs the
18
+ # Apple team in app.json (expo.ios.appleTeamId).
14
19
  # Version and build numbers come from the repo, so set them first (the m-release skill does).
15
20
  # Output: .ai/release/
16
21
  set -eu
@@ -29,6 +34,18 @@ secret() {
29
34
 
30
35
  case "$platform" in
31
36
  android)
37
+ sh scripts/ai/prebuild.sh android
38
+ target=${target:-${AMK_ANDROID_FLAVOR:-}}
39
+ if [ -z "$target" ]; then
40
+ code=0
41
+ flavors=$(node scripts/ai/android-flavors.js) || code=$?
42
+ case $code in
43
+ 0) ;;
44
+ 2) echo "This app has several flavor dimensions: name the variant, for example: sh scripts/ai/release-build.sh android devFree" >&2; exit 1 ;;
45
+ *) echo "Couldn't read the product flavors from build.gradle (see the error above)." >&2; exit 1 ;;
46
+ esac
47
+ [ -z "$flavors" ] || { echo "This app has product flavors ($(echo $flavors)). Name the one to build, for example: sh scripts/ai/release-build.sh android $(echo "$flavors" | head -n 1)" >&2; exit 1; }
48
+ fi
32
49
  flavor=$(printf %s "$target" | awk '{ print toupper(substr($0, 1, 1)) substr($0, 2) }')
33
50
  if [ -n "${AMK_UPLOAD_KEYSTORE:-}" ]; then
34
51
  secret AMK_UPLOAD_STORE_PASSWORD 'Keystore password'
@@ -54,15 +71,20 @@ android)
54
71
  done
55
72
  ;;
56
73
  ios)
74
+ sh scripts/ai/prebuild.sh ios
75
+ if [ ! -d ios/Pods ] || [ ios/Podfile -nt ios/Pods/Manifest.lock ]; then sh scripts/ai/pod-install.sh; fi
57
76
  workspace=$(ls -d ios/*.xcworkspace | head -n 1)
58
- scheme=${target:-$(basename "$workspace" .xcworkspace)}
59
- [ -d ios/Pods ] || (cd ios && pod install)
77
+ scheme=${target:-${AMK_IOS_SCHEME:-$(basename "$workspace" .xcworkspace)}}
60
78
  log="$out/$scheme-ios.log"
61
79
  echo "Archiving $scheme (several minutes; log: $log)"
62
- xcodebuild -workspace "$workspace" -scheme "$scheme" -configuration Release -destination 'generic/platform=iOS' \
80
+ xcodebuild -workspace "$workspace" -scheme "$scheme" -destination 'generic/platform=iOS' \
63
81
  -archivePath "$out/$scheme.xcarchive" -allowProvisioningUpdates archive > "$log" 2>&1 \
64
82
  || { grep -E 'error:|BUILD FAILED|ARCHIVE FAILED' "$log" | head -n 20; exit 1; }
65
- cat > "$out/ExportOptions.plist" <<'PLIST'
83
+ options=${AMK_IOS_EXPORT_OPTIONS:-ios/ExportOptions.plist}
84
+ if [ ! -f "$options" ]; then
85
+ [ -z "${AMK_IOS_EXPORT_OPTIONS:-}" ] || { echo "AMK_IOS_EXPORT_OPTIONS: no file at $options" >&2; exit 1; }
86
+ options="$out/ExportOptions.plist"
87
+ cat > "$options" <<'PLIST'
66
88
  <?xml version="1.0" encoding="UTF-8"?>
67
89
  <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
68
90
  <plist version="1.0"><dict>
@@ -71,8 +93,10 @@ ios)
71
93
  <key>signingStyle</key><string>automatic</string>
72
94
  </dict></plist>
73
95
  PLIST
96
+ fi
97
+ echo "Exporting with $options"
74
98
  xcodebuild -exportArchive -archivePath "$out/$scheme.xcarchive" -exportPath "$out/$scheme" \
75
- -exportOptionsPlist "$out/ExportOptions.plist" -allowProvisioningUpdates >> "$log" 2>&1 \
99
+ -exportOptionsPlist "$options" -allowProvisioningUpdates >> "$log" 2>&1 \
76
100
  || { grep -E 'error:|EXPORT FAILED' "$log" | head -n 20; exit 1; }
77
101
  ipa=$(ls "$out/$scheme"/*.ipa | head -n 1)
78
102
  # the export re-signs for distribution, so check the app inside the .ipa, not the archive
@@ -81,7 +105,7 @@ PLIST
81
105
  echo "$ipa"
82
106
  ;;
83
107
  *)
84
- sed -n '2,16p' "$0"
108
+ sed -n '2,20p' "$0"
85
109
  exit 1
86
110
  ;;
87
111
  esac