# Refactor Log

Internal refactor of AdventureOS. Behaviour, API contracts, and schema preserved unless explicitly noted.

## Phase 1: Safety baseline

- Removed debug telemetry from `apps/web/src/app/api/library/books/route.ts`
- Extracted pure adventure helpers: `derive-state.ts`, `template-matching.ts`, `checklist-value.ts`
- Added unit tests for `@adventureos/shared` (xp, levels, scores, chapters)
- Added characterization tests for deriveState, template matching, undo Calibre mismatch
- Replaced misnamed `feature-repair.test.ts` with real tests

### Manual smoke checklist

- [ ] Login / logout
- [ ] Command Centre: adventure items, todos, rest day, customize
- [ ] Settings: theme, AI config, templates, action history undo
- [ ] Library: manual books and Calibre (if configured)
- [ ] Cartographer: generate, activate, complete, dismiss
- [ ] Teacher: generate, complete, deep links
- [ ] Undo toast and settings undo

### Commands run each phase

```bash
npm run test
npm run lint
npm run build
npm run db:migrate   # when DB available
```

## Phase 2: Configuration and constants

- Centralised env reads in `lib/config/`
- Typed constants for settings keys, action types, theme IDs

## Phase 3: API and data access

- Zod input validation on teacher, templates, settings routes
- Repository layer for settings, teacher, adventure templates
- Typed errors in `lib/errors/`; `handleApi` uses `mapErrorToResponse`
- Teacher route uses `createTeacherLesson` service

## Phase 4: Domain/service cleanup

- Split `adventure.ts` into `lib/services/adventure/{materialization,daily,scoring,templates}.ts`
- Unified Calibre reading log via `lib/services/reading/log-pages.ts`

## Phase 5: Frontend cleanup

- Client API: `features/adventure/api.ts`, `features/undo/api.ts`, `lib/api-client.ts`
- Hooks: `useAdventureMutations`, `useUndoMutation`, `useActionToastHandlers`
- Split `todays-adventure.tsx`; extracted `adventure-item-row`, `checklist-item`
- Consolidated AI prompt editors into `AiPromptEditor`
- Shared UI: `RetroWindow`, `TabToggle`, `LoadingState`, `ErrorState`
- Undo toast uses query invalidation (no full page reload)

## Phase 6: Type safety

- JSONB interfaces in `lib/types/jsonb.ts`
- Teacher types in `@adventureos/shared`
- Removed unused `@radix-ui/*` dependencies

## Phase 7: Tests and CI

- Validation/error unit tests
- `@adventureos/shared` test script and vitest config
- Root `npm run test` runs web + shared
- GitHub Actions CI workflow

## Phase 8: Documentation

- [ARCHITECTURE.md](./ARCHITECTURE.md) — layers and service boundaries
- [KNOWN-ISSUES.md](./KNOWN-ISSUES.md) — documented gaps