agentic-mobile-kit 0.7.6 → 0.7.8
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/doctor.js +15 -0
- package/lib/init.js +64 -0
- package/package.json +1 -1
- package/stacks/react-native/expo/AGENTS.md +2 -1
- package/stacks/react-native/expo/docs/amk/expo.md +23 -1
- package/stacks/react-native/template/.agents/skills/m-explore/SKILL.md +1 -1
- package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +2 -2
- package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +4 -1
- package/stacks/react-native/template/.rulesync/subagents/m-reviewer.md +1 -1
- package/stacks/react-native/template/AGENTS.md +2 -1
- package/stacks/react-native/template/docs/amk/react-native.md +23 -1
- package/stacks/react-native/template/scripts/amk/screens.js +99 -0
- package/stacks/react-native/template/scripts/amk/verify.sh +193 -45
package/lib/doctor.js
CHANGED
|
@@ -5,6 +5,7 @@ const os = require('os');
|
|
|
5
5
|
const path = require('path');
|
|
6
6
|
const { spawnSync } = require('child_process');
|
|
7
7
|
const { tool, hookManager, hooksWired, checkProject, emptyFolder } = require('./init');
|
|
8
|
+
const screens = require('../stacks/react-native/template/scripts/amk/screens.js');
|
|
8
9
|
|
|
9
10
|
const RULESYNC = 'rulesync@27.0.0';
|
|
10
11
|
|
|
@@ -104,8 +105,19 @@ function projectChecks(cwd, opts) {
|
|
|
104
105
|
return out;
|
|
105
106
|
}
|
|
106
107
|
|
|
108
|
+
// an Android emulator's smallest screen width in dp, from its config.ini: 600 and up is a tablet
|
|
109
|
+
function avdWidth(name) {
|
|
110
|
+
const home = process.env.ANDROID_AVD_HOME || path.join(process.env.ANDROID_USER_HOME || path.join(os.homedir(), '.android'), 'avd');
|
|
111
|
+
const ini = Object.fromEntries((read(home, `${name}.avd/config.ini`) || '').split('\n').map(l => l.split('=').map(s => s.trim())));
|
|
112
|
+
const [w, h, d] = ['hw.lcd.width', 'hw.lcd.height', 'hw.lcd.density'].map(k => Number(ini[k]));
|
|
113
|
+
return d ? Math.min(w, h) * 160 / d : 0;
|
|
114
|
+
}
|
|
115
|
+
|
|
107
116
|
function machineChecks(cwd) {
|
|
108
117
|
const out = [];
|
|
118
|
+
// verify.sh checks tablets for apps that run on them, so they need an iPad simulator and a tablet emulator
|
|
119
|
+
const s = screens.screens(cwd);
|
|
120
|
+
const tablets = Boolean(s.ios && s.ios.tablet);
|
|
109
121
|
const node = version(process.versions.node);
|
|
110
122
|
out.push(node[0] >= 20 ? ok('Node', process.versions.node) : fail(`Node ${process.versions.node}`, 'install Node 20 or newer'));
|
|
111
123
|
|
|
@@ -126,6 +138,7 @@ function machineChecks(cwd) {
|
|
|
126
138
|
}
|
|
127
139
|
const sims = run('xcrun', ['simctl', 'list', 'devices', 'available']);
|
|
128
140
|
out.push(sims && /iPhone/.test(sims) ? ok('iPhone simulator available') : warn('No iPhone simulator', 'add one in Xcode > Settings > Components / Window > Devices and Simulators'));
|
|
141
|
+
if (tablets) out.push(sims && /iPad/.test(sims) ? ok('iPad simulator available') : warn('No iPad simulator: the app runs on iPad, so verify.sh checks iPads', 'add one in Xcode > Window > Devices and Simulators'));
|
|
129
142
|
}
|
|
130
143
|
|
|
131
144
|
// Android
|
|
@@ -134,6 +147,8 @@ function machineChecks(cwd) {
|
|
|
134
147
|
out.push(fs.existsSync(adb) ? ok('Android SDK', sdk) : fail('Android SDK not found', 'install Android Studio, or set ANDROID_HOME'));
|
|
135
148
|
const avds = run(path.join(sdk, 'emulator/emulator'), ['-list-avds']);
|
|
136
149
|
out.push(avds ? ok('Android emulator', avds.split('\n')[0]) : warn('No Android emulator', 'create one in Android Studio > Device Manager'));
|
|
150
|
+
const tabletAvd = (avds || '').split('\n').find(a => a && avdWidth(a) >= 600);
|
|
151
|
+
if (tablets) out.push(tabletAvd ? ok('Android tablet emulator', tabletAvd) : warn('No Android tablet emulator: the app runs on tablets, so verify.sh checks them', 'create one in Android Studio > Device Manager > Tablet'));
|
|
137
152
|
const java = spawnSync('java', ['-version'], { encoding: 'utf8' });
|
|
138
153
|
const jv = version((java.stderr || '').match(/version "([^"]+)"/)?.[1]);
|
|
139
154
|
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)'));
|
package/lib/init.js
CHANGED
|
@@ -9,6 +9,7 @@ const { execFileSync, spawnSync } = require('child_process');
|
|
|
9
9
|
|
|
10
10
|
const KIT_VERSION = require('../package.json').version;
|
|
11
11
|
const TEMPLATE = path.join(__dirname, '..', 'stacks', 'react-native', 'template');
|
|
12
|
+
const screens = require(path.join(TEMPLATE, 'scripts', 'amk', 'screens.js'));
|
|
12
13
|
const RULESYNC = 'rulesync@27.0.0';
|
|
13
14
|
const MARKERS = /<!-- KIT:START[\s\S]*?<!-- KIT:END[^>]*-->\n?/;
|
|
14
15
|
// files with {{PLACEHOLDERS}} filled in from the project
|
|
@@ -169,6 +170,8 @@ function createApp(cwd, kind, { run = tool, log = console.log, pods = process.pl
|
|
|
169
170
|
try {
|
|
170
171
|
// the tools commit only in a repository they create; init needs everything committed
|
|
171
172
|
commit(own ? 'Initial commit' : 'Add the files that were already in the folder');
|
|
173
|
+
newAppDefaults(cwd, kind, { run, log });
|
|
174
|
+
commit('Support tablets and landscape; stricter TypeScript with @/ imports');
|
|
172
175
|
// the first pod install changes the Xcode project and Info.plist: a commit of its own keeps that out of the first feature
|
|
173
176
|
if (kind === 'bare' && pods) {
|
|
174
177
|
log('Installing the iOS pods\n');
|
|
@@ -180,6 +183,66 @@ function createApp(cwd, kind, { run = tool, log = console.log, pods = process.pl
|
|
|
180
183
|
}
|
|
181
184
|
}
|
|
182
185
|
|
|
186
|
+
// What a new app starts with beyond the tool's template: iPad and every orientation (the React Native template locks
|
|
187
|
+
// iPhones to portrait; Expo's locks everything to portrait and leaves iPad out), and stricter TypeScript with "@/"
|
|
188
|
+
// imports for src/. Expo's template has the "@/" paths already, and Metro reads them; bare apps need a Babel plugin.
|
|
189
|
+
const STRICTER = { noUncheckedIndexedAccess: true, noImplicitOverride: true, noImplicitReturns: true, noFallthroughCasesInSwitch: true };
|
|
190
|
+
const ALIAS_PLUGIN = 'babel-plugin-module-resolver@5';
|
|
191
|
+
const ADD_DEV = { npm: ['npm', 'install', '--save-dev'], Yarn: ['yarn', 'add', '--dev'], pnpm: ['pnpm', 'add', '--save-dev'], Bun: ['bun', 'add', '--dev'] };
|
|
192
|
+
function newAppDefaults(cwd, kind, { run, log }) {
|
|
193
|
+
const edit = (rel, change) => {
|
|
194
|
+
const text = readIf(path.join(cwd, rel));
|
|
195
|
+
const next = text === null ? null : change(text);
|
|
196
|
+
if (next !== null && next !== text) fs.writeFileSync(path.join(cwd, rel), next);
|
|
197
|
+
};
|
|
198
|
+
const json = text => { try { return JSON.parse(text); } catch { return null; } };
|
|
199
|
+
// short lists stay on one line, as the templates write them
|
|
200
|
+
const format = j => `${JSON.stringify(j, null, 2).replace(/\[\n\s*([^[\]{}]*?)\n\s*\]/g, (m, items) => `[${items.split(/,\n\s*/).join(', ')}]`)}\n`;
|
|
201
|
+
const stricter = paths => text => {
|
|
202
|
+
const j = json(text);
|
|
203
|
+
if (!j) { log('! tsconfig.json isn\'t plain JSON, so the stricter TypeScript settings weren\'t added'); return null; }
|
|
204
|
+
const { extends: base, compilerOptions, ...rest } = j;
|
|
205
|
+
return format({ ...(base ? { extends: base } : {}), compilerOptions: { ...compilerOptions, ...STRICTER, ...(paths ? { paths: { '@/*': ['./src/*'] } } : {}) }, ...rest });
|
|
206
|
+
};
|
|
207
|
+
if (kind === 'expo') {
|
|
208
|
+
edit('app.json', text => {
|
|
209
|
+
const j = json(text);
|
|
210
|
+
if (!j || !j.expo) return null;
|
|
211
|
+
j.expo = { ...j.expo, orientation: 'default', ios: { ...j.expo.ios, supportsTablet: true } };
|
|
212
|
+
return `${JSON.stringify(j, null, 2)}\n`;
|
|
213
|
+
});
|
|
214
|
+
edit('tsconfig.json', stricter(false));
|
|
215
|
+
// Expo's types (CSS modules, assets) come from expo-env.d.ts, which `expo start` generates and git ignores: in a
|
|
216
|
+
// fresh clone or CI the template's own typecheck fails without them
|
|
217
|
+
if ((readIf(path.join(cwd, '.gitignore')) || '').split('\n').includes('expo-env.d.ts') && !fs.existsSync(path.join(cwd, 'expo-types.d.ts'))) {
|
|
218
|
+
fs.writeFileSync(path.join(cwd, 'expo-types.d.ts'), '// Expo\'s types, as expo-env.d.ts has them: that file is generated by `expo start` and not in git,\n// so type checks in a fresh clone or in CI need this one\n/// <reference types="expo/types" />\n');
|
|
219
|
+
}
|
|
220
|
+
return;
|
|
221
|
+
}
|
|
222
|
+
// bare: iPhones turn too; iPads already do, and Android doesn't lock
|
|
223
|
+
const plist = (fs.existsSync(path.join(cwd, 'ios')) ? fs.readdirSync(path.join(cwd, 'ios')) : [])
|
|
224
|
+
.map(d => `ios/${d}/Info.plist`).find(f => !/Tests\//.test(f) && fs.existsSync(path.join(cwd, f)));
|
|
225
|
+
if (plist) {
|
|
226
|
+
edit(plist, text => text.replace(/(<key>UISupportedInterfaceOrientations<\/key>\s*<array>)([\s\S]*?)(\s*<\/array>)/, (m, open, items, close) => {
|
|
227
|
+
if (items.includes('Landscape')) return m;
|
|
228
|
+
const indent = (items.match(/\n[ \t]*(?=<string>)/) || ['\n\t\t'])[0];
|
|
229
|
+
return `${open}${items}${indent}<string>UIInterfaceOrientationLandscapeLeft</string>${indent}<string>UIInterfaceOrientationLandscapeRight</string>${close}`;
|
|
230
|
+
}));
|
|
231
|
+
}
|
|
232
|
+
// "@/" imports: the Babel plugin rewrites them for Metro and Jest, tsconfig's paths for the type checker
|
|
233
|
+
const babel = readIf(path.join(cwd, 'babel.config.js'));
|
|
234
|
+
let alias = false;
|
|
235
|
+
if (babel !== null && !babel.includes('plugins') && /\n(\s*)presets: \[[^\]]*\],\n/.test(babel)) {
|
|
236
|
+
const [bin, ...args] = ADD_DEV[detectPm(cwd).name];
|
|
237
|
+
log(`Adding ${ALIAS_PLUGIN} for "@/" imports\n`);
|
|
238
|
+
if (run(bin, [...args, ALIAS_PLUGIN], { cwd, stdio: 'inherit', env: cleanEnv() }).status === 0) {
|
|
239
|
+
edit('babel.config.js', text => text.replace(/\n(\s*)presets: \[[^\]]*\],\n/, (m, indent) => `${m}${indent}plugins: [['module-resolver', { alias: { '^@/(.+)': './src/\\\\1' } }]],\n`));
|
|
240
|
+
alias = true;
|
|
241
|
+
} else log('! Couldn\'t install the Babel plugin for "@/" imports (see above), so the app uses relative imports.');
|
|
242
|
+
}
|
|
243
|
+
edit('tsconfig.json', stricter(alias));
|
|
244
|
+
}
|
|
245
|
+
|
|
183
246
|
// Expo apps whose ios/ and android/ come from `expo prebuild` (Continuous Native Generation, not in git) get the
|
|
184
247
|
// Expo overlay. Expo apps that keep the native folders in git are set up like bare apps.
|
|
185
248
|
function detectStack(cwd, deps) {
|
|
@@ -259,6 +322,7 @@ function projectValues(cwd, pkg, deps, pm, ci, stack) {
|
|
|
259
322
|
NODE_VERSION: (pkg.engines && pkg.engines.node) || `${process.versions.node.split('.')[0]}`,
|
|
260
323
|
PM: pm.name,
|
|
261
324
|
PM_RUN: pm.run,
|
|
325
|
+
SCREENS: screens.describe(screens.screens(cwd)),
|
|
262
326
|
IOS_BUNDLE_ID: stack === 'expo' ? (expoConfig(cwd).ios || {}).bundleIdentifier || 'com.example.app' : iosBundleId(cwd),
|
|
263
327
|
};
|
|
264
328
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agentic-mobile-kit",
|
|
3
|
-
"version": "0.7.
|
|
3
|
+
"version": "0.7.8",
|
|
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",
|
|
@@ -9,6 +9,7 @@ This project may also use other AI workflow frameworks (for example Superpowers,
|
|
|
9
9
|
|
|
10
10
|
- Expo SDK {{EXPO_SDK}}, React Native {{RN_VERSION}} ({{RN_ARCH}}), React {{REACT_VERSION}}, {{LANGUAGE}}, Node {{NODE_VERSION}}. Package manager: {{PM}}.
|
|
11
11
|
- `ios/` and `android/` are generated by `npx expo prebuild` and aren't in git (Continuous Native Generation). The kit's scripts generate them when they need them.
|
|
12
|
+
- Screens: {{SCREENS}}. Build every screen for each of them (`docs/amk/expo.md`, Tablets and landscape); `verify.sh` checks each one.
|
|
12
13
|
- What the app does: `docs/amk/product.md`, and requirement by requirement, as it works now: `specs/current/`. Stack and services: `docs/amk/tech.md`. Folders and layers: `docs/amk/structure.md`. Code style: `docs/amk/conventions.md`.
|
|
13
14
|
|
|
14
15
|
## Commands
|
|
@@ -28,7 +29,7 @@ This project may also use other AI workflow frameworks (for example Superpowers,
|
|
|
28
29
|
|
|
29
30
|
A task is done only when:
|
|
30
31
|
1. `sh scripts/amk/verify.sh quick` passes (lint, typecheck, tests) and you show its output from this session. In an app whose base branch already fails some of them, it passes when your change adds no new failure, and lists the old ones: leave those alone unless the task is to fix them;
|
|
31
|
-
2. UI changes were checked with `sh scripts/amk/verify.sh all --spec <id>` on both iOS and Android, and you looked at the screenshots. On Windows or Linux, that covers Android only: write in `progress.md` and the PR that iOS still needs checking on a Mac, and the PR isn't merged until a teammate with a Mac has done it;
|
|
32
|
+
2. UI changes were checked with `sh scripts/amk/verify.sh all --spec <id>` on both iOS and Android, on each screen listed above, and you looked at the screenshots. On Windows or Linux, that covers Android only: write in `progress.md` and the PR that iOS still needs checking on a Mac, and the PR isn't merged until a teammate with a Mac has done it;
|
|
32
33
|
3. the change stays inside the task's scope;
|
|
33
34
|
4. `specs/<id>/progress.md` is updated, when working from a spec.
|
|
34
35
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Expo rules
|
|
2
2
|
|
|
3
|
-
Rules for things AI agents commonly get wrong in Expo apps. Each one comes from a documented platform change.
|
|
3
|
+
Rules for things AI agents commonly get wrong in Expo apps. Each one comes from a documented platform change, or from a bug agents keep making on screens.
|
|
4
4
|
|
|
5
5
|
## Expo changes with every SDK
|
|
6
6
|
|
|
@@ -26,10 +26,32 @@ Rules for things AI agents commonly get wrong in Expo apps. Each one comes from
|
|
|
26
26
|
- Use `react-native-safe-area-context` for safe areas. React Native's built-in `SafeAreaView` is deprecated and iOS-only.
|
|
27
27
|
- Android draws edge to edge (Android 15 and later), so handle top and bottom insets on every screen.
|
|
28
28
|
- For apps targeting Android 16 (API 36), `onBackPressed` is no longer called. Handle back with `BackHandler` in JS.
|
|
29
|
+
- With the keyboard open, the field being typed in and the button that submits the form stay visible and tappable, on both platforms.
|
|
30
|
+
- Lists that grow with the user's data scroll (`FlatList`, or the list component the app already uses), and so does any screen taller than a small phone.
|
|
31
|
+
- At the largest system text size, text wraps instead of being cut off: no fixed heights on views that hold text. Don't turn off font scaling (`allowFontScaling={false}`) to make a layout fit.
|
|
32
|
+
- Messages that appear after an action, such as a form error, are read out by screen readers: announce them with `AccessibilityInfo.announceForAccessibility`.
|
|
29
33
|
- Check every UI change on both iOS and Android; behavior differs (keyboard, insets, fonts, permissions).
|
|
30
34
|
- Give every interactive element a `testID` (kebab-case, for example `dark-mode-switch`). End-to-end tools tap by `testID`. On iOS, React Native exposes a label and its control as duplicate accessibility elements, so tapping by text can hit the label: nothing happens, yet the tool reports success.
|
|
31
35
|
- Give every interactive element an `accessibilityLabel` that says what it does and an `accessibilityRole` (`button`, `link`, `switch`, …), so screen readers can use it. Icon-only buttons need it most; screen readers don't read `testID`.
|
|
32
36
|
|
|
37
|
+
## Tablets and landscape
|
|
38
|
+
|
|
39
|
+
`AGENTS.md` lists the screens this app supports: phones and tablets, portrait and landscape. Build every screen for each of them, and skip what isn't listed. `verify.sh` checks each one.
|
|
40
|
+
|
|
41
|
+
- One set of screens for every device: layouts adapt to the window. No separate tablet copies of screens, and no phone-width column centered on a tablet.
|
|
42
|
+
- Read the window size with `useWindowDimensions()`, which updates on rotation, split view and resizable windows. `Dimensions.get` read once at startup goes stale.
|
|
43
|
+
- Lay out by window width: under 600 points (dp on Android), the phone layout; from 600, the tablet layout, with more columns, and a list beside its detail where that helps. Text-heavy content and forms keep a readable width (about 600 to 700 points) instead of stretching edge to edge.
|
|
44
|
+
- Sizes: when the app already has a way to size things (a scaling helper, or sizes in its theme), use it everywhere and don't mix in another. A new app takes sizes from its theme: spacing and a few text sizes step up from 600 points, and text follows the system font size. Judge the tablet and landscape screenshots like the phone's: each should look made for that screen, not stretched or tiny.
|
|
45
|
+
- Landscape leaves little height: screens scroll, the keyboard covers more, and the safe-area insets include the left and right edges (the notch or Dynamic Island side).
|
|
46
|
+
- Apps targeting Android 16 (API 36) can't lock the orientation or size on tablets and foldables (600 dp wide and up): the system ignores the lock there. So on Android tablets every screen has to work turned, whatever the app's settings say.
|
|
47
|
+
- Don't lock the orientation in code to avoid layout work. Which orientations the app supports is a product decision, set in `app.json`: `orientation` (`default` turns, `portrait` or `landscape` locks) and `ios.supportsTablet` for the iPad app.
|
|
48
|
+
|
|
49
|
+
## TypeScript
|
|
50
|
+
|
|
51
|
+
- Keep the checks `tsconfig.json` has. Don't loosen them, or get past one with `any`, `@ts-ignore` or a non-null `!`.
|
|
52
|
+
- New apps from `init --new` also turn on `noUncheckedIndexedAccess`, `noImplicitOverride`, `noImplicitReturns` and `noFallthroughCasesInSwitch`. In an existing app, turning these on is a change of its own (`m-change`), since they flag code that already exists.
|
|
53
|
+
- Import with the app's path alias when `tsconfig.json` has one (`@/` for `src/` in new apps) instead of long relative paths. Expo's Metro reads the alias from `tsconfig.json` by itself.
|
|
54
|
+
|
|
33
55
|
## Performance and libraries
|
|
34
56
|
|
|
35
57
|
- Prefer Expo's own modules (`expo-image`, `expo-file-system`, `expo-secure-store`, …) when one fits.
|
|
@@ -14,5 +14,5 @@ Input: $ARGUMENTS (a problem, a question about how something works, or an idea t
|
|
|
14
14
|
2. **Explain what's there today:** the screens, state, API calls and native parts involved, and where iOS and Android differ.
|
|
15
15
|
3. **When there's a choice, lay out options:** two or three, each with its trade-offs (effort, risk, both platforms, native changes, store review, what it leaves unsolved). Say which one you'd pick and why. Diagrams help when the flow is complicated.
|
|
16
16
|
4. **Change nothing.** Exploring never edits code, config or project files. Write notes only when the user asks: a draft in `specs/<id>/requirements.md` for `m-feature`, or a decision in `docs/amk/decisions.md`.
|
|
17
|
-
5. **Confirm what's final, and write it down in one place.** When the exploration settled or changed what the app must do, ask the user whether these requirements are now final; don't assume it. Once they say yes, write them where the next workflow reads them, and tell the user the path: for the whole app, every feature with its rules in `docs/amk/product.md`, each marked planned until `m-feature` ships it; for one feature, a draft in `specs/<id>/requirements.md`. `decisions.md` logs choices and their reasons; it isn't the requirements document.
|
|
17
|
+
5. **Confirm what's final, and write it down in one place.** When the exploration settled or changed what the app must do, ask the user whether these requirements are now final; don't assume it. Once they say yes, write them where the next workflow reads them, and tell the user the path: for the whole app, every feature with its rules in `docs/amk/product.md`, each marked planned until `m-feature` ships it; for one feature, a draft in `specs/<id>/requirements.md`. `decisions.md` logs choices and their reasons; it isn't the requirements document. Then offer to commit those files on their own, so the next feature's branch starts from them instead of carrying them along uncommitted.
|
|
18
18
|
6. **Hand off when it's clear.** Suggest the next step: `m-feature <one-line summary>`, `m-change <one-line summary>` for a small change, `m-prototype <one-line summary>` when it needs a demo or a design before it's built, or `m-bugfix <one-line summary>`, carrying over what you found. If the idea turns out not to be worth doing, say so; learning that cheaply is a good outcome.
|
|
@@ -45,7 +45,7 @@ From here the plan lives in files, so the building can also run in a fresh sessi
|
|
|
45
45
|
## 4. Build, one task at a time
|
|
46
46
|
|
|
47
47
|
For each task:
|
|
48
|
-
1. Implement only that task. Write tests first for logic (state, data, utils); UI can be tested after.
|
|
48
|
+
1. Implement only that task. Write tests first for logic (state, data, utils); UI can be tested after. Build screens to the screen rules in the React Native rules file `AGENTS.md` names (keyboard, system bars, scrolling, large text, announced messages), for every phone, tablet and orientation `AGENTS.md` lists: they're the bugs device checks and reviews find most.
|
|
49
49
|
2. Run `lint`, `typecheck` and `test` (see AGENTS.md). Paste the real output. If something fails, fix it; after 2 failed attempts, stop and report.
|
|
50
50
|
3. Commit with a clear message ending in `Spec: specs/<id>`.
|
|
51
51
|
4. Tick the task in `tasks.md` and update the handoff block and log in `progress.md`.
|
|
@@ -55,7 +55,7 @@ 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 all --spec <id>`. 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. Then **open the screenshots** in `.amk/evidence/<id>/` and check each one against its scenario. Maestro can report a tap as passed when nothing happened, so the screenshots are the evidence, not the log.
|
|
58
|
+
1. Run `sh scripts/amk/verify.sh all --spec <id>`. 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. Then **open the screenshots** in `.amk/evidence/<id>/` and check each one against its scenario, in every screen's folder (phone, landscape, tablet). A turned screen's screenshots are landscape; one that shows the screen sideways 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.
|
|
59
59
|
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.
|
|
60
60
|
|
|
61
61
|
## 6. Update the living spec and the docs
|
|
@@ -20,8 +20,11 @@ If your tool has subagents, hand the review to the `m-reviewer` subagent, so it
|
|
|
20
20
|
- *Coherent:* the decisions in `design.md` show up in the code, and `specs/current/` was updated (`node scripts/amk/specs.js merge <id>`) if behavior changed.
|
|
21
21
|
- **No spec:** does the diff do what was asked, and nothing unrelated?
|
|
22
22
|
- **Tests:** were tests added for new logic? Were any tests deleted, skipped or weakened?
|
|
23
|
+
- **TypeScript:** any new `any`, `@ts-ignore` or non-null `!` to get past a check, or a loosened `tsconfig.json`?
|
|
23
24
|
- **Both platforms:** anything iOS-only or Android-only (insets, back button, permissions, keyboard)?
|
|
24
|
-
- **
|
|
25
|
+
- **Screens:** with the keyboard open, do the field and its button stay visible? Does anything sit under the status bar, home indicator or gesture bar? Do lists that grow with the user's data scroll? Does text wrap at the largest text size?
|
|
26
|
+
- **Tablets and landscape** (the screens `AGENTS.md` lists): does each layout adapt to the window width (`useWindowDimensions`), rather than stretching or centering the phone layout? Do turned screens scroll, with the left and right insets handled? Are sizes done the app's existing way?
|
|
27
|
+
- **Accessibility:** does every new button or other touchable have an `accessibilityLabel` and an `accessibilityRole`? Are messages that appear after an action, such as form errors, announced to screen readers?
|
|
25
28
|
- **Errors and states:** offline, server errors, empty and loading states.
|
|
26
29
|
- **Security:** secrets, tokens, `.env` contents, logging of personal data.
|
|
27
30
|
- **Native:** `project.pbxproj`, `Podfile`, Gradle or manifest changes, and whether pods and builds were re-run.
|
|
@@ -9,7 +9,7 @@ claudecode:
|
|
|
9
9
|
You review code changes with fresh eyes. You never edit files. Use the shell only for read-only commands such as `git diff`, `git log` and `git show`.
|
|
10
10
|
|
|
11
11
|
1. Get the changes: `git diff main...HEAD`. If a spec exists in `specs/<id>/`, read its `requirements.md`.
|
|
12
|
-
2. Check scope, tests (added, deleted, weakened), iOS vs Android differences, error and empty states, secrets, native file changes, and performance.
|
|
12
|
+
2. Check scope, tests (added, deleted, weakened), iOS vs Android differences, screens (the keyboard covering a field or button, content under the system bars, lists that don't scroll, text cut off at large sizes), tablets and landscape for the screens AGENTS.md lists (layouts that adapt to the window width, turned screens that scroll), accessibility (labels and roles, messages announced to screen readers), TypeScript (new `any` or `@ts-ignore`, a loosened tsconfig), error and empty states, secrets, native file changes, and performance.
|
|
13
13
|
3. Confirm each finding in the code before reporting it.
|
|
14
14
|
4. Report each finding as: severity (blocker or should fix), file:line, the problem, and a suggested fix. No style nits.
|
|
15
15
|
5. End with "Ready for PR" or "Not ready: N blockers".
|
|
@@ -8,6 +8,7 @@ This project may also use other AI workflow frameworks (for example Superpowers,
|
|
|
8
8
|
## Project
|
|
9
9
|
|
|
10
10
|
- Bare React Native {{RN_VERSION}} ({{RN_ARCH}}), React {{REACT_VERSION}}, {{LANGUAGE}}, Node {{NODE_VERSION}}. Package manager: {{PM}}.
|
|
11
|
+
- Screens: {{SCREENS}}. Build every screen for each of them (`docs/amk/react-native.md`, Tablets and landscape); `verify.sh` checks each one.
|
|
11
12
|
- What the app does: `docs/amk/product.md`, and requirement by requirement, as it works now: `specs/current/`. Stack and services: `docs/amk/tech.md`. Folders and layers: `docs/amk/structure.md`. Code style: `docs/amk/conventions.md`.
|
|
12
13
|
|
|
13
14
|
## Commands
|
|
@@ -28,7 +29,7 @@ This project may also use other AI workflow frameworks (for example Superpowers,
|
|
|
28
29
|
|
|
29
30
|
A task is done only when:
|
|
30
31
|
1. `sh scripts/amk/verify.sh quick` passes (lint, typecheck, tests) and you show its output from this session. In an app whose base branch already fails some of them, it passes when your change adds no new failure, and lists the old ones: leave those alone unless the task is to fix them;
|
|
31
|
-
2. UI changes were checked with `sh scripts/amk/verify.sh all --spec <id>` on both iOS and Android, and you looked at the screenshots. On Windows or Linux, that covers Android only: write in `progress.md` and the PR that iOS still needs checking on a Mac, and the PR isn't merged until a teammate with a Mac has done it;
|
|
32
|
+
2. UI changes were checked with `sh scripts/amk/verify.sh all --spec <id>` on both iOS and Android, on each screen listed above, and you looked at the screenshots. On Windows or Linux, that covers Android only: write in `progress.md` and the PR that iOS still needs checking on a Mac, and the PR isn't merged until a teammate with a Mac has done it;
|
|
32
33
|
3. the change stays inside the task's scope;
|
|
33
34
|
4. `specs/<id>/progress.md` is updated, when working from a spec.
|
|
34
35
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# React Native rules (bare)
|
|
2
2
|
|
|
3
|
-
Rules for things AI agents commonly get wrong in current React Native. Each one comes from a documented platform change.
|
|
3
|
+
Rules for things AI agents commonly get wrong in current React Native. Each one comes from a documented platform change, or from a bug agents keep making on screens.
|
|
4
4
|
|
|
5
5
|
## Architecture
|
|
6
6
|
|
|
@@ -13,10 +13,32 @@ Rules for things AI agents commonly get wrong in current React Native. Each one
|
|
|
13
13
|
- Use `react-native-safe-area-context` for safe areas. React Native's built-in `SafeAreaView` is deprecated and iOS-only.
|
|
14
14
|
- Android draws edge to edge (Android 15 and later), so handle top and bottom insets on every screen.
|
|
15
15
|
- For apps targeting Android 16 (API 36), `onBackPressed` is no longer called. Handle back with `BackHandler` in JS, or `OnBackPressedDispatcher` in native code.
|
|
16
|
+
- With the keyboard open, the field being typed in and the button that submits the form stay visible and tappable, on both platforms.
|
|
17
|
+
- Lists that grow with the user's data scroll (`FlatList`, or the list component the app already uses), and so does any screen taller than a small phone.
|
|
18
|
+
- At the largest system text size, text wraps instead of being cut off: no fixed heights on views that hold text. Don't turn off font scaling (`allowFontScaling={false}`) to make a layout fit.
|
|
19
|
+
- Messages that appear after an action, such as a form error, are read out by screen readers: announce them with `AccessibilityInfo.announceForAccessibility`.
|
|
16
20
|
- Check every UI change on both iOS and Android; behavior differs (keyboard, insets, fonts, permissions).
|
|
17
21
|
- Give every interactive element a `testID` (kebab-case, for example `dark-mode-switch`). End-to-end tools tap by `testID`. On iOS, React Native exposes a label and its control as duplicate accessibility elements, so tapping by text can hit the label: nothing happens, yet the tool reports success.
|
|
18
22
|
- Give every interactive element an `accessibilityLabel` that says what it does and an `accessibilityRole` (`button`, `link`, `switch`, …), so screen readers can use it. Icon-only buttons need it most; screen readers don't read `testID`.
|
|
19
23
|
|
|
24
|
+
## Tablets and landscape
|
|
25
|
+
|
|
26
|
+
`AGENTS.md` lists the screens this app supports: phones and tablets, portrait and landscape. Build every screen for each of them, and skip what isn't listed. `verify.sh` checks each one.
|
|
27
|
+
|
|
28
|
+
- One set of screens for every device: layouts adapt to the window. No separate tablet copies of screens, and no phone-width column centered on a tablet.
|
|
29
|
+
- Read the window size with `useWindowDimensions()`, which updates on rotation, split view and resizable windows. `Dimensions.get` read once at startup goes stale.
|
|
30
|
+
- Lay out by window width: under 600 points (dp on Android), the phone layout; from 600, the tablet layout, with more columns, and a list beside its detail where that helps. Text-heavy content and forms keep a readable width (about 600 to 700 points) instead of stretching edge to edge.
|
|
31
|
+
- Sizes: when the app already has a way to size things (a scaling helper, or sizes in its theme), use it everywhere and don't mix in another. A new app takes sizes from its theme: spacing and a few text sizes step up from 600 points, and text follows the system font size. Judge the tablet and landscape screenshots like the phone's: each should look made for that screen, not stretched or tiny.
|
|
32
|
+
- Landscape leaves little height: screens scroll, the keyboard covers more, and the safe-area insets include the left and right edges (the notch or Dynamic Island side).
|
|
33
|
+
- Apps targeting Android 16 (API 36) can't lock the orientation or size on tablets and foldables (600 dp wide and up): the system ignores the lock there. So on Android tablets every screen has to work turned, whatever the app's settings say.
|
|
34
|
+
- Don't lock the orientation in code to avoid layout work. Which orientations the app supports is a product decision, set in `Info.plist` (`UISupportedInterfaceOrientations`, and `~ipad` for iPads) and the Android manifest (`android:screenOrientation`); the iPad app itself is the Xcode target's device family.
|
|
35
|
+
|
|
36
|
+
## TypeScript
|
|
37
|
+
|
|
38
|
+
- Keep the checks `tsconfig.json` has. Don't loosen them, or get past one with `any`, `@ts-ignore` or a non-null `!`.
|
|
39
|
+
- New apps from `init --new` also turn on `noUncheckedIndexedAccess`, `noImplicitOverride`, `noImplicitReturns` and `noFallthroughCasesInSwitch`. In an existing app, turning these on is a change of its own (`m-change`), since they flag code that already exists.
|
|
40
|
+
- Import with the app's path alias when `tsconfig.json` has one (`@/` for `src/` in new apps) instead of long relative paths. In a bare app the alias also needs `babel-plugin-module-resolver` with the same mapping in `babel.config.js`, or Metro and Jest won't find the files.
|
|
41
|
+
|
|
20
42
|
## Native changes
|
|
21
43
|
|
|
22
44
|
- After adding or removing a native dependency: `sh scripts/amk/pod-install.sh`, then rebuild both apps. Restart Metro with `--reset-cache` if the bundle looks stale.
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// The screens the app supports: phones and tablets, portrait and landscape, on iOS and Android. Read from the native
|
|
3
|
+
// projects (app.json in an Expo app that doesn't have them yet), so agents build for them and verify.sh checks them.
|
|
4
|
+
// The app runs on tablets when its iOS app runs on iPad; Android runs every app on tablets, but the kit checks
|
|
5
|
+
// Android tablets only for apps made for tablets.
|
|
6
|
+
// Usage: node scripts/amk/screens.js one sentence, as AGENTS.md says it
|
|
7
|
+
// node scripts/amk/screens.js ios|android the screens to check, one per line: phone-portrait, tablet-landscape, …
|
|
8
|
+
'use strict';
|
|
9
|
+
const fs = require('fs');
|
|
10
|
+
const path = require('path');
|
|
11
|
+
|
|
12
|
+
const BOTH = ['portrait', 'landscape'];
|
|
13
|
+
const read = f => { try { return fs.readFileSync(f, 'utf8'); } catch { return null; } };
|
|
14
|
+
|
|
15
|
+
// an Info.plist array's orientations, or null without the key (upside down counts as portrait)
|
|
16
|
+
function plistOrientations(plist, key) {
|
|
17
|
+
const m = plist.match(new RegExp(`<key>${key}</key>\\s*<array>([\\s\\S]*?)</array>`));
|
|
18
|
+
if (!m) return null;
|
|
19
|
+
const found = BOTH.filter(o => m[1].includes(`UIInterfaceOrientation${o === 'portrait' ? 'Portrait' : 'Landscape'}`));
|
|
20
|
+
return found.length ? found : null;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
function ios(cwd) {
|
|
24
|
+
const dir = path.join(cwd, 'ios');
|
|
25
|
+
const proj = (fs.existsSync(dir) ? fs.readdirSync(dir) : []).find(f => f.endsWith('.xcodeproj'));
|
|
26
|
+
if (!proj) return null;
|
|
27
|
+
const pbx = read(path.join(dir, proj, 'project.pbxproj')) || '';
|
|
28
|
+
// the app target's Info.plist, not a test target's
|
|
29
|
+
const plistFile = [...pbx.matchAll(/INFOPLIST_FILE = "?([^";]+)"?;/g)].map(m => m[1].replace(/^\$\(SRCROOT\)\//, ''))
|
|
30
|
+
.find(f => !/Tests?\//.test(f)) || `${proj.replace(/\.xcodeproj$/, '')}/Info.plist`;
|
|
31
|
+
const plist = read(path.join(dir, plistFile)) || '';
|
|
32
|
+
// without the key, iOS lets the app turn both ways
|
|
33
|
+
const phone = plistOrientations(plist, 'UISupportedInterfaceOrientations') || BOTH;
|
|
34
|
+
const ipad = /TARGETED_DEVICE_FAMILY = "?[\d,]*2/.test(pbx);
|
|
35
|
+
return { phone, tablet: ipad ? plistOrientations(plist, 'UISupportedInterfaceOrientations~ipad') || phone : null };
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
const lockOf = value => (/portrait/i.test(value) ? ['portrait'] : /landscape/i.test(value) ? ['landscape'] : BOTH);
|
|
39
|
+
|
|
40
|
+
function android(cwd) {
|
|
41
|
+
const manifest = read(path.join(cwd, 'android/app/src/main/AndroidManifest.xml'));
|
|
42
|
+
if (manifest === null) return null;
|
|
43
|
+
// the launcher activity's orientation lock, if it has one
|
|
44
|
+
const at = manifest.lastIndexOf('<activity', manifest.indexOf('android.intent.action.MAIN'));
|
|
45
|
+
const tag = at < 0 ? '' : manifest.slice(at, manifest.indexOf('>', at) + 1);
|
|
46
|
+
const phone = lockOf((tag.match(/android:screenOrientation="([^"]+)"/) || [])[1] || '');
|
|
47
|
+
// apps targeting Android 16 (API 36) can't lock the orientation on tablets: the system ignores it there
|
|
48
|
+
const gradle = ['build.gradle', 'app/build.gradle', 'gradle.properties'].map(f => read(path.join(cwd, 'android', f)) || '').join('\n');
|
|
49
|
+
const target = Number((gradle.match(/targetSdk(?:Version)?\s*[=:]?\s*(\d+)/) || [])[1]) || 36;
|
|
50
|
+
return { phone, tablet: target >= 36 ? BOTH : phone };
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
// app.json's expo section: "orientation" (no lock unless it says portrait or landscape) and ios.supportsTablet
|
|
54
|
+
function expo(cwd) {
|
|
55
|
+
let config;
|
|
56
|
+
try { config = JSON.parse(read(path.join(cwd, 'app.json'))).expo; } catch { return null; }
|
|
57
|
+
if (!config) return null;
|
|
58
|
+
const phone = lockOf(config.orientation || '');
|
|
59
|
+
return { ios: { phone, tablet: config.ios && config.ios.supportsTablet ? phone : null }, android: { phone, tablet: BOTH } };
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
function screens(cwd) {
|
|
63
|
+
const fromExpo = expo(cwd);
|
|
64
|
+
const i = ios(cwd) || (fromExpo && fromExpo.ios);
|
|
65
|
+
const a = android(cwd) || (fromExpo && fromExpo.android);
|
|
66
|
+
const tablets = Boolean(i && i.tablet);
|
|
67
|
+
return {
|
|
68
|
+
ios: i && { phone: i.phone, tablet: tablets ? i.tablet : null },
|
|
69
|
+
android: a && { phone: a.phone, tablet: tablets ? a.tablet : null },
|
|
70
|
+
};
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
// the screens to check on a platform, phone portrait first
|
|
74
|
+
function list(s, platform) {
|
|
75
|
+
const p = s[platform] || { phone: ['portrait'], tablet: null };
|
|
76
|
+
return [...p.phone.map(o => `phone-${o}`), ...(p.tablet || []).map(o => `tablet-${o}`)];
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
function describe(s) {
|
|
80
|
+
const say = o => (o.length === 2 ? 'portrait and landscape' : `${o[0]} only`);
|
|
81
|
+
const part = (kind, apple) => {
|
|
82
|
+
const i = s.ios && s.ios[kind];
|
|
83
|
+
const a = s.android && s.android[kind];
|
|
84
|
+
if (i && a && say(i) !== say(a)) return `${say(i)} on ${apple}, ${say(a)} on Android`;
|
|
85
|
+
return say(i || a || ['portrait']);
|
|
86
|
+
};
|
|
87
|
+
const tablets = (s.ios && s.ios.tablet) || (s.android && s.android.tablet);
|
|
88
|
+
return tablets
|
|
89
|
+
? `phones (${part('phone', 'iPhone')}) and tablets (${part('tablet', 'iPad')})`
|
|
90
|
+
: `phones only (${part('phone', 'iPhone')}), no iPad app`;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
if (require.main === module) {
|
|
94
|
+
const s = screens(process.cwd());
|
|
95
|
+
const platform = process.argv[2];
|
|
96
|
+
console.log(platform ? list(s, platform).join('\n') : describe(s));
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
module.exports = { screens, list, describe };
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
#!/bin/sh
|
|
2
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.
|
|
3
|
+
# and Android emulator, running Maestro flows and saving screenshots as evidence. Apps that support tablets or
|
|
4
|
+
# landscape (scripts/amk/screens.js) are checked on each: an iPad simulator and a tablet emulator, and turned.
|
|
4
5
|
#
|
|
5
6
|
# Usage: sh scripts/amk/verify.sh [quick|ios|android|all] [--spec <id>] [--flow <file>] [--label <name>]
|
|
6
7
|
# [--flavor <name>] [--scheme <name>]
|
|
@@ -12,9 +13,11 @@
|
|
|
12
13
|
# --flavor <name> Android product flavor to check (default: the first one in build.gradle)
|
|
13
14
|
# --scheme <name> iOS scheme to check (default: the one named like the workspace)
|
|
14
15
|
# (no flows found: a smoke check that launches the app and takes a screenshot)
|
|
16
|
+
# Evidence per screen: ios/ and android/ (phone, portrait), then -landscape/, -tablet/ and -tablet-landscape/
|
|
15
17
|
# Env: AMK_ANDROID_FLAVOR, AMK_IOS_SCHEME (defaults for the two options), AMK_IOS_DEVICE (simulator name
|
|
16
|
-
# or UDID), AMK_ANDROID_DEVICE (adb serial: the only way to check on a phone
|
|
17
|
-
# AMK_ANDROID_AVD (the emulator to use, started if it isn't running; other devices are left alone)
|
|
18
|
+
# or UDID), AMK_ANDROID_DEVICE (adb serial: the only way to check on a phone, whose app data the flows clear),
|
|
19
|
+
# AMK_ANDROID_AVD (the emulator to use, started if it isn't running; other devices are left alone),
|
|
20
|
+
# AMK_IOS_TABLET (iPad simulator name or UDID), AMK_ANDROID_TABLET_AVD (tablet emulator), AMK_ANDROID_TABLET (serial)
|
|
18
21
|
# Flows that log in read ${MAESTRO_EMAIL} and the like from a local, gitignored .maestro/.env.local (never committed).
|
|
19
22
|
set -eu
|
|
20
23
|
|
|
@@ -48,7 +51,21 @@ flow_files() {
|
|
|
48
51
|
fi
|
|
49
52
|
}
|
|
50
53
|
|
|
51
|
-
|
|
54
|
+
run_flow() { # screen device app_id file name orientation
|
|
55
|
+
# Maestro's own log, which has errors its output leaves out; it adds to the file, so one run's log at a time
|
|
56
|
+
debug="$evidence/maestro-logs/$1-$5"
|
|
57
|
+
mkdir -p "$debug"
|
|
58
|
+
rm -f "$debug/maestro.log"
|
|
59
|
+
# the flow runs inside one that turns the device first and back to portrait after. Maestro reads the path in it
|
|
60
|
+
# itself, so it's a native path (a Windows path in Git Bash)
|
|
61
|
+
native=$(cd "$(dirname "$4")" && { pwd -W 2> /dev/null || pwd; })/$(basename "$4")
|
|
62
|
+
printf "appId: %s\nonFlowComplete:\n - setOrientation: PORTRAIT\n---\n- setOrientation: %s\n- runFlow: '%s'\n" "$3" "$6" "$native" > "$debug/screen.yaml"
|
|
63
|
+
# screenshots use relative names: older Maestro saves them in the current folder, newer in --test-output-dir
|
|
64
|
+
(cd "$out" && maestro --device "$2" test --test-output-dir "$out" --debug-output "$debug" --flatten-debug-output \
|
|
65
|
+
-e APP_ID="$3" "$debug/screen.yaml" > "$out/$5.log" 2>&1)
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
run_flows() { # screen device app_id orientation (PORTRAIT or LANDSCAPE_LEFT)
|
|
52
69
|
out="$evidence/$1"
|
|
53
70
|
mkdir -p "$out"
|
|
54
71
|
files=$(flow_files)
|
|
@@ -63,14 +80,30 @@ run_flows() { # platform device app_id
|
|
|
63
80
|
for f in $files; do
|
|
64
81
|
total=$((total + 1))
|
|
65
82
|
name=$(basename "$f" .yaml)
|
|
66
|
-
|
|
67
|
-
|
|
83
|
+
ok=0
|
|
84
|
+
run_flow "$1" "$2" "$3" "$f" "$name" "$4" || ok=$?
|
|
85
|
+
# an emulator sometimes drops its adb connection for a moment: reconnect, then run the flow once more
|
|
86
|
+
if [ "$ok" != 0 ] && [ "${1%%-*}" = android ] && grep -qs 'device offline' "$debug/maestro.log"; then
|
|
87
|
+
echo " $1: the device went offline during flow $name; running it once more"
|
|
88
|
+
"$adb" reconnect offline > /dev/null 2>&1 || true
|
|
89
|
+
android_ready "$2" || true
|
|
90
|
+
ok=0
|
|
91
|
+
run_flow "$1" "$2" "$3" "$f" "$name" "$4" || ok=$?
|
|
92
|
+
fi
|
|
93
|
+
if [ "$ok" = 0 ]; then
|
|
68
94
|
passed=$((passed + 1))
|
|
69
95
|
else
|
|
70
|
-
echo " $1: flow $name failed, see ${out#"$root"/}/$name.log"
|
|
96
|
+
echo " $1: flow $name failed, see ${out#"$root"/}/$name.log and Maestro's own log ${debug#"$root"/}/maestro.log"
|
|
71
97
|
status=1
|
|
72
98
|
fi
|
|
73
99
|
done
|
|
100
|
+
# iOS saves a turned screen's screenshots sideways, at the device's upright size: turn them back, for reviewing
|
|
101
|
+
case $1 in
|
|
102
|
+
ios*-landscape) find "$out" -name '*.png' | while read -r png; do
|
|
103
|
+
sips -g pixelWidth -g pixelHeight "$png" | awk '/pixelWidth/ { w = $2 } /pixelHeight/ { h = $2 } END { exit !(h + 0 > w + 0) }' &&
|
|
104
|
+
sips -r 270 "$png" > /dev/null
|
|
105
|
+
done ;;
|
|
106
|
+
esac
|
|
74
107
|
shots=$(find "$out" -name '*.png' | wc -l | tr -d ' ')
|
|
75
108
|
echo "$1: flows $passed/$total passed, $shots screenshots in ${out#"$root"/}"
|
|
76
109
|
if [ "$shots" = 0 ]; then
|
|
@@ -79,6 +112,29 @@ run_flows() { # platform device app_id
|
|
|
79
112
|
fi
|
|
80
113
|
}
|
|
81
114
|
|
|
115
|
+
# runs the flows on each screen the app supports: the phone upright into <platform>/, then <platform>-landscape/,
|
|
116
|
+
# <platform>-tablet/ and <platform>-tablet-landscape/
|
|
117
|
+
check_screens() { # platform phone tablet app_id screens…
|
|
118
|
+
p=$1 phone=$2 tab=$3 id=$4
|
|
119
|
+
shift 4
|
|
120
|
+
for screen in "$@"; do
|
|
121
|
+
case $screen in
|
|
122
|
+
tablet-*) [ -n "$tab" ] || continue; on=$tab where=$p-tablet ;;
|
|
123
|
+
*) on=$phone where=$p ;;
|
|
124
|
+
esac
|
|
125
|
+
# Maestro turns an Android device from its natural orientation, which on most tablets is landscape
|
|
126
|
+
upright=PORTRAIT turned=LANDSCAPE_LEFT
|
|
127
|
+
if [ "$p" = android ] && "$adb" -s "$on" shell wm size 2> /dev/null |
|
|
128
|
+
awk -F'[: x]+' '/Physical size/ { found = 1; wide = $3 + 0 > $4 + 0 } END { exit !(found && wide) }'; then
|
|
129
|
+
upright=LANDSCAPE_LEFT turned=PORTRAIT
|
|
130
|
+
fi
|
|
131
|
+
case $screen in
|
|
132
|
+
*-landscape) run_flows "$where-landscape" "$on" "$id" "$turned" ;;
|
|
133
|
+
*) run_flows "$where" "$on" "$id" "$upright" ;;
|
|
134
|
+
esac
|
|
135
|
+
done
|
|
136
|
+
}
|
|
137
|
+
|
|
82
138
|
quick() {
|
|
83
139
|
# each one passes when the app's script passes, or when all its failures were already on the base branch
|
|
84
140
|
if node scripts/amk/baseline.js lint > "$evidence/lint.log" 2>&1 &&
|
|
@@ -111,36 +167,97 @@ ios() {
|
|
|
111
167
|
if [ ! -d ios/Pods ] || [ ! -d ios/build/generated ] || [ ios/Podfile -nt ios/Pods/Manifest.lock ]; then
|
|
112
168
|
sh scripts/amk/pod-install.sh > "$evidence/pod-install.log" 2>&1
|
|
113
169
|
fi
|
|
170
|
+
# the simulators first, so they boot while Xcode builds
|
|
171
|
+
screens=$(node scripts/amk/screens.js ios)
|
|
172
|
+
device=$(simulator iPhone "${AMK_IOS_DEVICE:-}")
|
|
173
|
+
if [ -z "$device" ]; then
|
|
174
|
+
if [ -n "${AMK_IOS_DEVICE:-}" ]; then echo "ios: no simulator has the name or UDID \"$AMK_IOS_DEVICE\""; else echo "ios: no iPhone simulator found (set AMK_IOS_DEVICE)"; fi
|
|
175
|
+
status=1; return
|
|
176
|
+
fi
|
|
177
|
+
tablet=""
|
|
178
|
+
if echo "$screens" | grep -q '^tablet-'; then
|
|
179
|
+
tablet=$(simulator iPad "${AMK_IOS_TABLET:-}")
|
|
180
|
+
if [ -z "$tablet" ] && [ -n "${AMK_IOS_TABLET:-}" ]; then echo "ios: no simulator has the name or UDID \"$AMK_IOS_TABLET\""; status=1; return; fi
|
|
181
|
+
[ -n "$tablet" ] || echo "ios: the app runs on iPad, but there's no iPad simulator, so iPads aren't checked (add one in Xcode, or set AMK_IOS_TABLET)"
|
|
182
|
+
fi
|
|
183
|
+
for d in $device $tablet; do xcrun simctl boot "$d" 2> /dev/null || true; done
|
|
114
184
|
if ! CONFIGURATION=Release sh scripts/amk/ios-build.sh > "$evidence/ios-build.log" 2>&1; then
|
|
115
185
|
echo "ios: release build FAILED, see ${evidence#"$root"/}/ios-build.log"; status=1; return
|
|
116
186
|
fi
|
|
117
187
|
# the newest app: the scheme just built (another scheme's app may still be there from an earlier build)
|
|
118
188
|
app=$(ls -dt ios/DerivedData/Build/Products/*-iphonesimulator/*.app | head -n 1)
|
|
119
189
|
app_id=$(/usr/libexec/PlistBuddy -c 'Print CFBundleIdentifier' "$app/Info.plist")
|
|
120
|
-
|
|
190
|
+
for d in $device $tablet; do
|
|
191
|
+
xcrun simctl bootstatus "$d" -b > /dev/null
|
|
192
|
+
xcrun simctl install "$d" "$app"
|
|
193
|
+
done
|
|
194
|
+
check_screens ios "$device" "$tablet" "$app_id" $screens
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
# a simulator's UDID: the one named in $2 (name or UDID), else a booted $1 (iPhone or iPad), else one with the newest iOS
|
|
198
|
+
simulator() {
|
|
199
|
+
xcrun simctl list devices available -j | KIND=$1 WANT=$2 node -e '
|
|
121
200
|
const all = Object.entries(JSON.parse(require("fs").readFileSync(0, "utf8")).devices)
|
|
122
201
|
.flatMap(([rt, ds]) => ds.map(d => ({ ...d, v: (rt.match(/iOS-(\d+)-(\d+)/) || []).slice(1).map(Number) })))
|
|
123
202
|
.filter(d => d.v.length);
|
|
124
|
-
const want = process.env.
|
|
125
|
-
//
|
|
126
|
-
const
|
|
203
|
+
const want = process.env.WANT;
|
|
204
|
+
// by device type: a simulator can have any name, such as a separate one kept for tests
|
|
205
|
+
const kind = all.filter(d => (d.deviceTypeIdentifier || d.name).includes(process.env.KIND));
|
|
127
206
|
const pick = want ? all.find(d => d.udid === want || d.name === want)
|
|
128
|
-
:
|
|
129
|
-
console.log(pick ? pick.udid : "");'
|
|
130
|
-
if [ -z "$device" ]; then
|
|
131
|
-
if [ -n "${AMK_IOS_DEVICE:-}" ]; then echo "ios: no simulator has the name or UDID \"$AMK_IOS_DEVICE\""; else echo "ios: no iPhone simulator found (set AMK_IOS_DEVICE)"; fi
|
|
132
|
-
status=1; return
|
|
133
|
-
fi
|
|
134
|
-
xcrun simctl boot "$device" 2> /dev/null || true
|
|
135
|
-
xcrun simctl bootstatus "$device" -b > /dev/null
|
|
136
|
-
xcrun simctl install "$device" "$app"
|
|
137
|
-
run_flows ios "$device" "$app_id"
|
|
207
|
+
: kind.find(d => d.state === "Booted") || kind.sort((a, b) => b.v[0] - a.v[0] || b.v[1] - a.v[1])[0];
|
|
208
|
+
console.log(pick ? pick.udid : "");'
|
|
138
209
|
}
|
|
139
210
|
|
|
140
|
-
# a running emulator's adb serial
|
|
211
|
+
# a running emulator's adb serial: of the AVD named in $1 if one is, else of the kind in $2 (phone or tablet) if given
|
|
141
212
|
running_emulator() {
|
|
142
213
|
for d in $("$adb" devices | awk 'NR > 1 && $2 == "device" && /^emulator-/ { print $1 }'); do
|
|
143
|
-
if [ -
|
|
214
|
+
if [ -n "$1" ]; then
|
|
215
|
+
[ "$("$adb" -s "$d" emu avd name 2> /dev/null | head -n 1 | tr -d '\r')" = "$1" ] || continue
|
|
216
|
+
elif [ -n "${2:-}" ]; then
|
|
217
|
+
[ "$(kind_of "$(device_width "$d")")" = "$2" ] || continue
|
|
218
|
+
fi
|
|
219
|
+
echo "$d"; return
|
|
220
|
+
done
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
# a screen's smallest width in dp: 600 and up is a tablet
|
|
224
|
+
kind_of() { if [ "${1:-0}" -ge 600 ]; then echo tablet; else echo phone; fi; }
|
|
225
|
+
device_width() {
|
|
226
|
+
"$adb" -s "$1" shell 'wm size; wm density' 2> /dev/null | tr -d '\r' | awk -F': ' '
|
|
227
|
+
/Physical size/ { split($2, s, "x"); w = s[1] + 0 < s[2] + 0 ? s[1] : s[2] } /Physical density/ { d = $2 }
|
|
228
|
+
END { if (d) print int(w * 160 / d) }'
|
|
229
|
+
}
|
|
230
|
+
# the same for an emulator that isn't running, from its config.ini
|
|
231
|
+
avd_width() {
|
|
232
|
+
awk -F' *= *' '$1 == "hw.lcd.width" { w = $2 } $1 == "hw.lcd.height" { h = $2 } $1 == "hw.lcd.density" { d = $2 }
|
|
233
|
+
END { if (d) print int((w + 0 < h + 0 ? w : h) * 160 / d) }' \
|
|
234
|
+
"${ANDROID_AVD_HOME:-${ANDROID_USER_HOME:-$HOME/.android}/avd}/$1.avd/config.ini" 2> /dev/null || true
|
|
235
|
+
}
|
|
236
|
+
# the first AVD of the kind $1 (phone or tablet)
|
|
237
|
+
first_avd() {
|
|
238
|
+
for a in $avds; do
|
|
239
|
+
if [ "$(kind_of "$(avd_width "$a")")" = "$1" ]; then echo "$a"; return; fi
|
|
240
|
+
done
|
|
241
|
+
}
|
|
242
|
+
# starts the AVD $1 and prints its serial once adb sees it (up to 5 minutes)
|
|
243
|
+
start_emulator() {
|
|
244
|
+
nohup "$sdk/emulator/emulator" -avd "$1" -no-snapshot-save -no-boot-anim > /dev/null 2>&1 &
|
|
245
|
+
tries=0
|
|
246
|
+
until serial=$(running_emulator "$1") && [ -n "$serial" ]; do
|
|
247
|
+
tries=$((tries + 1))
|
|
248
|
+
[ "$tries" -le 150 ] || return 1
|
|
249
|
+
sleep 2
|
|
250
|
+
done
|
|
251
|
+
echo "$serial"
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
# waits for the Android device $1 to finish starting, for up to 5 minutes
|
|
255
|
+
android_ready() {
|
|
256
|
+
tries=0
|
|
257
|
+
until [ "$("$adb" -s "$1" shell getprop sys.boot_completed 2> /dev/null | tr -d '\r')" = 1 ]; do
|
|
258
|
+
tries=$((tries + 1))
|
|
259
|
+
[ "$tries" -le 100 ] || return 1
|
|
260
|
+
sleep 3
|
|
144
261
|
done
|
|
145
262
|
}
|
|
146
263
|
|
|
@@ -170,33 +287,55 @@ android() {
|
|
|
170
287
|
[ -z "$flavor" ] || echo "android: checking the \"$flavor\" flavor (the app has: $(echo $flavors)); --flavor <name> checks another"
|
|
171
288
|
fi
|
|
172
289
|
variant=$(printf %s "$flavor" | awk '{ print toupper(substr($0, 1, 1)) substr($0, 2) }')
|
|
173
|
-
# the
|
|
174
|
-
# The flows clear the app's data, so
|
|
175
|
-
|
|
176
|
-
|
|
290
|
+
# the devices first: the build only needs the CPU type, and emulators boot while Gradle builds.
|
|
291
|
+
# The flows clear the app's data, so a phone plugged in over USB is used only when AMK_ANDROID_DEVICE names it
|
|
292
|
+
screens=$(node scripts/amk/screens.js android)
|
|
293
|
+
avds=$("$sdk/emulator/emulator" -list-avds 2> /dev/null || true)
|
|
294
|
+
device=${AMK_ANDROID_DEVICE:-$(running_emulator "${AMK_ANDROID_AVD:-}" phone)}
|
|
177
295
|
if [ -z "$device" ]; then
|
|
178
|
-
|
|
179
|
-
avd=$
|
|
296
|
+
avd=${AMK_ANDROID_AVD:-$(first_avd phone)}
|
|
297
|
+
[ -n "$avd" ] || avd=$(echo "$avds" | head -n 1) # only tablet emulators: one of them
|
|
180
298
|
if [ -n "$avd" ]; then
|
|
181
299
|
echo "$avds" | grep -qxF "$avd" || { echo "android: there's no emulator named $avd (see: emulator -list-avds)"; status=1; return; }
|
|
182
|
-
|
|
183
|
-
tries=0
|
|
184
|
-
until device=$(running_emulator "$avd") && [ -n "$device" ]; do
|
|
185
|
-
tries=$((tries + 1))
|
|
186
|
-
[ "$tries" -le 150 ] || { echo "android: emulator $avd didn't start"; status=1; return; }
|
|
187
|
-
sleep 2
|
|
188
|
-
done
|
|
300
|
+
device=$(start_emulator "$avd") || { echo "android: emulator $avd didn't start"; status=1; return; }
|
|
189
301
|
else
|
|
190
|
-
|
|
191
|
-
|
|
302
|
+
phone=$("$adb" devices | awk 'NR > 1 && $2 == "device" { print $1; exit }')
|
|
303
|
+
echo "android: no emulator found (create one in Android Studio)"
|
|
304
|
+
[ -z "$phone" ] || echo " or check on the phone $phone, which clears the app's data on it: AMK_ANDROID_DEVICE=$phone sh scripts/amk/verify.sh android"
|
|
305
|
+
status=1; return
|
|
192
306
|
fi
|
|
193
307
|
fi
|
|
194
308
|
case $device in
|
|
195
309
|
emulator-*) echo "android: checking on $device" ;;
|
|
196
310
|
*) echo "android: checking on the phone $device; the flows clear the app's data on it" ;;
|
|
197
311
|
esac
|
|
198
|
-
|
|
199
|
-
|
|
312
|
+
tablet=""
|
|
313
|
+
if echo "$screens" | grep -q '^tablet-'; then
|
|
314
|
+
tablet=${AMK_ANDROID_TABLET:-$(running_emulator "${AMK_ANDROID_TABLET_AVD:-}" tablet)}
|
|
315
|
+
if [ -z "$tablet" ]; then
|
|
316
|
+
tablet_avd=${AMK_ANDROID_TABLET_AVD:-$(first_avd tablet)}
|
|
317
|
+
if [ -z "$tablet_avd" ]; then
|
|
318
|
+
echo "android: the app runs on tablets, but there's no tablet emulator, so tablets aren't checked (create one in Android Studio: Device Manager > Tablet, or set AMK_ANDROID_TABLET_AVD)"
|
|
319
|
+
elif ! echo "$avds" | grep -qxF "$tablet_avd"; then
|
|
320
|
+
echo "android: there's no emulator named $tablet_avd (see: emulator -list-avds)"; status=1; return
|
|
321
|
+
else
|
|
322
|
+
tablet=$(start_emulator "$tablet_avd") || { echo "android: emulator $tablet_avd didn't start, so tablets aren't checked"; tablet=""; }
|
|
323
|
+
fi
|
|
324
|
+
fi
|
|
325
|
+
[ "$tablet" != "$device" ] || tablet="" # only tablet emulators: the one in use is checked as the phone
|
|
326
|
+
case $tablet in
|
|
327
|
+
"") ;;
|
|
328
|
+
emulator-*) echo "android: tablets on $tablet" ;;
|
|
329
|
+
*) echo "android: tablets on $tablet; the flows clear the app's data on it" ;;
|
|
330
|
+
esac
|
|
331
|
+
fi
|
|
332
|
+
# an emulator that has just started (another one starting too) may not answer for a moment
|
|
333
|
+
tries=0
|
|
334
|
+
until abi=$("$adb" -s "$device" shell getprop ro.product.cpu.abi 2> /dev/null | tr -d '\r') && [ -n "$abi" ]; do
|
|
335
|
+
tries=$((tries + 1))
|
|
336
|
+
[ "$tries" -le 30 ] || { echo "android: device $device isn't connected (see: adb devices)"; status=1; return; }
|
|
337
|
+
sleep 2
|
|
338
|
+
done
|
|
200
339
|
# native code for that CPU type only, as run-android --active-arch-only does: much faster than all four
|
|
201
340
|
set -- -PreactNativeArchitectures="$abi"
|
|
202
341
|
# signed with the project's debug key, so the check build installs whatever key its real release needs
|
|
@@ -217,12 +356,21 @@ android() {
|
|
|
217
356
|
aapt2="$(ls -d "$sdk"/build-tools/*/ 2> /dev/null | sort -V | tail -n 1)aapt2"
|
|
218
357
|
app_id=$("$aapt2" dump badging "$apk" 2> /dev/null | sed -n "s/^package: name='\([^']*\)'.*/\1/p")
|
|
219
358
|
[ -n "$app_id" ] || app_id=$(sed -n 's/.*applicationId *=\{0,1\} *"\([^"]*\)".*/\1/p' android/app/build.gradle* | head -n 1)
|
|
220
|
-
|
|
359
|
+
android_ready "$device" || { echo "android: $device didn't finish starting (see: adb devices)"; status=1; return; }
|
|
221
360
|
"$adb" -s "$device" install -r "$apk" > /dev/null
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
361
|
+
if [ -n "$tablet" ]; then
|
|
362
|
+
if ! android_ready "$tablet"; then echo "android: $tablet didn't finish starting, so tablets aren't checked"; tablet=""
|
|
363
|
+
elif ! "$adb" -s "$tablet" install -r "$apk" > /dev/null 2>&1; then
|
|
364
|
+
echo "android: the app didn't install on the tablet $tablet (a different CPU type?), so tablets aren't checked"; tablet=""
|
|
365
|
+
fi
|
|
366
|
+
fi
|
|
367
|
+
for d in $device $tablet; do
|
|
368
|
+
# system "isn't responding" pop-ups (common on busy emulators) cover the app and fail flows; app crashes still fail
|
|
369
|
+
# them. Emulators only: the setting is device-wide and stays, so a phone keeps showing them
|
|
370
|
+
case $d in emulator-*) "$adb" -s "$d" shell settings put global hide_error_dialogs 1 ;; esac
|
|
371
|
+
"$adb" -s "$d" shell am broadcast -a android.intent.action.CLOSE_SYSTEM_DIALOGS > /dev/null 2>&1 || true
|
|
372
|
+
done
|
|
373
|
+
check_screens android "$device" "$tablet" "$app_id" $screens
|
|
226
374
|
}
|
|
227
375
|
|
|
228
376
|
case $mode in
|