agentic-mobile-kit 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/init.js CHANGED
@@ -141,9 +141,9 @@ function init(cwd, opts = {}) {
141
141
  // 3. .gitignore: keep secrets out of git
142
142
  const gi = path.join(cwd, '.gitignore');
143
143
  const giText = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
144
- const missing = ['.env', '.env.*', '!.env.example'].filter(l => !giText.split('\n').includes(l));
144
+ const missing = ['.env', '.env.*', '!.env.example', '.ai/'].filter(l => !giText.split('\n').includes(l));
145
145
  if (missing.length) {
146
- fs.writeFileSync(gi, `${giText.replace(/\n*$/, giText ? '\n' : '')}\n# agentic-mobile-kit: secrets stay out of git\n${missing.join('\n')}\n`);
146
+ fs.writeFileSync(gi, `${giText.replace(/\n*$/, giText ? '\n' : '')}\n# agentic-mobile-kit: secrets stay out of git; .ai/ holds local evidence (screenshots, logs)\n${missing.join('\n')}\n`);
147
147
  report.merged.push('.gitignore');
148
148
  }
149
149
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentic-mobile-kit",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "One setup for AI-assisted mobile development that works the same in Claude Code, Codex, Cursor, OpenCode, Kiro and Antigravity. Early development.",
5
5
  "license": "MIT",
6
6
  "author": "prakashpro1",
@@ -17,7 +17,7 @@ Input: $ARGUMENTS (what's wrong, steps to reproduce, error text, screenshots, ta
17
17
  - Form one hypothesis, test it, and confirm or reject it. One at a time.
18
18
  - Fix the cause, not the symptom: no try/catch that hides the error, no special case for the failing input.
19
19
  5. **Make the smallest fix.** Don't refactor or touch unrelated code.
20
- 6. **Verify.** The new test passes, and lint, typecheck and all tests pass. Paste the output. For UI or native bugs, rebuild and check the affected platform(s).
20
+ 6. **Verify.** The new test passes, and lint, typecheck and all tests pass. Paste the output. For UI or native bugs, run `sh scripts/ai/verify.sh ios` and/or `android` and look at the screenshots.
21
21
  7. **Two attempts at most.** If two fixes didn't work, stop. Report what you tried, what you learned and what you suspect next.
22
22
  8. **Record it.** If this kind of error could come back, add an entry to `docs/ai/known-issues.md` (error, cause, fix, prevention).
23
23
  9. **Commit** with a message ending in `Assisted-by: <tool>/<model>`. Ask the user before pushing, then open a PR with the evidence.
@@ -25,7 +25,7 @@ If the input describes a bug rather than new behavior, suggest `m-bugfix` and st
25
25
 
26
26
  1. **Search the codebase before designing.** List the components, hooks, API clients and helpers you'll reuse in `design.md` under "Existing code to reuse". Read `docs/ai/structure.md` and `docs/ai/conventions.md`.
27
27
  2. Fill `design.md`: approach, files to change, risks (native changes, pod install, migrations).
28
- 3. Fill `tasks.md`: small tasks (about an hour, under ~300 changed lines each), each with its own check.
28
+ 3. Fill `tasks.md`: small tasks (about an hour, under ~300 changed lines each), each with its own check. The last task writes `.maestro/<id>.yaml` (from `specs/_templates/flow.yaml`), a Maestro flow that walks through the acceptance criteria, taps elements by `testID` and takes a screenshot per criterion.
29
29
  4. Show design and tasks and **stop until the user approves them**.
30
30
 
31
31
  ## 4. Build, one task at a time
@@ -39,7 +39,7 @@ For each task:
39
39
  ## 5. Check against the spec
40
40
 
41
41
  When all tasks are done:
42
- 1. For UI changes, build iOS (`sh scripts/ai/ios-build.sh`) and Android (`cd android && ./gradlew assembleDebug`) and say what you checked on each.
42
+ 1. Run `sh scripts/ai/verify.sh all --spec <id>`. Then **open the screenshots** in `.ai/evidence/<id>/` and check each one against its criterion. Maestro can report a tap as passed when nothing happened, so the screenshots are the evidence, not the log.
43
43
  2. Go through every acceptance criterion and note the evidence for it (test name, command output, or screen checked). If one isn't met, fix the code or ask whether the spec should change.
44
44
 
45
45
  ## 6. Review and pull request
@@ -0,0 +1,72 @@
1
+ # agentic-mobile-kit end-to-end check: runs the Maestro flows in .maestro/ on an Android emulator
2
+ # with a release build, the same way `sh scripts/ai/verify.sh android` does locally.
3
+ # Runs nightly, on demand, and on pull requests labelled "e2e". Screenshots are uploaded as an artifact.
4
+ name: e2e
5
+
6
+ on:
7
+ schedule:
8
+ - cron: "0 2 * * *"
9
+ workflow_dispatch:
10
+ pull_request:
11
+ types: [opened, synchronize, reopened, labeled]
12
+
13
+ concurrency:
14
+ group: e2e-${{ github.ref }}
15
+ cancel-in-progress: true
16
+
17
+ permissions:
18
+ contents: read
19
+
20
+ env:
21
+ MAESTRO_VERSION: 2.11.0
22
+ MAESTRO_SHA256: 5384593cb4e7a106489e75a821d157dd43f4e438df6bc308b72e82c685e1283a
23
+
24
+ jobs:
25
+ android:
26
+ if: github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'e2e')
27
+ runs-on: ubuntu-latest
28
+ timeout-minutes: 45
29
+ steps:
30
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
31
+ - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
32
+ with:
33
+ node-version: 24
34
+ - uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6.0.1
35
+ with:
36
+ distribution: temurin
37
+ java-version: 17
38
+ cache: gradle
39
+ - run: sh scripts/ai/install-deps.sh
40
+ - name: Install Maestro (pinned version, checksum verified)
41
+ run: |
42
+ curl -fsSL -o maestro.zip "https://github.com/mobile-dev-inc/maestro/releases/download/cli-$MAESTRO_VERSION/maestro.zip"
43
+ echo "$MAESTRO_SHA256 maestro.zip" | sha256sum -c -
44
+ unzip -q maestro.zip -d "$HOME" && rm maestro.zip
45
+ echo "$HOME/maestro/bin" >> "$GITHUB_PATH"
46
+ - name: Build release APK
47
+ working-directory: android
48
+ run: ./gradlew assembleRelease --no-daemon
49
+ - name: Enable KVM (hardware acceleration for the emulator)
50
+ run: |
51
+ echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
52
+ sudo udevadm control --reload-rules
53
+ sudo udevadm trigger --name-match=kvm
54
+ - name: Run Maestro flows on an emulator
55
+ uses: ReactiveCircus/android-emulator-runner@a421e43855164a8197daf9d8d40fe71c6996bb0d # v2.38.0
56
+ with:
57
+ api-level: 35
58
+ arch: x86_64
59
+ target: google_apis
60
+ profile: pixel_6
61
+ ram-size: 4096M
62
+ cores: 4
63
+ disable-animations: true
64
+ emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
65
+ script: sh scripts/ai/verify.sh android --label ci
66
+ - name: Upload screenshots and logs
67
+ if: always()
68
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
69
+ with:
70
+ name: e2e-evidence
71
+ path: .ai/evidence/
72
+ if-no-files-found: ignore
@@ -17,12 +17,13 @@ Read by Claude Code (through CLAUDE.md), Codex, Cursor, OpenCode, Kiro and Antig
17
17
  | iOS pods (after native dependency changes) | `cd ios && pod install` |
18
18
  | iOS build (simulator, no signing) | `sh scripts/ai/ios-build.sh` |
19
19
  | Android build | `cd android && ./gradlew assembleDebug` |
20
+ | Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/ai/verify.sh all --spec <id>` |
20
21
 
21
22
  ## Definition of done
22
23
 
23
24
  A task is done only when:
24
25
  1. lint, typecheck and tests pass, and you show the command output from this session;
25
- 2. UI changes were built and checked on both iOS and Android;
26
+ 2. UI changes were checked with `sh scripts/ai/verify.sh all --spec <id>` on both iOS and Android, and you looked at the screenshots;
26
27
  3. the change stays inside the task's scope;
27
28
  4. `specs/<id>/progress.md` is updated, when working from a spec.
28
29
 
@@ -1,11 +1,14 @@
1
1
  #!/bin/sh
2
2
  # Builds the iOS app for the simulator without code signing (CI and local checks).
3
+ # CONFIGURATION=Release builds a self-contained app (JS bundled; no Metro needed).
4
+ # Output goes to ios/DerivedData: ios/build holds React Native codegen files from pod install.
3
5
  set -eu
6
+ config=${CONFIGURATION:-Debug}
4
7
  workspace=$(ls -d ios/*.xcworkspace 2>/dev/null | head -n 1)
5
8
  [ -n "$workspace" ] || { echo "No ios/*.xcworkspace found. Run pod install in ios/ first."; exit 1; }
6
9
  scheme=$(basename "$workspace" .xcworkspace)
7
10
 
8
- xcodebuild -workspace "$workspace" -scheme "$scheme" -configuration Debug \
11
+ xcodebuild -workspace "$workspace" -scheme "$scheme" -configuration "$config" \
9
12
  -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' \
10
- -derivedDataPath ios/build CODE_SIGNING_ALLOWED=NO -quiet build
11
- echo "iOS simulator build OK ($scheme)"
13
+ -derivedDataPath ios/DerivedData CODE_SIGNING_ALLOWED=NO -quiet build
14
+ echo "iOS simulator build OK ($scheme, $config)"
@@ -0,0 +1,139 @@
1
+ #!/bin/sh
2
+ # Checks the app the way a user would: lint, typecheck and tests, then release builds on the iOS simulator
3
+ # and Android emulator, running Maestro flows and saving screenshots as evidence.
4
+ #
5
+ # Usage: sh scripts/ai/verify.sh [quick|ios|android|all] [--spec <id>] [--flow <file>] [--label <name>]
6
+ # quick lint, typecheck, tests
7
+ # ios|android release build, install, run flows, screenshots
8
+ # all everything (default)
9
+ # --spec <id> run .maestro/<id>*.yaml and save evidence in .ai/evidence/<id>/
10
+ # --label <n> evidence folder name (default: the spec id, or a timestamp)
11
+ # (no flows found: a smoke check that launches the app and takes a screenshot)
12
+ # Env: AMK_IOS_DEVICE (simulator name or UDID), AMK_ANDROID_AVD (emulator name)
13
+ set -eu
14
+
15
+ mode=${1:-all}
16
+ [ $# -gt 0 ] && shift
17
+ spec=""
18
+ flow=""
19
+ label=""
20
+ while [ $# -gt 0 ]; do
21
+ case $1 in
22
+ --spec) spec=$2; shift 2 ;;
23
+ --flow) flow=$2; shift 2 ;;
24
+ --label) label=$2; shift 2 ;;
25
+ *) echo "verify: unknown option $1"; exit 2 ;;
26
+ esac
27
+ done
28
+
29
+ root=$(pwd)
30
+ evidence="$root/.ai/evidence/${label:-${spec:-$(date +%Y%m%d-%H%M%S)}}"
31
+ mkdir -p "$evidence"
32
+ status=0
33
+
34
+ flow_files() {
35
+ if [ -n "$flow" ]; then echo "$root/$flow"
36
+ elif [ -n "$spec" ]; then find "$root/.maestro" -maxdepth 1 -iname "$spec*.yaml" 2>/dev/null | sort
37
+ else find "$root/.maestro" -maxdepth 1 -name '*.yaml' 2>/dev/null | sort
38
+ fi
39
+ }
40
+
41
+ run_flows() { # platform device app_id
42
+ out="$evidence/$1"
43
+ mkdir -p "$out"
44
+ files=$(flow_files)
45
+ if [ -z "$files" ]; then
46
+ printf 'appId: %s\n---\n- launchApp\n- takeScreenshot: smoke-launch\n' "$3" > "$out/smoke.yaml"
47
+ files="$out/smoke.yaml"
48
+ fi
49
+ passed=0
50
+ total=0
51
+ for f in $files; do
52
+ total=$((total + 1))
53
+ name=$(basename "$f" .yaml)
54
+ # screenshots use relative names: older Maestro saves them in the current folder, newer in --test-output-dir
55
+ if (cd "$out" && maestro --device "$2" test --test-output-dir "$out" -e APP_ID="$3" "$f" > "$out/$name.log" 2>&1); then
56
+ passed=$((passed + 1))
57
+ else
58
+ echo " $1: flow $name failed, see ${out#"$root"/}/$name.log"
59
+ status=1
60
+ fi
61
+ done
62
+ shots=$(find "$out" -name '*.png' | wc -l | tr -d ' ')
63
+ echo "$1: flows $passed/$total passed, $shots screenshots in ${out#"$root"/}"
64
+ if [ "$shots" = 0 ]; then
65
+ echo " $1: no screenshots were saved, so there's no evidence; treating this as a failure"
66
+ status=1
67
+ fi
68
+ }
69
+
70
+ quick() {
71
+ if sh scripts/ai/pm-run.sh lint > "$evidence/lint.log" 2>&1 &&
72
+ sh scripts/ai/pm-run.sh typecheck > "$evidence/typecheck.log" 2>&1 &&
73
+ CI=true sh scripts/ai/pm-run.sh test > "$evidence/test.log" 2>&1; then
74
+ echo "quick: lint, typecheck and tests passed"
75
+ else
76
+ echo "quick: FAILED, see the logs in ${evidence#"$root"/}"
77
+ status=1
78
+ fi
79
+ }
80
+
81
+ ios() {
82
+ command -v maestro > /dev/null || { echo "ios: Maestro isn't installed (https://maestro.dev)"; status=1; return; }
83
+ # pod install also generates React Native codegen files into ios/build/generated
84
+ if [ ! -d ios/Pods ] || [ ! -d ios/build/generated ]; then (cd ios && pod install > "$evidence/pod-install.log" 2>&1); fi
85
+ if ! CONFIGURATION=Release sh scripts/ai/ios-build.sh > "$evidence/ios-build.log" 2>&1; then
86
+ echo "ios: release build FAILED, see ${evidence#"$root"/}/ios-build.log"; status=1; return
87
+ fi
88
+ app=$(ls -d ios/DerivedData/Build/Products/Release-iphonesimulator/*.app | head -n 1)
89
+ app_id=$(/usr/libexec/PlistBuddy -c 'Print CFBundleIdentifier' "$app/Info.plist")
90
+ device=$(xcrun simctl list devices available -j | node -e '
91
+ const all = Object.entries(JSON.parse(require("fs").readFileSync(0, "utf8")).devices)
92
+ .flatMap(([rt, ds]) => ds.map(d => ({ ...d, v: (rt.match(/iOS-(\d+)-(\d+)/) || []).slice(1).map(Number) })))
93
+ .filter(d => d.v.length && /iPhone/.test(d.name));
94
+ const want = process.env.AMK_IOS_DEVICE;
95
+ const pick = want ? all.find(d => d.udid === want || d.name === want)
96
+ : all.find(d => d.state === "Booted") || all.sort((a, b) => b.v[0] - a.v[0] || b.v[1] - a.v[1])[0];
97
+ console.log(pick ? pick.udid : "");')
98
+ [ -n "$device" ] || { echo "ios: no iPhone simulator found (set AMK_IOS_DEVICE)"; status=1; return; }
99
+ xcrun simctl boot "$device" 2> /dev/null || true
100
+ xcrun simctl bootstatus "$device" -b > /dev/null
101
+ xcrun simctl install "$device" "$app"
102
+ run_flows ios "$device" "$app_id"
103
+ }
104
+
105
+ android() {
106
+ command -v maestro > /dev/null || { echo "android: Maestro isn't installed (https://maestro.dev)"; status=1; return; }
107
+ sdk=${ANDROID_HOME:-$HOME/Library/Android/sdk}
108
+ adb="$sdk/platform-tools/adb"
109
+ if ! (cd android && ./gradlew assembleRelease --no-daemon -q) > "$evidence/android-build.log" 2>&1; then
110
+ echo "android: release build FAILED, see ${evidence#"$root"/}/android-build.log"; status=1; return
111
+ fi
112
+ apk=$(ls android/app/build/outputs/apk/release/*.apk | head -n 1)
113
+ app_id=$(sed -n 's/.*applicationId *=\{0,1\} *"\([^"]*\)".*/\1/p' android/app/build.gradle* | head -n 1)
114
+ device=$("$adb" devices | awk 'NR > 1 && $2 == "device" { print $1; exit }')
115
+ if [ -z "$device" ]; then
116
+ avd=${AMK_ANDROID_AVD:-$("$sdk/emulator/emulator" -list-avds | head -n 1)}
117
+ [ -n "$avd" ] || { echo "android: no emulator found (create one in Android Studio)"; status=1; return; }
118
+ nohup "$sdk/emulator/emulator" -avd "$avd" -no-snapshot-save -no-boot-anim > /dev/null 2>&1 &
119
+ "$adb" wait-for-device
120
+ until [ "$("$adb" shell getprop sys.boot_completed 2> /dev/null | tr -d '\r')" = 1 ]; do sleep 3; done
121
+ device=$("$adb" devices | awk 'NR > 1 && $2 == "device" { print $1; exit }')
122
+ fi
123
+ "$adb" -s "$device" install -r "$apk" > /dev/null
124
+ # system "isn't responding" pop-ups (common on busy emulators) cover the app and fail flows; app crashes still fail them
125
+ "$adb" -s "$device" shell settings put global hide_error_dialogs 1
126
+ "$adb" -s "$device" shell am broadcast -a android.intent.action.CLOSE_SYSTEM_DIALOGS > /dev/null 2>&1 || true
127
+ run_flows android "$device" "$app_id"
128
+ }
129
+
130
+ case $mode in
131
+ quick) quick ;;
132
+ ios) ios ;;
133
+ android) android ;;
134
+ all) quick; ios; android ;;
135
+ *) echo "verify: unknown mode $mode (quick, ios, android or all)"; exit 2 ;;
136
+ esac
137
+
138
+ echo "Evidence: ${evidence#"$root"/}/ (open the screenshots: a tool saying 'passed' isn't proof)"
139
+ exit $status
@@ -0,0 +1,14 @@
1
+ # Copy to .maestro/<id>.yaml. verify.sh runs it on iOS and Android and keeps the screenshots as evidence.
2
+ # Tap by testID (give every interactive element one); tapping by text can hit a label instead of the control.
3
+ appId: ${APP_ID} # set by verify.sh
4
+ ---
5
+ - launchApp:
6
+ clearState: true
7
+ # Criterion 1: <WHEN … THE APP SHALL …>
8
+ - assertVisible:
9
+ id: "<testID of the element>"
10
+ - takeScreenshot: <id>-1-<short-name>
11
+ # Criterion 2: …
12
+ - tapOn:
13
+ id: "<testID>"
14
+ - takeScreenshot: <id>-2-<short-name>