chore: Add pre-push hook and clean up build duplication

Author: abeiderman

.githooks/pre-push

@@ -0,0 +1,47 @@
+#!/usr/bin/env sh
+#
+# Runs `make check-all` — the same lint, type, test, distribution, and sample-app checks that
+# CI runs — before allowing a push. The checks themselves live in the Makefile so that this
+# hook and CI cannot drift apart; this script only adds the git-specific parts.
+#
+# Install it with `make hooks` (which points core.hooksPath at this directory).
+# Bypass it for a single push with `git push --no-verify`.
+#
+# Note: this checks the working tree, not the commits being pushed. Uncommitted changes are
+# included, which is usually what you want and occasionally surprising.
+
+set -eu
+
+# --- skip when the push only deletes remote refs -----------------------------------------
+# git feeds "<local ref> <local sha> <remote ref> <remote sha>" per ref on stdin. A deletion
+# has an all-zero local sha and nothing to check. Skip the read entirely when run from a
+# terminal, so the hook stays runnable by hand.
+if [ ! -t 0 ]; then
+    saw_ref=0
+    only_deletes=1
+    while read -r _local_ref local_sha _remote_ref _remote_sha; do
+        saw_ref=1
+        case "$local_sha" in
+            *[!0]*) only_deletes=0 ;;
+        esac
+    done
+    if [ "$saw_ref" -eq 1 ] && [ "$only_deletes" -eq 1 ]; then
+        echo "pre-push: deleting refs only, nothing to check."
+        exit 0
+    fi
+fi
+
+cd "$(git rev-parse --show-toplevel)"
+
+for tool in make uv; do
+    if ! command -v "$tool" >/dev/null 2>&1; then
+        echo "pre-push: $tool is not installed, cannot run the checks."
+        [ "$tool" = uv ] && echo "  see https://docs.astral.sh/uv/getting-started/installation/"
+        exit 1
+    fi
+done
+
+if ! make check-all; then
+    printf '\n%s\n' "pre-push FAILED. Fix the problem above, or bypass with: git push --no-verify"
+    exit 1
+fi

.github/workflows/ci.yml

@@ -8,6 +8,12 @@ on:
 permissions:
   contents: read
 
+# The checks themselves live in the Makefile so that CI and the pre-push hook cannot drift
+# apart. bash everywhere keeps the make recipes portable across the runner images.
+defaults:
+  run:
+    shell: bash
+
 jobs:
   lint:
     name: Lint + Typecheck
@@ -20,17 +26,9 @@ jobs:
         with:
           enable-cache: true
 
-      - name: uv sync
-        run: uv sync --all-extras --frozen
-
-      - name: ruff check
-        run: uv run ruff check .
-
-      - name: ruff format --check
-        run: uv run ruff format --check .
-
-      - name: mypy
-        run: uv run mypy
+      - run: make verify-lock
+      - run: make lint
+      - run: make typecheck
 
   test:
     name: Test (Python ${{ matrix.python-version }} on ${{ matrix.os }})
@@ -54,11 +52,8 @@ jobs:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
 
-      - name: uv sync
-        run: uv sync --all-extras --frozen
-
-      - name: pytest
-        run: uv run pytest --cov --cov-report=term-missing
+      - run: make verify-lock
+      - run: make coverage
 
   build:
     name: Build distribution
@@ -71,17 +66,8 @@ jobs:
         with:
           enable-cache: true
 
-      - name: uv build
-        run: uv build
-
-      - name: Check distribution metadata
-        run: uvx twine check dist/*
-
-      - name: Verify the wheel imports cleanly
-        run: |
-          uv venv /tmp/smoke
-          VIRTUAL_ENV=/tmp/smoke uv pip install dist/*.whl
-          /tmp/smoke/bin/python -c "import configdirector; print(configdirector.__version__)"
+      # Builds into dist/, checks the metadata, and imports the wheel in a clean environment.
+      - run: make dist-check
 
       - uses: actions/upload-artifact@v4
         with:
@@ -91,10 +77,6 @@ jobs:
   samples:
     name: Sample apps
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        sample: [flask]
     steps:
       - uses: actions/checkout@v5
 
@@ -103,15 +85,5 @@ jobs:
         with:
           enable-cache: true
 
-      # Samples resolve the SDK from a local path, so they are not locked against a release.
-      - name: uv sync
-        run: uv sync
-        working-directory: ./samples/${{ matrix.sample }}
-
-      - name: mypy
-        run: uv run mypy
-        working-directory: ./samples/${{ matrix.sample }}
-
-      - name: pytest
-        run: uv run pytest
-        working-directory: ./samples/${{ matrix.sample }}
+      # Each sample resolves the SDK by local path, so it is not locked against a release.
+      - run: make samples

Makefile

@@ -1,9 +1,19 @@
-.PHONY: install lint format typecheck test coverage build clean check
+.PHONY: install hooks lint format typecheck test coverage build verify-lock dist-check samples check check-all clean
 
 install:
 	uv sync --all-extras
 
+hooks:
+	git config core.hooksPath .githooks
+	@echo "pre-push hook installed. Bypass a single push with 'git push --no-verify'."
+
+# Asserts uv.lock is still consistent with pyproject.toml, which is what CI installs from.
+verify-lock:
+	@printf '\n\033[1m==> verify-lock\033[0m\n'
+	uv sync --all-extras --locked
+
 lint:
+	@printf '\n\033[1m==> lint\033[0m\n'
 	uv run ruff check .
 	uv run ruff format --check .
 
@@ -12,19 +22,49 @@ format:
 	uv run ruff format .
 
 typecheck:
+	@printf '\n\033[1m==> typecheck\033[0m\n'
 	uv run mypy
 
 test:
+	@printf '\n\033[1m==> test\033[0m\n'
 	uv run pytest
 
 coverage:
+	@printf '\n\033[1m==> coverage\033[0m\n'
 	uv run pytest --cov --cov-report=term-missing
 
 build:
+	@printf '\n\033[1m==> build\033[0m\n'
+	rm -rf dist
 	uv build
 
+# Validates the built distribution's metadata and that the wheel imports on its own, in a
+# throwaway environment. Leaves dist/ in place so CI can upload it.
+dist-check: build
+	@printf '\n\033[1m==> dist-check\033[0m\n'
+	uvx twine check dist/*
+	@tmp=$$(mktemp -d); \
+	uv venv "$$tmp/venv" --quiet \
+		&& VIRTUAL_ENV="$$tmp/venv" uv pip install --quiet dist/*.whl \
+		&& VIRTUAL_ENV="$$tmp/venv" uv run --no-project python -c \
+			"import configdirector; print('wheel imports cleanly:', configdirector.__version__)"; \
+	status=$$?; rm -rf "$$tmp"; exit $$status
+
+# Samples resolve the SDK by local path, so this is what catches a breaking API change.
+samples:
+	@for sample in samples/*/; do \
+		[ -f "$$sample/pyproject.toml" ] || continue; \
+		printf '\n\033[1m==> sample %s\033[0m\n' "$$(basename $$sample)"; \
+		(cd "$$sample" && uv sync --quiet && uv run mypy && uv run pytest) || exit 1; \
+	done
+
+# The fast loop while working.
 check: lint typecheck test
 
+# Everything CI runs. The pre-push hook calls this.
+check-all: verify-lock lint typecheck test dist-check samples
+	@printf '\n\033[1m✓ all checks passed\033[0m\n'
+
 clean:
 	rm -rf dist build .pytest_cache .mypy_cache .ruff_cache .coverage htmlcov
 	find . -type d -name __pycache__ -prune -exec rm -rf {} +

README.md

@@ -167,13 +167,38 @@ This project uses [uv](https://docs.astral.sh/uv/).
 
 ```bash
 make install     # uv sync --all-extras
+make hooks       # install the pre-push hook (once, per clone)
+
 make test        # pytest
 make lint        # ruff check + ruff format --check
 make typecheck   # mypy
-make check       # lint + typecheck + test
+make samples     # typecheck and test every app under samples/
 make build       # build the sdist and wheel
+make dist-check  # build, validate the metadata, import the wheel in a clean env
+
+make check       # lint + typecheck + test — the fast loop
+make check-all   # everything CI runs
+```
+
+CI and the pre-push hook both call these targets rather than repeating the commands, so the
+three cannot drift apart.
+
+### Pre-push hook
+
+`make hooks` points `core.hooksPath` at [`.githooks/`](.githooks/), so
+[`.githooks/pre-push`](.githooks/pre-push) runs `make check-all` before every push: lockfile,
+lint, formatting, types, tests, a real distribution build, and every sample app. It takes a few
+seconds.
+
+Pushes that only delete remote refs skip the checks. To bypass it for a single push:
+
+```bash
+git push --no-verify
 ```
 
+Note that the hook checks your working tree, not the commits being pushed, so uncommitted
+changes count.
+
 ## Documentation
 
 Refer to the [official documentation for the Python SDK](https://docs.configdirector.com/sdks/server/python).

samples/flask/.env.example

@@ -3,5 +3,5 @@
 CONFIGDIRECTOR_SERVER_KEY=your-server-sdk-key
 
 # Verbosity of the SDK's own logger: DEBUG, INFO, WARNING, ERROR.
-# The sample defaults to DEBUG so you can watch every evaluation; set INFO to quiet it down.
-CONFIGDIRECTOR_LOG_LEVEL=DEBUG
+# Set DEBUG to watch every evaluation as it happens.
+CONFIGDIRECTOR_LOG_LEVEL=INFO

samples/flask/README.md

@@ -87,7 +87,7 @@ lands in the application's logging namespace rather than the SDK's:
 
 ```python
 sdk_logger = logging.getLogger("flask_sample.configdirector")
-sdk_logger.setLevel(os.environ.get("CONFIGDIRECTOR_LOG_LEVEL", "DEBUG"))
+sdk_logger.setLevel(os.environ.get("CONFIGDIRECTOR_LOG_LEVEL", "INFO"))
 
 client = ConfigDirectorClient(..., logger=sdk_logger)
 ```
@@ -99,8 +99,8 @@ flask_sample.configdirector DEBUG No config state found for 'integer-config', re
 Any object with `debug`/`info`/`warning`/`error` methods works — a stdlib `Logger` satisfies
 that, and so does `create_console_logger("debug")` if you would rather not configure the
 `logging` module at all. Omit `logger=` entirely and the SDK falls back to the standard library
-logger named `configdirector`. The sample defaults to `DEBUG` so you can watch every evaluation
-as it happens; set `CONFIGDIRECTOR_LOG_LEVEL=INFO` to quiet it down.
+logger named `configdirector`. Set `CONFIGDIRECTOR_LOG_LEVEL=DEBUG` to watch every evaluation as
+it happens.
 
 **Shutdown is clean.** `atexit` closes the client, dropping connections and flushing pending
 telemetry. A production deployment would also hook its server's worker-exit signal.