docs: trim CLAUDE.md to gotchas-only, add CONTRIBUTING.md

+290 -337

2 changed files

expand all

CLAUDE.md

+26 -337

CLAUDE.md

··· 55 55 56 56 **When adding new env vars to tests:** Update `turbo.json` immediately, or tests will mysteriously fail when run via Turbo but pass when run directly. 57 57 58 - ### When to Run Tests 59 - 60 - **Before every commit:** 61 - ```sh 62 - pnpm test # Verify all tests pass 63 - git add . 64 - git commit -m "feat: your changes" 65 - ``` 66 - 67 - **Before requesting code review:** 68 - ```sh 69 - pnpm build # Ensure clean build 70 - pnpm test # Verify all tests pass 71 - # Only then push and request review 72 - ``` 73 - 74 - **After fixing review feedback:** 75 - ```sh 76 - # Make fixes 77 - pnpm test # Verify tests still pass 78 - # Push updates 79 - ``` 80 - 81 - ### Test Requirements 82 - 83 - **All new features must include tests:** 84 - - API endpoints: Test success cases, error cases, edge cases 85 - - Business logic: Test all code paths and error conditions 86 - - Error handling: Test that errors are caught and logged appropriately 87 - - Security features: Test authentication, authorization, input validation 88 - 89 - **Test quality standards:** 90 - - Tests must be independent (no shared state between tests) 91 - - Use descriptive test names that explain what is being tested 92 - - Mock external dependencies (databases, APIs, network calls) 93 - - Test error paths, not just happy paths 94 - - Verify logging and error messages are correct 95 - 96 - **Red flags (do not commit):** 97 - - Skipped tests (`test.skip`, `it.skip`) without Linear issue tracking why 98 - - Tests that pass locally but fail in CI 99 - - Tests that require manual setup or specific data 100 - - Tests with hardcoded timing (`setTimeout`, `sleep`) - use proper mocks 101 - - Placeholder/stub tests that don't actually test anything 102 - 103 58 **Placeholder tests are prohibited:** 104 59 ```typescript 105 60 // ❌ FORBIDDEN: Stub tests provide false confidence ··· 129 84 }); 130 85 ``` 131 86 132 - **Why this matters:** Stub tests pass in CI, creating false confidence that code is tested. They hide bugs that would be caught by real tests with actual assertions. 133 - 134 - **If you're unsure how to test something:** Leave a `// TODO: Add test for X` comment and create a Linear issue. Never commit a stub test that pretends to test something. 135 - 136 - 137 - ### Test Coverage Expectations 138 - 139 - While we don't enforce strict coverage percentages, aim for: 140 - - **Critical paths:** 100% coverage (authentication, authorization, data integrity) 141 - - **Error handling:** All catch blocks should be tested 142 - - **API endpoints:** All routes should have tests 143 - - **Business logic:** All functions with branching logic should be tested 144 - 145 - **Do not:** 146 - - Skip writing tests to "move faster" - untested code breaks in production 147 - - Write tests after requesting review - tests inform implementation 148 - - Rely on manual testing alone - automated tests catch regressions 87 + **Skipped tests (`test.skip`, `it.skip`) must have a Linear issue tracking why.** Skipping without a tracked reason is prohibited. 149 88 150 89 ### Before Requesting Code Review 151 90 ··· 178 117 - **References:** Use `com.atproto.repo.strongRef` wrapped in named defs (e.g., `forumRef`, `subjectRef`). 179 118 - **Extensible fields:** Use `knownValues` (not `enum`) for strings that may grow (permissions, reaction types, mod actions). 180 119 - **Record ownership:** 181 - - Forum DID owns: `forum.forum`, `forum.category`, `forum.role`, `modAction` 120 + - Forum DID owns: `forum.forum`, `forum.category`, `forum.board`, `forum.role`, `modAction` 182 121 - User DID owns: `post`, `membership`, `reaction` 183 122 184 123 ## AT Protocol Conventions ··· 455 394 - Prefer returning `null` over fake values (`"0"`, `new Date()`) 456 395 - Document fallback behavior in JSDoc if unavoidable 457 396 458 - ### Defensive Programming 459 - 460 - **All list queries must have defensive limits:** 461 - ```typescript 462 - .from(categories) 463 - .orderBy(categories.sortOrder) 464 - .limit(1000); // Prevent memory exhaustion on unbounded queries 465 - ``` 466 - 467 - **Filter deleted/soft-deleted records:** 468 - ```typescript 469 - .where(and( 470 - eq(posts.rootPostId, topicId), 471 - eq(posts.deleted, false) // Never show deleted content to users 472 - )) 473 - ``` 474 - 475 - **Use ordering for consistent results:** 476 - ```typescript 477 - .orderBy(asc(posts.createdAt)) // Chronological order for replies 478 - ``` 479 - 480 - ### Global Error Handler 481 - 482 - The Hono app must have a global error handler as a safety net: 483 - ```typescript 484 - app.onError((err, c) => { 485 - console.error("Unhandled error in route handler", { 486 - path: c.req.path, 487 - method: c.req.method, 488 - error: err.message, 489 - stack: err.stack, 490 - }); 491 - return c.json( 492 - { 493 - error: "An internal error occurred. Please try again later.", 494 - ...(process.env.NODE_ENV !== "production" && { 495 - details: err.message, 496 - }), 497 - }, 498 - 500 499 - ); 500 - }); 501 - ``` 502 - 503 - ### Testing Error Handling 504 - 505 - **Test error classification, not just error catching.** Users need actionable feedback: "retry later" (503) vs "report this bug" (500). 506 - 507 - ```typescript 508 - // ✅ Test network errors return 503 (retry later) 509 - it("returns 503 when PDS connection fails", async () => { 510 - mockPutRecord.mockRejectedValueOnce(new Error("fetch failed")); 511 - const res = await app.request("/api/topics", { 512 - method: "POST", 513 - body: JSON.stringify({ text: "Test" }) 514 - }); 515 - expect(res.status).toBe(503); // Not 500! 516 - const data = await res.json(); 517 - expect(data.error).toContain("Unable to reach your PDS"); 518 - }); 519 - 520 - // ✅ Test server errors return 500 (bug report) 521 - it("returns 500 for unexpected database errors", async () => { 522 - mockPutRecord.mockRejectedValueOnce(new Error("Database connection lost")); 523 - const res = await app.request("/api/topics", { 524 - method: "POST", 525 - body: JSON.stringify({ text: "Test" }) 526 - }); 527 - expect(res.status).toBe(500); // Not 503! 528 - const data = await res.json(); 529 - expect(data.error).not.toContain("PDS"); // Generic message for server errors 530 - }); 531 - 532 - // ✅ Test input validation returns 400 533 - it("returns 400 for malformed JSON", async () => { 534 - const res = await app.request("/api/topics", { 535 - method: "POST", 536 - headers: { "Content-Type": "application/json" }, 537 - body: "{ invalid json }" 538 - }); 539 - expect(res.status).toBe(400); 540 - const data = await res.json(); 541 - expect(data.error).toContain("Invalid JSON"); 542 - }); 543 - ``` 544 - 545 - **Error classification patterns to test:** 546 - - **400 (Bad Request):** Invalid input, missing required fields, malformed JSON 547 - - **404 (Not Found):** Resource doesn't exist (forum, post, user) 548 - - **503 (Service Unavailable):** Network errors, PDS connection failures, timeouts — user should retry 549 - - **500 (Internal Server Error):** Unexpected errors, database errors — needs bug investigation 550 - 551 397 ## Security-Critical Code Standards 552 398 553 399 When implementing authentication, authorization, or permission systems, follow these additional requirements: ··· 574 420 return false; // Role deleted = deny access 575 421 } 576 422 577 - return role.permissions.includes(permission) || 578 - role.permissions.includes("*"); 423 + // Permissions live in role_permissions join table, not role.permissions array 424 + const [match] = await ctx.db 425 + .select() 426 + .from(rolePermissions) 427 + .where(and( 428 + eq(rolePermissions.roleId, role.id), 429 + or( 430 + eq(rolePermissions.permission, permission), 431 + eq(rolePermissions.permission, "*") 432 + ) 433 + )) 434 + .limit(1); 435 + 436 + return !!match; 579 437 } catch (error) { 580 438 if (isProgrammingError(error)) throw error; 581 439 582 440 console.error("Failed to check permissions - denying access", { 583 - did, permission, error: ... 441 + did, permission, error: String(error) 584 442 }); 585 443 return false; // Error = deny access (fail closed) 586 444 } ··· 608 466 }); 609 467 ``` 610 468 611 - ### 2. Security Test Coverage Requirements 612 - 613 - **All security features require comprehensive tests covering:** 614 - 615 - - ✅ **Happy path** - Authorized user succeeds 616 - - ✅ **Unauthorized user** - Returns 401 (not authenticated) 617 - - ✅ **Forbidden** - Returns 403 (authenticated but lacks permission) 618 - - ✅ **Privilege escalation prevention** - Cannot grant yourself higher privileges 619 - - ✅ **Peer protection** - Cannot modify users with equal authority 620 - - ✅ **Fail-closed behavior** - Database/network errors deny access 621 - - ✅ **Input validation** - Malformed requests return 400, not 500 622 - - ✅ **Error classification** - Network errors (503) vs server errors (500) 623 - 624 - **Example security test suite structure:** 625 - ```typescript 626 - describe("POST /api/admin/members/:did/role (security-critical)", () => { 627 - describe("Authorization", () => { 628 - it("returns 401 when not authenticated", async () => { /* ... */ }); 629 - it("returns 403 when user lacks manageRoles permission", async () => { /* ... */ }); 630 - }); 631 - 632 - describe("Privilege Escalation Prevention", () => { 633 - it("prevents admin from assigning owner role (higher authority)", async () => { 634 - // Admin (priority 10) tries to assign Owner (priority 0) → 403 635 - }); 636 - 637 - it("prevents admin from assigning admin role (equal authority)", async () => { 638 - // Admin (priority 10) tries to assign Admin (priority 10) → 403 639 - }); 640 - 641 - it("allows admin to assign moderator role (lower authority)", async () => { 642 - // Admin (priority 10) assigns Moderator (priority 20) → 200 643 - }); 644 - }); 645 - 646 - describe("Error Handling", () => { 647 - it("returns 503 when PDS connection fails (network error)", async () => { /* ... */ }); 648 - it("returns 500 when database query fails (server error)", async () => { /* ... */ }); 649 - it("returns 400 for malformed roleUri (input validation)", async () => { /* ... */ }); 650 - }); 651 - }); 652 - ``` 653 - 654 - ### 3. Startup Failures for Missing Security Infrastructure 469 + ### 2. Startup Failures for Missing Security Infrastructure 655 470 656 471 **Security-critical infrastructure must fail fast on startup, not at first request.** 657 472 ··· 680 495 681 496 **Why this matters:** If the permission system is broken, every request will fail authorization. It's better to fail startup loudly than silently deploy a non-functional system. 682 497 683 - ### 4. Security Code Review Checklist 684 - 685 - Before requesting review for authentication/authorization code, verify: 686 - 687 - - [ ] All permission checks fail closed (deny access on error) 688 - - [ ] Database errors in security checks are caught and logged 689 - - [ ] Programming errors (TypeError) are re-thrown, not caught 690 - - [ ] Privilege escalation is prevented (equal/higher authority blocked) 691 - - [ ] Tests cover unauthorized (401), forbidden (403), and error cases 692 - - [ ] Error messages don't leak internal details (priority values, permission names) 693 - - [ ] Middleware composition is correct (auth before permission checks) 694 - - [ ] Startup fails fast if security infrastructure is unavailable 695 - 696 498 ## Documentation & Project Tracking 697 499 698 500 **Keep these synchronized when completing work:** ··· 707 509 - Add comments documenting implementation details when marking Done 708 510 - Keep status in sync with actual codebase state, not planning estimates 709 511 710 - 3. **Workflow:** When finishing a task: 512 + 3. **`docs/plans/` convention:** 513 + - Active/in-progress plan documents go directly in `docs/plans/` 514 + - Completed plan documents move to `docs/plans/complete/` when work is shipped 515 + 516 + 4. **Workflow:** When finishing a task: 711 517 ```sh 712 518 # 1. Run tests to verify implementation is correct 713 519 pnpm test ··· 726 532 727 533 ## Bruno API Collections 728 534 729 - **CRITICAL: Keep Bruno collections synchronized with API changes.** 535 + **CRITICAL: Update Bruno collections in the SAME commit as route implementation.** 730 536 731 - The `bruno/` directory contains [Bruno](https://www.usebruno.com/) collections that serve dual purpose: 732 - 1. **Interactive API testing** during development 733 - 2. **Version-controlled API documentation** that stays in sync with code 537 + The `bruno/` directory contains [Bruno](https://www.usebruno.com/) collections for API documentation and interactive testing. See `CONTRIBUTING.md` for the full update workflow and file template. 734 538 735 - ### When to Update Bruno Collections 736 - 737 - **When adding a new API endpoint:** 738 - 1. Create a new `.bru` file in the appropriate `bruno/AppView API/` subdirectory 739 - 2. Follow the naming pattern: use descriptive names like `Create Topic.bru`, `Get Forum Metadata.bru` 740 - 3. Include all request details: method, URL with variables, headers, body (if POST/PUT) 741 - 4. Add comprehensive documentation in the `docs` block explaining: 742 - - Required/optional parameters 743 - - Expected response format with example 744 - - All possible error codes (400, 401, 404, 500, 503) 745 - - Authentication requirements 746 - - Validation rules 747 - 5. Add assertions to validate responses automatically 748 - 749 - **When modifying an existing endpoint:** 750 - 1. Update the corresponding `.bru` file in `bruno/AppView API/` 751 - 2. Update parameter descriptions if inputs changed 752 - 3. Update response documentation if output format changed 753 - 4. Update error documentation if new error cases added 754 - 5. Update assertions if validation logic changed 755 - 756 - **When removing an endpoint:** 757 - 1. Delete the corresponding `.bru` file 758 - 2. Update `bruno/README.md` if it referenced the removed endpoint 759 - 760 - **When adding new environment variables:** 761 - 1. Update `bruno/environments/local.bru` with local development values 762 - 2. Update `bruno/environments/dev.bru` with deployment values 763 - 3. Document the variable in `bruno/README.md` under "Environment Variables Reference" 764 - 765 - ### Bruno File Template 766 - 767 - When creating new `.bru` files, follow this template: 768 - 769 - ```bru 770 - meta { 771 - name: Endpoint Name 772 - type: http 773 - seq: 1 774 - } 775 - 776 - get { 777 - url: {{appview_url}}/api/path 778 - } 779 - 780 - params:query { 781 - param1: {{variable}} 782 - } 783 - 784 - headers { 785 - Content-Type: application/json 786 - } 787 - 788 - body:json { 789 - { 790 - "field": "value" 791 - } 792 - } 793 - 794 - assert { 795 - res.status: eq 200 796 - res.body.field: isDefined 797 - } 798 - 799 - docs { 800 - Brief description of what this endpoint does. 801 - 802 - Path/query/body params: 803 - - param1: Description (type, required/optional) 804 - 805 - Returns: 806 - { 807 - "field": "value" 808 - } 809 - 810 - Error codes: 811 - - 400: Bad request (invalid input) 812 - - 401: Unauthorized (requires auth) 813 - - 404: Not found 814 - - 500: Server error 815 - 816 - Notes: 817 - - Any special considerations or validation rules 818 - } 819 - ``` 820 - 821 - ### Workflow Integration 822 - 823 - **When committing API changes, update Bruno collections in the SAME commit:** 824 - 825 - ```sh 826 - # Example: Adding a new endpoint 827 - git add apps/appview/src/routes/my-route.ts 828 - git add apps/appview/src/routes/__tests__/my-route.test.ts 829 - git add bruno/AppView\ API/MyRoute/New\ Endpoint.bru 830 - git commit -m "feat: add new endpoint for X 831 - 832 - - Implements POST /api/my-endpoint 833 - - Adds validation for Y 834 - - Updates Bruno collection with request documentation" 835 - ``` 836 - 837 - **Why commit together:** Bruno collections are API documentation. Keeping them in the same commit ensures the documentation is never out of sync with the implementation. 838 - 839 - ### Testing Bruno Collections 840 - 841 - Before committing: 842 - 1. Open the collection in Bruno 843 - 2. Test each modified request against your local dev server (`pnpm dev`) 844 - 3. Verify assertions pass (green checkmarks) 845 - 4. Verify documentation is accurate and complete 846 - 5. Check that error scenarios are documented (not just happy path) 847 - 848 - ### Common Mistakes 539 + **Common Mistakes:** 849 540 850 541 **DON'T:** 851 542 - Commit API changes without updating Bruno collections ··· 858 549 - Update Bruno files in the same commit as route implementation 859 550 - Use environment variables for all URLs and test data 860 551 - Document all HTTP status codes the endpoint can return 861 - - Include example request/response bodies that match actual behavior 862 - - Test requests locally before committing 863 552 864 553 ## Git Conventions 865 554

+264

CONTRIBUTING.md

··· 1 + # Contributing to atBB 2 + 3 + This document covers development workflow, testing standards, and coding patterns for contributors. For project-specific gotchas and non-obvious quirks, see [`CLAUDE.md`](CLAUDE.md). 4 + 5 + ## Testing Workflow 6 + 7 + ### When to Run Tests 8 + 9 + **Before every commit:** 10 + ```sh 11 + pnpm test 12 + git add <specific files> 13 + git commit -m "feat: your changes" 14 + ``` 15 + 16 + **Before requesting code review:** 17 + ```sh 18 + pnpm build # Ensure clean build 19 + pnpm test # Verify all tests pass 20 + # Only then push and request review 21 + ``` 22 + 23 + **After fixing review feedback:** 24 + ```sh 25 + # Make fixes 26 + pnpm test # Verify tests still pass 27 + # Push updates 28 + ``` 29 + 30 + ### Test Requirements 31 + 32 + All new features must include tests: 33 + - **API endpoints:** Success cases, error cases, edge cases 34 + - **Business logic:** All code paths and error conditions 35 + - **Error handling:** All catch blocks tested 36 + - **Security features:** Authentication, authorization, input validation 37 + 38 + ### Test Quality Standards 39 + 40 + - Tests must be independent (no shared state between tests) 41 + - Use descriptive test names that explain what is being tested 42 + - Mock external dependencies (databases, APIs, network calls) 43 + - Test error paths, not just happy paths 44 + - Verify logging and error messages are correct 45 + 46 + ### Test Coverage Expectations 47 + 48 + While we don't enforce strict coverage percentages, aim for: 49 + - **Critical paths:** 100% coverage (authentication, authorization, data integrity) 50 + - **Error handling:** All catch blocks should be tested 51 + - **API endpoints:** All routes should have tests 52 + - **Business logic:** All functions with branching logic should be tested 53 + 54 + Do not: 55 + - Skip writing tests to "move faster" — untested code breaks in production 56 + - Write tests after requesting review — tests inform implementation 57 + - Rely on manual testing alone — automated tests catch regressions 58 + 59 + ## Error Handling Patterns 60 + 61 + ### Defensive Programming 62 + 63 + All list queries must include defensive limits: 64 + ```typescript 65 + .from(categories) 66 + .orderBy(categories.sortOrder) 67 + .limit(1000); // Prevent memory exhaustion on unbounded queries 68 + ``` 69 + 70 + Always filter soft-deleted records in read queries: 71 + ```typescript 72 + .where(and( 73 + eq(posts.rootPostId, topicId), 74 + eq(posts.deleted, false), 75 + eq(posts.bannedByMod, false) 76 + )) 77 + ``` 78 + 79 + Use explicit ordering for consistent, reproducible results: 80 + ```typescript 81 + .orderBy(asc(posts.createdAt)) // Chronological order for replies 82 + ``` 83 + 84 + ### Global Error Handler 85 + 86 + Every Hono app must have a global error handler as a safety net. See `apps/appview/src/create-app.ts` for the production implementation: 87 + 88 + ```typescript 89 + app.onError((err, c) => { 90 + console.error("Unhandled error in route handler", { 91 + path: c.req.path, 92 + method: c.req.method, 93 + error: err.message, 94 + stack: err.stack, 95 + }); 96 + return c.json( 97 + { 98 + error: "An internal error occurred. Please try again later.", 99 + ...(process.env.NODE_ENV !== "production" && { 100 + details: err.message, 101 + }), 102 + }, 103 + 500 104 + ); 105 + }); 106 + ``` 107 + 108 + ### Testing Error Classification 109 + 110 + Test that errors return the right status code — users need actionable feedback: 111 + 112 + | Status | When to return | 113 + |--------|----------------| 114 + | 400 | Invalid input, missing required fields, malformed JSON | 115 + | 404 | Resource doesn't exist | 116 + | 503 | Network errors, PDS connection failures — user should retry | 117 + | 500 | Unexpected errors, database errors — needs investigation | 118 + 119 + ```typescript 120 + // ✅ Network errors should return 503 (user should retry) 121 + it("returns 503 when PDS connection fails", async () => { 122 + mockPutRecord.mockRejectedValueOnce(new Error("fetch failed")); 123 + const res = await app.request("/api/topics", { 124 + method: "POST", 125 + body: JSON.stringify({ text: "Test" }) 126 + }); 127 + expect(res.status).toBe(503); 128 + }); 129 + 130 + // ✅ Server errors should return 500 (needs investigation) 131 + it("returns 500 for unexpected database errors", async () => { 132 + mockPutRecord.mockRejectedValueOnce(new Error("Database connection lost")); 133 + const res = await app.request("/api/topics", { 134 + method: "POST", 135 + body: JSON.stringify({ text: "Test" }) 136 + }); 137 + expect(res.status).toBe(500); 138 + }); 139 + 140 + // ✅ Input validation should return 400 141 + it("returns 400 for malformed JSON", async () => { 142 + const res = await app.request("/api/topics", { 143 + method: "POST", 144 + headers: { "Content-Type": "application/json" }, 145 + body: "{ invalid json }" 146 + }); 147 + expect(res.status).toBe(400); 148 + }); 149 + ``` 150 + 151 + ## Security Code Review Checklist 152 + 153 + Before requesting review for authentication/authorization code: 154 + 155 + - [ ] All permission checks fail closed (deny access on error) 156 + - [ ] Database errors in security checks are caught and logged 157 + - [ ] Programming errors (TypeError) are re-thrown, not caught 158 + - [ ] Privilege escalation is prevented (equal/higher authority blocked) 159 + - [ ] Tests cover unauthorized (401), forbidden (403), and error cases 160 + - [ ] Error messages don't leak internal details (priority values, permission names) 161 + - [ ] Middleware composition is correct (auth before permission checks) 162 + - [ ] Startup fails fast if security infrastructure is unavailable 163 + 164 + **Example test suite structure for security-critical endpoints:** 165 + ```typescript 166 + describe("POST /api/admin/members/:did/role (security-critical)", () => { 167 + describe("Authorization", () => { 168 + it("returns 401 when not authenticated", async () => { /* ... */ }); 169 + it("returns 403 when user lacks manageRoles permission", async () => { /* ... */ }); 170 + }); 171 + 172 + describe("Privilege Escalation Prevention", () => { 173 + it("prevents admin from assigning owner role (higher authority)", async () => { 174 + // Admin (priority 10) tries to assign Owner (priority 0) → 403 175 + }); 176 + it("allows admin to assign moderator role (lower authority)", async () => { 177 + // Admin (priority 10) assigns Moderator (priority 20) → 200 178 + }); 179 + }); 180 + 181 + describe("Error Handling", () => { 182 + it("returns 503 when PDS connection fails (network error)", async () => { /* ... */ }); 183 + it("returns 500 when database query fails (server error)", async () => { /* ... */ }); 184 + it("returns 400 for malformed roleUri (input validation)", async () => { /* ... */ }); 185 + }); 186 + }); 187 + ``` 188 + 189 + ## Bruno API Collections 190 + 191 + The `bruno/` directory contains [Bruno](https://www.usebruno.com/) collections for API documentation and interactive testing. 192 + 193 + ### When to Update 194 + 195 + | Event | Action | 196 + |-------|--------| 197 + | New endpoint | Create a `.bru` file in `bruno/AppView API/<feature>/` | 198 + | Modified endpoint | Update the corresponding `.bru` file | 199 + | Removed endpoint | Delete the `.bru` file; update `bruno/README.md` if referenced | 200 + | New environment variable | Update `bruno/environments/local.bru` and `bruno/environments/dev.bru`; document in `bruno/README.md` | 201 + 202 + Always update Bruno files **in the same commit** as the route implementation. 203 + 204 + ### File Template 205 + 206 + ```bru 207 + meta { 208 + name: Endpoint Name 209 + type: http 210 + seq: 1 211 + } 212 + 213 + get { 214 + url: {{appview_url}}/api/path 215 + } 216 + 217 + params:query { 218 + param1: {{variable}} 219 + } 220 + 221 + headers { 222 + Content-Type: application/json 223 + } 224 + 225 + body:json { 226 + { 227 + "field": "value" 228 + } 229 + } 230 + 231 + assert { 232 + res.status: eq 200 233 + res.body.field: isDefined 234 + } 235 + 236 + docs { 237 + Brief description of what this endpoint does. 238 + 239 + Path/query/body params: 240 + - param1: Description (type, required/optional) 241 + 242 + Returns: 243 + { 244 + "field": "value" 245 + } 246 + 247 + Error codes: 248 + - 400: Bad request (invalid input) 249 + - 401: Unauthorized (requires auth) 250 + - 404: Not found 251 + - 500: Server error 252 + 253 + Notes: 254 + - Any special considerations or validation rules 255 + } 256 + ``` 257 + 258 + ### Before Committing 259 + 260 + 1. Open the collection in Bruno 261 + 2. Test each modified request against your local dev server (`pnpm dev`) 262 + 3. Verify assertions pass (green checkmarks) 263 + 4. Verify documentation is accurate and complete 264 + 5. Check that error scenarios are documented (not just happy path)

Configure Feed

Configure Feed