From 286e629782ff2ae147316f7cb0a056d1c51d0a90 Mon Sep 17 00:00:00 2001 From: Matt Mabrey Date: Tue, 6 Oct 2026 10:53:29 -0700 Subject: [PATCH 1/9] wave 12: plan for CR-020 on a branch from main; details confirmed Brings docs/waves/wave-12.md and decisions-2026-09-17.md across from feat/waves-11-13 (planning docs only, no wave 11 or 13 code), so the PR into main is wave 12 alone. Confirmed 2026-10-06 by Matt Mabrey: typed DELETE for bulk delete; project assignment is add/remove per project; changing the filter clears the selection; the CSV holds usernames only. --- docs/waves/decisions-2026-09-17.md | 355 +++++++++++++++++++++++++++++ docs/waves/wave-12.md | 200 ++++++++++++++++ 2 files changed, 555 insertions(+) create mode 100644 docs/waves/decisions-2026-09-17.md create mode 100644 docs/waves/wave-12.md diff --git a/docs/waves/decisions-2026-09-17.md b/docs/waves/decisions-2026-09-17.md new file mode 100644 index 0000000..901385b --- /dev/null +++ b/docs/waves/decisions-2026-09-17.md @@ -0,0 +1,355 @@ +# Decisions — September 17, 2026 + +Three items. Like `D11`, `D15`, `D16` and `D17`, these are new scope raised after +R2 closed out (see `docs/reference/completion.md`, T9.7), not a reopening of +anything already decided there. + +`CR-019` and `CR-020` get `CR` ids because they are field/product-facing feature +requests — the same kind of thing `CR-001`-`CR-018` were — not internal +engineering calls made mid-build. `D18` gets a `D` id because it is exactly that: +an internal security/architecture call, the same category as `D15` (Okta vs. +LDAPS), not a feature a user asked for. + +Requested/raised by Matt Mabrey, 2026-09-17. + +--- + +## CR-019 — Usage and activity metrics (admin console) + +- **Area:** Admin Console / Monitoring +- **Priority:** proposed High — the current admin console has no reliable way to + answer "who is using this and how much," which is the same visibility gap the + original UX review found in `B4` (numbers that look authoritative but are not). +- **Source:** Matt Mabrey, 2026-09-17. + +### Why this is not already built + +`D5`/`T7.10` already shipped a usage-analytics feature — `html/wp-usage.js`, with +a report at `admin.js:666-699` — but it reads `localStorage`, which is scoped to +one browser. The report's own empty state says exactly this: *"No usage recorded +in this browser yet."* It cannot show who across the team is active or what they +use, because each person's activity exists only on their own machine. This is the +same class of defect `B4` named for the pipeline strip — a number that looks +authoritative but is not — just never generalized to this feature. `CR-019` is +therefore new server-side work, not a UI addition on top of what exists. + +Two things already in the schema are relevant and reused rather than duplicated: +`User.last_login_at` (one timestamp, no history) and `AuditLog` (append-only, +already records business mutations — WP created, status changed, role changed — +per user, with a timestamp). Neither captures navigation or feature-open events, +which is the actual gap. + +### Intent + +Give admins a real, server-backed picture of who is using the suite, what parts +of it they use, and how active they are — replacing the per-browser report as +the thing anyone actually looks at. + +### Decisions, made 2026-09-17 + +1. **Retention: indefinite.** No automatic purge of usage-event data. (Separate + from `AuditLog`'s own retention, which this does not change.) +2. **Scope: suite-wide, filterable.** Not per-project by default; the console + provides filters (date range, project, user, tool/page) rather than scoping + the data itself. +3. **Export: raw view shows real identities; export supports sanitization.** + The admin console's own tables and the CSV export both default to real + usernames — this is an internal audit tool, not a public one. But the export + also offers a "sanitize" toggle that replaces the actor with a **stable + pseudonymous id** (a per-user hash, consistent across rows and across + export runs) rather than dropping the identity field outright — so an + external system (Power BI or similar) can still group and trend "by user" + without ever receiving a real name. Flagged here as the recommended + approach rather than the only one Matt confirmed in so many words: if a + fully-anonymous (no stable id at all) export turns out to be what's + actually wanted, that is a one-line change to the same feature, raise it + in the PR rather than treating it as blocking. +4. **The old per-browser report is retired**, not kept alongside the new one. + Once `CR-019` ships, `admin.js`'s existing `usage-admin` panel (reading + `WPUsage.load(...)` per browser) is removed rather than left next to the + real report, where it would show a smaller, misleading number for whoever + happens to have it open. `html/wp-usage.js` and its two call sites + (`html/work-package-suite-app.js`'s wizard dwell-tracking, and the + creator's equivalent) are a separate question — the *recording* code can + stay or go independent of the *admin report* being retired, since dwell + events were never reliably tied to a real identity anyway. Default to + removing both unless a task finds a reason to keep the recorder; log that + reason rather than deciding it here. + +### Acceptance criteria + +- A new admin-only tab in `admin.html` (same role gate as the User Directory) + shows: active users over a selectable date range (day/week/month), each + user's last-active timestamp, and a breakdown of which tools/pages get + opened and how often. +- Server-side event capture, keyed to the authenticated session (real identity, + not a browser-local guess) — a new table, not an extension of `AuditLog`, + since page-open/navigation events are not business mutations and mixing them + in would make `AuditLog` noisy for its existing, narrower purpose. +- The console's filters cover date range, project, user, and tool/page, and + combine (e.g., "user X, last 30 days, field view only"). +- CSV export from the console, in both raw (real usernames) and sanitized + (stable pseudonymous id per user) modes. +- Retention is indefinite; nothing in this item purges data. +- View-only, refresh-on-load. No alerting — matches how the rest of the admin + console works today; if that changes later it is new scope, not a rider on + this item. +- The old per-browser "Usage" report and its admin-console panel are removed + in the same wave, not left running alongside the new one. +- Accessible per `CLAUDE.md`'s standing `C1` rules (this is a new component, + not a legacy one — it ships accessible or it is not done, same as + everything else built since wave 7). + +### Frontend/backend boundary + +This needs server work, the same way `CR-004`/`CR-018`/`B4` did: a real table, +a capture endpoint, an aggregation endpoint, and an export endpoint. If a task +under this item is being built by writing to `localStorage`, it is rebuilding +the exact defect this item exists to replace — stop and say so, per +`CLAUDE.md`. + +### Scheduling + +New wave. Wave 10 (Okta) is merged, so this does not wait on anything. +Task breakdown: `docs/waves/wave-11.md`. + +--- + +## CR-020 — Bulk editing of users in the admin console + +- **Area:** Admin Console / User Directory +- **Priority:** proposed High — three of the four actions below touch access + control (role, project assignment, active/disabled) and the fourth is a hard + delete; getting the guardrails right matters more than getting it built fast. +- **Source:** Matt Mabrey, 2026-09-17. + +### Why this is not already built + +Every user-editing action in `html/users.js` today is one row, one action: +a role ` - +
+ + +
+
Loading…
diff --git a/html/users.js b/html/users.js index 20ecb3e..064d6d0 100644 --- a/html/users.js +++ b/html/users.js @@ -23,6 +23,10 @@ let _users = []; // the directory as the server scoped it let _scope = null; // GET /api/auth/user-scope let _meId = null; +// CR-020: the rows checked for a bulk action. Client-side UI state only - every +// bulk action is decided and audited by the server, row by row (T12.1). +let _selected = new Set(); +let _shownSelectable = []; // ids the current filter shows AND this caller may select // ── boot ────────────────────────────────────────────────────────────────────── async function boot(){ @@ -90,11 +94,100 @@ async function loadUsers(){ } banner('users-banner','', ''); _users = json; + // Fresh data: any earlier selection may name accounts that changed or are gone. + clearSelection(false); renderUsers(); } function manages(){ return !!(_scope && _scope.can_manage_users); } +// ── selection (CR-020, T12.2) ───────────────────────────────────────────────── +// A row is selectable when this caller may change the account. Your own row is +// not: every bulk action that could touch it (disable, demote, delete) is refused +// for your own account, so offering it would only produce a guaranteed failure. +function selectable(u){ return manages() && !!u.manageable && u.id !== _meId; } + +// The search box and the filter both decide which rows are shown. Changing either +// clears the selection (decided 2026-10-06), so no row hidden by the filter can +// stay selected and be acted on without being seen. +function filterChanged(){ + const had = _selected.size; + clearSelection(false); + renderUsers(); + banner('sel-banner', '', had ? 'Selection cleared: the filter changed. Select the rows again.' : ''); +} + +function clearSelection(announce){ + const had = _selected.size; + _selected = new Set(); + updateSelectionUI(); + banner('sel-banner', '', (announce && had) ? 'Selection cleared.' : ''); +} + +function setRowSelected(id, on){ + if(on) _selected.add(id); else _selected.delete(id); +} + +// Select-all acts on the rows the filter shows, never on the whole directory. +function toggleSelectAll(on){ + _shownSelectable.forEach(id => setRowSelected(id, on)); + banner('sel-banner', '', ''); + updateSelectionUI(); +} + +// Reflect _selected into the page without re-rendering the table, so keyboard +// focus stays on the checkbox that was just used. +function updateSelectionUI(){ + const wrap = document.getElementById('users-table'); + if(wrap){ + wrap.querySelectorAll('input.selbox').forEach(cb => { + const on = _selected.has(cb.dataset.id); + cb.checked = on; + const tr = cb.closest('tr'); + if(tr) tr.classList.toggle('is-selected', on); + }); + const all = document.getElementById('sel-all'); + if(all){ + const n = _shownSelectable.filter(id => _selected.has(id)).length; + all.checked = n > 0 && n === _shownSelectable.length; + all.indeterminate = n > 0 && n < _shownSelectable.length; + all.disabled = !_shownSelectable.length; + } + } + const bar = document.getElementById('bulk-bar'); + if(bar){ + const n = _selected.size; + bar.hidden = n === 0; + const c = document.getElementById('bulk-count'); + if(c) c.textContent = n + ' selected'; + } +} + +// One listener for every checkbox in the table (event delegation): no ids are +// bound into inline handlers, so there is nothing to escape. +document.addEventListener('change', e => { + const t = e.target; + if(!(t instanceof HTMLInputElement)) return; + if(t.id === 'sel-all'){ toggleSelectAll(t.checked); return; } + if(t.classList.contains('selbox')){ + setRowSelected(t.dataset.id, t.checked); + banner('sel-banner', '', ''); + updateSelectionUI(); + } +}); + +function selCell(u){ + if(!selectable(u)){ + const why = u.id === _meId ? 'Your own account: change it one setting at a time' + : (u.manage_blocked_reason || 'You cannot change this account'); + return ''+ + ''; + } + return ''; +} + function renderUsers(){ const wrap = document.getElementById('users-table'); const q = ((document.getElementById('user-search')||{}).value||'').trim().toLowerCase(); @@ -116,7 +209,8 @@ function renderUsers(){ (u.project_role||'')+' '+roleLabel(u.role)).toLowerCase().indexOf(q) >= 0; }); const count = '
'+list.length+' of '+total+' '+(total===1?'person':'people')+'
'; - if(!list.length){ wrap.innerHTML = count+'
Nothing matches.
'; return; } + _shownSelectable = list.filter(selectable).map(u => u.id); + if(!list.length){ wrap.innerHTML = count+'
Nothing matches.
'; updateSelectionUI(); return; } const head = manages() ? ['Username','Name','Email', @@ -130,9 +224,16 @@ function renderUsers(){ 'Status']; const ths = head.map(h => Array.isArray(h) ? ''+uesc(h[0])+'' : ''+uesc(h)+'').join(''); + // CR-020: a selection column for anyone who manages accounts. Select-all names + // how many rows it covers, because it covers only what the filter shows. + const selTh = manages() + ? '' + : ''; const rows = list.map(manages() ? managerRow : readonlyRow).join(''); - wrap.innerHTML = count+'
'+ths+ + wrap.innerHTML = count+'
'+selTh+ths+ ''+rows+'
'+legend(); + updateSelectionUI(); } function legend(){ @@ -189,6 +290,7 @@ function managerRow(u){ if(!can && !me) actions.push('read-only'); return ''+ + selCell(u)+ ''+uesc(u.username)+''+(me?'you':'')+''+ ''+uesc(u.full_name||'')+''+ // The address is truncated with the full value on the title: a long one used to From 681048197aecd5a0e5e0a5b819d9d8a3a8598361 Mon Sep 17 00:00:00 2001 From: Matt Mabrey Date: Tue, 6 Oct 2026 11:02:09 -0700 Subject: [PATCH 4/9] T12.3: CR-020 bulk-action toolbar Role change, enable/disable, and project add/remove on the selected rows, wired to the T12.1 endpoints. Delete is T12.5. - The toolbar offers only what the caller may do: grantable roles, managed projects (archived last, marked), grantable per-project roles. - Every action confirms through wpConfirmDialog naming the exact count (and for projects, the project and role) before anything is sent. - The result lists every failed row with the server's reason, plus the changed / already-set counts; a partial failure is a warning, an all-failed batch an alert, a server error says nothing was changed. Never a blanket success. Announced through the live-region banner. - The directory reloads afterwards, which clears the selection. DOM harness (jsdom, real page and scripts, mocked API): 30/30 with T12.2. --- html/users.js | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) diff --git a/html/users.js b/html/users.js index 064d6d0..4edd95b 100644 --- a/html/users.js +++ b/html/users.js @@ -44,6 +44,7 @@ async function boot(){ renderScope(); } renderCreateForm(); + renderBulkActions(); loadUsers(); } @@ -176,6 +177,119 @@ document.addEventListener('change', e => { } }); +// ── bulk actions (CR-020, T12.3) ────────────────────────────────────────────── +// The toolbar offers only what this caller may do: the roles they may grant, the +// projects they administer, the per-project roles they may hand out. The server +// re-checks every row anyway (T12.1); this is so nobody is offered a choice that +// can only fail. +function renderBulkActions(){ + const box = document.getElementById('bulk-actions'); + if(!box || !manages()) return; + const grantable = PERM_ROLES.filter(r => (_scope.grantable_roles || []).indexOf(r) >= 0); + const projects = (_scope.managed_projects || []).slice() + .sort((a,b) => (a.archived?1:0) - (b.archived?1:0)); + const projRoles = PROJECT_SCOPED_ROLES.filter(r => (_scope.grantable_project_roles || []).indexOf(r) >= 0); + const group = (label, inner) => '
'+ + ''+uesc(label)+''+inner+'
'; + box.innerHTML = + group('Permissions', + ''+ + '') + + group('Sign-in', + ''+ + '') + + (projects.length ? group('Project access', + ''+ + ''+ + ''+ + '') : ''); +} + +function selectedIds(){ return _users.filter(u => _selected.has(u.id)).map(u => u.id); } +function people(n){ return n + ' user' + (n === 1 ? '' : 's'); } +function selVal(id){ return (document.getElementById(id) || {}).value || ''; } +function selText(id){ + const s = document.getElementById(id); + return (s && s.selectedIndex >= 0) ? s.options[s.selectedIndex].text : ''; +} + +// One path for every bulk action: confirm through the dialog kit with the exact +// count, send, report row by row, reload. A reload clears the selection, which is +// right: the rows may have changed underneath it. +async function runBulk(path, body, ask){ + const ids = selectedIds(); + if(!ids.length) return; + if(!(await wpConfirmDialog({title: ask.title, okLabel: ask.ok, message: ask.message(ids.length)}))) return; + bannerHtml('bulk-banner', '', uesc(ask.title)+': working on '+uesc(people(ids.length))+'…'); + const { status, json } = await api('POST', path, Object.assign({ user_ids: ids }, body)); + if(status !== 200 || !json || !Array.isArray(json.results)){ + bannerHtml('bulk-banner', 'bad', '✕ '+uesc(apiError(status, json, ask.title+' failed'))+' Nothing was changed.'); + return; + } + showBulkResult(json, ask.title); + loadUsers(); +} + +// Every row is accounted for: changed, already so, or failed with the server's +// reason. A batch that partly failed never reads as a success (CR-020). +function showBulkResult(json, title){ + const failed = json.results.filter(r => r.status === 'failed'); + const parts = [json.ok+' changed']; + if(json.unchanged) parts.push(json.unchanged+' already set'); + if(failed.length) parts.push(failed.length+' failed'); + const kind = !failed.length ? 'ok' : (json.ok + json.unchanged ? 'warn' : 'bad'); + const lead = (failed.length ? (kind === 'bad' ? '✕ ' : '⚠ ') : '✓ ')+uesc(title)+': '+parts.join(', ')+'.'; + const list = failed.length + ? '
    '+failed.map(r => '
  • '+uesc(r.username || r.user_id)+': '+uesc(r.reason)+'
  • ').join('')+'
' + : ''; + bannerHtml('bulk-banner', kind, lead + list); +} + +function bannerHtml(id, kind, html){ + const el = document.getElementById(id); + if(!el) return; + el.className = 'banner' + (kind ? ' '+kind : ''); + el.innerHTML = html; +} + +function bulkRole(){ + const role = selVal('bulk-role'); + if(!role) return; + return runBulk('/api/auth/bulk-users/role', { role }, { + title: 'Set permissions', ok: 'Change permissions', + message: n => 'Set permissions to '+(PERM_LABELS[role] || role)+' for '+people(n)+'?\n\n'+ + 'Each account is checked on its own. Any that cannot be changed are listed afterwards.'}); +} + +function bulkActive(on){ + return runBulk('/api/auth/bulk-users/active', { is_active: !!on }, { + title: on ? 'Enable accounts' : 'Disable accounts', ok: on ? 'Enable' : 'Disable', + message: n => (on ? 'Enable sign-in for ' : 'Disable sign-in for ')+people(n)+'?'+ + (on ? '' : '\n\nA disabled account cannot sign in. Nothing else about it changes.')}); +} + +function bulkProject(op){ + const pid = selVal('bulk-project'); + if(!pid) return; + const role = op === 'add' ? selVal('bulk-project-role') : ''; + const pname = selText('bulk-project'); + return runBulk('/api/auth/bulk-users/projects', { project_id: pid, op, role }, { + title: op === 'add' ? 'Add to project' : 'Remove from project', + ok: op === 'add' ? 'Add' : 'Remove', + message: n => op === 'add' + ? 'Add '+people(n)+' to '+pname+' with '+(role ? PERM_LABELS[role]+' on that project' : 'their account role')+'?\n\n'+ + 'Their other projects, and their roles there, stay as they are.' + : 'Remove '+people(n)+' from '+pname+'?\n\nTheir other projects stay as they are.'}); +} + function selCell(u){ if(!selectable(u)){ const why = u.id === _meId ? 'Your own account: change it one setting at a time' From 74d3bc4af77673631ae03e2d778258f4c3c3b926 Mon Sep 17 00:00:00 2001 From: Matt Mabrey Date: Tue, 6 Oct 2026 11:04:01 -0700 Subject: [PATCH 5/9] T12.4: CR-020 CSV upload (usernames only) POST /api/auth/bulk-users/resolve reads a list of usernames (first column; comma, semicolon or tab; header skipped) and answers line by line, the CR-005 validate-and-report pattern. A line is rejected, with its number and reason, when it names nobody the caller can see ('User not found', as everywhere else), an account they may not change (the single route's own reason), their own account, or a username already listed (duplicate of line N). An email address resolves only when exactly one account has it. Nothing is changed by this route. The console's 'Select from CSV' turns the accepted accounts into the ordinary selection (filter reset so every selected row is visible) and lists every rejected line. The action, confirm and per-row report are the checkbox ones, through the same T12.1 routes, which re-check each row: a CSV cannot reach an account a checkbox could not. Usernames only, action in the toolbar (decided 2026-10-06). Files over 1 MB are refused before upload; FileReader fallback for browsers without Blob.text(). bulk_users_check.py: 61/61. DOM harness: 40/40. --- html/users.html | 12 +++++-- html/users.js | 66 ++++++++++++++++++++++++++++++++++++ server/app.py | 71 +++++++++++++++++++++++++++++++++++++++ tests/bulk_users_check.py | 52 ++++++++++++++++++++++++++-- 4 files changed, 197 insertions(+), 4 deletions(-) diff --git a/html/users.html b/html/users.html index ca2133b..01a8f3d 100644 --- a/html/users.html +++ b/html/users.html @@ -38,8 +38,10 @@ .whoami-chip strong{ color:var(--text); } /* CR-020: row selection and the bulk bar. Tokens only (the token rule). */ - #sel-banner:not(:empty), #bulk-banner:not(:empty){ margin-bottom:var(--s3); } - #bulk-banner ul{ margin:var(--s1) 0 0; padding-left:var(--s5); font-weight:400; } + #sel-banner:not(:empty), #bulk-banner:not(:empty), #csv-banner:not(:empty){ margin-bottom:var(--s3); } + #bulk-banner ul, #csv-banner ul{ margin:var(--s1) 0 0; padding-left:var(--s5); font-weight:400; + max-height:220px; overflow:auto; } + #csv-btn[hidden]{ display:none; } table.grid th.selcell, table.grid td.selcell{ width:1%; padding:0 var(--s1); text-align:center; } /* The label is the hit area: the 16px box alone is under the 24px floor. */ .selhit{ display:inline-flex; align-items:center; justify-content:center; @@ -111,8 +113,14 @@ + + +
+