- Documents fire-and-forget architecture with graceful degradation
- Specifies helper function createMembershipForUser() implementation
- Details OAuth callback integration point after profile fetch
- Outlines comprehensive testing strategy (unit, integration, error scenarios)
- Covers edge cases: race conditions, firehose lag, PDS failures
- Includes implementation checklist and future considerations

* ci: add GitHub Actions workflow for PR validation

Adds CI workflow that mirrors local git hooks:
- Lint: oxlint checks for code quality issues
- Typecheck: TypeScript validation (continue-on-error due to 32 baseline errors)
- Test: Full test suite with PostgreSQL 17 service

Features:
- Parallel job execution for faster feedback
- pnpm store caching for speed
- PostgreSQL service container for integration tests
- Triggers on pull requests and pushes to main

* fix: resolve all 35 TypeScript build errors

Fixes all baseline TypeScript errors blocking CI/CD builds.

**Changes:**

1. **OAuth test fixes (11 errors) - apps/appview/src/lib/__tests__/oauth-stores.test.ts:**
- Fixed NodeSavedState: dpopKey → dpopJwk, added required iss property
- Fixed TokenSet: added required iss and aud properties
- Removed invalid serverMetadata property from NodeSavedSession

2. **Lexicon generator update (23 errors) - packages/lexicon/package.json:**
- Upgraded @atproto/lex-cli: 0.5.0 → 0.9.8
- Fixes 'v is unknown' errors (now uses proper generics)

3. **TypeScript config (16 errors) - tsconfig.base.json:**
- Changed module: "Node16" → "ESNext"
- Changed moduleResolution: "Node16" → "bundler"
- Fixes missing .js extension errors in generated lexicon code
- "bundler" mode appropriate for monorepo with build tools

4. **App context fix (1 error) - apps/appview/src/lib/app-context.ts:**
- Fixed requestLock signature: fn: () => Promise<T> → fn: () => T | PromiseLike<T>
- Wrapped fn() call in Promise.resolve() to normalize return type
- Matches NodeOAuthClient's Awaitable<T> requirement

**Result:** Clean build - all 4 packages compile successfully.

Root causes: Library type definition updates (OAuth), code generator
limitations (lexicon), and type signature mismatches (app-context).

* ci: run database migrations before tests

Add database migration step to test workflow to ensure
PostgreSQL schema is created before tests run.

Fixes password authentication error that was actually caused
by missing database schema.

* fix: merge process.env with .env in vitest config

Vitest's env config was replacing process.env with .env file contents.
In CI, there's no .env file, so DATABASE_URL from GitHub Actions
wasn't reaching the tests.

Now we merge both sources, with process.env taking precedence,
so CI environment variables work correctly.

* fix: only override vitest env when .env file exists

Previous fix attempted to merge but process.env spread might
not work as expected in vitest config context.

New approach: only set env config if we found a .env file.
In CI (no .env file), vitest will use process.env naturally,
which includes DATABASE_URL from GitHub Actions workflow.

* fix: load ALL env vars with empty prefix in loadEnv

loadEnv by default only loads VITE_* prefixed variables.
Pass empty string as prefix to load all variables including
DATABASE_URL from .env file.

* fix: use vitest setup file to load .env without replacing process.env

Instead of using vitest's 'env' config (which replaces process.env),
use a setup file that loads .env into process.env using dotenv.

This way:
- Local dev: .env file is loaded into process.env
- CI: GitHub Actions env vars pass through naturally
- dotenv.config() won't override existing env vars

Add dotenv and vite as devDependencies.
Keep debug logging to verify DATABASE_URL is set.

* fix: configure Turbo to pass DATABASE_URL to test tasks

Turbo blocks environment variables by default for cache safety.
Tests were failing because DATABASE_URL wasn't being passed through.

Add DATABASE_URL to test task env configuration so it's available
to vitest in both local dev and CI.

This was the root cause all along - vitest setup, GitHub Actions config,
and migrations were all correct. Turbo was blocking the env var!

* fix: make vitest.setup.ts work in both main repo and worktrees

The .env file path resolution needs to handle two cases:
- Main repo: apps/appview -> ../../.env
- Worktree: .worktrees/branch/apps/appview -> ../../../../.env

Added fallback logic to try both paths.

* docs: add Turbo environment variable passthrough guidance to Testing Standards

Documents critical non-obvious behavior where Turbo blocks env vars by default
for cache safety. Tests requiring env vars must declare them in turbo.json.

Includes symptoms, explanation, and when to update configuration.

* refactor: extract per-entity response serializers from route handlers

Route handlers in topics.ts, categories.ts, and forum.ts manually mapped
DB rows to JSON with repeated serializeBigInt/serializeDate/serializeAuthor
calls. Extract reusable serializer functions to reduce duplication:

- serializePost(post, author) for topic posts and replies
- serializeCategory(cat) for category listings
- serializeForum(forum) for forum metadata
- Add CategoryRow and ForumRow type aliases

Update all route handlers to use the new serializers and add comprehensive
unit tests covering happy paths, null handling, and BigInt serialization.

* fix: remove log spam from serializeBigInt for null values

Null values are expected for optional BigInt fields like parentPostId
(null for topic posts) and forumId (null for orphaned categories).

Logging these creates noise without adding debugging value since the
null return is the correct behavior.

* test commit

* fix: remove broken turbo filter from lefthook pre-commit

The --filter='...[HEAD]' syntax doesn't work during merges and returns
zero packages in scope, causing turbo commands to fail with non-zero
exit codes even when checks pass.

Removing the filter makes turbo run on all packages with staged changes,
which is more reliable for pre-commit hooks.

* test: add integration tests for serialized GET endpoint responses

Addresses PR #23 'Important' feedback - adds comprehensive integration
tests that verify GET /api/forum and GET /api/categories return properly
serialized responses.

Tests verify:
- BigInt id fields serialized to strings
- Date fields serialized to ISO 8601 strings
- Internal fields (rkey, cid) not leaked
- Null optional fields handled gracefully
- Response structure matches serializer output

Also fixes:
- createTestContext() return type (TestContext not AppContext)
- Cleanup order (delete categories before forums for FK constraints)

All 249 tests pass.

* docs: add API response shape documentation to serializers

Addresses PR #23 'Suggestion' feedback - adds comprehensive JSDoc
comments documenting the JSON response shape for each serializer.

Documents:
- Field types and serialization (BigInt → string, Date → ISO 8601)
- Null handling for optional fields
- Response structure for GET /api/forum, /api/categories, /api/topics/:id

---------

Co-authored-by: Claude <noreply@anthropic.com>

* refactor: extract generic TTLStore to replace duplicate in-memory store logic

OAuthStateStore, OAuthSessionStore, and CookieSessionStore all implemented
the same pattern: Map + set/get/del + periodic cleanup interval + destroy.
Extract that shared logic into a generic TTLStore<V> class with a configurable
isExpired predicate, and refactor all three stores to delegate to it.

- TTLStore provides: set, get (lazy eviction), getRaw (no eviction), delete,
destroy, and background cleanup with structured logging
- OAuthStateStore/OAuthSessionStore wrap TTLStore with async methods for
@atproto/oauth-client-node SimpleStore compatibility
- CookieSessionStore wraps TTLStore with null-returning get for its API
- app-context.ts unchanged (same public interface for all three stores)
- 18 new tests for TTLStore covering expiration, cleanup, logging, destroy

* fix: address critical adapter testing and lifecycle issues in TTLStore refactoring

**Issue #1: Adapter layer completely untested (Critical)** ✅
- Added 19 comprehensive adapter tests (11 OAuth + 8 cookie session)
- OAuthStateStore: async interface, StateEntry wrapping, 10-min TTL verification
- OAuthSessionStore: getUnchecked() bypass, complex refresh token expiration logic
- CookieSessionStore: Date comparison, null mapping, expiration boundary testing
- Tests verify adapters correctly wrap TTLStore with collection-specific behavior

**Issue #2: Complex expiration logic untested (Critical)** ✅
- Added 3 critical tests for OAuthSessionStore refresh token handling:
- Sessions with refresh tokens never expire (even if access token expired)
- Sessions without refresh token expire when access token expires
- Sessions missing expires_at never expire (defensive)
- Verifies the conditional expiration predicate works correctly

**Issue #3: Post-destruction usage creates zombie stores (Critical)** ✅
- Added destroyed state tracking to TTLStore
- CRUD operations now throw after destroy() is called
- destroy() is idempotent (safe to call multiple times)
- Prevents memory leaks from zombie stores with no cleanup

**Issue #4: getRaw() violates TTL contract (Important)** ✅
- Renamed getRaw() to getUnchecked() to make danger explicit
- Added UNSAFE JSDoc warning about bypassing expiration
- Updated all callers (OAuthSessionStore, ttl-store.test.ts)

Test count: 171 passed (was 152)

Addresses PR #24 review feedback from type-design-analyzer, code-reviewer, and pr-test-analyzer agents.

---------

Co-authored-by: Claude <noreply@anthropic.com>

* refactor: replace 18 indexer handler methods with data-driven collection configs

Extract duplicated try/catch/log/throw scaffolding (~108 lines per handler)
into three generic methods: genericCreate, genericUpdate, genericDelete.
Each of the 5 collection types (post, forum, category, membership, modAction)
is now defined as a CollectionConfig object that supplies collection-specific
logic via toInsertValues/toUpdateValues callbacks. The 15 handler methods
become thin one-line delegations to the generic methods. Reaction stubs
remain as-is (no table yet).

All existing behavior is preserved: same SQL queries, same log messages,
same error handling, same transaction boundaries. Updates are now uniformly
wrapped in transactions for consistency.

* fix: address critical error handling issues in indexer refactoring

**Issue #1: Silent failure logging (Critical)**
- Added skip tracking in genericCreate/genericUpdate
- Success logs now only fire when operations actually happen
- Before: Transaction succeeds with no insert, logs "[CREATE] Success"
- After: Skipped operations don't log success (console.warn still fires in configs)

**Issue #2: Database error swallowing (Critical)**
- Removed catch block from getForumIdByDid that returned null for ALL errors
- Database connection failures now propagate to generic handler's catch block
- Before: DB errors became indistinguishable from "forum not found"
- After: Infrastructure failures bubble up, logged and re-thrown

**Issue #3: Test coverage (Critical)**
- Added 18 critical test cases for refactored generic methods
- Tests cover: transaction rollback (3), null return paths (6), error re-throwing (4), delete strategies (5)
- Verifies behavioral equivalence after consolidating 15 handlers into 3 generic methods
- All 152 tests pass (was 141)

Addresses PR #25 review feedback from code-reviewer, silent-failure-hunter, and pr-test-analyzer agents.

---------

Co-authored-by: Claude <noreply@anthropic.com>

* refactor: unify duplicate session restoration logic

Extract shared restoreOAuthSession() into lib/session.ts to eliminate
duplicate cookie-lookup + OAuth-restore logic from middleware/auth.ts
and routes/auth.ts. The auth middleware now wraps the shared function
to produce AuthenticatedUser with Agent/handle/pdsUrl enrichment.

* fix: eliminate redundant cookie store query in session restoration

Changes:
- `restoreOAuthSession()` now returns both oauth + cookie sessions
- Removes duplicate `cookieSessionStore.get()` call in auth middleware
- Adds `handle` field to `/api/auth/session` response (bonus improvement)
- Updates tests to match new return structure

Before: Cookie store queried twice per authenticated request
After: Single query, both sessions returned together

Addresses PR #21 review feedback (Option A - recommended approach)

---------

Co-authored-by: Claude <noreply@anthropic.com>

* refactor: consolidate AT-URI parsing into shared utility

Extract duplicate AT-URI parsing logic into a single shared
parseAtUri() function in lib/at-uri.ts. Replace the Indexer's private
method and helpers' inline regex with imports of the shared utility.
Add comprehensive unit tests covering valid URIs, invalid inputs,
and edge cases.

* fix: restore observability logging in parseAtUri

- Add console.warn() for invalid AT URI format (aids firehose debugging)
- Add try-catch wrapper with structured error logging for unexpected failures
- Addresses PR #19 review feedback on observability regression

---------

Co-authored-by: Claude <noreply@anthropic.com>

* tooling: add Bruno API collections for testing and documentation

Adds Bruno (git-friendly API client) collections for all AppView endpoints:
- Health check, auth (OAuth flow), forum, categories, topics, posts
- Pre-configured environments for local and dev
- Inline documentation and response assertions
- README with setup instructions and usage guide

Bruno's plain-text .bru format provides version-controlled API documentation
that stays in sync with code changes.

* docs: add Bruno collection maintenance guidelines to CLAUDE.md

Ensures Bruno collections stay synchronized with API changes by:
- Requiring Bruno updates in the same commit as route changes
- Providing template and best practices for .bru files
- Documenting when/how to update collections
- Emphasizing Bruno files as living API documentation

Added isProgrammingError() and isNetworkError() helpers to routes/helpers.ts
to replace ~35 lines of duplicated error classification logic in the POST
catch blocks of topics.ts and posts.ts.

Co-authored-by: Claude <noreply@anthropic.com>

Replace 18 one-liner handler property declarations and the wrapHandler
method with a single createWrappedHandler factory that generates
circuit-breaker-wrapped handlers from Indexer method names.

https://claude.ai/code/session_01YL7ZhPgh8CZ9QzKH5A2exT

Co-authored-by: Claude <noreply@anthropic.com>