agentic-mobile-kit 0.3.0 → 0.4.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.
package/README.md CHANGED
@@ -21,6 +21,19 @@ npx agentic-mobile-kit doctor
21
21
 
22
22
  `init` never overwrites your files. It adds its section to an existing `AGENTS.md` between `KIT` markers, and it's safe to run again. Undo it with git.
23
23
 
24
+ ## Update or remove it
25
+
26
+ ```sh
27
+ npx agentic-mobile-kit@latest sync # update the kit's files; your own changes to them are merged in
28
+ npx agentic-mobile-kit uninstall # remove the kit; files you changed are kept and listed
29
+ ```
30
+
31
+ Both need a clean working tree, and both leave the result for you to review with `git diff`.
32
+
33
+ `sync` reports what it updated, added, removed and merged. If you and the kit changed the same lines, the file gets `<<<<<<<` conflict markers to resolve. The docs your team filled in (`docs/ai/product.md`, `tech.md`, `structure.md`, `conventions.md`) are never changed.
34
+
35
+ Installs older than 0.4.0 don't record which kit version made them, so their first `sync` or `uninstall` needs `--from <version>`, for example `--from 0.3.0`. That version can only be a guess, so `sync` doesn't merge on top of it: every file that matches neither version gets conflict markers instead.
36
+
24
37
  ## What it adds
25
38
 
26
39
  - **Context for every AI tool:** `AGENTS.md` (plus a one-line `CLAUDE.md`), `docs/ai/` (product, tech, structure, conventions, decisions, known issues, React Native rules) and spec templates in `specs/_templates/`.
package/bin/cli.js CHANGED
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
  const { version } = require('../package.json');
3
- const { init, printSummary, InitError, TOOLS } = require('../lib/init');
3
+ const { init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS } = require('../lib/init');
4
4
  const { doctor, printDoctor } = require('../lib/doctor');
5
5
 
6
6
  const [cmd, ...rest] = process.argv.slice(2);
@@ -13,27 +13,41 @@ const help = `agentic-mobile-kit ${version}
13
13
 
14
14
  Usage:
15
15
  npx agentic-mobile-kit init [--tools claude,codex,antigravity] [--pm yarn|npm|pnpm|bun]
16
+ npx agentic-mobile-kit sync [--from <version>]
17
+ npx agentic-mobile-kit uninstall [--from <version>]
16
18
  npx agentic-mobile-kit doctor
17
19
 
18
20
  Commands:
19
- init Install the kit into a bare React Native project (run in the app's root).
20
- doctor Check the project and this machine, with a fix for each problem.
21
+ init Install the kit into a bare React Native project (run in the app's root).
22
+ sync Update the kit's files to this version. Your own changes to them are merged in, not lost.
23
+ uninstall Remove the kit's files and sections. Files you changed are kept and listed.
24
+ doctor Check the project and this machine, with a fix for each problem.
21
25
 
22
26
  Options:
23
27
  --tools AI tools your team uses: ${Object.keys(TOOLS).join(', ')} (default: claude,codex,antigravity)
24
- --pm Package manager, if it can't be detected from the lockfile`;
28
+ --pm Package manager, if it can't be detected from the lockfile
29
+ --from The kit version that installed the project; needed only for installs made before 0.4.0`;
30
+
31
+ // init, sync and uninstall stop with a plain message when the project isn't ready for them
32
+ function run(name, fn) {
33
+ try { fn(); } catch (e) {
34
+ if (!(e instanceof InitError)) throw e;
35
+ console.error(`${name} stopped: ${e.message}`);
36
+ process.exitCode = 1;
37
+ }
38
+ }
25
39
 
26
40
  if (cmd === '--version' || cmd === '-v') {
27
41
  console.log(version);
28
42
  } else if (cmd === 'init') {
29
- try {
43
+ run('init', () => {
30
44
  const tools = flag('tools') ? flag('tools').split(',').map(s => s.trim()).filter(Boolean) : undefined;
31
45
  printSummary(init(process.cwd(), { tools, pm: flag('pm') }));
32
- } catch (e) {
33
- if (!(e instanceof InitError)) throw e;
34
- console.error(`init stopped: ${e.message}`);
35
- process.exitCode = 1;
36
- }
46
+ });
47
+ } else if (cmd === 'sync') {
48
+ run('sync', () => printSync(sync(process.cwd(), { from: flag('from'), pm: flag('pm') })));
49
+ } else if (cmd === 'uninstall') {
50
+ run('uninstall', () => printUninstall(uninstall(process.cwd(), { from: flag('from'), pm: flag('pm') })));
37
51
  } else if (cmd === 'doctor') {
38
52
  if (printDoctor(doctor(process.cwd())) > 0) process.exitCode = 1;
39
53
  } else {
package/lib/init.js CHANGED
@@ -1,13 +1,21 @@
1
1
  'use strict';
2
2
  // `agentic-mobile-kit init`: installs the kit into a bare React Native project.
3
- // Never overwrites existing files; merges AGENTS.md / CLAUDE.md; git is the backup (clean tree required).
3
+ // `sync` updates an installed project to this kit version; `uninstall` removes the kit.
4
+ // All three need a clean working tree, so git is the backup for everything they touch.
4
5
  const fs = require('fs');
6
+ const os = require('os');
5
7
  const path = require('path');
6
8
  const { execFileSync, spawnSync } = require('child_process');
7
9
 
10
+ const KIT_VERSION = require('../package.json').version;
8
11
  const TEMPLATE = path.join(__dirname, '..', 'stacks', 'react-native', 'template');
9
12
  const RULESYNC = 'rulesync@27.0.0';
10
13
  const MARKERS = /<!-- KIT:START[\s\S]*?<!-- KIT:END[^>]*-->\n?/;
14
+ // files with {{PLACEHOLDERS}} filled in from the project
15
+ const FILLED = ['AGENTS.md', 'codemagic.yaml'];
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`);
18
+ const HOOKS_CMD = 'git config core.hooksPath .githooks || true';
11
19
 
12
20
  // tool name -> rulesync targets
13
21
  const TOOLS = {
@@ -27,6 +35,11 @@ function git(cwd, ...args) {
27
35
  }
28
36
 
29
37
  function readJson(file) { return JSON.parse(fs.readFileSync(file, 'utf8')); }
38
+ const readIf = file => { try { return fs.readFileSync(file, 'utf8'); } catch { return null; } };
39
+ function isLink(p) { try { return fs.lstatSync(p).isSymbolicLink(); } catch { return false; } }
40
+
41
+ // when the kit runs under npx, npm_config_* variables (e.g. the outer --package) would leak into the npx/npm it starts
42
+ const cleanEnv = () => Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^npm_(config|package|lifecycle)_/i.test(k)));
30
43
 
31
44
  function installedVersion(cwd, pkg, declared) {
32
45
  try { return readJson(path.join(cwd, 'node_modules', pkg, 'package.json')).version; } catch {}
@@ -55,10 +68,10 @@ function checkProject(cwd) {
55
68
  throw new InitError('This folder is not a git repository. Run "git init" and commit first; git is how init can be undone.');
56
69
  }
57
70
  if (git(cwd, 'status', '--porcelain')) {
58
- throw new InitError('You have uncommitted changes. Commit or stash them first, so init can be undone with git.');
71
+ throw new InitError('You have uncommitted changes. Commit or stash them first, so this can be undone with git.');
59
72
  }
60
73
  const pkgFile = path.join(cwd, 'package.json');
61
- if (!fs.existsSync(pkgFile)) throw new InitError('No package.json here. Run init in the root of your React Native app.');
74
+ if (!fs.existsSync(pkgFile)) throw new InitError('No package.json here. Run this in the root of your React Native app.');
62
75
  const pkg = readJson(pkgFile);
63
76
  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
64
77
  if (!deps['react-native']) throw new InitError('This is not a React Native project (no "react-native" dependency).');
@@ -68,7 +81,7 @@ function checkProject(cwd) {
68
81
  return { pkg, deps };
69
82
  }
70
83
 
71
- // all template files, relative paths, including dotfiles
84
+ // all files under dir, as relative paths, including dotfiles
72
85
  function templateFiles(dir = TEMPLATE, base = '') {
73
86
  return fs.readdirSync(dir, { withFileTypes: true }).flatMap(e => {
74
87
  const rel = path.join(base, e.name);
@@ -90,13 +103,9 @@ function fillPlaceholders(text, values) {
90
103
  return text.replace(/\{\{(\w+)\}\}/g, (m, k) => (k in values ? values[k] : m));
91
104
  }
92
105
 
93
- function init(cwd, opts = {}) {
94
- const { pkg, deps } = checkProject(cwd);
95
- const pm = detectPm(cwd, opts.pm);
96
- const tools = opts.tools || TESTED;
97
- for (const t of tools) if (!TOOLS[t]) throw new InitError(`Unknown tool "${t}". Choose from: ${Object.keys(TOOLS).join(', ')}.`);
98
-
99
- const values = {
106
+ function projectValues(cwd, pkg, deps, pm) {
107
+ return {
108
+ KIT_VERSION,
100
109
  APP_NAME: pkg.name || path.basename(cwd),
101
110
  RN_VERSION: installedVersion(cwd, 'react-native', deps['react-native']),
102
111
  REACT_VERSION: installedVersion(cwd, 'react', deps.react),
@@ -106,95 +115,273 @@ function init(cwd, opts = {}) {
106
115
  PM_RUN: pm.run,
107
116
  IOS_BUNDLE_ID: iosBundleId(cwd),
108
117
  };
109
- const report = { created: [], merged: [], skipped: [] };
118
+ }
110
119
 
111
- // 1. template files (never overwrite)
112
- for (const rel of templateFiles()) {
113
- const src = path.join(TEMPLATE, rel);
114
- const dest = path.join(cwd, rel);
115
- const kitText = () => fillPlaceholders(fs.readFileSync(src, 'utf8'), values);
120
+ // a template file's text as the kit writes it into this project
121
+ function kitText(templateDir, rel, values, targets) {
122
+ const text = fs.readFileSync(path.join(templateDir, rel), 'utf8');
123
+ if (FILLED.includes(rel)) return fillPlaceholders(text, values);
124
+ if (rel === 'rulesync.jsonc') return setTargets(text, targets);
125
+ return text;
126
+ }
116
127
 
117
- if (rel === 'AGENTS.md' && fs.existsSync(dest)) {
118
- const current = fs.readFileSync(dest, 'utf8');
119
- const section = kitText();
120
- const next = MARKERS.test(current) ? current.replace(MARKERS, section) : `${current.replace(/\n*$/, '\n\n')}${section}`;
121
- if (next !== current) { fs.writeFileSync(dest, next); report.merged.push(rel); } else report.skipped.push(rel);
122
- continue;
123
- }
124
- if (rel === 'CLAUDE.md' && fs.existsSync(dest)) {
125
- const current = fs.readFileSync(dest, 'utf8');
126
- if (/^@AGENTS\.md\s*$/m.test(current)) report.skipped.push(rel);
127
- else { fs.writeFileSync(dest, `${current.replace(/\n*$/, '\n\n')}@AGENTS.md\n`); report.merged.push(rel); }
128
- continue;
129
- }
130
- if (fs.existsSync(dest)) { report.skipped.push(rel); continue; }
128
+ const setTargets = (text, targets) => text.replace(/"targets":\s*\[[^\]]*\]/, () => `"targets": ${JSON.stringify(targets)}`);
129
+ // a project file's text for comparing with the kit's: the targets line is the project's own (init rewrites it)
130
+ const projectText = (cwd, rel, targets) => {
131
+ const text = readIf(path.join(cwd, rel));
132
+ return text !== null && rel === 'rulesync.jsonc' ? setTargets(text, targets) : text;
133
+ };
134
+ // a function replacement, so "$" in the kit's text is never read as a replacement pattern
135
+ const mergeAgents = (current, section) => (MARKERS.test(current) ? current.replace(MARKERS, () => section) : `${current.replace(/\n*$/, '\n\n')}${section}`);
136
+ const mergeClaude = current => (/^@AGENTS\.md\s*$/m.test(current) ? current : `${current.replace(/\n*$/, '\n\n')}@AGENTS.md\n`);
131
137
 
132
- fs.mkdirSync(path.dirname(dest), { recursive: true });
133
- if (rel === 'AGENTS.md' || rel === 'codemagic.yaml') fs.writeFileSync(dest, kitText());
134
- else fs.copyFileSync(src, dest);
135
- // npm doesn't always keep the executable bit, and git silently skips non-executable hooks
136
- const executable = rel.startsWith(`.githooks${path.sep}`) || /\.(sh|js)$/.test(rel) && rel.startsWith(`scripts${path.sep}`);
137
- fs.chmodSync(dest, executable ? 0o755 : 0o644);
138
- report.created.push(rel);
138
+ function writeKitFile(cwd, rel, text) {
139
+ const dest = path.join(cwd, rel);
140
+ fs.mkdirSync(path.dirname(dest), { recursive: true });
141
+ fs.writeFileSync(dest, text);
142
+ // npm doesn't always keep the executable bit, and git silently skips non-executable hooks
143
+ const executable = rel.startsWith(`.githooks${path.sep}`) || /\.(sh|js)$/.test(rel) && rel.startsWith(`scripts${path.sep}`);
144
+ fs.chmodSync(dest, executable ? 0o755 : 0o644);
145
+ }
146
+
147
+ // the tools a project was set up for, read back from its rulesync targets
148
+ function installedTools(cwd) {
149
+ const m = (readIf(path.join(cwd, 'rulesync.jsonc')) || '').match(/"targets":\s*\[([^\]]*)\]/);
150
+ let targets = [];
151
+ try { targets = JSON.parse(`[${m ? m[1] : ''}]`); } catch {}
152
+ const tools = Object.keys(TOOLS).filter(t => TOOLS[t].every(x => targets.includes(x)));
153
+ return tools.length ? tools : TESTED;
154
+ }
155
+
156
+ // the kit version that installed the project: recorded in AGENTS.md since 0.4.0, or given with --from.
157
+ // A --from version is a guess (installs may predate it), so it isn't trusted as a merge base.
158
+ function oldTemplate(agents, opts) {
159
+ if (opts.fromDir) return { from: opts.from || 'old', dir: opts.fromDir, exact: !opts.from };
160
+ const from = opts.from || (agents.match(/KIT:START agentic-mobile-kit (\d[^\s>]*)/) || [])[1];
161
+ if (!from) {
162
+ throw new InitError('This project doesn\'t record which kit version installed it (versions before 0.4.0 didn\'t). '
163
+ + 'Pass it with --from, for example --from 0.3.0; the commit that added or last updated the kit usually says.');
139
164
  }
165
+ const [a, b] = [from, KIT_VERSION].map(v => v.split('.').map(n => parseInt(n, 10) || 0));
166
+ const newer = a.findIndex((n, i) => n !== b[i]);
167
+ if (newer >= 0 && a[newer] > b[newer]) throw new InitError(`This project uses kit ${from}, which is newer than this one (${KIT_VERSION}). Use the latest: npx agentic-mobile-kit@latest`);
168
+ return { from, dir: from === KIT_VERSION ? TEMPLATE : fetchTemplate(from), exact: !opts.from };
169
+ }
170
+
171
+ function fetchTemplate(version) {
172
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amk-kit-'));
173
+ const r = spawnSync('npm', ['pack', `agentic-mobile-kit@${version}`, '--pack-destination', dir, '--silent'], { cwd: dir, env: cleanEnv(), encoding: 'utf8' });
174
+ if (r.status !== 0) throw new InitError(`Couldn't download agentic-mobile-kit@${version} from npm: ${(r.stderr || '').trim().split('\n').pop()}`);
175
+ execFileSync('tar', ['-xzf', path.join(dir, r.stdout.trim().split('\n').pop()), '-C', dir]);
176
+ return path.join(dir, 'package', 'stacks', 'react-native', 'template');
177
+ }
178
+
179
+ // three-way merge: your changes and the kit's changes since the old version, both kept
180
+ function merge3(current, base, kitNew, from) {
181
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amk-merge-'));
182
+ const files = [current, base, kitNew].map((text, i) => { const f = path.join(dir, String(i)); fs.writeFileSync(f, text); return f; });
183
+ const r = spawnSync('git', ['merge-file', '-p', '-L', 'your version', '-L', `kit ${from}`, '-L', `kit ${KIT_VERSION}`, ...files], { encoding: 'utf8' });
184
+ fs.rmSync(dir, { recursive: true, force: true });
185
+ if (r.status === null || r.status < 0 || r.status > 127) throw new Error(`git merge-file failed: ${r.stderr}`);
186
+ return { text: r.stdout, conflicts: r.status };
187
+ }
188
+
189
+ // steps 2–6, shared by init and sync
190
+ function finish(cwd, { pkg, deps, tools, skipGenerate }) {
191
+ const done = { created: [], merged: [], skipped: [] };
140
192
 
141
193
  // 2. skills folder links for tools that don't read .agents/skills
142
- const links = [['.claude/skills', 'claude'], ['.kiro/skills', 'kiro']];
143
- for (const [link, tool] of links) {
194
+ for (const [link, tool] of [['.claude/skills', 'claude'], ['.kiro/skills', 'kiro']]) {
144
195
  if (!tools.includes(tool)) continue;
145
196
  const dest = path.join(cwd, link);
146
- if (fs.existsSync(dest) || isLink(dest)) { report.skipped.push(link); continue; }
197
+ if (fs.existsSync(dest) || isLink(dest)) { done.skipped.push(link); continue; }
147
198
  fs.mkdirSync(path.dirname(dest), { recursive: true });
148
199
  fs.symlinkSync('../.agents/skills', dest);
149
- report.created.push(`${link} -> .agents/skills`);
200
+ done.created.push(`${link} -> .agents/skills`);
150
201
  }
151
202
 
152
203
  // 3. .gitignore: keep secrets out of git
153
204
  const gi = path.join(cwd, '.gitignore');
154
- const giText = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
205
+ const giText = readIf(gi) || '';
155
206
  const missing = ['.env', '.env.*', '!.env.example', '.ai/'].filter(l => !giText.split('\n').includes(l));
156
207
  if (missing.length) {
157
208
  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`);
158
- report.merged.push('.gitignore');
209
+ done.merged.push('.gitignore');
159
210
  }
160
211
 
161
212
  // 4. package.json scripts: typecheck, and hooks path on install (never overwrite existing scripts)
162
- const pkgFile = path.join(cwd, 'package.json');
163
213
  const scripts = (pkg.scripts = pkg.scripts || {});
164
214
  let pkgChanged = false;
165
215
  // only TypeScript projects get typecheck: tsc fails ("no inputs") in JavaScript apps that merely have typescript installed
166
216
  const hasTs = git(cwd, 'ls-files', '*.ts', '*.tsx').split('\n').some(f => f && !f.endsWith('.d.ts'));
167
217
  if (!scripts.typecheck && deps.typescript && hasTs) { scripts.typecheck = 'tsc --noEmit'; pkgChanged = true; }
168
- const hooksCmd = 'git config core.hooksPath .githooks || true';
169
218
  if (!(scripts.postinstall || '').includes('core.hooksPath')) {
170
219
  // parentheses keep the existing script's failure behavior: `a && b || true` would hide a failing `a`
171
- scripts.postinstall = scripts.postinstall ? `${scripts.postinstall} && (${hooksCmd})` : hooksCmd;
220
+ scripts.postinstall = scripts.postinstall ? `${scripts.postinstall} && (${HOOKS_CMD})` : HOOKS_CMD;
172
221
  pkgChanged = true;
173
222
  }
174
- if (pkgChanged) { fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`); report.merged.push('package.json (scripts)'); }
223
+ if (pkgChanged) { fs.writeFileSync(path.join(cwd, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`); done.merged.push('package.json (scripts)'); }
175
224
 
176
225
  // 5. activate the git hooks now
177
226
  git(cwd, 'config', 'core.hooksPath', '.githooks');
178
227
 
179
228
  // 6. tool configs for the chosen tools (permissions, hooks, subagents)
180
229
  const rsFile = path.join(cwd, 'rulesync.jsonc');
181
- const rs = fs.readFileSync(rsFile, 'utf8');
182
- const targets = tools.flatMap(t => TOOLS[t]);
183
- fs.writeFileSync(rsFile, rs.replace(/"targets":\s*\[[^\]]*\]/, `"targets": ${JSON.stringify(targets)}`));
230
+ fs.writeFileSync(rsFile, setTargets(fs.readFileSync(rsFile, 'utf8'), tools.flatMap(t => TOOLS[t])));
184
231
  let generated = true;
185
232
  let generateError = '';
186
- if (!opts.skipGenerate) {
187
- // when init itself runs under npx, npm_config_* variables (e.g. the outer --package) would leak into this npx
188
- const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^npm_(config|package|lifecycle)_/i.test(k)));
189
- const r = spawnSync('npx', ['-y', RULESYNC, 'generate'], { cwd, env, encoding: 'utf8' });
233
+ if (!skipGenerate) {
234
+ const r = spawnSync('npx', ['-y', RULESYNC, 'generate'], { cwd, env: cleanEnv(), encoding: 'utf8' });
190
235
  generated = r.status === 0;
191
236
  if (!generated) generateError = `${r.stderr || ''}${r.stdout || ''}`.trim().split('\n').slice(-5).join('\n');
192
237
  }
238
+ return { done, generated, generateError };
239
+ }
240
+
241
+ function init(cwd, opts = {}) {
242
+ const { pkg, deps } = checkProject(cwd);
243
+ const pm = detectPm(cwd, opts.pm);
244
+ const tools = opts.tools || TESTED;
245
+ for (const t of tools) if (!TOOLS[t]) throw new InitError(`Unknown tool "${t}". Choose from: ${Object.keys(TOOLS).join(', ')}.`);
246
+ const template = opts.template || TEMPLATE;
247
+ const values = projectValues(cwd, pkg, deps, pm);
248
+ const targets = tools.flatMap(t => TOOLS[t]);
249
+ const report = { created: [], merged: [], skipped: [] };
250
+
251
+ // 1. template files (never overwrite)
252
+ for (const rel of templateFiles(template)) {
253
+ const dest = path.join(cwd, rel);
254
+ const text = kitText(template, rel, values, targets);
255
+ const current = readIf(dest);
256
+ if (current !== null && (rel === 'AGENTS.md' || rel === 'CLAUDE.md')) {
257
+ const next = rel === 'AGENTS.md' ? mergeAgents(current, text) : mergeClaude(current);
258
+ if (next !== current) { fs.writeFileSync(dest, next); report.merged.push(rel); } else report.skipped.push(rel);
259
+ continue;
260
+ }
261
+ if (fs.existsSync(dest)) { report.skipped.push(rel); continue; }
262
+ writeKitFile(cwd, rel, text);
263
+ report.created.push(rel);
264
+ }
193
265
 
266
+ const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, skipGenerate: opts.skipGenerate });
267
+ for (const k of Object.keys(report)) report[k].push(...done[k]);
194
268
  return { report, values, tools, generated, generateError };
195
269
  }
196
270
 
197
- function isLink(p) { try { return fs.lstatSync(p).isSymbolicLink(); } catch { return false; } }
271
+ function sync(cwd, opts = {}) {
272
+ const { pkg, deps } = checkProject(cwd);
273
+ const agents = readIf(path.join(cwd, 'AGENTS.md'));
274
+ if (!agents || !MARKERS.test(agents)) throw new InitError('The kit isn\'t installed here (AGENTS.md has no KIT section). Run init instead.');
275
+ const { from, dir: oldDir, exact } = oldTemplate(agents, opts);
276
+ const template = opts.template || TEMPLATE;
277
+ const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm));
278
+ const tools = installedTools(cwd);
279
+ const targets = tools.flatMap(t => TOOLS[t]);
280
+ const report = { updated: [], added: [], merged: [], conflicts: [], removed: [], kept: [] };
281
+ const newFiles = templateFiles(template);
282
+ const oldFiles = new Set(templateFiles(oldDir));
283
+
284
+ for (const rel of newFiles) {
285
+ const kitNew = kitText(template, rel, values, targets);
286
+ const kitOld = oldFiles.has(rel) ? kitText(oldDir, rel, values, targets) : null;
287
+ const current = projectText(cwd, rel, targets);
288
+ if (rel === 'AGENTS.md' || rel === 'CLAUDE.md') {
289
+ const next = current === null ? kitNew : rel === 'AGENTS.md' ? mergeAgents(current, kitNew) : mergeClaude(current);
290
+ if (next !== current) { fs.writeFileSync(path.join(cwd, rel), next); report.updated.push(rel); }
291
+ continue;
292
+ }
293
+ if (current === null) {
294
+ if (kitOld === null) { writeKitFile(cwd, rel, kitNew); report.added.push(rel); } else report.kept.push(`${rel} (you deleted it)`);
295
+ continue;
296
+ }
297
+ if (current === kitNew) continue;
298
+ if (kitOld === null) { report.kept.push(`${rel} (your own file; the kit now has one with this name)`); continue; }
299
+ if (current === kitOld) { writeKitFile(cwd, rel, kitNew); report.updated.push(rel); continue; }
300
+ if (PROJECT_DOCS.includes(rel)) continue;
301
+ // without an exact base, an old unchanged file would look like your edit and be kept: show every difference instead
302
+ const { text, conflicts } = merge3(current, exact ? kitOld : '', kitNew, from);
303
+ writeKitFile(cwd, rel, text);
304
+ (conflicts ? report.conflicts : report.merged).push(rel);
305
+ }
306
+ // files the kit no longer ships
307
+ for (const rel of oldFiles) {
308
+ if (newFiles.includes(rel)) continue;
309
+ const current = projectText(cwd, rel, targets);
310
+ if (current === null) continue;
311
+ 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)`);
312
+ }
313
+
314
+ const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, skipGenerate: opts.skipGenerate });
315
+ report.added.push(...done.created);
316
+ report.updated.push(...done.merged);
317
+ return { report, from, to: KIT_VERSION, tools, generated, generateError };
318
+ }
319
+
320
+ // what rulesync generates from the project's kit sources, regenerated in an empty folder: [[path, text]]
321
+ function generatedFiles(cwd) {
322
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amk-gen-'));
323
+ fs.cpSync(path.join(cwd, '.rulesync'), path.join(dir, '.rulesync'), { recursive: true });
324
+ fs.copyFileSync(path.join(cwd, 'rulesync.jsonc'), path.join(dir, 'rulesync.jsonc'));
325
+ const r = spawnSync('npx', ['-y', RULESYNC, 'generate'], { cwd: dir, env: cleanEnv(), encoding: 'utf8' });
326
+ if (r.status !== 0) throw new InitError(`Couldn't work out which tool configs rulesync generated: ${`${r.stderr}${r.stdout}`.trim().split('\n').pop()}`);
327
+ const files = templateFiles(dir).filter(f => !f.startsWith(`.rulesync${path.sep}`) && !['rulesync.jsonc', '.gitignore'].includes(f));
328
+ const out = files.map(f => [f, fs.readFileSync(path.join(dir, f), 'utf8')]);
329
+ fs.rmSync(dir, { recursive: true, force: true });
330
+ return out;
331
+ }
332
+
333
+ function uninstall(cwd, opts = {}) {
334
+ const { pkg, deps } = checkProject(cwd);
335
+ const agents = readIf(path.join(cwd, 'AGENTS.md'));
336
+ if (!agents || !MARKERS.test(agents)) throw new InitError('The kit isn\'t installed here (AGENTS.md has no KIT section).');
337
+ const { from, dir: template } = oldTemplate(agents, opts);
338
+ const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm));
339
+ const targets = installedTools(cwd).flatMap(t => TOOLS[t]);
340
+ const report = { removed: [], kept: [], left: [] };
341
+ const remove = rel => { fs.unlinkSync(path.join(cwd, rel)); report.removed.push(rel); };
342
+ // listed before their sources are removed
343
+ const generated = opts.skipGenerate ? [] : generatedFiles(cwd);
344
+
345
+ for (const rel of templateFiles(template)) {
346
+ const current = projectText(cwd, rel, targets);
347
+ if (current === null) continue;
348
+ if (rel === 'AGENTS.md' || rel === 'CLAUDE.md') {
349
+ const rest = rel === 'AGENTS.md' ? current.replace(MARKERS, () => '') : current.replace(/^@AGENTS\.md[ \t]*\n?/m, '');
350
+ if (!rest.trim()) remove(rel);
351
+ else if (rest !== current) { fs.writeFileSync(path.join(cwd, rel), rest.replace(/\n+$/, '\n')); report.removed.push(`${rel} (the kit's part)`); }
352
+ continue;
353
+ }
354
+ if (current === kitText(template, rel, values, targets)) remove(rel); else report.kept.push(rel);
355
+ }
356
+ for (const [rel, text] of generated) {
357
+ const current = readIf(path.join(cwd, rel));
358
+ if (current === null) continue;
359
+ if (current === text) remove(rel); else report.kept.push(`${rel} (also has your own settings; remove the kit's entries by hand)`);
360
+ }
361
+ for (const link of ['.claude/skills', '.kiro/skills']) {
362
+ const p = path.join(cwd, link);
363
+ if (isLink(p) && fs.readlinkSync(p) === '../.agents/skills') { fs.unlinkSync(p); report.removed.push(link); }
364
+ }
365
+ // folders left empty (rmdir refuses non-empty ones)
366
+ const dirs = [...new Set(report.removed.map(r => path.dirname(r.split(' (')[0])))].sort((a, b) => b.length - a.length);
367
+ for (let d of dirs) {
368
+ for (; d && d !== '.'; d = path.dirname(d)) { try { fs.rmdirSync(path.join(cwd, d)); } catch { break; } }
369
+ }
370
+
371
+ // git hooks
372
+ const scripts = pkg.scripts || {};
373
+ const postinstall = scripts.postinstall === HOOKS_CMD ? undefined : (scripts.postinstall || '').replace(` && (${HOOKS_CMD})`, '') || undefined;
374
+ if (postinstall !== scripts.postinstall) {
375
+ if (postinstall) scripts.postinstall = postinstall; else delete scripts.postinstall;
376
+ fs.writeFileSync(path.join(cwd, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`);
377
+ report.removed.push('package.json postinstall (git hooks)');
378
+ }
379
+ try { if (git(cwd, 'config', 'core.hooksPath') === '.githooks') git(cwd, 'config', '--unset', 'core.hooksPath'); } catch {}
380
+
381
+ report.left.push('.gitignore lines for .env files and .ai/ (they keep secrets and local evidence out of git)');
382
+ if (scripts.typecheck === 'tsc --noEmit') report.left.push('the "typecheck" script in package.json');
383
+ return { report, from };
384
+ }
198
385
 
199
386
  function printSummary({ report, values, tools, generated, generateError }, log = console.log) {
200
387
  log(`agentic-mobile-kit installed for ${values.APP_NAME} (React Native ${values.RN_VERSION}, ${values.PM}).`);
@@ -211,4 +398,23 @@ function printSummary({ report, values, tools, generated, generateError }, log =
211
398
  if (tools.includes('codex')) log(' 5. Codex users: open the project in Codex once and approve its hooks (they stay off until approved).');
212
399
  }
213
400
 
214
- module.exports = { init, printSummary, InitError, TOOLS };
401
+ function printSync({ report, from, to, generated, generateError }, log = console.log) {
402
+ log(`agentic-mobile-kit updated from ${from} to ${to}.`);
403
+ const lines = [
404
+ ['updated', report.updated], ['added', report.added], ['removed', report.removed],
405
+ ['merged with your changes', report.merged], ['CONFLICTS, resolve the <<<<<<< markers', report.conflicts], ['left alone', report.kept],
406
+ ];
407
+ for (const [label, files] of lines) if (files.length) log(` ${label}: ${files.join(', ')}`);
408
+ if (!Object.values(report).some(a => a.length)) log(' Nothing to change.');
409
+ if (!generated) log(` ! could not generate tool configs; run: npx -y ${RULESYNC} generate\n${generateError.replace(/^/gm, ' ')}`);
410
+ log('\nReview it with "git diff", run the checks, then commit on a branch and open a PR.');
411
+ }
412
+
413
+ function printUninstall({ report }, log = console.log) {
414
+ log(`agentic-mobile-kit removed: ${report.removed.length} files and sections.`);
415
+ if (report.kept.length) log(` kept because you changed them: ${report.kept.join(', ')}`);
416
+ for (const l of report.left) log(` left in place: ${l}`);
417
+ log('\nReview it with "git status" and "git diff", then commit. Undo it with git if you change your mind.');
418
+ }
419
+
420
+ module.exports = { init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS, KIT_VERSION };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentic-mobile-kit",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "description": "One setup for AI-assisted mobile development that works the same in Claude Code, Codex, Cursor, OpenCode, Kiro and Antigravity. Early development.",
5
5
  "license": "MIT",
6
6
  "author": "prakashpro1",
@@ -1,4 +1,4 @@
1
- <!-- KIT:START agentic-mobile-kit (edit outside these markers; the kit updates what's inside) -->
1
+ <!-- KIT:START agentic-mobile-kit {{KIT_VERSION}} (edit outside these markers; the kit updates what's inside) -->
2
2
  # {{APP_NAME}}: instructions for AI agents
3
3
 
4
4
  Read by Claude Code (through CLAUDE.md), Codex, Cursor, OpenCode, Kiro and Antigravity. Keep it short; details live in `docs/ai/`.