yadflow 4.8.0 → 4.9.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 +27 -0
- package/bin/commands.mjs +1 -0
- package/bin/yad.mjs +22 -2
- package/cli/agent-rules.mjs +7 -0
- package/cli/build.mjs +1 -1
- package/cli/doctor.mjs +105 -0
- package/cli/machine.mjs +141 -0
- package/cli/openpr.mjs +46 -6
- package/cli/preview.mjs +253 -0
- package/cli/repo.mjs +64 -3
- package/cli/review.mjs +4 -0
- package/cli/story-frames.mjs +296 -0
- package/cli/test-machine.mjs +140 -0
- package/cli/test-preview.mjs +511 -0
- package/cli/test-story-frames.mjs +339 -0
- package/cli/toolbox.mjs +34 -0
- package/package.json +3 -3
- package/skills/yad-connect-design/SKILL.md +7 -4
- package/skills/yad-connect-design/references/design-context.md +23 -0
- package/skills/yad-connect-design/references/design-registry.md +3 -3
- package/skills/yad-connect-repos/SKILL.md +8 -0
- package/skills/yad-engineer-review/SKILL.md +13 -0
- package/skills/yad-epic/references/state-schema.md +6 -0
- package/skills/yad-guide/SKILL.md +2 -2
- package/skills/yad-implement/SKILL.md +14 -0
- package/skills/yad-open-pr/SKILL.md +4 -1
- package/skills/yad-pair-review/SKILL.md +5 -0
- 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-review-companion/SKILL.md +4 -1
- package/skills/yad-spec/SKILL.md +21 -0
- package/skills/yad-stories/SKILL.md +22 -0
- package/skills/yad-stories/references/story-schema.md +1 -0
- package/skills/yad-ui/SKILL.md +5 -0
|
@@ -0,0 +1,339 @@
|
|
|
1
|
+
// #354: each story records its design frames (`design-frames: [id, …]`), `yad story frames` reads them
|
|
2
|
+
// with their names and links from the epic's design-links.json, and `yad doctor` warns on any it cannot
|
|
3
|
+
// read. One rule (`frameFindings`) decides for both, and every finding is a warning in both.
|
|
4
|
+
import { test } from 'node:test';
|
|
5
|
+
import assert from 'node:assert/strict';
|
|
6
|
+
import { spawnSync } from 'node:child_process';
|
|
7
|
+
import fs from 'node:fs';
|
|
8
|
+
import os from 'node:os';
|
|
9
|
+
import path from 'node:path';
|
|
10
|
+
import { fileURLToPath } from 'node:url';
|
|
11
|
+
|
|
12
|
+
if (process.env.NODE_TEST_CONTEXT) {
|
|
13
|
+
const write = process.stdout.write;
|
|
14
|
+
for (const k of ['log', 'info']) {
|
|
15
|
+
const orig = console[k];
|
|
16
|
+
console[k] = (...a) => (process.stdout.write === write ? console.error(...a) : orig(...a));
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
process.env.YAD_NO_UPDATE_NOTIFIER = '1';
|
|
20
|
+
|
|
21
|
+
const { frameFindings, readDesignLinks, readStoryFrames, allStoryFrames, FRAMES_KEY } = await import('./story-frames.mjs');
|
|
22
|
+
const { storyFrameChecks } = await import('./doctor.mjs');
|
|
23
|
+
|
|
24
|
+
const HERE = path.dirname(fileURLToPath(import.meta.url));
|
|
25
|
+
const YAD = path.join(HERE, '..', 'bin', 'yad.mjs');
|
|
26
|
+
const REPO = path.join(HERE, '..');
|
|
27
|
+
|
|
28
|
+
const tmp = () => fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'yad-frames-')));
|
|
29
|
+
const put = (file, data) => { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, typeof data === 'string' ? data : JSON.stringify(data)); };
|
|
30
|
+
const done = (T) => fs.rmSync(T, { recursive: true, force: true });
|
|
31
|
+
const story = (id, line) => `---\nid: ${id}\nepic: ${id.replace(/-S\d+$/, '')}\nstatus: draft\nrepos: [web]\n${line === null ? '' : `${line}\n`}---\n\n## Story\n`;
|
|
32
|
+
const LINKS = {
|
|
33
|
+
tool: 'pencil', fileUrl: 'https://design.example/f', direction: 'generate', source: 'pencil',
|
|
34
|
+
screens: [
|
|
35
|
+
{ name: 'Cart', platform: 'web', nodeId: '12:34', url: 'https://design.example/f?node=12:34' },
|
|
36
|
+
{ name: 'Pay', platform: 'mobile', nodeId: 'aB3xQ', url: 'https://design.example/f?node=aB3xQ' },
|
|
37
|
+
],
|
|
38
|
+
};
|
|
39
|
+
const ok = { state: 'ok', tool: 'pencil', fileUrl: LINKS.fileUrl, screens: LINKS.screens };
|
|
40
|
+
const kinds = (r) => r.findings.map((f) => f.kind);
|
|
41
|
+
const BOM = String.fromCharCode(0xfeff);
|
|
42
|
+
|
|
43
|
+
// A Product with one epic: its design-links.json (or none) and the given stories.
|
|
44
|
+
function product(stories, links = LINKS) {
|
|
45
|
+
const T = tmp();
|
|
46
|
+
const epic = path.join(T, 'epics', 'EP-shop');
|
|
47
|
+
fs.mkdirSync(epic, { recursive: true });
|
|
48
|
+
if (links !== null) put(path.join(epic, '.sdlc', 'design-links.json'), links);
|
|
49
|
+
for (const [id, line] of Object.entries(stories)) put(path.join(epic, 'stories', `${id}.md`), story(id, line));
|
|
50
|
+
return T;
|
|
51
|
+
}
|
|
52
|
+
const yad = (T, ...args) => spawnSync(process.execPath, [YAD, ...args, '--dir', T], { encoding: 'utf8', env: { ...process.env, NO_COLOR: '1', SDLC_NONINTERACTIVE: '1' } });
|
|
53
|
+
|
|
54
|
+
test('#354: frameFindings — no key, an empty list, and IDs that all resolve', () => {
|
|
55
|
+
assert.deepEqual(frameFindings({}, ok), { recorded: false, ids: [], frames: [], findings: [] });
|
|
56
|
+
const none = frameFindings({ [FRAMES_KEY]: [] }, { state: 'missing' });
|
|
57
|
+
assert.equal(none.recorded, true);
|
|
58
|
+
assert.deepEqual(none.findings, [], '`[]` needs no design-links.json — a story with no screens');
|
|
59
|
+
const r = frameFindings({ [FRAMES_KEY]: ['12:34', 'aB3xQ'] }, ok);
|
|
60
|
+
assert.deepEqual(r.findings, []);
|
|
61
|
+
assert.deepEqual(r.frames, [
|
|
62
|
+
{ id: '12:34', found: true, name: 'Cart', platform: 'web', url: LINKS.screens[0].url },
|
|
63
|
+
{ id: 'aB3xQ', found: true, name: 'Pay', platform: 'mobile', url: LINKS.screens[1].url },
|
|
64
|
+
], 'a Figma 12:34 ID and a Pencil-style ID both resolve');
|
|
65
|
+
});
|
|
66
|
+
|
|
67
|
+
test('#354: frameFindings — every problem is a finding, never a silent "no frames"', () => {
|
|
68
|
+
assert.deepEqual(kinds(frameFindings({ [FRAMES_KEY]: ['12:34', '99:99'] }, ok)), ['not-found']);
|
|
69
|
+
assert.deepEqual(kinds(frameFindings({ [FRAMES_KEY]: '[12:34] # the cart' }, ok)), ['commented'], 'the comment trap');
|
|
70
|
+
assert.deepEqual(kinds(frameFindings({ [FRAMES_KEY]: '' }, ok)), ['not-a-list'], 'blank — what a `- id` block list reads as');
|
|
71
|
+
assert.deepEqual(kinds(frameFindings({ [FRAMES_KEY]: '12:34' }, ok)), ['not-a-list']);
|
|
72
|
+
assert.deepEqual(kinds(frameFindings({ [FRAMES_KEY]: ['12 34'] }, ok)), ['bad-id', 'not-found']);
|
|
73
|
+
assert.deepEqual(kinds(frameFindings({ [FRAMES_KEY]: ['12:34', '12:34'] }, ok)), ['duplicate']);
|
|
74
|
+
assert.deepEqual(kinds(frameFindings({ [FRAMES_KEY]: ['12:34'] }, { state: 'missing' })), ['no-design-links']);
|
|
75
|
+
assert.deepEqual(kinds(frameFindings({ [FRAMES_KEY]: ['12:34'] }, { state: 'unreadable', why: 'x' })), ['design-links-unreadable']);
|
|
76
|
+
});
|
|
77
|
+
|
|
78
|
+
test('#354: frameFindings — text from the files reaches the terminal cleaned', () => {
|
|
79
|
+
const r = frameFindings({ [FRAMES_KEY]: ['\x1b[31m1:2'] }, ok);
|
|
80
|
+
for (const f of r.findings) assert.ok(!f.message.includes('\x1b'), f.message);
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
test('#354: readDesignLinks — missing, not JSON, no screens list, and ok', () => {
|
|
84
|
+
const T = tmp();
|
|
85
|
+
try {
|
|
86
|
+
assert.equal(readDesignLinks(T).state, 'missing');
|
|
87
|
+
put(path.join(T, '.sdlc', 'design-links.json'), '{ nope');
|
|
88
|
+
assert.equal(readDesignLinks(T).state, 'unreadable');
|
|
89
|
+
put(path.join(T, '.sdlc', 'design-links.json'), { tool: 'figma' });
|
|
90
|
+
assert.equal(readDesignLinks(T).state, 'unreadable');
|
|
91
|
+
put(path.join(T, '.sdlc', 'design-links.json'), LINKS);
|
|
92
|
+
const r = readDesignLinks(T);
|
|
93
|
+
assert.equal(r.state, 'ok');
|
|
94
|
+
assert.equal(r.screens.length, 2);
|
|
95
|
+
} finally { done(T); }
|
|
96
|
+
});
|
|
97
|
+
|
|
98
|
+
test('#354: the frontmatter reader round-trips the key the stories step writes', () => {
|
|
99
|
+
const T = product({ 'EP-shop-S01': `${FRAMES_KEY}: [12:34, aB3xQ]`, 'EP-shop-S02': `${FRAMES_KEY}: []`, 'EP-shop-S03': null });
|
|
100
|
+
try {
|
|
101
|
+
assert.deepEqual(readStoryFrames(T, 'EP-shop-S01').frames.map((f) => f.found), [true, true]);
|
|
102
|
+
const s2 = readStoryFrames(T, 'EP-shop-S02');
|
|
103
|
+
assert.deepEqual([s2.recorded, s2.ids, s2.findings], [true, [], []]);
|
|
104
|
+
assert.equal(readStoryFrames(T, 'EP-shop-S03').recorded, false);
|
|
105
|
+
assert.throws(() => readStoryFrames(T, 'EP-shop-S09'), /no story file/);
|
|
106
|
+
assert.throws(() => readStoryFrames(T, 'shop'), /not a story id/);
|
|
107
|
+
assert.throws(() => readStoryFrames(T, undefined), /needs a story id/);
|
|
108
|
+
} finally { done(T); }
|
|
109
|
+
});
|
|
110
|
+
|
|
111
|
+
test('#354: yad story frames — text, --json, and the exit code', () => {
|
|
112
|
+
const T = product({ 'EP-shop-S01': `${FRAMES_KEY}: [12:34, 99:99]` });
|
|
113
|
+
try {
|
|
114
|
+
const text = yad(T, 'story', 'frames', 'EP-shop-S01');
|
|
115
|
+
assert.equal(text.status, 0, text.stderr);
|
|
116
|
+
assert.match(text.stdout, /12:34 {2}Cart {2}\[web\]/);
|
|
117
|
+
assert.match(text.stdout, /99:99 — not found/);
|
|
118
|
+
const j = yad(T, 'story', 'frames', 'EP-shop-S01', '--json');
|
|
119
|
+
assert.equal(j.status, 0, j.stderr);
|
|
120
|
+
const out = JSON.parse(j.stdout);
|
|
121
|
+
assert.equal(out.command, 'story frames');
|
|
122
|
+
assert.equal(out.ok, true);
|
|
123
|
+
assert.equal(out.tool, 'pencil');
|
|
124
|
+
assert.deepEqual(out.frames.map((f) => [f.id, f.found]), [['12:34', true], ['99:99', false]]);
|
|
125
|
+
assert.deepEqual(out.findings.map((f) => f.kind), ['not-found']);
|
|
126
|
+
assert.equal(out.warnings.length, 1, 'a missing frame is a warning, and the exit code stays 0');
|
|
127
|
+
|
|
128
|
+
const gone = yad(T, 'story', 'frames', 'EP-shop-S09', '--json');
|
|
129
|
+
assert.equal(gone.status, 1);
|
|
130
|
+
const g = JSON.parse(gone.stdout);
|
|
131
|
+
assert.equal(g.ok, false);
|
|
132
|
+
assert.match(g.hint, /story id/);
|
|
133
|
+
assert.equal(yad(T, 'story', 'paint').status, 1, 'an unknown action is refused');
|
|
134
|
+
} finally { done(T); }
|
|
135
|
+
});
|
|
136
|
+
|
|
137
|
+
test('#354: doctor — no row without frames, an ok row with a count, one warn row naming the problems', () => {
|
|
138
|
+
const run = (T) => { const checks = []; storyFrameChecks(checks, T); return checks; };
|
|
139
|
+
let T = product({ 'EP-shop-S01': null });
|
|
140
|
+
try { assert.deepEqual(run(T), []); } finally { done(T); }
|
|
141
|
+
|
|
142
|
+
T = product({ 'EP-shop-S01': `${FRAMES_KEY}: [12:34]`, 'EP-shop-S02': `${FRAMES_KEY}: []` }, LINKS);
|
|
143
|
+
try {
|
|
144
|
+
const [row, ...rest] = run(T);
|
|
145
|
+
assert.equal(rest.length, 0);
|
|
146
|
+
assert.deepEqual([row.id, row.status], ['stories:design-frames', 'ok']);
|
|
147
|
+
assert.match(row.message, /^1 story\(ies\) record design frames.*; 1 story\(ies\) say they have no screens/);
|
|
148
|
+
} finally { done(T); }
|
|
149
|
+
|
|
150
|
+
T = product({ 'EP-shop-S01': `${FRAMES_KEY}: [12:34] # cart`, 'EP-shop-S02': `${FRAMES_KEY}: [77:1]` });
|
|
151
|
+
try {
|
|
152
|
+
const rows = run(T);
|
|
153
|
+
assert.equal(rows.length, 1);
|
|
154
|
+
assert.deepEqual([rows[0].id, rows[0].status], ['stories:design-frames', 'warn']);
|
|
155
|
+
assert.match(rows[0].message, /^2 problem/);
|
|
156
|
+
assert.match(rows[0].message, /EP-shop-S01: .*#/);
|
|
157
|
+
assert.match(rows[0].message, /EP-shop-S02: .*77:1/);
|
|
158
|
+
assert.deepEqual(allStoryFrames(T, ['EP-shop']).map((s) => s.findings[0].kind), ['commented', 'not-found']);
|
|
159
|
+
} finally { done(T); }
|
|
160
|
+
});
|
|
161
|
+
|
|
162
|
+
test('#354 review 1: Windows line endings, a byte-order mark and a trailing space still read the list', () => {
|
|
163
|
+
const T = product({});
|
|
164
|
+
try {
|
|
165
|
+
const dir = path.join(T, 'epics', 'EP-shop', 'stories');
|
|
166
|
+
put(path.join(dir, 'EP-shop-S01.md'), story('EP-shop-S01', `${FRAMES_KEY}: [12:34]`).replace(/\n/g, '\r\n'));
|
|
167
|
+
put(path.join(dir, 'EP-shop-S02.md'), BOM + story('EP-shop-S02', `${FRAMES_KEY}: [12:34]`));
|
|
168
|
+
put(path.join(dir, 'EP-shop-S03.md'), story('EP-shop-S03', `${FRAMES_KEY}: [12:34] `));
|
|
169
|
+
for (const id of ['EP-shop-S01', 'EP-shop-S02', 'EP-shop-S03']) {
|
|
170
|
+
const r = readStoryFrames(T, id);
|
|
171
|
+
assert.deepEqual([r.recorded, r.frames.map((f) => f.found), r.findings], [true, [true], []], id);
|
|
172
|
+
}
|
|
173
|
+
assert.deepEqual(allStoryFrames(T, ['EP-shop']).map((s) => s.findings.length), [0, 0, 0], 'doctor reads them the same way');
|
|
174
|
+
} finally { done(T); }
|
|
175
|
+
});
|
|
176
|
+
|
|
177
|
+
test('#354 review 1: a misspelled key and quoted IDs are said, not read as "no frames" or "not found"', () => {
|
|
178
|
+
for (const k of ['Design-Frames', 'designFrames', 'design_frames']) {
|
|
179
|
+
const r = frameFindings({ [k]: ['12:34'] }, ok);
|
|
180
|
+
assert.deepEqual([r.recorded, kinds(r)], [false, ['key-spelling']], k);
|
|
181
|
+
}
|
|
182
|
+
const q = frameFindings({ [FRAMES_KEY]: ['"12:34"', "'aB3xQ'"] }, ok);
|
|
183
|
+
assert.deepEqual(kinds(q), ['quoted']);
|
|
184
|
+
assert.deepEqual(q.frames.map((f) => [f.id, f.found]), [['12:34', true], ['aB3xQ', true]]);
|
|
185
|
+
assert.doesNotMatch(frameFindings({ [FRAMES_KEY]: 'x y' }, ok).findings[0].message, /\[\[/, 'never advice to double the brackets');
|
|
186
|
+
});
|
|
187
|
+
|
|
188
|
+
test('#354 review 1: doctor never points at a command that would refuse the story', () => {
|
|
189
|
+
const T = product({ 'EP-shop-S01': `${FRAMES_KEY}: []` });
|
|
190
|
+
try {
|
|
191
|
+
const dir = path.join(T, 'epics', 'EP-shop', 'stories');
|
|
192
|
+
put(path.join(dir, 'EP-Shop-S04.md'), story('EP-Shop-S04', `${FRAMES_KEY}: [12:34]`));
|
|
193
|
+
put(path.join(dir, 'EP-other-S01.md'), story('EP-other-S01', `${FRAMES_KEY}: [12:34]`));
|
|
194
|
+
fs.mkdirSync(path.join(dir, 'EP-shop-S07.md'));
|
|
195
|
+
const rows = allStoryFrames(T, ['EP-shop']);
|
|
196
|
+
assert.deepEqual(rows.map((s) => [s.story, kinds(s)]), [['EP-Shop-S04', ['not-a-story-file']], ['EP-other-S01', ['not-a-story-file']], ['EP-shop-S01', []]]);
|
|
197
|
+
for (const s of rows.filter((x) => x.findings.length)) assert.match(s.findings[0].message, /rename the file/);
|
|
198
|
+
assert.throws(() => readStoryFrames(T, 'EP-shop-S07'), /no story file/, 'a folder named like a story is refused, not a crash');
|
|
199
|
+
const checks = [];
|
|
200
|
+
storyFrameChecks(checks, T);
|
|
201
|
+
assert.equal(checks[0].status, 'warn');
|
|
202
|
+
} finally { done(T); }
|
|
203
|
+
});
|
|
204
|
+
|
|
205
|
+
test('#354 review 1: the ok row tells stories with frames from stories with no screens', () => {
|
|
206
|
+
const T = product({ 'EP-shop-S01': `${FRAMES_KEY}: []` }, null);
|
|
207
|
+
try {
|
|
208
|
+
const checks = [];
|
|
209
|
+
storyFrameChecks(checks, T);
|
|
210
|
+
assert.equal(checks[0].status, 'ok');
|
|
211
|
+
assert.match(checks[0].message, /^1 story\(ies\) say they have no screens/);
|
|
212
|
+
assert.equal(yad(T, 'story', 'frames', 'EP-shop-S01', 'EP-shop-S02').status, 1, 'one story at a time');
|
|
213
|
+
} finally { done(T); }
|
|
214
|
+
});
|
|
215
|
+
|
|
216
|
+
test('#354 review 2: doctor reads what the command reads — a symlinked story, a misspelled key', () => {
|
|
217
|
+
const T = product({ 'EP-shop-S02': 'designFrames: [12:34]' });
|
|
218
|
+
try {
|
|
219
|
+
const dir = path.join(T, 'epics', 'EP-shop', 'stories');
|
|
220
|
+
put(path.join(T, 'elsewhere.md'), story('EP-shop-S01', `${FRAMES_KEY}: [9:9]`));
|
|
221
|
+
fs.symlinkSync(path.join(T, 'elsewhere.md'), path.join(dir, 'EP-shop-S01.md'));
|
|
222
|
+
assert.deepEqual(kinds(readStoryFrames(T, 'EP-shop-S01')), ['not-found']);
|
|
223
|
+
assert.deepEqual(allStoryFrames(T, ['EP-shop']).map((s) => [s.story, kinds(s)]), [['EP-shop-S01', ['not-found']], ['EP-shop-S02', ['key-spelling']]]);
|
|
224
|
+
const checks = [];
|
|
225
|
+
storyFrameChecks(checks, T);
|
|
226
|
+
assert.equal(checks[0].status, 'warn');
|
|
227
|
+
assert.match(checks[0].hint, /rename a story file/);
|
|
228
|
+
} finally { done(T); }
|
|
229
|
+
});
|
|
230
|
+
|
|
231
|
+
test('#354 review 2: a misspelled key beside the right one is said; `""` is not an empty ID', () => {
|
|
232
|
+
const both = frameFindings({ [FRAMES_KEY]: ['12:34'], designFrames: ['56:78'] }, ok);
|
|
233
|
+
assert.deepEqual(kinds(both), ['key-spelling']);
|
|
234
|
+
assert.match(both.findings[0].message, /move its IDs/);
|
|
235
|
+
const empty = frameFindings({ [FRAMES_KEY]: ['""'] }, ok);
|
|
236
|
+
assert.deepEqual(kinds(empty), ['not-found'], '`""` is left as it is, never turned into an empty ID');
|
|
237
|
+
assert.deepEqual(empty.ids, ['""']);
|
|
238
|
+
assert.match(frameFindings({ [FRAMES_KEY]: ['"12:34"'] }, ok).findings[0].message, /should be written without quotes/);
|
|
239
|
+
});
|
|
240
|
+
|
|
241
|
+
const { designPreflight, readDesignConfig } = await import('./story-frames.mjs');
|
|
242
|
+
const { TOOLBOX, toolProblems, reachFor } = await import('./toolbox.mjs');
|
|
243
|
+
|
|
244
|
+
test('#358: designPreflight — Pencil is read through the app; Figma only through its desktop server', () => {
|
|
245
|
+
const frames = [{ id: '99:1', found: false }, { id: '12:34', found: true }];
|
|
246
|
+
const links = { state: 'ok', fileUrl: 'design/app.pen', screens: [] };
|
|
247
|
+
const pencil = designPreflight({ state: 'ok', data: { tool: 'pencil', provider: 'pencil-mcp' } }, links, frames);
|
|
248
|
+
assert.deepEqual([pencil.reachable, pencil.appBound, pencil.frame, pencil.file], ['check', true, '12:34', 'design/app.pen'], 'the first frame that resolves is the one probed');
|
|
249
|
+
assert.match(pencil.stop, /^Open the Pencil desktop app with `design\/app\.pen` loaded/);
|
|
250
|
+
assert.match(pencil.probe, /get_app_state/);
|
|
251
|
+
const desk = designPreflight({ state: 'ok', data: { tool: 'figma', provider: 'figma-desktop' } }, links, frames);
|
|
252
|
+
assert.deepEqual([desk.appBound, /desktop app/.test(desk.stop)], [true, true]);
|
|
253
|
+
const cloud = designPreflight({ state: 'ok', data: { tool: 'figma', provider: 'figma' } }, links, frames);
|
|
254
|
+
assert.deepEqual([cloud.appBound, /^Sign in to Figma/.test(cloud.stop)], [false, true]);
|
|
255
|
+
assert.match(cloud.probe, /`12:34`/);
|
|
256
|
+
const old = designPreflight({ state: 'ok', data: { tool: 'figma', provider: 'figma-mcp' } }, links, frames);
|
|
257
|
+
assert.deepEqual([old.appBound, /desktop app.*or sign in/.test(old.stop)], [null, true], 'the older figma-mcp: yad cannot tell, so both');
|
|
258
|
+
const viaSource = designPreflight({ state: 'ok', data: { tool: 'figma', source: 'figma-desktop' } }, links, frames);
|
|
259
|
+
assert.deepEqual([viaSource.provider, viaSource.appBound], ['figma-desktop', true], 'no provider: source names the server');
|
|
260
|
+
const noFile = designPreflight({ state: 'ok', data: { tool: 'pencil', project_url: 'https://team/project' } }, { state: 'ok', tool: 'pencil', fileUrl: null, screens: [] }, frames);
|
|
261
|
+
assert.match(noFile.stop, /the design file/, 'no file: said plainly — a project_url is a project, never compared as the file');
|
|
262
|
+
const switched = designPreflight({ state: 'ok', data: { tool: 'pencil' } }, { state: 'ok', tool: 'figma', fileUrl: 'https://figma/f', screens: [] }, frames);
|
|
263
|
+
assert.deepEqual([switched.reachable, /recorded for figma.*re-run the UI step/.test(switched.why)], ['not-checkable', true], 'frames of another tool are never probed through this one');
|
|
264
|
+
const odd = designPreflight({ state: 'ok', data: { tool: 'figma', source: 'figma-dev-mode-mcp-server' } }, links, frames);
|
|
265
|
+
assert.deepEqual([odd.reachable, odd.appBound], ['check', null], 'an MCP id yad does not know is still probed, with both messages');
|
|
266
|
+
assert.equal(designPreflight({ state: 'ok', data: { tool: 'figma', provider: 'Figma-Desktop' } }, links, frames).appBound, true, 'names are compared in lower case');
|
|
267
|
+
for (const provider of ['HTML-to-Design', 'html.to.design', ' html_to_design ']) {
|
|
268
|
+
assert.equal(designPreflight({ state: 'ok', data: { tool: 'figma', provider } }, links, frames).reachable, 'not-checkable', provider);
|
|
269
|
+
}
|
|
270
|
+
assert.equal(designPreflight({ state: 'ok', data: { tool: 'figma' } }, { ...links, tool: 'Figma' }, frames).reachable, 'check', 'the same tool in other letters is not a switch');
|
|
271
|
+
});
|
|
272
|
+
|
|
273
|
+
test('#358: designPreflight — nothing to probe is not-checkable, and no frame means no preflight', () => {
|
|
274
|
+
const frames = [{ id: '12:34', found: true }];
|
|
275
|
+
const links = { state: 'ok', fileUrl: 'f', screens: [] };
|
|
276
|
+
for (const design of [{ state: 'missing' }, { state: 'unreadable' }, { state: 'ok', data: { tool: 'none' } }, { state: 'ok', data: { tool: 'pencil', source: 'unavailable' } }, { state: 'ok', data: { tool: 'sketch' } }]) {
|
|
277
|
+
assert.equal(designPreflight(design, links, frames).reachable, 'not-checkable', JSON.stringify(design));
|
|
278
|
+
}
|
|
279
|
+
assert.equal(designPreflight({ state: 'ok', data: { tool: 'pencil' } }, links, []), null);
|
|
280
|
+
const writer = designPreflight({ state: 'ok', data: { tool: 'figma', provider: 'html-to-design' } }, links, frames);
|
|
281
|
+
assert.deepEqual([writer.reachable, /cannot read a frame/.test(writer.why)], ['not-checkable', true]);
|
|
282
|
+
const gone = designPreflight({ state: 'ok', data: { tool: 'pencil' } }, { state: 'missing' }, [{ id: '9:9', found: false }]);
|
|
283
|
+
assert.match(gone.why, /no design-links\.json/, 'a missing file is named, not blamed on the IDs');
|
|
284
|
+
assert.match(designPreflight({ state: 'ok', data: { tool: 'pencil' } }, { state: 'unreadable', why: 'it does not parse as JSON' }, [{ id: '9:9', found: false }]).why, /cannot be read/);
|
|
285
|
+
const unresolved = designPreflight({ state: 'ok', data: { tool: 'pencil' } }, links, [{ id: '9:9', found: false }]);
|
|
286
|
+
assert.deepEqual([unresolved.reachable, /fix the frame IDs/.test(unresolved.why)], ['not-checkable', true]);
|
|
287
|
+
for (const data of [{ tool: 123 }, { tool: 'figma', provider: {} }, { tool: 'pencil', source: ['unavailable'] }]) {
|
|
288
|
+
const r = designPreflight({ state: 'ok', data }, links, frames);
|
|
289
|
+
assert.ok(r && ['check', 'not-checkable'].includes(r.reachable), JSON.stringify(data));
|
|
290
|
+
}
|
|
291
|
+
const dirty = designPreflight({ state: 'ok', data: { tool: 'pencil' } }, { state: 'ok', fileUrl: 'a\x1b[31mb', screens: [] }, frames);
|
|
292
|
+
assert.ok(!dirty.stop.includes('\x1b') && !dirty.probe.includes('\x1b'));
|
|
293
|
+
});
|
|
294
|
+
|
|
295
|
+
test('#358: readDesignConfig, the reach data, and preflight through the command', () => {
|
|
296
|
+
for (const t of TOOLBOX.filter((x) => x.reach)) assert.deepEqual(toolProblems(t), [], t.id);
|
|
297
|
+
const figma = TOOLBOX.find((x) => x.id === 'figma');
|
|
298
|
+
assert.deepEqual(toolProblems({ ...figma, reach: { app: 'F', probe: 'p', open: 'o', readers: true, appBound: ['x'] } }), ['reach.signIn and reach.either say what to do when the provider needs no app, or yad cannot tell']);
|
|
299
|
+
assert.ok(toolProblems({ ...figma, reach: { readers: true, appBound: true } }).includes('reach has app, probe and open'));
|
|
300
|
+
assert.ok(toolProblems({ ...figma, reach: null }).length > 0);
|
|
301
|
+
assert.ok(toolProblems({ ...figma, reach: { ...figma.reach, appBound: false } }).includes('reach.appBound is true, or the providers read through the app'));
|
|
302
|
+
assert.equal(reachFor('repomix'), null);
|
|
303
|
+
const T = product({ 'EP-shop-S01': `${FRAMES_KEY}: [12:34]`, 'EP-shop-S02': `${FRAMES_KEY}: []` });
|
|
304
|
+
try {
|
|
305
|
+
assert.equal(readDesignConfig(T).state, 'missing');
|
|
306
|
+
put(path.join(T, '.sdlc', 'design.json'), '{ nope');
|
|
307
|
+
assert.equal(readDesignConfig(T).state, 'unreadable');
|
|
308
|
+
put(path.join(T, '.sdlc', 'design.json'), { tool: 'pencil', provider: 'pencil-mcp', source: 'pencil-mcp', auth: 'user' });
|
|
309
|
+
const j = JSON.parse(yad(T, 'story', 'frames', 'EP-shop-S01', '--json').stdout);
|
|
310
|
+
assert.deepEqual([j.preflight.reachable, j.preflight.tool, j.preflight.appBound], ['check', 'pencil', true]);
|
|
311
|
+
assert.match(yad(T, 'story', 'frames', 'EP-shop-S01').stdout, /before UI work: .* if that fails, stop: Open the Pencil desktop app/);
|
|
312
|
+
assert.equal(JSON.parse(yad(T, 'story', 'frames', 'EP-shop-S02', '--json').stdout).preflight, null, 'no screens, no probe');
|
|
313
|
+
} finally { done(T); }
|
|
314
|
+
});
|
|
315
|
+
|
|
316
|
+
test('#354: the stories, spec and implement skills all name `yad story frames`', () => {
|
|
317
|
+
for (const skill of ['yad-stories', 'yad-spec', 'yad-implement']) {
|
|
318
|
+
const body = fs.readFileSync(path.join(REPO, 'skills', skill, 'SKILL.md'), 'utf8');
|
|
319
|
+
assert.ok(body.includes('yad story frames'), `${skill} does not read the story's frames`);
|
|
320
|
+
}
|
|
321
|
+
const schema = fs.readFileSync(path.join(REPO, 'skills', 'yad-stories', 'references', 'story-schema.md'), 'utf8');
|
|
322
|
+
assert.ok(schema.includes(FRAMES_KEY), 'the story schema names the key');
|
|
323
|
+
const template = fs.readFileSync(path.join(REPO, 'skills', 'yad-stories', 'SKILL.md'), 'utf8');
|
|
324
|
+
assert.match(template, new RegExp(`^${FRAMES_KEY}: \\[\\]$`, 'm'), 'the template ships the key bare, with no trailing comment');
|
|
325
|
+
});
|
|
326
|
+
|
|
327
|
+
test('#358: spec and implement probe the design tool first, stop on a failure, and record an override', () => {
|
|
328
|
+
for (const [skill, where] of [['yad-spec', '## Clarifications'], ['yad-implement', 'Decisions:']]) {
|
|
329
|
+
const body = fs.readFileSync(path.join(REPO, 'skills', skill, 'SKILL.md'), 'utf8');
|
|
330
|
+
for (const word of ['preflight.probe', 'not-checkable', where]) assert.ok(body.includes(word), `${skill} lacks ${word}`);
|
|
331
|
+
assert.match(body, /STOP\W+print `preflight\.stop` word for word/i, `${skill} does not stop with the message`);
|
|
332
|
+
}
|
|
333
|
+
const ctx = fs.readFileSync(path.join(REPO, 'skills', 'yad-connect-design', 'references', 'design-context.md'), 'utf8');
|
|
334
|
+
assert.ok(ctx.includes('Reachable before Build (#358)'));
|
|
335
|
+
const connect = fs.readFileSync(path.join(REPO, 'skills', 'yad-connect-design', 'SKILL.md'), 'utf8');
|
|
336
|
+
for (const p of ['figma-desktop', '`figma`', 'html-to-design']) assert.ok(connect.includes(p), `yad-connect-design does not name the ${p} provider`);
|
|
337
|
+
const example = connect.slice(connect.indexOf('### Step 2'), connect.indexOf('### Step 3'));
|
|
338
|
+
assert.ok(example.includes('"provider": "figma-desktop"') && !example.includes('figma-mcp'), 'the registry example records a provider the preflight can read');
|
|
339
|
+
});
|
package/cli/toolbox.mjs
CHANGED
|
@@ -254,6 +254,18 @@ export const TOOLBOX = Object.freeze([
|
|
|
254
254
|
versions: null,
|
|
255
255
|
fallback: 'markdown-only: yad-ui writes ui-design.md and DESIGN.md only',
|
|
256
256
|
records: null, note: 'Sign-in is your own (OAuth); yadflow stores no token. The desktop server is named figma-desktop.',
|
|
257
|
+
// #358: how a UI task checks the tool can be reached before it starts. `provider` in design.json says
|
|
258
|
+
// which server: `figma-desktop` reads through the running app; `figma` (the hosted server) needs the
|
|
259
|
+
// person signed in, not an app; the older `figma-mcp` could be either, so its message names both.
|
|
260
|
+
// `html-to-design` only writes (import-html) and cannot read a frame. Any other provider name — the
|
|
261
|
+
// MCP id is free text — is probed, with the message that names both servers.
|
|
262
|
+
reach: {
|
|
263
|
+
app: 'Figma', writers: ['html-to-design'], appBound: ['figma-desktop'], signInOnly: ['figma'],
|
|
264
|
+
probe: 'read frame <frame> through the Figma MCP (get_metadata, with that node ID)',
|
|
265
|
+
open: 'Open the Figma desktop app with <file> loaded and its Dev Mode MCP server on, then continue',
|
|
266
|
+
signIn: 'Sign in to Figma in your agent (its Figma MCP server), check that you can open <file>, then continue',
|
|
267
|
+
either: 'Open the Figma desktop app with <file> loaded (if you use its desktop MCP server), or sign in to Figma in your agent (the hosted server), then continue',
|
|
268
|
+
},
|
|
257
269
|
usedBy: ['yad-connect-design', 'yad-ui'],
|
|
258
270
|
},
|
|
259
271
|
{
|
|
@@ -271,6 +283,12 @@ export const TOOLBOX = Object.freeze([
|
|
|
271
283
|
versions: null,
|
|
272
284
|
fallback: 'markdown-only: yad-ui writes ui-design.md and DESIGN.md only',
|
|
273
285
|
records: null, note: 'Set up inside the desktop app: open a .pen file, then Settings → MCP → enable your agent.',
|
|
286
|
+
// #358: Pencil is read through the running desktop app, so the app must be open with the file loaded.
|
|
287
|
+
reach: {
|
|
288
|
+
app: 'Pencil', appBound: true,
|
|
289
|
+
probe: 'read the app state through the Pencil MCP (get_app_state, or get_editor_state): the active canvas editor must be <file> — compare by file name, as the app shows the full path. Frame <frame> may sit inside a container frame, so if it is not in the top-level list, read it by its ID (batch_get, or the node-read tool your Pencil MCP has) before calling it missing',
|
|
290
|
+
open: 'Open the Pencil desktop app with <file> loaded, then continue',
|
|
291
|
+
},
|
|
274
292
|
usedBy: ['yad-connect-design', 'yad-ui'],
|
|
275
293
|
},
|
|
276
294
|
{
|
|
@@ -405,6 +423,19 @@ export function toolProblems(t) {
|
|
|
405
423
|
need(t?.manual === null || (typeof t?.manual === 'string' && /^https:\/\//.test(t.manual)), 'manual is null or an https URL');
|
|
406
424
|
need(isStringList(t?.usedBy), 'usedBy lists the skills or commands that use it');
|
|
407
425
|
need(t?.tier !== 'connector' || !isStringList(t?.usedBy) || connectorFile(t) !== null, 'a connector names the yad-connect-* skill that connects it');
|
|
426
|
+
// #358 reach: `appBound` is `true` (every provider) or a list of providers; `writers` (optional) lists the
|
|
427
|
+
// providers that cannot read a frame. Provider names are compared in lower case. A tool whose
|
|
428
|
+
// providers need no app writes `appBound: []`; then `signIn` (a provider in `signInOnly`) and `either`
|
|
429
|
+
// (a provider in neither list, so yad cannot tell) say what to do instead.
|
|
430
|
+
const r = t?.reach;
|
|
431
|
+
if (r !== undefined) {
|
|
432
|
+
const text = (v) => typeof v === 'string' && v.length > 0;
|
|
433
|
+
need(r && typeof r === 'object' && text(r.app) && text(r.probe) && text(r.open), 'reach has app, probe and open');
|
|
434
|
+
need(r?.writers === undefined || isStringList(r?.writers), 'reach.writers is absent or the providers that cannot read a frame');
|
|
435
|
+
need(r?.appBound === true || isStringList(r?.appBound), 'reach.appBound is true, or the providers read through the app');
|
|
436
|
+
need(r?.signInOnly === undefined || isStringList(r?.signInOnly), 'reach.signInOnly is absent or a list of providers');
|
|
437
|
+
need(r?.appBound === true || (text(r?.signIn) && text(r?.either)), 'reach.signIn and reach.either say what to do when the provider needs no app, or yad cannot tell');
|
|
438
|
+
}
|
|
408
439
|
return out;
|
|
409
440
|
}
|
|
410
441
|
|
|
@@ -771,6 +802,9 @@ export function connectorFile(tool) {
|
|
|
771
802
|
}
|
|
772
803
|
|
|
773
804
|
// The skills (folders under skills/, not `yad <command>`s) that use a tool.
|
|
805
|
+
// #358 — how a UI task checks a design tool can be reached, or null when yad has no check for it.
|
|
806
|
+
export const reachFor = (id) => TOOLBOX.find((t) => t.id === id)?.reach ?? null;
|
|
807
|
+
|
|
774
808
|
export const skillsUsing = (tool) => tool.usedBy.filter((u) => !u.startsWith('yad '));
|
|
775
809
|
|
|
776
810
|
// The line a skill writes when the tool was not used. `recordsElse` is the one case where the skill chose
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "yadflow",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.9.0",
|
|
4
4
|
"description": "Shared project memory and workflows for teams building with AI: a versioned record of plans, decisions, contracts and reviews across repos, human-approved review gates, and a zero-dependency `yad` CLI plus 39 skills for your AI assistant.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"author": "AbdelRahman Nasr",
|
|
@@ -46,12 +46,12 @@
|
|
|
46
46
|
"scripts": {
|
|
47
47
|
"yad": "node bin/yad.mjs",
|
|
48
48
|
"lint": "eslint cli bin",
|
|
49
|
-
"test": "node --test cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs cli/test-golden.mjs cli/test-migrate.mjs cli/test-hooks.mjs cli/test-detect.mjs cli/test-members.mjs cli/test-standup.mjs cli/test-lifecycle.mjs cli/test-run-checks.mjs cli/test-build.mjs cli/test-worktree.mjs cli/test-guide.mjs cli/test-agents-file.mjs cli/test-setup-agent.mjs cli/test-signing.mjs cli/test-ci-check.mjs cli/test-node.mjs cli/test-fuzz.js",
|
|
49
|
+
"test": "node --test cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs cli/test-golden.mjs cli/test-migrate.mjs cli/test-hooks.mjs cli/test-detect.mjs cli/test-members.mjs cli/test-standup.mjs cli/test-lifecycle.mjs cli/test-run-checks.mjs cli/test-build.mjs cli/test-worktree.mjs cli/test-guide.mjs cli/test-agents-file.mjs cli/test-setup-agent.mjs cli/test-signing.mjs cli/test-ci-check.mjs cli/test-node.mjs cli/test-machine.mjs cli/test-story-frames.mjs cli/test-preview.mjs cli/test-fuzz.js",
|
|
50
50
|
"test:e2e": "bash test/e2e/run.sh",
|
|
51
51
|
"test:agents": "bash test/agent-acceptance/run.sh",
|
|
52
52
|
"test:agents:selftest": "bash test/agent-acceptance/run.sh selftest",
|
|
53
53
|
"release-check": "bash scripts/release-check.sh",
|
|
54
|
-
"coverage": "node --test --test-reporter=tap --experimental-test-coverage --test-coverage-exclude='cli/test*.mjs' --test-coverage-exclude='cli/test*.js' --test-coverage-lines=70 --test-coverage-branches=70 cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs cli/test-golden.mjs cli/test-migrate.mjs cli/test-hooks.mjs cli/test-detect.mjs cli/test-members.mjs cli/test-standup.mjs cli/test-lifecycle.mjs cli/test-run-checks.mjs cli/test-build.mjs cli/test-worktree.mjs cli/test-guide.mjs cli/test-agents-file.mjs cli/test-setup-agent.mjs cli/test-signing.mjs cli/test-ci-check.mjs cli/test-node.mjs cli/test-fuzz.js",
|
|
54
|
+
"coverage": "node --test --test-reporter=tap --experimental-test-coverage --test-coverage-exclude='cli/test*.mjs' --test-coverage-exclude='cli/test*.js' --test-coverage-lines=70 --test-coverage-branches=70 cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs cli/test-golden.mjs cli/test-migrate.mjs cli/test-hooks.mjs cli/test-detect.mjs cli/test-members.mjs cli/test-standup.mjs cli/test-lifecycle.mjs cli/test-run-checks.mjs cli/test-build.mjs cli/test-worktree.mjs cli/test-guide.mjs cli/test-agents-file.mjs cli/test-setup-agent.mjs cli/test-signing.mjs cli/test-ci-check.mjs cli/test-node.mjs cli/test-machine.mjs cli/test-story-frames.mjs cli/test-preview.mjs cli/test-fuzz.js",
|
|
55
55
|
"diagrams": "npx -y @mermaid-js/mermaid-cli@11.15.0 -i docs/diagrams/sdlc-overview.mmd -o docs/diagrams/sdlc-overview.svg -b transparent && npx -y @mermaid-js/mermaid-cli@11.15.0 -i docs/diagrams/review-loop.mmd -o docs/diagrams/review-loop.svg -b transparent && npx -y @mermaid-js/mermaid-cli@11.15.0 -i docs/diagrams/work-and-memory.mmd -o docs/diagrams/work-and-memory.svg -b transparent && npx -y @mermaid-js/mermaid-cli@11.15.0 -i docs/diagrams/feature-evolution.mmd -o docs/diagrams/feature-evolution.svg -b transparent",
|
|
56
56
|
"prepublishOnly": "npm test"
|
|
57
57
|
},
|
|
@@ -67,8 +67,11 @@ Determine which tool is being connected from `tool` (default `figma`); reject a
|
|
|
67
67
|
- **pencil** → the `pencil` MCP (`batch_design` writes `.pen` web/mobile screens — generate-capable).
|
|
68
68
|
- another adapter → its named MCP.
|
|
69
69
|
|
|
70
|
-
Record `provider` (the concrete MCP
|
|
71
|
-
|
|
70
|
+
Record `provider` (the concrete MCP) and whether it is available. For Figma, say which server it is,
|
|
71
|
+
because a UI task checks it before it starts (#358): `figma-desktop` (the Dev Mode MCP server inside the
|
|
72
|
+
running desktop app — the app must be open), `figma` (Figma's hosted server — a sign-in, no app), or
|
|
73
|
+
`html-to-design` (writes screens only, cannot read a frame). For Pencil, `pencil-mcp`. The older value
|
|
74
|
+
`figma-mcp` does not say which Figma server it is: on a refresh, record the exact one. **Auth is the local user's own** — the user's authenticated MCP session. The skill
|
|
72
75
|
**stores no tokens**; `project_url`/`files` are plain references, never credentials.
|
|
73
76
|
|
|
74
77
|
**Graceful degradation:** if no design-tool MCP is available, record `source: "unavailable"` and report
|
|
@@ -81,13 +84,13 @@ Upsert into `{project-root}/.sdlc/design.json` (create the file + parent `.sdlc/
|
|
|
81
84
|
```json
|
|
82
85
|
{
|
|
83
86
|
"tool": "figma",
|
|
84
|
-
"provider": "figma-
|
|
87
|
+
"provider": "figma-desktop",
|
|
85
88
|
"project_url": "https://www.figma.com/files/project/<id>/<name>",
|
|
86
89
|
"auth": "user",
|
|
87
90
|
"files": { "web": null, "mobile": null },
|
|
88
91
|
"connectedAt": "<YYYY-MM-DD>",
|
|
89
92
|
"lastSyncedAt": "<YYYY-MM-DD>",
|
|
90
|
-
"source": "figma-
|
|
93
|
+
"source": "figma-desktop"
|
|
91
94
|
}
|
|
92
95
|
```
|
|
93
96
|
|
|
@@ -56,6 +56,29 @@ it authors `ui-design.md` / `DESIGN.md` exactly as before and records `design: n
|
|
|
56
56
|
with a one-line note (mirroring the `impeccable: not-installed` degrade). No error — the design tool is
|
|
57
57
|
purely additive.
|
|
58
58
|
|
|
59
|
+
## Reachable before Build (#358)
|
|
60
|
+
|
|
61
|
+
A design tool read through its running desktop app — Pencil, or Figma's `figma-desktop` server — cannot be
|
|
62
|
+
read while the app is closed or the design file is not open. So before a UI task, `yad-spec` and
|
|
63
|
+
`yad-implement` check it first, and stop early when it fails. yad itself cannot call an MCP server (it
|
|
64
|
+
belongs to the agent's session), so `yad story frames <story> --json` returns a `preflight` block that says
|
|
65
|
+
how to check and what to tell the person; the text for each tool is the toolbox entry's `reach` field.
|
|
66
|
+
|
|
67
|
+
| `tool` | What the agent checks | When it fails |
|
|
68
|
+
|--------|-----------------------|---------------|
|
|
69
|
+
| `pencil` | `get_app_state` (or `get_editor_state`): the active canvas editor is the design file, compared by file name (the app shows the full path). A frame inside a container is not in the top-level list, so it is read by its ID before it counts as missing | open the Pencil desktop app with the file loaded, then continue |
|
|
70
|
+
| `figma`, provider `figma-desktop` | `get_metadata` on one recorded frame | open the Figma desktop app with the file loaded and its Dev Mode MCP server on |
|
|
71
|
+
| `figma`, provider `figma` (hosted) | `get_metadata` on one recorded frame | sign in to Figma in your agent; no app is needed |
|
|
72
|
+
| `figma`, provider `figma-mcp` (older value), any other name, or none | `get_metadata` on one recorded frame | either of the two above — yad cannot tell which server it is |
|
|
73
|
+
| `figma`, provider `html-to-design` | nothing: it writes screens and cannot read a frame | not checked; build from the frame links |
|
|
74
|
+
|
|
75
|
+
Also not checked (build from the frame links): no `design.json`, tool `none`, source `unavailable`; no
|
|
76
|
+
`design-links.json`, one that cannot be read, or one recorded for another tool (re-run the UI step); and a
|
|
77
|
+
story whose recorded frame IDs are all missing from `design-links.json` — the bad IDs are the problem then.
|
|
78
|
+
|
|
79
|
+
A failed check stops the step. The person may choose to go on from the frame links only; that choice is
|
|
80
|
+
recorded (in `spec.md`'s Clarifications, or the commit's Decisions paragraph).
|
|
81
|
+
|
|
59
82
|
## Staleness / refresh
|
|
60
83
|
|
|
61
84
|
A re-generated or designer-edited file is like a moved code repo: `yad-ui` **flags** a divergence and
|
|
@@ -15,13 +15,13 @@ root, not under any `epics/EP-<slug>/.sdlc/`.
|
|
|
15
15
|
```json
|
|
16
16
|
{
|
|
17
17
|
"tool": "figma", // figma | pencil | <adapter id> | none (markdown-only)
|
|
18
|
-
"provider": "figma-
|
|
18
|
+
"provider": "figma-desktop", // the concrete MCP: figma-desktop | figma | html-to-design | pencil-mcp | null (figma-mcp: older, either Figma server)
|
|
19
19
|
"project_url": "https://www.figma.com/files/project/123/feature", // team/project/file reference; null if none yet
|
|
20
20
|
"auth": "user", // ALWAYS the user's own MCP session — never a token
|
|
21
21
|
"files": { "web": null, "mobile": null }, // optional default file refs per platform
|
|
22
22
|
"connectedAt": "2026-06-13", // first connect (YYYY-MM-DD)
|
|
23
23
|
"lastSyncedAt": "2026-06-13", // last connect/refresh
|
|
24
|
-
"source": "figma-
|
|
24
|
+
"source": "figma-desktop" // the MCP detected at connect | unavailable (degraded)
|
|
25
25
|
}
|
|
26
26
|
```
|
|
27
27
|
|
|
@@ -36,7 +36,7 @@ root, not under any `epics/EP-<slug>/.sdlc/`.
|
|
|
36
36
|
session.
|
|
37
37
|
- **`connect` overwrites in place** — a project carries exactly one design connection at a time;
|
|
38
38
|
switching tools is just another `connect`. There is no array (unlike `repos.json`).
|
|
39
|
-
- **`source`** is the authority for availability: an MCP id (`figma-
|
|
39
|
+
- **`source`** is the authority for availability: an MCP id (`figma-desktop` / `figma` / `pencil-mcp` / …) means
|
|
40
40
|
`yad-ui` can generate/link; `unavailable` means `yad-ui` degrades to markdown-only. `refresh`
|
|
41
41
|
re-detects and may flip it.
|
|
42
42
|
- **`tool: "none"`** is a valid, deliberate state: a project that has chosen markdown-only. `yad-ui`
|
|
@@ -180,6 +180,14 @@ new repo later is the same `connect` action. Write no `domain_owner`/`domain_own
|
|
|
180
180
|
release wrote with them is left as it is (nothing reads them, and `yad doctor` warns
|
|
181
181
|
`people:domain-owners-unused`).
|
|
182
182
|
|
|
183
|
+
**Preview address (optional, #359).** A repo whose PRs/MRs get a live preview deployment (Vercel,
|
|
184
|
+
Netlify, a GitLab review app) can record its address pattern as `preview_url`, for example
|
|
185
|
+
`"https://pr-{pr}.myapp.dev"` (placeholders `{pr}`, `{branch}`, `{repo}`; https only, or
|
|
186
|
+
`http://localhost`). Ask the person for it; never guess one. Write it with
|
|
187
|
+
`yad repo preview <repo> <pattern>` (it checks the pattern; `--clear` removes it), not by hand. With no
|
|
188
|
+
pattern, review steps ask the platform for the PR's deployment, and else say the design check ran
|
|
189
|
+
locally only.
|
|
190
|
+
|
|
183
191
|
### Step 5 — Report
|
|
184
192
|
Report the connected repo, its `platform`, the pack + code-map paths, the secret-scan result, and that
|
|
185
193
|
the Shape phases will now load this repo's code-map. Nothing auto-advances; this is setup.
|
|
@@ -59,6 +59,19 @@ asking questions, answering theirs, until both are satisfied — then records th
|
|
|
59
59
|
growth in the local-only learning log. Still soft: it rides the same `engagement: verified` signal and
|
|
60
60
|
never gates. When a pair session backs the approve, you may set `companion.pair: true` on the ship record.
|
|
61
61
|
|
|
62
|
+
**Live design check (a UI change only, #359).** A live design check opens the running page and looks
|
|
63
|
+
at it at several screen widths (phone, tablet, desktop). `yad review context --repo <r> --pr <n> --json`
|
|
64
|
+
carries a `preview` field that says where to run it:
|
|
65
|
+
- `preview.url` set (`source: pattern` from the repo's `yad repo preview` pattern, or `source: platform`
|
|
66
|
+
from the deployment GitHub/GitLab records for the PR): run the check against `preview.url`, and name it
|
|
67
|
+
in the review ("checked live on <url> at 375, 768 and 1280 px"). The address is where the preview
|
|
68
|
+
should be, not proof that it is there: if the page does not load, or does not show this PR's change
|
|
69
|
+
yet, treat it as `local-only` and say so.
|
|
70
|
+
- `source: local-only`: there is no preview deployment. Run the check on the developer's machine if you
|
|
71
|
+
can, and say plainly, in the review and in a PR comment, **"design check ran locally only: <preview.why>"**.
|
|
72
|
+
Never present a local check as a check of the deployed page. `preview.why` names the fix
|
|
73
|
+
(`yad repo preview <repo> <pattern>`); offer it, never run it unasked.
|
|
74
|
+
|
|
62
75
|
### Step 2 — `approve` (the engineer review — the human gate)
|
|
63
76
|
A human engineer reads the diff **against the spec** (`specs/<story>/`) and the acceptance criteria,
|
|
64
77
|
and records an approval. Determine the count with `bash checks/risk-route.sh <pr-body-file> origin/<base>`,
|
|
@@ -724,6 +724,12 @@ chain is unchanged — this is an *output enrichment*, mirrored by the `design:`
|
|
|
724
724
|
"source": "<mcp id>" }
|
|
725
725
|
```
|
|
726
726
|
|
|
727
|
+
**Who reads it (#354):** each story lists the `nodeId`s of the screens it builds in its own
|
|
728
|
+
`design-frames: [<id>, …]` frontmatter field (written by `yad-stories`). `yad story frames <story>` looks
|
|
729
|
+
each ID up here for its name, platform and link; `yad-spec` and `yad-implement` run it, and `yad doctor`
|
|
730
|
+
warns (`stories:design-frames`) on an ID this file does not hold. So keep a frame's `nodeId` the same when
|
|
731
|
+
the design changes.
|
|
732
|
+
|
|
727
733
|
## `test-links.json`
|
|
728
734
|
Present only when the `test-cases` step materialized automation in a connected testing tool
|
|
729
735
|
(`yad-connect-testing` → `.sdlc/testing.json`). Written by `yad-test-cases`, the machine-readable
|
|
@@ -69,8 +69,8 @@ Only the person does these:
|
|
|
69
69
|
|
|
70
70
|
`yad guide --json` gives each command its `class` and `ask`. In short:
|
|
71
71
|
|
|
72
|
-
- **read** — run it without asking. `yad guide`, `yad help`, `yad check` (not with `--fix`, `--push`, `--open-pr`, `--overwrite-local`, `--allow-branch`), `yad doctor`, `yad migrate` (not with `--apply`), `yad detect`, `yad signing check`, `yad ci check`, `yad toolbox list`, `yad toolbox check`, `yad skill list`, `yad skill recommend`, `yad report` (not with `--post`), `yad foundation status`, `yad status`, `yad next`, `yad dial` (not with `--to`), `yad mode`, `yad gate status`, `yad gate review`, `yad gate walkthrough`, `yad review context`, `yad review chat`, `yad review cards`, `yad review walkthrough`, `yad build merged` (not with `--ship`), `yad member list`, `yad worktree list`, `yad standup`, `yad claims`, `yad owners`, `yad history list`, `yad history show`, `yad history search`, `yad repo list`, `yad risk-map check`, `yad codeowners check`, `yad docs list`, `yad thread`, `yad reconcile check`.
|
|
73
|
-
- **local-write** — run it without asking. `yad check --fix`, `yad update` (not with `--push`, `--open-pr`, `--overwrite-local`, `--allow-branch`), `yad migrate --apply`, `yad usage`, `yad sync-status`, `yad epic new`, `yad foundation new`, `yad gate comments`, `yad gate repair` (not with `--push`, `--allow-branch`), `yad review reconcile`, `yad commit` (not with `--manual`, `--force`, `--ai`), `yad build start`, `yad build step`, `yad build trust` (not with `--uid`), `yad build ship` (not with `--merge-commit`, `--approver`), `yad build merged --ship`, `yad build done`, `yad build sync`, `yad run checks`, `yad checkpoint` (not with `--push`, `--retro-ship`, `--allow-branch`), `yad member remove` (not with `--reason`), `yad worktree add`, `yad worktree remove`, `yad assign` (not with `--force`), `yad unassign` (not with `--force`), `yad fold`, `yad tidy up` (not with `--push`, `--allow-branch`), `yad index`, `yad repo refresh` (not with `--push`, `--allow-branch`), `yad repo sync`, `yad repo clone`, `yad risk-map draft`, `yad docs build`, `yad docs sync`, `yad docs deploy`, `yad reconcile refresh`, `yad reconcile wire`.
|
|
72
|
+
- **read** — run it without asking. `yad guide`, `yad help`, `yad check` (not with `--fix`, `--push`, `--open-pr`, `--overwrite-local`, `--allow-branch`), `yad doctor`, `yad migrate` (not with `--apply`), `yad detect`, `yad signing check`, `yad ci check`, `yad toolbox list`, `yad toolbox check`, `yad skill list`, `yad skill recommend`, `yad report` (not with `--post`), `yad foundation status`, `yad status`, `yad next`, `yad dial` (not with `--to`), `yad mode`, `yad gate status`, `yad gate review`, `yad gate walkthrough`, `yad review context`, `yad review chat`, `yad review cards`, `yad review walkthrough`, `yad build merged` (not with `--ship`), `yad member list`, `yad worktree list`, `yad standup`, `yad claims`, `yad owners`, `yad history list`, `yad history show`, `yad history search`, `yad repo list`, `yad risk-map check`, `yad codeowners check`, `yad story frames`, `yad docs list`, `yad thread`, `yad reconcile check`.
|
|
73
|
+
- **local-write** — run it without asking. `yad check --fix`, `yad update` (not with `--push`, `--open-pr`, `--overwrite-local`, `--allow-branch`), `yad migrate --apply`, `yad usage`, `yad sync-status`, `yad epic new`, `yad foundation new`, `yad gate comments`, `yad gate repair` (not with `--push`, `--allow-branch`), `yad review reconcile`, `yad commit` (not with `--manual`, `--force`, `--ai`), `yad build start`, `yad build step`, `yad build trust` (not with `--uid`), `yad build ship` (not with `--merge-commit`, `--approver`), `yad build merged --ship`, `yad build done`, `yad build sync`, `yad run checks`, `yad checkpoint` (not with `--push`, `--retro-ship`, `--allow-branch`), `yad member remove` (not with `--reason`), `yad worktree add`, `yad worktree remove`, `yad assign` (not with `--force`), `yad unassign` (not with `--force`), `yad fold`, `yad tidy up` (not with `--push`, `--allow-branch`), `yad index`, `yad repo refresh` (not with `--push`, `--allow-branch`), `yad repo sync`, `yad repo clone`, `yad repo preview`, `yad risk-map draft`, `yad docs build`, `yad docs sync`, `yad docs deploy`, `yad reconcile refresh`, `yad reconcile wire`.
|
|
74
74
|
- **open-pr** — run it without asking. `yad join`, `yad check --open-pr`, `yad update --open-pr`, `yad gate open`, `yad gate sync`, `yad gate trailer`, `yad review trailer`, `yad review nudge`, `yad capture`, `yad member add`.
|
|
75
75
|
- **task-pr** — ask first, unless `yad dial open-pr` is `auto`. `yad open-pr`, `yad ship` (not with `--force`, `--ai`).
|
|
76
76
|
- **default-push** — ask the person every time, naming what it will do; run it only on a yes. `yad check --push`, `yad update --push`, `yad gate repair --push`, `yad checkpoint --push`, `yad tidy up --push`, `yad repo refresh --push`.
|
|
@@ -108,6 +108,20 @@ light spec has only `spec.md`: its `## Plan` section is the plan, and it has no
|
|
|
108
108
|
contract slice is **quoted** from the product repo's locked `contract.md` — implement to it, never
|
|
109
109
|
change it here.
|
|
110
110
|
|
|
111
|
+
**For a task with UI, read its design frames (#354).** Run `yad story frames <story> --json` (yad finds
|
|
112
|
+
the Product from the code repo). Its `frames` list names each design-tool frame the story builds, with
|
|
113
|
+
its `name`, `platform` and `url`; `spec.md`'s `## Design frames` section, when there is one, says the
|
|
114
|
+
same. Build to those frames: open them through the connected design tool's MCP when there is one, and
|
|
115
|
+
read them from their `url` otherwise. Never pick a frame by its look or its name alone. An ID it cannot
|
|
116
|
+
find is an open question for the batch below, not a guess.
|
|
117
|
+
|
|
118
|
+
**Before any code for a task with UI, check the design tool can be reached (#358).** When that answer's
|
|
119
|
+
`preflight.reachable` is `check`, make the MCP call `preflight.probe` describes. If it fails, or another
|
|
120
|
+
file is open, **STOP**: print `preflight.stop` word for word and wait. Go on without the design tool, from
|
|
121
|
+
the frame links only, only when the person says so, and record that in the commit's `Decisions:`
|
|
122
|
+
paragraph (Step 6) as `design tool not reachable: continued from the frame links, on <person>'s word`.
|
|
123
|
+
`not-checkable` means there is nothing to probe: go on from the links. `preflight: null` means no frames.
|
|
124
|
+
|
|
111
125
|
**Then ask the batch (#357)** that **Ask the human-only questions first** above describes, before
|
|
112
126
|
writing any code. Read `spec.md`'s `## Clarifications` first: `yad-spec` recorded its answers there.
|
|
113
127
|
Ask only what is still open for THIS task, from its block in `tasks.md`, `plan.md` and the contract
|