agentic-mobile-kit 0.7.14 → 0.7.16

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
@@ -718,11 +718,27 @@ function finish(cwd, { pkg, deps, tools, files, stack, skipGenerate }) {
718
718
  if (!skipGenerate) {
719
719
  const r = tool('npx', ['-y', RULESYNC, 'generate'], { cwd, env: cleanEnv(), encoding: 'utf8' });
720
720
  generated = r.status === 0;
721
+ if (generated) flattenAntigravityStop(cwd);
721
722
  if (!generated) generateError = `${r.stderr || ''}${r.stdout || ''}`.trim().split('\n').slice(-12).join('\n');
722
723
  }
723
724
  return { done, generated, generateError };
724
725
  }
725
726
 
727
+ // rulesync before 40 writes Antigravity's Stop hooks in the matcher shape ([{ hooks: [...] }]). Antigravity takes them
728
+ // as a plain list of handlers and rejects the rest, which drops the whole hook set, guard included
729
+ function flattenAntigravityStop(cwd) {
730
+ const file = path.join(cwd, '.agents/hooks.json');
731
+ let hooks;
732
+ try { hooks = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return; }
733
+ let changed = false;
734
+ for (const set of Object.values(hooks)) {
735
+ if (!set || !Array.isArray(set.Stop) || !set.Stop.some(e => e && Array.isArray(e.hooks) && !e.command)) continue;
736
+ set.Stop = set.Stop.flatMap(e => (e && Array.isArray(e.hooks) && !e.command ? e.hooks : [e]));
737
+ changed = true;
738
+ }
739
+ if (changed) fs.writeFileSync(file, `${JSON.stringify(hooks, null, 2)}\n`);
740
+ }
741
+
726
742
  function init(cwd, opts = {}) {
727
743
  const { pkg, deps, stack } = checkProject(cwd);
728
744
  // monorepos: git runs hooks from the repository root, and GitHub reads workflows only there
@@ -966,5 +982,5 @@ function printUninstall({ report }, log = console.log) {
966
982
 
967
983
  module.exports = {
968
984
  init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS, TESTED, CI, KIT_VERSION, tool, cleanEnv,
969
- hookManager, hooksWired, kitRun, ignoredByGit, checkProject, recorded, installedCi, emptyFolder, createApp,
985
+ hookManager, hooksWired, kitRun, ignoredByGit, flattenAntigravityStop, checkProject, recorded, installedCi, emptyFolder, createApp,
970
986
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentic-mobile-kit",
3
- "version": "0.7.14",
3
+ "version": "0.7.16",
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",
@@ -21,7 +21,7 @@ This project may also use other AI workflow frameworks (for example Superpowers,
21
21
  | Lint, typecheck, test (each skips what the app doesn't have yet) | `sh scripts/amk/pm-run.sh lint`, `sh scripts/amk/pm-run.sh typecheck`, `sh scripts/amk/pm-run.sh test` |
22
22
  | Check dependency versions and the app config | `npx expo install --check`, `npx expo-doctor` |
23
23
  | Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; 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) |
24
- | Check every device at the same time, on a machine with room for it | `sh scripts/amk/verify.sh plan --spec <id>` says whether, and prints the commands: one per device, each for an `m-device-checker` subagent |
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
25
  | 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
26
  | Check a release before tagging it (versions, permission texts, debug leftovers) | `node scripts/amk/release-check.js` |
27
27
  | Signed release builds (a person runs them: they use the signing keys) | `sh scripts/amk/release-build.sh android`, `sh scripts/amk/release-build.sh ios` |
@@ -37,7 +37,7 @@ If no requirement changes, as with a pure style change, skip the spec files (ste
37
37
  1. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Write `specs/<id>/requirements.md` with a title, a one-line goal and only the requirements that change, under `## MODIFIED Requirements: <area>` (or ADDED or REMOVED; the format is in `specs/current/README.md`). Run `node scripts/amk/specs.js check specs/<id>/requirements.md`.
38
38
  2. Change the code, and add or update a test where logic changed.
39
39
  3. Run `sh scripts/amk/verify.sh quick` and show its output.
40
- 4. For a visible change, write `.maestro/<id>.yaml` from `specs/_templates/flow.yaml`: open the changed screen and take a screenshot. Check it on the devices as `sh scripts/amk/verify.sh plan --spec <id>` says (one command, or each device in its own `m-device-checker` subagent at the same time, as in `m-feature`'s step 5), and open the screenshots in `.amk/evidence/<id>/`. Off a Mac it checks Android only: say that iOS still needs checking on a Mac.
40
+ 4. For a visible change, write `.maestro/<id>.yaml` from `specs/_templates/flow.yaml`: open the changed screen and take a screenshot. Check it on the devices as `sh scripts/amk/verify.sh plan --spec <id>` says (one command, or devices in rounds, each in its own `m-device-checker` subagent, as in `m-feature`'s step 5), and open the screenshots in `.amk/evidence/<id>/`. Off a Mac it checks Android only: say that iOS still needs checking on a Mac.
41
41
  5. Run `node scripts/amk/specs.js merge <id>` to update the living spec, and change the doc lines from step 3.
42
42
  6. Copy `specs/_templates/progress.md` to `specs/<id>/progress.md`, set `Status: done`, and write down the checks and their results.
43
43
 
@@ -55,9 +55,9 @@ If building shows the plan is wrong: when the intent is the same, update `requir
55
55
  ## 5. Check against the spec
56
56
 
57
57
  When all tasks are done:
58
- 1. Run `sh scripts/amk/verify.sh plan --spec <id>`. It says whether this machine has room to check the devices at the same time, and prints the commands.
58
+ 1. Run `sh scripts/amk/verify.sh plan --spec <id>`. It says how many devices this machine's memory can check at the same time, and prints the commands.
59
59
  - **One command** (`verify.sh all --spec <id>`): run it. Then **open the screenshots** in `.amk/evidence/<id>/` and check each one against its scenario, in every screen's folder (phone, landscape, tablet).
60
- - **A plan, and your tool has subagents:** run its `quick` and `build` commands as printed (nothing added: the plain commands are the ones people allow), then start one `m-device-checker` subagent per device command, all at once; each runs its device, checks its screenshots and hands back a report. When all are back, check them yourself: every flow passed, every screen has screenshots in its folder (list them), and open every screenshot a report flags plus at least one per screen. A report alone isn't evidence. Without subagents, run `verify.sh all --spec <id>` instead.
60
+ - **A plan, and your tool has subagents:** run its `quick` and `build` commands as printed (nothing added: the plain commands are the ones people allow), then, round by round, start one `m-device-checker` subagent per device command of the round, all at once, and wait for their reports before the next round; each runs its device (or its part of the flows), checks its screenshots and hands back a report. When all are back, check them yourself: every flow passed, every screen has screenshots in its folder, or in each `part-k/` folder when its flows ran in parts (list them), and open every screenshot a report flags plus at least one per screen. A report alone isn't evidence. Without subagents, run `verify.sh all --spec <id>` instead.
61
61
 
62
62
  Off a Mac it checks Android only: record in `progress.md` that iOS still needs `verify.sh ios --spec <id>` on a Mac, and say so in the PR. A turned screen's screenshots are landscape; a portrait one means the app didn't turn. Maestro can report a tap as passed when nothing happened, so the screenshots are the evidence, not the log.
63
63
  2. Go through every scenario and note its evidence: a test name, command output, or the screen checked. Where the code and the spec disagree, fix whichever is wrong, asking first if it's the spec. The spec must describe what ships.
@@ -1,10 +1,11 @@
1
1
  {
2
2
  "version": 1,
3
3
  "hooks": {
4
- // "./" lets rulesync anchor each command to the project folder for a tool that keeps the agent's cd between
5
- // commands (Claude Code: "$CLAUDE_PROJECT_DIR"/scripts/...): a relative one isn't found after a cd into a
6
- // subfolder, which turns the guard off. No matcher: runs for every tool call; guard.js decides from the payload
7
- "preToolUse": [{ "command": "node ./scripts/amk/guard.js" }],
8
- "stop": [{ "command": "node ./scripts/amk/handoff-check.js" }]
4
+ // Each command finds the project through git, so it runs from wherever the tool starts it: Claude Code keeps the
5
+ // agent's cd between commands, Antigravity runs hooks from .agents/, Codex from the project. A relative path
6
+ // isn't found there, which turns the guard off (or, in Antigravity, blocks every command). No shell variables,
7
+ // so it also runs in PowerShell. No matcher: runs for every tool call; guard.js decides from the payload
8
+ "preToolUse": [{ "command": "node -e \"require(require('child_process').execSync('git rev-parse --show-toplevel').toString().trim() + '/scripts/amk/guard.js')\"" }],
9
+ "stop": [{ "command": "node -e \"require(require('child_process').execSync('git rev-parse --show-toplevel').toString().trim() + '/scripts/amk/handoff-check.js')\"" }]
9
10
  }
10
11
  }
@@ -1,14 +1,14 @@
1
1
  ---
2
2
  name: m-device-checker
3
3
  targets: ["*"]
4
- description: Checks the app on one device and reports the evidence. Use when `verify.sh plan` says to check the devices at the same time, one m-device-checker per device command, all started together.
4
+ description: Checks the app on one device and reports the evidence. Use when `verify.sh plan` says to check devices at the same time, one m-device-checker per device command of a round, all started together.
5
5
  claudecode:
6
6
  tools: ["Read", "Grep", "Glob", "Bash"]
7
7
  ---
8
8
 
9
9
  You check the app on one device with fresh eyes, and hand the evidence back. You never edit files.
10
10
 
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>/`. Don't build, and don't run anything else on a device: other checkers are using the other devices.
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
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
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.
14
14
  4. Report, and say only what you saw in this run:
@@ -21,7 +21,7 @@ This project may also use other AI workflow frameworks (for example Superpowers,
21
21
  | iOS build (simulator, no signing) | `sh scripts/amk/ios-build.sh` |
22
22
  | Android build | `cd android && ./gradlew assembleDebug` |
23
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) |
24
- | Check every device at the same time, on a machine with room for it | `sh scripts/amk/verify.sh plan --spec <id>` says whether, and prints the commands: one per device, each for an `m-device-checker` subagent |
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
25
  | 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
26
  | Check a release before tagging it (versions, permission texts, debug leftovers) | `node scripts/amk/release-check.js` |
27
27
  | 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]` |
@@ -9,14 +9,19 @@
9
9
  # ios|android release build, install, run flows, screenshots
10
10
  # all everything (default)
11
11
  # build the release builds only, iOS and Android at the same time, for --no-build checks after it
12
- # plan whether this machine can check the devices at the same time, and the commands to run
12
+ # plan how many devices this machine's memory can check at the same time, and the commands to run:
13
+ # one per device, in rounds when they don't all fit, the flows split into parts when there's room
13
14
  # --spec <id> run .maestro/<id>*.yaml and save evidence in .amk/evidence/<id>/
15
+ # --flow <file> run only this flow: a path in the project, or anywhere (an absolute path)
14
16
  # --label <n> evidence folder name (default: the spec id, or no-spec)
15
17
  # --flavor <name> Android product flavor to check (default: the first one in build.gradle)
16
18
  # --scheme <name> iOS scheme to check (default: the one named like the workspace)
17
19
  # --screens <l> only these of the screens the app supports, comma-separated: phone, tablet, portrait,
18
20
  # landscape, or one such as tablet-landscape
19
21
  # --no-build check the last build instead of building again (after `build`)
22
+ # --part <k/n> only part k of the flows split in n (every n-th, from the k-th), with its evidence in
23
+ # <screen>/part-k/: part 1 on the usual device, the others on a temporary copy of it (the same kind of
24
+ # simulator, or an emulator with the same settings), deleted afterwards. plan prints these
20
25
  # (no flows found: a smoke check that launches the app and takes a screenshot)
21
26
  # Evidence per screen: ios/ and android/ (phone, portrait), then -landscape/, -tablet/ and -tablet-landscape/, each
22
27
  # with its latest run only (the device's own log only for a flow that failed); the newest 5 evidence folders stay,
@@ -27,7 +32,9 @@
27
32
  # AMK_ANDROID_AVD (the emulator to use, started if it isn't running; other devices are left alone),
28
33
  # AMK_IOS_TABLET (iPad simulator, or a connected iPad: name or UDID), AMK_ANDROID_TABLET_AVD (tablet emulator),
29
34
  # AMK_ANDROID_TABLET (serial), AMK_IOS_TEAM (the Apple team ID that signs builds for real iPhones and iPads;
30
- # default: the project's), AMK_PARALLEL (1 or 0: overrides plan's choice), AMK_DEVICE_WAIT (minutes to wait for a
35
+ # default: the project's), AMK_PARALLEL (1 or 0: overrides plan's choice), AMK_MEMORY_GB (the memory plan
36
+ # counts on: this machine's; less when other emulators stay open), AMK_DEVICES (how many devices plan checks at
37
+ # once: one per 6 GB beyond 4), AMK_DEVICE_WAIT (minutes to wait for a
31
38
  # device in use, 30), AMK_LOCK_DIR (where runs on this machine claim devices; /tmp/agentic-mobile-kit-<user id>),
32
39
  # AMK_EVIDENCE_KEEP (how many evidence folders stay, newest first: 5; 0 keeps them all)
33
40
  # A device in use by another run (any project on this machine) is skipped for a free one of the same kind, or waited
@@ -47,6 +54,7 @@ flavor=${AMK_ANDROID_FLAVOR:-}
47
54
  only=${AMK_SCREENS:-}
48
55
  no_build=0
49
56
  build_only=0
57
+ part=""
50
58
  while [ $# -gt 0 ]; do
51
59
  case $1 in
52
60
  --spec) spec=$2; shift 2 ;;
@@ -56,11 +64,23 @@ while [ $# -gt 0 ]; do
56
64
  --scheme) AMK_IOS_SCHEME=$2; export AMK_IOS_SCHEME; shift 2 ;;
57
65
  --screens) only=$2; shift 2 ;;
58
66
  --no-build) no_build=1; shift ;;
67
+ --part) part=$2; shift 2 ;;
59
68
  *) echo "verify: unknown option $1"; exit 2 ;;
60
69
  esac
61
70
  done
71
+ part_k=1 part_n=1
72
+ if [ -n "$part" ]; then
73
+ part_k=${part%/*} part_n=${part#*/}
74
+ case $part in */*) ;; *) part_k=x ;; esac
75
+ case "$part_k$part_n" in '' | *[!0-9]*) echo "verify: --part takes k/n, such as 2/3"; exit 2 ;; esac
76
+ [ "$part_k" -ge 1 ] && [ "$part_k" -le "$part_n" ] || { echo "verify: --part takes k/n, such as 2/3"; exit 2; }
77
+ fi
62
78
 
63
79
  root=$(pwd)
80
+ # --flow: a path in the project, or an absolute one (C:/… on Windows too); a Windows path's backslashes become slashes
81
+ case $flow in *\\*) flow=$(printf '%s' "$flow" | tr '\\' /) ;; esac
82
+ case $flow in "" | /* | [A-Za-z]:/*) ;; *) flow=$root/$flow ;; esac
83
+ [ -z "$flow" ] || [ -f "$flow" ] || { echo "verify: no flow file $flow"; exit 2; }
64
84
  . scripts/amk/maestro-env.sh
65
85
  # runs without a spec or a label (verify.sh quick, mostly) share one folder, so they don't push out a feature's
66
86
  evidence="$root/.amk/evidence/${label:-${spec:-no-spec}}"
@@ -73,17 +93,20 @@ keep=${AMK_EVIDENCE_KEEP:-5}
73
93
  if [ "$keep" -gt 0 ] 2> /dev/null; then
74
94
  old=$(ls -dt "$root"/.amk/evidence/*/ 2> /dev/null | grep -v -- '-prototype/$' | tail -n +$((keep + 1)))
75
95
  if [ -n "$old" ]; then
76
- echo "$old" | while IFS= read -r d; do rm -r "${d:?}" || true; done
96
+ # another run on this machine (a part, a round) may have just removed the same folder
97
+ echo "$old" | while IFS= read -r d; do rm -r "${d:?}" 2> /dev/null || true; done
77
98
  echo "evidence: removed $(echo "$old" | wc -l | tr -d ' ') older folders from .amk/evidence, keeping the newest $keep (AMK_EVIDENCE_KEEP sets how many; 0 keeps them all)"
78
99
  fi
79
100
  fi
80
101
  status=0
81
102
 
82
103
  flow_files() {
83
- if [ -n "$flow" ]; then echo "$root/$flow"
84
- elif [ -n "$spec" ]; then find "$root/.maestro" -maxdepth 1 -iname "$spec*.yaml" 2>/dev/null | sort
85
- else find "$root/.maestro" -maxdepth 1 -name '*.yaml' 2>/dev/null | sort
86
- fi
104
+ {
105
+ if [ -n "$flow" ]; then echo "$flow"
106
+ elif [ -n "$spec" ]; then find "$root/.maestro" -maxdepth 1 -iname "$spec*.yaml" 2>/dev/null | sort
107
+ else find "$root/.maestro" -maxdepth 1 -name '*.yaml' 2>/dev/null | sort
108
+ fi
109
+ } | awk -v k="$part_k" -v n="$part_n" '(NR - 1) % n == k - 1'
87
110
  }
88
111
 
89
112
  # the screens to check on a platform: the ones the app supports, narrowed by --screens
@@ -130,7 +153,8 @@ claim() {
130
153
  }
131
154
  unclaim() { l=$(lock_path "$1"); rm -f "$l/owner"; rmdir "$l" 2> /dev/null || true; held=$(echo "$held" | sed "s| $l||"); }
132
155
  release() { for l in $held; do rm -f "$l/owner"; rmdir "$l" 2> /dev/null || true; done; held=""; }
133
- trap release EXIT
156
+ temps="" # the temporary devices this run made for a part of the flows (--part), deleted at its end
157
+ trap 'release; drop_temps' EXIT
134
158
  trap 'exit 130' INT TERM
135
159
  holder() {
136
160
  l=$(lock_path "$1")
@@ -163,13 +187,27 @@ run_flow() { # screen device app_id file name orientation
163
187
  # pressing the last button of the app's own alerts too, such as a Delete. Maestro never answers an app's alerts.
164
188
  # So one that says to leave permissions alone comes first, where it never runs (on Android only)
165
189
  on_complete="" turn=""
190
+ # what's beside the flow, and below it in the project (its subflows): only beside it, for a flow outside the
191
+ # project, whose folder may hold anything
192
+ case $4 in "$root"/*) depth="" ;; *) depth="-maxdepth 1" ;; esac
193
+ # a flow that turns airplane mode on and fails before turning it off leaves the device offline, and an offline
194
+ # device doesn't open a development-signed app: every later flow would fail as if the team weren't trusted.
195
+ # maestro-runner runs this one's onFlowComplete, not the flow's own. It looks for the switch on Settings' main page,
196
+ # but Settings opens on the page it was last left on: restarted, it opens on its main page (for the flow's own
197
+ # setAirplaneMode too). Optional, so a flow that passed never fails here. A few seconds, so only where flows use it
198
+ if find "$(dirname "$4")" $depth \( -path "$root/.amk" -o -name node_modules \) -prune -o \( -name '*.yaml' -o -name '*.yml' \) \
199
+ -exec grep -qs setAirplaneMode {} \; -print | grep -q .; then
200
+ xcrun devicectl device process launch --device "$2" --terminate-existing com.apple.Preferences > /dev/null 2>&1 || true
201
+ on_complete=' - setAirplaneMode:\n value: disabled\n optional: true\n'
202
+ fi
166
203
  if [ "$6" != PORTRAIT ]; then
167
204
  # WebDriverAgent turns the device, then fails the step unless the app in front turned too: here the home
168
205
  # screen, which most iPhones never turn. Whether the app turned shows in its screenshots. It knows
169
206
  # LANDSCAPE_LEFT only as "landscape"
170
- on_complete='onFlowComplete:\n - setOrientation:\n orientation: PORTRAIT\n optional: true\n'
207
+ on_complete="$on_complete"' - setOrientation:\n orientation: PORTRAIT\n optional: true\n'
171
208
  turn='- setOrientation:\n orientation: landscape\n optional: true\n'
172
209
  fi
210
+ [ -z "$on_complete" ] || on_complete="onFlowComplete:\n$on_complete"
173
211
  printf "appId: %s\n${on_complete}---\n- runFlow:\n when:\n platform: Android\n commands:\n - launchApp:\n permissions:\n all: unset\n${turn}- runFlow: '%s'\n" "$3" "$native" > "$debug/screen.yaml"
174
212
  target=$debug/screen.yaml
175
213
  elif [ "$6" != PORTRAIT ]; then
@@ -181,7 +219,7 @@ run_flow() { # screen device app_id file name orientation
181
219
  if is_real "$2"; then
182
220
  # it also saves each named screenshot next to its flow file: the ones it makes there move to its log folder, so
183
221
  # the project stays as it was (they're in its report too)
184
- pngs() { find "$(dirname "$4")" \( -path "$root/.amk" -o -name node_modules \) -prune -o -name '*.png' -print | sort; }
222
+ pngs() { find "$(dirname "$4")" $depth \( -path "$root/.amk" -o -name node_modules \) -prune -o -name '*.png' -print | sort; }
185
223
  pngs "$@" > "$debug/.pngs"
186
224
  # with the app's build: on a real device, clearState installs the app again
187
225
  MAESTRO_RUNNER_NO_TELEMETRY=1 DO_NOT_TRACK=1 npx -y "$runner" --platform ios --driver wda --device "$2" \
@@ -200,8 +238,35 @@ run_flow() { # screen device app_id file name orientation
200
238
  return $rc
201
239
  }
202
240
 
241
+ # whether a flow failed because the Android device dropped out: Maestro says so in its own log or the flow's ($1)
242
+ lost_device() {
243
+ grep -qs -E 'device offline|DeviceServerDiedException|Device server died' "$debug/maestro.log" ||
244
+ grep -qs -E 'was requested, but it is not connected|Device server died' "$1"
245
+ }
246
+ # waits until the Android device $1 answers three times in a row, 10 seconds apart (3 minutes at most)
247
+ steady() {
248
+ "$adb" reconnect offline > /dev/null 2>&1 || true
249
+ in_row=0 tries=0
250
+ while [ "$in_row" -lt 3 ] && [ "$tries" -lt 18 ]; do
251
+ tries=$((tries + 1))
252
+ if [ "$("$adb" -s "$1" shell getprop sys.boot_completed 2> /dev/null | tr -d '\r')" = 1 ]; then in_row=$((in_row + 1)); else in_row=0; "$adb" reconnect offline > /dev/null 2>&1 || true; fi
253
+ [ "$in_row" -ge 3 ] || sleep 10
254
+ done
255
+ }
203
256
  run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to turn it) [again]
204
257
  out="$evidence/$1"
258
+ # a part of the flows has a folder of its own in the screen's, as the parts run at the same time: part 1 clears what
259
+ # an earlier run left beside them
260
+ if [ -n "$part" ]; then
261
+ if [ "$part_k" = 1 ] && [ -z "${5:-}" ] && [ -d "$out" ]; then
262
+ for e in "$out"/* "$out"/.[!.]*; do
263
+ [ -e "$e" ] || continue
264
+ case ${e##*/} in part-*) [ "${e##*/part-}" -le "$part_n" ] 2> /dev/null && continue ;; esac
265
+ rm -r "$e"
266
+ done
267
+ fi
268
+ out="$out/part-$part_k"
269
+ fi
205
270
  # the screen's latest run only: an earlier run's screenshots aren't this run's evidence
206
271
  [ -n "${5:-}" ] || [ ! -d "$out" ] || rm -r "$out"
207
272
  mkdir -p "$out"
@@ -228,12 +293,17 @@ run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to
228
293
  echo " $1: Maestro stopped before flow $name started; running it once more"
229
294
  ok=0
230
295
  run_flow "$1" "$2" "$3" "$f" "$name" "$4" || ok=$?
231
- elif [ "$ok" != 0 ] && [ "${1%%-*}" = android ] && grep -qs 'device offline' "$debug/maestro.log"; then
232
- echo " $1: the device went offline during flow $name; running it once more"
233
- "$adb" reconnect offline > /dev/null 2>&1 || true
234
- android_ready "$2" || true
235
- ok=0
236
- run_flow "$1" "$2" "$3" "$f" "$name" "$4" || ok=$?
296
+ # (or missed it as it started, or Maestro's server on it died: an emulator under load, with other devices starting
297
+ # or running on this machine, can drop it for a few minutes). Once it answers steadily, run it again, twice at most
298
+ elif [ "$ok" != 0 ] && [ "${1%%-*}" = android ] && lost_device "$out/$name.log"; then
299
+ again=0
300
+ while [ "$ok" != 0 ] && [ "$again" -lt 2 ] && lost_device "$out/$name.log"; do
301
+ again=$((again + 1))
302
+ echo " $1: the device went offline during flow $name; running it once more when it answers steadily"
303
+ steady "$2"
304
+ ok=0
305
+ run_flow "$1" "$2" "$3" "$f" "$name" "$4" || ok=$?
306
+ done
237
307
  elif [ "$ok" != 0 ] && is_real "$2" && grep -qs 'explicitly trusted' "$out/$name.log"; then
238
308
  # as launch_check found it does: here after clearState installed the app again, which it opened a moment later
239
309
  echo " $1: the device didn't open the app it had just installed again; running flow $name once more"
@@ -329,6 +399,7 @@ check_screens() { # platform phone tablet app_id screens…
329
399
  run_flows "$where" "$on" "$id" "$turn"
330
400
  done
331
401
  release # this platform's devices, and Maestro's turn, for other runs
402
+ drop_temps
332
403
  }
333
404
 
334
405
  quick() {
@@ -459,6 +530,17 @@ simulators() {
459
530
  # device's
460
531
  take_simulator() {
461
532
  taken=""
533
+ if [ "$part_k" -gt 1 ]; then
534
+ first=$(simulators "$1" "$2" | head -n 1)
535
+ if [ -z "$first" ]; then
536
+ [ -z "$2" ] || { echo "ios: part $part of the flows runs on a copy of the device, which works only for a simulator, not $2"; return 1; }
537
+ return 0
538
+ fi
539
+ temp_simulator "$first" || { echo "ios: couldn't make a simulator for part $part of the flows"; return 1; }
540
+ claim "ios-$taken" "$taken" || true
541
+ echo "ios: part $part of the flows runs on a temporary $1 simulator like $first, deleted afterwards"
542
+ return 0
543
+ fi
462
544
  candidates=$(simulators "$1" "$2")
463
545
  if [ -z "$candidates" ] && [ -n "$2" ]; then
464
546
  candidates=$(real_ios "$2")
@@ -505,7 +587,7 @@ launch_check() {
505
587
  tries=$((tries + 1))
506
588
  case $said in
507
589
  *'explicitly trusted'*) [ "$tries" -lt 3 ] || {
508
- echo "ios: $1 doesn't open apps from this team yet: on it, Settings > General > VPN & Device Management > Developer App > Trust, then run this again"
590
+ echo "ios: $1 doesn't open apps from this team: on it, trust the team (Settings > General > VPN & Device Management > Developer App > Trust), and turn airplane mode off (offline, it doesn't open apps signed for development). Then run this again"
509
591
  return 1; } ;;
510
592
  *) echo "ios: the app didn't open on $1 (is it unlocked?), see ${log#"$root"/}"; return 1 ;;
511
593
  esac
@@ -557,11 +639,54 @@ device_width() {
557
639
  /Physical size/ { split($2, s, "x"); w = s[1] + 0 < s[2] + 0 ? s[1] : s[2] } /Physical density/ { d = $2 }
558
640
  END { if (d) print int(w * 160 / d) }'
559
641
  }
642
+ avd_home=${ANDROID_AVD_HOME:-${ANDROID_USER_HOME:-$HOME/.android}/avd}
643
+ # an AVD's folder: its .ini names it (an AVD can be renamed, and keep its folder), else <name>.avd
644
+ avd_dir() { d=$(sed -n 's/^path=//p' "$avd_home/$1.ini" 2> /dev/null | head -n 1); echo "${d:-$avd_home/$1.avd}"; }
645
+ # a temporary AVD with the settings of AVD $1 (not its data), in $tavd, for a part of the flows after the first
646
+ temp_avd() {
647
+ tavd="amk_part_${part_k}_$$_$(printf %s "$1" | tr -c 'A-Za-z0-9._-' _)"
648
+ [ -f "$(avd_dir "$1")/config.ini" ] && mkdir -p "$avd_home/$tavd.avd" || return 1
649
+ temps="$temps avd:$tavd"
650
+ grep -v -E '^(avd\.ini\.displayname|AvdId|avd\.id|fastboot\.)' "$(avd_dir "$1")/config.ini" > "$avd_home/$tavd.avd/config.ini"
651
+ printf 'avd.ini.displayname=%s\nAvdId=%s\n' "$tavd" "$tavd" >> "$avd_home/$tavd.avd/config.ini"
652
+ printf 'avd.ini.encoding=UTF-8\npath=%s\npath.rel=avd/%s.avd\ntarget=%s\n' "$avd_home/$tavd.avd" "$tavd" \
653
+ "$(sed -n 's/^target=//p' "$avd_home/$1.ini" 2> /dev/null | head -n 1)" > "$avd_home/$tavd.ini"
654
+ }
655
+ # a temporary simulator of the same type and iOS version as simulator $1, in $taken, for a part after the first
656
+ temp_simulator() {
657
+ like=$(xcrun simctl list devices available -j | UDID=$1 node -e '
658
+ for (const [rt, ds] of Object.entries(JSON.parse(require("fs").readFileSync(0, "utf8")).devices))
659
+ for (const d of ds) if (d.udid === process.env.UDID) console.log(d.deviceTypeIdentifier, rt);')
660
+ [ -n "$like" ] || return 1
661
+ taken=$(xcrun simctl create "amk part $part_k of $part_n ($$)" $like) && [ -n "$taken" ] || return 1
662
+ temps="$temps ios:$taken"
663
+ }
664
+ # waits until adb no longer lists the emulator $1 (up to $2 seconds): it has stopped, or is about to
665
+ gone() { tries=0; while [ -n "$(running_emulator "$1" 2> /dev/null || true)" ] && [ "$tries" -lt "$2" ]; do tries=$((tries + 1)); sleep 1; done; }
666
+ # deletes the temporary devices this run made: their data goes with them
667
+ drop_temps() {
668
+ for t in $temps; do
669
+ case $t in
670
+ ios:*) xcrun simctl shutdown "${t#ios:}" > /dev/null 2>&1 || true; xcrun simctl delete "${t#ios:}" > /dev/null 2>&1 || true ;;
671
+ avd:*)
672
+ n=${t#avd:}
673
+ s=$(running_emulator "$n" 2> /dev/null || true)
674
+ [ -z "$s" ] || "$adb" -s "$s" emu kill > /dev/null 2>&1 || true
675
+ gone "$n" 30
676
+ # an emulator can hold its files for a moment after adb lets it go (on Windows, a file in use can't be deleted)
677
+ tries=0
678
+ until rm -rf "${avd_home:?}/$n.avd" "$avd_home/$n.ini" 2> /dev/null && [ ! -e "$avd_home/$n.avd" ] || [ "$tries" -ge 5 ]; do
679
+ tries=$((tries + 1)); sleep 2
680
+ done ;;
681
+ esac
682
+ done
683
+ temps=""
684
+ }
560
685
  # the same for an emulator that isn't running, from its config.ini
561
686
  avd_width() {
562
687
  awk -F' *= *' '$1 == "hw.lcd.width" { w = $2 } $1 == "hw.lcd.height" { h = $2 } $1 == "hw.lcd.density" { d = $2 }
563
688
  END { if (d) print int((w + 0 < h + 0 ? w : h) * 160 / d) }' \
564
- "${ANDROID_AVD_HOME:-${ANDROID_USER_HOME:-$HOME/.android}/avd}/$1.avd/config.ini" 2> /dev/null || true
689
+ "$(avd_dir "$1")/config.ini" 2> /dev/null || true
565
690
  }
566
691
  # the emulators of the kind $1 (phone or tablet), best first: the running ones, then the others
567
692
  emulators() {
@@ -577,6 +702,29 @@ emulators() {
577
702
  # best one, once it's free. Empty when there's none of that kind. An emulator is claimed by its name, however named
578
703
  take_android() {
579
704
  taken="" pick=""
705
+ if [ "$part_k" -gt 1 ]; then
706
+ src=$3
707
+ if [ -n "$2" ]; then
708
+ case $2 in
709
+ emulator-*) src=$("$adb" -s "$2" emu avd name 2> /dev/null | head -n 1 | tr -d '\r') ;;
710
+ *) echo "android: part $part of the flows runs on a copy of the device, which works only for an emulator, not $2"; return 1 ;;
711
+ esac
712
+ fi
713
+ [ -n "$src" ] || src=$(emulators "$1" | head -n 1)
714
+ [ -n "$src" ] || return 0
715
+ temp_avd "$src" || { echo "android: couldn't copy emulator $src for part $part of the flows"; return 1; }
716
+ taken=$(start_emulator "$tavd") || { echo "android: the copy of emulator $src for part $part of the flows didn't start"; return 1; }
717
+ # a new emulator's first boot drops its adb connection during flows ("device offline"), however long it's left;
718
+ # started again, it doesn't (measured: 5 of 6 runs failed on first boots, 6 of 6 passed after a restart). It's
719
+ # stopped through its console, as adb itself can be offline then, and started again
720
+ android_ready "$taken" || { echo "android: the copy of emulator $src for part $part of the flows didn't start"; return 1; }
721
+ "$adb" -s "$taken" emu kill > /dev/null 2>&1 || true
722
+ gone "$tavd" 60
723
+ taken=$(start_emulator "$tavd") || { echo "android: the copy of emulator $src for part $part of the flows didn't start again"; return 1; }
724
+ claim "android-avd-$tavd" "$taken" || true
725
+ echo "android: part $part of the flows runs on a temporary copy of emulator $src, deleted afterwards"
726
+ return 0
727
+ fi
580
728
  if [ -n "$2" ]; then
581
729
  key=android-$2
582
730
  case $2 in emulator-*) key=android-avd-$("$adb" -s "$2" emu avd name 2> /dev/null | head -n 1 | tr -d '\r') ;; esac
@@ -630,6 +778,8 @@ android() {
630
778
  *) default_sdk=$HOME/Android/Sdk ;;
631
779
  esac
632
780
  sdk=${ANDROID_HOME:-${ANDROID_SDK_ROOT:-$default_sdk}}
781
+ # Gradle finds the SDK through it too: an AI tool started from the Dock or a menu doesn't load the shell's profile
782
+ [ -n "${ANDROID_HOME:-}" ] || export ANDROID_HOME="$sdk"
633
783
  adb="$sdk/platform-tools/adb"
634
784
  # Expo apps without native folders in git: generate android/ first
635
785
  if [ "$no_build" = 0 ] && ! sh scripts/amk/prebuild.sh android > "$evidence/prebuild-android.log" 2>&1; then
@@ -763,36 +913,97 @@ build() {
763
913
  plan() {
764
914
  set -- $(node -e 'const os = require("os"), fs = require("fs"), s = fs.statfsSync(".");
765
915
  console.log(Math.round(os.totalmem() / 2 ** 30), Math.round(s.bavail * s.bsize / 2 ** 30))')
766
- have="$1 GB of memory, $2 GB free disk, Maestro $(maestro_version)"
767
- checks=""
768
- if [ "$(uname -s)" = Darwin ]; then
769
- for kind in phone tablet; do screens_for ios | grep -q "^$kind-" && checks="$checks ios:$kind"; done
770
- fi
771
- for kind in phone tablet; do screens_for android | grep -q "^$kind-" && checks="$checks android:$kind"; done
916
+ mem=$1
917
+ case ${AMK_MEMORY_GB:-x} in *[!0-9]*) ;; *) mem=$AMK_MEMORY_GB ;; esac
918
+ have="$mem GB of memory, $2 GB free disk, Maestro $(maestro_version)"
919
+ # the devices to check, phones first and the platforms mixed, so a round of two has one of each
920
+ # (each platform's screens are read first: grep -q stops reading at its first match, and a writer still going then
921
+ # says "Broken pipe")
922
+ checks="" ios_screens="" android_screens=$(screens_for android)
923
+ [ "$(uname -s)" != Darwin ] || ios_screens=$(screens_for ios)
924
+ for kind in phone tablet; do
925
+ if echo "$ios_screens" | grep -q "^$kind-"; then checks="$checks ios:$kind"; fi
926
+ if echo "$android_screens" | grep -q "^$kind-"; then checks="$checks android:$kind"; fi
927
+ done
772
928
  n=$(echo $checks | wc -w | tr -d ' ')
929
+ # a device under test takes about 6 GB (a simulator or an emulator with Maestro: an iPhone simulator and a phone
930
+ # emulator at once measured 11 GB), and macOS and the rest about 4 GB: 2 devices at once from 16 GB, 4 from 28 GB
931
+ slots=$(( (mem - 4) / 6 ))
932
+ case ${AMK_DEVICES:-x} in *[!0-9]*) ;; *) slots=$AMK_DEVICES ;; esac
773
933
  why=""
774
934
  case ${AMK_PARALLEL:-} in
775
935
  0) why="AMK_PARALLEL=0" ;;
776
- 1) ;;
936
+ 1) [ "$slots" -ge "$n" ] || slots=$n ;;
777
937
  *)
778
- [ "$1" -ge 32 ] || why="it needs 32 GB of memory"
938
+ if [ "$slots" -lt 2 ]; then why=${AMK_DEVICES:+AMK_DEVICES=$AMK_DEVICES}; why=${why:-it needs 16 GB of memory}; fi
779
939
  [ "$2" -ge 20 ] || why="${why:+$why and }it needs 20 GB free disk"
780
940
  maestro_at_least 2.6.0 || why="${why:+$why and }it needs Maestro 2.6 or later" ;;
781
941
  esac
782
- [ "$n" -ge 2 ] || why="there's one device to check"
942
+ # room for more devices than kinds: each kind's flows split into parts, each part on a device of its own
943
+ # A part's device is one more: about 6 GB for a simulator, 8 GB for an emulator (measured with 4 GB of guest memory),
944
+ # so parts need room for every kind's devices at once; AMK_DEVICES says how many outright
945
+ flows=$(flow_files | grep -c . || true)
946
+ parts=1
947
+ if [ "$slots" -gt "$n" ] && [ "$flows" -ge 2 ]; then
948
+ parts=$((slots / n))
949
+ case ${AMK_DEVICES:-x} in
950
+ *[!0-9]*)
951
+ per=0
952
+ for c in $checks; do case $c in ios:*) per=$((per + 6)) ;; *) per=$((per + 8)) ;; esac; done
953
+ [ "$parts" -le $(( (mem - 4) / per )) ] || parts=$(( (mem - 4) / per )) ;;
954
+ esac
955
+ [ "$parts" -le "$flows" ] || parts=$flows
956
+ [ "$parts" -ge 1 ] || parts=1
957
+ fi
958
+ [ "$n" -ge 2 ] || [ "$parts" -ge 2 ] || why="there's one device to check"
783
959
  if [ -n "$why" ]; then
784
960
  echo "plan: $have: one device at a time ($why; AMK_PARALLEL=1 overrides)"
785
961
  echo " sh scripts/amk/verify.sh all${args:+ $args}"
786
962
  return
787
963
  fi
788
- echo "plan: $have: check the $n devices at the same time"
964
+ # one command per device, a kind's parts next to each other. A real iPhone, iPad or phone can't be copied for a
965
+ # part, so it runs all its flows
966
+ jobs=""
967
+ for c in $checks; do
968
+ p=$parts
969
+ case $c in
970
+ ios:phone) [ -z "${AMK_IOS_DEVICE:-}" ] || [ -n "$(simulators iPhone "$AMK_IOS_DEVICE")" ] || p=1 ;;
971
+ ios:tablet) [ -z "${AMK_IOS_TABLET:-}" ] || [ -n "$(simulators iPad "$AMK_IOS_TABLET")" ] || p=1 ;;
972
+ android:phone) case ${AMK_ANDROID_DEVICE:-emulator-} in emulator-*) ;; *) p=1 ;; esac ;;
973
+ android:tablet) case ${AMK_ANDROID_TABLET:-emulator-} in emulator-*) ;; *) p=1 ;; esac ;;
974
+ esac
975
+ i=1
976
+ while [ "$i" -le "$p" ]; do
977
+ cmd="sh scripts/amk/verify.sh ${c%:*} --no-build --screens ${c#*:}"
978
+ [ "$p" = 1 ] || cmd="$cmd --part $i/$p"
979
+ jobs="$jobs$cmd${args:+ $args}
980
+ "
981
+ i=$((i + 1))
982
+ done
983
+ done
984
+ total=$(printf %s "$jobs" | grep -c .)
985
+ rounds=$(( (total + slots - 1) / slots ))
986
+ if [ "$rounds" -gt 1 ]; then echo "plan: $have: $slots devices at a time, in $rounds rounds"
987
+ elif [ "$parts" -gt 1 ]; then echo "plan: $have: check on $total devices at the same time, each kind's flows in parts"
988
+ else echo "plan: $have: check the $n devices at the same time"; fi
789
989
  echo " 1. sh scripts/amk/verify.sh quick${args:+ $args}"
790
990
  echo " 2. sh scripts/amk/verify.sh build${args:+ $args}"
791
- echo " 3. at the same time, each in its own subagent (m-device-checker), which checks its screenshots and reports:"
792
- for c in $checks; do echo " sh scripts/amk/verify.sh ${c%:*} --no-build --screens ${c#*:}${args:+ $args}"; done
991
+ r=1
992
+ while [ "$r" -le "$rounds" ]; do
993
+ if [ "$rounds" = 1 ]; then echo " 3. at the same time, each in its own subagent (m-device-checker), which checks its screenshots and reports:"
994
+ elif [ "$r" = 1 ]; then echo " 3. round 1 of $rounds, at the same time, each in its own subagent (m-device-checker), which checks its screenshots and reports:"
995
+ else echo " $((r + 2)). round $r of $rounds, once round $((r - 1)) has reported, the same way:"; fi
996
+ printf %s "$jobs" | sed -n "$(( (r - 1) * slots + 1 )),$(( r * slots ))p" | sed 's/^/ /'
997
+ r=$((r + 1))
998
+ done
793
999
  [ "$(uname -s)" = Darwin ] || echo " iOS isn't checked here: it needs a Mac with Xcode"
794
1000
  }
795
1001
 
1002
+ # a part beyond the flows (more parts than flows) has nothing to check: no build, and no device made for it
1003
+ if [ -n "$part" ] && [ -z "$(flow_files)" ]; then
1004
+ case $mode in ios | android | all) echo "verify: part $part has no flows: there are fewer flows than parts"; exit 0 ;; esac
1005
+ fi
1006
+
796
1007
  case $mode in
797
1008
  quick) quick ;;
798
1009
  ios) ios ;;
@@ -1,6 +1,10 @@
1
1
  # Copy to .maestro/<id>.yaml. verify.sh runs it on iOS and Android and keeps the screenshots as evidence.
2
2
  # Tap by testID (give every interactive element one); tapping by text can hit a label instead of the control.
3
3
  # Test logins: ${MAESTRO_EMAIL}, ${MAESTRO_PASSWORD} and the like, set in .maestro/.env.local, which isn't committed.
4
+ # On a real iPhone (maestro-runner): text with an apostrophe can't be searched for (use a testID), and permission
5
+ # prompts aren't answered for the flow (tapOn: { text: "Allow", optional: true }). setAirplaneMode works only on an
6
+ # iPhone in English (it looks for "Airplane Mode" in Settings) and leaves Settings in front: launchApp: { stopApp: false }
7
+ # brings the app back. verify.sh opens Settings on its main page before such a flow, and turns airplane mode off after.
4
8
  appId: ${APP_ID} # set by verify.sh
5
9
  ---
6
10
  - launchApp: