loop: baseline

2026-10-20 20:33:35 +11:00
parent f1ae7b3119
commit 9a308b697d
32 changed files with 959 additions and 2046 deletions
@@ -0,0 +1,50 @@
+# 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.4 (hunt endpoint) + a full review/fix pass
+- **Next step:** 4.5 — hunt UI (needs `GET /api/zones` first, see STATUS issue 2)
+- **Updated:** 2026-10-20
+- **Was the last session cut off mid-task?** No
+
+## 2. Verified state (run these first)
+| Command | Expected |
+|---|---|
+| `npm install` | succeeds (better-sqlite3 is a native module; needs Node 20+ and a C++ toolchain if no prebuilt binary) |
+| `npm run migrate` | applies 001–004 and 006 / "nothing to do" |
+| `npm test` | **93 passing, 0 failing** (69 unit + 24 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/characterService.js` — `createCharacter`, `getCharacterProfile`, `getCharacterIdForUser`.
+- `src/utils/time.js` — `now()/setNow()/resetNow()`; never call `Date.now()` in services.
+- `src/middleware/session.js` — real SQLite session store (timer unref'd).
+- `src/db/migrations/003_content.sql` — also SEEDS zones/monsters/items/loot (INSERT OR IGNORE). Changing balance = NEW migration, never edit 003.
+- `tests/helpers.js` — `setup()/teardown()/cleanup()`: fresh app + temp DB per call. `tests/integration/hunt-service.test.js` shows how to force outcomes with test-only zones.
+
+## 4. Half-finished / fragile things
+- No `GET /api/zones` yet; `public/js/game.js` has no hunt UI yet (4.5).
+- HP never regenerates naturally; only level-up restores it (Rest/potions in Phases 5–6).
+- No restart-persistence test for sessions.
+
+## 5. Decisions & deviations from the docs
+- D-004..D-007 in `docs/DECISIONS.md` (combat rounds, equipment counted once, session store, clock).
+
+## 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".
+
+## 7. Next-step briefing (4.5)
+- **Goal:** zone list + Hunt button + combat log replay + result summary + level-up message on the dashboard.
+- **Docs:** API.md §Hunting, UI_GUIDE.md §game.html, GAME_DESIGN.md §Combat.
+- **Files:** add `src/routes/zones.js` (+ service fn) and mount in app.js; extend `public/game.html` + `public/js/game.js`; add an integration test for `GET /api/zones`.
+- **Watch out for:** use `textContent` (no innerHTML); show energy cost on the button; disable button while request is in flight; re-sync energy from the hunt response (`data.energy`, `data.hpRemaining`, `data.hpMax`).
+
+## 8. Open Known Issues
+STATUS.md issues 1–6 (balance, zones endpoint, dangling `seed` script, restart test, equipment-in-combat, HP regen).