WIP! A BB-style forum, on the ATmosphere!
We're still working... we'll be back soon when we have something to show off!
node
typescript
hono
htmx
atproto
docs: add ATB-43 implementation plan
+1223
+1223
docs/plans/2026-02-28-atb-43-admin-members-page.md
+1223
docs/plans/2026-02-28-atb-43-admin-members-page.md
···
1
+
# ATB-43 Admin Members Page Implementation Plan
2
+
3
+
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
4
+
5
+
**Goal:** Add `GET /admin/members` page and `POST /admin/members/:did/role` proxy route to the web app, enabling admins to view all forum members and assign roles via inline HTMX row swaps.
6
+
7
+
**Architecture:** The members page calls two AppView APIs in parallel (`/api/admin/members` and `/api/admin/roles`), renders a table of members, and conditionally shows role-assignment `<select>` + submit forms if the session user has `manageRoles`. Form submissions hit a web-server proxy route that forwards to the AppView and returns an updated `<tr>` fragment (HTMX `outerHTML` swap). The proxy needs no extra API calls because the form carries reconstruction data in hidden inputs (handle, joinedAt, current role, roles list).
8
+
9
+
**Tech Stack:** Hono (web server + AppView), Hono JSX, HTMX, `typed-htmx`, Vitest (web tests use global `fetch` mock; AppView tests use `createTestContext()`)
10
+
11
+
---
12
+
13
+
## Task 1: Add `canManageRoles` session helper
14
+
15
+
**Files:**
16
+
- Modify: `apps/web/src/lib/session.ts`
17
+
- Test: `apps/web/src/lib/__tests__/session.test.ts`
18
+
19
+
**Step 1: Write the failing tests**
20
+
21
+
Add the following `describe` block to `apps/web/src/lib/__tests__/session.test.ts`. Add `canManageRoles` to the existing import at the top of the file:
22
+
23
+
```typescript
24
+
// In the import line at the top, add canManageRoles:
25
+
import { getSession, getSessionWithPermissions, canLockTopics, canModeratePosts, canBanUsers, hasAnyAdminPermission, canManageMembers, canManageCategories, canViewModLog, canManageRoles } from "../session.js";
26
+
```
27
+
28
+
Then add this block at the end of the file:
29
+
30
+
```typescript
31
+
describe("canManageRoles", () => {
32
+
it("returns false for unauthenticated session", () => {
33
+
const auth: WebSessionWithPermissions = {
34
+
authenticated: false,
35
+
permissions: new Set(),
36
+
};
37
+
expect(canManageRoles(auth)).toBe(false);
38
+
});
39
+
40
+
it("returns false when authenticated but missing manageRoles", () => {
41
+
const auth: WebSessionWithPermissions = {
42
+
authenticated: true,
43
+
did: "did:plc:x",
44
+
handle: "x.bsky.social",
45
+
permissions: new Set(["space.atbb.permission.manageMembers"]),
46
+
};
47
+
expect(canManageRoles(auth)).toBe(false);
48
+
});
49
+
50
+
it("returns true with manageRoles permission", () => {
51
+
const auth: WebSessionWithPermissions = {
52
+
authenticated: true,
53
+
did: "did:plc:x",
54
+
handle: "x.bsky.social",
55
+
permissions: new Set(["space.atbb.permission.manageRoles"]),
56
+
};
57
+
expect(canManageRoles(auth)).toBe(true);
58
+
});
59
+
60
+
it("returns true with wildcard (*) permission", () => {
61
+
const auth: WebSessionWithPermissions = {
62
+
authenticated: true,
63
+
did: "did:plc:x",
64
+
handle: "x.bsky.social",
65
+
permissions: new Set(["*"]),
66
+
};
67
+
expect(canManageRoles(auth)).toBe(true);
68
+
});
69
+
});
70
+
```
71
+
72
+
Also add `WebSessionWithPermissions` to the import if not already imported as a type — it's in `../session.js` as an exported type.
73
+
74
+
**Step 2: Run the tests to confirm they fail**
75
+
76
+
```sh
77
+
PATH=/path/to/main-repo/.devenv/profile/bin:/bin:/usr/bin:$PATH \
78
+
pnpm --filter @atbb/web exec vitest run src/lib/__tests__/session.test.ts
79
+
```
80
+
81
+
Expected: 4 failures saying `canManageRoles is not a function`.
82
+
83
+
**Step 3: Implement the helper**
84
+
85
+
Add the following at the end of `apps/web/src/lib/session.ts`, after the `canViewModLog` function:
86
+
87
+
```typescript
88
+
/** Returns true if the session grants permission to assign member roles. */
89
+
export function canManageRoles(auth: WebSessionWithPermissions): boolean {
90
+
return (
91
+
auth.authenticated &&
92
+
(auth.permissions.has("space.atbb.permission.manageRoles") ||
93
+
auth.permissions.has("*"))
94
+
);
95
+
}
96
+
```
97
+
98
+
**Step 4: Run tests to confirm they pass**
99
+
100
+
```sh
101
+
PATH=/path/to/main-repo/.devenv/profile/bin:/bin:/usr/bin:$PATH \
102
+
pnpm --filter @atbb/web exec vitest run src/lib/__tests__/session.test.ts
103
+
```
104
+
105
+
Expected: all existing tests + 4 new `canManageRoles` tests pass.
106
+
107
+
**Step 5: Commit**
108
+
109
+
```sh
110
+
git add apps/web/src/lib/session.ts apps/web/src/lib/__tests__/session.test.ts
111
+
git commit -m "feat(web): add canManageRoles session helper (ATB-43)"
112
+
```
113
+
114
+
---
115
+
116
+
## Task 2: Add `uri` field to `GET /api/admin/roles` AppView response
117
+
118
+
The members page dropdown needs role AT URIs (e.g. `at://did:plc:forum/space.atbb.forum.role/rkey`) to submit to `POST /api/admin/members/:did/role`. The current `/api/admin/roles` response omits the URI. This task adds it.
119
+
120
+
**Files:**
121
+
- Modify: `apps/appview/src/routes/admin.ts`
122
+
- Test: `apps/appview/src/routes/__tests__/admin.test.ts`
123
+
124
+
**Step 1: Write the failing test**
125
+
126
+
In `apps/appview/src/routes/__tests__/admin.test.ts`, find the existing `describe.sequential("Admin Routes")` block and add this test inside it (near the other `/roles` tests if any, otherwise at an appropriate location):
127
+
128
+
```typescript
129
+
describe("GET /api/admin/roles", () => {
130
+
it("includes uri field in each role", async () => {
131
+
// Seed a role
132
+
const [role] = await ctx.db
133
+
.insert(roles)
134
+
.values({
135
+
did: ctx.config.forumDid,
136
+
rkey: "owner",
137
+
cid: "bafytest",
138
+
name: "Owner",
139
+
description: "Forum owner",
140
+
priority: 0,
141
+
indexedAt: new Date(),
142
+
createdAt: new Date(),
143
+
})
144
+
.returning();
145
+
146
+
mockUser = { did: "did:plc:test-admin" };
147
+
148
+
const res = await app.request("/api/admin/roles", {
149
+
headers: { Cookie: "atbb_session=token" },
150
+
});
151
+
152
+
expect(res.status).toBe(200);
153
+
const data = await res.json() as { roles: Array<{ name: string; uri: string }> };
154
+
expect(data.roles).toHaveLength(1);
155
+
expect(data.roles[0].uri).toBe(
156
+
`at://${ctx.config.forumDid}/space.atbb.forum.role/owner`
157
+
);
158
+
});
159
+
});
160
+
```
161
+
162
+
**Step 2: Run the test to confirm it fails**
163
+
164
+
```sh
165
+
PATH=/path/to/main-repo/.devenv/profile/bin:/bin:/usr/bin:$PATH \
166
+
pnpm --filter @atbb/appview exec vitest run src/routes/__tests__/admin.test.ts
167
+
```
168
+
169
+
Expected: failure — `data.roles[0].uri` is `undefined`.
170
+
171
+
**Step 3: Implement the change**
172
+
173
+
In `apps/appview/src/routes/admin.ts`, find the `GET /roles` handler. Locate the `select` query inside it:
174
+
175
+
```typescript
176
+
const rolesList = await ctx.db
177
+
.select({
178
+
id: roles.id,
179
+
name: roles.name,
180
+
description: roles.description,
181
+
priority: roles.priority,
182
+
})
183
+
```
184
+
185
+
Add `rkey` and `did` to the select:
186
+
187
+
```typescript
188
+
const rolesList = await ctx.db
189
+
.select({
190
+
id: roles.id,
191
+
name: roles.name,
192
+
description: roles.description,
193
+
priority: roles.priority,
194
+
rkey: roles.rkey,
195
+
did: roles.did,
196
+
})
197
+
```
198
+
199
+
Then in the `.map()` that builds `rolesWithPermissions`, add the `uri` field:
200
+
201
+
```typescript
202
+
return {
203
+
id: role.id.toString(),
204
+
name: role.name,
205
+
description: role.description,
206
+
permissions: perms.map((p) => p.permission),
207
+
priority: role.priority,
208
+
uri: `at://${role.did}/space.atbb.forum.role/${role.rkey}`,
209
+
};
210
+
```
211
+
212
+
**Step 4: Run tests to confirm they pass**
213
+
214
+
```sh
215
+
PATH=/path/to/main-repo/.devenv/profile/bin:/bin:/usr/bin:$PATH \
216
+
pnpm --filter @atbb/appview exec vitest run src/routes/__tests__/admin.test.ts
217
+
```
218
+
219
+
Expected: all existing tests + new `uri` test pass.
220
+
221
+
**Step 5: Commit**
222
+
223
+
```sh
224
+
git add apps/appview/src/routes/admin.ts apps/appview/src/routes/__tests__/admin.test.ts
225
+
git commit -m "feat(appview): include uri in GET /api/admin/roles response (ATB-43)"
226
+
```
227
+
228
+
---
229
+
230
+
## Task 3: Add admin member table CSS
231
+
232
+
**Files:**
233
+
- Modify: `apps/web/public/static/css/theme.css`
234
+
235
+
**Step 1: Add CSS**
236
+
237
+
At the very end of `apps/web/public/static/css/theme.css`, after the `.admin-nav-card__description` block, add:
238
+
239
+
```css
240
+
/* ─── Admin Member Table ─────────────────────────────────────────────────── */
241
+
242
+
.admin-member-table {
243
+
width: 100%;
244
+
border-collapse: collapse;
245
+
margin-top: var(--space-md);
246
+
}
247
+
248
+
.admin-member-table th {
249
+
text-align: left;
250
+
padding: var(--space-sm) var(--space-md);
251
+
border-bottom: calc(var(--border-width) * 2) solid var(--color-border);
252
+
font-weight: var(--font-weight-bold);
253
+
font-size: var(--font-size-sm);
254
+
color: var(--color-text-muted);
255
+
text-transform: uppercase;
256
+
letter-spacing: 0.05em;
257
+
}
258
+
259
+
.admin-member-table td {
260
+
padding: var(--space-sm) var(--space-md);
261
+
border-bottom: var(--border-width) solid var(--color-border);
262
+
vertical-align: middle;
263
+
}
264
+
265
+
.admin-member-table tbody tr:last-child td {
266
+
border-bottom: none;
267
+
}
268
+
269
+
.role-badge {
270
+
display: inline-block;
271
+
padding: var(--space-xs) var(--space-sm);
272
+
border: var(--border-width) solid var(--color-border);
273
+
font-size: var(--font-size-sm);
274
+
font-weight: var(--font-weight-bold);
275
+
background-color: var(--color-surface);
276
+
}
277
+
278
+
.member-row__assign-form {
279
+
display: flex;
280
+
align-items: center;
281
+
gap: var(--space-sm);
282
+
flex-wrap: wrap;
283
+
}
284
+
285
+
.member-row__error {
286
+
display: block;
287
+
color: var(--color-danger);
288
+
font-size: var(--font-size-sm);
289
+
font-weight: var(--font-weight-bold);
290
+
margin-top: var(--space-xs);
291
+
}
292
+
```
293
+
294
+
**Step 2: Commit**
295
+
296
+
```sh
297
+
git add apps/web/public/static/css/theme.css
298
+
git commit -m "style(web): add admin member table CSS classes (ATB-43)"
299
+
```
300
+
301
+
---
302
+
303
+
## Task 4: Add `GET /admin/members` page route
304
+
305
+
**Files:**
306
+
- Modify: `apps/web/src/routes/admin.tsx`
307
+
- Test: `apps/web/src/routes/__tests__/admin.test.tsx`
308
+
309
+
### Step 1: Write the failing tests
310
+
311
+
Add a new `describe` block to `apps/web/src/routes/__tests__/admin.test.tsx`:
312
+
313
+
```typescript
314
+
describe("createAdminRoutes — GET /admin/members", () => {
315
+
beforeEach(() => {
316
+
vi.stubGlobal("fetch", mockFetch);
317
+
vi.stubEnv("APPVIEW_URL", "http://localhost:3000");
318
+
vi.resetModules();
319
+
});
320
+
321
+
afterEach(() => {
322
+
vi.unstubAllGlobals();
323
+
vi.unstubAllEnvs();
324
+
mockFetch.mockReset();
325
+
});
326
+
327
+
function mockResponse(body: unknown, ok = true, status = 200) {
328
+
return {
329
+
ok,
330
+
status,
331
+
statusText: ok ? "OK" : "Error",
332
+
json: () => Promise.resolve(body),
333
+
};
334
+
}
335
+
336
+
/** Sets up the two-fetch mock sequence for an authenticated session. */
337
+
function setupSession(permissions: string[]) {
338
+
mockFetch.mockResolvedValueOnce(
339
+
mockResponse({ authenticated: true, did: "did:plc:admin", handle: "admin.bsky.social" })
340
+
);
341
+
mockFetch.mockResolvedValueOnce(mockResponse({ permissions }));
342
+
}
343
+
344
+
const SAMPLE_MEMBERS = [
345
+
{ did: "did:plc:alice", handle: "alice.bsky.social", role: "Owner", roleUri: "at://did:plc:forum/space.atbb.forum.role/owner", joinedAt: "2026-01-01T00:00:00.000Z" },
346
+
{ did: "did:plc:bob", handle: "bob.bsky.social", role: "Member", roleUri: "at://did:plc:forum/space.atbb.forum.role/member", joinedAt: "2026-01-05T00:00:00.000Z" },
347
+
];
348
+
349
+
const SAMPLE_ROLES = [
350
+
{ id: "1", name: "Owner", uri: "at://did:plc:forum/space.atbb.forum.role/owner", priority: 0, permissions: ["*"] },
351
+
{ id: "2", name: "Member", uri: "at://did:plc:forum/space.atbb.forum.role/member", priority: 30, permissions: [] },
352
+
];
353
+
354
+
async function loadAdminRoutes() {
355
+
const { createAdminRoutes } = await import("../admin.js");
356
+
return createAdminRoutes("http://localhost:3000");
357
+
}
358
+
359
+
// ── Auth guards ──────────────────────────────────────────────────────────
360
+
361
+
it("redirects unauthenticated users to /login", async () => {
362
+
const routes = await loadAdminRoutes();
363
+
const res = await routes.request("/admin/members");
364
+
expect(res.status).toBe(302);
365
+
expect(res.headers.get("location")).toBe("/login");
366
+
});
367
+
368
+
it("returns 403 for authenticated user without manageMembers", async () => {
369
+
setupSession(["space.atbb.permission.manageCategories"]);
370
+
const routes = await loadAdminRoutes();
371
+
const res = await routes.request("/admin/members", {
372
+
headers: { cookie: "atbb_session=token" },
373
+
});
374
+
expect(res.status).toBe(403);
375
+
});
376
+
377
+
// ── Successful renders ───────────────────────────────────────────────────
378
+
379
+
it("renders member table with handles and role badges", async () => {
380
+
setupSession(["space.atbb.permission.manageMembers"]);
381
+
mockFetch.mockResolvedValueOnce(
382
+
mockResponse({ members: SAMPLE_MEMBERS, isTruncated: false })
383
+
);
384
+
// No roles fetch — no manageRoles permission
385
+
386
+
const routes = await loadAdminRoutes();
387
+
const res = await routes.request("/admin/members", {
388
+
headers: { cookie: "atbb_session=token" },
389
+
});
390
+
391
+
expect(res.status).toBe(200);
392
+
const html = await res.text();
393
+
expect(html).toContain("alice.bsky.social");
394
+
expect(html).toContain("bob.bsky.social");
395
+
expect(html).toContain("role-badge");
396
+
expect(html).toContain("Owner");
397
+
expect(html).toContain("Member");
398
+
});
399
+
400
+
it("renders joined date for members", async () => {
401
+
setupSession(["space.atbb.permission.manageMembers"]);
402
+
mockFetch.mockResolvedValueOnce(
403
+
mockResponse({ members: SAMPLE_MEMBERS, isTruncated: false })
404
+
);
405
+
406
+
const routes = await loadAdminRoutes();
407
+
const res = await routes.request("/admin/members", {
408
+
headers: { cookie: "atbb_session=token" },
409
+
});
410
+
411
+
const html = await res.text();
412
+
// Jan 1 2026
413
+
expect(html).toContain("Jan");
414
+
expect(html).toContain("2026");
415
+
});
416
+
417
+
it("hides role assignment form when user lacks manageRoles", async () => {
418
+
setupSession(["space.atbb.permission.manageMembers"]);
419
+
mockFetch.mockResolvedValueOnce(
420
+
mockResponse({ members: SAMPLE_MEMBERS, isTruncated: false })
421
+
);
422
+
423
+
const routes = await loadAdminRoutes();
424
+
const res = await routes.request("/admin/members", {
425
+
headers: { cookie: "atbb_session=token" },
426
+
});
427
+
428
+
const html = await res.text();
429
+
expect(html).not.toContain("hx-post");
430
+
expect(html).not.toContain("Assign");
431
+
});
432
+
433
+
it("shows role assignment form when user has manageRoles", async () => {
434
+
setupSession([
435
+
"space.atbb.permission.manageMembers",
436
+
"space.atbb.permission.manageRoles",
437
+
]);
438
+
// members fetch
439
+
mockFetch.mockResolvedValueOnce(
440
+
mockResponse({ members: SAMPLE_MEMBERS, isTruncated: false })
441
+
);
442
+
// roles fetch (parallel)
443
+
mockFetch.mockResolvedValueOnce(mockResponse({ roles: SAMPLE_ROLES }));
444
+
445
+
const routes = await loadAdminRoutes();
446
+
const res = await routes.request("/admin/members", {
447
+
headers: { cookie: "atbb_session=token" },
448
+
});
449
+
450
+
const html = await res.text();
451
+
expect(html).toContain("hx-post");
452
+
expect(html).toContain("/admin/members/did:plc:bob/role");
453
+
expect(html).toContain("Assign");
454
+
});
455
+
456
+
it("shows empty state when no members", async () => {
457
+
setupSession(["space.atbb.permission.manageMembers"]);
458
+
mockFetch.mockResolvedValueOnce(
459
+
mockResponse({ members: [], isTruncated: false })
460
+
);
461
+
462
+
const routes = await loadAdminRoutes();
463
+
const res = await routes.request("/admin/members", {
464
+
headers: { cookie: "atbb_session=token" },
465
+
});
466
+
467
+
const html = await res.text();
468
+
expect(html).toContain("No members");
469
+
});
470
+
471
+
it("shows truncated indicator when isTruncated is true", async () => {
472
+
setupSession(["space.atbb.permission.manageMembers"]);
473
+
mockFetch.mockResolvedValueOnce(
474
+
mockResponse({ members: SAMPLE_MEMBERS, isTruncated: true })
475
+
);
476
+
477
+
const routes = await loadAdminRoutes();
478
+
const res = await routes.request("/admin/members", {
479
+
headers: { cookie: "atbb_session=token" },
480
+
});
481
+
482
+
const html = await res.text();
483
+
// Member count should include "+" indicator
484
+
expect(html).toContain("+");
485
+
});
486
+
487
+
// ── Error handling ───────────────────────────────────────────────────────
488
+
489
+
it("returns 503 on AppView network error fetching members", async () => {
490
+
setupSession(["space.atbb.permission.manageMembers"]);
491
+
mockFetch.mockRejectedValueOnce(new Error("fetch failed"));
492
+
493
+
const routes = await loadAdminRoutes();
494
+
const res = await routes.request("/admin/members", {
495
+
headers: { cookie: "atbb_session=token" },
496
+
});
497
+
498
+
expect(res.status).toBe(503);
499
+
const html = await res.text();
500
+
expect(html).toContain("error-display");
501
+
});
502
+
503
+
it("returns 500 on AppView server error fetching members", async () => {
504
+
setupSession(["space.atbb.permission.manageMembers"]);
505
+
mockFetch.mockResolvedValueOnce(mockResponse({}, false, 500));
506
+
507
+
const routes = await loadAdminRoutes();
508
+
const res = await routes.request("/admin/members", {
509
+
headers: { cookie: "atbb_session=token" },
510
+
});
511
+
512
+
expect(res.status).toBe(500);
513
+
const html = await res.text();
514
+
expect(html).toContain("error-display");
515
+
});
516
+
});
517
+
```
518
+
519
+
**Step 2: Run tests to confirm they fail**
520
+
521
+
```sh
522
+
PATH=/path/to/main-repo/.devenv/profile/bin:/bin:/usr/bin:$PATH \
523
+
pnpm --filter @atbb/web exec vitest run src/routes/__tests__/admin.test.tsx
524
+
```
525
+
526
+
Expected: all new tests fail — `GET /admin/members` returns 404.
527
+
528
+
**Step 3: Implement the route**
529
+
530
+
Replace the entire content of `apps/web/src/routes/admin.tsx` with the following:
531
+
532
+
```tsx
533
+
import { Hono } from "hono";
534
+
import { BaseLayout } from "../layouts/base.js";
535
+
import { PageHeader, Card, EmptyState, ErrorDisplay } from "../components/index.js";
536
+
import {
537
+
getSessionWithPermissions,
538
+
hasAnyAdminPermission,
539
+
canManageMembers,
540
+
canManageCategories,
541
+
canViewModLog,
542
+
canManageRoles,
543
+
} from "../lib/session.js";
544
+
import { isProgrammingError } from "../lib/errors.js";
545
+
import { logger } from "../lib/logger.js";
546
+
547
+
// ─── Types ─────────────────────────────────────────────────────────────────
548
+
549
+
interface MemberEntry {
550
+
did: string;
551
+
handle: string;
552
+
role: string;
553
+
roleUri: string | null;
554
+
joinedAt: string | null;
555
+
}
556
+
557
+
interface RoleEntry {
558
+
id: string;
559
+
name: string;
560
+
uri: string;
561
+
priority: number;
562
+
}
563
+
564
+
// ─── Helpers ───────────────────────────────────────────────────────────────
565
+
566
+
function formatJoinedDate(isoString: string | null): string {
567
+
if (!isoString) return "—";
568
+
const d = new Date(isoString);
569
+
if (isNaN(d.getTime())) return "—";
570
+
return d.toLocaleDateString("en-US", {
571
+
month: "short",
572
+
day: "numeric",
573
+
year: "numeric",
574
+
});
575
+
}
576
+
577
+
// ─── Components ────────────────────────────────────────────────────────────
578
+
579
+
function MemberRow({
580
+
member,
581
+
roles,
582
+
showRoleControls,
583
+
errorMsg = null,
584
+
}: {
585
+
member: MemberEntry;
586
+
roles: RoleEntry[];
587
+
showRoleControls: boolean;
588
+
errorMsg?: string | null;
589
+
}) {
590
+
const colSpan = showRoleControls ? 4 : 3;
591
+
return (
592
+
<tr>
593
+
<td>{member.handle}</td>
594
+
<td>
595
+
<span class="role-badge">{member.role}</span>
596
+
</td>
597
+
<td>{formatJoinedDate(member.joinedAt)}</td>
598
+
{showRoleControls && (
599
+
<td>
600
+
<form
601
+
hx-post={`/admin/members/${member.did}/role`}
602
+
hx-target="closest tr"
603
+
hx-swap="outerHTML"
604
+
>
605
+
<input type="hidden" name="handle" value={member.handle} />
606
+
<input type="hidden" name="joinedAt" value={member.joinedAt ?? ""} />
607
+
<input type="hidden" name="currentRole" value={member.role} />
608
+
<input type="hidden" name="currentRoleUri" value={member.roleUri ?? ""} />
609
+
<input type="hidden" name="canManageRoles" value="1" />
610
+
<input
611
+
type="hidden"
612
+
name="rolesJson"
613
+
value={JSON.stringify(roles)}
614
+
/>
615
+
<div class="member-row__assign-form">
616
+
<label class="sr-only" for={`role-${member.did}`}>
617
+
Assign role to {member.handle}
618
+
</label>
619
+
<select id={`role-${member.did}`} name="roleUri">
620
+
{roles.map((role) => (
621
+
<option
622
+
value={role.uri}
623
+
selected={member.roleUri === role.uri}
624
+
>
625
+
{role.name}
626
+
</option>
627
+
))}
628
+
</select>
629
+
<button type="submit" class="btn btn-primary">
630
+
Assign
631
+
</button>
632
+
</div>
633
+
{errorMsg && (
634
+
<span class="member-row__error">{errorMsg}</span>
635
+
)}
636
+
</form>
637
+
</td>
638
+
)}
639
+
</tr>
640
+
);
641
+
}
642
+
643
+
// ─── Routes ────────────────────────────────────────────────────────────────
644
+
645
+
export function createAdminRoutes(appviewUrl: string) {
646
+
const app = new Hono();
647
+
648
+
// ── GET /admin ────────────────────────────────────────────────────────────
649
+
650
+
app.get("/admin", async (c) => {
651
+
const auth = await getSessionWithPermissions(appviewUrl, c.req.header("cookie"));
652
+
653
+
if (!auth.authenticated) {
654
+
return c.redirect("/login");
655
+
}
656
+
657
+
if (!hasAnyAdminPermission(auth)) {
658
+
return c.html(
659
+
<BaseLayout title="Access Denied — atBB Forum" auth={auth}>
660
+
<PageHeader title="Access Denied" />
661
+
<p>You don't have permission to access the admin panel.</p>
662
+
</BaseLayout>,
663
+
403
664
+
);
665
+
}
666
+
667
+
const showMembers = canManageMembers(auth);
668
+
const showStructure = canManageCategories(auth);
669
+
const showModLog = canViewModLog(auth);
670
+
671
+
return c.html(
672
+
<BaseLayout title="Admin Panel — atBB Forum" auth={auth}>
673
+
<PageHeader title="Admin Panel" />
674
+
<div class="admin-nav-grid">
675
+
{showMembers && (
676
+
<a href="/admin/members" class="admin-nav-card">
677
+
<Card>
678
+
<p class="admin-nav-card__icon" aria-hidden="true">👥</p>
679
+
<p class="admin-nav-card__title">Members</p>
680
+
<p class="admin-nav-card__description">View and assign member roles</p>
681
+
</Card>
682
+
</a>
683
+
)}
684
+
{showStructure && (
685
+
<a href="/admin/structure" class="admin-nav-card">
686
+
<Card>
687
+
<p class="admin-nav-card__icon" aria-hidden="true">📁</p>
688
+
<p class="admin-nav-card__title">Structure</p>
689
+
<p class="admin-nav-card__description">Manage categories and boards</p>
690
+
</Card>
691
+
</a>
692
+
)}
693
+
{showModLog && (
694
+
<a href="/admin/modlog" class="admin-nav-card">
695
+
<Card>
696
+
<p class="admin-nav-card__icon" aria-hidden="true">📋</p>
697
+
<p class="admin-nav-card__title">Mod Log</p>
698
+
<p class="admin-nav-card__description">Audit trail of moderation actions</p>
699
+
</Card>
700
+
</a>
701
+
)}
702
+
</div>
703
+
</BaseLayout>
704
+
);
705
+
});
706
+
707
+
// ── GET /admin/members ────────────────────────────────────────────────────
708
+
709
+
app.get("/admin/members", async (c) => {
710
+
const auth = await getSessionWithPermissions(appviewUrl, c.req.header("cookie"));
711
+
712
+
if (!auth.authenticated) {
713
+
return c.redirect("/login");
714
+
}
715
+
716
+
if (!canManageMembers(auth)) {
717
+
return c.html(
718
+
<BaseLayout title="Access Denied — atBB Forum" auth={auth}>
719
+
<PageHeader title="Members" />
720
+
<p>You don't have permission to manage members.</p>
721
+
</BaseLayout>,
722
+
403
723
+
);
724
+
}
725
+
726
+
const cookie = c.req.header("cookie") ?? "";
727
+
const showRoleControls = canManageRoles(auth);
728
+
729
+
let membersRes: Response;
730
+
let rolesRes: Response | null = null;
731
+
732
+
try {
733
+
[membersRes, rolesRes] = await Promise.all([
734
+
fetch(`${appviewUrl}/api/admin/members`, { headers: { Cookie: cookie } }),
735
+
showRoleControls
736
+
? fetch(`${appviewUrl}/api/admin/roles`, { headers: { Cookie: cookie } })
737
+
: Promise.resolve(null),
738
+
]);
739
+
} catch (error) {
740
+
if (isProgrammingError(error)) throw error;
741
+
logger.error("Network error fetching members", {
742
+
operation: "GET /admin/members",
743
+
error: error instanceof Error ? error.message : String(error),
744
+
});
745
+
return c.html(
746
+
<BaseLayout title="Members — atBB Forum" auth={auth}>
747
+
<PageHeader title="Members" />
748
+
<ErrorDisplay
749
+
message="Unable to load members"
750
+
detail="The forum is temporarily unavailable. Please try again."
751
+
/>
752
+
</BaseLayout>,
753
+
503
754
+
);
755
+
}
756
+
757
+
if (!membersRes.ok) {
758
+
logger.error("AppView returned error for members list", {
759
+
operation: "GET /admin/members",
760
+
status: membersRes.status,
761
+
});
762
+
return c.html(
763
+
<BaseLayout title="Members — atBB Forum" auth={auth}>
764
+
<PageHeader title="Members" />
765
+
<ErrorDisplay
766
+
message="Something went wrong"
767
+
detail="Could not load member list. Please try again."
768
+
/>
769
+
</BaseLayout>,
770
+
500
771
+
);
772
+
}
773
+
774
+
const membersData = (await membersRes.json()) as {
775
+
members: MemberEntry[];
776
+
isTruncated: boolean;
777
+
};
778
+
const rolesData =
779
+
rolesRes?.ok ? ((await rolesRes.json()) as { roles: RoleEntry[] }) : null;
780
+
781
+
const members = membersData.members;
782
+
const roles = rolesData?.roles ?? [];
783
+
const isTruncated = membersData.isTruncated;
784
+
785
+
const title = `Members (${members.length}${isTruncated ? "+" : ""})`;
786
+
787
+
return c.html(
788
+
<BaseLayout title="Members — atBB Forum" auth={auth}>
789
+
<PageHeader title={title} />
790
+
{members.length === 0 ? (
791
+
<EmptyState message="No members yet" />
792
+
) : (
793
+
<div class="card">
794
+
<table class="admin-member-table">
795
+
<thead>
796
+
<tr>
797
+
<th scope="col">Handle</th>
798
+
<th scope="col">Role</th>
799
+
<th scope="col">Joined</th>
800
+
{showRoleControls && <th scope="col">Assign Role</th>}
801
+
</tr>
802
+
</thead>
803
+
<tbody>
804
+
{members.map((member) => (
805
+
<MemberRow
806
+
member={member}
807
+
roles={roles}
808
+
showRoleControls={showRoleControls}
809
+
/>
810
+
))}
811
+
</tbody>
812
+
</table>
813
+
</div>
814
+
)}
815
+
</BaseLayout>
816
+
);
817
+
});
818
+
819
+
// ── POST /admin/members/:did/role (HTMX proxy) ────────────────────────────
820
+
821
+
app.post("/admin/members/:did/role", async (c) => {
822
+
const targetDid = c.req.param("did");
823
+
const cookie = c.req.header("cookie") ?? "";
824
+
825
+
// Parse form body
826
+
let body: Record<string, string | File>;
827
+
try {
828
+
body = await c.req.parseBody();
829
+
} catch {
830
+
return c.html(
831
+
<tr>
832
+
<td colspan="4">
833
+
<span class="member-row__error">Invalid form submission.</span>
834
+
</td>
835
+
</tr>
836
+
);
837
+
}
838
+
839
+
const roleUri = typeof body.roleUri === "string" ? body.roleUri.trim() : "";
840
+
const handle = typeof body.handle === "string" ? body.handle : targetDid;
841
+
const joinedAt = typeof body.joinedAt === "string" ? body.joinedAt : null;
842
+
const currentRole = typeof body.currentRole === "string" ? body.currentRole : "";
843
+
const currentRoleUri =
844
+
typeof body.currentRoleUri === "string" && body.currentRoleUri
845
+
? body.currentRoleUri
846
+
: null;
847
+
const showRoleControls = body.canManageRoles === "1";
848
+
849
+
let roles: RoleEntry[] = [];
850
+
try {
851
+
const rolesJson = typeof body.rolesJson === "string" ? body.rolesJson : "[]";
852
+
roles = JSON.parse(rolesJson) as RoleEntry[];
853
+
} catch {
854
+
// Roles stay empty — dropdown won't render but row will still show
855
+
}
856
+
857
+
if (!roleUri) {
858
+
return c.html(
859
+
<MemberRow
860
+
member={{ did: targetDid, handle, role: currentRole, roleUri: currentRoleUri, joinedAt }}
861
+
roles={roles}
862
+
showRoleControls={showRoleControls}
863
+
errorMsg="Please select a role."
864
+
/>
865
+
);
866
+
}
867
+
868
+
// Forward to AppView
869
+
let appviewRes: Response;
870
+
try {
871
+
appviewRes = await fetch(
872
+
`${appviewUrl}/api/admin/members/${targetDid}/role`,
873
+
{
874
+
method: "POST",
875
+
headers: {
876
+
"Content-Type": "application/json",
877
+
Cookie: cookie,
878
+
},
879
+
body: JSON.stringify({ roleUri }),
880
+
}
881
+
);
882
+
} catch (error) {
883
+
if (isProgrammingError(error)) throw error;
884
+
logger.error("Network error proxying role assignment", {
885
+
operation: "POST /admin/members/:did/role",
886
+
targetDid,
887
+
error: error instanceof Error ? error.message : String(error),
888
+
});
889
+
return c.html(
890
+
<MemberRow
891
+
member={{ did: targetDid, handle, role: currentRole, roleUri: currentRoleUri, joinedAt }}
892
+
roles={roles}
893
+
showRoleControls={showRoleControls}
894
+
errorMsg="Forum temporarily unavailable. Please try again."
895
+
/>
896
+
);
897
+
}
898
+
899
+
if (appviewRes.ok) {
900
+
const data = (await appviewRes.json()) as {
901
+
roleAssigned: string;
902
+
targetDid: string;
903
+
};
904
+
const newRoleName = data.roleAssigned || currentRole;
905
+
return c.html(
906
+
<MemberRow
907
+
member={{ did: targetDid, handle, role: newRoleName, roleUri, joinedAt }}
908
+
roles={roles}
909
+
showRoleControls={showRoleControls}
910
+
/>
911
+
);
912
+
}
913
+
914
+
// Map AppView errors to user-friendly messages
915
+
let errorMsg: string;
916
+
if (appviewRes.status === 403) {
917
+
errorMsg = "Cannot assign a role with equal or higher authority than your own.";
918
+
} else if (appviewRes.status === 404) {
919
+
errorMsg = "Member or role not found.";
920
+
} else if (appviewRes.status === 401) {
921
+
errorMsg = "Your session has expired. Please log in again.";
922
+
} else {
923
+
logger.error("AppView returned error for role assignment", {
924
+
operation: "POST /admin/members/:did/role",
925
+
targetDid,
926
+
status: appviewRes.status,
927
+
});
928
+
errorMsg = "Something went wrong. Please try again.";
929
+
}
930
+
931
+
return c.html(
932
+
<MemberRow
933
+
member={{ did: targetDid, handle, role: currentRole, roleUri: currentRoleUri, joinedAt }}
934
+
roles={roles}
935
+
showRoleControls={showRoleControls}
936
+
errorMsg={errorMsg}
937
+
/>
938
+
);
939
+
});
940
+
941
+
return app;
942
+
}
943
+
```
944
+
945
+
**Step 4: Run tests to confirm they pass**
946
+
947
+
```sh
948
+
PATH=/path/to/main-repo/.devenv/profile/bin:/bin:/usr/bin:$PATH \
949
+
pnpm --filter @atbb/web exec vitest run src/routes/__tests__/admin.test.tsx
950
+
```
951
+
952
+
Expected: all previous `GET /admin` tests still pass + all new `GET /admin/members` tests pass.
953
+
954
+
**Step 5: Commit**
955
+
956
+
```sh
957
+
git add apps/web/src/routes/admin.tsx apps/web/src/routes/__tests__/admin.test.tsx
958
+
git commit -m "feat(web): add GET /admin/members page with role display (ATB-43)"
959
+
```
960
+
961
+
---
962
+
963
+
## Task 5: Add proxy route tests and verify
964
+
965
+
The proxy route is already implemented in Task 4's code. This task writes and runs tests for `POST /admin/members/:did/role` to verify error handling.
966
+
967
+
**Files:**
968
+
- Test: `apps/web/src/routes/__tests__/admin.test.tsx`
969
+
970
+
**Step 1: Write the failing tests**
971
+
972
+
Add another `describe` block to `apps/web/src/routes/__tests__/admin.test.tsx`:
973
+
974
+
```typescript
975
+
describe("createAdminRoutes — POST /admin/members/:did/role", () => {
976
+
beforeEach(() => {
977
+
vi.stubGlobal("fetch", mockFetch);
978
+
vi.stubEnv("APPVIEW_URL", "http://localhost:3000");
979
+
vi.resetModules();
980
+
});
981
+
982
+
afterEach(() => {
983
+
vi.unstubAllGlobals();
984
+
vi.unstubAllEnvs();
985
+
mockFetch.mockReset();
986
+
});
987
+
988
+
function mockResponse(body: unknown, ok = true, status = 200) {
989
+
return {
990
+
ok,
991
+
status,
992
+
statusText: ok ? "OK" : "Error",
993
+
json: () => Promise.resolve(body),
994
+
};
995
+
}
996
+
997
+
const SAMPLE_ROLES = [
998
+
{ id: "1", name: "Owner", uri: "at://did:plc:forum/space.atbb.forum.role/owner", priority: 0, permissions: ["*"] },
999
+
{ id: "2", name: "Member", uri: "at://did:plc:forum/space.atbb.forum.role/member", priority: 30, permissions: [] },
1000
+
];
1001
+
1002
+
function makeFormBody(overrides: Partial<Record<string, string>> = {}): string {
1003
+
const params = new URLSearchParams({
1004
+
roleUri: "at://did:plc:forum/space.atbb.forum.role/member",
1005
+
handle: "bob.bsky.social",
1006
+
joinedAt: "2026-01-05T00:00:00.000Z",
1007
+
currentRole: "Owner",
1008
+
currentRoleUri: "at://did:plc:forum/space.atbb.forum.role/owner",
1009
+
canManageRoles: "1",
1010
+
rolesJson: JSON.stringify(SAMPLE_ROLES),
1011
+
...overrides,
1012
+
});
1013
+
return params.toString();
1014
+
}
1015
+
1016
+
async function loadAdminRoutes() {
1017
+
const { createAdminRoutes } = await import("../admin.js");
1018
+
return createAdminRoutes("http://localhost:3000");
1019
+
}
1020
+
1021
+
// ── Success ──────────────────────────────────────────────────────────────
1022
+
1023
+
it("returns updated <tr> with new role name on success", async () => {
1024
+
mockFetch.mockResolvedValueOnce(
1025
+
mockResponse({ success: true, roleAssigned: "Member", targetDid: "did:plc:bob" })
1026
+
);
1027
+
1028
+
const routes = await loadAdminRoutes();
1029
+
const res = await routes.request("/admin/members/did:plc:bob/role", {
1030
+
method: "POST",
1031
+
headers: {
1032
+
"Content-Type": "application/x-www-form-urlencoded",
1033
+
cookie: "atbb_session=token",
1034
+
},
1035
+
body: makeFormBody(),
1036
+
});
1037
+
1038
+
expect(res.status).toBe(200);
1039
+
const html = await res.text();
1040
+
expect(html).toContain("<tr");
1041
+
expect(html).toContain("Member"); // new role badge
1042
+
expect(html).toContain("bob.bsky.social"); // handle preserved
1043
+
});
1044
+
1045
+
it("re-renders form with updated role selected on success", async () => {
1046
+
mockFetch.mockResolvedValueOnce(
1047
+
mockResponse({ success: true, roleAssigned: "Member", targetDid: "did:plc:bob" })
1048
+
);
1049
+
1050
+
const routes = await loadAdminRoutes();
1051
+
const res = await routes.request("/admin/members/did:plc:bob/role", {
1052
+
method: "POST",
1053
+
headers: {
1054
+
"Content-Type": "application/x-www-form-urlencoded",
1055
+
cookie: "atbb_session=token",
1056
+
},
1057
+
body: makeFormBody({
1058
+
roleUri: "at://did:plc:forum/space.atbb.forum.role/member",
1059
+
}),
1060
+
});
1061
+
1062
+
const html = await res.text();
1063
+
// The new roleUri should be pre-selected in the dropdown
1064
+
expect(html).toContain(
1065
+
'value="at://did:plc:forum/space.atbb.forum.role/member"'
1066
+
);
1067
+
});
1068
+
1069
+
// ── AppView errors ───────────────────────────────────────────────────────
1070
+
1071
+
it("returns row with friendly error on AppView 403", async () => {
1072
+
mockFetch.mockResolvedValueOnce(mockResponse({}, false, 403));
1073
+
1074
+
const routes = await loadAdminRoutes();
1075
+
const res = await routes.request("/admin/members/did:plc:bob/role", {
1076
+
method: "POST",
1077
+
headers: {
1078
+
"Content-Type": "application/x-www-form-urlencoded",
1079
+
cookie: "atbb_session=token",
1080
+
},
1081
+
body: makeFormBody(),
1082
+
});
1083
+
1084
+
expect(res.status).toBe(200);
1085
+
const html = await res.text();
1086
+
expect(html).toContain("<tr");
1087
+
expect(html).toContain("member-row__error");
1088
+
expect(html).toContain("equal or higher authority");
1089
+
// Preserves current role in badge
1090
+
expect(html).toContain("Owner");
1091
+
});
1092
+
1093
+
it("returns row with friendly error on AppView 404", async () => {
1094
+
mockFetch.mockResolvedValueOnce(mockResponse({}, false, 404));
1095
+
1096
+
const routes = await loadAdminRoutes();
1097
+
const res = await routes.request("/admin/members/did:plc:bob/role", {
1098
+
method: "POST",
1099
+
headers: {
1100
+
"Content-Type": "application/x-www-form-urlencoded",
1101
+
cookie: "atbb_session=token",
1102
+
},
1103
+
body: makeFormBody(),
1104
+
});
1105
+
1106
+
expect(res.status).toBe(200);
1107
+
const html = await res.text();
1108
+
expect(html).toContain("member-row__error");
1109
+
expect(html).toContain("not found");
1110
+
});
1111
+
1112
+
it("returns row with friendly error on AppView 500", async () => {
1113
+
mockFetch.mockResolvedValueOnce(mockResponse({}, false, 500));
1114
+
1115
+
const routes = await loadAdminRoutes();
1116
+
const res = await routes.request("/admin/members/did:plc:bob/role", {
1117
+
method: "POST",
1118
+
headers: {
1119
+
"Content-Type": "application/x-www-form-urlencoded",
1120
+
cookie: "atbb_session=token",
1121
+
},
1122
+
body: makeFormBody(),
1123
+
});
1124
+
1125
+
expect(res.status).toBe(200);
1126
+
const html = await res.text();
1127
+
expect(html).toContain("member-row__error");
1128
+
expect(html).toContain("Something went wrong");
1129
+
});
1130
+
1131
+
it("returns row with unavailable message on network error", async () => {
1132
+
mockFetch.mockRejectedValueOnce(new Error("fetch failed"));
1133
+
1134
+
const routes = await loadAdminRoutes();
1135
+
const res = await routes.request("/admin/members/did:plc:bob/role", {
1136
+
method: "POST",
1137
+
headers: {
1138
+
"Content-Type": "application/x-www-form-urlencoded",
1139
+
cookie: "atbb_session=token",
1140
+
},
1141
+
body: makeFormBody(),
1142
+
});
1143
+
1144
+
expect(res.status).toBe(200);
1145
+
const html = await res.text();
1146
+
expect(html).toContain("member-row__error");
1147
+
expect(html).toContain("temporarily unavailable");
1148
+
});
1149
+
1150
+
it("returns row with error when roleUri is missing", async () => {
1151
+
const routes = await loadAdminRoutes();
1152
+
const res = await routes.request("/admin/members/did:plc:bob/role", {
1153
+
method: "POST",
1154
+
headers: {
1155
+
"Content-Type": "application/x-www-form-urlencoded",
1156
+
cookie: "atbb_session=token",
1157
+
},
1158
+
body: makeFormBody({ roleUri: "" }),
1159
+
});
1160
+
1161
+
expect(res.status).toBe(200);
1162
+
const html = await res.text();
1163
+
expect(html).toContain("member-row__error");
1164
+
// No AppView call should have been made
1165
+
expect(mockFetch).not.toHaveBeenCalled();
1166
+
});
1167
+
});
1168
+
```
1169
+
1170
+
**Step 2: Run tests to confirm they fail**
1171
+
1172
+
```sh
1173
+
PATH=/path/to/main-repo/.devenv/profile/bin:/bin:/usr/bin:$PATH \
1174
+
pnpm --filter @atbb/web exec vitest run src/routes/__tests__/admin.test.tsx
1175
+
```
1176
+
1177
+
Expected: 8 new tests fail — the proxy route doesn't exist yet in your current test environment (though it's in the file from Task 4). If all 8 pass immediately, verify the implementation from Task 4 is in place.
1178
+
1179
+
**Step 3: Run all tests to confirm nothing regressed**
1180
+
1181
+
```sh
1182
+
PATH=/path/to/main-repo/.devenv/profile/bin:/bin:/usr/bin:$PATH \
1183
+
pnpm --filter @atbb/web exec vitest run
1184
+
```
1185
+
1186
+
Expected: all web tests pass.
1187
+
1188
+
**Step 4: Run AppView tests too**
1189
+
1190
+
```sh
1191
+
PATH=/path/to/main-repo/.devenv/profile/bin:/bin:/usr/bin:$PATH \
1192
+
pnpm --filter @atbb/appview exec vitest run
1193
+
```
1194
+
1195
+
Expected: all AppView tests pass.
1196
+
1197
+
**Step 5: Commit**
1198
+
1199
+
```sh
1200
+
git add apps/web/src/routes/__tests__/admin.test.tsx
1201
+
git commit -m "test(web): add POST /admin/members/:did/role proxy tests (ATB-43)"
1202
+
```
1203
+
1204
+
---
1205
+
1206
+
## Task 6: Final verification
1207
+
1208
+
**Step 1: Run full test suite**
1209
+
1210
+
```sh
1211
+
PATH=/path/to/main-repo/.devenv/profile/bin:/bin:/usr/bin:$PATH \
1212
+
pnpm test
1213
+
```
1214
+
1215
+
Expected: all tests in all packages pass.
1216
+
1217
+
**Step 2: Update Linear issue**
1218
+
1219
+
Update ATB-43 status to "In Review" and add a comment summarising what was implemented.
1220
+
1221
+
**Step 3: Update project plan doc**
1222
+
1223
+
Mark ATB-43 complete in `docs/atproto-forum-plan.md` if applicable.