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 CHANGED
@@ -1,3 +1,30 @@
1
+ # [4.9.0](https://github.com/abdelrahmannasr/yadflow/compare/v4.8.0...v4.9.0) (2026-11-04)
2
+
3
+
4
+ ### Bug Fixes
5
+
6
+ * **doctor:** [#352](https://github.com/abdelrahmannasr/yadflow/issues/352) review 1 — '>22' and '>= 22' read as npm reads them, glab duplicates only where glab looks, repo text cleaned, one Node row per folder ([5474a05](https://github.com/abdelrahmannasr/yadflow/commit/5474a052012a1bf7e2322d53e998654e171bb90f))
7
+ * **doctor:** [#352](https://github.com/abdelrahmannasr/yadflow/issues/352) review 2 — look for glab's config only where glab is known to look on Windows ([35b9d67](https://github.com/abdelrahmannasr/yadflow/commit/35b9d67a93f5b7639f07492ac7bd63f503265134))
8
+ * **preview:** review 1 — a {branch} pattern never fills from the wrong branch, one hard time budget, no false 'none recorded' ([#359](https://github.com/abdelrahmannasr/yadflow/issues/359)) ([d1688b0](https://github.com/abdelrahmannasr/yadflow/commit/d1688b0d23d9b88f6709b7a9921091e760b49f86))
9
+ * **preview:** review 2 — the Preview line is set before the summary, GitLab environments asked for their state, the default branch is no PR's ([#359](https://github.com/abdelrahmannasr/yadflow/issues/359)) ([aa8b8b7](https://github.com/abdelrahmannasr/yadflow/commit/aa8b8b7b56222a2f9047691a3f7019ad30e44d94))
10
+ * **preview:** review 3 — one next step in the why, GitLab merge-request pipeline deployments count ([#359](https://github.com/abdelrahmannasr/yadflow/issues/359)) ([98089df](https://github.com/abdelrahmannasr/yadflow/commit/98089dfeebc7ca590b71c883208f4bace61d178d))
11
+ * **preview:** review 4 — GitLab without --pr and a non-number --pr both say pass --pr; the MR ref counts with no source branch ([#359](https://github.com/abdelrahmannasr/yadflow/issues/359)) ([86d65ae](https://github.com/abdelrahmannasr/yadflow/commit/86d65aea2a8b47d7f4a6fa3a2b3b3ec35534b8d2))
12
+ * **preview:** review 5 — a broken pattern is named before --pr on GitLab, and --pr is never offered for a GitLab that cannot be asked ([#359](https://github.com/abdelrahmannasr/yadflow/issues/359)) ([04c4379](https://github.com/abdelrahmannasr/yadflow/commit/04c43798e2d6b4e97f7c6e4b5f27047fa654f55d))
13
+ * **preview:** review 6 — the GitLab MR-pipeline step reads a flag, not the wording ([#359](https://github.com/abdelrahmannasr/yadflow/issues/359)) ([42fa00d](https://github.com/abdelrahmannasr/yadflow/commit/42fa00d8779f655eaeada77082c60ca02d3d25bd))
14
+ * **story:** review 1 — the preflight never stops a person for the wrong reason ([#358](https://github.com/abdelrahmannasr/yadflow/issues/358)) ([5dcd98b](https://github.com/abdelrahmannasr/yadflow/commit/5dcd98b3244309b7ce2bb4a72c6504c357cf91eb))
15
+ * **story:** review 1 — Windows line endings, misspelled keys and odd story files never read as "no frames" ([#354](https://github.com/abdelrahmannasr/yadflow/issues/354)) ([b130a56](https://github.com/abdelrahmannasr/yadflow/commit/b130a56c397d2ee6851ff9264bb93e950633eb2c))
16
+ * **story:** review 2 — doctor follows symlinks like the command; a second, misspelled key is said ([#354](https://github.com/abdelrahmannasr/yadflow/issues/354)) ([c4a0570](https://github.com/abdelrahmannasr/yadflow/commit/c4a0570db90c28ec59d8d931fb81555ac450615c))
17
+ * **story:** review 2 — frames of another tool, unknown MCP ids and a missing design-links.json never stop a person wrongly ([#358](https://github.com/abdelrahmannasr/yadflow/issues/358)) ([041c368](https://github.com/abdelrahmannasr/yadflow/commit/041c36867198a62843f4daf643b366f910e632d1))
18
+ * **story:** review 3 — provider and tool names compared on their letters and digits ([#358](https://github.com/abdelrahmannasr/yadflow/issues/358)) ([edd1145](https://github.com/abdelrahmannasr/yadflow/commit/edd1145833792700a787b5c0795ddf441364321b))
19
+
20
+
21
+ ### Features
22
+
23
+ * **doctor:** [#352](https://github.com/abdelrahmannasr/yadflow/issues/352) — check the machine: the Node each repo pins, Docker where a repo asks for it, duplicate glab config files ([fdabafc](https://github.com/abdelrahmannasr/yadflow/commit/fdabafc166d8fce0216023c885650b6362ca1de6))
24
+ * **repo:** a preview address per PR/MR for live design checks ([#359](https://github.com/abdelrahmannasr/yadflow/issues/359)) ([225b646](https://github.com/abdelrahmannasr/yadflow/commit/225b646bbed8fd1422368279e2c03e1c348a95c5))
25
+ * **story:** yad story frames reads a story's design frames; doctor warns on any it cannot read ([#354](https://github.com/abdelrahmannasr/yadflow/issues/354)) ([fda0a46](https://github.com/abdelrahmannasr/yadflow/commit/fda0a468b9c7213b308ad60bcabd653fd5bf231d))
26
+ * **story:** yad story frames says how to check the design tool can be reached ([#358](https://github.com/abdelrahmannasr/yadflow/issues/358)) ([dd9bd94](https://github.com/abdelrahmannasr/yadflow/commit/dd9bd94c0a35b62e62416c9b5999c966de4bccb6))
27
+
1
28
  # [4.8.0](https://github.com/abdelrahmannasr/yadflow/compare/v4.7.0...v4.8.0) (2026-11-02)
2
29
 
3
30
 
package/bin/commands.mjs CHANGED
@@ -41,6 +41,7 @@ export { runHistory, HISTORY_FLAGS } from '../cli/history.mjs';
41
41
  export { runRepo } from '../cli/repo.mjs';
42
42
  export { runRiskMap } from '../cli/riskmap-command.mjs';
43
43
  export { runCodeowners } from '../cli/codeowners-command.mjs';
44
+ export { runStory } from '../cli/story-frames.mjs';
44
45
  export { runDocs } from '../cli/docs.mjs';
45
46
  export { runDetect } from '../cli/detect.mjs';
46
47
  export { runToolboxAdd, runToolboxCheck, runToolboxList, runToolboxRemove } from '../cli/toolbox.mjs';
package/bin/yad.mjs CHANGED
@@ -319,6 +319,9 @@ ${c.bold('Build helpers')}
319
319
  Commit by convention (trailers, atomic guard); --body adds a
320
320
  body above the trailers; --manual is
321
321
  the door past the Product's ledger hook, reason recorded
322
+ yad story frames <story> [--json] Show the design frames a story records (its design-frames
323
+ list), with each frame's name, platform and link from the
324
+ epic's design-links.json; warns on an ID it cannot find
322
325
  yad build start <story> --repo <r> ${c.dim('(on the Product)')} Begin a story's Build lane in one repo
323
326
  yad build step <story> --repo <r> <step> in_progress|in_review|done|blocked [--reason <text>] [--run <uid>] [--via auto|human] [--task <T>]
324
327
  Move the lane's current step; done records how it closed.
@@ -421,6 +424,10 @@ ${c.bold('Build helpers')}
421
424
  yad repo refresh [name] [--push] Re-pack a stale repo (a human decision). --push commits the
422
425
  refreshed code-maps + registry as a chore(product): sync code-context … [skip ci]
423
426
  audit commit and pushes it to the Product default branch (--allow-branch to override)
427
+ yad repo preview <name> [<pattern>] [--clear]
428
+ Show, set or clear a repo's preview address pattern (#359), e.g.
429
+ 'https://pr-{pr}.myapp.dev' ({pr} {branch} {repo}). Review steps
430
+ check the live page there; with none, they say "locally only"
424
431
  yad risk-map check [repo] [--json] Warn where a code repo's .sdlc/risk-map (a risk level per
425
432
  directory, no names) has gone stale — advisory, never blocks
426
433
  yad risk-map draft [repo] Add an 'unset' line for every directory the map does not cover
@@ -507,6 +514,7 @@ function parseArgs(argv) {
507
514
  else if (a === '--open-pr') o.openPr = true;
508
515
  else if (a === '--post') o.post = true;
509
516
  else if (a === '--allow-branch') o.allowBranch = true;
517
+ else if (a === '--clear') o.clear = true;
510
518
  else if (a === '--overwrite-local') o.overwriteLocal = true;
511
519
  else if (a === '--merged') o.merged = true;
512
520
  else if (a === '--ship') o.ship = true;
@@ -609,9 +617,10 @@ const ACTIONS = {
609
617
  review: { known: ['trailer', 'context', 'chat', 'cards', 'walkthrough', 'nudge', 'reconcile'] },
610
618
  tidy: { known: ['up'] },
611
619
  history: { known: ['list', 'show', 'search'], default: 'list' },
612
- repo: { known: ['list', 'refresh', 'sync', 'clone'], default: 'list' },
620
+ repo: { known: ['list', 'refresh', 'sync', 'clone', 'preview'], default: 'list' },
613
621
  'risk-map': { known: ['check', 'draft'], default: 'check' },
614
622
  codeowners: { known: ['check'], default: 'check' },
623
+ story: { known: ['frames'] },
615
624
  docs: { known: ['list', 'build', 'deploy', 'sync'], default: 'list' },
616
625
  reconcile: { known: ['check', 'refresh', 'wire'] },
617
626
  hook: { known: ['ledger-guard', 'agent-guard'] },
@@ -631,6 +640,7 @@ const PRODUCT_CMDS = new Set([
631
640
  'skip', 'unskip', 'defer', 'undefer', 'dial', 'mode', 'kill', 'unkill', 'unblock', 'gate', 'checkpoint',
632
641
  'capture', 'claims', 'assign', 'unassign', 'owners', 'fold', 'tidy', 'index', 'history', 'repo',
633
642
  'risk-map', 'codeowners', 'docs', 'thread', 'reconcile', 'member', 'standup', 'build', 'worktree', 'ci',
643
+ 'story',
634
644
  ]);
635
645
  // `status` reads the Product but must keep the folder it ran in: "here" is that checkout's task branch (#349).
636
646
  const REPO_CMDS = new Set(['commit', 'open-pr', 'ship', 'review', 'run', 'status', 'guide']);
@@ -1291,7 +1301,11 @@ async function main() {
1291
1301
  }
1292
1302
  case 'repo': {
1293
1303
  const [, action, name] = o._;
1294
- result = await commands.runRepo(o.dir, { action: action || 'list', name, today, push: o.push, allowBranch: o.allowBranch });
1304
+ // `yad repo preview <name> [<pattern>]` (#359): the one action with a third word.
1305
+ const pattern = action === 'preview' ? o._[3] : undefined;
1306
+ if (action === 'preview' && o._.length > 4) { refuse(`unexpected argument(s): ${o._.slice(4).join(' ')}`, 'use: yad repo preview <name> [<pattern>] [--clear] — quote the pattern'); break; }
1307
+ result = await commands.runRepo(o.dir, { action: action || 'list', name, pattern, clear: !!o.clear, today,
1308
+ push: o.push, allowBranch: o.allowBranch });
1295
1309
  break;
1296
1310
  }
1297
1311
  case 'risk-map': {
@@ -1305,6 +1319,12 @@ async function main() {
1305
1319
  result = await commands.runCodeowners(o.dir, { action: action || 'check', name, json: o.json, platform: o.platform, write: o._.some((a) => a === '--write' || a.startsWith('--write=')) });
1306
1320
  break;
1307
1321
  }
1322
+ case 'story': {
1323
+ if (o._.length > 3) { refuse(`unexpected argument(s): ${o._.slice(3).join(' ')}`, 'use: yad story frames <story-id> — one story at a time'); break; }
1324
+ const [, action, story] = o._;
1325
+ result = await commands.runStory(o.dir, { action, story, json: o.json });
1326
+ break;
1327
+ }
1308
1328
  case 'roster':
1309
1329
  // Removed in E62. Kept as a word for one major so a script or a habit gets told where it went
1310
1330
  // instead of "unknown command".
@@ -181,9 +181,11 @@ export const COMMAND_CLASS = {
181
181
  'repo refresh': { class: 'local-write', flags: { push: 'default-push', 'allow-branch': 'on-request' } },
182
182
  'repo sync': { class: 'local-write' },
183
183
  'repo clone': { class: 'local-write' },
184
+ 'repo preview': { class: 'local-write' },
184
185
  'risk-map check': { class: 'read' },
185
186
  'risk-map draft': { class: 'local-write' },
186
187
  'codeowners check': { class: 'read' },
188
+ 'story frames': { class: 'read' },
187
189
  roster: { class: 'removed' },
188
190
  'docs list': { class: 'read' },
189
191
  'docs build': { class: 'local-write' },
@@ -373,6 +375,11 @@ export const SHIPPED_ALLOW_LISTS = Object.freeze([
373
375
  'gate status', 'gate review', 'gate walkthrough', 'review context', 'review chat', 'review cards', 'review walkthrough', 'member list',
374
376
  'worktree list', 'claims', 'owners', 'history list', 'history show', 'history search', 'repo list', 'risk-map check', 'codeowners check', 'docs list',
375
377
  'thread', 'reconcile check'].map((k) => `Bash(yad ${k}:*)`),
378
+ // next release (#354): `story frames`
379
+ ['guide', 'help', 'doctor', 'detect', 'signing check', 'ci check', 'toolbox list', 'toolbox check', 'skill list', 'skill recommend', 'foundation status', 'status', 'next',
380
+ 'gate status', 'gate review', 'gate walkthrough', 'review context', 'review chat', 'review cards', 'review walkthrough', 'member list',
381
+ 'worktree list', 'claims', 'owners', 'history list', 'history show', 'history search', 'repo list', 'risk-map check', 'codeowners check', 'story frames', 'docs list',
382
+ 'thread', 'reconcile check'].map((k) => `Bash(yad ${k}:*)`),
376
383
  ].map((list) => Object.freeze(list)));
377
384
 
378
385
  // Entries an older yadflow pre-approved that this one does not (a command later reclassed as a write, say).
package/cli/build.mjs CHANGED
@@ -31,7 +31,7 @@ import { sealedEpic } from './thread.mjs';
31
31
  import { worktreeAt, sameDir } from './worktree-record.mjs';
32
32
 
33
33
  const CODE = 'YAD-STATE-009';
34
- const STORY_RE = /^EP-[a-z0-9-]+-S\d+$/;
34
+ export const STORY_RE = /^EP-[a-z0-9-]+-S\d+$/;
35
35
  const TASK_RE = /^T\d+$/;
36
36
  export const VERDICTS = ['approved-unchanged', 'approved-with-edits', 'rejected'];
37
37
  // The signals each step's trust entry may carry (state-schema.md, "Per-step signals fields").
package/cli/doctor.mjs CHANGED
@@ -3,6 +3,7 @@
3
3
  // real repos), shape (what schemaVersion the files are on vs the engine), epics (each ledger loads),
4
4
  // and threads (feature-thread lineage). Pure reporting: exit 1 on any FAIL, 0 with warnings.
5
5
  // `--json` emits the checks for CI / bug reports.
6
+ import os from 'node:os';
6
7
  import path from 'node:path';
7
8
  import fs from 'node:fs';
8
9
  import { c, log, ok, info, warn, fail, hand, run, has, exists, isPlainObject, readJSON, readJSONStrict, emitJSON, asArg, nodeSupport, nodeEndOfLife, NODE_FLOOR, NODE_SUPPORTED } from './lib.mjs';
@@ -30,6 +31,9 @@ import { readOwners } from './owners.mjs';
30
31
  import { readMembers, judgedMemberFiles } from './members.mjs';
31
32
  import { loadChoices, readToolboxFile } from './toolbox.mjs';
32
33
  import { signingDoctorLine } from './signing.mjs';
34
+ import { nodePins, satisfies, nodeFix, dockerReasons, dockerState, glabConfigs } from './machine.mjs';
35
+ import { allStoryFrames, FRAMES_KEY } from './story-frames.mjs';
36
+ import { previewPattern, PREVIEW_KEY } from './preview.mjs';
33
37
 
34
38
  // A registered path doctor may run git in (E81): a checkout the judgement accepts — never a refused
35
39
  // entry (git run in a folder the Product shaped as a repo reads its `config`, which can run a command),
@@ -110,6 +114,60 @@ export function signingChecks(checks, root) {
110
114
  check(checks, 'signing', 'environment', line.status, line.message, line.hint, { alwaysHint: true });
111
115
  }
112
116
 
117
+ // #352 — the machine setup local work depends on (cli/machine.mjs): the active Node against each repo's
118
+ // pinned version, Docker where a repo asks for it, and duplicate glab config files. The Product folder and
119
+ // every registered repo cloned here are read; the rest is not this machine's to judge.
120
+ export function machineChecks(checks, root, { nodeVersion = process.versions.node, env = process.env, home = os.homedir(), platform = process.platform, runner } = {}) {
121
+ const tilde = (p) => (p.startsWith(home + path.sep) ? `~${p.slice(home.length)}` : p);
122
+ const folders = [];
123
+ if (exists(productConfigPath(root))) folders.push({ name: 'the Product', dir: root, id: 'product' });
124
+ const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
125
+ for (const repo of Array.isArray(registry?.repos) ? registry.repos : []) {
126
+ if (!repo || typeof repo.name !== 'string' || typeof repo.path !== 'string' || !repo.path) continue;
127
+ const dir = path.resolve(root, repo.path);
128
+ if (path.resolve(dir) === path.resolve(root) || !isCheckout(root, repo)) continue;
129
+ folders.push({ name: forTerminal(repo.name), dir, id: `repo:${forTerminal(repo.name)}` });
130
+ }
131
+
132
+ // Node: one warning per folder with the pins the running Node does not meet; one ok line when every pin
133
+ // read is met. A pin yad cannot read as a version is counted as skipped, never judged.
134
+ let read = 0;
135
+ let skipped = 0;
136
+ let wrong = 0;
137
+ for (const { name, dir, id } of folders) {
138
+ const unmet = [];
139
+ for (const { source, want } of nodePins(dir)) {
140
+ const meets = satisfies(nodeVersion, want);
141
+ if (meets === null) { skipped += 1; continue; }
142
+ read += 1;
143
+ if (!meets) unmet.push({ source, want });
144
+ }
145
+ if (!unmet.length) continue;
146
+ wrong += 1;
147
+ check(checks, `node-version:${id}`, 'environment', 'warn',
148
+ `node ${nodeVersion} does not meet what ${name} pins: ${unmet.map((u) => `${forTerminal(u.want)} (${u.source})`).join(', ')}`,
149
+ `${nodeFix(unmet[0].want, { env, home })} — the Node that runs yad is the active one (your version manager's default in a new shell)`);
150
+ }
151
+ if (read && !wrong) check(checks, 'node-version', 'environment', 'ok', `node ${nodeVersion} meets every Node version the repos pin (${read} read${skipped ? `, ${skipped} not a version yad reads` : ''})`);
152
+
153
+ // Docker: asked only where a repo names it.
154
+ const needs = folders.map((f) => ({ ...f, why: dockerReasons(f.dir) })).filter((f) => f.why.length);
155
+ if (needs.length) {
156
+ const who = needs.map((f) => `${f.name} (${f.why.join('; ')})`).join(', ');
157
+ const state = dockerState(runner ? { runner } : {});
158
+ if (state === 'running') check(checks, 'docker', 'environment', 'ok', `Docker is running, as ${who} needs`);
159
+ else check(checks, 'docker', 'environment', 'warn', state === 'missing' ? `Docker is not installed, and ${who} asks for it` : `Docker is not running, and ${who} asks for it`,
160
+ state === 'missing' ? 'install Docker (Docker Desktop, or the docker engine), start it, then run those local checks again' : 'start Docker (Docker Desktop, or the docker service), then run those local checks again — the CI runs them either way');
161
+ }
162
+
163
+ // glab: more than one config file.
164
+ const confs = glabConfigs({ env, home, platform });
165
+ if (confs.length > 1) {
166
+ check(checks, 'glab-config', 'environment', 'warn', `glab has ${confs.length} config files: ${confs.map((f) => forTerminal(tilde(f))).join(', ')}`,
167
+ 'glab reads only one of them and ignores the other (a login saved there is not used), and warns about it on every run, which also breaks JSON for any tool that reads glab\'s output and errors together — keep the file glab\'s warning says it uses, copy into it any host it lacks from the other, then delete the other');
168
+ }
169
+ }
170
+
113
171
  // `headCount` is a count of people the caller already read (E74); the CLI passes none, a test passes one.
114
172
  export function projectChecks(checks, root, { headCount = null } = {}) {
115
173
  const productPath = productConfigPath(root);
@@ -513,6 +571,7 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
513
571
  else check(checks, `repo:${repo.name}`, 'project', 'ok', `${nm}: git repo, context fresh`);
514
572
  }
515
573
  if (!registry.repos.length) check(checks, 'repos', 'project', 'warn', 'no code repos registered', 'run `yad setup` to connect one');
574
+ previewChecks(checks, repoEntries);
516
575
  // Per-repo owners went with the roster (E62). Named only where a repo actually lists someone: every
517
576
  // repo an older setup connected carries an EMPTY `domain_owner`, which says nothing.
518
577
  const owned = repoEntries.filter((r) => (Array.isArray(r.domain_owners) && r.domain_owners.length) || (typeof r.domain_owner === 'string' && r.domain_owner));
@@ -1603,6 +1662,35 @@ export function themeChecks(checks, root) {
1603
1662
  }
1604
1663
  }
1605
1664
 
1665
+ // #354 — the design frames each story records (`design-frames: [id, …]`). The rule is `frameFindings` in
1666
+ // cli/story-frames.mjs, the same one `yad story frames` prints, and every finding is a warning there too,
1667
+ // so the two never disagree. No row at all when no story records frames: most Products have no design
1668
+ // tool, and a line saying so on every run would teach people to skip the section.
1669
+ export function storyFrameChecks(checks, root) {
1670
+ const epicsDir = path.join(root, 'epics');
1671
+ if (!exists(epicsDir)) return;
1672
+ const stories = allStoryFrames(root, epicIds(root).sort());
1673
+ if (!stories.length) return;
1674
+ const problems = stories.flatMap((s) => s.findings.map((f) => `${forTerminal(s.story)}: ${f.message}`));
1675
+ if (!problems.length) {
1676
+ const withFrames = stories.filter((s) => s.frames > 0).length;
1677
+ const noScreens = stories.length - withFrames;
1678
+ const parts = [
1679
+ ...(withFrames ? [`${withFrames} story(ies) record design frames, and every frame ID is in its epic's design-links.json`] : []),
1680
+ ...(noScreens ? [`${noScreens} story(ies) say they have no screens (\`${FRAMES_KEY}: []\`)`] : []),
1681
+ ];
1682
+ check(checks, 'stories:design-frames', 'shape', 'ok', parts.join('; '));
1683
+ return;
1684
+ }
1685
+ const shownN = 3;
1686
+ const list = `${problems.slice(0, shownN).join('; ')}${problems.length > shownN ? ` (+${problems.length - shownN} more)` : ''}`;
1687
+ check(
1688
+ checks, 'stories:design-frames', 'shape', 'warn',
1689
+ `${problems.length} problem(s) with the design frames stories record: ${list}`,
1690
+ `run \`yad story frames <story>\` for one story's frames and findings, and rename a story file whose name is not \`<epic>-S<n>.md\` (the command cannot read it). Fixing \`${FRAMES_KEY}\` changes the story file, so a stories review that already passed must approve it again`,
1691
+ );
1692
+ }
1693
+
1606
1694
  // A project's chain against the step catalogue (E4). `phaseChecks` below asks whether a step id is
1607
1695
  // KNOWN; this asks whether a known step is set up the way the catalogue says it is.
1608
1696
  //
@@ -2718,6 +2806,7 @@ export function collectDoctor(root, { headCount = null } = {}) {
2718
2806
  const checks = [];
2719
2807
  envChecks(checks);
2720
2808
  signingChecks(checks, root);
2809
+ machineChecks(checks, root);
2721
2810
  projectChecks(checks, root, { headCount });
2722
2811
  riskMapChecks(checks, root);
2723
2812
  codeownersChecks(checks, root);
@@ -2732,6 +2821,7 @@ export function collectDoctor(root, { headCount = null } = {}) {
2732
2821
  legacyModuleChecks(checks, root);
2733
2822
  typeChecks(checks, root);
2734
2823
  themeChecks(checks, root);
2824
+ storyFrameChecks(checks, root);
2735
2825
  catalogueChecks(checks, root);
2736
2826
  profileChecks(checks, root);
2737
2827
  skipChecks(checks, root);
@@ -2979,3 +3069,18 @@ function gitHookCheck(root, checks) {
2979
3069
  check(checks, 'git-hook', 'project', 'ok', `git pre-commit ledger guard installed in this clone (${where})`);
2980
3070
  }
2981
3071
  }
3072
+
3073
+ // The preview address patterns (#359), by the same rule `yad repo preview` writes with. Said only when
3074
+ // some repo records one: a repo with no pattern is the normal case, and its review says "locally only".
3075
+ export function previewChecks(checks, repoEntries) {
3076
+ const withPreview = repoEntries.filter((r) => PREVIEW_KEY in r && r[PREVIEW_KEY] != null);
3077
+ if (!withPreview.length) return;
3078
+ const bad = withPreview.map((r) => ({ r, problems: previewPattern(r).problems })).filter((x) => x.problems);
3079
+ if (bad.length) {
3080
+ check(checks, 'repos:preview', 'project', 'warn',
3081
+ `${bad.length} preview address pattern${bad.length > 1 ? 's' : ''} in ${PROJECT_FILES.reposRegistry} cannot be used: ${bad.map((x) => `${forTerminal(x.r.name || '(unnamed)')}: it ${x.problems.join('; ')}`).join(', ')}`,
3082
+ `set ${bad.length > 1 ? 'each' : 'it'} again with \`yad repo preview ${bad.length === 1 ? asArg(bad[0].r.name) : '<name>'} <pattern>\` (or --clear) — until then its review checks the page locally only`);
3083
+ } else {
3084
+ check(checks, 'repos:preview', 'project', 'ok', `${withPreview.length} repo${withPreview.length > 1 ? 's record' : ' records'} a preview address pattern`);
3085
+ }
3086
+ }
@@ -0,0 +1,141 @@
1
+ // #352 — the machine setup local work depends on, for `yad doctor`. Three checks, each from what is on disk
2
+ // here (no network):
3
+ // node the Node running yad (the active one, e.g. nvm's default) against the version each repo pins:
4
+ // .nvmrc, .node-version, .tool-versions (nodejs), package.json `engines.node` and `volta.node`.
5
+ // A pin yad cannot read as a version (`lts/*`, a URL) is left out, never guessed.
6
+ // docker Docker running, only where a repo itself asks for it: a compose file, a Dockerfile, a `docker`
7
+ // call in its package.json scripts, or a docker hook in its pre-commit config. yad's own gates
8
+ // need no Docker, so a repo that names none is never asked about.
9
+ // glab more than one glab config file. glab then reads only one and ignores the other (a login saved
10
+ // there is not used), and warns on every run, which breaks JSON for a tool that reads its output
11
+ // and its errors together.
12
+ import fs from 'node:fs';
13
+ import os from 'node:os';
14
+ import path from 'node:path';
15
+ import { run, readJSON, isPlainObject, forTerminal } from './lib.mjs';
16
+
17
+ const read = (file) => { try { return fs.readFileSync(file, 'utf8'); } catch { return null; } };
18
+
19
+ // The Node versions a folder pins, each { source, want }.
20
+ export function nodePins(dir) {
21
+ const pins = [];
22
+ for (const f of ['.nvmrc', '.node-version']) {
23
+ const t = read(path.join(dir, f));
24
+ const v = t?.split('\n').map((l) => l.replace(/#.*/, '').trim()).find(Boolean);
25
+ if (v) pins.push({ source: f, want: v });
26
+ }
27
+ const tv = read(path.join(dir, '.tool-versions'));
28
+ // A line may list fallbacks (`nodejs 24.2.0 22.0.0`): the first is the one in use, and the one read.
29
+ const line = tv?.split('\n').map((l) => l.replace(/#.*/, '').trim()).find((l) => /^(nodejs|node)\s/.test(l));
30
+ if (line) pins.push({ source: '.tool-versions', want: line.split(/\s+/)[1] });
31
+ const pkg = readJSON(path.join(dir, 'package.json'), null);
32
+ if (isPlainObject(pkg)) {
33
+ if (typeof pkg.engines?.node === 'string' && pkg.engines.node.trim()) pins.push({ source: 'package.json engines.node', want: pkg.engines.node.trim() });
34
+ if (typeof pkg.volta?.node === 'string' && pkg.volta.node.trim()) pins.push({ source: 'package.json volta.node', want: pkg.volta.node.trim() });
35
+ }
36
+ return pins;
37
+ }
38
+
39
+ const parts = (v) => {
40
+ const m = /^v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?$/i.exec(String(v).trim());
41
+ if (!m) return null;
42
+ const n = (x) => (x === undefined || /^[x*]$/i.test(x) ? null : Number(x));
43
+ return [Number(m[1]), n(m[2]), n(m[3])];
44
+ };
45
+ const cmp = (a, b) => { for (let i = 0; i < 3; i++) { const d = (a[i] ?? 0) - (b[i] ?? 0); if (d) return d; } return 0; };
46
+
47
+ // Does `version` (x.y.z) meet `spec`? true / false, or null when the spec is not one yad reads (a name such
48
+ // as `lts/*`, a URL): never guessed. Reads exact and partial versions (`24`, `22.8`), `x` and `*`, the
49
+ // operators >= > <= < = (with or without a space before the version), ^ and ~, `a - b`, spaces (all must
50
+ // hold) and `||` (any may). A pre-release (`24.0.0-rc.1`), in the spec or the running Node, is not read.
51
+ export function satisfies(version, spec) {
52
+ const have = parts(version);
53
+ if (!have) return null;
54
+ const alts = String(spec).split('||').map((s) => s.trim());
55
+ let unknown = false;
56
+ for (const alt of alts) {
57
+ if (alt === '' || alt === '*' || /^x$/i.test(alt)) return true;
58
+ const hyphen = /^(\S+)\s+-\s+(\S+)$/.exec(alt);
59
+ // `>= 22` is `>=22`: an operator is joined to its version before the spaces split the terms.
60
+ const joined = alt.replace(/(>=|<=|>|<|=|\^|~)\s+/g, '$1');
61
+ const terms = hyphen ? [`>=${hyphen[1]}`, `<=${hyphen[2]}`] : joined.split(/\s+/).filter(Boolean);
62
+ let all = true;
63
+ for (const term of terms) {
64
+ const m = /^(>=|<=|>|<|=|\^|~)?\s*(.+)$/.exec(term);
65
+ const want = m && parts(m[2]);
66
+ if (!want) { unknown = true; all = false; break; }
67
+ const op = m[1] || '';
68
+ const c = cmp(have, want);
69
+ const lead = want.findIndex((x) => x === null);
70
+ let ok;
71
+ if (op === '>=') ok = c >= 0;
72
+ // `>24` is above every 24.x.y (npm reads it as >=25.0.0): only the parts it names are compared.
73
+ else if (op === '>') ok = lead >= 0 ? cmp(have.slice(0, lead), want.slice(0, lead)) > 0 : c > 0;
74
+ else if (op === '<=') ok = c <= 0 || (lead >= 0 && have.slice(0, lead).every((x, i) => x === want[i]));
75
+ else if (op === '<') ok = c < 0;
76
+ else if (op === '^') {
77
+ ok = c >= 0 && (want[0] > 0 ? have[0] === want[0]
78
+ : want[1] === null || want[1] > 0 ? have[0] === 0 && (want[1] === null || have[1] === want[1])
79
+ : have[0] === 0 && have[1] === 0 && (want[2] === null || have[2] === want[2]));
80
+ }
81
+ else if (op === '~') ok = c >= 0 && have[0] === want[0] && (want[1] === null || have[1] === want[1]);
82
+ // A bare or `=` version: the parts it names must match (`24` is any 24.x.y).
83
+ else ok = want.every((x, i) => x === null || x === have[i]);
84
+ if (!ok) { all = false; break; }
85
+ }
86
+ if (all) return true;
87
+ }
88
+ return unknown ? null : false;
89
+ }
90
+
91
+ // What the person runs to fix a Node mismatch: nvm's commands when nvm is here, else plain words.
92
+ export function nodeFix(rawWant, { env = process.env, home = os.homedir() } = {}) {
93
+ const want = forTerminal(rawWant);
94
+ const exact = /^v?\d+(\.\d+){0,2}$/.test(want) ? want.replace(/^v/, '') : null;
95
+ const nvm = !!env.NVM_DIR || fs.existsSync(path.join(home, '.nvm'));
96
+ if (nvm && exact) return `nvm install ${exact} && nvm use ${exact} (and \`nvm alias default ${exact}\` to make it the default in new shells)`;
97
+ if (nvm) return `nvm install <a version that meets ${want}> && nvm use <that version>`;
98
+ return `install Node ${want} (or switch to it with your version manager)`;
99
+ }
100
+
101
+ // Why a folder needs Docker: the files and lines that ask for it ([] when none). Script names come from the
102
+ // repo, so they are cleaned for the terminal here.
103
+ export function dockerReasons(dir) {
104
+ const why = [];
105
+ let names = [];
106
+ try { names = fs.readdirSync(dir); } catch { /* not readable: no reasons */ }
107
+ for (const f of names) {
108
+ if (/^(docker-)?compose\.ya?ml$/i.test(f) || /^dockerfile(\..+)?$/i.test(f) || /\.dockerfile$/i.test(f)) why.push(forTerminal(f));
109
+ }
110
+ const pkg = readJSON(path.join(dir, 'package.json'), null);
111
+ const scripts = isPlainObject(pkg?.scripts) ? pkg.scripts : {};
112
+ // docker run as a command: at the start, after `&&` `||` `;` `|` `(`, after `npx`, or by its path —
113
+ // not the word inside another command (`--ignore-pattern docker`, `echo docker`).
114
+ const cmd = /(^|[;&|(]\s*|\bnpx\s+(-y\s+)?)(\S*\/)?docker(-compose)?(\s|$)/;
115
+ const named = Object.entries(scripts).filter(([, v]) => typeof v === 'string' && cmd.test(v)).map(([k]) => forTerminal(k));
116
+ if (named.length) why.push(`package.json scripts: ${named.join(', ')}`);
117
+ const pre = read(path.join(dir, '.pre-commit-config.yaml'));
118
+ if (pre && /^\s*language:\s*["']?(docker|docker_image)["']?\s*(#.*)?$/m.test(pre)) why.push('.pre-commit-config.yaml (a docker hook)');
119
+ return why;
120
+ }
121
+
122
+ // Is Docker here and running? 'running' | 'stopped' (the CLI is here, the daemon does not answer) |
123
+ // 'missing' (no docker command).
124
+ export function dockerState({ runner = run } = {}) {
125
+ if (!runner(process.platform === 'win32' ? 'where' : 'which', ['docker']).ok) return 'missing';
126
+ return runner('docker', ['info', '--format', '{{.ServerVersion}}'], { timeout: 8000 }).ok ? 'running' : 'stopped';
127
+ }
128
+
129
+ // The glab config files that exist on this machine, in the places glab looks. GLAB_CONFIG_DIR, or else
130
+ // XDG_CONFIG_HOME, names the one place glab reads (it then warns about no other); without them glab looks
131
+ // in ~/.config and the system's own folder, and warns when both hold a config.
132
+ export function glabConfigs({ env = process.env, home = os.homedir(), platform = process.platform } = {}) {
133
+ const places = env.GLAB_CONFIG_DIR ? [path.join(env.GLAB_CONFIG_DIR, 'config.yml')]
134
+ : env.XDG_CONFIG_HOME ? [path.join(env.XDG_CONFIG_HOME, 'glab-cli', 'config.yml')]
135
+ : [
136
+ path.join(home, '.config', 'glab-cli', 'config.yml'),
137
+ platform === 'darwin' && path.join(home, 'Library', 'Application Support', 'glab-cli', 'config.yml'),
138
+ platform === 'win32' && env.APPDATA && path.join(env.APPDATA, 'glab-cli', 'config.yml'),
139
+ ].filter(Boolean);
140
+ return [...new Set(places)].filter((f) => fs.existsSync(f));
141
+ }
package/cli/openpr.mjs CHANGED
@@ -7,7 +7,7 @@ import fs from 'node:fs';
7
7
  import { c, log, ok, info, warn, hand, fail, run, exists, readJSON } from './lib.mjs';
8
8
  import { PROJECT_FILES , productConfigPath, settingsEditHint } from './manifest.mjs';
9
9
  import {
10
- detectPlatform, createPr, platformLogin, resolveBaseBranch, prNumberFromUrl,
10
+ detectPlatform, createPr, platformLogin, resolveBaseBranch, prNumberFromUrl, editPrBody,
11
11
  } from './platform.mjs';
12
12
  import { taskFromBranch } from './commit.mjs';
13
13
  import { parseReviewBranch, artifactFromBase, gateCapFor, capLimit, peopleWord, gateRuleSum, gateRuleEnforced, legacyLogins } from './epic-state.mjs';
@@ -22,6 +22,7 @@ import { autoOpenCheck, recordAutoOpen, branchTasks, rangeTasks, groupWarnings }
22
22
  import { productDriftError } from './epic-state.mjs';
23
23
  import { err } from './errors.mjs';
24
24
  import { recordActor } from './skip.mjs';
25
+ import { previewLine, previewPattern, fillPattern, needs } from './preview.mjs';
25
26
 
26
27
  // Resolve the target code repo: --repo <name> from the registry, else --dir, else cwd. `product` (E80) is
27
28
  // the Product found from a code repo beside it: the registry is read there, and a repo run without
@@ -81,7 +82,7 @@ function codeTaskTemplate(platform) {
81
82
  }
82
83
  }
83
84
 
84
- export function templateBody(repoRoot, platform, { task, summary, risk, contract, domains, stage }) {
85
+ export function templateBody(repoRoot, platform, { task, summary, risk, contract, domains, stage, preview }) {
85
86
  // product-tooling: the Product's own template is artifact-review — use the bundled code-task template so the
86
87
  // body matches the shape the Product `pr-template` gate demands for a non-review head.
87
88
  let base;
@@ -100,7 +101,9 @@ export function templateBody(repoRoot, platform, { task, summary, risk, contract
100
101
  // Fill the obvious fields; leave the rest of the committed template intact for the author.
101
102
  // Function replacers (not string replacements) so a `$` in interpolated free text — a commit-derived
102
103
  // summary or a repo name — is inserted verbatim, never read as a `$1`/`$&` replacement token.
103
- let out = base
104
+ // The Preview line first, while the template is the only text: the summary, inserted below, is
105
+ // free text from the commit and may hold a `## Testing` of its own.
106
+ let out = (preview != null ? withPreviewLine(base, preview) : base)
104
107
  .replace(/EP-<slug>-S0N-T0N/g, () => task || 'EP-<slug>-S0N-T0N')
105
108
  .replace(/specs\/EP-<slug>-S0N\//g, () => `specs/${story || 'EP-<slug>-S0N'}/`)
106
109
  .replace(/(\*\*Risk level:\*\*)\s*\w+/i, (_m, g1) => `${g1} ${risk}`)
@@ -114,6 +117,24 @@ export function templateBody(repoRoot, platform, { task, summary, risk, contract
114
117
  return out;
115
118
  }
116
119
 
120
+ // The PR/MR description with its Preview line set (#359), looked for only in the `## Testing` section
121
+ // (the Summary, taken from the commit, may hold a line of its own that reads the same): the template's
122
+ // `**Preview:**` line there, else a line added at the top of that section (a template committed before
123
+ // #359). A template with no `## Testing` is the team's own shape and is left as it is.
124
+ export function withPreviewLine(body, preview) {
125
+ const eol = body.includes('\r\n') ? '\r\n' : '\n';
126
+ const head = /^## Testing[ \t]*\r?\n/m.exec(body);
127
+ if (!head) return body;
128
+ const start = head.index + head[0].length;
129
+ const next = body.slice(start).search(/^## /m);
130
+ const end = next < 0 ? body.length : start + next;
131
+ const section = body.slice(start, end);
132
+ const line = /^([-*][ \t]+)?(\*\*Preview:\*\*)[^\r\n]*/m;
133
+ if (line.test(section)) return body.slice(0, start) + section.replace(line, (_m, b, g) => `${b || ''}${g} ${preview}`) + body.slice(end);
134
+ const lead = /^(?:<!--[\s\S]*?-->[ \t]*\r?\n)?/.exec(section)[0];
135
+ return `${body.slice(0, start)}${lead}- **Preview:** ${preview}${eol}${section.slice(lead.length)}${body.slice(end)}`;
136
+ }
137
+
117
138
  // E66 — how many approvers this PR asks for, printed once it is open: the body's own level and contract
118
139
  // answer (what `--risk` / `--contract-change` put there), and the risk map on the BASE branch — a change
119
140
  // touching a `high` directory adds the high step. The largest step wins, so the map can raise what the
@@ -389,9 +410,13 @@ export async function runOpenPr(root, opts = {}) {
389
410
  .join('\n')
390
411
  .trim();
391
412
  const summary = [subjectText, bodyText].filter(Boolean).join('\n\n') || undefined;
392
- const body = templateBody(repoRoot, platform, {
393
- task: bodyTask, summary, risk: opts.risk || 'low', contract: !!opts.contractChange, domains: meta?.name, stage,
394
- });
413
+ // The Preview line (#359), on a code task only: the repo's pattern filled now, or a note. A pattern
414
+ // that needs the PR number is filled once the PR exists (below).
415
+ const pp = stage === 'code-repo' ? previewPattern(meta) : {};
416
+ const preview = stage === 'code-repo' ? previewLine(meta, { branch }) : undefined;
417
+ if (pp.problems) warn(`this repo's preview_url pattern cannot be used: it ${pp.problems.join('; ')} — set it again with \`yad repo preview <repo> <pattern>\``);
418
+ const bodyOpts = { task: bodyTask, summary, risk: opts.risk || 'low', contract: !!opts.contractChange, domains: meta?.name, stage };
419
+ const body = templateBody(repoRoot, platform, { ...bodyOpts, preview });
395
420
 
396
421
  // Assignee = the committer: `@me` on GitHub (buildPrArgs sends it when no assignee is named, and `gh`
397
422
  // resolves it on the repo's own host), the login `glab` reports on GitLab. No reviewers are requested (E62): the roster that named them is gone. The team requests them
@@ -405,6 +430,21 @@ export async function runOpenPr(root, opts = {}) {
405
430
  const r = creator(platform, { title, body, base: baseBranch, head: branch, assignees, cwd: repoRoot });
406
431
  if (!r.ok) { fail(`could not open PR/MR — ${r.reason || 'unknown'}`); process.exitCode = 1; return; }
407
432
  ok(`opened ${r.url}`);
433
+ // A {pr} pattern can only be filled now the PR has a number: the description is edited once. The PR
434
+ // is open whatever happens here — a failed edit is said, never a failure.
435
+ const pat = pp.pattern || null;
436
+ if (pat && needs(pat, 'pr')) {
437
+ const n = Number(prNumberFromUrl(r.url)) || null;
438
+ const url = n ? fillPattern(pat, { pr: n, branch, repo: meta?.name }) : null;
439
+ // The same body, built again with the address: only the Preview line can differ.
440
+ const filled = url ? templateBody(repoRoot, platform, { ...bodyOpts, preview: `<${url}>` }) : null;
441
+ if (url && filled === body) info(`this repo's PR/MR template has no ## Testing section, so the preview address was not written: ${url}`);
442
+ else if (url) {
443
+ const edit = (opts.editBody || editPrBody)(platform, n, filled, { cwd: repoRoot });
444
+ if (edit?.ok) ok(`preview ${url}`);
445
+ else warn(`the PR/MR is open, but its Preview line could not be filled (${String(edit?.reason || 'unknown').split('\n')[0]}) — the preview should be at ${url}`);
446
+ } else warn('the PR/MR is open, but its number could not be read from the URL, so the Preview line was left unfilled (`yad review context --pr <n>` gives the address)');
447
+ }
408
448
  if (auto) {
409
449
  // The PR is open whatever happens next: a record that cannot be written is said, never a failure.
410
450
  try {