feat: add list hero api endpoints and auto generate openapi spec

Author: jeff-arn

.githooks/pre-commit

@@ -29,4 +29,16 @@ cargo clippy --all-targets --all-features -- -D warnings
 echo "pre-commit: running unit tests..."
 cargo test --lib --bins --quiet
 
+echo "pre-commit: checking openapi.json freshness..."
+tmp_spec=$(mktemp)
+trap 'rm -f "$tmp_spec"' EXIT
+cargo run --quiet --bin export_openapi -- "$tmp_spec"
+if ! diff -q openapi.json "$tmp_spec" >/dev/null 2>&1; then
+    echo "pre-commit: openapi.json is stale relative to the API code." >&2
+    echo "  regenerate with: cargo run --bin export_openapi openapi.json" >&2
+    echo "  then stage the result and re-commit." >&2
+    diff -u openapi.json "$tmp_spec" | head -40 >&2 || true
+    exit 1
+fi
+
 echo "pre-commit: ok"

.github/workflows/rust.yml

@@ -2,21 +2,49 @@ name: Rust
 
 on:
   push:
-    branches: [ "main" ]
+    branches: ["main"]
   pull_request:
-    branches: [ "main" ]
+    branches: ["main"]
 
 env:
   CARGO_TERM_COLOR: always
+  RUSTFLAGS: -D warnings
 
 jobs:
-  build:
-
+  check:
     runs-on: ubuntu-latest
-
     steps:
-    - uses: actions/checkout@v4
-    - name: Build
-      run: cargo build --verbose
-    - name: Run tests
-      run: cargo test --verbose
+      - uses: actions/checkout@v4
+
+      - name: Restore cargo cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Format
+        run: cargo fmt --all -- --check
+
+      - name: Clippy
+        run: cargo clippy --all-targets --all-features -- -D warnings
+
+      - name: Build
+        run: cargo build --verbose
+
+      - name: Unit tests
+        run: cargo test --lib --bins --verbose
+
+      - name: OpenAPI spec is up to date
+        # The committed openapi.json must match what the code generates.
+        # If this fails, run `cargo run --bin export_openapi openapi.json`
+        # locally, commit the result, and push.
+        run: |
+          cargo run --quiet --bin export_openapi -- /tmp/generated-openapi.json
+          if ! diff -q openapi.json /tmp/generated-openapi.json >/dev/null; then
+            echo "openapi.json is stale relative to the API code." >&2
+            diff -u openapi.json /tmp/generated-openapi.json >&2 || true
+            exit 1
+          fi

CLAUDE.md

@@ -46,7 +46,7 @@ Read these for their respective domains:
 
 Two hooks live in `.githooks/`, wired up by one `git config core.hooksPath .githooks` per clone:
 
-- **`pre-commit`** — scans staged changes for secrets via `gitleaks`, then runs `cargo fmt --check`, `cargo clippy -- -D warnings`, and `cargo test --lib --bins`. Integration tests in `tests/` are deliberately excluded — they need Postgres and run in CI.
+- **`pre-commit`** — scans staged changes for secrets via `gitleaks`, then runs `cargo fmt --check`, `cargo clippy -- -D warnings`, `cargo test --lib --bins`, and an OpenAPI drift check (regenerates `openapi.json` to a tempfile and diffs against the committed copy). Integration tests in `tests/` are deliberately excluded — they need Postgres and run in CI.
 - **`commit-msg`** — validates the commit subject line against `.claude/rules/commits.md` (Conventional Commits 1.0). Pure bash, no commitlint dependency.
 
 One-time setup per clone:
@@ -76,8 +76,11 @@ sqlx migrate run
 # Audit dependencies
 cargo audit
 
-# Generate OpenAPI spec to stdout
-cargo run --bin export_openapi > openapi.json
+# Regenerate the committed OpenAPI spec (deterministic LF, no BOM,
+# regardless of shell). Run this after any API change; the pre-commit
+# hook and CI both fail if openapi.json drifts from what the code
+# generates.
+cargo run --bin export_openapi openapi.json
 ```
 
 ## Definition of done
@@ -86,7 +89,7 @@ A change is done when:
 
 - Code compiles without warnings (treat warnings as errors locally and in CI)
 - Tests pass, including negative and variant cases for the changed code
-- New endpoints have utoipa annotations and appear in `openapi.json`
+- New endpoints have utoipa annotations, `openapi.json` is regenerated, and the regenerated file is staged in the same commit as the code change
 - New SQL queries are compile-time checked by sqlx and the `.sqlx` cache is committed
 - Migration files are append-only if in `production` phase, freely editable in `pre-launch`
 - cargo-audit reports no new advisories