yadflow 4.8.0 → 4.10.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/CHANGELOG.md +114 -0
- package/README.md +4 -3
- package/bin/commands.mjs +7 -0
- package/bin/yad.mjs +123 -8
- package/cli/agent-guard.mjs +793 -65
- package/cli/agent-rules.mjs +40 -5
- package/cli/argv-flags.mjs +1 -1
- package/cli/build.mjs +1 -1
- package/cli/ci-check.mjs +45 -1
- package/cli/codeowners-command.mjs +72 -6
- package/cli/commit.mjs +17 -3
- package/cli/docs.mjs +2 -0
- package/cli/doctor.mjs +176 -12
- package/cli/epic-state.mjs +94 -4
- package/cli/epic.mjs +11 -7
- package/cli/fold.mjs +31 -6
- package/cli/guide.mjs +3 -1
- package/cli/hook.mjs +50 -7
- package/cli/issue-links.mjs +61 -0
- package/cli/issues-act.mjs +327 -0
- package/cli/issues-write.mjs +428 -0
- package/cli/issues.mjs +474 -0
- package/cli/lifecycle.mjs +7 -0
- package/cli/machine.mjs +141 -0
- package/cli/manifest.mjs +9 -3
- package/cli/openpr.mjs +69 -9
- package/cli/plan.mjs +2 -0
- package/cli/platform.mjs +157 -2
- package/cli/preview.mjs +253 -0
- package/cli/protection.mjs +21 -3
- package/cli/reconcile.mjs +1 -1
- package/cli/repo.mjs +64 -3
- package/cli/review.mjs +4 -0
- package/cli/run-checks.mjs +10 -2
- package/cli/scan.mjs +314 -0
- package/cli/setup.mjs +12 -3
- package/cli/standup.mjs +33 -7
- package/cli/story-frames.mjs +307 -0
- package/cli/test-agents-file.mjs +378 -11
- package/cli/test-build.mjs +25 -0
- package/cli/test-ci-check.mjs +469 -10
- package/cli/test-guide.mjs +7 -0
- package/cli/test-machine.mjs +140 -0
- package/cli/test-node.mjs +15 -0
- package/cli/test-preview.mjs +511 -0
- package/cli/test-run-checks.mjs +17 -0
- package/cli/test-setup-agent.mjs +14 -0
- package/cli/test-story-frames.mjs +409 -0
- package/cli/toolbox-connect.mjs +244 -0
- package/cli/toolbox.mjs +159 -5
- package/package.json +7 -3
- package/skills/sdlc/config.yaml +1 -1
- package/skills/sdlc/module-help.csv +3 -1
- package/skills/yad-analysis/SKILL.md +4 -0
- package/skills/yad-backfill/SKILL.md +4 -0
- package/skills/yad-change/SKILL.md +4 -0
- package/skills/yad-checks/SKILL.md +13 -7
- package/skills/yad-checks/references/check-gates.md +62 -30
- package/skills/yad-checks/templates/checks/member-check.mjs +3 -2
- package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
- package/skills/yad-checks/templates/checks/verified-commits.sh +3 -3
- package/skills/yad-checks/templates/github/yad-checks.yml +357 -69
- package/skills/yad-checks/templates/github/yad-pr-text.yml +118 -0
- package/skills/yad-checks/templates/github/yad-product-checks.yml +130 -54
- package/skills/yad-checks/templates/github/yad-product-pr-text.yml +131 -0
- package/skills/yad-checks/templates/github/yad-update-guard.yml +2 -1
- package/skills/yad-checks/templates/github/yad-verified-commits.yml +49 -3
- package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +79 -20
- package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +59 -9
- package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -0
- package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +49 -1
- package/skills/yad-checks/templates/hooks/agent-guard.mjs +44 -10
- package/skills/yad-checks/templates/hooks/ledger-guard-cursor.mjs +12 -6
- package/skills/yad-commit/SKILL.md +3 -1
- package/skills/yad-connect-design/SKILL.md +48 -13
- package/skills/yad-connect-design/references/design-context.md +56 -3
- package/skills/yad-connect-design/references/design-registry.md +4 -4
- package/skills/yad-connect-learning/SKILL.md +12 -2
- package/skills/yad-connect-repos/SKILL.md +12 -0
- package/skills/yad-connect-testing/SKILL.md +22 -5
- package/skills/yad-connect-testing/references/testing-context.md +1 -1
- package/skills/yad-engineer-review/SKILL.md +13 -0
- package/skills/yad-epic/SKILL.md +4 -0
- package/skills/yad-epic/references/state-schema.md +21 -0
- package/skills/yad-guide/SKILL.md +8 -4
- package/skills/yad-implement/SKILL.md +69 -3
- package/skills/yad-implement/references/implement-conventions.md +2 -1
- package/skills/yad-issues/SKILL.md +53 -0
- package/skills/yad-learn/SKILL.md +4 -0
- package/skills/yad-open-pr/SKILL.md +10 -1
- package/skills/yad-pair-review/SKILL.md +5 -0
- package/skills/yad-pr-template/SKILL.md +2 -1
- package/skills/yad-pr-template/templates/checks/pr-title.sh +34 -2
- package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -0
- package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -0
- package/skills/yad-product-bridge/references/bridge.md +28 -0
- package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +25 -11
- package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +38 -14
- package/skills/yad-review-companion/SKILL.md +4 -1
- package/skills/yad-run/SKILL.md +5 -0
- package/skills/yad-scan/SKILL.md +51 -0
- package/skills/yad-spec/SKILL.md +32 -0
- package/skills/yad-stories/SKILL.md +22 -0
- package/skills/yad-stories/references/story-schema.md +1 -0
- package/skills/yad-test-cases/SKILL.md +18 -2
- package/skills/yad-ui/SKILL.md +48 -8
- package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +0 -49
package/cli/preview.mjs
ADDED
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
// The preview address of a PR/MR (#359): a live copy of the app that a service (Vercel, Netlify, a
|
|
2
|
+
// review app) deploys for each PR/MR, so a live design check — the page at several screen widths — can
|
|
3
|
+
// run against it instead of only on the developer's machine.
|
|
4
|
+
//
|
|
5
|
+
// Where it comes from, in order (the user's decision, 2026-11-02):
|
|
6
|
+
// 1. a per-repo pattern, `preview_url` in the Product's `.sdlc/repos.json`
|
|
7
|
+
// (`https://pr-{pr}.myapp.dev`), set with `yad repo preview`;
|
|
8
|
+
// 2. else the platform: the newest successful, non-production deployment GitHub/GitLab records for
|
|
9
|
+
// the PR's head (what Vercel/Netlify/review apps report);
|
|
10
|
+
// 3. else none — and the answer says the check runs locally only, and why.
|
|
11
|
+
//
|
|
12
|
+
// One rule (`patternProblems`) is shared by the command that writes a pattern, doctor that reads it and
|
|
13
|
+
// the resolver that fills it, so the three never disagree.
|
|
14
|
+
import { run } from './lib.mjs';
|
|
15
|
+
|
|
16
|
+
export const PREVIEW_KEY = 'preview_url';
|
|
17
|
+
export const PLACEHOLDERS = ['pr', 'branch', 'repo'];
|
|
18
|
+
const MAX_LEN = 2048;
|
|
19
|
+
|
|
20
|
+
// A name made safe for a host name or a path: lowercase, every run of other characters one `-`.
|
|
21
|
+
export const slug = (s) => String(s ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
|
|
22
|
+
|
|
23
|
+
// Is this a URL yad may print and write into a PR/MR description? https, or http on this machine
|
|
24
|
+
// (a local preview server). Printable ASCII only, and none of the characters that end a Markdown link
|
|
25
|
+
// or an HTML attribute — the text comes from a shared file or a deployment service.
|
|
26
|
+
export function urlProblem(u) {
|
|
27
|
+
if (typeof u !== 'string' || !u) return 'is not a URL';
|
|
28
|
+
if (u.length > MAX_LEN) return `longer than ${MAX_LEN} characters`;
|
|
29
|
+
if (!/^[\x21-\x7e]+$/.test(u)) return 'has a space, a control character or a non-ASCII character';
|
|
30
|
+
if (/[<>"'`\\]/.test(u)) return 'has a character that is not allowed in it (< > " \' ` \\)';
|
|
31
|
+
let p;
|
|
32
|
+
try { p = new URL(u); } catch { return 'is not a URL'; }
|
|
33
|
+
if (p.username || p.password) return 'carries a user name or password';
|
|
34
|
+
if (p.protocol === 'https:') return null;
|
|
35
|
+
if (p.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(p.hostname)) return null;
|
|
36
|
+
return 'must start with https:// (or http://localhost)';
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
// Why a pattern cannot be used, or [] when it can. The placeholders are filled with harmless sample
|
|
40
|
+
// values, so the URL check sees what a filled pattern would be.
|
|
41
|
+
export function patternProblems(p) {
|
|
42
|
+
if (typeof p !== 'string') return ['is not text'];
|
|
43
|
+
const problems = [];
|
|
44
|
+
const unknown = [...p.matchAll(/\{([^}]*)\}/g)].map((m) => m[1]).filter((n) => !PLACEHOLDERS.includes(n));
|
|
45
|
+
if (unknown.length) problems.push(`has an unknown placeholder ${[...new Set(unknown)].map((n) => `{${n}}`).join(', ')} (use {pr}, {branch} or {repo})`);
|
|
46
|
+
if (/[{}]/.test(p.replace(/\{(pr|branch|repo)\}/g, ''))) {
|
|
47
|
+
if (!unknown.length) problems.push('has a lone { or }');
|
|
48
|
+
}
|
|
49
|
+
const sample = p.replace(/\{pr\}/g, '1').replace(/\{branch\}/g, 'branch').replace(/\{repo\}/g, 'repo');
|
|
50
|
+
if (!unknown.length && !/[{}]/.test(sample)) {
|
|
51
|
+
const why = urlProblem(sample);
|
|
52
|
+
if (why) problems.push(why);
|
|
53
|
+
}
|
|
54
|
+
return problems;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
// The pattern recorded for a repo entry: { pattern } when there is a usable one, { problems } when one
|
|
58
|
+
// is recorded but cannot be used, {} when none is recorded.
|
|
59
|
+
export function previewPattern(meta) {
|
|
60
|
+
if (!meta || typeof meta !== 'object' || !(PREVIEW_KEY in meta) || meta[PREVIEW_KEY] == null) return {};
|
|
61
|
+
const p = meta[PREVIEW_KEY];
|
|
62
|
+
const problems = patternProblems(p);
|
|
63
|
+
return problems.length ? { problems } : { pattern: p };
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
// The pattern with its placeholders filled, or null when it needs a value that is missing ({pr} before
|
|
67
|
+
// the PR exists) or the result is not a URL yad would write.
|
|
68
|
+
export function fillPattern(p, { pr, branch, repo } = {}) {
|
|
69
|
+
if (patternProblems(p).length) return null;
|
|
70
|
+
const vals = { pr: pr == null || pr === '' ? null : String(pr), branch: slug(branch) || null, repo: slug(repo) || null };
|
|
71
|
+
if (vals.pr != null && !/^\d+$/.test(vals.pr)) return null;
|
|
72
|
+
let missing = false;
|
|
73
|
+
const out = p.replace(/\{(pr|branch|repo)\}/g, (_m, k) => { if (vals[k] == null) { missing = true; return ''; } return vals[k]; });
|
|
74
|
+
if (missing) return null;
|
|
75
|
+
return urlProblem(out) ? null : out;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
export const needs = (p, key) => typeof p === 'string' && p.includes(`{${key}}`);
|
|
79
|
+
|
|
80
|
+
const parse = (s) => { try { return JSON.parse(s); } catch { return undefined; } };
|
|
81
|
+
// A review must not stall on a slow or unreachable host: one budget covers every call the lookup makes
|
|
82
|
+
// (the PR's head, the deployments, their statuses), and each call gets only the time that is left.
|
|
83
|
+
// Spent, the answer is local-only, with why.
|
|
84
|
+
const PLATFORM_TIMEOUT = 8000;
|
|
85
|
+
export const PLATFORM_BUDGET = 15000;
|
|
86
|
+
const MIN_CALL = 500;
|
|
87
|
+
export function budget(now = Date.now, total = PLATFORM_BUDGET) {
|
|
88
|
+
const until = now() + total;
|
|
89
|
+
return { now, left: () => Math.min(PLATFORM_TIMEOUT, until - now()), spent: () => until - now() < MIN_CALL };
|
|
90
|
+
}
|
|
91
|
+
export const isPrNumber = (pr) => pr != null && /^\d+$/.test(String(pr));
|
|
92
|
+
const isSha = (s) => typeof s === 'string' && /^[0-9a-f]{7,64}$/i.test(s);
|
|
93
|
+
// A production environment is the live site, never a PR's preview — however the integration marked it.
|
|
94
|
+
// `production`, `prod`, and names that start with them: Vercel's `Production – app`, `production-eu`, `prod_us`.
|
|
95
|
+
const isProduction = (name) => typeof name === 'string' && /^prod(uction)?(?![a-z0-9])/i.test(name.trim());
|
|
96
|
+
|
|
97
|
+
// The newest successful, non-production deployment the platform records for the PR's head commit
|
|
98
|
+
// (GitHub) or branch (GitLab). Never throws: { url } or { url: null, why }.
|
|
99
|
+
export function platformPreview(platform, { cwd, sha, branch, pr = null, runner = run, clock = budget() } = {}) {
|
|
100
|
+
const opts = () => ({ cwd, timeout: clock.left() });
|
|
101
|
+
const slow = (host) => ({ url: null, why: `${host} was too slow to answer about deployments` });
|
|
102
|
+
if (platform === 'github') {
|
|
103
|
+
if (!isSha(sha)) return { url: null, why: 'the PR\'s head commit is not known' };
|
|
104
|
+
if (clock.spent()) return slow('GitHub');
|
|
105
|
+
const r = runner('gh', ['api', `repos/{owner}/{repo}/deployments?sha=${sha}&per_page=20`], opts());
|
|
106
|
+
if (!r.ok) return { url: null, why: 'GitHub could not be asked for deployments (gh not signed in, offline, or no GitHub remote)' };
|
|
107
|
+
const list = parse(r.stdout);
|
|
108
|
+
if (!Array.isArray(list)) return { url: null, why: 'GitHub gave an answer yad cannot read' };
|
|
109
|
+
// Newest first, as GitHub lists them.
|
|
110
|
+
const candidates = list.filter((d) => d && typeof d === 'object' && Number.isInteger(d.id)
|
|
111
|
+
&& d.production_environment !== true && !isProduction(d.environment));
|
|
112
|
+
let asked = 0, failed = 0;
|
|
113
|
+
for (const d of candidates.slice(0, 3)) {
|
|
114
|
+
if (clock.spent()) return slow('GitHub');
|
|
115
|
+
asked++;
|
|
116
|
+
const s = runner('gh', ['api', `repos/{owner}/{repo}/deployments/${d.id}/statuses?per_page=20`], opts());
|
|
117
|
+
const statuses = s.ok ? parse(s.stdout) : undefined;
|
|
118
|
+
if (!Array.isArray(statuses)) { failed++; continue; }
|
|
119
|
+
// The newest status decides (GitHub lists them newest first): not success now is not live now.
|
|
120
|
+
const latest = statuses.find((x) => x && typeof x === 'object' && typeof x.state === 'string');
|
|
121
|
+
if (!latest || latest.state !== 'success') continue;
|
|
122
|
+
const url = latest.environment_url;
|
|
123
|
+
if (!url) continue;
|
|
124
|
+
if (urlProblem(url)) return { url: null, why: 'GitHub reports a deployment address yad will not use (not https, or an odd character in it)' };
|
|
125
|
+
return { url };
|
|
126
|
+
}
|
|
127
|
+
if (asked && failed === asked) return { url: null, why: 'GitHub could not be asked for the deployments\' status' };
|
|
128
|
+
return { url: null, why: candidates.length ? 'GitHub lists no successful deployment with an address for this commit' : 'GitHub lists no preview deployment for this commit' };
|
|
129
|
+
}
|
|
130
|
+
if (platform === 'gitlab') {
|
|
131
|
+
if (!branch && !pr) return { url: null, why: 'the PR\'s branch is not known' };
|
|
132
|
+
if (clock.spent()) return slow('GitLab');
|
|
133
|
+
// The deployments list has no branch filter: the newest 100 successful ones are read, and only this
|
|
134
|
+
// branch's (at its head commit, when known) are kept. A deployment's environment there is a short
|
|
135
|
+
// record, so the environment itself is asked whether it is still running and not production.
|
|
136
|
+
const r = runner('glab', ['api', 'projects/:id/deployments?status=success&order_by=id&sort=desc&per_page=100'], opts());
|
|
137
|
+
if (!r.ok) return { url: null, why: 'GitLab could not be asked for deployments (glab not signed in, offline, or no GitLab remote)' };
|
|
138
|
+
const list = parse(r.stdout);
|
|
139
|
+
if (!Array.isArray(list)) return { url: null, why: 'GitLab gave an answer yad cannot read' };
|
|
140
|
+
const env = (x) => (x && typeof x === 'object' && x.environment && typeof x.environment === 'object' ? x.environment : null);
|
|
141
|
+
const seen = new Set();
|
|
142
|
+
// A merge-request pipeline deploys from `refs/merge-requests/<iid>/head` (a merged-results one, a
|
|
143
|
+
// merge commit whose id is not the MR head's): for that ref the commit is not compared. The skills
|
|
144
|
+
// still treat a page that does not show the change as local-only. Newest first: the answer is the
|
|
145
|
+
// newest one whose environment is still running.
|
|
146
|
+
const mrRef = pr ? `refs/merge-requests/${pr}/head` : null;
|
|
147
|
+
const candidates = list.filter((x) => env(x) && ((x.ref === branch && (!sha || x.sha === sha)) || (mrRef && x.ref === mrRef))
|
|
148
|
+
&& Number.isInteger(env(x).id) && !isProduction(env(x).name) && !seen.has(env(x).id) && seen.add(env(x).id));
|
|
149
|
+
let asked = 0, failed = 0;
|
|
150
|
+
for (const d of candidates.slice(0, 3)) {
|
|
151
|
+
if (clock.spent()) return slow('GitLab');
|
|
152
|
+
asked++;
|
|
153
|
+
const e = runner('glab', ['api', `projects/:id/environments/${env(d).id}`], opts());
|
|
154
|
+
const full = e.ok ? parse(e.stdout) : undefined;
|
|
155
|
+
if (!full || typeof full !== 'object') { failed++; continue; }
|
|
156
|
+
if (full.state !== 'available' || isProduction(full.tier) || isProduction(full.name) || !full.external_url) continue;
|
|
157
|
+
if (urlProblem(full.external_url)) return { url: null, why: 'GitLab reports a deployment address yad will not use (not https, or an odd character in it)' };
|
|
158
|
+
return { url: full.external_url };
|
|
159
|
+
}
|
|
160
|
+
if (asked && failed === asked) return { url: null, why: 'GitLab could not be asked about the review environments' };
|
|
161
|
+
// `listedNone`: GitLab answered and listed nothing that fits — the one answer --pr could change.
|
|
162
|
+
return { url: null, listedNone: true, why: 'GitLab lists no successful, running review deployment with an address for this branch or MR among its newest 100 deployments' };
|
|
163
|
+
}
|
|
164
|
+
return { url: null, why: 'the platform is not GitHub or GitLab' };
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
// The PR/MR's head commit and branch. With a PR number they are asked of the platform, and only the
|
|
168
|
+
// platform's answer counts: this checkout may be on another branch (main, a detached worktree), and its
|
|
169
|
+
// preview is not the PR's. Without one, this checkout's (the review of the branch you are on).
|
|
170
|
+
// { sha, branch } or { sha: null, branch: null, why }.
|
|
171
|
+
export function prHead(platform, pr, { cwd, runner = run, clock = budget(), base = null } = {}) {
|
|
172
|
+
if (!pr) {
|
|
173
|
+
const sha = runner('git', ['rev-parse', 'HEAD'], { cwd }).stdout || null;
|
|
174
|
+
const b = runner('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd }).stdout || null;
|
|
175
|
+
// The default branch is not a PR's branch: its deployment is the main site, never a preview.
|
|
176
|
+
// Detached is no PR's either: yad's worktrees are detached at the default branch (#115).
|
|
177
|
+
if (b && base && b === base) return { sha: null, branch: null, why: `this checkout is on the default branch (${base}), not the PR's` };
|
|
178
|
+
if (b === 'HEAD') return { sha: null, branch: null, why: 'this checkout is on no branch (detached)' };
|
|
179
|
+
if (!b) return { sha: null, branch: null, why: 'this checkout\'s branch could not be read' };
|
|
180
|
+
return { sha: isSha(sha) ? sha : null, branch: b };
|
|
181
|
+
}
|
|
182
|
+
const none = (why) => ({ sha: null, branch: null, why });
|
|
183
|
+
if (!isPrNumber(pr)) return none('the PR number given (--pr) is not a number');
|
|
184
|
+
if (clock.spent()) return none('the platform was too slow to answer');
|
|
185
|
+
const opts = { cwd, timeout: clock.left() };
|
|
186
|
+
if (platform === 'github') {
|
|
187
|
+
const r = runner('gh', ['pr', 'view', String(pr), '--json', 'headRefOid,headRefName'], opts);
|
|
188
|
+
const j = r.ok ? parse(r.stdout) : null;
|
|
189
|
+
if (j && isSha(j.headRefOid)) return { sha: j.headRefOid, branch: typeof j.headRefName === 'string' && j.headRefName ? j.headRefName : null };
|
|
190
|
+
return none(`GitHub could not be asked for PR #${pr}'s head branch (gh not signed in, offline, or no such PR)`);
|
|
191
|
+
}
|
|
192
|
+
if (platform === 'gitlab') {
|
|
193
|
+
const r = runner('glab', ['mr', 'view', String(pr), '-F', 'json'], opts);
|
|
194
|
+
const j = r.ok ? parse(r.stdout) : null;
|
|
195
|
+
if (j && isSha(j.sha)) return { sha: j.sha, branch: typeof j.source_branch === 'string' && j.source_branch ? j.source_branch : null };
|
|
196
|
+
return none(`GitLab could not be asked for MR !${pr}'s source branch (glab not signed in, offline, or no such MR)`);
|
|
197
|
+
}
|
|
198
|
+
return none('the platform is not GitHub or GitLab');
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
// The answer a review step uses: { url, source: 'pattern'|'platform' } or
|
|
202
|
+
// { url: null, source: 'local-only', why }. `why` says what was tried and how to set a pattern.
|
|
203
|
+
// The PR's head is asked only when it is needed: a {pr} or {repo} pattern answers with no network call.
|
|
204
|
+
export function resolvePreview({ meta, platform, pr, base = null, cwd, runner = run, lookup = platformPreview, clock = budget(), head: given } = {}) {
|
|
205
|
+
const repo = meta?.name;
|
|
206
|
+
let head = given || null;
|
|
207
|
+
const getHead = () => (head ||= prHead(platform, pr, { cwd, runner, clock, base }));
|
|
208
|
+
const tried = [];
|
|
209
|
+
const pat = previewPattern(meta);
|
|
210
|
+
if (pat.pattern) {
|
|
211
|
+
const h = needs(pat.pattern, 'branch') ? getHead() : {};
|
|
212
|
+
const url = fillPattern(pat.pattern, { pr, branch: h.branch, repo });
|
|
213
|
+
if (url) return { url, source: 'pattern' };
|
|
214
|
+
if (needs(pat.pattern, 'pr') && pr && !isPrNumber(pr)) tried.push('the PR number given (--pr) is not a number');
|
|
215
|
+
else if (needs(pat.pattern, 'pr') && !pr) tried.push('the repo\'s preview_url pattern needs the PR number ({pr}), and none was given (--pr)');
|
|
216
|
+
else if (needs(pat.pattern, 'branch') && !h.branch) tried.push(`the repo's preview_url pattern needs the PR's branch ({branch}), and it is not known: ${h.why || 'no branch'}`);
|
|
217
|
+
else tried.push('the repo\'s preview_url pattern could not be filled');
|
|
218
|
+
} else if (pat.problems) {
|
|
219
|
+
tried.push(`the repo's preview_url pattern cannot be used: it ${pat.problems.join('; ')}`);
|
|
220
|
+
} else {
|
|
221
|
+
tried.push(`no preview_url pattern is recorded for ${repo ? 'this repo' : 'a repo outside the registry'}`);
|
|
222
|
+
}
|
|
223
|
+
const h = getHead();
|
|
224
|
+
const p = h.sha || h.branch ? lookup(platform, { cwd, sha: h.sha, branch: h.branch, pr, runner, clock }) : { url: null, why: h.why };
|
|
225
|
+
if (p?.url) return { url: p.url, source: 'platform' };
|
|
226
|
+
if (p?.why && !tried.some((t) => t === p.why || t.endsWith(p.why))) tried.push(p.why);
|
|
227
|
+
// GitLab's merge-request pipelines deploy under the MR's own ref, which only its number finds — said
|
|
228
|
+
// only when GitLab was asked and listed nothing (a GitLab it could not ask, --pr would not help).
|
|
229
|
+
const gitlabNoPr = !pr && platform === 'gitlab' && p?.listedNone === true;
|
|
230
|
+
if (gitlabNoPr) tried.push('a merge-request pipeline\'s deployment is found only with --pr');
|
|
231
|
+
const fix = repo ? 'set one with `yad repo preview <repo> <pattern>`' : 'register the repo, then set one with `yad repo preview <repo> <pattern>`';
|
|
232
|
+
// One next step, chosen here, the one that most likely unblocks the answer: a --pr that is missing
|
|
233
|
+
// or wrong when it is what stopped it, then a pattern to fix, then --pr for GitLab's MR pipelines.
|
|
234
|
+
const badPr = pr && !isPrNumber(pr);
|
|
235
|
+
const next = badPr || (!pr && ((pat.pattern && needs(pat.pattern, 'pr')) || (head && !head.branch && !head.sha))) ? 'pass --pr <n>'
|
|
236
|
+
: pat.pattern ? 'check the pattern with `yad repo preview <repo>`'
|
|
237
|
+
: pat.problems ? 'set it again with `yad repo preview <repo> <pattern>`'
|
|
238
|
+
: gitlabNoPr ? 'pass --pr <n>' : fix;
|
|
239
|
+
return { url: null, source: 'local-only', why: `${tried.join('; ')} — ${next}` };
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
// The PR/MR description's Preview line, at open time: a pattern that can be filled now, else a note
|
|
243
|
+
// that says which case it is. A {pr} pattern is filled after the PR exists (`runOpenPr` edits the body).
|
|
244
|
+
export const PREVIEW_NONE = 'none recorded — a live design check runs locally only, unless the platform reports a deployment for this PR';
|
|
245
|
+
export const PREVIEW_UNFILLED = 'a preview_url pattern is recorded but could not be filled here — `yad review context --pr <n>` gives the address';
|
|
246
|
+
export const PREVIEW_UNUSABLE = 'the recorded preview_url pattern cannot be used — a live design check runs locally only, unless the platform reports a deployment for this PR; fix it with `yad repo preview <repo> <pattern>`';
|
|
247
|
+
export function previewLine(meta, { pr, branch } = {}) {
|
|
248
|
+
const pat = previewPattern(meta);
|
|
249
|
+
if (pat.problems) return PREVIEW_UNUSABLE;
|
|
250
|
+
if (!pat.pattern) return PREVIEW_NONE;
|
|
251
|
+
const url = fillPattern(pat.pattern, { pr, branch, repo: meta?.name });
|
|
252
|
+
return url ? `<${url}>` : PREVIEW_UNFILLED;
|
|
253
|
+
}
|
package/cli/protection.mjs
CHANGED
|
@@ -716,14 +716,15 @@ function unknownHint(r) {
|
|
|
716
716
|
}
|
|
717
717
|
|
|
718
718
|
// E160b — what `yad ci check` reads beyond protection and approvals: the rules that make yad's checks hold a
|
|
719
|
-
// merge. Read-only, the same calls `readProtection` makes plus a few GETs, and the same trap: a failed call is
|
|
719
|
+
// merge. Read-only, the same calls `readProtection` makes plus a few GETs and one GraphQL query, and the same trap: a failed call is
|
|
720
720
|
// never "none". `readProtection` runs first, so a repo that cannot be read (no platform, reads turned off,
|
|
721
721
|
// no login…) comes back with only `protection`, and every platform row is "not known" with its reason.
|
|
722
722
|
// GitHub — `rules`: the active rules on the branch (null when not read; `full` when a whole page came
|
|
723
723
|
// back, which proves nothing about what is past it). `classic`: classic branch protection, the
|
|
724
724
|
// string 'none' when PROVEN absent (the branch reads `protected: false`, or GitHub answers 404 with
|
|
725
725
|
// exactly "Branch not protected"), or null — GitHub answers a bare 404 to anyone who is not an
|
|
726
|
-
// admin, even on a protected branch.
|
|
726
|
+
// admin, even on a protected branch. `mergeQueue` (#433): 'on' / 'off' from one GraphQL query (a read),
|
|
727
|
+
// null when it was not answered.
|
|
727
728
|
// GitLab — the project's merge settings, the protected-branch entries that match the branch (null when not
|
|
728
729
|
// read), the approval settings (Premium) and the push rule (Premium; a 404 is "no push rule").
|
|
729
730
|
export function readCiSettings(target, { runner: ask = run, env = process.env, authCache = new Map() } = {}) {
|
|
@@ -750,7 +751,24 @@ export function readCiSettings(target, { runner: ask = run, env = process.env, a
|
|
|
750
751
|
if (c.ok && c.body && typeof c.body === 'object' && !Array.isArray(c.body)) classic = c.body;
|
|
751
752
|
else if (c.status === 404 && c.body?.message === 'Branch not protected') classic = 'none';
|
|
752
753
|
}
|
|
753
|
-
|
|
754
|
+
// #433: a merge queue can be turned on by a ruleset or by classic branch protection, and the classic answer
|
|
755
|
+
// does not show it. GraphQL names the queue whatever turned it on: an object when on, null when off.
|
|
756
|
+
// The names go in as variables, never into the query text, and with -f, as plain strings: -F would turn
|
|
757
|
+
// `123` or `true` into a number or a boolean, and read a file for a value that starts with `@`.
|
|
758
|
+
// Anything else is not known (null).
|
|
759
|
+
const [owner, name] = repo.split('/');
|
|
760
|
+
const q = runner('gh', ['api', '--hostname', host, 'graphql',
|
|
761
|
+
'-f', 'query=query($owner: String!, $name: String!, $branch: String!) { repository(owner: $owner, name: $name) { mergeQueue(branch: $branch) { id } } }',
|
|
762
|
+
'-f', `owner=${owner}`, '-f', `branch=${branch}`, '-f', `name=${name}`], { timeout: TIMEOUT });
|
|
763
|
+
let mergeQueue = null;
|
|
764
|
+
if (q.ok) {
|
|
765
|
+
try {
|
|
766
|
+
const body = JSON.parse(q.stdout);
|
|
767
|
+
const repoNode = body?.data?.repository;
|
|
768
|
+
if (!body?.errors && repoNode && typeof repoNode === 'object' && 'mergeQueue' in repoNode) mergeQueue = repoNode.mergeQueue ? 'on' : 'off';
|
|
769
|
+
} catch { /* not JSON: not known */ }
|
|
770
|
+
}
|
|
771
|
+
return { protection, rules, rulesFull: !!rules && rules.length >= PAGE, classic, mergeQueue };
|
|
754
772
|
}
|
|
755
773
|
const at = `projects/${encodeURIComponent(repo)}`;
|
|
756
774
|
const obj = (res) => (res.ok && res.body && typeof res.body === 'object' && !Array.isArray(res.body) ? res.body : null);
|
package/cli/reconcile.mjs
CHANGED
|
@@ -218,7 +218,7 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
|
|
|
218
218
|
// `product` is on disk or this run installs one — the same test `yad doctor` makes (review 2).
|
|
219
219
|
const productRel = (p) => path.relative(root, p).split(path.sep).join('/');
|
|
220
220
|
const installsProduct = actions.filter((a) => a.managed && a.managed.root === root
|
|
221
|
-
&& /(^|\/)yad-product-checks\.yml$/.test(productRel(a.managed.dest))
|
|
221
|
+
&& /(^|\/)yad-product-(checks|pr-text)\.yml$/.test(productRel(a.managed.dest))
|
|
222
222
|
&& a.status !== 'ok' && a.status !== 'modified' && (scope === 'all' || a.status !== 'missing'))
|
|
223
223
|
.map((a) => productRel(a.managed.dest));
|
|
224
224
|
const passing = [...new Set([...workflowsPassingProduct(root), ...installsProduct])];
|
package/cli/repo.mjs
CHANGED
|
@@ -12,6 +12,7 @@ import { PROJECT_FILES } from './manifest.mjs';
|
|
|
12
12
|
import { judgeRepo, cloneMissingRepos, reportClones, readRegistry, codeContextPathOk, CODE_CONTEXT_DIR, runnable, shown } from './workspace.mjs';
|
|
13
13
|
import { gitHead, packRepo } from './setup.mjs';
|
|
14
14
|
import { publishCodeContext, packOf, codeMapOf } from './repo-publish.mjs';
|
|
15
|
+
import { PREVIEW_KEY, patternProblems } from './preview.mjs';
|
|
15
16
|
|
|
16
17
|
// Why `refresh` will not pack this entry, or null when it will (E81): see the loop in `runRepo`.
|
|
17
18
|
function notPackable(root, repo, j) {
|
|
@@ -59,7 +60,7 @@ function defaultBranch(cwd, repo) {
|
|
|
59
60
|
return !/^[-+]/.test(b) && git(cwd, 'check-ref-format', `refs/heads/${b}`).ok ? b : null;
|
|
60
61
|
}
|
|
61
62
|
|
|
62
|
-
export async function runRepo(root, { action = 'list', name, today, push = false, allowBranch = false } = {}) {
|
|
63
|
+
export async function runRepo(root, { action = 'list', name, pattern, clear = false, today, push = false, allowBranch = false } = {}) {
|
|
63
64
|
const { regPath, registry, problem } = load(root);
|
|
64
65
|
if (problem) { fail(`${problem} — fix it in the Product and re-run`); process.exitCode = 1; return { action, repos: [] }; }
|
|
65
66
|
if (!registry.repos.length) { warn('no repos registered (.sdlc/repos.json) — run `yad setup`'); return { action, repos: [] }; }
|
|
@@ -88,7 +89,9 @@ export async function runRepo(root, { action = 'list', name, today, push = false
|
|
|
88
89
|
}
|
|
89
90
|
const { head, stale, unknown, neverPacked } = staleness(root, repo);
|
|
90
91
|
rows.push({ name: repo.name ?? null, path: repo.path ?? null, head: head || null, syncedHead: repo.syncedHead ?? null,
|
|
91
|
-
state: unknown ? 'unreadable' : neverPacked ? 'no-pack' : stale ? 'stale' : 'fresh'
|
|
92
|
+
state: unknown ? 'unreadable' : neverPacked ? 'no-pack' : stale ? 'stale' : 'fresh',
|
|
93
|
+
...(typeof repo[PREVIEW_KEY] === 'string' ? { preview_url: repo[PREVIEW_KEY] } : {}) });
|
|
94
|
+
if (typeof repo[PREVIEW_KEY] === 'string') info(`${j.name} ${c.dim('— preview')} ${shown(repo[PREVIEW_KEY])}`);
|
|
92
95
|
if (unknown) { warn(`${j.name} ${c.dim(`(${j.path})`)} — HEAD unreadable`); continue; }
|
|
93
96
|
if (neverPacked) { staleCount++; warn(`${j.name} ${c.dim(`(${j.path})`)} — ${c.yellow('no code-context pack yet')} (registered without one)`); }
|
|
94
97
|
else if (stale) { staleCount++; warn(`${j.name} ${c.dim(`(${j.path})`)} — ${c.yellow('stale')} (HEAD moved since last pack)`); }
|
|
@@ -225,7 +228,65 @@ export async function runRepo(root, { action = 'list', name, today, push = false
|
|
|
225
228
|
return { action, ...repos };
|
|
226
229
|
}
|
|
227
230
|
|
|
228
|
-
|
|
231
|
+
if (action === 'preview') return previewAction(root, entries, regPath, registry, { name, pattern, clear, push });
|
|
232
|
+
|
|
233
|
+
fail(`unknown repo action: ${action} (list | refresh | sync | clone | preview)`);
|
|
229
234
|
process.exitCode = 1;
|
|
230
235
|
return { action };
|
|
231
236
|
}
|
|
237
|
+
|
|
238
|
+
// `yad repo preview <name> [<pattern>] [--clear]` (#359): show, set or clear the repo's preview address
|
|
239
|
+
// pattern — `https://pr-{pr}.myapp.dev`, filled per PR/MR so a live design check runs against the
|
|
240
|
+
// deployed copy. A team setting in the Product's registry: written here, committed by the person.
|
|
241
|
+
function previewAction(root, entries, regPath, registry, { name, pattern, clear, push }) {
|
|
242
|
+
const done = (extra) => ({ action: 'preview', name: name ?? null, ...extra });
|
|
243
|
+
const usage = 'yad repo preview <name> [<pattern>] [--clear]';
|
|
244
|
+
// It writes one shared file and commits nothing: `--push` would read as a promise it does not keep.
|
|
245
|
+
if (push) { fail(`--push does not apply to \`yad repo preview\` — it writes ${PROJECT_FILES.reposRegistry}; commit that in the Product`); process.exitCode = 1; return done({ preview_url: null }); }
|
|
246
|
+
if (!name) { fail(`usage: ${usage}`); process.exitCode = 1; return done({ preview_url: null }); }
|
|
247
|
+
const matches = entries.filter((r) => r.name === name);
|
|
248
|
+
if (!matches.length) { fail(`unknown repo: ${shown(name)}`); process.exitCode = 1; return done({ preview_url: null }); }
|
|
249
|
+
if (matches.length > 1) { fail(`${matches.length} entries in ${PROJECT_FILES.reposRegistry} are named ${shown(name)} — fix the registry first`); process.exitCode = 1; return done({ preview_url: null }); }
|
|
250
|
+
const repo = matches[0];
|
|
251
|
+
const current = typeof repo[PREVIEW_KEY] === 'string' ? repo[PREVIEW_KEY] : null;
|
|
252
|
+
if (clear && pattern !== undefined) { fail(`give a pattern or --clear, not both (${usage})`); process.exitCode = 1; return done({ preview_url: current }); }
|
|
253
|
+
|
|
254
|
+
if (!clear && pattern === undefined) {
|
|
255
|
+
if (repo[PREVIEW_KEY] == null) info(`${shown(name)} has no preview address pattern — set one with \`${usage}\``);
|
|
256
|
+
else {
|
|
257
|
+
const problems = patternProblems(repo[PREVIEW_KEY]);
|
|
258
|
+
if (problems.length) warn(`${shown(name)}'s preview_url cannot be used: it ${problems.join('; ')} — set it again with \`${usage}\``);
|
|
259
|
+
else ok(`${shown(name)} — preview ${shown(current)}`);
|
|
260
|
+
}
|
|
261
|
+
return done({ preview_url: current, problems: repo[PREVIEW_KEY] == null ? [] : patternProblems(repo[PREVIEW_KEY]) });
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
if (!clear) {
|
|
265
|
+
const problems = patternProblems(pattern);
|
|
266
|
+
if (problems.length) {
|
|
267
|
+
fail(`the preview address pattern ${problems.join('; ')} — nothing written`);
|
|
268
|
+
hand('a pattern is a URL that may hold {pr}, {branch} and {repo}, for example https://pr-{pr}.myapp.dev');
|
|
269
|
+
process.exitCode = 1;
|
|
270
|
+
return done({ preview_url: current, problems });
|
|
271
|
+
}
|
|
272
|
+
}
|
|
273
|
+
// Never through a `.sdlc` the Product commits as a link (as `refresh`): the write would land where it points.
|
|
274
|
+
let sdlcLinked = false;
|
|
275
|
+
try { sdlcLinked = fs.lstatSync(path.dirname(regPath)).isSymbolicLink(); } catch { /* not there */ }
|
|
276
|
+
if (sdlcLinked) {
|
|
277
|
+
fail(`${path.dirname(PROJECT_FILES.reposRegistry)} in the Product is a link — ${PROJECT_FILES.reposRegistry} was not written`);
|
|
278
|
+
process.exitCode = 1;
|
|
279
|
+
return done({ preview_url: current });
|
|
280
|
+
}
|
|
281
|
+
if (clear) {
|
|
282
|
+
if (!(PREVIEW_KEY in repo)) { info(`${shown(name)} has no preview address pattern — nothing to clear`); return done({ preview_url: null, changed: false }); }
|
|
283
|
+
delete repo[PREVIEW_KEY];
|
|
284
|
+
} else {
|
|
285
|
+
if (current === pattern) { info(`${shown(name)} already has that preview address pattern`); return done({ preview_url: current, changed: false }); }
|
|
286
|
+
repo[PREVIEW_KEY] = pattern;
|
|
287
|
+
}
|
|
288
|
+
writeJSON(regPath, registry);
|
|
289
|
+
ok(clear ? `${shown(name)} — preview address pattern cleared` : `${shown(name)} — preview ${shown(pattern)}`);
|
|
290
|
+
hand(`commit ${PROJECT_FILES.reposRegistry} in the Product so the team shares it`);
|
|
291
|
+
return done({ preview_url: clear ? null : pattern, changed: true });
|
|
292
|
+
}
|
package/cli/review.mjs
CHANGED
|
@@ -17,6 +17,7 @@ import {
|
|
|
17
17
|
} from './platform.mjs';
|
|
18
18
|
import { upsertTrailerBlock, nudgeMessage, parseEngagement } from './companion.mjs';
|
|
19
19
|
import { sequenceDiff } from './walkthrough.mjs';
|
|
20
|
+
import { resolvePreview } from './preview.mjs';
|
|
20
21
|
|
|
21
22
|
const NUDGE_CMD = 'yad review chat';
|
|
22
23
|
|
|
@@ -68,6 +69,9 @@ function contextBundle(root, { repo, dir, product, pr, runner = run } = {}) {
|
|
|
68
69
|
codeMap: meta?.name ? path.join(rr.productRoot, '.sdlc/code-context', meta.name, 'code-map.md') : null,
|
|
69
70
|
pack: meta?.name ? path.join(rr.productRoot, '.sdlc/code-context', meta.name, 'pack.md') : null,
|
|
70
71
|
contract: meta?.contract || null,
|
|
72
|
+
// Where a live design check (the page at several screen widths) runs (#359): the PR's preview
|
|
73
|
+
// address, or `local-only` with why — the review then says the check ran locally only.
|
|
74
|
+
preview: resolvePreview({ meta, platform, pr: pr || null, base, cwd: repoRoot, runner }),
|
|
71
75
|
markers: {
|
|
72
76
|
trailerBegin: '<!-- yad:trailer -->', noblock: '<!-- yad:noblock -->',
|
|
73
77
|
engagementVerified: '<!-- yad:engagement verified -->', pair: '<!-- yad:pair -->',
|
package/cli/run-checks.mjs
CHANGED
|
@@ -33,7 +33,7 @@ import path from 'node:path';
|
|
|
33
33
|
import { spawn, spawnSync } from 'node:child_process';
|
|
34
34
|
import { setTimeout, clearTimeout, setImmediate } from 'node:timers';
|
|
35
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';
|
|
36
|
+
import { detectPlatform, forkBranch, forkBranchWords, resolveBaseBranch } from './platform.mjs';
|
|
37
37
|
import { registryEntryFor } from './find-product.mjs';
|
|
38
38
|
import { repoPathFromGitUrl } from './protection.mjs';
|
|
39
39
|
import { rangeTasks, groupWarnings } from './build.mjs';
|
|
@@ -314,6 +314,7 @@ export async function runChecks(dir, opts = {}) {
|
|
|
314
314
|
|
|
315
315
|
// The base: as given, else the branch `yad open-pr` would open the PR against, fetched first.
|
|
316
316
|
let base = opts.base;
|
|
317
|
+
let chosenBase = null;
|
|
317
318
|
if (!base) {
|
|
318
319
|
// The Product's own default_branch counts only for the Product itself: a code repo's trunk is its own.
|
|
319
320
|
const chosen = resolveBaseBranch(platform, { cwd: repoRoot, meta, productConfig: isProduct ? settings : null, probe: false });
|
|
@@ -321,6 +322,9 @@ export async function runChecks(dir, opts = {}) {
|
|
|
321
322
|
if (!b) return refuse(`the base branch '${chosen.base}' (from ${chosen.source}) is not a branch name git accepts`, 'pass --base <ref>');
|
|
322
323
|
if (opts.fetch !== false && !fetchBranch(repoRoot, b).ok) warn(`could not fetch ${b} from origin — the last fetched origin/${b} is the base`);
|
|
323
324
|
base = `origin/${b}`;
|
|
325
|
+
// A base nobody chose may not be where this branch was cut from (#450) — `yad open-pr` stops there;
|
|
326
|
+
// this run only warns, as it opens nothing.
|
|
327
|
+
if (!['registry', 'product'].includes(chosen.source)) chosenBase = b;
|
|
324
328
|
} else if (base.startsWith('-')) {
|
|
325
329
|
return refuse(`--base '${base}' is not a ref`, 'pass a branch or commit, such as origin/main');
|
|
326
330
|
}
|
|
@@ -328,6 +332,10 @@ export async function runChecks(dir, opts = {}) {
|
|
|
328
332
|
return refuse(`base '${base}' is not a commit here`, 'fetch it (git fetch origin), or pass --base <ref>');
|
|
329
333
|
}
|
|
330
334
|
info(`${isProduct ? 'Product' : 'code repo'} ${path.basename(repoRoot)} · branch ${branchName} · base ${base}`);
|
|
335
|
+
if (chosenBase) {
|
|
336
|
+
const fork = forkBranch(repoRoot, { base: chosenBase, head: branchName });
|
|
337
|
+
if (fork && !fork.skipped) warn(forkBranchWords(fork, chosenBase, { ref: 'origin/', verb: 'check against' }));
|
|
338
|
+
}
|
|
331
339
|
// A grouped PR (#350) — commits carrying several tasks — is warned about over its size limit, as
|
|
332
340
|
// `yad open-pr` warns. Never a failed gate.
|
|
333
341
|
if (!isProduct) {
|
|
@@ -412,7 +420,7 @@ export async function runChecks(dir, opts = {}) {
|
|
|
412
420
|
const results = [];
|
|
413
421
|
let record = null;
|
|
414
422
|
try {
|
|
415
|
-
// The changed paths, for the Product's pr-title/pr-template split, built as yad-product-
|
|
423
|
+
// The changed paths, for the Product's pr-title/pr-template split, built as yad-product-pr-text.yml does.
|
|
416
424
|
const changedFile = path.join(scratch, 'changed');
|
|
417
425
|
if (isProduct) {
|
|
418
426
|
const d = git(repoRoot, ['-c', 'core.quotePath=false', 'diff', '--no-renames', '--name-only', `${base}...HEAD`]);
|