cronekorkn/left4me
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
left4me/docs/superpowers/plans/2026-05-06-l4d2-web-ui.md
mwiegand d090750a50
docs(l4d2-web): plan functional web ui
2026-05-06 11:34:23 +02:00

1376 lines
48 KiB
Markdown
Raw Blame History

# L4D2 Web UI Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Implement the approved functional admin-console UI for `l4d2web` without changing the Flask/Jinja/HTMX/SSE architecture.
**Architecture:** Treat the current `l4d2web` implementation as a rough draft, not a compatibility boundary. Keep the Flask/Jinja/HTMX/SSE architecture, but replace routes, templates, CSS, JavaScript, and tests where needed to match the approved UI contract. Use tokenized CSS for neutral light/dark themes, standard HTML forms for CRUD and lifecycle actions, HTMX only for small partial updates, and SSE for log streams.
**Tech Stack:** Python 3.12+, Flask, SQLAlchemy, pytest, Jinja templates, vendored HTMX, vanilla JavaScript, custom CSS, SSE.
---
## File Structure
- `l4d2web/routes/page_routes.py`: GET pages for dashboard, servers, blueprints, overlays, server detail, blueprint detail, admin, users, and jobs.
- `l4d2web/routes/overlay_routes.py`: admin-only overlay create, update, and delete form handlers under `/overlays`.
- `l4d2web/routes/blueprint_routes.py`: standard form create/update/delete handlers for blueprints and ordered overlays. Keep JSON handling only if it remains useful and does not constrain the UI.
- `l4d2web/routes/server_routes.py`: standard form lifecycle action handlers that enqueue `Job` rows. Keep JSON handling only if it remains useful and does not constrain the UI.
- `l4d2web/templates/base.html`: shared shell, nav, account area, logout POST form, CSS/JS includes.
- `l4d2web/templates/dashboard.html`: simple landing text.
- `l4d2web/templates/servers.html`: server list table.
- `l4d2web/templates/server_detail.html`: server operations, metadata, blueprint summary, job log, and server log.
- `l4d2web/templates/blueprints.html`: blueprint list table and create form.
- `l4d2web/templates/blueprint_detail.html`: blueprint edit form with ordered overlays and textareas.
- `l4d2web/templates/overlays.html`: single overlay catalog page with admin-only edit controls.
- `l4d2web/templates/admin.html`: admin landing page.
- `l4d2web/templates/admin_users.html`: admin user list.
- `l4d2web/templates/admin_jobs.html`: admin job list.
- `l4d2web/static/css/tokens.css`: all color, spacing, line, radius, and light/dark variables.
- `l4d2web/static/css/layout.css`: page shell and layout primitives using tokens.
- `l4d2web/static/css/components.css`: tables, forms, buttons, status badges, and panels using tokens.
- `l4d2web/static/css/logs.css`: tokenized log panels.
- `l4d2web/static/js/sse.js`: unobtrusive SSE binding for log elements with `data-sse-url`.
- `l4d2web/tests/test_pages.py`: page, shell, nav, server, blueprint, and admin page tests.
- `l4d2web/tests/test_overlays.py`: overlay page and admin form tests.
- `l4d2web/tests/test_blueprints.py`: form-based blueprint creation/editing tests plus any retained JSON behavior.
- `l4d2web/tests/test_servers.py`: server form and lifecycle enqueue tests plus any retained JSON behavior.
- `AGENTS.md`: remove the stale fixed link-color contract.
- `docs/superpowers/plans/2026-04-23-l4d2-web-app-v1.md`: remove the stale fixed link-color contract.
The current web code and tests may be replaced instead of carefully preserved. When this plan says to append a test or modify a draft file, an implementer may rewrite the file if that is clearer and still satisfies the task tests and final suite.
### Task 1: Implement shell, tokens, and dashboard landing text
**Files:**
- Modify: `l4d2web/templates/base.html`
- Modify: `l4d2web/templates/dashboard.html`
- Modify: `l4d2web/static/css/tokens.css`
- Modify: `l4d2web/static/css/layout.css`
- Modify: `l4d2web/static/css/components.css`
- Modify: `l4d2web/static/css/logs.css`
- Test: `l4d2web/tests/test_pages.py`
- [ ] **Step 1: Add failing shell and dashboard tests**
Append these tests to `l4d2web/tests/test_pages.py`:
```python
def test_dashboard_is_simple_landing_page(auth_client_with_server) -> None:
response = auth_client_with_server.get("/dashboard")
text = response.get_data(as_text=True)
assert response.status_code == 200
assert "Dashboard" in text
assert "Use the navigation to manage servers, blueprints, and overlays." in text
assert "alpha" not in text
def test_shell_nav_uses_main_sections(auth_client_with_server) -> None:
response = auth_client_with_server.get("/dashboard")
text = response.get_data(as_text=True)
assert 'href="/dashboard"' in text
assert 'href="/servers"' in text
assert 'href="/blueprints"' in text
assert 'href="/overlays"' in text
assert 'action="/logout"' in text
assert "csrf_token" in text
def test_css_tokens_define_neutral_light_and_dark_theme() -> None:
css = Path("l4d2web/static/css/tokens.css").read_text()
for token in [
"--color-bg",
"--color-surface",
"--color-text",
"--color-muted",
"--color-border",
"--color-link",
"--space-base",
"--space-xs",
"--space-s",
"--space-m",
"--space-l",
"--space-xl",
"--space-2xl",
"--radius-s",
"--radius-m",
"--line",
]:
assert token in css
assert "prefers-color-scheme: dark" in css
assert "radial-gradient" not in Path("l4d2web/static/css/layout.css").read_text()
```
Also add the import at the top of `l4d2web/tests/test_pages.py`:
```python
from pathlib import Path
```
- [ ] **Step 2: Run tests and verify failure**
Run: `pytest l4d2web/tests/test_pages.py::test_dashboard_is_simple_landing_page l4d2web/tests/test_pages.py::test_shell_nav_uses_main_sections l4d2web/tests/test_pages.py::test_css_tokens_define_neutral_light_and_dark_theme -q`
Expected: FAIL because the dashboard still renders servers and the CSS tokens are not the approved neutral theme.
- [ ] **Step 3: Update base shell and dashboard**
Change `l4d2web/templates/base.html` to use this shell shape:
```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="csrf-token" content="{{ session.get('csrf_token', '') }}">
<title>{% block title %}left4me{% endblock %}</title>
<link rel="stylesheet" href="{{ url_for('static', filename='css/tokens.css') }}">
<link rel="stylesheet" href="{{ url_for('static', filename='css/layout.css') }}">
<link rel="stylesheet" href="{{ url_for('static', filename='css/components.css') }}">
<link rel="stylesheet" href="{{ url_for('static', filename='css/logs.css') }}">
</head>
<body>
<header class="site-header">
<div class="site-header-inner">
<nav class="primary-nav" aria-label="Main navigation">
<a class="brand" href="/dashboard">left4me</a>
<a href="/servers">servers</a>
<a href="/blueprints">blueprints</a>
<a href="/overlays">overlays</a>
</nav>
{% if g.user %}
<nav class="account-nav" aria-label="Account navigation">
{% if g.user.admin %}<a href="/admin">admin</a>{% endif %}
<span class="muted">{{ g.user.username }}</span>
<form method="post" action="/logout" class="inline-form">
<input type="hidden" name="csrf_token" value="{{ session.get('csrf_token', '') }}">
<button class="link-button" type="submit">logout</button>
</form>
</nav>
{% endif %}
</div>
</header>
<main class="container">
{% block content %}{% endblock %}
</main>
<script src="{{ url_for('static', filename='vendor/htmx.min.js') }}"></script>
<script src="{{ url_for('static', filename='js/csrf.js') }}"></script>
<script src="{{ url_for('static', filename='js/sse.js') }}"></script>
</body>
</html>
```
Change `l4d2web/templates/dashboard.html` to:
```html
{% extends "base.html" %}
{% block title %}Dashboard | left4me{% endblock %}
{% block content %}
<section class="panel">
<h1>Dashboard</h1>
<p class="muted">Use the navigation to manage servers, blueprints, and overlays.</p>
</section>
{% endblock %}
```
- [ ] **Step 4: Update CSS tokens and layout**
Replace `l4d2web/static/css/tokens.css` with:
```css
:root {
--color-bg: #f4f4f5;
--color-surface: #ffffff;
--color-surface-muted: #f8fafc;
--color-text: #18181b;
--color-muted: #60646c;
--color-border: #d4d4d8;
--color-link: #1d4ed8;
--color-primary: #1d4ed8;
--color-danger: #b42318;
--color-warning: #a15c07;
--color-success: #067647;
--color-focus: #2563eb;
--color-log-bg: #111827;
--color-log-text: #e5e7eb;
--space-base: 0.25rem;
--space-xs: var(--space-base);
--space-s: calc(var(--space-base) * 2);
--space-m: calc(var(--space-base) * 3);
--space-l: calc(var(--space-base) * 4);
--space-xl: calc(var(--space-base) * 6);
--space-2xl: calc(var(--space-base) * 8);
--radius-base: 0.25rem;
--radius-s: var(--radius-base);
--radius-m: calc(var(--radius-base) * 2);
--line: 1px solid var(--color-border);
}
@media (prefers-color-scheme: dark) {
:root {
--color-bg: #18181b;
--color-surface: #27272a;
--color-surface-muted: #1f1f23;
--color-text: #f4f4f5;
--color-muted: #a1a1aa;
--color-border: #3f3f46;
--color-link: #93c5fd;
--color-primary: #93c5fd;
--color-danger: #fca5a5;
--color-warning: #fcd34d;
--color-success: #86efac;
--color-focus: #bfdbfe;
}
}
a {
color: var(--color-link);
}
```
Update `layout.css`, `components.css`, and `logs.css` so all colors, spacing, borders, and radii reference tokens. Use `.panel` as the new neutral surface class and keep `.card` as an alias during migration:
```css
.panel,
.card {
background: var(--color-surface);
border: var(--line);
border-radius: var(--radius-m);
padding: var(--space-l);
margin-bottom: var(--space-l);
}
```
- [ ] **Step 5: Run tests and verify pass**
Run: `pytest l4d2web/tests/test_pages.py::test_dashboard_is_simple_landing_page l4d2web/tests/test_pages.py::test_shell_nav_uses_main_sections l4d2web/tests/test_pages.py::test_css_tokens_define_neutral_light_and_dark_theme -q`
Expected: PASS.
- [ ] **Step 6: Commit shell and token changes**
```bash
git add l4d2web/templates/base.html l4d2web/templates/dashboard.html l4d2web/static/css/tokens.css l4d2web/static/css/layout.css l4d2web/static/css/components.css l4d2web/static/css/logs.css l4d2web/tests/test_pages.py
git commit -m "feat(l4d2-web): add neutral shell and theme tokens"
```
### Task 2: Consolidate overlays into one authenticated page
**Files:**
- Modify: `l4d2web/routes/page_routes.py`
- Modify: `l4d2web/routes/overlay_routes.py`
- Create: `l4d2web/templates/overlays.html`
- Delete: `l4d2web/templates/admin_overlays.html`
- Test: `l4d2web/tests/test_overlays.py`
- [ ] **Step 1: Replace overlay tests with the single-page contract**
Update `l4d2web/tests/test_overlays.py` so it includes these tests:
```python
from l4d2web.models import Overlay, User
def test_user_can_view_overlay_catalog(user_client_with_overlay) -> None:
response = user_client_with_overlay.get("/overlays")
text = response.get_data(as_text=True)
assert response.status_code == 200
assert "standard" in text
assert "Add overlay" not in text
def test_admin_can_view_overlay_edit_controls(admin_client) -> None:
response = admin_client.get("/overlays")
text = response.get_data(as_text=True)
assert response.status_code == 200
assert "Add overlay" in text
assert 'action="/overlays"' in text
def test_admin_can_create_overlay(admin_client) -> None:
response = admin_client.post(
"/overlays",
data={"name": "standard", "path": "/opt/l4d2/overlays/standard"},
headers={"X-CSRF-Token": "test-token"},
)
assert response.status_code == 302
assert response.headers["Location"] == "/overlays"
def test_overlay_path_must_be_under_root(admin_client) -> None:
response = admin_client.post(
"/overlays",
data={"name": "bad", "path": "/tmp/bad"},
headers={"X-CSRF-Token": "test-token"},
)
assert response.status_code == 400
def test_non_admin_cannot_create_overlay(user_client_with_overlay) -> None:
response = user_client_with_overlay.post(
"/overlays",
data={"name": "bad", "path": "/opt/l4d2/overlays/bad"},
headers={"X-CSRF-Token": "test-token"},
)
assert response.status_code == 403
def test_admin_can_update_and_delete_overlay(admin_client) -> None:
create = admin_client.post(
"/overlays",
data={"name": "standard", "path": "/opt/l4d2/overlays/standard"},
headers={"X-CSRF-Token": "test-token"},
)
assert create.status_code == 302
update = admin_client.post(
"/overlays/1",
data={"name": "edited", "path": "/opt/l4d2/overlays/edited"},
headers={"X-CSRF-Token": "test-token"},
)
assert update.status_code == 302
delete = admin_client.post(
"/overlays/1/delete",
headers={"X-CSRF-Token": "test-token"},
)
assert delete.status_code == 302
```
Add a `user_client_with_overlay` fixture that creates a non-admin user and one overlay, sets `user_id`, and sets `csrf_token` to `test-token`.
- [ ] **Step 2: Run tests and verify failure**
Run: `pytest l4d2web/tests/test_overlays.py -q`
Expected: FAIL because the app still uses `/admin/overlays` and has no GET `/overlays` page.
- [ ] **Step 3: Move overlay form handlers to `/overlays`**
In `l4d2web/routes/overlay_routes.py`, replace the current create route and add update/delete routes:
```python
@bp.post("/overlays")
@require_admin
def create_overlay() -> Response:
name = request.form.get("name", "").strip()
raw_path = request.form.get("path", "").strip()
if not name or not raw_path:
return Response("missing fields", status=400)
try:
validated_path = validate_overlay_path(raw_path)
except ValueError as exc:
return Response(str(exc), status=400)
with session_scope() as db:
existing = db.scalar(select(Overlay).where(Overlay.name == name))
if existing is not None:
return Response("overlay already exists", status=409)
db.add(Overlay(name=name, path=str(validated_path)))
return redirect("/overlays")
@bp.post("/overlays/<int:overlay_id>")
@require_admin
def update_overlay(overlay_id: int) -> Response:
name = request.form.get("name", "").strip()
raw_path = request.form.get("path", "").strip()
if not name or not raw_path:
return Response("missing fields", status=400)
try:
validated_path = validate_overlay_path(raw_path)
except ValueError as exc:
return Response(str(exc), status=400)
with session_scope() as db:
overlay = db.scalar(select(Overlay).where(Overlay.id == overlay_id))
if overlay is None:
return Response(status=404)
overlay.name = name
overlay.path = str(validated_path)
return redirect("/overlays")
@bp.post("/overlays/<int:overlay_id>/delete")
@require_admin
def delete_overlay(overlay_id: int) -> Response:
with session_scope() as db:
overlay = db.scalar(select(Overlay).where(Overlay.id == overlay_id))
if overlay is None:
return Response(status=404)
db.delete(overlay)
return redirect("/overlays")
```
- [ ] **Step 4: Add the `/overlays` page and remove `/admin/overlays`**
In `l4d2web/routes/page_routes.py`, replace the `admin_overlays` route with:
```python
@bp.get("/overlays")
@require_login
def overlays() -> str:
with session_scope() as db:
overlays = db.scalars(select(Overlay).order_by(Overlay.name)).all()
return render_template("overlays.html", overlays=overlays)
```
Create `l4d2web/templates/overlays.html`:
```html
{% extends "base.html" %}
{% block title %}Overlays | left4me{% endblock %}
{% block content %}
<section class="panel">
<div class="page-heading">
<h1>Overlays</h1>
</div>
{% if g.user.admin %}
<form method="post" action="/overlays" class="stack form-panel">
<input type="hidden" name="csrf_token" value="{{ session.get('csrf_token', '') }}">
<label>Name <input name="name" required></label>
<label>Path <input name="path" required placeholder="/opt/l4d2/overlays/example"></label>
<button type="submit">Add overlay</button>
</form>
{% endif %}
<table class="table">
<thead><tr><th>Name</th><th>Path</th>{% if g.user.admin %}<th>Actions</th>{% endif %}</tr></thead>
<tbody>
{% for overlay in overlays %}
<tr>
<td>{{ overlay.name }}</td>
<td class="muted">{{ overlay.path }}</td>
{% if g.user.admin %}
<td>
<form method="post" action="/overlays/{{ overlay.id }}" class="inline-form">
<input type="hidden" name="csrf_token" value="{{ session.get('csrf_token', '') }}">
<input name="name" value="{{ overlay.name }}" required>
<input name="path" value="{{ overlay.path }}" required>
<button type="submit">Save</button>
</form>
<form method="post" action="/overlays/{{ overlay.id }}/delete" class="inline-form">
<input type="hidden" name="csrf_token" value="{{ session.get('csrf_token', '') }}">
<button class="danger" type="submit">Delete</button>
</form>
</td>
{% endif %}
</tr>
{% else %}
<tr><td colspan="{% if g.user.admin %}3{% else %}2{% endif %}" class="muted">No overlays configured.</td></tr>
{% endfor %}
</tbody>
</table>
</section>
{% endblock %}
```
Delete `l4d2web/templates/admin_overlays.html` after the new template is in place.
- [ ] **Step 5: Run tests and verify pass**
Run: `pytest l4d2web/tests/test_overlays.py -q`
Expected: PASS.
- [ ] **Step 6: Commit overlay consolidation**
```bash
git add l4d2web/routes/page_routes.py l4d2web/routes/overlay_routes.py l4d2web/templates/overlays.html l4d2web/tests/test_overlays.py
git rm l4d2web/templates/admin_overlays.html
git commit -m "feat(l4d2-web): consolidate overlay catalog page"
```
### Task 3: Add server list, server detail, and lifecycle form enqueueing
**Files:**
- Modify: `l4d2web/routes/page_routes.py`
- Modify: `l4d2web/routes/server_routes.py`
- Create: `l4d2web/templates/servers.html`
- Modify: `l4d2web/templates/server_detail.html`
- Modify: `l4d2web/static/js/sse.js`
- Test: `l4d2web/tests/test_pages.py`
- Test: `l4d2web/tests/test_servers.py`
- [ ] **Step 1: Add failing server page tests**
Append these tests to `l4d2web/tests/test_pages.py`:
```python
def test_servers_page_links_server_names(auth_client_with_server) -> None:
response = auth_client_with_server.get("/servers")
text = response.get_data(as_text=True)
assert response.status_code == 200
assert '<a href="/servers/1">alpha</a>' in text
assert "View" not in text
assert ">details<" not in text
def test_server_detail_shows_operations_and_logs(auth_client_with_server) -> None:
response = auth_client_with_server.get("/servers/1")
text = response.get_data(as_text=True)
assert response.status_code == 200
assert "Server: alpha" in text
assert 'action="/servers/1/start"' in text
assert 'action="/servers/1/stop"' in text
assert 'action="/servers/1/initialize"' in text
assert 'action="/servers/1/delete"' in text
assert 'href="/blueprints/1"' in text
assert 'data-sse-url="/servers/1/logs/stream"' in text
```
Append this test to `l4d2web/tests/test_servers.py`:
```python
def test_lifecycle_form_creates_queued_job(user_client_with_blueprints) -> None:
client, data = user_client_with_blueprints
create_response = client.post(
"/servers",
data=json.dumps({"name": "alpha", "port": 27015, "blueprint_id": data["blueprint_id"]}),
content_type="application/json",
headers={"X-CSRF-Token": "test-token"},
)
server_id = create_response.get_json()["id"]
response = client.post(
f"/servers/{server_id}/start",
headers={"X-CSRF-Token": "test-token"},
)
assert response.status_code == 302
assert response.headers["Location"] == f"/servers/{server_id}"
```
- [ ] **Step 2: Run tests and verify failure**
Run: `pytest l4d2web/tests/test_pages.py::test_servers_page_links_server_names l4d2web/tests/test_pages.py::test_server_detail_shows_operations_and_logs l4d2web/tests/test_servers.py::test_lifecycle_form_creates_queued_job -q`
Expected: FAIL because `/servers` has no GET page and lifecycle form routes do not exist.
- [ ] **Step 3: Add lifecycle form endpoint**
In `l4d2web/routes/server_routes.py`, import `redirect` and `Job`, then add:
```python
LIFECYCLE_OPERATIONS = {"initialize", "start", "stop", "delete"}
@bp.post("/servers/<int:server_id>/<operation>")
@require_login
def enqueue_server_operation(server_id: int, operation: str) -> Response:
user = current_user()
assert user is not None
if operation not in LIFECYCLE_OPERATIONS:
return Response(status=404)
with session_scope() as db:
server = db.scalar(select(Server).where(Server.id == server_id, Server.user_id == user.id))
if server is None:
return Response(status=404)
db.add(Job(user_id=user.id, server_id=server.id, operation=operation, state="queued"))
if operation == "start":
server.desired_state = "running"
if operation in {"stop", "delete"}:
server.desired_state = "stopped"
return redirect(f"/servers/{server_id}")
```
- [ ] **Step 4: Add server list and enrich server detail route**
In `l4d2web/routes/page_routes.py`, add imports for `Job` and `BlueprintOverlay`, then add:
```python
@bp.get("/servers")
@require_login
def servers_page() -> str:
user = current_user()
assert user is not None
with session_scope() as db:
rows = db.execute(
select(Server, BlueprintModel)
.join(BlueprintModel, BlueprintModel.id == Server.blueprint_id)
.where(Server.user_id == user.id)
.order_by(Server.name)
).all()
return render_template("servers.html", rows=rows)
```
Replace `server_detail` with a version that loads server, blueprint, ordered overlay names, decoded arguments/config, and the newest job:
```python
@bp.get("/servers/<int:server_id>")
@require_login
def server_detail(server_id: int):
user = current_user()
assert user is not None
with session_scope() as db:
server = db.scalar(select(Server).where(Server.id == server_id, Server.user_id == user.id))
if server is None:
return Response(status=404)
blueprint = db.scalar(select(BlueprintModel).where(BlueprintModel.id == server.blueprint_id))
overlay_rows = db.execute(
select(Overlay.name)
.join(BlueprintOverlay, BlueprintOverlay.overlay_id == Overlay.id)
.where(BlueprintOverlay.blueprint_id == server.blueprint_id)
.order_by(BlueprintOverlay.position)
).all()
latest_job = db.scalar(
select(Job)
.where(Job.server_id == server.id)
.order_by(Job.created_at.desc())
.limit(1)
)
return render_template(
"server_detail.html",
server=server,
blueprint=blueprint,
overlay_names=[row[0] for row in overlay_rows],
arguments=json.loads(blueprint.arguments) if blueprint is not None else [],
config_lines=json.loads(blueprint.config) if blueprint is not None else [],
latest_job=latest_job,
)
```
- [ ] **Step 5: Add server templates and generic SSE binding**
Create `l4d2web/templates/servers.html`:
```html
{% extends "base.html" %}
{% block title %}Servers | left4me{% endblock %}
{% block content %}
<section class="panel">
<h1>Servers</h1>
<table class="table">
<thead><tr><th>Name</th><th>Port</th><th>Blueprint</th><th>Desired</th><th>Actual</th></tr></thead>
<tbody>
{% for server, blueprint in rows %}
<tr>
<td><a href="/servers/{{ server.id }}">{{ server.name }}</a></td>
<td>{{ server.port }}</td>
<td><a href="/blueprints/{{ blueprint.id }}">{{ blueprint.name }}</a></td>
<td>{{ server.desired_state }}</td>
<td>{{ server.actual_state }}</td>
</tr>
{% else %}
<tr><td colspan="5" class="muted">No servers configured.</td></tr>
{% endfor %}
</tbody>
</table>
</section>
{% endblock %}
```
Replace `l4d2web/templates/server_detail.html` with:
```html
{% extends "base.html" %}
{% block title %}Server {{ server.name }} | left4me{% endblock %}
{% block content %}
<section class="panel">
<div class="page-heading">
<h1>Server: {{ server.name }}</h1>
<div class="button-row">
{% for operation in ["initialize", "start", "stop"] %}
<form method="post" action="/servers/{{ server.id }}/{{ operation }}" class="inline-form">
<input type="hidden" name="csrf_token" value="{{ session.get('csrf_token', '') }}">
<button type="submit">{{ operation }}</button>
</form>
{% endfor %}
<form method="post" action="/servers/{{ server.id }}/delete" class="inline-form">
<input type="hidden" name="csrf_token" value="{{ session.get('csrf_token', '') }}">
<button class="danger" type="submit">delete</button>
</form>
</div>
</div>
<table class="definition-table">
<tbody>
<tr><th>Name</th><td>{{ server.name }}</td></tr>
<tr><th>Port</th><td>{{ server.port }}</td></tr>
<tr><th>Blueprint</th><td>{% if blueprint %}<a href="/blueprints/{{ blueprint.id }}">{{ blueprint.name }}</a>{% endif %}</td></tr>
<tr><th>Desired state</th><td>{{ server.desired_state }}</td></tr>
<tr><th>Actual state</th><td>{{ server.actual_state }}</td></tr>
<tr><th>Last error</th><td>{{ server.last_error or "-" }}</td></tr>
</tbody>
</table>
</section>
<section class="panel">
<h2>Blueprint</h2>
<h3>Overlay order</h3>
<ol>
{% for name in overlay_names %}<li>{{ name }}</li>{% else %}<li class="muted">No overlays configured.</li>{% endfor %}
</ol>
<h3>Arguments</h3>
<pre class="code-block">{{ arguments | join('\n') }}</pre>
<h3>Config</h3>
<pre class="code-block">{{ config_lines | join('\n') }}</pre>
</section>
<section class="panel">
<h2>Current / Recent Job</h2>
{% if latest_job %}
<table class="definition-table"><tbody><tr><th>Operation</th><td>{{ latest_job.operation }}</td></tr><tr><th>State</th><td>{{ latest_job.state }}</td></tr></tbody></table>
<pre class="log-stream" data-sse-url="/jobs/{{ latest_job.id }}/stream"></pre>
{% else %}
<p class="muted">No jobs have run for this server.</p>
{% endif %}
</section>
<section class="panel">
<h2>Server Log</h2>
<pre class="log-stream" data-sse-url="/servers/{{ server.id }}/logs/stream"></pre>
</section>
{% endblock %}
```
Update `l4d2web/static/js/sse.js` so it binds every element with `data-sse-url`:
```javascript
function streamTextToElement(element) {
const url = element.dataset.sseUrl;
if (!url) {
return;
}
const source = new EventSource(url);
source.onmessage = (event) => {
element.textContent += `${event.data}\n`;
element.scrollTop = element.scrollHeight;
};
}
document.addEventListener("DOMContentLoaded", () => {
document.querySelectorAll("[data-sse-url]").forEach(streamTextToElement);
});
```
- [ ] **Step 6: Run tests and verify pass**
Run: `pytest l4d2web/tests/test_pages.py::test_servers_page_links_server_names l4d2web/tests/test_pages.py::test_server_detail_shows_operations_and_logs l4d2web/tests/test_servers.py::test_lifecycle_form_creates_queued_job -q`
Expected: PASS.
- [ ] **Step 7: Commit server pages**
```bash
git add l4d2web/routes/page_routes.py l4d2web/routes/server_routes.py l4d2web/templates/servers.html l4d2web/templates/server_detail.html l4d2web/static/js/sse.js l4d2web/tests/test_pages.py l4d2web/tests/test_servers.py
git commit -m "feat(l4d2-web): add server pages and lifecycle forms"
```
### Task 4: Add blueprint list and form-based ordered overlay editing
**Files:**
- Modify: `l4d2web/routes/page_routes.py`
- Modify: `l4d2web/routes/blueprint_routes.py`
- Modify: `l4d2web/templates/blueprints.html`
- Create: `l4d2web/templates/blueprint_detail.html`
- Test: `l4d2web/tests/test_pages.py`
- Test: `l4d2web/tests/test_blueprints.py`
- [ ] **Step 1: Add failing blueprint page and form tests**
Append these tests to `l4d2web/tests/test_pages.py`:
```python
def test_blueprint_pages_fixture_has_ordered_overlay_data(auth_client_with_server) -> None:
response = auth_client_with_server.get("/blueprints/1")
text = response.get_data(as_text=True)
assert response.status_code == 200
assert "standard" in text
def test_blueprints_page_links_blueprint_names(auth_client_with_server) -> None:
response = auth_client_with_server.get("/blueprints")
text = response.get_data(as_text=True)
assert response.status_code == 200
assert '<a href="/blueprints/1">default</a>' in text
assert "View" not in text
def test_blueprint_detail_has_ordered_overlay_form(auth_client_with_server) -> None:
response = auth_client_with_server.get("/blueprints/1")
text = response.get_data(as_text=True)
assert response.status_code == 200
assert "Overlay order matters" in text
assert 'name="arguments"' in text
assert 'name="config"' in text
assert 'name="overlay_ids"' in text
assert 'name="overlay_position_1"' in text
```
Update the `auth_client_with_server` fixture in `l4d2web/tests/test_pages.py` so it imports `BlueprintOverlay` and `Overlay`, creates one overlay named `standard`, and links it to blueprint `default` with position `0`.
Append this test to `l4d2web/tests/test_blueprints.py`:
```python
def test_form_update_preserves_ordered_overlays_and_multiline_fields(user_client) -> None:
create = user_client.post(
"/blueprints",
data={
"name": "comp",
"arguments": "-tickrate 100",
"config": "sv_consistency 1",
"overlay_ids": ["2", "1"],
"overlay_position_1": "2",
"overlay_position_2": "1",
},
headers={"X-CSRF-Token": "test-token"},
)
assert create.status_code == 302
update = user_client.post(
"/blueprints/1",
data={
"name": "edited",
"arguments": "-tickrate 100\n+sv_lan 0",
"config": "sv_consistency 1\nsv_allow_lobby_connect_only 0",
"overlay_ids": ["1", "2"],
"overlay_position_1": "1",
"overlay_position_2": "2",
},
headers={"X-CSRF-Token": "test-token"},
)
assert update.status_code == 302
assert update.headers["Location"] == "/blueprints/1"
```
- [ ] **Step 2: Run tests and verify failure**
Run: `pytest l4d2web/tests/test_pages.py::test_blueprint_pages_fixture_has_ordered_overlay_data l4d2web/tests/test_pages.py::test_blueprints_page_links_blueprint_names l4d2web/tests/test_pages.py::test_blueprint_detail_has_ordered_overlay_form l4d2web/tests/test_blueprints.py::test_form_update_preserves_ordered_overlays_and_multiline_fields -q`
Expected: FAIL because `/blueprints` has no GET page and the blueprint routes accept JSON only.
- [ ] **Step 3: Add form helpers to blueprint routes**
In `l4d2web/routes/blueprint_routes.py`, add helpers:
```python
def split_textarea_lines(raw: str) -> list[str]:
return [line.strip() for line in raw.splitlines() if line.strip()]
def ordered_overlay_ids_from_form() -> list[int]:
ordered = []
for fallback_position, value in enumerate(request.form.getlist("overlay_ids")):
if not value:
continue
overlay_id = int(value)
raw_position = request.form.get(f"overlay_position_{overlay_id}", "").strip()
try:
position = int(raw_position)
except ValueError:
position = fallback_position + 1
ordered.append((position, fallback_position, overlay_id))
return [overlay_id for _, _, overlay_id in sorted(ordered)]
def replace_blueprint_overlays(db, blueprint_id: int, overlay_ids: list[int]) -> None:
db.execute(delete(BlueprintOverlay).where(BlueprintOverlay.blueprint_id == blueprint_id))
for position, overlay_id in enumerate(overlay_ids):
db.add(BlueprintOverlay(blueprint_id=blueprint_id, overlay_id=overlay_id, position=position))
```
- [ ] **Step 4: Support form creates and retain JSON only if useful**
Change `create_blueprint` so form requests redirect to the new detail page. The implementation below also keeps JSON requests returning `201` because the draft tests already cover that path, but JSON support is not a UI compatibility requirement:
```python
@bp.post("/blueprints")
@require_login
def create_blueprint() -> Response:
user = current_user()
assert user is not None
if request.is_json:
payload = request.get_json(silent=True) or {}
name = str(payload.get("name", "")).strip()
arguments = [str(item) for item in payload.get("arguments", [])]
config = [str(item) for item in payload.get("config", [])]
overlay_ids = [int(item) for item in payload.get("overlay_ids", [])]
json_response = True
else:
name = request.form.get("name", "").strip()
arguments = split_textarea_lines(request.form.get("arguments", ""))
config = split_textarea_lines(request.form.get("config", ""))
overlay_ids = ordered_overlay_ids_from_form()
json_response = False
if not name:
return Response("name is required", status=400)
with session_scope() as db:
blueprint = BlueprintModel(user_id=user.id, name=name, arguments=json.dumps(arguments), config=json.dumps(config))
db.add(blueprint)
db.flush()
replace_blueprint_overlays(db, blueprint.id, overlay_ids)
blueprint_id = blueprint.id
if json_response:
return jsonify({"id": blueprint_id}), 201
return redirect(f"/blueprints/{blueprint_id}")
```
- [ ] **Step 5: Add form update route for blueprint details**
Add this route to `l4d2web/routes/blueprint_routes.py`:
```python
@bp.post("/blueprints/<int:blueprint_id>")
@require_login
def update_blueprint_form(blueprint_id: int) -> Response:
user = current_user()
assert user is not None
name = request.form.get("name", "").strip()
if not name:
return Response("name is required", status=400)
with session_scope() as db:
blueprint = db.scalar(
select(BlueprintModel).where(BlueprintModel.id == blueprint_id, BlueprintModel.user_id == user.id)
)
if blueprint is None:
return Response(status=404)
blueprint.name = name
blueprint.arguments = json.dumps(split_textarea_lines(request.form.get("arguments", "")))
blueprint.config = json.dumps(split_textarea_lines(request.form.get("config", "")))
replace_blueprint_overlays(db, blueprint.id, ordered_overlay_ids_from_form())
return redirect(f"/blueprints/{blueprint_id}")
```
- [ ] **Step 6: Add blueprint list route and detail data**
In `l4d2web/routes/page_routes.py`, add a `/blueprints` route:
```python
@bp.get("/blueprints")
@require_login
def blueprints_page() -> str:
user = current_user()
assert user is not None
with session_scope() as db:
blueprints = db.scalars(
select(BlueprintModel).where(BlueprintModel.user_id == user.id).order_by(BlueprintModel.name)
).all()
return render_template("blueprints.html", blueprints=blueprints)
```
Replace the existing `blueprint_page` render logic with:
```python
@bp.get("/blueprints/<int:blueprint_id>")
@require_login
def blueprint_page(blueprint_id: int):
user = current_user()
assert user is not None
with session_scope() as db:
blueprint = db.scalar(select(BlueprintModel).where(BlueprintModel.id == blueprint_id))
if blueprint is None:
return Response(status=404)
if blueprint.user_id != user.id:
return Response(status=403)
selected_overlays = db.scalars(
select(Overlay)
.join(BlueprintOverlay, BlueprintOverlay.overlay_id == Overlay.id)
.where(BlueprintOverlay.blueprint_id == blueprint.id)
.order_by(BlueprintOverlay.position)
).all()
position_rows = db.execute(
select(BlueprintOverlay.overlay_id, BlueprintOverlay.position)
.where(BlueprintOverlay.blueprint_id == blueprint.id)
).all()
all_overlays = db.scalars(select(Overlay).order_by(Overlay.name)).all()
overlay_positions = {overlay_id: position + 1 for overlay_id, position in position_rows}
return render_template(
"blueprint_detail.html",
blueprint=blueprint,
selected_overlays=selected_overlays,
all_overlays=all_overlays,
selected_overlay_ids={overlay.id for overlay in selected_overlays},
overlay_positions=overlay_positions,
arguments=json.loads(blueprint.arguments),
config_lines=json.loads(blueprint.config),
)
```
- [ ] **Step 7: Create blueprint templates**
Replace `l4d2web/templates/blueprints.html` with:
```html
{% extends "base.html" %}
{% block title %}Blueprints | left4me{% endblock %}
{% block content %}
<section class="panel">
<h1>Blueprints</h1>
<form method="post" action="/blueprints" class="stack form-panel">
<input type="hidden" name="csrf_token" value="{{ session.get('csrf_token', '') }}">
<label>Name <input name="name" required></label>
<label>Arguments <textarea name="arguments"></textarea></label>
<label>Config <textarea name="config"></textarea></label>
<button type="submit">Create blueprint</button>
</form>
<table class="table">
<thead><tr><th>Name</th><th>Created</th><th>Updated</th><th>Actions</th></tr></thead>
<tbody>
{% for blueprint in blueprints %}
<tr>
<td><a href="/blueprints/{{ blueprint.id }}">{{ blueprint.name }}</a></td>
<td>{{ blueprint.created_at }}</td>
<td>{{ blueprint.updated_at }}</td>
<td>
<form method="post" action="/blueprints/{{ blueprint.id }}/delete" class="inline-form">
<input type="hidden" name="csrf_token" value="{{ session.get('csrf_token', '') }}">
<button class="danger" type="submit">Delete</button>
</form>
</td>
</tr>
{% else %}
<tr><td colspan="4" class="muted">No blueprints configured.</td></tr>
{% endfor %}
</tbody>
</table>
</section>
{% endblock %}
```
Create `l4d2web/templates/blueprint_detail.html` with:
```html
{% extends "base.html" %}
{% block title %}Blueprint {{ blueprint.name }} | left4me{% endblock %}
{% block content %}
<section class="panel">
<h1>Blueprint: {{ blueprint.name }}</h1>
<form method="post" action="/blueprints/{{ blueprint.id }}" class="stack">
<input type="hidden" name="csrf_token" value="{{ session.get('csrf_token', '') }}">
<label>Name <input name="name" value="{{ blueprint.name }}" required></label>
<p class="muted">Overlay order matters: the first overlay has highest precedence.</p>
<table class="table">
<thead><tr><th>Use</th><th>Order</th><th>Overlay</th></tr></thead>
<tbody>
{% for overlay in all_overlays %}
<tr>
<td><input type="checkbox" name="overlay_ids" value="{{ overlay.id }}" {% if overlay.id in selected_overlay_ids %}checked{% endif %}></td>
<td><input class="position-input" name="overlay_position_{{ overlay.id }}" value="{{ overlay_positions.get(overlay.id, '') }}" inputmode="numeric"></td>
<td>{{ overlay.name }}</td>
</tr>
{% else %}
<tr><td colspan="3" class="muted">No overlays available.</td></tr>
{% endfor %}
</tbody>
</table>
<label>Arguments <textarea name="arguments">{{ arguments | join('\n') }}</textarea></label>
<label>Config <textarea name="config">{{ config_lines | join('\n') }}</textarea></label>
<button type="submit">Save blueprint</button>
</form>
</section>
{% endblock %}
```
- [ ] **Step 8: Run tests and verify pass**
Run: `pytest l4d2web/tests/test_pages.py::test_blueprint_pages_fixture_has_ordered_overlay_data l4d2web/tests/test_pages.py::test_blueprints_page_links_blueprint_names l4d2web/tests/test_pages.py::test_blueprint_detail_has_ordered_overlay_form l4d2web/tests/test_blueprints.py::test_form_update_preserves_ordered_overlays_and_multiline_fields -q`
Expected: PASS.
- [ ] **Step 9: Commit blueprint pages**
```bash
git add l4d2web/routes/page_routes.py l4d2web/routes/blueprint_routes.py l4d2web/templates/blueprints.html l4d2web/templates/blueprint_detail.html l4d2web/tests/test_pages.py l4d2web/tests/test_blueprints.py
git commit -m "feat(l4d2-web): add form-based blueprint editor"
```
### Task 5: Add admin landing, users, and jobs pages
**Files:**
- Modify: `l4d2web/routes/page_routes.py`
- Create: `l4d2web/templates/admin.html`
- Create: `l4d2web/templates/admin_users.html`
- Create: `l4d2web/templates/admin_jobs.html`
- Test: `l4d2web/tests/test_pages.py`
- [ ] **Step 1: Add failing admin page tests**
Append these tests to `l4d2web/tests/test_pages.py`:
```python
def test_non_admin_does_not_see_admin_nav(auth_client_with_server) -> None:
response = auth_client_with_server.get("/dashboard")
text = response.get_data(as_text=True)
assert response.status_code == 200
assert 'href="/admin"' not in text
def test_admin_can_use_admin_pages(tmp_path, monkeypatch) -> None:
db_url = f"sqlite:///{tmp_path/'admin-pages.db'}"
monkeypatch.setenv("DATABASE_URL", db_url)
app = create_app({"TESTING": True, "DATABASE_URL": db_url, "SECRET_KEY": "test"})
init_db()
with session_scope() as session:
admin = User(username="admin", password_digest=hash_password("secret"), admin=True)
session.add(admin)
session.flush()
admin_id = admin.id
client = app.test_client()
with client.session_transaction() as sess:
sess["user_id"] = admin_id
assert client.get("/admin").status_code == 200
assert client.get("/admin/users").status_code == 200
assert client.get("/admin/jobs").status_code == 200
assert 'href="/admin"' in client.get("/dashboard").get_data(as_text=True)
def test_non_admin_cannot_open_admin_pages(auth_client_with_server) -> None:
assert auth_client_with_server.get("/admin").status_code == 403
assert auth_client_with_server.get("/admin/users").status_code == 403
assert auth_client_with_server.get("/admin/jobs").status_code == 403
```
- [ ] **Step 2: Run tests and verify failure**
Run: `pytest l4d2web/tests/test_pages.py::test_non_admin_does_not_see_admin_nav l4d2web/tests/test_pages.py::test_admin_can_use_admin_pages l4d2web/tests/test_pages.py::test_non_admin_cannot_open_admin_pages -q`
Expected: FAIL because the admin pages do not exist.
- [ ] **Step 3: Add admin page routes**
In `l4d2web/routes/page_routes.py`, add imports for `User` and `Job`, then add:
```python
@bp.get("/admin")
@require_admin
def admin_home() -> str:
return render_template("admin.html")
@bp.get("/admin/users")
@require_admin
def admin_users() -> str:
with session_scope() as db:
users = db.scalars(select(User).order_by(User.username)).all()
return render_template("admin_users.html", users=users)
@bp.get("/admin/jobs")
@require_admin
def admin_jobs() -> str:
with session_scope() as db:
rows = db.execute(
select(Job, User, Server)
.join(User, User.id == Job.user_id)
.outerjoin(Server, Server.id == Job.server_id)
.order_by(Job.created_at.desc())
).all()
return render_template("admin_jobs.html", rows=rows)
```
- [ ] **Step 4: Add admin templates**
Create `l4d2web/templates/admin.html`:
```html
{% extends "base.html" %}
{% block title %}Admin | left4me{% endblock %}
{% block content %}
<section class="panel">
<h1>Admin</h1>
<ul class="link-list">
<li><a href="/admin/users">Users</a></li>
<li><a href="/admin/jobs">Jobs</a></li>
</ul>
</section>
{% endblock %}
```
Create `l4d2web/templates/admin_users.html`:
```html
{% extends "base.html" %}
{% block title %}Admin Users | left4me{% endblock %}
{% block content %}
<section class="panel">
<h1>Users</h1>
<table class="table">
<thead><tr><th>Username</th><th>Admin</th><th>Created</th><th>Updated</th></tr></thead>
<tbody>
{% for user in users %}
<tr><td>{{ user.username }}</td><td>{{ "yes" if user.admin else "no" }}</td><td>{{ user.created_at }}</td><td>{{ user.updated_at }}</td></tr>
{% else %}
<tr><td colspan="4" class="muted">No users found.</td></tr>
{% endfor %}
</tbody>
</table>
</section>
{% endblock %}
```
Create `l4d2web/templates/admin_jobs.html`:
```html
{% extends "base.html" %}
{% block title %}Admin Jobs | left4me{% endblock %}
{% block content %}
<section class="panel">
<h1>Jobs</h1>
<table class="table">
<thead><tr><th>ID</th><th>Operation</th><th>State</th><th>User</th><th>Server</th><th>Created</th><th>Finished</th></tr></thead>
<tbody>
{% for job, user, server in rows %}
<tr>
<td>{{ job.id }}</td>
<td>{{ job.operation }}</td>
<td>{{ job.state }}</td>
<td>{{ user.username }}</td>
<td>{% if server %}<a href="/servers/{{ server.id }}">{{ server.name }}</a>{% else %}-{% endif %}</td>
<td>{{ job.created_at }}</td>
<td>{{ job.finished_at or "-" }}</td>
</tr>
{% else %}
<tr><td colspan="7" class="muted">No jobs found.</td></tr>
{% endfor %}
</tbody>
</table>
</section>
{% endblock %}
```
- [ ] **Step 5: Run tests and verify pass**
Run: `pytest l4d2web/tests/test_pages.py::test_non_admin_does_not_see_admin_nav l4d2web/tests/test_pages.py::test_admin_can_use_admin_pages l4d2web/tests/test_pages.py::test_non_admin_cannot_open_admin_pages -q`
Expected: PASS.
- [ ] **Step 6: Commit admin pages**
```bash
git add l4d2web/routes/page_routes.py l4d2web/templates/admin.html l4d2web/templates/admin_users.html l4d2web/templates/admin_jobs.html l4d2web/tests/test_pages.py
git commit -m "feat(l4d2-web): add admin landing and system pages"
```
### Task 6: Update stale color-contract docs and run full web test suite
**Files:**
- Modify: `AGENTS.md`
- Modify: `docs/superpowers/plans/2026-04-23-l4d2-web-app-v1.md`
- Test: `l4d2web/tests/*.py`
- [ ] **Step 1: Update stale fixed-link-color wording**
In `AGENTS.md`, replace:
```markdown
- Custom CSS with consistent link color `#0F766E`.
```
with:
```markdown
- Custom CSS with tokenized, consistent link and accent colors.
```
In `docs/superpowers/plans/2026-04-23-l4d2-web-app-v1.md`, replace:
```markdown
- consistent link color `#0F766E`
```
with:
```markdown
- tokenized, consistent link and accent colors
```
Also update the sample CSS token in that plan from `--color-link: #0F766E;` to:
```css
--color-link: var(--color-primary);
```
- [ ] **Step 2: Verify stale exact color contract is gone from active guidance**
Run: `rg '#0F766E|0F766E' AGENTS.md docs/superpowers/plans/2026-04-23-l4d2-web-app-v1.md l4d2web/static/css`
Expected: no matches.
- [ ] **Step 3: Run the focused UI test files**
Run: `pytest l4d2web/tests/test_pages.py l4d2web/tests/test_overlays.py l4d2web/tests/test_blueprints.py l4d2web/tests/test_servers.py -q`
Expected: PASS.
- [ ] **Step 4: Run the full web test suite**
Run: `pytest l4d2web/tests -q`
Expected: PASS.
- [ ] **Step 5: Commit docs and final verification updates**
```bash
git add AGENTS.md docs/superpowers/plans/2026-04-23-l4d2-web-app-v1.md
git commit -m "docs(l4d2-web): update ui color contract"
```
---
## Self-Review
- [ ] Spec coverage: shell, dashboard landing text, single overlay page, linked table names, blueprint ordered overlays, server detail page, admin pages, standard forms, SSE logs, no WebSockets, neutral light/dark tokens.
- [ ] No external frontend dependencies are introduced.
- [ ] No inline JavaScript is introduced.
- [ ] Draft JSON route tests are either intentionally retained or replaced by form-based tests.
- [ ] Access rules are covered for normal users and admins.
- [ ] Docs are updated to remove the fixed `#0F766E` contract.
- [ ] Final verification command is `pytest l4d2web/tests -q`.
Reference in a new issue View git blame Copy permalink