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.
264 lines
12 KiB
Markdown
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.
|