agentic-mobile-kit 0.7.18 → 0.14.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 (76) hide show
  1. package/README.md +20 -5
  2. package/bin/cli.js +5 -3
  3. package/lib/doctor.js +31 -5
  4. package/lib/init.js +19 -24
  5. package/lib/menu.js +3 -3
  6. package/package.json +1 -1
  7. package/stacks/react-native/expo/.eas/workflows/pr-preview.yml +54 -0
  8. package/stacks/react-native/expo/.rulesync/permissions.jsonc +6 -0
  9. package/stacks/react-native/expo/AGENTS.md +33 -17
  10. package/stacks/react-native/expo/docs/amk/expo.md +22 -1
  11. package/stacks/react-native/template/.agents/skills/m-bugfix/SKILL.md +14 -12
  12. package/stacks/react-native/template/.agents/skills/m-change/SKILL.md +3 -2
  13. package/stacks/react-native/template/.agents/skills/m-continue/SKILL.md +6 -4
  14. package/stacks/react-native/template/.agents/skills/m-explore/SKILL.md +2 -2
  15. package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +34 -27
  16. package/stacks/react-native/template/.agents/skills/m-feature/build.md +35 -0
  17. package/stacks/react-native/template/.agents/skills/m-feature/plan.md +43 -0
  18. package/stacks/react-native/template/.agents/skills/m-learn/SKILL.md +3 -1
  19. package/stacks/react-native/template/.agents/skills/m-onboard/SKILL.md +10 -5
  20. package/stacks/react-native/template/.agents/skills/m-pause/SKILL.md +2 -0
  21. package/stacks/react-native/template/.agents/skills/m-prototype/SKILL.md +8 -9
  22. package/stacks/react-native/template/.agents/skills/m-release/SKILL.md +5 -4
  23. package/stacks/react-native/template/.agents/skills/m-report/SKILL.md +25 -0
  24. package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +8 -4
  25. package/stacks/react-native/template/.agents/skills/m-test/SKILL.md +24 -0
  26. package/stacks/react-native/template/.agents/skills/m-test/agents/openai.yaml +3 -0
  27. package/stacks/react-native/template/.githooks/pre-commit +12 -0
  28. package/stacks/react-native/template/.github/pull_request_template.md +7 -1
  29. package/stacks/react-native/template/.github/workflows/amk-ai-deps.yml +90 -0
  30. package/stacks/react-native/template/.github/workflows/amk-ai-review.yml +82 -0
  31. package/stacks/react-native/template/.github/workflows/amk-kit-update.yml +95 -0
  32. package/stacks/react-native/template/.github/workflows/amk-ready.yml +39 -0
  33. package/stacks/react-native/template/.github/workflows/ci.yml +79 -13
  34. package/stacks/react-native/template/.github/workflows/e2e.yml +10 -1
  35. package/stacks/react-native/template/.rulesync/hooks.jsonc +3 -1
  36. package/stacks/react-native/template/.rulesync/permissions.jsonc +6 -0
  37. package/stacks/react-native/template/.rulesync/subagents/m-design-reviewer.md +22 -0
  38. package/stacks/react-native/template/.rulesync/subagents/m-device-checker.md +2 -1
  39. package/stacks/react-native/template/.rulesync/subagents/m-reviewer.md +4 -2
  40. package/stacks/react-native/template/.rulesync/subagents/m-spec-writer.md +15 -0
  41. package/stacks/react-native/template/.rulesync/subagents/m-tester.md +23 -0
  42. package/stacks/react-native/template/AGENTS.md +26 -10
  43. package/stacks/react-native/template/codemagic.yaml +82 -1
  44. package/stacks/react-native/template/docs/amk/codemagic.md +8 -0
  45. package/stacks/react-native/template/docs/amk/design-system.md +15 -0
  46. package/stacks/react-native/template/docs/amk/glossary.md +12 -0
  47. package/stacks/react-native/template/docs/amk/react-native.md +22 -1
  48. package/stacks/react-native/template/docs/amk/team-process.md +33 -1
  49. package/stacks/react-native/template/rulesync.jsonc +1 -1
  50. package/stacks/react-native/template/scripts/amk/ai-job.js +106 -0
  51. package/stacks/react-native/template/scripts/amk/autopilot.js +837 -0
  52. package/stacks/react-native/template/scripts/amk/baseline.js +19 -7
  53. package/stacks/react-native/template/scripts/amk/ci-scope.js +59 -0
  54. package/stacks/react-native/template/scripts/amk/coverage.js +111 -0
  55. package/stacks/react-native/template/scripts/amk/guard.js +64 -1
  56. package/stacks/react-native/template/scripts/amk/handoff-check.js +87 -14
  57. package/stacks/react-native/template/scripts/amk/issue.js +31 -0
  58. package/stacks/react-native/template/scripts/amk/metrics.js +164 -0
  59. package/stacks/react-native/template/scripts/amk/pr.js +244 -0
  60. package/stacks/react-native/template/scripts/amk/redact.js +57 -0
  61. package/stacks/react-native/template/scripts/amk/release-build.sh +14 -0
  62. package/stacks/react-native/template/scripts/amk/report.js +48 -11
  63. package/stacks/react-native/template/scripts/amk/rn-check.js +204 -47
  64. package/stacks/react-native/template/scripts/amk/shots.js +131 -0
  65. package/stacks/react-native/template/scripts/amk/specs.js +717 -34
  66. package/stacks/react-native/template/scripts/amk/tool-configs.js +41 -0
  67. package/stacks/react-native/template/scripts/amk/verify.sh +127 -23
  68. package/stacks/react-native/template/specs/_templates/design.md +25 -3
  69. package/stacks/react-native/template/specs/_templates/flow.yaml +5 -1
  70. package/stacks/react-native/template/specs/_templates/plan.md +54 -0
  71. package/stacks/react-native/template/specs/_templates/progress.md +1 -1
  72. package/stacks/react-native/template/specs/_templates/questions.md +29 -0
  73. package/stacks/react-native/template/specs/_templates/requirements.md +40 -0
  74. package/stacks/react-native/template/specs/_templates/tasks.md +2 -2
  75. package/stacks/react-native/template/specs/_templates/test-report.md +25 -0
  76. package/stacks/react-native/template/.github/workflows/ios.yml +0 -41
@@ -5,13 +5,16 @@
5
5
  // lint ESLint errors in the files changed since the base, compared with those files at the base
6
6
  // typecheck TypeScript errors (file, code, message), compared with a type check of the base
7
7
  // test failing Jest tests and test files, compared with a test run of the base
8
- // The base: AMK_BASE, else the first of the remote's default branch, origin/main, origin/master, main and master
9
- // whose merge base with HEAD has a package.json (a default branch left at an old first commit isn't the app's base).
8
+ // The base: AMK_BASE; on a release branch (release/…), the last release's tag (v…); else the first of the remote's
9
+ // default branch, origin/main, origin/master, main and master whose merge base with HEAD has a package.json (a default
10
+ // branch left at an old first commit isn't the app's base).
10
11
  // Its merge base is checked out once into a temporary git worktree that shares node_modules, and its results are kept
11
12
  // for the next run.
13
+ // `test --related` runs only the Jest tests related to the files changed since the base (Jest's --changedSince, which
14
+ // follows the imports), for each task while building; the whole suite runs before a pull request.
12
15
  // `base` prints the base, for reviews of a branch's changes. `staged <files>` is the pre-commit hook's lint: it passes
13
16
  // when the files have no ESLint error they didn't have at HEAD, and exits with 3 when it can't find ESLint's CLI.
14
- // Usage: node scripts/amk/baseline.js lint|typecheck|test|base|staged <files>
17
+ // Usage: node scripts/amk/baseline.js lint|typecheck|test [--related]|base|staged <files>
15
18
  'use strict';
16
19
  const fs = require('fs');
17
20
  const os = require('os');
@@ -20,6 +23,7 @@ const crypto = require('crypto');
20
23
  const { spawnSync, execFileSync } = require('child_process');
21
24
 
22
25
  const check = process.argv[2];
26
+ const related = check === 'test' && process.argv.includes('--related');
23
27
  if (!['lint', 'typecheck', 'test', 'base', 'staged'].includes(check)) {
24
28
  console.error('usage: node scripts/amk/baseline.js lint|typecheck|test|base|staged <files>');
25
29
  process.exit(2);
@@ -49,12 +53,12 @@ const minus = (a, b) => {
49
53
  });
50
54
  };
51
55
 
52
- // the package.json script, through pm-run.sh, in dir (the app, or the base's worktree)
53
- function runScript(dir) {
56
+ // the package.json script, through pm-run.sh, in dir (the app, or the base's worktree), with extra arguments for it
57
+ function runScript(dir, extra = []) {
54
58
  fs.mkdirSync(scratch, { recursive: true });
55
59
  const json = path.join(scratch, `jest-${hash(dir)}.json`);
56
60
  fs.rmSync(json, { force: true });
57
- const r = spawnSync('sh', [path.join(root, 'scripts/amk/pm-run.sh'), check, ...(jest ? ['--json', `--outputFile=${json}`] : [])],
61
+ const r = spawnSync('sh', [path.join(root, 'scripts/amk/pm-run.sh'), check, ...extra, ...(jest ? ['--json', `--outputFile=${json}`] : [])],
58
62
  { cwd: dir, encoding: 'utf8', env: { ...process.env, CI: 'true' }, maxBuffer: 2 ** 28 });
59
63
  return { code: r.status, out: `${r.stdout || ''}${r.stderr || ''}`, json, dir };
60
64
  }
@@ -84,6 +88,10 @@ const hasApp = sha => Boolean(sha && git('rev-parse', '--verify', '--quiet', `${
84
88
  // { ref, note }: the note says when the remote's default branch was passed over
85
89
  function baseRef() {
86
90
  if (process.env.AMK_BASE) return { ref: process.env.AMK_BASE, note: '' };
91
+ // a release branch is compared with the last release, not with main: what main gained since that release is the
92
+ // release's change, so a test that broke on main since then is new
93
+ const tag = /^release\//.test(git('symbolic-ref', '--quiet', '--short', 'HEAD')) && git('describe', '--tags', '--abbrev=0', '--match', 'v*', 'HEAD');
94
+ if (tag && hasApp(tag)) return { ref: tag, note: '' };
87
95
  const remoteDefault = git('symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD');
88
96
  const refs = [...new Set([remoteDefault, 'origin/main', 'origin/master', 'main', 'master'])]
89
97
  .filter(r => r && git('rev-parse', '--verify', '--quiet', `${r}^{commit}`));
@@ -222,8 +230,12 @@ if (check === 'staged') {
222
230
  process.exit(1);
223
231
  }
224
232
 
225
- const now = runScript(root);
233
+ // --related: the tests of the files changed since where this branch left the base (the whole suite without one)
234
+ const since = related && jest && (() => { const f = baseRef(); return f && git('merge-base', 'HEAD', f.ref); })();
235
+ const now = runScript(root, since ? [`--changedSince=${since}`] : []);
226
236
  process.stdout.write(now.out);
237
+ if (related) console.log(since ? `test: only the tests related to the files changed since ${since.slice(0, 7)} (verify.sh quick without --related runs them all)`
238
+ : `test: every test ran, as ${jest ? 'there\'s no base branch to compare with' : 'the test script isn\'t Jest'}`);
227
239
  if (now.code === 0) process.exit(0);
228
240
 
229
241
  const found = baseRef();
@@ -0,0 +1,59 @@
1
+ #!/usr/bin/env node
2
+ // CI by what a change touches (.github/workflows/ci.yml), so every check it needs runs and none it doesn't:
3
+ // node scripts/amk/ci-scope.js <base> the jobs the change since <base> calls for, as GitHub Actions outputs:
4
+ // code (the tests and the Android build) and native (the iOS build). Only specs or docs: neither. Native files
5
+ // (ios/, android/, package.json and lockfiles, an Expo app's config, config plugins and patches, the CI workflow
6
+ // itself): both. Anything else: code. A change it can't read (a first push, a base it can't find): both
7
+ // node scripts/amk/ci-scope.js verdict ci.yml's summary job ("checks", the one branch protection requires): the jobs'
8
+ // results, from NEEDS (toJSON(needs)), fail it when one failed or was cancelled, or was skipped though the change
9
+ // called for it
10
+ 'use strict';
11
+ const { execFileSync } = require('child_process');
12
+
13
+ const DOCS = /^(docs|specs)\/|\.md$|^\.github\/(ISSUE_TEMPLATE\/|pull_request_template\.md$)|^(LICENSE|CODEOWNERS|\.github\/CODEOWNERS)$/i;
14
+ const NATIVE = /^(ios|android|plugins|patches)\/|^(package\.json|package-lock\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|app\.json|app\.config\.(js|ts|json)|eas\.json|react-native\.config\.js|Gemfile(\.lock)?|\.github\/workflows\/ci\.yml)$/;
15
+
16
+ function scope(files) {
17
+ if (!files) return { code: true, native: true, why: 'the change couldn\'t be read, so everything runs' };
18
+ if (!files.length || files.every(f => DOCS.test(f))) return { code: false, native: false, why: `only specs or docs (${files.length} file(s))` };
19
+ const native = files.filter(f => NATIVE.test(f));
20
+ return { code: true, native: native.length > 0, why: native.length ? `native files: ${native.slice(0, 5).join(', ')}${native.length > 5 ? ', …' : ''}` : 'code, no native files' };
21
+ }
22
+
23
+ // the jobs' results: a failure, a cancel, or a skip the change didn't allow
24
+ function verdict(needs) {
25
+ const out = (needs.scope && needs.scope.outputs) || {};
26
+ const wanted = { tests: out.code === 'true', android: out.code === 'true', ios: out.native === 'true' };
27
+ const problems = [];
28
+ const lines = [];
29
+ for (const [job, r] of Object.entries(needs)) {
30
+ const result = r.result;
31
+ lines.push(`${job}: ${result}`);
32
+ if (['failure', 'cancelled'].includes(result)) problems.push(`${job} ${result === 'failure' ? 'failed' : 'was cancelled'}`);
33
+ else if (result === 'skipped' && (job === 'scope' || job === 'basics' || wanted[job])) problems.push(`${job} was skipped, though this change calls for it`);
34
+ }
35
+ return { ok: !problems.length, problems, lines };
36
+ }
37
+
38
+ module.exports = { scope, verdict, DOCS, NATIVE };
39
+
40
+ if (require.main === module) {
41
+ const [arg] = process.argv.slice(2);
42
+ if (arg === 'verdict') {
43
+ let needs = {};
44
+ try { needs = JSON.parse(process.env.NEEDS || '{}'); } catch {}
45
+ const v = verdict(needs);
46
+ console.log(v.lines.join('\n'));
47
+ if (!v.ok) { console.log(`✗ ${v.problems.join('; ')}`); process.exit(1); }
48
+ console.log('✓ every job this change calls for passed');
49
+ } else {
50
+ let files = null;
51
+ // a branch's first push has no "before" (all zeros): everything runs
52
+ if (arg && !/^0+$/.test(arg)) {
53
+ try { files = execFileSync('git', ['diff', '--name-only', `${arg}...HEAD`], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).split('\n').filter(Boolean); } catch {}
54
+ }
55
+ const s = scope(files);
56
+ console.error(`scope: ${s.why}`);
57
+ console.log(`code=${s.code}\nnative=${s.native}`);
58
+ }
59
+ }
@@ -0,0 +1,111 @@
1
+ #!/usr/bin/env node
2
+ // Coverage floors: a check that tests weren't deleted or weakened. .amk-coverage, which the project commits, holds the
3
+ // lowest each coverage measure of the Jest tests may go (statements, branches, functions and lines, in percent), and the
4
+ // slack: how many points under its floor a measure may drop and still pass. Without the file there's no check.
5
+ // node scripts/amk/coverage.js write a coverage run of the tests as they are writes .amk-coverage
6
+ // node scripts/amk/coverage.js check runs them with Jest's --coverageThreshold set from it
7
+ // node scripts/amk/coverage.js raise raises the floors to the coverage now, where it's higher
8
+ // node scripts/amk/coverage.js lower --reason "<why>" lowers them to the coverage now, and records why
9
+ // Floors are the coverage rounded up, and come down only with a reason, which the file keeps. The verdict is the coverage
10
+ // alone: failing tests are verify.sh quick's to judge, against the base branch.
11
+ 'use strict';
12
+ const fs = require('fs');
13
+ const os = require('os');
14
+ const path = require('path');
15
+ const { spawnSync } = require('child_process');
16
+
17
+ const FILE = '.amk-coverage';
18
+ const MEASURES = ['statements', 'branches', 'functions', 'lines'];
19
+ const [cmd, ...args] = process.argv.slice(2);
20
+ const root = process.cwd();
21
+ const read = f => { try { return fs.readFileSync(f, 'utf8').replace(/\r\n/g, '\n'); } catch { return null; } };
22
+ const up = n => Math.min(100, Math.ceil(n));
23
+
24
+ // the floors file: its values ({ statements: 73, …, slack: 2 }) and its text
25
+ function floors() {
26
+ const text = read(path.join(root, FILE));
27
+ if (text === null) return null;
28
+ const values = {};
29
+ for (const l of text.split('\n')) {
30
+ const m = /^\s*([a-z]+)\s+(\d+(?:\.\d+)?)\s*$/.exec(l);
31
+ if (m) values[m[1]] = Number(m[2]);
32
+ }
33
+ return { values, text };
34
+ }
35
+
36
+ // a coverage run of the app's test script, with these extra arguments: each measure's percentage, or why there's none
37
+ function coverage(extra = []) {
38
+ let pkg = {};
39
+ try { pkg = JSON.parse(read(path.join(root, 'package.json'))); } catch {}
40
+ if (!/\bjest\b/.test((pkg.scripts || {}).test || '')) return { why: 'the test script isn\'t Jest' };
41
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amk-coverage-'));
42
+ try {
43
+ const r = spawnSync('sh', [path.join(root, 'scripts/amk/pm-run.sh'), 'test', '--coverage', '--coverageReporters=json-summary',
44
+ '--coverageReporters=text-summary', `--coverageDirectory=${dir}`, ...extra], { cwd: root, encoding: 'utf8', env: { ...process.env, CI: 'true' }, maxBuffer: 2 ** 28 });
45
+ let total;
46
+ try { total = JSON.parse(fs.readFileSync(path.join(dir, 'coverage-summary.json'), 'utf8')).total; } catch {
47
+ return { why: `Jest wrote no coverage report: ${`${r.stderr || ''}${r.stdout || ''}`.trim().split('\n').pop()}` };
48
+ }
49
+ // "Unknown" for a measure with nothing to count (no branches at all)
50
+ return { pct: Object.fromEntries(MEASURES.map(m => [m, Number((total[m] || {}).pct) || 0])) };
51
+ } finally {
52
+ fs.rmSync(dir, { recursive: true, force: true });
53
+ }
54
+ }
55
+
56
+ // the floors file with these values, and a line about the change
57
+ function save(f, values, note) {
58
+ let text = f.text;
59
+ for (const [k, v] of Object.entries(values)) text = text.replace(new RegExp(`^(\\s*${k}\\s+)\\d+(?:\\.\\d+)?(\\s*)$`, 'm'), `$1${v}$2`);
60
+ fs.writeFileSync(path.join(root, FILE), note ? `${text.replace(/\n*$/, '\n')}${note}\n` : text);
61
+ }
62
+
63
+ function main() {
64
+ if (!['write', 'check', 'raise', 'lower'].includes(cmd)) {
65
+ const head = fs.readFileSync(process.argv[1], 'utf8').split('\n').slice(1);
66
+ console.log(head.slice(0, head.findIndex(l => !l.startsWith('//'))).map(l => l.replace(/^\/\/ ?/, '')).join('\n'));
67
+ return 2;
68
+ }
69
+ const f = floors();
70
+ if (cmd === 'write') {
71
+ if (f) { console.error(`coverage: ${FILE} is there already: raise or lower its floors instead`); return 1; }
72
+ const run = coverage();
73
+ if (run.why) { console.error(`coverage: ${run.why}`); return 1; }
74
+ fs.writeFileSync(path.join(root, FILE), [
75
+ '# Coverage floors: node scripts/amk/coverage.js check fails when a measure of the Jest tests drops more than the slack',
76
+ '# below its floor, in percent. Floors only rise (coverage.js raise), or come down with a reason (coverage.js lower',
77
+ '# --reason "<why>"), which is kept here.',
78
+ ...MEASURES.map(m => `${m} ${up(run.pct[m])}`), 'slack 2', '',
79
+ ].join('\n'));
80
+ console.log(`${FILE}: ${MEASURES.map(m => `${m} ${up(run.pct[m])}`).join(', ')}, slack 2. Commit it.`);
81
+ return 0;
82
+ }
83
+ if (!f) {
84
+ console.log(`coverage: no ${FILE}, so nothing to check (node scripts/amk/coverage.js write makes one)`);
85
+ return cmd === 'check' ? 0 : 1;
86
+ }
87
+ const missing = MEASURES.filter(m => !(m in f.values));
88
+ if (missing.length) { console.error(`coverage: ${FILE} has no floor for ${missing.join(', ')}: add it, or write the file again`); return 1; }
89
+ const slack = f.values.slack || 0;
90
+ if (cmd === 'check') {
91
+ const min = Object.fromEntries(MEASURES.map(m => [m, Math.max(0, f.values[m] - slack)]));
92
+ const run = coverage([`--coverageThreshold=${JSON.stringify({ global: min })}`]);
93
+ if (run.why) { console.error(`coverage: ${run.why}`); return 1; }
94
+ const low = MEASURES.filter(m => run.pct[m] < min[m]);
95
+ console.log(`coverage: ${MEASURES.map(m => `${m} ${run.pct[m]}% (floor ${f.values[m]})`).join(', ')}, slack ${slack}`);
96
+ for (const m of low) console.log(` ✗ ${m} ${run.pct[m]}% is more than ${slack} points under its floor of ${f.values[m]}: tests were deleted or weakened, or new code has none`);
97
+ return low.length ? 1 : 0;
98
+ }
99
+ const reason = args.includes('--reason') ? (args[args.indexOf('--reason') + 1] || '').trim() : '';
100
+ if (cmd === 'lower' && !reason) { console.error('coverage: lower needs --reason "<why>", which the floors file keeps'); return 2; }
101
+ const run = coverage();
102
+ if (run.why) { console.error(`coverage: ${run.why}`); return 1; }
103
+ const next = Object.fromEntries(MEASURES.map(m => [m, cmd === 'raise' ? Math.max(f.values[m], up(run.pct[m])) : Math.min(f.values[m], up(run.pct[m]))]));
104
+ const changes = MEASURES.filter(m => next[m] !== f.values[m]).map(m => `${m} ${f.values[m]} → ${next[m]}`);
105
+ if (!changes.length) { console.log(`coverage: nothing to ${cmd}: ${MEASURES.map(m => `${m} ${run.pct[m]}%`).join(', ')}`); return 0; }
106
+ save(f, next, cmd === 'lower' && `# lowered ${new Date().toISOString().slice(0, 10)}, ${changes.join(', ')}: ${reason}`);
107
+ console.log(`${FILE}: ${cmd === 'raise' ? 'raised' : 'lowered'} ${changes.join(', ')}`);
108
+ return 0;
109
+ }
110
+
111
+ process.exitCode = main();
@@ -27,6 +27,22 @@ const paths = [];
27
27
  // rm with a recursive flag and a force flag anywhere before the next ; & | (-rf, -Rf, -r -f, --recursive --force);
28
28
  // a push with --force, -f or a +refspec
29
29
  const destructive = /\brm(?=[^;&|\n]*\s(-[a-zA-Z]*[rR][a-zA-Z]*|--recursive)\b)(?=[^;&|\n]*\s(-[a-zA-Z]*f[a-zA-Z]*|--force)\b)|git\s+reset\s+--hard|git\s+push\s+(.*\s)?((--force|-f)\b|\+\S)|git\s+clean\s+-[a-z]*f|--no-verify|xcrun\s+simctl\s+erase/;
30
+ // git commands that throw away work for good: every uncommitted change (a checkout or restore of the whole tree, a forced
31
+ // checkout or switch), saved stashes, a branch with commits merged nowhere. Undoing one file's edit stays allowed
32
+ const discards = c => c.split(/&&|\|\||[;&|\n]/).some(s => {
33
+ const m = /\bgit\s+(checkout|restore|switch|stash|branch)\b(.*)/.exec(s);
34
+ if (!m) return false;
35
+ const args = m[2].trim().split(/\s+/).filter(Boolean);
36
+ const short = args.filter(a => /^-[a-zA-Z]+$/.test(a)).join('');
37
+ const has = (letter, long) => short.includes(letter) || args.includes(long);
38
+ const everything = args.some(a => /^['"]?(\.|\.\/|:\/|\*)['"]?$/.test(a));
39
+ if (m[1] === 'checkout') return everything || has('f', '--force');
40
+ // --staged alone only unstages: the changes stay
41
+ if (m[1] === 'restore') return everything && (!has('S', '--staged') || has('W', '--worktree'));
42
+ if (m[1] === 'switch') return has('f', '--force') || args.includes('--discard-changes');
43
+ if (m[1] === 'stash') return args[0] === 'drop' || args[0] === 'clear';
44
+ return short.includes('D') || (has('d', '--delete') && has('f', '--force'));
45
+ });
30
46
  // example files (.env.example, .env.local.example, .env.sample, .env.template) aren't secrets
31
47
  const secretFile = /(^|[\s/'"=])\.env(?![\w.-]*\.(?:example|sample|template)(?=$|[\s'";|&)]))(\.[\w.-]+)?(?=$|[\s'";|&)])|\.(keystore|jks|p8|p12|mobileprovision)\b/;
32
48
  // the project's own secret files: .amk-secrets lists them, one path from the project root per line (a folder ends in /)
@@ -37,10 +53,57 @@ const secret = s => secretFile.test(s) || listed.some(p => s.includes(p));
37
53
  const block = reason => { process.stderr.write(`Blocked by scripts/amk/guard.js: ${reason}\n`); process.exit(2); };
38
54
  for (const c of commands) {
39
55
  // a command that only mentions one, in a commit message, is blocked too: the message can come from a file instead
40
- if (destructive.test(c)) block(`destructive command: ${c}${/git\s+commit\b/.test(c) ? '\n(Only in the commit message? Write it to a file and use git commit -F <file>.)' : ''}`);
56
+ const inMessage = /git\s+commit\b/.test(c) ? '\n(Only in the commit message? Write it to a file and use git commit -F <file>.)' : '';
57
+ if (destructive.test(c)) block(`destructive command: ${c}${inMessage}`);
58
+ if (discards(c)) {
59
+ block(`this throws away work that can't be brought back (uncommitted changes, stashes or unmerged commits): ${c}\n`
60
+ + `Ask the user first, or keep the work: git stash, or a commit. To undo your own edit to a file: git checkout -- <that file>.${inMessage}`);
61
+ }
41
62
  if (secret(c)) block(`shell access to a secret file: ${c}`);
42
63
  }
43
64
  for (const p of paths) {
44
65
  if (secret(p)) block(`access to a secret file: ${p}`);
45
66
  }
67
+
68
+ // An unattended build (scripts/amk/autopilot.js sets AMK_AUTOPILOT) works under your GitHub login, so it never does what
69
+ // only a person should: call GitHub's API directly, approve a pull request or request changes, merge without
70
+ // auto-merge, touch the trigger labels, push anything but a feature/ or fix/ branch by name, or change the guardrails
71
+ // (autopilot.js and the pre-commit hook hold the same list)
72
+ if (process.env.AMK_AUTOPILOT) {
73
+ const GUARDRAILS = /^(?:scripts\/amk\/|\.rulesync\/|\.githooks\/|\.github\/workflows\/|\.agents\/|\.claude\/|\.codex\/|(?:\.github\/|docs\/)?CODEOWNERS$|AGENTS\.md$|CLAUDE\.md$|rulesync\.jsonc$|\.amk-(?:coverage|size-caps|secrets)$)/;
74
+ const roots = [root, fs.realpathSync(root)];
75
+ const rel = p => roots.map(r => path.relative(r, path.resolve(r, p)).replace(/\\/g, '/')).find(x => !x.startsWith('..')) || '';
76
+ // relative to the project, or as written without leading ../ (after a cd the guard doesn't follow)
77
+ const kept = p => { const f = String(p).replace(/^['"]|['"]$/g, ''); return GUARDRAILS.test(rel(f)) || GUARDRAILS.test(f.replace(/^(?:\.{1,2}\/)+/, '')); };
78
+ const refuse = (what, c) => block(`an unattended build ${what}: ${c.trim()}`);
79
+ const writes = /^\s*(?:cp|mv|rm|rmdir|ln|chmod|chown|truncate|touch|mkdir|install|tee|dd|patch|sed\s+(?:-[a-zA-Z]*i|--in-place)|perl\s+-[a-zA-Z]*i|git\s+(?:apply|checkout|restore|rm|mv))\b/;
80
+ const edits = /^(Edit|Write|MultiEdit|NotebookEdit|apply_patch|write_to_file|replace_file_content|multi_replace_file_content|sed_file|notebook_edit)$/;
81
+ if (edits.test(payload.tool_name || '') && paths.some(kept)) refuse('doesn\'t change the kit\'s guardrails (its scripts, hooks and tool settings, the workflows, the agents\' instructions)', paths.join(' '));
82
+ for (const c of commands) {
83
+ for (const f of c.matchAll(/^\*\*\* (?:Add|Update|Delete) File: (.+)$|^\*\*\* Move to: (.+)$/gm)) {
84
+ if (kept((f[1] || f[2]).trim())) refuse('doesn\'t change the kit\'s guardrails (its scripts, hooks and tool settings, the workflows, the agents\' instructions)', f[0]);
85
+ }
86
+ // a redirection such as 2>&1 isn't a command separator
87
+ for (const s of c.replace(/\d*>&\d*-?/g, ' ').split(/&&|\|\||[;&|\n]/)) {
88
+ if (/\bgh\s+api\b/.test(s)) refuse('doesn\'t call GitHub\'s API directly', s);
89
+ if (/\bgh\s+pr\s+review\b/.test(s)) refuse('doesn\'t approve pull requests or request changes: a person does', s);
90
+ if (/\bgh\s+pr\s+merge\b/.test(s) && !/\s--auto\b/.test(s)) refuse('merges only through auto-merge, after a person approves', s);
91
+ if (/\bgh\b/.test(s) && /\bamk-(?:ready|fix)\b/.test(s)) refuse('doesn\'t add or remove the amk-ready or amk-fix labels: a person does', s);
92
+ const push = /\bgit\s+push\b(.*)/.exec(s);
93
+ if (push) {
94
+ // its words, without redirections (2>/dev/null, > out.txt)
95
+ const words = push[1].replace(/\d*>{1,2}\s*\S+|<\s*\S+/g, ' ').trim().split(/\s+/).filter(Boolean);
96
+ const refs = words.filter(w => !w.startsWith('-')).slice(1);
97
+ if (words.some(w => w.startsWith('-') && !/^(-u|--set-upstream|-q|--quiet|-v|--verbose|--progress|--no-progress|--porcelain)$/.test(w))
98
+ || !refs.length || refs.some(r => !/^(?:feature|fix)\/[A-Za-z0-9._/-]+$/.test(r))) {
99
+ refuse('pushes only its own feature/ or fix/ branch, named (git push -u origin feature/<id>)', s);
100
+ }
101
+ }
102
+ const targets = [...s.matchAll(/>{1,2}\s*([^\s;&|<>]+)/g)].map(m => m[1]);
103
+ if (targets.some(kept) || (writes.test(s) && s.trim().split(/\s+/).slice(1).some(kept))) {
104
+ refuse('doesn\'t change the kit\'s guardrails (its scripts, hooks and tool settings, the workflows, the agents\' instructions)', s);
105
+ }
106
+ }
107
+ }
108
+ }
46
109
  process.exit(0);
@@ -1,31 +1,104 @@
1
1
  #!/usr/bin/env node
2
- // Agent stop hook. If code changed but the active spec's handoff block wasn't updated, ask the agent to update it.
2
+ // Agent hooks on the handoff in specs/<id>/progress.md.
3
+ // Stop: if code changed but the active spec's handoff block wasn't updated, ask the agent to update it. In an unattended
4
+ // build (scripts/amk/autopilot.js sets AMK_AUTOPILOT), it also keeps the feature of the branch going: a stop while it
5
+ // isn't done or blocked goes back to the agent, unless .amk/build/STOP is there, or the agent stops again with nothing
6
+ // changed since its last stop (no commit, no task ticked, the same next step), which autopilot.js treats as a stall.
7
+ // Both: a feature marked done whose requirements never reached the living spec is asked to merge them first.
8
+ // SessionStart, after a compaction: the active spec's handoff, its next task and the definition of done, read fresh from
9
+ // the files, so nothing the summary lost is missing.
3
10
  const fs = require('fs');
4
11
  const path = require('path');
5
12
  const { execSync } = require('child_process');
6
13
  // the project this script is in (scripts/amk/): the agent may have moved into a subfolder
7
14
  const root = path.join(__dirname, '..', '..');
15
+ const read = f => { try { return fs.readFileSync(path.join(root, f), 'utf8').replace(/\r\n/g, '\n'); } catch { return null; } };
16
+ // (only the end trimmed: git status's lines start with a space)
17
+ const sh = cmd => { try { return execSync(cmd, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).replace(/\s+$/, ''); } catch { return ''; } };
8
18
 
9
19
  let payload = {};
10
20
  try { payload = JSON.parse(fs.readFileSync(0, 'utf8')); } catch {}
11
- if (payload.stop_hook_active) process.exit(0); // already reminded once; don't loop
21
+ const unattended = Boolean(process.env.AMK_AUTOPILOT);
12
22
 
13
23
  // a spec counts only when its handoff says "Status: in progress" (not done, not an untouched template copy)
14
24
  const inProgress = d => {
15
25
  const f = path.join(root, 'specs', d, 'progress.md');
16
26
  return d !== '_templates' && fs.existsSync(f) && /^Status:\s*in progress/im.test(fs.readFileSync(f, 'utf8'));
17
27
  };
18
- const specs = fs.existsSync(path.join(root, 'specs')) ? fs.readdirSync(path.join(root, 'specs')).filter(inProgress) : [];
19
- if (specs.length === 0) process.exit(0); // no spec in progress (quick change, bug fix, or finished work)
20
-
21
- const changed = execSync('git status --porcelain --untracked-files=all', { cwd: root, encoding: 'utf8' }) // every new file, not just its new folder
22
- .split('\n').filter(Boolean).map(l => l.slice(3));
23
- const codeChanged = changed.some(f => !f.startsWith('specs/') && !f.startsWith('.amk/'));
24
- const handoffUpdated = changed.some(f => /^specs\/[^/]+\/progress\.md$/.test(f));
25
-
26
- if (codeChanged && !handoffUpdated) {
27
- process.stderr.write('There are uncommitted code changes, but no specs/<id>/progress.md was updated. ' +
28
- 'Update its handoff block (status, next step, decisions, last checks) before stopping.\n');
29
- process.exit(2);
28
+ const working = fs.existsSync(path.join(root, 'specs')) ? fs.readdirSync(path.join(root, 'specs')).filter(inProgress) : [];
29
+ // the feature of this branch (feature/<id>), where an unattended build works
30
+ const feature = (/^feature\/(.+)$/.exec(sh('git symbolic-ref --quiet --short HEAD')) || [])[1];
31
+ const own = feature && read(`specs/${feature}/progress.md`) !== null ? feature : null;
32
+
33
+ if (payload.hook_event_name === 'SessionStart') {
34
+ const id = own || working[0];
35
+ if (!id) process.exit(0);
36
+ const p = read(`specs/${id}/progress.md`) || '';
37
+ const handoff = (/^## Handoff[\s\S]*?(?=^## |(?![\s\S]))/m.exec(p) || [''])[0].trim();
38
+ const next = ((read(`specs/${id}/tasks.md`) || '').split('\n').find(l => /^\s*- \[ \]/.test(l)) || 'none left').trim();
39
+ const done = (/^## Definition of done\s*$([\s\S]*?)(?=^## |(?![\s\S]))/m.exec(read('AGENTS.md') || '') || [])[1] || '';
40
+ console.log([`After the compaction, from the files as they are now. The work in progress: specs/${id}.`, '', handoff, '',
41
+ `Its next task (specs/${id}/tasks.md): ${next}`, ...(done.trim() ? ['', `Definition of done (AGENTS.md):${done.replace(/\s+$/, '')}`] : []),
42
+ ...(unattended ? ['', 'Nobody is watching this build: record a blocked question under Blocked: in its progress.md instead of asking one.'] : [])].join('\n'));
43
+ process.exit(0);
44
+ }
45
+
46
+ if (payload.stop_hook_active && !unattended) process.exit(0); // already reminded once; don't loop
47
+
48
+ // unattended: the feature's state at this stop (its last commit, ticked tasks and next step)
49
+ const progress = unattended && own ? read(`specs/${own}/progress.md`) || '' : null;
50
+ const state = progress === null ? null : JSON.stringify([sh('git rev-parse HEAD'),
51
+ ((read(`specs/${own}/tasks.md`) || '').match(/^\s*- \[[xX]\]/gm) || []).length, (/^Next step:\s*(.*)$/m.exec(progress) || [])[1] || '']);
52
+
53
+ // code changed without the handoff: asked once (stop_hook_active: the agent goes on because of an earlier ask)
54
+ if ((working.length || progress !== null) && !payload.stop_hook_active) {
55
+ const changed = sh('git status --porcelain --untracked-files=all') // every new file, not just its new folder
56
+ .split('\n').filter(Boolean).map(l => l.slice(3));
57
+ const codeChanged = changed.some(f => !f.startsWith('specs/') && !f.startsWith('.amk/'));
58
+ const handoffUpdated = changed.some(f => /^specs\/[^/]+\/progress\.md$/.test(f));
59
+ if (codeChanged && !handoffUpdated) {
60
+ process.stderr.write('There are uncommitted code changes, but no specs/<id>/progress.md was updated. ' +
61
+ 'Update its handoff block (status, next step, decisions, last checks) before stopping.\n');
62
+ process.exit(2);
63
+ }
64
+ }
65
+
66
+ // a feature marked done whose requirements never reached the living spec (specs.js merge writes "Source: specs/<id>"
67
+ // beside each one it adds or changes): asked once, as the living spec must say what ships
68
+ if (own && !payload.stop_hook_active) {
69
+ const req = read(`specs/${own}/requirements.md`) || '';
70
+ const changes = /^## (?:ADDED|MODIFIED) Requirements/m.test(req) && /^### Requirement:/m.test(req);
71
+ let merged = false;
72
+ try { merged = fs.readdirSync(path.join(root, 'specs', 'current')).some(f => f.endsWith('.md') && (read(`specs/current/${f}`) || '').includes(`Source: specs/${own}\n`)); } catch {}
73
+ if (changes && !merged && /^Status:\s*done/im.test(read(`specs/${own}/progress.md`) || '')) {
74
+ process.stderr.write(`specs/${own} says done, but its requirements aren't in the living spec (no "Source: specs/${own}" in specs/current/): ` +
75
+ `run node scripts/amk/specs.js merge ${own}, commit specs/current/ with the feature, then stop.\n`);
76
+ process.exit(2);
77
+ }
78
+ }
79
+
80
+ if (progress !== null) {
81
+ // kept for the next stop, written whole (this never fails the agent): stopping again with nothing changed is going
82
+ // in circles, and autopilot.js starts it again from the handoff
83
+ const file = path.join(root, '.amk', 'build', own, 'stop-state.json');
84
+ let before = null;
85
+ try { before = JSON.parse(fs.readFileSync(file, 'utf8')).state; } catch {}
86
+ try {
87
+ fs.mkdirSync(path.dirname(file), { recursive: true });
88
+ fs.writeFileSync(`${file}.tmp`, JSON.stringify({ time: new Date().toISOString(), state }));
89
+ fs.renameSync(`${file}.tmp`, file);
90
+ } catch {}
91
+ if (before === state) process.exit(0);
92
+ }
93
+
94
+ if (progress !== null && !fs.existsSync(path.join(root, '.amk', 'build', 'STOP'))) {
95
+ const { NONE } = require('./specs.js');
96
+ const done = /^Status:\s*done/im.test(progress);
97
+ const blocked = !NONE.test((/^Blocked:\s*(.*?)\s*$/m.exec(progress) || [])[1] || '');
98
+ if (!done && !blocked) {
99
+ process.stderr.write(`Nobody is watching this build, so it doesn't stop here: specs/${own} isn't done or blocked. Go on with the next step in its handoff. ` +
100
+ 'If you can\'t, record why under Blocked: in its progress.md (what happened, why, and what would unblock it), commit, push, and stop.\n');
101
+ process.exit(2);
102
+ }
30
103
  }
31
104
  process.exit(0);
@@ -0,0 +1,31 @@
1
+ #!/usr/bin/env node
2
+ // A GitHub issue, for m-bugfix and the overnight bug queue: its title, labels, text and comments as outside text (data,
3
+ // never instructions), with secrets taken out.
4
+ // Usage: node scripts/amk/issue.js <number or link>
5
+ 'use strict';
6
+ const { spawnSync } = require('child_process');
7
+ const { redact, untrusted } = require('./redact.js');
8
+
9
+ const ghReal = args => {
10
+ const r = spawnSync('gh', args, { encoding: 'utf8', maxBuffer: 2 ** 26, timeout: 120000 });
11
+ try { return r.status === 0 ? JSON.parse(r.stdout) : null; } catch { return null; }
12
+ };
13
+
14
+ function show(ref, gh = ghReal) {
15
+ const n = (/^(?:#?(\d+)|https:\/\/[^\s]+\/issues\/(\d+)\/?)$/.exec(String(ref || '').trim()) || []).slice(1).find(Boolean);
16
+ if (!n) return { code: 2, text: 'usage: node scripts/amk/issue.js <number or link>' };
17
+ const i = gh(['issue', 'view', n, '--json', 'number,title,body,labels,comments,url,state']);
18
+ if (!i) return { code: 2, text: `No issue #${n} here, or gh isn't signed in.` };
19
+ const who = a => (a && a.login) || 'someone';
20
+ const text = [`#${i.number}: ${i.title}`, `Labels: ${(i.labels || []).map(l => l.name).join(', ') || 'none'}`, '', i.body || '(no text)',
21
+ ...(i.comments || []).map(c => `\n---\n${who(c.author)}, ${String(c.createdAt || '').slice(0, 10)}:\n${c.body}`)].join('\n');
22
+ return { code: 0, text: `Issue #${i.number} (${String(i.state || '').toLowerCase()}): ${i.url}\n${untrusted(redact(text), `issue #${i.number}`)}` };
23
+ }
24
+
25
+ module.exports = { show };
26
+
27
+ if (require.main === module) {
28
+ const r = show(process.argv[2]);
29
+ (r.code ? console.error : console.log)(r.text);
30
+ process.exitCode = r.code;
31
+ }