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
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
// #354 — each story records the design frames it builds, so the developer never has to ask which ones.
|
|
2
|
+
//
|
|
3
|
+
// The stories step writes the frame IDs into the story's frontmatter, as one inline list:
|
|
4
|
+
//
|
|
5
|
+
// design-frames: [12:34, 56:78]
|
|
6
|
+
//
|
|
7
|
+
// The IDs only. Each one is a `nodeId` the UI step already recorded in the epic's
|
|
8
|
+
// `.sdlc/design-links.json` (`screens[]`: name, platform, nodeId, url), and the name and URL are read
|
|
9
|
+
// from there, so they are written down once. `design-frames: []` says the story has no screens (a
|
|
10
|
+
// backend story); no key at all says nobody recorded them.
|
|
11
|
+
//
|
|
12
|
+
// ONE RULE, TWO READERS. `frameFindings` decides every problem; `yad story frames` and `yad doctor` both
|
|
13
|
+
// print what it returns, and every finding is a warning in both, so the two can never disagree about a
|
|
14
|
+
// story. The only refusals are about the command line itself: a word that is not a story id, or a story
|
|
15
|
+
// with no file.
|
|
16
|
+
//
|
|
17
|
+
// The frontmatter reader is `readFrontmatter`: one line per key, a `[ … ]` value split on commas, and
|
|
18
|
+
// everything else kept as the rest of the line. So a trailing `# note` turns the list into a plain
|
|
19
|
+
// string, and a YAML `- item` list on the next lines is not read at all (the key reads as blank). Both
|
|
20
|
+
// are reported here instead of being read as "no frames".
|
|
21
|
+
import fs from 'node:fs';
|
|
22
|
+
import path from 'node:path';
|
|
23
|
+
|
|
24
|
+
import { c, emitJSON, forTerminal, hand, info, log, ok, readJSONStrict, refuse, stripAnsi, warn } from './lib.mjs';
|
|
25
|
+
import { epicRoot, parseFrontmatter } from './epic-state.mjs';
|
|
26
|
+
import { STORY_RE, storyEpic } from './build.mjs';
|
|
27
|
+
import { PROJECT_FILES } from './manifest.mjs';
|
|
28
|
+
import { reachFor } from './toolbox.mjs';
|
|
29
|
+
|
|
30
|
+
export const FRAMES_KEY = 'design-frames';
|
|
31
|
+
export const DESIGN_LINKS_FILE = path.join('.sdlc', 'design-links.json');
|
|
32
|
+
|
|
33
|
+
// A character an ID cannot hold and still be read back the same: whitespace splits it in a person's
|
|
34
|
+
// eye, `#` is the comment trap, and a bracket ends or starts the list. A comma cannot be tested here —
|
|
35
|
+
// the reader has already split on it — so an ID holding one reads as two halves, and neither is found.
|
|
36
|
+
const BAD_ID = /[\s#[\]]/;
|
|
37
|
+
|
|
38
|
+
const quote = (s) => `\`${forTerminal(s)}\``;
|
|
39
|
+
|
|
40
|
+
// The epic's design-links.json as { state: 'missing' | 'unreadable' | 'ok', screens, tool, fileUrl, why }.
|
|
41
|
+
// A file that does not parse, or parses without a `screens` list, is `unreadable` — never "no screens",
|
|
42
|
+
// which would report every recorded frame as missing for the wrong reason.
|
|
43
|
+
export function readDesignLinks(epicDir) {
|
|
44
|
+
const file = path.join(epicDir, DESIGN_LINKS_FILE);
|
|
45
|
+
if (!fs.existsSync(file)) return { state: 'missing' };
|
|
46
|
+
let data;
|
|
47
|
+
try {
|
|
48
|
+
data = readJSONStrict(file, null);
|
|
49
|
+
} catch {
|
|
50
|
+
return { state: 'unreadable', why: 'it does not parse as JSON' };
|
|
51
|
+
}
|
|
52
|
+
if (!data || typeof data !== 'object' || Array.isArray(data) || !Array.isArray(data.screens)) {
|
|
53
|
+
return { state: 'unreadable', why: 'it has no `screens` list' };
|
|
54
|
+
}
|
|
55
|
+
const str = (v) => (typeof v === 'string' ? v : null);
|
|
56
|
+
return {
|
|
57
|
+
state: 'ok',
|
|
58
|
+
tool: str(data.tool),
|
|
59
|
+
fileUrl: str(data.fileUrl),
|
|
60
|
+
screens: data.screens.filter((s) => s && typeof s === 'object' && typeof s.nodeId === 'string'),
|
|
61
|
+
};
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
// The key spelled another way — `Design-Frames`, `design_frames`, `designFrames`. It is never read as
|
|
65
|
+
// the key, but it is said: a story that misspells it must not read as "nobody recorded frames".
|
|
66
|
+
const keyVariant = (fm) => Object.keys(fm).find((k) => k !== FRAMES_KEY && k.toLowerCase().replace(/[_-]/g, '') === 'designframes');
|
|
67
|
+
export const recordsFrames = (fm = {}) => Object.hasOwn(fm, FRAMES_KEY) || keyVariant(fm) !== undefined;
|
|
68
|
+
|
|
69
|
+
// `"12:34"` and `'12:34'` — a YAML habit. The reader keeps the quote marks, so they are taken off here
|
|
70
|
+
// (and said), rather than reported as an ID that is not in design-links.json.
|
|
71
|
+
const unquote = (id) => (id.length >= 3 && /^(["']).+\1$/.test(id) ? id.slice(1, -1) : id);
|
|
72
|
+
|
|
73
|
+
// The pure rule. `fm` is the story's parsed frontmatter, `links` what `readDesignLinks` returned.
|
|
74
|
+
// Returns { recorded, ids, frames, findings }: `recorded` is false only when the key is absent;
|
|
75
|
+
// `findings` are { kind, message } — every one a warning.
|
|
76
|
+
export function frameFindings(fm = {}, links = { state: 'missing' }) {
|
|
77
|
+
if (!Object.hasOwn(fm, FRAMES_KEY)) {
|
|
78
|
+
const k = keyVariant(fm);
|
|
79
|
+
const findings = k === undefined ? [] : [{ kind: 'key-spelling', message: `\`${forTerminal(k)}:\` is not read — the key is spelled \`${FRAMES_KEY}\`, exactly` }];
|
|
80
|
+
return { recorded: false, ids: [], frames: [], findings };
|
|
81
|
+
}
|
|
82
|
+
const v = fm[FRAMES_KEY];
|
|
83
|
+
const findings = [];
|
|
84
|
+
// The right key AND a misspelled one: the second is never read, so its IDs would be lost in silence.
|
|
85
|
+
const twin = keyVariant(fm);
|
|
86
|
+
if (twin !== undefined) findings.push({ kind: 'key-spelling', message: `\`${forTerminal(twin)}:\` is not read — only \`${FRAMES_KEY}\` is; move its IDs into that line and delete it` });
|
|
87
|
+
if (!Array.isArray(v)) {
|
|
88
|
+
const text = String(v ?? '');
|
|
89
|
+
findings.push(text.includes('#')
|
|
90
|
+
? { kind: 'commented', message: `\`${FRAMES_KEY}: ${forTerminal(text)}\` has a \`#\` after it, so it is read as text, not a list — write the list bare, with no comment on the line` }
|
|
91
|
+
: text === ''
|
|
92
|
+
? { kind: 'not-a-list', message: `\`${FRAMES_KEY}:\` is blank — write the IDs on the same line, as \`${FRAMES_KEY}: [id, id]\` (a \`- id\` list on the lines below is not read), or \`${FRAMES_KEY}: []\` for a story with no screens` }
|
|
93
|
+
: { kind: 'not-a-list', message: `\`${FRAMES_KEY}: ${forTerminal(text)}\` is not a list — write the IDs inside one pair of brackets, as \`${FRAMES_KEY}: [id, id]\`` });
|
|
94
|
+
return { recorded: true, ids: [], frames: [], findings };
|
|
95
|
+
}
|
|
96
|
+
const quoted = v.filter((id) => unquote(id) !== id);
|
|
97
|
+
if (quoted.length) findings.push({ kind: 'quoted', message: `frame IDs should be written without quotes: ${quoted.map(quote).join(', ')} — they are read without them` });
|
|
98
|
+
const ids = v.map(unquote);
|
|
99
|
+
const seen = new Set();
|
|
100
|
+
for (const id of ids) {
|
|
101
|
+
if (BAD_ID.test(id)) findings.push({ kind: 'bad-id', message: `frame ID ${quote(id)} holds a space, \`#\` or bracket, so it cannot be read back — give the frame a plain ID in the design tool` });
|
|
102
|
+
if (seen.has(id)) findings.push({ kind: 'duplicate', message: `frame ID ${quote(id)} is listed twice` });
|
|
103
|
+
seen.add(id);
|
|
104
|
+
}
|
|
105
|
+
const unique = [...seen];
|
|
106
|
+
if (!unique.length) return { recorded: true, ids, frames: [], findings };
|
|
107
|
+
if (links.state === 'missing') {
|
|
108
|
+
findings.push({ kind: 'no-design-links', message: `${unique.length} frame ID(s) are recorded, but there is no ${DESIGN_LINKS_FILE} to read their names and links from — the UI step writes it` });
|
|
109
|
+
return { recorded: true, ids, frames: unique.map((id) => ({ id, found: false })), findings };
|
|
110
|
+
}
|
|
111
|
+
if (links.state === 'unreadable') {
|
|
112
|
+
findings.push({ kind: 'design-links-unreadable', message: `${DESIGN_LINKS_FILE} cannot be read (${links.why}), so the frame IDs cannot be checked` });
|
|
113
|
+
return { recorded: true, ids, frames: unique.map((id) => ({ id, found: false })), findings };
|
|
114
|
+
}
|
|
115
|
+
const frames = unique.map((id) => {
|
|
116
|
+
const s = links.screens.find((x) => x.nodeId === id);
|
|
117
|
+
if (!s) return { id, found: false };
|
|
118
|
+
const str = (x) => (typeof x === 'string' ? x : null);
|
|
119
|
+
return { id, found: true, name: str(s.name), platform: str(s.platform), url: str(s.url) };
|
|
120
|
+
});
|
|
121
|
+
const missing = frames.filter((f) => !f.found);
|
|
122
|
+
if (missing.length) {
|
|
123
|
+
findings.push({ kind: 'not-found', message: `frame ID(s) ${missing.map((f) => quote(f.id)).join(', ')} are not in ${DESIGN_LINKS_FILE} — copy the \`nodeId\` exactly, or re-run the UI step if the screen is new` });
|
|
124
|
+
}
|
|
125
|
+
return { recorded: true, ids, frames, findings };
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
// A story file's frontmatter, read the same way by both readers. A byte-order mark, Windows line endings
|
|
129
|
+
// (git's `core.autocrlf` writes them on checkout) and spaces at the end of a line are taken out first:
|
|
130
|
+
// the shared reader matches `---\n` and `[ … ]` to the end of the line, so without this a story checked
|
|
131
|
+
// out on Windows would read as "nobody recorded frames", and `[12:34] ` as not a list.
|
|
132
|
+
export function readStoryFrontmatter(file) {
|
|
133
|
+
const text = fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n').replace(/[ \t]+$/gm, '');
|
|
134
|
+
return parseFrontmatter(text);
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
// The Product's design.json as { state: 'missing' | 'unreadable' | 'ok', data }. Read safely, like
|
|
138
|
+
// design-links.json: a file that does not parse is said, never thrown out of the command.
|
|
139
|
+
export function readDesignConfig(root) {
|
|
140
|
+
const file = path.join(root, PROJECT_FILES.designConfig);
|
|
141
|
+
if (!fs.existsSync(file)) return { state: 'missing' };
|
|
142
|
+
try {
|
|
143
|
+
const data = readJSONStrict(file, null);
|
|
144
|
+
return data && typeof data === 'object' && !Array.isArray(data) ? { state: 'ok', data } : { state: 'unreadable' };
|
|
145
|
+
} catch {
|
|
146
|
+
return { state: 'unreadable' };
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
// #358 — before UI work, can the agent reach the design tool with the right file open? yad cannot ask:
|
|
151
|
+
// an MCP server belongs to the agent's session. So this says HOW to ask, and what to tell the person
|
|
152
|
+
// when the answer is no; the yad-spec and yad-implement skills make the call and stop on a failure.
|
|
153
|
+
// null when the story names no frame (no UI task, nothing to check). `reachable` is `check` (probe, and
|
|
154
|
+
// stop when it fails) or `not-checkable` (nothing to probe: go on with the links). `appBound` is true (read
|
|
155
|
+
// through the running app), false (no app: a hosted server, so sign in — or, with `local` true, a CLI that
|
|
156
|
+
// works on the design file on disk, E164) or null (yad cannot tell: `stop` names both).
|
|
157
|
+
export function designPreflight(design, links, frames) {
|
|
158
|
+
if (!frames.length) return null;
|
|
159
|
+
const d = design.state === 'ok' ? design.data : null;
|
|
160
|
+
const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
|
|
161
|
+
const tool = str(d?.tool);
|
|
162
|
+
const notCheckable = (why) => ({ tool, reachable: 'not-checkable', why });
|
|
163
|
+
if (design.state === 'missing') return notCheckable('no .sdlc/design.json: no design tool is connected');
|
|
164
|
+
if (design.state === 'unreadable') return notCheckable('.sdlc/design.json cannot be read');
|
|
165
|
+
if (!tool || tool === 'none') return notCheckable('design.json connects no design tool');
|
|
166
|
+
if (d.source === 'unavailable') return notCheckable(`design.json records ${forTerminal(tool)} as unavailable (source: unavailable)`);
|
|
167
|
+
const reach = reachFor(tool);
|
|
168
|
+
if (!reach) return notCheckable(`yad has no reachability check for ${forTerminal(tool)}`);
|
|
169
|
+
const provider = str(d.provider) ?? str(d.source);
|
|
170
|
+
// The MCP id is free text: `Figma-Desktop`, `html.to.design` and ` html_to_design ` are the names yad
|
|
171
|
+
// knows, so names are compared on their letters and digits alone.
|
|
172
|
+
const fold = (s) => String(s).toLowerCase().replace(/[^a-z0-9]/g, '');
|
|
173
|
+
const key = provider === null ? null : fold(provider);
|
|
174
|
+
const listed = (list) => key !== null && Array.isArray(list) && list.some((p) => fold(p) === key);
|
|
175
|
+
// A provider that only writes (html-to-design) has no call that reads a frame: probing it would fail
|
|
176
|
+
// on every story and make the person override each time.
|
|
177
|
+
if (listed(reach.writers)) return notCheckable(`the connected provider ${forTerminal(provider)} cannot read a frame`);
|
|
178
|
+
// The frames come from design-links.json. Without it — or with one the UI step wrote for ANOTHER tool —
|
|
179
|
+
// the IDs belong to nothing this tool can open, and a probe would blame the app.
|
|
180
|
+
if (links.state === 'missing') return notCheckable('there is no design-links.json for the frame IDs — re-run the UI step');
|
|
181
|
+
if (links.state === 'unreadable') return notCheckable(`design-links.json cannot be read (${links.why})`);
|
|
182
|
+
if (links.tool && fold(links.tool) !== fold(tool)) {
|
|
183
|
+
return notCheckable(`design-links.json was recorded for ${forTerminal(links.tool)}, but design.json now connects ${forTerminal(tool)} — re-run the UI step`);
|
|
184
|
+
}
|
|
185
|
+
// Every recorded ID is unresolved: the bad IDs are the problem (the warnings name them), not the app.
|
|
186
|
+
const found = frames.find((f) => f.found);
|
|
187
|
+
if (!found) return notCheckable('no recorded frame is in design-links.json — fix the frame IDs first');
|
|
188
|
+
const local = listed(reach.local);
|
|
189
|
+
const appBound = local ? false : reach.appBound === true || listed(reach.appBound) ? true : listed(reach.signInOnly) ? false : null;
|
|
190
|
+
// design.json's project_url is a project, not a file, so it is never compared against.
|
|
191
|
+
const file = links.fileUrl;
|
|
192
|
+
const fill = (s) => s.replace(/<file>/g, file ? `\`${forTerminal(file)}\`` : 'the design file').replace(/<frame>/g, `\`${forTerminal(found.id)}\``);
|
|
193
|
+
return {
|
|
194
|
+
tool, provider, reachable: 'check', appBound, local, file, frame: found.id,
|
|
195
|
+
probe: fill(local ? reach.localProbe : appBound === null && reach.eitherProbe ? reach.eitherProbe : reach.probe),
|
|
196
|
+
stop: fill(local ? reach.localStop : appBound === true ? reach.open : appBound === false ? reach.signIn : reach.either),
|
|
197
|
+
// E165: when the probe fails because the tool is not on this machine at all (not a closed app or a
|
|
198
|
+
// sign-in), the agent offers this first, under the connect-tool rule. A tool with a reach rule is shipped.
|
|
199
|
+
// Not for a provider that is one app's own server (`reach.ownServer`: Figma's figma-desktop): the tool's
|
|
200
|
+
// recipe connects its other server, so the person opens the app instead, as `stop` says. OpenPencil's
|
|
201
|
+
// MCP server is not one: its recipe adds it.
|
|
202
|
+
...(listed(reach.ownServer) ? {} : { connect: `yad toolbox connect ${tool} --json` }),
|
|
203
|
+
};
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
const isFile = (p) => { try { return fs.statSync(p).isFile(); } catch { return false; } };
|
|
207
|
+
|
|
208
|
+
// One story's frames. Throws { message, hint } only for the command line: a word that is not a story
|
|
209
|
+
// id, or a story with no file. Everything about the frames themselves comes back in `findings`.
|
|
210
|
+
export function readStoryFrames(root, story) {
|
|
211
|
+
if (!story || story === true) {
|
|
212
|
+
throw Object.assign(new Error('yad story frames needs a story id'), { hint: 'use: yad story frames <story-id>, such as EP-checkout-S01' });
|
|
213
|
+
}
|
|
214
|
+
if (!STORY_RE.test(String(story))) {
|
|
215
|
+
throw Object.assign(new Error(`'${forTerminal(story)}' is not a story id`), { hint: 'expected EP-<slug>-S<n>, such as EP-checkout-S01' });
|
|
216
|
+
}
|
|
217
|
+
const epic = storyEpic(story);
|
|
218
|
+
const epicDir = epicRoot(root, epic);
|
|
219
|
+
const file = path.join(epicDir, 'stories', `${story}.md`);
|
|
220
|
+
if (!isFile(file)) {
|
|
221
|
+
throw Object.assign(new Error(`no story file epics/${epic}/stories/${story}.md`), { hint: 'check the story id; the stories step writes one file per story' });
|
|
222
|
+
}
|
|
223
|
+
const links = readDesignLinks(epicDir);
|
|
224
|
+
const r = frameFindings(readStoryFrontmatter(file), links);
|
|
225
|
+
return {
|
|
226
|
+
story, epic,
|
|
227
|
+
tool: links.state === 'ok' ? links.tool : null,
|
|
228
|
+
fileUrl: links.state === 'ok' ? links.fileUrl : null,
|
|
229
|
+
...r,
|
|
230
|
+
preflight: designPreflight(readDesignConfig(root), links, r.frames),
|
|
231
|
+
};
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
// Every story that records frames (or misspells the key), for `yad doctor`:
|
|
235
|
+
// [{ epic, story, recorded, frames: <how many IDs>, findings }]. The epic folders are the caller's to
|
|
236
|
+
// pick. A story file the command cannot reach — named for another epic, or not `EP-<slug>-S<n>.md` — is
|
|
237
|
+
// reported as that, never with advice to run a command that would refuse it.
|
|
238
|
+
export function allStoryFrames(root, epicIds) {
|
|
239
|
+
const out = [];
|
|
240
|
+
for (const epic of epicIds) {
|
|
241
|
+
const epicDir = epicRoot(root, epic);
|
|
242
|
+
const dir = path.join(epicDir, 'stories');
|
|
243
|
+
let names;
|
|
244
|
+
try {
|
|
245
|
+
// `isFile` follows a symlink, as the command's own check does, so the two read the same stories.
|
|
246
|
+
names = fs.readdirSync(dir).filter((n) => n.endsWith('.md') && isFile(path.join(dir, n))).sort();
|
|
247
|
+
} catch {
|
|
248
|
+
continue;
|
|
249
|
+
}
|
|
250
|
+
let links = null; // read once per epic, and only when a story there records frames
|
|
251
|
+
for (const f of names) {
|
|
252
|
+
const fm = readStoryFrontmatter(path.join(dir, f));
|
|
253
|
+
if (!recordsFrames(fm)) continue;
|
|
254
|
+
const story = f.replace(/\.md$/, '');
|
|
255
|
+
if (!STORY_RE.test(story) || storyEpic(story) !== epic) {
|
|
256
|
+
out.push({ epic, story, recorded: true, frames: 0, findings: [{ kind: 'not-a-story-file', message: `stories/${forTerminal(f)} records design frames, but its name is not ${epic}-S<n>.md, so \`yad story frames\` cannot read it — rename the file` }] });
|
|
257
|
+
continue;
|
|
258
|
+
}
|
|
259
|
+
links ??= readDesignLinks(epicDir);
|
|
260
|
+
const r = frameFindings(fm, links);
|
|
261
|
+
out.push({ epic, story, recorded: r.recorded, frames: r.ids.length, findings: r.findings });
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
return out;
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
// `yad story frames <story> [--json]`. Read only: it prints the story's frames and every finding as a
|
|
268
|
+
// warning, and exits 1 only for a refusal (an unknown action, a word that is not a story id, a story
|
|
269
|
+
// with no file).
|
|
270
|
+
export async function runStory(root, { action, story, json = false } = {}) {
|
|
271
|
+
if (action !== 'frames') {
|
|
272
|
+
refuse(action ? `unknown action: ${forTerminal(action)}` : 'yad story needs an action', 'use: yad story frames <story-id> [--json]', { json });
|
|
273
|
+
return { ok: false };
|
|
274
|
+
}
|
|
275
|
+
let r;
|
|
276
|
+
try {
|
|
277
|
+
r = readStoryFrames(root, story);
|
|
278
|
+
} catch (e) {
|
|
279
|
+
refuse(e.message, e.hint ?? null, { json });
|
|
280
|
+
return { ok: false };
|
|
281
|
+
}
|
|
282
|
+
const warnings = r.findings.map((f) => f.message);
|
|
283
|
+
if (json) {
|
|
284
|
+
emitJSON({
|
|
285
|
+
ok: true, story: r.story, epic: r.epic, tool: r.tool, fileUrl: r.fileUrl, recorded: r.recorded, preflight: r.preflight,
|
|
286
|
+
frames: r.frames, findings: r.findings.map((f) => ({ kind: f.kind, message: stripAnsi(f.message) })), warnings,
|
|
287
|
+
});
|
|
288
|
+
return { ok: true, ...r };
|
|
289
|
+
}
|
|
290
|
+
log(c.bold(`\n${r.story} — design frames${r.tool ? ` (${forTerminal(r.tool)})` : ''}`));
|
|
291
|
+
if (!r.recorded) info(`no design frames recorded — the stories step adds \`${FRAMES_KEY}: [id, …]\` to the story`);
|
|
292
|
+
else if (!r.ids.length && !r.findings.length) info(`no screens (\`${FRAMES_KEY}: []\`)`);
|
|
293
|
+
for (const f of r.frames) {
|
|
294
|
+
const id = forTerminal(f.id);
|
|
295
|
+
if (!f.found) { warn(`${id} — not found`); continue; }
|
|
296
|
+
ok(`${id} ${forTerminal(f.name ?? '(no name)')}${f.platform ? ` [${forTerminal(f.platform)}]` : ''}`);
|
|
297
|
+
if (f.url) log(` ${c.dim(forTerminal(f.url))}`);
|
|
298
|
+
}
|
|
299
|
+
for (const w of warnings) warn(w);
|
|
300
|
+
const p = r.preflight;
|
|
301
|
+
if (p?.reachable === 'check') {
|
|
302
|
+
hand(`before UI work: ${p.probe} — if that fails, stop: ${p.stop}`);
|
|
303
|
+
if (p.connect) hand(`if ${forTerminal(p.tool)} is not on this machine at all, your agent can offer to connect it first: \`${p.connect}\``);
|
|
304
|
+
}
|
|
305
|
+
else if (p) info(`before UI work: the design tool is not checked (${p.why}) — build from the frame links`);
|
|
306
|
+
return { ok: true, ...r };
|
|
307
|
+
}
|