agentic-mobile-kit 0.7.16 → 0.7.18

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 (24) hide show
  1. package/bin/cli.js +1 -1
  2. package/lib/init.js +122 -20
  3. package/package.json +1 -1
  4. package/stacks/react-native/expo/.agents/skills/THIRD_PARTY.md +1 -1
  5. package/stacks/react-native/expo/AGENTS.md +6 -3
  6. package/stacks/react-native/expo/docs/amk/expo.md +60 -4
  7. package/stacks/react-native/new-app/ErrorBoundary.tsx +61 -0
  8. package/stacks/react-native/new-app/error-boundary.tsx +30 -0
  9. package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +6 -5
  10. package/stacks/react-native/template/.agents/skills/m-prototype/SKILL.md +4 -3
  11. package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +10 -6
  12. package/stacks/react-native/template/.github/workflows/e2e.yml +3 -0
  13. package/stacks/react-native/template/.rulesync/subagents/m-device-checker.md +2 -2
  14. package/stacks/react-native/template/.rulesync/subagents/m-reviewer.md +3 -3
  15. package/stacks/react-native/template/AGENTS.md +5 -2
  16. package/stacks/react-native/template/docs/amk/react-native.md +58 -3
  17. package/stacks/react-native/template/scripts/amk/a11y.js +78 -0
  18. package/stacks/react-native/template/scripts/amk/release-check.js +149 -2
  19. package/stacks/react-native/template/scripts/amk/report.js +78 -0
  20. package/stacks/react-native/template/scripts/amk/rn-check.js +435 -0
  21. package/stacks/react-native/template/scripts/amk/verify.sh +139 -15
  22. package/stacks/react-native/template/specs/_templates/design.md +16 -0
  23. package/stacks/react-native/template/specs/_templates/flow.yaml +8 -0
  24. package/stacks/react-native/template/specs/_templates/subflow.yaml +36 -0
@@ -12,23 +12,27 @@ If your tool has subagents, hand the review to the `m-reviewer` subagent, so it
12
12
 
13
13
  ## Reviewing
14
14
 
15
- 1. Get the changes since the base branch the kit's checks use: `node scripts/amk/baseline.js base` prints it, then `git diff <base>...HEAD` and `git log <base>..HEAD --oneline`. If there's a spec, read its `requirements.md`.
15
+ 1. Get the changes since the base branch the kit's checks use: `node scripts/amk/baseline.js base` prints it, then `git diff <base>...HEAD` and `git log <base>..HEAD --oneline`. If there's a spec, read its `requirements.md`. Run `node scripts/amk/rn-check.js`: what it reports in the changed lines is a finding, and each `// amk-ok: <reason>` it lists needs a reason that holds.
16
16
  2. Check, in order:
17
17
  - **Against the spec**, when there is one:
18
18
  - *Complete:* every task is ticked, every requirement is implemented, and every scenario has evidence (a test or a screenshot).
19
19
  - *Correct:* the code does what each requirement says, edge cases included, and nothing outside the agreed scope.
20
- - *Coherent:* the decisions in `design.md` show up in the code, and `specs/current/` was updated (`node scripts/amk/specs.js merge <id>`) if behavior changed.
20
+ - *Coherent:* the decisions in `design.md` show up in the code, its UI/UX level in the screens, and `specs/current/` was updated (`node scripts/amk/specs.js merge <id>`) if behavior changed.
21
21
  - **No spec:** does the diff do what was asked, and nothing unrelated?
22
22
  - **Tests:** were tests added for new logic? Were any tests deleted, skipped or weakened?
23
23
  - **TypeScript:** any new `any`, `@ts-ignore` or non-null `!` to get past a check, or a loosened `tsconfig.json`?
24
24
  - **Both platforms:** anything iOS-only or Android-only (insets, back button, permissions, keyboard)?
25
25
  - **Screens:** with the keyboard open, do the field and its button stay visible? Does anything sit under the status bar, home indicator or gesture bar? Do lists that grow with the user's data scroll? Does text wrap at the largest text size?
26
26
  - **Tablets and landscape** (the screens `AGENTS.md` lists): does each layout adapt to the window width (`useWindowDimensions`), rather than stretching or centering the phone layout? Do turned screens scroll, with the left and right insets handled? Are sizes done the app's existing way?
27
- - **Accessibility:** does every new button or other touchable have an `accessibilityLabel` and an `accessibilityRole`? Are messages that appear after an action, such as form errors, announced to screen readers?
28
- - **Errors and states:** offline, server errors, empty and loading states.
29
- - **Security:** secrets, tokens, `.env` contents, logging of personal data.
27
+ - **Accessibility:** does every new button or other touchable have an `accessibilityLabel` and an `accessibilityRole`, and checkboxes, switches and tabs their `accessibilityState`? Are messages that appear after an action, such as form errors, announced to screen readers? Text contrast 4.5:1 in both themes, nothing under 11 points, swipe and long-press actions reachable another way?
28
+ - **Platform guidelines:** tap areas of at least 44×44 pt (48×48 dp on Android); swipe back and the Android back button still work, and every `Modal` closes with back; permissions asked when the user starts the feature, with a way to Settings once blocked; native controls; dark mode from the theme; Reduce Motion respected.
29
+ - **Store review:** a new sign-up path needs account deletion in the app; a new social login needs Sign in with Apple; digital goods use in-app purchase; a new permission has a text that says why, and Google Play's restricted ones (photos, all packages, exact alarms, background location) a reason the feature can't do without. `node scripts/amk/release-check.js` finds some of these.
30
+ - **Current APIs:** nothing React Native removed or deprecated, no `react-native/Libraries/…` imports, and React 19's ways (`ref` as a prop, `<Context value>`), as the React Native rules list them.
31
+ - **Errors and states:** offline, server errors, empty and loading states; an error boundary around the app; no empty `catch`; an action that fails shows it and can be retried.
32
+ - **Effects:** timers, listeners and subscriptions are cleaned up, and async work that ends after the screen closes doesn't update it.
33
+ - **Security:** secrets, tokens in plain storage instead of the Keychain/Keystore (or `expo-secure-store`), secret keys in the JavaScript bundle, `.env` contents, logging of personal data, session replay that records typed text.
30
34
  - **Native:** `project.pbxproj`, `Podfile`, Gradle or manifest changes, and whether pods and builds were re-run.
31
- - **Performance:** heavy work in render, list keys, needless re-renders.
35
+ - **Performance:** heavy work in render, list keys (from IDs, not the index), needless re-renders, base64 images in code.
32
36
  3. For each finding, check it in the code before reporting it. Report: severity (**blocker**, **should fix**), file and line, the problem, and a suggested fix. Leave out style nits; lint handles those.
33
37
  4. End with: "Ready for PR" or "Not ready: N blockers".
34
38
 
@@ -65,6 +65,9 @@ jobs:
65
65
  disable-animations: true
66
66
  emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
67
67
  script: sh scripts/amk/verify.sh android --label ci
68
+ - name: Summary (each flow's result, from verify.sh's report)
69
+ if: always()
70
+ run: if [ -d .amk/evidence/ci ]; then node scripts/amk/report.js .amk/evidence/ci --summary >> "$GITHUB_STEP_SUMMARY"; fi
68
71
  - name: Upload screenshots and logs
69
72
  if: always()
70
73
  uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
@@ -9,8 +9,8 @@ claudecode:
9
9
  You check the app on one device with fresh eyes, and hand the evidence back. You never edit files.
10
10
 
11
11
  1. Run the one command you were given exactly as it is, for example `sh scripts/amk/verify.sh ios --no-build --screens tablet --spec <id>`: no pipes, redirects or other commands added. Its output is short, and the plain command is the one people allow, so you don't wait on a permission prompt while the other checkers run. It installs the build that's there, runs the feature's Maestro flows on that device's screens (upright and turned), and saves screenshots in `.amk/evidence/<id>/<screen>/`. A command with `--part k/n` runs only its share of the flows, on a device of its own (a temporary copy for the parts after the first, deleted afterwards), and saves them in `.amk/evidence/<id>/<screen>/part-k/`. Don't build, and don't run anything else on a device: other checkers are using the other devices. A check takes several minutes, up to about 15 when a flow has to run again: give the command a timeout that long, or run it in the background and wait for it to end, never stopping it early.
12
- 2. If a flow failed, read its log and Maestro's own log (the output names both) and say why, and whether the app or the flow is wrong: on a turned screen, a flow often checks or taps something further down without scrolling to it first. Don't fix anything.
13
- 3. Open every screenshot in your screens' folders and check each against its scenario in `specs/<id>/requirements.md`, and against the screen rules in the React Native rules file that `AGENTS.md` names: the right content, nothing cut off or covered, a layout made for that screen. A turned screen's screenshots are landscape; a portrait one means the app didn't turn.
12
+ 2. If a flow failed, the output says at which step and what Maestro said, and shows the screen then (`report.md` in the evidence folder has it too); read its log and Maestro's own log for more, and say why, and whether the app or the flow is wrong: on a turned screen, a flow often checks or taps something further down without scrolling to it first. Don't fix anything.
13
+ 3. On Android screens, the output may list accessibility warnings from the screens' view trees (controls without a label, tap areas under 48 dp; `report.md` says which screenshot): report them as they are, they don't fail the check. Open every screenshot in your screens' folders and check each against its scenario in `specs/<id>/requirements.md`, and against the screen rules in the React Native rules file that `AGENTS.md` names: the right content, nothing cut off or covered, a layout made for that screen. A turned screen's screenshots are landscape; a portrait one means the app didn't turn.
14
14
  4. Report, and say only what you saw in this run:
15
15
  - the command, and its last lines of output;
16
16
  - per screen: flows passed out of total, and the evidence folder;
@@ -6,10 +6,10 @@ claudecode:
6
6
  tools: ["Read", "Grep", "Glob", "Bash"]
7
7
  ---
8
8
 
9
- You review code changes with fresh eyes. You never edit files. Use the shell only for read-only commands such as `git diff`, `git log`, `git show` and `node scripts/amk/baseline.js base`.
9
+ You review code changes with fresh eyes. You never edit files. Use the shell only for read-only commands such as `git diff`, `git log`, `git show`, `node scripts/amk/baseline.js base` and `node scripts/amk/rn-check.js`.
10
10
 
11
- 1. Get the changes since the base branch the kit's checks use: `node scripts/amk/baseline.js base` prints it, then `git diff <base>...HEAD`. If a spec exists in `specs/<id>/`, read its `requirements.md`.
12
- 2. Check scope, tests (added, deleted, weakened), iOS vs Android differences, screens (the keyboard covering a field or button, content under the system bars, lists that don't scroll, text cut off at large sizes), tablets and landscape for the screens AGENTS.md lists (layouts that adapt to the window width, turned screens that scroll), accessibility (labels and roles, messages announced to screen readers), TypeScript (new `any` or `@ts-ignore`, a loosened tsconfig), error and empty states, secrets, native file changes, and performance.
11
+ 1. Get the changes since the base branch the kit's checks use: `node scripts/amk/baseline.js base` prints it, then `git diff <base>...HEAD`. If a spec exists in `specs/<id>/`, read its `requirements.md`. Run `node scripts/amk/rn-check.js`: what it reports is a finding, and each `// amk-ok: <reason>` it lists needs a reason that holds.
12
+ 2. Check scope, tests (added, deleted, weakened), iOS vs Android differences, screens (the keyboard covering a field or button, content under the system bars, lists that don't scroll, text cut off at large sizes), tablets and landscape for the screens AGENTS.md lists (layouts that adapt to the window width, turned screens that scroll), accessibility (labels and roles, state on checkboxes, switches and tabs, contrast, text sizes, messages announced to screen readers), platform guidelines (44/48 tap areas, back gestures and the back button, permissions asked in context, native controls, dark mode, Reduce Motion), store review (account deletion, Sign in with Apple next to a social login, in-app purchase for digital goods, permission texts, restricted Android permissions), TypeScript (new `any` or `@ts-ignore`, a loosened tsconfig), removed or deprecated React Native APIs, errors (an error boundary, no empty `catch`, failed actions shown), error and empty states, effects that don't clean up, secrets and tokens in plain storage, native file changes, and performance.
13
13
  3. Confirm each finding in the code before reporting it.
14
14
  4. Report each finding as: severity (blocker or should fix), file:line, the problem, and a suggested fix. No style nits.
15
15
  5. End with "Ready for PR" or "Not ready: N blockers".
@@ -20,10 +20,11 @@ This project may also use other AI workflow frameworks (for example Superpowers,
20
20
  | iOS pods (after native dependency changes) | `sh scripts/amk/pod-install.sh` |
21
21
  | iOS build (simulator, no signing) | `sh scripts/amk/ios-build.sh` |
22
22
  | Android build | `cd android && ./gradlew assembleDebug` |
23
- | Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; with product flavors it checks the first unless `--flavor <name>`; another iOS scheme: `--scheme <name>`; only some screens: `--screens phone` (or `tablet`, `landscape`, …); on a real iPhone or iPad the user names: `AMK_IOS_DEVICE=<its UDID>` (the flows clear the app's data on it) |
23
+ | Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; with product flavors it checks the first unless `--flavor <name>`; another iOS scheme: `--scheme <name>`; only some screens: `--screens phone` (or `tablet`, `landscape`, …); only the flows tagged smoke: `--tags smoke`; on a real iPhone or iPad the user names: `AMK_IOS_DEVICE=<its UDID>` (the flows clear the app's data on it) |
24
24
  | Check devices at the same time | `sh scripts/amk/verify.sh plan --spec <id>` says how many this machine's memory fits, and prints the commands: one per device (in rounds when they don't all fit; a device's flows in parts when there's room), each for an `m-device-checker` subagent |
25
+ | React Native mistakes and Maestro flow problems in this branch's changed lines (`verify.sh quick` runs it) | `node scripts/amk/rn-check.js` |
25
26
  | Specs: progress, format check, fold a finished feature into the living spec | `node scripts/amk/specs.js status`, `node scripts/amk/specs.js check`, `node scripts/amk/specs.js merge <id>` |
26
- | Check a release before tagging it (versions, permission texts, debug leftovers) | `node scripts/amk/release-check.js` |
27
+ | Check a release before tagging it (versions, permission texts, store review rules, debug leftovers) | `node scripts/amk/release-check.js` |
27
28
  | Signed release builds (a person runs them: they use the signing keys) | `sh scripts/amk/release-build.sh android [flavor]`, `sh scripts/amk/release-build.sh ios [scheme]` |
28
29
 
29
30
  ## Definition of done
@@ -39,10 +40,12 @@ Never say a check passed unless you ran it in this session.
39
40
  ## Rules
40
41
 
41
42
  - Stay inside the task. Ask before touching unrelated files.
43
+ - Before designing a feature's screens, ask the user which UI/UX level they want: Simple (the default), Mixed or Premium (`specs/_templates/design.md` describes each). Build them to it.
42
44
  - Ask before adding or upgrading dependencies, and before editing `package.json`, lockfiles, `Podfile`, `build.gradle`, `Info.plist`, `AndroidManifest.xml` or `.github/workflows/`.
43
45
  - Don't hand-edit `ios/*.xcodeproj/project.pbxproj`. If a native file must be added to the Xcode project, stop and ask.
44
46
  - Never read, print or commit `.env` files, keystores, signing files or the files `.amk-secrets` lists. Secrets don't belong in this repo.
45
47
  - Never use `git commit --no-verify`, `git push --force`, `git reset --hard` or `rm -rf`.
48
+ - When `rn-check` (in `verify.sh quick`) reports a problem (✗), show it to the user and let them choose, for each one: fix it, or keep the line with `// amk-ok <today's date>: <their reason>`. Never add an `amk-ok` on your own. One kept over two weeks ago comes back when its file changes again: ask again. Fix the warnings (!) in code the task changed, or tell the user why one stays.
46
49
  - After 2 failed attempts at the same fix, stop and report what you found.
47
50
  - Chat is not memory: write decisions into the spec or `docs/amk/decisions.md` straight away.
48
51
  - Follow `docs/amk/react-native.md`. Before fixing a build error, check `docs/amk/known-issues.md`.
@@ -1,6 +1,6 @@
1
1
  # React Native rules (bare)
2
2
 
3
- Rules for things AI agents commonly get wrong in current React Native. Each one comes from a documented platform change, or from a bug agents keep making on screens.
3
+ Rules for things AI agents commonly get wrong in current React Native. Each one comes from a documented platform change, or from a bug agents keep making on screens. `node scripts/amk/rn-check.js`, which `verify.sh quick` runs, checks the lines a branch changes for some of them.
4
4
 
5
5
  ## Architecture
6
6
 
@@ -16,7 +16,7 @@ Rules for things AI agents commonly get wrong in current React Native. Each one
16
16
  - With the keyboard open, the field being typed in and the button that submits the form stay visible and tappable, on both platforms.
17
17
  - Lists that grow with the user's data scroll (`FlatList`, or the list component the app already uses), and so does any screen taller than a small phone.
18
18
  - At the largest system text size, text wraps instead of being cut off: no fixed heights on views that hold text. Don't turn off font scaling (`allowFontScaling={false}`) to make a layout fit.
19
- - Messages that appear after an action, such as a form error, are read out by screen readers: announce them with `AccessibilityInfo.announceForAccessibility`.
19
+ - Messages that appear after an action, such as a form error, are read out by screen readers. On Android, show the message in a view with `accessibilityLiveRegion="polite"`: Android 16 deprecated announcements. On iOS, announce it with `AccessibilityInfo.announceForAccessibility`.
20
20
  - Check every UI change on both iOS and Android; behavior differs (keyboard, insets, fonts, permissions).
21
21
  - 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.
22
22
  - Give every interactive element an `accessibilityLabel` that says what it does and an `accessibilityRole` (`button`, `link`, `switch`, …), so screen readers can use it. Icon-only buttons need it most; screen readers don't read `testID`.
@@ -30,9 +30,64 @@ Rules for things AI agents commonly get wrong in current React Native. Each one
30
30
  - Lay out by window width: under 600 points (dp on Android), the phone layout; from 600, the tablet layout, with more columns, and a list beside its detail where that helps. Text-heavy content and forms keep a readable width (about 600 to 700 points) instead of stretching edge to edge.
31
31
  - Sizes: when the app already has a way to size things (a scaling helper, or sizes in its theme), use it everywhere and don't mix in another. A new app takes sizes from its theme: spacing and a few text sizes step up from 600 points, and text follows the system font size. Judge the tablet and landscape screenshots like the phone's: each should look made for that screen, not stretched or tiny.
32
32
  - Landscape leaves little height: screens scroll, the keyboard covers more, and the safe-area insets include the left and right edges (the notch or Dynamic Island side).
33
- - Apps targeting Android 16 (API 36) can't lock the orientation or size on tablets and foldables (600 dp wide and up): the system ignores the lock there. So on Android tablets every screen has to work turned, whatever the app's settings say.
33
+ - Android ignores orientation and size locks on tablets and foldables (600 dp wide and up) for apps targeting Android 16 (API 36), and from Android 17 (API 37) apps can't opt out. Apple deprecated `UIRequiresFullScreen` with iPadOS 26, so iPad windows resize too. Every screen has to work at any window size and turned, whatever the app's settings say.
34
34
  - Don't lock the orientation in code to avoid layout work. Which orientations the app supports is a product decision, set in `Info.plist` (`UISupportedInterfaceOrientations`, and `~ipad` for iPads) and the Android manifest (`android:screenOrientation`); the iPad app itself is the Xcode target's device family.
35
35
 
36
+ ## Current React Native and React
37
+
38
+ These changed after most AI training data was written: check them instead of writing from memory.
39
+
40
+ - Removed: `InteractionManager` (0.87; use `requestIdleCallback`), the `StatusBar` props `backgroundColor` and `translucent` (0.87; edge to edge, they did nothing), `Modal`'s `animated` (0.87; `animationType`), a boolean `keyboardShouldPersistTaps` (0.87; `"handled"`) and `StyleSheet.absoluteFillObject` (0.85; `StyleSheet.absoluteFill`).
41
+ - Deprecated, so not in new code: `ImageBackground` (a `View` with an absolutely positioned `Image`), `InputAccessoryView` (`KeyboardStickyView` from `react-native-keyboard-controller`), `DrawerLayoutAndroid` (`react-native-drawer-layout`) and `AccessibilityInfo.setAccessibilityFocus` (`sendAccessibilityEvent`).
42
+ - Import from `react-native` itself. `react-native/Libraries/…` is private, and a type error from 0.87; don't add the `react-native-legacy-deep-imports` opt-out to hide it (it goes after 0.88).
43
+ - Jest: from 0.85 the preset is its own package, `preset: '@react-native/jest-preset'`.
44
+ - React 19: pass `ref` as a prop instead of `forwardRef`, render `<SomeContext value={…}>` instead of `<SomeContext.Provider>`, and use `useEffectEvent` (19.2) instead of turning off `react-hooks/exhaustive-deps`.
45
+ - With the React Compiler on (`babel-plugin-react-compiler` in `babel.config.js`), it memoizes: don't add `memo`, `useMemo` or `useCallback` to new code, and don't remove the ones there as a side task.
46
+ - iOS: apps built with Xcode 27 (the iOS 27 SDK) don't launch without the UIScene life cycle, which React Native supports from 0.88. Below 0.88, build with Xcode 26: moving to 0.88 is a task of its own. From then on, URL and user-activity handling goes in `SceneDelegate`.
47
+ - Android: Google Play takes only apps targeting Android 16 (API 36) or higher (from 31 August 2026). Don't lower `targetSdkVersion` to get out of edge to edge, back handling or orientation changes.
48
+
49
+ ## Errors, storage and effects
50
+
51
+ - Wrap the app in an error boundary (the crash reporter's, or a component with `getDerivedStateFromError`), so a render error shows a screen to recover from instead of a blank or closed app.
52
+ - Every failure reaches the user or the crash reporter: no empty `catch`, and an action started from a button catches its error and shows it, with a way to retry, so a spinner never stays up.
53
+ - Tokens, passwords and keys go in the Keychain and Keystore (`react-native-keychain`), never in AsyncStorage or other plain storage. Anything in the JavaScript bundle can be read by anyone who has the app: no secret keys in code, or in `.env` values the bundle includes.
54
+ - Session replay and analytics mask what users type, and logs leave out tokens and personal data.
55
+ - Effects clean up what they start: timers (`clearTimeout`, `clearInterval`), listeners and subscriptions (return their `remove`), and async work that can finish after the screen closes (an `AbortController`, or a flag the cleanup sets).
56
+ - List keys come from the item's ID, not its index: index keys mix up rows when items are added, removed or reordered.
57
+ - Images go in asset files, never in code as base64 strings: they bloat the bundle, and all of it loads with the JavaScript.
58
+ - Component tests use React Native Testing Library (`@testing-library/react-native`) and find elements as users and screen readers do, by role, label or text (`getByRole('button', { name: 'Save' })`), rather than relying on snapshots.
59
+
60
+ ## Platform guidelines and accessibility
61
+
62
+ From Apple's Human Interface Guidelines, Android's design and app quality guidelines, and WCAG 2.2.
63
+
64
+ - Touch targets: every button, link and control is at least 44×44 points on iOS and 48×48 dp on Android (`minWidth`/`minHeight: 48` covers both): pad a small icon instead of sizing the button to it. `hitSlop` doesn't reach past the parent's bounds, so use it only where the layout can't grow.
65
+ - Text: no `fontSize` under 11, and don't cap scaling below 2× (`maxFontSizeMultiplier`), in `Text.defaultProps`, or in native code (a `fontScale` or content size override).
66
+ - Contrast, in both light and dark: text 4.5:1 against its background (3:1 from 18 points, or 14 bold), and input borders, focus rings and icons that carry meaning 3:1. Colors come from the theme, whose pairs are checked once; a grey like `#999` on white is only 2.8:1.
67
+ - Screen readers: controls show their state in `accessibilityState` (`checked`, `selected`, `expanded`, `disabled`), and screen and section titles have `accessibilityRole="header"`. A label names the action ("Delete photo"), without the role ("button") the reader already says. Put `accessible` on a row that reads as one item, never on one that holds its own buttons. Meaningful images get a label; decorative ones need nothing.
68
+ - Every swipe, drag or long-press action also has a visible button or menu item, and is in `accessibilityActions`. Color is never the only signal: an error shows text, and a state adds an icon or a word.
69
+ - Back: keep swipe back on iOS and the system back on Android. To ask before leaving unsaved changes, use React Navigation's `usePreventRemove`, not `gestureEnabled: false`. A `hardwareBackPress` listener returns `true` only while it closes something on screen; apps don't quit themselves (`BackHandler.exitApp`). Every `Modal` has `onRequestClose`, which Android's back button calls; forms open as sheets (`presentationStyle="pageSheet"`, or the navigator's sheet presentation).
70
+ - Permissions: ask when the user starts the feature that needs it, never at launch or when a screen opens; first say in the app why. When it's denied, say what's unavailable and keep the rest working. When the system won't ask again (`never_ask_again`, `blocked`), the feature's button explains that and offers `Linking.openSettings()`. Ask for notifications (Android 13 and later need `POST_NOTIFICATIONS`) after an action they serve, not on launch.
71
+ - Use the native controls (`@react-native-community/datetimepicker`, `Alert.alert` with verb buttons and `style: 'destructive'` and `'cancel'`, `ActionSheetIOS`, `Switch`); a custom one gets the same role, state and size.
72
+ - Dark mode: colors come from the theme's light and dark values (`useColorScheme()`), not hex values in components; don't lock the app to light.
73
+ - Data screens have loading, empty (why, and what to do next), error (what failed, with Retry) and content states. A message the user has to read doesn't vanish on a timer, and screen readers announce it.
74
+ - Reduce Motion: with it on, nothing loops or moves for decoration. Don't pass `ReduceMotion.Never` to Reanimated for decoration; with `Animated` or Lottie, read `AccessibilityInfo.isReduceMotionEnabled()` and the `reduceMotionChanged` event, and fade or stop instead.
75
+ - iOS 26: use native headers and tab bars (React Navigation's native stack and native tabs), which iOS draws in its current style; don't draw imitation glass behind content, or opt out with `UIDesignRequiresCompatibility` (builds with the iOS 27 SDK ignore it). Nothing the user needs sits under a floating tab bar, button or footer: scroll content gets bottom padding for it.
76
+ - Haptics only for success, error or a selection, never as the only feedback, through the app's haptics library; not `Vibration.vibrate`.
77
+
78
+ ## Store review
79
+
80
+ What App Store review and Google Play reject. `node scripts/amk/release-check.js` checks the project for some of it.
81
+
82
+ - Apps where people can create an account let them start deleting it in the app: a full deletion, not deactivation; a direct link to a web page that finishes it is fine (Apple 5.1.1(v)). Google Play also needs that web link in the Data safety form.
83
+ - A third-party or social login (Google, Facebook) as the main sign-in also needs an equivalent private one, usually Sign in with Apple (4.8); an app that signs in only with the company's own accounts doesn't.
84
+ - Digital content and subscriptions are sold with in-app purchase (3.1.1); physical goods and services aren't. Links to buy elsewhere follow the storefront's current rules.
85
+ - Permission texts (`…UsageDescription`) say what the app does with the data and why, for each use; ask only for what the app uses.
86
+ - The privacy manifest and App Store Connect's privacy details list the data the app and its SDKs collect (analytics, crash reporting, session replay). Tracking needs the App Tracking Transparency prompt first.
87
+ - Google Play restricts these permissions to apps whose core feature needs them, with a declaration in Play Console: photos and videos (`READ_MEDIA_IMAGES`, `READ_MEDIA_VIDEO`: others use the Android photo picker), `QUERY_ALL_PACKAGES`, `MANAGE_EXTERNAL_STORAGE`, SMS and call log, `USE_EXACT_ALARM`, and background location (also a video and an in-app disclosure first). A library can add one: remove it in `AndroidManifest.xml` with `tools:node="remove"` when the app doesn't need it.
88
+ - Android foreground services declare their type (`android:foregroundServiceType`) and its `FOREGROUND_SERVICE_<TYPE>` permission, and each type is declared in Play Console.
89
+ - From 1 February 2027, Google Play takes updates to apps targeting Android 15 or later only with 16 KB page size support, which React Native has from 0.77.
90
+
36
91
  ## TypeScript
37
92
 
38
93
  - Keep the checks `tsconfig.json` has. Don't loosen them, or get past one with `any`, `@ts-ignore` or a non-null `!`.
@@ -0,0 +1,78 @@
1
+ #!/usr/bin/env node
2
+ // Accessibility on the device: from the view trees verify.sh has Maestro save after each screenshot on Android (which
3
+ // marks what's tappable; iOS' tree doesn't), the tappable elements without a label, which a screen reader can't name,
4
+ // and the ones smaller than 48×48 dp, Android's minimum (and more than iOS' 44 points: React Native lays out both
5
+ // alike). An element a scrolling list cuts off at its edge isn't measured. Prints a line each, once per element and
6
+ // kind of problem in a flow: flow, screenshot, problem, element.
7
+ // Usage: node scripts/amk/a11y.js <Maestro debug folder> <screen density in dpi> <flow>
8
+ 'use strict';
9
+ const fs = require('fs');
10
+ const path = require('path');
11
+
12
+ const [dir, dpi, flow] = process.argv.slice(2);
13
+ const scale = Number(dpi) / 160;
14
+ if (!dir || !scale || !fs.existsSync(dir)) process.exit(0);
15
+
16
+ // the trees and the screenshot each follows, in the order the flow saved them. Maestro's commands.json has each step:
17
+ // the view-tree step's id (amk-view-tree-<screenshot>) and the tree it saved; the file's own name is cut short
18
+ const trees = [];
19
+ const files = [];
20
+ (function find(d, depth) {
21
+ for (const e of fs.readdirSync(d, { withFileTypes: true })) {
22
+ const p = path.join(d, e.name);
23
+ if (e.isDirectory() && depth < 4) find(p, depth + 1);
24
+ else files.push(p);
25
+ }
26
+ })(dir, 0);
27
+ for (const f of files.filter(p => path.basename(p) === 'commands.json')) {
28
+ let steps;
29
+ try { steps = JSON.parse(fs.readFileSync(f, 'utf8')); } catch { continue; }
30
+ for (const s of Array.isArray(steps) ? steps : []) {
31
+ const id = ((((s.command || {}).assertConditionCommand || {}).condition || {}).visible || {}).idRegex || '';
32
+ const tree = ((s.metadata || {}).artifacts || []).find(a => a.type === 'SCREEN_HIERARCHY');
33
+ if (id.startsWith('amk-view-tree-') && tree) trees.push([path.join(path.dirname(f), tree.path), id.slice(14)]);
34
+ }
35
+ }
36
+ // without commands.json: the names of the trees' files
37
+ if (!trees.length) {
38
+ for (const p of files.filter(p => /amk-view-tree-.+\.json$/.test(p)).sort((a, b) => path.basename(a).localeCompare(path.basename(b)))) {
39
+ trees.push([p, /amk-view-tree-(.+)\.json$/.exec(path.basename(p))[1]]);
40
+ }
41
+ }
42
+
43
+ // the system's own windows, with everything inside them (the status bar, a keyboard and its suggestions); Android's
44
+ // own ids (android:id/…) only for that element, as the app's views sit inside android:id/content
45
+ const SYSTEM = /^(com\.android\.systemui|com\.google\.android\.inputmethod|com\.android\.inputmethod|com\.samsung\.android\.honeyboard|com\.touchtype\.swiftkey)/;
46
+ const box = a => { const b = /\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]/.exec(a.bounds || ''); return b && b.slice(1).map(Number); };
47
+ const seen = new Set();
48
+ for (const [file, shot] of trees) {
49
+ let tree;
50
+ try { tree = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { continue; }
51
+ // each node with the bounds of the nearest scrolling container around it
52
+ (function walk(n, clip) {
53
+ if (!n) return;
54
+ const a = n.attributes || {};
55
+ if (SYSTEM.test(a['resource-id'] || '')) return;
56
+ const b = box(a);
57
+ if (a.clickable === 'true' && b && !/^android:id\//.test(a['resource-id'] || '')) {
58
+ const [x1, y1, x2, y2] = b;
59
+ const w = (x2 - x1) / scale;
60
+ const h = (y2 - y1) / scale;
61
+ const label = (a.accessibilityText || a.text || a.hintText || '').trim();
62
+ const id = a['resource-id'] || '';
63
+ const name = id ? `testID ${id}` : label ? `"${label}"` : `${a.class || 'an element'} at ${a.bounds}`;
64
+ // once per element and kind of problem in a flow, where it first shows (its size can differ a little later)
65
+ const say = problem => {
66
+ const key = `${id || label}|${problem.startsWith('no label') ? 'label' : 'size'}`; // a testID names it, whatever it shows
67
+ if (!seen.has(key)) { seen.add(key); console.log([flow, shot, problem, name].join('\t')); }
68
+ };
69
+ if (w > 0 && h > 0) {
70
+ if (!label) say('no label: a screen reader can\'t say what it does');
71
+ const cut = clip && (y1 <= clip[1] || y2 >= clip[3] || x1 <= clip[0] || x2 >= clip[2]);
72
+ if (!cut && (w < 47.5 || h < 47.5)) say(`${Math.round(w)}×${Math.round(h)} dp: under 48×48`);
73
+ }
74
+ }
75
+ const inner = a.scrollable === 'true' && b ? b : clip;
76
+ for (const c of n.children || []) walk(c, inner);
77
+ })(tree.root || tree, null);
78
+ }
@@ -161,6 +161,8 @@ const NEEDS = {
161
161
  'expo-location': ['NSLocationWhenInUseUsageDescription'],
162
162
  'expo-contacts': ['NSContactsUsageDescription'],
163
163
  'expo-local-authentication': ['NSFaceIDUsageDescription'],
164
+ 'react-native-tracking-transparency': ['NSUserTrackingUsageDescription'],
165
+ 'expo-tracking-transparency': ['NSUserTrackingUsageDescription'],
164
166
  };
165
167
  // the texts Expo's config plugins write when app.json gives none: too vague for App Review
166
168
  const EXPO_DEFAULT = /^Allow \$\(PRODUCT_NAME\) to /;
@@ -189,7 +191,10 @@ for (const plistPath of Object.keys(textsByPlist)) {
189
191
  }
190
192
  const vague = Object.entries(texts).filter(([, t]) => EXPO_DEFAULT.test(t)).map(([k]) => k);
191
193
  if (vague.length) warn(`${plistPath}: Expo's default text for ${vague.join(', ')}`, 'App Review asks why the app needs each permission: set the text in the library\'s plugin options or ios.infoPlist in app.json');
192
- if (!problems.length && !vague.length && !Object.values(texts).some(t => PLACEHOLDER.test(t))) ok(`${plistPath}: permission texts`, `${Object.keys(texts).length} present`);
194
+ // too short to say what the app does with the data and why ("Camera access")
195
+ const short = Object.entries(texts).filter(([, t]) => t.trim() && t.trim().length < 25 && !PLACEHOLDER.test(t) && !EXPO_DEFAULT.test(t));
196
+ for (const [key, text] of short) warn(`${plistPath}: ${key} is short ("${text.trim()}")`, 'say what the app does with it and why, for each use; App Review rejects vague texts (5.1.1)');
197
+ if (!problems.length && !vague.length && !short.length && !Object.values(texts).some(t => PLACEHOLDER.test(t))) ok(`${plistPath}: permission texts`, `${Object.keys(texts).length} present`);
193
198
  const arbitrary = expo ? (expoPlist.NSAppTransportSecurity || {}).NSAllowsArbitraryLoads === true
194
199
  : /<key>NSAllowsArbitraryLoads<\/key>\s*<true\s*\/>/.test(readNow(plistPath) || '');
195
200
  if (arbitrary) {
@@ -199,7 +204,9 @@ for (const plistPath of Object.keys(textsByPlist)) {
199
204
 
200
205
  // ---------- 4. Android permissions ----------
201
206
  const SENSITIVE = /\.(ACCESS_(FINE|COARSE|BACKGROUND)_LOCATION|CAMERA|RECORD_AUDIO|READ_CONTACTS|WRITE_CONTACTS|READ_EXTERNAL_STORAGE|WRITE_EXTERNAL_STORAGE|READ_MEDIA_\w+|BLUETOOTH_SCAN|BLUETOOTH_CONNECT|POST_NOTIFICATIONS|READ_PHONE_STATE|BODY_SENSORS|READ_CALENDAR|WRITE_CALENDAR|ACCESS_MEDIA_LOCATION)$/;
202
- const perms = t => all(/<uses-permission[^>]*android:name="([^"]+)"/g, t);
207
+ // what the manifest asks for: not the ones it removes (tools:node="remove", for a permission a library adds)
208
+ const perms = t => uniq([...(t || '').matchAll(/<uses-permission\b[^>]*>/g)].map(m => m[0]).filter(p => !/tools:node="remove"/.test(p))
209
+ .map(p => (/android:name="([^"]+)"/.exec(p) || [])[1]).filter(Boolean));
203
210
  // Expo: the manifest prebuild would write, as JSON
204
211
  const expoManifest = ((expoResults.android || {}).manifest || {}).manifest;
205
212
  const permsNow = expo ? uniq(((expoManifest || {})['uses-permission'] || []).map(p => p.$['android:name'])) : perms(readNow(manifestPath));
@@ -274,6 +281,146 @@ for (const f of noteFiles) {
274
281
  }
275
282
  if (!noteFiles.length) info('No store release notes yet', 'run the m-release skill to write them from the changelog');
276
283
 
284
+ // ---------- 8. store review rules ----------
285
+ // what App Store review and Google Play policy reject that the project shows. Most need a person to judge (an
286
+ // exception, an approved Play declaration), so they warn
287
+ const found = names => names.filter(n => deps[n]);
288
+ const sourceFiles = (git('ls-files', '--', '*.js', '*.jsx', '*.ts', '*.tsx') || '').split('\n')
289
+ .filter(f => f && !/(^|\/)(node_modules|scripts\/amk|__tests__|__mocks__|e2e|ios|android)\//.test(f) && !/\.(test|spec)\.\w+$/.test(f));
290
+ const source = sourceFiles.map(f => readNow(f) || '').join('\n');
291
+ // a sign-up in code (a call, a screen, an API path), not the words in a comment or in text ("No account, no sign-up")
292
+ const SIGN_UP = /\b(signUp|signup|createAccount|createUserWithEmailAndPassword|registerUser|registerAccount)\s*\(|\b(name|screen)\s*[:=]\s*\{?\s*['"](SignUp|Signup|Register|Registration|CreateAccount)['"]|navigate\(\s*['"](SignUp|Signup|Register|Registration|CreateAccount)['"]|['"`][^'"`\s]*\/(sign-?up|register|registration|create-?account)\b/i;
293
+ const rnVersion = (() => { try { return require(path.resolve('node_modules/react-native/package.json')).version; } catch { return (deps['react-native'] || '').replace(/^[^\d]*/, ''); } })();
294
+ const [rnMajor, rnMinor] = rnVersion.split('.').map(Number);
295
+ const rnBelow = minor => rnMajor === 0 && rnMinor < minor;
296
+ let storeFindings = 0;
297
+ const storeWarn = (label, fix) => { storeFindings++; warn(label, fix); };
298
+
299
+ // Apple
300
+ if (SIGN_UP.test(stripComments(source))
301
+ && !/delete[ _-]?(my[ _-]?)?account|account[ _-]?deletion|deleteUser|close[ _-]?account|remove[ _-]?account/i.test(source)) {
302
+ storeWarn('The app has a sign-up, but no account deletion was found in its code', 'people who can create an account must be able to start deleting it in the app (Apple 5.1.1(v)); Google Play also needs a web link to it in the Data safety form');
303
+ }
304
+ const social = [...found(['@react-native-google-signin/google-signin', 'react-native-fbsdk-next']),
305
+ ...(/expo-auth-session\/providers\/(google|facebook)/.test(source) ? ['expo-auth-session'] : [])];
306
+ const entitlements = fs.existsSync('ios') ? fs.readdirSync('ios', { withFileTypes: true }).filter(e => e.isDirectory())
307
+ .flatMap(e => fs.readdirSync(`ios/${e.name}`).filter(f => f.endsWith('.entitlements')).map(f => readNow(`ios/${e.name}/${f}`) || '')) : [];
308
+ const appleSignIn = found(['expo-apple-authentication', '@invertase/react-native-apple-authentication']).length
309
+ || entitlements.some(e => e.includes('com.apple.developer.applesignin')) || ((expo || {}).ios || {}).usesAppleSignIn;
310
+ if (social.length && !appleSignIn) {
311
+ storeWarn(`A social login (${social.join(', ')}) without Sign in with Apple`, 'App Review needs an equivalent private login next to it, usually Sign in with Apple (4.8); fine if the app signs in only with the company\'s own accounts');
312
+ }
313
+ const trackers = found(['react-native-fbsdk-next', 'react-native-appsflyer', 'react-native-adjust', 'react-native-google-mobile-ads']);
314
+ const allTexts = Object.values(textsByPlist).flatMap(Object.keys);
315
+ if (trackers.length && !found(['react-native-tracking-transparency', 'expo-tracking-transparency']).length && !allTexts.includes('NSUserTrackingUsageDescription')) {
316
+ storeWarn(`${trackers.join(', ')} can track people across apps, and the app has no App Tracking Transparency prompt`, 'ask with the ATT prompt first (react-native-tracking-transparency or expo-tracking-transparency) and set NSUserTrackingUsageDescription (5.1.2)');
317
+ }
318
+ const privacy = expo ? [['app config (ios.privacyManifests)', (expo.ios || {}).privacyManifests || {}]]
319
+ : (fs.existsSync('ios') ? fs.readdirSync('ios', { withFileTypes: true }) : []).filter(e => e.isDirectory() && fs.existsSync(`ios/${e.name}/PrivacyInfo.xcprivacy`))
320
+ .map(e => [`ios/${e.name}/PrivacyInfo.xcprivacy`, readNow(`ios/${e.name}/PrivacyInfo.xcprivacy`) || '']);
321
+ const collectors = found(['@react-native-firebase/analytics', '@react-native-firebase/crashlytics', '@sentry/react-native', '@amplitude/analytics-react-native',
322
+ '@segment/analytics-react-native', 'posthog-react-native', 'mixpanel-react-native', '@microsoft/react-native-clarity', '@datadog/mobile-react-native',
323
+ '@bugsnag/react-native', '@intercom/intercom-react-native', 'react-native-appsflyer', 'react-native-fbsdk-next']);
324
+ for (const [where, m] of privacy) {
325
+ const xml = typeof m === 'string';
326
+ const tracking = xml ? /<key>NSPrivacyTracking<\/key>\s*<true\s*\/>/.test(m) : m.NSPrivacyTracking === true;
327
+ const domains = xml ? /<key>NSPrivacyTrackingDomains<\/key>\s*<array>\s*<string>/.test(m) : (m.NSPrivacyTrackingDomains || []).length > 0;
328
+ const collected = xml ? /<key>NSPrivacyCollectedDataTypes<\/key>\s*<array>\s*<dict>/.test(m) : (m.NSPrivacyCollectedDataTypes || []).length > 0;
329
+ if (tracking && !domains) fail(`${where}: NSPrivacyTracking is true but lists no NSPrivacyTrackingDomains`, 'list the domains the app tracks with; Apple needs them when tracking is on');
330
+ if (!collected && collectors.length) storeWarn(`${where} lists no collected data, and ${collectors.join(', ')} collect some`, 'make sure App Store Connect\'s privacy details (and this manifest, where the SDK\'s own doesn\'t) list it: names, emails, usage data, crash data, recordings');
331
+ }
332
+ const plistFlags = expo ? [['app config (ios.infoPlist)', expoPlist]] : plists.map(p => [p, readNow(p) || '']);
333
+ for (const [where, p] of plistFlags) {
334
+ const on = key => (typeof p === 'string' ? new RegExp(`<key>${key}</key>\\s*<true\\s*/>`).test(p) : p[key] === true);
335
+ if (on('UIDesignRequiresCompatibility')) storeWarn(`${where}: UIDesignRequiresCompatibility opts out of iOS 26's design`, 'builds with the iOS 27 SDK ignore it: make the app work with the current design');
336
+ if (on('UIRequiresFullScreen')) storeWarn(`${where}: UIRequiresFullScreen is deprecated (iPadOS 26)`, 'iPad windows resize anyway: make every screen adapt to the window');
337
+ }
338
+ const nativeCaps = [...(git('grep', '-l', '-E', 'override +var +preferredContentSizeCategory|\\(UIContentSizeCategory\\) *preferredContentSizeCategory', '--', 'ios/*.swift', 'ios/*.m', 'ios/*.mm') || '').split('\n'),
339
+ ...(git('grep', '-l', '-E', 'fontScale *= *[^= ]', '--', 'android/*.kt', 'android/*.java') || '').split('\n')].filter(f => f && !f.includes('/Pods/'));
340
+ if (nativeCaps.length) storeWarn(`Native code caps the user's text size: ${nativeCaps.join(', ')}`, 'people who pick a large text size get a smaller one; let text scale, and make layouts wrap');
341
+ if (rnVersion && rnBelow(88)) info(`React Native ${rnVersion}: apps built with Xcode 27 (the iOS 27 SDK) don't launch below 0.88`, 'App Store uploads move to each new Xcode from a date Apple announces: upgrade React Native before then');
342
+ const payments = found(['@stripe/stripe-react-native', 'react-native-razorpay', 'react-native-paypal', 'react-native-braintree-dropin-ui']);
343
+ if (payments.length && !found(['react-native-iap', 'react-native-purchases', 'expo-iap', 'expo-in-app-purchases']).length) {
344
+ info(`${payments.join(', ')} without in-app purchase`, 'fine for physical goods and services; digital content and subscriptions need in-app purchase (3.1.1)');
345
+ }
346
+
347
+ // Google: every permission the release build gets: the app's manifests and its libraries' (Gradle merges them), less
348
+ // what the app removes. A release build's merged manifest already is that, when it's newer than what it was built from
349
+ function walk(dir, keep, depth = 0) {
350
+ if (depth > 6 || !fs.existsSync(dir)) return [];
351
+ return fs.readdirSync(dir, { withFileTypes: true }).flatMap(e => (e.isDirectory() ? walk(`${dir}/${e.name}`, keep, depth + 1) : keep(`${dir}/${e.name}`) ? [`${dir}/${e.name}`] : []));
352
+ }
353
+ const tags = (t, name) => [...(t || '').matchAll(new RegExp(`<${name}\\b[^>]*>`, 'g'))].map(m => m[0]);
354
+ const attr = (tag, a) => (new RegExp(`${a}="([^"]+)"`).exec(tag) || [])[1];
355
+ const mtime = f => { try { return fs.statSync(f).mtimeMs; } catch { return 0; } };
356
+ const ownManifests = expo ? [] : (fs.existsSync('android/app/src') ? fs.readdirSync('android/app/src') : [])
357
+ .map(d => `android/app/src/${d}/AndroidManifest.xml`).filter(f => fs.existsSync(f));
358
+ const intermediates = 'android/app/build/intermediates';
359
+ const built = expo || !fs.existsSync(intermediates) ? [] : fs.readdirSync(intermediates).filter(d => /^merged_manifests?$/.test(d))
360
+ .flatMap(d => walk(`${intermediates}/${d}`, f => /release/i.test(f) && f.endsWith('AndroidManifest.xml')));
361
+ const sourcesTime = Math.max(...[...ownManifests, 'package.json', gradlePath].filter(Boolean).map(mtime));
362
+ const merged = built.filter(f => mtime(f) >= sourcesTime);
363
+ const appManifests = merged.length ? merged : ownManifests;
364
+ const libManifests = merged.length ? [] : Object.keys(deps).map(d => [d, readNow(`node_modules/${d}/android/src/main/AndroidManifest.xml`)]).filter(([, t]) => t);
365
+ const removed = new Set([...ownManifests.flatMap(f => tags(readNow(f), 'uses-permission').filter(p => /tools:node="remove"/.test(p)).map(p => attr(p, 'android:name'))),
366
+ ...(expo ? ((expoManifest || {})['uses-permission'] || []).filter(p => p.$['tools:node'] === 'remove').map(p => p.$['android:name']) : []),
367
+ ...(((expo || {}).android || {}).blockedPermissions || [])]);
368
+ const granted = new Map();
369
+ const grant = (name, from) => { if (name && !removed.has(name)) granted.set(name, [...new Set([...(granted.get(name) || []), from])]); };
370
+ if (expo) for (const p of (expoManifest || {})['uses-permission'] || []) { if (p.$['tools:node'] !== 'remove') grant(p.$['android:name'], 'the app config'); }
371
+ for (const f of appManifests) for (const p of tags(readNow(f), 'uses-permission').filter(x => !/tools:node="remove"/.test(x))) grant(attr(p, 'android:name'), merged.length ? 'the merged release manifest' : f);
372
+ for (const [lib, t] of libManifests) for (const p of tags(t, 'uses-permission')) grant(attr(p, 'android:name'), lib);
373
+ const permName = n => n.replace(/^android\.permission\./, '');
374
+ const RESTRICTED = {
375
+ READ_MEDIA_IMAGES: 'only for apps built around broad access to photos; others use the Android photo picker, which needs no permission',
376
+ READ_MEDIA_VIDEO: 'only for apps built around broad access to videos; others use the Android photo picker, which needs no permission',
377
+ QUERY_ALL_PACKAGES: 'list the apps it needs to see in <queries> instead',
378
+ MANAGE_EXTERNAL_STORAGE: 'picking files or media isn\'t an allowed use: use the system pickers',
379
+ READ_SMS: 'only for the default SMS app: one-time codes use the SMS Retriever API', RECEIVE_SMS: 'only for the default SMS app: one-time codes use the SMS Retriever API',
380
+ SEND_SMS: 'only for the default SMS app', RECEIVE_MMS: 'only for the default SMS app', RECEIVE_WAP_PUSH: 'only for the default SMS app', WRITE_SMS: 'only for the default SMS app',
381
+ READ_CALL_LOG: 'only for the default phone app', WRITE_CALL_LOG: 'only for the default phone app', PROCESS_OUTGOING_CALLS: 'only for the default phone app',
382
+ USE_EXACT_ALARM: 'only for alarm, timer and calendar apps: others use SCHEDULE_EXACT_ALARM, and check canScheduleExactAlarms',
383
+ ACCESS_BACKGROUND_LOCATION: 'needs a Play Console declaration for one feature, a short video, and a prominent disclosure in the app before asking',
384
+ REQUEST_INSTALL_PACKAGES: 'needs a Play Console declaration', USE_FULL_SCREEN_INTENT: 'only for calls and alarms',
385
+ };
386
+ const remove = expo ? 'list it in android.blockedPermissions' : 'remove it (tools:node="remove" for one a library adds)';
387
+ for (const [name, from] of granted) {
388
+ const why = RESTRICTED[permName(name)];
389
+ if (why) storeWarn(`Google Play restricts ${permName(name)} (from ${from.join(', ')})`, `${why}; keep it only with an approved Play Console declaration, otherwise ${remove}`);
390
+ }
391
+ // foreground services: each declares its type, and each FOREGROUND_SERVICE_<TYPE> permission has a service of that type
392
+ // the app's own services (a merged manifest also has every library's, which declare their own types)
393
+ const services = [...ownManifests.flatMap(f => tags(readNow(f), 'service').map(s => [s, f])),
394
+ ...(expo ? ((((expoManifest || {}).application || [])[0] || {}).service || []).map(s => [`<service ${Object.entries(s.$ || {}).map(([k, v]) => `${k}="${v}"`).join(' ')}>`, 'the app config']) : [])];
395
+ const typeName = v => v.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase();
396
+ const allServices = [...services, ...merged.flatMap(f => tags(readNow(f), 'service').map(s => [s, f])), ...libManifests.flatMap(([lib, t]) => tags(t, 'service').map(s => [s, lib]))];
397
+ const types = new Set(allServices.flatMap(([s]) => (attr(s, 'android:foregroundServiceType') || '').split('|').filter(Boolean).map(typeName)));
398
+ if ([...granted.keys()].some(n => permName(n).startsWith('FOREGROUND_SERVICE'))) {
399
+ // once per service, wherever it's declared (the main manifest and a flavor's, say)
400
+ const untyped = new Map();
401
+ for (const [s, from] of services.filter(([s]) => !attr(s, 'android:foregroundServiceType'))) {
402
+ const name = attr(s, 'android:name') || 'a service';
403
+ untyped.set(name, [...(untyped.get(name) || []), from]);
404
+ }
405
+ for (const [name, from] of untyped) {
406
+ storeWarn(`${name} has no android:foregroundServiceType (${from.join(', ')})`, 'if it runs in the foreground, declare its type and the matching FOREGROUND_SERVICE_<TYPE> permission: from Android 14, starting it without one crashes');
407
+ }
408
+ for (const n of [...granted.keys()].map(permName).filter(n => /^FOREGROUND_SERVICE_./.test(n))) {
409
+ if (!types.has(n.replace('FOREGROUND_SERVICE_', ''))) storeWarn(`${n} is declared, but no service has that type`, 'give the service that does this work the matching android:foregroundServiceType, or remove the permission');
410
+ }
411
+ if (types.size) info(`Foreground service types to declare in Play Console: ${[...types].join(', ')}`);
412
+ }
413
+ if (rnVersion && rnBelow(77)) {
414
+ const due = Date.now() >= Date.parse('2027-02-01');
415
+ (due ? fail : warn)(`React Native ${rnVersion} has no 16 KB page size support (from 0.77)`, 'from 1 February 2027 Google Play takes updates to apps targeting Android 15 or later only with it: upgrade React Native');
416
+ if (!due) storeFindings++;
417
+ }
418
+ const notifiers = found(['@react-native-firebase/messaging', '@notifee/react-native', 'react-native-push-notification', 'expo-notifications', 'react-native-onesignal', 'react-native-notifications']);
419
+ if (notifiers.length && !/requestPermission|requestPermissionsAsync|requestNotifications|POST_NOTIFICATIONS|requestUserPermission/.test(source)) {
420
+ storeWarn(`${notifiers.join(', ')}, but the code never asks for permission to notify`, 'Android 13 and later show notifications only once the user allows them: ask after an action they serve');
421
+ }
422
+ if (!storeFindings) ok('Store review rules', 'nothing found');
423
+
277
424
  // ---------- report ----------
278
425
  const icon = { ok: '✓', info: '·', warn: '!', fail: '✗' };
279
426
  console.log(`Release check${since ? ` (compared with ${since})` : ''}`);
@@ -0,0 +1,78 @@
1
+ #!/usr/bin/env node
2
+ // A device check's report, from its evidence folder (.amk/evidence/<label>/): report.md for people (each screen, its
3
+ // flows, passed or failed and why, and their screenshots) and junit.xml for CI. --summary prints a short Markdown
4
+ // table instead, for a CI job's summary. verify.sh runs it after each device check, and builds it from what's on disk,
5
+ // so devices and parts checked at the same time all end up in it: each screen's flows are in <screen>/.flows (or
6
+ // <screen>/part-<k>/.flows), a line each: name, passed or failed, why, its screenshots, the screen when it failed.
7
+ // Usage: node scripts/amk/report.js <evidence folder> [--summary]
8
+ 'use strict';
9
+ const fs = require('fs');
10
+ const path = require('path');
11
+
12
+ const [dir, mode] = process.argv.slice(2);
13
+ if (!dir || !fs.existsSync(dir)) {
14
+ console.error('usage: node scripts/amk/report.js <evidence folder> [--summary]');
15
+ process.exit(2);
16
+ }
17
+ const label = path.basename(path.resolve(dir));
18
+ const read = f => { try { return fs.readFileSync(f, 'utf8'); } catch { return null; } };
19
+
20
+ // the screens: <screen>/.flows, and <screen>/part-<k>/.flows for a device's flows split in parts
21
+ const screens = [];
22
+ for (const s of fs.readdirSync(dir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name).sort()) {
23
+ for (const sub of ['', ...(fs.readdirSync(path.join(dir, s)).filter(p => /^part-\d+$/.test(p)).sort())]) {
24
+ const text = read(path.join(dir, s, sub, '.flows'));
25
+ if (text === null) continue;
26
+ // what the view trees showed on Android: flow, screenshot, problem, element (a11y.js)
27
+ const a11y = (read(path.join(dir, s, sub, '.a11y')) || '').split('\n').filter(Boolean).map(l => l.split('\t'));
28
+ const flows = text.split('\n').filter(Boolean).map(l => {
29
+ const [name, result, why, shots, shot] = l.split('\t');
30
+ return { name, passed: result === 'passed', why: why || '', shots: (shots || '').split(',').filter(Boolean), shot: shot || '',
31
+ a11y: a11y.filter(x => x[0] === name).map(([, at, problem, element]) => ({ at, problem, element })) };
32
+ });
33
+ screens.push({ name: sub ? `${s} (${sub.replace('-', ' ')})` : s, dir: sub ? `${s}/${sub}` : s, flows });
34
+ }
35
+ }
36
+ const all = screens.flatMap(s => s.flows);
37
+ const failed = all.filter(f => !f.passed);
38
+ const counts = s => `${s.flows.filter(f => f.passed).length}/${s.flows.length}`;
39
+ const table = ['| Screen | Flows passed | Screenshots |', '|---|---|---|',
40
+ ...screens.map(s => `| ${s.name} | ${counts(s)}${s.flows.every(f => f.passed) ? '' : ' ✗'} | ${s.flows.reduce((n, f) => n + f.shots.length, 0)} |`)];
41
+ const warned = all.reduce((n, f) => n + f.a11y.length, 0);
42
+ const headline = `${all.length - failed.length} of ${all.length} flows passed on ${screens.length} screen${screens.length === 1 ? '' : 's'}${warned ? `, ${warned} accessibility warning${warned === 1 ? '' : 's'}` : ''}`;
43
+
44
+ if (mode === '--summary') {
45
+ console.log([`### Device checks: ${label}`, '', headline, '', ...table, '',
46
+ ...failed.map(f => `- ✗ ${screens.find(s => s.flows.includes(f)).name}: ${f.name}${f.why ? `, failed ${f.why}` : ''}`)].join('\n'));
47
+ process.exit(0);
48
+ }
49
+
50
+ // a path inside the evidence folder, for a link from report.md, which sits in it
51
+ const link = p => p.split('/').map(encodeURIComponent).join('/');
52
+ const md = [`# Device checks: ${label}`, '', `${new Date().toISOString().slice(0, 16).replace('T', ' ')} UTC · ${headline}`, '', ...table];
53
+ for (const s of screens) {
54
+ md.push('', `## ${s.name}`);
55
+ for (const f of s.flows) {
56
+ md.push('', `### ${f.passed ? '✓' : '✗'} ${f.name}`);
57
+ if (!f.passed) {
58
+ md.push('', `Failed${f.why ? ` ${f.why}` : ''}. Log: [${s.dir}/${f.name}.log](${link(`${s.dir}/${f.name}.log`)})${f.shot ? ` · [the screen when it failed](${link(f.shot)})` : ''}`);
59
+ }
60
+ if (f.shots.length) md.push('', f.shots.map(p => `<img src="${link(p)}" width="180" alt="${path.basename(p, '.png')}" title="${path.basename(p, '.png')}">`).join(' '));
61
+ if (f.a11y.length) md.push('', 'Accessibility, from the screen\'s view tree:', '', ...f.a11y.map(x => `- ${x.at}: ${x.element}: ${x.problem}`));
62
+ }
63
+ }
64
+ fs.writeFileSync(path.join(dir, 'report.md'), `${md.join('\n')}\n`);
65
+
66
+ const xml = s => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
67
+ fs.writeFileSync(path.join(dir, 'junit.xml'), [
68
+ '<?xml version="1.0" encoding="UTF-8"?>',
69
+ `<testsuites name="${xml(label)}" tests="${all.length}" failures="${failed.length}">`,
70
+ ...screens.flatMap(s => [
71
+ ` <testsuite name="${xml(s.name)}" tests="${s.flows.length}" failures="${s.flows.filter(f => !f.passed).length}">`,
72
+ ...s.flows.map(f => (f.passed ? ` <testcase classname="${xml(s.name)}" name="${xml(f.name)}"/>`
73
+ : ` <testcase classname="${xml(s.name)}" name="${xml(f.name)}"><failure message="${xml(f.why || 'failed')}"/></testcase>`)),
74
+ ' </testsuite>',
75
+ ]),
76
+ '</testsuites>', '',
77
+ ].join('\n'));
78
+ console.log(`${headline}: ${path.join(dir, 'report.md')}`);