feat(web): implement web server foundation

tickets/2026-01-07-web-server-foundation.md

@@ -0,0 +1,59 @@
+# 2026-01-07-web-server-foundation: Web Server Infrastructure Foundation
+
+**Status:** Done
+**Created:** 2026-01-07
+**Tags:** infrastructure, web, core
+
+## 1. Context & User Story
+* **As a:** Developer
+* **I want to:** Establish a lightweight, integrated web server foundation within the existing codebase.
+* **So that:** We can serve internal tools (Workbench) or public pages (Leaderboard) with minimal friction, avoiding complex separate build pipelines.
+
+## 2. Technical Requirements
+### Architecture
+- **Native Bun Server:** Use `Bun.serve()` for high performance.
+- **Exposure:** The server port must be exposed in `docker-compose.yml` to be accessible outside the container.
+- **Rendering Strategy:** **Server-Side Rendering (SSR) via Template Literals**.
+    - *Why?* Zero dependencies. No build step (like Vite/Webpack) required. We can simply write functions that return HTML strings.
+    - *Client Side:* Minimal Vanilla JS or a lightweight drop-in library (like HTMX or Alpine from CDN) can be used if interactivity is needed later.
+
+### File Organization (`src/web/`)
+We will separate the web infrastructure from game modules to keep concerns clean.
+- `src/web/server.ts`: Main server class/entry point.
+- `src/web/router.ts`: Simple routing logic.
+- `src/web/routes/`: Individual route handlers (e.g., `home.ts`, `health.ts`).
+- `src/web/views/`: Reusable HTML template functions (Header, Footer, Layouts).
+- `src/web/public/`: Static assets (CSS, Images) served directly.
+
+### API / Interface
+- **GET /health**: Returns `{ status: "ok", uptime: <seconds> }`.
+- **GET /**: Renders a basic HTML landing page using the View system.
+
+## 3. Constraints & Validations (CRITICAL)
+- **Zero Frameworks:** No Express/NestJS.
+- **Zero Build Tools:** No Webpack/Vite. The code must be runnable directly by `bun run`.
+- **Docker Integration:** Port 3000 (or env `PORT`) must be mapped in Docker Compose.
+- **Static Files:** Must implement a handler to check `src/web/public` for file requests.
+
+## 4. Acceptance Criteria
+1. [x] `docker-compose up` exposes port 3000.
+2. [x] `http://localhost:3000` loads a styled HTML page (verifying static asset serving + SSR).
+3. [x] `http://localhost:3000/health` returns JSON.
+4. [x] Folder structure established as defined above.
+
+## 5. Implementation Plan
+- [x] **Infrastructure**: Create `src/web/` directory structure.
+- [x] **Core Logic**: Implement `WebServer` class in `src/web/server.ts` with routing and static file serving logic.
+- [x] **Integration**: Bind `WebServer.start()` to `src/index.ts`.
+- [x] **Docker**: Update `docker-compose.yml` to map port `3000:3000`.
+- [x] **Views**: Create a basic `BaseLayout` function in `src/web/views/layout.ts`.
+- [x] **Env**: Add `PORT` to `config.ts` / `env.ts`.
+
+## Implementation Notes
+- Created `src/web` directory with `router.ts`, `server.ts` and subdirectories `routes`, `views`, `public`.
+- Implemented `WebServer` class using `Bun.serve`.
+- Added basic CSS and layout system.
+- Added `PORT` to `src/lib/env.ts` (default 3000).
+- Integrated into `src/index.ts` to start on boot and graceful shutdown.
+- Fixed unrelated typing issues in `src/commands/admin/note.ts` and `src/db/indexes.test.ts` to pass strict CI checks.
+- Verified with `bun test` and `bun x tsc`.