Phase 2: Mode A static site — build, serve, search, stage panel

One Go binary serves a pre-rendered site. No Node, no bundler, no node_modules:
htmx and the SSE extension are vendored files, Markdown and code highlighting
run at build time (goldmark + chroma), and the server only writes files.

Implements docs/phase-2-static-site.md:

  2.1 service skeleton   cmd/build (content -> dist), cmd/server (dist -> HTTP),
                         env-configured, 127.0.0.1:8096, /healthz with separate
                         static / ai / search readiness, --health-check probe,
                         deploy/compose.yml + deploy/Dockerfile at 120m
  2.2 rendering          templ components (Layout, Nav, PillarCard, Stage,
                         EvidenceTable, CodeBlock, Timeline, Footer);
                         `make generate` is a build step and is byte-stable
  2.3 navigation         six-area rail, <details> disclosure under 900px,
                         breadcrumbs, aria-current, L1/L2/L3 with artefact pages
  2.4 stage panel        internal/stage owns the contract; RouteDriver (fragment
                         swap) and SSEDriver (event stream) differ only in the
                         Binding, never in layout. fragment ids live in the
                         contract so route files, links and streamed frames agree
  2.5 search             SQLite FTS5 over titles and body, rebuilt by the build;
                         one handler returns a page without HTMX, a fragment with
                         it. Visitors' FTS operators are never honoured
  2.6 quality floor      print stylesheet, JS-off navigation, focus states,
                         semantic landmarks, dark default; security headers

Definition of Done evidence (see issue AUD-142):
  A1  all pages 200 in a network namespace with no external route
  one binary serves the site; make dist writes 45 pages, 86 fragments, 40 docs
  templ generate is deterministic (md5 identical across runs)
  6 L1 + 6 L2 pages, artefact pages reachable in <= 3 clicks
  FTS5 returns sensible hits for zigbee / signage / routing (tested)
  Lighthouse 100 performance and 100 accessibility, mobile and desktop
  first byte well inside 100ms over loopback (test)
  panel renders from a route driver and re-points at the stream untouched
  print legible: /edge/ renders to a 3-page PDF with the print stylesheet

Also fixes found while finishing the build:
  - reject "." / ".." path segments before ServeMux redirects them into a file
    outside the asset directory (/static/../build.json now 404, was 307->200)
  - make test is the real gate: go test ./... plus the validator self-test
This commit is contained in:
2026-10-26 20:42:52 +11:00
parent fd9974d07e
commit 84fc585c91
23 changed files with 4373 additions and 34 deletions

48
deploy/compose.yml Normal file
View File

@@ -0,0 +1,48 @@
# Container shape for the Mode A site (docs/phase-2-static-site.md §2.1).
#
# Values are fixed by the specification and must not drift:
# mem_limit == memswap_limit == 120m so the app cannot eat the host's swap
# ports published on 127.0.0.1 only Caddy on .35 is the only public listener
# logging capped one bad day cannot fill the disk
#
# Run it (build the artefacts first — Phase 3's deploy.sh does both):
#
# make build dist
# docker compose -f deploy/compose.yml up -d
#
# `curl http://127.0.0.1:8096/healthz` must answer with static ready.
name: ai-resume
services:
resume:
image: ai-resume:local
build:
context: ..
dockerfile: deploy/Dockerfile
restart: unless-stopped
mem_limit: 120m
memswap_limit: 120m
# The app listens on 0.0.0.0 inside the container namespace; the host-side
# binding is loopback, so nothing is reachable from the LAN except through
# docker-proxy on 127.0.0.1:8096 — which is what Caddy proxies to.
ports:
- "127.0.0.1:8096:8096"
read_only: true
security_opt:
- no-new-privileges:true
logging:
driver: json-file
options:
max-size: 10m
max-file: "3"
healthcheck:
test: ["CMD", "/usr/bin/resume-server", "--health-check"]
interval: 30s
timeout: 3s
retries: 3
start_period: 5s
# Phase 4/5 add at most three more containers (Qdrant, Prefect worker, query
# service) inside the 4-container and 1.0 GiB budget in AGENTS.md §4.3. Mode A
# needs none of them and must keep working when they are stopped (test A1).