Build spec-first docs site and contract enforcement pipeline

.github/workflows/ci.yml

@@ -7,6 +7,46 @@ on:
   pull_request:
 
 jobs:
+  spec-and-web:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Install web dependencies
+        run: npm ci
+        working-directory: web
+
+      - name: Generate artifacts from OpenAPI
+        run: ./scripts/generate-all.sh
+
+      - name: Ensure generated files are up to date
+        run: ./scripts/check-generated-clean.sh
+
+      - name: Build website
+        run: npm run build
+        working-directory: web
+
+      - name: Run web unit tests
+        run: npm run test:unit
+        working-directory: web
+
+      - name: Install Playwright Chromium
+        run: npx playwright install --with-deps chromium
+        working-directory: web
+
+      - name: Run accessibility and UI tests
+        run: npm run test:a11y
+        working-directory: web
+
   rust-tests:
     runs-on: ubuntu-latest
 
@@ -26,6 +66,22 @@ jobs:
       - name: Run tests
         run: cargo test --all-targets --all-features
 
+  runtime-contract:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Run runtime contract checks
+        run: ./scripts/contract-test.sh
+
   docker-smoke:
     runs-on: ubuntu-latest
 

.gitignore

@@ -1 +1,5 @@
 /target
+/.worktrees
+web/node_modules
+web/dist
+/contracts/rust/api_contract/target

Cargo.toml

@@ -4,6 +4,7 @@ version = "0.1.0"
 edition = "2021"
 
 [dependencies]
+api_contract = { path = "contracts/rust/api_contract" }
 axum = { version = "0.8", features = ["query"] }
 base64 = "0.22"
 chrono = { version = "0.4", features = ["clock"] }

Dockerfile

@@ -4,6 +4,8 @@ FROM rust:1.93-bookworm AS builder
 WORKDIR /app
 
 COPY Cargo.toml Cargo.lock* ./
+COPY openapi.yaml ./openapi.yaml
+COPY contracts ./contracts
 COPY src ./src
 
 RUN cargo build --release

README.md

@@ -71,3 +71,53 @@ OpenAPI 3.0 spec is available at:
 ```
 openapi.yaml
 ```
+
+## Spec-first contract workflow
+
+This repository treats `openapi.yaml` as the canonical API contract.
+
+- Web documentation and API tester are generated from the spec.
+- Rust contract interface (`api_contract::EpochApiContract`) is generated from the spec.
+- Backend implementation compiles against that generated trait.
+
+Generate artifacts:
+
+```bash
+./scripts/generate-all.sh
+```
+
+Check generated artifacts are committed and up-to-date:
+
+```bash
+./scripts/check-generated-clean.sh
+```
+
+## Web documentation site
+
+A separate Astro site lives in `web/`.
+
+Install dependencies and build:
+
+```bash
+cd web
+npm install
+npm run build
+npm run test:unit
+npx playwright install chromium
+npm run test:a11y
+```
+
+Run locally:
+
+```bash
+cd web
+PUBLIC_API_BASE_URL=http://localhost:8080 npm run dev
+```
+
+## Runtime contract test
+
+Runtime conformance uses `uv` to create a local virtual environment, install Schemathesis, and run contract checks:
+
+```bash
+./scripts/contract-test.sh
+```