Emberfall/STATUS.md

STATUS.md — Living Progress Tracker

Agent rules for this file

• Update it at the end of EVERY step. Do not skip.
• Only tick a box when the step's Acceptance line is actually verified.
• Add problems you could not fix to Known Issues instead of hiding them.
• Keep Session Log entries to one or two lines.

Current Focus

• Phase: 4
• Step: 4.4
• Blocked? No
• Last verified working command: npm test — 62/62 passing, Phase 4 step 4.4 complete

Project Health

Item	State
App starts (npm start)	✅ works (session interval keeps process alive)
Tests pass (npm test)	✅ 62/62 passing (4 hunt + 6 auth + 1 health + 51 unit)
Migrations run clean on empty DB	✅ 001_users, 002_characters, 003_content, 004_inventory, 006_logs
Can register + login	✅ verified by tests
Data persists across restart	✅ SQLite-backed sessions

---

Phase 0 — Scaffold

• 0.1 npm init, install deps from NOTES.md §2, add scripts: start, dev (node --watch), test, migrate, seed. Acceptance: npm install succeeds; scripts exist in package.json.
• 0.2 src/config/index.js loads .env (use process.loadEnvFile or dotenv), validates required vars, exports a frozen config object. Acceptance: missing SESSION_SECRET in production throws a clear error.
• 0.3 src/db/index.js opens SQLite (WAL mode, foreign_keys ON) and exports the handle. scripts/migrate.js runs numbered .sql files from src/db/migrations/ in order and records them in a _migrations table. Acceptance: npm run migrate twice in a row is safe (second run does nothing).
• 0.4 src/app.js (builds Express app, no listen) + src/server.js (listens). Add helmet, JSON body parser (limit 10kb), static public/, GET /api/health → {ok:true}, central error handler (see CODING_STANDARDS). Acceptance: curl localhost:3000/api/health returns {"ok":true}.
• 0.5 First test: health endpoint via node:test + fetch against app on an ephemeral port (see TESTING.md). Acceptance: npm test passes.

Phase 1 — Accounts & Sessions (docs: DATABASE, API, SECURITY)

• 1.1 Migration 001_users.sql (users table).
• 1.2 src/services/authService.js: register, verifyLogin. bcryptjs cost 10–12. Case-insensitive unique username.
• 1.3 Session middleware (httpOnly, sameSite=lax, secure in production, SQLite-backed store) + requireAuth middleware.
• 1.4 Routes: POST /api/auth/register, POST /api/auth/login, POST /api/auth/logout, GET /api/auth/me. Zod validation. Rate limit login/register.
• 1.5 Pages public/login.html, public/register.html + public/js/auth.js.
• 1.6 Tests: register ok, duplicate username, bad password, login ok/fail, me requires session, logout clears session. Acceptance (phase): can register, log in, refresh page and stay logged in, restart server and stay logged in, log out.

Phase 2 — Hero Creation & Profile (docs: GAME_DESIGN §Classes, DATABASE, BALANCE)

• 2.1 Migration 002_characters.sql.
• 2.2 src/game/classes.js (class base stats) + src/game/stats.js (derived stats). Unit tests.
• 2.3 POST /api/character (create; one per user), GET /api/character (full profile incl. derived stats and current energy).
• 2.4 public/create-hero.html, public/game.html (dashboard shell with stats panel). Acceptance: new user is redirected to create-hero; after creation, dashboard shows stats.

Phase 3 — Energy & Lazy Time (docs: GAME_DESIGN §Time, BALANCE)

• 3.1 src/game/energy.js: pure computeEnergy(stored, updatedAtMs, nowMs, cfg) → {energy, updatedAtMs}. Unit tests incl. cap, partial intervals, clock going backwards.
• 3.2 characterService.spendEnergy(characterId, cost) runs in a transaction; rejects when insufficient.
• 3.3 Dashboard shows energy bar + "next +1 in mm:ss" countdown (client-side countdown only; server remains authoritative). Acceptance: set energy_updated_at back in DB by 30 min → refresh shows regen applied. Verified: energy bar + countdown in game.html/game.js; server returns nextTickInSec; 16 computeEnergy unit tests cover cap/partial/large-gap scenarios.

Phase 4 — Combat (Hunting) (docs: GAME_DESIGN §Combat, BALANCE)

• 4.2 src/game/combat.js: pure resolveCombat(hero, monster, rng) → {winner, rounds[], hpRemaining}. Seedable RNG in src/utils/rng.js. Unit tests with fixed seed. Acceptance: 10 combat unit tests pass; deterministic with same seed; speed determines turn order; mage bonus vs high-def; 20-round cap.
• 4.3 src/game/rewards.js: XP, gold, loot roll. src/game/leveling.js: XP curve, level-up, stat points. Acceptance: 23 unit tests pass; xpToNext matches BALANCE.md; level-up handles multi-level; points allocation validated.
• 4.4 POST /api/hunt { zoneId }: spend energy → pick monster → resolve → apply rewards/penalty → write combat_log → return summary + round log. All inside one DB transaction. Acceptance: 4 integration tests pass; hunt returns winner, rounds, xpGained, goldGained, loot, leveledUp, zone, monster.
• 4.5 UI: zone list, "Hunt" button, combat log display, result summary, level-up message. Acceptance: hunting repeatedly drains energy, awards XP/gold, levels the hero, and persists.

Phase 5 — Inventory & Equipment (docs: GAME_DESIGN §Items, DATABASE)

• 5.1 Migration 004_inventory.sql.
• 5.2 Services + routes: list inventory, equip, unequip (slots: weapon, armor, trinket). Equipment modifies derived stats.
• 5.3 Stackable consumables: POST /api/inventory/use (health potion heals; energy tonic restores energy, capped).
• 5.4 UI: inventory grid, equipment panel, tooltips with stats.

Phase 6 — Shop & Economy (docs: GAME_DESIGN §Economy)

• 6.1 GET /api/shop, POST /api/shop/buy, POST /api/shop/sell. Sell value = 40% of base price. Gold can never go negative.
• 6.2 Level-gated shop stock. UI page.
• 6.3 Tests: buy with insufficient gold, sell equipped item (must be rejected), concurrent double-buy safety (transaction).

Phase 7 — Expeditions (Offline Progress) (docs: GAME_DESIGN §Time, §Expeditions)

• 7.1 Migration 005_expeditions.sql. Expedition definitions in seed data.
• 7.2 POST /api/expeditions/start, GET /api/expeditions/active, POST /api/expeditions/claim. Only one active expedition per hero. Claim rejected before ends_at.
• 7.3 UI: start panel, progress bar, claim button. Acceptance: start → close browser → return after duration → claim → rewards granted exactly once.

Phase 8 — Leaderboards & Social-lite (docs: GAME_DESIGN §Leaderboards)

• 8.1 GET /api/leaderboard?type=level|gold|kills top 50, with pagination param.
• 8.2 Public profile GET /api/heroes/:name (no private data).
• 8.3 UI page.

Phase 9 — Hardening & Polish (docs: SECURITY, UI_GUIDE, TESTING)

• 9.1 Walk the SECURITY.md checklist; fix gaps.
• 9.2 Add npm run seed:dev creating a demo account and hero.
• 9.3 Global error pages / friendly UI error toasts. Loading states.
• 9.4 Mobile-responsive pass (see UI_GUIDE).
• 9.5 Final full run of "Definition of playable" from NOTES.md §7. Record results below.
• 9.6 Update README with real run instructions.

Stretch Goals (only after Phase 9)

• S1 Async PvP duels (attack another hero's snapshot; cooldown; rating).
• S2 Skills / talent points spent on level-up.
• S3 Guilds (create, join, leave, guild board).
• S4 Player market (list/buy items between players, 5% tax gold sink).
• S5 Daily login reward + daily quests.
• S6 In-game chat via polling (no websockets).
• S7 Achievements.

---

Known Issues

#	Area	Description	Severity	Status	Found in step
none yet

Severity: blocker / major / minor / cosmetic. Status: open / fixing / wontfix / fixed.

Technical Debt / TODOs

• none yet

Open Questions (for the human)

• none yet

Decisions Made (short; long form goes in docs/DECISIONS.md)

• none yet

Test Summary

Suite	Passing	Failing	Last run
unit	51	0	Phase 4.4
integration	7	0	Phase 4.4

Session Log

Format: YYYY-MM-DD | step | what changed | result

• 2026-10-20 | 4.4 | Created 004_inventory.sql + 006_logs.sql migrations; fixed huntService transaction (db.transaction() returns wrapper, must call separately); added huntService to helpers.js cache invalidation; session middleware uses memory store in tests | 62/62 tests pass, hunt endpoint working
• 2026-10-20 | 3.3 | Fixed game.js countdown: separated updateEnergyBar (pure display) from startCountdown (client-side timer), added energyData store and startEnergySync (60s server refetch) | 35/35 tests pass, energy bar + countdown working correctly
• 2026-10-20 | 0.1 | npm init -y, installed express, better-sqlite3, bcryptjs, express-session, better-sqlite3-session-store, helmet, express-rate-limit, zod; added start/dev/test/migrate/seed scripts | verified all 5 scripts present in package.json
• 2026-10-20 | 0.2 | Created src/config/index.js with process.loadEnvFile, required var validation, frozen export | verified config loads; production check rejects placeholder SECRET
• 2026-10-20 | 0.3 | Created src/db/index.js (WAL, FK ON) + scripts/migrate.js (runs numbered .sql, tracks in _migrations) | npm run migrate twice is safe
• 2026-10-20 | 0.4 | Created src/utils/errors.js, src/app.js (helmet, JSON parser, static, health, error handler) + src/server.js | curl localhost:3000/api/health → {"ok":true}
• 2026-10-20 | 0.5 | Created tests/health.test.js — boots app on ephemeral port, hits /api/health | npm test passes (1/1)
• 2026-10-20 | 1.1 | Created src/db/migrations/001_users.sql | migration applies clean
• 2026-10-20 | 1.2 | Created src/services/authService.js: register + verifyLogin with bcrypt cost 12, timing-safe | service loads
• 2026-10-20 | 1.3 | Created src/middleware/session.js: better-sqlite3-session-store, requireAuth | middleware loads
• 2026-10-20 | 1.4 | Created src/routes/auth.js with Zod validation, rate limiting; integrated into app.js | app loads
• 2026-10-20 | 1.5 | Created public/login.html, public/register.html, public/css/main.css, public/js/auth.js, login.js, register.js | static files served
• 2026-10-20 | 1.6 | Created tests/helpers.js + tests/auth.test.js (6 tests) | 6/6 auth tests pass
• 2026-10-20 | 2.1 | Created src/db/migrations/002_characters.sql | migration applies clean
• 2026-10-20 | 2.2 | Created src/game/classes.js, src/game/stats.js + unit tests (23 tests) | 23/23 pass
• 2026-10-20 | 2.3 | Created src/services/characterService.js, src/routes/character.js; integrated into app.js | app loads
• 2026-10-20 | 2.4 | Created public/create-hero.html, public/game.html, public/js/create-hero.js, public/js/game.js | app loads