agentic-mobile-kit 0.7.6 → 0.7.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentic-mobile-kit",
3
- "version": "0.7.6",
3
+ "version": "0.7.7",
4
4
  "description": "One setup for AI-assisted development of React Native apps, bare or Expo: shared rules and workflows for Claude Code, Codex and Antigravity, git hooks, device checks with screenshots, and release tooling for the App Store and Google Play.",
5
5
  "license": "MIT",
6
6
  "author": "prakashpro1",
@@ -1,6 +1,6 @@
1
1
  # Expo rules
2
2
 
3
- Rules for things AI agents commonly get wrong in Expo apps. Each one comes from a documented platform change.
3
+ Rules for things AI agents commonly get wrong in Expo apps. Each one comes from a documented platform change, or from a bug agents keep making on screens.
4
4
 
5
5
  ## Expo changes with every SDK
6
6
 
@@ -26,6 +26,10 @@ Rules for things AI agents commonly get wrong in Expo apps. Each one comes from
26
26
  - Use `react-native-safe-area-context` for safe areas. React Native's built-in `SafeAreaView` is deprecated and iOS-only.
27
27
  - Android draws edge to edge (Android 15 and later), so handle top and bottom insets on every screen.
28
28
  - For apps targeting Android 16 (API 36), `onBackPressed` is no longer called. Handle back with `BackHandler` in JS.
29
+ - With the keyboard open, the field being typed in and the button that submits the form stay visible and tappable, on both platforms.
30
+ - 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.
31
+ - 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.
32
+ - Messages that appear after an action, such as a form error, are read out by screen readers: announce them with `AccessibilityInfo.announceForAccessibility`.
29
33
  - Check every UI change on both iOS and Android; behavior differs (keyboard, insets, fonts, permissions).
30
34
  - 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
35
  - 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`.
@@ -14,5 +14,5 @@ Input: $ARGUMENTS (a problem, a question about how something works, or an idea t
14
14
  2. **Explain what's there today:** the screens, state, API calls and native parts involved, and where iOS and Android differ.
15
15
  3. **When there's a choice, lay out options:** two or three, each with its trade-offs (effort, risk, both platforms, native changes, store review, what it leaves unsolved). Say which one you'd pick and why. Diagrams help when the flow is complicated.
16
16
  4. **Change nothing.** Exploring never edits code, config or project files. Write notes only when the user asks: a draft in `specs/<id>/requirements.md` for `m-feature`, or a decision in `docs/amk/decisions.md`.
17
- 5. **Confirm what's final, and write it down in one place.** When the exploration settled or changed what the app must do, ask the user whether these requirements are now final; don't assume it. Once they say yes, write them where the next workflow reads them, and tell the user the path: for the whole app, every feature with its rules in `docs/amk/product.md`, each marked planned until `m-feature` ships it; for one feature, a draft in `specs/<id>/requirements.md`. `decisions.md` logs choices and their reasons; it isn't the requirements document.
17
+ 5. **Confirm what's final, and write it down in one place.** When the exploration settled or changed what the app must do, ask the user whether these requirements are now final; don't assume it. Once they say yes, write them where the next workflow reads them, and tell the user the path: for the whole app, every feature with its rules in `docs/amk/product.md`, each marked planned until `m-feature` ships it; for one feature, a draft in `specs/<id>/requirements.md`. `decisions.md` logs choices and their reasons; it isn't the requirements document. Then offer to commit those files on their own, so the next feature's branch starts from them instead of carrying them along uncommitted.
18
18
  6. **Hand off when it's clear.** Suggest the next step: `m-feature <one-line summary>`, `m-change <one-line summary>` for a small change, `m-prototype <one-line summary>` when it needs a demo or a design before it's built, or `m-bugfix <one-line summary>`, carrying over what you found. If the idea turns out not to be worth doing, say so; learning that cheaply is a good outcome.
@@ -45,7 +45,7 @@ From here the plan lives in files, so the building can also run in a fresh sessi
45
45
  ## 4. Build, one task at a time
46
46
 
47
47
  For each task:
48
- 1. Implement only that task. Write tests first for logic (state, data, utils); UI can be tested after.
48
+ 1. Implement only that task. Write tests first for logic (state, data, utils); UI can be tested after. Build screens to the screen rules in the React Native rules file `AGENTS.md` names (keyboard, system bars, scrolling, large text, announced messages): they're the bugs device checks and reviews find most.
49
49
  2. Run `lint`, `typecheck` and `test` (see AGENTS.md). Paste the real output. If something fails, fix it; after 2 failed attempts, stop and report.
50
50
  3. Commit with a clear message ending in `Spec: specs/<id>`.
51
51
  4. Tick the task in `tasks.md` and update the handoff block and log in `progress.md`.
@@ -21,7 +21,8 @@ If your tool has subagents, hand the review to the `m-reviewer` subagent, so it
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
  - **Both platforms:** anything iOS-only or Android-only (insets, back button, permissions, keyboard)?
24
- - **Accessibility:** does every new button or other touchable have an `accessibilityLabel` and an `accessibilityRole`?
24
+ - **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?
25
+ - **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?
25
26
  - **Errors and states:** offline, server errors, empty and loading states.
26
27
  - **Security:** secrets, tokens, `.env` contents, logging of personal data.
27
28
  - **Native:** `project.pbxproj`, `Podfile`, Gradle or manifest changes, and whether pods and builds were re-run.
@@ -9,7 +9,7 @@ claudecode:
9
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` and `git show`.
10
10
 
11
11
  1. Get the changes: `git diff main...HEAD`. If a spec exists in `specs/<id>/`, read its `requirements.md`.
12
- 2. Check scope, tests (added, deleted, weakened), iOS vs Android differences, error and empty states, secrets, native file changes, and performance.
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), accessibility (labels and roles, messages announced to screen readers), error and empty states, secrets, 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".
@@ -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.
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.
4
4
 
5
5
  ## Architecture
6
6
 
@@ -13,6 +13,10 @@ Rules for things AI agents commonly get wrong in current React Native. Each one
13
13
  - Use `react-native-safe-area-context` for safe areas. React Native's built-in `SafeAreaView` is deprecated and iOS-only.
14
14
  - Android draws edge to edge (Android 15 and later), so handle top and bottom insets on every screen.
15
15
  - For apps targeting Android 16 (API 36), `onBackPressed` is no longer called. Handle back with `BackHandler` in JS, or `OnBackPressedDispatcher` in native code.
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
+ - 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
+ - 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`.
16
20
  - Check every UI change on both iOS and Android; behavior differs (keyboard, insets, fonts, permissions).
17
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.
18
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`.
@@ -13,7 +13,7 @@
13
13
  # --scheme <name> iOS scheme to check (default: the one named like the workspace)
14
14
  # (no flows found: a smoke check that launches the app and takes a screenshot)
15
15
  # Env: AMK_ANDROID_FLAVOR, AMK_IOS_SCHEME (defaults for the two options), AMK_IOS_DEVICE (simulator name
16
- # or UDID), AMK_ANDROID_DEVICE (adb serial: the only way to check on a phone while an emulator exists),
16
+ # or UDID), AMK_ANDROID_DEVICE (adb serial: the only way to check on a phone, whose app data the flows clear),
17
17
  # AMK_ANDROID_AVD (the emulator to use, started if it isn't running; other devices are left alone)
18
18
  # Flows that log in read ${MAESTRO_EMAIL} and the like from a local, gitignored .maestro/.env.local (never committed).
19
19
  set -eu
@@ -48,6 +48,15 @@ flow_files() {
48
48
  fi
49
49
  }
50
50
 
51
+ run_flow() { # platform device app_id file name
52
+ # Maestro's own log, which has errors its output leaves out; it adds to the file, so one run's log at a time
53
+ debug="$evidence/maestro-logs/$1-$5"
54
+ rm -f "$debug/maestro.log"
55
+ # screenshots use relative names: older Maestro saves them in the current folder, newer in --test-output-dir
56
+ (cd "$out" && maestro --device "$2" test --test-output-dir "$out" --debug-output "$debug" --flatten-debug-output \
57
+ -e APP_ID="$3" "$4" > "$out/$5.log" 2>&1)
58
+ }
59
+
51
60
  run_flows() { # platform device app_id
52
61
  out="$evidence/$1"
53
62
  mkdir -p "$out"
@@ -63,11 +72,20 @@ run_flows() { # platform device app_id
63
72
  for f in $files; do
64
73
  total=$((total + 1))
65
74
  name=$(basename "$f" .yaml)
66
- # screenshots use relative names: older Maestro saves them in the current folder, newer in --test-output-dir
67
- if (cd "$out" && maestro --device "$2" test --test-output-dir "$out" -e APP_ID="$3" "$f" > "$out/$name.log" 2>&1); then
75
+ ok=0
76
+ run_flow "$@" "$f" "$name" || ok=$?
77
+ # an emulator sometimes drops its adb connection for a moment: reconnect, then run the flow once more
78
+ if [ "$ok" != 0 ] && [ "$1" = android ] && grep -qs 'device offline' "$debug/maestro.log"; then
79
+ echo " android: the device went offline during flow $name; running it once more"
80
+ "$adb" reconnect offline > /dev/null 2>&1 || true
81
+ android_ready "$2" || true
82
+ ok=0
83
+ run_flow "$@" "$f" "$name" || ok=$?
84
+ fi
85
+ if [ "$ok" = 0 ]; then
68
86
  passed=$((passed + 1))
69
87
  else
70
- echo " $1: flow $name failed, see ${out#"$root"/}/$name.log"
88
+ echo " $1: flow $name failed, see ${out#"$root"/}/$name.log and Maestro's own log ${debug#"$root"/}/maestro.log"
71
89
  status=1
72
90
  fi
73
91
  done
@@ -144,6 +162,16 @@ running_emulator() {
144
162
  done
145
163
  }
146
164
 
165
+ # waits for the Android device $1 to finish starting, for up to 5 minutes
166
+ android_ready() {
167
+ tries=0
168
+ until [ "$("$adb" -s "$1" shell getprop sys.boot_completed 2> /dev/null | tr -d '\r')" = 1 ]; do
169
+ tries=$((tries + 1))
170
+ [ "$tries" -le 100 ] || return 1
171
+ sleep 3
172
+ done
173
+ }
174
+
147
175
  android() {
148
176
  command -v maestro > /dev/null || { echo "android: Maestro isn't installed (https://maestro.dev)"; status=1; return; }
149
177
  case $(uname -s) in # where Android Studio puts the SDK by default
@@ -171,8 +199,7 @@ android() {
171
199
  fi
172
200
  variant=$(printf %s "$flavor" | awk '{ print toupper(substr($0, 1, 1)) substr($0, 2) }')
173
201
  # the device first: the build only needs its CPU type, and an emulator boots while Gradle builds.
174
- # The flows clear the app's data, so an emulator comes before a phone plugged in over USB: a phone is used
175
- # only when AMK_ANDROID_DEVICE names it, or when there's no emulator at all
202
+ # The flows clear the app's data, so a phone plugged in over USB is used only when AMK_ANDROID_DEVICE names it
176
203
  device=${AMK_ANDROID_DEVICE:-$(running_emulator "${AMK_ANDROID_AVD:-}")}
177
204
  if [ -z "$device" ]; then
178
205
  avds=$("$sdk/emulator/emulator" -list-avds 2> /dev/null || true)
@@ -187,8 +214,10 @@ android() {
187
214
  sleep 2
188
215
  done
189
216
  else
190
- device=$("$adb" devices | awk 'NR > 1 && $2 == "device" { print $1; exit }')
191
- [ -n "$device" ] || { echo "android: no emulator found (create one in Android Studio)"; status=1; return; }
217
+ phone=$("$adb" devices | awk 'NR > 1 && $2 == "device" { print $1; exit }')
218
+ echo "android: no emulator found (create one in Android Studio)"
219
+ [ -z "$phone" ] || echo " or check on the phone $phone, which clears the app's data on it: AMK_ANDROID_DEVICE=$phone sh scripts/amk/verify.sh android"
220
+ status=1; return
192
221
  fi
193
222
  fi
194
223
  case $device in
@@ -217,10 +246,11 @@ android() {
217
246
  aapt2="$(ls -d "$sdk"/build-tools/*/ 2> /dev/null | sort -V | tail -n 1)aapt2"
218
247
  app_id=$("$aapt2" dump badging "$apk" 2> /dev/null | sed -n "s/^package: name='\([^']*\)'.*/\1/p")
219
248
  [ -n "$app_id" ] || app_id=$(sed -n 's/.*applicationId *=\{0,1\} *"\([^"]*\)".*/\1/p' android/app/build.gradle* | head -n 1)
220
- until [ "$("$adb" -s "$device" shell getprop sys.boot_completed 2> /dev/null | tr -d '\r')" = 1 ]; do sleep 3; done
249
+ android_ready "$device" || { echo "android: $device didn't finish starting (see: adb devices)"; status=1; return; }
221
250
  "$adb" -s "$device" install -r "$apk" > /dev/null
222
- # system "isn't responding" pop-ups (common on busy emulators) cover the app and fail flows; app crashes still fail them
223
- "$adb" -s "$device" shell settings put global hide_error_dialogs 1
251
+ # system "isn't responding" pop-ups (common on busy emulators) cover the app and fail flows; app crashes still fail them.
252
+ # Emulators only: the setting is device-wide and stays, so a phone keeps showing them
253
+ case $device in emulator-*) "$adb" -s "$device" shell settings put global hide_error_dialogs 1 ;; esac
224
254
  "$adb" -s "$device" shell am broadcast -a android.intent.action.CLOSE_SYSTEM_DIALOGS > /dev/null 2>&1 || true
225
255
  run_flows android "$device" "$app_id"
226
256
  }