61 lines
3.9 KiB
Markdown
61 lines
3.9 KiB
Markdown
# HANDOFF.md — Session Handoff (OVERWRITE at the end of every phase or when context is getting long)
|
||
|
||
> **Read order for a new session:** `NOTES.md` → `STATUS.md` → this file → then work.
|
||
> If this file disagrees with the code, trust the code and fix this file.
|
||
|
||
## 1. Where we are
|
||
- **Last completed step:** 4.5 (hunt UI — zones endpoint, combat-log endpoint, zone cards, hunt button, result panel, combat log replay)
|
||
- **Next step:** 5.1 — inventory migration (`004_inventory.sql`)
|
||
- **Updated:** 2026-10-20
|
||
- **Was the last session cut off mid-task?** No
|
||
|
||
## 2. Verified state (run these first)
|
||
| Command | Expected |
|
||
|---|---|
|
||
| `npm install` | succeeds |
|
||
| `npm run migrate` | applies 001–004 and 006 / "nothing to do" |
|
||
| `npm test` | **98 passing, 0 failing** (74 unit + 29 integration) |
|
||
|
||
## 3. What exists now (files that matter)
|
||
- `src/game/stats.js` — `calcDerived()` is the ONLY derived-stat formula. Also re-exports xpToNext/checkLevelUp (implemented in `leveling.js`).
|
||
- `src/game/combat.js` — `resolveCombat(hero, monster, rng)`; both sides attack each round, faster first.
|
||
- `src/services/huntService.js` — `hunt(characterId, zoneId, {rng, now})`; ONE transaction; test-injectable.
|
||
- `src/services/zoneService.js` — `listZones(characterLevel)` → zones with `unlocked` flag.
|
||
- `src/services/combatLogService.js` — `getCombatLog(characterId, limit)` → recent fights.
|
||
- `src/services/characterService.js` — `createCharacter`, `getCharacterProfile`, `getCharacterIdForUser`.
|
||
- `src/utils/time.js` — `now()/setNow()/resetNow()`; never call `Date.now()` in services.
|
||
- `src/routes/zones.js` — `GET /api/zones`.
|
||
- `src/routes/combatLog.js` — `GET /api/combat-log`.
|
||
- `src/db/migrations/003_content.sql` — also SEEDS zones/monsters/items/loot (INSERT OR IGNORE).
|
||
- `tests/integration/zones-log.test.js` — 5 integration tests for zones + combat-log endpoints.
|
||
- `public/game.html` — dashboard with stats panel, zone list, combat log, result panel.
|
||
- `public/js/game.js` — full hunt UI: load zones, hunt handler, result display, combat log replay, toast notifications, energy sync.
|
||
- `public/css/main.css` — zone cards, combat log entries, result panel, toast styles.
|
||
|
||
## 4. Half-finished / fragile things
|
||
- No inventory/equipment system yet (Phase 5).
|
||
- HP never regenerates naturally; only level-up restores it.
|
||
- No restart-persistence test for sessions.
|
||
- `npm run seed` script in package.json points to nonexistent `scripts/seed.js`.
|
||
|
||
## 5. Decisions & deviations from the docs
|
||
- D-004..D-007 in `docs/DECISIONS.md` (combat rounds, equipment counted once, session store, clock).
|
||
- Zod query param parsing uses `zod.coerce.number()` because Express query params are strings.
|
||
|
||
## 6. Gotchas learned
|
||
- `npm test` must be `node --test` with NO path/glob; files must be named `*.test.js`. A shell glob once skipped 17 tests.
|
||
- better-sqlite3-session-store ignores `clear:false`; that's why the timer is unref'd.
|
||
- Statement caches are per-DB-handle (WeakMap) in huntService; copy that pattern for new services.
|
||
- Verify test COUNT, not just "all passing".
|
||
- Node.js `fetch` doesn't persist cookies across calls — extract `Set-Cookie` header and pass manually in integration tests.
|
||
- Express query params are strings, not numbers — use `zod.coerce.number()` for numeric query params.
|
||
|
||
## 7. Next-step briefing (5.1)
|
||
- **Goal:** Create `004_inventory.sql` migration (inventory table + starting items for new heroes).
|
||
- **Docs:** DATABASE.md, GAME_DESIGN.md §Items.
|
||
- **Files:** `src/db/migrations/004_inventory.sql`.
|
||
- **Schema:** `inventory` table (`id, character_id, item_id, quantity, equipped_slot NULL, acquired_at`), FK constraints. Starting items: class-appropriate common weapon (auto-equipped) + 2 Minor Healing Potions on character creation.
|
||
|
||
## 8. Open Known Issues
|
||
STATUS.md issues 1–6 (balance, dangling `seed` script, restart test, equipment-in-combat, HP regen, zone min_level balance).
|