docs(plans): move ATB-44 and ATB-45 plan docs to complete/

+2435

2 changed files

expand all

docs

plans

complete

2026-02-28-atb-44-category-management-endpoints.md

2026-02-28-atb-45-board-management-endpoints.md

+1108

docs/plans/complete/2026-02-28-atb-44-category-management-endpoints.md

··· 1 + # ATB-44: Admin Panel Category Management AppView Endpoints 2 + 3 + > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. 4 + 5 + **Goal:** Add `POST /api/admin/categories`, `PUT /api/admin/categories/:id`, and `DELETE /api/admin/categories/:id` to the AppView. 6 + 7 + **Architecture:** All mutations follow the PDS-first write pattern — validate input, do DB pre-flight checks (reads only), write to Forum DID's PDS via `ForumAgent`, return the AT URI + CID from the PDS response. The firehose indexer handles the DB row update asynchronously. No direct DB writes in the mutation path. 8 + 9 + **Tech Stack:** Hono, Drizzle ORM (postgres.js/libsql), `@atproto/api` (`AtpAgent`), `@atproto/common-web` (`TID`), Vitest, Bruno 10 + 11 + --- 12 + 13 + ## Background 14 + 15 + All code for these endpoints lives in `apps/appview/src/routes/admin.ts`. 16 + Tests live in `apps/appview/src/routes/__tests__/admin.test.ts`. 17 + Bruno docs live in `bruno/AppView API/Admin/`. 18 + 19 + ### Key helpers already in scope (admin.ts already imports these): 20 + - `safeParseJsonBody(c)` — parses JSON body, returns `{ body, error }` (400 on malformed JSON) 21 + - `getForumAgentOrError(ctx, c, operation)` — returns `{ agent, error }` (500 if null, 503 if unauthenticated) 22 + - `handleReadError(c, error, msg, ctx)` — classifies DB read errors (503 DB, 503 network, 500 other) 23 + - `handleWriteError(c, error, msg, ctx)` — classifies PDS write errors (503 network, 500 other) 24 + - `requireAuth(ctx)` middleware — returns 401 if not authenticated, sets `c.get("user")` 25 + - `requirePermission(ctx, permission)` middleware — returns 403 if user lacks permission 26 + 27 + ### Imports to ADD to admin.ts: 28 + ```typescript 29 + import { TID } from "@atproto/common-web"; 30 + import { parseBigIntParam } from "./helpers.js"; 31 + // Add to the @atbb/db import: categories, boards 32 + // count is already imported from drizzle-orm 33 + ``` 34 + 35 + ### The category lexicon (`space.atbb.forum.category`): 36 + ``` 37 + Required: name (string, max 100 graphemes), createdAt (datetime) 38 + Optional: description (string), slug (string), sortOrder (integer ≥ 0) 39 + ``` 40 + 41 + ### DB schema for categories (packages/db/src/schema.ts): 42 + ```typescript 43 + categories: { id: bigserial, did, rkey, cid, name, description, slug, sortOrder, forumId, createdAt, indexedAt } 44 + boards: { id: bigserial, did, rkey, cid, name, ..., categoryId (FK → categories.id), categoryUri } 45 + ``` 46 + 47 + ### Test mock setup pattern: 48 + ```typescript 49 + // In beforeEach — extend the ForumAgent mock to include deleteRecord 50 + let mockDeleteRecord: ReturnType<typeof vi.fn>; 51 + mockDeleteRecord = vi.fn().mockResolvedValue({}); 52 + 53 + ctx.forumAgent = { 54 + getAgent: () => ({ 55 + com: { 56 + atproto: { 57 + repo: { 58 + putRecord: mockPutRecord, 59 + deleteRecord: mockDeleteRecord, 60 + }, 61 + }, 62 + }, 63 + }), 64 + } as any; 65 + ``` 66 + 67 + ### How tests verify 401: 68 + Set `mockUser = null` before the request — the `requireAuth` mock returns 401 when `mockUser` is null. 69 + 70 + ### Run command: 71 + ```bash 72 + PATH=/path/to/monorepo/.devenv/profile/bin:/bin:/usr/bin:$PATH pnpm --filter @atbb/appview exec vitest run src/routes/__tests__/admin.test.ts 73 + ``` 74 + 75 + --- 76 + 77 + ## Task 1: Add failing tests for POST /api/admin/categories 78 + 79 + **Files:** 80 + - Modify: `apps/appview/src/routes/__tests__/admin.test.ts` 81 + 82 + **Step 1: Add a new `describe` block for the create endpoint** 83 + 84 + Add this after the final closing `});` of the `describe("GET /api/admin/members/me", ...)` block (before the final `});` that closes `describe.sequential("Admin Routes", ...)`): 85 + 86 + ```typescript 87 + describe("POST /api/admin/categories", () => { 88 + beforeEach(async () => { 89 + await ctx.cleanDatabase(); 90 + 91 + await ctx.db.insert(forums).values({ 92 + did: ctx.config.forumDid, 93 + rkey: "self", 94 + cid: "bafytest", 95 + name: "Test Forum", 96 + description: "A test forum", 97 + indexedAt: new Date(), 98 + }); 99 + 100 + mockUser = { did: "did:plc:test-admin" }; 101 + mockPutRecord.mockClear(); 102 + mockPutRecord.mockResolvedValue({ data: { uri: "at://did:plc:test-forum/space.atbb.forum.category/tid123", cid: "bafycategory" } }); 103 + }); 104 + 105 + it("creates category with valid body → 201 and putRecord called", async () => { 106 + const res = await app.request("/api/admin/categories", { 107 + method: "POST", 108 + headers: { "Content-Type": "application/json" }, 109 + body: JSON.stringify({ name: "General Discussion", description: "Talk about anything.", sortOrder: 1 }), 110 + }); 111 + 112 + expect(res.status).toBe(201); 113 + const data = await res.json(); 114 + expect(data.uri).toBeDefined(); 115 + expect(data.cid).toBeDefined(); 116 + expect(mockPutRecord).toHaveBeenCalledWith( 117 + expect.objectContaining({ 118 + repo: ctx.config.forumDid, 119 + collection: "space.atbb.forum.category", 120 + record: expect.objectContaining({ 121 + $type: "space.atbb.forum.category", 122 + name: "General Discussion", 123 + description: "Talk about anything.", 124 + sortOrder: 1, 125 + createdAt: expect.any(String), 126 + }), 127 + }) 128 + ); 129 + }); 130 + 131 + it("creates category without optional fields → 201", async () => { 132 + const res = await app.request("/api/admin/categories", { 133 + method: "POST", 134 + headers: { "Content-Type": "application/json" }, 135 + body: JSON.stringify({ name: "Minimal" }), 136 + }); 137 + 138 + expect(res.status).toBe(201); 139 + expect(mockPutRecord).toHaveBeenCalledWith( 140 + expect.objectContaining({ 141 + record: expect.objectContaining({ name: "Minimal" }), 142 + }) 143 + ); 144 + }); 145 + 146 + it("returns 400 when name is missing → no PDS write", async () => { 147 + const res = await app.request("/api/admin/categories", { 148 + method: "POST", 149 + headers: { "Content-Type": "application/json" }, 150 + body: JSON.stringify({ description: "No name field" }), 151 + }); 152 + 153 + expect(res.status).toBe(400); 154 + const data = await res.json(); 155 + expect(data.error).toContain("name"); 156 + expect(mockPutRecord).not.toHaveBeenCalled(); 157 + }); 158 + 159 + it("returns 400 when name is empty string → no PDS write", async () => { 160 + const res = await app.request("/api/admin/categories", { 161 + method: "POST", 162 + headers: { "Content-Type": "application/json" }, 163 + body: JSON.stringify({ name: " " }), 164 + }); 165 + 166 + expect(res.status).toBe(400); 167 + expect(mockPutRecord).not.toHaveBeenCalled(); 168 + }); 169 + 170 + it("returns 400 for malformed JSON", async () => { 171 + const res = await app.request("/api/admin/categories", { 172 + method: "POST", 173 + headers: { "Content-Type": "application/json" }, 174 + body: "{ bad json }", 175 + }); 176 + 177 + expect(res.status).toBe(400); 178 + const data = await res.json(); 179 + expect(data.error).toContain("Invalid JSON"); 180 + expect(mockPutRecord).not.toHaveBeenCalled(); 181 + }); 182 + 183 + it("returns 401 when unauthenticated → no PDS write", async () => { 184 + mockUser = null; 185 + 186 + const res = await app.request("/api/admin/categories", { 187 + method: "POST", 188 + headers: { "Content-Type": "application/json" }, 189 + body: JSON.stringify({ name: "Test" }), 190 + }); 191 + 192 + expect(res.status).toBe(401); 193 + expect(mockPutRecord).not.toHaveBeenCalled(); 194 + }); 195 + 196 + it("returns 503 when PDS network error", async () => { 197 + mockPutRecord.mockRejectedValue(new Error("fetch failed")); 198 + 199 + const res = await app.request("/api/admin/categories", { 200 + method: "POST", 201 + headers: { "Content-Type": "application/json" }, 202 + body: JSON.stringify({ name: "Test" }), 203 + }); 204 + 205 + expect(res.status).toBe(503); 206 + const data = await res.json(); 207 + expect(data.error).toContain("Unable to reach external service"); 208 + }); 209 + 210 + it("returns 500 when ForumAgent unavailable", async () => { 211 + ctx.forumAgent = null; 212 + 213 + const res = await app.request("/api/admin/categories", { 214 + method: "POST", 215 + headers: { "Content-Type": "application/json" }, 216 + body: JSON.stringify({ name: "Test" }), 217 + }); 218 + 219 + expect(res.status).toBe(500); 220 + const data = await res.json(); 221 + expect(data.error).toContain("Forum agent not available"); 222 + }); 223 + }); 224 + ``` 225 + 226 + **Step 2: Run tests to confirm they fail** 227 + 228 + ```bash 229 + PATH=/path/to/.devenv/profile/bin:/bin:/usr/bin:$PATH pnpm --filter @atbb/appview exec vitest run src/routes/__tests__/admin.test.ts 2>&1 | tail -30 230 + ``` 231 + 232 + Expected: `POST /api/admin/categories` tests fail with 404 (route not found). 233 + 234 + --- 235 + 236 + ## Task 2: Implement POST /api/admin/categories 237 + 238 + **Files:** 239 + - Modify: `apps/appview/src/routes/admin.ts` 240 + 241 + **Step 1: Add missing imports at the top of admin.ts** 242 + 243 + The current import line is: 244 + ```typescript 245 + import { memberships, roles, rolePermissions, users, forums, backfillProgress, backfillErrors } from "@atbb/db"; 246 + ``` 247 + 248 + Change it to: 249 + ```typescript 250 + import { memberships, roles, rolePermissions, users, forums, backfillProgress, backfillErrors, categories, boards } from "@atbb/db"; 251 + ``` 252 + 253 + Also add at the top of the file (after existing imports): 254 + ```typescript 255 + import { TID } from "@atproto/common-web"; 256 + import { parseBigIntParam } from "./helpers.js"; 257 + ``` 258 + 259 + **Step 2: Add the POST /api/admin/categories handler** 260 + 261 + Add the following inside the `createAdminRoutes` function, before the `return app;` line: 262 + 263 + ```typescript 264 + /** 265 + * POST /api/admin/categories 266 + * 267 + * Create a new forum category. Writes space.atbb.forum.category to Forum DID's PDS. 268 + * The firehose indexer creates the DB row asynchronously. 269 + */ 270 + app.post( 271 + "/categories", 272 + requireAuth(ctx), 273 + requirePermission(ctx, "space.atbb.permission.manageCategories"), 274 + async (c) => { 275 + const { body, error: parseError } = await safeParseJsonBody(c); 276 + if (parseError) return parseError; 277 + 278 + const { name, description, sortOrder } = body; 279 + 280 + if (typeof name !== "string" || name.trim().length === 0) { 281 + return c.json({ error: "name is required and must be a non-empty string" }, 400); 282 + } 283 + 284 + const { agent, error: agentError } = getForumAgentOrError(ctx, c, "POST /api/admin/categories"); 285 + if (agentError) return agentError; 286 + 287 + const rkey = TID.nextStr(); 288 + const now = new Date().toISOString(); 289 + 290 + try { 291 + const result = await agent.com.atproto.repo.putRecord({ 292 + repo: ctx.config.forumDid, 293 + collection: "space.atbb.forum.category", 294 + rkey, 295 + record: { 296 + $type: "space.atbb.forum.category", 297 + name: name.trim(), 298 + ...(typeof description === "string" && { description: description.trim() }), 299 + ...(typeof sortOrder === "number" && { sortOrder }), 300 + createdAt: now, 301 + }, 302 + }); 303 + 304 + return c.json({ uri: result.data.uri, cid: result.data.cid }, 201); 305 + } catch (error) { 306 + return handleWriteError(c, error, "Failed to create category", { 307 + operation: "POST /api/admin/categories", 308 + logger: ctx.logger, 309 + }); 310 + } 311 + } 312 + ); 313 + ``` 314 + 315 + **Step 3: Run tests** 316 + 317 + ```bash 318 + PATH=/path/to/.devenv/profile/bin:/bin:/usr/bin:$PATH pnpm --filter @atbb/appview exec vitest run src/routes/__tests__/admin.test.ts 2>&1 | tail -30 319 + ``` 320 + 321 + Expected: All `POST /api/admin/categories` tests pass. 322 + 323 + **Step 4: Commit** 324 + 325 + ```bash 326 + git add apps/appview/src/routes/admin.ts apps/appview/src/routes/__tests__/admin.test.ts 327 + git commit -m "feat(appview): POST /api/admin/categories create endpoint (ATB-44)" 328 + ``` 329 + 330 + --- 331 + 332 + ## Task 3: Add failing tests for PUT /api/admin/categories/:id 333 + 334 + **Files:** 335 + - Modify: `apps/appview/src/routes/__tests__/admin.test.ts` 336 + 337 + **Step 1: Add the `describe` block** 338 + 339 + Add a new `describe` block (after the POST block, before the final `});`). Note that we need `categories` in scope — add it to the import at line 5: 340 + 341 + ```typescript 342 + import { memberships, roles, rolePermissions, users, forums, categories } from "@atbb/db"; 343 + ``` 344 + 345 + Then add: 346 + 347 + ```typescript 348 + describe.sequential("PUT /api/admin/categories/:id", () => { 349 + let categoryId: string; 350 + 351 + beforeEach(async () => { 352 + await ctx.cleanDatabase(); 353 + 354 + await ctx.db.insert(forums).values({ 355 + did: ctx.config.forumDid, 356 + rkey: "self", 357 + cid: "bafytest", 358 + name: "Test Forum", 359 + description: "A test forum", 360 + indexedAt: new Date(), 361 + }); 362 + 363 + const [cat] = await ctx.db.insert(categories).values({ 364 + did: ctx.config.forumDid, 365 + rkey: "tid-test-cat", 366 + cid: "bafycat", 367 + name: "Original Name", 368 + description: "Original description", 369 + sortOrder: 1, 370 + createdAt: new Date("2026-01-01T00:00:00.000Z"), 371 + indexedAt: new Date(), 372 + }).returning({ id: categories.id }); 373 + 374 + categoryId = cat.id.toString(); 375 + 376 + mockUser = { did: "did:plc:test-admin" }; 377 + mockPutRecord.mockClear(); 378 + mockPutRecord.mockResolvedValue({ data: { uri: `at://${ctx.config.forumDid}/space.atbb.forum.category/tid-test-cat`, cid: "bafynewcid" } }); 379 + }); 380 + 381 + it("updates category name → 200 and putRecord called with same rkey", async () => { 382 + const res = await app.request(`/api/admin/categories/${categoryId}`, { 383 + method: "PUT", 384 + headers: { "Content-Type": "application/json" }, 385 + body: JSON.stringify({ name: "Updated Name", description: "New desc", sortOrder: 2 }), 386 + }); 387 + 388 + expect(res.status).toBe(200); 389 + const data = await res.json(); 390 + expect(data.uri).toBeDefined(); 391 + expect(data.cid).toBeDefined(); 392 + expect(mockPutRecord).toHaveBeenCalledWith( 393 + expect.objectContaining({ 394 + repo: ctx.config.forumDid, 395 + collection: "space.atbb.forum.category", 396 + rkey: "tid-test-cat", // same rkey as existing category 397 + record: expect.objectContaining({ 398 + $type: "space.atbb.forum.category", 399 + name: "Updated Name", 400 + description: "New desc", 401 + sortOrder: 2, 402 + }), 403 + }) 404 + ); 405 + }); 406 + 407 + it("preserves original createdAt on update", async () => { 408 + const res = await app.request(`/api/admin/categories/${categoryId}`, { 409 + method: "PUT", 410 + headers: { "Content-Type": "application/json" }, 411 + body: JSON.stringify({ name: "Updated Name" }), 412 + }); 413 + 414 + expect(res.status).toBe(200); 415 + expect(mockPutRecord).toHaveBeenCalledWith( 416 + expect.objectContaining({ 417 + record: expect.objectContaining({ 418 + createdAt: "2026-01-01T00:00:00.000Z", 419 + }), 420 + }) 421 + ); 422 + }); 423 + 424 + it("returns 400 when name is missing", async () => { 425 + const res = await app.request(`/api/admin/categories/${categoryId}`, { 426 + method: "PUT", 427 + headers: { "Content-Type": "application/json" }, 428 + body: JSON.stringify({ description: "No name" }), 429 + }); 430 + 431 + expect(res.status).toBe(400); 432 + expect(mockPutRecord).not.toHaveBeenCalled(); 433 + }); 434 + 435 + it("returns 400 for invalid category ID", async () => { 436 + const res = await app.request("/api/admin/categories/not-a-number", { 437 + method: "PUT", 438 + headers: { "Content-Type": "application/json" }, 439 + body: JSON.stringify({ name: "Test" }), 440 + }); 441 + 442 + expect(res.status).toBe(400); 443 + const data = await res.json(); 444 + expect(data.error).toContain("Invalid category ID"); 445 + expect(mockPutRecord).not.toHaveBeenCalled(); 446 + }); 447 + 448 + it("returns 404 when category not found", async () => { 449 + const res = await app.request("/api/admin/categories/99999", { 450 + method: "PUT", 451 + headers: { "Content-Type": "application/json" }, 452 + body: JSON.stringify({ name: "Test" }), 453 + }); 454 + 455 + expect(res.status).toBe(404); 456 + expect(mockPutRecord).not.toHaveBeenCalled(); 457 + }); 458 + 459 + it("returns 401 when unauthenticated", async () => { 460 + mockUser = null; 461 + 462 + const res = await app.request(`/api/admin/categories/${categoryId}`, { 463 + method: "PUT", 464 + headers: { "Content-Type": "application/json" }, 465 + body: JSON.stringify({ name: "Test" }), 466 + }); 467 + 468 + expect(res.status).toBe(401); 469 + expect(mockPutRecord).not.toHaveBeenCalled(); 470 + }); 471 + 472 + it("returns 503 when PDS network error", async () => { 473 + mockPutRecord.mockRejectedValue(new Error("fetch failed")); 474 + 475 + const res = await app.request(`/api/admin/categories/${categoryId}`, { 476 + method: "PUT", 477 + headers: { "Content-Type": "application/json" }, 478 + body: JSON.stringify({ name: "Test" }), 479 + }); 480 + 481 + expect(res.status).toBe(503); 482 + }); 483 + 484 + it("returns 500 when ForumAgent unavailable", async () => { 485 + ctx.forumAgent = null; 486 + 487 + const res = await app.request(`/api/admin/categories/${categoryId}`, { 488 + method: "PUT", 489 + headers: { "Content-Type": "application/json" }, 490 + body: JSON.stringify({ name: "Test" }), 491 + }); 492 + 493 + expect(res.status).toBe(500); 494 + }); 495 + }); 496 + ``` 497 + 498 + **Step 2: Run tests to confirm they fail** 499 + 500 + ```bash 501 + PATH=/path/to/.devenv/profile/bin:/bin:/usr/bin:$PATH pnpm --filter @atbb/appview exec vitest run src/routes/__tests__/admin.test.ts 2>&1 | tail -30 502 + ``` 503 + 504 + Expected: PUT tests fail with 404 (route not found). 505 + 506 + --- 507 + 508 + ## Task 4: Implement PUT /api/admin/categories/:id 509 + 510 + **Files:** 511 + - Modify: `apps/appview/src/routes/admin.ts` 512 + 513 + **Step 1: Add the PUT /api/admin/categories/:id handler** 514 + 515 + Add the following inside `createAdminRoutes`, after the POST /categories handler and before `return app;`: 516 + 517 + ```typescript 518 + /** 519 + * PUT /api/admin/categories/:id 520 + * 521 + * Update an existing category. Fetches existing rkey from DB, calls putRecord 522 + * with updated fields preserving the original createdAt. 523 + */ 524 + app.put( 525 + "/categories/:id", 526 + requireAuth(ctx), 527 + requirePermission(ctx, "space.atbb.permission.manageCategories"), 528 + async (c) => { 529 + const idParam = c.req.param("id"); 530 + const id = parseBigIntParam(idParam); 531 + if (id === null) { 532 + return c.json({ error: "Invalid category ID" }, 400); 533 + } 534 + 535 + const { body, error: parseError } = await safeParseJsonBody(c); 536 + if (parseError) return parseError; 537 + 538 + const { name, description, sortOrder } = body; 539 + 540 + if (typeof name !== "string" || name.trim().length === 0) { 541 + return c.json({ error: "name is required and must be a non-empty string" }, 400); 542 + } 543 + 544 + let category: typeof categories.$inferSelect; 545 + try { 546 + const [row] = await ctx.db 547 + .select() 548 + .from(categories) 549 + .where(and(eq(categories.id, id), eq(categories.did, ctx.config.forumDid))) 550 + .limit(1); 551 + 552 + if (!row) { 553 + return c.json({ error: "Category not found" }, 404); 554 + } 555 + category = row; 556 + } catch (error) { 557 + return handleReadError(c, error, "Failed to look up category", { 558 + operation: "PUT /api/admin/categories/:id", 559 + logger: ctx.logger, 560 + id: idParam, 561 + }); 562 + } 563 + 564 + const { agent, error: agentError } = getForumAgentOrError(ctx, c, "PUT /api/admin/categories/:id"); 565 + if (agentError) return agentError; 566 + 567 + try { 568 + const result = await agent.com.atproto.repo.putRecord({ 569 + repo: ctx.config.forumDid, 570 + collection: "space.atbb.forum.category", 571 + rkey: category.rkey, 572 + record: { 573 + $type: "space.atbb.forum.category", 574 + name: name.trim(), 575 + ...(typeof description === "string" && { description: description.trim() }), 576 + ...(typeof sortOrder === "number" && { sortOrder }), 577 + createdAt: category.createdAt.toISOString(), 578 + }, 579 + }); 580 + 581 + return c.json({ uri: result.data.uri, cid: result.data.cid }); 582 + } catch (error) { 583 + return handleWriteError(c, error, "Failed to update category", { 584 + operation: "PUT /api/admin/categories/:id", 585 + logger: ctx.logger, 586 + id: idParam, 587 + }); 588 + } 589 + } 590 + ); 591 + ``` 592 + 593 + **Step 2: Run tests** 594 + 595 + ```bash 596 + PATH=/path/to/.devenv/profile/bin:/bin:/usr/bin:$PATH pnpm --filter @atbb/appview exec vitest run src/routes/__tests__/admin.test.ts 2>&1 | tail -30 597 + ``` 598 + 599 + Expected: All PUT tests pass. 600 + 601 + **Step 3: Commit** 602 + 603 + ```bash 604 + git add apps/appview/src/routes/admin.ts apps/appview/src/routes/__tests__/admin.test.ts 605 + git commit -m "feat(appview): PUT /api/admin/categories/:id update endpoint (ATB-44)" 606 + ``` 607 + 608 + --- 609 + 610 + ## Task 5: Add failing tests for DELETE /api/admin/categories/:id 611 + 612 + **Files:** 613 + - Modify: `apps/appview/src/routes/__tests__/admin.test.ts` 614 + 615 + **Step 1: Add `boards` to the import at line 5** 616 + 617 + ```typescript 618 + import { memberships, roles, rolePermissions, users, forums, categories, boards } from "@atbb/db"; 619 + ``` 620 + 621 + **Step 2: Update the top-level `beforeEach` to include `mockDeleteRecord`** 622 + 623 + The existing outer `beforeEach` has: 624 + ```typescript 625 + mockPutRecord = vi.fn().mockResolvedValue({ uri: "at://...", cid: "bafytest" }); 626 + ``` 627 + 628 + Change the ForumAgent mock to also expose `deleteRecord`: 629 + ```typescript 630 + mockPutRecord = vi.fn().mockResolvedValue({ data: { uri: "at://...", cid: "bafytest" } }); 631 + const mockDeleteRecord = vi.fn().mockResolvedValue({}); 632 + 633 + ctx.forumAgent = { 634 + getAgent: () => ({ 635 + com: { 636 + atproto: { 637 + repo: { 638 + putRecord: mockPutRecord, 639 + deleteRecord: mockDeleteRecord, 640 + }, 641 + }, 642 + }, 643 + }), 644 + } as any; 645 + ``` 646 + 647 + Wait — `mockDeleteRecord` needs to be accessible inside the DELETE describe block. Promote it to module level alongside `mockPutRecord`: 648 + 649 + At module level (near line 10): 650 + ```typescript 651 + let mockDeleteRecord: ReturnType<typeof vi.fn>; 652 + ``` 653 + 654 + Then in the outer `beforeEach`: 655 + ```typescript 656 + mockDeleteRecord = vi.fn().mockResolvedValue({}); 657 + ``` 658 + 659 + And update the ForumAgent mock shape in the outer `beforeEach` to include it. 660 + 661 + **Step 3: Add the DELETE describe block** 662 + 663 + ```typescript 664 + describe.sequential("DELETE /api/admin/categories/:id", () => { 665 + let categoryId: string; 666 + 667 + beforeEach(async () => { 668 + await ctx.cleanDatabase(); 669 + 670 + await ctx.db.insert(forums).values({ 671 + did: ctx.config.forumDid, 672 + rkey: "self", 673 + cid: "bafytest", 674 + name: "Test Forum", 675 + description: "A test forum", 676 + indexedAt: new Date(), 677 + }); 678 + 679 + const [cat] = await ctx.db.insert(categories).values({ 680 + did: ctx.config.forumDid, 681 + rkey: "tid-test-del", 682 + cid: "bafycat", 683 + name: "Delete Me", 684 + description: null, 685 + sortOrder: 1, 686 + createdAt: new Date(), 687 + indexedAt: new Date(), 688 + }).returning({ id: categories.id }); 689 + 690 + categoryId = cat.id.toString(); 691 + 692 + mockUser = { did: "did:plc:test-admin" }; 693 + mockDeleteRecord.mockClear(); 694 + mockDeleteRecord.mockResolvedValue({}); 695 + }); 696 + 697 + it("deletes empty category → 200 and deleteRecord called", async () => { 698 + const res = await app.request(`/api/admin/categories/${categoryId}`, { 699 + method: "DELETE", 700 + }); 701 + 702 + expect(res.status).toBe(200); 703 + const data = await res.json(); 704 + expect(data.success).toBe(true); 705 + expect(mockDeleteRecord).toHaveBeenCalledWith({ 706 + repo: ctx.config.forumDid, 707 + collection: "space.atbb.forum.category", 708 + rkey: "tid-test-del", 709 + }); 710 + }); 711 + 712 + it("returns 409 when category has boards → deleteRecord NOT called", async () => { 713 + // Insert a category for the board to reference 714 + const [cat] = await ctx.db.select({ id: categories.id }) 715 + .from(categories) 716 + .where(eq(categories.rkey, "tid-test-del")) 717 + .limit(1); 718 + 719 + await ctx.db.insert(boards).values({ 720 + did: ctx.config.forumDid, 721 + rkey: "tid-board-1", 722 + cid: "bafyboard", 723 + name: "Blocked Board", 724 + categoryId: cat.id, 725 + categoryUri: `at://${ctx.config.forumDid}/space.atbb.forum.category/tid-test-del`, 726 + createdAt: new Date(), 727 + indexedAt: new Date(), 728 + }); 729 + 730 + const res = await app.request(`/api/admin/categories/${categoryId}`, { 731 + method: "DELETE", 732 + }); 733 + 734 + expect(res.status).toBe(409); 735 + const data = await res.json(); 736 + expect(data.error).toContain("boards"); 737 + expect(mockDeleteRecord).not.toHaveBeenCalled(); 738 + }); 739 + 740 + it("returns 400 for invalid category ID", async () => { 741 + const res = await app.request("/api/admin/categories/not-a-number", { 742 + method: "DELETE", 743 + }); 744 + 745 + expect(res.status).toBe(400); 746 + const data = await res.json(); 747 + expect(data.error).toContain("Invalid category ID"); 748 + expect(mockDeleteRecord).not.toHaveBeenCalled(); 749 + }); 750 + 751 + it("returns 404 when category not found", async () => { 752 + const res = await app.request("/api/admin/categories/99999", { 753 + method: "DELETE", 754 + }); 755 + 756 + expect(res.status).toBe(404); 757 + expect(mockDeleteRecord).not.toHaveBeenCalled(); 758 + }); 759 + 760 + it("returns 401 when unauthenticated", async () => { 761 + mockUser = null; 762 + 763 + const res = await app.request(`/api/admin/categories/${categoryId}`, { 764 + method: "DELETE", 765 + }); 766 + 767 + expect(res.status).toBe(401); 768 + expect(mockDeleteRecord).not.toHaveBeenCalled(); 769 + }); 770 + 771 + it("returns 503 when PDS network error on delete", async () => { 772 + mockDeleteRecord.mockRejectedValue(new Error("fetch failed")); 773 + 774 + const res = await app.request(`/api/admin/categories/${categoryId}`, { 775 + method: "DELETE", 776 + }); 777 + 778 + expect(res.status).toBe(503); 779 + }); 780 + 781 + it("returns 500 when ForumAgent unavailable", async () => { 782 + ctx.forumAgent = null; 783 + 784 + const res = await app.request(`/api/admin/categories/${categoryId}`, { 785 + method: "DELETE", 786 + }); 787 + 788 + expect(res.status).toBe(500); 789 + }); 790 + }); 791 + ``` 792 + 793 + **Step 4: Run tests to confirm they fail** 794 + 795 + ```bash 796 + PATH=/path/to/.devenv/profile/bin:/bin:/usr/bin:$PATH pnpm --filter @atbb/appview exec vitest run src/routes/__tests__/admin.test.ts 2>&1 | tail -30 797 + ``` 798 + 799 + Expected: DELETE tests fail with 404 (route not found). 800 + 801 + --- 802 + 803 + ## Task 6: Implement DELETE /api/admin/categories/:id 804 + 805 + **Files:** 806 + - Modify: `apps/appview/src/routes/admin.ts` 807 + 808 + **Step 1: Add the DELETE /api/admin/categories/:id handler** 809 + 810 + Add after the PUT handler, before `return app;`: 811 + 812 + ```typescript 813 + /** 814 + * DELETE /api/admin/categories/:id 815 + * 816 + * Delete a category. Pre-flight: refuses with 409 if any boards reference this 817 + * category in the DB. If clear, calls deleteRecord on the Forum DID's PDS. 818 + * The firehose indexer removes the DB row asynchronously. 819 + */ 820 + app.delete( 821 + "/categories/:id", 822 + requireAuth(ctx), 823 + requirePermission(ctx, "space.atbb.permission.manageCategories"), 824 + async (c) => { 825 + const idParam = c.req.param("id"); 826 + const id = parseBigIntParam(idParam); 827 + if (id === null) { 828 + return c.json({ error: "Invalid category ID" }, 400); 829 + } 830 + 831 + let category: typeof categories.$inferSelect; 832 + try { 833 + const [row] = await ctx.db 834 + .select() 835 + .from(categories) 836 + .where(and(eq(categories.id, id), eq(categories.did, ctx.config.forumDid))) 837 + .limit(1); 838 + 839 + if (!row) { 840 + return c.json({ error: "Category not found" }, 404); 841 + } 842 + category = row; 843 + } catch (error) { 844 + return handleReadError(c, error, "Failed to look up category", { 845 + operation: "DELETE /api/admin/categories/:id", 846 + logger: ctx.logger, 847 + id: idParam, 848 + }); 849 + } 850 + 851 + // Pre-flight: refuse if any boards reference this category 852 + try { 853 + const [boardCount] = await ctx.db 854 + .select({ count: count() }) 855 + .from(boards) 856 + .where(eq(boards.categoryId, id)); 857 + 858 + if (boardCount && boardCount.count > 0) { 859 + return c.json( 860 + { error: "Cannot delete category with boards. Remove all boards first." }, 861 + 409 862 + ); 863 + } 864 + } catch (error) { 865 + return handleReadError(c, error, "Failed to check category boards", { 866 + operation: "DELETE /api/admin/categories/:id", 867 + logger: ctx.logger, 868 + id: idParam, 869 + }); 870 + } 871 + 872 + const { agent, error: agentError } = getForumAgentOrError(ctx, c, "DELETE /api/admin/categories/:id"); 873 + if (agentError) return agentError; 874 + 875 + try { 876 + await agent.com.atproto.repo.deleteRecord({ 877 + repo: ctx.config.forumDid, 878 + collection: "space.atbb.forum.category", 879 + rkey: category.rkey, 880 + }); 881 + 882 + return c.json({ success: true }); 883 + } catch (error) { 884 + return handleWriteError(c, error, "Failed to delete category", { 885 + operation: "DELETE /api/admin/categories/:id", 886 + logger: ctx.logger, 887 + id: idParam, 888 + }); 889 + } 890 + } 891 + ); 892 + ``` 893 + 894 + **Step 2: Run all tests** 895 + 896 + ```bash 897 + PATH=/path/to/.devenv/profile/bin:/bin:/usr/bin:$PATH pnpm --filter @atbb/appview exec vitest run src/routes/__tests__/admin.test.ts 2>&1 | tail -30 898 + ``` 899 + 900 + Expected: All tests pass. 901 + 902 + **Step 3: Run full test suite** 903 + 904 + ```bash 905 + PATH=/path/to/.devenv/profile/bin:/bin:/usr/bin:$PATH pnpm --filter @atbb/appview test 2>&1 | tail -20 906 + ``` 907 + 908 + Expected: All pass. 909 + 910 + **Step 4: Commit** 911 + 912 + ```bash 913 + git add apps/appview/src/routes/admin.ts apps/appview/src/routes/__tests__/admin.test.ts 914 + git commit -m "feat(appview): DELETE /api/admin/categories/:id delete endpoint (ATB-44)" 915 + ``` 916 + 917 + --- 918 + 919 + ## Task 7: Add Bruno API collection files 920 + 921 + **Files:** 922 + - Create: `bruno/AppView API/Admin/Create Category.bru` 923 + - Create: `bruno/AppView API/Admin/Update Category.bru` 924 + - Create: `bruno/AppView API/Admin/Delete Category.bru` 925 + 926 + **Step 1: Create the three .bru files** 927 + 928 + `bruno/AppView API/Admin/Create Category.bru`: 929 + ``` 930 + meta { 931 + name: Create Category 932 + type: http 933 + seq: 10 934 + } 935 + 936 + post { 937 + url: {{appview_url}}/api/admin/categories 938 + } 939 + 940 + body:json { 941 + { 942 + "name": "General Discussion", 943 + "description": "Talk about anything.", 944 + "sortOrder": 1 945 + } 946 + } 947 + 948 + assert { 949 + res.status: eq 201 950 + res.body.uri: isDefined 951 + res.body.cid: isDefined 952 + } 953 + 954 + docs { 955 + Create a new forum category. Writes space.atbb.forum.category to the Forum DID's PDS. 956 + The firehose indexer creates the DB row asynchronously. 957 + 958 + **Requires:** space.atbb.permission.manageCategories 959 + 960 + Body: 961 + - name (required): Category display name 962 + - description (optional): Short description 963 + - sortOrder (optional): Numeric sort position (lower = first) 964 + 965 + Returns (201): 966 + { 967 + "uri": "at://did:plc:.../space.atbb.forum.category/abc123", 968 + "cid": "bafyrei..." 969 + } 970 + 971 + Error codes: 972 + - 400: Missing or empty name, malformed JSON 973 + - 401: Not authenticated 974 + - 403: Missing manageCategories permission 975 + - 500: ForumAgent not configured 976 + - 503: PDS network error 977 + } 978 + ``` 979 + 980 + `bruno/AppView API/Admin/Update Category.bru`: 981 + ``` 982 + meta { 983 + name: Update Category 984 + type: http 985 + seq: 11 986 + } 987 + 988 + put { 989 + url: {{appview_url}}/api/admin/categories/:id 990 + } 991 + 992 + params:path { 993 + id: {{category_id}} 994 + } 995 + 996 + body:json { 997 + { 998 + "name": "Updated Name", 999 + "description": "Updated description.", 1000 + "sortOrder": 2 1001 + } 1002 + } 1003 + 1004 + assert { 1005 + res.status: eq 200 1006 + res.body.uri: isDefined 1007 + res.body.cid: isDefined 1008 + } 1009 + 1010 + docs { 1011 + Update an existing forum category. Fetches existing rkey from DB, calls putRecord 1012 + with updated fields preserving the original createdAt. 1013 + 1014 + **Requires:** space.atbb.permission.manageCategories 1015 + 1016 + Path params: 1017 + - id: Category database ID (bigint as string) 1018 + 1019 + Body: 1020 + - name (required): New display name 1021 + - description (optional): New description 1022 + - sortOrder (optional): New sort position 1023 + 1024 + Returns (200): 1025 + { 1026 + "uri": "at://did:plc:.../space.atbb.forum.category/abc123", 1027 + "cid": "bafyrei..." 1028 + } 1029 + 1030 + Error codes: 1031 + - 400: Missing name, empty name, invalid ID format, malformed JSON 1032 + - 401: Not authenticated 1033 + - 403: Missing manageCategories permission 1034 + - 404: Category not found 1035 + - 500: ForumAgent not configured 1036 + - 503: PDS network error 1037 + } 1038 + ``` 1039 + 1040 + `bruno/AppView API/Admin/Delete Category.bru`: 1041 + ``` 1042 + meta { 1043 + name: Delete Category 1044 + type: http 1045 + seq: 12 1046 + } 1047 + 1048 + delete { 1049 + url: {{appview_url}}/api/admin/categories/:id 1050 + } 1051 + 1052 + params:path { 1053 + id: {{category_id}} 1054 + } 1055 + 1056 + assert { 1057 + res.status: eq 200 1058 + res.body.success: isTrue 1059 + } 1060 + 1061 + docs { 1062 + Delete a forum category. Pre-flight check refuses with 409 if any boards reference 1063 + this category. If clear, calls deleteRecord on the Forum DID's PDS. 1064 + The firehose indexer removes the DB row asynchronously. 1065 + 1066 + **Requires:** space.atbb.permission.manageCategories 1067 + 1068 + Path params: 1069 + - id: Category database ID (bigint as string) 1070 + 1071 + Returns (200): 1072 + { 1073 + "success": true 1074 + } 1075 + 1076 + Error codes: 1077 + - 400: Invalid ID format 1078 + - 401: Not authenticated 1079 + - 403: Missing manageCategories permission 1080 + - 404: Category not found 1081 + - 409: Category has boards — remove them first 1082 + - 500: ForumAgent not configured 1083 + - 503: PDS network error 1084 + } 1085 + ``` 1086 + 1087 + **Step 2: Commit** 1088 + 1089 + ```bash 1090 + git add "bruno/AppView API/Admin/Create Category.bru" \ 1091 + "bruno/AppView API/Admin/Update Category.bru" \ 1092 + "bruno/AppView API/Admin/Delete Category.bru" 1093 + git commit -m "docs(bruno): add category management API collection (ATB-44)" 1094 + ``` 1095 + 1096 + --- 1097 + 1098 + ## Final verification 1099 + 1100 + ```bash 1101 + # Run full test suite 1102 + PATH=/path/to/.devenv/profile/bin:/bin:/usr/bin:$PATH pnpm --filter @atbb/appview test 1103 + 1104 + # Lint fix 1105 + PATH=/path/to/.devenv/profile/bin:/bin:/usr/bin:$PATH pnpm --filter @atbb/appview lint:fix 1106 + ``` 1107 + 1108 + Then update Linear ATB-44 to Done and mark items complete in `docs/atproto-forum-plan.md`.

+1327

docs/plans/complete/2026-02-28-atb-45-board-management-endpoints.md

··· 1 + # Board Management Endpoints Implementation Plan (ATB-45) 2 + 3 + > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. 4 + 5 + **Goal:** Add `POST /api/admin/boards`, `PUT /api/admin/boards/:id`, and `DELETE /api/admin/boards/:id` endpoints to the AppView, following the same PDS-first write pattern as category management. 6 + 7 + **Architecture:** All mutations write to the Forum DID's PDS via `ForumAgent.putRecord()`/`deleteRecord()`; the firehose indexer handles DB updates asynchronously. The only synchronous DB read is looking up the category CID on create (needed to build the `categoryRef` strongRef required by the lexicon). Delete pre-flights against `posts.boardId` to refuse with 409 if posts exist. 8 + 9 + **Tech Stack:** Hono, Drizzle ORM (postgres.js), `@atproto/common-web` (TID generation), Vitest, Bruno. 10 + 11 + --- 12 + 13 + ## Key files to understand before starting 14 + 15 + - **Implementation:** `apps/appview/src/routes/admin.ts` — add the 3 new endpoints at the bottom (before `return app`) 16 + - **Tests:** `apps/appview/src/routes/__tests__/admin.test.ts` — add a new `describe.sequential("POST /api/admin/boards"...)` block after the categories tests (around line 1450) 17 + - **DB schema:** `packages/db/src/schema.ts` — `boards` table has `id`, `did`, `rkey`, `cid`, `name`, `description`, `slug`, `sortOrder`, `categoryId`, `categoryUri`, `createdAt`, `indexedAt` 18 + - **Lexicon:** `packages/lexicon/lexicons/space/atbb/forum/board.yaml` — record has `name`, `description`, `slug`, `sortOrder`, `category` (a `categoryRef` object: `{ category: { uri, cid } }`) 19 + - **Route helpers:** `apps/appview/src/lib/route-errors.ts` — `handleRouteError`, `safeParseJsonBody`, `getForumAgentOrError` 20 + - **Bruno templates:** `bruno/AppView API/Admin/Create Category.bru`, `Update Category.bru`, `Delete Category.bru` — copy as starting point 21 + 22 + ## Test setup pattern (copy from categories tests) 23 + 24 + The test file already has mocks at the top for `requireAuth`, `requirePermission`, `mockPutRecord`, and `mockDeleteRecord`. The board tests reuse these same mocks. No new setup needed — just add new `describe.sequential` blocks after the existing categories describe blocks. 25 + 26 + For tests that need a category in the DB (create + edit lookups), insert with: 27 + ```typescript 28 + const [cat] = await ctx.db.insert(categories).values({ 29 + did: ctx.config.forumDid, 30 + rkey: "tid-test-cat", 31 + cid: "bafycat", 32 + name: "Test Category", 33 + createdAt: new Date("2026-01-01T00:00:00.000Z"), 34 + indexedAt: new Date(), 35 + }).returning({ id: categories.id }); 36 + const categoryUri = `at://${ctx.config.forumDid}/space.atbb.forum.category/tid-test-cat`; 37 + ``` 38 + 39 + For tests that need a board in the DB (edit + delete), insert with: 40 + ```typescript 41 + const [brd] = await ctx.db.insert(boards).values({ 42 + did: ctx.config.forumDid, 43 + rkey: "tid-test-board", 44 + cid: "bafyboard", 45 + name: "Original Name", 46 + description: "Original description", 47 + sortOrder: 1, 48 + categoryId: cat.id, 49 + categoryUri, 50 + createdAt: new Date("2026-01-01T00:00:00.000Z"), 51 + indexedAt: new Date(), 52 + }).returning({ id: boards.id }); 53 + const boardId = brd.id.toString(); 54 + ``` 55 + 56 + --- 57 + 58 + ## Task 1: POST /api/admin/boards — failing tests 59 + 60 + **Files:** 61 + - Modify: `apps/appview/src/routes/__tests__/admin.test.ts` (append after line ~1450, after the closing `});` of the DELETE categories describe block) 62 + 63 + **Step 1: Write the failing tests** 64 + 65 + Add this new describe block to the end of the `describe.sequential("Admin Routes", ...)` block (just before the outer closing `});`): 66 + 67 + ```typescript 68 + describe.sequential("POST /api/admin/boards", () => { 69 + let categoryUri: string; 70 + 71 + beforeEach(async () => { 72 + await ctx.cleanDatabase(); 73 + 74 + mockUser = { did: "did:plc:test-admin" }; 75 + mockPutRecord.mockClear(); 76 + mockDeleteRecord.mockClear(); 77 + mockPutRecord.mockResolvedValue({ 78 + data: { 79 + uri: `at://${ctx.config.forumDid}/space.atbb.forum.board/tid123`, 80 + cid: "bafyboard", 81 + }, 82 + }); 83 + 84 + // Insert a category the tests can reference 85 + await ctx.db.insert(categories).values({ 86 + did: ctx.config.forumDid, 87 + rkey: "tid-test-cat", 88 + cid: "bafycat", 89 + name: "Test Category", 90 + createdAt: new Date("2026-01-01T00:00:00.000Z"), 91 + indexedAt: new Date(), 92 + }); 93 + categoryUri = `at://${ctx.config.forumDid}/space.atbb.forum.category/tid-test-cat`; 94 + }); 95 + 96 + it("creates board with valid body → 201 and putRecord called with categoryRef", async () => { 97 + const res = await app.request("/api/admin/boards", { 98 + method: "POST", 99 + headers: { "Content-Type": "application/json" }, 100 + body: JSON.stringify({ name: "General Chat", description: "Talk here.", sortOrder: 1, categoryUri }), 101 + }); 102 + 103 + expect(res.status).toBe(201); 104 + const data = await res.json(); 105 + expect(data.uri).toContain("/space.atbb.forum.board/"); 106 + expect(data.cid).toBe("bafyboard"); 107 + expect(mockPutRecord).toHaveBeenCalledWith( 108 + expect.objectContaining({ 109 + repo: ctx.config.forumDid, 110 + collection: "space.atbb.forum.board", 111 + rkey: expect.any(String), 112 + record: expect.objectContaining({ 113 + $type: "space.atbb.forum.board", 114 + name: "General Chat", 115 + description: "Talk here.", 116 + sortOrder: 1, 117 + category: { category: { uri: categoryUri, cid: "bafycat" } }, 118 + createdAt: expect.any(String), 119 + }), 120 + }) 121 + ); 122 + }); 123 + 124 + it("creates board without optional fields → 201", async () => { 125 + const res = await app.request("/api/admin/boards", { 126 + method: "POST", 127 + headers: { "Content-Type": "application/json" }, 128 + body: JSON.stringify({ name: "Minimal", categoryUri }), 129 + }); 130 + 131 + expect(res.status).toBe(201); 132 + expect(mockPutRecord).toHaveBeenCalledWith( 133 + expect.objectContaining({ 134 + record: expect.objectContaining({ name: "Minimal" }), 135 + }) 136 + ); 137 + }); 138 + 139 + it("returns 400 when name is missing → no PDS write", async () => { 140 + const res = await app.request("/api/admin/boards", { 141 + method: "POST", 142 + headers: { "Content-Type": "application/json" }, 143 + body: JSON.stringify({ categoryUri }), 144 + }); 145 + 146 + expect(res.status).toBe(400); 147 + const data = await res.json(); 148 + expect(data.error).toContain("name"); 149 + expect(mockPutRecord).not.toHaveBeenCalled(); 150 + }); 151 + 152 + it("returns 400 when name is empty string → no PDS write", async () => { 153 + const res = await app.request("/api/admin/boards", { 154 + method: "POST", 155 + headers: { "Content-Type": "application/json" }, 156 + body: JSON.stringify({ name: " ", categoryUri }), 157 + }); 158 + 159 + expect(res.status).toBe(400); 160 + expect(mockPutRecord).not.toHaveBeenCalled(); 161 + }); 162 + 163 + it("returns 400 when categoryUri is missing → no PDS write", async () => { 164 + const res = await app.request("/api/admin/boards", { 165 + method: "POST", 166 + headers: { "Content-Type": "application/json" }, 167 + body: JSON.stringify({ name: "Test Board" }), 168 + }); 169 + 170 + expect(res.status).toBe(400); 171 + const data = await res.json(); 172 + expect(data.error).toContain("categoryUri"); 173 + expect(mockPutRecord).not.toHaveBeenCalled(); 174 + }); 175 + 176 + it("returns 404 when categoryUri references unknown category → no PDS write", async () => { 177 + const res = await app.request("/api/admin/boards", { 178 + method: "POST", 179 + headers: { "Content-Type": "application/json" }, 180 + body: JSON.stringify({ name: "Test Board", categoryUri: `at://${ctx.config.forumDid}/space.atbb.forum.category/unknown999` }), 181 + }); 182 + 183 + expect(res.status).toBe(404); 184 + const data = await res.json(); 185 + expect(data.error).toContain("Category not found"); 186 + expect(mockPutRecord).not.toHaveBeenCalled(); 187 + }); 188 + 189 + it("returns 400 for malformed JSON", async () => { 190 + const res = await app.request("/api/admin/boards", { 191 + method: "POST", 192 + headers: { "Content-Type": "application/json" }, 193 + body: "{ bad json }", 194 + }); 195 + 196 + expect(res.status).toBe(400); 197 + const data = await res.json(); 198 + expect(data.error).toContain("Invalid JSON"); 199 + expect(mockPutRecord).not.toHaveBeenCalled(); 200 + }); 201 + 202 + it("returns 401 when unauthenticated → no PDS write", async () => { 203 + mockUser = null; 204 + 205 + const res = await app.request("/api/admin/boards", { 206 + method: "POST", 207 + headers: { "Content-Type": "application/json" }, 208 + body: JSON.stringify({ name: "Test", categoryUri }), 209 + }); 210 + 211 + expect(res.status).toBe(401); 212 + expect(mockPutRecord).not.toHaveBeenCalled(); 213 + }); 214 + 215 + it("returns 503 when PDS network error", async () => { 216 + mockPutRecord.mockRejectedValue(new Error("fetch failed")); 217 + 218 + const res = await app.request("/api/admin/boards", { 219 + method: "POST", 220 + headers: { "Content-Type": "application/json" }, 221 + body: JSON.stringify({ name: "Test", categoryUri }), 222 + }); 223 + 224 + expect(res.status).toBe(503); 225 + const data = await res.json(); 226 + expect(data.error).toContain("Unable to reach external service"); 227 + expect(mockPutRecord).toHaveBeenCalled(); 228 + }); 229 + 230 + it("returns 500 when ForumAgent unavailable", async () => { 231 + ctx.forumAgent = null; 232 + 233 + const res = await app.request("/api/admin/boards", { 234 + method: "POST", 235 + headers: { "Content-Type": "application/json" }, 236 + body: JSON.stringify({ name: "Test", categoryUri }), 237 + }); 238 + 239 + expect(res.status).toBe(500); 240 + const data = await res.json(); 241 + expect(data.error).toContain("Forum agent not available"); 242 + }); 243 + 244 + it("returns 403 when user lacks manageCategories permission", async () => { 245 + const { requirePermission } = await import("../../middleware/permissions.js"); 246 + const mockRequirePermission = requirePermission as any; 247 + mockRequirePermission.mockImplementation(() => async (c: any) => { 248 + return c.json({ error: "Forbidden" }, 403); 249 + }); 250 + 251 + const testApp = new Hono<{ Variables: Variables }>().route("/api/admin", createAdminRoutes(ctx)); 252 + const res = await testApp.request("/api/admin/boards", { 253 + method: "POST", 254 + headers: { "Content-Type": "application/json" }, 255 + body: JSON.stringify({ name: "Test", categoryUri }), 256 + }); 257 + 258 + expect(res.status).toBe(403); 259 + expect(mockPutRecord).not.toHaveBeenCalled(); 260 + 261 + mockRequirePermission.mockImplementation(() => async (_c: any, next: any) => { 262 + await next(); 263 + }); 264 + }); 265 + }); 266 + ``` 267 + 268 + **Step 2: Run tests to verify they fail** 269 + 270 + ```bash 271 + export PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:/bin:/usr/bin:$PATH 272 + cd /Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo 273 + pnpm --filter @atbb/appview exec vitest run src/routes/__tests__/admin.test.ts 2>&1 | grep -E "FAIL|PASS|Error|✓|×|POST.*boards" | head -30 274 + ``` 275 + 276 + Expected: Tests fail with "Cannot find route" or similar. 277 + 278 + **Step 3: Commit the failing tests** 279 + 280 + ```bash 281 + git add apps/appview/src/routes/__tests__/admin.test.ts 282 + git commit -m "test(appview): add failing tests for POST /api/admin/boards (ATB-45)" 283 + ``` 284 + 285 + --- 286 + 287 + ## Task 2: POST /api/admin/boards — implementation 288 + 289 + **Files:** 290 + - Modify: `apps/appview/src/routes/admin.ts` (add before `return app;` at the end, around line 701) 291 + 292 + **Step 1: Add the POST /api/admin/boards endpoint** 293 + 294 + Insert the following handler before the `return app;` line: 295 + 296 + ```typescript 297 + /** 298 + * POST /api/admin/boards 299 + * 300 + * Create a new forum board within a category. Fetches the category's CID from DB 301 + * to build the categoryRef strongRef required by the lexicon. Writes 302 + * space.atbb.forum.board to the Forum DID's PDS via putRecord. 303 + * The firehose indexer creates the DB row asynchronously. 304 + */ 305 + app.post( 306 + "/boards", 307 + requireAuth(ctx), 308 + requirePermission(ctx, "space.atbb.permission.manageCategories"), 309 + async (c) => { 310 + const { body, error: parseError } = await safeParseJsonBody(c); 311 + if (parseError) return parseError; 312 + 313 + const { name, description, sortOrder, categoryUri } = body; 314 + 315 + if (typeof name !== "string" || name.trim().length === 0) { 316 + return c.json({ error: "name is required and must be a non-empty string" }, 400); 317 + } 318 + 319 + if (typeof categoryUri !== "string" || !categoryUri.startsWith("at://")) { 320 + return c.json({ error: "categoryUri is required and must be a valid AT URI" }, 400); 321 + } 322 + 323 + // Derive rkey from the categoryUri to look up the category in the DB 324 + const categoryRkey = categoryUri.split("/").pop(); 325 + 326 + let category: typeof categories.$inferSelect; 327 + try { 328 + const [row] = await ctx.db 329 + .select() 330 + .from(categories) 331 + .where( 332 + and( 333 + eq(categories.did, ctx.config.forumDid), 334 + eq(categories.rkey, categoryRkey ?? "") 335 + ) 336 + ) 337 + .limit(1); 338 + 339 + if (!row) { 340 + return c.json({ error: "Category not found" }, 404); 341 + } 342 + category = row; 343 + } catch (error) { 344 + return handleRouteError(c, error, "Failed to look up category", { 345 + operation: "POST /api/admin/boards", 346 + logger: ctx.logger, 347 + categoryUri, 348 + }); 349 + } 350 + 351 + const { agent, error: agentError } = getForumAgentOrError(ctx, c, "POST /api/admin/boards"); 352 + if (agentError) return agentError; 353 + 354 + const rkey = TID.nextStr(); 355 + const now = new Date().toISOString(); 356 + 357 + try { 358 + const result = await agent.com.atproto.repo.putRecord({ 359 + repo: ctx.config.forumDid, 360 + collection: "space.atbb.forum.board", 361 + rkey, 362 + record: { 363 + $type: "space.atbb.forum.board", 364 + name: name.trim(), 365 + ...(typeof description === "string" && { description: description.trim() }), 366 + ...(Number.isInteger(sortOrder) && sortOrder >= 0 && { sortOrder }), 367 + category: { category: { uri: categoryUri, cid: category.cid } }, 368 + createdAt: now, 369 + }, 370 + }); 371 + 372 + return c.json({ uri: result.data.uri, cid: result.data.cid }, 201); 373 + } catch (error) { 374 + return handleRouteError(c, error, "Failed to create board", { 375 + operation: "POST /api/admin/boards", 376 + logger: ctx.logger, 377 + categoryUri, 378 + }); 379 + } 380 + } 381 + ); 382 + ``` 383 + 384 + **Step 2: Run tests to verify they pass** 385 + 386 + ```bash 387 + export PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:/bin:/usr/bin:$PATH 388 + cd /Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo 389 + pnpm --filter @atbb/appview exec vitest run src/routes/__tests__/admin.test.ts 2>&1 | grep -E "FAIL|PASS|POST.*boards|✓|×" | head -30 390 + ``` 391 + 392 + Expected: All POST /api/admin/boards tests PASS. 393 + 394 + **Step 3: Commit** 395 + 396 + ```bash 397 + git add apps/appview/src/routes/admin.ts 398 + git commit -m "feat(appview): POST /api/admin/boards create endpoint (ATB-45)" 399 + ``` 400 + 401 + --- 402 + 403 + ## Task 3: PUT /api/admin/boards/:id — failing tests 404 + 405 + **Files:** 406 + - Modify: `apps/appview/src/routes/__tests__/admin.test.ts` (append after the POST boards describe block) 407 + 408 + **Step 1: Write the failing tests** 409 + 410 + ```typescript 411 + describe.sequential("PUT /api/admin/boards/:id", () => { 412 + let boardId: string; 413 + let categoryUri: string; 414 + 415 + beforeEach(async () => { 416 + await ctx.cleanDatabase(); 417 + 418 + mockUser = { did: "did:plc:test-admin" }; 419 + mockPutRecord.mockClear(); 420 + mockDeleteRecord.mockClear(); 421 + mockPutRecord.mockResolvedValue({ 422 + data: { 423 + uri: `at://${ctx.config.forumDid}/space.atbb.forum.board/tid-test-board`, 424 + cid: "bafyboardupdated", 425 + }, 426 + }); 427 + 428 + // Insert a category and a board 429 + const [cat] = await ctx.db.insert(categories).values({ 430 + did: ctx.config.forumDid, 431 + rkey: "tid-test-cat", 432 + cid: "bafycat", 433 + name: "Test Category", 434 + createdAt: new Date("2026-01-01T00:00:00.000Z"), 435 + indexedAt: new Date(), 436 + }).returning({ id: categories.id }); 437 + 438 + categoryUri = `at://${ctx.config.forumDid}/space.atbb.forum.category/tid-test-cat`; 439 + 440 + const [brd] = await ctx.db.insert(boards).values({ 441 + did: ctx.config.forumDid, 442 + rkey: "tid-test-board", 443 + cid: "bafyboard", 444 + name: "Original Name", 445 + description: "Original description", 446 + sortOrder: 1, 447 + categoryId: cat.id, 448 + categoryUri, 449 + createdAt: new Date("2026-01-01T00:00:00.000Z"), 450 + indexedAt: new Date(), 451 + }).returning({ id: boards.id }); 452 + 453 + boardId = brd.id.toString(); 454 + }); 455 + 456 + it("updates board with all fields → 200 and putRecord called with same rkey", async () => { 457 + const res = await app.request(`/api/admin/boards/${boardId}`, { 458 + method: "PUT", 459 + headers: { "Content-Type": "application/json" }, 460 + body: JSON.stringify({ name: "Renamed Board", description: "New description", sortOrder: 2 }), 461 + }); 462 + 463 + expect(res.status).toBe(200); 464 + const data = await res.json(); 465 + expect(data.uri).toContain("/space.atbb.forum.board/"); 466 + expect(data.cid).toBe("bafyboardupdated"); 467 + expect(mockPutRecord).toHaveBeenCalledWith( 468 + expect.objectContaining({ 469 + repo: ctx.config.forumDid, 470 + collection: "space.atbb.forum.board", 471 + rkey: "tid-test-board", 472 + record: expect.objectContaining({ 473 + $type: "space.atbb.forum.board", 474 + name: "Renamed Board", 475 + description: "New description", 476 + sortOrder: 2, 477 + category: { category: { uri: categoryUri, cid: "bafycat" } }, 478 + }), 479 + }) 480 + ); 481 + }); 482 + 483 + it("updates board without optional fields → falls back to existing values", async () => { 484 + const res = await app.request(`/api/admin/boards/${boardId}`, { 485 + method: "PUT", 486 + headers: { "Content-Type": "application/json" }, 487 + body: JSON.stringify({ name: "Renamed Only" }), 488 + }); 489 + 490 + expect(res.status).toBe(200); 491 + expect(mockPutRecord).toHaveBeenCalledWith( 492 + expect.objectContaining({ 493 + record: expect.objectContaining({ 494 + name: "Renamed Only", 495 + description: "Original description", 496 + sortOrder: 1, 497 + }), 498 + }) 499 + ); 500 + }); 501 + 502 + it("returns 400 when name is missing", async () => { 503 + const res = await app.request(`/api/admin/boards/${boardId}`, { 504 + method: "PUT", 505 + headers: { "Content-Type": "application/json" }, 506 + body: JSON.stringify({ description: "No name" }), 507 + }); 508 + 509 + expect(res.status).toBe(400); 510 + const data = await res.json(); 511 + expect(data.error).toContain("name"); 512 + expect(mockPutRecord).not.toHaveBeenCalled(); 513 + }); 514 + 515 + it("returns 400 when name is empty string", async () => { 516 + const res = await app.request(`/api/admin/boards/${boardId}`, { 517 + method: "PUT", 518 + headers: { "Content-Type": "application/json" }, 519 + body: JSON.stringify({ name: " " }), 520 + }); 521 + 522 + expect(res.status).toBe(400); 523 + expect(mockPutRecord).not.toHaveBeenCalled(); 524 + }); 525 + 526 + it("returns 400 for non-numeric ID", async () => { 527 + const res = await app.request("/api/admin/boards/not-a-number", { 528 + method: "PUT", 529 + headers: { "Content-Type": "application/json" }, 530 + body: JSON.stringify({ name: "Test" }), 531 + }); 532 + 533 + expect(res.status).toBe(400); 534 + expect(mockPutRecord).not.toHaveBeenCalled(); 535 + }); 536 + 537 + it("returns 404 when board not found", async () => { 538 + const res = await app.request("/api/admin/boards/99999", { 539 + method: "PUT", 540 + headers: { "Content-Type": "application/json" }, 541 + body: JSON.stringify({ name: "Test" }), 542 + }); 543 + 544 + expect(res.status).toBe(404); 545 + const data = await res.json(); 546 + expect(data.error).toContain("Board not found"); 547 + expect(mockPutRecord).not.toHaveBeenCalled(); 548 + }); 549 + 550 + it("returns 400 for malformed JSON", async () => { 551 + const res = await app.request(`/api/admin/boards/${boardId}`, { 552 + method: "PUT", 553 + headers: { "Content-Type": "application/json" }, 554 + body: "{ bad json }", 555 + }); 556 + 557 + expect(res.status).toBe(400); 558 + expect(mockPutRecord).not.toHaveBeenCalled(); 559 + }); 560 + 561 + it("returns 401 when unauthenticated", async () => { 562 + mockUser = null; 563 + 564 + const res = await app.request(`/api/admin/boards/${boardId}`, { 565 + method: "PUT", 566 + headers: { "Content-Type": "application/json" }, 567 + body: JSON.stringify({ name: "Test" }), 568 + }); 569 + 570 + expect(res.status).toBe(401); 571 + expect(mockPutRecord).not.toHaveBeenCalled(); 572 + }); 573 + 574 + it("returns 503 when PDS network error", async () => { 575 + mockPutRecord.mockRejectedValue(new Error("fetch failed")); 576 + 577 + const res = await app.request(`/api/admin/boards/${boardId}`, { 578 + method: "PUT", 579 + headers: { "Content-Type": "application/json" }, 580 + body: JSON.stringify({ name: "Test" }), 581 + }); 582 + 583 + expect(res.status).toBe(503); 584 + const data = await res.json(); 585 + expect(data.error).toContain("Unable to reach external service"); 586 + }); 587 + 588 + it("returns 500 when ForumAgent unavailable", async () => { 589 + ctx.forumAgent = null; 590 + 591 + const res = await app.request(`/api/admin/boards/${boardId}`, { 592 + method: "PUT", 593 + headers: { "Content-Type": "application/json" }, 594 + body: JSON.stringify({ name: "Test" }), 595 + }); 596 + 597 + expect(res.status).toBe(500); 598 + const data = await res.json(); 599 + expect(data.error).toContain("Forum agent not available"); 600 + }); 601 + 602 + it("returns 403 when user lacks manageCategories permission", async () => { 603 + const { requirePermission } = await import("../../middleware/permissions.js"); 604 + const mockRequirePermission = requirePermission as any; 605 + mockRequirePermission.mockImplementation(() => async (c: any) => { 606 + return c.json({ error: "Forbidden" }, 403); 607 + }); 608 + 609 + const testApp = new Hono<{ Variables: Variables }>().route("/api/admin", createAdminRoutes(ctx)); 610 + const res = await testApp.request(`/api/admin/boards/${boardId}`, { 611 + method: "PUT", 612 + headers: { "Content-Type": "application/json" }, 613 + body: JSON.stringify({ name: "Test" }), 614 + }); 615 + 616 + expect(res.status).toBe(403); 617 + expect(mockPutRecord).not.toHaveBeenCalled(); 618 + 619 + mockRequirePermission.mockImplementation(() => async (_c: any, next: any) => { 620 + await next(); 621 + }); 622 + }); 623 + }); 624 + ``` 625 + 626 + **Step 2: Run tests to verify they fail** 627 + 628 + ```bash 629 + export PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:/bin:/usr/bin:$PATH 630 + cd /Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo 631 + pnpm --filter @atbb/appview exec vitest run src/routes/__tests__/admin.test.ts 2>&1 | grep -E "FAIL|PUT.*boards|×" | head -20 632 + ``` 633 + 634 + Expected: PUT /api/admin/boards tests FAIL. 635 + 636 + **Step 3: Commit** 637 + 638 + ```bash 639 + git add apps/appview/src/routes/__tests__/admin.test.ts 640 + git commit -m "test(appview): add failing tests for PUT /api/admin/boards/:id (ATB-45)" 641 + ``` 642 + 643 + --- 644 + 645 + ## Task 4: PUT /api/admin/boards/:id — implementation 646 + 647 + **Files:** 648 + - Modify: `apps/appview/src/routes/admin.ts` (add after the POST /boards handler, before `return app;`) 649 + 650 + **Step 1: Add the PUT /api/admin/boards/:id endpoint** 651 + 652 + Note: The `boards` table stores `categoryUri` and `categoryId`. The edit endpoint re-uses the existing `categoryUri` and fetches the category CID. This avoids clients being able to secretly reparent a board by passing a new `categoryUri` on edit (category changes would need a dedicated reparent operation). 653 + 654 + ```typescript 655 + /** 656 + * PUT /api/admin/boards/:id 657 + * 658 + * Update an existing board's name, description, and sortOrder. 659 + * Fetches existing rkey + categoryUri from DB, then putRecord with updated fields. 660 + * Preserves the original categoryRef and createdAt. 661 + * The firehose indexer updates the DB row asynchronously. 662 + */ 663 + app.put( 664 + "/boards/:id", 665 + requireAuth(ctx), 666 + requirePermission(ctx, "space.atbb.permission.manageCategories"), 667 + async (c) => { 668 + const idParam = c.req.param("id"); 669 + const id = parseBigIntParam(idParam); 670 + if (id === null) { 671 + return c.json({ error: "Invalid board ID" }, 400); 672 + } 673 + 674 + const { body, error: parseError } = await safeParseJsonBody(c); 675 + if (parseError) return parseError; 676 + 677 + const { name, description, sortOrder } = body; 678 + 679 + if (typeof name !== "string" || name.trim().length === 0) { 680 + return c.json({ error: "name is required and must be a non-empty string" }, 400); 681 + } 682 + 683 + let board: typeof boards.$inferSelect; 684 + try { 685 + const [row] = await ctx.db 686 + .select() 687 + .from(boards) 688 + .where(and(eq(boards.id, id), eq(boards.did, ctx.config.forumDid))) 689 + .limit(1); 690 + 691 + if (!row) { 692 + return c.json({ error: "Board not found" }, 404); 693 + } 694 + board = row; 695 + } catch (error) { 696 + return handleRouteError(c, error, "Failed to look up board", { 697 + operation: "PUT /api/admin/boards/:id", 698 + logger: ctx.logger, 699 + id: idParam, 700 + }); 701 + } 702 + 703 + // Fetch category CID to build the categoryRef strongRef 704 + let categoryCid: string; 705 + try { 706 + const categoryRkey = board.categoryUri.split("/").pop() ?? ""; 707 + const [cat] = await ctx.db 708 + .select({ cid: categories.cid }) 709 + .from(categories) 710 + .where( 711 + and( 712 + eq(categories.did, ctx.config.forumDid), 713 + eq(categories.rkey, categoryRkey) 714 + ) 715 + ) 716 + .limit(1); 717 + 718 + if (!cat) { 719 + return c.json({ error: "Category not found" }, 404); 720 + } 721 + categoryCid = cat.cid; 722 + } catch (error) { 723 + return handleRouteError(c, error, "Failed to look up category", { 724 + operation: "PUT /api/admin/boards/:id", 725 + logger: ctx.logger, 726 + id: idParam, 727 + }); 728 + } 729 + 730 + const { agent, error: agentError } = getForumAgentOrError(ctx, c, "PUT /api/admin/boards/:id"); 731 + if (agentError) return agentError; 732 + 733 + // putRecord is a full replacement — fall back to existing values for 734 + // optional fields not provided in the request body, to avoid data loss. 735 + const resolvedDescription = typeof description === "string" 736 + ? description.trim() 737 + : board.description; 738 + const resolvedSortOrder = (Number.isInteger(sortOrder) && sortOrder >= 0) 739 + ? sortOrder 740 + : board.sortOrder; 741 + 742 + try { 743 + const result = await agent.com.atproto.repo.putRecord({ 744 + repo: ctx.config.forumDid, 745 + collection: "space.atbb.forum.board", 746 + rkey: board.rkey, 747 + record: { 748 + $type: "space.atbb.forum.board", 749 + name: name.trim(), 750 + ...(resolvedDescription != null && { description: resolvedDescription }), 751 + ...(resolvedSortOrder != null && { sortOrder: resolvedSortOrder }), 752 + category: { category: { uri: board.categoryUri, cid: categoryCid } }, 753 + createdAt: board.createdAt.toISOString(), 754 + }, 755 + }); 756 + 757 + return c.json({ uri: result.data.uri, cid: result.data.cid }); 758 + } catch (error) { 759 + return handleRouteError(c, error, "Failed to update board", { 760 + operation: "PUT /api/admin/boards/:id", 761 + logger: ctx.logger, 762 + id: idParam, 763 + }); 764 + } 765 + } 766 + ); 767 + ``` 768 + 769 + **Step 2: Run tests to verify they pass** 770 + 771 + ```bash 772 + export PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:/bin:/usr/bin:$PATH 773 + cd /Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo 774 + pnpm --filter @atbb/appview exec vitest run src/routes/__tests__/admin.test.ts 2>&1 | grep -E "FAIL|PASS|PUT.*boards|✓|×" | head -30 775 + ``` 776 + 777 + Expected: All PUT /api/admin/boards tests PASS. 778 + 779 + **Step 3: Commit** 780 + 781 + ```bash 782 + git add apps/appview/src/routes/admin.ts 783 + git commit -m "feat(appview): PUT /api/admin/boards/:id update endpoint (ATB-45)" 784 + ``` 785 + 786 + --- 787 + 788 + ## Task 5: DELETE /api/admin/boards/:id — failing tests 789 + 790 + **Files:** 791 + - Modify: `apps/appview/src/routes/__tests__/admin.test.ts` (append after the PUT boards describe block) 792 + 793 + **Step 1: Write the failing tests** 794 + 795 + ```typescript 796 + describe.sequential("DELETE /api/admin/boards/:id", () => { 797 + let boardId: string; 798 + let categoryUri: string; 799 + 800 + beforeEach(async () => { 801 + await ctx.cleanDatabase(); 802 + 803 + mockUser = { did: "did:plc:test-admin" }; 804 + mockPutRecord.mockClear(); 805 + mockDeleteRecord.mockClear(); 806 + mockDeleteRecord.mockResolvedValue({}); 807 + 808 + // Insert a category and a board 809 + const [cat] = await ctx.db.insert(categories).values({ 810 + did: ctx.config.forumDid, 811 + rkey: "tid-test-cat", 812 + cid: "bafycat", 813 + name: "Test Category", 814 + createdAt: new Date("2026-01-01T00:00:00.000Z"), 815 + indexedAt: new Date(), 816 + }).returning({ id: categories.id }); 817 + 818 + categoryUri = `at://${ctx.config.forumDid}/space.atbb.forum.category/tid-test-cat`; 819 + 820 + const [brd] = await ctx.db.insert(boards).values({ 821 + did: ctx.config.forumDid, 822 + rkey: "tid-test-board", 823 + cid: "bafyboard", 824 + name: "Test Board", 825 + categoryId: cat.id, 826 + categoryUri, 827 + createdAt: new Date("2026-01-01T00:00:00.000Z"), 828 + indexedAt: new Date(), 829 + }).returning({ id: boards.id }); 830 + 831 + boardId = brd.id.toString(); 832 + }); 833 + 834 + it("deletes empty board → 200 and deleteRecord called", async () => { 835 + const res = await app.request(`/api/admin/boards/${boardId}`, { 836 + method: "DELETE", 837 + }); 838 + 839 + expect(res.status).toBe(200); 840 + const data = await res.json(); 841 + expect(data.success).toBe(true); 842 + expect(mockDeleteRecord).toHaveBeenCalledWith( 843 + expect.objectContaining({ 844 + repo: ctx.config.forumDid, 845 + collection: "space.atbb.forum.board", 846 + rkey: "tid-test-board", 847 + }) 848 + ); 849 + }); 850 + 851 + it("returns 409 when board has posts → deleteRecord NOT called", async () => { 852 + // Insert a user and a post referencing this board 853 + await ctx.db.insert(users).values({ 854 + did: "did:plc:test-user", 855 + handle: "testuser.bsky.social", 856 + indexedAt: new Date(), 857 + }); 858 + 859 + const [brd] = await ctx.db.select().from(boards).where(eq(boards.rkey, "tid-test-board")).limit(1); 860 + 861 + // Insert a post with boardId set 862 + await ctx.db.insert(posts).values({ 863 + did: "did:plc:test-user", 864 + rkey: "tid-test-post", 865 + cid: "bafypost", 866 + text: "Hello world", 867 + boardId: brd.id, 868 + boardUri: `at://${ctx.config.forumDid}/space.atbb.forum.board/tid-test-board`, 869 + forumUri: `at://${ctx.config.forumDid}/space.atbb.forum.forum/self`, 870 + createdAt: new Date(), 871 + indexedAt: new Date(), 872 + }); 873 + 874 + const res = await app.request(`/api/admin/boards/${boardId}`, { 875 + method: "DELETE", 876 + }); 877 + 878 + expect(res.status).toBe(409); 879 + const data = await res.json(); 880 + expect(data.error).toContain("posts"); 881 + expect(mockDeleteRecord).not.toHaveBeenCalled(); 882 + }); 883 + 884 + it("returns 400 for non-numeric ID", async () => { 885 + const res = await app.request("/api/admin/boards/not-a-number", { 886 + method: "DELETE", 887 + }); 888 + 889 + expect(res.status).toBe(400); 890 + expect(mockDeleteRecord).not.toHaveBeenCalled(); 891 + }); 892 + 893 + it("returns 404 when board not found", async () => { 894 + const res = await app.request("/api/admin/boards/99999", { 895 + method: "DELETE", 896 + }); 897 + 898 + expect(res.status).toBe(404); 899 + const data = await res.json(); 900 + expect(data.error).toContain("Board not found"); 901 + expect(mockDeleteRecord).not.toHaveBeenCalled(); 902 + }); 903 + 904 + it("returns 401 when unauthenticated", async () => { 905 + mockUser = null; 906 + 907 + const res = await app.request(`/api/admin/boards/${boardId}`, { 908 + method: "DELETE", 909 + }); 910 + 911 + expect(res.status).toBe(401); 912 + expect(mockDeleteRecord).not.toHaveBeenCalled(); 913 + }); 914 + 915 + it("returns 503 when PDS network error", async () => { 916 + mockDeleteRecord.mockRejectedValue(new Error("fetch failed")); 917 + 918 + const res = await app.request(`/api/admin/boards/${boardId}`, { 919 + method: "DELETE", 920 + }); 921 + 922 + expect(res.status).toBe(503); 923 + const data = await res.json(); 924 + expect(data.error).toContain("Unable to reach external service"); 925 + }); 926 + 927 + it("returns 500 when ForumAgent unavailable", async () => { 928 + ctx.forumAgent = null; 929 + 930 + const res = await app.request(`/api/admin/boards/${boardId}`, { 931 + method: "DELETE", 932 + }); 933 + 934 + expect(res.status).toBe(500); 935 + const data = await res.json(); 936 + expect(data.error).toContain("Forum agent not available"); 937 + }); 938 + 939 + it("returns 403 when user lacks manageCategories permission", async () => { 940 + const { requirePermission } = await import("../../middleware/permissions.js"); 941 + const mockRequirePermission = requirePermission as any; 942 + mockRequirePermission.mockImplementation(() => async (c: any) => { 943 + return c.json({ error: "Forbidden" }, 403); 944 + }); 945 + 946 + const testApp = new Hono<{ Variables: Variables }>().route("/api/admin", createAdminRoutes(ctx)); 947 + const res = await testApp.request(`/api/admin/boards/${boardId}`, { 948 + method: "DELETE", 949 + }); 950 + 951 + expect(res.status).toBe(403); 952 + expect(mockDeleteRecord).not.toHaveBeenCalled(); 953 + 954 + mockRequirePermission.mockImplementation(() => async (_c: any, next: any) => { 955 + await next(); 956 + }); 957 + }); 958 + }); 959 + ``` 960 + 961 + **Important:** The DELETE test that inserts a post needs to import `posts` from `@atbb/db`. Check the import at the top of the test file — if `posts` is not already imported, add it to the existing import: 962 + 963 + ```typescript 964 + import { memberships, roles, rolePermissions, users, forums, categories, boards, posts } from "@atbb/db"; 965 + ``` 966 + 967 + **Step 2: Run tests to verify they fail** 968 + 969 + ```bash 970 + export PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:/bin:/usr/bin:$PATH 971 + cd /Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo 972 + pnpm --filter @atbb/appview exec vitest run src/routes/__tests__/admin.test.ts 2>&1 | grep -E "FAIL|DELETE.*boards|×" | head -20 973 + ``` 974 + 975 + Expected: DELETE /api/admin/boards tests FAIL. 976 + 977 + **Step 3: Commit** 978 + 979 + ```bash 980 + git add apps/appview/src/routes/__tests__/admin.test.ts 981 + git commit -m "test(appview): add failing tests for DELETE /api/admin/boards/:id (ATB-45)" 982 + ``` 983 + 984 + --- 985 + 986 + ## Task 6: DELETE /api/admin/boards/:id — implementation 987 + 988 + **Files:** 989 + - Modify: `apps/appview/src/routes/admin.ts` (add after the PUT /boards/:id handler, before `return app;`) 990 + 991 + **Step 1: Add the DELETE /api/admin/boards/:id endpoint** 992 + 993 + Also add `posts` to the existing Drizzle import at the top of the file: 994 + ```typescript 995 + import { memberships, roles, rolePermissions, users, forums, backfillProgress, backfillErrors, categories, boards, posts } from "@atbb/db"; 996 + ``` 997 + 998 + Then add the handler: 999 + 1000 + ```typescript 1001 + /** 1002 + * DELETE /api/admin/boards/:id 1003 + * 1004 + * Delete a board. Pre-flight: refuses with 409 if any posts have boardId 1005 + * pointing to this board. If clear, calls deleteRecord on the Forum DID's PDS. 1006 + * The firehose indexer removes the DB row asynchronously. 1007 + */ 1008 + app.delete( 1009 + "/boards/:id", 1010 + requireAuth(ctx), 1011 + requirePermission(ctx, "space.atbb.permission.manageCategories"), 1012 + async (c) => { 1013 + const idParam = c.req.param("id"); 1014 + const id = parseBigIntParam(idParam); 1015 + if (id === null) { 1016 + return c.json({ error: "Invalid board ID" }, 400); 1017 + } 1018 + 1019 + let board: typeof boards.$inferSelect; 1020 + try { 1021 + const [row] = await ctx.db 1022 + .select() 1023 + .from(boards) 1024 + .where(and(eq(boards.id, id), eq(boards.did, ctx.config.forumDid))) 1025 + .limit(1); 1026 + 1027 + if (!row) { 1028 + return c.json({ error: "Board not found" }, 404); 1029 + } 1030 + board = row; 1031 + } catch (error) { 1032 + return handleRouteError(c, error, "Failed to look up board", { 1033 + operation: "DELETE /api/admin/boards/:id", 1034 + logger: ctx.logger, 1035 + id: idParam, 1036 + }); 1037 + } 1038 + 1039 + // Pre-flight: refuse if any posts reference this board 1040 + try { 1041 + const [postCount] = await ctx.db 1042 + .select({ count: count() }) 1043 + .from(posts) 1044 + .where(eq(posts.boardId, id)); 1045 + 1046 + if (postCount && postCount.count > 0) { 1047 + return c.json( 1048 + { error: "Cannot delete board with posts. Remove all posts first." }, 1049 + 409 1050 + ); 1051 + } 1052 + } catch (error) { 1053 + return handleRouteError(c, error, "Failed to check board posts", { 1054 + operation: "DELETE /api/admin/boards/:id", 1055 + logger: ctx.logger, 1056 + id: idParam, 1057 + }); 1058 + } 1059 + 1060 + const { agent, error: agentError } = getForumAgentOrError(ctx, c, "DELETE /api/admin/boards/:id"); 1061 + if (agentError) return agentError; 1062 + 1063 + try { 1064 + await agent.com.atproto.repo.deleteRecord({ 1065 + repo: ctx.config.forumDid, 1066 + collection: "space.atbb.forum.board", 1067 + rkey: board.rkey, 1068 + }); 1069 + 1070 + return c.json({ success: true }); 1071 + } catch (error) { 1072 + return handleRouteError(c, error, "Failed to delete board", { 1073 + operation: "DELETE /api/admin/boards/:id", 1074 + logger: ctx.logger, 1075 + id: idParam, 1076 + }); 1077 + } 1078 + } 1079 + ); 1080 + ``` 1081 + 1082 + **Step 2: Run all admin tests to verify everything passes** 1083 + 1084 + ```bash 1085 + export PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:/bin:/usr/bin:$PATH 1086 + cd /Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo 1087 + pnpm --filter @atbb/appview exec vitest run src/routes/__tests__/admin.test.ts 2>&1 | tail -20 1088 + ``` 1089 + 1090 + Expected: All tests PASS, no failures. 1091 + 1092 + **Step 3: Run the full test suite** 1093 + 1094 + ```bash 1095 + export PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:/bin:/usr/bin:$PATH 1096 + cd /Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo 1097 + pnpm --filter @atbb/appview exec vitest run 2>&1 | tail -20 1098 + ``` 1099 + 1100 + Expected: All tests PASS. 1101 + 1102 + **Step 4: Commit** 1103 + 1104 + ```bash 1105 + git add apps/appview/src/routes/admin.ts 1106 + git commit -m "feat(appview): DELETE /api/admin/boards/:id delete endpoint (ATB-45)" 1107 + ``` 1108 + 1109 + --- 1110 + 1111 + ## Task 7: Bruno collection — board management 1112 + 1113 + **Files:** 1114 + - Create: `bruno/AppView API/Admin/Create Board.bru` 1115 + - Create: `bruno/AppView API/Admin/Update Board.bru` 1116 + - Create: `bruno/AppView API/Admin/Delete Board.bru` 1117 + 1118 + **Step 1: Create Create Board.bru** 1119 + 1120 + ``` 1121 + meta { 1122 + name: Create Board 1123 + type: http 1124 + seq: 13 1125 + } 1126 + 1127 + post { 1128 + url: {{appview_url}}/api/admin/boards 1129 + } 1130 + 1131 + body:json { 1132 + { 1133 + "name": "General Chat", 1134 + "description": "Talk about anything.", 1135 + "sortOrder": 1, 1136 + "categoryUri": "{{category_uri}}" 1137 + } 1138 + } 1139 + 1140 + assert { 1141 + res.status: eq 201 1142 + res.body.uri: isDefined 1143 + res.body.cid: isDefined 1144 + } 1145 + 1146 + docs { 1147 + Create a new forum board within a category. Fetches the category's CID from DB 1148 + to build the categoryRef strongRef. Writes space.atbb.forum.board to the Forum 1149 + DID's PDS. The firehose indexer creates the DB row asynchronously. 1150 + 1151 + **Requires:** space.atbb.permission.manageCategories 1152 + 1153 + Body: 1154 + - name (required): Board display name 1155 + - categoryUri (required): AT URI of the parent category 1156 + - description (optional): Short description 1157 + - sortOrder (optional): Numeric sort position (lower = first) 1158 + 1159 + Returns (201): 1160 + { 1161 + "uri": "at://did:plc:.../space.atbb.forum.board/abc123", 1162 + "cid": "bafyrei..." 1163 + } 1164 + 1165 + Error codes: 1166 + - 400: Missing or empty name, missing categoryUri, malformed JSON 1167 + - 401: Not authenticated 1168 + - 403: Missing manageCategories permission 1169 + - 404: categoryUri references unknown category 1170 + - 500: ForumAgent not configured 1171 + - 503: PDS network error 1172 + } 1173 + ``` 1174 + 1175 + **Step 2: Create Update Board.bru** 1176 + 1177 + ``` 1178 + meta { 1179 + name: Update Board 1180 + type: http 1181 + seq: 14 1182 + } 1183 + 1184 + put { 1185 + url: {{appview_url}}/api/admin/boards/:id 1186 + } 1187 + 1188 + params:path { 1189 + id: {{board_id}} 1190 + } 1191 + 1192 + body:json { 1193 + { 1194 + "name": "General Chat (renamed)", 1195 + "description": "Updated description.", 1196 + "sortOrder": 2 1197 + } 1198 + } 1199 + 1200 + assert { 1201 + res.status: eq 200 1202 + res.body.uri: isDefined 1203 + res.body.cid: isDefined 1204 + } 1205 + 1206 + docs { 1207 + Update an existing forum board's name, description, and sortOrder. 1208 + Fetches existing rkey and categoryRef from DB, calls putRecord with updated 1209 + fields preserving the original category and createdAt. 1210 + 1211 + **Requires:** space.atbb.permission.manageCategories 1212 + 1213 + Path params: 1214 + - id: Board database ID (bigint as string) 1215 + 1216 + Body: 1217 + - name (required): New display name 1218 + - description (optional): New description (falls back to existing if omitted) 1219 + - sortOrder (optional): New sort position (falls back to existing if omitted) 1220 + 1221 + Returns (200): 1222 + { 1223 + "uri": "at://did:plc:.../space.atbb.forum.board/abc123", 1224 + "cid": "bafyrei..." 1225 + } 1226 + 1227 + Error codes: 1228 + - 400: Missing name, empty name, invalid ID format, malformed JSON 1229 + - 401: Not authenticated 1230 + - 403: Missing manageCategories permission 1231 + - 404: Board not found 1232 + - 500: ForumAgent not configured 1233 + - 503: PDS network error 1234 + } 1235 + ``` 1236 + 1237 + **Step 3: Create Delete Board.bru** 1238 + 1239 + ``` 1240 + meta { 1241 + name: Delete Board 1242 + type: http 1243 + seq: 15 1244 + } 1245 + 1246 + delete { 1247 + url: {{appview_url}}/api/admin/boards/:id 1248 + } 1249 + 1250 + params:path { 1251 + id: {{board_id}} 1252 + } 1253 + 1254 + assert { 1255 + res.status: eq 200 1256 + res.body.success: isTrue 1257 + } 1258 + 1259 + docs { 1260 + Delete a forum board. Pre-flight check refuses with 409 if any posts reference 1261 + this board. If clear, calls deleteRecord on the Forum DID's PDS. 1262 + The firehose indexer removes the DB row asynchronously. 1263 + 1264 + **Requires:** space.atbb.permission.manageCategories 1265 + 1266 + Path params: 1267 + - id: Board database ID (bigint as string) 1268 + 1269 + Returns (200): 1270 + { 1271 + "success": true 1272 + } 1273 + 1274 + Error codes: 1275 + - 400: Invalid ID format 1276 + - 401: Not authenticated 1277 + - 403: Missing manageCategories permission 1278 + - 404: Board not found 1279 + - 409: Board has posts — remove them first 1280 + - 500: ForumAgent not configured 1281 + - 503: PDS network error 1282 + } 1283 + ``` 1284 + 1285 + **Step 4: Commit** 1286 + 1287 + ```bash 1288 + git add "bruno/AppView API/Admin/Create Board.bru" "bruno/AppView API/Admin/Update Board.bru" "bruno/AppView API/Admin/Delete Board.bru" 1289 + git commit -m "docs(bruno): add board management API collection (ATB-45)" 1290 + ``` 1291 + 1292 + --- 1293 + 1294 + ## Task 8: Lint, full test run, and verification 1295 + 1296 + **Step 1: Run lint fix** 1297 + 1298 + ```bash 1299 + export PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:/bin:/usr/bin:$PATH 1300 + cd /Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo 1301 + pnpm --filter @atbb/appview lint:fix 1302 + ``` 1303 + 1304 + Expected: No unfixable errors. 1305 + 1306 + **Step 2: Run full test suite** 1307 + 1308 + ```bash 1309 + export PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:/bin:/usr/bin:$PATH 1310 + cd /Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo 1311 + pnpm --filter @atbb/appview exec vitest run 2>&1 | tail -20 1312 + ``` 1313 + 1314 + Expected: All tests PASS. 1315 + 1316 + **Step 3: Update Linear issue** 1317 + 1318 + Mark ATB-45 as "In Progress" in Linear, then as "Done" once the branch is ready for review. 1319 + 1320 + **Step 4: Request code review** 1321 + 1322 + Follow the commit-push-pr skill to push and open a PR: 1323 + ```bash 1324 + git log --oneline origin/main..HEAD 1325 + ``` 1326 + 1327 + Verify all commits are present, then push and open PR against `main`.

Configure Feed

Configure Feed