agentic-mobile-kit 0.7.16 → 0.7.18
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/bin/cli.js +1 -1
- package/lib/init.js +122 -20
- package/package.json +1 -1
- package/stacks/react-native/expo/.agents/skills/THIRD_PARTY.md +1 -1
- package/stacks/react-native/expo/AGENTS.md +6 -3
- package/stacks/react-native/expo/docs/amk/expo.md +60 -4
- package/stacks/react-native/new-app/ErrorBoundary.tsx +61 -0
- package/stacks/react-native/new-app/error-boundary.tsx +30 -0
- package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +6 -5
- package/stacks/react-native/template/.agents/skills/m-prototype/SKILL.md +4 -3
- package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +10 -6
- package/stacks/react-native/template/.github/workflows/e2e.yml +3 -0
- package/stacks/react-native/template/.rulesync/subagents/m-device-checker.md +2 -2
- package/stacks/react-native/template/.rulesync/subagents/m-reviewer.md +3 -3
- package/stacks/react-native/template/AGENTS.md +5 -2
- package/stacks/react-native/template/docs/amk/react-native.md +58 -3
- package/stacks/react-native/template/scripts/amk/a11y.js +78 -0
- package/stacks/react-native/template/scripts/amk/release-check.js +149 -2
- package/stacks/react-native/template/scripts/amk/report.js +78 -0
- package/stacks/react-native/template/scripts/amk/rn-check.js +435 -0
- package/stacks/react-native/template/scripts/amk/verify.sh +139 -15
- package/stacks/react-native/template/specs/_templates/design.md +16 -0
- package/stacks/react-native/template/specs/_templates/flow.yaml +8 -0
- package/stacks/react-native/template/specs/_templates/subflow.yaml +36 -0
package/bin/cli.js
CHANGED
|
@@ -50,7 +50,7 @@ function main([cmd, ...rest]) {
|
|
|
50
50
|
printSummary(init(process.cwd(), { tools: list('tools'), ci: list('ci'), pm: flag('pm') }));
|
|
51
51
|
});
|
|
52
52
|
} else if (cmd === 'sync') {
|
|
53
|
-
run('sync', () => printSync(sync(process.cwd(), { from: flag('from'), ci: list('ci'), pm: flag('pm') })));
|
|
53
|
+
run('sync', () => { if (printSync(sync(process.cwd(), { from: flag('from'), ci: list('ci'), pm: flag('pm') }))) process.exitCode = 1; });
|
|
54
54
|
} else if (cmd === 'uninstall') {
|
|
55
55
|
run('uninstall', () => printUninstall(uninstall(process.cwd(), { from: flag('from'), pm: flag('pm') })));
|
|
56
56
|
} else if (cmd === 'doctor') {
|
package/lib/init.js
CHANGED
|
@@ -173,7 +173,7 @@ function createApp(cwd, kind, { run = tool, log = console.log, pods = process.pl
|
|
|
173
173
|
// the tools commit only in a repository they create; init needs everything committed
|
|
174
174
|
commit(own ? 'Initial commit' : 'Add the files that were already in the folder');
|
|
175
175
|
newAppDefaults(cwd, kind, { run, log });
|
|
176
|
-
commit('Support tablets and landscape; stricter TypeScript with @/ imports');
|
|
176
|
+
commit('Support tablets and landscape; stricter TypeScript with @/ imports; an error boundary');
|
|
177
177
|
// the first pod install changes the Xcode project and Info.plist: a commit of its own keeps that out of the first feature
|
|
178
178
|
if (kind === 'bare' && pods) {
|
|
179
179
|
log('Installing the iOS pods\n');
|
|
@@ -186,8 +186,9 @@ function createApp(cwd, kind, { run = tool, log = console.log, pods = process.pl
|
|
|
186
186
|
}
|
|
187
187
|
|
|
188
188
|
// What a new app starts with beyond the tool's template: iPad and every orientation (the React Native template locks
|
|
189
|
-
// iPhones to portrait; Expo's locks everything to portrait and leaves iPad out),
|
|
190
|
-
// imports for src
|
|
189
|
+
// iPhones to portrait; Expo's locks everything to portrait and leaves iPad out), stricter TypeScript with "@/"
|
|
190
|
+
// imports for src/, and an error boundary around the app (neither template has one, so a render error leaves a blank
|
|
191
|
+
// screen). Expo's template has the "@/" paths already, and Metro reads them; bare apps need a Babel plugin.
|
|
191
192
|
const STRICTER = { noUncheckedIndexedAccess: true, noImplicitOverride: true, noImplicitReturns: true, noFallthroughCasesInSwitch: true };
|
|
192
193
|
const ALIAS_PLUGIN = 'babel-plugin-module-resolver@5';
|
|
193
194
|
const ADD_DEV = { npm: ['npm', 'install', '--save-dev'], Yarn: ['yarn', 'add', '--dev'], pnpm: ['pnpm', 'add', '--save-dev'], Bun: ['bun', 'add', '--dev'] };
|
|
@@ -197,6 +198,7 @@ function newAppDefaults(cwd, kind, { run, log }) {
|
|
|
197
198
|
const next = text === null ? null : change(text);
|
|
198
199
|
if (next !== null && next !== text) fs.writeFileSync(path.join(cwd, rel), next);
|
|
199
200
|
};
|
|
201
|
+
errorBoundary(cwd, kind, edit, log);
|
|
200
202
|
const json = text => { try { return JSON.parse(text); } catch { return null; } };
|
|
201
203
|
// short lists stay on one line, as the templates write them
|
|
202
204
|
const format = j => `${JSON.stringify(j, null, 2).replace(/\[\n\s*([^[\]{}]*?)\n\s*\]/g, (m, items) => `[${items.split(/,\n\s*/).join(', ')}]`)}\n`;
|
|
@@ -245,6 +247,45 @@ function newAppDefaults(cwd, kind, { run, log }) {
|
|
|
245
247
|
edit('tsconfig.json', stricter(alias));
|
|
246
248
|
}
|
|
247
249
|
|
|
250
|
+
// the error boundary: the component next to the app's others, used by the root layout (Expo Router shows an
|
|
251
|
+
// ErrorBoundary that a route exports) or around the root component index.js registers. Relative imports, which work
|
|
252
|
+
// whether or not the "@/" alias is set up
|
|
253
|
+
const NEW_APP_FILES = path.join(TEMPLATE, '..', 'new-app');
|
|
254
|
+
function errorBoundary(cwd, kind, edit, log) {
|
|
255
|
+
const place = (rel, source) => {
|
|
256
|
+
if (fs.existsSync(path.join(cwd, rel))) return false;
|
|
257
|
+
fs.mkdirSync(path.dirname(path.join(cwd, rel)), { recursive: true });
|
|
258
|
+
fs.copyFileSync(path.join(NEW_APP_FILES, source), path.join(cwd, rel));
|
|
259
|
+
return true;
|
|
260
|
+
};
|
|
261
|
+
const from = (file, target) => { const r = path.relative(path.dirname(file), target).split(path.sep).join('/'); return r.startsWith('.') ? r : `./${r}`; };
|
|
262
|
+
if (kind === 'expo') {
|
|
263
|
+
const layout = ['src/app/_layout.tsx', 'app/_layout.tsx'].find(f => fs.existsSync(path.join(cwd, f)));
|
|
264
|
+
if (!layout) { log('! No app/_layout.tsx or src/app/_layout.tsx, so no error boundary was added: export an ErrorBoundary from the root layout'); return; }
|
|
265
|
+
if (/\bErrorBoundary\b/.test(readIf(path.join(cwd, layout)))) return;
|
|
266
|
+
const component = `${layout.startsWith('src/') || fs.existsSync(path.join(cwd, 'src')) ? 'src/' : ''}components/error-boundary.tsx`;
|
|
267
|
+
if (!place(component, 'error-boundary.tsx')) { log(`! ${component} is already there, so no error boundary was added`); return; }
|
|
268
|
+
const line = `export { ErrorBoundary } from '${from(layout, component.replace(/\.tsx$/, ''))}';`;
|
|
269
|
+
// after the last import, which may span lines
|
|
270
|
+
edit(layout, text => {
|
|
271
|
+
const imports = [...text.matchAll(/^import\b[^;]*?(?:from\s*)?['"][^'"]+['"];?[ \t]*$/gm)];
|
|
272
|
+
const at = imports.length ? imports[imports.length - 1].index + imports[imports.length - 1][0].length : 0;
|
|
273
|
+
return at ? `${text.slice(0, at)}\n${line}${text.slice(at)}` : `${line}\n${text}`;
|
|
274
|
+
});
|
|
275
|
+
return;
|
|
276
|
+
}
|
|
277
|
+
const index = readIf(path.join(cwd, 'index.js'));
|
|
278
|
+
const register = /AppRegistry\.registerComponent\(\s*appName\s*,\s*\(\)\s*=>\s*App\s*\)/;
|
|
279
|
+
if (!index || !register.test(index) || !/^import App from '\.\/App';$/m.test(index)) {
|
|
280
|
+
log('! index.js doesn\'t register App the usual way, so no error boundary was added: wrap the app in one');
|
|
281
|
+
return;
|
|
282
|
+
}
|
|
283
|
+
if (!place('src/components/ErrorBoundary.tsx', 'ErrorBoundary.tsx')) { log('! src/components/ErrorBoundary.tsx is already there, so no error boundary was added'); return; }
|
|
284
|
+
edit('index.js', text => text
|
|
285
|
+
.replace(/^import App from '\.\/App';$/m, "import App from './App';\nimport { withErrorBoundary } from './src/components/ErrorBoundary';")
|
|
286
|
+
.replace(register, 'AppRegistry.registerComponent(appName, () => withErrorBoundary(App))'));
|
|
287
|
+
}
|
|
288
|
+
|
|
248
289
|
// Expo apps whose ios/ and android/ come from `expo prebuild` (Continuous Native Generation, not in git) get the
|
|
249
290
|
// Expo overlay. Expo apps that keep the native folders in git are set up like bare apps.
|
|
250
291
|
function detectStack(cwd, deps) {
|
|
@@ -252,11 +293,14 @@ function detectStack(cwd, deps) {
|
|
|
252
293
|
}
|
|
253
294
|
|
|
254
295
|
// a stack's files, rel -> source: the template, and for Expo the overlay next to it, which replaces or adds files
|
|
296
|
+
// deps, when given, are the app's: an app on Expo Router doesn't get the react-navigation skill, as from SDK 56 it imports
|
|
297
|
+
// navigation from expo-router, which its own skill teaches (one on React Navigation itself still needs it)
|
|
255
298
|
const EXPO_LEAVES_OUT = ['docs/amk/react-native.md', '.agents/skills/upgrading-react-native/'];
|
|
256
|
-
function stackFiles(template, stack) {
|
|
299
|
+
function stackFiles(template, stack, deps = {}) {
|
|
257
300
|
const files = new Map(templateFiles(template).map(rel => [rel, path.join(template, rel)]));
|
|
258
301
|
if (stack !== 'expo') return files;
|
|
259
|
-
|
|
302
|
+
const out = [...EXPO_LEAVES_OUT, ...(deps['expo-router'] ? ['.agents/skills/react-navigation/'] : [])];
|
|
303
|
+
for (const rel of files.keys()) if (out.some(f => (f.endsWith('/') ? rel.startsWith(f) : rel === f))) files.delete(rel);
|
|
260
304
|
const overlay = path.join(template, '..', 'expo');
|
|
261
305
|
if (fs.existsSync(overlay)) for (const rel of templateFiles(overlay)) files.set(rel, path.join(overlay, rel));
|
|
262
306
|
return files;
|
|
@@ -426,6 +470,34 @@ function merge3(current, base, kitNew, from) {
|
|
|
426
470
|
return { text: r.stdout, conflicts: r.status };
|
|
427
471
|
}
|
|
428
472
|
|
|
473
|
+
// AGENTS.md's kit section as the team left it, merged with the kit's new one: a team's edit inside it (the screens it
|
|
474
|
+
// builds for, say) stays. A line the kit fills in with what it finds (the versions, the package manager, the app's
|
|
475
|
+
// checks) is the kit's, whatever it says now: there the old version's line, filled in today, stands in for the team's.
|
|
476
|
+
// The screens are a team's decision, so a line with them counts as an edit. The marker lines are the kit's
|
|
477
|
+
function mergeSection(mine, rawOld, kitOld, kitNew, from) {
|
|
478
|
+
const lines = s => s.replace(/\n$/, '').split('\n');
|
|
479
|
+
const [raw, base, theirs] = [rawOld, kitOld, kitNew].map(lines);
|
|
480
|
+
const found = raw.length !== base.length ? [] : raw.map((l, i) => /\{\{\w+\}\}/.test(l) && !l.includes('{{SCREENS}}')
|
|
481
|
+
&& [new RegExp(`^${l.split(/\{\{\w+\}\}/).map(s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`), base[i]]).filter(Boolean);
|
|
482
|
+
const ours = lines(mine).map(l => (base.includes(l) ? l : (found.find(([re]) => re.test(l)) || [null, l])[1]));
|
|
483
|
+
const inner = a => `${a.slice(1, -1).join('\n')}\n`;
|
|
484
|
+
const { text, conflicts } = merge3(inner(ours), inner(base), inner(theirs), from);
|
|
485
|
+
return { text: !conflicts && text === inner(theirs) ? kitNew : `${theirs[0]}\n${text}${theirs[theirs.length - 1]}\n`, conflicts };
|
|
486
|
+
}
|
|
487
|
+
|
|
488
|
+
// whether a merged script still parses (two edits can merge cleanly into one that doesn't): sh -n for shell scripts
|
|
489
|
+
// and git hooks, node --check for JavaScript. Without sh on the PATH (Windows without Git's), shell isn't checked
|
|
490
|
+
function parses(rel, text) {
|
|
491
|
+
const shell = rel.endsWith('.sh') || rel.startsWith('.githooks/');
|
|
492
|
+
if (!shell && !/\.[cm]?js$/.test(rel)) return true;
|
|
493
|
+
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amk-parse-'));
|
|
494
|
+
const file = path.join(dir, path.basename(rel));
|
|
495
|
+
fs.writeFileSync(file, text);
|
|
496
|
+
const r = spawnSync(shell ? 'sh' : process.execPath, [shell ? '-n' : '--check', file], { encoding: 'utf8' });
|
|
497
|
+
fs.rmSync(dir, { recursive: true, force: true });
|
|
498
|
+
return Boolean(r.error) || r.status === 0;
|
|
499
|
+
}
|
|
500
|
+
|
|
429
501
|
// Git hook managers a project may already use. The kit's hooks then run from theirs and core.hooksPath stays theirs:
|
|
430
502
|
// two tools setting it undo each other on every install (husky's prepare script runs after the kit's postinstall).
|
|
431
503
|
const KIT_HOOKS = ['pre-commit', 'pre-push'];
|
|
@@ -445,7 +517,10 @@ const forwarder = h => `#!/bin/sh\n${FORWARD} .git/hooks/${h}, which core.hooksP
|
|
|
445
517
|
const localHooksPath = cwd => {
|
|
446
518
|
let v = '';
|
|
447
519
|
try { v = git(cwd, 'config', '--local', 'core.hooksPath'); } catch {}
|
|
448
|
-
|
|
520
|
+
v = v && path.posix.normalize(v.replace(/\\/g, '/')).replace(/\/+$/, '');
|
|
521
|
+
// the project's own .githooks as a full path (git config core.hooksPath "$PWD/.githooks") is the kit's folder too
|
|
522
|
+
const real = p => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
|
|
523
|
+
return v && path.isAbsolute(v) && real(v) === real(path.join(cwd, '.githooks')) ? '.githooks' : v;
|
|
449
524
|
};
|
|
450
525
|
|
|
451
526
|
function hookManager(cwd, pkg) {
|
|
@@ -618,10 +693,11 @@ function finish(cwd, { pkg, deps, tools, files, stack, skipGenerate }) {
|
|
|
618
693
|
const gi = path.join(cwd, '.gitignore');
|
|
619
694
|
const giText = readIf(gi) || '';
|
|
620
695
|
// Expo: ios/ and android/ are generated by prebuild, so they stay out of git too
|
|
621
|
-
|
|
696
|
+
// .maestro/.amk-*: the copies of flows with view-tree steps that verify.sh runs on Android, there only while they run
|
|
697
|
+
const ignored = ['.env', '.env.*', '!.env*.example', '!.env*.sample', '!.env*.template', '.amk/', '.maestro/.amk-*', ...(stack === 'expo' ? ['/ios', '/android'] : [])];
|
|
622
698
|
const missing = ignored.filter(l => !giText.split('\n').includes(l));
|
|
623
699
|
if (missing.length) {
|
|
624
|
-
fs.writeFileSync(gi, `${giText.replace(/\n*$/, giText ? '\n' : '')}\n# agentic-mobile-kit: secrets stay out of git; .amk/ holds local evidence (screenshots, logs)${stack === 'expo' ? '; ios/ and android/ are generated' : ''}\n${missing.join('\n')}\n`);
|
|
700
|
+
fs.writeFileSync(gi, `${giText.replace(/\n*$/, giText ? '\n' : '')}\n# agentic-mobile-kit: secrets stay out of git; .amk/ holds local evidence (screenshots, logs), .maestro/.amk-* the flows verify.sh is running${stack === 'expo' ? '; ios/ and android/ are generated' : ''}\n${missing.join('\n')}\n`);
|
|
625
701
|
done.merged.push('.gitignore');
|
|
626
702
|
}
|
|
627
703
|
|
|
@@ -747,7 +823,7 @@ function init(cwd, opts = {}) {
|
|
|
747
823
|
const pm = detectPm(cwd, opts.pm);
|
|
748
824
|
const tools = opts.tools || TESTED;
|
|
749
825
|
for (const t of tools) if (!TOOLS[t]) throw new InitError(`Unknown tool "${t}". Choose from: ${Object.keys(TOOLS).join(', ')}.`);
|
|
750
|
-
const files = stackFiles(opts.template || TEMPLATE, stack);
|
|
826
|
+
const files = stackFiles(opts.template || TEMPLATE, stack, deps);
|
|
751
827
|
const ci = chooseCi(cwd, readIf(path.join(cwd, 'AGENTS.md')), opts.ci);
|
|
752
828
|
const values = projectValues(cwd, pkg, deps, pm, ci, stack);
|
|
753
829
|
const targets = tools.flatMap(t => TOOLS[t]);
|
|
@@ -790,10 +866,11 @@ function sync(cwd, opts = {}) {
|
|
|
790
866
|
const oldValues = { ...values, ...ciTexts(hadCi) };
|
|
791
867
|
const tools = installedTools(cwd);
|
|
792
868
|
const targets = tools.flatMap(t => TOOLS[t]);
|
|
793
|
-
const report = { moved: [], updated: [], added: [], merged: [], conflicts: [], removed: [], kept: [] };
|
|
794
|
-
const newFiles = stackFiles(opts.template || TEMPLATE, stack);
|
|
869
|
+
const report = { moved: [], updated: [], added: [], merged: [], conflicts: [], byHand: [], removed: [], kept: [] };
|
|
870
|
+
const newFiles = stackFiles(opts.template || TEMPLATE, stack, deps);
|
|
795
871
|
// an install from before 0.7.0: the kit's files move to the new folders first, so the team's edits come along.
|
|
796
872
|
// Other files in the old folders may be the app's own, so they stay where they are.
|
|
873
|
+
// all the old version installed, whatever the app uses now: what this one leaves out goes
|
|
797
874
|
const oldKit = stackFiles(oldDir, stack);
|
|
798
875
|
const moved = [...oldKit.keys()].filter(rel => renamedPath(rel) !== rel
|
|
799
876
|
&& fs.existsSync(path.join(cwd, rel)) && !fs.existsSync(path.join(cwd, renamedPath(rel))));
|
|
@@ -817,8 +894,14 @@ function sync(cwd, opts = {}) {
|
|
|
817
894
|
const kitOld = oldFiles.has(rel) && wasInstalled(rel) ? kitText(oldFiles.get(rel), rel, oldValues, targets) : null;
|
|
818
895
|
const current = projectText(cwd, rel, targets);
|
|
819
896
|
if (rel === 'AGENTS.md' || rel === 'CLAUDE.md') {
|
|
820
|
-
|
|
821
|
-
|
|
897
|
+
// the team's edits inside the kit's section stay, merged like any file's
|
|
898
|
+
const mine = rel === 'AGENTS.md' && exact && kitOld !== null && current !== null && (current.match(MARKERS) || [])[0];
|
|
899
|
+
const { text: section, conflicts } = mine ? mergeSection(mine, fs.readFileSync(oldFiles.get(rel), 'utf8'), kitOld, kitNew, from) : { text: kitNew, conflicts: 0 };
|
|
900
|
+
const next = current === null ? kitNew : rel === 'AGENTS.md' ? mergeAgents(current, section) : mergeClaude(current);
|
|
901
|
+
if (next === current) continue;
|
|
902
|
+
fs.writeFileSync(path.join(cwd, rel), next);
|
|
903
|
+
if (section === kitNew) report.updated.push(rel);
|
|
904
|
+
else (conflicts ? report.conflicts : report.merged).push(`${rel} (your edits inside the kit's section)`);
|
|
822
905
|
continue;
|
|
823
906
|
}
|
|
824
907
|
if (current === null) {
|
|
@@ -834,6 +917,14 @@ function sync(cwd, opts = {}) {
|
|
|
834
917
|
if (kitOld === kitNew || PROJECT_DOCS.includes(rel)) continue;
|
|
835
918
|
// without an exact base, an old unchanged file would look like your edit and be kept: show every difference instead
|
|
836
919
|
const { text, conflicts } = merge3(current, exact ? kitOld : '', kitNew, from);
|
|
920
|
+
// markers, or a merge that no longer parses, would stop a script, a hook, a workflow or a config from working (and
|
|
921
|
+
// every check with it): those get the kit's version, and the team's goes beside it to bring its changes back
|
|
922
|
+
if (!rel.endsWith('.md') && (conflicts || !parses(rel, text))) {
|
|
923
|
+
fs.copyFileSync(path.join(cwd, rel), path.join(cwd, `${rel}.mine`));
|
|
924
|
+
writeKitFile(cwd, rel, kitNew);
|
|
925
|
+
report.byHand.push(rel);
|
|
926
|
+
continue;
|
|
927
|
+
}
|
|
837
928
|
writeKitFile(cwd, rel, text);
|
|
838
929
|
(conflicts ? report.conflicts : report.merged).push(rel);
|
|
839
930
|
}
|
|
@@ -844,6 +935,7 @@ function sync(cwd, opts = {}) {
|
|
|
844
935
|
if (current === null) continue;
|
|
845
936
|
if (current === kitText(src, rel, values, targets)) { fs.unlinkSync(path.join(cwd, rel)); report.removed.push(rel); } else report.kept.push(`${rel} (the kit dropped it; you changed it)`);
|
|
846
937
|
}
|
|
938
|
+
removeEmptyFolders(cwd, report.removed);
|
|
847
939
|
|
|
848
940
|
const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, files: newFiles, stack, skipGenerate: opts.skipGenerate });
|
|
849
941
|
report.added.push(...done.created);
|
|
@@ -870,6 +962,14 @@ function generatedFiles(cwd) {
|
|
|
870
962
|
return out;
|
|
871
963
|
}
|
|
872
964
|
|
|
965
|
+
// the folders that removed files (paths from cwd, maybe followed by " (why)") left empty; rmdir refuses non-empty ones
|
|
966
|
+
function removeEmptyFolders(cwd, removed) {
|
|
967
|
+
const dirs = [...new Set(removed.map(r => path.dirname(r.split(' (')[0])))].sort((a, b) => b.length - a.length);
|
|
968
|
+
for (let d of dirs) {
|
|
969
|
+
for (; d && d !== '.'; d = path.dirname(d)) { try { fs.rmdirSync(path.join(cwd, d)); } catch { break; } }
|
|
970
|
+
}
|
|
971
|
+
}
|
|
972
|
+
|
|
873
973
|
function uninstall(cwd, opts = {}) {
|
|
874
974
|
const { pkg, deps, stack: detected } = checkProject(cwd);
|
|
875
975
|
const agents = readIf(path.join(cwd, 'AGENTS.md'));
|
|
@@ -910,11 +1010,7 @@ function uninstall(cwd, opts = {}) {
|
|
|
910
1010
|
}
|
|
911
1011
|
}
|
|
912
1012
|
for (const h of OTHER_HOOKS) if ((readIf(path.join(cwd, '.githooks', h)) || '').includes(FORWARD)) remove(`.githooks/${h}`);
|
|
913
|
-
|
|
914
|
-
const dirs = [...new Set(report.removed.map(r => path.dirname(r.split(' (')[0])))].sort((a, b) => b.length - a.length);
|
|
915
|
-
for (let d of dirs) {
|
|
916
|
-
for (; d && d !== '.'; d = path.dirname(d)) { try { fs.rmdirSync(path.join(cwd, d)); } catch { break; } }
|
|
917
|
-
}
|
|
1013
|
+
removeEmptyFolders(cwd, report.removed);
|
|
918
1014
|
|
|
919
1015
|
// git hooks: the kit's postinstall, or its lines in the project's hook manager (which would fail once .githooks is gone)
|
|
920
1016
|
const scripts = pkg.scripts || {};
|
|
@@ -964,13 +1060,19 @@ function printSync({ report, warnings = [], from, to, changed, generated, genera
|
|
|
964
1060
|
log(from === to ? `agentic-mobile-kit is already ${to}.` : `agentic-mobile-kit updated from ${from} to ${to}.`);
|
|
965
1061
|
const lines = [
|
|
966
1062
|
['moved to the new folders', report.moved || []], ['updated', report.updated], ['added', report.added], ['removed', report.removed],
|
|
967
|
-
['merged with your changes', report.merged], ['CONFLICTS, resolve the <<<<<<< markers', report.conflicts],
|
|
1063
|
+
['merged with your changes', report.merged], ['CONFLICTS, resolve the <<<<<<< markers', report.conflicts],
|
|
1064
|
+
['CONFLICTS where markers would stop the file from working, so the kit\'s version is in place: bring your changes back from <file>.mine, then delete it', report.byHand || []],
|
|
1065
|
+
['left alone', report.kept],
|
|
968
1066
|
];
|
|
969
1067
|
for (const [label, files] of lines) if (files.length) log(` ${label}: ${files.join(', ')}`);
|
|
970
1068
|
if (!changed) log(' Nothing changed.');
|
|
971
1069
|
for (const w of warnings) log(` ! ${w}`);
|
|
972
1070
|
if (!generated) log(` ! could not generate tool configs; run: npx -y ${RULESYNC} generate\n${generateError.replace(/^/gm, ' ')}`);
|
|
973
|
-
|
|
1071
|
+
// a conflict left is an update not finished: said last, and the command fails
|
|
1072
|
+
const open = report.conflicts.length + (report.byHand || []).length;
|
|
1073
|
+
if (open) log(`\nsync isn't finished: ${open === 1 ? 'a conflict' : `${open} conflicts`} to resolve (above). Then run the checks, and commit.`);
|
|
1074
|
+
else if (changed) log('\nReview it with "git diff", run the checks, then commit on a branch and open a PR.');
|
|
1075
|
+
return open;
|
|
974
1076
|
}
|
|
975
1077
|
|
|
976
1078
|
function printUninstall({ report }, log = console.log) {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agentic-mobile-kit",
|
|
3
|
-
"version": "0.7.
|
|
3
|
+
"version": "0.7.18",
|
|
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",
|
|
@@ -6,6 +6,6 @@
|
|
|
6
6
|
| expo-upgrade | same | same | MIT | Image files left out |
|
|
7
7
|
| expo-module | same | same | MIT | Image files left out |
|
|
8
8
|
| react-native-best-practices | https://github.com/callstackincubator/agent-skills | 61e6e7dfdf3a8ee862254c200d751fcb1fb863dc | MIT (`LICENSE-callstack`) | Image files left out |
|
|
9
|
-
| react-navigation | same | same | MIT | Image files left out |
|
|
9
|
+
| react-navigation | same | same | MIT | Image files left out; not in apps on Expo Router |
|
|
10
10
|
|
|
11
11
|
Updated with `scripts/vendor-skills.sh` in the agentic-mobile-kit repo.
|
|
@@ -20,10 +20,11 @@ This project may also use other AI workflow frameworks (for example Superpowers,
|
|
|
20
20
|
| Add a library (ask first) | `npx expo install <package>`: the version that matches the SDK |
|
|
21
21
|
| Lint, typecheck, test (each skips what the app doesn't have yet) | `sh scripts/amk/pm-run.sh lint`, `sh scripts/amk/pm-run.sh typecheck`, `sh scripts/amk/pm-run.sh test` |
|
|
22
22
|
| Check dependency versions and the app config | `npx expo install --check`, `npx expo-doctor` |
|
|
23
|
-
| Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; 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) |
|
|
23
|
+
| Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; 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
24
|
| 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 and Maestro flow problems in this branch's changed lines (`verify.sh quick` runs it) | `node scripts/amk/rn-check.js` |
|
|
25
26
|
| 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>` |
|
|
26
|
-
| Check a release before tagging it (versions, permission texts, debug leftovers) | `node scripts/amk/release-check.js` |
|
|
27
|
+
| Check a release before tagging it (versions, permission texts, store review rules, debug leftovers) | `node scripts/amk/release-check.js` |
|
|
27
28
|
| Signed release builds (a person runs them: they use the signing keys) | `sh scripts/amk/release-build.sh android`, `sh scripts/amk/release-build.sh ios` |
|
|
28
29
|
|
|
29
30
|
## Definition of done
|
|
@@ -39,16 +40,18 @@ Never say a check passed unless you ran it in this session.
|
|
|
39
40
|
## Rules
|
|
40
41
|
|
|
41
42
|
- Stay inside the task. Ask before touching unrelated files.
|
|
43
|
+
- 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.
|
|
42
44
|
- Ask before adding or upgrading dependencies, and before editing `package.json`, lockfiles, `app.json`, `app.config.*`, `eas.json` or `.github/workflows/`.
|
|
43
45
|
- Never edit `ios/` or `android/`: the next prebuild overwrites them. Native settings go in `app.json` or `app.config.*`, through config plugins; native code goes in an Expo module (`expo-module` skill). Ask before adding a config plugin.
|
|
44
46
|
- Never run `eas build`, `eas submit` or `eas update`: they build, ship or publish with the team's accounts, so a person runs them.
|
|
45
47
|
- Never read, print or commit `.env` files, keystores, signing files or the files `.amk-secrets` lists. Secrets don't belong in this repo.
|
|
46
48
|
- Never use `git commit --no-verify`, `git push --force`, `git reset --hard` or `rm -rf`.
|
|
49
|
+
- 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.
|
|
47
50
|
- After 2 failed attempts at the same fix, stop and report what you found.
|
|
48
51
|
- Chat is not memory: write decisions into the spec or `docs/amk/decisions.md` straight away.
|
|
49
52
|
- Follow `docs/amk/expo.md`. Before fixing a build error, check `docs/amk/known-issues.md`.
|
|
50
53
|
|
|
51
54
|
## Skills
|
|
52
55
|
|
|
53
|
-
`expo-router`, `expo-upgrade`, `expo-module` (from Expo), `react-native-best-practices`, `react-navigation` (from Callstack), in `.agents/skills/`.
|
|
56
|
+
`expo-router`, `expo-upgrade`, `expo-module` (from Expo), `react-native-best-practices`, and in an app on React Navigation without Expo Router, `react-navigation` (from Callstack), in `.agents/skills/`.
|
|
54
57
|
<!-- KIT:END agentic-mobile-kit -->
|
|
@@ -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, or from a bug agents keep making on screens.
|
|
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. `node scripts/amk/rn-check.js`, which `verify.sh quick` runs, checks the lines a branch changes for some of them.
|
|
4
4
|
|
|
5
5
|
## Expo changes with every SDK
|
|
6
6
|
|
|
@@ -14,7 +14,8 @@ Rules for things AI agents commonly get wrong in Expo apps. Each one comes from
|
|
|
14
14
|
- `ios/` and `android/` are generated by `npx expo prebuild` and aren't in git. Never edit them: the next prebuild overwrites the change.
|
|
15
15
|
- Native settings (permissions and their texts, bundle ID, entitlements) go in `app.json` or `app.config.*`. Libraries with native setup bring a config plugin; add it to `plugins`.
|
|
16
16
|
- Native code of the app's own goes in an Expo module (`expo-module` skill), not into the generated folders.
|
|
17
|
-
-
|
|
17
|
+
- Run the app in a development build, not Expo Go: Expo Go can't load native code the app adds, and the store version runs only one SDK. `sh scripts/amk/verify.sh` makes release builds with the current native code.
|
|
18
|
+
- Android release builds shrink the code with R8 (on by default from SDK 58). A crash only in release builds usually means a missing keep rule: add the rule; don't turn R8 off.
|
|
18
19
|
|
|
19
20
|
## Architecture
|
|
20
21
|
|
|
@@ -29,7 +30,7 @@ Rules for things AI agents commonly get wrong in Expo apps. Each one comes from
|
|
|
29
30
|
- With the keyboard open, the field being typed in and the button that submits the form stay visible and tappable, on both platforms.
|
|
30
31
|
- 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
32
|
- 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
|
|
33
|
+
- 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`.
|
|
33
34
|
- Check every UI change on both iOS and Android; behavior differs (keyboard, insets, fonts, permissions).
|
|
34
35
|
- 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.
|
|
35
36
|
- 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`.
|
|
@@ -43,9 +44,64 @@ Rules for things AI agents commonly get wrong in Expo apps. Each one comes from
|
|
|
43
44
|
- 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
45
|
- 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
46
|
- 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
|
-
-
|
|
47
|
+
- Android ignores orientation and size locks on tablets and foldables (600 dp wide and up) for apps targeting Android 16 (API 36), and from Android 17 (API 37) apps can't opt out. Apple deprecated `UIRequiresFullScreen` with iPadOS 26, so iPad windows resize too, and on iOS 27 `ScreenOrientation.lockAsync` may do nothing. Every screen has to work at any window size and turned, whatever the app's settings say.
|
|
47
48
|
- 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
|
|
|
50
|
+
## Current Expo, React Native and React
|
|
51
|
+
|
|
52
|
+
These changed after most AI training data was written: check them instead of writing from memory.
|
|
53
|
+
|
|
54
|
+
- Navigation (SDK 56 and later): import from Expo Router's own entry points, such as `expo-router/react-navigation`, never from `@react-navigation/*`, which no longer works alongside it (`expo-router` skill; the `expo-upgrade` skill's codemod moves old imports).
|
|
55
|
+
- `expo-av` isn't maintained any more: use `expo-audio` and `expo-video`. `@expo/vector-icons` is deprecated from SDK 56: use `@react-native-vector-icons/*`. In `expo-file-system`, `File` and `Directory`'s `copy` and `move` (SDK 56) and `File.write` (SDK 58) are async; the `…Sync` versions aren't.
|
|
56
|
+
- iOS: from SDK 58, prebuild generates `SceneDelegate.swift`, as apps built with Xcode 27 don't launch without the UIScene life cycle. Config plugins that change the app delegate's window or URL handling have to change the scene delegate instead.
|
|
57
|
+
- Removed from React Native: `InteractionManager` (0.87; use `requestIdleCallback`), the `StatusBar` props `backgroundColor` and `translucent` (0.87), `Modal`'s `animated` (0.87; `animationType`), a boolean `keyboardShouldPersistTaps` (0.87; `"handled"`) and `StyleSheet.absoluteFillObject` (0.85; `StyleSheet.absoluteFill`).
|
|
58
|
+
- Deprecated, so not in new code: `ImageBackground` (a `View` with an absolutely positioned image), `InputAccessoryView` (`KeyboardStickyView` from `react-native-keyboard-controller`) and `AccessibilityInfo.setAccessibilityFocus` (`sendAccessibilityEvent`).
|
|
59
|
+
- Import from `react-native` itself. `react-native/Libraries/…` is private, and a type error from React Native 0.87; don't add the `react-native-legacy-deep-imports` opt-out to hide it.
|
|
60
|
+
- React 19: pass `ref` as a prop instead of `forwardRef`, render `<SomeContext value={…}>` instead of `<SomeContext.Provider>`, and use `useEffectEvent` (19.2) instead of turning off `react-hooks/exhaustive-deps`.
|
|
61
|
+
- With the React Compiler on (`experiments.reactCompiler` in `app.json`), it memoizes: don't add `memo`, `useMemo` or `useCallback` to new code, and don't remove the ones there as a side task.
|
|
62
|
+
- Android: Google Play takes only apps targeting Android 16 (API 36) or higher (from 31 August 2026). Don't lower the target SDK to get out of edge to edge, back handling or orientation changes.
|
|
63
|
+
|
|
64
|
+
## Errors, storage and effects
|
|
65
|
+
|
|
66
|
+
- Wrap the app in an error boundary, so a render error shows a screen to recover from instead of a blank or closed app: export an `ErrorBoundary` from the root layout (Expo Router), or use the crash reporter's.
|
|
67
|
+
- Every failure reaches the user or the crash reporter: no empty `catch`, and an action started from a button catches its error and shows it, with a way to retry, so a spinner never stays up.
|
|
68
|
+
- Tokens, passwords and keys go in `expo-secure-store`, never in AsyncStorage or other plain storage. Anything in the JavaScript bundle, `EXPO_PUBLIC_` variables included, can be read by anyone who has the app: no secret keys there.
|
|
69
|
+
- Session replay and analytics mask what users type, and logs leave out tokens and personal data.
|
|
70
|
+
- Effects clean up what they start: timers (`clearTimeout`, `clearInterval`), listeners and subscriptions (return their `remove`), and async work that can finish after the screen closes (an `AbortController`, or a flag the cleanup sets).
|
|
71
|
+
- List keys come from the item's ID, not its index: index keys mix up rows when items are added, removed or reordered.
|
|
72
|
+
- Images go in asset files, never in code as base64 strings: they bloat the bundle, and all of it loads with the JavaScript.
|
|
73
|
+
- 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.
|
|
74
|
+
|
|
75
|
+
## Platform guidelines and accessibility
|
|
76
|
+
|
|
77
|
+
From Apple's Human Interface Guidelines, Android's design and app quality guidelines, and WCAG 2.2.
|
|
78
|
+
|
|
79
|
+
- Touch targets: every button, link and control is at least 44×44 points on iOS and 48×48 dp on Android (`minWidth`/`minHeight: 48` covers both): pad a small icon instead of sizing the button to it. `hitSlop` doesn't reach past the parent's bounds, so use it only where the layout can't grow.
|
|
80
|
+
- Text: no `fontSize` under 11, and don't cap scaling below 2× (`maxFontSizeMultiplier`, or `Text.defaultProps`).
|
|
81
|
+
- Contrast, in both light and dark: text 4.5:1 against its background (3:1 from 18 points, or 14 bold), and input borders, focus rings and icons that carry meaning 3:1. Colors come from the theme, whose pairs are checked once; a grey like `#999` on white is only 2.8:1.
|
|
82
|
+
- Screen readers: controls show their state in `accessibilityState` (`checked`, `selected`, `expanded`, `disabled`), and screen and section titles have `accessibilityRole="header"`. A label names the action ("Delete photo"), without the role ("button") the reader already says. Put `accessible` on a row that reads as one item, never on one that holds its own buttons. Meaningful images get a label; decorative ones need nothing.
|
|
83
|
+
- Every swipe, drag or long-press action also has a visible button or menu item, and is in `accessibilityActions`. Color is never the only signal: an error shows text, and a state adds an icon or a word.
|
|
84
|
+
- Back: keep swipe back on iOS and the system back on Android. To ask before leaving unsaved changes, use `usePreventRemove` (from `expo-router/react-navigation`), not `gestureEnabled: false`. A `hardwareBackPress` listener returns `true` only while it closes something on screen; apps don't quit themselves (`BackHandler.exitApp`). Every `Modal` has `onRequestClose`, which Android's back button calls; forms open as sheets (a route with `presentation: 'formSheet'`, or `presentationStyle="pageSheet"`).
|
|
85
|
+
- Permissions: ask when the user starts the feature that needs it, never at launch or when a screen opens; first say in the app why. When it's denied, say what's unavailable and keep the rest working. When the system won't ask again (`canAskAgain` is false), the feature's button explains that and offers `Linking.openSettings()`. Ask for notifications after an action they serve, not on launch; on Android 13 and later, `expo-notifications` shows the prompt only once a notification channel exists, so create it first.
|
|
86
|
+
- Use the native controls (`@react-native-community/datetimepicker`, `Alert.alert` with verb buttons and `style: 'destructive'` and `'cancel'`, `Switch`); a custom one gets the same role, state and size.
|
|
87
|
+
- Dark mode: `userInterfaceStyle: "automatic"` in `app.json` (Android also needs `expo-system-ui`), and colors from the theme's light and dark values (`useColorScheme()`), not hex values in components; don't lock the app to light.
|
|
88
|
+
- 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.
|
|
89
|
+
- 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.
|
|
90
|
+
- iOS 26: use native headers and tab bars (Expo Router's `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.
|
|
91
|
+
- Haptics only for success, error or a selection, never as the only feedback, with `expo-haptics`; not `Vibration.vibrate`.
|
|
92
|
+
|
|
93
|
+
## Store review
|
|
94
|
+
|
|
95
|
+
What App Store review and Google Play reject. `node scripts/amk/release-check.js` checks the app config for some of it.
|
|
96
|
+
|
|
97
|
+
- Apps where people can create an account let them start deleting it in the app: a full deletion, not deactivation; a direct link to a web page that finishes it is fine (Apple 5.1.1(v)). Google Play also needs that web link in the Data safety form.
|
|
98
|
+
- A third-party or social login (Google, Facebook) as the main sign-in also needs an equivalent private one, usually Sign in with Apple (`expo-apple-authentication`, 4.8); an app that signs in only with the company's own accounts doesn't.
|
|
99
|
+
- Digital content and subscriptions are sold with in-app purchase (3.1.1); physical goods and services aren't. Links to buy elsewhere follow the storefront's current rules.
|
|
100
|
+
- Permission texts (in each library's plugin options, or `ios.infoPlist`) say what the app does with the data and why, for each use; ask only for what the app uses.
|
|
101
|
+
- The privacy manifest (`ios.privacyManifests` in `app.json`) and App Store Connect's privacy details list the data the app and its SDKs collect (analytics, crash reporting, session replay). Tracking needs the App Tracking Transparency prompt first (`expo-tracking-transparency`).
|
|
102
|
+
- Google Play restricts these permissions to apps whose core feature needs them, with a declaration in Play Console: photos and videos (`READ_MEDIA_IMAGES`, `READ_MEDIA_VIDEO`: others use the Android photo picker), `QUERY_ALL_PACKAGES`, `MANAGE_EXTERNAL_STORAGE`, SMS and call log, `USE_EXACT_ALARM`, and background location (also a video and an in-app disclosure first). A library can add one: list it in `android.blockedPermissions` when the app doesn't need it.
|
|
103
|
+
- Android foreground services declare their type and its `FOREGROUND_SERVICE_<TYPE>` permission (the library's config plugin usually does), and each type is declared in Play Console.
|
|
104
|
+
|
|
49
105
|
## TypeScript
|
|
50
106
|
|
|
51
107
|
- Keep the checks `tsconfig.json` has. Don't loosen them, or get past one with `any`, `@ts-ignore` or a non-null `!`.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
// The app's error boundary. index.js registers withErrorBoundary(App), so a render error anywhere in the app shows this
|
|
2
|
+
// screen, with a way to try again, instead of a blank screen or a closed app. Once the app has a crash reporter, report
|
|
3
|
+
// the error in componentDidCatch (or use the reporter's own boundary).
|
|
4
|
+
import React from 'react';
|
|
5
|
+
import { Pressable, StyleSheet, Text, useColorScheme, View } from 'react-native';
|
|
6
|
+
|
|
7
|
+
type Props = { children: React.ReactNode };
|
|
8
|
+
type State = { error: Error | null };
|
|
9
|
+
|
|
10
|
+
export class ErrorBoundary extends React.Component<Props, State> {
|
|
11
|
+
override state: State = { error: null };
|
|
12
|
+
|
|
13
|
+
static getDerivedStateFromError(error: Error): State {
|
|
14
|
+
return { error };
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
override componentDidCatch(error: Error, info: React.ErrorInfo) {
|
|
18
|
+
console.error(error, info.componentStack);
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
override render() {
|
|
22
|
+
if (!this.state.error) return this.props.children;
|
|
23
|
+
return <Fallback error={this.state.error} retry={() => this.setState({ error: null })} />;
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function Fallback({ error, retry }: { error: Error; retry: () => void }) {
|
|
28
|
+
const dark = useColorScheme() === 'dark';
|
|
29
|
+
return (
|
|
30
|
+
<View style={[styles.screen, dark && styles.screenDark]} accessibilityLiveRegion="assertive">
|
|
31
|
+
<Text style={[styles.title, dark && styles.textDark]} accessibilityRole="header">
|
|
32
|
+
Something went wrong
|
|
33
|
+
</Text>
|
|
34
|
+
{__DEV__ ? <Text style={[styles.detail, dark && styles.textDark]}>{error.message}</Text> : null}
|
|
35
|
+
<Pressable onPress={retry} style={styles.button} accessibilityRole="button" accessibilityLabel="Try again" testID="error-try-again">
|
|
36
|
+
<Text style={styles.buttonText}>Try again</Text>
|
|
37
|
+
</Pressable>
|
|
38
|
+
</View>
|
|
39
|
+
);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
// the app's root component inside the boundary
|
|
43
|
+
export function withErrorBoundary<P extends object>(Component: React.ComponentType<P>) {
|
|
44
|
+
return function WithErrorBoundary(props: P) {
|
|
45
|
+
return (
|
|
46
|
+
<ErrorBoundary>
|
|
47
|
+
<Component {...props} />
|
|
48
|
+
</ErrorBoundary>
|
|
49
|
+
);
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
const styles = StyleSheet.create({
|
|
54
|
+
screen: { flex: 1, alignItems: 'center', justifyContent: 'center', padding: 24, gap: 16, backgroundColor: '#fff' },
|
|
55
|
+
screenDark: { backgroundColor: '#000' },
|
|
56
|
+
title: { fontSize: 20, fontWeight: '600', textAlign: 'center', color: '#000' },
|
|
57
|
+
detail: { fontSize: 14, textAlign: 'center', color: '#000' },
|
|
58
|
+
textDark: { color: '#fff' },
|
|
59
|
+
button: { paddingVertical: 12, paddingHorizontal: 24, borderRadius: 8, backgroundColor: '#007AFF' },
|
|
60
|
+
buttonText: { fontSize: 16, fontWeight: '600', color: '#fff' },
|
|
61
|
+
});
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
// The app's error boundary. The root layout exports it, so Expo Router shows it, with a way to try again, when a screen
|
|
2
|
+
// throws while rendering, instead of a blank screen or a closed app. A route can export its own ErrorBoundary for its
|
|
3
|
+
// screens. Once the app has a crash reporter, report the error here.
|
|
4
|
+
import { type ErrorBoundaryProps } from 'expo-router';
|
|
5
|
+
import { Pressable, StyleSheet, Text, useColorScheme, View } from 'react-native';
|
|
6
|
+
|
|
7
|
+
export function ErrorBoundary({ error, retry }: ErrorBoundaryProps) {
|
|
8
|
+
const dark = useColorScheme() === 'dark';
|
|
9
|
+
return (
|
|
10
|
+
<View style={[styles.screen, dark && styles.screenDark]} accessibilityLiveRegion="assertive">
|
|
11
|
+
<Text style={[styles.title, dark && styles.textDark]} accessibilityRole="header">
|
|
12
|
+
Something went wrong
|
|
13
|
+
</Text>
|
|
14
|
+
{__DEV__ ? <Text style={[styles.detail, dark && styles.textDark]}>{error.message}</Text> : null}
|
|
15
|
+
<Pressable onPress={retry} style={styles.button} accessibilityRole="button" accessibilityLabel="Try again" testID="error-try-again">
|
|
16
|
+
<Text style={styles.buttonText}>Try again</Text>
|
|
17
|
+
</Pressable>
|
|
18
|
+
</View>
|
|
19
|
+
);
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
const styles = StyleSheet.create({
|
|
23
|
+
screen: { flex: 1, alignItems: 'center', justifyContent: 'center', padding: 24, gap: 16, backgroundColor: '#fff' },
|
|
24
|
+
screenDark: { backgroundColor: '#000' },
|
|
25
|
+
title: { fontSize: 20, fontWeight: '600', textAlign: 'center', color: '#000' },
|
|
26
|
+
detail: { fontSize: 14, textAlign: 'center', color: '#000' },
|
|
27
|
+
textDark: { color: '#fff' },
|
|
28
|
+
button: { paddingVertical: 12, paddingHorizontal: 24, borderRadius: 8, backgroundColor: '#007AFF' },
|
|
29
|
+
buttonText: { fontSize: 16, fontWeight: '600', color: '#fff' },
|
|
30
|
+
});
|
|
@@ -35,17 +35,18 @@ If the input describes a bug rather than new behavior, suggest `m-bugfix` and st
|
|
|
35
35
|
|
|
36
36
|
## 3. Design and tasks (then stop for approval)
|
|
37
37
|
|
|
38
|
-
1. **
|
|
39
|
-
2.
|
|
40
|
-
3. Fill `
|
|
41
|
-
4.
|
|
38
|
+
1. **Ask for the UI/UX level first, when the feature has screens.** As one question, ask which level its screens should have: Simple (clean, minimal and functional), Mixed (simple, with modern touches) or Premium (polished, following current design trends; it takes longer). `specs/_templates/design.md` describes each. Offer as the default the level a prototype settled (under `## Decisions` in `requirements.md`), otherwise the one the app's other screens have (an earlier spec's `design.md`), otherwise Simple. Don't design until the user has answered. Write the answer and the date under "UI/UX level" in `design.md` (n/a for a feature without screens).
|
|
39
|
+
2. **Search the codebase before designing.** List the components, hooks, API clients and helpers you'll reuse in `design.md` under "Existing code to reuse". Read `docs/amk/structure.md` and `docs/amk/conventions.md`.
|
|
40
|
+
3. Fill `design.md`: approach, files to change, risks (native changes, pod install, migrations).
|
|
41
|
+
4. Fill `tasks.md`: small tasks (about an hour, under ~300 changed lines each). Each task names the requirement it serves and how it's checked, and its tests are written in the same task, not left for the end. The last task writes `.maestro/<id>.yaml` (from `specs/_templates/flow.yaml`): a Maestro flow with a `# Scenario <n>: <name>` comment above each scenario's steps, an assertion for its THEN and a screenshot, tapping elements by `testID` and scrolling to the ones further down a screen first (`scrollUntilVisible`): turned screens are short.
|
|
42
|
+
5. Show design and tasks and **stop until the user approves them**. Ask them to check that every task serves an approved requirement and nothing goes beyond the agreed scope.
|
|
42
43
|
|
|
43
44
|
From here the plan lives in files, so the building can also run in a fresh session or another tool with `m-continue <id>`.
|
|
44
45
|
|
|
45
46
|
## 4. Build, one task at a time
|
|
46
47
|
|
|
47
48
|
For each task:
|
|
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
|
+
1. Implement only that task. Write tests first for logic (state, data, utils); UI can be tested after. Build screens to the UI/UX level in `design.md`, and 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
50
|
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
51
|
3. Commit with a clear message ending in `Spec: specs/<id>`.
|
|
51
52
|
4. Tick the task in `tasks.md` and update the handoff block and log in `progress.md`.
|
|
@@ -16,9 +16,10 @@ A prototype answers questions before the real build: what the client wants, how
|
|
|
16
16
|
|
|
17
17
|
1. Read the requirement, `docs/amk/product.md`, `structure.md` and `conventions.md`, the living spec for the area in `specs/current/`, and the screens around where this would live: their components, theme and navigation.
|
|
18
18
|
2. Ask who the demo is for (the client or the team) and what it must show, one question at a time.
|
|
19
|
-
3.
|
|
20
|
-
4.
|
|
21
|
-
5.
|
|
19
|
+
3. Ask which UI/UX level the screens should have: Simple (clean, minimal and functional; the default), Mixed (simple, with modern touches) or Premium (polished, following current design trends). `specs/_templates/design.md` describes each; offer the level the app's other screens have, if an earlier spec's `design.md` records one. The concepts and the prototype are made at that level. Don't start them until the user has answered.
|
|
20
|
+
4. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Create the branch `prototype/<id>` from the main branch; this workflow commits everything there.
|
|
21
|
+
5. Write `specs/<id>/requirements.md` from `specs/_templates/requirements.md`: the goal, what's known so far, and the open questions the prototype should answer. Add a `## Decisions` section for what gets settled along the way, starting with the UI/UX level and the date.
|
|
22
|
+
6. Decide which case this is:
|
|
22
23
|
- **What to show is clear** (the screens and the flow are known): go to step 3.
|
|
23
24
|
- **How it should work or look is still open:** go to step 2.
|
|
24
25
|
|