agentic-mobile-kit 0.6.1 → 0.7.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 (52) hide show
  1. package/README.md +9 -7
  2. package/bin/cli.js +30 -22
  3. package/lib/doctor.js +12 -7
  4. package/lib/init.js +79 -34
  5. package/lib/menu.js +149 -0
  6. package/package.json +1 -1
  7. package/stacks/react-native/expo/AGENTS.md +13 -13
  8. package/stacks/react-native/expo/docs/{ai → amk}/expo.md +1 -1
  9. package/stacks/react-native/template/.agents/skills/m-bugfix/SKILL.md +4 -4
  10. package/stacks/react-native/template/.agents/skills/m-continue/SKILL.md +1 -1
  11. package/stacks/react-native/template/.agents/skills/m-explore/SKILL.md +2 -2
  12. package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +5 -5
  13. package/stacks/react-native/template/.agents/skills/m-learn/SKILL.md +5 -5
  14. package/stacks/react-native/template/.agents/skills/m-onboard/SKILL.md +60 -0
  15. package/stacks/react-native/template/.agents/skills/m-pause/SKILL.md +2 -2
  16. package/stacks/react-native/template/.agents/skills/m-release/SKILL.md +5 -5
  17. package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +1 -1
  18. package/stacks/react-native/template/.githooks/pre-commit +5 -5
  19. package/stacks/react-native/template/.githooks/pre-push +3 -3
  20. package/stacks/react-native/template/.github/workflows/ci.yml +5 -5
  21. package/stacks/react-native/template/.github/workflows/e2e.yml +5 -5
  22. package/stacks/react-native/template/.github/workflows/ios.yml +4 -4
  23. package/stacks/react-native/template/.rulesync/hooks.jsonc +2 -2
  24. package/stacks/react-native/template/AGENTS.md +15 -15
  25. package/stacks/react-native/template/codemagic.yaml +6 -6
  26. package/stacks/react-native/template/docs/{ai → amk}/codemagic.md +1 -1
  27. package/stacks/react-native/template/docs/{ai → amk}/known-issues.md +2 -2
  28. package/stacks/react-native/template/docs/{ai → amk}/react-native.md +1 -1
  29. package/stacks/react-native/template/docs/{ai → amk}/team-process.md +2 -2
  30. package/stacks/react-native/template/scripts/{ai → amk}/baseline.js +7 -6
  31. package/stacks/react-native/template/scripts/{ai → amk}/guard.js +1 -1
  32. package/stacks/react-native/template/scripts/{ai → amk}/handoff-check.js +1 -1
  33. package/stacks/react-native/template/scripts/{ai → amk}/ios-build.sh +1 -1
  34. package/stacks/react-native/template/scripts/{ai → amk}/pm-run.sh +1 -1
  35. package/stacks/react-native/template/scripts/{ai → amk}/pod-install.sh +1 -1
  36. package/stacks/react-native/template/scripts/{ai → amk}/prebuild.sh +1 -1
  37. package/stacks/react-native/template/scripts/{ai → amk}/release-build.sh +10 -10
  38. package/stacks/react-native/template/scripts/{ai → amk}/release-check.js +3 -3
  39. package/stacks/react-native/template/scripts/{ai → amk}/set-version.sh +2 -2
  40. package/stacks/react-native/template/scripts/{ai → amk}/specs.js +3 -3
  41. package/stacks/react-native/template/scripts/{ai → amk}/verify.sh +13 -13
  42. package/stacks/react-native/template/specs/current/README.md +2 -2
  43. /package/stacks/react-native/expo/docs/{ai → amk}/known-issues.md +0 -0
  44. /package/stacks/react-native/template/docs/{ai → amk}/conventions.md +0 -0
  45. /package/stacks/react-native/template/docs/{ai → amk}/decisions.md +0 -0
  46. /package/stacks/react-native/template/docs/{ai → amk}/product.md +0 -0
  47. /package/stacks/react-native/template/docs/{ai → amk}/structure.md +0 -0
  48. /package/stacks/react-native/template/docs/{ai → amk}/tech.md +0 -0
  49. /package/stacks/react-native/template/scripts/{ai → amk}/android-flavors.js +0 -0
  50. /package/stacks/react-native/template/scripts/{ai → amk}/case-check.js +0 -0
  51. /package/stacks/react-native/template/scripts/{ai → amk}/install-deps.sh +0 -0
  52. /package/stacks/react-native/template/scripts/{ai → amk}/maestro-env.sh +0 -0
package/README.md CHANGED
@@ -9,18 +9,16 @@ Tested with Claude Code, Codex and Antigravity. `--tools` also sets up Cursor, O
9
9
  1. In your app's root folder, on a clean git branch, run:
10
10
 
11
11
  ```sh
12
- npx agentic-mobile-kit init
12
+ npx agentic-mobile-kit
13
13
  ```
14
14
 
15
- If the app uses CI, add `--ci github`, `--ci codemagic` or both. To pick AI tools, add `--tools claude,codex,antigravity`, which is the default. `--help` lists every option.
15
+ It asks what to do, one step at a time: install with the recommended setup (Claude Code, Codex and Antigravity, no CI), or choose the AI tools and CI. There's nothing to `npm install`: the kit copies its files into the app and isn't a dependency. If you ran `npm i agentic-mobile-kit`, commit or undo that first, because the kit needs a clean working tree.
16
16
 
17
- 2. Check the project and your machine. `doctor` lists each problem with its fix:
17
+ 2. Run it again and choose **Check this project and machine**. It lists each problem with its fix.
18
18
 
19
- ```sh
20
- npx agentic-mobile-kit doctor
21
- ```
19
+ 3. In your AI tool, run `m-onboard`. It reads the project, drafts `docs/amk/product.md`, `tech.md`, `structure.md` and `conventions.md`, asks what the code can't show, and writes them once you approve. Then commit and open a PR.
22
20
 
23
- 3. Fill in `docs/ai/product.md`, `tech.md`, `structure.md` and `conventions.md`, then commit and open a PR.
21
+ Each choice prints the command it runs, for scripts and CI: `init` (with `--ci github`, `--ci codemagic` or `--tools claude,codex,antigravity`), `sync`, `doctor` and `uninstall`. `--help` lists every option.
24
22
 
25
23
  `init` never overwrites your files, is safe to run again, and can be undone with git. The [team guide](docs/team-guide.md#setup) lists everything it changes.
26
24
 
@@ -28,6 +26,7 @@ Tested with Claude Code, Codex and Antigravity. `--tools` also sets up Cursor, O
28
26
 
29
27
  | You want to | Run | What happens |
30
28
  |---|---|---|
29
+ | Describe the app for agents | `m-onboard` | Reads the whole project, drafts the product, tech, structure and conventions files in `docs/amk/`, asks what the code can't show, and writes them once you approve. Run it after installing, and again after big changes. |
31
30
  | Think a problem through | `m-explore` | The agent reads the code, explains how it works today and lays out options with trade-offs. It never edits code. |
32
31
  | Build a feature | `m-feature` | Requirements → you approve → design and tasks → you approve → one task at a time with tests → device checks with screenshots → living spec updated → review → PR |
33
32
  | Fix a bug | `m-bugfix` | Reproduces the bug, proves it with a failing test, finds the root cause, then makes the smallest fix |
@@ -49,6 +48,8 @@ Apps that already use Superpowers, BMAD, proAgents or similar keep them as they
49
48
 
50
49
  ## Update or remove
51
50
 
51
+ Run `npx agentic-mobile-kit` in an app that has the kit. It offers to update it, add CI, check the setup or remove the kit, and tells you when a newer version is out. The same as commands:
52
+
52
53
  ```sh
53
54
  npx agentic-mobile-kit@latest sync # update the kit's files, merging in your own changes
54
55
  npx agentic-mobile-kit uninstall # remove the kit; files you changed are kept and listed
@@ -58,6 +59,7 @@ Both need a clean working tree and leave the result for you to review with `git
58
59
  - **Report:** `sync` lists what it updated, added, removed and merged.
59
60
  - **Your docs:** the product, tech, structure and conventions files your team filled in are never changed.
60
61
  - **Adding CI later:** `sync --ci github` or `--ci codemagic` does it.
62
+ - **From 0.6 or earlier:** the update moves the kit's files from `docs/ai/` and `scripts/ai/` to `docs/amk/` and `scripts/amk/`, with your edits. Your own files in the old folders stay where they are, and it lists any of your files that still use the old paths.
61
63
 
62
64
  ## Requirements
63
65
 
package/bin/cli.js CHANGED
@@ -2,17 +2,12 @@
2
2
  const { version } = require('../package.json');
3
3
  const { init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS, CI } = require('../lib/init');
4
4
  const { doctor, printDoctor } = require('../lib/doctor');
5
-
6
- const [cmd, ...rest] = process.argv.slice(2);
7
- const flag = name => {
8
- const i = rest.indexOf(`--${name}`);
9
- return i >= 0 ? rest[i + 1] : undefined;
10
- };
11
- const list = name => (flag(name) ? flag(name).split(',').map(s => s.trim()).filter(Boolean) : undefined);
5
+ const { menu } = require('../lib/menu');
12
6
 
13
7
  const help = `agentic-mobile-kit ${version}
14
8
 
15
9
  Usage:
10
+ npx agentic-mobile-kit In a terminal: pick what to do in this app, step by step
16
11
  npx agentic-mobile-kit init [--tools claude,codex,antigravity] [--ci github,codemagic] [--pm yarn|npm|pnpm|bun]
17
12
  npx agentic-mobile-kit sync [--ci github,codemagic] [--from <version>]
18
13
  npx agentic-mobile-kit uninstall [--from <version>]
@@ -39,19 +34,32 @@ function run(name, fn) {
39
34
  }
40
35
  }
41
36
 
42
- if (cmd === '--version' || cmd === '-v') {
43
- console.log(version);
44
- } else if (cmd === 'init') {
45
- run('init', () => {
46
- printSummary(init(process.cwd(), { tools: list('tools'), ci: list('ci'), pm: flag('pm') }));
47
- });
48
- } else if (cmd === 'sync') {
49
- run('sync', () => printSync(sync(process.cwd(), { from: flag('from'), ci: list('ci'), pm: flag('pm') })));
50
- } else if (cmd === 'uninstall') {
51
- run('uninstall', () => printUninstall(uninstall(process.cwd(), { from: flag('from'), pm: flag('pm') })));
52
- } else if (cmd === 'doctor') {
53
- if (printDoctor(doctor(process.cwd())) > 0) process.exitCode = 1;
54
- } else {
55
- console.log(help);
56
- if (cmd && cmd !== 'help' && cmd !== '--help' && cmd !== '-h') process.exitCode = 1;
37
+ function main([cmd, ...rest]) {
38
+ const flag = name => {
39
+ const i = rest.indexOf(`--${name}`);
40
+ return i >= 0 ? rest[i + 1] : undefined;
41
+ };
42
+ const list = name => (flag(name) ? flag(name).split(',').map(s => s.trim()).filter(Boolean) : undefined);
43
+
44
+ if (cmd === '--version' || cmd === '-v') {
45
+ console.log(version);
46
+ } else if (cmd === 'init') {
47
+ run('init', () => {
48
+ printSummary(init(process.cwd(), { tools: list('tools'), ci: list('ci'), pm: flag('pm') }));
49
+ });
50
+ } else if (cmd === 'sync') {
51
+ run('sync', () => printSync(sync(process.cwd(), { from: flag('from'), ci: list('ci'), pm: flag('pm') })));
52
+ } else if (cmd === 'uninstall') {
53
+ run('uninstall', () => printUninstall(uninstall(process.cwd(), { from: flag('from'), pm: flag('pm') })));
54
+ } else if (cmd === 'doctor') {
55
+ if (printDoctor(doctor(process.cwd())) > 0) process.exitCode = 1;
56
+ } else {
57
+ console.log(help);
58
+ if (cmd && cmd !== 'help' && cmd !== '--help' && cmd !== '-h') process.exitCode = 1;
59
+ }
57
60
  }
61
+
62
+ // no command: the menu, but only for a person at a terminal. CI and AI agents get the help instead of a question
63
+ const args = process.argv.slice(2);
64
+ if (!args.length && process.stdin.isTTY && process.stdout.isTTY) menu(process.cwd()).then(chosen => chosen && main(chosen));
65
+ else main(args);
package/lib/doctor.js CHANGED
@@ -33,12 +33,16 @@ function projectChecks(cwd, opts) {
33
33
  return out; // the rest needs the kit
34
34
  }
35
35
  out.push(ok('Kit installed'));
36
+ // installs from before 0.7.0, until sync moves them
37
+ if (fs.existsSync(path.join(cwd, 'scripts/ai/verify.sh')) && !fs.existsSync(path.join(cwd, 'scripts/amk'))) {
38
+ out.push(warn('The kit\'s folders have their old names (docs/ai, scripts/ai)', 'update the kit: run npx agentic-mobile-kit and choose Update'));
39
+ }
36
40
 
37
41
  const lines = agents.split('\n').length;
38
42
  const bytes = Buffer.byteLength(agents);
39
43
  out.push(lines <= 150 && bytes <= 8192
40
44
  ? ok('AGENTS.md size', `${lines} lines`)
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/'));
45
+ : 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/amk/'));
42
46
 
43
47
  let pkg = {};
44
48
  try { pkg = JSON.parse(read(cwd, 'package.json') || '{}'); } catch {}
@@ -60,8 +64,8 @@ function projectChecks(cwd, opts) {
60
64
  : fail(`${manager.name} isn't set up on this clone, so no git hooks run`, 'run your package manager\'s install'));
61
65
  }
62
66
 
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' });
67
+ if (fs.existsSync(path.join(cwd, 'scripts/amk/case-check.js'))) {
68
+ const r = spawnSync(process.execPath, ['scripts/amk/case-check.js'], { cwd, encoding: 'utf8' });
65
69
  const lines = (r.stderr || '').trim().split('\n');
66
70
  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
71
  }
@@ -86,13 +90,14 @@ function projectChecks(cwd, opts) {
86
90
  : warn('Tool configs out of date with .rulesync/', `run: npx -y ${RULESYNC} generate, then commit`));
87
91
  }
88
92
 
93
+ const docs = fs.existsSync(path.join(cwd, 'docs/amk')) ? 'docs/amk' : 'docs/ai';
89
94
  const unfilled = ['product', 'tech', 'structure', 'conventions'].filter(n => {
90
- const t = read(cwd, `docs/ai/${n}.md`);
95
+ const t = read(cwd, `${docs}/${n}.md`);
91
96
  return t !== null && t.replace(/<!--[\s\S]*?-->/g, '').replace(/^#.*$/gm, '').trim() === '';
92
97
  });
93
98
  out.push(unfilled.length
94
- ? warn(`docs/ai not filled in: ${unfilled.join(', ')}`, 'describe the app there; agents build better with it')
95
- : ok('docs/ai filled in'));
99
+ ? warn(`${docs} not filled in: ${unfilled.join(', ')}`, 'run the m-onboard skill in your AI tool: it drafts them from the code')
100
+ : ok(`${docs} filled in`));
96
101
  return out;
97
102
  }
98
103
 
@@ -103,7 +108,7 @@ function machineChecks(cwd) {
103
108
 
104
109
  const pm = fs.existsSync(path.join(cwd, 'yarn.lock')) ? 'yarn' : fs.existsSync(path.join(cwd, 'pnpm-lock.yaml')) ? 'pnpm' : 'npm';
105
110
  out.push(run(pm, ['--version'], { cwd }) ? ok(`Package manager (${pm})`) : fail(`${pm} not found`, pm === 'npm' ? 'install Node' : 'run: corepack enable'));
106
- out.push(fs.existsSync(path.join(cwd, 'node_modules')) ? ok('Dependencies installed') : fail('Dependencies not installed', 'run: sh scripts/ai/install-deps.sh'));
111
+ out.push(fs.existsSync(path.join(cwd, 'node_modules')) ? ok('Dependencies installed') : fail('Dependencies not installed', 'run: sh scripts/amk/install-deps.sh'));
107
112
 
108
113
  // iOS (macOS only)
109
114
  if (process.platform === 'darwin') {
package/lib/init.js CHANGED
@@ -14,17 +14,23 @@ const MARKERS = /<!-- KIT:START[\s\S]*?<!-- KIT:END[^>]*-->\n?/;
14
14
  // files with {{PLACEHOLDERS}} filled in from the project
15
15
  const FILLED = ['AGENTS.md', 'codemagic.yaml'];
16
16
  // docs each team rewrites for its app: sync replaces them only while they're untouched, and never merges into them
17
- const PROJECT_DOCS = ['product', 'tech', 'structure', 'conventions'].map(n => `docs/ai/${n}.md`);
17
+ const PROJECT_DOCS = ['product', 'tech', 'structure', 'conventions'].map(n => `docs/amk/${n}.md`);
18
18
  const HOOKS_CMD = 'git config core.hooksPath .githooks || true';
19
19
  // the app's own ESLint skips the kit's scripts: they follow the kit's style, not each app's rules
20
- const ESLINT_IGNORE = 'scripts/ai/';
20
+ const ESLINT_IGNORE = 'scripts/amk/';
21
21
  const ESLINT_NOTE = "# agentic-mobile-kit: its scripts follow the kit's style, not this app's lint rules";
22
22
  // optional parts, installed only when a project chooses them with --ci: not every app uses CI
23
23
  const CI = {
24
24
  github: rel => rel.startsWith('.github/'),
25
- codemagic: rel => rel === 'codemagic.yaml' || rel === 'docs/ai/codemagic.md',
25
+ codemagic: rel => rel === 'codemagic.yaml' || rel === 'docs/amk/codemagic.md',
26
26
  };
27
27
  const ciGroup = rel => Object.keys(CI).find(g => CI[g](rel));
28
+ // 0.7.0 renamed the kit's folders from "ai", which apps may already use for their own AI features
29
+ const RENAMED = [['docs/ai/', 'docs/amk/'], ['scripts/ai/', 'scripts/amk/']];
30
+ const renamedPath = rel => {
31
+ const r = RENAMED.find(([from]) => rel.startsWith(from));
32
+ return r ? r[1] + rel.slice(r[0].length) : rel;
33
+ };
28
34
 
29
35
  // tool name -> rulesync targets
30
36
  const TOOLS = {
@@ -82,18 +88,19 @@ function detectPm(cwd, forced) {
82
88
  return pms.npm;
83
89
  }
84
90
 
91
+ // the app's folder first: in the wrong folder, "run git init" would be the wrong advice
85
92
  function checkProject(cwd) {
93
+ const pkgFile = path.join(cwd, 'package.json');
94
+ if (!fs.existsSync(pkgFile)) throw new InitError('No package.json here. Run this in the root of your React Native app.');
95
+ const pkg = readJson(pkgFile);
96
+ const deps = { ...pkg.dependencies, ...pkg.devDependencies };
97
+ if (!deps['react-native']) throw new InitError('This is not a React Native project (no "react-native" dependency).');
86
98
  try { git(cwd, 'rev-parse', '--is-inside-work-tree'); } catch {
87
99
  throw new InitError('This folder is not a git repository. Run "git init" and commit first; git is how init can be undone.');
88
100
  }
89
101
  if (git(cwd, 'status', '--porcelain')) {
90
102
  throw new InitError('You have uncommitted changes. Commit or stash them first, so this can be undone with git.');
91
103
  }
92
- const pkgFile = path.join(cwd, 'package.json');
93
- if (!fs.existsSync(pkgFile)) throw new InitError('No package.json here. Run this in the root of your React Native app.');
94
- const pkg = readJson(pkgFile);
95
- const deps = { ...pkg.dependencies, ...pkg.devDependencies };
96
- if (!deps['react-native']) throw new InitError('This is not a React Native project (no "react-native" dependency).');
97
104
  const stack = detectStack(cwd, deps);
98
105
  if (stack === 'bare' && (!fs.existsSync(path.join(cwd, 'ios')) || !fs.existsSync(path.join(cwd, 'android')))) {
99
106
  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.');
@@ -108,7 +115,7 @@ function detectStack(cwd, deps) {
108
115
  }
109
116
 
110
117
  // a stack's files, rel -> source: the template, and for Expo the overlay next to it, which replaces or adds files
111
- const EXPO_LEAVES_OUT = ['docs/ai/react-native.md', '.agents/skills/upgrading-react-native/'];
118
+ const EXPO_LEAVES_OUT = ['docs/amk/react-native.md', '.agents/skills/upgrading-react-native/'];
112
119
  function stackFiles(template, stack) {
113
120
  const files = new Map(templateFiles(template).map(rel => [rel, path.join(template, rel)]));
114
121
  if (stack !== 'expo') return files;
@@ -156,8 +163,14 @@ function architecture(cwd, rnVersion) {
156
163
  return (flag ? flag === 'true' : minor >= 76) ? 'New Architecture' : 'Old Architecture: newArchEnabled=false';
157
164
  }
158
165
 
166
+ // TypeScript files, not just the typescript package: the React Native template installs it in JavaScript apps too
167
+ const usesTs = cwd => git(cwd, 'ls-files', '*.ts', '*.tsx').split('\n').some(f => f && !f.endsWith('.d.ts'));
168
+
159
169
  function projectValues(cwd, pkg, deps, pm, ci, stack) {
160
170
  const rn = installedVersion(cwd, 'react-native', deps['react-native']);
171
+ const ts = usesTs(cwd);
172
+ // the checks agents can run: the app's own scripts, and the typecheck script init adds to TypeScript apps
173
+ const checks = ['lint', 'typecheck', 'test'].filter(s => (pkg.scripts || {})[s] || (s === 'typecheck' && ts && deps.typescript));
161
174
  return {
162
175
  KIT_VERSION,
163
176
  KIT_CI: ci.join(',') || 'none',
@@ -168,6 +181,9 @@ function projectValues(cwd, pkg, deps, pm, ci, stack) {
168
181
  RN_ARCH: architecture(cwd, rn),
169
182
  REACT_VERSION: installedVersion(cwd, 'react', deps.react),
170
183
  TS_VERSION: installedVersion(cwd, 'typescript', deps.typescript),
184
+ LANGUAGE: ts ? `TypeScript${deps.typescript ? ` ${installedVersion(cwd, 'typescript', deps.typescript)}` : ''}` : 'JavaScript',
185
+ CHECK_TASKS: checks.length ? checks.join(', ').replace(/^./, c => c.toUpperCase()) : 'Lint, typecheck, test',
186
+ CHECK_COMMANDS: checks.map(s => `\`${pm.run} ${s}\``).join(', ') || 'none in `package.json` yet',
171
187
  NODE_VERSION: (pkg.engines && pkg.engines.node) || `${process.versions.node.split('.')[0]}`,
172
188
  PM: pm.name,
173
189
  PM_RUN: pm.run,
@@ -433,10 +449,10 @@ function finish(cwd, { pkg, deps, tools, files, stack, skipGenerate }) {
433
449
  const gi = path.join(cwd, '.gitignore');
434
450
  const giText = readIf(gi) || '';
435
451
  // Expo: ios/ and android/ are generated by prebuild, so they stay out of git too
436
- const ignored = ['.env', '.env.*', '!.env*.example', '!.env*.sample', '!.env*.template', '.ai/', ...(stack === 'expo' ? ['/ios', '/android'] : [])];
452
+ const ignored = ['.env', '.env.*', '!.env*.example', '!.env*.sample', '!.env*.template', '.amk/', ...(stack === 'expo' ? ['/ios', '/android'] : [])];
437
453
  const missing = ignored.filter(l => !giText.split('\n').includes(l));
438
454
  if (missing.length) {
439
- 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`);
455
+ 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`);
440
456
  done.merged.push('.gitignore');
441
457
  }
442
458
 
@@ -453,18 +469,20 @@ function finish(cwd, { pkg, deps, tools, files, stack, skipGenerate }) {
453
469
  // the kit's scripts pass React Native's default rules, but stricter configs such as Airbnb's flag them)
454
470
  const eslintrc = fs.readdirSync(cwd).some(f => /^\.eslintrc(\.\w+)?$/.test(f)) || Boolean(pkg.eslintConfig);
455
471
  const ei = path.join(cwd, '.eslintignore');
456
- const eiText = readIf(ei) || '';
457
- if (eslintrc && !eiText.split('\n').includes(ESLINT_IGNORE)) {
458
- fs.writeFileSync(ei, `${eiText.replace(/\n*$/, eiText ? '\n' : '')}${eiText ? '\n' : ''}${ESLINT_NOTE}\n${ESLINT_IGNORE}\n`);
459
- (eiText ? done.merged : done.created).push('.eslintignore');
472
+ const eiOld = readIf(ei) || '';
473
+ // before 0.7.0 the kit's line named scripts/ai/
474
+ let eiText = eiOld.replace(`${ESLINT_NOTE}\nscripts/ai/\n`, `${ESLINT_NOTE}\n${ESLINT_IGNORE}\n`);
475
+ if (eslintrc && !eiText.split('\n').includes(ESLINT_IGNORE)) eiText = `${eiText.replace(/\n*$/, eiText ? '\n' : '')}${eiText ? '\n' : ''}${ESLINT_NOTE}\n${ESLINT_IGNORE}\n`;
476
+ if (eiText !== eiOld) {
477
+ fs.writeFileSync(ei, eiText);
478
+ (eiOld ? done.merged : done.created).push('.eslintignore');
460
479
  }
461
480
 
462
481
  // 4. package.json scripts: typecheck, and hooks path on install (never overwrite existing scripts)
463
482
  const scripts = (pkg.scripts = pkg.scripts || {});
464
483
  let pkgChanged = false;
465
484
  // only TypeScript projects get typecheck: tsc fails ("no inputs") in JavaScript apps that merely have typescript installed
466
- const hasTs = git(cwd, 'ls-files', '*.ts', '*.tsx').split('\n').some(f => f && !f.endsWith('.d.ts'));
467
- if (!scripts.typecheck && deps.typescript && hasTs) { scripts.typecheck = 'tsc --noEmit'; pkgChanged = true; }
485
+ if (!scripts.typecheck && deps.typescript && usesTs(cwd)) { scripts.typecheck = 'tsc --noEmit'; pkgChanged = true; }
468
486
  const manager = hookManager(cwd, pkg);
469
487
  if (manager) {
470
488
  // the project's hook manager runs the kit's hooks; drop the postinstall earlier kit versions added, which fought it
@@ -504,11 +522,10 @@ function finish(cwd, { pkg, deps, tools, files, stack, skipGenerate }) {
504
522
  }
505
523
 
506
524
  function init(cwd, opts = {}) {
525
+ const { pkg, deps, stack } = checkProject(cwd);
507
526
  // monorepos: git runs hooks from the repository root, and GitHub reads workflows only there
508
- let prefix = '';
509
- try { prefix = git(cwd, 'rev-parse', '--show-prefix').replace(/\/$/, ''); } catch {}
527
+ const prefix = git(cwd, 'rev-parse', '--show-prefix').replace(/\/$/, '');
510
528
  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.`);
511
- const { pkg, deps, stack } = checkProject(cwd);
512
529
  const pm = detectPm(cwd, opts.pm);
513
530
  const tools = opts.tools || TESTED;
514
531
  for (const t of tools) if (!TOOLS[t]) throw new InitError(`Unknown tool "${t}". Choose from: ${Object.keys(TOOLS).join(', ')}.`);
@@ -553,9 +570,26 @@ function sync(cwd, opts = {}) {
553
570
  const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm), ci, stack);
554
571
  const tools = installedTools(cwd);
555
572
  const targets = tools.flatMap(t => TOOLS[t]);
556
- const report = { updated: [], added: [], merged: [], conflicts: [], removed: [], kept: [] };
573
+ const report = { moved: [], updated: [], added: [], merged: [], conflicts: [], removed: [], kept: [] };
557
574
  const newFiles = stackFiles(opts.template || TEMPLATE, stack);
558
- const oldFiles = stackFiles(oldDir, stack);
575
+ // an install from before 0.7.0: the kit's files move to the new folders first, so the team's edits come along.
576
+ // Other files in the old folders may be the app's own, so they stay where they are.
577
+ const oldKit = stackFiles(oldDir, stack);
578
+ const moved = [...oldKit.keys()].filter(rel => renamedPath(rel) !== rel
579
+ && fs.existsSync(path.join(cwd, rel)) && !fs.existsSync(path.join(cwd, renamedPath(rel))));
580
+ for (const rel of moved) {
581
+ fs.mkdirSync(path.dirname(path.join(cwd, renamedPath(rel))), { recursive: true });
582
+ fs.renameSync(path.join(cwd, rel), path.join(cwd, renamedPath(rel)));
583
+ }
584
+ for (const [from, to] of RENAMED) {
585
+ const n = moved.filter(rel => rel.startsWith(from)).length;
586
+ if (!n) continue;
587
+ report.moved.push(`${from} to ${to} (${n} files)`);
588
+ const left = templateFiles(path.join(cwd, from));
589
+ if (left.length) report.kept.push(`${left.map(f => from + f).join(', ')} (not the kit's; its files moved to ${to})`);
590
+ else fs.rmSync(path.join(cwd, from), { recursive: true, force: true });
591
+ }
592
+ const oldFiles = new Map([...oldKit].map(([rel, src]) => [renamedPath(rel), src]));
559
593
 
560
594
  for (const [rel, src] of newFiles) {
561
595
  if (ciGroup(rel) && !ci.includes(ciGroup(rel))) continue;
@@ -592,7 +626,13 @@ function sync(cwd, opts = {}) {
592
626
  const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, files: newFiles, stack, skipGenerate: opts.skipGenerate });
593
627
  report.added.push(...done.created);
594
628
  report.updated.push(...done.merged);
595
- return { report, warnings: done.warnings, from, to: KIT_VERSION, tools, generated, generateError };
629
+ // the team's own files that still name a moved file: scripts in package.json, other CI, their docs
630
+ let stale = '';
631
+ try { if (moved.length) stale = git(cwd, 'grep', '-l', '--untracked', '-F', ...moved.flatMap(rel => ['-e', rel])); } catch {}
632
+ if (stale) done.warnings.push(`still pointing to the kit's old folders: ${stale.split('\n').join(', ')}. Change docs/ai/ to docs/amk/ and scripts/ai/ to scripts/amk/ there.`);
633
+ // it started from a clean working tree, so git shows everything it changed (tool configs too)
634
+ const changed = git(cwd, 'status', '--porcelain') !== '';
635
+ return { report, warnings: done.warnings, from, to: KIT_VERSION, tools, changed, generated, generateError };
596
636
  }
597
637
 
598
638
  // what rulesync generates from the project's kit sources, regenerated in an empty folder: [[path, text]]
@@ -664,13 +704,15 @@ function uninstall(cwd, opts = {}) {
664
704
 
665
705
  // .eslintignore: the kit's lines, and the file if nothing else is in it
666
706
  const eiText = readIf(path.join(cwd, '.eslintignore'));
667
- if (eiText !== null && eiText.split('\n').includes(ESLINT_IGNORE)) {
668
- const rest = eiText.split('\n').filter(l => l !== ESLINT_IGNORE && l !== ESLINT_NOTE).join('\n').replace(/\n{3,}/g, '\n\n');
707
+ // installs from before 0.7.0 have scripts/ai/ under the kit's note
708
+ const ours = l => l === ESLINT_NOTE || l === ESLINT_IGNORE || (l === 'scripts/ai/' && eiText.includes(ESLINT_NOTE));
709
+ if (eiText !== null && eiText.split('\n').some(l => l !== ESLINT_NOTE && ours(l))) {
710
+ const rest = eiText.split('\n').filter(l => !ours(l)).join('\n').replace(/\n{3,}/g, '\n\n');
669
711
  if (!rest.trim()) fs.unlinkSync(path.join(cwd, '.eslintignore')); else fs.writeFileSync(path.join(cwd, '.eslintignore'), rest.replace(/\n*$/, '\n'));
670
712
  report.removed.push('.eslintignore (the kit\'s lines)');
671
713
  }
672
714
 
673
- report.left.push('.gitignore lines for .env files and .ai/ (they keep secrets and local evidence out of git)');
715
+ report.left.push('the kit\'s .gitignore lines (they keep .env files and local evidence out of git)');
674
716
  if (scripts.typecheck === 'tsc --noEmit') report.left.push('the "typecheck" script in package.json');
675
717
  return { report, from };
676
718
  }
@@ -685,27 +727,27 @@ function printSummary({ report, warnings = [], values, tools, ci, generated, gen
685
727
  for (const w of warnings) log(` ! ${w}`);
686
728
  if (!generated) log(` ! could not generate tool configs; run: npx -y ${RULESYNC} generate\n${generateError.replace(/^/gm, ' ')}`);
687
729
  log('\nNext steps:');
688
- log(' 1. Fill in docs/ai/product.md, tech.md, structure.md and conventions.md for this app.');
730
+ log(' 1. In your AI tool, run m-onboard (/m-onboard, or $m-onboard in Codex). It drafts docs/amk/product.md, tech.md,\n structure.md and conventions.md from the code, asks what the code can\'t show, and writes them once you approve.');
689
731
  log(' 2. Commit on a branch and open a PR. Add the "large-pr" label (the vendored skills are large).');
690
732
  const more = [
691
733
  ci.includes('github') && 'Turn on branch protection for main: see docs/branch-protection.md in the kit repo.',
692
- ci.includes('codemagic') && 'Signed store builds on Codemagic: one-time setup in docs/ai/codemagic.md.',
734
+ ci.includes('codemagic') && 'Signed store builds on Codemagic: one-time setup in docs/amk/codemagic.md.',
693
735
  tools.includes('codex') && 'Codex users: open the project in Codex once and approve its hooks (they stay off until approved).',
694
736
  ].filter(Boolean);
695
737
  more.forEach((m, i) => log(` ${i + 3}. ${m}`));
696
738
  }
697
739
 
698
- function printSync({ report, warnings = [], from, to, generated, generateError }, log = console.log) {
699
- log(`agentic-mobile-kit updated from ${from} to ${to}.`);
740
+ function printSync({ report, warnings = [], from, to, changed, generated, generateError }, log = console.log) {
741
+ log(from === to ? `agentic-mobile-kit is already ${to}.` : `agentic-mobile-kit updated from ${from} to ${to}.`);
700
742
  const lines = [
701
- ['updated', report.updated], ['added', report.added], ['removed', report.removed],
743
+ ['moved to the new folders', report.moved || []], ['updated', report.updated], ['added', report.added], ['removed', report.removed],
702
744
  ['merged with your changes', report.merged], ['CONFLICTS, resolve the <<<<<<< markers', report.conflicts], ['left alone', report.kept],
703
745
  ];
704
746
  for (const [label, files] of lines) if (files.length) log(` ${label}: ${files.join(', ')}`);
705
- if (!Object.values(report).some(a => a.length)) log(' Nothing to change.');
747
+ if (!changed) log(' Nothing changed.');
706
748
  for (const w of warnings) log(` ! ${w}`);
707
749
  if (!generated) log(` ! could not generate tool configs; run: npx -y ${RULESYNC} generate\n${generateError.replace(/^/gm, ' ')}`);
708
- log('\nReview it with "git diff", run the checks, then commit on a branch and open a PR.');
750
+ if (changed) log('\nReview it with "git diff", run the checks, then commit on a branch and open a PR.');
709
751
  }
710
752
 
711
753
  function printUninstall({ report }, log = console.log) {
@@ -715,4 +757,7 @@ function printUninstall({ report }, log = console.log) {
715
757
  log('\nReview it with "git status" and "git diff", then commit. Undo it with git if you change your mind.');
716
758
  }
717
759
 
718
- module.exports = { init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS, CI, KIT_VERSION, tool, hookManager, hooksWired };
760
+ module.exports = {
761
+ init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS, TESTED, CI, KIT_VERSION, tool, cleanEnv,
762
+ hookManager, hooksWired, checkProject, recorded, installedCi,
763
+ };
package/lib/menu.js ADDED
@@ -0,0 +1,149 @@
1
+ 'use strict';
2
+ // `npx agentic-mobile-kit` with no command, in a terminal: what the kit can do in this app, asked one step at a time.
3
+ // It returns the command to run and prints it, so people learn the commands that scripts, CI and agents use.
4
+ const fs = require('fs');
5
+ const path = require('path');
6
+ const readline = require('readline');
7
+ const { checkProject, recorded, installedCi, InitError, TOOLS, TESTED, CI, KIT_VERSION, tool, cleanEnv } = require('./init');
8
+
9
+ const NAMES = { claude: 'Claude Code', codex: 'Codex', antigravity: 'Antigravity', cursor: 'Cursor', opencode: 'OpenCode', kiro: 'Kiro' };
10
+ const CI_NAMES = { github: 'GitHub Actions', codemagic: 'Codemagic' };
11
+ const CI_LABELS = { github: 'GitHub Actions: checks on every pull request', codemagic: 'Codemagic: signed store builds' };
12
+ const and = a => (a.length > 1 ? `${a.slice(0, -1).join(', ')} and ${a[a.length - 1]}` : a[0]);
13
+ const newer = (a, b) => a.localeCompare(b, 'en', { numeric: true }) > 0;
14
+ class Closed extends Error {}
15
+
16
+ // the version npm installs now; null when that can't be checked (offline, no npm)
17
+ function latestVersion(cwd) {
18
+ const r = tool('npm', ['view', 'agentic-mobile-kit', 'version'], { cwd, env: cleanEnv(), encoding: 'utf8', timeout: 8000 });
19
+ const v = (r.stdout || '').trim();
20
+ return r.status === 0 && /^\d+\.\d+\.\d+$/.test(v) ? v : null;
21
+ }
22
+
23
+ async function menu(cwd, { input = process.stdin, output = process.stdout, latest = latestVersion } = {}) {
24
+ const rl = readline.createInterface({ input, output });
25
+ // Ctrl-C ends the menu, like Ctrl-D (readline alone would only pause)
26
+ rl.on('SIGINT', () => rl.close());
27
+ let closed = false;
28
+ rl.on('close', () => { closed = true; });
29
+ const lines = rl[Symbol.asyncIterator]();
30
+ const say = s => output.write(`${s}\n`);
31
+ const ask = async q => {
32
+ // piped answers can outlast the input, which closes readline
33
+ if (closed) output.write(q);
34
+ else {
35
+ rl.setPrompt(q);
36
+ rl.prompt();
37
+ }
38
+ const { value, done } = await lines.next();
39
+ if (done) throw new Closed();
40
+ return value.trim();
41
+ };
42
+ const show = (question, items) => {
43
+ say(`\n${question}`);
44
+ items.forEach((it, i) => say(` ${i + 1}. ${it.label}`));
45
+ };
46
+ // one item: Enter takes the default, anything else is asked again
47
+ const pick = async (question, items, def = 0) => {
48
+ show(question, items);
49
+ for (;;) {
50
+ const item = items[Number((await ask(`Choose 1-${items.length} [${def + 1}]: `)) || def + 1) - 1];
51
+ if (item) return item;
52
+ }
53
+ };
54
+ const pickSome = async (question, items, defaults) => {
55
+ show(question, items);
56
+ const def = items.flatMap((it, i) => (defaults.includes(it.value) ? [i + 1] : [])).join(',');
57
+ for (;;) {
58
+ const chosen = ((await ask(`Numbers, separated by commas [${def}]: `)) || def).split(/[\s,]+/).filter(Boolean).map(n => items[Number(n) - 1]);
59
+ if (chosen.length && chosen.every(Boolean)) return items.filter(it => chosen.includes(it)).map(it => it.value);
60
+ }
61
+ };
62
+ const yes = async (question, def) => {
63
+ const a = (await ask(`${question} [${def ? 'Y/n' : 'y/N'}]: `)).toLowerCase();
64
+ return a ? a.startsWith('y') : def;
65
+ };
66
+ const ciItems = groups => [...groups.map(g => ({ label: CI_LABELS[g], value: [g] })), ...(groups.length > 1 ? [{ label: 'Both', value: groups }] : [])];
67
+
68
+ try {
69
+ say(`agentic-mobile-kit ${KIT_VERSION}`);
70
+ // npx can run an older copy it keeps in its cache
71
+ const next = latest(cwd);
72
+ if (next && newer(next, KIT_VERSION) && await yes(`Version ${next} is out. Use it?`, true)) {
73
+ rl.close();
74
+ process.exitCode = tool('npx', ['-y', `agentic-mobile-kit@${next}`], { cwd, stdio: 'inherit', env: cleanEnv() }).status ?? 1;
75
+ return null;
76
+ }
77
+
78
+ let problem = '';
79
+ try { checkProject(cwd); } catch (e) {
80
+ if (!(e instanceof InitError)) throw e;
81
+ problem = e.message;
82
+ }
83
+ let agents = '';
84
+ try { agents = fs.readFileSync(path.join(cwd, 'AGENTS.md'), 'utf8'); } catch {}
85
+ const doctor = { label: 'Check this project and machine (doctor)', args: ['doctor'] };
86
+ const quit = { label: 'Quit', args: null };
87
+ let items;
88
+ let def = 0;
89
+ if (!/<!-- KIT:START/.test(agents)) {
90
+ say('The kit isn\'t installed here.');
91
+ items = [
92
+ { label: `Install it for ${and(TESTED.map(t => NAMES[t]))}, without CI (init)`, args: ['init'], changes: true },
93
+ {
94
+ label: 'Install it and choose the AI tools and CI',
95
+ changes: true,
96
+ steps: async () => {
97
+ const tools = await pickSome('Which AI tools does your team use?',
98
+ Object.keys(TOOLS).map(t => ({ value: t, label: `${NAMES[t]}${TESTED.includes(t) ? '' : ' (not tested yet)'}` })), TESTED);
99
+ const ci = (await pick('Set up CI? Only if the app uses it.', [{ label: 'No CI', value: [] }, ...ciItems(Object.keys(CI))])).value;
100
+ return ['init', ...(String(tools) === String(TESTED) ? [] : ['--tools', tools.join(',')]), ...(ci.length ? ['--ci', ci.join(',')] : [])];
101
+ },
102
+ },
103
+ doctor, quit,
104
+ ];
105
+ } else {
106
+ const from = recorded(agents).version;
107
+ const ci = installedCi(cwd, agents);
108
+ const missing = Object.keys(CI).filter(g => !ci.includes(g));
109
+ const update = !from || newer(KIT_VERSION, from);
110
+ say(`Kit ${from || '(an early version)'} is installed here. CI: ${ci.length ? and(ci.map(g => CI_NAMES[g])) : 'none'}.`);
111
+ if (from && newer(from, KIT_VERSION)) problem ||= `This app has kit ${from}, newer than this copy (${KIT_VERSION}). Run: npx agentic-mobile-kit@latest`;
112
+ items = [
113
+ { label: update ? `Update the kit${from ? ` from ${from}` : ''} to ${KIT_VERSION} (sync)` : 'Sync the kit again; it\'s up to date (sync)', args: ['sync'], changes: true },
114
+ missing.length && {
115
+ label: `Add CI: ${missing.map(g => CI_NAMES[g]).join(' or ')}${update ? ', and update the kit' : ''} (sync --ci)`,
116
+ changes: true,
117
+ steps: async () => ['sync', '--ci', (missing.length > 1 ? (await pick('Which CI?', ciItems(missing))).value : missing).join(',')],
118
+ },
119
+ doctor,
120
+ { label: 'Remove the kit (uninstall)', args: ['uninstall'], changes: true, confirm: 'Remove the kit from this app? Files you changed are kept, and git can undo it.' },
121
+ quit,
122
+ ].filter(Boolean);
123
+ def = update ? 0 : items.indexOf(doctor);
124
+ }
125
+ // installing, updating and removing need a clean git repository: say why they aren't offered
126
+ if (problem) {
127
+ say(`! ${problem}`);
128
+ items = items.filter(it => !it.changes);
129
+ def = 0;
130
+ }
131
+
132
+ const choice = await pick('What would you like to do?', items, def);
133
+ if (choice.confirm && !(await yes(choice.confirm, false))) {
134
+ say('Nothing changed.');
135
+ return null;
136
+ }
137
+ const args = choice.steps ? await choice.steps() : choice.args;
138
+ if (args) say(`\nRunning: npx agentic-mobile-kit ${args.join(' ')}\n`);
139
+ return args;
140
+ } catch (e) {
141
+ if (!(e instanceof Closed)) throw e;
142
+ say('');
143
+ return null;
144
+ } finally {
145
+ rl.close();
146
+ }
147
+ }
148
+
149
+ module.exports = { menu };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentic-mobile-kit",
3
- "version": "0.6.1",
3
+ "version": "0.7.0",
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",