agentic-mobile-kit 0.5.4 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/README.md +6 -1
  2. package/bin/cli.js +1 -1
  3. package/lib/doctor.js +26 -5
  4. package/lib/init.js +235 -49
  5. package/package.json +4 -2
  6. package/stacks/react-native/expo/.agents/skills/LICENSE-expo +21 -0
  7. package/stacks/react-native/expo/.agents/skills/THIRD_PARTY.md +11 -0
  8. package/stacks/react-native/expo/.agents/skills/expo-module/SKILL.md +151 -0
  9. package/stacks/react-native/expo/.agents/skills/expo-module/agents/openai.yaml +4 -0
  10. package/stacks/react-native/expo/.agents/skills/expo-module/references/config-plugin.md +90 -0
  11. package/stacks/react-native/expo/.agents/skills/expo-module/references/create-expo-module.md +206 -0
  12. package/stacks/react-native/expo/.agents/skills/expo-module/references/lifecycle.md +127 -0
  13. package/stacks/react-native/expo/.agents/skills/expo-module/references/module-config.md +48 -0
  14. package/stacks/react-native/expo/.agents/skills/expo-module/references/native-module.md +286 -0
  15. package/stacks/react-native/expo/.agents/skills/expo-module/references/native-view.md +171 -0
  16. package/stacks/react-native/expo/.agents/skills/expo-router/SKILL.md +240 -0
  17. package/stacks/react-native/expo/.agents/skills/expo-router/agents/openai.yaml +4 -0
  18. package/stacks/react-native/expo/.agents/skills/expo-router/references/form-sheet.md +253 -0
  19. package/stacks/react-native/expo/.agents/skills/expo-router/references/route-structure.md +229 -0
  20. package/stacks/react-native/expo/.agents/skills/expo-router/references/search.md +248 -0
  21. package/stacks/react-native/expo/.agents/skills/expo-router/references/tabs.md +433 -0
  22. package/stacks/react-native/expo/.agents/skills/expo-router/references/toolbar-and-headers.md +284 -0
  23. package/stacks/react-native/expo/.agents/skills/expo-router/references/zoom-transitions.md +158 -0
  24. package/stacks/react-native/expo/.agents/skills/expo-upgrade/SKILL.md +150 -0
  25. package/stacks/react-native/expo/.agents/skills/expo-upgrade/agents/openai.yaml +4 -0
  26. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/expo-av-to-audio.md +132 -0
  27. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/expo-av-to-video.md +160 -0
  28. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/native-tabs.md +124 -0
  29. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/new-architecture.md +79 -0
  30. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/react-19.md +79 -0
  31. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/react-compiler.md +59 -0
  32. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/react-navigation-to-expo-router.md +61 -0
  33. package/stacks/react-native/expo/.rulesync/permissions.jsonc +40 -0
  34. package/stacks/react-native/expo/AGENTS.md +52 -0
  35. package/stacks/react-native/expo/docs/ai/expo.md +35 -0
  36. package/stacks/react-native/expo/docs/ai/known-issues.md +32 -0
  37. package/stacks/react-native/template/.agents/skills/m-release/SKILL.md +5 -4
  38. package/stacks/react-native/template/.githooks/pre-commit +7 -2
  39. package/stacks/react-native/template/.github/workflows/e2e.yml +2 -0
  40. package/stacks/react-native/template/.github/workflows/ios.yml +3 -5
  41. package/stacks/react-native/template/AGENTS.md +4 -4
  42. package/stacks/react-native/template/codemagic.yaml +2 -1
  43. package/stacks/react-native/template/docs/ai/known-issues.md +12 -2
  44. package/stacks/react-native/template/docs/ai/react-native.md +5 -4
  45. package/stacks/react-native/template/scripts/ai/android-flavors.js +41 -0
  46. package/stacks/react-native/template/scripts/ai/case-check.js +35 -0
  47. package/stacks/react-native/template/scripts/ai/install-deps.sh +4 -1
  48. package/stacks/react-native/template/scripts/ai/ios-build.sh +10 -3
  49. package/stacks/react-native/template/scripts/ai/pm-run.sh +12 -0
  50. package/stacks/react-native/template/scripts/ai/pod-install.sh +12 -0
  51. package/stacks/react-native/template/scripts/ai/prebuild.sh +28 -0
  52. package/stacks/react-native/template/scripts/ai/release-build.sh +32 -8
  53. package/stacks/react-native/template/scripts/ai/release-check.js +98 -18
  54. package/stacks/react-native/template/scripts/ai/set-version.sh +19 -1
  55. package/stacks/react-native/template/scripts/ai/verify.sh +69 -16
  56. package/stacks/react-native/template/specs/_templates/flow.yaml +9 -0
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # agentic-mobile-kit
2
2
 
3
- One setup for AI-assisted development of bare React Native apps. Every AI tool on the team reads the same rules, project knowledge and workflows. Git hooks and CI check the work, whichever person or tool wrote it. A task started in one tool, or on one machine, carries on in another.
3
+ One setup for AI-assisted development of React Native apps, bare or Expo. Every AI tool on the team reads the same rules, project knowledge and workflows. Git hooks and CI check the work, whichever person or tool wrote it. A task started in one tool, or on one machine, carries on in another.
4
4
 
5
5
  Tested with Claude Code, Codex and Antigravity. `--tools` also sets up Cursor, OpenCode and Kiro.
6
6
 
@@ -43,6 +43,10 @@ Invoke a skill with `/m-feature` in Claude Code and Antigravity, or `$m-feature`
43
43
 
44
44
  Apps that already use Superpowers, BMAD, proAgents or similar keep them as they are. The kit adds its section next to theirs and links its skills into an existing `.claude/skills` folder. A task started with an `m-` skill follows the kit's steps, and everything else keeps working as before.
45
45
 
46
+ ## Expo apps
47
+
48
+ `init` recognizes Expo apps that generate `ios/` and `android/` with `npx expo prebuild`. Agents get Expo's rules and skills, and never edit the generated folders. The kit's scripts generate them before each build, so device checks, release checks and signed builds work as they do in bare apps, with no Expo account. Teams that build with EAS run `eas build` and `eas submit` themselves. Expo apps that keep `ios/` and `android/` in git are set up like bare apps.
49
+
46
50
  ## Update or remove
47
51
 
48
52
  ```sh
@@ -58,6 +62,7 @@ Both need a clean working tree and leave the result for you to review with `git
58
62
  ## Requirements
59
63
 
60
64
  - Git and Node.js 20 or later, on macOS, Windows or Linux. The kit's tests run on all three for every change.
65
+ - The app at the root of its git repository.
61
66
  - Android work needs the Android SDK and Java. iOS work needs a Mac with Xcode and CocoaPods. `doctor` checks the rest.
62
67
  - On Windows, turn on Developer Mode (Settings > System > For developers) and run `git config --global core.symlinks true`. Then `init` can link the Claude Code skills folder, and clones keep the link.
63
68
 
package/bin/cli.js CHANGED
@@ -19,7 +19,7 @@ Usage:
19
19
  npx agentic-mobile-kit doctor
20
20
 
21
21
  Commands:
22
- init Install the kit into a bare React Native project (run in the app's root).
22
+ init Install the kit into a React Native or Expo app (run in the app's root).
23
23
  sync Update the kit's files to this version. Your own changes to them are merged in, not lost.
24
24
  uninstall Remove the kit's files and sections. Files you changed are kept and listed.
25
25
  doctor Check the project and this machine, with a fix for each problem.
package/lib/doctor.js CHANGED
@@ -4,7 +4,7 @@ const fs = require('fs');
4
4
  const os = require('os');
5
5
  const path = require('path');
6
6
  const { spawnSync } = require('child_process');
7
- const { tool } = require('./init');
7
+ const { tool, hookManager, hooksWired } = require('./init');
8
8
 
9
9
  const RULESYNC = 'rulesync@27.0.0';
10
10
 
@@ -40,10 +40,31 @@ function projectChecks(cwd, opts) {
40
40
  ? ok('AGENTS.md size', `${lines} lines`)
41
41
  : warn(`AGENTS.md is ${lines} lines / ${bytes} bytes`, 'keep it under 150 lines and 8 KB; tools truncate or ignore long files. Move details to docs/ai/'));
42
42
 
43
- const hooksPath = run('git', ['config', 'core.hooksPath'], { cwd });
44
- out.push(hooksPath === '.githooks'
45
- ? ok('Git hooks active')
46
- : fail('Git hooks not active on this clone', 'run: git config core.hooksPath .githooks (your package manager\'s install does this too)'));
43
+ let pkg = {};
44
+ try { pkg = JSON.parse(read(cwd, 'package.json') || '{}'); } catch {}
45
+ const manager = hookManager(cwd, pkg);
46
+ if (!manager) {
47
+ const hooksPath = run('git', ['config', 'core.hooksPath'], { cwd });
48
+ out.push(hooksPath === '.githooks'
49
+ ? ok('Git hooks active')
50
+ : fail('Git hooks not active on this clone', 'run: git config core.hooksPath .githooks (your package manager\'s install does this too)'));
51
+ } else if (manager.manual) {
52
+ out.push(warn(`Git hooks run from ${manager.name}, without the kit's checks`, 'add "sh .githooks/pre-commit" and "sh .githooks/pre-push" to those hooks'));
53
+ } else if (!hooksWired(cwd, manager)) {
54
+ out.push(fail(`The kit's checks aren't in your ${manager.name} hooks`, 'run: npx agentic-mobile-kit sync'));
55
+ } else {
56
+ // what git runs: core.hooksPath, or .git/hooks
57
+ const dir = run('git', ['rev-parse', '--git-path', 'hooks'], { cwd });
58
+ out.push(dir && fs.existsSync(path.join(cwd, dir, 'pre-commit'))
59
+ ? ok('Git hooks active', `the kit's checks run from ${manager.name}`)
60
+ : fail(`${manager.name} isn't set up on this clone, so no git hooks run`, 'run your package manager\'s install'));
61
+ }
62
+
63
+ if (fs.existsSync(path.join(cwd, 'scripts/ai/case-check.js'))) {
64
+ const r = spawnSync(process.execPath, ['scripts/ai/case-check.js'], { cwd, encoding: 'utf8' });
65
+ const lines = (r.stderr || '').trim().split('\n');
66
+ out.push(r.status === 0 ? ok('File names match git') : fail(`Renamed only in letter case, and git missed it:${lines.slice(1, -1).join(',')}`, lines.pop()));
67
+ }
47
68
 
48
69
  const tracked = (run('git', ['ls-files'], { cwd }) || '').split('\n').filter(f => /(^|\/)\.env(\.(?!example$)[\w.-]+)?$/.test(f));
49
70
  out.push(tracked.length ? fail(`Secret files tracked by git: ${tracked.join(', ')}`, 'git rm --cached them, rotate the secrets, keep them out of the repo') : ok('No .env files in git'));
package/lib/init.js CHANGED
@@ -91,10 +91,33 @@ function checkProject(cwd) {
91
91
  const pkg = readJson(pkgFile);
92
92
  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
93
93
  if (!deps['react-native']) throw new InitError('This is not a React Native project (no "react-native" dependency).');
94
- if (!fs.existsSync(path.join(cwd, 'ios')) || !fs.existsSync(path.join(cwd, 'android'))) {
95
- throw new InitError('No ios/ and android/ folders found. Only bare React Native projects are supported for now (Expo support comes later).');
94
+ const stack = detectStack(cwd, deps);
95
+ if (stack === 'bare' && (!fs.existsSync(path.join(cwd, 'ios')) || !fs.existsSync(path.join(cwd, 'android')))) {
96
+ throw new InitError('No ios/ and android/ folders found, and this isn\'t an Expo app. The kit supports bare React Native and Expo apps.');
96
97
  }
97
- return { pkg, deps };
98
+ return { pkg, deps, stack };
99
+ }
100
+
101
+ // Expo apps whose ios/ and android/ come from `expo prebuild` (Continuous Native Generation, not in git) get the
102
+ // Expo overlay. Expo apps that keep the native folders in git are set up like bare apps.
103
+ function detectStack(cwd, deps) {
104
+ return deps.expo && !git(cwd, 'ls-files', 'ios', 'android') ? 'expo' : 'bare';
105
+ }
106
+
107
+ // a stack's files, rel -> source: the template, and for Expo the overlay next to it, which replaces or adds files
108
+ const EXPO_LEAVES_OUT = ['docs/ai/react-native.md', '.agents/skills/upgrading-react-native/'];
109
+ function stackFiles(template, stack) {
110
+ const files = new Map(templateFiles(template).map(rel => [rel, path.join(template, rel)]));
111
+ if (stack !== 'expo') return files;
112
+ for (const rel of files.keys()) if (EXPO_LEAVES_OUT.some(f => (f.endsWith('/') ? rel.startsWith(f) : rel === f))) files.delete(rel);
113
+ const overlay = path.join(template, '..', 'expo');
114
+ if (fs.existsSync(overlay)) for (const rel of templateFiles(overlay)) files.set(rel, path.join(overlay, rel));
115
+ return files;
116
+ }
117
+
118
+ // app.json's expo section, for the values the kit fills in (app.config.* would need the Expo CLI to evaluate)
119
+ function expoConfig(cwd) {
120
+ try { return readJson(path.join(cwd, 'app.json')).expo || {}; } catch { return {}; }
98
121
  }
99
122
 
100
123
  // all files under dir, as relative paths with "/" on every OS (as git shows them), including dotfiles
@@ -119,24 +142,39 @@ function fillPlaceholders(text, values) {
119
142
  return text.replace(/\{\{(\w+)\}\}/g, (m, k) => (k in values ? values[k] : m));
120
143
  }
121
144
 
122
- function projectValues(cwd, pkg, deps, pm, ci) {
145
+ // React Native 0.82 and later run only the New Architecture. Before that, android/gradle.properties chooses:
146
+ // the New Architecture was opt-in before 0.76 and the default from 0.76.
147
+ function architecture(cwd, rnVersion) {
148
+ const [major, minor] = String(rnVersion).split('.').map(Number);
149
+ if (!(major === 0 && minor < 82)) return 'New Architecture';
150
+ // Expo apps without native folders set it in app.json
151
+ const flag = ((readIf(path.join(cwd, 'android', 'gradle.properties')) || '').match(/^\s*newArchEnabled\s*=\s*(true|false)/m) || [])[1]
152
+ || (typeof expoConfig(cwd).newArchEnabled === 'boolean' ? String(expoConfig(cwd).newArchEnabled) : undefined);
153
+ return (flag ? flag === 'true' : minor >= 76) ? 'New Architecture' : 'Old Architecture: newArchEnabled=false';
154
+ }
155
+
156
+ function projectValues(cwd, pkg, deps, pm, ci, stack) {
157
+ const rn = installedVersion(cwd, 'react-native', deps['react-native']);
123
158
  return {
124
159
  KIT_VERSION,
125
160
  KIT_CI: ci.join(',') || 'none',
161
+ KIT_STACK: stack,
162
+ EXPO_SDK: deps.expo ? installedVersion(cwd, 'expo', deps.expo).split('.')[0] : '',
126
163
  APP_NAME: pkg.name || path.basename(cwd),
127
- RN_VERSION: installedVersion(cwd, 'react-native', deps['react-native']),
164
+ RN_VERSION: rn,
165
+ RN_ARCH: architecture(cwd, rn),
128
166
  REACT_VERSION: installedVersion(cwd, 'react', deps.react),
129
167
  TS_VERSION: installedVersion(cwd, 'typescript', deps.typescript),
130
168
  NODE_VERSION: (pkg.engines && pkg.engines.node) || `${process.versions.node.split('.')[0]}`,
131
169
  PM: pm.name,
132
170
  PM_RUN: pm.run,
133
- IOS_BUNDLE_ID: iosBundleId(cwd),
171
+ IOS_BUNDLE_ID: stack === 'expo' ? (expoConfig(cwd).ios || {}).bundleIdentifier || 'com.example.app' : iosBundleId(cwd),
134
172
  };
135
173
  }
136
174
 
137
175
  // a template file's text as the kit writes it into this project
138
- function kitText(templateDir, rel, values, targets) {
139
- const text = fs.readFileSync(path.join(templateDir, rel), 'utf8');
176
+ function kitText(src, rel, values, targets) {
177
+ const text = fs.readFileSync(src, 'utf8');
140
178
  if (FILLED.includes(rel)) return fillPlaceholders(text, values);
141
179
  if (rel === 'rulesync.jsonc') return setTargets(text, targets);
142
180
  return text;
@@ -170,10 +208,10 @@ function installedTools(cwd) {
170
208
  return tools.length ? tools : TESTED;
171
209
  }
172
210
 
173
- // what the kit marker in AGENTS.md records: the kit version since 0.4.0, the CI choice since 0.5.0
211
+ // what the kit marker in AGENTS.md records: the kit version since 0.4.0, the CI choice since 0.5.0, the stack since 0.6.0
174
212
  function recorded(agents) {
175
- const m = (agents || '').match(/KIT:START agentic-mobile-kit (\d[^\s>]*)(?: ci=([\w,]+))?/);
176
- return { version: m ? m[1] : null, ci: m && m[2] ? m[2].split(',').filter(g => CI[g]) : null };
213
+ const m = (agents || '').match(/KIT:START agentic-mobile-kit (\d[^\s>]*)(?: ci=([\w,]+))?(?: stack=(\w+))?/);
214
+ return { version: m ? m[1] : null, ci: m && m[2] ? m[2].split(',').filter(g => CI[g]) : null, stack: m && m[3] ? m[3] : null };
177
215
  }
178
216
 
179
217
  // the CI parts a project has: as recorded, or (installs before 0.5.0 got them by default) recognized by the kit's own files
@@ -222,11 +260,141 @@ function merge3(current, base, kitNew, from) {
222
260
  return { text: r.stdout, conflicts: r.status };
223
261
  }
224
262
 
263
+ // Git hook managers a project may already use. The kit's hooks then run from theirs and core.hooksPath stays theirs:
264
+ // two tools setting it undo each other on every install (husky's prepare script runs after the kit's postinstall).
265
+ const KIT_HOOKS = ['pre-commit', 'pre-push'];
266
+ const MARK = 'agentic-mobile-kit';
267
+ const hookCall = h => `sh .githooks/${h}${h === 'pre-push' ? ' "$@"' : ''} || exit 1 # ${MARK}`;
268
+ const localHooksPath = cwd => {
269
+ let v = '';
270
+ try { v = git(cwd, 'config', '--local', 'core.hooksPath'); } catch {}
271
+ return v && path.posix.normalize(v.replace(/\\/g, '/')).replace(/\/+$/, '');
272
+ };
273
+
274
+ function hookManager(cwd, pkg) {
275
+ const local = localHooksPath(cwd);
276
+ const deps = { ...pkg.dependencies, ...pkg.devDependencies };
277
+ if ((deps.husky && fs.existsSync(path.join(cwd, '.husky'))) || local.startsWith('.husky')) return { name: 'husky', dir: '.husky' };
278
+ if (pkg.husky && pkg.husky.hooks) return { name: 'husky', json: pkg.husky.hooks }; // husky 4
279
+ if (pkg['simple-git-hooks']) return { name: 'simple-git-hooks', json: pkg['simple-git-hooks'] };
280
+ const yaml = ['lefthook.yml', '.lefthook.yml', 'lefthook.yaml', '.lefthook.yaml'].find(f => fs.existsSync(path.join(cwd, f)));
281
+ if (yaml) return { name: 'lefthook', yaml };
282
+ // the team's own hooks folder; one outside the repo isn't the kit's to edit
283
+ if (local && local !== '.githooks') return path.isAbsolute(local) || local.startsWith('..') ? { name: local, manual: true } : { name: local, dir: local };
284
+ // hooks another tool installed into .git/hooks, which core.hooksPath would switch off
285
+ let gitHooks = '';
286
+ try { gitHooks = git(cwd, 'rev-parse', '--git-path', 'hooks'); } catch {}
287
+ if (!local && gitHooks && KIT_HOOKS.some(h => fs.existsSync(path.join(cwd, gitHooks, h)))) return { name: '.git/hooks', manual: true };
288
+ return null;
289
+ }
290
+
291
+ const hookFile = (m, h) => (m.dir ? `${m.dir}/${h}` : m.yaml);
292
+ const hooksWired = (cwd, m) => KIT_HOOKS.every(h => (m.json ? m.json[h] || '' : readIf(path.join(cwd, hookFile(m, h))) || '').includes(`.githooks/${h}`));
293
+
294
+ // after the shebang, comments and husky's own setup line: a command after the team's `exit` would never run
295
+ function insertCall(text, line) {
296
+ const lines = text.replace(/\n+$/, '').split('\n');
297
+ let i = 0;
298
+ while (i < lines.length && /^(#|\s*$|\.\s|source\s)/.test(lines[i])) i++;
299
+ lines.splice(i, 0, line);
300
+ return `${lines.join('\n')}\n`;
301
+ }
302
+
303
+ // adds the kit's command to a lefthook hook (under its commands: or jobs:), or the hook itself; null if it can't tell where
304
+ function lefthookAdd(text, h) {
305
+ const run = `sh .githooks/${h}`;
306
+ const lines = text.replace(/\n+$/, '').split('\n');
307
+ const start = lines.findIndex(l => new RegExp(`^["']?${h}["']?\\s*:`).test(l));
308
+ if (start < 0) return `${lines.join('\n')}\n${h}: # ${MARK}\n commands: # ${MARK}\n ${MARK}:\n run: ${run}\n`;
309
+ if (!/:\s*(#.*)?$/.test(lines[start])) return null; // written inline ({ … }) or with an anchor
310
+ let end = lines.findIndex((l, i) => i > start && /^[^\s#]/.test(l));
311
+ if (end < 0) end = lines.length;
312
+ const at = lines.findIndex((l, i) => i > start && i < end && /^\s+(commands|jobs):\s*(#.*)?$/.test(l));
313
+ if (at < 0) return null;
314
+ const indent = lines[at].match(/^\s*/)[0];
315
+ const next = lines.slice(at + 1, end).find(l => l.trim() && !l.trim().startsWith('#'));
316
+ const nextIndent = next ? next.match(/^\s*/)[0] : '';
317
+ if (/jobs:/.test(lines[at])) {
318
+ // a list: its items may sit at the same indent as "jobs:"
319
+ const item = next && next.trim().startsWith('-') ? nextIndent : `${indent} `;
320
+ lines.splice(at + 1, 0, `${item}- name: ${MARK}`, `${item} run: ${run}`);
321
+ } else {
322
+ const key = nextIndent.length > indent.length ? nextIndent : `${indent} `;
323
+ lines.splice(at + 1, 0, `${key}${MARK}:`, `${key}${key.slice(indent.length)}run: ${run}`);
324
+ }
325
+ return `${lines.join('\n')}\n`;
326
+ }
327
+
328
+ // runs the kit's hooks from the project's hook manager; true if package.json changed
329
+ function wireHooks(cwd, m, done) {
330
+ if (m.manual) {
331
+ done.warnings.push(`git hooks already run from ${m.name}, so the kit left core.hooksPath alone. To run the kit's checks too, add "sh .githooks/pre-commit" and "sh .githooks/pre-push" to those hooks.`);
332
+ return false;
333
+ }
334
+ let pkgChanged = false;
335
+ for (const h of KIT_HOOKS) {
336
+ if (m.json) {
337
+ if ((m.json[h] || '').includes(`.githooks/${h}`)) continue;
338
+ m.json[h] = m.json[h] ? `sh .githooks/${h} && ${m.json[h]}` : `sh .githooks/${h}`;
339
+ pkgChanged = true;
340
+ continue;
341
+ }
342
+ const rel = hookFile(m, h);
343
+ const file = path.join(cwd, rel);
344
+ const text = readIf(file);
345
+ if ((text || '').includes(`.githooks/${h}`)) continue;
346
+ if (m.yaml) {
347
+ const next = lefthookAdd(text, h);
348
+ if (next === null) { done.warnings.push(`couldn't add the kit's ${h} check to ${rel}: add a command there that runs "sh .githooks/${h}"`); continue; }
349
+ fs.writeFileSync(file, next);
350
+ if (!done.merged.includes(rel)) done.merged.push(rel);
351
+ continue;
352
+ }
353
+ fs.mkdirSync(path.dirname(file), { recursive: true });
354
+ fs.writeFileSync(file, text === null ? `#!/usr/bin/env sh\n${hookCall(h)}\n` : insertCall(text, hookCall(h)));
355
+ // husky 5 to 8 and plain hook folders run the file itself
356
+ fs.chmodSync(file, 0o755);
357
+ if (WIN) git(cwd, 'add', '--chmod=+x', '--', rel);
358
+ (text === null ? done.created : done.merged).push(rel);
359
+ }
360
+ if (pkgChanged && m.name === 'simple-git-hooks') done.warnings.push('run "npx simple-git-hooks" once, so it installs the hooks with the kit\'s checks in them');
361
+ return pkgChanged;
362
+ }
363
+
364
+ // takes the kit's lines back out of the project's hook manager
365
+ function unwireHooks(cwd, m, report) {
366
+ let pkgChanged = false;
367
+ for (const h of KIT_HOOKS) {
368
+ if (m.json) {
369
+ const before = m.json[h];
370
+ if (before === `sh .githooks/${h}`) delete m.json[h];
371
+ else if (before) m.json[h] = before.replace(`sh .githooks/${h} && `, '');
372
+ if (m.json[h] !== before) { pkgChanged = true; report.removed.push(`package.json ${m.name} ${h} (the kit's command)`); }
373
+ continue;
374
+ }
375
+ const rel = hookFile(m, h);
376
+ const text = readIf(path.join(cwd, rel));
377
+ if (text === null || !text.includes(MARK) && !text.includes('.githooks/')) continue;
378
+ const rest = text.split('\n').filter(l => !l.includes(MARK) && !l.includes('.githooks/')).join('\n');
379
+ if (/^(#![^\n]*)?\s*$/.test(rest)) fs.unlinkSync(path.join(cwd, rel)); else fs.writeFileSync(path.join(cwd, rel), rest);
380
+ if (!report.removed.some(r => r.startsWith(rel))) report.removed.push(`${rel} (the kit's lines)`);
381
+ }
382
+ return pkgChanged;
383
+ }
384
+
385
+ // takes the kit's command out of postinstall; true if it was there
386
+ function dropHooksCmd(scripts) {
387
+ const next = scripts.postinstall === HOOKS_CMD ? undefined : (scripts.postinstall || '').replace(` && (${HOOKS_CMD})`, '') || undefined;
388
+ if (next === scripts.postinstall) return false;
389
+ if (next) scripts.postinstall = next; else delete scripts.postinstall;
390
+ return true;
391
+ }
392
+
225
393
  const SKILL_LINKS = [['.claude/skills', 'claude'], ['.kiro/skills', 'kiro']];
226
- const kitSkills = template => fs.readdirSync(path.join(template, '.agents', 'skills'), { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name);
394
+ const kitSkills = files => [...files.keys()].filter(rel => /^\.agents\/skills\/[^/]+\/SKILL\.md$/.test(rel)).map(rel => rel.split('/')[2]);
227
395
 
228
396
  // steps 2–6, shared by init and sync
229
- function finish(cwd, { pkg, deps, tools, template, skipGenerate }) {
397
+ function finish(cwd, { pkg, deps, tools, files, stack, skipGenerate }) {
230
398
  const done = { created: [], merged: [], skipped: [], warnings: [] };
231
399
  // Windows creates symbolic links only with Developer Mode on (or as admin)
232
400
  const link = (target, p, label) => {
@@ -248,7 +416,7 @@ function finish(cwd, { pkg, deps, tools, template, skipGenerate }) {
248
416
  }
249
417
  if (isLink(dest) || !fs.statSync(dest).isDirectory()) { done.skipped.push(linkPath); continue; }
250
418
  // the folder already holds another framework's skills: link each kit skill into it
251
- for (const name of kitSkills(template)) {
419
+ for (const name of kitSkills(files)) {
252
420
  const p = path.join(dest, name);
253
421
  const target = `../../.agents/skills/${name}`;
254
422
  if (isLink(p) && linkTarget(p) === target) continue;
@@ -261,9 +429,11 @@ function finish(cwd, { pkg, deps, tools, template, skipGenerate }) {
261
429
  // 3. .gitignore: keep secrets out of git
262
430
  const gi = path.join(cwd, '.gitignore');
263
431
  const giText = readIf(gi) || '';
264
- const missing = ['.env', '.env.*', '!.env.example', '.ai/'].filter(l => !giText.split('\n').includes(l));
432
+ // Expo: ios/ and android/ are generated by prebuild, so they stay out of git too
433
+ const ignored = ['.env', '.env.*', '!.env.example', '.ai/', ...(stack === 'expo' ? ['/ios', '/android'] : [])];
434
+ const missing = ignored.filter(l => !giText.split('\n').includes(l));
265
435
  if (missing.length) {
266
- fs.writeFileSync(gi, `${giText.replace(/\n*$/, giText ? '\n' : '')}\n# agentic-mobile-kit: secrets stay out of git; .ai/ holds local evidence (screenshots, logs)\n${missing.join('\n')}\n`);
436
+ fs.writeFileSync(gi, `${giText.replace(/\n*$/, giText ? '\n' : '')}\n# agentic-mobile-kit: secrets stay out of git; .ai/ holds local evidence (screenshots, logs)${stack === 'expo' ? '; ios/ and android/ are generated' : ''}\n${missing.join('\n')}\n`);
267
437
  done.merged.push('.gitignore');
268
438
  }
269
439
 
@@ -282,7 +452,12 @@ function finish(cwd, { pkg, deps, tools, template, skipGenerate }) {
282
452
  // only TypeScript projects get typecheck: tsc fails ("no inputs") in JavaScript apps that merely have typescript installed
283
453
  const hasTs = git(cwd, 'ls-files', '*.ts', '*.tsx').split('\n').some(f => f && !f.endsWith('.d.ts'));
284
454
  if (!scripts.typecheck && deps.typescript && hasTs) { scripts.typecheck = 'tsc --noEmit'; pkgChanged = true; }
285
- if (!(scripts.postinstall || '').includes('core.hooksPath')) {
455
+ const manager = hookManager(cwd, pkg);
456
+ if (manager) {
457
+ // the project's hook manager runs the kit's hooks; drop the postinstall earlier kit versions added, which fought it
458
+ if (dropHooksCmd(scripts)) pkgChanged = true;
459
+ if (wireHooks(cwd, manager, done)) pkgChanged = true;
460
+ } else if (!(scripts.postinstall || '').includes('core.hooksPath')) {
286
461
  // parentheses keep the existing script's failure behavior: `a && b || true` would hide a failing `a`
287
462
  scripts.postinstall = scripts.postinstall ? `${scripts.postinstall} && (${HOOKS_CMD})` : HOOKS_CMD;
288
463
  pkgChanged = true;
@@ -290,7 +465,13 @@ function finish(cwd, { pkg, deps, tools, template, skipGenerate }) {
290
465
  if (pkgChanged) { fs.writeFileSync(path.join(cwd, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`); done.merged.push('package.json (scripts)'); }
291
466
 
292
467
  // 5. activate the git hooks now
293
- git(cwd, 'config', 'core.hooksPath', '.githooks');
468
+ if (!manager) git(cwd, 'config', 'core.hooksPath', '.githooks');
469
+ else if (localHooksPath(cwd) === '.githooks') {
470
+ // an earlier kit version took core.hooksPath over: give it back (husky 9 uses .husky/_, husky 5 to 8 .husky)
471
+ const husky = manager.dir === '.husky' && ['.husky/_/h', '.husky/_/husky.sh'].find(f => fs.existsSync(path.join(cwd, f)));
472
+ if (husky) git(cwd, 'config', 'core.hooksPath', husky.endsWith('/h') ? '.husky/_' : '.husky');
473
+ else git(cwd, 'config', '--unset', 'core.hooksPath');
474
+ }
294
475
  // Windows files have no executable bit, and git skips non-executable hooks on Mac and Linux clones:
295
476
  // stage the hooks as executable so the commit carries it
296
477
  const hooks = ['.githooks/pre-commit', '.githooks/pre-push'].filter(h => fs.existsSync(path.join(cwd, h)));
@@ -310,21 +491,25 @@ function finish(cwd, { pkg, deps, tools, template, skipGenerate }) {
310
491
  }
311
492
 
312
493
  function init(cwd, opts = {}) {
313
- const { pkg, deps } = checkProject(cwd);
494
+ // monorepos: git runs hooks from the repository root, and GitHub reads workflows only there
495
+ let prefix = '';
496
+ try { prefix = git(cwd, 'rev-parse', '--show-prefix').replace(/\/$/, ''); } catch {}
497
+ if (prefix) throw new InitError(`This app is in a subfolder of its git repository (${prefix}), as in a monorepo. The kit doesn't support that yet: git runs hooks from the repository root, and GitHub reads workflows only there.`);
498
+ const { pkg, deps, stack } = checkProject(cwd);
314
499
  const pm = detectPm(cwd, opts.pm);
315
500
  const tools = opts.tools || TESTED;
316
501
  for (const t of tools) if (!TOOLS[t]) throw new InitError(`Unknown tool "${t}". Choose from: ${Object.keys(TOOLS).join(', ')}.`);
317
- const template = opts.template || TEMPLATE;
502
+ const files = stackFiles(opts.template || TEMPLATE, stack);
318
503
  const ci = chooseCi(cwd, readIf(path.join(cwd, 'AGENTS.md')), opts.ci);
319
- const values = projectValues(cwd, pkg, deps, pm, ci);
504
+ const values = projectValues(cwd, pkg, deps, pm, ci, stack);
320
505
  const targets = tools.flatMap(t => TOOLS[t]);
321
506
  const report = { created: [], merged: [], skipped: [] };
322
507
 
323
508
  // 1. template files (never overwrite)
324
- for (const rel of templateFiles(template)) {
509
+ for (const [rel, src] of files) {
325
510
  if (ciGroup(rel) && !ci.includes(ciGroup(rel))) continue;
326
511
  const dest = path.join(cwd, rel);
327
- const text = kitText(template, rel, values, targets);
512
+ const text = kitText(src, rel, values, targets);
328
513
  const current = readIf(dest);
329
514
  if (current !== null && (rel === 'AGENTS.md' || rel === 'CLAUDE.md')) {
330
515
  const next = rel === 'AGENTS.md' ? mergeAgents(current, text) : mergeClaude(current);
@@ -336,32 +521,33 @@ function init(cwd, opts = {}) {
336
521
  report.created.push(rel);
337
522
  }
338
523
 
339
- const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, template, skipGenerate: opts.skipGenerate });
524
+ const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, files, stack, skipGenerate: opts.skipGenerate });
340
525
  for (const k of Object.keys(report)) report[k].push(...done[k]);
341
526
  return { report, warnings: done.warnings, values, tools, ci, generated, generateError };
342
527
  }
343
528
 
344
529
  function sync(cwd, opts = {}) {
345
- const { pkg, deps } = checkProject(cwd);
530
+ const { pkg, deps, stack: detected } = checkProject(cwd);
346
531
  const agents = readIf(path.join(cwd, 'AGENTS.md'));
347
532
  if (!agents || !MARKERS.test(agents)) throw new InitError('The kit isn\'t installed here (AGENTS.md has no KIT section). Run init instead.');
348
533
  const { from, dir: oldDir, exact } = oldTemplate(agents, opts);
349
- const template = opts.template || TEMPLATE;
534
+ // installs before 0.6.0 don't record it, and were all bare
535
+ const stack = recorded(agents).stack || detected;
350
536
  const ci = chooseCi(cwd, agents, opts.ci);
351
537
  // a CI part chosen just now was never installed, so its files are new rather than deleted by the team
352
538
  const hadCi = installedCi(cwd, agents);
353
539
  const wasInstalled = rel => !ciGroup(rel) || hadCi.includes(ciGroup(rel));
354
- const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm), ci);
540
+ const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm), ci, stack);
355
541
  const tools = installedTools(cwd);
356
542
  const targets = tools.flatMap(t => TOOLS[t]);
357
543
  const report = { updated: [], added: [], merged: [], conflicts: [], removed: [], kept: [] };
358
- const newFiles = templateFiles(template);
359
- const oldFiles = new Set(templateFiles(oldDir));
544
+ const newFiles = stackFiles(opts.template || TEMPLATE, stack);
545
+ const oldFiles = stackFiles(oldDir, stack);
360
546
 
361
- for (const rel of newFiles) {
547
+ for (const [rel, src] of newFiles) {
362
548
  if (ciGroup(rel) && !ci.includes(ciGroup(rel))) continue;
363
- const kitNew = kitText(template, rel, values, targets);
364
- const kitOld = oldFiles.has(rel) && wasInstalled(rel) ? kitText(oldDir, rel, values, targets) : null;
549
+ const kitNew = kitText(src, rel, values, targets);
550
+ const kitOld = oldFiles.has(rel) && wasInstalled(rel) ? kitText(oldFiles.get(rel), rel, values, targets) : null;
365
551
  const current = projectText(cwd, rel, targets);
366
552
  if (rel === 'AGENTS.md' || rel === 'CLAUDE.md') {
367
553
  const next = current === null ? kitNew : rel === 'AGENTS.md' ? mergeAgents(current, kitNew) : mergeClaude(current);
@@ -383,14 +569,14 @@ function sync(cwd, opts = {}) {
383
569
  (conflicts ? report.conflicts : report.merged).push(rel);
384
570
  }
385
571
  // files the kit no longer ships
386
- for (const rel of oldFiles) {
387
- if (newFiles.includes(rel) || !wasInstalled(rel)) continue;
572
+ for (const [rel, src] of oldFiles) {
573
+ if (newFiles.has(rel) || !wasInstalled(rel)) continue;
388
574
  const current = projectText(cwd, rel, targets);
389
575
  if (current === null) continue;
390
- if (current === kitText(oldDir, 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)`);
576
+ 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)`);
391
577
  }
392
578
 
393
- const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, template, skipGenerate: opts.skipGenerate });
579
+ const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, files: newFiles, stack, skipGenerate: opts.skipGenerate });
394
580
  report.added.push(...done.created);
395
581
  report.updated.push(...done.merged);
396
582
  return { report, warnings: done.warnings, from, to: KIT_VERSION, tools, generated, generateError };
@@ -410,18 +596,19 @@ function generatedFiles(cwd) {
410
596
  }
411
597
 
412
598
  function uninstall(cwd, opts = {}) {
413
- const { pkg, deps } = checkProject(cwd);
599
+ const { pkg, deps, stack: detected } = checkProject(cwd);
414
600
  const agents = readIf(path.join(cwd, 'AGENTS.md'));
415
601
  if (!agents || !MARKERS.test(agents)) throw new InitError('The kit isn\'t installed here (AGENTS.md has no KIT section).');
416
602
  const { from, dir: template } = oldTemplate(agents, opts);
417
- const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm), installedCi(cwd, agents));
603
+ const stack = recorded(agents).stack || detected;
604
+ const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm), installedCi(cwd, agents), stack);
418
605
  const targets = installedTools(cwd).flatMap(t => TOOLS[t]);
419
606
  const report = { removed: [], kept: [], left: [] };
420
607
  const remove = rel => { fs.unlinkSync(path.join(cwd, rel)); report.removed.push(rel); };
421
608
  // listed before their sources are removed
422
609
  const generated = opts.skipGenerate ? [] : generatedFiles(cwd);
423
610
 
424
- for (const rel of templateFiles(template)) {
611
+ for (const [rel, src] of stackFiles(template, stack)) {
425
612
  const current = projectText(cwd, rel, targets);
426
613
  if (current === null) continue;
427
614
  if (rel === 'AGENTS.md' || rel === 'CLAUDE.md') {
@@ -430,7 +617,7 @@ function uninstall(cwd, opts = {}) {
430
617
  else if (rest !== current) { fs.writeFileSync(path.join(cwd, rel), rest.replace(/\n+$/, '\n')); report.removed.push(`${rel} (the kit's part)`); }
431
618
  continue;
432
619
  }
433
- if (current === kitText(template, rel, values, targets)) remove(rel); else report.kept.push(rel);
620
+ if (current === kitText(src, rel, values, targets)) remove(rel); else report.kept.push(rel);
434
621
  }
435
622
  for (const [rel, text] of generated) {
436
623
  const current = readIf(path.join(cwd, rel));
@@ -453,14 +640,13 @@ function uninstall(cwd, opts = {}) {
453
640
  for (; d && d !== '.'; d = path.dirname(d)) { try { fs.rmdirSync(path.join(cwd, d)); } catch { break; } }
454
641
  }
455
642
 
456
- // git hooks
643
+ // git hooks: the kit's postinstall, or its lines in the project's hook manager (which would fail once .githooks is gone)
457
644
  const scripts = pkg.scripts || {};
458
- const postinstall = scripts.postinstall === HOOKS_CMD ? undefined : (scripts.postinstall || '').replace(` && (${HOOKS_CMD})`, '') || undefined;
459
- if (postinstall !== scripts.postinstall) {
460
- if (postinstall) scripts.postinstall = postinstall; else delete scripts.postinstall;
461
- fs.writeFileSync(path.join(cwd, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`);
462
- report.removed.push('package.json postinstall (git hooks)');
463
- }
645
+ let pkgChanged = false;
646
+ if (dropHooksCmd(scripts)) { pkgChanged = true; report.removed.push('package.json postinstall (git hooks)'); }
647
+ const manager = hookManager(cwd, pkg);
648
+ if (manager && !manager.manual && unwireHooks(cwd, manager, report)) pkgChanged = true;
649
+ if (pkgChanged) fs.writeFileSync(path.join(cwd, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`);
464
650
  try { if (git(cwd, 'config', 'core.hooksPath') === '.githooks') git(cwd, 'config', '--unset', 'core.hooksPath'); } catch {}
465
651
 
466
652
  report.left.push('.gitignore lines for .env files and .ai/ (they keep secrets and local evidence out of git)');
@@ -469,7 +655,7 @@ function uninstall(cwd, opts = {}) {
469
655
  }
470
656
 
471
657
  function printSummary({ report, warnings = [], values, tools, ci, generated, generateError }, log = console.log) {
472
- log(`agentic-mobile-kit installed for ${values.APP_NAME} (React Native ${values.RN_VERSION}, ${values.PM}).`);
658
+ log(`agentic-mobile-kit installed for ${values.APP_NAME} (${values.KIT_STACK === 'expo' ? `Expo SDK ${values.EXPO_SDK}, ` : ''}React Native ${values.RN_VERSION}, ${values.PM}).`);
473
659
  log(`Tools: ${tools.join(', ')}${tools.some(t => !TESTED.includes(t)) ? ' (cursor, opencode and kiro are not tested yet)' : ''}`);
474
660
  log(`CI: ${ci.length ? ci.join(', ') : 'none (add it any time with --ci github,codemagic)'}`);
475
661
  log(` created: ${report.created.length} files`);
@@ -508,4 +694,4 @@ function printUninstall({ report }, log = console.log) {
508
694
  log('\nReview it with "git status" and "git diff", then commit. Undo it with git if you change your mind.');
509
695
  }
510
696
 
511
- module.exports = { init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS, CI, KIT_VERSION, tool };
697
+ module.exports = { init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS, CI, KIT_VERSION, tool, hookManager, hooksWired };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "agentic-mobile-kit",
3
- "version": "0.5.4",
4
- "description": "One setup for AI-assisted development of bare React Native apps: 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.",
3
+ "version": "0.6.0",
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",
7
7
  "repository": {
@@ -26,6 +26,8 @@
26
26
  "keywords": [
27
27
  "react-native",
28
28
  "bare-react-native",
29
+ "expo",
30
+ "expo-router",
29
31
  "mobile",
30
32
  "ios",
31
33
  "android",
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2025-present 650 Industries, Inc. (aka Expo)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,11 @@
1
+ # Third-party skills
2
+
3
+ | Skill | Source | Commit | License | Changes |
4
+ |---|---|---|---|---|
5
+ | expo-router | https://github.com/expo/skills | d4f484024fec15196bfd3c272e953e3f983972cf | MIT (`LICENSE-expo`) | Image files left out |
6
+ | expo-upgrade | same | same | MIT | Image files left out |
7
+ | expo-module | same | same | MIT | Image files left out |
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 |
10
+
11
+ Updated with `scripts/vendor-skills.sh` in the agentic-mobile-kit repo.