From 71f61bb12209cc5913531b113ccb30ce8d618045 Mon Sep 17 00:00:00 2001 From: Frank Tovar Date: Wed, 28 Jan 2026 14:23:08 +0100 Subject: [PATCH] initial md submit --- AGENTS.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ API.md | 26 +++++++++++++++++++ IIS.md | 7 +++++ SPEC.md | 37 ++++++++++++++++++++++++++ TASKS.md | 47 +++++++++++++++++++++++++++++++++ 5 files changed, 195 insertions(+) create mode 100644 AGENTS.md create mode 100644 API.md create mode 100644 IIS.md create mode 100644 SPEC.md create mode 100644 TASKS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7fa581b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,78 @@ +# Codex Agent Guide — CoopGameChooser + +This repo is a tiny, purpose-built web app for a closed Discord group to: +1) submit game suggestions blindly +2) reveal all suggestions with authors +3) vote 0–10 blindly +4) reveal totals sorted by score + +Tech constraints: +- .NET 8 +- ASP.NET Core Minimal API +- Static HTML/CSS/JS (no Razor Pages, no Blazor, no HTMX) +- SQLite via EF Core +- Cookie-based anonymous identity (no accounts) +- Single active “session” (one room) unless extended later +- Runs on IIS (Windows Server) + +This file tells Codex how to work in this repo. +Also see the other related files: API.md, IIS.md, SPEC.md + +--- + +## Operating Principles + +### Non-negotiables +- **Server-side enforcement of phase rules** (clients must not be trusted). +- **Blindness**: + - Suggest phase: player can only read/write their own suggestions. + - Vote phase: player can only read/write their own votes. + - Results phase: only aggregated totals are shown. +- **Minimal moving parts**: prefer `Program.cs` + a few small files over frameworks. + +### “Ridiculously fast” bias +- Prefer “ship a working MVP” over architecture purity. +- Avoid introducing new dependencies unless they remove complexity. + +--- + +## Repo Layout Target + +- `Program.cs` — Minimal API endpoints, middleware, cookie identity, admin endpoints +- `Data/` — EF Core DbContext and migrations (optional for MVP) +- `Domain/` — Plain models: Player, Suggestion, Vote, AppState, Phase enum +- `wwwroot/` + - `index.html` — app shell; loads phase-specific views + - `app.js` — API client + render functions + polling + - `styles.css` — minimal styling + +Do not introduce MVC controllers, Razor Pages, Blazor, or SPA frameworks. + +--- + +## Implementation Checklist (Codex should follow this order) + +1. App boots and serves static files +2. Cookie-based anonymous identity +3. Phase gating (server-side) +4. Suggest phase (blind input) +5. Reveal phase (read-only) +6. Vote phase (blind scoring) +7. Results phase (aggregated leaderboard) +8. Admin controls (phase switch, reset) + +--- + +## Security Notes + +- Cookie must be HttpOnly and SameSite=Strict +- Use HTTPS in production +- No client-side trust for blindness + +--- + +## Codex Working Style + +- Implement API first, UI second +- Keep changes small and testable +- Prefer clarity over abstraction diff --git a/API.md b/API.md new file mode 100644 index 0000000..e25f55a --- /dev/null +++ b/API.md @@ -0,0 +1,26 @@ +# API Contract (MVP) + +All endpoints are JSON. Player identity comes from HttpOnly cookie `player`. + +## State +GET /api/state + +## Player +GET /api/me +POST /api/me/name + +## Suggestions +GET /api/suggestions/mine +POST /api/suggestions +GET /api/suggestions/all + +## Votes +GET /api/votes/mine +POST /api/votes + +## Results +GET /api/results + +## Admin +POST /api/admin/phase +POST /api/admin/reset diff --git a/IIS.md b/IIS.md new file mode 100644 index 0000000..ebe7b68 --- /dev/null +++ b/IIS.md @@ -0,0 +1,7 @@ +# IIS Deployment Notes + +- ASP.NET Core out-of-process behind IIS +- HTTPS termination at IIS +- SQLite DB stored in App_Data +- App pool identity must have write access +- Admin password via environment variable diff --git a/SPEC.md b/SPEC.md new file mode 100644 index 0000000..df47436 --- /dev/null +++ b/SPEC.md @@ -0,0 +1,37 @@ +# CoopGameChooser — Product Spec (MVP) + +## Goal +A micro web app for a closed Discord group (4–8 players) to decide what co-op game to play using a phased process: +1. Suggest (blind) +2. Reveal (discuss) +3. Vote (blind scoring 0–10) +4. Results (leaderboard) + +## MVP Scope +- Single shared instance +- Anonymous join via cookie +- Organizer-controlled phase switching + +## Suggest Phase +- Up to 3 suggestions per player +- Name required +- Optional genre, description, screenshot URL, YouTube URL +- Players see only their own suggestions + +## Reveal Phase +- All suggestions visible +- Suggester name shown +- Suggestions locked + +## Vote Phase +- Score each suggestion 0–10 +- Players see only their own votes + +## Results Phase +- Totals, vote count, optional averages +- Sorted by total descending + +## Non-functional +- Desktop + mobile usable +- Simple polling acceptable +- IIS-hosted diff --git a/TASKS.md b/TASKS.md new file mode 100644 index 0000000..96e9e8d --- /dev/null +++ b/TASKS.md @@ -0,0 +1,47 @@ +# CoopGameChooser Task List + +- [x] Initialize git repository. + +## Foundation +- [ ] Add `.gitignore` for .NET / IIS publish artifacts. +- [ ] Scaffold .NET 8 minimal API project with static file hosting (`wwwroot`). +- [ ] Configure SQLite connection pointing to `App_Data` with EF Core migrations folder under `Data/`. +- [ ] Define domain models in `Domain/`: `Player`, `Suggestion`, `Vote`, `AppState`, `Phase` enum. +- [ ] Implement `AppDbContext` in `Data/` with DbSets and simple seeding of `AppState`. + +## Identity & Middleware +- [ ] Middleware to issue/read HttpOnly `player` cookie with Guid; SameSite=Strict; secure in production. +- [ ] Minimal API filters/helpers to resolve current player and ensure existence in DB. +- [ ] Global exception/validation handling and basic logging. + +## Phase Enforcement +- [ ] Store current phase in `AppState`; default to Suggest. +- [ ] Central guard ensuring endpoints respect allowed phase (server-side blindness, no client trust). + +## API Endpoints (see API.md) +- [ ] `GET /api/state` returns phase and counts. +- [ ] `GET /api/me` and `POST /api/me/name` to set display name. +- [ ] Suggestion endpoints: mine/create/all with per-player visibility rules. +- [ ] Vote endpoints: mine/create with per-player visibility and phase gating. +- [ ] Results endpoint aggregates totals and vote counts (optionally averages) sorted desc. +- [ ] Admin endpoints: switch phase, reset data; protect via env password. + +## Frontend (wwwroot) +- [ ] `index.html` shell with phase-driven sections. +- [ ] `app.js` API client, polling, and render functions per phase; enforce blindness in UI. +- [ ] `styles.css` basic responsive layout (desktop + mobile). + +## Persistence & Migrations +- [ ] Create initial EF Core migration for SQLite schema. +- [ ] Add startup migration application. + +## Testing & Quality +- [ ] Happy-path smoke test script (manual or minimal automated) for phase flow. +- [ ] Lint/format via `dotnet format` (optional) and ensure build succeeds. + +## Deployment +- [ ] Add minimal publish profile/notes for IIS (respect `ASPNETCORE_ENVIRONMENT`, admin password env var, writable App_Data). + +## Stretch (later) +- [ ] Support multiple sessions/rooms. +- [ ] Add rate limiting or spam safeguards.