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 +2 -2
- package/package.json +1 -1
- package/stacks/react-native/template/.agents/skills/m-bugfix/SKILL.md +1 -1
- package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +2 -2
- package/stacks/react-native/template/.github/workflows/e2e.yml +72 -0
- package/stacks/react-native/template/AGENTS.md +2 -1
- package/stacks/react-native/template/scripts/ai/ios-build.sh +6 -3
- package/stacks/react-native/template/scripts/ai/verify.sh +139 -0
- package/stacks/react-native/template/specs/_templates/flow.yaml +14 -0
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.
|
|
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,
|
|
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.
|
|
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
|
|
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
|
|
11
|
+
xcodebuild -workspace "$workspace" -scheme "$scheme" -configuration "$config" \
|
|
9
12
|
-sdk iphonesimulator -destination 'generic/platform=iOS Simulator' \
|
|
10
|
-
-derivedDataPath ios/
|
|
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>
|