step 10.8: wip (not ticked)

HANDOFF.md

@@ -4,9 +4,9 @@
 > If this file disagrees with the code, trust the code and fix this file.
 
 ## 1. Where we are
-- **Last completed step:** 10.7 — Error handling gaps: malformed JSON → 400 INVALID_JSON, body over limit → 413 PAYLOAD_TOO_LARGE, unknown /api/* → 404 JSON, session regenerate throw → next(err) — TICKED in STATUS.md
-- **Next step:** Phase 10.8 — POST /api/character/allocate (stat point allocation)
-- **Updated:** 2026-10-22
+- **Last completed step:** 10.8 — POST /api/character/allocate: stat point allocation endpoint with zod validation, service transaction, and 12 integration tests — TICKED in STATUS.md
+- **Next step:** Phase 10.9 — Allocation UI: unspent points display with + buttons per stat on dashboard stats panel
+- **Updated:** 2026-10-23
 - **Was the last session cut off mid-task?** No
 
 ## 2. Verified state (run these first)
@@ -14,18 +14,18 @@
 |---|---|
 | `npm install` | succeeds |
 | `npm run migrate` | applies 001–006 / "nothing to do" |
-| `npm test` | **202 passing, 0 failing** (85 unit + 112 integration incl. 4 rate-limiting + 5 error-handling tests) |
+| `npm test` | **214 passing, 0 failing** (85 unit + 124 integration incl. 12 allocate tests) |
 | `npm run seed:dev` | creates demo user "demo"/"demo123", hero "Aldric" (warrior), starter gear |
 | `npm start` + `curl localhost:3000/` | 200 HTML landing page |
-| `npm start` + `curl localhost:3000/api/health` | `{"ok":true}` |
-| `curl -X POST localhost:3000/api/auth/login -H 'Content-Type: application/json' -d '{bad'` | 400 `{"ok":false,"error":{"code":"INVALID_JSON",...}}` |
-| `curl -X POST localhost:3000/api/auth/login -H 'Content-Type: application/json' -d '{"data":"x"' --data-binary @<(python3 -c "print('x'*12000)")` | 413 `{"ok":false,"error":{"code":"PAYLOAD_TOO_LARGE",...}}` |
-| `curl localhost:3000/api/nonexistent` | 404 `{"ok":false,"error":{"code":"NOT_FOUND",...}}` |
+| `curl -X POST localhost:3000/api/character/allocate -H 'Content-Type: application/json' -H 'Cookie: ...' -d '{"str":1}'` | 200 with updated stats (requires authenticated session) |
 
 ## 3. What exists now (files that matter)
-- `src/app.js` — JSON parser error handling added: SyntaxError (400 INVALID_JSON), PayloadTooLargeError (413 PAYLOAD_TOO_LARGE). Catch-all for /api/* paths always returns JSON.
-- `src/routes/auth.js` — Session regenerate/destroy callbacks use `next(err)` instead of `throw`.
-- `tests/integration/step-10.7.test.js` — 5 tests: malformed JSON on login, malformed JSON on character, body over limit, unknown /api/*, session regenerate error.
+- `src/services/characterService.js` — New `allocatePoints(userId, allocation)` function: validates input, uses `allocatePoints` from `leveling.js`, computes `remainingPoints = character.unspent_points - total`, updates in transaction, returns `{character, derived}`.
+- `src/routes/character.js` — New `handleAllocate` handler with zod `.strictObject` schema (optional stat fields + `.refine` requiring at least one).
+- `src/game/leveling.js` — `allocatePoints` now accepts non-negative integers (including 0 for unallocated stats).
+- `src/app.js` — Route `POST /api/character/allocate` mounted with `requireAuth`.
+- `tests/integration/step-10.8.test.js` — 6 HTTP integration tests (spend partial, overspend, negative, float, unknown keys, cross-user).
+- `tests/integration/allocate-service.test.js` — 6 direct service tests (same scenarios via service call).
 
 ## 4. Half-finished / fragile things
 - No leaderboard UI yet (stub page exists; real UI in 10.17).
@@ -36,7 +36,7 @@
 - Starter gear documented but not auto-created on character creation.
 - `GET /api/zones` documented in API.md but not implemented (Issue #2).
 - Mobile nav uses emoji icons (⚔️ 🏕️ 🎒) — verify they render acceptably on all platforms.
-- **10.8 next:** POST /api/character/allocate — stat point allocation endpoint.
+- **10.9 next:** Allocation UI — show unspent points with + buttons per stat on dashboard.
 
 ## 5. Decisions & deviations from the docs
 - D-004..D-007 in `docs/DECISIONS.md` (combat rounds, equipment counted once, session store, clock).
@@ -46,6 +46,7 @@
 - **D-017:** Landing page `public/index.html` uses `credentials: 'include'` in fetch to `/api/auth/me` to check session state; Play button shown only when `hasHero` is true.
 - **D-018:** Link-checker test skips API endpoints (`/api/...`) since they're not static files.
 - **D-019:** Rate limiters use `process.env.NODE_ENV === 'test' ? 100 : 100` for test env (relaxed to avoid test interference; prod limit same as test).
+- **D-020:** `allocatePoints` in `leveling.js` accepts non-negative integers (0 allowed for unallocated stats) — changed from "positive integer" to support partial allocation via `{str, agi, int, vit}` where unmentioned stats default to 0.
 
 ## 6. Gotchas learned
 - `npm test` must be `node --test` with NO path/glob; files must be named `*.test.js`.
@@ -87,11 +88,9 @@
 - **10.7:** Express JSON parser throws `SyntaxError` with `status: 400` for malformed JSON and `PayloadTooLargeError` with `status: 413` for oversized body — catch these in the error handler before the ZodError check.
 - **10.7:** `req.path.startsWith('/api/')` is more reliable than `req.accepts('html')` for deciding JSON vs HTML on unknown paths — Node.js fetch defaults to accepting HTML.
 - **10.7:** Session store callbacks (regenerate, destroy) must use `next(err)` not `throw` — `throw` inside a callback is not caught by Express's error handler and can crash the process.
+- **10.8:** `leveling.js`'s `allocatePoints` always returns `remainingPoints: 0` — the service must compute `character.unspent_points - total` itself.
+- **10.8:** zod `.strictObject` with optional fields needs `.refine()` to require at least one field present.
+- **10.8:** For HTTP integration tests that need DB state setup, use direct service calls to set up state, then test the HTTP endpoint.
 
 ## 7. Next-step briefing
-- **Next step: 10.8** — Add `POST /api/character/allocate` endpoint:
-  - Body: `{str,agi,int,vit}` as points to add (zod `.strict()`, non-negative integers)
-  - Use existing `allocatePoints` from `src/game/leveling.js`
-  - One transaction; reject if total exceeds `unspent_points` (422 `NOT_ENOUGH_POINTS`)
-  - Return `{character, derived}`
-  - Tests: spend partial points, overspend → 422, negative/float/unknown keys → 400, cross-user rejection
+- **Next step: 10.9** — Allocation UI: on the dashboard stats panel show unspent points and a `+` button per stat (only when points remain), with a confirm/apply button, loading state, and error toast. Use `textContent`, never `innerHTML` with dynamic data.