rungate 0.8.26 → 0.8.28

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.
@@ -0,0 +1,955 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * Where the current plan stands, in one place a person can read without an
4
+ * agent — #2097.
5
+ *
6
+ * One renderer, two outputs:
7
+ * bun scripts/status-view.ts terminal text (what `/board` prints)
8
+ * bun scripts/status-view.ts --markdown > <f> the pinned issue's body
9
+ * bun scripts/status-view.ts --publish <f> --repo owner/name
10
+ * write <f> into the pinned issue
11
+ *
12
+ * `.github/workflows/status-issue.yml` runs the second and third on every
13
+ * change. Reading and writing are separate invocations so the board token,
14
+ * which the read needs, is never held by the step that writes (ADR-013).
15
+ *
16
+ * ## It follows the plan, not a name
17
+ *
18
+ * The goal and stages come from `project-state.json`. The phases are the
19
+ * milestones in the configured focus family (`board.milestonePrefix`, the
20
+ * setting Ready already orders by), and their one-line meanings come from the
21
+ * spec configured as `board.engineSpec`. Nothing here names a family or a
22
+ * spec. When the plan moves to other work, the config moves and so does the
23
+ * view.
24
+ *
25
+ * ## Unread is never empty
26
+ *
27
+ * Every section is a `Reading`. A source that could not be read renders as
28
+ * UNMEASURED with its reason, never as an empty list: an empty "In progress"
29
+ * is byte-identical to a project with nothing in progress
30
+ * (`.claude/rules/config-access.md`, Silent Default Substitution).
31
+ *
32
+ * Stage verdicts are each item's `done` flag. They are not re-run here:
33
+ * `test/stage-ladder.test.ts` runs every done item's proof command in CI on
34
+ * every pull request, so a `done` that stopped being true is already red
35
+ * there. Re-running roughly forty commands on every issue event would add
36
+ * minutes and decide nothing new.
37
+ */
38
+ import { spawnSync } from "child_process";
39
+ import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
40
+ import { tmpdir } from "os";
41
+ import { join } from "path";
42
+ import { readBoardConfig, readBoardInputs, readQueueLabel } from "../lib/config-readers";
43
+ import { nextCursor } from "../lib/graphql-cursor";
44
+ import { readMilestoneTitle } from "../lib/milestone-title";
45
+ import { parseCriteria } from "../lib/spec-evidence";
46
+ import { PHASE_VALUE, parsePlacementRows } from "../lib/spec-placement";
47
+ import { ladderReport } from "../lib/work-status";
48
+
49
+ /** The marker that identifies the pinned issue this script owns. */
50
+ export const STATUS_MARKER = "<!-- rungate:status-view -->";
51
+ /** Longest list a section prints before it links to the rest. */
52
+ export const LIST_LIMIT = 10;
53
+ /** The label a session puts on an issue it parks for a person to decide (#2138). */
54
+ export const NEEDS_DECISION = "needs-decision";
55
+ /** Every refusal exits through this. */
56
+ export const REFUSAL_EXIT = 1;
57
+ /** Where "How this view is made" points: the published package, which every repository using it can open. */
58
+ export const PACKAGE_PAGE = "https://www.npmjs.com/package/rungate";
59
+ /**
60
+ * This package's own CLI. Not `<root>/bin/rungate.ts`: in a consumer the
61
+ * package is in node_modules and the root has no bin/ (#2330).
62
+ */
63
+ const CLI_ENTRY = join(import.meta.dir, "..", "bin", "rungate.ts");
64
+
65
+ export type Reading<T> = { kind: "READ"; value: T } | { kind: "UNMEASURED"; why: string };
66
+
67
+ export interface StageLine {
68
+ id: string;
69
+ name: string;
70
+ meaning: string;
71
+ state: "done" | "next" | "later";
72
+ open: string[];
73
+ total: number;
74
+ }
75
+
76
+ export interface PhaseLine {
77
+ number: number;
78
+ title: string;
79
+ meaning: string | null;
80
+ open: number;
81
+ closed: number;
82
+ url: string;
83
+ state: "done" | "current" | "later" | "empty";
84
+ /**
85
+ * For a phase with no issues only: how many criteria the spec's Phase
86
+ * placement table puts in it, and how many of those are unticked (#2147).
87
+ * Absent when the phase has issues, or the spec places nothing in it.
88
+ */
89
+ criteria?: { placed: number; unticked: number };
90
+ }
91
+
92
+ /** A family other than the focus family: its totals, and every phase in it (#2330). */
93
+ export interface FamilyLine {
94
+ family: string;
95
+ open: number;
96
+ closed: number;
97
+ phases: PhaseLine[];
98
+ }
99
+
100
+ /** One open issue in a phase, with what still blocks it and who has it (#2330). */
101
+ export interface PhaseIssue {
102
+ number: number;
103
+ title: string;
104
+ url: string;
105
+ milestone: string;
106
+ assignees: string[];
107
+ /** Open blockers only: a closed blocker no longer holds anything back. */
108
+ blockers: number[];
109
+ /** The blocked-by list was longer than one page, so `blockers` may be short. */
110
+ moreBlockers: boolean;
111
+ }
112
+
113
+ export interface WorkLine {
114
+ number: number;
115
+ title: string;
116
+ url: string;
117
+ note?: string;
118
+ }
119
+
120
+ export interface HealthLine {
121
+ name: string;
122
+ status: string;
123
+ measured: number;
124
+ target: number;
125
+ }
126
+
127
+ export interface StatusView {
128
+ repo: string;
129
+ generatedAt: string;
130
+ commit: string | null;
131
+ family: string | null;
132
+ goal: Reading<string>;
133
+ stages: Reading<StageLine[]>;
134
+ phases: Reading<PhaseLine[]>;
135
+ otherFamilies: Reading<FamilyLine[]>;
136
+ /** Every open issue that sits in a milestone, for listing under its phase (#2330). */
137
+ phaseIssues: Reading<PhaseIssue[]>;
138
+ inProgress: Reading<WorkLine[]>;
139
+ ready: Reading<WorkLine[]>;
140
+ decisions: Reading<WorkLine[]>;
141
+ unphased: Reading<WorkLine[]>;
142
+ /**
143
+ * What `unphased` holds: queued issues with no milestone when a queue label
144
+ * is configured, or every open issue with no milestone when none is (#2330).
145
+ */
146
+ unphasedScope: "queued" | "all";
147
+ health: Reading<HealthLine[]>;
148
+ /** A link whose address could not be read carries `url: null` and why, rendered as UNMEASURED. */
149
+ links: { label: string; url: string | null; why?: string }[];
150
+ }
151
+
152
+ export interface Milestone {
153
+ title: string;
154
+ open: number;
155
+ closed: number;
156
+ url: string;
157
+ }
158
+
159
+ const read = <T>(value: T): Reading<T> => ({ kind: "READ", value });
160
+ const unmeasured = <T>(why: string): Reading<T> => ({ kind: "UNMEASURED", why });
161
+
162
+ /**
163
+ * The goal and the finish line, from the plan's own text.
164
+ *
165
+ * Well-formedness and the next stage are `ladderReport`'s, the one reader
166
+ * `work-status` also uses, so the two reports cannot disagree about which
167
+ * stage is next.
168
+ */
169
+ export function planLines(source: string | null, where: string): { goal: Reading<string>; stages: Reading<StageLine[]> } {
170
+ const report = ladderReport(source, where);
171
+ if (report.kind === "UNMEASURED") return { goal: unmeasured(report.why), stages: unmeasured(report.why) };
172
+ // `ladderViolations` (inside `ladderReport`) has already refused a plan
173
+ // without a goal statement, so this reads it rather than re-checking it.
174
+ const doc = JSON.parse(source as string) as {
175
+ goal: { statement: string };
176
+ stages: { id: string; name: string; goal?: unknown; items: { id: string; done: boolean }[] }[];
177
+ };
178
+ const goal = read(doc.goal.statement.trim());
179
+ const stages = doc.stages.map(s => {
180
+ const open = s.items.filter(i => !i.done).map(i => i.id);
181
+ const state: StageLine["state"] = open.length === 0 ? "done" : s.id === report.next ? "next" : "later";
182
+ return {
183
+ id: s.id,
184
+ name: s.name,
185
+ meaning: typeof s.goal === "string" ? s.goal : "",
186
+ state,
187
+ open,
188
+ total: s.items.length,
189
+ };
190
+ });
191
+ return { goal, stages: read(stages) };
192
+ }
193
+
194
+ /**
195
+ * The first paragraph of a spec's `### Phase N` section, kept to whole
196
+ * sentences within `limit` characters (at least one sentence).
197
+ *
198
+ * Read, never written here. Where that paragraph is jargon, rewriting it is
199
+ * a spec edit, so the fix lands in one place and every reader gets it.
200
+ */
201
+ export function phaseBlurb(specText: string, phase: number, limit = 280): string | null {
202
+ const lines = specText.split("\n");
203
+ const at = lines.findIndex(l => new RegExp(`^###\\s+Phase\\s+${phase}\\b`).test(l));
204
+ if (at === -1) return null;
205
+ const para: string[] = [];
206
+ for (const line of lines.slice(at + 1)) {
207
+ if (/^#{1,6}\s/.test(line)) break;
208
+ if (line.trim() === "") {
209
+ if (para.length > 0) break;
210
+ continue;
211
+ }
212
+ para.push(line.trim());
213
+ }
214
+ if (para.length === 0) return null;
215
+ // A sentence ends at punctuation FOLLOWED BY WHITESPACE, so the dot in
216
+ // "AGENTS.md" stays inside its sentence.
217
+ const sentences = para.join(" ").split(/(?<=[.!?])\s+/);
218
+ let out = "";
219
+ for (const s of sentences) {
220
+ const next = out === "" ? s : `${out} ${s}`;
221
+ if (out !== "" && next.length > limit) break;
222
+ out = next;
223
+ }
224
+ return out.trim();
225
+ }
226
+
227
+ /**
228
+ * Per phase number, the criteria the spec's Phase placement table puts there
229
+ * and how many are unticked. A placed id the spec never states counts as
230
+ * unticked: a criterion nobody can find has not been shown true.
231
+ */
232
+ export function placedCriteria(specText: string): Map<number, { placed: number; unticked: number }> {
233
+ const ticked = new Map(parseCriteria(specText).map(c => [c.id, c.ticked]));
234
+ const out = new Map<number, { placed: number; unticked: number }>();
235
+ for (const row of parsePlacementRows(specText)) {
236
+ const m = row.placement.match(PHASE_VALUE);
237
+ if (m === null || row.ids.length === 0) continue;
238
+ // Summed, not set: a phase whose criteria sit in two rows is judged on both.
239
+ const prev = out.get(Number(m[1])) ?? { placed: 0, unticked: 0 };
240
+ out.set(Number(m[1]), {
241
+ placed: prev.placed + row.ids.length,
242
+ unticked: prev.unticked + row.ids.filter(id => ticked.get(id) !== true).length,
243
+ });
244
+ }
245
+ return out;
246
+ }
247
+
248
+ /**
249
+ * The focus family's phases, in phase order, each with its meaning and progress.
250
+ *
251
+ * A phase with issues is judged by its issues. A phase with none is done only
252
+ * when the spec places criteria in it and every one is ticked (#2147) — work
253
+ * that landed before criteria became issues leaves a milestone empty and the
254
+ * phase finished. Anything less stays "empty", never done.
255
+ */
256
+ export function phaseLines(milestones: readonly Milestone[], family: string, specText: string | null): PhaseLine[] {
257
+ const mine = milestones
258
+ .map(m => ({ m, r: readMilestoneTitle(m.title) }))
259
+ .filter(x => x.r !== null && x.r.family === family)
260
+ .map(x => ({ m: x.m, number: x.r!.phase }))
261
+ .sort((a, b) => a.number - b.number);
262
+ const current = mine.find(x => x.m.open > 0)?.number;
263
+ const placed = specText === null ? new Map<number, { placed: number; unticked: number }>() : placedCriteria(specText);
264
+ return mine.map(({ m, number }) => {
265
+ const criteria = m.open + m.closed === 0 ? placed.get(number) : undefined;
266
+ const state: PhaseLine["state"] =
267
+ m.open + m.closed === 0
268
+ ? criteria !== undefined && criteria.unticked === 0
269
+ ? "done"
270
+ : "empty"
271
+ : m.open === 0
272
+ ? "done"
273
+ : number === current
274
+ ? "current"
275
+ : "later";
276
+ return {
277
+ number,
278
+ title: m.title,
279
+ meaning: specText === null ? null : phaseBlurb(specText, number),
280
+ open: m.open,
281
+ closed: m.closed,
282
+ url: m.url,
283
+ state,
284
+ ...(criteria === undefined ? {} : { criteria }),
285
+ };
286
+ });
287
+ }
288
+
289
+ /**
290
+ * Every family other than the focus family, with its phases (#2330).
291
+ *
292
+ * A consumer's own work is usually NOT the focus family: the focus is the
293
+ * family Ready orders by, and on 2026-11-17 the one consumer had it set to a
294
+ * family whose phases were all closed. Shown as a count, its open family read
295
+ * `3 phase(s), 0 of 22 done` and named none of the 22 issues. The renderer
296
+ * collapses a family only when nothing in it is open.
297
+ */
298
+ export function otherFamilyLines(milestones: readonly Milestone[], family: string): FamilyLine[] {
299
+ const names = new Set<string>();
300
+ for (const m of milestones) {
301
+ const f = readMilestoneTitle(m.title)?.family ?? null;
302
+ if (f !== null && f !== "" && f !== family) names.add(f);
303
+ }
304
+ return [...names]
305
+ .sort((a, b) => a.localeCompare(b))
306
+ .map(f => {
307
+ const phases = phaseLines(milestones, f, null);
308
+ return {
309
+ family: f,
310
+ open: phases.reduce((n, p) => n + p.open, 0),
311
+ closed: phases.reduce((n, p) => n + p.closed, 0),
312
+ phases,
313
+ };
314
+ });
315
+ }
316
+
317
+ /**
318
+ * Repository text made safe to place in the issue body.
319
+ *
320
+ * Titles are written by anyone who can open an issue. Unescaped, an
321
+ * `@name` would notify that person on every rewrite, and brackets or angle
322
+ * brackets would let a title inject a link or markup into the pinned view.
323
+ *
324
+ * **Criterion ids are broken with a non-breaking hyphen.** The pinned view is
325
+ * an open issue, and every reader that asks "does an open issue name SC-N?"
326
+ * reads its body. A title or spec sentence quoting `SC-2752` would make this
327
+ * issue cover that criterion for as long as it stays open, which is forever,
328
+ * so a real gap would never show again. `SC‑2752` (U+2011) reads the same and
329
+ * matches no id pattern.
330
+ */
331
+ export function plain(s: string): string {
332
+ return s
333
+ .replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
334
+ .replace(/&/g, "&amp;")
335
+ .replace(/</g, "&lt;")
336
+ .replace(/>/g, "&gt;")
337
+ .replace(/([[\]`*_|\\])/g, "\\$1")
338
+ .replace(/@/g, "@&#8203;")
339
+ .replace(/\b([A-Z]{2,5})-([A-Z]?\d+)\b/g, "$1‑$2");
340
+ }
341
+
342
+ /** Terminal text: control characters only, so an escape code cannot redraw the screen. */
343
+ function term(s: string): string {
344
+ return s.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ");
345
+ }
346
+
347
+ /** The note after an open issue in a phase: its open blockers, then who has it. */
348
+ function issueNote(i: PhaseIssue): string {
349
+ const notes: string[] = [];
350
+ if (i.blockers.length > 0) notes.push(`blocked by ${i.blockers.map(n => `#${n}`).join(", ")}${i.moreBlockers ? " and more" : ""}`);
351
+ else if (i.moreBlockers) notes.push("blocked by more than one page of issues");
352
+ if (i.assignees.length > 0) notes.push(i.assignees.join(", "));
353
+ return notes.join("; ");
354
+ }
355
+
356
+ const STAGE_MARK = { done: "✓", next: "●", later: "○" } as const;
357
+ const PHASE_MARK = { done: "✓", current: "●", later: "○", empty: "–" } as const;
358
+
359
+ type Fmt = {
360
+ text: (s: string) => string;
361
+ heading: (s: string) => string;
362
+ link: (label: string, url: string) => string;
363
+ item: (s: string) => string;
364
+ /** A list item nested `depth` levels under an item. */
365
+ sub: (depth: number, s: string) => string;
366
+ };
367
+
368
+ const MARKDOWN: Fmt = {
369
+ text: plain,
370
+ heading: s => `### ${s}`,
371
+ link: (label, url) => `[${plain(label)}](${url})`,
372
+ item: s => `- ${s}`,
373
+ sub: (depth, s) => `${" ".repeat(depth)}- ${s}`,
374
+ };
375
+
376
+ const TEXT: Fmt = {
377
+ text: term,
378
+ heading: s => `\n${s}\n${"─".repeat(s.length)}`,
379
+ link: (label, url) => `${term(label)} (${url})`,
380
+ item: s => ` ${s}`,
381
+ sub: (depth, s) => `${" ".repeat(depth)} ${s}`,
382
+ };
383
+
384
+ function section<T>(f: Fmt, title: string, r: Reading<T>, body: (v: T) => string[]): string[] {
385
+ const out = [f.heading(title)];
386
+ if (r.kind === "UNMEASURED") out.push(f.item(`UNMEASURED — ${f.text(r.why)}`));
387
+ else out.push(...body(r.value));
388
+ return out;
389
+ }
390
+
391
+ function workList(f: Fmt, lines: WorkLine[], empty: string, more?: string): string[] {
392
+ if (lines.length === 0) return [f.item(empty)];
393
+ const shown = lines.slice(0, LIST_LIMIT).map(w =>
394
+ f.item(`${f.link(`#${w.number}`, w.url)} ${f.text(w.title)}${w.note ? ` — ${f.text(w.note)}` : ""}`),
395
+ );
396
+ if (lines.length > LIST_LIMIT) {
397
+ shown.push(f.item(`… and ${lines.length - LIST_LIMIT} more${more ? ` (${more})` : ""}`));
398
+ }
399
+ return shown;
400
+ }
401
+
402
+ /** A phase's line, its meaning, and the open issues in it, at list depth `depth`. */
403
+ function phaseBlock(f: Fmt, p: PhaseLine, issues: Reading<PhaseIssue[]>, markdown: boolean, depth: number): string[] {
404
+ const total = p.open + p.closed;
405
+ const c = p.criteria;
406
+ const why =
407
+ c === undefined
408
+ ? ""
409
+ : c.unticked === 0
410
+ ? `; its ${c.placed} criteria are ticked`
411
+ : `; ${c.unticked} of its ${c.placed} criteria unticked`;
412
+ const progress = total === 0 ? `no issues${why}` : `${p.closed} of ${total} done`;
413
+ const line = `${PHASE_MARK[p.state]} ${f.link(p.title, p.url)} — ${progress}`;
414
+ const out = [depth === 0 ? f.item(line) : f.sub(depth, line)];
415
+ if (p.meaning) out.push(`${markdown ? " ".repeat(depth + 1) : " ".repeat(depth) + " "}${f.text(p.meaning)}`);
416
+ if (issues.kind === "READ" && p.open > 0) {
417
+ const mine = issues.value.filter(i => i.milestone === p.title);
418
+ for (const i of mine.slice(0, LIST_LIMIT)) {
419
+ const note = issueNote(i);
420
+ out.push(f.sub(depth + 1, `${f.link(`#${i.number}`, i.url)} ${f.text(i.title)}${note ? ` — ${f.text(note)}` : ""}`));
421
+ }
422
+ if (mine.length > LIST_LIMIT) out.push(f.sub(depth + 1, `… and ${mine.length - LIST_LIMIT} more`));
423
+ // A milestone's open count includes pull requests, and the issue read
424
+ // returns issues only, so the difference is said rather than left as a
425
+ // phase that reads open with too little under it (review of #2334).
426
+ const prs = p.open - mine.length;
427
+ if (prs > 0) out.push(f.sub(depth + 1, `and ${prs} open pull request(s), which the milestone counts`));
428
+ }
429
+ return out;
430
+ }
431
+
432
+ /** One line when the open issues could not be read, so a phase without them is not read as a phase without issues. */
433
+ function issuesUnread(f: Fmt, issues: Reading<PhaseIssue[]>): string[] {
434
+ return issues.kind === "UNMEASURED" ? [f.item(`open issues per phase: UNMEASURED — ${f.text(issues.why)}`)] : [];
435
+ }
436
+
437
+ function render(v: StatusView, f: Fmt, markdown: boolean): string {
438
+ const out: string[] = [];
439
+ if (markdown) {
440
+ out.push(STATUS_MARKER);
441
+ out.push(
442
+ `> Rewritten from live readings by \`scripts/status-view.ts\` on every change. Do not edit by hand; ` +
443
+ `edits are overwritten. Read at ${v.generatedAt}${v.commit ? ` from \`${v.commit.slice(0, 8)}\`` : ""}.`,
444
+ );
445
+ } else {
446
+ out.push(`Where we are — read at ${v.generatedAt}${v.commit ? ` from ${v.commit.slice(0, 8)}` : ""}`);
447
+ }
448
+
449
+ out.push(...section(f, "The goal", v.goal, g => [f.text(g)]));
450
+
451
+ out.push(
452
+ ...section(f, "The finish line", v.stages, stages =>
453
+ stages.map(s => {
454
+ const left = s.open.length === 0 ? "" : ` — ${s.open.length} of ${s.total} left: ${f.text(s.open.join(", "))}`;
455
+ const id = markdown ? `**${f.text(s.id)}**` : s.id;
456
+ return f.item(`${STAGE_MARK[s.state]} ${id} ${f.text(s.name)}: ${f.text(s.meaning)}${left}`);
457
+ }),
458
+ ),
459
+ );
460
+
461
+ const phaseTitle = v.family === null ? "Phases" : `Phases (${v.family})`;
462
+ out.push(
463
+ ...section(f, phaseTitle, v.phases, phases =>
464
+ phases.length === 0
465
+ ? [f.item(`no milestone is in the ${f.text(v.family ?? "")} family`)]
466
+ : [...issuesUnread(f, v.phaseIssues), ...phases.flatMap(p => phaseBlock(f, p, v.phaseIssues, markdown, 0))],
467
+ ),
468
+ );
469
+ out.push(
470
+ ...section(f, "Other work", v.otherFamilies, fams =>
471
+ fams.length === 0
472
+ ? [f.item("no other milestone family")]
473
+ : [
474
+ ...(fams.some(x => x.open > 0) ? issuesUnread(f, v.phaseIssues) : []),
475
+ ...fams.flatMap(x =>
476
+ x.open === 0 && x.closed === 0
477
+ ? // No issue ever sat in these milestones: not started, which is not done (review of #2334).
478
+ [f.item(`${f.text(x.family)}: not started — no issue in any of its phases yet`)]
479
+ : x.open === 0
480
+ ? [f.item(`✓ ${f.text(x.family)}: done — ${x.phases.length} phase(s), ${x.closed} closed`)]
481
+ : [
482
+ f.item(`${f.text(x.family)}: ${x.closed} of ${x.open + x.closed} done`),
483
+ ...x.phases.flatMap(p => phaseBlock(f, p, v.phaseIssues, markdown, 1)),
484
+ ],
485
+ ),
486
+ ],
487
+ ),
488
+ );
489
+
490
+ out.push(...section(f, "In progress", v.inProgress, w => workList(f, w, "nothing is assigned or in a pull request")));
491
+ out.push(...section(f, "Ready next", v.ready, w => workList(f, w, "nothing is in Ready")));
492
+ out.push(...section(f, "Needs a decision", v.decisions, w => workList(f, w, "nothing is waiting on a decision")));
493
+ out.push(
494
+ ...section(f, "Unphased", v.unphased, w =>
495
+ v.unphasedScope === "queued"
496
+ ? workList(f, w, "every queued issue has a phase", "queued issues with no milestone")
497
+ : w.length === 0
498
+ ? [f.item("every open issue has a milestone")]
499
+ : [f.item(`${w.length} open issue(s) have no milestone; the oldest is ${f.link(`#${w[0].number}`, w[0].url)} ${f.text(w[0].title)}`)],
500
+ ),
501
+ );
502
+ out.push(
503
+ ...section(f, "Health", v.health, h => {
504
+ const met = h.filter(x => x.status === "met").length;
505
+ return [
506
+ f.item(`board checks: ${met} of ${h.length} met`),
507
+ ...h.filter(x => x.status !== "met").map(x => f.item(`${x.status.toUpperCase()} ${x.name}: ${x.measured} of ${x.target}`)),
508
+ ];
509
+ }),
510
+ );
511
+ out.push(
512
+ f.heading("Links"),
513
+ ...v.links.map(l => f.item(l.url === null ? `${f.text(l.label)} — UNMEASURED: ${f.text(l.why ?? "unknown")}` : f.link(l.label, l.url))),
514
+ );
515
+ if (markdown) {
516
+ out.push("", "_This view serves no criterion; it reports on the ones the plan names._");
517
+ }
518
+ return `${out.join("\n")}\n`;
519
+ }
520
+
521
+ /** The pinned issue's body. */
522
+ export function renderMarkdown(v: StatusView): string {
523
+ return render(v, MARKDOWN, true);
524
+ }
525
+
526
+ /** What `/board` prints in a terminal: the same sections, no markup. */
527
+ export function renderText(v: StatusView): string {
528
+ return render(v, TEXT, false);
529
+ }
530
+
531
+ // ---------------------------------------------------------------------------
532
+ // Reading the live sources. Everything below is I/O; everything above is pure.
533
+ // ---------------------------------------------------------------------------
534
+
535
+ type Gh = (args: string[]) => { ok: true; out: string } | { ok: false; why: string };
536
+
537
+ const liveGh: Gh = args => {
538
+ const r = spawnSync("gh", args, { encoding: "utf-8", maxBuffer: 64 * 1024 * 1024 });
539
+ if (r.error) return { ok: false, why: `gh could not start: ${r.error.message}` };
540
+ if (r.status !== 0) return { ok: false, why: `gh ${args[0]} exited ${r.status}: ${(r.stderr ?? "").trim().split("\n")[0]}` };
541
+ return { ok: true, out: r.stdout };
542
+ };
543
+
544
+ function ghJson<T>(gh: Gh, args: string[]): Reading<T> {
545
+ const r = gh(args);
546
+ if (!r.ok) return unmeasured(r.why);
547
+ try {
548
+ return read(JSON.parse(r.out) as T);
549
+ } catch (e) {
550
+ return unmeasured(`gh returned text that is not JSON (${(e as Error).message})`);
551
+ }
552
+ }
553
+
554
+ /** `gh api --paginate` prints one JSON array per page; `--jq '.[]'` makes it one value per line. */
555
+ function ghLines<T>(gh: Gh, path: string, jq: string): Reading<T[]> {
556
+ const r = gh(["api", "--paginate", path, "--jq", jq]);
557
+ if (!r.ok) return unmeasured(r.why);
558
+ try {
559
+ return read(r.out.split("\n").filter(l => l.trim() !== "").map(l => JSON.parse(l) as T));
560
+ } catch (e) {
561
+ return unmeasured(`gh returned a line that is not JSON (${(e as Error).message})`);
562
+ }
563
+ }
564
+
565
+ interface OpenItem {
566
+ number: number;
567
+ title: string;
568
+ url: string;
569
+ pr: boolean;
570
+ assignees: string[];
571
+ labels: string[];
572
+ milestone: string | null;
573
+ }
574
+
575
+ export function gather(
576
+ root: string,
577
+ repo: string,
578
+ gh: Gh = liveGh,
579
+ now = new Date(),
580
+ health: (root: string) => Reading<HealthLine[]> = readHealth,
581
+ ): StatusView {
582
+ const planPath = join(root, "project-state.json");
583
+ const plan = planLines(existsSync(planPath) ? readFileSync(planPath, "utf-8") : null, "project-state.json");
584
+ const { engineSpec, milestonePrefix } = readBoardInputs(root);
585
+ const queueLabel = readQueueLabel(root);
586
+ let specText: string | null = null;
587
+ if (engineSpec !== null && existsSync(join(root, engineSpec))) specText = readFileSync(join(root, engineSpec), "utf-8");
588
+
589
+ const milestones = ghLines<Milestone>(
590
+ gh,
591
+ `repos/${repo}/milestones?state=all&per_page=100`,
592
+ ".[] | {title, open: .open_issues, closed: .closed_issues, url: .html_url}",
593
+ );
594
+ const phases: Reading<PhaseLine[]> =
595
+ milestonePrefix === null
596
+ ? unmeasured("board.milestonePrefix is not set, so there is no focus family to show")
597
+ : milestones.kind === "UNMEASURED"
598
+ ? unmeasured(milestones.why)
599
+ : read(phaseLines(milestones.value, milestonePrefix, specText));
600
+ const otherFamilies: Reading<FamilyLine[]> =
601
+ milestones.kind === "UNMEASURED" ? unmeasured(milestones.why) : read(otherFamilyLines(milestones.value, milestonePrefix ?? ""));
602
+
603
+ const items = ghLines<OpenItem>(
604
+ gh,
605
+ `repos/${repo}/issues?state=open&per_page=100`,
606
+ ".[] | {number, title, url: .html_url, pr: (.pull_request != null), assignees: [.assignees[].login], labels: [.labels[].name], milestone: .milestone.title}",
607
+ );
608
+ const own = (i: OpenItem) => !i.pr;
609
+ const toLine = (i: OpenItem, note?: string): WorkLine => ({ number: i.number, title: i.title, url: i.url, note });
610
+
611
+ const inProgress: Reading<WorkLine[]> =
612
+ items.kind === "UNMEASURED"
613
+ ? unmeasured(items.why)
614
+ : read([
615
+ ...items.value.filter(i => i.pr).map(i => toLine(i, "pull request")),
616
+ ...items.value.filter(i => own(i) && i.assignees.length > 0).map(i => toLine(i, i.assignees.join(", "))),
617
+ ]);
618
+
619
+ // With no queue label there is no work queue to check, but an issue with no
620
+ // milestone is still outside every phase: count them, oldest first (#2330).
621
+ const unphased: Reading<WorkLine[]> =
622
+ items.kind === "UNMEASURED"
623
+ ? unmeasured(items.why)
624
+ : read(
625
+ items.value
626
+ .filter(i => own(i) && i.milestone === null && (queueLabel === null || i.labels.includes(queueLabel)))
627
+ .sort((a, b) => (queueLabel === null ? a.number - b.number : 0))
628
+ .map(i => toLine(i)),
629
+ );
630
+
631
+ const phaseIssues = readPhaseIssues(gh, repo);
632
+
633
+ const decisions = readDecisions(gh, repo, items);
634
+ const ready = readReady(gh, root, items);
635
+ const healthReading = health(root);
636
+ const head = spawnSync("git", ["-C", root, "rev-parse", "HEAD"], { encoding: "utf-8" });
637
+
638
+ const links: StatusView["links"] = [{ label: "Milestones", url: `https://github.com/${repo}/milestones` }];
639
+ // The board's address comes from the API, never built from config: a
640
+ // project owned by an organisation lives under /orgs/, one owned by a user
641
+ // under /users/, and the config does not say which (AI review of #2103).
642
+ const boardConfig = readBoardConfig(root);
643
+ if (boardConfig !== null) {
644
+ const r = ghJson<{ data?: { node?: { url?: string } } }>(gh, [
645
+ "api", "graphql", "-f", "query=query($p:ID!){node(id:$p){... on ProjectV2{url}}}", "-f", `p=${boardConfig.projectId}`,
646
+ ]);
647
+ const url = r.kind === "READ" ? r.value.data?.node?.url : undefined;
648
+ links.push(
649
+ typeof url === "string" && url.startsWith("https://")
650
+ ? { label: "The board", url }
651
+ : { label: "The board", url: null, why: r.kind === "UNMEASURED" ? r.why : "this token cannot see the project" },
652
+ );
653
+ }
654
+ if (queueLabel !== null) {
655
+ links.push({
656
+ label: `Open issues labelled ${queueLabel}`,
657
+ url: `https://github.com/${repo}/issues?q=${encodeURIComponent(`is:open label:${queueLabel}`)}`,
658
+ });
659
+ }
660
+ // The package, not a path in `repo`: in a consumer, scripts/status-view.ts
661
+ // is in node_modules, and a link built from the repository named a file the
662
+ // consumer does not have (#2330).
663
+ links.push({ label: "How this view is made", url: PACKAGE_PAGE });
664
+
665
+ return {
666
+ repo,
667
+ generatedAt: now.toISOString().replace(/\.\d+Z$/, "Z"),
668
+ commit: head.status === 0 ? head.stdout.trim() : null,
669
+ family: milestonePrefix,
670
+ goal: plan.goal,
671
+ stages: plan.stages,
672
+ phases,
673
+ otherFamilies,
674
+ phaseIssues,
675
+ inProgress,
676
+ ready,
677
+ decisions,
678
+ unphased,
679
+ unphasedScope: queueLabel === null ? "all" : "queued",
680
+ health: healthReading,
681
+ links,
682
+ };
683
+ }
684
+
685
+ /**
686
+ * Every open issue in a milestone, with its open blockers and assignees
687
+ * (#2330). One paged GraphQL read rather than a blocked-by call per issue:
688
+ * the workflow runs this on every issue event.
689
+ */
690
+ const PHASE_ISSUES_QUERY =
691
+ "query($owner:String!,$name:String!,$after:String){repository(owner:$owner,name:$name){" +
692
+ "issues(first:100,after:$after,states:OPEN){pageInfo{hasNextPage endCursor} nodes{number title url " +
693
+ "milestone{title} assignees(first:10){nodes{login}} blockedBy(first:50){pageInfo{hasNextPage} nodes{number state}}}}}}";
694
+
695
+ /**
696
+ * Paged by hand, as `readReady` and `lib/live-issues.ts` do, rather than
697
+ * with `gh --paginate`: the query nests a second paged connection
698
+ * (`blockedBy`) in every node, and a hand loop follows the outer cursor by
699
+ * name instead of trusting gh to find the right `pageInfo` (review of #2334).
700
+ */
701
+ function readPhaseIssues(gh: Gh, repo: string): Reading<PhaseIssue[]> {
702
+ const [owner, name] = repo.split("/");
703
+ const out: PhaseIssue[] = [];
704
+ let cursor: string | null = null;
705
+ for (let page = 0; page < 50; page++) {
706
+ const args = ["api", "graphql", "-f", `query=${PHASE_ISSUES_QUERY}`, "-f", `owner=${owner}`, "-f", `name=${name}`];
707
+ if (cursor !== null) args.push("-f", `after=${cursor}`);
708
+ const r = ghJson<{ data?: { repository?: { issues?: { pageInfo: { hasNextPage: boolean; endCursor: string }; nodes: any[] } } } }>(gh, args);
709
+ if (r.kind === "UNMEASURED") return unmeasured(r.why);
710
+ const conn = r.value.data?.repository?.issues;
711
+ if (!conn) return unmeasured("the open issues could not be read: the reply carried no issues connection");
712
+ for (const n of conn.nodes) {
713
+ if (!n?.milestone?.title) continue;
714
+ out.push({
715
+ number: n.number,
716
+ title: n.title,
717
+ url: n.url,
718
+ milestone: n.milestone.title,
719
+ assignees: (n.assignees?.nodes ?? []).map((a: { login: string }) => a.login),
720
+ blockers: (n.blockedBy?.nodes ?? []).filter((b: { state: string }) => b.state === "OPEN").map((b: { number: number }) => b.number),
721
+ moreBlockers: n.blockedBy?.pageInfo?.hasNextPage === true,
722
+ });
723
+ }
724
+ // The one decider of "is there another page" (SC-2721), so an empty or
725
+ // missing cursor on a page that says more exist is UNMEASURED, not the end.
726
+ const next = nextCursor(conn.pageInfo);
727
+ if (next.kind === "done") return read(out);
728
+ if (next.kind === "unreadable") return unmeasured(`the open issues could not be paged: ${next.why}`);
729
+ cursor = next.cursor;
730
+ }
731
+ return unmeasured("the open issues kept paging past 5,000");
732
+ }
733
+
734
+ /**
735
+ * What only a person can decide, as far as the tracker records it: an open
736
+ * pull request that changes a decision record (`docs/adr/`), which a person
737
+ * merges; open issues labelled `needs-criterion`, whose criterion text a
738
+ * person writes; and open issues labelled `needs-decision`, which a session
739
+ * parked for a person (#2138). A decision parked only in prose is still
740
+ * invisible here: on 2026-11-14 two were, and this section said nothing was
741
+ * waiting. Label the issue, or it is not on this list.
742
+ */
743
+ function readDecisions(gh: Gh, repo: string, items: Reading<OpenItem[]>): Reading<WorkLine[]> {
744
+ if (items.kind === "UNMEASURED") return unmeasured(items.why);
745
+ const out: WorkLine[] = [];
746
+ for (const pr of items.value.filter(i => i.pr)) {
747
+ const files = ghLines<string>(gh, `repos/${repo}/pulls/${pr.number}/files?per_page=100`, ".[] | .filename | @json");
748
+ if (files.kind === "UNMEASURED") return unmeasured(`files of pull request #${pr.number}: ${files.why}`);
749
+ if (files.value.some(f => f.startsWith("docs/adr/"))) out.push({ number: pr.number, title: pr.title, url: pr.url, note: "decision record to merge" });
750
+ }
751
+ for (const i of items.value.filter(i => !i.pr)) {
752
+ const notes = [
753
+ ...(i.labels.includes("needs-criterion") ? ["names no criterion"] : []),
754
+ ...(i.labels.includes(NEEDS_DECISION) ? ["parked for a decision"] : []),
755
+ ];
756
+ if (notes.length > 0) out.push({ number: i.number, title: i.title, url: i.url, note: notes.join("; ") });
757
+ }
758
+ return read(out);
759
+ }
760
+
761
+ /** The board's Ready lane: issues whose Status is `Ready`, in board order. */
762
+ function readReady(gh: Gh, root: string, items: Reading<OpenItem[]>): Reading<WorkLine[]> {
763
+ const board = readBoardConfig(root);
764
+ if (board === null) return unmeasured("no board is configured (board.id and board.fields.Criteria)");
765
+ if (items.kind === "UNMEASURED") return unmeasured(items.why);
766
+ const q =
767
+ "query($p:ID!,$c:String){node(id:$p){... on ProjectV2{items(first:100,after:$c){pageInfo{hasNextPage endCursor} " +
768
+ "nodes{status:fieldValueByName(name:\"Status\"){... on ProjectV2ItemFieldSingleSelectValue{name}} " +
769
+ "content{... on Issue{number state}}}}}}}";
770
+ const ready: number[] = [];
771
+ let cursor: string | null = null;
772
+ for (let page = 0; page < 50; page++) {
773
+ const args = ["api", "graphql", "-f", `query=${q}`, "-f", `p=${board.projectId}`];
774
+ if (cursor !== null) args.push("-f", `c=${cursor}`);
775
+ const r = ghJson<{ data?: { node?: { items?: { pageInfo: { hasNextPage: boolean; endCursor: string }; nodes: any[] } } } }>(gh, args);
776
+ if (r.kind === "UNMEASURED") return unmeasured(`the board could not be read: ${r.why}`);
777
+ const conn = r.value.data?.node?.items;
778
+ if (!conn) return unmeasured("the board could not be read: this token cannot see the project");
779
+ for (const n of conn.nodes) {
780
+ if (n?.status?.name === "Ready" && n?.content?.state === "OPEN" && typeof n.content.number === "number") ready.push(n.content.number);
781
+ }
782
+ if (!conn.pageInfo.hasNextPage) {
783
+ const byNumber = new Map(items.value.map(i => [i.number, i]));
784
+ return read(
785
+ ready.flatMap(n => {
786
+ const i = byNumber.get(n);
787
+ return i ? [{ number: i.number, title: i.title, url: i.url }] : [];
788
+ }),
789
+ );
790
+ }
791
+ cursor = conn.pageInfo.endCursor;
792
+ }
793
+ return unmeasured("the board kept paging past 5,000 items");
794
+ }
795
+
796
+ /** Board health: `board-conformance`'s own readings, written as JSON by the command itself (#1889). */
797
+ function readHealth(root: string): Reading<HealthLine[]> {
798
+ const dir = mkdtempSync(join(tmpdir(), "status-view-"));
799
+ try {
800
+ const out = join(dir, "readings.json");
801
+ const r = spawnSync("bun", [CLI_ENTRY, "board-conformance", "--emit-readings", out], {
802
+ cwd: root,
803
+ encoding: "utf-8",
804
+ maxBuffer: 64 * 1024 * 1024,
805
+ });
806
+ if (!existsSync(out)) {
807
+ return unmeasured(`board-conformance wrote no readings (exit ${r.status}): ${(r.stderr ?? "").trim().split("\n").pop() ?? ""}`);
808
+ }
809
+ const rows = JSON.parse(readFileSync(out, "utf-8")) as HealthLine[];
810
+ if (!Array.isArray(rows) || rows.length === 0) return unmeasured("board-conformance wrote an empty list of readings");
811
+ return read(rows.map(x => ({ name: x.name, status: x.status, measured: x.measured, target: x.target })));
812
+ } catch (e) {
813
+ return unmeasured(`board-conformance's readings could not be parsed (${(e as Error).message})`);
814
+ } finally {
815
+ rmSync(dir, { recursive: true, force: true });
816
+ }
817
+ }
818
+
819
+ /**
820
+ * Write the rendered body into the issue that carries the marker, pinned or
821
+ * not. If there is none, create one. Then make sure it is pinned.
822
+ *
823
+ * **Found by marker among ALL open issues, not only the pinned ones** (AI
824
+ * review of #2103). Looking only at pinned issues meant a pin that failed
825
+ * once (the repository's three pin slots full, or a token without the right)
826
+ * created a fresh issue on every later run, because the one just created was
827
+ * never pinned and so was never found. Now it is found, reused, and the pin is
828
+ * retried. A pin that still fails is a warning annotation on its own line,
829
+ * and the body is still written.
830
+ */
831
+ export function publish(body: string, repo: string, title: string, gh: Gh = liveGh): { ok: boolean; message: string } {
832
+ if (!body.startsWith(STATUS_MARKER)) return { ok: false, message: "refusing to publish a body without the status marker" };
833
+ const [owner, name] = repo.split("/");
834
+ const pinned = ghJson<{ data?: { repository?: { pinnedIssues?: { nodes: { issue: { number: number; body: string } }[] } } } }>(gh, [
835
+ "api", "graphql", "-f",
836
+ "query=query($o:String!,$n:String!){repository(owner:$o,name:$n){pinnedIssues(first:3){nodes{issue{number body}}}}}",
837
+ "-f", `o=${owner}`, "-f", `n=${name}`,
838
+ ]);
839
+ if (pinned.kind === "UNMEASURED") return { ok: false, message: `UNMEASURED — the pinned issues could not be read: ${pinned.why}` };
840
+ const pinnedMine = (pinned.value.data?.repository?.pinnedIssues?.nodes ?? []).find(n => n.issue.body.startsWith(STATUS_MARKER));
841
+ let number: string | null = pinnedMine ? String(pinnedMine.issue.number) : null;
842
+ if (number === null) {
843
+ // Only an issue this workflow or a maintainer wrote. The marker is text
844
+ // anyone can type into an issue they open; reusing a stranger's issue
845
+ // would pin it, and its author could edit it back afterwards while it
846
+ // stays pinned (security review of #2103). A pinned issue needs no such
847
+ // check: pinning already takes maintainer rights.
848
+ const open = ghLines<{ number: number; body: string | null; login: string | null; association: string | null }>(
849
+ gh,
850
+ `repos/${repo}/issues?state=open&per_page=100`,
851
+ ".[] | select(.pull_request == null) | {number, body, login: .user.login, association: .author_association}",
852
+ );
853
+ if (open.kind === "UNMEASURED") return { ok: false, message: `UNMEASURED — the open issues could not be read: ${open.why}` };
854
+ const found = open.value.find(i => (i.body ?? "").startsWith(STATUS_MARKER) && trustedAuthor(i.login, i.association));
855
+ if (found) number = String(found.number);
856
+ }
857
+ const dir = mkdtempSync(join(tmpdir(), "status-publish-"));
858
+ try {
859
+ const file = join(dir, "body.md");
860
+ writeFileSync(file, body);
861
+ let verb: string;
862
+ if (number !== null) {
863
+ const r = gh(["issue", "edit", number, "-R", repo, "--title", title, "--body-file", file]);
864
+ if (!r.ok) return { ok: false, message: r.why };
865
+ verb = "updated";
866
+ } else {
867
+ const created = gh(["issue", "create", "-R", repo, "--title", title, "--body-file", file]);
868
+ if (!created.ok) return { ok: false, message: created.why };
869
+ number = /\/issues\/(\d+)/.exec(created.out)?.[1] ?? null;
870
+ if (number === null) return { ok: false, message: `created an issue but could not read its number from: ${created.out.trim()}` };
871
+ verb = "created";
872
+ }
873
+ if (pinnedMine) return { ok: true, message: `${verb} #${number}` };
874
+ const pin = gh(["issue", "pin", number, "-R", repo]);
875
+ return pin.ok
876
+ ? { ok: true, message: `${verb} and pinned #${number}` }
877
+ : {
878
+ ok: true,
879
+ message:
880
+ `${verb} #${number}\n::warning title=Status view::#${number} could not be pinned (${pin.why}). ` +
881
+ "Pin it once by hand; later runs find and reuse it either way.",
882
+ };
883
+ } finally {
884
+ rmSync(dir, { recursive: true, force: true });
885
+ }
886
+ }
887
+
888
+ /** The workflow's own identity, or someone with write access to the repository. */
889
+ export function trustedAuthor(login: string | null, association: string | null): boolean {
890
+ return login === "github-actions[bot]" || ["OWNER", "MEMBER", "COLLABORATOR"].includes(association ?? "");
891
+ }
892
+
893
+ /** The pinned issue's title: follows the focus family, never a fixed name. */
894
+ export function viewTitle(family: string | null): string {
895
+ return family === null ? "Where we are" : `Where we are: ${family}`;
896
+ }
897
+
898
+ function flag(argv: string[], name: string): string | null {
899
+ const i = argv.indexOf(name);
900
+ return i === -1 ? null : (argv[i + 1] ?? "");
901
+ }
902
+
903
+ /** `owner/name` from a git remote URL in any spelling git writes, or null for one that names no repository. */
904
+ export function repoFromRemote(url: string): string | null {
905
+ const m = /^(?:[a-z+]+:\/\/(?:[^@/]+@)?[^/]+\/|[^@/\s]+@[^:/\s]+:)([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(url.trim());
906
+ return m === null ? null : `${m[1]}/${m[2]}`;
907
+ }
908
+
909
+ /**
910
+ * Which repository to read: `--repo`, then `GITHUB_REPOSITORY`, then the
911
+ * checkout's `origin` remote (#2330), so `rungate board` run in a consumer
912
+ * reads that consumer with no flag. Null when none of the three names one.
913
+ */
914
+ export function resolveRepo(argv: string[], env: Record<string, string | undefined>, root: string): string | null {
915
+ // An explicit `--repo` is used as given, even empty, so a bad flag is
916
+ // refused rather than guessed past. An empty GITHUB_REPOSITORY names
917
+ // nothing and falls through to the remote (review of #2334).
918
+ const flagged = flag(argv, "--repo");
919
+ if (flagged !== null) return flagged;
920
+ if (env.GITHUB_REPOSITORY !== undefined && env.GITHUB_REPOSITORY !== "") return env.GITHUB_REPOSITORY;
921
+ const origin = spawnSync("git", ["-C", root, "remote", "get-url", "origin"], { encoding: "utf-8" });
922
+ return origin.status === 0 ? repoFromRemote(origin.stdout) : null;
923
+ }
924
+
925
+ export function main(argv: string[], root = process.cwd()): number {
926
+ const repo = resolveRepo(argv, process.env, root);
927
+ if (repo === null || !/^[^/\s]+\/[^/\s]+$/.test(repo)) {
928
+ console.error("status-view: name the repository with --repo owner/name (or GITHUB_REPOSITORY), or run it in a checkout whose origin remote is the repository.");
929
+ return REFUSAL_EXIT;
930
+ }
931
+ const toPublish = flag(argv, "--publish");
932
+ if (toPublish !== null) {
933
+ if (toPublish === "" || !existsSync(toPublish)) {
934
+ console.error(`status-view: --publish needs a rendered file; "${toPublish}" does not exist.`);
935
+ return REFUSAL_EXIT;
936
+ }
937
+ const body = readFileSync(toPublish, "utf-8");
938
+ const family = readBoardInputs(root).milestonePrefix;
939
+ const r = publish(body, repo, viewTitle(family));
940
+ console.log(`status-view: ${r.message}`);
941
+ return r.ok ? 0 : REFUSAL_EXIT;
942
+ }
943
+ const view = gather(root, repo);
944
+ // Printed, never written to a path from argv: the caller redirects it.
945
+ // A write to an argv path is a site the spec-write sweep cannot follow
946
+ // (#1584), and a redirect in the workflow says where it goes in plain sight.
947
+ if (argv.includes("--markdown")) {
948
+ process.stdout.write(renderMarkdown(view));
949
+ } else {
950
+ process.stdout.write(renderText(view));
951
+ }
952
+ return 0;
953
+ }
954
+
955
+ if (import.meta.main) process.exit(main(process.argv.slice(2)));