From 7815e1c231155c2fa39bfbad3298e9495712c191 Mon Sep 17 00:00:00 2001
From: Jeroen Schweitzer <jpmschweitzer@gmail.com>
Date: Sun, 9 Aug 2026 15:10:31 +0200
Subject: [PATCH] build: add the Makefile command surface (D-27)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every repo gets one at the root: help, plus test and lint where those exist.
The point is that a target name means the same thing in every repo, so an
agent or a person can act without reading the repo first.

Paths resolve here rather than in callers (D-10). python3 on this host is 3.8
and cannot parse these sources, and a bare pytest or ruff resolves only in a
login shell — so both are named explicitly through the venv, and a missing
venv fails with the command to fix it rather than a bare no-such-file.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 Makefile | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)
 create mode 100644 Makefile

diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..9e81060
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,30 @@
+# core-api — the repo's command surface (D-27).
+#
+# Paths resolve here rather than in callers (D-10). `python3` on this host is
+# 3.8 and cannot parse these sources, and a bare `pytest` resolves only in a
+# login shell — so both are named explicitly through the venv.
+
+VENV   := $(CURDIR)/.venv
+PYTHON ?= python3.12
+
+.DEFAULT_GOAL := help
+
+.PHONY: help
+help: ## Show this help
+	@grep -hE '^[a-z][a-z0-9_-]*:.*?## ' $(MAKEFILE_LIST) \
+	  | awk 'BEGIN{FS=":.*?## "}{printf "  \033[36m%-14s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: setup
+setup: ## Create the venv and install dependencies
+	$(PYTHON) -m venv .venv
+	$(VENV)/bin/pip install -r requirements.txt -r dev-requirements.txt
+
+.PHONY: test
+test: ## Run the test suite
+	@test -x $(VENV)/bin/python || { echo "FAIL — no venv; run: make setup"; exit 1; }
+	$(VENV)/bin/python -m pytest tests/
+
+# No `lint` target, deliberately. This repo configures no linter — no ruff or
+# flake8 config, and neither in requirements. Per D-27 the name is reserved for
+# repos that lint; an empty target here would report clean for something never
+# run. Add the target when a linter is added, not before.