* docs: add ATB-18 ForumAgent implementation plan

Detailed TDD-based plan with 10 bite-sized tasks:
1. Add forum credentials to config
2. Create ForumAgent class with status types
3. Implement error classification and retry logic
4. Implement proactive session refresh
5. Integrate into AppContext
6. Create health endpoint
7. Update test context
8. Manual integration testing
9. Update documentation
10. Update Linear issue and project plan

Each task follows TDD: write test → verify fail → implement → verify pass → commit

* feat(appview): add forum credentials to config

- Add forumHandle and forumPassword to AppConfig
- Load from FORUM_HANDLE and FORUM_PASSWORD env vars
- Make credentials optional (undefined if not set)
- Add tests for loading forum credentials

* feat(appview): create ForumAgent class with basic structure

- Define ForumAgentStatus and ForumAgentState types
- Implement initialization with status tracking
- Add getStatus(), isAuthenticated(), getAgent() methods
- Add shutdown() for resource cleanup
- Add tests for initialization and successful auth

* fix(appview): address ForumAgent code quality issues

Critical fixes:

- Logging: Wrap all console logs in JSON.stringify() per project standards

- Type safety: Remove non-null assertions by making agent non-nullable

- Test lifecycle: Add shutdown() calls in afterEach for proper cleanup

- Test coverage: Add test verifying shutdown() cleans up resources

All ForumAgent tests pass.

* feat(appview): implement error classification and retry logic in ForumAgent

- Add isAuthError() and isNetworkError() helpers

- Auth errors fail permanently (no retry, prevent lockouts)

- Network errors retry with exponential backoff (10s, 20s, 40s, 80s, 160s)

- Stop retrying after 5 failed attempts

- Update status to 'retrying' during retry attempts

- Add comprehensive tests for error classification and retry behavior

* fix(appview): correct retry backoff intervals to match spec (10s, 30s, 1m, 5m, 10m)

* feat(appview): implement proactive session refresh in ForumAgent

- Add scheduleRefresh() to run every 30 minutes
- Add refreshSession() using agent.resumeSession()
- Fall back to full re-auth if refresh fails
- Add tests for session refresh and refresh failure handling

* fix(appview): address ForumAgent session refresh critical issues

- Add isRefreshing flag to prevent concurrent refresh execution
- Add session existence check to guard clause in refreshSession()
- Set status='retrying' immediately on refresh failure (before attemptAuth)
- Remove non-null assertion by checking session in guard clause

Fixes race conditions and status consistency issues identified in code review.

* feat(appview): integrate ForumAgent into AppContext

- Add forumAgent to AppContext interface (nullable)
- Initialize ForumAgent in createAppContext if credentials provided
- Clean up ForumAgent in destroyAppContext
- Add tests for ForumAgent integration with AppContext
- Use structured logging with JSON.stringify for missing credentials warning

* fix(appview): add missing forumDid field to AppContext test config

- Add required forumDid field to test configuration
- Extend sessionSecret to meet 32-character minimum

* fix(appview): improve AppContext ForumAgent integration logging and tests

- Use JSON.stringify for structured logging (follows project convention)
- Add assertion that initialize() is called when ForumAgent created
- Add console.warn spy assertion for missing credentials path
- Improves test coverage of critical initialization path

* feat(appview): add comprehensive health endpoint with service status reporting

- Create GET /api/health endpoint (public, no auth required)

- Report status: healthy, degraded, unhealthy

- Include database status with latency measurement

- Include firehose connection status

- Include ForumAgent status (authenticated, retrying, failed, etc)

- Expose granular ForumAgent states with retry countdown

- Security: no sensitive data exposed (no DIDs, handles, credentials)

- Add comprehensive tests for all health states

- Maintain backward compatibility with /api/healthz legacy endpoints

* fix(appview): make health endpoint spec-compliant with FirehoseService API

- Add isRunning() and getLastEventTime() methods to FirehoseService
- Track last event timestamp in firehose
- Update health endpoint to use spec-compliant methods
- Add last_event_at field to firehose health response
- Update tests to use new API methods

Fixes spec deviation where health endpoint was using getHealthStatus()
instead of the specified isRunning() and getLastEventTime() methods.

* refactor(appview): improve health endpoint code quality

- Replace 'any' type with proper HealthResponse interface
- Remove dead code (isHealthy, getHealthStatus methods)
- Eliminate redundant isRunning() call (use cached value)
- Add test coverage for last_event_at field
- Improve type safety and reduce maintenance burden

* test(appview): add ForumAgent to test context

- Add forumAgent: null to test context return value
- Ensures route tests have proper AppContext shape
- Mock ForumAgent is null by default (can be overridden in tests)

* docs: mark ATB-18 implementation complete and add usage guide

- Update acceptance criteria to show all items complete
- Add usage examples for checking ForumAgent availability in routes
- Add monitoring examples for health endpoint
- Document required environment variables

* docs: mark ATB-18 complete in project plan

ForumAgent service implemented with:
- Graceful degradation and smart retry logic
- Proactive session refresh
- Health endpoint integration
- Comprehensive test coverage

* docs: update Bruno collection for /api/health endpoint

Update existing Check Health.bru to document the new comprehensive
health endpoint at /api/health instead of the legacy /api/healthz.

Changes:
- Updated URL from /api/healthz to /api/health
- Added comprehensive documentation of response structure
- Documented all three overall status types (healthy/degraded/unhealthy)
- Documented all five ForumAgent status values
- Added assertions for response fields
- Included example responses for each health state
- Added usage examples for monitoring and alerting
- Noted security guarantee (no sensitive data exposure)

Addresses code review feedback on PR #31.

* chore: remove spike package and references

Remove the spike package which was used for early PDS testing but is no longer needed. Updates all documentation references in CLAUDE.md, README.md, environment files, and planning docs.

Changes:
- Delete packages/spike directory
- Update CLAUDE.md: remove spike from packages table and commands
- Update README.md: remove spike from packages table
- Update .env.example and .env.production.example
- Update docs: atproto-forum-plan.md, oauth-implementation-summary.md, write-endpoints-design.md
- Update pnpm-lock.yaml via pnpm install

* fix: resolve TypeScript errors in generated lexicon code

Fixes the 29 TypeScript compilation errors in packages/lexicon by:

1. Adding missing @atproto dependencies:
- @atproto/xrpc@^0.7.7 for XrpcClient imports
- @atproto/api@^0.15.0 for ComAtprotoRepo* namespace types

2. Automating the fix with build:fix-generated-types script:
- Runs after lex gen-api generates TypeScript
- Injects missing import statements for ComAtprotoRepo* types
- Idempotent (safe to run multiple times)

3. Removing error suppression from build:compile script:
- Compilation now succeeds without fallback echo

The @atproto/lex-cli code generator references standard AT Protocol
namespaces (ComAtprotoRepoListRecords, ComAtprotoRepoGetRecord, etc.)
but doesn't import them. This is expected behavior - generated clients
are meant to consume @atproto/api which provides these types.

Before: 29 TypeScript errors, CI allowed to fail
After: Clean compilation, all tests pass

* docs: remove TypeScript error warnings after fix

Updates documentation to reflect that the 29 TypeScript errors in
generated lexicon code have been resolved:

- Remove 'Known Issues' section from CLAUDE.md
- Update CI workflow description to remove error allowance note
- Remove continue-on-error from typecheck job in ci.yml

The typecheck hook and CI job now enforce zero TypeScript errors.

* refactor: address PR review feedback on fix-generated-types script

Addresses all critical issues from PR #30 review:

## Test Coverage (Issue #1 - Severity 9/10)
- Added comprehensive test suite with 10 test cases
- Covers success paths, error cases, idempotency, and edge cases
- Tests validate: clean generation, duplicate prevention, whitespace
tolerance, missing file errors, pattern mismatches, and more
- All tests passing (10/10)

## Robust Pattern Matching (Issue #2 - Severity 9/10)
- Replaced brittle string matching with regex: ANCHOR_IMPORT_REGEX
- Handles whitespace variations and optional .js extensions
- Clear error message when pattern doesn't match
- Resilient to @atproto/lex-cli format changes

## Accurate Idempotency Check (Issue #3 - Severity 8/10)
- Fixed overly broad check that looked for ANY @atproto/api import
- Now checks for ALL 5 specific required types
- Prevents false positives if lex-cli adds other imports
- Uses regex to verify exact type imports

## Replacement Validation (Issue #4 - Severity 8/10)
- Validates that string replace() actually modified content
- Confirms all required imports are present after injection
- Throws clear errors if validation fails
- Prevents silent failures

## Specific Error Messages (Issue #5 - Severity 8/10)
- Distinguishes ENOENT (file missing) from EACCES (permission denied)
- Provides actionable recovery instructions for each error
- Clear messages when generator format changes
- Includes context in all error paths

## Correct Dependency Placement (Issue #6)
- Moved @atproto/api and @atproto/xrpc to devDependencies
- Only needed at build time, not runtime
- Reduces published package size

## Enhanced Documentation (Issue #7)
- Expanded JSDoc comment explaining WHY workaround exists
- Documents WHEN it might break (format changes)
- Provides HOW to fix when it breaks
- Added maintenance guidance for future updates

All improvements verified with comprehensive test suite.

* fix: move @atproto/api and @atproto/xrpc to dependencies

These packages are imported in the generated dist/types/index.js
at runtime, so they must be runtime dependencies, not devDependencies.

The lockfile already had them as dependencies, but package.json had
them in devDependencies, causing CI frozen-lockfile check to fail.

* debug: add verification step to check lexicon build outputs

Add diagnostic step to verify that lexicon dist files are created
before tests run. This will help debug the CI module resolution error.

* fix: refresh workspace links after build

Add pnpm install step after build to ensure workspace package links
are correctly updated when Vitest runs. This should resolve the
module resolution error in CI while tests pass locally.

* fix: add Vite resolve alias for workspace packages

Configure Vite to explicitly resolve @atbb/lexicon workspace package
imports. This works around a CI-specific module resolution issue where
Vite cannot find workspace package files even though they exist.

The alias ensures Vite resolves workspace imports directly to the
package dist directory, bypassing the workspace symlink resolution
that fails in CI but works locally.

* refactor: use main package exports instead of deep imports

Replace deep import paths (@atbb/lexicon/dist/types/...) with imports
from the main package export (@atbb/lexicon). The generated index.ts
already re-exports all types as named exports.

This avoids the CI module resolution issue where Vite couldn't find
deep import paths in the workspace package structure. Using the main
package export is cleaner and more maintainable.

* fix: revert to deep imports with proper namespace types

Revert to the original deep import style which provides proper
TypeScript namespace support for helper functions like isReplyRef.

Testing if the earlier CI fixes (pnpm install refresh, Vite alias)
combined with the dependency placement fix resolves the module
resolution issue.

* feat: add clean export paths for lexicon types

Add explicit package.json exports for common types:
- @atbb/lexicon/post
- @atbb/lexicon/forum
- @atbb/lexicon/category
- @atbb/lexicon/membership
- @atbb/lexicon/mod-action

This provides clean, readable import paths that work correctly in
both local development and CI, avoiding the workspace module resolution
issues with deep import paths while maintaining proper TypeScript
namespace support.

* fix: use conditional exports for proper Vite module resolution

- Add 'types' condition to package exports to help Vite resolve TypeScript definitions
- Specify 'import' and 'default' conditions for ESM module resolution
- Modern package.json pattern required for proper TypeScript + Vite support
- Fixes 'Cannot find module' error in CI test runs

* debug: add more diagnostics to investigate CI module resolution failure

- Show package.json exports in CI logs
- Test if Node can import the module successfully
- This will help identify the difference between local (works) and CI (fails)

* fix: resolve TypeScript errors in generated lexicon code

- Add build step to inject @atproto/api imports into generated types
- Use deep import paths for lexicon types (simpler and more reliable)
- Move @atproto/api and @atproto/xrpc to dependencies (runtime imports)

This fixes the 23 TypeScript errors in generated lexicon code that
occurred because @atproto/lex-cli generates files without importing
the types they reference from @atproto/api.

* fix: add Vite resolve.alias to fix module resolution in CI

- Use regex-based alias to map @atbb/lexicon imports to physical paths
- This resolves Vite module resolution issues in CI environments
- Deep import paths work locally and in CI with explicit path mapping

* chore: install vite-tsconfig-paths so that vite can resolve lexicon files

* chore: wild attempt to get ci to work

* fix: resolve TypeScript errors in generated lexicon code

Copy generated lexicon files to appview package and use local Vite aliases instead of workspace imports. Fixes all 32 TypeScript errors.

Changes: Updated copy script to exclude .ts files, added @atproto/lexicon and @atproto/xrpc deps, added __generated__/ to .gitignore

All 371 tests passing (db: 40, lexicon: 53, web: 20, appview: 258)

* fix: use package entry point for lexicon type imports

Replace @lexicons/* path aliases (only resolved by Vitest, invisible to
tsc) with named re-exports from the @atbb/lexicon package entry point.
The generated index.ts already re-exports all type namespaces — this is
the intended consumption pattern for @atproto/lex-cli output.

Removes the copy-to-appview build step, fix-copied-imports script,
@lexicons vitest alias, and unused appview dependencies that only
existed to support the file-copying approach.

Remove the spike package which was used for early PDS testing but is no longer needed. Updates all documentation references in CLAUDE.md, README.md, environment files, and planning docs.

Changes:
- Delete packages/spike directory
- Update CLAUDE.md: remove spike from packages table and commands
- Update README.md: remove spike from packages table
- Update .env.example and .env.production.example
- Update docs: atproto-forum-plan.md, oauth-implementation-summary.md, write-endpoints-design.md
- Update pnpm-lock.yaml via pnpm install

Design document for ForumAgent service with:
- Graceful degradation (soft failure with fallback)
- Smart retry logic (network errors retry, auth errors fail permanently)
- Proactive session refresh
- Health endpoint with granular status states
- AppContext integration pattern
- Comprehensive testing strategy

* docs: add design document for ATB-15 membership auto-creation

- 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

* test: add failing test for membership duplicate check

* feat: add database duplicate check for memberships

* feat: add forum metadata lookup with error handling

- Query forums table for forum.did, forum.rkey, forum.cid
- Build forumUri from database instead of hardcoded config value
- Throw error if forum not found (defensive check)
- Add test for missing forum error case
- Add emptyDb option to createTestContext for testing error paths

* feat: implement PDS write logic for membership records

* test: add error handling and duplicate check tests

* feat: integrate membership creation into OAuth callback

* docs: mark ATB-15 complete in project plan

* test: add manual testing helper script for ATB-15

* fix: address critical code review feedback - logging format and test cleanup (ATB-15)

Critical fixes:
- Fix logging format to use JSON.stringify() pattern (matches auth.ts:156)
Ensures logs are parseable by aggregation tools (Datadog, CloudWatch)
- Fix test cleanup to handle all test DIDs with pattern matching
Prevents test data pollution from dynamic DIDs (duptest-*, create-*)

Addresses 2 of 3 critical blocking issues from PR #27 review.

Note on integration tests:
The review requested OAuth callback integration tests. This codebase has no
existing route test patterns, and OAuth testing requires complex mocking.
The 5 unit tests provide 100% coverage of helper logic. Establishing OAuth
integration test patterns is valuable but deferred to a separate effort.

* test: add OAuth callback integration tests for fire-and-forget pattern (ATB-15)

Adds 4 integration tests verifying the architectural contract:
'Login succeeds even when membership creation fails'

Tests verify:
- Login succeeds when PDS unreachable (membership creation throws)
- Login succeeds when database connection fails
- Login succeeds when membership already exists (no duplicate)
- Login succeeds when membership creation succeeds

Follows established pattern from topics.test.ts:
- Mock dependencies at module level before importing routes
- Use createTestContext() for test database
- Test through HTTP requests with Hono app

Addresses critical blocking issue #1 from PR #27 code review.
Total test coverage: 5 unit tests + 4 integration tests = 9 tests

* fix: mock cookieSessionStore.set in auth integration tests

CI was failing with 'ctx.cookieSessionStore.set is not a function'.
The OAuth callback creates a session cookie after successful login,
so the test context needs this method mocked.

Fixes CI test failures. All 258 tests now passing.

ATB-15 implemented fire-and-forget membership record creation on first OAuth login.
9 tests verify graceful degradation. PR #27 approved and merged.

- 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>

Add comprehensive skill for working with Nix and devenv to prevent
common anti-patterns and teach proper development workflows.

**Skill Features:**
- Quick reference table for common operations
- Patterns for interactive dev, scripts, and automation
- direnv setup for automatic environment activation
- Anti-patterns prevented: manual PATH modification, global installs,
nested shells, assuming commands available
- Troubleshooting guide

**Development Process:**
- Created using TDD for documentation (RED-GREEN-REFACTOR)
- Tested with multiple pressure scenarios
- Verified agents follow proper patterns after skill deployment
- Condensed from 928 to 597 words for token efficiency

The skill is installable via: cp -r skills/working-with-devenv ~/.claude/skills/

* fix: prevent unhandled rejection in reconnection-manager test

Attach the rejection handler before advancing fake timers to avoid
a timing window where the promise rejects without a handler attached.
This eliminates the 'Unhandled Rejection' warning from Vitest.

* build: add oxlint and lefthook dependencies

* build: add oxlint configuration with recommended rules

* build: add lefthook pre-commit hook configuration

* test: verify pre-commit hooks execute

* docs: add pre-commit checks section to CLAUDE.md

* fix: add missing lint:fix scripts to 3 packages and register task in turbo

- Add lint:fix script to @atbb/appview, @atbb/web, and @atbb/db
- Register lint:fix task in turbo.json with cache disabled
- Enables documented 'pnpm turbo lint:fix' command
- Fixes critical blocker from code review

* docs: add oxlint/lefthook implementation plan

- Detailed 8-task breakdown for oxlint and lefthook setup
- Step-by-step instructions with expected outputs
- Documents PATH requirement for pnpm in Nix environment
- Records baseline TypeScript errors (32 total)

* fix: resolve oxlint unused variable errors and duplicate script

- Prefix unused parameters with underscore (appview)
- Remove unused imports from topics.test.ts
- Fix duplicate lint:fix script in lexicon package.json

All packages now pass oxlint with 0 warnings and 0 errors.

Elevates lessons from ATB-12 (two review cycles) to shared team knowledge.

Added to "TypeScript / Hono Gotchas":
- Type guards for API endpoint parameters (prevent runtime crashes)
- JSON parsing safety pattern (malformed JSON → 400, not 500)

Added to "Testing Standards":
- Pre-review checklist (run before requesting review)
- Dependencies verification (runtime imports must be in dependencies)
- Error test coverage requirements (write during implementation, not after review)

Added to "Error Handling Standards":
- Error classification testing patterns with examples
- Test cases for 400/404/503/500 status codes
- Emphasis on testing user-facing error messages, not just catching

Why these matter:
- Type guards prevent TypeError crashes from missing/wrong-type fields
- Pre-review checklist prevents two-cycle review pattern (implement → review → fix → review)
- Error classification tests verify user experience (actionable feedback), not just error handling

These patterns caught 5 critical issues in ATB-12 review that would have caused:
- Production crashes (TypeError from missing type guards)
- Deployment failures (drizzle-orm in devDependencies)
- Poor UX (network errors returning 500 instead of 503)

Implements POST /api/topics and POST /api/posts for creating forum posts via OAuth-authenticated PDS writes. Includes comprehensive error handling, Unicode validation, and fire-and-forget design with firehose indexing.

- 29 new tests, 134 total tests passing
- All critical review issues resolved across 3 review rounds
- Phase 1 (AppView Core) now 100% complete

Closes ATB-12

* docs: add OAuth implementation design for ATB-14

Complete design for AT Protocol OAuth authentication covering:
- Decentralized PDS authority model
- @atproto/oauth-client-node integration
- Pluggable session storage (in-memory → Redis migration path)
- Authentication middleware and route protection
- Client metadata configuration
- Error handling and security considerations

Includes implementation roadmap with 5 phases and testing strategy.

* docs: add OAuth implementation plan

Comprehensive step-by-step plan for ATB-14:
- 16 tasks covering dependencies, config, session storage, OAuth flow
- Routes: login, callback, session check, logout
- Authentication middleware (requireAuth, optionalAuth)
- Manual testing checklist and post-implementation tasks

Ready for execution via superpowers:executing-plans

* feat(appview): add OAuth client dependencies

- Add @atproto/oauth-client-node v0.3.16
- Add @atproto/identity v0.4.11 for handle resolution

* feat(appview): add OAuth environment variables

- Add OAUTH_PUBLIC_URL, SESSION_SECRET, SESSION_TTL_DAYS, REDIS_URL to .env.example with documentation
- Extend AppConfig interface with OAuth configuration fields
- Add validateOAuthConfig() with startup validation:
- Requires SESSION_SECRET (min 32 chars) in all environments
- Requires OAUTH_PUBLIC_URL in production
- Warns about in-memory sessions in production without Redis
- Update test-context with OAuth config defaults
- Add comprehensive OAuth config tests (10 new tests covering validation, defaults, and edge cases)

Note: Pre-existing config tests fail due to test infrastructure issue with
process.env restoration and vi.resetModules(). OAuth-specific tests pass.

* fix(appview): improve OAuth config validation

- Change SESSION_SECRET default to fail validation, forcing developers to generate real secret
- Reorder validation checks to show environment-specific errors (OAUTH_PUBLIC_URL) before global errors (SESSION_SECRET)
- Improves production safety and error message clarity

* feat(appview): create session store interface

- Add SessionData type for OAuth session metadata
- Add SessionStore interface for pluggable storage
- Implement MemorySessionStore with TTL auto-cleanup
- Document limitations: single-instance only, lost on restart

* feat(appview): create state store for OAuth flow

- Store PKCE verifier during authorization redirect
- Auto-cleanup after 10 minutes (prevent timing attacks)
- Ephemeral storage for OAuth flow only

* feat(appview): add session and state stores to AppContext

* feat(appview): add Hono context types for authentication

* feat(appview): add OAuth client metadata endpoint

* feat(appview): add auth route scaffolding

- Create /api/auth/login, /callback, /session, /logout endpoints
- Stub implementations return 501 (to be implemented next)
- Register auth routes in API router

* feat(appview): implement OAuth login flow

- Resolve handle to DID and PDS endpoint
- Generate PKCE code verifier and challenge (S256 method)
- Generate random OAuth state for CSRF protection
- Store state + verifier in StateStore
- Redirect user to PDS authorization endpoint
- Add structured logging for OAuth events

* fix(appview): correct OAuth redirect URI in client metadata

OAuth callback route is at /api/auth/callback, not /auth/callback.
This mismatch would cause PDS to reject authorization redirects.

* feat(appview): implement OAuth callback and token exchange

- Validate OAuth state parameter (CSRF protection)
- Exchange authorization code for access/refresh tokens
- Create session with token metadata
- Set HTTP-only session cookie (secure, SameSite=Lax)
- Handle user denial gracefully (redirect with message)
- Clean up state after use

* feat(appview): implement session check and logout

- GET /api/auth/session returns current user or 401
- Check session expiration, clean up expired sessions
- GET /api/auth/logout deletes session and clears cookie
- Support optional redirect parameter on logout

* feat(appview): create authentication middleware

- requireAuth: validates session, returns 401 if missing/invalid
- optionalAuth: attaches user if session exists, allows unauthenticated
- Create Agent pre-configured with user's access token
- Attach AuthenticatedUser to Hono context via c.set('user')

* docs: mark ATB-14 (OAuth implementation) as complete

- Implemented full AT Protocol OAuth flow
- Session management with pluggable storage
- Authentication middleware for route protection
- All endpoints tested and validated

* docs: add OAuth implementation summary

Comprehensive documentation of ATB-14 OAuth implementation including
architecture, security considerations, testing results, and roadmap.

- Complete OAuth flow with PKCE and DPoP
- Session management with pluggable storage
- Authentication middleware for route protection
- Known MVP limitations documented
- Post-MVP improvement priorities
- Migration guide from password auth

* fix(appview): address security vulnerabilities in OAuth flow

Fix critical security issues identified in PR #14 code review:

1. Open Redirect Vulnerability (logout endpoint)
- Validate redirect parameter to only allow relative paths
- Reject protocol-relative URLs (//example.com)
- Prevent phishing attacks via unvalidated redirects

2. State Token Logging
- Hash state tokens before logging (SHA256, first 8 chars)
- Prevent token leakage in logs for invalid state warnings
- Maintain auditability without exposing sensitive tokens

Related: ATB-14

* fix(appview): fix resource leaks in shutdown

Call destroy() on session and state stores during app context cleanup:

- MemorySessionStore.destroy() clears 5-minute cleanup interval
- StateStore.destroy() clears 5-minute cleanup interval
- Prevents dangling timers after graceful shutdown
- Uses type guard to check for destroy method on SessionStore interface

Without this fix, setInterval timers continue running after server
shutdown, preventing clean process exit and leaking resources.

Related: ATB-14

* docs: document MVP limitations and fix file references

Address documentation accuracy issues from PR #14 code review:

1. PDS Hardcoding Documentation
- Add comprehensive JSDoc to resolveHandleToPds() explaining MVP limitation
- Document that only bsky.social users can authenticate
- List required post-MVP work (DNS TXT, .well-known, DID document parsing)
- Include links to AT Protocol specs for handle and DID resolution

2. Fix File Path References
- oauth-implementation-summary.md: Update all file paths to match actual structure
- Remove references to @atproto/oauth-client-node (not used)
- Clarify "Manual OAuth 2.1 implementation using fetch API"
- Fix session store paths: lib/session/types.ts → lib/session-store.ts
- Document auth middleware as "planned, not yet implemented"

3. Update atproto-forum-plan.md
- Correct Phase 2 OAuth description (manual fetch, not oauth-client-node)
- Document bsky.social hardcoding limitation
- Fix session store file references
- Note that auth middleware is not yet implemented

Related: ATB-14

* fix(appview): use forEach instead of for-of in cleanup methods

Replace for-of iteration over Map.entries() with forEach pattern:
- Avoids TypeScript TS2802 error (MapIterator requires --downlevelIteration)
- Compatible with current tsconfig target (ES2020 without downlevel flag)
- Maintains same error handling and logging from previous commit

This fixes a TypeScript compilation error introduced in the cleanup
error handling commit while preserving the improved error handling.

Related: ATB-14

* refactor(appview): integrate @atproto/oauth-client-node library

Replace manual OAuth implementation with official AT Protocol library.

Benefits:
- Proper multi-PDS handle resolution (fixes hardcoded bsky.social)
- DPoP-bound access tokens for enhanced security
- Automatic PKCE generation and validation
- Built-in state management and CSRF protection
- Token refresh support with automatic expiration handling
- Standards-compliant OAuth 2.0 implementation

Breaking changes:
- OAuth now requires HTTPS URL for client_id (AT Protocol spec)
- Local development requires ngrok/tunneling or proper domain with HTTPS
- Session structure changed (incompatible with previous implementation)

Implementation details:
- Created OAuthStateStore and OAuthSessionStore adapters for library
- Added CookieSessionStore to map HTTP cookies to OAuth sessions (DID-indexed)
- Integrated NodeOAuthClient with proper requestLock for token refresh
- Updated middleware to use OAuth sessions and create Agent with DPoP
- Fetch user handle during callback for display purposes
- Added config validation to warn about localhost limitations

Technical notes:
- Library enforces strict OAuth 2.0 security requirements
- Client ID must be publicly accessible HTTPS URL with domain name
- For multi-instance deployments, replace in-memory lock with Redis-based lock
- Session store is indexed by DID (sub), not random session tokens
- Access tokens are automatically refreshed when expired

Known limitations:
- Localhost URLs (http://localhost:3000) are rejected by OAuth client
- Development requires ngrok, staging environment, or mkcert + local domain
- TypeScript compilation fails on unrelated lexicon generated code issues
(pre-existing, not introduced by this change)

ATB-14

* chore(appview): remove unused session-store and state-store files

These files were replaced by oauth-stores.ts and cookie-session-store.ts
in the OAuth client integration.

* fix(appview): improve OAuth error handling and cleanup

Addresses code review feedback from PR #14:

**Error Handling Improvements:**
- Distinguish client errors (400) from server errors (500) in OAuth flows
- Log security validation failures (CSRF, PKCE) with appropriate severity
- Fail login if handle fetch fails instead of silent fallback
- Make session restoration throw on unexpected errors, return null only for expected cases

**Session Management:**
- Clean up invalid cookies in optionalAuth middleware to prevent repeated validation
- Add error handling to CookieSessionStore cleanup to prevent server crashes
- Fix session check endpoint to handle transient errors without deleting valid cookies

**Dependencies:**
- Remove unused @atproto/identity package (OAuth library handles resolution)

**Tests:**
- Fix Vitest async assertions to use correct syntax (remove await from rejects)

This ensures proper HTTP semantics, security logging, and error recovery.

* docs: update OAuth implementation summary to reflect library integration

Major updates to docs/oauth-implementation-summary.md:

**What Changed:**
- Updated to reflect @atproto/oauth-client-node library usage (not manual implementation)
- Documented two-layer session architecture (OAuth sessions + cookie mapping)
- Added requireAuth/optionalAuth middleware documentation (previously marked "not yet implemented")
- Corrected file references (oauth-stores.ts, cookie-session-store.ts instead of session-store.ts)
- Removed outdated limitations (automatic token refresh, session cleanup now work)
- Updated error handling section to reflect 400/401/500 distinctions
- Added security logging for CSRF/PKCE failures
- Clarified multi-PDS support (not limited to bsky.social)

**Why:**
After integrating @atproto/oauth-client-node (commit b1c40b4), documentation was stale.
Documentation claimed manual OAuth implementation and non-existent features.
Code review flagged this as a blocking issue.

This brings documentation in sync with actual implementation.

* docs: add comprehensive testing standards to CLAUDE.md

- Add 'Testing Standards' section with clear guidance on when/how to run tests
- Add pnpm test commands to Commands section
- Update workflow to explicitly include test verification step
- Define test quality standards and coverage expectations
- Provide example test structure

Motivation: PR #14 review revealed tests with bugs (31-char SESSION_SECRET)
that weren't caught before requesting review. This ensures tests are always
run before commits and code review requests.

* test: fix remaining test issues for final review

Three quick fixes to pass final code review:

**Fix 1: SESSION_SECRET length (apps/appview/src/lib/__tests__/config.test.ts:4)**
- Changed from 31 characters to 32 characters
- Was: "this-is-a-valid-32-char-secret!" (31 chars)
- Now: "this-is-a-valid-32-char-secret!!" (32 chars)
- Fixes 12 failing config tests that couldn't load config

**Fix 2: Restore await on test assertions (lines 103, 111, 128)**
- Added `await` back to `expect().rejects.toThrow()` assertions
- Vitest .rejects returns a Promise that must be awaited
- Previous removal was based on incorrect review feedback

**Fix 3: Make warning check more specific (line 177)**
- Changed from `expect(warnSpy).not.toHaveBeenCalled()`
- To: `expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("in-memory session storage"))`
- Allows OAuth URL warnings while checking that session storage warning doesn't appear
- Fixes "does not warn about in-memory sessions in development" test

**Fix 4: Update project plan documentation**
- Updated docs/atproto-forum-plan.md lines 166-168
- Changed references from "Manual OAuth" to "@atproto/oauth-client-node library"
- Changed file references from session-store.ts to oauth-stores.ts + cookie-session-store.ts
- Updated to reflect actual implementation (multi-PDS support, automatic token refresh)

**Test Results:**
- All 89 tests passing ✅
- All 13 test files passing ✅
- Minor Node.js async warning (timing, not a failure)

Ready for final merge.

Complete design for AT Protocol OAuth authentication covering:
- Decentralized PDS authority model
- @atproto/oauth-client-node integration
- Pluggable session storage (in-memory → Redis migration path)
- Authentication middleware and route protection
- Client metadata configuration
- Error handling and security considerations

Includes implementation roadmap with 5 phases and testing strategy.

Add comprehensive error handling patterns based on PR #13 review learnings:
- API route handler requirements (validation, try-catch, HTTP status codes)
- Catch block guidelines (specific types, re-throw unexpected errors)
- Helper function conventions (null returns, error re-throwing)
- Defensive programming checklist (limits, deleted filtering, ordering)
- Global error handler pattern

These standards codify patterns that emerged from multi-round PR reviews,
helping future PRs get error handling right on the first iteration.

* feat(appview): implement read-path API endpoints with database queries (ATB-11)

Implement all four read-only API endpoints that serve indexed forum data
from PostgreSQL via Drizzle ORM.

**Route Factory Pattern**
- Convert routes to factory functions accepting AppContext for DI
- createForumRoutes(ctx), createCategoriesRoutes(ctx), createTopicsRoutes(ctx)
- Routes access database via ctx.db

**Endpoints Implemented**
- GET /api/forum: Query singleton forum record (rkey='self')
- GET /api/categories: List all categories ordered by sort_order
- GET /api/categories/:id/topics: List thread starters (rootPostId IS NULL)
- GET /api/topics/:id: Fetch topic + replies with author data

**Technical Details**
- BigInt IDs serialized to strings for JSON compatibility
- Defensive BigInt parsing with try-catch (returns 400 on invalid IDs)
- LEFT JOIN with users table for author information
- Filter deleted posts (deleted = false)
- Stub implementations for test compatibility

**Files Changed**
- apps/appview/src/routes/{forum,categories,topics,index}.ts
- apps/appview/src/lib/create-app.ts
- docs/atproto-forum-plan.md (mark Phase 1 read-path complete)

All 81 tests passing.

* fix(appview): address PR review feedback - add error handling and fix category filter

Address all 7 blocking issues from PR review:

**1. Fixed Category Filter Bug (CRITICAL)**
- Categories/:id/topics now correctly filters by category URI
- Build categoryUri from category DID and rkey
- Filter posts by: rootPostId IS NULL + forumUri = categoryUri + deleted = false
- This was completely broken before - all categories showed same topics

**2. Added Database Error Handling**
- All route handlers now wrapped in try-catch
- Log structured errors with operation context
- Return user-friendly 500 errors instead of crashes
- Prevents production blind spots

**3. Fixed Overly Broad Catch Blocks**
- parseBigIntParam() helper specifically catches RangeError/SyntaxError
- Re-throws unexpected errors instead of masking them
- Returns null for invalid IDs, undefined errors propagate

**4. Added Global Error Handler**
- app.onError() catches unhandled route errors
- Structured logging with path, method, error, stack
- Returns generic error in production, details in dev

**5. Added LIMIT to Categories Query**
- Defensive limit of 1000 categories
- Prevents memory exhaustion with large datasets

**6. Fixed Inconsistent Deleted Post Filtering**
- Categories/:id/topics now filters deleted = false
- Matches topics/:id behavior
- Prevents deleted topics appearing in listings

**7. Added Reply Ordering**
- Replies now ordered by createdAt ASC (chronological)
- Previously returned in arbitrary database order

**Helper Functions Created (DRY)**
- parseBigIntParam(): Safe BigInt parsing with proper error handling
- serializeAuthor(): Deduplicated author serialization (used 3x)
- serializeBigInt(): Safe BigInt→string with null handling
- serializeDate(): Safe Date→ISO string with null handling

All 81 tests passing.

* fix(appview): remove categories/:id/topics endpoint (data model gap)

**Critical Issue from Review #2:**

The GET /api/categories/:id/topics endpoint was attempting to filter
posts by category, but the data model doesn't support this:

**The Problem:**
- posts.forumUri stores forum URIs (space.atbb.forum.forum)
- Attempted filter used category URIs (space.atbb.forum.category)
- Collections never match → always returns empty array
- This is a schema gap, not a code bug

**Decision: Remove endpoint (Option C)**

Rather than ship a broken endpoint that silently returns [] for all
categories, removing it until the schema supports category-to-post
association.

**Changes:**
- Removed GET /api/categories/:id/topics route handler
- Removed corresponding tests
- Removed stub implementation
- Cleaned up unused imports (posts, users, parseBigIntParam, etc.)
- Added TODO comments explaining why + when to re-add
- Updated docs/atproto-forum-plan.md with note

**Future Work (ATB-12 or later):**
Need to either:
1. Add categoryUri field to posts table + update indexer, OR
2. Add categoryId foreign key to posts table, OR
3. Store category reference in post lexicon record

Until then, category-filtered topic listing is not possible.

**Tests:** Reduced from 81 to 79 tests (removed 2 `:id/topics` tests)

* fix(appview): address final review cleanup items

Three minor non-blocking improvements from final review:

**1. Move Unreachable Comments to JSDoc**
- Comments after return statement were unreachable code
- Moved to function JSDoc in categories.ts
- Documents why :id/topics endpoint was removed

**2. Add Defensive LIMIT to Replies Query**
- Topics replies query had no limit (inconsistent with categories)
- Added .limit(1000) to prevent memory exhaustion on popular threads
- Now consistent across all list endpoints

**3. Fix serializeDate to Return Null**
- Was fabricating current time for missing/invalid dates
- Now returns null explicitly for missing values
- Prevents data fabrication and inconsistent responses
- API consumers can properly handle missing dates

All non-nullable schema fields (createdAt, indexedAt) should never hit
the null case in practice - this is defensive programming for data
corruption scenarios.

Ready to merge!

Replace 18 nearly-identical event handler registrations in FirehoseService
with a declarative registry pattern. This eliminates boilerplate and makes
adding new collections easier.

Changes:
- Add EventHandlerRegistry class with fluent interface
- Refactor FirehoseService to use registry for handler setup
- Derive wantedCollections from registered handlers
- Add comprehensive unit tests for registry

Benefits:
- DRY compliance: Single place to configure collection handlers
- Easier to maintain: Clear declaration-based configuration
- Simpler to extend: Adding a collection now requires one .register() call
- Better testability: Registry can be tested independently

The setupEventHandlers() method went from 86 lines of repetitive code
to 12 lines that apply the registry and set up cursor/error handlers.

Introduces a proper dependency injection pattern to make the appview
more testable and configurable. This change improves separation of
concerns and enables easier mocking in tests.

Changes:
- Add AppContext interface and factory (app-context.ts)
- Extract app creation logic to createApp() (create-app.ts)
- Add test helper createTestContext() (test-context.ts)
- Refactor index.ts to use composition root pattern
- Wrap startup in async main() for better error handling

Benefits:
- Dependencies can be easily swapped for testing
- Clear composition root at application startup
- Proper lifecycle management (creation and cleanup)
- More testable architecture with explicit dependencies

Extract three focused classes to separate concerns in FirehoseService:

- CursorManager: manages firehose cursor persistence in database
- Handles loading/saving cursor state
- Provides rewind utility for safety margin

- CircuitBreaker: implements circuit breaker pattern
- Tracks consecutive operation failures
- Triggers callback when failure threshold exceeded
- Prevents cascading failures

- ReconnectionManager: handles reconnection with exponential backoff
- Implements backoff strategy: baseDelay * 2^(attempt - 1)
- Enforces max attempt limit
- Provides attempt count for monitoring

Benefits:
- Single Responsibility Principle: each class has one well-defined purpose
- Testability: classes can be tested in isolation with unit tests
- Reusability: helper classes can be reused in other services
- Maintainability: easier to understand, modify, and debug
- Monitoring: exposes failure/attempt counts for health checks

FirehoseService now delegates cursor, circuit breaker, and reconnection
concerns to these helper classes while focusing on WebSocket management
and event routing.

Replace module-level state in indexer with class-based architecture:

- Convert all handler functions to methods on new Indexer class
- Database instance passed to constructor, not module-level variable
- Remove initIndexer() function in favor of instantiation
- Update FirehoseService to create and use Indexer instance
- Update all tests to instantiate Indexer with test database
- Add TxOrDb type alias for cleaner transaction/database parameter types

Benefits:
- Explicit dependencies - database requirement visible in constructor
- Testability - no shared module state between tests
- Flexibility - can create multiple indexer instances if needed
- Type safety - transaction parameters properly typed

Extract Transaction and DbOrTransaction types from inline definitions
in the indexer to shared type exports in @atbb/db package.

This improves code clarity and reusability by:
- Eliminating complex inline type expressions
- Providing a single source of truth for transaction types
- Adding comprehensive documentation with usage examples
- Making these types available to all consumers of @atbb/db

The Transaction type extracts the transaction callback parameter type
from Drizzle's database instance. The DbOrTransaction union type is
useful for helper functions that can work with either a database
instance or an active transaction context.

After discovering drift between codebase reality and project tracking
(ATB-10 was complete but marked as Backlog), established a clear
workflow for keeping these synchronized:

- docs/atproto-forum-plan.md (master plan with phase checklist)
- Linear issues (task tracker)

New section explains when and how to update both sources of truth
when completing work, with commit prefix convention for plan updates.

Also updated MEMORY.md with critical reminder about doc sync.

Marked Phase 0 and Phase 1 items as complete based on codebase audit:

Phase 0 (Foundation):
- Forum Service Account setup (ATB-5)
- PDS spike script validation (ATB-6)

Phase 1 (AppView Core):
- Database schema with 7 tables (ATB-7)
- Firehose subscription with Jetstream (ATB-9)
- Record indexer for all types (ATB-10)
- Read/Write API scaffolding (ATB-11, ATB-12 - in progress)

Linear issues ATB-10 and ATB-11 updated to match reality.

ATB-9: Add Jetstream firehose integration for real-time event indexing

Addresses two critical issues from PR #7 code review:

1. Lookup functions now participate in transactions
- Added dbOrTx parameter to getForumIdByUri, getForumIdByDid, and getPostIdByUri
- Updated all handlers to pass transaction context to lookups
- Ensures lookups see uncommitted writes within the same transaction
- Fixes reply chain resolution when parent and child arrive in the same batch

2. Test mocks now support transactions
- Added transaction method to createMockDb() that executes callbacks
- Prevents TypeError: mockDb.transaction is not a function in tests

Additional improvements:
- Wrapped all multi-step handlers in transactions for atomicity
- handleCategoryCreate/Update, handleMembershipUpdate, handleModActionUpdate now use transactions

All tests pass (42/42).

Address all 7 blocking issues identified in comprehensive PR review:

1. parseAtUri: Replace URL constructor with regex for at:// scheme support
2. Collection names: Use full lexicon IDs (space.atbb.forum.forum, space.atbb.forum.category)
3. Forum resolution: Add getForumIdByDid() for category/modAction records owned by Forum DID
4. ModAction subject: Access record.subject.post.uri and record.subject.did correctly
5. Circuit breaker: Track consecutive failures (max 100), stop firehose on threshold
6. Transactions: Wrap ensureUser + insert operations in db.transaction()
7. Reconnection state: Set isRunning=false on exhaustion, add health check methods

Additional improvements:
- Propagate errors from all handlers to circuit breaker
- Update test collection names and add type assertions
- Enhance error logging with event context

Added comprehensive test coverage for the firehose subscription system:

Indexer tests (indexer.test.ts):
- Post handlers: creation, updates, deletion, forum refs, reply refs
- Forum handlers: create, update, delete
- Category handlers: creation with/without forum lookup

Firehose service tests (firehose.test.ts):
- Construction and initialization
- Lifecycle management (start, stop, already running check)
- Cursor management (resume from saved, start fresh)

Test coverage:
- 42 total tests passing
- Validates event transformation logic
- Confirms proper database interaction patterns
- Tests error handling and edge cases

All tests use vitest with mocked database instances to verify
behavior without requiring actual database connections.

Resolved merge conflicts from monorepo reorganization and updated firehose
implementation to work with extracted packages:

Database layer refactoring:
- Removed singleton db export from @atbb/db package
- Added db instance injection to FirehoseService constructor
- Created initIndexer() function to initialize indexer with db instance
- Added drizzle-orm to appview dependencies for type imports

Schema alignment fixes:
- Updated post handlers to use correct column names (text not content,
rootPostId/parentPostId not replyRootId/replyParentId, deleted boolean
not deletedAt timestamp)
- Removed forumId from posts table (only forumUri exists)
- Fixed forum handlers (removed displayName and createdAt fields)
- Fixed category handlers (removed forumUri and displayName, added slug)
- Fixed membership handlers (replaced status with role/roleUri/joinedAt)
- Fixed modAction handlers (removed forumUri, use subjectPostUri not
subjectPostId, added createdBy and expiresAt)

Lexicon type fixes:
- Corrected nested ref structure (record.forum.forum.uri not
record.forumRef.uri)
- Corrected reply refs (record.reply not record.replyRef)
- Added type assertions for unknown types from Jetstream events
- Added @atproto/lexicon and multiformats dependencies to lexicon package

Note: TypeScript errors remain in generated lexicon code due to missing .js
extensions and type guard issues, but these don't affect runtime behavior.

Resolved conflicts from monorepo reorganization:
- Moved firehose implementation files to apps/appview
- Consolidated database dependencies in @atbb/db package
- Removed duplicate drizzle-orm and postgres dependencies from appview
- Added @skyware/jetstream dependency for Jetstream integration
- Updated lockfile with pnpm install

docs: analyze test coverage gaps and propose testing strategy

- Add @types/node and typescript to lexicon package devDependencies
- Add missing columns to schema tests (cid, description, indexedAt on all AT Proto record tables)
- Replace defensive if with explicit toBeDefined() in modAction test

Set up vitest as the monorepo test framework with workspace support
and turbo task integration. Added tests across all three packages:

- appview: route handler tests (health, forum, categories, topics,
posts, routing), config loading, and database schema assertions
- lexicon: contract tests validating YAML structure, lexicon IDs,
record key conventions, knownValues usage, and strongRef fields
- web: fetchApi client tests (URL construction, error handling)
and config loading tests

Tests also document two config gaps where ?? doesn't catch empty
strings, causing NaN ports and empty URLs.

https://claude.ai/code/session_01MffppURah8kTTYS3SUZu5e

The monorepo currently has zero test infrastructure and 0% coverage
across ~530 lines of source code. This document catalogs every
untested module, recommends vitest as the framework, and provides a
prioritized implementation plan with concrete code examples.

https://claude.ai/code/session_01MffppURah8kTTYS3SUZu5e

refactor: reorganize monorepo into apps/ and packages/ directories

- Add explicit types exports using conditional exports format
- Remove unused barrel file apps/appview/src/db/index.ts
- Add @types/node to @atbb/db devDependencies per project convention

All three suggestions from PR #5 code review implemented.

docs: add mobile apps plan (React Native + Expo)

Fix critical issues:
- Fix OAuth architecture: remove appview mediation endpoints, rewrite auth
flow to have mobile app exchange tokens directly with user's PDS and
present DPoP-bound tokens to appview (preserves AT Proto decentralization)
- Update iOS PWA claim: reflect iOS 16.4+ Web Push support with accurate
constraints (requires add-to-home-screen, constrained UX)
- Add missing reactions endpoints to API inventory with note about DB/lexicon
gaps
- Remove premature API versioning: defer /api/v1/* until post-v1 to avoid
breaking changes while API still evolving

Improvements per review suggestions:
- Elevate DPoP key management to dedicated Authentication subsection with
mobile-specific secure storage details (secure enclave/keystore)
- Clarify devices table is local/appview-managed, not AT Proto record
- Clarify mobile build pipeline: Metro bundler (expo/eas build) vs Turborepo
(lexicon types used at dev/typecheck only)
- Reframe component sharing question: web and mobile paradigms fundamentally
different, share types/contracts not UI components

docs: add comprehensive phpBB research and gap analysis

Critical fixes:
- Add note confirming Jetstream wildcard syntax is supported

Important fixes:
- Correct post grapheme limit (300, not 3000 chars)
- Acknowledge that limit may need revisiting for forum posts
- Fix categoryId schema mismatch (posts use forumUri)
- Update event routing to use forumUri with implementation note
- Fix Hono JSX rendering API (use JSX directly in streamSSE, not renderToString)
- Clarify "zero custom client-side JS" (HTMX itself is ~14KB)
- Update AT Proto record description (supports updates via putRecord)
- Fix empty <tr> sentinel by moving SSE attributes to <tbody>

All changes address feedback from PR review to ensure technical
accuracy before merge.

Add theming system design plan

Fix lexicon convention issues identified in code review:
- Use knownValues (not implicit enum) for colorScheme field
- Wrap theme references with strongRef for CID integrity checks
- Separate themePolicy into its own singleton to prevent forum record bloat
- Note that forum.theme must be added to CLAUDE.md ownership list

Add missing implementation details:
- Elevate CSS sanitization from open question to mandatory Phase 3 gate
- Document cache key must include resolved color scheme
- Constrain fontUrls to HTTPS with allowlist consideration
- Add database schema notes for themes and memberships tables
- Clarify AppView endpoints are REST, not XRPC

Updates theme resolution waterfall to show CID integrity checks via strongRef.

Implemented a complete firehose subscription system that connects to AT Proto Jetstream,
filters for space.atbb.* records, and indexes them into the PostgreSQL database.

Key Changes:

**Firehose Service** (packages/appview/src/lib/firehose.ts):
- Created FirehoseService class using @skyware/jetstream client
- Subscribes to space.atbb.post, space.atbb.forum, space.atbb.category,
space.atbb.membership, space.atbb.modAction, and space.atbb.reaction collections
- Implements connection lifecycle with automatic reconnection and exponential backoff
- Tracks cursor position in database for resume-from-last-position functionality
- Handles create, update, and delete events for all record types

**Record Indexer** (packages/appview/src/lib/indexer.ts):
- Implements database operations for all space.atbb.* record types
- Handles posts (topics and replies) with forum references and reply chains
- Creates users on-the-fly when new records are encountered
- Implements soft delete for posts (sets deleted flag)
- Parses AT Proto URIs to resolve foreign key references
- Handles forum, category, membership, and moderation action records

**Database Schema**:
- Added firehose_cursor table to track Jetstream event position
- Supports resuming from last known cursor after restarts
- Migration generated: drizzle/0001_daily_power_pack.sql

**Configuration**:
- Added JETSTREAM_URL environment variable
- Defaults to wss://jetstream2.us-east.bsky.network/subscribe
- Integrated firehose service with appview server startup
- Implements graceful shutdown to properly close WebSocket connections

**Dependencies**:
- Added @skyware/jetstream v0.2.5 to appview
- Added @atproto/api, @atproto/xrpc, @atproto/lexicon, multiformats to lexicon package
- Updated package exports to support direct type imports

**Integration**:
- Firehose starts automatically when appview server starts
- Handles SIGTERM and SIGINT for graceful shutdown
- Logs all record operations (create/update/delete) for debugging

Note: TypeScript build currently has issues with generated lexicon types missing .js
extensions. Runtime execution with tsx works correctly. This will be addressed in a
future update to the lexicon generation process.

Resolves ATB-9

https://claude.ai/code/session_01PaA43d9Q2ztwuRS8BRzJEL