yadflow 4.6.0 → 4.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 (96) hide show
  1. package/CHANGELOG.md +170 -0
  2. package/README.md +4 -1
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +167 -15
  5. package/cli/artifact-status.mjs +88 -20
  6. package/cli/build.mjs +1372 -0
  7. package/cli/checkpoint.mjs +2 -2
  8. package/cli/commit.mjs +1 -0
  9. package/cli/dial.mjs +21 -1
  10. package/cli/docs.mjs +6 -1
  11. package/cli/doctor.mjs +133 -26
  12. package/cli/epic-state.mjs +357 -9
  13. package/cli/errors.mjs +2 -0
  14. package/cli/find-product.mjs +36 -2
  15. package/cli/fold.mjs +9 -5
  16. package/cli/gate-local.mjs +9 -1
  17. package/cli/gate.mjs +364 -22
  18. package/cli/history.mjs +22 -2
  19. package/cli/hook.mjs +3 -1
  20. package/cli/index-command.mjs +2 -2
  21. package/cli/ledger.mjs +60 -0
  22. package/cli/next.mjs +34 -11
  23. package/cli/openpr.mjs +81 -5
  24. package/cli/platform.mjs +21 -0
  25. package/cli/pr-list.mjs +5 -3
  26. package/cli/product-index.mjs +6 -3
  27. package/cli/product-token.mjs +186 -0
  28. package/cli/productcommit.mjs +33 -0
  29. package/cli/recommend.mjs +3 -1
  30. package/cli/repo-publish.mjs +2 -2
  31. package/cli/run-checks.mjs +586 -0
  32. package/cli/ship-drift.mjs +49 -18
  33. package/cli/standup.mjs +1 -1
  34. package/cli/status.mjs +282 -0
  35. package/cli/test-build.mjs +1559 -0
  36. package/cli/test-run-checks.mjs +603 -0
  37. package/cli/test-worktree.mjs +520 -0
  38. package/cli/thread.mjs +4 -0
  39. package/cli/tidy.mjs +2 -2
  40. package/cli/toolbox.mjs +36 -5
  41. package/cli/workspace.mjs +4 -1
  42. package/cli/worktree-record.mjs +53 -0
  43. package/cli/worktree.mjs +379 -0
  44. package/package.json +3 -3
  45. package/skills/sdlc/config.yaml +1 -1
  46. package/skills/sdlc/module-help.csv +1 -1
  47. package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
  48. package/skills/yad-change/SKILL.md +3 -0
  49. package/skills/yad-checks/SKILL.md +34 -5
  50. package/skills/yad-checks/references/check-gates.md +69 -10
  51. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  52. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  53. package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
  54. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  55. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  56. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  57. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  58. package/skills/yad-checks/templates/checks/package-manager.sh +41 -4
  59. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  60. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  61. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  62. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  63. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  64. package/skills/yad-checks/templates/github/yad-checks.yml +8 -8
  65. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +3 -0
  66. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +4 -4
  67. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  68. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  69. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  70. package/skills/yad-commit/SKILL.md +4 -2
  71. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  72. package/skills/yad-docs/templates/app/package.json +2 -2
  73. package/skills/yad-engineer-review/SKILL.md +45 -20
  74. package/skills/yad-engineer-review/references/ship-and-record.md +42 -8
  75. package/skills/yad-epic/references/state-schema.md +75 -16
  76. package/skills/yad-implement/SKILL.md +75 -13
  77. package/skills/yad-implement/references/implement-conventions.md +8 -1
  78. package/skills/yad-implement/templates/.gitmessage +3 -0
  79. package/skills/yad-open-pr/SKILL.md +21 -0
  80. package/skills/yad-pr-template/SKILL.md +6 -2
  81. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  82. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  83. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  84. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  85. package/skills/yad-product-bridge/SKILL.md +14 -1
  86. package/skills/yad-product-bridge/references/bridge.md +5 -2
  87. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  88. package/skills/yad-reconcile/SKILL.md +9 -3
  89. package/skills/yad-review-gate/SKILL.md +4 -0
  90. package/skills/yad-review-gate/references/gating.md +26 -1
  91. package/skills/yad-run/SKILL.md +52 -28
  92. package/skills/yad-run/references/run-loop.md +42 -21
  93. package/skills/yad-spec/SKILL.md +137 -16
  94. package/skills/yad-spec/references/spec-handoff.md +50 -3
  95. package/skills/yad-status/SKILL.md +7 -0
  96. package/skills/yad-stories/references/story-schema.md +1 -1
@@ -0,0 +1,586 @@
1
+ // `yad run checks` (issue #347): run every pull request gate on this machine before pushing, so a failure
2
+ // shows here and not after a CI round trip. The same words for a GitHub pull request and a GitLab merge
3
+ // request.
4
+ //
5
+ // What makes "passes here" mean "passes in CI":
6
+ // - the repo's OWN installed `checks/` scripts run, not the templates this package ships — CI runs the
7
+ // installed copies. One whose content differs from the shipped template is named.
8
+ // - the base is the branch the change will merge into, chosen as `yad open-pr` chooses it
9
+ // (`resolveBaseBranch`: the registry, then origin/HEAD; on the Product itself its own settings
10
+ // between them), fetched first.
11
+ // - the four Product-reading gates read the Product's DEFAULT BRANCH, as CI's product-checkout.sh
12
+ // clones it (the user's decision, 2026-10-19): it is written out from the local Product clone's
13
+ // `origin/<default_branch>` to where `.sdlc/product-link.json` ON THE BASE says, just before those
14
+ // four gates, and removed right after them — so the build gates never see it, as in CI. Written with
15
+ // a private index: the Product clone's own index, branch and files are never touched. The path gets
16
+ // the checks product-checkout.sh applies (no symlink on the way, nothing tracked there). A run removes
17
+ // only what it wrote itself; a folder already there is read as it is and kept.
18
+ // - every gate runs, even after one fails (CI jobs run side by side), then one summary.
19
+ //
20
+ // What cannot be the same here, and says so:
21
+ // - verified-commits asks the platform for its Verified badge, which an unpushed commit does not have.
22
+ // Locally each commit's signature is checked with git instead (`%G?`); the badge is judged in CI.
23
+ // - member-check needs the PR's author, which only the platform event carries. It runs when no member
24
+ // file changes, and otherwise is left to CI with a note.
25
+ // - pr-title and pr-template need text the PR does not have yet: --title and --body <file>, with the
26
+ // subject of a one-commit branch as the title (it becomes the squash title).
27
+ // - CI on GitHub tests the merge of the branch into the base; here it is the branch tip. A note says so
28
+ // when the branch is not on top of the base.
29
+ // - the build gates use this machine's Node and tools.
30
+ import fs from 'node:fs';
31
+ import os from 'node:os';
32
+ import path from 'node:path';
33
+ import { spawn, spawnSync } from 'node:child_process';
34
+ import { setTimeout, clearTimeout, setImmediate } from 'node:timers';
35
+ import { c, log, info, warn, fail, hand, ok, run, exists, readJSON, refuse, inJSON, asset, contentSha } from './lib.mjs';
36
+ import { detectPlatform, resolveBaseBranch } from './platform.mjs';
37
+ import { registryEntryFor } from './find-product.mjs';
38
+ import { repoPathFromGitUrl } from './protection.mjs';
39
+ import { rangeTasks, groupWarnings } from './build.mjs';
40
+
41
+ // GitLab hands CI only this many characters of a merge request description (#164, #343).
42
+ const GITLAB_DESCRIPTION_CUT = 2700;
43
+ const PRODUCT_GATES = new Set(['contract-check', 'lineage-check', 'epic-open', 'reconcile-debt']);
44
+
45
+ const git = (cwd, args, opts = {}) => run('git', args, { cwd, ...opts });
46
+
47
+ // A branch name git accepts, and never one read as an option: a value from a file the PR can shape
48
+ // (`default_branch`) reaches `git fetch` (review 1: `--upload-pack=…` ran a command).
49
+ function safeBranch(b) {
50
+ if (typeof b !== 'string' || !b || b.startsWith('-')) return null;
51
+ return run('git', ['check-ref-format', '--branch', b]).ok ? b : null;
52
+ }
53
+ // Fetch one branch by an explicit refspec: the name is data, never an option.
54
+ const fetchBranch = (cwd, b) => git(cwd, ['fetch', '--quiet', 'origin', `+refs/heads/${b}:refs/remotes/origin/${b}`]);
55
+
56
+ // The shipped template a gate was installed from, or null.
57
+ function shippedTemplate(script) {
58
+ const skills = asset('skills');
59
+ for (const sk of fs.readdirSync(skills)) {
60
+ const p = path.join(skills, sk, 'templates', 'checks', script);
61
+ if (exists(p)) return p;
62
+ }
63
+ return null;
64
+ }
65
+
66
+ // The record path's checks, as product-checkout.sh makes them: relative, no `..`, no `.git` part. A quote
67
+ // or a backslash is refused too: the gate reads such a value as no path at all.
68
+ function safeRecordPath(p) {
69
+ // Only ASCII spaces count as space, as the gate's [[:space:]] does under LC_ALL=C (trim() takes NBSP too).
70
+ if (typeof p !== 'string' || !/[^ \t\n\v\f\r]/.test(p) || path.isAbsolute(p) || /["\\]/.test(p)) return null;
71
+ const parts = p.split('/').filter((x) => x && x !== '.');
72
+ if (!parts.length || parts.some((x) => x === '..' || x.toLowerCase() === '.git')) return null;
73
+ return parts.join('/');
74
+ }
75
+
76
+ // The record on the base, read as product-checkout.sh's `field` reads it — never parsed as JSON: the raw
77
+ // bytes (LC_ALL=C there, latin1 here) with CR and LF dropped, the last `"key": "value"` whose value holds no
78
+ // quote and no backslash. So a value written with a JSON escape (`\/`, `\t`, `\u00e9`) reads as empty here
79
+ // as it does in CI, and a record that does not parse, a nested key or a duplicate one reads the same in
80
+ // both. `isSet` is the gate's own `"key": "<one character>` test. Null when the base has no record.
81
+ function recordFields(repoRoot, base) {
82
+ const shown = spawnSync('git', ['show', `${base}:.sdlc/product-link.json`], { cwd: repoRoot, encoding: 'latin1' });
83
+ if (shown.status !== 0) return null;
84
+ const flat = shown.stdout.replace(/[\r\n]/g, '');
85
+ const field = (key) => flat.match(new RegExp(`^.*"${key}"[ \\t\\f\\v]*:[ \\t\\f\\v]*"([^"\\\\]*)"`, 's'))?.[1] ?? '';
86
+ // A NUL byte: sed reads past it, so the value loses it after the match; bash's $(…) drops it before
87
+ // the `isSet` test.
88
+ const isSet = (key) => new RegExp(`"${key}"[ \\t\\f\\v]*:[ \\t\\f\\v]*"[^"]`).test(flat.replace(/\0/g, ''));
89
+ return { field: (key) => Buffer.from(field(key).replace(/\0/g, ''), 'latin1').toString('utf8'), isSet };
90
+ }
91
+
92
+ // Read the record on the base and decide where the Product goes. Returns { rel, branch, record, fail? }
93
+ // or { none: note }.
94
+ function readRecord(repoRoot, base) {
95
+ const fields = recordFields(repoRoot, base);
96
+ if (!fields) return { none: true };
97
+ const { field, isSet } = fields;
98
+ const url = field('git_url');
99
+ const dest = field('path');
100
+ // No git_url it can read: CI's product-checkout clones nothing and says so before it looks at the path,
101
+ // so nothing is written here either, and nothing else in the record fails.
102
+ if (!url && isSet('git_url')) return { nothing: `.sdlc/product-link.json on ${base} names a git_url CI's product-checkout cannot read (it is written with a JSON escape, a quote or a backslash), so CI checks no Product out — write it in the record without escapes and merge that change first. Nothing is written here` };
103
+ if (!url) return { nothing: `.sdlc/product-link.json on ${base} names no git_url, so CI checks no Product out — nothing is written here either` };
104
+ const rel = safeRecordPath(dest);
105
+ // `yad check --fix` writes a missing path and keeps one that is set (even one of only spaces, or one
106
+ // written with an escape), so the fix named differs by case. It reaches only the repos cloned on that
107
+ // machine, on their default branch.
108
+ if (!rel) {
109
+ const ci = "CI's product-checkout fails it too when YAD_PRODUCT_TOKEN is set";
110
+ if (!dest && isSet('path')) return { fail: `.sdlc/product-link.json on ${base} names a path the gate cannot read (it is written with a JSON escape, a quote or a backslash) — ${ci}. Change path in it to a plain folder such as .yad/product, and merge that change first: the record is read from ${base}` };
111
+ if (!dest) return { fail: `.sdlc/product-link.json on ${base} names no path — ${ci}; run \`yad check --fix --push\` from the Product, on a machine that has this repo cloned and on its default branch; it writes path .yad/product to the record there. Or set path yourself and merge that change first` };
112
+ return { fail: `.sdlc/product-link.json on ${base} says path ${JSON.stringify(dest)}, which is not a folder inside this repo — ${ci}. Change path in it to one, such as .yad/product, and merge that change first: the record is read from ${base}, so changing it on this branch does not help` };
113
+ }
114
+ // No default_branch is deliberate (cli/plan.mjs writes null when it does not know): CI then clones the
115
+ // remote's own default branch, so placeProduct asks the Product clone's origin/HEAD for it.
116
+ const raw = field('default_branch') || null;
117
+ const branch = raw === null ? null : safeBranch(raw);
118
+ if (raw !== null && !branch) return { fail: `.sdlc/product-link.json on ${base} names a default_branch git cannot use as a branch name — run \`yad check --fix --push\` from the Product to write it again` };
119
+ // Nothing on the way may be a symlink, and nothing there may be tracked: CI's product-checkout refuses
120
+ // both (when YAD_PRODUCT_TOKEN is set; without it, it checks nothing out).
121
+ const parts = rel.split('/');
122
+ for (let i = 1; i <= parts.length; i++) {
123
+ const p = path.join(repoRoot, ...parts.slice(0, i));
124
+ let st;
125
+ try { st = fs.lstatSync(p); } catch { break; }
126
+ if (st.isSymbolicLink()) return { fail: `'${parts.slice(0, i).join('/')}' is a symlink — the Product is not written through it (CI refuses it too, when YAD_PRODUCT_TOKEN is set). Point path in .sdlc/product-link.json at a real folder` };
127
+ if (i < parts.length && !st.isDirectory()) return { fail: `'${parts.slice(0, i).join('/')}' is a file where the Product's folder goes — move it, or point path in .sdlc/product-link.json elsewhere` };
128
+ }
129
+ const tracked = git(repoRoot, ['ls-files', '-z', '--', rel]);
130
+ if (tracked.ok && tracked.stdout) return { fail: `'${rel}' holds files this repo tracks — the Product cannot be checked out there (CI refuses it too, when YAD_PRODUCT_TOKEN is set). Untrack them only if they do not belong in this repo (git rm -r --cached -- '${rel.replaceAll("'", "'\\''")}', and add the folder to .gitignore), or change path in .sdlc/product-link.json to an untracked folder such as .yad/product and merge that change first (the record is read from ${base})` };
131
+ return { rel, branch, record: { git_url: url } };
132
+ }
133
+
134
+ // Remove a copy this run wrote: `dest` itself (it did not exist before), then each folder this run made on
135
+ // the way to it, from the inside out, only while it is empty — a file someone put there meanwhile stays.
136
+ // What mkdirSync({ recursive }) reports it made, in the form path.join gives: on Windows, Node 18 and 20
137
+ // report it in the long `\\?\C:\…` form, which would never match `dest`.
138
+ export const plainPath = (p, P = path) => (typeof p === 'string' && p ? P.resolve(p.replace(/^\\\\\?\\UNC\\/, '\\\\').replace(/^\\\\\?\\/, '')) : p);
139
+
140
+ export function removeCopy(dest, created) {
141
+ fs.rmSync(dest, { recursive: true, force: true });
142
+ removeParents(dest, created);
143
+ }
144
+ // The folders this run made on the way to `dest` (`created` is the top one), only while each is empty.
145
+ // Bounded by `created`, which is `dest` or an ancestor of it inside the repo (built with path.join, so the
146
+ // same separators as path.dirname on every platform).
147
+ export function removeParents(dest, created) {
148
+ if (!created || created === dest || !dest.startsWith(created + path.sep)) return;
149
+ for (let d = path.dirname(dest); d.length >= created.length; d = path.dirname(d)) {
150
+ try { fs.rmdirSync(d); } catch { break; }
151
+ if (d === created) break;
152
+ }
153
+ }
154
+
155
+ // Write the Product's default branch to `rel`. Returns { placed, created?, note } or { fail }.
156
+ function placeProduct(repoRoot, productRoot, { rel, branch: recorded, record }, { fetch }) {
157
+ const dest = path.join(repoRoot, rel);
158
+ // A run removes only what it wrote itself. A folder already there — the user's own, another run's in use,
159
+ // or one a killed run left behind — is read as it is and never removed (CI's product-checkout leaves an
160
+ // existing folder too).
161
+ const alreadyThere = { placed: false, existing: dest, note: `${rel} is already there, so it is read as it is — it may not be the Product's default branch (another run may be using it, or a run that was killed left it): remove it to read the default branch` };
162
+ if (exists(dest)) return alreadyThere;
163
+ if (!productRoot) {
164
+ return { placed: false, note: `no Product clone found from this repo (the workspace file names it), so ${rel} is not written — the Product-reading gates may read what product-repo in a link.md reaches on this machine, including unmerged edits, where CI would read nothing` };
165
+ }
166
+ const notes = [];
167
+ let branch = recorded;
168
+ if (!branch) {
169
+ const h = git(productRoot, ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD']);
170
+ branch = safeBranch(h.ok && h.stdout.startsWith('origin/') ? h.stdout.slice('origin/'.length) : '') || 'main';
171
+ notes.push(`the record names no default_branch, so the Product clone's origin/HEAD says it: ${branch}`);
172
+ }
173
+ const want = repoPathFromGitUrl(record?.git_url || '');
174
+ const have = repoPathFromGitUrl(git(productRoot, ['remote', 'get-url', 'origin']).stdout);
175
+ if (want && have && want.toLowerCase() !== have.toLowerCase()) notes.push(`the Product clone's origin is ${have}, but the record names ${want} — it is read anyway`);
176
+ if (fetch && !fetchBranch(productRoot, branch).ok) notes.push(`could not fetch ${branch} in the Product clone — its last fetched copy is read`);
177
+ const sha = git(productRoot, ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${branch}^{commit}`]);
178
+ if (!sha.ok || !sha.stdout) {
179
+ return { placed: false, note: [...notes, `the Product clone has no origin/${branch}, so ${rel} is not written — the Product-reading gates may read what product-repo in a link.md reaches on this machine, where CI would read the default branch`].join('; ') };
180
+ }
181
+ // Making the folder itself is the claim: one mkdir, which fails when another run made it first, between
182
+ // the check above and here (the fetch takes seconds). `created` is the top folder this run made (`.yad`
183
+ // for `.yad/product`) — what mkdir reports, so the clean-up removes only what this run made.
184
+ let top;
185
+ let created;
186
+ try {
187
+ top = plainPath(fs.mkdirSync(path.dirname(dest), { recursive: true }));
188
+ fs.mkdirSync(dest);
189
+ created = top || dest;
190
+ } catch (e) {
191
+ removeParents(dest, top);
192
+ if (e.code === 'EEXIST') {
193
+ let isDir = false;
194
+ try { isDir = fs.lstatSync(dest).isDirectory(); } catch { /* gone again */ }
195
+ return isDir ? { ...alreadyThere, note: [...notes, alreadyThere.note].join('; ') } : { placed: false, note: [...notes, `a file is where the Product's folder goes (${rel}) — move it, or point path in .sdlc/product-link.json elsewhere`].join('; ') };
196
+ }
197
+ return { placed: false, note: [...notes, `could not make ${rel} (${e.message}) — the Product-reading gates may read what product-repo in a link.md reaches on this machine`].join('; ') };
198
+ }
199
+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'yad-run-checks-'));
200
+ const idx = path.join(tmp, 'index');
201
+ try {
202
+ const env = { ...process.env, GIT_INDEX_FILE: idx };
203
+ delete env.GIT_DIR; delete env.GIT_WORK_TREE;
204
+ const read = spawnSync('git', ['read-tree', sha.stdout], { cwd: productRoot, env, encoding: 'utf8' });
205
+ const out = read.status === 0
206
+ ? spawnSync('git', ['checkout-index', '-a', '-f'], { cwd: productRoot, env: { ...env, GIT_WORK_TREE: dest }, encoding: 'utf8' })
207
+ : read;
208
+ if (out.status !== 0) throw new Error((out.stderr || '').trim().split('\n')[0] || 'git could not write it');
209
+ } catch (e) {
210
+ removeCopy(dest, created);
211
+ return { placed: false, note: [...notes, `could not write the Product's ${branch} to ${rel} (${e.message}) — the Product-reading gates may read what product-repo in a link.md reaches on this machine`].join('; ') };
212
+ } finally {
213
+ fs.rmSync(tmp, { recursive: true, force: true });
214
+ }
215
+ return { placed: true, created, dest, note: [...notes, `the Product's ${branch} (${sha.stdout.slice(0, 12)}) is written to ${rel}, as CI checks it out, and removed after these gates`].join('; ') };
216
+ }
217
+
218
+ // Each commit's signature, as git reads it here. `%G?`: G good, U good with unknown trust, X/Y expired,
219
+ // R revoked, E cannot be checked (no key here), B bad, N none — or a signature git has no way to check:
220
+ // an SSH one with no gpg.ssh.allowedSignersFile reads N too, so the commit object itself is asked.
221
+ function localSignatures(repoRoot, base) {
222
+ const r = git(repoRoot, ['log', '--format=%H %G? %P', `${base}..HEAD`]);
223
+ if (!r.ok) return { status: 'fail', lines: [`FAIL [verified-commits]: git could not list the commits in ${base}..HEAD`] };
224
+ const lines = [];
225
+ let bad = 0;
226
+ for (const row of r.stdout.split('\n').filter(Boolean)) {
227
+ const [sha, mark, ...parents] = row.split(' ');
228
+ const short = sha.slice(0, 7);
229
+ let m = mark;
230
+ if (m === 'N' && /^gpgsig(-sha256)? /m.test(git(repoRoot, ['cat-file', 'commit', sha]).stdout.split('\n\n')[0])) m = 'E';
231
+ if (m === 'N' && parents.length > 1) { lines.push(`note [verified-commits]: ${short} is an unsigned merge commit — CI waives it only when it adds nothing of its own`); continue; }
232
+ if (m === 'N') { bad++; lines.push(`FAIL [verified-commits]: ${short} is not signed — sign commits (git config commit.gpgsign true, with a GPG or SSH key added to your account), then re-sign: git rebase --exec 'git commit --amend --no-edit -S' ${base}, and force-push`); continue; }
233
+ if (m === 'B' || m === 'R') { bad++; lines.push(`FAIL [verified-commits]: ${short} has a ${m === 'B' ? 'bad' : 'revoked'} signature — re-sign it with a key your account holds`); continue; }
234
+ if (m === 'X' || m === 'Y') { lines.push(`note [verified-commits]: ${short} is signed, but the ${m === 'X' ? 'signature' : 'key'} has expired — the platform may not mark it Verified`); continue; }
235
+ if (m === 'E') { lines.push(`note [verified-commits]: ${short} is signed, but this machine cannot check the key — the platform checks it in CI`); continue; }
236
+ lines.push(`PASS [verified-commits]: ${short} is signed`);
237
+ }
238
+ if (!lines.length) lines.push(`PASS [verified-commits]: no commits in ${base}..HEAD`);
239
+ lines.push('note [verified-commits]: checked with git here; the platform\'s Verified badge (your key on your account) is judged in CI after the push');
240
+ return { status: bad ? 'fail' : 'pass', lines };
241
+ }
242
+
243
+ // Run one gate, its output shown as it comes, and resolved when it ends. `stop` kills it on a signal.
244
+ function runGate(cmd, args, { cwd, env }, live) {
245
+ return new Promise((resolve) => {
246
+ let out = '';
247
+ let child;
248
+ // Its own process group, so a stop reaches the whole gate — bash and the npm/node it starts — and not
249
+ // bash alone, which would leave them holding the output open.
250
+ const detached = process.platform !== 'win32';
251
+ try { child = spawn(cmd, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], detached }); } catch (e) { resolve({ error: e }); return; }
252
+ live.group = detached;
253
+ live.child = child;
254
+ let partial = '';
255
+ const take = (d) => {
256
+ const s = d.toString();
257
+ out += s;
258
+ partial += s;
259
+ const cut = partial.lastIndexOf('\n');
260
+ if (cut >= 0) { log(partial.slice(0, cut).replace(/^/gm, ' ')); partial = partial.slice(cut + 1); }
261
+ };
262
+ child.stdout.on('data', take);
263
+ child.stderr.on('data', take);
264
+ let done = false;
265
+ let wait = null;
266
+ const finish = (res) => {
267
+ if (wait) clearTimeout(wait);
268
+ if (done) return;
269
+ done = true;
270
+ live.child = null;
271
+ if (partial) log(` ${partial}`);
272
+ resolve({ ...res, out: out.replace(/\s+$/, '') });
273
+ };
274
+ child.on('error', (e) => finish({ error: e }));
275
+ // Done when the gate EXITS, not when every process holding its output lets go: a server or watcher
276
+ // it left behind would hold the run open. What it left is ended with its process group, after a short
277
+ // wait for the last output.
278
+ let ended = 0;
279
+ child.stdout.on('end', () => { ended++; });
280
+ child.stderr.on('end', () => { ended++; });
281
+ child.on('close', (status, signal) => finish({ status, signal }));
282
+ child.on('exit', (status, signal) => {
283
+ const end = () => {
284
+ if (detached) { try { process.kill(-child.pid, 'SIGTERM'); } catch { /* none left */ } }
285
+ child.stdout.destroy(); child.stderr.destroy();
286
+ finish({ status, signal });
287
+ };
288
+ // Nothing left holding the output: done now. Otherwise a short wait for the last of it.
289
+ if (ended === 2) end(); else wait = setTimeout(end, 300);
290
+ });
291
+ });
292
+ }
293
+
294
+ export async function runChecks(dir, opts = {}) {
295
+ log(c.bold('\nyad run checks'));
296
+ const top = git(dir, ['rev-parse', '--show-toplevel']);
297
+ if (!top.ok) return refuse(`not a git repo: ${dir}`, 'run it inside the repo whose change you want checked');
298
+ const repoRoot = top.stdout;
299
+ const checksDir = path.join(repoRoot, 'checks');
300
+ if (!exists(checksDir)) return refuse(`no checks/ folder in ${repoRoot} — the gates are not installed here`, 'run `yad check --fix` from the Product to install them');
301
+ let bodyFile = null;
302
+ if (opts.body) {
303
+ bodyFile = path.resolve(process.cwd(), opts.body);
304
+ if (!exists(bodyFile)) return refuse(`--body file not found: ${opts.body}`, 'save the PR/MR description to a file and pass its path');
305
+ }
306
+
307
+ const settings = readJSON(path.join(repoRoot, '.sdlc/product.json'), null) || readJSON(path.join(repoRoot, '.sdlc/hub.json'), null);
308
+ const isProduct = !!settings;
309
+ const branchName = git(repoRoot, ['rev-parse', '--abbrev-ref', 'HEAD']).stdout;
310
+ const meta = registryEntryFor(opts.product || null, repoRoot)?.meta || null;
311
+ // The registry's platform first: a self-hosted GitLab's host need not say "gitlab".
312
+ const platform = (isProduct ? settings.platform : null) || meta?.platform
313
+ || detectPlatform(git(repoRoot, ['remote', 'get-url', 'origin']).stdout) || null;
314
+
315
+ // The base: as given, else the branch `yad open-pr` would open the PR against, fetched first.
316
+ let base = opts.base;
317
+ if (!base) {
318
+ // The Product's own default_branch counts only for the Product itself: a code repo's trunk is its own.
319
+ const chosen = resolveBaseBranch(platform, { cwd: repoRoot, meta, productConfig: isProduct ? settings : null, probe: false });
320
+ const b = safeBranch(chosen.base);
321
+ if (!b) return refuse(`the base branch '${chosen.base}' (from ${chosen.source}) is not a branch name git accepts`, 'pass --base <ref>');
322
+ if (opts.fetch !== false && !fetchBranch(repoRoot, b).ok) warn(`could not fetch ${b} from origin — the last fetched origin/${b} is the base`);
323
+ base = `origin/${b}`;
324
+ } else if (base.startsWith('-')) {
325
+ return refuse(`--base '${base}' is not a ref`, 'pass a branch or commit, such as origin/main');
326
+ }
327
+ if (!git(repoRoot, ['rev-parse', '--verify', '--quiet', '--end-of-options', `${base}^{commit}`]).ok) {
328
+ return refuse(`base '${base}' is not a commit here`, 'fetch it (git fetch origin), or pass --base <ref>');
329
+ }
330
+ info(`${isProduct ? 'Product' : 'code repo'} ${path.basename(repoRoot)} · branch ${branchName} · base ${base}`);
331
+ // A grouped PR (#350) — commits carrying several tasks — is warned about over its size limit, as
332
+ // `yad open-pr` warns. Never a failed gate.
333
+ if (!isProduct) {
334
+ const ids = rangeTasks(repoRoot, `${base}..HEAD`);
335
+ const productSettings = opts.product ? (readJSON(path.join(opts.product, '.sdlc/product.json'), null) || readJSON(path.join(opts.product, '.sdlc/hub.json'), null)) : null;
336
+ for (const line of groupWarnings(repoRoot, base, ids, productSettings || {})) warn(line);
337
+ }
338
+ if (!git(repoRoot, ['merge-base', '--is-ancestor', base, 'HEAD']).ok) {
339
+ info(`this branch is not on top of ${base}: CI on GitHub tests the merge of the two, this run the branch tip — rebase onto ${base} for the same answer`);
340
+ }
341
+ // Uncommitted work, but not a Product copy at the record's path (one already there gets its own note when the Product gates run).
342
+ let recRel = null;
343
+ // Read as readRecord and the gate read it, so the same folder is skipped.
344
+ recRel = safeRecordPath(recordFields(repoRoot, base)?.field('path') ?? '');
345
+ const st = spawnSync('git', ['status', '--porcelain=v1', '-z', '--untracked-files=normal'], { cwd: repoRoot, encoding: 'utf8' });
346
+ // A rename or copy is two entries, `R new` then the old name with no status: the old one is skipped.
347
+ const entries = (st.stdout || '').split('\0');
348
+ const changed = [];
349
+ for (let i = 0; i < entries.length; i++) {
350
+ const e = entries[i];
351
+ if (!e) continue;
352
+ changed.push(e.slice(3));
353
+ if ('RC'.includes(e[0]) || 'RC'.includes(e[1])) i++;
354
+ }
355
+ // An untracked folder on the record's path (`.yad/`, shown collapsed) is skipped whole.
356
+ const dirty = changed
357
+ .filter((p) => !(recRel && (p.startsWith(`${recRel}/`) || `${recRel}/`.startsWith(`${p.replace(/\/$/, '')}/`))));
358
+ if (dirty.length) info(`uncommitted changes are built and tested here but are not in the push (${dirty.slice(0, 3).join(', ')}${dirty.length > 3 ? `, and ${dirty.length - 3} more` : ''}) — commit or stash them for CI's answer`);
359
+ if (git(repoRoot, ['rev-list', '--count', `${base}..HEAD`]).stdout === '0') {
360
+ info(`no commits in ${base}..HEAD — there is nothing of this branch's own to check`);
361
+ }
362
+
363
+ // The PR text.
364
+ let title = opts.title || null;
365
+ let titleNote = null;
366
+ // A Product review branch's title is `review: <artifact> (EP-<slug>)`, which `yad gate open` writes — a
367
+ // commit subject is never it.
368
+ const reviewHead = isProduct && /^review\/EP-/.test(branchName);
369
+ if (isProduct && branchName === 'HEAD') info('HEAD is detached: the Product gates split by branch name, so check out the branch the PR comes from for CI\'s answer');
370
+ if (!title && !reviewHead) {
371
+ const subjects = git(repoRoot, ['log', '--no-merges', '--format=%s', `${base}..HEAD`]).stdout.split('\n').filter(Boolean);
372
+ if (subjects.length === 1) { title = subjects[0]; titleNote = 'the title is the branch\'s one commit subject (pass --title to check another)'; }
373
+ }
374
+
375
+ const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'yad-run-checks-'));
376
+ let placed = null;
377
+ const live = { child: null, stopped: false };
378
+ // A folder this run read as it was (another run's copy, say) may be removed by that run meanwhile.
379
+ const checkVanished = () => {
380
+ if (!placed?.existing || placed.vanished !== undefined) return;
381
+ placed.vanished = !exists(placed.existing);
382
+ if (placed.vanished) warn(`${record?.rel || 'the Product copy'} was removed while the Product gates read it (another run ended) — their answers may be wrong; run again`);
383
+ };
384
+ const removeProduct = () => {
385
+ if (!placed?.placed) return;
386
+ removeCopy(placed.dest, placed.created);
387
+ placed.placed = false;
388
+ };
389
+ // The gate runs in a session of its own, so a Ctrl-C reaches only yad, which passes it on. It ends the
390
+ // run: the gate is stopped, the Product copy removed, and nothing after it runs. A gate that ignores it
391
+ // is killed on the second signal, or after five seconds.
392
+ const killGate = (sig) => {
393
+ const ch = live.child;
394
+ if (!ch) return;
395
+ try {
396
+ if (live.group) process.kill(-ch.pid, sig);
397
+ else if (process.platform === 'win32' && sig === 'SIGKILL') spawnSync('taskkill', ['/T', '/F', '/PID', String(ch.pid)]);
398
+ else ch.kill(sig);
399
+ } catch { /* already gone */ }
400
+ };
401
+ let escalate = null;
402
+ const onSignal = (sig) => {
403
+ if (live.stopped) { killGate('SIGKILL'); return; }
404
+ live.stopped = sig;
405
+ killGate(sig);
406
+ escalate = setTimeout(() => killGate('SIGKILL'), 5000);
407
+ escalate.unref();
408
+ };
409
+ const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
410
+ for (const s of signals) process.on(s, onSignal);
411
+
412
+ const results = [];
413
+ let record = null;
414
+ try {
415
+ // The changed paths, for the Product's pr-title/pr-template split, built as yad-product-checks.yml does.
416
+ const changedFile = path.join(scratch, 'changed');
417
+ if (isProduct) {
418
+ const d = git(repoRoot, ['-c', 'core.quotePath=false', 'diff', '--no-renames', '--name-only', `${base}...HEAD`]);
419
+ fs.writeFileSync(changedFile, d.ok ? `${d.stdout}\n` : '');
420
+ }
421
+
422
+ const profile = isProduct ? 'product' : 'code';
423
+ const head = isProduct ? ['--head', branchName, '--changed', changedFile] : [];
424
+ const titleNeeds = title ? null : reviewHead
425
+ ? 'a review branch: pass --title "review: <artifact> (EP-<slug>)" — `yad gate open` writes that title'
426
+ : 'no title: pass --title "<the PR/MR title>" (a branch of one commit uses its subject)';
427
+ const bodyNeeds = bodyFile ? null : 'no description: pass --body <file holding the PR/MR description>';
428
+ // The build gates first and the four Product-reading gates together, so the Product copy exists only
429
+ // while they run — in CI the build job never has it.
430
+ const gates = isProduct
431
+ ? [
432
+ { name: 'commit-message', script: 'commit-message.sh', args: ['--profile', profile, base] },
433
+ { name: 'pr-title', script: 'pr-title.sh', args: ['--profile', profile, ...head, title], needs: titleNeeds },
434
+ { name: 'pr-template', script: 'pr-template.sh', args: ['--profile', profile, ...head, bodyFile], needs: bodyNeeds },
435
+ { name: 'ledger-guard', script: 'ledger-guard.sh', args: [base] },
436
+ { name: 'member-check', script: 'member-check.mjs', node: true, args: [base] },
437
+ { name: 'verified-commits', local: true },
438
+ ]
439
+ : [
440
+ { name: 'spec-link', script: 'spec-link.sh', args: [base] },
441
+ { name: 'commit-message', script: 'commit-message.sh', args: ['--profile', profile, base] },
442
+ { name: 'pr-title', script: 'pr-title.sh', args: ['--profile', profile, title], needs: titleNeeds },
443
+ { name: 'pr-template', script: 'pr-template.sh', args: ['--profile', profile, bodyFile], needs: bodyNeeds },
444
+ { name: 'risk-map', script: 'risk-map-check.sh', args: [base] },
445
+ { name: 'install-deps', script: 'install-deps.sh', args: [], build: true },
446
+ { name: 'build/test/lint', script: 'build-test-lint.sh', args: [], build: true, after: 'install-deps' },
447
+ { name: 'contract-check', script: 'contract-check.sh', args: [base] },
448
+ { name: 'lineage-check', script: 'lineage-check.sh', args: [base] },
449
+ { name: 'epic-open', script: 'epic-open.sh', args: [base] },
450
+ { name: 'reconcile-debt', script: 'reconcile-debt-check.sh', args: [base] },
451
+ { name: 'verified-commits', local: true },
452
+ { name: 'backfill', script: 'backfill-check.sh', args: [base], optional: true },
453
+ ];
454
+
455
+ // Nothing from the shell this runs in may make a gate act as in CI, or read another settings file,
456
+ // platform or git folder. GITHUB_TOKEN stays: gh reads it to sign in.
457
+ const env = { ...process.env };
458
+ for (const k of Object.keys(env)) {
459
+ if (k === 'CI' || k === 'GITLAB_CI' || k.startsWith('CI_') || (k.startsWith('GITHUB_') && k !== 'GITHUB_TOKEN')
460
+ || k.startsWith('SDLC_') || k === 'GIT_DIR' || k === 'GIT_WORK_TREE' || k === 'GIT_INDEX_FILE') delete env[k];
461
+ }
462
+ // The build gates get what the CI job sets for them.
463
+ const headSha = git(repoRoot, ['rev-parse', 'HEAD']).stdout;
464
+ const baseSha = git(repoRoot, ['rev-parse', `${base}^{commit}`]).stdout;
465
+ const buildEnv = { ...env, CI: 'true', NX_BASE: baseSha, NX_HEAD: headSha, YAD_TEST_MAX_WORKERS: env.YAD_TEST_MAX_WORKERS || '2' };
466
+
467
+ for (const g of gates) {
468
+ if (live.stopped) break;
469
+ const scriptPath = g.script ? path.join(checksDir, g.script) : null;
470
+ if (g.optional && !exists(scriptPath)) continue;
471
+ // The copy exists only while the Product-reading gates run, whichever of them is installed.
472
+ if (placed?.placed && !PRODUCT_GATES.has(g.name)) removeProduct();
473
+ if (placed?.existing && !PRODUCT_GATES.has(g.name)) checkVanished();
474
+ log(`\n${c.bold(g.name)}`);
475
+ const r = { name: g.name, status: 'pass', reason: null, output: '' };
476
+ results.push(r);
477
+
478
+ // The Product goes in place just before the first Product-reading gate.
479
+ if (!isProduct && PRODUCT_GATES.has(g.name) && !record) {
480
+ record = readRecord(repoRoot, base);
481
+ if (record.fail) {
482
+ results.splice(results.length - 1, 0, { name: 'product-checkout', status: 'fail', reason: 'the Product could not be put where CI puts it', output: `FAIL [product-checkout]: ${record.fail}` });
483
+ log(` FAIL [product-checkout]: ${record.fail}`);
484
+ } else if (record.nothing) {
485
+ info(record.nothing);
486
+ } else if (record.none) {
487
+ info(`no .sdlc/product-link.json on ${base}, so nothing is checked out for the Product — the Product-reading gates read what product-repo in a link.md reaches on this machine (CI reaches nothing, and they skip their Product check there)`);
488
+ } else {
489
+ placed = placeProduct(repoRoot, opts.product || null, record, { fetch: opts.fetch !== false });
490
+ info(placed.note);
491
+ }
492
+ }
493
+
494
+ // In CI these four are steps after product-checkout in the same job: they never run when it fails.
495
+ if (record?.fail && PRODUCT_GATES.has(g.name)) { r.status = 'skip'; r.reason = 'product-checkout failed, so it was not run (as in CI)'; info(r.reason); continue; }
496
+ if (g.local) {
497
+ const s = localSignatures(repoRoot, base);
498
+ r.status = s.status; r.output = s.lines.join('\n');
499
+ log(r.output.replace(/^/gm, ' '));
500
+ continue;
501
+ }
502
+ if (!exists(scriptPath)) {
503
+ r.status = 'skip';
504
+ r.reason = `checks/${g.script} is not installed here — \`yad check --fix\` installs the gates this repo is wired for`;
505
+ info(r.reason);
506
+ continue;
507
+ }
508
+ if (g.build && opts.build === false) { r.status = 'skip'; r.reason = 'skipped with --no-build'; info(r.reason); continue; }
509
+ if (g.after && results.find((x) => x.name === g.after)?.status === 'fail') { r.status = 'skip'; r.reason = `${g.after} failed, so it was not run`; info(r.reason); continue; }
510
+ if (g.needs) { r.status = 'skip'; r.reason = g.needs; info(r.reason); continue; }
511
+ if (g.name === 'member-check') {
512
+ const m = git(repoRoot, ['diff', '--no-renames', '--name-only', `${base}...HEAD`, '--', '.sdlc/members']);
513
+ if (m.ok && m.stdout) { r.status = 'skip'; r.reason = 'a member file changes, and the gate needs the PR\'s author, which only CI has — it is judged in CI'; info(r.reason); continue; }
514
+ }
515
+ if (g.name === 'install-deps') info('installs from the lockfile as CI does (npm ci or pnpm install --frozen-lockfile, which replace node_modules; Corepack is enabled when package.json pins a package manager) — --no-build skips it');
516
+ const shipped = shippedTemplate(g.script);
517
+ if (shipped && contentSha(shipped) !== contentSha(scriptPath)) {
518
+ r.differs = true;
519
+ warn(`checks/${g.script} is not the gate this yadflow ships — CI runs the committed copy; if it is an older one, \`yad update\` replaces it`);
520
+ }
521
+ if (live.stopped) { results.pop(); break; }
522
+ const p = await runGate(g.node ? process.execPath : 'bash', [scriptPath, ...g.args], { cwd: repoRoot, env: g.build ? buildEnv : env }, live);
523
+ r.output = p.out || '';
524
+ if (p.error) {
525
+ r.status = 'fail';
526
+ r.reason = `could not run it: ${p.error.message}${process.platform === 'win32' && !g.node ? ' — the gates need bash (Git Bash) on the PATH' : ''}`;
527
+ log(` ${r.reason}`);
528
+ } else if (live.stopped || (process.platform === 'win32' && (p.status === 130 || p.status === 3221225786))) {
529
+ r.status = 'skip'; r.reason = 'stopped';
530
+ live.stopped = live.stopped || 'SIGINT';
531
+ } else {
532
+ r.exit = p.status;
533
+ r.status = p.status === 0 ? 'pass' : 'fail';
534
+ }
535
+ if (g.name === 'pr-title' && titleNote) info(titleNote);
536
+ if (g.name === 'pr-template' && platform === 'gitlab') {
537
+ const len = [...fs.readFileSync(bodyFile, 'utf8')].length;
538
+ if (len >= GITLAB_DESCRIPTION_CUT) warn(`the description is ${len} characters; GitLab hands CI only the first ${GITLAB_DESCRIPTION_CUT} — the gate then reads the rest from GitLab's API with a token, so keep the required sections near the top`);
539
+ }
540
+ }
541
+ // A signal that came during the last synchronous step is handled before the listeners go.
542
+ await new Promise((r) => setImmediate(r));
543
+ checkVanished();
544
+ } finally {
545
+ if (escalate) clearTimeout(escalate);
546
+ removeProduct();
547
+ fs.rmSync(scratch, { recursive: true, force: true });
548
+ for (const s of signals) process.removeListener(s, onSignal);
549
+ }
550
+
551
+ const failed = results.filter((r) => r.status === 'fail');
552
+ const skipped = results.filter((r) => r.status === 'skip');
553
+ const passed = results.filter((r) => r.status === 'pass');
554
+ const json = () => ({
555
+ repo: path.basename(repoRoot), kind: isProduct ? 'product' : 'code', base, platform,
556
+ product: placed ? { placed: !!placed.dest, path: record?.rel || null, note: placed.note || null, ...(placed.vanished ? { vanished: true } : {}) } : null,
557
+ gates: results.map(({ name, status, reason, exit, differs, output }) => ({
558
+ name, status, ...(reason ? { reason } : {}), ...(exit !== undefined ? { exit } : {}), ...(differs ? { differs: true } : {}),
559
+ // The FAIL lines, so an agent reading --json sees what to change without the whole log.
560
+ fails: (output || '').split('\n').map((l) => l.trim()).filter((l) => /^FAIL /.test(l)),
561
+ })),
562
+ passed: passed.length, failed: failed.length, skipped: skipped.length,
563
+ stopped: !!live.stopped,
564
+ });
565
+ if (live.stopped) {
566
+ fail(`stopped (${live.stopped}) — nothing after that gate ran${placed?.dest ? '; the Product copy is removed' : ''}`);
567
+ process.exitCode = { SIGTERM: 143, SIGHUP: 129 }[live.stopped] || 130;
568
+ return inJSON() ? json() : { stopped: true };
569
+ }
570
+ log(`\n${c.bold('Summary')}`);
571
+ for (const r of results) {
572
+ const line = `${r.name}${r.reason ? ` — ${r.reason}` : ''}`;
573
+ if (r.status === 'pass') ok(line);
574
+ else if (r.status === 'skip') info(`skipped: ${line}`);
575
+ else log(` ${c.red('✗')} ${line}`);
576
+ }
577
+ if (failed.length) {
578
+ fail(`${failed.length} gate${failed.length > 1 ? 's' : ''} failed: ${failed.map((r) => r.name).join(', ')}`);
579
+ hand('fix what each FAIL line says, then run `yad run checks` again — docs/GATES.md lists every message and what to change');
580
+ process.exitCode = 1;
581
+ } else {
582
+ ok(`${passed.length} passed${skipped.length ? `, ${skipped.length} skipped (a skipped gate is not a pass)` : ''} — push when ready`);
583
+ }
584
+ if (inJSON()) return json();
585
+ return { failed: failed.length };
586
+ }