Emberfall/HANDOFF.md

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: 9.1 (Security checklist walk — fixed innerHTML + added rate limiter) — TICKED in STATUS.md
• Next step: Phase 9 — 9.2 (Add npm run seed:dev creating a demo account and hero)
• Updated: 2026-10-21
• 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–006 / "nothing to do"
npm test	172 passing, 0 failing (85 unit + 87 integration)

3. What exists now (files that matter)

• public/profile.html — Public hero profile page (reads ?name=, displays stats/equipment).
• public/js/profile.js — Fetches GET /api/heroes/:name, renders profile, handles 404.
• public/game.html — Dashboard with stats panel, tabbed action panel (Hunt/Inventory/Expedition).
• public/js/game.js — hunt UI + inventory UI + expedition UI.
• public/shop.html — Dedicated shop page.
• public/login.html, public/register.html, public/create-hero.html — Auth & hero creation.
• src/services/heroProfileService.js — getHeroProfile(heroName).
• src/routes/heroProfile.js — GET /api/heroes/:name (public).
• src/services/leaderboardService.js — getLeaderboard(type, page, limit).
• src/routes/leaderboard.js — GET /api/leaderboard?type=level|gold|kills.
• src/services/expeditionService.js — start, getActive, claim, listDefinitions.
• src/routes/expeditions.js — 4 expedition endpoints.
• src/services/shopService.js — getStock, buyItem, sellItem.
• src/routes/shop.js — GET/POST shop endpoints.
• src/services/inventoryService.js — listInventory, equipItem, unequipItem, useConsumable.
• src/services/huntService.js — hunt (one transaction).
• src/services/characterService.js — createCharacter, getCharacterProfile, getCharacterIdForUser.
• src/services/authService.js — register, verifyLogin.
• src/game/combat.js — resolveCombat.
• src/game/stats.js — calcDerived, xpToNext, checkLevelUp.
• src/game/energy.js — computeEnergy.
• src/utils/time.js — now()/setNow()/resetNow().
• src/app.js — Express app with helmet, rate limiters (auth + general /api), all routes.
• src/middleware/session.js — session store, requireAuth.
• src/config/index.js — env validation, frozen config.
• tests/integration/*.test.js — 87 integration tests across auth, combat, hunt, inventory, shop, expeditions, profile, leaderboard.
• tests/unit/*.test.js — 85 unit tests for game logic.

4. Half-finished / fragile things

• No leaderboard UI yet (Phase 8 API done but no UI).
• 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.
• Equipment bonuses not yet passed into combat (Issue #5 in STATUS.md).
• Starter gear (GAME_DESIGN.md §Items) documented but not auto-created on character creation.
• GET /api/zones documented in API.md but not implemented (Issue #2).
• Step 9.2 (npm run seed:dev) not yet implemented.

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.
• Inventory response uses itemId (item.id) and inventoryId (inventory row id) to avoid confusion.
• Consumable effect parsing: regex ^(heal|energy):(\d+)$ on items.effect field.
• Qty decrement avoids CHECK constraint violation: delete directly when qty==1, decrement when qty>1.
• D-008: Shop materials with buy_price=0 sell at floor(default_rate * character_level / item_min_level).
• D-009: sellItem checks equipped_slot before material type.
• D-010: startExpedition checks active-expedition before energy.
• D-011: computeEnergy uses now() from utils/time.
• D-012: General /api rate limiter at 120 req/min per IP (SECURITY.md spec), 1000 in test mode.
• D-013: All innerHTML with dynamic data removed from game.js and profile.js — use createElement/textContent.

6. Gotchas learned

• npm test must be node --test with NO path/glob; files must be named *.test.js.
• better-sqlite3-session-store ignores expired.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.
• SQL SELECT id from inventory returns the auto-increment row id; rename with AS inventory_id when you also need item_id.
• Transaction callback args must match the call order exactly.
• Error responses from route-level AppErrors do NOT include data field.
• setNow affects ALL now() calls including those in service logic.
• Shop API returns { ok: true, data: { stock: [...], character: {...} } } — field is stock, not stocks.
• Shop stock items have flat fields (itemId, buyPrice), not nested (item.id).
• New characters have NO inventory items (starter gear not auto-created yet).
• Hero profile endpoint is PUBLIC — no requireAuth middleware.
• Profile page is public: no auth.js guard needed; uses ?name= query param for lookup.
• Rate limiters in tests: set NODE_ENV=test to get 1000 req/window limit; otherwise tests fail with 429.

7. Next-step briefing (9.2)

• Goal: Add npm run seed:dev script that creates a demo account and hero on an empty DB.
• Docs: None specific — follow existing patterns (migrate.js, authService, characterService).
• Should: run migrations, then insert a test user + character, optionally give starter gear.
• Should be safe to re-run (check if demo user exists first).
• Should NOT be used in production (skip if NODE_ENV=production or check for a flag).