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.
- package/README.md +3 -3
- package/bin/cli.js +1 -1
- package/lib/init.js +62 -10
- package/package.json +1 -1
- package/stacks/react-native/expo/.rulesync/permissions.jsonc +6 -0
- package/stacks/react-native/expo/AGENTS.md +7 -3
- package/stacks/react-native/expo/docs/amk/expo.md +11 -0
- package/stacks/react-native/template/.agents/skills/m-bugfix/SKILL.md +10 -11
- package/stacks/react-native/template/.agents/skills/m-continue/SKILL.md +1 -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 +16 -11
- package/stacks/react-native/template/.agents/skills/m-onboard/SKILL.md +8 -5
- package/stacks/react-native/template/.agents/skills/m-prototype/SKILL.md +5 -5
- package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +5 -2
- package/stacks/react-native/template/.github/pull_request_template.md +3 -1
- package/stacks/react-native/template/.github/workflows/e2e.yml +3 -0
- package/stacks/react-native/template/.rulesync/permissions.jsonc +6 -0
- package/stacks/react-native/template/.rulesync/subagents/m-design-reviewer.md +22 -0
- package/stacks/react-native/template/.rulesync/subagents/m-device-checker.md +2 -2
- package/stacks/react-native/template/.rulesync/subagents/m-reviewer.md +1 -1
- package/stacks/react-native/template/AGENTS.md +7 -3
- package/stacks/react-native/template/docs/amk/design-system.md +15 -0
- package/stacks/react-native/template/docs/amk/glossary.md +12 -0
- package/stacks/react-native/template/docs/amk/react-native.md +11 -0
- package/stacks/react-native/template/scripts/amk/a11y.js +78 -0
- package/stacks/react-native/template/scripts/amk/guard.js +22 -1
- package/stacks/react-native/template/scripts/amk/report.js +78 -0
- package/stacks/react-native/template/scripts/amk/rn-check.js +155 -17
- package/stacks/react-native/template/scripts/amk/verify.sh +134 -15
- package/stacks/react-native/template/specs/_templates/design.md +16 -0
- package/stacks/react-native/template/specs/_templates/flow.yaml +11 -0
- package/stacks/react-native/template/specs/_templates/questions.md +29 -0
- package/stacks/react-native/template/specs/_templates/subflow.yaml +36 -0
- package/stacks/react-native/template/specs/_templates/tasks.md +2 -2
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: m-design-reviewer
|
|
3
|
+
targets: ["*"]
|
|
4
|
+
description: Read-only review of how screens look, from their device screenshots alone. Use when m-feature or m-prototype asks for a design review of a check's screenshots.
|
|
5
|
+
claudecode:
|
|
6
|
+
tools: ["Read", "Glob"]
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
You review how screens look, from their screenshots alone. You didn't build them and aren't told why anything is the way it is: judge what's on the screen. You never edit files.
|
|
10
|
+
|
|
11
|
+
Your inputs, and nothing else: the screenshot folders you're given (`.amk/evidence/<id>/<screen>/`, one per phone, tablet and orientation), `docs/amk/design-system.md`, and the UI/UX level in `specs/<id>/design.md`.
|
|
12
|
+
|
|
13
|
+
1. Open every screenshot in every folder.
|
|
14
|
+
2. Check each one:
|
|
15
|
+
- **The app's look:** colours, type sizes, spacing, corner radius, buttons and fields as `design-system.md` describes them; nothing that looks like it came from another app.
|
|
16
|
+
- **Care:** edges line up, spacing is even, one primary action per screen, nothing crowded against an edge or the system bars, no text cut off, overlapping or wrapping badly, on every screen size and orientation.
|
|
17
|
+
- **Every state:** loading, empty and error screens look as finished as the full one, and say what to do next.
|
|
18
|
+
- **Not generic:** no card inside a card, rows of identical icon-and-title tiles, decorative gradients, emoji used as icons, filler text (Lorem ipsum, Jane Doe) or figures that look made up.
|
|
19
|
+
- **Its level:** a Simple screen carrying decoration it doesn't need, or a Mixed or Premium one that looks unfinished.
|
|
20
|
+
3. Start your report with one word: **ship** (nothing owed), **fix** (findings follow) or **recapture** (a screenshot is missing, blank or shows the wrong screen: name it, then review the rest). A screen that may be empty on purpose is also judged as an empty state: does it say what belongs there and what to do?
|
|
21
|
+
4. Then at most eight findings, the costliest first, one line each: the screenshot, what's wrong, and what you'd change.
|
|
22
|
+
5. End with one line: what must not be lost while fixing it.
|
|
@@ -9,8 +9,8 @@ claudecode:
|
|
|
9
9
|
You check the app on one device with fresh eyes, and hand the evidence back. You never edit files.
|
|
10
10
|
|
|
11
11
|
1. Run the one command you were given exactly as it is, for example `sh scripts/amk/verify.sh ios --no-build --screens tablet --spec <id>`: no pipes, redirects or other commands added. Its output is short, and the plain command is the one people allow, so you don't wait on a permission prompt while the other checkers run. It installs the build that's there, runs the feature's Maestro flows on that device's screens (upright and turned), and saves screenshots in `.amk/evidence/<id>/<screen>/`. A command with `--part k/n` runs only its share of the flows, on a device of its own (a temporary copy for the parts after the first, deleted afterwards), and saves them in `.amk/evidence/<id>/<screen>/part-k/`. Don't build, and don't run anything else on a device: other checkers are using the other devices. A check takes several minutes, up to about 15 when a flow has to run again: give the command a timeout that long, or run it in the background and wait for it to end, never stopping it early.
|
|
12
|
-
2. If a flow failed, read its log and Maestro's own log
|
|
13
|
-
3. Open every screenshot in your screens' folders and check each against its scenario in `specs/<id>/requirements.md`, and against the screen rules in the React Native rules file that `AGENTS.md` names: the right content, nothing cut off or covered, a layout made for that screen. A turned screen's screenshots are landscape; a portrait one means the app didn't turn.
|
|
12
|
+
2. If a flow failed, the output says at which step and what Maestro said, and shows the screen then (`report.md` in the evidence folder has it too); read its log and Maestro's own log for more, and say why, and whether the app or the flow is wrong: on a turned screen, a flow often checks or taps something further down without scrolling to it first. Don't fix anything.
|
|
13
|
+
3. On Android screens, the output may list accessibility warnings from the screens' view trees (controls without a label, tap areas under 48 dp; `report.md` says which screenshot): report them as they are, they don't fail the check. Open every screenshot in your screens' folders and check each against its scenario in `specs/<id>/requirements.md`, and against the screen rules in the React Native rules file that `AGENTS.md` names: the right content, nothing cut off or covered, a layout made for that screen. A turned screen's screenshots are landscape; a portrait one means the app didn't turn.
|
|
14
14
|
4. Report, and say only what you saw in this run:
|
|
15
15
|
- the command, and its last lines of output;
|
|
16
16
|
- per screen: flows passed out of total, and the evidence folder;
|
|
@@ -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`, `git show`, `node scripts/amk/baseline.js base` and `node scripts/amk/rn-check.js`.
|
|
10
10
|
|
|
11
11
|
1. Get the changes since the base branch the kit's checks use: `node scripts/amk/baseline.js base` prints it, then `git diff <base>...HEAD`. If a spec exists in `specs/<id>/`, read its `requirements.md`. Run `node scripts/amk/rn-check.js`: what it reports is a finding, and each `// amk-ok: <reason>` it lists needs a reason that holds.
|
|
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, state on checkboxes, switches and tabs, contrast, text sizes, messages announced to screen readers), platform guidelines (44/48 tap areas, back gestures and the back button, permissions asked in context, native controls, dark mode, Reduce Motion), store review (account deletion, Sign in with Apple next to a social login, in-app purchase for digital goods, permission texts, restricted Android permissions), TypeScript (new `any` or `@ts-ignore`, a loosened tsconfig), removed or deprecated React Native APIs, errors (an error boundary, no empty `catch`, failed actions shown), error and empty states, effects that don't clean up, secrets and tokens in plain storage, native file changes, and performance.
|
|
12
|
+
2. Check scope, tests (added, deleted, weakened), iOS vs Android differences, the design system (`docs/amk/design-system.md`: no colours, sizes or controls outside it), forms (labels, keyboard and autofill, errors under fields, no double submit), nothing invented on screens (figures, ratings, placeholder names), 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, state on checkboxes, switches and tabs, contrast, text sizes, messages announced to screen readers), platform guidelines (44/48 tap areas, back gestures and the back button, permissions asked in context, native controls, dark mode, Reduce Motion), store review (account deletion, Sign in with Apple next to a social login, in-app purchase for digital goods, permission texts, restricted Android permissions), TypeScript (new `any` or `@ts-ignore`, a loosened tsconfig), removed or deprecated React Native APIs, errors (an error boundary, no empty `catch`, failed actions shown), error and empty states, effects that don't clean up, secrets and tokens in plain storage, 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".
|
|
@@ -10,6 +10,8 @@ This project may also use other AI workflow frameworks (for example Superpowers,
|
|
|
10
10
|
- Bare React Native {{RN_VERSION}} ({{RN_ARCH}}), React {{REACT_VERSION}}, {{LANGUAGE}}, Node {{NODE_VERSION}}. Package manager: {{PM}}.
|
|
11
11
|
- Screens: {{SCREENS}}. Build every screen for each of them (`docs/amk/react-native.md`, Tablets and landscape); `verify.sh` checks each one.
|
|
12
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`.
|
|
13
|
+
- The app's own words, to use in names, specs and messages: `docs/amk/glossary.md`.
|
|
14
|
+
- How the app looks, which new screens follow (colours, type, spacing, controls): `docs/amk/design-system.md`.
|
|
13
15
|
|
|
14
16
|
## Commands
|
|
15
17
|
|
|
@@ -20,9 +22,9 @@ This project may also use other AI workflow frameworks (for example Superpowers,
|
|
|
20
22
|
| iOS pods (after native dependency changes) | `sh scripts/amk/pod-install.sh` |
|
|
21
23
|
| iOS build (simulator, no signing) | `sh scripts/amk/ios-build.sh` |
|
|
22
24
|
| Android build | `cd android && ./gradlew assembleDebug` |
|
|
23
|
-
| Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; with product flavors it checks the first unless `--flavor <name>`; another iOS scheme: `--scheme <name>`; only some screens: `--screens phone` (or `tablet`, `landscape`, …); on a real iPhone or iPad the user names: `AMK_IOS_DEVICE=<its UDID>` (the flows clear the app's data on it) |
|
|
25
|
+
| Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; with product flavors it checks the first unless `--flavor <name>`; another iOS scheme: `--scheme <name>`; only some screens: `--screens phone` (or `tablet`, `landscape`, …); only the flows tagged smoke: `--tags smoke`; on a real iPhone or iPad the user names: `AMK_IOS_DEVICE=<its UDID>` (the flows clear the app's data on it) |
|
|
24
26
|
| Check devices at the same time | `sh scripts/amk/verify.sh plan --spec <id>` says how many this machine's memory fits, and prints the commands: one per device (in rounds when they don't all fit; a device's flows in parts when there's room), each for an `m-device-checker` subagent |
|
|
25
|
-
| React Native mistakes in this branch's changed lines (`verify.sh quick` runs it) | `node scripts/amk/rn-check.js` |
|
|
27
|
+
| React Native mistakes and Maestro flow problems in this branch's changed lines (`verify.sh quick` runs it) | `node scripts/amk/rn-check.js` |
|
|
26
28
|
| Specs: progress, format check, fold a finished feature into the living spec | `node scripts/amk/specs.js status`, `node scripts/amk/specs.js check`, `node scripts/amk/specs.js merge <id>` |
|
|
27
29
|
| Check a release before tagging it (versions, permission texts, store review rules, debug leftovers) | `node scripts/amk/release-check.js` |
|
|
28
30
|
| Signed release builds (a person runs them: they use the signing keys) | `sh scripts/amk/release-build.sh android [flavor]`, `sh scripts/amk/release-build.sh ios [scheme]` |
|
|
@@ -40,10 +42,12 @@ Never say a check passed unless you ran it in this session.
|
|
|
40
42
|
## Rules
|
|
41
43
|
|
|
42
44
|
- Stay inside the task. Ask before touching unrelated files.
|
|
45
|
+
- Ask the user in rounds: every question you can ask now (its answer doesn't wait on another open question), numbered, each with the answer you recommend and worded so "yes" takes it. A "yes" answers that round and nothing more: an approval is asked for on its own. The answers can open the next round. Look facts up in the code yourself; ask only for decisions. A question only someone else can answer (the client, a designer, the backend team) goes into `specs/<id>/questions-<who>.md`, from `specs/_templates/questions.md`, for the user to send; go on with the rest.
|
|
46
|
+
- Before designing a feature's screens, ask the user which UI/UX level they want: Simple (the default), Mixed or Premium (`specs/_templates/design.md` describes each). Build them to it.
|
|
43
47
|
- Ask before adding or upgrading dependencies, and before editing `package.json`, lockfiles, `Podfile`, `build.gradle`, `Info.plist`, `AndroidManifest.xml` or `.github/workflows/`.
|
|
44
48
|
- Don't hand-edit `ios/*.xcodeproj/project.pbxproj`. If a native file must be added to the Xcode project, stop and ask.
|
|
45
49
|
- Never read, print or commit `.env` files, keystores, signing files or the files `.amk-secrets` lists. Secrets don't belong in this repo.
|
|
46
|
-
- Never use `git commit --no-verify`, `git push --force`, `git reset --hard` or `rm -rf
|
|
50
|
+
- Never use `git commit --no-verify`, `git push --force`, `git reset --hard` or `rm -rf`, and never throw away work that can't be brought back (uncommitted changes with `git checkout .` or `git restore .`, stashes with `git stash drop` or `clear`, unmerged commits with `git branch -D`): ask first. To undo your own edit to a file, `git checkout -- <that file>`.
|
|
47
51
|
- When `rn-check` (in `verify.sh quick`) reports a problem (✗), show it to the user and let them choose, for each one: fix it, or keep the line with `// amk-ok <today's date>: <their reason>`. Never add an `amk-ok` on your own. One kept over two weeks ago comes back when its file changes again: ask again. Fix the warnings (!) in code the task changed, or tell the user why one stays.
|
|
48
52
|
- After 2 failed attempts at the same fix, stop and report what you found.
|
|
49
53
|
- Chat is not memory: write decisions into the spec or `docs/amk/decisions.md` straight away.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Design system
|
|
2
|
+
|
|
3
|
+
<!-- How the app looks, so every new screen matches the ones it has. Facts from the app's theme and shared components,
|
|
4
|
+
each with the file it comes from, not advice. m-onboard drafts it; something new (a colour, a component) is added here
|
|
5
|
+
and to the theme before a screen uses it.
|
|
6
|
+
- Theme: the file(s) holding colours, type and spacing (`src/theme/…`), and how a screen reads them (a hook, an import).
|
|
7
|
+
- Colours, by role: background, surface (cards, sheets), text, muted text, primary (the main action), error, success,
|
|
8
|
+
border. Dark mode's too, if the app has it.
|
|
9
|
+
- Type: the font(s), and the size and weight of each role in use (title, heading, body, caption, button).
|
|
10
|
+
- Spacing and shape: the spacing steps (4, 8, 16, …), corner radius, shadows.
|
|
11
|
+
- Controls: the primary and secondary button, text field, list row, and the shared components that draw them.
|
|
12
|
+
- Icons: the set (library) and its sizes; images and illustrations, if the app has them.
|
|
13
|
+
- Motion: what animates and for how long, and what happens with Reduce Motion on.
|
|
14
|
+
- Voice: how the app's texts speak (formal or casual, "you") and the words its buttons use (Save, Done, …).
|
|
15
|
+
-->
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Glossary
|
|
2
|
+
|
|
3
|
+
<!-- The app's own words: what its users and its business talk about (an Order, a Visit, a Plan), so agents and people
|
|
4
|
+
name things the same way in code, specs, flows and messages, and say in one word what would take a sentence.
|
|
5
|
+
- One entry per term: the word, what it is in one or two sentences (what it is, not how the code does it), and the other
|
|
6
|
+
words people use for it that this app doesn't, when there are any (no "not" line otherwise).
|
|
7
|
+
- Only the app's own concepts: not general programming terms (a cache, a hook, a retry).
|
|
8
|
+
- When two words mean the same thing, pick one and list the other under "not".
|
|
9
|
+
|
|
10
|
+
**<Term>**: what it is, in one or two sentences.
|
|
11
|
+
_Not:_ <the other words used for it>.
|
|
12
|
+
-->
|
|
@@ -14,6 +14,11 @@ Rules for things AI agents commonly get wrong in current React Native. Each one
|
|
|
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
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
|
+
- New screens use the app's design system (`docs/amk/design-system.md`): its colours, type sizes, spacing, radius and shared controls. Something it doesn't have (a colour, a component) goes into it and the theme first, not into one screen.
|
|
18
|
+
- Every field has a visible label; a placeholder only shows the format (`DD/MM/YYYY`), never the label, which disappears once the user types.
|
|
19
|
+
- The keyboard and autofill fit the field: `keyboardType` (`email-address`, `number-pad`, `phone-pad`), `autoComplete` (`email`, `password`, `one-time-code`, `postal-code`, …) and on iOS `textContentType`, `autoCapitalize="none"` for emails and codes, `secureTextEntry` for passwords, and `returnKeyType` with `onSubmitEditing` going to the next field.
|
|
20
|
+
- A field is checked when the user leaves it, then as they type; its error shows under it and says what to do. The submit button is disabled only while the request runs.
|
|
21
|
+
- A button that starts a request shows it's working without changing size, ignores a second tap until the request ends, then shows the result or the error: never a success message when nothing was saved. A destructive action asks first, or can be undone.
|
|
17
22
|
- 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
23
|
- 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
24
|
- Messages that appear after an action, such as a form error, are read out by screen readers. On Android, show the message in a view with `accessibilityLiveRegion="polite"`: Android 16 deprecated announcements. On iOS, announce it with `AccessibilityInfo.announceForAccessibility`.
|
|
@@ -56,6 +61,10 @@ These changed after most AI training data was written: check them instead of wri
|
|
|
56
61
|
- List keys come from the item's ID, not its index: index keys mix up rows when items are added, removed or reordered.
|
|
57
62
|
- Images go in asset files, never in code as base64 strings: they bloat the bundle, and all of it loads with the JavaScript.
|
|
58
63
|
- Component tests use React Native Testing Library (`@testing-library/react-native`) and find elements as users and screen readers do, by role, label or text (`getByRole('button', { name: 'Save' })`), rather than relying on snapshots.
|
|
64
|
+
- A test checks what a user or a caller sees, through the public interface (rendered text and roles, a hook's result, a function's return), so a refactor that keeps the behavior keeps the test passing.
|
|
65
|
+
- Mock only what the app doesn't own: the network, storage, native modules, time and randomness. Not the app's own components, hooks or modules: a test of mocks passes whatever the code does.
|
|
66
|
+
- Expected values come from the spec or a worked example (`expect(total([10, 5])).toBe(15)`), never computed the way the code computes them, or the test can't fail.
|
|
67
|
+
- A bug fix comes with a test that failed before the fix.
|
|
59
68
|
|
|
60
69
|
## Platform guidelines and accessibility
|
|
61
70
|
|
|
@@ -71,6 +80,8 @@ From Apple's Human Interface Guidelines, Android's design and app quality guidel
|
|
|
71
80
|
- Use the native controls (`@react-native-community/datetimepicker`, `Alert.alert` with verb buttons and `style: 'destructive'` and `'cancel'`, `ActionSheetIOS`, `Switch`); a custom one gets the same role, state and size.
|
|
72
81
|
- Dark mode: colors come from the theme's light and dark values (`useColorScheme()`), not hex values in components; don't lock the app to light.
|
|
73
82
|
- Data screens have loading, empty (why, and what to do next), error (what failed, with Retry) and content states. A message the user has to read doesn't vanish on a timer, and screen readers announce it.
|
|
83
|
+
- Nothing on a screen is invented: texts, numbers, ratings, reviews, user counts and images come from the spec, the app's data or the client. Where one is missing, a placeholder the PR lists (and `specs/<id>/questions-<who>.md` asks for), never a made-up figure, quote or rating. Brand colours, fonts and logos come from the project or the client, never from memory. A prototype's mock data stays in its mock-data file.
|
|
84
|
+
- Texts say what things do, in the app's words (`docs/amk/glossary.md`), not marketing filler (seamless, effortless, unlock your potential); icons come from the app's icon set, not emoji.
|
|
74
85
|
- Reduce Motion: with it on, nothing loops or moves for decoration. Don't pass `ReduceMotion.Never` to Reanimated for decoration; with `Animated` or Lottie, read `AccessibilityInfo.isReduceMotionEnabled()` and the `reduceMotionChanged` event, and fade or stop instead.
|
|
75
86
|
- iOS 26: use native headers and tab bars (React Navigation's native stack and native tabs), which iOS draws in its current style; don't draw imitation glass behind content, or opt out with `UIDesignRequiresCompatibility` (builds with the iOS 27 SDK ignore it). Nothing the user needs sits under a floating tab bar, button or footer: scroll content gets bottom padding for it.
|
|
76
87
|
- Haptics only for success, error or a selection, never as the only feedback, through the app's haptics library; not `Vibration.vibrate`.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Accessibility on the device: from the view trees verify.sh has Maestro save after each screenshot on Android (which
|
|
3
|
+
// marks what's tappable; iOS' tree doesn't), the tappable elements without a label, which a screen reader can't name,
|
|
4
|
+
// and the ones smaller than 48×48 dp, Android's minimum (and more than iOS' 44 points: React Native lays out both
|
|
5
|
+
// alike). An element a scrolling list cuts off at its edge isn't measured. Prints a line each, once per element and
|
|
6
|
+
// kind of problem in a flow: flow, screenshot, problem, element.
|
|
7
|
+
// Usage: node scripts/amk/a11y.js <Maestro debug folder> <screen density in dpi> <flow>
|
|
8
|
+
'use strict';
|
|
9
|
+
const fs = require('fs');
|
|
10
|
+
const path = require('path');
|
|
11
|
+
|
|
12
|
+
const [dir, dpi, flow] = process.argv.slice(2);
|
|
13
|
+
const scale = Number(dpi) / 160;
|
|
14
|
+
if (!dir || !scale || !fs.existsSync(dir)) process.exit(0);
|
|
15
|
+
|
|
16
|
+
// the trees and the screenshot each follows, in the order the flow saved them. Maestro's commands.json has each step:
|
|
17
|
+
// the view-tree step's id (amk-view-tree-<screenshot>) and the tree it saved; the file's own name is cut short
|
|
18
|
+
const trees = [];
|
|
19
|
+
const files = [];
|
|
20
|
+
(function find(d, depth) {
|
|
21
|
+
for (const e of fs.readdirSync(d, { withFileTypes: true })) {
|
|
22
|
+
const p = path.join(d, e.name);
|
|
23
|
+
if (e.isDirectory() && depth < 4) find(p, depth + 1);
|
|
24
|
+
else files.push(p);
|
|
25
|
+
}
|
|
26
|
+
})(dir, 0);
|
|
27
|
+
for (const f of files.filter(p => path.basename(p) === 'commands.json')) {
|
|
28
|
+
let steps;
|
|
29
|
+
try { steps = JSON.parse(fs.readFileSync(f, 'utf8')); } catch { continue; }
|
|
30
|
+
for (const s of Array.isArray(steps) ? steps : []) {
|
|
31
|
+
const id = ((((s.command || {}).assertConditionCommand || {}).condition || {}).visible || {}).idRegex || '';
|
|
32
|
+
const tree = ((s.metadata || {}).artifacts || []).find(a => a.type === 'SCREEN_HIERARCHY');
|
|
33
|
+
if (id.startsWith('amk-view-tree-') && tree) trees.push([path.join(path.dirname(f), tree.path), id.slice(14)]);
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
// without commands.json: the names of the trees' files
|
|
37
|
+
if (!trees.length) {
|
|
38
|
+
for (const p of files.filter(p => /amk-view-tree-.+\.json$/.test(p)).sort((a, b) => path.basename(a).localeCompare(path.basename(b)))) {
|
|
39
|
+
trees.push([p, /amk-view-tree-(.+)\.json$/.exec(path.basename(p))[1]]);
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
// the system's own windows, with everything inside them (the status bar, a keyboard and its suggestions); Android's
|
|
44
|
+
// own ids (android:id/…) only for that element, as the app's views sit inside android:id/content
|
|
45
|
+
const SYSTEM = /^(com\.android\.systemui|com\.google\.android\.inputmethod|com\.android\.inputmethod|com\.samsung\.android\.honeyboard|com\.touchtype\.swiftkey)/;
|
|
46
|
+
const box = a => { const b = /\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]/.exec(a.bounds || ''); return b && b.slice(1).map(Number); };
|
|
47
|
+
const seen = new Set();
|
|
48
|
+
for (const [file, shot] of trees) {
|
|
49
|
+
let tree;
|
|
50
|
+
try { tree = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { continue; }
|
|
51
|
+
// each node with the bounds of the nearest scrolling container around it
|
|
52
|
+
(function walk(n, clip) {
|
|
53
|
+
if (!n) return;
|
|
54
|
+
const a = n.attributes || {};
|
|
55
|
+
if (SYSTEM.test(a['resource-id'] || '')) return;
|
|
56
|
+
const b = box(a);
|
|
57
|
+
if (a.clickable === 'true' && b && !/^android:id\//.test(a['resource-id'] || '')) {
|
|
58
|
+
const [x1, y1, x2, y2] = b;
|
|
59
|
+
const w = (x2 - x1) / scale;
|
|
60
|
+
const h = (y2 - y1) / scale;
|
|
61
|
+
const label = (a.accessibilityText || a.text || a.hintText || '').trim();
|
|
62
|
+
const id = a['resource-id'] || '';
|
|
63
|
+
const name = id ? `testID ${id}` : label ? `"${label}"` : `${a.class || 'an element'} at ${a.bounds}`;
|
|
64
|
+
// once per element and kind of problem in a flow, where it first shows (its size can differ a little later)
|
|
65
|
+
const say = problem => {
|
|
66
|
+
const key = `${id || label}|${problem.startsWith('no label') ? 'label' : 'size'}`; // a testID names it, whatever it shows
|
|
67
|
+
if (!seen.has(key)) { seen.add(key); console.log([flow, shot, problem, name].join('\t')); }
|
|
68
|
+
};
|
|
69
|
+
if (w > 0 && h > 0) {
|
|
70
|
+
if (!label) say('no label: a screen reader can\'t say what it does');
|
|
71
|
+
const cut = clip && (y1 <= clip[1] || y2 >= clip[3] || x1 <= clip[0] || x2 >= clip[2]);
|
|
72
|
+
if (!cut && (w < 47.5 || h < 47.5)) say(`${Math.round(w)}×${Math.round(h)} dp: under 48×48`);
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
const inner = a.scrollable === 'true' && b ? b : clip;
|
|
76
|
+
for (const c of n.children || []) walk(c, inner);
|
|
77
|
+
})(tree.root || tree, null);
|
|
78
|
+
}
|
|
@@ -27,6 +27,22 @@ const paths = [];
|
|
|
27
27
|
// rm with a recursive flag and a force flag anywhere before the next ; & | (-rf, -Rf, -r -f, --recursive --force);
|
|
28
28
|
// a push with --force, -f or a +refspec
|
|
29
29
|
const destructive = /\brm(?=[^;&|\n]*\s(-[a-zA-Z]*[rR][a-zA-Z]*|--recursive)\b)(?=[^;&|\n]*\s(-[a-zA-Z]*f[a-zA-Z]*|--force)\b)|git\s+reset\s+--hard|git\s+push\s+(.*\s)?((--force|-f)\b|\+\S)|git\s+clean\s+-[a-z]*f|--no-verify|xcrun\s+simctl\s+erase/;
|
|
30
|
+
// git commands that throw away work for good: every uncommitted change (a checkout or restore of the whole tree, a forced
|
|
31
|
+
// checkout or switch), saved stashes, a branch with commits merged nowhere. Undoing one file's edit stays allowed
|
|
32
|
+
const discards = c => c.split(/&&|\|\||[;&|\n]/).some(s => {
|
|
33
|
+
const m = /\bgit\s+(checkout|restore|switch|stash|branch)\b(.*)/.exec(s);
|
|
34
|
+
if (!m) return false;
|
|
35
|
+
const args = m[2].trim().split(/\s+/).filter(Boolean);
|
|
36
|
+
const short = args.filter(a => /^-[a-zA-Z]+$/.test(a)).join('');
|
|
37
|
+
const has = (letter, long) => short.includes(letter) || args.includes(long);
|
|
38
|
+
const everything = args.some(a => /^['"]?(\.|\.\/|:\/|\*)['"]?$/.test(a));
|
|
39
|
+
if (m[1] === 'checkout') return everything || has('f', '--force');
|
|
40
|
+
// --staged alone only unstages: the changes stay
|
|
41
|
+
if (m[1] === 'restore') return everything && (!has('S', '--staged') || has('W', '--worktree'));
|
|
42
|
+
if (m[1] === 'switch') return has('f', '--force') || args.includes('--discard-changes');
|
|
43
|
+
if (m[1] === 'stash') return args[0] === 'drop' || args[0] === 'clear';
|
|
44
|
+
return short.includes('D') || (has('d', '--delete') && has('f', '--force'));
|
|
45
|
+
});
|
|
30
46
|
// example files (.env.example, .env.local.example, .env.sample, .env.template) aren't secrets
|
|
31
47
|
const secretFile = /(^|[\s/'"=])\.env(?![\w.-]*\.(?:example|sample|template)(?=$|[\s'";|&)]))(\.[\w.-]+)?(?=$|[\s'";|&)])|\.(keystore|jks|p8|p12|mobileprovision)\b/;
|
|
32
48
|
// the project's own secret files: .amk-secrets lists them, one path from the project root per line (a folder ends in /)
|
|
@@ -37,7 +53,12 @@ const secret = s => secretFile.test(s) || listed.some(p => s.includes(p));
|
|
|
37
53
|
const block = reason => { process.stderr.write(`Blocked by scripts/amk/guard.js: ${reason}\n`); process.exit(2); };
|
|
38
54
|
for (const c of commands) {
|
|
39
55
|
// a command that only mentions one, in a commit message, is blocked too: the message can come from a file instead
|
|
40
|
-
|
|
56
|
+
const inMessage = /git\s+commit\b/.test(c) ? '\n(Only in the commit message? Write it to a file and use git commit -F <file>.)' : '';
|
|
57
|
+
if (destructive.test(c)) block(`destructive command: ${c}${inMessage}`);
|
|
58
|
+
if (discards(c)) {
|
|
59
|
+
block(`this throws away work that can't be brought back (uncommitted changes, stashes or unmerged commits): ${c}\n`
|
|
60
|
+
+ `Ask the user first, or keep the work: git stash, or a commit. To undo your own edit to a file: git checkout -- <that file>.${inMessage}`);
|
|
61
|
+
}
|
|
41
62
|
if (secret(c)) block(`shell access to a secret file: ${c}`);
|
|
42
63
|
}
|
|
43
64
|
for (const p of paths) {
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// A device check's report, from its evidence folder (.amk/evidence/<label>/): report.md for people (each screen, its
|
|
3
|
+
// flows, passed or failed and why, and their screenshots) and junit.xml for CI. --summary prints a short Markdown
|
|
4
|
+
// table instead, for a CI job's summary. verify.sh runs it after each device check, and builds it from what's on disk,
|
|
5
|
+
// so devices and parts checked at the same time all end up in it: each screen's flows are in <screen>/.flows (or
|
|
6
|
+
// <screen>/part-<k>/.flows), a line each: name, passed or failed, why, its screenshots, the screen when it failed.
|
|
7
|
+
// Usage: node scripts/amk/report.js <evidence folder> [--summary]
|
|
8
|
+
'use strict';
|
|
9
|
+
const fs = require('fs');
|
|
10
|
+
const path = require('path');
|
|
11
|
+
|
|
12
|
+
const [dir, mode] = process.argv.slice(2);
|
|
13
|
+
if (!dir || !fs.existsSync(dir)) {
|
|
14
|
+
console.error('usage: node scripts/amk/report.js <evidence folder> [--summary]');
|
|
15
|
+
process.exit(2);
|
|
16
|
+
}
|
|
17
|
+
const label = path.basename(path.resolve(dir));
|
|
18
|
+
const read = f => { try { return fs.readFileSync(f, 'utf8'); } catch { return null; } };
|
|
19
|
+
|
|
20
|
+
// the screens: <screen>/.flows, and <screen>/part-<k>/.flows for a device's flows split in parts
|
|
21
|
+
const screens = [];
|
|
22
|
+
for (const s of fs.readdirSync(dir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name).sort()) {
|
|
23
|
+
for (const sub of ['', ...(fs.readdirSync(path.join(dir, s)).filter(p => /^part-\d+$/.test(p)).sort())]) {
|
|
24
|
+
const text = read(path.join(dir, s, sub, '.flows'));
|
|
25
|
+
if (text === null) continue;
|
|
26
|
+
// what the view trees showed on Android: flow, screenshot, problem, element (a11y.js)
|
|
27
|
+
const a11y = (read(path.join(dir, s, sub, '.a11y')) || '').split('\n').filter(Boolean).map(l => l.split('\t'));
|
|
28
|
+
const flows = text.split('\n').filter(Boolean).map(l => {
|
|
29
|
+
const [name, result, why, shots, shot] = l.split('\t');
|
|
30
|
+
return { name, passed: result === 'passed', why: why || '', shots: (shots || '').split(',').filter(Boolean), shot: shot || '',
|
|
31
|
+
a11y: a11y.filter(x => x[0] === name).map(([, at, problem, element]) => ({ at, problem, element })) };
|
|
32
|
+
});
|
|
33
|
+
screens.push({ name: sub ? `${s} (${sub.replace('-', ' ')})` : s, dir: sub ? `${s}/${sub}` : s, flows });
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
const all = screens.flatMap(s => s.flows);
|
|
37
|
+
const failed = all.filter(f => !f.passed);
|
|
38
|
+
const counts = s => `${s.flows.filter(f => f.passed).length}/${s.flows.length}`;
|
|
39
|
+
const table = ['| Screen | Flows passed | Screenshots |', '|---|---|---|',
|
|
40
|
+
...screens.map(s => `| ${s.name} | ${counts(s)}${s.flows.every(f => f.passed) ? '' : ' ✗'} | ${s.flows.reduce((n, f) => n + f.shots.length, 0)} |`)];
|
|
41
|
+
const warned = all.reduce((n, f) => n + f.a11y.length, 0);
|
|
42
|
+
const headline = `${all.length - failed.length} of ${all.length} flows passed on ${screens.length} screen${screens.length === 1 ? '' : 's'}${warned ? `, ${warned} accessibility warning${warned === 1 ? '' : 's'}` : ''}`;
|
|
43
|
+
|
|
44
|
+
if (mode === '--summary') {
|
|
45
|
+
console.log([`### Device checks: ${label}`, '', headline, '', ...table, '',
|
|
46
|
+
...failed.map(f => `- ✗ ${screens.find(s => s.flows.includes(f)).name}: ${f.name}${f.why ? `, failed ${f.why}` : ''}`)].join('\n'));
|
|
47
|
+
process.exit(0);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
// a path inside the evidence folder, for a link from report.md, which sits in it
|
|
51
|
+
const link = p => p.split('/').map(encodeURIComponent).join('/');
|
|
52
|
+
const md = [`# Device checks: ${label}`, '', `${new Date().toISOString().slice(0, 16).replace('T', ' ')} UTC · ${headline}`, '', ...table];
|
|
53
|
+
for (const s of screens) {
|
|
54
|
+
md.push('', `## ${s.name}`);
|
|
55
|
+
for (const f of s.flows) {
|
|
56
|
+
md.push('', `### ${f.passed ? '✓' : '✗'} ${f.name}`);
|
|
57
|
+
if (!f.passed) {
|
|
58
|
+
md.push('', `Failed${f.why ? ` ${f.why}` : ''}. Log: [${s.dir}/${f.name}.log](${link(`${s.dir}/${f.name}.log`)})${f.shot ? ` · [the screen when it failed](${link(f.shot)})` : ''}`);
|
|
59
|
+
}
|
|
60
|
+
if (f.shots.length) md.push('', f.shots.map(p => `<img src="${link(p)}" width="180" alt="${path.basename(p, '.png')}" title="${path.basename(p, '.png')}">`).join(' '));
|
|
61
|
+
if (f.a11y.length) md.push('', 'Accessibility, from the screen\'s view tree:', '', ...f.a11y.map(x => `- ${x.at}: ${x.element}: ${x.problem}`));
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
fs.writeFileSync(path.join(dir, 'report.md'), `${md.join('\n')}\n`);
|
|
65
|
+
|
|
66
|
+
const xml = s => String(s).replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"');
|
|
67
|
+
fs.writeFileSync(path.join(dir, 'junit.xml'), [
|
|
68
|
+
'<?xml version="1.0" encoding="UTF-8"?>',
|
|
69
|
+
`<testsuites name="${xml(label)}" tests="${all.length}" failures="${failed.length}">`,
|
|
70
|
+
...screens.flatMap(s => [
|
|
71
|
+
` <testsuite name="${xml(s.name)}" tests="${s.flows.length}" failures="${s.flows.filter(f => !f.passed).length}">`,
|
|
72
|
+
...s.flows.map(f => (f.passed ? ` <testcase classname="${xml(s.name)}" name="${xml(f.name)}"/>`
|
|
73
|
+
: ` <testcase classname="${xml(s.name)}" name="${xml(f.name)}"><failure message="${xml(f.why || 'failed')}"/></testcase>`)),
|
|
74
|
+
' </testsuite>',
|
|
75
|
+
]),
|
|
76
|
+
'</testsuites>', '',
|
|
77
|
+
].join('\n'));
|
|
78
|
+
console.log(`${headline}: ${path.join(dir, 'report.md')}`);
|