add precommit hook for checking openapi client drift

.github/workflows/openapi-clients.yml

@@ -0,0 +1,46 @@
+name: OpenAPI Clients
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  check-clients:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+
+      - name: Install python deps
+        run: uv sync --frozen
+
+      - name: Install bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+
+      - name: Install frontend deps
+        working-directory: frontend
+        run: bun install --frozen-lockfile
+
+      - name: Regenerate clients
+        run: make client-python client-frontend
+
+      # we check full regen here because it may be that someone manually edited or versioning changed on the generators
+      - name: Fail if generated clients are stale
+        run: |
+          if ! git diff --exit-code -- openapi.json client/src/lclstream_api_client/_generated frontend/src/client; then
+            echo "::error::Generated OpenAPI clients are out of date. Run 'make clients' locally, review the diff, and commit the result."
+            exit 1
+          fi

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: local
+    hooks:
+      - id: openapi-clients
+        name: Regenerate OpenAPI clients on backend schema changes
+        description: >-
+          Dumps the v2 app's OpenAPI schema and, only if it changed,
+          regenerates the Python (client/) and frontend (frontend/src/client)
+          clients. Fails the commit so the regenerated files can be reviewed
+          and staged.
+        entry: make clients
+        language: system
+        files: ^src/lclstream_api/v2/.*\.py$
+        exclude: ^src/lclstream_api/v2/alembic/versions/
+        pass_filenames: false

Makefile

@@ -0,0 +1,34 @@
+.PHONY: openapi client-python client-frontend clients lint-frontend
+
+openapi:
+	uv run python scripts/dump_openapi.py
+
+lint-frontend:
+	cd frontend && bun run lint
+
+client-python: openapi
+	bash client/regenerate.sh
+
+client-frontend: openapi
+	cd frontend && bun run generate-client
+	$(MAKE) lint-frontend
+
+# Regenerates openapi.json and, only if its content actually changed
+# relative to git HEAD, regenerates the Python + frontend clients. Used by
+# the local prek hook (see .pre-commit-config.yaml) so most commits (which
+# don't change the schema) skip the expensive Docker/bun regeneration steps
+# entirely. CI bypasses this gate and calls client-python/client-frontend
+# directly for an unconditional full regen (see openapi-clients.yml).
+clients: openapi
+	@if git diff --quiet -- openapi.json; then \
+		exit 0; \
+	fi; \
+	echo "openapi.json changed — regenerating python + frontend clients..."; \
+	$(MAKE) -s client-python client-frontend; \
+	echo ""; \
+	echo "The OpenAPI schema changed, so the Python and frontend clients were"; \
+	echo "regenerated. Review the diff, then:"; \
+	echo ""; \
+	echo "  git add openapi.json client/src/lclstream_api_client/_generated frontend/src/client"; \
+	echo "  git commit"; \
+	exit 1

client/regenerate.sh

@@ -13,6 +13,7 @@ uv run python scripts/dump_openapi.py
 GENERATOR_IMAGE="openapitools/openapi-generator-cli@sha256:da552b8d0add9fd3cd89ce836d55b433c8cf467b287dd50c62bbd4482c03f677"
 
 docker run --rm \
+  --user "$(id -u):$(id -g)" \
   -v "$REPO_ROOT/openapi.json:/spec.json:ro" \
   -v "$GENERATOR_CONFIG:/config.yaml:ro" \
   -v "$TMP_DIR:/out" \

pyproject.toml

@@ -39,6 +39,7 @@ dev = [
     "ruff>=0.15.17",
     "types-pyyaml>=6.0.12.20260518",
     "testcontainers[postgres]>=4.14.2",
+    "prek>=0.4.8",
 ]
 
 [build-system]