agentic-mobile-kit 0.1.0 → 0.2.1
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/README.md +6 -0
- package/bin/cli.js +5 -0
- package/lib/doctor.js +167 -0
- package/lib/init.js +7 -4
- 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/README.md
CHANGED
|
@@ -13,6 +13,12 @@ npx agentic-mobile-kit init
|
|
|
13
13
|
npx agentic-mobile-kit init --tools claude,codex,antigravity # choose your AI tools
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
+
Then check the project and your machine, with a fix for each problem:
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
npx agentic-mobile-kit doctor
|
|
20
|
+
```
|
|
21
|
+
|
|
16
22
|
`init` never overwrites your files. It adds its section to an existing `AGENTS.md` between `KIT` markers, and it's safe to run again. Undo it with git.
|
|
17
23
|
|
|
18
24
|
## What it adds
|
package/bin/cli.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
const { version } = require('../package.json');
|
|
3
3
|
const { init, printSummary, InitError, TOOLS } = require('../lib/init');
|
|
4
|
+
const { doctor, printDoctor } = require('../lib/doctor');
|
|
4
5
|
|
|
5
6
|
const [cmd, ...rest] = process.argv.slice(2);
|
|
6
7
|
const flag = name => {
|
|
@@ -12,9 +13,11 @@ const help = `agentic-mobile-kit ${version}
|
|
|
12
13
|
|
|
13
14
|
Usage:
|
|
14
15
|
npx agentic-mobile-kit init [--tools claude,codex,antigravity] [--pm yarn|npm|pnpm|bun]
|
|
16
|
+
npx agentic-mobile-kit doctor
|
|
15
17
|
|
|
16
18
|
Commands:
|
|
17
19
|
init Install the kit into a bare React Native project (run in the app's root).
|
|
20
|
+
doctor Check the project and this machine, with a fix for each problem.
|
|
18
21
|
|
|
19
22
|
Options:
|
|
20
23
|
--tools AI tools your team uses: ${Object.keys(TOOLS).join(', ')} (default: claude,codex,antigravity)
|
|
@@ -31,6 +34,8 @@ if (cmd === '--version' || cmd === '-v') {
|
|
|
31
34
|
console.error(`init stopped: ${e.message}`);
|
|
32
35
|
process.exitCode = 1;
|
|
33
36
|
}
|
|
37
|
+
} else if (cmd === 'doctor') {
|
|
38
|
+
if (printDoctor(doctor(process.cwd())) > 0) process.exitCode = 1;
|
|
34
39
|
} else {
|
|
35
40
|
console.log(help);
|
|
36
41
|
if (cmd && cmd !== 'help' && cmd !== '--help' && cmd !== '-h') process.exitCode = 1;
|
package/lib/doctor.js
ADDED
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
// `agentic-mobile-kit doctor`: checks the project and this machine, and says how to fix each problem.
|
|
3
|
+
const fs = require('fs');
|
|
4
|
+
const os = require('os');
|
|
5
|
+
const path = require('path');
|
|
6
|
+
const { execFileSync, spawnSync } = require('child_process');
|
|
7
|
+
|
|
8
|
+
const RULESYNC = 'rulesync@27.0.0';
|
|
9
|
+
|
|
10
|
+
// run a command; return trimmed stdout, or null if it isn't installed or fails
|
|
11
|
+
function run(cmd, args, opts = {}) {
|
|
12
|
+
try { return execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 60000, ...opts }).trim(); } catch { return null; }
|
|
13
|
+
}
|
|
14
|
+
const version = s => (String(s || '').match(/(\d+)\.(\d+)(?:\.(\d+))?/) || []).slice(1).map(n => Number(n || 0));
|
|
15
|
+
const atLeast = (v, min) => { for (let i = 0; i < 3; i++) { if ((v[i] || 0) !== min[i]) return (v[i] || 0) > min[i]; } return true; };
|
|
16
|
+
const read = (cwd, f) => { try { return fs.readFileSync(path.join(cwd, f), 'utf8'); } catch { return null; } };
|
|
17
|
+
|
|
18
|
+
const ok = (label, detail = '') => ({ level: 'ok', label, detail });
|
|
19
|
+
const warn = (label, fix) => ({ level: 'warn', label, fix });
|
|
20
|
+
const fail = (label, fix) => ({ level: 'fail', label, fix });
|
|
21
|
+
|
|
22
|
+
function projectChecks(cwd, opts) {
|
|
23
|
+
const out = [];
|
|
24
|
+
const agents = read(cwd, 'AGENTS.md');
|
|
25
|
+
if (!agents || !/<!-- KIT:START/.test(agents) || !fs.existsSync(path.join(cwd, '.agents/skills/m-feature/SKILL.md'))) {
|
|
26
|
+
out.push(fail('Kit installed', 'run: npx agentic-mobile-kit init'));
|
|
27
|
+
return out; // the rest needs the kit
|
|
28
|
+
}
|
|
29
|
+
out.push(ok('Kit installed'));
|
|
30
|
+
|
|
31
|
+
const lines = agents.split('\n').length;
|
|
32
|
+
const bytes = Buffer.byteLength(agents);
|
|
33
|
+
out.push(lines <= 150 && bytes <= 8192
|
|
34
|
+
? ok('AGENTS.md size', `${lines} lines`)
|
|
35
|
+
: warn(`AGENTS.md is ${lines} lines / ${bytes} bytes`, 'keep it under 150 lines and 8 KB; tools truncate or ignore long files. Move details to docs/ai/'));
|
|
36
|
+
|
|
37
|
+
const hooksPath = run('git', ['config', 'core.hooksPath'], { cwd });
|
|
38
|
+
out.push(hooksPath === '.githooks'
|
|
39
|
+
? ok('Git hooks active')
|
|
40
|
+
: fail('Git hooks not active on this clone', 'run: git config core.hooksPath .githooks (your package manager\'s install does this too)'));
|
|
41
|
+
|
|
42
|
+
const tracked = (run('git', ['ls-files'], { cwd }) || '').split('\n').filter(f => /(^|\/)\.env(\.(?!example$)[\w.-]+)?$/.test(f));
|
|
43
|
+
out.push(tracked.length ? fail(`Secret files tracked by git: ${tracked.join(', ')}`, 'git rm --cached them, rotate the secrets, keep them out of the repo') : ok('No .env files in git'));
|
|
44
|
+
|
|
45
|
+
const claudeLink = path.join(cwd, '.claude/skills');
|
|
46
|
+
if (fs.existsSync(path.join(cwd, '.claude/settings.json'))) {
|
|
47
|
+
out.push(fs.existsSync(path.join(claudeLink, 'm-feature/SKILL.md'))
|
|
48
|
+
? ok('Claude Code skills link')
|
|
49
|
+
: fail('.claude/skills link missing or broken', 'run: ln -sfn ../.agents/skills .claude/skills (on Windows, enable git symlinks)'));
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
if (!opts.skipNetwork && fs.existsSync(path.join(cwd, 'rulesync.jsonc'))) {
|
|
53
|
+
const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^npm_(config|package|lifecycle)_/i.test(k)));
|
|
54
|
+
const r = spawnSync('npx', ['-y', RULESYNC, 'generate', '--check'], { cwd, env, encoding: 'utf8', timeout: 120000 });
|
|
55
|
+
out.push(r.status === 0
|
|
56
|
+
? ok('Tool configs match .rulesync/')
|
|
57
|
+
: warn('Tool configs out of date with .rulesync/', `run: npx -y ${RULESYNC} generate, then commit`));
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
const unfilled = ['product', 'tech', 'structure', 'conventions'].filter(n => {
|
|
61
|
+
const t = read(cwd, `docs/ai/${n}.md`);
|
|
62
|
+
return t !== null && t.replace(/<!--[\s\S]*?-->/g, '').replace(/^#.*$/gm, '').trim() === '';
|
|
63
|
+
});
|
|
64
|
+
out.push(unfilled.length
|
|
65
|
+
? warn(`docs/ai not filled in: ${unfilled.join(', ')}`, 'describe the app there; agents build better with it')
|
|
66
|
+
: ok('docs/ai filled in'));
|
|
67
|
+
return out;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
function machineChecks(cwd) {
|
|
71
|
+
const out = [];
|
|
72
|
+
const node = version(process.versions.node);
|
|
73
|
+
out.push(node[0] >= 20 ? ok('Node', process.versions.node) : fail(`Node ${process.versions.node}`, 'install Node 20 or newer'));
|
|
74
|
+
|
|
75
|
+
const pm = fs.existsSync(path.join(cwd, 'yarn.lock')) ? 'yarn' : fs.existsSync(path.join(cwd, 'pnpm-lock.yaml')) ? 'pnpm' : 'npm';
|
|
76
|
+
out.push(run(pm, ['--version'], { cwd }) ? ok(`Package manager (${pm})`) : fail(`${pm} not found`, pm === 'npm' ? 'install Node' : 'run: corepack enable'));
|
|
77
|
+
out.push(fs.existsSync(path.join(cwd, 'node_modules')) ? ok('Dependencies installed') : fail('Dependencies not installed', 'run: sh scripts/ai/install-deps.sh'));
|
|
78
|
+
|
|
79
|
+
// iOS (macOS only)
|
|
80
|
+
if (process.platform === 'darwin') {
|
|
81
|
+
const xcode = run('xcodebuild', ['-version']);
|
|
82
|
+
out.push(xcode ? ok('Xcode', xcode.split('\n')[0]) : fail('Xcode not found', 'install Xcode from the App Store, then: sudo xcode-select -s /Applications/Xcode.app'));
|
|
83
|
+
out.push(run('pod', ['--version']) ? ok('CocoaPods') : fail('CocoaPods not found', 'install it: brew install cocoapods'));
|
|
84
|
+
if (fs.existsSync(path.join(cwd, 'ios'))) {
|
|
85
|
+
out.push(fs.existsSync(path.join(cwd, 'ios/Pods')) ? ok('iOS pods installed') : warn('iOS pods not installed', 'run: cd ios && pod install'));
|
|
86
|
+
}
|
|
87
|
+
const sims = run('xcrun', ['simctl', 'list', 'devices', 'available']);
|
|
88
|
+
out.push(sims && /iPhone/.test(sims) ? ok('iPhone simulator available') : warn('No iPhone simulator', 'add one in Xcode > Settings > Components / Window > Devices and Simulators'));
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
// Android
|
|
92
|
+
const sdk = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT || path.join(os.homedir(), 'Library/Android/sdk');
|
|
93
|
+
const adb = path.join(sdk, 'platform-tools/adb');
|
|
94
|
+
out.push(fs.existsSync(adb) ? ok('Android SDK', sdk) : fail('Android SDK not found', 'install Android Studio, or set ANDROID_HOME'));
|
|
95
|
+
const avds = run(path.join(sdk, 'emulator/emulator'), ['-list-avds']);
|
|
96
|
+
out.push(avds ? ok('Android emulator', avds.split('\n')[0]) : warn('No Android emulator', 'create one in Android Studio > Device Manager'));
|
|
97
|
+
const java = spawnSync('java', ['-version'], { encoding: 'utf8' });
|
|
98
|
+
const jv = version((java.stderr || '').match(/version "([^"]+)"/)?.[1]);
|
|
99
|
+
out.push(jv[0] >= 17 ? ok('Java', jv.join('.')) : fail(java.error ? 'Java not found' : `Java ${jv.join('.')}`, 'install JDK 17 (e.g. the one bundled with Android Studio)'));
|
|
100
|
+
|
|
101
|
+
// tools the checks use
|
|
102
|
+
const maestro = run('maestro', ['--version']);
|
|
103
|
+
const ciMaestro = (read(cwd, '.github/workflows/e2e.yml') || '').match(/MAESTRO_VERSION:\s*([\d.]+)/)?.[1];
|
|
104
|
+
if (!maestro) out.push(warn('Maestro not installed (needed by verify.sh)', 'install: curl -fsSL https://get.maestro.mobile.dev | bash'));
|
|
105
|
+
else {
|
|
106
|
+
const mv = (maestro.split('\n').pop() || '').trim();
|
|
107
|
+
out.push(ciMaestro && mv !== ciMaestro
|
|
108
|
+
? warn(`Maestro ${mv} here, ${ciMaestro} in CI`, `use the same version: MAESTRO_VERSION=${ciMaestro} curl -fsSL https://get.maestro.mobile.dev | bash`)
|
|
109
|
+
: ok('Maestro', mv));
|
|
110
|
+
}
|
|
111
|
+
out.push(run('gitleaks', ['version']) ? ok('gitleaks') : warn('gitleaks not installed', 'pre-commit falls back to a basic secret check; install: brew install gitleaks'));
|
|
112
|
+
return out;
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
function aiToolChecks(cwd) {
|
|
116
|
+
const out = [];
|
|
117
|
+
const home = os.homedir();
|
|
118
|
+
const real = fs.realpathSync(cwd);
|
|
119
|
+
|
|
120
|
+
if (process.env.ANTHROPIC_API_KEY) {
|
|
121
|
+
out.push(warn('ANTHROPIC_API_KEY is set in this shell', 'Claude Code bills this API key instead of your Claude subscription; unset it if that isn\'t intended'));
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
const codexCfg = read(home, '.codex/config.toml');
|
|
125
|
+
if (codexCfg !== null && fs.existsSync(path.join(cwd, '.codex'))) {
|
|
126
|
+
const trusted = [cwd, real].some(p => codexCfg.includes(`[projects."${p}"]`) && new RegExp(`\\[projects\\."${p.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')}"\\][^\\[]*trust_level\\s*=\\s*"trusted"`).test(codexCfg));
|
|
127
|
+
out.push(trusted
|
|
128
|
+
? ok('Codex trusts this project', 'its hooks still need approving once in Codex')
|
|
129
|
+
: warn('Codex doesn\'t trust this project yet', 'open the project in Codex once, trust it and approve its hooks; until then the guard hook is off in Codex'));
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
const agy = run('agy', ['--version']);
|
|
133
|
+
if (agy) {
|
|
134
|
+
out.push(atLeast(version(agy), [1, 3, 0]) ? ok('Antigravity CLI', agy) : warn(`Antigravity CLI ${agy}`, 'update: agy update (versions before 1.3 ignore AGENTS.md)'));
|
|
135
|
+
let trusted = false;
|
|
136
|
+
try { trusted = (JSON.parse(read(home, '.gemini/antigravity-cli/settings.json') || '{}').trustedWorkspaces || []).some(p => p === cwd || p === real); } catch {}
|
|
137
|
+
out.push(trusted ? ok('Antigravity trusts this project') : warn('Antigravity doesn\'t trust this project yet', 'open it in Antigravity once and trust the folder'));
|
|
138
|
+
}
|
|
139
|
+
return out;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
function doctor(cwd, opts = {}) {
|
|
143
|
+
return [
|
|
144
|
+
['Project', projectChecks(cwd, opts)],
|
|
145
|
+
['This machine', machineChecks(cwd)],
|
|
146
|
+
['AI tools', aiToolChecks(cwd)],
|
|
147
|
+
];
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
function printDoctor(sections, log = console.log) {
|
|
151
|
+
const icon = { ok: '✓', warn: '!', fail: '✗' };
|
|
152
|
+
let failures = 0;
|
|
153
|
+
let warnings = 0;
|
|
154
|
+
for (const [title, checks] of sections) {
|
|
155
|
+
log(`\n${title}`);
|
|
156
|
+
for (const c of checks) {
|
|
157
|
+
if (c.level === 'fail') failures++;
|
|
158
|
+
if (c.level === 'warn') warnings++;
|
|
159
|
+
log(` ${icon[c.level]} ${c.label}${c.detail ? ` (${c.detail})` : ''}`);
|
|
160
|
+
if (c.fix) log(` → ${c.fix}`);
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
log(`\n${failures} problem(s), ${warnings} warning(s).`);
|
|
164
|
+
return failures;
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
module.exports = { doctor, printDoctor, projectChecks };
|
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
|
|
|
@@ -151,10 +151,13 @@ function init(cwd, opts = {}) {
|
|
|
151
151
|
const pkgFile = path.join(cwd, 'package.json');
|
|
152
152
|
const scripts = (pkg.scripts = pkg.scripts || {});
|
|
153
153
|
let pkgChanged = false;
|
|
154
|
-
|
|
154
|
+
// only TypeScript projects get typecheck: tsc fails ("no inputs") in JavaScript apps that merely have typescript installed
|
|
155
|
+
const hasTs = git(cwd, 'ls-files', '*.ts', '*.tsx').split('\n').some(f => f && !f.endsWith('.d.ts'));
|
|
156
|
+
if (!scripts.typecheck && deps.typescript && hasTs) { scripts.typecheck = 'tsc --noEmit'; pkgChanged = true; }
|
|
155
157
|
const hooksCmd = 'git config core.hooksPath .githooks || true';
|
|
156
158
|
if (!(scripts.postinstall || '').includes('core.hooksPath')) {
|
|
157
|
-
|
|
159
|
+
// parentheses keep the existing script's failure behavior: `a && b || true` would hide a failing `a`
|
|
160
|
+
scripts.postinstall = scripts.postinstall ? `${scripts.postinstall} && (${hooksCmd})` : hooksCmd;
|
|
158
161
|
pkgChanged = true;
|
|
159
162
|
}
|
|
160
163
|
if (pkgChanged) { fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`); report.merged.push('package.json (scripts)'); }
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agentic-mobile-kit",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "0.2.1",
|
|
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>
|