agentic-mobile-kit 0.7.5 → 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/lib/init.js CHANGED
@@ -111,7 +111,7 @@ function checkProject(cwd) {
111
111
  // a folder with nothing but these can get a new app: system and editor files, and the .git of an empty clone
112
112
  const EMPTY_OK = ['.git', '.DS_Store', 'Thumbs.db', '.vscode', '.idea'];
113
113
  const emptyFolder = cwd => fs.readdirSync(cwd).every(f => EMPTY_OK.includes(f));
114
- // the React Native CLI wants an identifier: a folder "full-tank-log" gives FullTankLog
114
+ // the React Native CLI wants an identifier: a folder "my-new-app" gives MyNewApp
115
115
  const appName = folder => {
116
116
  const n = (folder.match(/[A-Za-z0-9]+/g) || []).map(w => w[0].toUpperCase() + w.slice(1)).join('');
117
117
  return /^[A-Za-z]/.test(n) ? n : `App${n}`;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentic-mobile-kit",
3
- "version": "0.7.5",
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,4 +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. **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.
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
+ 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.
@@ -10,6 +10,11 @@ The user chose this workflow: follow its steps for this task, even where other w
10
10
 
11
11
  Input: $ARGUMENTS (the requirement text, a file path, or a task link plus pasted details).
12
12
 
13
+ With no input, don't guess what to build:
14
+ 1. Run `node scripts/amk/specs.js status`. If a spec is in progress, say which one and where it stopped, and suggest `m-continue`. Start something new only if the user says so.
15
+ 2. Otherwise list the features marked planned in `docs/amk/product.md` and recommend the next one: the first in the list whose dependencies are built. Wait for the user to pick.
16
+ 3. If nothing is planned, ask what to build, or suggest `m-explore` when the requirements aren't settled yet.
17
+
13
18
  ## 1. Always use the full flow
14
19
 
15
20
  The user chose `m-feature`, so follow every step below, however small the change looks. Never skip the spec or the approval stops on your own judgment. (For a small change to behavior the app already has, suggest `m-change`. A change with nothing to record, such as fixing a typo, can just be asked for directly.)
@@ -40,7 +45,7 @@ From here the plan lives in files, so the building can also run in a fresh sessi
40
45
  ## 4. Build, one task at a time
41
46
 
42
47
  For each task:
43
- 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.
44
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.
45
50
  3. Commit with a clear message ending in `Spec: specs/<id>`.
46
51
  4. Tick the task in `tasks.md` and update the handoff block and log in `progress.md`.
@@ -57,7 +62,7 @@ When all tasks are done:
57
62
 
58
63
  Run `node scripts/amk/specs.js merge <id>`. It applies the ADDED, MODIFIED and REMOVED requirements to `specs/current/` and notes the source of each. If it refuses, the reason is usually that a requirement listed as ADDED already exists, or one listed as MODIFIED doesn't. Fix `requirements.md` and run it again. Commit `specs/current/` with the feature, so reviewers see the change in behavior.
59
64
 
60
- Then update the `docs/amk/` files the feature made untrue: a new key journey in `product.md`, a new library or service in `tech.md`, a new folder or shared component in `structure.md`, a new pattern in `conventions.md`. Commit them with the feature too.
65
+ Then update the `docs/amk/` files the feature made untrue: a new key journey in `product.md` or, for a planned feature there, its rules replaced by one line without the planned mark, a new library or service in `tech.md`, a new folder or shared component in `structure.md`, a new pattern in `conventions.md`. Commit them with the feature too.
61
66
 
62
67
  ## 7. Review and pull request
63
68
 
@@ -44,11 +44,12 @@ A prototype answers questions before the real build: what the client wants, how
44
44
 
45
45
  ## 5. Take in the feedback
46
46
 
47
- After the demo, write what was settled into `requirements.md`: answered questions become requirements and scenarios, and the choices go under `## Decisions`. If the client asked for changes, change the prototype and run step 4 again. Repeat until the user approves the requirements.
47
+ After the demo, write what was settled into `requirements.md`: answered questions become requirements and scenarios, and the choices go under `## Decisions`. If the client asked for changes, change the prototype and run step 4 again. Repeat until the user approves the requirements: **stop and ask for that approval**, and record it under `## Decisions` with the date. Step 6 doesn't start without it.
48
48
 
49
49
  ## 6. Hand off to m-feature
50
50
 
51
51
  1. Create the feature branch from the main branch and bring the spec over: `git checkout prototype/<id> -- specs/<id>`. Leave the prototype code behind.
52
52
  2. Add the decisions from `## Decisions` to `docs/amk/decisions.md`, with the date. Run `node scripts/amk/specs.js check specs/<id>/requirements.md`, and commit.
53
- 3. Suggest `m-feature specs/<id>/requirements.md`. In `design.md` it names the `prototype/<id>` branch as the agreed flow and look, and it builds the real screens properly: real data, error, loading and empty states, and tests, on both platforms.
54
- 4. Delete the `prototype/<id>` branch once the feature has shipped.
53
+ 3. If the prototype covered more than one feature, such as an app's first version, also write every feature with its rules in `docs/amk/product.md`, in the order to build them, each marked planned, and tell the user the path. `decisions.md` logs choices and their reasons; it isn't the requirements document.
54
+ 4. Suggest `m-feature specs/<id>/requirements.md`, or one `m-feature` per feature when there are several. In `design.md` it names the `prototype/<id>` branch as the agreed flow and look, and it builds the real screens properly: real data, error, loading and empty states, and tests, on both platforms.
55
+ 5. Delete the `prototype/<id>` branch once the feature has shipped.
@@ -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".
@@ -4,4 +4,5 @@
4
4
  - What the app does.
5
5
  - Who uses it.
6
6
  - The key user journeys (sign-up, checkout, …).
7
- - Anything that must never break (payments, data sync, …). -->
7
+ - Anything that must never break (payments, data sync, …).
8
+ - Features that are planned but not built yet, in the order to build them, each marked planned, with its rules. When `m-feature` ships one, its rules move to `specs/current/` and one line stays here. -->
@@ -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,8 @@
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, when several are connected), AMK_ANDROID_AVD (emulator to start)
16
+ # or UDID), AMK_ANDROID_DEVICE (adb serial: the only way to check on a phone, whose app data the flows clear),
17
+ # AMK_ANDROID_AVD (the emulator to use, started if it isn't running; other devices are left alone)
17
18
  # Flows that log in read ${MAESTRO_EMAIL} and the like from a local, gitignored .maestro/.env.local (never committed).
18
19
  set -eu
19
20
 
@@ -47,6 +48,15 @@ flow_files() {
47
48
  fi
48
49
  }
49
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
+
50
60
  run_flows() { # platform device app_id
51
61
  out="$evidence/$1"
52
62
  mkdir -p "$out"
@@ -62,11 +72,20 @@ run_flows() { # platform device app_id
62
72
  for f in $files; do
63
73
  total=$((total + 1))
64
74
  name=$(basename "$f" .yaml)
65
- # screenshots use relative names: older Maestro saves them in the current folder, newer in --test-output-dir
66
- 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
67
86
  passed=$((passed + 1))
68
87
  else
69
- 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"
70
89
  status=1
71
90
  fi
72
91
  done
@@ -136,6 +155,23 @@ ios() {
136
155
  run_flows ios "$device" "$app_id"
137
156
  }
138
157
 
158
+ # a running emulator's adb serial, of the AVD named in $1 if one is
159
+ running_emulator() {
160
+ for d in $("$adb" devices | awk 'NR > 1 && $2 == "device" && /^emulator-/ { print $1 }'); do
161
+ if [ -z "$1" ] || [ "$("$adb" -s "$d" emu avd name 2> /dev/null | head -n 1 | tr -d '\r')" = "$1" ]; then echo "$d"; return; fi
162
+ done
163
+ }
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
+
139
175
  android() {
140
176
  command -v maestro > /dev/null || { echo "android: Maestro isn't installed (https://maestro.dev)"; status=1; return; }
141
177
  case $(uname -s) in # where Android Studio puts the SDK by default
@@ -162,15 +198,32 @@ android() {
162
198
  [ -z "$flavor" ] || echo "android: checking the \"$flavor\" flavor (the app has: $(echo $flavors)); --flavor <name> checks another"
163
199
  fi
164
200
  variant=$(printf %s "$flavor" | awk '{ print toupper(substr($0, 1, 1)) substr($0, 2) }')
165
- # the device first: the build only needs its CPU type, and an emulator boots while Gradle builds
166
- device=${AMK_ANDROID_DEVICE:-$("$adb" devices | awk 'NR > 1 && $2 == "device" { print $1; exit }')}
201
+ # the device first: the build only needs its CPU type, and an emulator boots while Gradle builds.
202
+ # The flows clear the app's data, so a phone plugged in over USB is used only when AMK_ANDROID_DEVICE names it
203
+ device=${AMK_ANDROID_DEVICE:-$(running_emulator "${AMK_ANDROID_AVD:-}")}
167
204
  if [ -z "$device" ]; then
168
- avd=${AMK_ANDROID_AVD:-$("$sdk/emulator/emulator" -list-avds | head -n 1)}
169
- [ -n "$avd" ] || { echo "android: no emulator found (create one in Android Studio)"; status=1; return; }
170
- nohup "$sdk/emulator/emulator" -avd "$avd" -no-snapshot-save -no-boot-anim > /dev/null 2>&1 &
171
- "$adb" wait-for-device
172
- device=$("$adb" devices | awk 'NR > 1 && $2 == "device" { print $1; exit }')
205
+ avds=$("$sdk/emulator/emulator" -list-avds 2> /dev/null || true)
206
+ avd=${AMK_ANDROID_AVD:-$(echo "$avds" | head -n 1)}
207
+ if [ -n "$avd" ]; then
208
+ echo "$avds" | grep -qxF "$avd" || { echo "android: there's no emulator named $avd (see: emulator -list-avds)"; status=1; return; }
209
+ nohup "$sdk/emulator/emulator" -avd "$avd" -no-snapshot-save -no-boot-anim > /dev/null 2>&1 &
210
+ tries=0
211
+ until device=$(running_emulator "$avd") && [ -n "$device" ]; do
212
+ tries=$((tries + 1))
213
+ [ "$tries" -le 150 ] || { echo "android: emulator $avd didn't start"; status=1; return; }
214
+ sleep 2
215
+ done
216
+ else
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
221
+ fi
173
222
  fi
223
+ case $device in
224
+ emulator-*) echo "android: checking on $device" ;;
225
+ *) echo "android: checking on the phone $device; the flows clear the app's data on it" ;;
226
+ esac
174
227
  abi=$("$adb" -s "$device" shell getprop ro.product.cpu.abi 2> /dev/null | tr -d '\r')
175
228
  [ -n "$abi" ] || { echo "android: device $device isn't connected (see: adb devices)"; status=1; return; }
176
229
  # native code for that CPU type only, as run-android --active-arch-only does: much faster than all four
@@ -193,10 +246,11 @@ android() {
193
246
  aapt2="$(ls -d "$sdk"/build-tools/*/ 2> /dev/null | sort -V | tail -n 1)aapt2"
194
247
  app_id=$("$aapt2" dump badging "$apk" 2> /dev/null | sed -n "s/^package: name='\([^']*\)'.*/\1/p")
195
248
  [ -n "$app_id" ] || app_id=$(sed -n 's/.*applicationId *=\{0,1\} *"\([^"]*\)".*/\1/p' android/app/build.gradle* | head -n 1)
196
- 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; }
197
250
  "$adb" -s "$device" install -r "$apk" > /dev/null
198
- # system "isn't responding" pop-ups (common on busy emulators) cover the app and fail flows; app crashes still fail them
199
- "$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
200
254
  "$adb" -s "$device" shell am broadcast -a android.intent.action.CLOSE_SYSTEM_DIALOGS > /dev/null 2>&1 || true
201
255
  run_flows android "$device" "$app_id"
202
256
  }