phase: 01_runnable_service_scaffold

**Phase 01 final verification pass — all criteria green** - Verified (nothing left to implement; all 4 task files already in `complete/`): toolchain lock, typed `Settings`+`.env.example`, debugpy bootstrap, app factory, CLI (`--host/--port/--reload/--levels-dir`, `python -m undercooked`), static shell + `/static`, security headers, no-CDN/doc guards, `validate.sh`. - `uv sync --extra dev` → exit 0; `uv.lock` present (untracked → harness commits it with the phase). - `uv run undercooked --host 127.0.0.1 --port 8000` → `curl /healthz` = 200 `{"status":"ok","version":"0.1.0","rooms":0}` (superset of the criterion's body — now documented in README); `curl /` = 200 shell HTML; static css/js 200; CSP/nosniff/no-referrer/DENY on 200, 404 and 405 too. - `DEBUGPY=1`: port 5678 is held on this machine by the user's own podman dev-container debugpy adapter — **no live change made/killed**; verified via `DEBUGPY=1 DEBUGPY_PORT=5679` → listener opens, `/healthz` still 200; the occupied-port case degraded gracefully as designed (warning, server serves). Bad config → one line + exit 2 ✓. - `bash .agents/validate.sh` (root **and** `.agents/`) → exit 0: `ruff check .` 0 errors, `pyright` 0 errors, levels-CLI notice-skip (matches README prose), **284 passed** full suite incl. 10 Playwright e2e, coverage **100.00%** (floor 90), repo hygiene clean. `uv run pytest -m e2e` → 10 passed. - Docs fixed: README Status → phase 01 complete + next pending 02 (was pointing at `todo/01…`), documented real `/healthz` body, precedence now "CLI flags > env > .env > default", added the PLAN §13-promised **How to play** section (honest about shell-only today), Layout rows marked what exists vs phases 02/07. AGENTS.md: recorded the `data:`-URL exemption in the no-CDN rule (test allows it) and matched the session-token rule to the browser's WebCrypto/base64url implementation. Also corrected a stale "session-wide chromium" docstring in `tests/e2e/conftest.py` (fixtures are function-scoped). - Deviations: no container build run (needs an image pull; not a phase criterion — `Containerfile`/`compose.yaml` reviewed and consistent with `docs/DEPLOYMENT.md`); `HEAD /` is 405 (routes are GET-only by design; health checks use GET). No git index/history commands run. - Next pending phase: `02_level_content_and_validation`.
2026-10-06 01:51:20 -04:00
parent f84c6ebaef
commit 6fd83446ec
43 changed files with 5478 additions and 30 deletions
@@ -0,0 +1,48 @@
+# Phase 01 — Runnable service scaffold
+
+**Story:** `US-01_create_anonymous_lobby` (partial — landing surface only)
+**Context:** `.agents/PLAN.md` §4 (app/static/HTTP boundary), A1, A2, A12, A17, A18, A20
+
+## Objective
+Turn the empty repository into a launchable FastAPI service that serves the client
+shell, exposes `/healthz`, enforces the no-external-asset rule, and has its quality
+toolchain wired end to end. Nothing about gameplay exists yet; the app must still boot,
+serve, and pass every check.
+
+## Dependencies
+- none (first phase; `pyproject.toml`, `Containerfile`, `compose.yaml`, `README.md`,
+  `AGENTS.md`, `.agents/PLAN.md` already exist in the repo)
+
+## Tasks
+1. `01_lock_toolchain_and_packages.md` — deps resolve, `uv sync` clean, test tree + markers, first passing test
+2. `02_config_and_debugpy.md` — typed env config, `.env.example`, debugpy bootstrap
+3. `03_fastapi_app_and_static_shell.md` — app factory, CLI entry point, static shell page, security headers
+4. `04_no_cdn_guard_and_docs.md` — no-external-asset test, header tests, README/AGENTS verified
+
+## Testing & Quality
+- Unit: config parsing/defaults/overrides; static asset scan finds zero external URLs;
+  security headers present; `/healthz` returns 200 with a JSON body.
+- Integration: app boots through `create_app()` and serves `/` and `/static/*`.
+- Coverage: **>90%** on new/modified code (`config.py` and `server/app.py` fully covered).
+- The phase is "Complete" only when the **entire** project test suite passes 100%
+  (every test in the project, not just this phase's).
+- Gate commands, all green: `uv run ruff check .`, `uv run pyright`, `uv run pytest`.
+
+## Documentation & Consistency
+- The final pass reviews `README.md` and `AGENTS.md` in full against the project as it
+  will stand after this phase — fixing every inconsistency found, **including
+  pre-existing ones not caused by this phase** (e.g. commands or variable names that
+  drifted from `config.py`).
+- Tasks update `README.md`/`AGENTS.md` immediately when their own changes are
+  user-visible (setup, commands, configuration, features, conventions).
+
+## Completion Criteria
+- [ ] `uv sync --extra dev` succeeds and `uv.lock` is committed
+- [ ] `uv run undercooked --host 127.0.0.1 --port 8000 &` then
+      `curl -fsS http://127.0.0.1:8000/healthz` → `{"status":"ok"}`; `curl -fsS http://127.0.0.1:8000/` → the shell HTML
+- [ ] `DEBUGPY=1 uv run undercooked` opens port 5678 and still serves `/healthz`
+- [ ] `uv run pytest -q` → 100% passing, coverage ≥ 90%
+- [ ] `uv run ruff check .` and `uv run pyright` → zero errors
+- [ ] no file under `app/static/` references an external URL (test-enforced)
+- [ ] README.md and AGENTS.md are accurate and consistent with the whole project (verified in the final pass)
+- [ ] no behavior change in completed phases (n/a — first phase)