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

Closed opened this
Closed without merging

scout/forge:scout/6525-the-flow-panel-on-boards-lists-held-file → main 3 commits fork 9 threads · 9 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
8 files changed +229 −12
README.md +2
@@ -389,3 +389,5 @@ This page is the front door. Everything else is a file of its own under
389389
390390 - [`docs/DESIGN.md`](docs/DESIGN.md) — the design system's spine; its sections are under `docs/design/sections/`.
391391 - [`docs/SPIKE-CLOUDFLARE.md`](docs/SPIKE-CLOUDFLARE.md), [`docs/AUDIT-MANY-HANDS.md`](docs/AUDIT-MANY-HANDS.md), [`docs/BACKLOG.md`](docs/BACKLOG.md) and [`docs/research/`](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.

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.

src/crew/file_holds.ts +10
@@ -66,3 +66,13 @@ export function heldFiles(db: Database, repoId: string): FileHold[] {
6666 .all(repoId)
6767 .map((r) => ({ repoId: r.repo_id, path: r.path, by: r.by, at: r.at }));
6868 }
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 {
339339 agentUpdate,
340340 crewPage,
341341 } from "../web/pages/crew.ts";
342 import { fileHoldUpdate } from "../web/pages/file_holds.ts";
342 import { boardsHoldUpdate, fileHoldUpdate } from "../web/pages/file_holds.ts";
343343 import { newPullPage, newPullSubmit } from "../web/pages/pulls.ts";
344344 import {
345345 pullPage,
@@ -885,6 +885,7 @@ export function buildRouter(): Router<Handler> {
885885 router.add("GET", "/settings/capacity", capacityPage);
886886 router.add("POST", "/settings/capacity", capacitySet);
887887 router.add("GET", "/boards", boardsList);
888 router.add("POST", "/boards/holds", boardsHoldUpdate);
888889 router.add("GET", "/boards/data", boardsPage);
889890 router.add("POST", "/boards/new", boardNew);
890891 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: canRead is the wrong gate. Every other door to the holds list (listFileHolds, the terminal screen, the MCP tool) answers only an admin of the repository. Gate the row on listFileHolds(app, viewer, r).ok, or build the rows from what listFileHolds returns.

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 canAdmin && listFileHolds(...).ok check is redundant. As written, it also runs a holds query once per row rather than once per repository.

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 <li class="row"> with spans directly inside, which skips the row() component's structure (.row-main, .row-title, .row-meta, .row-trail). Use row({ title: html<span class="mono">${hold.path}</span>, meta: html<a href=…>${nameOf(repo)}</a> · held by <span data-by>…</span> · ${time(hold.at)}, data: { "file-hold": hold.path, repo: nameOf(repo) }, trail: releaseForm }), as src/web/studio/file_holds.ts:37 already does.

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

.bar is a one-line toolbar, but this form holds two stacked field()s with hints. Match the settings card: a plain post form with the button in <div class="form-actions">.

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> {
104104 </ul>`,
105105 { pad: false },
106106 );
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));
108108 const rendering = performance.now();
109109 const response = page({
110110 ctx,
src/web/pages/file_holds.ts +29 −9
@@ -1,21 +1,21 @@
11 /**
22 * POST /:owner/:name/settings/holds — hold new work on a file, or release it.
33 * 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.
56 */
67
78 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";
811 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";
1114 import { flashTo } from "../layout.ts";
1215 import { adminForm } from "./settings.ts";
1316
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 {
1919 const path = field(form, "path");
2020 if (field(form, "verb") === "release") {
2121 const released = releaseFileAs(ctx.app, ctx.auth.user, repo, path);
@@ -37,8 +37,28 @@ export async function fileHoldUpdate(ctx: Ctx): Promise<Response> {
3737 tone: "danger",
3838 message:
3939 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.`
4141 : "That file could not be held.",
4242 },
4343 );
4444 }
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 fileHoldUpdate's body; only the gate and to differ. Move the shared part into one helper, so the two routes cannot drift apart.

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";
4242 import type { App } from "../../app.ts";
4343 import { html, type Html } from "../html.ts";
4444 import { heldCard } from "./boards-held.ts";
45 import { fileHoldsPanel } from "./boards-file-holds.ts";
46 import type { User } from "../../core/users.ts";
4547 import { badge, card, meter } from "../ui.ts";
4648
4749 /** 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 {
8890 }
8991
9092 /** 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 {
9294 const now = Date.now();
9395 const stages = readPipeline(app.db, new Date(now));
9496 const worst = bottleneck(stages);
@@ -192,6 +194,7 @@ export function flowPanel(app: App, reader: Reader, url: URL, base: string): Htm
192194 )}
193195 ${hotFilesCard(app, reader)}
194196 ${heldCard(readHeld(app, reader.kind === "owner", now))}
197 ${viewer === undefined ? null : fileHoldsPanel(app, viewer)}
195198 ${queueCard(queuesFor(app, reader, new Date(now), { batches: true }))}
196199 ${listed === null || shown === undefined ? null : outList(shown, listed.hour, now)}`;
197200 }
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 alice/garden, so he should not see its holds. Assert not.toContain('data-file-hold="src/b.ts"') instead.

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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs