Files
Project-SDE-WP-Suite/docs/waves/wave-12.md
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

12 KiB

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_ids 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:

  • each of the four bulk actions is callable with a list of user ids and a single set of parameters
  • a batch containing the actor's own account rejects only that row, not the whole batch — verified for disable, demote, and delete
  • a super user's batch that includes a user/project outside what they manage rejects only that row, with a stated reason
  • every successful row produces its own AuditLog entry, identical in shape to what the single-user endpoint would have written
  • 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:

  • select-all selects exactly the rows currently visible under the active filter, not the full unfiltered table
  • 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
  • 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:

  • role change, activate/disable, and project assignment each work end to end against a multi-row selection
  • the confirmation dialog names the exact affected count before anything is sent
  • a batch with a partial failure shows which rows failed, not just an undifferentiated error
  • 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:

  • 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
  • the same permission/self-action guards from T12.1 apply here — a CSV cannot reach a user a checkbox-driven batch couldn't
  • 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:

  • the affected usernames are listed in the confirmation dialog before delete is sent
  • the request is not sent until the confirmation phrase is typed correctly
  • 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:

  • all CR-020 acceptance criteria in decisions-2026-09-17.md are met or a failure is stated with a reason
  • screenshots committed
  • smoke test and seed_demo.py both still pass
  • full test suite passes

Wave 12 exit criteria

  • all four bulk actions work against both a checkbox selection and a CSV upload
  • every existing single-user guardrail (self-action, scope, grantable roles) holds under bulk use
  • bulk delete requires typed confirmation and lists affected usernames
  • partial failures are always reported, never hidden behind a blanket success
  • 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.