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

The flow panel on /boards now has a "Held files" card. It lists every held path in each repository the viewer can read, with the repository, who held it and when. Type check, design lint and the new test pass, along with the related holds and flow-panel tests.

Notes

stopped closed without shipping deploy c94ad22

opened this

The flow panel on /boards now has a "Held files" card. It lists every held path in each repository the viewer can read, with the repository, who held it and when. Type check, design lint and the new test pass, along with the related holds and flow-panel tests.

  • Admin of a repository: its rows get a Release button, and the card gets a "Repository (owner/name) + path" form to hold another file.
  • Everyone else: they see the list with no controls.
  • Route: the Release button and the hold form both post to a new route, POST /boards/holds. It goes through the same same-origin and admin-scope check as the settings form and uses the existing holdFileAs / releaseFileAs. A cross-origin post gets 403. A non-admin or unknown repository gets 404, and a bad path flashes the usual error.
  • Where: the card is src/web/pages/boards-file-holds.ts, drawn by flowPanel for a signed-in viewer. The handler boardsHoldUpdate is in src/web/pages/file_holds.ts, and allHeldFiles is added to src/crew/file_holds.ts.
  • Tests: test/boards-file-holds.test.ts covers hold, list, release, a non-admin's view and refusal, and a cross-origin post, a bad repository and a bad path.

I left out a repository dropdown. The hold form takes owner/name as text, because a dropdown of every repository the viewer administers could be long. The settings-page card is unchanged.

Closes #6525

8 earlier comments · 3 events
commented

The flow panel on /boards now has a "Held files" card. It lists every held path in each repository the viewer can read, with the repository, who held it and when. Type check, design lint and the new test pass, along with the related holds and flow-panel tests.

  • Admin of a repository: its rows get a Release button, and the card gets a "Repository (owner/name) + path" form to hold another file.
  • Everyone else: they see the list with no controls.
  • Route: the Release button and the hold form both post to a new route, POST /boards/holds. It goes through the same same-origin and admin-scope check as the settings form and uses the existing holdFileAs / releaseFileAs. A cross-origin post gets 403. A non-admin or unknown repository gets 404, and a bad path flashes the usual error.
  • Where: the card is src/web/pages/boards-file-holds.ts, drawn by flowPanel for a signed-in viewer. The handler boardsHoldUpdate is in src/web/pages/file_holds.ts, and allHeldFiles is added to src/crew/file_holds.ts.
  • Tests: test/boards-file-holds.test.ts covers hold, list, release, a non-admin's view and refusal, and a cross-origin post, a bad repository and a bad path.

I left out a repository dropdown. The hold form takes owner/name as text, because a dropdown of every repository the viewer administers could be long. The settings-page card is unchanged.

Changes requested — before the latest push

The route is sound. It goes through readForm(ctx, "admin"), so it gets the same-origin check, the token scope and a body capped by the bytes read. It then checks canAdmin on the named repository and calls the existing holdFileAs / releaseFileAs, so by is the verified actor. On the preview, /boards sends a guest to sign-in, and a guest's POST to /boards/holds gets 403.

High: the card shows holds to people the hold action is meant to hide them from. actions/file_holds.ts lists holds for an admin of the repository only (listFileHolds: "anyone else is told nothing"). The terminal's fileholds screen and the MCP hold tool follow that rule. fileHoldsPanel skips it: it reads allHeldFiles directly and filters with canRead. So any signed-in user who can read a repository sees its held paths and the admins who held them. That is every user, for a public repository, since /boards only needs a sign-in. The test pins the leak too: bob, a non-admin, is expected to see src/b.ts.

Fix first: draw only the rows of repositories where listFileHolds(app, viewer, repo).ok is true. Better, build the card from listFileHolds, which already names the holder, and drop allHeldFiles or keep it as a pure read the action layer gates. Then flip the non-admin test so it expects bob to see none of alice's holds. With that change, the web panel and the terminal give the same answer.

Also to fix in this round:

  • boardsHoldUpdate copies fileHoldUpdate almost line for line, including the hard-coded "under 300 characters" next to MAX_HOLD_PATH. Move the hold/release-and-flash logic into one helper that takes (ctx, repo, form, to), and call it from both routes.
  • The README does not mention the new card or POST /boards/holds. Add one line next to the existing file-hold docs saying how to hold and release from /boards.
  • Imports in pages/file_holds.ts are reordered for no reason (readForm sits after layout.ts, core/repos comes before actions). Keep the file's existing order.
commented

The flow panel on /boards now has a "Held files" card for admins: it lists each hold with who set it and when, a Release button on each, and a form that holds a path. The type check, design lint and the holds and flow-panel tests pass.

Review changes

  • Who sees holds: the card is built from listFileHolds, the same admin-only answer the terminal and the MCP give, so bob no longer sees alice's holds. A viewer who administers no repository with holds, and isn't a forge admin, gets no card. The test now expects bob's /boards page to show none of alice's holds.
  • Shared handler: the hold and release logic is one helper, holdOrRelease(ctx, repo, form, to), used by both the settings route and POST /boards/holds. The error text now uses MAX_HOLD_PATH instead of a hard-coded 300.
  • Imports: pages/file_holds.ts keeps its original import order.
  • README: one paragraph explains how to hold and release from /boards. There were no existing file-hold docs to put it next to, so it is added at the end.

Where I differ from the issue: it asked that non-admins see the list without the controls. Following the review, they see no holds and no card at all, which matches the terminal and the MCP.

Try it: sign in as a forge admin, open /boards, hold owner/name plus a path, then press Release on the row.

Changes requested — before the latest push

The security is sound. POST /boards/holds goes through readForm(ctx, "admin"), so it gets the same-origin check and admin scope; it checks canAdmin on the named repository and answers 404 to everyone else. The list goes through listFileHolds, the same admin door the terminal and the MCP use. Every output passes through html and is escaped. The tests cover hold, release, a non-admin, a cross-origin post, a bad repository and a bad path. On the preview, /boards sends a guest to sign in and a post with no session is refused (403).

The design is a change request. The new card hand-rolls its list rows instead of using the named row() component (docs/design/sections/5-components.md, "list row"). <li class="row"> with bare spans inside skips .row-main, .row-title, .row-meta and .row-trail, so the row's layout, its one-line meta and its trailing control don't apply. The repository already draws this exact list correctly in src/web/studio/file_holds.ts:37: row({ title, meta, data: { "file-hold": path }, trail: <release form> }) inside <ul class="list setting-list">.

Fix first: build each row with row() the way the studio card does, with the repo link in meta, the Release form in trail and data: { "file-hold", repo }. Then put the hold form's button in <div class="form-actions"> like the settings card, rather than putting class="bar" on a form of stacked fields. Keep the existing data-file-hold and data-by hooks so the tests still hold.

commented

The "Held files" card on /boards now builds its rows the way the studio card does. I pushed the change; the type check, design lint and the two hold tests pass.

  • Rows: each row is a row() inside <ul class="list setting-list">. The path is the title. The meta line has the repository link, "held by" the holder, and the time. The Release form is the trailing control. The data-file-hold, data-repo and data-by hooks are kept.
  • Hold form: it is now a plain post form, like the settings card's, with the Hold button in <div class="form-actions"> instead of class="bar".

Nothing else changed. The card is still shown only to admins of the repository, and holding or releasing still goes through POST /boards/holds.

Changes requested

The handler is sound. POST /boards/holds goes through readForm(ctx, "admin"), so it gets the same-origin check, the admin scope and a body capped by the bytes read. Anyone who is not an admin, or names an unknown repository, gets the one 404, and the write goes through holdFileAs/releaseFileAs, which name the verified actor. The rows come from listFileHolds, so a reader is shown nothing private, and the TUI file-holds screen and the MCP hold tool cover the other doors. The card uses card/row/field/btn, a .setting-list and .form-actions, with plain post forms that work with JavaScript off. On the preview, /boards answers 200 and shows no card to a guest, a same-origin post with no session is refused 403, and a cross-origin post is refused 403.

What does not work, fix first: the issue asks for a form to hold a file on /boards, but most of the admins it is for never see that form. fileHoldsPanel returns null unless the viewer is a forge admin or already has a hold listed. So an ordinary owner of a repository whose first hold is not set yet sees no card at all, and has to go to settings to make the first hold. Only after that does the /boards form appear. The test misses this because alice is the first user, which makes her a forge admin, and bob owns no repository.

Fix: show the card, with the empty state and the form, whenever the viewer administers at least one repository. listReposOwnedBy(app.db, viewer.id) plus the org repositories where canAdmin holds would do, or a small administersAny helper. Add a test where bob creates his own repository, holds nothing, and /boards shows him id="hold-path". That test fails on this head.

Minor, not blocking: the README paragraph sits at the very end, under the list of other documents, where nobody looking for /boards will find it. Move it next to where the README talks about /boards or the flow panel.

commented

Handed to a person by the crew: the reviewer asked for changes three times with no approval between, so the planner re-scopes it: split, replaced, or one more round with the reviewer's ask restated.

  1. sentinel:

The route is sound. It goes through readForm(ctx, "admin"), so it gets the same-origin check, the token scope and a body capped by the bytes read. It then checks canAdmin on the named repository and calls the existing holdFileAs / releaseFileAs, so by is the verified actor. On the preview, /boards sends a guest to sign-in, and a guest's POST to /boards/holds gets 403.

High: the card shows holds to people the hold action is meant to hide them from. actions/file_holds.ts lists holds for an admin of the repository only (listFileHolds: "anyone else is told nothing").

  • src/web/pages/boards-file-holds.ts:25: 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,
  • src/web/pages/boards-file-holds.ts:30: 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.
  • test/boards-file-holds.test.ts:94: 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.
  • src/web/pages/file_holds.ts:51: 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.
  • src/web/pages/file_holds.ts:79: The 300 is hard-coded here, next to MAX_HOLD_PATH. Use the constant, as the card's hint already does.
  1. sentinel:

The security is sound. POST /boards/holds goes through readForm(ctx, "admin"), so it gets the same-origin check and admin scope; it checks canAdmin on the named repository and answers 404 to everyone else. The list goes through listFileHolds, the same admin door the terminal and the MCP use. Every output passes through html and is escaped. The tests cover hold, release, a non-admin, a cross-origin post, a bad repository and a bad path. On the preview, /boards sends a guest to sign in and a post with no session is refused (403).

The design is a change request.

  • src/web/pages/boards-file-holds.ts:39: 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=
  • src/web/pages/boards-file-holds.ts:53: .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">.
  1. sentinel:

The handler is sound. POST /boards/holds goes through readForm(ctx, "admin"), so it gets the same-origin check, the admin scope and a body capped by the bytes read. Anyone who is not an admin, or names an unknown repository, gets the one 404, and the write goes through holdFileAs/releaseFileAs, which name the verified actor. The rows come from listFileHolds, so a reader is shown nothing private, and the TUI file-holds screen and the MCP hold tool cover the other doors. The card uses card/row/field/btn, a .setting-list and .form-actions, with plain post forms that work w…

  • src/web/pages/boards-file-holds.ts:31: 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 a
  • README.md:393: 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.
commented

Planner, one more round, one change: draw the held-files card, with its hold form, for any viewer who administers at least one repository, even when no hold exists yet. Add a test where a repository owner who is not a forge admin and has no holds sees the form on /boards. Also move the README line next to the README's /boards or flow-panel text.

commented

One more round. The one change: draw the held-files card (with its hold form) for any viewer who administers at least one repository, even when they have no holds yet, not only when rows exist; add a test where a repository owner who is not a forge admin and has no holds sees the form and makes their first hold from /boards. While there, move the README note next to the existing /boards text rather than after the docs list. The earlier asks (admin-only rows via listFileHolds, row() component, MAX_HOLD_PATH, one shared helper) still stand where not yet done.

commented

Planner: this now lands as #6846, which replaces #6525. One concrete change: draw the Held files card with its hold form for any viewer who administers at least one repository, even with no holds yet. Add a test where an owner who is not a forge admin makes their first hold from /boards. Also move the README line next to the /boards flow-panel text. Rebase after #6840 (the /boards incident) lands, and add no read to the panel's load.

commented

Closed by the planner after three reviews asked for changes. The work continues as #6846, which says what done looks like now and folds in every review ask. This branch stays, and the builder of #6846 may start from it.

commented

Closed by the planner: the issue this pull was built for is closed.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs