Public: anyone can read this; the crew can change it.
The rosters: generate each shared roster from one file per member (child of #14248) #14385
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14355-the-rosters-generate-each-shared-roster → main 5 commits fork
8 files
changed +111
−46
AGENTS.md +2
| @@ -4,6 +4,8 @@ Read `CLAUDE.md` first: it is the rulebook for agents editing this repo. | ||
| 4 | 4 | |
| 5 | 5 | Read the guide first, in this order: `docs/guide-what-a-forge-is.md`, `docs/guide-first-app.md`, `docs/guide-tell-the-crew.md`, `docs/guide-ship-and-undo.md`, `docs/guide-your-apps.md`, `docs/guide-hosting.md`, `docs/guide-own-ai.md`, `docs/guide-agents.md`, `docs/guide-backups-moving.md`, `docs/guide-settings.md`, `docs/guide-when-wrong.md`. That is the spine (ordered in `src/view/guide.ts`, served at `/docs` with search, listed first by /llms.txt): eleven pages, each at most 300 words and 60 lines, every command, path and link in them checked by `test/guide.test.ts`. A feature's `docs/features/<name>.md` is its reference; open it with front matter `topic:` and `row:` (#14248), which builds its row in `docs/features/README.md`, the index every spine page links; never edit that list by hand (`test/feature-orphans.test.ts`). The section list of `docs/DESIGN.md` is built the same way: a section file under `docs/design/sections/` opens with `order:` and `nest:` front matter and its first heading is its title (#14354, `test/design-spine.test.ts`). |
| 6 | 6 | |
| 7 | A maintenance duty is a file in `src/maintain/duties/` that exports `duty`; `src/maintain/registry.ts` builds the roster from that directory, never edit a list by hand (#14355, `test/duty-roster.test.ts`). | |
| 8 | ||
| 7 | 9 | README.md is capped: a new feature's how-to goes in `docs/features/<name>.md`, not a new README section. |
| 8 | 10 | A pull that adds a page (`src/web/pages/*.ts`) also adds a terminal screen under `src/tui/screens/` that another module imports (its palette entry) and a `docs/features/<name>.md`, or a commit line `No door: <why>`; a new `src/web/render/*.ts`, `src/web/studio/*.ts` or `src/actions/*.ts` is asked for the screen alone, and a new feature module under `src/` in a pull that edits an existing page is asked for both, and a pull that edits an existing page (or any shared `src/web/` file, #13376: a new feature module wired into it is asked for both) changes something under `src/tui/` and a `docs/features/*.md` too (#13196); an edited API route, MCP tool or `src/actions/*.ts` changes something under `src/tui/` too (#14040); a new `src/http/api/*.ts` or `src/http/mcp/tools/*.ts` is asked for the screen, and a new module wired into `src/http/server.ts` for both (#14320); `bun scripts/gate.ts` refuses it otherwise ("both doors", #10628). |
| 9 | 11 | Both doors are also read from the tree (#14289): `test/doorless.test.ts` fails on a page in `src/web/pages/` with no terminal door unless `scripts/doorless-allow.json` lists it (the list only shrinks; `bun scripts/doorless.ts --write` prunes). A page has a door when `src/tui/` or `src/actions/` imports it, a screen is named for it, or a features doc naming the page file names `src/tui/` too. |
docs/features/maintenance-duties.md +6
| @@ -41,3 +41,9 @@ For each idle duty it files one issue, once (an open one is not filed again), ti | ||
| 41 | 41 | There is no terminal screen for it: it files an issue, and both doors (the web and the terminal) already show issues. |
| 42 | 42 | |
| 43 | 43 | Tests: `test/duty-idle.test.ts`. |
| 44 | ||
| 45 | ## Adding a duty (#14355) | |
| 46 | ||
| 47 | A duty is one file in `src/maintain/duties/` that exports `duty` (a `Duty`, see `src/maintain/duty.ts`). `src/maintain/registry.ts` lists that directory when it loads and builds the roster from it, so a pull that adds a duty adds that file and edits no shared list; `scripts/unreached.ts` counts every file there as reached. A file that does not export `duty` stops boot with an error naming it. `duty_idle.ts` is the one exception: it watches the others and is appended last. | |
| 48 | ||
| 49 | The roster is in file-name order, and that is the order the runner ticks the duties and `/maintenance` lists them (it used to be a hand-picked order). To place a duty, name its file for where it should sit. Tests: `test/duty-roster.test.ts`. |
scripts/unreached.ts +4 −1
| @@ -30,6 +30,9 @@ export const ENTRIES = [ | ||
| 30 | 30 | "src/web/highlight-client.ts", |
| 31 | 31 | ]; |
| 32 | 32 | |
| 33 | /** Loaded by listing the directory, so nothing imports them: the duty roster (#14355). */ | |
| 34 | const LISTED_DIRS = /^src\/maintain\/duties\/[^/]+\.ts$/; | |
| 35 | ||
| 33 | 36 | /** |
| 34 | 37 | * Scripts the check and operators run, and the benches run at release, are callers too: their |
| 35 | 38 | * imports count. |
| @@ -58,7 +61,7 @@ export function unreached(root: string): string[] { | ||
| 58 | 61 | const files = new Set( |
| 59 | 62 | [...new Bun.Glob("src/**/*.ts").scanSync({ cwd: root })].filter((f) => !f.endsWith(".d.ts") && !NOT_MODULES.test(f)), |
| 60 | 63 | ); |
| 61 | const reached = new Set<string>(ENTRIES.filter((e) => files.has(e))); | |
| 64 | const reached = new Set<string>([...ENTRIES.filter((e) => files.has(e)), ...[...files].filter((f) => LISTED_DIRS.test(f))]); | |
| 62 | 65 | const queue = [...reached, ...SCRIPTS.flatMap((g) => [...new Bun.Glob(g).scanSync({ cwd: root })])]; |
| 63 | 66 | for (let file = queue.pop(); file; file = queue.pop()) { |
| 64 | 67 | const text = readFileSync(join(root, file), "utf8"); |
src/maintain/duties/preview_dirs.ts added +28
| @@ -0,0 +1,28 @@ | ||
| 1 | /** | |
| 2 | * The preview-directory duty: it only reads and names the count and bytes of preview data of pulls | |
| 3 | * closed over a week ago. The listing and the removal are in `../previews.ts`. | |
| 4 | */ | |
| 5 | ||
| 6 | import type { Duty } from "../duty.ts"; | |
| 7 | import { PREVIEW_DAYS, previewLine, sizeWords, sizedPreviewDirs } from "../previews.ts"; | |
| 8 | ||
| 9 | export const duty: Duty = { | |
| 10 | name: "preview-dirs", | |
| 11 | intervalMs: 6 * 3_600_000, | |
| 12 | budget: { runsPerDay: 8, dollarsPerDay: 1, reason: "every six hours is four a day; the rest is room for a catch-up, and it spends no money" }, | |
| 13 | async run({ now, app }) { | |
| 14 | if (app === undefined) return { findings: [], actions: [] }; | |
| 15 | const found = await sizedPreviewDirs(app, now); | |
| 16 | if (found.length === 0) return { findings: [], actions: [] }; | |
| 17 | const total = found.reduce((n, p) => n + (p.bytes ?? 0), 0); | |
| 18 | return { | |
| 19 | findings: [ | |
| 20 | { | |
| 21 | summary: `${found.length} preview director${found.length === 1 ? "y" : "ies"} of pulls closed over ${PREVIEW_DAYS} days ago, ${sizeWords(total)}: ${found.slice(0, 5).map(previewLine).join(", ")}${found.length > 5 ? ", …" : ""}`, | |
| 22 | probe: { kind: "measurement", what: "bytes in preview directories of pulls closed over seven days ago", number: total, at: now.toISOString() }, | |
| 23 | }, | |
| 24 | ], | |
| 25 | actions: [], | |
| 26 | }; | |
| 27 | }, | |
| 28 | }; |
src/maintain/previews.ts −22
| @@ -15,7 +15,6 @@ import { appsRoot, envDir, previewEnv, removeEnv } from "../apps/data.ts"; | ||
| 15 | 15 | import { dirBytes } from "../apps/bytes.ts"; |
| 16 | 16 | import type { User } from "../core/users.ts"; |
| 17 | 17 | import { err, ok, type Result } from "../kernel/result.ts"; |
| 18 | import type { Duty } from "./duty.ts"; | |
| 19 | 18 | import { record } from "./runs.ts"; |
| 20 | 19 | |
| 21 | 20 | export const PREVIEW_DAYS = 7; |
| @@ -168,24 +167,3 @@ export async function removePreviewDirs(app: App, admin: User | undefined, shown | ||
| 168 | 167 | record(app.db, { duty: "preview-dirs", started: now, finished: now, findings: [], actions: [says], outcome: "ok" }); |
| 169 | 168 | return ok({ says }); |
| 170 | 169 | } |
| 171 | ||
| 172 | export const duty: Duty = { | |
| 173 | name: "preview-dirs", | |
| 174 | intervalMs: 6 * 3_600_000, | |
| 175 | budget: { runsPerDay: 8, dollarsPerDay: 1, reason: "every six hours is four a day; the rest is room for a catch-up, and it spends no money" }, | |
| 176 | async run({ now, app }) { | |
| 177 | if (app === undefined) return { findings: [], actions: [] }; | |
| 178 | const found = await sizedPreviewDirs(app, now); | |
| 179 | if (found.length === 0) return { findings: [], actions: [] }; | |
| 180 | const total = found.reduce((n, p) => n + (p.bytes ?? 0), 0); | |
| 181 | return { | |
| 182 | findings: [ | |
| 183 | { | |
| 184 | summary: `${found.length} preview director${found.length === 1 ? "y" : "ies"} of pulls closed over ${PREVIEW_DAYS} days ago, ${sizeWords(total)}: ${found.slice(0, 5).map(previewLine).join(", ")}${found.length > 5 ? ", …" : ""}`, | |
| 185 | probe: { kind: "measurement", what: "bytes in preview directories of pulls closed over seven days ago", number: total, at: now.toISOString() }, | |
| 186 | }, | |
| 187 | ], | |
| 188 | actions: [], | |
| 189 | }; | |
| 190 | }, | |
| 191 | }; |
src/maintain/registry.ts +32 −22
| @@ -1,29 +1,39 @@ | ||
| 1 | /** The duties the forge runs: one line per duty file in `duties/`. */ | |
| 1 | /** | |
| 2 | * The duties the forge runs, built from the files in `duties/` when this module loads (#14355): a | |
| 3 | * duty file exports `duty` and is on the roster; a pull that adds a duty adds that one file and | |
| 4 | * edits no shared list. Sorted by file name (the order the runner and /maintenance show). | |
| 5 | * `duty_idle.ts` is not listed: it watches the rest. | |
| 6 | */ | |
| 2 | 7 | |
| 8 | import { readdirSync } from "node:fs"; | |
| 9 | import { fileURLToPath } from "node:url"; | |
| 3 | 10 | import type { Duty } from "./duty.ts"; |
| 4 | import { duty as pullsWaiting } from "./duties/stale_pulls.ts"; | |
| 5 | import { duty as ruleWatcher } from "./duties/rule_watcher.ts"; | |
| 6 | import { duty as efficiencyWatcher } from "./duties/efficiency_watcher.ts"; | |
| 7 | import { duty as flowKeeper } from "./duties/flow_keeper.ts"; | |
| 8 | import { duty as visitorRetention } from "./duties/visitor_retention.ts"; | |
| 9 | import { duty as backupGrowth } from "./duties/backup_growth.ts"; | |
| 10 | import { duty as v1Proven } from "./duties/v1_proven.ts"; | |
| 11 | import { duty as backupAge } from "./duties/backup_age.ts"; | |
| 12 | import { duty as mergedBranches } from "./duties/merged_branches.ts"; | |
| 13 | import { duty as staleBranches } from "./duties/stale_branches.ts"; | |
| 14 | import { duty as previewDirs } from "./previews.ts"; | |
| 15 | import { duty as diskFree } from "./duties/disk_free.ts"; | |
| 16 | import { duty as staleIssues } from "./duties/stale_issues.ts"; | |
| 17 | import { duty as waitSplit } from "./duties/wait_split.ts"; | |
| 18 | import { duty as slowTests } from "./duties/slow_tests.ts"; | |
| 19 | import { duty as deadDocPaths } from "./duties/dead_doc_paths.ts"; | |
| 20 | import { duty as redApps } from "./duties/red_apps.ts"; | |
| 21 | import { duty as flakyTests } from "./duties/flaky_tests.ts"; | |
| 22 | import { duty as untestedSources } from "./duties/untested_sources.ts"; | |
| 23 | import { duty as chapterStall } from "./duties/chapter_stall.ts"; | |
| 24 | 11 | import { dutyIdle } from "./duties/duty_idle.ts"; |
| 25 | 12 | |
| 26 | const others: readonly Duty[] = [pullsWaiting, ruleWatcher, efficiencyWatcher, flowKeeper, visitorRetention, backupGrowth, backupAge, v1Proven, diskFree, mergedBranches, staleBranches, previewDirs, staleIssues, waitSplit, slowTests, flakyTests, redApps, chapterStall, deadDocPaths, untestedSources]; | |
| 13 | const dir = new URL("./duties/", import.meta.url); | |
| 14 | ||
| 15 | /** The duty files' names in a directory, sorted: every `.ts` but the idle watcher. */ | |
| 16 | export function dutyFiles(from: URL = dir): string[] { | |
| 17 | return readdirSync(from) | |
| 18 | .filter((f) => f.endsWith(".ts") && f !== "duty_idle.ts") | |
| 19 | .sort(); | |
| 20 | } | |
| 21 | ||
| 22 | /** | |
| 23 | * The duties the files in a directory export, in file-name order. A file without `duty` throws, | |
| 24 | * naming the file. Loaded with `require`, not a top-level `await import`: this module sits in | |
| 25 | * import cycles (a duty reaches the runner, which imports this), and a cycle through an awaiting | |
| 26 | * module never settles. | |
| 27 | */ | |
| 28 | export function loadDuties(from: URL = dir): Duty[] { | |
| 29 | return dutyFiles(from).map((f) => { | |
| 30 | const m = require(fileURLToPath(new URL(f, from))) as { duty?: Duty }; | |
| 31 | if (m.duty === undefined) throw new Error(`${f} in ${fileURLToPath(from)} must export \`duty\` (it is the roster's entry, #14355)`); | |
| 32 | return m.duty; | |
| 33 | }); | |
| 34 | } | |
| 35 | ||
| 36 | const others: readonly Duty[] = loadDuties(); | |
| 27 | 37 | |
| 28 | 38 | /** The duties plus the one that watches them for silence. */ |
| 29 | 39 | export const duties: readonly Duty[] = [...others, dutyIdle(others)]; |
test/duty-roster.test.ts added +37
| @@ -0,0 +1,37 @@ | ||
| 1 | import { expect, test } from "bun:test"; | |
| 2 | import { mkdirSync, mkdtempSync, readdirSync, writeFileSync } from "node:fs"; | |
| 3 | import { join } from "node:path"; | |
| 4 | import { pathToFileURL } from "node:url"; | |
| 5 | import { dutyFiles, duties, loadDuties } from "../src/maintain/registry.ts"; | |
| 6 | import { NAME } from "../src/maintain/duties/duty_idle.ts"; | |
| 7 | import { validName } from "../src/maintain/duty.ts"; | |
| 8 | ||
| 9 | // The roster is the files in duties/ (#14355). | |
| 10 | test("every duty file is on the roster, once, and the idle watcher is last", () => { | |
| 11 | const files = readdirSync("src/maintain/duties").filter((f) => f.endsWith(".ts") && f !== "duty_idle.ts"); | |
| 12 | expect(dutyFiles()).toEqual(files.sort()); | |
| 13 | expect(duties.length).toBe(files.length + 1); | |
| 14 | expect(duties.at(-1)?.name).toBe(NAME); | |
| 15 | const names = duties.map((d) => d.name); | |
| 16 | expect(new Set(names).size).toBe(names.length); | |
| 17 | for (const n of names) expect(validName(n)).toBe(true); | |
| 18 | }); | |
| 19 | ||
| 20 | function fixture(files: Record<string, string>): URL { | |
| 21 | const dir = mkdtempSync(join(process.env.TMPDIR ?? "/tmp", "duties-")); | |
| 22 | mkdirSync(dir, { recursive: true }); | |
| 23 | for (const [name, text] of Object.entries(files)) writeFileSync(join(dir, name), text); | |
| 24 | return pathToFileURL(dir + "/"); | |
| 25 | } | |
| 26 | ||
| 27 | const ok = (name: string) => `export const duty: { name: string } = { name: "${name}" };\n`; | |
| 28 | ||
| 29 | test("a directory's duties load in file-name order, whatever the export's spelling", () => { | |
| 30 | const from = fixture({ "b.ts": ok("bee"), "a.ts": `const duty = { name: "ay" };\nexport { duty };\n`, "duty_idle.ts": "throw new Error('not loaded');\n", "notes.md": "" }); | |
| 31 | expect(loadDuties(from).map((d) => d.name)).toEqual(["ay", "bee"]); | |
| 32 | }); | |
| 33 | ||
| 34 | test("a duty file that does not export `duty` is refused by name", () => { | |
| 35 | const from = fixture({ "good.ts": ok("good"), "lonely.ts": "export const other = 1;\n" }); | |
| 36 | expect(() => loadDuties(from)).toThrow(/lonely\.ts.*must export `duty`/); | |
| 37 | }); |
test/maintain-previews-duty.test.ts +2 −1
| @@ -12,7 +12,8 @@ import { appsRoot } from "../src/apps/data.ts"; | ||
| 12 | 12 | import { createRepo } from "../src/core/repos.ts"; |
| 13 | 13 | import { createUser } from "../src/core/users.ts"; |
| 14 | 14 | import { id } from "../src/kernel/id.ts"; |
| 15 | import { duty, previewDirs } from "../src/maintain/previews.ts"; | |
| 15 | import { duty } from "../src/maintain/duties/preview_dirs.ts"; | |
| 16 | import { previewDirs } from "../src/maintain/previews.ts"; | |
| 16 | 17 | import { duties } from "../src/maintain/registry.ts"; |
| 17 | 18 | import { quietLogs } from "./helpers/globals.ts"; |
| 18 | 19 |
new above
offline