meadows-web 0.1.0__tar.gz

meadows_web-0.1.0/.env.example

@@ -0,0 +1,13 @@
+# Meadows web host: bind address and port (Traefik terminates TLS in front of this)
+MEADOWS_WEB_HOST=0.0.0.0
+MEADOWS_WEB_PORT=8081
+
+# URL of meadows-server the browser Socket.IO client connects to (injected into index.html)
+MEADOWS_SERVER_URL=http://localhost:8080
+
+# Display name shown in the chat UI
+MEADOWS_SYSTEM_NAME=MEADOWS Chat
+
+# Traefik routing (see docker-compose.yml labels)
+PROJECT=meadows
+HOSTINGDOMAIN=localhost

meadows_web-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+
+# edwh / template
+.env
+.toml
+
+# OS / editors
+*.swp
+*.bak
+.DS_Store

meadows_web-0.1.0/Dockerfile

@@ -0,0 +1,9 @@
+FROM python:3.13-slim
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+WORKDIR /app
+COPY pyproject.toml .
+COPY src/ ./src/
+COPY README.md .
+RUN uv pip install --system --no-cache .
+EXPOSE 8081
+CMD ["python", "-m", "meadows.web"]

meadows_web-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.5
+Name: meadows-web
+Version: 0.1.0
+Summary: MEADOWS web host: serves index.html and static assets. Dumb HTTP host, no domain logic.
+Author: MEADOWS
+Requires-Python: >=3.12
+Requires-Dist: meadows-protocol
+Requires-Dist: starlette>=0.37.0
+Requires-Dist: uvicorn>=0.30.0
+Provides-Extra: dev
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff==0.14.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# meadows-web
+
+> MEADOWS web host: a dumb HTTP host that serves `index.html` and static assets.
+> No Socket.IO, no auth, no domain logic. The browser is the client; the
+> Socket.IO connection runs browser→meadows-server, NOT via this Python webserver.
+> See `MEADOWS-migration-intent.md` section 2 line 40 and section 4 line 115.
+
+## Architecture
+
+```mermaid
+graph LR
+    B[Browser<br>JS] -->|Socket.IO| S[meadows-server<br>:8080]
+    B -->|HTTP| W[meadows-web<br>:8081]
+    W -.->|static files only| B
+```
+
+The browser connects directly to `meadows-server` via Socket.IO. This Python server is just a file host.
+
+## What this package contains
+
+- `app.py` — the Starlette ASGI app. Serves `/` → `dist/index.html` and `/static/*` → assets. Nothing else.
+- `build.py` — template injection: reads `templates/index.html`, injects protocol constants + env config, writes `dist/index.html`.
+- `templates/index.html` — minimal webchat page (Socket.IO client in the browser).
+- `__main__.py` — `python -m meadows.web` entrypoint (uvicorn).
+
+## Install
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+This pulls in `meadows-protocol` (editable, via the sibling path) — the **only** MEADOWS dependency. The web host touches `meadows.protocol` solely to inject `EventName` constants into the template. It does **not** import `Message`, `JWTClaims`, or any domain model.
+
+## Build the template
+
+```bash
+uv run python -m meadows.web.build
+```
+
+## Run
+
+```bash
+uv run python -m meadows.web
+# or
+uv run uvicorn meadows.web.app:app --host 0.0.0.0 --port 8081
+```
+
+## Test
+
+```bash
+uv run pytest -q
+```
+
+## Architecture invariants
+
+1. **Dumb host.** No Socket.IO, no auth, no JWT, no message parsing. It serves files. Period.
+2. **TLS is not a concern.** Traefik terminates TLS (section 4 line 115). No cert logic here.
+3. **Protocol constants only.** The only import from `meadows.protocol` is `EventName` (for template injection).
+4. **PEP 420 namespace.** `src/meadows/web/__init__.py` exists; there is NO `src/meadows/__init__.py`.
+
+## Configuration (env vars, managed via `check_env` in `tasks.py:setup`)
+
+| variable | default | purpose |
+|---|---|---|
+| `MEADOWS_WEB_HOST` | `0.0.0.0` | bind address for uvicorn |
+| `MEADOWS_WEB_PORT` | `8081` | bind port for uvicorn |
+| `MEADOWS_SERVER_URL` | `http://localhost:8080` | server URL injected into the page (browser Socket.IO target) |
+| `MEADOWS_SYSTEM_NAME` | `MEADOWS Chat` | display name injected into the page |
+| `PROJECT` | `meadows` | Traefik router prefix |
+| `HOSTINGDOMAIN` | `localhost` | Traefik host domain |

meadows_web-0.1.0/README.md

@@ -0,0 +1,70 @@
+# meadows-web
+
+> MEADOWS web host: a dumb HTTP host that serves `index.html` and static assets.
+> No Socket.IO, no auth, no domain logic. The browser is the client; the
+> Socket.IO connection runs browser→meadows-server, NOT via this Python webserver.
+> See `MEADOWS-migration-intent.md` section 2 line 40 and section 4 line 115.
+
+## Architecture
+
+```mermaid
+graph LR
+    B[Browser<br>JS] -->|Socket.IO| S[meadows-server<br>:8080]
+    B -->|HTTP| W[meadows-web<br>:8081]
+    W -.->|static files only| B
+```
+
+The browser connects directly to `meadows-server` via Socket.IO. This Python server is just a file host.
+
+## What this package contains
+
+- `app.py` — the Starlette ASGI app. Serves `/` → `dist/index.html` and `/static/*` → assets. Nothing else.
+- `build.py` — template injection: reads `templates/index.html`, injects protocol constants + env config, writes `dist/index.html`.
+- `templates/index.html` — minimal webchat page (Socket.IO client in the browser).
+- `__main__.py` — `python -m meadows.web` entrypoint (uvicorn).
+
+## Install
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+This pulls in `meadows-protocol` (editable, via the sibling path) — the **only** MEADOWS dependency. The web host touches `meadows.protocol` solely to inject `EventName` constants into the template. It does **not** import `Message`, `JWTClaims`, or any domain model.
+
+## Build the template
+
+```bash
+uv run python -m meadows.web.build
+```
+
+## Run
+
+```bash
+uv run python -m meadows.web
+# or
+uv run uvicorn meadows.web.app:app --host 0.0.0.0 --port 8081
+```
+
+## Test
+
+```bash
+uv run pytest -q
+```
+
+## Architecture invariants
+
+1. **Dumb host.** No Socket.IO, no auth, no JWT, no message parsing. It serves files. Period.
+2. **TLS is not a concern.** Traefik terminates TLS (section 4 line 115). No cert logic here.
+3. **Protocol constants only.** The only import from `meadows.protocol` is `EventName` (for template injection).
+4. **PEP 420 namespace.** `src/meadows/web/__init__.py` exists; there is NO `src/meadows/__init__.py`.
+
+## Configuration (env vars, managed via `check_env` in `tasks.py:setup`)
+
+| variable | default | purpose |
+|---|---|---|
+| `MEADOWS_WEB_HOST` | `0.0.0.0` | bind address for uvicorn |
+| `MEADOWS_WEB_PORT` | `8081` | bind port for uvicorn |
+| `MEADOWS_SERVER_URL` | `http://localhost:8080` | server URL injected into the page (browser Socket.IO target) |
+| `MEADOWS_SYSTEM_NAME` | `MEADOWS Chat` | display name injected into the page |
+| `PROJECT` | `meadows` | Traefik router prefix |
+| `HOSTINGDOMAIN` | `localhost` | Traefik host domain |

meadows_web-0.1.0/captain-hooks/backup_files.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Restic file backup (template convention).
+# $HOST, $URI, $SNAPSHOT are provided by the edwh restic plugin at runtime.
+restic $HOST -r $URI backup ./backups --tag files 2>/dev/null || true

meadows_web-0.1.0/captain-hooks/restore_files.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Restic file restore (template convention).
+# $HOST, $URI, $SNAPSHOT are provided by the edwh restic plugin at runtime.
+restic $HOST -r $URI restore $SNAPSHOT --target ./ 2>/dev/null || true

meadows_web-0.1.0/docker-compose.yml

@@ -0,0 +1,35 @@
+networks:
+  meadows:
+    driver: bridge
+  broker:
+    external: true
+    name: broker
+
+services:
+  meadows-web:
+    build: .
+    image: meadows-web:latest
+    restart: unless-stopped
+    environment:
+      - MEADOWS_WEB_HOST=${MEADOWS_WEB_HOST:-0.0.0.0}
+      - MEADOWS_WEB_PORT=${MEADOWS_WEB_PORT:-8081}
+      - MEADOWS_SERVER_URL=${MEADOWS_SERVER_URL:-http://localhost:8080}
+      - MEADOWS_SYSTEM_NAME=${MEADOWS_SYSTEM_NAME:-MEADOWS Chat}
+      - PROJECT=${PROJECT:-meadows}
+      - HOSTINGDOMAIN=${HOSTINGDOMAIN:-localhost}
+    networks:
+      - meadows
+      - broker
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "100m"
+        max-file: "5"
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.${PROJECT:-meadows}-meadows-web-secure.rule=Host(`${ROUTER_HOST:-chat.${HOSTINGDOMAIN:-localhost}}`)"
+      - "traefik.http.routers.${PROJECT:-meadows}-meadows-web-secure.tls=true"
+      - "traefik.http.routers.${PROJECT:-meadows}-meadows-web-secure.entrypoints=web-secured"
+      - "traefik.http.routers.${PROJECT:-meadows}-meadows-web-secure.tls.certresolver=letsencrypt"
+      - "traefik.http.services.${PROJECT:-meadows}-meadows-web.loadbalancer.server.port=${MEADOWS_WEB_PORT:-8081}"
+      - "traefik.docker.network=broker"

meadows_web-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "meadows-web"
+version = "0.1.0"
+description = "MEADOWS web host: serves index.html and static assets. Dumb HTTP host, no domain logic."
+readme = "README.md"
+requires-python = ">=3.12"
+license-expression = "MIT"
+authors = [{ name = "MEADOWS" }]
+dependencies = [
+    "meadows-protocol",
+    "uvicorn>=0.30.0",
+    "starlette>=0.37.0",
+]
+
+[project.optional-dependencies]
+dev = ["hatch", "pytest>=8.0.0", "pytest-asyncio>=0.23.0", "pytest-cov>=5.0.0", "httpx>=0.27.0", "ruff==0.14.9"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/meadows"]
+
+[tool.uv.sources]
+meadows-protocol = { path = "../meadows-protocol", editable = true }
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["F", "E", "W", "Q", "A", "SIM", "ARG", "PTH", "RUF", "C90", "N", "YTT"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.vommit]
+allow_breaking_bang = true
+allow_breaking_footer = true
+prerelease_token = "rc"
+confirm = true
+
+[tool.vommit.git]
+enabled = true
+origin = "origin"
+branch = "main"
+on_wrong_branch = "error"
+tag_format = "v{version}"
+commit_format = "{version}"
+
+[tool.vommit.changelog]
+enabled = true
+file = "CHANGELOG.md"
+include_prereleases = false
+placeholder = "<!-- next-version-placeholder -->"
+placeholder_regex = "<auto>"
+entry_title_format = "## v{version} ({date:%Y-%m-%d})"
+
+[tool.vommit.changelog.levels]
+break = "Breaking Change{s}"
+feat = "Feature{s}"
+fix = "Fix{es}"
+perf = "Performance"
+docs = "Documentation"
+
+[tool.vommit.pypi]
+enabled = true
+use_keyring = true
+
+[tool.vommit.commands]
+clean = "rm -rf ./dist"
+build = "uv build"
+publish = "../pypi-publish"
+post_publish = ""
+
+[tool.vommit.version_bump_map]
+break = "major"
+feat = "minor"
+fix = "patch"
+perf = "patch"

meadows_web-0.1.0/shared_keys/jwt.key

@@ -0,0 +1 @@
+f66dee38fa244ab248937238aef06918868c485c8f086a5bf022a0220a8c5464

meadows_web-0.1.0/src/meadows/web/__about__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("meadows-web")

meadows_web-0.1.0/src/meadows/web/__init__.py

@@ -0,0 +1,18 @@
+"""MEADOWS web host — a dumb HTTP host (MEADOWS §2 line 40).
+
+This package serves index.html and static assets. It is deliberately the
+simplest of the five MEADOWS distributions: no Socket.IO, no auth, no domain
+logic. The browser is the Socket.IO client; the connection runs browser→
+meadows-server, NOT via this Python webserver. TLS is terminated by Traefik
+(section 4 line 115).
+
+The only touch of meadows.protocol is in build.py, and only for EventName
+(architecture invariant #3: protocol constants only).
+
+PEP 420 (section 3.1): there is intentionally NO `src/meadows/__init__.py`.
+Only this leaf package's __init__ exists.
+"""
+
+from meadows.web.__about__ import __version__
+
+__all__ = ["__version__"]

meadows_web-0.1.0/src/meadows/web/__main__.py

@@ -0,0 +1,28 @@
+"""BUSINESS RULE (MEADOWS §2 line 40): `python -m meadows.web` runs the dumb
+HTTP host via uvicorn. Plain HTTP — TLS is terminated by Traefik (§4 line 115),
+so no cert logic here (invariant #2). Defaults match tasks.py:check_env so the
+container and local dev behave identically.
+"""
+
+from __future__ import annotations
+
+import os
+
+import uvicorn
+
+from meadows.web.app import create_app
+
+app = create_app()
+
+
+def main() -> None:
+    """BUSINESS RULE: serve files on the configured host/port. Nothing else —
+    the browser opens its own Socket.IO connection to meadows-server using the
+    URL injected into index.html by build.py."""
+    host = os.environ.get("MEADOWS_WEB_HOST", "0.0.0.0")
+    port = int(os.environ.get("MEADOWS_WEB_PORT", "8081"))
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

meadows_web-0.1.0/src/meadows/web/app.py

@@ -0,0 +1,120 @@
+"""
+BUSINESS RULE (MEADOWS §2 line 40 + §4 line 115): meadows-web is a dumb HTTP
+host. It serves index.html and static assets, injects protocol constants into
+the template, and does nothing else. The browser is the Socket.IO client; the
+connection runs browser→meadows-server, NOT via this Python webserver.
+
+This module deliberately has no socketio, no auth, no domain logic, no JWT, no
+message parsing (architecture invariant #1). TLS is terminated by Traefik
+(section 4 line 115), so this host speaks plain HTTP (invariant #2).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from starlette.applications import Starlette
+from starlette.responses import FileResponse, JSONResponse, Response
+from starlette.routing import Mount
+from starlette.staticfiles import StaticFiles
+
+from meadows.web.build import build
+
+# Resolved relative to this file so the app works regardless of CWD (container
+# WORKDIR is /app; the package lives at /app/src/meadows/web).
+_PACKAGE_DIR = Path(__file__).resolve().parent
+_DEFAULT_INDEX = _PACKAGE_DIR / "dist" / "index.html"
+_DEFAULT_STATIC = _PACKAGE_DIR / "static"
+
+
+class WebHost:
+    """
+    BUSINESS RULE (MEADOWS §2 line 40): meadows-web is a dumb HTTP host.
+    It serves files. The browser is the Socket.IO client, connecting directly
+    to meadows-server. This Python webserver never touches Socket.IO. TLS is
+    terminated by Traefik (MEADOWS §4 line 115).
+
+    This class wires three routes and nothing more:
+      - `GET /`          -> the built dist/index.html (template-injected by build.py)
+      - `/static/*`      -> static assets, if any (404 when absent)
+      - anything else    -> 404
+
+    No auth, no sockets, no domain logic. If dist/index.html is missing on
+    startup, the template is built once so the host is usable without a manual
+    build step — this is static-asset preparation, not domain logic.
+    """
+
+    def __init__(self, index_path: Path = _DEFAULT_INDEX, static_dir: Path = _DEFAULT_STATIC) -> None:
+        self.index_path = index_path
+        self.static_dir = static_dir
+
+    def _ensure_built(self) -> None:
+        """BUSINESS RULE: guarantee the served index.html exists before serving.
+
+        build.py is the single place that injects protocol constants (invariant
+        #3). If the dist file is absent (fresh checkout / container start without
+        a prior build), render it once from the template + env. This keeps the
+        host a pure file server at request time while still being runnable
+        standalone.
+        """
+        if not self.index_path.exists():
+            build()
+
+    def serve_index(self, request) -> Response:
+        """BUSINESS RULE: serve the pre-built index.html at `/`. Dumb file host —
+        no templating per request, no auth, no session. The page already carries
+        the injected protocol constants + server URL from build.py."""
+        del request  # request is unused: this route is a fixed file response (dumb host).
+        self._ensure_built()
+        if not self.index_path.exists():
+            return Response("index.html not found", status_code=404)
+        return FileResponse(self.index_path, media_type="text/html")
+
+    def serve_status(self, request) -> Response:
+        """BUSINESS RULE (MEADOWS §2 line 40): meadows-web has no auth surface.
+        The monolith's checkAuthStatus() fetches '/status' to detect Auth0
+        sessions; in MEADOWS, auth is JWT-only via the socket handshake. We
+        return a fixed `{"logged_in": false}` so the client JS falls through
+        to the manual-JWT auth overlay without a console 404 error. This is
+        a compatibility shim for the copied template, not domain logic."""
+        del request  # unused: fixed response, no per-request logic.
+        return JSONResponse({"logged_in": False})
+
+    def not_found(self, request) -> Response:
+        """BUSINESS RULE: anything that isn't `/` or `/static/*` is a 404. The
+        host serves only the chat page and static assets — no API surface."""
+        del request  # unused: a dumb host has no per-request routing logic here.
+        return Response("Not found", status_code=404)
+
+    def create_app(self) -> Starlette:
+        """BUSINESS RULE: assemble the ASGI app. Two real routes + a 404 catch-all.
+        StaticFiles is mounted (directory created empty if missing so missing
+        assets 404 instead of crashing the mount)."""
+        self.static_dir.mkdir(parents=True, exist_ok=True)
+        self._ensure_built()
+
+        routes = [
+            Mount(
+                "/static",
+                app=StaticFiles(directory=str(self.static_dir), html=False),
+                name="static",
+            ),
+        ]
+        app = Starlette(routes=routes)
+        app.router.add_route("/", self.serve_index, methods=["GET"])
+        app.router.add_route("/status", self.serve_status, methods=["GET"])
+        app.router.add_route("/{path:path}", self.not_found, methods=["GET"])
+        return app
+
+
+def create_app() -> Starlette:
+    """Module-level factory for `uvicorn meadows.web.app:app`."""
+    return WebHost().create_app()
+
+
+# BUSINESS RULE: a module-level `app` so `uvicorn meadows.web.app:app` works
+# without the caller invoking create_app() explicitly (matches the original
+# monolith's `webchat` ASGI exposure pattern).
+app = create_app()
+
+__all__ = ["WebHost", "app", "create_app"]

meadows_web-0.1.0/src/meadows/web/build.py

@@ -0,0 +1,112 @@
+"""
+BUSINESS RULE (MEADOWS §2 line 40): meadows-web injects protocol constants
+into the template. The browser needs to know event names (e.g. "message",
+"authenticate", "user_typing") to talk to meadows-server. Rather than
+hardcoding string literals in JS (which is what the monolith did — see
+MEADOWS-migration-intent.md §1 line 11, where the protocol "zat verstopt
+in de handlers en in conventies"), we inject them from the single source of
+truth: meadows.protocol.EventName.
+
+This module is the ONLY place meadows-web touches meadows.protocol, and it
+touches it ONLY for EventName. Per architecture invariant #3, it does not
+import Message, JWTClaims, or anything else — the web host doesn't need them.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+from meadows.protocol import EventName
+
+# BUSINESS RULE (MEADOWS §2 line 40): the template is the one artifact this host
+# shapes before serving. Paths are relative to this module so the build works
+# whether invoked from the repo root or from `python -m meadows.web.build`.
+_TEMPLATES_DIR = Path(__file__).resolve().parent / "templates"
+TEMPLATE_PATH = _TEMPLATES_DIR / "index.html"
+OUTPUT_PATH = Path(__file__).resolve().parent / "dist" / "index.html"
+
+
+def get_protocol_constants() -> dict[str, str]:
+    """BUSINESS RULE (MEADOWS §2 line 40 + §3.1): expose the closed set of event
+    names to the browser as a JSON blob.
+
+    The protocol package declares EventName as the single source of truth for the
+    Socket.IO events the system contracts (meadows-protocol/src/meadows/protocol/
+    events.py). The browser JS must emit and listen for these exact names. We
+    serialize `{MEMBER_NAME: string_value}` so JS can reference
+    `window.MEADOWS_PROTOCOL.MESSAGE` etc. without hardcoding literals.
+
+    This is a pure declaration pull — no behavior is imported, keeping invariant
+    #3 (protocol constants only).
+    """
+    return {member.name: member.value for member in EventName}
+
+
+def compute_hash(content: str) -> str:
+    """BUSINESS RULE: produce a cache-busting token for the served page.
+
+    The original monolith build.py (chat.openit.chat/webchat/build.py) computed a
+    SHA-256 prefix for the same purpose. We keep the 16-char hex prefix so CDN /
+    browser caches invalidate whenever the rendered content (and thus the injected
+    protocol constants or config) changes.
+    """
+    return hashlib.sha256(content.encode()).hexdigest()[:16]
+
+
+def build(
+    *,
+    server_url: str | None = None,
+    system_name: str | None = None,
+    template_path: Path | None = None,
+    output_path: Path | None = None,
+) -> Path:
+    """BUSINESS RULE (MEADOWS §2 line 40): render templates/index.html into
+    dist/index.html with env config + protocol constants injected.
+
+    This is the meadows-web equivalent of the monolith's build.py — but the only
+    protocol knowledge it carries is EventName (invariant #3). The rendered file
+    is what app.py serves at `/`. TLS, auth and sockets are deliberately absent
+    (invariants #1 and #2); the browser uses the injected MEADOWS_SERVER_URL to
+    open its own Socket.IO connection straight to meadows-server.
+
+    Defaults read from the environment so `python -m meadows.web.build` works in
+    the container (env vars come from docker-compose / check_env in tasks.py).
+    Returns the path to the built file so callers (tests, CLI) can locate it.
+    """
+    import os
+
+    server_url = server_url if server_url is not None else os.environ.get("MEADOWS_SERVER_URL", "http://localhost:8080")
+    system_name = system_name if system_name is not None else os.environ.get("MEADOWS_SYSTEM_NAME", "MEADOWS Chat")
+
+    template_path = template_path if template_path is not None else TEMPLATE_PATH
+    output_path = output_path if output_path is not None else OUTPUT_PATH
+
+    if not template_path.exists():
+        raise FileNotFoundError(f"Template not found: {template_path}")
+
+    content = template_path.read_text(encoding="utf-8")
+
+    # Inject config + protocol constants (single source of truth = EventName).
+    protocol_json = json.dumps(get_protocol_constants(), indent=2, sort_keys=True)
+    content = content.replace("{{ MEADOWS_SERVER_URL }}", server_url)
+    content = content.replace("{{ MEADOWS_SYSTEM_NAME }}", system_name)
+    content = content.replace("{{ MEADOWS_PROTOCOL }}", protocol_json)
+
+    # Cache-busting hash: computed over the rendered content, then injected
+    # as a meta tag before </head> (matching the monolith's build.py pattern).
+    client_hash = compute_hash(content)
+    content = content.replace(
+        "</head>",
+        f'<meta name="meadows-hash" content="{client_hash}"></head>',
+    )
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(content, encoding="utf-8")
+    print(f"Built {output_path} (hash={client_hash})")
+    return output_path
+
+
+if __name__ == "__main__":
+    build()