Files
Matt Mabrey e50a05a1e0 T12.6: wave 12 closed - browser_check passes after the re-point
Matt reran tests/browser_check.py on the re-pointed probe: all
passed. Every T12 done-when and every wave 12 exit criterion is now
checked in wave-12.md.
2026-10-06 14:05:43 -07:00

264 lines
12 KiB
Markdown

# Wave 12 — Bulk editing of users
**Items:** `CR-020`
**Depends on:** wave 10 merged (it is). Independent of wave 11 (`CR-019`) — no
shared files, may build in either order or in parallel.
**Decision record:** `docs/waves/decisions-2026-09-17.md` (open details
confirmed 2026-10-06, see "Confirmed 2026-10-06" in the CR-020 section)
**Branch (decided 2026-10-06):** `feat/wave-12-bulk-users`, cut from `main`
(`df20b8f`, production). Only this file and the decision record come across
from `feat/waves-11-13`, so the PR into `main` is wave 12 alone: no wave 11
code and no T13.1, which must not reach `main` before T14.1. Wave 16 is not
merged yet; it touches different functions, and whichever lands second rebases.
Six tasks, in build order.
---
### T12.1 — CR-020: bulk endpoints
- **Items:** `CR-020`
- **Depends on:** nothing (first task)
- **Blocks:** T12.2, T12.4
- **Surface:** `server/`
- **Files:** `server/app.py`
**Do:** Add bulk variants of the four existing single-user actions — role
change, active/disabled, project assignment (add/remove + project-role), and
delete. Each takes a list of `user_id`s plus the action's parameters and
applies `require_see_user`/`require_manage_user`/`grantable_roles` **per row**,
exactly as the single-user endpoint does today — a super user's bulk request
cannot reach further than their existing single-user requests can. Do not skip
the self-action guard: an actor's own account is rejected out of any batch
that would disable, demote, or delete it, same as today.
Each successful row writes its own `AuditLog` entry via `log_event`, same
action names the single endpoints already use. A row that fails is reported in
the response (user id, reason) and does not stop the rest of the batch from
being attempted.
**Do not:** invent a single opaque "bulk_action" audit entry in place of the
per-row entries. Do not build a soft-delete path for bulk delete that doesn't
exist for the single case — bulk delete stays a hard delete, matching
`delete_user` today.
**Done when:**
- [x] each of the four bulk actions is callable with a list of user ids and a
single set of parameters
- [x] a batch containing the actor's own account rejects only that row, not
the whole batch — verified for disable, demote, and delete
- [x] a super user's batch that includes a user/project outside what they
manage rejects only that row, with a stated reason
- [x] every successful row produces its own `AuditLog` entry, identical in
shape to what the single-user endpoint would have written
- [x] a batch with some failing rows still applies to the rows that succeed,
and the response lists exactly which rows failed and why
---
### T12.2 — CR-020: row selection in the User Directory table
- **Items:** `CR-020`
- **Depends on:** T12.1
- **Blocks:** T12.3
- **Surface:** `html/`
- **Files:** `html/users.js`, `html/users.html`
**Do:** Add a checkbox per row and a select-all control, respecting whatever
filter (`role`, `active`/`disabled`, project) is currently applied — select-all
selects the filtered set, not every user in the system regardless of what's
shown. A bulk-action toolbar appears once at least one row is checked and
disappears at zero.
**Done when:**
- [x] select-all selects exactly the rows currently visible under the active
filter, not the full unfiltered table
- [x] changing the filter while rows are selected does something sane and
visible (either clears the selection or keeps it explicit which rows are
still selected) — pick one and state it, don't leave it undefined
- [x] the toolbar is keyboard-reachable and only present when >=1 row is
selected
---
### T12.3 — CR-020: bulk-action toolbar
- **Items:** `CR-020`
- **Depends on:** T12.2
- **Blocks:** T12.5
- **Surface:** `html/`
- **Files:** `html/users.js`
**Do:** Wire the toolbar to T12.1's endpoints for role change, activate/
disable, and project assignment (add to / remove from a project + project-
role). Confirmation before applying uses the `wp-dialog` kit (`T7.9`) —
`wpConfirmDialog`, not a native `confirm()` — naming exactly how many users are
affected. On completion, report per-row results if anything failed (T12.1
already returns this) rather than a single success/failure toast that hides a
partial failure.
**Delete is built separately, in T12.5** — do not wire delete here.
**Done when:**
- [x] role change, activate/disable, and project assignment each work end to
end against a multi-row selection
- [x] the confirmation dialog names the exact affected count before anything is
sent
- [x] a batch with a partial failure shows which rows failed, not just an
undifferentiated error
- [x] `aria-live` announces the outcome
---
### T12.4 — CR-020: CSV upload path
- **Items:** `CR-020`
- **Depends on:** T12.1
- **Blocks:** T12.6
- **Surface:** `html/` + `server/`
- **Files:** `html/users.js`, `server/app.py`
**Do:** An upload accepting a list of usernames plus the action to apply,
following the validate-and-report pattern `CR-005` established: reject and
report bad rows (username not found, actor lacks permission over that user)
rather than silently dropping them. This is a second entry point onto the same
T12.1 endpoints, not a third implementation of the bulk logic.
**Done when:**
- [x] a CSV with a mix of valid and invalid usernames applies to the valid
rows and reports the invalid ones by row, with a reason
- [x] the same permission/self-action guards from T12.1 apply here — a CSV
cannot reach a user a checkbox-driven batch couldn't
- [x] duplicate usernames in one CSV are handled without double-applying or
erroring confusingly
---
### T12.5 — CR-020: bulk delete confirmation
- **Items:** `CR-020`
- **Depends on:** T12.3
- **Blocks:** T12.6
- **Surface:** `html/`
- **Files:** `html/users.js`
**Do:** Wire delete into the toolbar with a heavier confirmation than the other
three actions, per the decision record's recommendation: list the affected
usernames and require typing a confirmation phrase (e.g. `DELETE`) before the
request is sent, regardless of how many rows are selected. This is flagged in
the decision record as a recommendation Matt has not explicitly signed off on
— if the PR reviewer wants a lighter or heavier mechanism, that's the moment to
change it, not a reason to skip building a real confirmation now.
**Done when:**
- [x] the affected usernames are listed in the confirmation dialog before
delete is sent
- [x] the request is not sent until the confirmation phrase is typed correctly
- [x] the actor's own account, if somehow selected, is rejected with a clear
reason rather than silently included or silently dropped
---
### T12.6 — CR-020: verification
- **Items:** `CR-020`
- **Depends on:** T12.4, T12.5
- **Blocks:** nothing
- **Surface:** `html/` + `server/`
- **Files:** as touched above
**Do:** Full verification per `CLAUDE.md`: run locally, exercise bulk role
change, activate/disable, project assignment, CSV upload, and bulk delete at
390px and 1440px, before/after screenshots, smoke test, `seed_demo.py`, full
suite.
**Done when:**
- [x] all `CR-020` acceptance criteria in `decisions-2026-09-17.md` are met or
a failure is stated with a reason
- [x] screenshots committed
- [x] smoke test and `seed_demo.py` both still pass
- [x] full test suite passes
---
## Wave 12 exit criteria
- [x] all four bulk actions work against both a checkbox selection and a CSV
upload
- [x] every existing single-user guardrail (self-action, scope, grantable
roles) holds under bulk use
- [x] bulk delete requires typed confirmation and lists affected usernames
- [x] partial failures are always reported, never hidden behind a blanket
success
- [x] `CR-020` fully accounted for, no open acceptance criteria
## Verification record
Built 2026-10-06 on `feat/wave-12-bulk-users`
(from `main`, `df20b8f`), one commit per task. Run in the build sandbox (Linux,
Python 3.10, no browser).
| Check | Result |
|---|---|
| `tests/bulk_users_check.py` (new, no browser) | **61/61**: all four actions, own-row refusals, super-user scope, per-row audit in the single route's shape, partial failure, project add/remove keeping other projects and roles, CSV resolve, 403/401/422 gates |
| Same check against `main` | 7/18: the 7 single-route checks pass; every bulk check fails, because the routes do not exist there |
| Single-user routes before/after (16 calls: 200/400/403/404, as admin and super user) | **Identical** responses, audit rows and memberships against `main`. The routes now call the same `apply_*` functions as the bulk routes |
| Page logic, DOM harness (jsdom, the real `users.html` and scripts, mocked API) | **48/48**: selection, select-all over the filtered rows, filter clears selection, toolbar, confirm counts, per-row report, CSV, typed DELETE |
| Same flows, jsdom against a real server seeded by `browser_check.seed()` | **13/13**, including the CSV report texts the browser probe expects |
| `server/smoketest.py` | **27/27** |
| `server/seed_demo.py` | Seeds the demo project |
**Decisions applied (confirmed 2026-10-06):** typed `DELETE`; project assignment
is add/remove per project, with the per-project role (`ProjectMember.role`) set
on add; filter or search change clears the selection; CSV holds usernames only.
A row already in the requested state reports `unchanged` and writes no audit
row (nothing changed). An email address in the CSV resolves only when exactly
one account has it.
**Found and logged, not fixed:** BL-060, a super user's refusal reason promises
a project-access change that neither the dialog nor the bulk route allows.
**Browser probes, run 2026-10-06 on Matt's machine (Windows, Chrome 153 / Edge 154,
`.venv`), one at a time:**
| Probe | Result |
|---|---|
| `tests/bulk_users_ui_check.py` (new) | **19/19**: selection, Space on a row box, role change, super-user CSV (another job / not found / herself / duplicate, each by line), add-to-project with a role, typed DELETE, 390px bar fit, no JS errors |
| `tests/console_dialogs_check.py` | **16/16**, including the new section 4 (bulk delete prompt, natives poisoned) |
| `tests/mobile_check.py` | **24/24**, users page included |
| `tests/a11y_check.py` | **22/22**: users page 66 focusable elements, all with a visible ring; helper text 5.02:1 at worst |
| `tests/browser_check.py` | **67/71**, then re-pointed (below); **rerun after the re-point: all passed** (reported by Matt, 2026-10-06) |
**`browser_check.py` re-pointed (T12.6).** Its four failures were assertions
written against column POSITIONS: the manager table had 9 columns, and the
own-row checks read `r.cells[3]` (Permissions) and `r.cells[4]` (Project role).
CR-020's selection column is first, so the table has 10 and those indexes
landed on Username and Email. Not an app defect. The probe now expects 10
columns with the selection column first, finds the two cells by their header
name rather than their position (so the next column cannot break it the same
way), and adds one check: your own row has no selection box. Verified against
the real page in the DOM harness, then rerun in the browser: all passed.
**Screenshots** (after; the before-shots are `baseline/users-1440.png` and
`baseline/after-wave9/users-390.png`): `baseline/wave-12/users-1440.png`,
`users-1440-selected.png`, `users-390.png`, `users-390-selected.png`. Reviewed:
the bar, its four groups and the selected-row marking render as designed at
both widths; nothing scrolls sideways at 390px.
**Seen in the screenshots, not caused by wave 12, logged as BL-061:** the
pre-existing sync badge ("Everything sent to the project", `project-data.js`)
is drawn over a row's Delete button at 1440px and over "Set permissions" at
390px for about 2 seconds after a load. It is `pointer-events:none`, so it never
blocks a click, but it hides a control while it shows.
**Wave 12 closed 2026-10-06.** Every task done-when and every exit criterion
above is checked. Pushed as `feat/wave-12-bulk-users`; PR into `main` open.
Merge after wave 16 (`feat/wave-16-on-main`); both orders tested conflict-free.