Public: anyone can read this; the crew can change it.
The flow panel on /boards lists held files, with a form to hold one and a Release button on each #6777
scout/forge:scout/6525-the-flow-panel-on-boards-lists-held-file → main 3 commits fork 9 threads · 9 unresolved
README.md +2
| @@ -389,3 +389,5 @@ This page is the front door. Everything else is a file of its own under | ||
| 389 | 389 | |
| 390 | 390 | - [](docs/DESIGN.md) — the design system's spine; its sections are under `docs/design/sections/`. |
| 391 | 391 | - [](docs/SPIKE-CLOUDFLARE.md), [](docs/AUDIT-MANY-HANDS.md), [](docs/BACKLOG.md) and [](docs/research/) — a spike, an audit, a backlog and research notes, kept as written. |
| 392 | ||
| 393 | An admin of a repository can hold new work on a file from `/boards` as well as from its settings: the flow panel's "Held files" card lists the repository's holds (who set each, and when) with a Release button on each, and a form takes `owner/name` and a path to hold. Both post to `POST /boards/holds` (same-origin, admin scope, an admin of that repository; anyone else gets a 404 and no card). The MCP `hold` tool and the terminal's file holds do the same. | |
src/crew/file_holds.ts +10
| @@ -66,3 +66,13 @@ export function heldFiles(db: Database, repoId: string): FileHold[] { | ||
| 66 | 66 | .all(repoId) |
| 67 | 67 | .map((r) => ({ repoId: r.repo_id, path: r.path, by: r.by, at: r.at })); |
| 68 | 68 | } |
| 69 | ||
| 70 | /** Every file held anywhere, oldest hold first; the caller filters by who may see which repository. */ | |
| 71 | export function allHeldFiles(db: Database): FileHold[] { | |
| 72 | return db | |
| 73 | .query<{ repo_id: string; path: string; by: string; at: string }, []>( | |
| 74 | `SELECT repo_id, path, by, at FROM file_hold ORDER BY at, path`, | |
| 75 | ) | |
| 76 | .all() | |
| 77 | .map((r) => ({ repoId: r.repo_id, path: r.path, by: r.by, at: r.at })); | |
| 78 | } |
src/http/server.ts +2 −1
| @@ -339,7 +339,7 @@ import { | ||
| 339 | 339 | agentUpdate, |
| 340 | 340 | crewPage, |
| 341 | 341 | } from "../web/pages/crew.ts"; |
| 342 | import { fileHoldUpdate } from "../web/pages/file_holds.ts"; | |
| 342 | import { boardsHoldUpdate, fileHoldUpdate } from "../web/pages/file_holds.ts"; | |
| 343 | 343 | import { newPullPage, newPullSubmit } from "../web/pages/pulls.ts"; |
| 344 | 344 | import { |
| 345 | 345 | pullPage, |
| @@ -885,6 +885,7 @@ export function buildRouter(): Router<Handler> { | ||
| 885 | 885 | router.add("GET", "/settings/capacity", capacityPage); |
| 886 | 886 | router.add("POST", "/settings/capacity", capacitySet); |
| 887 | 887 | router.add("GET", "/boards", boardsList); |
| 888 | router.add("POST", "/boards/holds", boardsHoldUpdate); | |
| 888 | 889 | router.add("GET", "/boards/data", boardsPage); |
| 889 | 890 | router.add("POST", "/boards/new", boardNew); |
| 890 | 891 | router.add("POST", "/boards/pin", boardPin); |
src/web/pages/boards-file-holds.ts added +69
| @@ -0,0 +1,69 @@ | ||
| 1 | /** | |
| 2 | * The held files on the flow panel (/boards): every path held in the | |
| 3 | * repositories the viewer administers (`listFileHolds`, the same answer the | |
| 4 | * terminal and the MCP give; anyone else is shown no card), with who held it | |
| 5 | * and when, a Release button on each and one form to hold another path; both post to `/boards/holds` | |
| 6 | * (`pages/file_holds.ts`), which is where the admin and same-origin checks are. | |
| 7 | */ | |
| 8 | ||
| 9 | import { listFileHolds, type NamedHold } from "../../actions/file_holds.ts"; | |
| 10 | import type { App } from "../../app.ts"; | |
| 11 | import { getRepoById, type Repo } from "../../core/repos.ts"; | |
| 12 | import type { User } from "../../core/users.ts"; | |
| 13 | import { allHeldFiles, MAX_HOLD_PATH } from "../../crew/file_holds.ts"; | |
| 14 | import { html, type Html } from "../html.ts"; | |
| 15 | import { btn, card, field, row, time } from "../ui.ts"; | |
| 16 | ||
| 17 | const nameOf = (r: Repo): string => `${r.ownerName}/${r.name}`; | |
| 18 | ||
| 19 | /** Null unless the viewer administers a repository or the forge: the holds are an admin's book-keeping. */ | |
| 20 | export function fileHoldsPanel(app: App, viewer: User): Html | null { | |
| 21 | const rows: { repo: Repo; hold: NamedHold }[] = []; | |
| 22 | const seen = new Set<string>(); | |
| 23 | for (const h of allHeldFiles(app.db)) { | |
| 24 | if (seen.has(h.repoId)) continue; | |
| 25 | seen.add(h.repoId); | |
outdated
High: |
||
| 26 | const repo = getRepoById(app.db, h.repoId); | |
| 27 | // The admin door of `actions/file_holds.ts`, as the terminal and the MCP use it. | |
| 28 | const listed = repo ? listFileHolds(app, viewer, repo) : undefined; | |
| 29 | if (repo && listed?.ok) for (const hold of listed.value) rows.push({ repo, hold }); | |
| 30 | } | |
outdated
Once rows are admin-only, this |
||
| 31 | if (!viewer.isAdmin && rows.length === 0) return null; | |
This hides the card, and with it the hold form, from a repository admin who is not a forge admin and has no hold yet, so they cannot make their first hold from /boards. Show the card when the viewer administers any repository, not only when rows already exist, and add a test with a non-forge-admin owner who has no holds. |
||
| 32 | return card( | |
| 33 | html`<h2>Held files</h2> | |
| 34 | <p class="muted small">No build starts on an issue that names a held path. Nothing already running is cut.</p> | |
| 35 | ${rows.length === 0 | |
| 36 | ? html`<p class="muted" data-no-holds>No file is held.</p>` | |
| 37 | : html`<ul class="list setting-list"> | |
| 38 | ${rows.map(({ repo, hold }) => | |
| 39 | row({ | |
outdated
This hand-rolls |
||
| 40 | title: html`<span class="mono">${hold.path}</span>`, | |
| 41 | meta: html`<a href="/${nameOf(repo)}/settings#file-holds">${nameOf(repo)}</a> · held by <span data-by>${hold.byName}</span> · ${time(hold.at)}`, | |
| 42 | data: { "file-hold": hold.path, repo: nameOf(repo) }, | |
| 43 | trail: html`<form method="post" action="/boards/holds"> | |
| 44 | <input type="hidden" name="repo" value="${nameOf(repo)}" /> | |
| 45 | <input type="hidden" name="path" value="${hold.path}" /> | |
| 46 | <input type="hidden" name="verb" value="release" /> | |
| 47 | ${btn("Release", { variant: "ghost" })} | |
| 48 | </form>`, | |
| 49 | }), | |
| 50 | )} | |
| 51 | </ul>`} | |
| 52 | <form method="post" action="/boards/holds"> | |
| 53 | <input type="hidden" name="verb" value="hold" /> | |
outdated
|
||
| 54 | ${field({ label: "Repository", name: "repo", id: "hold-repo", placeholder: "owner/name", mono: true, required: true, spellcheck: false })} | |
| 55 | ${field({ | |
| 56 | label: "Hold new work on", | |
| 57 | name: "path", | |
| 58 | id: "hold-path", | |
| 59 | placeholder: "src/http/mcp.ts", | |
| 60 | mono: true, | |
| 61 | required: true, | |
| 62 | spellcheck: false, | |
| 63 | hint: `A path in the repository, relative, at most ${MAX_HOLD_PATH} characters.`, | |
| 64 | })} | |
| 65 | <div class="form-actions">${btn("Hold file", { variant: "primary" })}</div> | |
| 66 | </form>`, | |
| 67 | { id: "file-holds" }, | |
| 68 | ); | |
| 69 | } |
src/web/pages/boards-view.ts +1 −1
| @@ -104,7 +104,7 @@ export async function boardsList(ctx: Ctx): Promise<Response> { | ||
| 104 | 104 | </ul>`, |
| 105 | 105 | { pad: false }, |
| 106 | 106 | ); |
| 107 | const flow = timePhase(ctx.request, "flow", () => flowPanel(ctx.app, { kind: "owner" }, ctx.url, "/boards")); | |
| 107 | const flow = timePhase(ctx.request, "flow", () => flowPanel(ctx.app, { kind: "owner" }, ctx.url, "/boards", ctx.auth.user)); | |
| 108 | 108 | const rendering = performance.now(); |
| 109 | 109 | const response = page({ |
| 110 | 110 | ctx, |
src/web/pages/file_holds.ts +29 −9
| @@ -1,21 +1,21 @@ | ||
| 1 | 1 | /** |
| 2 | 2 | * POST /:owner/:name/settings/holds — hold new work on a file, or release it. |
| 3 | 3 | * Through `adminForm`: an admin of the repository, same-origin, admin scope; |
| 4 | * the hold names the signed-in admin (`actions/file_holds.ts`). | |
| 4 | * the hold names the signed-in admin (`actions/file_holds.ts`). The flow panel | |
| 5 | * on /boards posts to `boardsHoldUpdate`, which names the repository itself. | |
| 5 | 6 | */ |
| 6 | 7 | |
| 7 | 8 | import { holdFileAs, releaseFileAs } from "../../actions/file_holds.ts"; |
| 9 | import { canAdmin, getRepo, type Repo } from "../../core/repos.ts"; | |
| 10 | import { MAX_HOLD_PATH } from "../../crew/file_holds.ts"; | |
| 8 | 11 | import type { Ctx } from "../../http/context.ts"; |
| 9 | import { repoBase } from "../chrome.ts"; | |
| 10 | import { field } from "../form.ts"; | |
| 12 | import { repoBase, repoNotFound } from "../chrome.ts"; | |
| 13 | import { field, readForm, type Form } from "../form.ts"; | |
| 11 | 14 | import { flashTo } from "../layout.ts"; |
| 12 | 15 | import { adminForm } from "./settings.ts"; |
| 13 | 16 | |
| 14 | export async function fileHoldUpdate(ctx: Ctx): Promise<Response> { | |
| 15 | const gate = await adminForm(ctx); | |
| 16 | if (gate instanceof Response) return gate; | |
| 17 | const { repo, form } = gate; | |
| 18 | const to = `${repoBase(repo)}/settings#file-holds`; | |
| 17 | /** Hold or release the form's path in `repo` (the caller has checked the admin), then flash back to `to`. */ | |
| 18 | function holdOrRelease(ctx: Ctx, repo: Repo, form: Form, to: string): Response { | |
| 19 | 19 | const path = field(form, "path"); |
| 20 | 20 | if (field(form, "verb") === "release") { |
| 21 | 21 | const released = releaseFileAs(ctx.app, ctx.auth.user, repo, path); |
| @@ -37,8 +37,28 @@ export async function fileHoldUpdate(ctx: Ctx): Promise<Response> { | ||
| 37 | 37 | tone: "danger", |
| 38 | 38 | message: |
| 39 | 39 | held.error === "invalid_path" |
| 40 | ? "A held path is relative, without .. or empty parts, and under 300 characters." | |
| 40 | ? `A held path is relative, without .. or empty parts, and at most ${MAX_HOLD_PATH} characters.` | |
| 41 | 41 | : "That file could not be held.", |
| 42 | 42 | }, |
| 43 | 43 | ); |
| 44 | 44 | } |
| 45 | ||
| 46 | export async function fileHoldUpdate(ctx: Ctx): Promise<Response> { | |
| 47 | const gate = await adminForm(ctx); | |
| 48 | if (gate instanceof Response) return gate; | |
| 49 | return holdOrRelease(ctx, gate.repo, gate.form, `${repoBase(gate.repo)}/settings#file-holds`); | |
| 50 | } | |
| 51 | ||
outdated
This repeats |
||
| 52 | /** | |
| 53 | * POST /boards/holds — the flow panel's hold and release, naming the repository | |
| 54 | * as `owner/name`. Same-origin, admin scope, and an admin of that repository: | |
| 55 | * anyone else is told the one not-found. | |
| 56 | */ | |
| 57 | export async function boardsHoldUpdate(ctx: Ctx): Promise<Response> { | |
| 58 | const form = await readForm(ctx, "admin"); | |
| 59 | if (form instanceof Response) return form; | |
| 60 | const [owner, name, extra] = field(form, "repo").trim().split("/"); | |
| 61 | const repo = owner && name && extra === undefined ? getRepo(ctx.app.db, owner, name) : undefined; | |
| 62 | if (!repo || !canAdmin(ctx.app.db, repo, ctx.auth.user)) return repoNotFound(ctx); | |
| 63 | return holdOrRelease(ctx, repo, form, "/boards#file-holds"); | |
| 64 | } |
src/web/pages/flow-panel.ts +4 −1
| @@ -42,6 +42,8 @@ import { readHeld } from "../../flow/held.ts"; | ||
| 42 | 42 | import type { App } from "../../app.ts"; |
| 43 | 43 | import { html, type Html } from "../html.ts"; |
| 44 | 44 | import { heldCard } from "./boards-held.ts"; |
| 45 | import { fileHoldsPanel } from "./boards-file-holds.ts"; | |
| 46 | import type { User } from "../../core/users.ts"; | |
| 45 | 47 | import { badge, card, meter } from "../ui.ts"; |
| 46 | 48 | |
| 47 | 49 | /** What `?out=` and `?hour=` ask to list, checked: an unknown stage or hour lists nothing. */ |
| @@ -88,7 +90,7 @@ function outCell(base: string, t: StageThroughput): Html { | ||
| 88 | 90 | } |
| 89 | 91 | |
| 90 | 92 | /** The panel for `reader`; `base` is the page it sits on, where its counts link. */ |
| 91 | export function flowPanel(app: App, reader: Reader, url: URL, base: string): Html { | |
| 93 | export function flowPanel(app: App, reader: Reader, url: URL, base: string, viewer?: User): Html { | |
| 92 | 94 | const now = Date.now(); |
| 93 | 95 | const stages = readPipeline(app.db, new Date(now)); |
| 94 | 96 | const worst = bottleneck(stages); |
| @@ -192,6 +194,7 @@ export function flowPanel(app: App, reader: Reader, url: URL, base: string): Htm | ||
| 192 | 194 | )} |
| 193 | 195 | ${hotFilesCard(app, reader)} |
| 194 | 196 | ${heldCard(readHeld(app, reader.kind === "owner", now))} |
| 197 | ${viewer === undefined ? null : fileHoldsPanel(app, viewer)} | |
| 195 | 198 | ${queueCard(queuesFor(app, reader, new Date(now), { batches: true }))} |
| 196 | 199 | ${listed === null || shown === undefined ? null : outList(shown, listed.hour, now)}`; |
| 197 | 200 | } |
test/boards-file-holds.test.ts added +112
| @@ -0,0 +1,112 @@ | ||
| 1 | /** | |
| 2 | * The flow panel on /boards lists held files with who held them and when, a | |
| 3 | * Release button per row and a form to hold a path, both same-origin POSTs to | |
| 4 | * /boards/holds; a non-admin is shown no holds and refused, as in the terminal. | |
| 5 | */ | |
| 6 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; | |
| 7 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 8 | import { tmpdir } from "node:os"; | |
| 9 | import { join } from "node:path"; | |
| 10 | import { createApp, type App } from "../src/app.ts"; | |
| 11 | import { createRepo } from "../src/actions/repos.ts"; | |
| 12 | import { createUser, type User } from "../src/core/users.ts"; | |
| 13 | import { heldFiles } from "../src/crew/file_holds.ts"; | |
| 14 | import type { Repo } from "../src/core/repos.ts"; | |
| 15 | import { fileHoldsPanel } from "../src/web/pages/boards-file-holds.ts"; | |
| 16 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 17 | ||
| 18 | describe("held files on the flow panel", () => { | |
| 19 | let dir: string; | |
| 20 | let app: App; | |
| 21 | let servers: Servers; | |
| 22 | let alice: User; | |
| 23 | let bob: User; | |
| 24 | let repo: Repo; | |
| 25 | ||
| 26 | const person = async (username: string, first = false): Promise<User> => { | |
| 27 | const made = await createUser(app.db, { | |
| 28 | origin: "seed", | |
| 29 | trusted: true, | |
| 30 | username, | |
| 31 | email: `${username}@forge.local`, | |
| 32 | password: "a-good-passphrase", | |
| 33 | adminIfFirst: first, | |
| 34 | }); | |
| 35 | if (!made.ok) throw new Error(made.error); | |
| 36 | return made.value; | |
| 37 | }; | |
| 38 | const cookieOf = async (username: string): Promise<string> => | |
| 39 | ( | |
| 40 | ( | |
| 41 | await fetch(`${servers.url}/signin`, { | |
| 42 | method: "POST", | |
| 43 | body: new URLSearchParams({ username, password: "a-good-passphrase" }), | |
| 44 | redirect: "manual", | |
| 45 | }) | |
| 46 | ).headers.get("set-cookie") ?? "" | |
| 47 | ).split(";")[0]!; | |
| 48 | const post = (cookie: string, body: Record<string, string>, origin = servers.url) => | |
| 49 | fetch(`${servers.url}/boards/holds`, { | |
| 50 | method: "POST", | |
| 51 | headers: { cookie, origin }, | |
| 52 | body: new URLSearchParams(body), | |
| 53 | redirect: "manual", | |
| 54 | }); | |
| 55 | ||
| 56 | beforeAll(async () => { | |
| 57 | dir = await mkdtemp(join(tmpdir(), "boards-holds-")); | |
| 58 | app = createApp({ dataDir: dir, port: 0 }); | |
| 59 | alice = await person("alice", true); | |
| 60 | bob = await person("bob"); | |
| 61 | servers = await serve(app); | |
| 62 | const made = await createRepo(app, alice, { name: "garden", visibility: "public" }); | |
| 63 | if (!made.ok) throw new Error(String(made.error)); | |
| 64 | repo = made.value; | |
| 65 | }); | |
| 66 | afterAll(async () => { | |
| 67 | servers.stop(); | |
| 68 | app.close(); | |
| 69 | await rm(dir, { recursive: true, force: true }); | |
| 70 | }); | |
| 71 | ||
| 72 | test("an admin holds a path from the panel, sees it listed with a Release button, and releases it", async () => { | |
| 73 | const cookie = await cookieOf("alice"); | |
| 74 | const res = await post(cookie, { repo: "alice/garden", path: "src/a.ts", verb: "hold" }); | |
| 75 | expect(res.status).toBe(303); | |
| 76 | expect(heldFiles(app.db, repo.id).map((h) => h.path)).toEqual(["src/a.ts"]); | |
| 77 | ||
| 78 | const page = await (await fetch(`${servers.url}/boards`, { headers: { cookie } })).text(); | |
| 79 | expect(page).toContain('data-file-hold="src/a.ts"'); | |
| 80 | expect(page).toContain("held by <span data-by>alice</span>"); | |
| 81 | expect(page).toContain('name="verb" value="release"'); | |
| 82 | expect(page).toContain('id="hold-path"'); | |
| 83 | ||
| 84 | expect((await post(cookie, { repo: "alice/garden", path: "src/a.ts", verb: "release" })).status).toBe(303); | |
| 85 | expect(heldFiles(app.db, repo.id)).toEqual([]); | |
| 86 | const after = await (await fetch(`${servers.url}/boards`, { headers: { cookie } })).text(); | |
| 87 | expect(after).toContain("data-no-holds"); | |
| 88 | }); | |
| 89 | ||
| 90 | test("a non-admin sees no holds and is refused", async () => { | |
| 91 | const cookie = await cookieOf("alice"); | |
| 92 | await post(cookie, { repo: "alice/garden", path: "src/b.ts", verb: "hold" }); | |
| 93 | expect(fileHoldsPanel(app, bob)).toBeNull(); | |
| 94 | expect(fileHoldsPanel(app, alice)!.toString()).toContain('data-file-hold="src/b.ts"'); | |
outdated
This assertion pins the leak: bob does not administer |
||
| 95 | ||
| 96 | const bobCookie = await cookieOf("bob"); | |
| 97 | const bobPage = await (await fetch(`${servers.url}/boards`, { headers: { cookie: bobCookie } })).text(); | |
| 98 | expect(bobPage).not.toContain('data-file-hold="src/b.ts"'); | |
| 99 | expect((await post(bobCookie, { repo: "alice/garden", path: "src/c.ts", verb: "hold" })).status).toBe(404); | |
| 100 | expect((await post(bobCookie, { repo: "alice/garden", path: "src/b.ts", verb: "release" })).status).toBe(404); | |
| 101 | expect(heldFiles(app.db, repo.id).map((h) => h.path)).toEqual(["src/b.ts"]); | |
| 102 | }); | |
| 103 | ||
| 104 | test("a cross-origin post, a bad repository and a bad path change nothing", async () => { | |
| 105 | const cookie = await cookieOf("alice"); | |
| 106 | expect((await post(cookie, { repo: "alice/garden", path: "src/d.ts", verb: "hold" }, "https://evil.example")).status).toBe(403); | |
| 107 | expect((await post(cookie, { repo: "alice/nope", path: "src/d.ts", verb: "hold" })).status).toBe(404); | |
| 108 | expect((await post(cookie, { repo: "alice/garden/x", path: "src/d.ts", verb: "hold" })).status).toBe(404); | |
| 109 | expect((await post(cookie, { repo: "alice/garden", path: "../d.ts", verb: "hold" })).status).toBe(303); | |
| 110 | expect(heldFiles(app.db, repo.id).map((h) => h.path)).toEqual(["src/b.ts"]); | |
| 111 | }); | |
| 112 | }); |
Minor: this is appended after the list of docs at the end of the front page. Move it next to the README's /boards or flow-panel text.