Public: anyone can read this; the crew can change it.

`bun scripts/flow-report.ts` prints every flow read in one page, so each is reachable while its surface is built #6595

Parked opened this
Closed without merging

scout/forge:scout/6584-bun-scripts-flow-report-ts-prints-every → main 3 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
5 files changed +256 −0
README.md +1
@@ -702,6 +702,7 @@ This page is the front door. Everything else is a file of its own under
702702 - [`docs/CREW.md`](docs/CREW.md) — the crew: agents, how a run works, review, live triage, the merge queue, spend, roles and invites, the sandbox, passports, and the direction a vision pull will write.
703703 - [`docs/SENTINEL.md`](docs/SENTINEL.md) — the forge hunting its own faults; [`docs/HUNT.md`](docs/HUNT.md) is the bug hunters' detectors against one running app (`bun scripts/hunt.ts <origin>`).
704704 - [`docs/FLOW.md`](docs/FLOW.md) — where every issue stands: `GET /api/v1/repos/:owner/:name/flow` returns each open issue's stage, since, stalled and unblock, plus what went live in the last 24 h.
705 - **Flow reads, in one page** — `bun scripts/flow-report.ts [--db <path>] [--public] [--json]` (database read-only, default `forge.db` under `FORGE_DATA`; `--json` for raw values) and the last block of the terminal's Flow dialog print one line per read of `src/flow/report.ts`: `build_yield` (agent runs finished in 24 h: how many pushed, landed, closed), `review_latency` (median hours from opening to first verdict), `outsiders` (open pulls by non-writers and non-crew, oldest in hours), `checks_pile` (open pulls red or waiting for a check slot), `gate_minutes` (check-slot minutes in 1 h and 6 h), `oldest_approved` (the longest-waiting approved pull), `idle_pulls` (crew pulls untouched for 72 h), `lead_time` (opening to landing, 24 h) and `openers` (who opened the last hour's pulls). The admin's dialog and the script read everything; an agent's dialog and `--public` are cut to public repositories.
705706 - The flow panel on `/boards` and the terminal Flow dialog say how the open crew pulls sort into piles (red, conflicted, changes asked, approved and waiting, awaiting review), each pull counted once in the first pile it fits (`src/flow/pile.ts`).
706707 - [`docs/PLANNING.md`](docs/PLANNING.md) — how issues depend on issues: the edge, the map, and what "ready now" means to a person and to the crew.
707708 - [`docs/FLEET.md`](docs/FLEET.md) — one change across many repositories, runs or issues: a query, a dry-run plan of every row before → after, a receipt, and undo.
scripts/flow-report.ts added +23
@@ -0,0 +1,23 @@
1 /**
2 * Prints every flow read, one line each: `bun scripts/flow-report.ts [--db <path>] [--public] [--json]`.
3 * The database opens read-only; by default it is forge.db under FORGE_DATA.
4 */
5
6 import { Database } from "bun:sqlite";
7 import { join } from "node:path";
8 import { flowReadings, flowReportLines } from "../src/flow/report.ts";
9
10 const args = process.argv.slice(2);
11 const flag = (name: string) => args.includes(name);
12 const at = args.indexOf("--db");
13 const known = new Set(["--db", "--public", "--json"]);
14 const bad = args.find((a, i) => !known.has(a) && args[i - 1] !== "--db");
15 if (bad !== undefined || (at >= 0 && !args[at + 1])) {
16 console.error("usage: bun scripts/flow-report.ts [--db <path>] [--public] [--json]");
17 process.exit(2);
18 }
19 const path = at >= 0 ? args[at + 1]! : join(process.env.FORGE_DATA ?? "data", "forge.db");
20 const db = new Database(path, { readonly: true });
21 const readings = flowReadings(db, new Date(), flag("--public"));
22 console.log(flag("--json") ? JSON.stringify(readings, null, 2) : flowReportLines(readings).join("\n"));
23 db.close();
src/flow/report.ts added +59
@@ -0,0 +1,59 @@
1 /**
2 * Every flow read in one page: the nine reads under src/flow/ that nothing
3 * else calls yet, each as one plain line, in a fixed order. `flowReadings`
4 * is the raw values; `flowReport` words them. `publicOnly` is the rule every
5 * read keeps: public repositories alone.
6 */
7
8 import type { Database } from "bun:sqlite";
9 import { readBuildYield } from "./build_yield.ts";
10 import { readChecksPile } from "./checks_pile.ts";
11 import { readGateMinutes } from "./gate_minutes.ts";
12 import { readIdlePulls } from "./idle_pulls.ts";
13 import { readLeadTime } from "./lead_time.ts";
14 import { readOldestApproved } from "./oldest_approved.ts";
15 import { readOpeners } from "./openers.ts";
16 import { readOutsiders } from "./outsiders.ts";
17 import { readReviewLatency } from "./review_latency.ts";
18
19 /** The raw value of each read, keyed by its name, in report order. */
20 export function flowReadings(db: Database, now = new Date(), publicOnly = false) {
21 return {
22 build_yield: readBuildYield(db, now, publicOnly),
23 review_latency: readReviewLatency(db, now, publicOnly),
24 outsiders: readOutsiders(db, now, publicOnly),
25 checks_pile: readChecksPile(db, publicOnly),
26 gate_minutes: readGateMinutes(db, now, publicOnly),
27 oldest_approved: readOldestApproved(db, now, publicOnly),
28 idle_pulls: readIdlePulls(db, now, publicOnly),
29 lead_time: readLeadTime(db, now, publicOnly),
30 openers: readOpeners(db, now, publicOnly),
31 };
32 }
33
34 export type FlowReadings = ReturnType<typeof flowReadings>;
35
36 const hours = (h: number | null): string => (h === null ? "—" : `${Math.round(h * 10) / 10} h`);
37
38 /** One line per read: `name: words`. */
39 export function flowReportLines(r: FlowReadings): string[] {
40 const y = r.build_yield;
41 const g = r.gate_minutes;
42 const o = r.oldest_approved;
43 const l = r.lead_time;
44 return [
45 `build_yield: ${y.pushed} of ${y.finished} runs pushed in 24 h, ${y.landed} landed, ${y.closed} closed`,
46 `review_latency: ${r.review_latency ? `median ${hours(r.review_latency.median)} over ${r.review_latency.count} pulls in 24 h` : "no first verdict in 24 h"}`,
47 `outsiders: ${r.outsiders.open} open, oldest ${r.outsiders.oldestHours} h`,
48 `checks_pile: ${r.checks_pile.red} red, ${r.checks_pile.queued} queued`,
49 `gate_minutes: gates ${g.gate1h} min in 1 h, ${g.gate6h} min in 6 h; pull checks ${g.pull1h} min in 1 h, ${g.pull6h} min in 6 h`,
50 `oldest_approved: ${o ? `${o.repo}#${o.pull} approved ${hours(o.hours)} ago` : "none waiting"}`,
51 `idle_pulls: ${r.idle_pulls.length === 0 ? "none" : r.idle_pulls.map((p) => `${p.repo}#${p.pull}${p.issue === null ? "" : ` (closes #${p.issue})`} ${hours(p.hours)}`).join(", ")}`,
52 `lead_time: ${l.landed} landed in 24 h, median ${hours(l.medianHours)}, slowest ${hours(l.maxHours)}`,
53 `openers: ${r.openers.length === 0 ? "none in 1 h" : r.openers.map((p) => `${p.author} ${p.opened} (${p.flow} flow)`).join(", ")}`,
54 ];
55 }
56
57 export function flowReport(db: Database, now = new Date(), publicOnly = false): string[] {
58 return flowReportLines(flowReadings(db, now, publicOnly));
59 }
src/tui/screens/flow.ts +5
@@ -10,6 +10,7 @@
1010 * builder and on a reviewer (`flow/requested.ts`, #2172); then each
1111 * autonomous repository's ready list, startable beside the count per
1212 * filter that holds the rest (`flow/held.ts`, #2244), as the flow panel draws it.
13 * Last, one line per flow read of `flow/report.ts`, cut to public for an agent.
1314 * Read-only; Enter, Esc or q closes it.
1415 */
1516
@@ -21,6 +22,7 @@ import { pileSays, readPile } from "../../flow/pile.ts";
2122 import { readPipeline, STAGE_LABEL, verdict } from "../../flow/pipeline.ts";
2223 import { parkedSays, readParked } from "../../flow/parked.ts";
2324 import { firedAlarms } from "../../flow/alarms.ts";
25 import { flowReport } from "../../flow/report.ts";
2426 import { readLeadTime, type LeadTime } from "../../flow/lead_time.ts";
2527 import { readOpeners, type Opener } from "../../flow/openers.ts";
2628 import { readVitals, vitalsLine } from "../../flow/vitals.ts";
@@ -100,6 +102,9 @@ export function flowLines(
100102 ...(reviewing === null ? [] : ["", ...wrap(reviewing, inner)]),
101103 ...(held === undefined ? [] : ["", ...heldLines(held, inner)]),
102104 "",
105 "Reads (bun scripts/flow-report.ts):",
106 ...flowReport(db, now, agent !== undefined).flatMap((l) => wrap(l, inner)),
107 "",
103108 ...duplicateLines(dups, inner),
104109 ];
105110 }
test/flow-report.test.ts added +168
@@ -0,0 +1,168 @@
1 /** The flow report (#6595): one line per read, cut to public repositories for a reader who may not see private ones. */
2 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
3 import { mkdtempSync, rmSync } from "node:fs";
4 import { tmpdir } from "node:os";
5 import { join } from "node:path";
6 import { createApp, type App } from "../src/app.ts";
7 import { createUser } from "../src/core/users.ts";
8 import { id } from "../src/kernel/id.ts";
9 import { flowReport } from "../src/flow/report.ts";
10 import { flowLines } from "../src/tui/screens/flow.ts";
11
12 const NOW = new Date("2026-10-26T12:00:00.000Z");
13 const ago = (min: number) => new Date(NOW.getTime() - min * 60_000).toISOString();
14 const ORDER = [
15 "build_yield", "review_latency", "outsiders", "checks_pile", "gate_minutes",
16 "oldest_approved", "idle_pulls", "lead_time", "openers",
17 ];
18 const name = (line: string) => line.split(":")[0]!;
19
20 let dir: string;
21 let app: App;
22 let priv: string;
23 let alice: string;
24 let bot: string;
25 let carol: string;
26 let n = 0;
27
28 const issue = (repo: string, author: string, minutes: number) => {
29 const iid = id();
30 app.db
31 .query(`INSERT INTO issue (id, repo_id, number, kind, title, body, author_id, created_at) VALUES (?1, ?2, ?3, 'pull', 't', '', ?4, ?5)`)
32 .run(iid, repo, ++n, author, ago(minutes));
33 return iid;
34 };
35 const pull = (iid: string, head: string, mergedMin: number | null = null) =>
36 app.db
37 .query(`INSERT INTO pull (issue_id, base_branch, head_branch, base_oid, head_oid, merged_at) VALUES (?1, 'main', ?2, '', ?3, ?4)`)
38 .run(iid, `b/${n}`, head, mergedMin === null ? null : ago(mergedMin));
39 const review = (iid: string, state: string, min: number) =>
40 app.db.query(`INSERT INTO review (id, issue_id, author_id, state, created_at) VALUES (?1, ?2, ?3, ?4, ?5)`).run(id(), iid, alice, state, ago(min));
41 const run = (repo: string, kind: string, extra: { issue?: string; oid?: string; state: string; start: number; end: number | null; reason?: string }) =>
42 app.db
43 .query(
44 `INSERT INTO run (id, repo_id, kind, issue_id, commit_oid, state, reason, started_at, finished_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)`,
45 )
46 .run(id(), repo, kind, extra.issue ?? null, extra.oid ?? "", extra.state, extra.reason ?? "", ago(extra.start), extra.end === null ? null : ago(extra.end));
47
48 beforeEach(async () => {
49 n = 0;
50 dir = mkdtempSync(join(tmpdir(), "forge-report-"));
51 app = createApp({ dataDir: dir, port: 0 });
52 const mk = async (username: string) => {
53 const u = await createUser(app.db, { username, email: `${username}@forge.test`, password: "a-good-passphrase", origin: "seed", trusted: true });
54 if (!u.ok) throw new Error(u.error);
55 return u.value.id;
56 };
57 alice = await mk("alice");
58 bot = await mk("builder");
59 carol = await mk("carol");
60 app.db.query(`UPDATE user SET is_agent = 1 WHERE id = ?1`).run(bot);
61 const repo = (rname: string, visibility: string) => {
62 const rid = id();
63 app.db.query(`INSERT INTO repo (id, owner_id, name, visibility) VALUES (?1, ?2, ?3, ?4)`).run(rid, alice, rname, visibility);
64 return rid;
65 };
66 repo("pub", "public");
67 priv = repo("priv", "private");
68 app.db.query(`INSERT INTO repo_crew (repo_id, user_id) VALUES (?1, ?2)`).run(priv, bot);
69
70 // Everything below lives in the private repository, so each read has something to hide.
71 const idle = issue(priv, bot, 100 * 60); // crew pull, untouched for 100 h, approved 30 h ago
72 pull(idle, "h1");
73 review(idle, "approved", 30 * 60);
74 const landed = issue(priv, bot, 5 * 60); // crew pull, first verdict 2 h ago, landed 1 h ago
75 pull(landed, "h2", 60);
76 review(landed, "changes_requested", 2 * 60);
77 const outsider = issue(priv, carol, 20); // an outsider's pull, red check, opened in the last hour
78 pull(outsider, "h3");
79 run(priv, "check", { issue: outsider, oid: "h3", state: "failed", start: 30, end: 10 });
80 run(priv, "agent", { state: "ok", start: 180, end: 120, reason: "build" });
81 });
82 afterEach(() => {
83 app.close?.();
84 rmSync(dir, { recursive: true, force: true });
85 });
86
87 describe("flowReport", () => {
88 test("one line per read, in a fixed order", () => {
89 const lines = flowReport(app.db, NOW, false);
90 expect(lines.map(name)).toEqual(ORDER);
91 expect(lines.every((l) => !l.includes("\n"))).toBe(true);
92 });
93
94 test("every read sees the private repository, and every read goes quiet under publicOnly", () => {
95 const all = flowReport(app.db, NOW, false);
96 const pub = flowReport(app.db, NOW, true);
97 for (let i = 0; i < ORDER.length; i++) expect(pub[i], ORDER[i]).not.toBe(all[i]!);
98 expect(pub).toEqual([
99 "build_yield: 0 of 0 runs pushed in 24 h, 0 landed, 0 closed",
100 "review_latency: no first verdict in 24 h",
101 "outsiders: 0 open, oldest 0 h",
102 "checks_pile: 0 red, 0 queued",
103 "gate_minutes: gates 0 min in 1 h, 0 min in 6 h; pull checks 0 min in 1 h, 0 min in 6 h",
104 "oldest_approved: none waiting",
105 "idle_pulls: none",
106 "lead_time: 0 landed in 24 h, median —, slowest —",
107 "openers: none in 1 h",
108 ]);
109 });
110
111 test("the words carry the numbers", () => {
112 const all = Object.fromEntries(flowReport(app.db, NOW, false).map((l) => [name(l), l]));
113 expect(all.build_yield).toContain("0 of 1 runs pushed");
114 expect(all.review_latency).toContain("over 1 pulls");
115 expect(all.outsiders).toBe("outsiders: 1 open, oldest 0 h");
116 expect(all.checks_pile).toBe("checks_pile: 1 red, 0 queued");
117 expect(all.gate_minutes).toContain("pull checks 20 min in 1 h");
118 expect(all.oldest_approved).toContain("priv#1");
119 expect(all.idle_pulls).toContain("priv#1");
120 expect(all.lead_time).toContain("1 landed in 24 h");
121 expect(all.openers).toBe("openers: carol 1 (0 flow)");
122 });
123 });
124
125 describe("the terminal's Flow dialog", () => {
126 test("an admin's dialog carries the report; an agent's carries the public cut", () => {
127 const admin = flowLines(app.db, NOW, []).join("\n");
128 const agent = flowLines(app.db, NOW, [], { queues: [] }).join("\n");
129 for (const l of flowReport(app.db, NOW, false)) expect(admin).toContain(l.slice(0, 30));
130 expect(admin).toContain("checks_pile: 1 red");
131 expect(agent).toContain("checks_pile: 0 red, 0 queued");
132 expect(agent).not.toContain("checks_pile: 1 red");
133 });
134 });
135
136 describe("scripts/flow-report.ts", () => {
137 const exec = (...args: string[]) => {
138 const p = Bun.spawnSync(["bun", "scripts/flow-report.ts", ...args], { env: { ...process.env, FORGE_DATA: dir } });
139 return { code: p.exitCode, out: p.stdout.toString(), err: p.stderr.toString() };
140 };
141 const db = () => join(dir, "forge.db");
142
143 test("prints nine lines; --db and FORGE_DATA name the same file", () => {
144 const a = exec("--db", db());
145 expect(a.code).toBe(0);
146 expect(a.out.trim().split("\n").map(name)).toEqual(ORDER);
147 expect(exec().out).toBe(a.out);
148 });
149
150 test("--public cuts to public repositories", () => {
151 expect(exec("--db", db(), "--public").out).toContain("checks_pile: 0 red, 0 queued");
152 expect(exec("--db", db()).out).toContain("checks_pile: 1 red");
153 });
154
155 test("--json prints the raw values", () => {
156 const v = JSON.parse(exec("--db", db(), "--json").out);
157 expect(Object.keys(v)).toEqual(ORDER);
158 expect(v.checks_pile).toEqual({ red: 1, queued: 0 });
159 });
160
161 test("a bad flag or a --db without a path exits 2 and says the usage", () => {
162 for (const args of [["--nope"], ["--db"], ["stray"]]) {
163 const r = exec(...args);
164 expect(r.code).toBe(2);
165 expect(r.err).toContain("usage:");
166 }
167 });
168 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs