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
scout/forge:scout/6584-bun-scripts-flow-report-ts-prints-every → main 3 commits fork
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 | ||
| 702 | 702 | - [](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. |
| 703 | 703 | - [](docs/SENTINEL.md) — the forge hunting its own faults; [](docs/HUNT.md) is the bug hunters' detectors against one running app (`bun scripts/hunt.ts <origin>`). |
| 704 | 704 | - [](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. | |
| 705 | 706 | - 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`). |
| 706 | 707 | - [](docs/PLANNING.md) — how issues depend on issues: the edge, the map, and what "ready now" means to a person and to the crew. |
| 707 | 708 | - [](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 @@ | ||
| 10 | 10 | * builder and on a reviewer (`flow/requested.ts`, #2172); then each |
| 11 | 11 | * autonomous repository's ready list, startable beside the count per |
| 12 | 12 | * 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. | |
| 13 | 14 | * Read-only; Enter, Esc or q closes it. |
| 14 | 15 | */ |
| 15 | 16 | |
| @@ -21,6 +22,7 @@ import { pileSays, readPile } from "../../flow/pile.ts"; | ||
| 21 | 22 | import { readPipeline, STAGE_LABEL, verdict } from "../../flow/pipeline.ts"; |
| 22 | 23 | import { parkedSays, readParked } from "../../flow/parked.ts"; |
| 23 | 24 | import { firedAlarms } from "../../flow/alarms.ts"; |
| 25 | import { flowReport } from "../../flow/report.ts"; | |
| 24 | 26 | import { readLeadTime, type LeadTime } from "../../flow/lead_time.ts"; |
| 25 | 27 | import { readOpeners, type Opener } from "../../flow/openers.ts"; |
| 26 | 28 | import { readVitals, vitalsLine } from "../../flow/vitals.ts"; |
| @@ -100,6 +102,9 @@ export function flowLines( | ||
| 100 | 102 | ...(reviewing === null ? [] : ["", ...wrap(reviewing, inner)]), |
| 101 | 103 | ...(held === undefined ? [] : ["", ...heldLines(held, inner)]), |
| 102 | 104 | "", |
| 105 | "Reads (bun scripts/flow-report.ts):", | |
| 106 | ...flowReport(db, now, agent !== undefined).flatMap((l) => wrap(l, inner)), | |
| 107 | "", | |
| 103 | 108 | ...duplicateLines(dups, inner), |
| 104 | 109 | ]; |
| 105 | 110 | } |
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 | }); |
new above
offline