Files

T

ducoterra 6fd83446ec 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

2.8 KiB

Raw Blame History

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

01_lock_toolchain_and_packages.md — deps resolve, uv sync clean, test tree + markers, first passing test
02_config_and_debugpy.md — typed env config, .env.example, debugpy bootstrap
03_fastapi_app_and_static_shell.md — app factory, CLI entry point, static shell page, security headers
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)

2.8 KiB Raw Blame History