agentic-mobile-kit 0.7.17 → 0.7.19

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.
Files changed (34) hide show
  1. package/README.md +3 -3
  2. package/bin/cli.js +1 -1
  3. package/lib/init.js +62 -10
  4. package/package.json +1 -1
  5. package/stacks/react-native/expo/.rulesync/permissions.jsonc +6 -0
  6. package/stacks/react-native/expo/AGENTS.md +7 -3
  7. package/stacks/react-native/expo/docs/amk/expo.md +11 -0
  8. package/stacks/react-native/template/.agents/skills/m-bugfix/SKILL.md +10 -11
  9. package/stacks/react-native/template/.agents/skills/m-continue/SKILL.md +1 -1
  10. package/stacks/react-native/template/.agents/skills/m-explore/SKILL.md +1 -1
  11. package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +16 -11
  12. package/stacks/react-native/template/.agents/skills/m-onboard/SKILL.md +8 -5
  13. package/stacks/react-native/template/.agents/skills/m-prototype/SKILL.md +5 -5
  14. package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +5 -2
  15. package/stacks/react-native/template/.github/pull_request_template.md +3 -1
  16. package/stacks/react-native/template/.github/workflows/e2e.yml +3 -0
  17. package/stacks/react-native/template/.rulesync/permissions.jsonc +6 -0
  18. package/stacks/react-native/template/.rulesync/subagents/m-design-reviewer.md +22 -0
  19. package/stacks/react-native/template/.rulesync/subagents/m-device-checker.md +2 -2
  20. package/stacks/react-native/template/.rulesync/subagents/m-reviewer.md +1 -1
  21. package/stacks/react-native/template/AGENTS.md +7 -3
  22. package/stacks/react-native/template/docs/amk/design-system.md +15 -0
  23. package/stacks/react-native/template/docs/amk/glossary.md +12 -0
  24. package/stacks/react-native/template/docs/amk/react-native.md +11 -0
  25. package/stacks/react-native/template/scripts/amk/a11y.js +78 -0
  26. package/stacks/react-native/template/scripts/amk/guard.js +22 -1
  27. package/stacks/react-native/template/scripts/amk/report.js +78 -0
  28. package/stacks/react-native/template/scripts/amk/rn-check.js +155 -17
  29. package/stacks/react-native/template/scripts/amk/verify.sh +134 -15
  30. package/stacks/react-native/template/specs/_templates/design.md +16 -0
  31. package/stacks/react-native/template/specs/_templates/flow.yaml +11 -0
  32. package/stacks/react-native/template/specs/_templates/questions.md +29 -0
  33. package/stacks/react-native/template/specs/_templates/subflow.yaml +36 -0
  34. package/stacks/react-native/template/specs/_templates/tasks.md +2 -2
@@ -1,6 +1,8 @@
1
1
  #!/usr/bin/env node
2
2
  // Checks the lines this branch adds or changes for React Native mistakes that the app's rules (docs/amk/react-native.md
3
- // or expo.md) list. Problems (✗) fail it, and so verify.sh quick; warnings (!) don't. Only changed lines: code already
3
+ // or expo.md) list, and its Maestro flows (.maestro/): Maestro's own syntax check, files they run that aren't there,
4
+ // taps by text, and each scenario of a spec the branch touched with its steps, an assertion and a screenshot.
5
+ // Problems (✗) fail it, and so verify.sh quick; warnings (!) don't. Only changed lines: code already
4
6
  // on the base branch is never reported. A line that's right as it is carries `// amk-ok <date>: <reason>`, on it or on
5
7
  // the line above, with the user's reason and the day they gave it; it's listed as kept, for review. When a branch changes
6
8
  // a file again, a kept line in it that's over two weeks old is reported again, for the user to decide again (the date
@@ -32,18 +34,21 @@ const since = baseRef || 'the last commit';
32
34
  const source = f => /\.(js|jsx|ts|tsx|mjs|cjs)$/.test(f) && !f.endsWith('.d.ts')
33
35
  && !/(^|\/)(node_modules|scripts\/amk|__tests__|__mocks__|e2e)\//.test(f)
34
36
  && !/\.(test|spec)\.\w+$|(^|\/)(jest[.-]setup|setup-?tests)[^/]*$/i.test(f);
37
+ // Maestro flows: the ones verify.sh runs (.maestro/*.yaml) and the subflows they run (in folders below)
38
+ // (not the copies with view-tree steps verify.sh runs for a moment on Android: .amk-<screen>-<flow>.yaml)
39
+ const flowFile = f => /^\.maestro\/.+\.ya?ml$/.test(f) && !/(^|\/)\.amk-/.test(f);
35
40
  const changed = new Map(); // file -> Set of line numbers, or 'all'
36
41
  if (sha) {
37
42
  let file = null;
38
43
  for (const line of (git('diff', '-U0', '--no-color', '--no-ext-diff', '--relative', '-M', '--diff-filter=ACMR', sha) || '').split('\n')) {
39
44
  if (line.startsWith('+++ ')) { file = line === '+++ /dev/null' ? null : line.slice(6); continue; }
40
45
  const h = /^@@ -\S+ \+(\d+)(?:,(\d+))? @@/.exec(line);
41
- if (!h || !file || !source(file)) continue;
46
+ if (!h || !file || !(source(file) || flowFile(file))) continue;
42
47
  if (!changed.has(file)) changed.set(file, new Set());
43
48
  for (let n = Number(h[1]), end = n + Number(h[2] ?? 1); n < end; n++) changed.get(file).add(n);
44
49
  }
45
50
  }
46
- for (const f of (git('ls-files', '--others', '--exclude-standard') || '').split('\n')) if (f && source(f)) changed.set(f, 'all');
51
+ for (const f of (git('ls-files', '--others', '--exclude-standard') || '').split('\n')) if (f && (source(f) || flowFile(f))) changed.set(f, 'all');
47
52
 
48
53
  // ---------- what the app uses ----------
49
54
  let pkg = {};
@@ -107,6 +112,13 @@ function okSince(file, n, date) {
107
112
  const t = /^committer-time (\d+)$/m.exec(git('blame', '--porcelain', '-L', `${n},${n}`, '--', file) || '');
108
113
  return t ? localDay(Number(t[1]) * 1000) : today;
109
114
  }
115
+ const BASE64 = new Set([...'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/='].map(c => c.charCodeAt(0)));
116
+ const SECRETS = [
117
+ [/\bgh[pousr]_[A-Za-z0-9]{36,}/g, 'a GitHub token'], [/\bgithub_pat_[A-Za-z0-9_]{40,}/g, 'a GitHub token'],
118
+ [/\b[sr]k_live_[A-Za-z0-9]{20,}/g, 'a Stripe secret key'], [/\bAKIA[0-9A-Z]{16}\b/g, 'an AWS access key'],
119
+ [/-----BEGIN [A-Z ]*PRIVATE KEY-----/g, 'a private key'], [/\bxox[baprs]-[A-Za-z0-9-]{10,}/g, 'a Slack token'],
120
+ [/\bsk-(proj-|ant-)?[A-Za-z0-9_-]{32,}/g, 'an AI service API key'],
121
+ ];
110
122
  const importsFrom = (code, from) => [...code.matchAll(new RegExp(`import\\s+[^;'"]*?\\{([^}]*)\\}\\s*from\\s*['"]${from}['"]`, 'g'))];
111
123
  const timers = /\bset(Timeout|Interval)\s*\(/;
112
124
  // a permission prompt (not App Tracking Transparency's, which apps show early on purpose)
@@ -155,15 +167,17 @@ function check(file, text) {
155
167
  }
156
168
  });
157
169
  // secrets are reported without their value; comments too, as they ship in the repository
158
- const secrets = [
159
- [/\bgh[pousr]_[A-Za-z0-9]{36,}/g, 'a GitHub token'], [/\bgithub_pat_[A-Za-z0-9_]{40,}/g, 'a GitHub token'],
160
- [/\b[sr]k_live_[A-Za-z0-9]{20,}/g, 'a Stripe secret key'], [/\bAKIA[0-9A-Z]{16}\b/g, 'an AWS access key'],
161
- [/-----BEGIN [A-Z ]*PRIVATE KEY-----/g, 'a private key'], [/\bxox[baprs]-[A-Za-z0-9-]{10,}/g, 'a Slack token'],
162
- [/\bsk-(proj-|ant-)?[A-Za-z0-9_-]{32,}/g, 'an AI service API key'],
163
- ];
164
- for (const [re, what] of secrets) each(re, m => add('✗', m.index, null, `${what} in code: anyone with the repository or the app can read it. Revoke it and keep it on a server`), text);
170
+ for (const [re, what] of SECRETS) each(re, m => add('✗', m.index, null, `${what} in code: anyone with the repository or the app can read it. Revoke it and keep it on a server`), text);
165
171
  each(/\bAIza[0-9A-Za-z_-]{35}\b/g, m => add('!', m.index, null, 'a Google API key in code: ship it only if it is restricted to this app (Google Cloud console)'), text);
166
- each(/data:image\/[a-z+]+;base64,[A-Za-z0-9+/=]{8000,}/g, m => add('✗', m.index, m.index + m[0].length, `a ${Math.round(m[0].length * 0.75 / 1024)} KB base64 image in code: put it in an asset file`), text);
172
+ // measured without a regular expression, whose repetition overflows the stack on an image of a few MB
173
+ for (let i = text.indexOf('data:image/'); i !== -1; i = text.indexOf('data:image/', i + 1)) {
174
+ const head = /^data:image\/[a-z+]+;base64,/.exec(text.slice(i, i + 40));
175
+ if (!head) continue;
176
+ let j = i + head[0].length;
177
+ while (j < text.length && BASE64.has(text.charCodeAt(j))) j++;
178
+ if (j - i >= 8000) add('✗', i, j, `a ${Math.round((j - i) * 0.75 / 1024)} KB base64 image in code: put it in an asset file`);
179
+ i = j;
180
+ }
167
181
  if (expoSdk >= 56 && deps['expo-router']) {
168
182
  each(/(['"])@react-navigation\/[^'"\n]+\1/g, m => add('✗', m.index, null, `${m[0]} doesn't work alongside Expo Router from SDK 56: import from expo-router (see the expo-router skill)`));
169
183
  }
@@ -197,6 +211,15 @@ function check(file, text) {
197
211
  if (l && !/\breturn\b/.test(body)) add('!', m.index, close, `${l[1]} in an effect that returns no cleanup: return a function that removes it`, lineAt(code, open + l.index));
198
212
  });
199
213
  each(/\bconsole\s*\.\s*log\s*\(/g, m => add('!', m.index, null, 'console.log left in: remove it, or use the app\'s logger'));
214
+ // the generated look: marketing filler for copy, placeholder text and names, emoji in place of the app's icons
215
+ each(/\b(seamless(?:ly)?|effortless(?:ly)?|supercharge[ds]?|revolutioni[sz](?:e|es|ed|ing)|revolutionary|cutting-edge|next-level|game-?chang(?:er|ing)|unleash(?:es|ed)?|elevate your|empower your|unlock your (?:full )?potential)\b/gi,
216
+ m => add('!', m.index, null, `"${m[0]}" reads as generated copy: say what it does, in the app's words (docs/amk/glossary.md)`));
217
+ each(/\b(lorem ipsum|(?:john|jane) doe|acme)\b/gi, m => add('!', m.index, null, `"${m[0]}" is filler: the real text, or a placeholder the PR lists`));
218
+ // not in translation files: an emoji there is part of a message ("Welcome 👋"), not an icon
219
+ if (!/(^|\/)(i18n?|locales?|translations?|lang)\//i.test(file)) {
220
+ each(/\p{Emoji_Presentation}|\p{Extended_Pictographic}\uFE0F/gu,
221
+ m => add('!', m.index, null, 'an emoji in the app: an icon from its icon set (docs/amk/design-system.md), unless it\'s content'));
222
+ }
200
223
  each(/\bmask(AllTextInputs|AllText|AllInputs|TextInputs)\s*:\s*false\b/g, m => add('!', m.index, null, 'session replay that records what users type: mask text inputs'));
201
224
  each(/\bAccessibilityInfo\s*\.\s*setAccessibilityFocus\s*\(/g, m => add('!', m.index, null, 'AccessibilityInfo.setAccessibilityFocus is deprecated: use sendAccessibilityEvent'));
202
225
  // platform guidelines: text, back, screen readers, tap areas, permissions, motion
@@ -246,6 +269,81 @@ function lineAt(code, i) {
246
269
  return n;
247
270
  }
248
271
 
272
+ // ---------- Maestro flows ----------
273
+ // a flow without its comments (each comment character a space, so positions stay): # outside quotes starts one
274
+ function stripYamlComments(text) {
275
+ return text.split('\n').map(l => {
276
+ let quote = null;
277
+ for (let i = 0; i < l.length; i++) {
278
+ const c = l[i];
279
+ if (quote) { if (c === quote) quote = null; } else if (c === '"' || c === "'") quote = c;
280
+ else if (c === '#' && (i === 0 || /\s/.test(l[i - 1]))) return l.slice(0, i) + ' '.repeat(l.length - i);
281
+ }
282
+ return l;
283
+ }).join('\n');
284
+ }
285
+ const TAPS = /^(tapOn|doubleTapOn|longPressOn)$/;
286
+ const SELECTS = /^(tapOn|doubleTapOn|longPressOn|assertVisible|assertNotVisible|scrollUntilVisible|extendedWaitUntil|copyTextFrom)$/;
287
+ const ASSERTS = /^(assertVisible|assertNotVisible|assertTrue|assertWithAI|assertNoDefectsWithAI)$/;
288
+ // buttons of system dialogs (permission prompts, alerts), which have no testID
289
+ const SYSTEM_BUTTON = /^(allow|allow while using (the )?app|allow once|only this time|while using the app|ok|cancel|continue|don.t allow|not now|deny|close)$/i;
290
+ const unquote = v => { v = v.trim(); return /^'.*'$/.test(v) ? v.slice(1, -1).replace(/''/g, "'") : /^".*"$/.test(v) ? v.slice(1, -1) : v; };
291
+ let noMaestro = false;
292
+ function checkFlow(file, text) {
293
+ const out = [];
294
+ const add = (level, at, message, always) => out.push({ level, at, end: at, message, always });
295
+ const dir = path.dirname(file);
296
+ let offset = 0;
297
+ let cmd = null;
298
+ let optional = false;
299
+ let target = '';
300
+ let asserts = 0;
301
+ const done = () => { if (cmd === 'extendedWaitUntil' && !optional) asserts++; };
302
+ for (const l of stripYamlComments(text).split('\n')) {
303
+ const at = offset;
304
+ offset += l.length + 1;
305
+ const item = /^\s*-\s*([A-Za-z]+)\s*:?\s*(.*)$/.exec(l);
306
+ if (item) { done(); cmd = item[1]; optional = false; if (ASSERTS.test(cmd)) asserts++; }
307
+ if (/^\s*optional\s*:\s*true\b/.test(l)) optional = true;
308
+ const app = /^appId\s*:\s*(.+)$/.exec(l);
309
+ if (app && !/\$\{APP_ID\}/.test(app[1])) add('!', at, `appId ${app[1].trim()}: verify.sh sets APP_ID for the build it checks, which a flavor or scheme changes: use appId: \${APP_ID}`);
310
+ // what this line selects: the command's own value (tapOn: Save), keys of an inline map, or a key below the command
311
+ const sel = [];
312
+ if (item && SELECTS.test(cmd) && item[2].trim() && !/^[{[|>]/.test(item[2].trim())) sel.push(['text', unquote(item[2])]);
313
+ for (const m of (item && /^\{/.test(item[2].trim()) ? item[2] : !item ? l : '').matchAll(/\b(text|id|visible|notVisible)\s*:\s*("[^"]*"|'(?:[^']|'')*'|[^,}\n]+)/g)) {
314
+ if (SELECTS.test(cmd || '') && unquote(m[2])) sel.push([m[1] === 'id' ? 'id' : 'text', unquote(m[2])]);
315
+ }
316
+ for (const [kind, value] of sel) {
317
+ if (TAPS.test(cmd)) target = value;
318
+ if (kind === 'text' && TAPS.test(cmd) && !SYSTEM_BUTTON.test(value) && !value.includes('${')) {
319
+ add('!', at, `${cmd} "${value}" taps by text: on iOS a label and its control both match, and on a real iPhone a hidden one can; tap by testID (id:)`);
320
+ }
321
+ if (kind === 'text' && /['’]/.test(value)) add('!', at, `"${value}" has an apostrophe, which a real iPhone can't search for (maestro-runner): match a testID, or text without it`);
322
+ }
323
+ if (item && cmd === 'inputText' && item[2].trim() && !item[2].includes('${') && /pass(word|code)?\b|\bpin\b|otp|secret/i.test(target)) {
324
+ add('!', at, `a password typed into the flow: use \${MAESTRO_PASSWORD} (or another MAESTRO_ variable) from .maestro/.env.local, which isn't committed`);
325
+ }
326
+ // a subflow or script it runs: there, or the flow fails when it gets to it
327
+ const runs = (item && /^(runFlow|runScript)$/.test(cmd) && !/^[{[|>]/.test(item[2].trim()) && item[2].trim()) || (!item && /^(runFlow|runScript)$/.test(cmd || '') && (/^\s*file\s*:\s*(.+)$/.exec(l) || [])[1]);
328
+ if (runs && !runs.includes('${') && /\.(ya?ml|js)$/.test(unquote(runs)) && !fs.existsSync(path.join(root, dir, unquote(runs)))) {
329
+ add('✗', at, `${cmd} ${unquote(runs)}: no such file next to this flow (${dir}/)`, true);
330
+ }
331
+ }
332
+ done();
333
+ for (const [re, what] of SECRETS) for (const m of text.matchAll(re)) add('✗', m.index, `${what} in a flow: anyone with the repository can read it. Revoke it, and use a MAESTRO_ variable from .maestro/.env.local`);
334
+ // a flow verify.sh runs (not a subflow) that never checks anything passes whatever the app shows
335
+ if (/^\.maestro\/[^/]+$/.test(file) && !asserts) add('!', 0, 'this flow checks nothing: add an assertVisible for what each scenario\'s THEN expects', true);
336
+ // Maestro's own syntax check (seconds, no device): AMK_MAESTRO names another maestro
337
+ const r = noMaestro ? null : spawnSync(process.env.AMK_MAESTRO || 'maestro', ['check-syntax', file], { cwd: root, encoding: 'utf8' });
338
+ if (r && r.error) noMaestro = true;
339
+ else if (r && r.status !== 0) {
340
+ const said = `${r.stdout || ''}\n${r.stderr || ''}`.split('\n').map(s => s.trim()).find(s => s && s !== 'OK') || 'invalid flow';
341
+ const n = Number((/:(\d+):\d+/.exec(said) || [])[1]) || 1;
342
+ add('✗', text.split('\n').slice(0, n - 1).reduce((a, s) => a + s.length + 1, 0), `maestro check-syntax: ${said.replace(/\s+at \/syntax-checker:\d+:\d+/, '')}`, true);
343
+ }
344
+ return out;
345
+ }
346
+
249
347
  for (const [file, lines] of changed) {
250
348
  let text;
251
349
  try { text = fs.readFileSync(path.join(root, file), 'utf8'); } catch { continue; }
@@ -253,13 +351,13 @@ for (const [file, lines] of changed) {
253
351
  const starts = [0];
254
352
  for (let i = text.indexOf('\n'); i !== -1; i = text.indexOf('\n', i + 1)) starts.push(i + 1);
255
353
  const line = i => { let lo = 0, hi = starts.length - 1; while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (starts[mid] <= i) lo = mid; else hi = mid - 1; } return lo + 1; };
256
- for (const f of check(file, text)) {
354
+ for (const f of flowFile(file) ? checkFlow(file, text) : check(file, text)) {
257
355
  const from = line(f.at);
258
356
  const to = line(f.end);
259
357
  const touched = lines === 'all' || [...Array(to - from + 1).keys()].some(k => lines.has(from + k));
260
358
  const at = f.line || from;
261
359
  // on the line, or in a comment on the line above
262
- const above = /^\s*(\/\/|\/\*|\{\s*\/\*)/.test(rows[at - 2] || '') ? at - 1 : 0;
360
+ const above = /^\s*(\/\/|\/\*|\{\s*\/\*|#)/.test(rows[at - 2] || '') ? at - 1 : 0;
263
361
  const okAt = [at, above].find(n => n && /amk-ok\b/.test(rows[n - 1]));
264
362
  const ok = okAt && /amk-ok(?:\s+(\d{4}-\d{2}-\d{2}))?\s*:\s*(\S.*?)\s*(\*\/\s*\}?)?\s*$/.exec(rows[okAt - 1]);
265
363
  let message = f.message;
@@ -268,14 +366,14 @@ for (const [file, lines] of changed) {
268
366
  // kept: listed when its own lines changed; over two weeks old, asked again whenever its file changes
269
367
  if (Date.parse(today) - Date.parse(since) <= 14 * DAY) { if (touched) kept.push(`${file}:${at}: ${ok[2]} (${since})`); continue; }
270
368
  message = `kept with amk-ok since ${since}, over two weeks, and its file changed again: ${f.message}. The user's reason then: ${ok[2]}`;
271
- } else if (!touched) continue;
369
+ } else if (!touched && !f.always) continue;
272
370
  if (!findings.some(x => x.where === `${file}:${at}` && x.message === message)) findings.push({ ...f, message, where: `${file}:${at}` });
273
371
  }
274
372
  }
275
373
 
276
374
  // ---------- once for the app: an error boundary somewhere ----------
277
375
  let boundary = true;
278
- if (changed.size) {
376
+ if ([...changed.keys()].some(source)) {
279
377
  boundary = false;
280
378
  const files = [...(git('ls-files') || '').split('\n'), ...changed.keys()].filter(f => f && source(f));
281
379
  for (const f of new Set(files)) {
@@ -285,6 +383,45 @@ if (changed.size) {
285
383
  }
286
384
  }
287
385
 
386
+ // ---------- each scenario of a spec the branch touched has its steps in the spec's flows ----------
387
+ // specs/<id>/requirements.md lists them ("#### Scenario: <name>"); the flows are .maestro/<id>*.yaml, with a
388
+ // "# Scenario <n>: <name>" comment above each one's steps, as specs/_templates/flow.yaml shows
389
+ const touchedPaths = [...(sha ? (git('diff', '--name-only', '--relative', sha) || '').split('\n') : []),
390
+ ...(git('ls-files', '--others', '--exclude-standard') || '').split('\n')].filter(Boolean);
391
+ const norm = s => s.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
392
+ const specIds = fs.existsSync(path.join(root, 'specs')) ? fs.readdirSync(path.join(root, 'specs'), { withFileTypes: true })
393
+ .filter(e => e.isDirectory() && !/^(_|current$)/.test(e.name)).map(e => e.name) : [];
394
+ const flowsDir = fs.existsSync(path.join(root, '.maestro')) ? fs.readdirSync(path.join(root, '.maestro')).filter(f => /\.ya?ml$/.test(f)) : [];
395
+ for (const id of specIds) {
396
+ const req = `specs/${id}/requirements.md`;
397
+ let reqText;
398
+ try { reqText = fs.readFileSync(path.join(root, req), 'utf8'); } catch { continue; }
399
+ const flows = flowsDir.filter(f => f.toLowerCase().startsWith(id.toLowerCase())).map(f => `.maestro/${f}`);
400
+ if (!flows.length || !touchedPaths.some(p => p.startsWith(`specs/${id}/`) || flows.includes(p))) continue;
401
+ const blocks = flows.flatMap(f => {
402
+ const text = fs.readFileSync(path.join(root, f), 'utf8');
403
+ const code = stripYamlComments(text).split('\n');
404
+ const out = [];
405
+ text.split('\n').forEach((l, i) => {
406
+ const m = /^\s*#\s*Scenario\b\s*(\d+)?\s*[:.)-]?\s*(.*)$/i.exec(l);
407
+ if (m) out.push({ n: Number(m[1]) || 0, name: norm(m[2]), at: i });
408
+ else if (out.length) out[out.length - 1].code = `${out[out.length - 1].code || ''}${code[i]}\n`;
409
+ });
410
+ return out.map(b => ({ ...b, flow: f }));
411
+ });
412
+ [...reqText.matchAll(/^#### Scenario:\s*(.*)$/gm)].forEach((m, i) => {
413
+ const name = norm(m[1]);
414
+ const where = `${req}:${reqText.slice(0, m.index).split('\n').length}`;
415
+ const b = blocks.find(x => x.n === i + 1) || blocks.find(x => name && x.name && (x.name.includes(name) || name.includes(x.name)));
416
+ const say = message => findings.push({ level: '!', message, where });
417
+ if (!b) say(`scenario ${i + 1} "${m[1].trim()}" has no block in ${flows.join(', ')}: add "# Scenario ${i + 1}: ${m[1].trim()}" above its steps, with an assertion for its THEN and a screenshot`);
418
+ else {
419
+ if (!/-\s*(assertVisible|assertNotVisible|assertTrue|assertWithAI|extendedWaitUntil)\b/.test(b.code || '')) say(`scenario ${i + 1} "${m[1].trim()}" has no assertion in ${b.flow}: check what its THEN expects`);
420
+ if (!/-\s*takeScreenshot\b/.test(b.code || '')) say(`scenario ${i + 1} "${m[1].trim()}" has no screenshot in ${b.flow}, so it has no evidence`);
421
+ }
422
+ });
423
+ }
424
+
288
425
  // ---------- report ----------
289
426
  // by file, then line
290
427
  const order = w => { const [, file, n] = /^(.*):(\d+)$/.exec(w); return [file, Number(n)]; };
@@ -292,14 +429,15 @@ findings.sort((a, b) => { const [fa, na] = order(a.where); const [fb, nb] = orde
292
429
  const problems = findings.filter(f => f.level === '✗');
293
430
  const warnings = findings.filter(f => f.level === '!');
294
431
  const plural = (n, w) => `${n} ${w}${n === 1 ? '' : 's'}`;
295
- if (!changed.size) console.log(`rn-check: no changed source files since ${since}`);
432
+ if (!changed.size && !findings.length) console.log(`rn-check: no changed code or flows since ${since}`);
296
433
  else if (!findings.length) console.log(`rn-check: nothing to report in the lines changed since ${since}`);
297
434
  else console.log(`rn-check: ${plural(problems.length, 'problem')}, ${plural(warnings.length, 'warning')} in the lines changed since ${since}`);
298
435
  for (const f of [...problems, ...warnings]) console.log(` ${f.level} ${f.where} ${f.message}`);
436
+ if (noMaestro && [...changed.keys()].some(flowFile)) console.log(' flows not syntax-checked: Maestro isn\'t installed here');
299
437
  if (!boundary) console.log(` ! the app has no error boundary: a render error shows a blank screen or closes the app. Wrap the app in one`);
300
438
  if (kept.length) console.log(` kept with amk-ok: ${[...new Set(kept)].join('; ')}`);
301
439
  if (problems.length) {
302
- console.log(` Each ✗ fails verify.sh quick. Ask the user, for each one: fix it, or keep the line with \`// amk-ok ${today}: <their reason>\` on it.`);
440
+ console.log(` Each ✗ fails verify.sh quick. Ask the user, for each one: fix it, or keep the line with \`// amk-ok ${today}: <their reason>\` on it (# in a flow).`);
303
441
  console.log(' Never add an amk-ok without the user\'s reason. One kept over two weeks ago comes back when its file changes: ask again, and to keep it, write today\'s date.');
304
442
  }
305
443
  if (warnings.length || !boundary) console.log(' Fix each ! in the code this task changed, or tell the user why it stays.');
@@ -13,6 +13,7 @@
13
13
  # one per device, in rounds when they don't all fit, the flows split into parts when there's room
14
14
  # --spec <id> run .maestro/<id>*.yaml and save evidence in .amk/evidence/<id>/
15
15
  # --flow <file> run only this flow: a path in the project, or anywhere (an absolute path)
16
+ # --tags <list> only the flows with one of these tags in their header (tags: [smoke]), comma-separated
16
17
  # --label <n> evidence folder name (default: the spec id, or no-spec)
17
18
  # --flavor <name> Android product flavor to check (default: the first one in build.gradle)
18
19
  # --scheme <name> iOS scheme to check (default: the one named like the workspace)
@@ -33,10 +34,13 @@
33
34
  # AMK_IOS_TABLET (iPad simulator, or a connected iPad: name or UDID), AMK_ANDROID_TABLET_AVD (tablet emulator),
34
35
  # AMK_ANDROID_TABLET (serial), AMK_IOS_TEAM (the Apple team ID that signs builds for real iPhones and iPads;
35
36
  # default: the project's), AMK_PARALLEL (1 or 0: overrides plan's choice), AMK_MEMORY_GB (the memory plan
36
- # counts on: this machine's; less when other emulators stay open), AMK_DEVICES (how many devices plan checks at
37
- # once: one per 6 GB beyond 4), AMK_DEVICE_WAIT (minutes to wait for a
37
+ # counts on: this machine's; less when other emulators stay open), AMK_DISK_GB (the free disk it counts on: this
38
+ # folder's), AMK_A11Y (0: no view-tree steps on Android, so no accessibility warnings. The steps go in a copy
39
+ # of each flow, .maestro/.amk-<screen>-<flow>.yaml, where ${MAESTRO_FILENAME} is the copy's name),
40
+ # AMK_DEVICES (how many devices plan checks at once: one per 6 GB beyond 4), AMK_DEVICE_WAIT (minutes to wait for a
38
41
  # device in use, 30), AMK_LOCK_DIR (where runs on this machine claim devices; /tmp/agentic-mobile-kit-<user id>),
39
- # AMK_EVIDENCE_KEEP (how many evidence folders stay, newest first: 5; 0 keeps them all)
42
+ # AMK_EVIDENCE_KEEP (how many evidence folders stay, newest first: 5; 0 keeps them all; a prototype's and those of a
43
+ # spec in progress always stay)
40
44
  # A device in use by another run (any project on this machine) is skipped for a free one of the same kind, or waited
41
45
  # for when it was named or none is free.
42
46
  # Real iPhones and iPads (iOS 17 or later): Maestro doesn't run on them, so their flows run through maestro-runner, with
@@ -49,6 +53,7 @@ mode=${1:-all}
49
53
  args=$* # for the commands plan prints
50
54
  spec=""
51
55
  flow=""
56
+ tags=""
52
57
  label=""
53
58
  flavor=${AMK_ANDROID_FLAVOR:-}
54
59
  only=${AMK_SCREENS:-}
@@ -59,6 +64,7 @@ while [ $# -gt 0 ]; do
59
64
  case $1 in
60
65
  --spec) spec=$2; shift 2 ;;
61
66
  --flow) flow=$2; shift 2 ;;
67
+ --tags) tags=$2; shift 2 ;;
62
68
  --label) label=$2; shift 2 ;;
63
69
  --flavor) flavor=$2; shift 2 ;;
64
70
  --scheme) AMK_IOS_SCHEME=$2; export AMK_IOS_SCHEME; shift 2 ;;
@@ -86,16 +92,26 @@ case $flow in "" | /* | [A-Za-z]:/*) ;; *) flow=$root/$flow ;; esac
86
92
  evidence="$root/.amk/evidence/${label:-${spec:-no-spec}}"
87
93
  mkdir -p "$evidence"
88
94
  # Evidence stays on this machine (.amk/ is out of git): the newest AMK_EVIDENCE_KEEP folders stay, this one among
89
- # them, and older ones go (5; 0 keeps them all). A prototype's folder (<id>-prototype, material for a demo) always
90
- # stays and isn't counted
95
+ # them, and older ones go (5; 0 keeps them all). A prototype's folder (<id>-prototype, material for a demo) and those
96
+ # of a spec in progress (its progress.md isn't done: its evidence table points there) always stay and aren't counted.
97
+ # Kits before 0.7.12 gave each run without a spec a folder named after its time: those go first
91
98
  touch "$evidence"
92
99
  keep=${AMK_EVIDENCE_KEEP:-5}
93
100
  if [ "$keep" -gt 0 ] 2> /dev/null; then
94
- old=$(ls -dt "$root"/.amk/evidence/*/ 2> /dev/null | grep -v -- '-prototype/$' | tail -n +$((keep + 1)))
101
+ open=$(for p in "$root"/specs/*/progress.md; do
102
+ case $p in (*/specs/_templates/* | */specs/current/*) continue ;; esac
103
+ if [ -f "$p" ] && ! grep -qi -E '^Status:[[:space:]]*done' "$p"; then basename "$(dirname "$p")"; fi
104
+ done)
105
+ all=$(ls -dt "$root"/.amk/evidence/*/ 2> /dev/null | grep -v -- '-prototype/$' | while IFS= read -r d; do
106
+ for s in $open; do case $(basename "$d") in ("$s" | "$s"-*) continue 2 ;; esac; done
107
+ echo "$d"
108
+ done)
109
+ timed='/[0-9]{8}-[0-9]{6}/$'
110
+ old=$({ echo "$all" | grep -v -E "$timed" || true; echo "$all" | grep -E "$timed" || true; } | grep . | tail -n +$((keep + 1)))
95
111
  if [ -n "$old" ]; then
96
112
  # another run on this machine (a part, a round) may have just removed the same folder
97
113
  echo "$old" | while IFS= read -r d; do rm -r "${d:?}" 2> /dev/null || true; done
98
- echo "evidence: removed $(echo "$old" | wc -l | tr -d ' ') older folders from .amk/evidence, keeping the newest $keep (AMK_EVIDENCE_KEEP sets how many; 0 keeps them all)"
114
+ echo "evidence: removed $(echo "$old" | awk -F/ 'NR <= 5 { s = s (NR > 1 ? ", " : "") $(NF - 1) } END { print s (NR > 5 ? " and " NR - 5 " more" : "") }') from .amk/evidence, keeping the newest $keep and those of specs in progress (AMK_EVIDENCE_KEEP sets how many; 0 keeps them all)"
99
115
  fi
100
116
  fi
101
117
  status=0
@@ -103,10 +119,27 @@ status=0
103
119
  flow_files() {
104
120
  {
105
121
  if [ -n "$flow" ]; then echo "$flow"
106
- elif [ -n "$spec" ]; then find "$root/.maestro" -maxdepth 1 -iname "$spec*.yaml" 2>/dev/null | sort
107
- else find "$root/.maestro" -maxdepth 1 -name '*.yaml' 2>/dev/null | sort
122
+ elif [ -n "$spec" ]; then find "$root/.maestro" -maxdepth 1 -iname "$spec*.yaml" ! -name '.amk-*' 2>/dev/null | sort
123
+ else find "$root/.maestro" -maxdepth 1 -name '*.yaml' ! -name '.amk-*' 2>/dev/null | sort
108
124
  fi
109
- } | awk -v k="$part_k" -v n="$part_n" '(NR - 1) % n == k - 1'
125
+ } | with_tags | awk -v k="$part_k" -v n="$part_n" '(NR - 1) % n == k - 1'
126
+ }
127
+ # the flows (a path a line) with one of --tags in their header: tags: [smoke, login], or one tag a line below tags:
128
+ with_tags() {
129
+ if [ -z "$tags" ]; then cat; return; fi
130
+ TAGS=$tags node -e '
131
+ const fs = require("fs");
132
+ const want = process.env.TAGS.split(",").map(s => s.trim()).filter(Boolean);
133
+ for (const f of fs.readFileSync(0, "utf8").split("\n").filter(Boolean)) {
134
+ const head = fs.readFileSync(f, "utf8").split(/^---\s*$/m)[0].split("\n");
135
+ const at = head.findIndex(l => /^tags\s*:/.test(l));
136
+ if (at < 0) continue;
137
+ const inline = head[at].replace(/^tags\s*:/, "").trim();
138
+ const below = [];
139
+ for (let i = at + 1; i < head.length && /^\s+-\s*\S/.test(head[i]); i++) below.push(head[i].replace(/^\s+-\s*/, ""));
140
+ const tags = (inline ? inline.replace(/^\[|\]$/g, "").split(",") : below).map(s => s.trim().replace(/^["\x27]|["\x27]$/g, ""));
141
+ if (tags.some(s => want.includes(s))) console.log(f);
142
+ }'
110
143
  }
111
144
 
112
145
  # the screens to check on a platform: the ones the app supports, narrowed by --screens
@@ -154,7 +187,8 @@ claim() {
154
187
  unclaim() { l=$(lock_path "$1"); rm -f "$l/owner"; rmdir "$l" 2> /dev/null || true; held=$(echo "$held" | sed "s| $l||"); }
155
188
  release() { for l in $held; do rm -f "$l/owner"; rmdir "$l" 2> /dev/null || true; done; held=""; }
156
189
  temps="" # the temporary devices this run made for a part of the flows (--part), deleted at its end
157
- trap 'release; drop_temps' EXIT
190
+ tree_flow="" # the copy of a flow with view-tree steps (Android), next to it while it runs
191
+ trap 'release; drop_temps; [ -z "$tree_flow" ] || rm -f "$tree_flow"' EXIT
158
192
  trap 'exit 130' INT TERM
159
193
  holder() {
160
194
  l=$(lock_path "$1")
@@ -179,8 +213,17 @@ run_flow() { # screen device app_id file name orientation
179
213
  [ ! -d "$debug" ] || rm -r "$debug"
180
214
  mkdir -p "$debug" "$out/screenshots"
181
215
  target=$4
216
+ # Android: after each screenshot, Maestro saves the screen's view tree (an optional step that can't pass, half a
217
+ # second), from which a11y.js lists tappable elements without a label or under 48 dp. Maestro runs a copy of the flow
218
+ # with those steps, next to it so its subflows' paths still work, deleted after. AMK_A11Y=0 turns it off
219
+ tree_flow=""
220
+ if [ "${1%%-*}" = android ] && [ "${AMK_A11Y:-1}" != 0 ]; then
221
+ tree_flow=$(dirname "$4")/.amk-$1-$5.yaml
222
+ with_trees "$4" > "$tree_flow"
223
+ target=$tree_flow
224
+ fi
182
225
  # Maestro reads the path in the flows below itself, so it's a native path (a Windows path in Git Bash)
183
- native=$(cd "$(dirname "$4")" && { pwd -W 2> /dev/null || pwd; })/$(basename "$4")
226
+ native=$(cd "$(dirname "$target")" && { pwd -W 2> /dev/null || pwd; })/$(basename "$target")
184
227
  if is_real "$2"; then
185
228
  # on a real device every flow runs inside one, first: the first launchApp maestro-runner finds in a flow decides
186
229
  # whether it answers alerts itself, and for most it does (for permission prompts, which it can't allow ahead),
@@ -223,7 +266,8 @@ run_flow() { # screen device app_id file name orientation
223
266
  pngs "$@" > "$debug/.pngs"
224
267
  # with the app's build: on a real device, clearState installs the app again
225
268
  MAESTRO_RUNNER_NO_TELEMETRY=1 DO_NOT_TRACK=1 npx -y "$runner" --platform ios --driver wda --device "$2" \
226
- --team-id "$team" --wda-bundle-id "$3.wda" --app-file "$device_app" test -e APP_ID="$3" --output "$debug" \
269
+ --team-id "$team" --wda-bundle-id "$3.wda" --app-file "$device_app" test -e APP_ID="$3" \
270
+ -e ORIENTATION="$([ "$6" = PORTRAIT ] && echo PORTRAIT || echo landscape)" --output "$debug" \
227
271
  --flatten "$target" > "$out/$5.log" 2>&1 || rc=$?
228
272
  pngs "$@" | comm -13 "$debug/.pngs" - | while IFS= read -r f; do mv "$f" "$debug/"; done
229
273
  # its takeScreenshot files, not the ones of a step that failed (<step>-after.png)
@@ -232,9 +276,18 @@ run_flow() { # screen device app_id file name orientation
232
276
  fi
233
277
  # screenshots use relative names: older Maestro saves them in the current folder, then in --test-output-dir, and
234
278
  # from 2.7 in the debug output under <flow>/takeScreenshot/, from where they join the screen's evidence
279
+ # ORIENTATION: how this screen turned the device, for a flow to turn it back after another app's portrait-only screen
280
+ # (a call, the camera) turned it
235
281
  (cd "$out" && maestro --device "$2" test --test-output-dir "$out" --debug-output "$debug" --flatten-debug-output \
236
- -e APP_ID="$3" "$target" > "$out/$5.log" 2>&1) || rc=$?
282
+ -e APP_ID="$3" -e ORIENTATION="$6" "$target" > "$out/$5.log" 2>&1) || rc=$?
237
283
  find "$debug" -path '*/takeScreenshot/*.png' -exec cp {} "$out/screenshots/" \;
284
+ if [ -n "$tree_flow" ]; then
285
+ rm -f "$tree_flow"
286
+ tree_flow=""
287
+ # Maestro named the flow's folder after the copy, a hidden name: the flow's own, as on iOS
288
+ [ ! -d "$debug/.amk-$1-$5" ] || [ -e "$debug/$5" ] || mv "$debug/.amk-$1-$5" "$debug/$5"
289
+ node scripts/amk/a11y.js "$debug" "$density" "$5" >> "$out/.a11y" 2> /dev/null || true
290
+ fi
238
291
  return $rc
239
292
  }
240
293
 
@@ -253,6 +306,39 @@ steady() {
253
306
  [ "$in_row" -ge 3 ] || sleep 10
254
307
  done
255
308
  }
309
+ # why flow $2 failed on the device $1, in a line: the step and what Maestro said (on a real device, maestro-runner's report)
310
+ why_failed() {
311
+ if is_real "$1"; then
312
+ node -e 'try { const e = ((JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).flows || [])[0] || {}).error;
313
+ if (e) console.log(`with: ${e.split("\n")[0]}`); } catch {}' "$debug/report.json"
314
+ else
315
+ # the first step that failed is the innermost; Maestro's message comes after the subflows that failed around it
316
+ # (Run <subflow>... FAILED) and the steps onFlowComplete ran
317
+ awk '/\.\.\. FAILED[[:space:]]*$/ { step = $0; sub(/\.\.\. FAILED[[:space:]]*$/, "", step); sub(/^[[:space:]]+/, "", step)
318
+ said = ""
319
+ while ((getline line) > 0) if (line ~ /[^[:space:]]/ && line !~ /\.\.\. [A-Z]+[[:space:]]*$/) { said = line; break }
320
+ sub(/^[[:space:]]+/, "", said)
321
+ printf "at \"%s\"%s\n", step, (said == "" ? "" : ": " said); exit }' "$out/$2.log"
322
+ fi
323
+ }
324
+ # the screen when a flow failed on the device $1: the last screenshot of a failing step (Maestro's, or maestro-runner's),
325
+ # not one of the view-tree steps', which Maestro takes too
326
+ failure_shot() {
327
+ if is_real "$1"; then find "$debug" -name '*-after.png' | sort | tail -n 1
328
+ else find "$debug" -path '*/screenshots/*.png' ! -name '*amk-view-tree*' | sort | tail -n 1; fi
329
+ }
330
+ # flow $1 with a step after each screenshot (takeScreenshot: <name>) that makes Maestro save the screen's view tree,
331
+ # named after the screenshot: it waits 1 ms for an element that isn't there, and doesn't fail the flow
332
+ with_trees() {
333
+ awk '{ print }
334
+ /^[[:space:]]*-[[:space:]]*takeScreenshot:[[:space:]]*[^[:space:]#]/ {
335
+ match($0, /^[[:space:]]*/); ind = substr($0, 1, RLENGTH)
336
+ name = $0; sub(/^[[:space:]]*-[[:space:]]*takeScreenshot:[[:space:]]*/, "", name); sub(/[[:space:]]+#.*$/, "", name)
337
+ sub(/[[:space:]]+$/, "", name) # and a Windows line end
338
+ gsub(/["\047]/, "", name); gsub(/[^A-Za-z0-9_-]/, "-", name)
339
+ printf "%s- extendedWaitUntil:\n%s visible:\n%s id: \"amk-view-tree-%s\"\n%s timeout: 1\n%s optional: true\n", ind, ind, ind, name, ind, ind
340
+ }' "$1"
341
+ }
256
342
  run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to turn it) [again]
257
343
  out="$evidence/$1"
258
344
  # a part of the flows has a folder of its own in the screen's, as the parts run at the same time: part 1 clears what
@@ -272,9 +358,14 @@ run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to
272
358
  mkdir -p "$out"
273
359
  # this run's screenshots are the ones newer than this; the status before it, for running the screen again
274
360
  : > "$out/.started"
361
+ # each flow's result, and what the view trees showed (Android), for the report
362
+ : > "$out/.flows"
363
+ : > "$out/.a11y"
364
+ [ "${1%%-*}" != android ] || density=$(device_density "$2")
275
365
  [ -n "${5:-}" ] || before=$status
276
366
  files=$(flow_files)
277
367
  if [ -z "$files" ]; then
368
+ [ -z "$tags" ] || echo " $1: no flow has the tag $tags, so this is a check that the app opens"
278
369
  # launchApp returns before the app has drawn, and a splash screen stays up until the JavaScript has loaded:
279
370
  # a fixed wait (for text that never appears), then for the screen to settle, so the screenshot shows the app
280
371
  printf 'appId: %s\n---\n- launchApp\n- extendedWaitUntil:\n visible: "agentic-mobile-kit: waiting for the app to draw"\n timeout: 5000\n optional: true\n- waitForAnimationToEnd\n- takeScreenshot: smoke-launch\n' "$3" > "$out/smoke.yaml"
@@ -285,7 +376,8 @@ run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to
285
376
  for f in $files; do
286
377
  total=$((total + 1))
287
378
  name=$(basename "$f" .yaml)
288
- ok=0
379
+ ok=0 why="" shot=""
380
+ : > "$out/.flow-started"
289
381
  run_flow "$1" "$2" "$3" "$f" "$name" "$4" || ok=$?
290
382
  # Maestro now and then stops before a flow starts (it printed nothing), and an emulator sometimes drops its adb
291
383
  # connection for a moment: run the flow once more (after reconnecting)
@@ -322,6 +414,19 @@ run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to
322
414
  echo " $1: flow $name failed, see ${out#"$root"/}/$name.log and Maestro's own log ${debug#"$root"/}/maestro.log"
323
415
  status=1
324
416
  fi
417
+ if [ "$ok" != 0 ]; then
418
+ why=$(why_failed "$2" "$name" | tr '\t' ' ')
419
+ # a step the device dropped out of has no FAILED line: say so, or it reads as the flow's own failure
420
+ [ -n "$why" ] || [ "${1%%-*}" != android ] || ! lost_device "$out/$name.log" ||
421
+ why="when the device went offline, on each try (an emulator under load drops out: check again with fewer devices open)"
422
+ shot=$(failure_shot "$2")
423
+ [ -z "$why" ] || echo " failed $why"
424
+ [ -z "$shot" ] || echo " the screen when it failed: ${shot#"$root"/}"
425
+ fi
426
+ # for the report: the flow, its result, why it failed, the screenshots it took, and the screen when it failed
427
+ printf '%s\t%s\t%s\t%s\t%s\n' "$name" "$([ "$ok" = 0 ] && echo passed || echo failed)" "$why" \
428
+ "$(find "$out" -name '*.png' -newer "$out/.flow-started" | sed "s|^$evidence/||" | sort | tr '\n' ',' | sed 's/,$//')" \
429
+ "${shot#"$evidence"/}" >> "$out/.flows"
325
430
  done
326
431
  # iOS saves a turned screen's screenshots at the device's upright size, with a tag that tells viewers to turn them,
327
432
  # and some viewers ignore it: save them turned (through BMP, which keeps no tag), so every viewer shows the screen
@@ -351,6 +456,8 @@ run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to
351
456
  fi
352
457
  shots=$(find "$out" -name '*.png' | wc -l | tr -d ' ')
353
458
  echo "$1: flows $passed/$total passed, $shots screenshots in ${out#"$root"/}"
459
+ a11y=$(grep -c . "$out/.a11y" 2> /dev/null || true)
460
+ [ "${a11y:-0}" = 0 ] || echo " $1: $a11y accessibility warning$([ "$a11y" = 1 ] || echo s) on the flows' screens (controls without a label, tap areas under 48 dp): see the report"
354
461
  if [ "$shots" = 0 ]; then
355
462
  echo " $1: no screenshots were saved, so there's no evidence; treating this as a failure"
356
463
  status=1
@@ -365,6 +472,7 @@ run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to
365
472
  case $was in upright) other=landscape ;; *) other=portrait ;; esac
366
473
  echo " $1: the app sets its orientation in its code (${set_in% }), which can keep it $was. If it's meant to stay $was, take $other out of its native settings (UISupportedInterfaceOrientations in Info.plist, screenOrientation in AndroidManifest.xml) and this screen isn't checked any more; otherwise change that code"
367
474
  fi
475
+ echo " $1: a flow that leaves the app (a call, the camera, a picker) comes back $was when the other app's screen turned the device: turn it back after that step with - setOrientation: \${ORIENTATION}"
368
476
  fi
369
477
  }
370
478
 
@@ -644,6 +752,10 @@ device_width() {
644
752
  /Physical size/ { split($2, s, "x"); w = s[1] + 0 < s[2] + 0 ? s[1] : s[2] } /Physical density/ { d = $2 }
645
753
  END { if (d) print int(w * 160 / d) }'
646
754
  }
755
+ # the screen density (dpi) of the Android device $1: the one set for it, else its own
756
+ device_density() {
757
+ "$adb" -s "$1" shell 'wm size; wm density' 2> /dev/null | tr -d '\r' | awk -F': ' '/Override density/ { o = $2 } /Physical density/ { p = $2 } END { print o ? o : p }'
758
+ }
647
759
  avd_home=${ANDROID_AVD_HOME:-${ANDROID_USER_HOME:-$HOME/.android}/avd}
648
760
  # an AVD's folder: its .ini names it (an AVD can be renamed, and keep its folder), else <name>.avd
649
761
  avd_dir() { d=$(sed -n 's/^path=//p' "$avd_home/$1.ini" 2> /dev/null | head -n 1); echo "${d:-$avd_home/$1.avd}"; }
@@ -920,6 +1032,7 @@ plan() {
920
1032
  console.log(Math.round(os.totalmem() / 2 ** 30), Math.round(s.bavail * s.bsize / 2 ** 30))')
921
1033
  mem=$1
922
1034
  case ${AMK_MEMORY_GB:-x} in *[!0-9]*) ;; *) mem=$AMK_MEMORY_GB ;; esac
1035
+ case ${AMK_DISK_GB:-x} in *[!0-9]*) ;; *) set -- "$1" "$AMK_DISK_GB" ;; esac
923
1036
  have="$mem GB of memory, $2 GB free disk, Maestro $(maestro_version)"
924
1037
  # the devices to check, phones first and the platforms mixed, so a round of two has one of each
925
1038
  # (each platform's screens are read first: grep -q stops reading at its first match, and a writer still going then
@@ -1019,5 +1132,11 @@ case $mode in
1019
1132
  *) echo "verify: unknown mode $mode (quick, ios, android, all, build or plan)"; exit 2 ;;
1020
1133
  esac
1021
1134
 
1135
+ # the run's report, from every screen checked so far: other devices, parts and rounds add theirs
1136
+ case $mode in
1137
+ ios | android | all) if [ -n "$(find "$evidence" -name .flows 2> /dev/null | head -n 1)" ] && node scripts/amk/report.js "$evidence" > /dev/null 2>&1; then
1138
+ echo "Report: ${evidence#"$root"/}/report.md (each flow's result, why one failed, and its screenshots)"
1139
+ fi ;;
1140
+ esac
1022
1141
  echo "Evidence: ${evidence#"$root"/}/ (open the screenshots: a tool saying 'passed' isn't proof)"
1023
1142
  exit $status
@@ -1,5 +1,21 @@
1
1
  # <ID>: design
2
2
 
3
+ ## UI/UX level
4
+
5
+ <!-- For a feature with screens: the level the user confirmed before the design, and the date (n/a without screens).
6
+ Simple (the default): clean, minimal and functional. The app's own components and theme
7
+ (`docs/amk/design-system.md`), or the platform's standard ones; a clear hierarchy with room around it; standard
8
+ navigation, lists and forms; motion only where the platform gives it (screen transitions, pressed states).
9
+ Mixed: Simple, with modern touches where they help: cards with rounded corners and soft shadows, an accent colour
10
+ and icons, subtle transitions and feedback when something changes, skeletons while loading, friendly empty and
11
+ error states.
12
+ Premium: polished and visually engaging, following current iOS and Android design (Apple's Human Interface
13
+ Guidelines, Material 3): one type scale, spacing and colour tokens, dark mode, purposeful motion (shared
14
+ transitions, gestures), haptics on key actions, illustrations for empty states. It takes longer, and may need a
15
+ library (animation, haptics): ask before adding one.
16
+ Every level meets the same requirements and the screen rules (accessibility, large text, Reduce Motion, both
17
+ platforms): the level changes how the screens look and move, not what they do. -->
18
+
3
19
  ## Existing code to reuse
4
20
 
5
21
  <!-- Search first: components, hooks, API clients and helpers this change will use instead of writing new ones. -->
@@ -1,11 +1,22 @@
1
1
  # Copy to .maestro/<id>.yaml. verify.sh runs it on iOS and Android and keeps the screenshots as evidence.
2
2
  # Tap by testID (give every interactive element one); tapping by text can hit a label instead of the control.
3
+ # Each scenario of specs/<id>/requirements.md gets a "# Scenario <n>: <name>" comment above its steps, an assertion for
4
+ # its THEN and a screenshot: rn-check (in verify.sh quick) checks that, and Maestro's syntax, before any build.
5
+ # A screen that loads data also gets its empty and error states, each a scenario with a screenshot, where a flow can
6
+ # reach them: cleared data (launchApp: { clearState: true }) or an account without any for empty, and for no network
7
+ # "- setAirplaneMode: enabled" before the step and "disabled" after it (and in onFlowComplete, so a failure can't leave it on).
8
+ # Steps several flows share (logging in, skipping onboarding, a permission prompt) and resetting test data go in
9
+ # .maestro/subflows/ (specs/_templates/subflow.yaml), run with "- runFlow: subflows/<name>.yaml".
3
10
  # Test logins: ${MAESTRO_EMAIL}, ${MAESTRO_PASSWORD} and the like, set in .maestro/.env.local, which isn't committed.
4
11
  # On a real iPhone (maestro-runner): text with an apostrophe can't be searched for (use a testID), and permission
5
12
  # prompts aren't answered for the flow (tapOn: { text: "Allow", optional: true }). setAirplaneMode works only on an
6
13
  # iPhone in English (it looks for "Airplane Mode" in Settings) and leaves Settings in front: launchApp: { stopApp: false }
7
14
  # brings the app back. verify.sh opens Settings on its main page before such a flow, and turns airplane mode off after.
15
+ # A flow that leaves the app (a call, the camera, a system picker) can come back upright on a turned screen: the other
16
+ # app's portrait-only screen turned the device. Turn it back after that step with "- setOrientation: ${ORIENTATION}",
17
+ # which verify.sh sets to the screen's (run by hand: maestro test -e ORIENTATION=PORTRAIT <flow>).
8
18
  appId: ${APP_ID} # set by verify.sh
19
+ # tags: [smoke] # optional: verify.sh --tags smoke checks only the flows with one of the tags
9
20
  ---
10
21
  - launchApp:
11
22
  clearState: true